wayne998998/dsh-rakazo

dsh-rakazo

给 AI 智能体一台属于它自己的计算机。

这将 Rakazo 的机器管理连接到
DeepSeek Harness，使一个智能体会话获得一台
一次性的 Linux 桌面：运行命令、读写文件、查看屏幕、驱动浏览器——
并在会话结束时被销毁。同一个 Team 的多个智能体可以共享一台计算机，
同时各自保留自己的屏幕。

它真正解决的问题是归属与授权，而不是“又一个 exec 包装器”：

- 身份是推导出来的，而不是被记住的。 botId = "dsh-" + scope，其中 scope 是会话 id
——或者在共享时是 Team 根。重启后的 harness 会自行重新认领同一台计算机：没有
状态文件、没有租约、没有心跳、没有清扫器。这些机制被移除，是因为它们正是那种
会自行出故障的部分，而其中之一确实出了问题：一台租约悄悄停止续期的计算机
在其会话仍然存活时被回收了。
- 边界是用凭据划定的。 三个令牌，刻意不可互换：harness
进程只持有 BRIDGE_TOKEN；Rakazo 的服务令牌留在无状态代理进程中；
沙箱监督者令牌从不外发。原因很直白——智能体可以读取自己的
环境，所以 bash 可以读取 /proc//environ。每台计算机的授权是一种能力：
由代理铸造，仅以哈希形式存储，保存在插件的内存中。知道另一个会话的
计算机 id 对你毫无用处。
- 共享是一种明说的权衡，分三步。 默认每个对话一台计算机。使用
share: true 时，一个 Team 的智能体使用同一台计算机，同时各自获得自己的屏幕（Rakazo
按屏幕身份为每个屏幕分配一个显示；三个观察者确实会产生三个 Xvfb 实例）。使用
account:  时，每个对话共享一台长期存活的机器，这正是复现一台
持久团队计算机的方式：跨对话相同的文件、相同的浏览器登录。每一步都以隔离换取
连续性，而最后一步完全放弃了跨对话隔离——所以
文档直白地说：不要把另一个对话不得使用的凭据放在共享计算机上。
共享计算机不是安全边界。

这个项目比功能更在意的两件事：

复杂性属于理解它的人。 机器生命周期、工作区检查点和
空闲挂起是 Rakazo 的职责。这一层只负责归属与授权，别的什么都不做。

主张需要可证伪的证据。 每一项检查都针对真实的 Rakazo 和真实的容器运行，并且
每一条承重断言都通过故意破坏该行为来验证——让 destroy
在不删除的情况下报告成功、移除屏幕命名、恢复有缺陷的共享模式防护——以
确认检查确实会失败。这种纪律也抓住了作者自己的两个测试，它们可能
从未失败，其中一次还支撑了一个错误的“已修复”结论。

快速开始

QUICKSTART.md —— 大约十五分钟即可跑通一个集成，其中包括人们最常弄错的两个步骤：Rakazo 需要两个补丁，它们不在上游；并且 pnpm --filter @rakazo/db generate 不是可选的。

如需完整演练、所有配置选项和操作指南，请使用 docs/deployment.md。

各部分如何协同

- Rakazo 负责机器：它配置 Docker 容器、维护持久工作区、暂停空闲计算机，并为其自身 UI 之外的程序暴露服务账户 API。
- DeepSeek Harness (DSH) 负责代理：会话、工具、子代理和 Agent Teams。

该集成由三部分组成，按信任顺序排列：

DSH agent session
│  native tools (bash/read/write/edit)  ──────────────┐
│  or rakazo_* tools                                   │
▼                                                      ▼
DSH plugin                                         fs/shell providers
(plugin/index.js)                                  (providers/.js)
│                                                      │
│  one bearer token: BRIDGE_TOKEN                       │
▼                                                      ▼
bridge (src/.mjs)  ── holds the Rakazo service token, keeps no state
│
│  one bearer token: EXTERNAL_COMPUTER_TOKEN
▼
Rakazo API  ──►  Docker container (browser, filesystem, terminal, displays)

为什么需要桥接

Rakazo 的服务令牌绝不能到达 harness 进程：代理可以运行 bash 并读取 /proc//environ。因此 Rakazo 凭据保留在桥接中，而 harness 只持有一个单独的 BRIDGE_TOKEN。桥接是一个无状态的凭据代理——它不保留数据库、不保留租约，也不在磁盘上保留状态。

每台计算机的授权是一种能力，由桥接在创建计算机时铸造，仅保存在插件的内存中，并通过哈希进行比较。调用方只能访问其持有能力的计算机，因此指定另一个会话的计算机名会失败。

代理能做什么

七个工具，由 plugin/index.js 注册：

| 工具 | 用途 |
| --- | --- |
| rakazo_computer_create | 创建或重新采用本会话的计算机 |
| rakazo_computers | 列出本会话的计算机，或用 computerId 报告某台计算机的状态 |
| rakazo_computer_exec | 运行一个 argv 命令（bash -lc 由你自己拼写） |
| rakazo_file | 读取或写入一个工作区相对路径的文本文件（op: read \| write） |
| rakazo_computer_observe | 截取桌面屏幕截图，以图像形式返回 |
| rakazo_computer_browser | 驱动浏览器：navigate、snapshot、act |
| rakazo_computer_destroy | 停止并删除一台计算机（幂等） |

providers/ 还会将 harness 的原生工具路由到计算机中，因此模型可以使用
纯 bash、read、write 和 edit，而不是包装器。关于这两条路径有何不同以及各自何时适用，参见
docs/architecture.md。

快速开始

前提条件：一个正在运行的 Rakazo，且已启用外部计算机接口；Docker、Node，以及一个
已构建的 DSH 检出。完整演练参见 docs/deployment.md。

1. 桥接凭据（仅所有者可读的文件，切勿提交）
cd /path/to/dsh-rakazo-bridge
cp .env.example .env
填写 BRIDGE_TOKEN（openssl rand -hex 32）和 RAKAZO_EXTERNAL_TOKEN
chmod 600 .env

2. 启动桥接
npm start                       # 监听 127.0.0.1:7400
curl -s http://127.0.0.1:7400/health

3. 将插件安装到 DSH profile
cd /path/to/dsh-rakazo-bridge
dsh plugin --profile web add ./dist/dsh-rakazo-computer-use/dsh-rakazo-computer-use-0.1.3.tgz
dsh --profile web --dump-config | grep -A6 rakazo-computer-use

需要一个已启用外部计算机接口的 Rakazo 部署——这是 Rakazo 侧的配置更改，详见
docs/deployment.md。

测试

三个测试套件，全部针对一个实时桥接、Rakazo 和真实容器运行。没有任何模拟，且每个
套件创建的每台计算机都会在结束前被销毁。

RAKAZO_ENV_FILE=/path/to/rakazo/.env npm run test:bridge   # 27 项检查 — 控制平面
RAKAZO_ENV_FILE=/path/to/rakazo/.env npm run test:screens  # 19 项检查 — 每屏一个显示器
DSH_HARNESS=/path/to/deepseek-harness npm run test:plugin  # 18 项检查 — 插件契约

test:bridge 和 test:screens 需要 Node、本仓库的 .env，以及指向
Rakazo 部署的 .env 的 RAKAZO_ENV_FILE。test:plugin 额外需要一个 Harness 检出，因为
harness 包只能在其自身的模块图下解析。每个套件都会销毁它创建的每台计算机，并断言没有
遗留任何东西。参见 docs/testing.md。

仓库布局

src/                 桥接：HTTP 控制平面，无状态
server.mjs         路由和请求日志
computers.mjs      所有权、能力、每台计算机的串行化
api-client.mjs     Rakazo API 客户端（持有服务令牌）
config.mjs         环境变量和仅所有者可读文件的加载
plugin/              DSH 插件：七个工具、身份、销毁
providers/           原生工具路由（fs + shell），基于同一桥接
test/                三个套件
patches/             必需的上游 Rakazo 更改 — 请先应用这些
dist/               用于 dsh plugin add 的打包 bundle
docs/                架构、部署、测试、安全

文档

| 文档 | 阅读目的 |
| --- | --- |
| QUICKSTART.md | 通往可用安装的最短路径，以及两个常见陷阱 |
| architecture.md | 三个组成部分、所有权模型、身份、屏幕 |
| deployment.md | 从零开始搭建并运行它 |
| testing.md | 每个测试套件证明了什么，以及如何扩展它们 |
| security.md | 信任边界、隔离保证了什么、没有保证什么 |
| contributing.md | 约定、需要保持的不变量、已知缺口 |
| patches/README.md | 所需的上游 Rakazo 变更 |

已知限制

这些限制是有意为之并记录在案的，而非偶然；完整列表见
contributing.md。

- keep: true 没有自动回收机制。 设置它后，会话消失的计算机永远不会被插件销毁；它会等待被重新接管，否则依赖 Rakazo 自身的空闲策略。默认情况下（未设置 keep）会在处置时销毁，这保证了关闭的对话不会留下任何容器。
- prune 需要会话存储。 插件会回收其所属会话已不存在的计算机，但仅在暴露了会话存储的组合中才能做到；没有它时，插件会记录一次跳过，而不是猜测，从而不碰这些计算机。
- 不支持后台命令执行。 Rakazo 的 exec 路由仅支持前台执行，因此 shell 提供者的 start() 会抛出一个描述性错误，而不是伪造一个进程句柄。
- 一台计算机就是一个安全边界。 共享一台计算机的队友可以读取彼此的文件和浏览器会话。这正是共享的意义，而非缺陷——见
security.md。

许可证

见 LICENSE。桥接器和插件是原创作品；Rakazo 和 DeepSeek Harness 仍受其各自许可证的约束。