zk-data-agent/docs/technical-architecture/11-workspace-runtime.md

# Workspace Runtime 设计稿

## 背景

当前项目已经有了平台账号、会话目录、Jupyter 远程工作区、Skill/Tools 和文件产物管理，但这些能力还没有被一个统一的“执行环境”概念串起来。

现在的问题不是单纯缺少登录账号，而是需要回答：

```text
谁在使用 Agent
  -> 当前会话绑定到哪个工作区
    -> 工具以什么身份、在什么目录、用什么权限执行
      -> 产物在哪里保存、展示和下载
```

因此，账户体系升级不应该只看账号密码，而应该引入 `Workspace Runtime` 作为平台账号和工具执行之间的核心抽象。

## 核心结论

账户体系分两层：

```text
平台账号 Account
  负责登录、角色、会话、Skill 配置、模型配置、记忆和集成状态。

工作区运行时 Workspace Runtime
  负责执行身份、工作目录、文件读写、Python 环境、远程连接和进程管理。
```

平台账号不直接等价于 Linux 账号，也不直接等价于 Jupyter 账号。平台账号可以绑定不同类型的 runtime。

## 目标

1. 统一本机工作区、Linux 子账户工作区、Jupyter 工作区和未来 SSH 工作区。
2. 让 Tool handler 不关心执行位置，只面向统一 runtime 执行。
3. 明确权限来源，避免把远程工作区误认为平台托管沙盒。
4. 让每个 session 的输入、输出、scratchpad、Python 环境和文件下载有稳定归属。
5. 为后续多用户、资源限制、审计、团队空间和远程执行打基础。

## 非目标

1. 不在第一阶段实现完整企业 SSO。
2. 不把所有账号体系直接迁移到 Linux PAM。
3. 不强制所有远程工作区都变成平台托管沙盒。
4. 不要求 Skill 感知 runtime 的具体实现细节。

## 对象模型

### Account

平台账号是 Web 产品层的身份。

```text
Account
  id
  username
  display_name
  role
  status
  created_at
  updated_at
```

职责：

- 登录和会话 token。
- 模型选择。
- Skill 启用状态。
- 用户记忆。
- 第三方集成状态。
- 默认 workspace runtime 策略。

### Session

Session 是一次 Agent 对话任务。

```text
Session
  id
  account_id
  runtime_id
  title
  status
  created_at
  updated_at
```

职责：

- 保存对话历史。
- 绑定一个 runtime。
- 保存工具调用、活动步骤和最终结果。
- 关联输入文件和输出 artifact。

Session 一旦绑定远程 runtime，刷新页面后也应该恢复到同一个 runtime。

### Workspace Runtime

Workspace Runtime 是工具执行的真实环境。

```text
WorkspaceRuntime
  id
  account_id
  session_id
  type
  root
  permissions_source
  status
  created_at
  updated_at
```

`type` 可以是：

```text
local_process
local_linux_user
remote_jupyter
remote_ssh
```

职责：

- 决定 bash/python/file 工具在哪里执行。
- 决定输入输出文件在哪里。
- 决定 Python 环境在哪里。
- 决定进程如何启动、停止和清理。
- 决定文件如何展示、下载和转在线文档。

### Artifact

Artifact 是输入和输出文件的统一抽象。

```text
Artifact
  id
  account_id
  session_id
  runtime_id
  kind: input | output | scratchpad
  uri
  name
  size
  mime
  created_at
```

`uri` 可以是：

```text
file:///home/<account_id>/zk-agent/sessions/<session_id>/output/a.jsonl
jupyter://<session_id>/root/zk_agent_workspaces/<session_id>/output/a.jsonl
ssh://<runtime_id>/home/user/zk_agent_workspaces/<session_id>/output/a.jsonl
```

文件列表只需要展示 metadata。下载或转在线文档时，再通过 runtime 拉取内容。

### Executor

Executor 是 Tool handler 和 Runtime 之间的执行适配层。

```text
Executor
  run_bash(command, cwd, timeout)
  run_python(code_or_file, cwd, timeout)
  read_file(path)
  write_file(path, content)
  list_files(path)
  open_file_stream(path)
  cancel(run_id)
```

Tool handler 不应该自己判断是在本地、Jupyter 还是 SSH。它只调用当前 session 的 executor。

## Runtime 类型

### local_process

当前已有的默认模式。工具在服务进程所在机器上执行，目录由平台约定。

```text
.port_sessions/accounts/<account_id>/sessions/<session_id>/
```

适合：

- 本地开发。
- 单用户调试。
- 早期兼容。

问题：

- 多用户隔离主要靠代码路径约束。
- 工具进程和平台服务权限一致，风险较高。

### local_linux_user

平台托管的标准多用户工作区。

```text
平台账号: banisherwy
Linux runtime user: banisherwy
workspace root: /home/banisherwy/zk-agent/sessions/<session_id>
```

服务进程可以是 root，工具进程切换到普通 Linux 用户执行。

```text
root backend
  -> runuser -u banisherwy -- <runner command>
```

职责分工：

```text
root 服务
  创建 runtime 用户
  初始化 workspace
  设置 owner 和权限
  启停进程
  管理平台账号和 session

普通 Linux 用户
  执行 bash/python
  拥有自己的 workspace
  拥有自己的 Python 虚拟环境
  只能写自己的目录
```

推荐目录：

```text
/home/<account_id>/zk-agent/
  sessions/
    <session_id>/
      input/
      output/
      scratchpad/
      session.json
  python/
    .venv/
  memory/
  integrations/
```

推荐约定：

```text
平台用户名 = Linux 用户名
平台密码 = Linux 用户密码
Linux 用户允许 SSH 登录
```

这样用户体验更直接：

- 在平台创建账号时，同步创建同名 Linux 用户。
- 用户可以使用同一套账号密码登录 Web 平台和 SSH。
- Agent 工具执行时也使用同一个 Linux 用户身份。
- 文件 owner、进程 owner、SSH 登录用户和平台用户名一致，便于排查和审计。

但两者在架构语义上仍然保留分层：

```text
平台账号体系
  登录、角色、session、Skill、模型配置。

Linux 用户体系
  执行隔离、文件权限、进程权限、资源限制。
```

也就是说，账号名和密码保持一致，但平台仍然保留自己的登录态、session、角色和配置管理。Linux 账号负责机器级登录和执行权限。

需要注意：

- 用户名必须同时满足平台账号规范和 Linux 用户名规范。
- 修改平台密码时必须同步修改 Linux 密码。
- 禁用平台账号时，也应该禁用 Linux 登录或锁定 Linux 用户。
- 删除平台账号时，需要明确是否保留 `/home/<account_id>/zk-agent/` 数据。
- root 服务创建用户和改密码时必须走受控 helper，不能把用户输入拼成 shell 命令。

### remote_jupyter

用户授权的远程工作区。

语义是：

```text
用户把自己已有权限的 Jupyter 环境接入平台。
平台代替用户在这个环境里执行。
```

这不是平台托管沙盒。权限边界来自用户提供的 Jupyter 凭证。

```text
Account: banisherwy
Session: xxx
Runtime: remote_jupyter
Root: /root/zk_agent_workspaces/<session_id>
Permissions source: Jupyter password/token 对应的远程用户权限
```

平台需要保证：

- Jupyter 凭证只绑定当前 account/session。
- 刷新后 runtime 状态可恢复。
- 文件列表 metadata-only。
- 下载时通过 Jupyter API 流式拉取。
- 转在线文档时按需拉取，不默认同步大文件。
- 用户明确知道 Agent 在远程环境里的权限等同于该 Jupyter 用户。

平台不能保证：

- 远程机器上的文件权限隔离。
- 远程 Jupyter 用户不是 root。
- 远程挂载目录的访问范围。

短期建议：`remote_jupyter` 先保持当前逻辑，不作为账户体系升级的主战场。

当前已经具备：

- session 级 Jupyter 绑定。
- 刷新后恢复远程工作区状态。
- 输出文件 metadata-only 展示。
- 下载时通过 Jupyter API 流式读取。
- 转在线文档时按需拉取。

因此下一步账户体系升级优先处理本机托管 runtime 和平台账号，不主动重构 Jupyter 执行链路。后续只需要让 Jupyter 工作区在概念上挂到 `WorkspaceRuntime` 模型下。

### remote_ssh

未来可扩展的用户授权远程工作区。

语义和 remote_jupyter 类似：

```text
用户提供 SSH 连接能力。
平台代替用户在远程机器上执行。
权限边界来自 SSH 凭证对应的远程用户。
```

remote_ssh 更适合：

- 远程机器没有 Jupyter。
- 需要更完整 shell 能力。
- 需要使用远程开发机的挂载盘、GPU、模型目录。

但它也更复杂：

- SSH 凭证管理。
- 长连接和心跳。
- relay / OTP / 扫码登录。
- 文件传输和断线恢复。
- 进程树管理。

因此优先级应低于 `local_linux_user` 和已有 `remote_jupyter`。

## 权限边界

需要在 UI 和文档中明确区分两类工作区：

```text
平台托管工作区
  平台负责权限隔离。
  典型类型: local_linux_user。

用户授权工作区
  用户提供凭证。
  平台不创建权限边界，只复用用户已有权限。
  典型类型: remote_jupyter, remote_ssh。
```

UI 可以显示：

```text
当前工作区：Jupyter 远程工作区
权限来源：用户提供的 Jupyter 凭证
Agent 权限：等同于该远程环境当前登录用户
```

或者：

```text
当前工作区：平台托管工作区
执行身份：banisherwy
Agent 权限：普通 Linux 用户权限
```

## Tool 调用关系

目标关系：

```text
Agent Loop
  -> Tool handler
    -> RuntimeResolver(session_id)
      -> Executor
        -> local process / linux user / jupyter / ssh
```

工具不应该散落处理路径和远程协议。

例如：

```text
python_exec
  -> executor.run_python(...)

write_file
  -> executor.write_file(...)

download_artifact
  -> executor.open_file_stream(...)
```

这样后续新增 runtime 时，尽量只新增 executor，不重写每个工具。

## 文件策略

### 输入文件

输入文件应该同步到当前 runtime 的 `input/`。

```text
local_linux_user
  上传文件 -> /home/<account_id>/zk-agent/sessions/<session_id>/input/

remote_jupyter
  上传文件 -> 通过 Jupyter API 写入 /root/zk_agent_workspaces/<session_id>/input/
```

### 输出文件

输出文件默认放到当前 runtime 的 `output/`。

```text
output/
  records.jsonl
  report.md
  samples.csv
```

对远程 runtime，平台只保存 metadata。

```text
name
size
mtime
uri
runtime_id
```

点击下载时再流式读取。点击转在线文档时再按需拉取，并设置大小限制。

## Python 环境策略

每个 runtime 应有自己的 Python 环境。

```text
local_linux_user
  /home/<account_id>/zk-agent/python/.venv

remote_jupyter
  /root/zk_agent_workspaces/.zk-agent-python/.venv
```

初始化时只做最小准备：

- 创建 venv。
- 配置 pip 源。
- 不预装大量包。

缺包时由 Agent 根据任务安装，安装也发生在当前 runtime 内。

## 进程管理

每个工具执行必须有 run id 和 process group。

```text
run_id
account_id
session_id
runtime_id
executor_pid 或 remote_execution_id
status
started_at
updated_at
```

停止任务时：

- local_process：杀本地进程组。
- local_linux_user：杀对应 runtime 用户下该 run 的进程组。
- remote_jupyter：中断 kernel 或关闭对应执行任务。
- remote_ssh：杀远程进程组。

不能只停止 Web 请求，否则会出现“前端以为停了，后台 Python 还在跑”的问题。

## 持久化建议

建议把当前 JSON 账号体系逐步迁到 SQLite。

第一阶段可新增这些表：

```text
accounts
  id
  username
  password_hash
  role
  status
  created_at
  updated_at

account_sessions
  token_hash
  account_id
  created_at
  updated_at
  expires_at

workspace_runtimes
  id
  account_id
  session_id
  type
  root
  status
  config_json
  created_at
  updated_at

artifacts
  id
  account_id
  session_id
  runtime_id
  kind
  uri
  name
  size
  mime
  created_at
```

敏感信息不要直接明文落库。Jupyter 密码、SSH key、token 至少需要加密或放入受控 secret store。

## 与现有实现的关系

当前已有能力可以映射到新模型：

```text
frontend/app/lib/claw-auth.ts
  Account 登录态原型。

.port_sessions/accounts/<account_id>
  local_process 模式下的 account workspace。

backend/api/server.py::account_paths
  Runtime path resolver 的雏形。

src/jupyter_runtime.py
  remote_jupyter executor 的雏形。

RunManager / RunStateStore
  run id、活动状态、停止任务的雏形。

frontend 文件面板
  Artifact list/download 的雏形。
```

所以这不是推翻重来，而是把已有能力抽象成更稳定的边界。

## 演进路线

### Phase 0：明确概念，不改执行路径

- 在代码和文档中引入 Workspace Runtime 术语。
- 把现有 `.port_sessions/accounts/<account_id>` 视为 `local_process` runtime。
- UI 显示当前工作区类型。
- 对 Jupyter 工作区补充权限提示。

### Phase 1：抽象 RuntimeResolver 和 Executor

- 新增 `RuntimeResolver`，根据 account/session 找当前 runtime。
- 新增统一 `Executor` 接口。
- 先把 `python_exec`、`bash`、文件工具迁到 executor。
- 保持现有 local 和 Jupyter 行为不变。

### Phase 2：账号存储升级

- 把 `users.json` 和 `auth_sessions.json` 迁到 SQLite。
- 增加 `account_id`、`role`、`status`、`expires_at`。
- 增加 session token 清理。
- 管理后台去掉 `admin/admin` 和默认 `123456`。

### Phase 3：local_linux_user runtime

- root 服务创建与平台账号同名的 Linux 用户。
- 平台密码同步设置为 Linux 用户密码。
- Linux 用户允许 SSH 登录。
- 初始化 `/home/<account_id>/zk-agent/`。
- 工具执行切到普通 Linux 用户。
- Python venv、session、output 全部进入用户 home。
- 停止任务时按 process group 清理。

### Phase 4：资源限制和审计

- ulimit / cgroup。
- 每账号磁盘 quota。
- 工具执行审计。
- 大文件下载限流。
- session/output 清理策略。

### Phase 5：remote_ssh runtime

- 在 remote_jupyter 稳定后再考虑。
- 重点解决认证、relay、长连接、文件传输和远程进程清理。

## 关键待决问题

1. 平台账号是否允许用户自注册，还是只允许管理员创建？
2. 用户自注册时，是否允许自动创建同名 Linux 用户？
3. 删除账号时，是否删除 Linux 用户，是否保留 home 目录？
4. 本机平台托管 workspace 是否统一迁到 `/home/<account_id>/zk-agent/`？
5. Jupyter 凭证如何加密保存？
6. 远程 workspace 产物保留多久？
7. 大文件下载、在线文档转换和文件预览的大小限制是多少？
8. 是否需要团队空间：一个 workspace 被多个账号共享？

## 推荐决策

短期建议：

```text
保留平台账号体系。
引入 Workspace Runtime 抽象。
继续稳定 remote_jupyter。
账号存储从 JSON 迁到 SQLite。
开始设计 local_linux_user，但不要立即替换所有执行路径。
```

中期建议：

```text
服务可以 root 运行。
平台账号创建时同步创建同名普通 Linux 用户。
平台密码和 Linux 密码保持一致。
Linux 用户允许 SSH 登录。
工具执行统一通过 runtime executor。
本机默认工作区逐步迁到 /home/<account_id>/zk-agent。
```

长期建议：

```text
平台账号负责产品身份。
Workspace Runtime 负责执行环境。
Artifact 负责跨 runtime 文件抽象。
Executor 负责工具执行适配。
```

这样账户体系、Linux 子账户、Jupyter/SSH 远程工作区、文件下载、Python 环境和工具执行可以合到一个统一设计里，而不是继续各自生长。