# 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//zk-agent/sessions//output/a.jsonl jupyter:///root/zk_agent_workspaces//output/a.jsonl ssh:///home/user/zk_agent_workspaces//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//sessions// ``` 适合： - 本地开发。 - 单用户调试。 - 早期兼容。 问题： - 多用户隔离主要靠代码路径约束。 - 工具进程和平台服务权限一致，风险较高。 ### local_linux_user 平台托管的标准多用户工作区。 ```text 平台账号: banisherwy Linux runtime user: banisherwy workspace root: /home/banisherwy/zk-agent/sessions/ ``` 服务进程可以是 root，工具进程切换到普通 Linux 用户执行。 ```text root backend -> runuser -u banisherwy -- ``` 职责分工： ```text root 服务 创建 runtime 用户 初始化 workspace 设置 owner 和权限 启停进程 管理平台账号和 session 普通 Linux 用户 执行 bash/python 拥有自己的 workspace 拥有自己的 Python 虚拟环境 只能写自己的目录 ``` 推荐目录： ```text /home//zk-agent/ sessions/ / 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//zk-agent/` 数据。 - root 服务创建用户和改密码时必须走受控 helper，不能把用户输入拼成 shell 命令。 ### remote_jupyter 用户授权的远程工作区。 语义是： ```text 用户把自己已有权限的 Jupyter 环境接入平台。 平台代替用户在这个环境里执行。 ``` 这不是平台托管沙盒。权限边界来自用户提供的 Jupyter 凭证。 ```text Account: banisherwy Session: xxx Runtime: remote_jupyter Root: /root/zk_agent_workspaces/ 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//zk-agent/sessions//input/ remote_jupyter 上传文件 -> 通过 Jupyter API 写入 /root/zk_agent_workspaces//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//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/ 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/` 视为 `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//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//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//zk-agent。 ``` 长期建议： ```text 平台账号负责产品身份。 Workspace Runtime 负责执行环境。 Artifact 负责跨 runtime 文件抽象。 Executor 负责工具执行适配。 ``` 这样账户体系、Linux 子账户、Jupyter/SSH 远程工作区、文件下载、Python 环境和工具执行可以合到一个统一设计里，而不是继续各自生长。