wuyang/zk-data-agent

Fork 0

Files

T

wuyang6 ee596a33e0 Add Linux account workspace runtime

2026-05-20 14:13:34 +08:00

15 KiB

Raw Blame History

Workspace Runtime 设计稿

背景

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

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

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

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

核心结论

账户体系分两层：

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

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

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

目标

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

非目标

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

对象模型

Account

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

Account
  id
  username
  display_name
  role
  status
  created_at
  updated_at

职责：

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

Session

Session 是一次 Agent 对话任务。

Session
  id
  account_id
  runtime_id
  title
  status
  created_at
  updated_at

职责：

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

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

Workspace Runtime

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

WorkspaceRuntime
  id
  account_id
  session_id
  type
  root
  permissions_source
  status
  created_at
  updated_at

type 可以是：

local_process
local_linux_user
remote_jupyter
remote_ssh

职责：

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

Artifact

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

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

uri 可以是：

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 之间的执行适配层。

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

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

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

适合：

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

问题：

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

local_linux_user

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

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

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

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

职责分工：

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

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

推荐目录：

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

推荐约定：

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

这样用户体验更直接：

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

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

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

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

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

需要注意：

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

remote_jupyter

用户授权的远程工作区。

语义是：

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

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

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 类似：

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

remote_ssh 更适合：

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

但它也更复杂：

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

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

权限边界

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

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

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

UI 可以显示：

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

或者：

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

Tool 调用关系

目标关系：

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

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

例如：

python_exec
  -> executor.run_python(...)

write_file
  -> executor.write_file(...)

download_artifact
  -> executor.open_file_stream(...)

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

文件策略

输入文件

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

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/。

output/
  records.jsonl
  report.md
  samples.csv

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

name
size
mtime
uri
runtime_id

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

Python 环境策略

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

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。

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。

第一阶段可新增这些表：

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。

与现有实现的关系

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

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、长连接、文件传输和远程进程清理。

关键待决问题

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

15 KiB Raw Blame History Unescape Escape