hanxuanliang/dsh-chaos

为 DeepSeek Harness 内的 Agent 提供持久化对等协作。

dsh-chaos 为官方 DSH Web UI 添加了一个本地协作工作区。创建稳定的 Agent，将它们引入 Channel，在 Thread 中讨论工作，将 Message 转化为 Task，并通过真实可信的 Activity 视图跟踪进度。协作记录存储在事务性本地账本中，可在浏览器刷新、插件重启和 Agent 会话替换后依然保留。

[!IMPORTANT]
版本 0.1.2 面向 DSH 0.1.0-rc.7 包系列。

[!WARNING]
每个由 Chaos 管理的 Agent Session 都以 DSH 的 danger-full-access 权限预设启动。Agent 可以在无需审批提示的情况下运行命令，并可以读取、修改或删除运行 DSH 的操作系统账户可访问的任何文件；这不会授予超出该账户的权限。请仅在受信任的模型以及适当隔离的账户或机器上使用 Chaos。这是当前固定的策略，而非用户可选择的设置。

灵感来自 Raft

dsh-chaos 源于对 Raft 的真诚敬佩。Raft 展示了如何将人类与 Agent 的协作视为一个持久化的产品系统：对话、任务、交付、归属和恢复都是明确的共享事实，而非隐藏在模型记录中的细节。

Chaos 借鉴了这种思维方式，并通过独立实现将这一灵感带入 DeepSeek Harness。Raft 始终是最初的灵感来源，也是这项工作深深尊重的项目；dsh-chaos 与 Raft 无关联，也未获得其认可。

截图

| 界面 | 预览 |
| --- | --- |
| Channel 与 Thread |  |
| Task 看板 |  |
| Agent 管理 |  |

它新增了什么

| 能力 | 它改变了什么 |
| --- | --- |
| 稳定的 Agent | 即使其 DSH Session 被替换，Agent 仍保留一个身份、本地自定义头像、Charter、受管理的 Workspace、Channel 成员关系和运行时配置。 |
| Channel 与 Thread | Channel 带有 Agent 可见的用途和由所有者管理的 active/archive/delete 生命周期；Thread 继承父级访问权限，而 Follow 控制普通 Agent 的投递。 |
| Task 生命周期 | 任何 Message 都可以锚定一个带编号的 Task，并具有明确的 claim、assignee、status、version fencing 以及 Channel task board。 |
| 权威投递 | Message、recipient Delivery 和 wake watermark 原子性提交，因此重启恢复不依赖于 provider transcripts 或浏览器状态。 |
| 活动收件箱 | 活跃对话由已提交的 Messages、Thread follows、Tasks 和 Done fences 投射而来，而非猜测的客户端计数器。 |
| 官方 DSH 接口 | 该插件使用 DSH 提供的 Sidebar、Settings、overlay、runtime、provider/model catalog、Agent Presets 和 Workspace API。 |

快速开始

前置条件

- Node.js ^22.19.0 或 >=24.0.0
- pnpm 9
- 从 0.1.0-rc.7 包系列安装的 dsh CLI

从 npm 安装预构建插件：

dsh plugin --profile web add @hanxuanliang/dsh-chaos@0.1.2

或从 GitHub 安装相同标签的源码：

npx @deepseek-ai/dsh@0.1.0-rc.7 plugin --profile web add github:hanxuanliang/dsh-chaos#v0.1.2

两种方式都会为当前平台选择预构建的原生模块；用户无需 Rust 工具链。支持的目标平台为 Linux x64（glibc）、Windows x64、macOS x64 和 macOS arm64。

如果 pnpm 明确报告 GitHub 包的构建被阻止，请使用 --allow-build=@hanxuanliang/dsh-chaos 重试。已发布的 npm 安装不会运行原生构建。

若要改为构建并链接当前检出内容，请安装 Rust 并运行：

pnpm install --frozen-lockfile
pnpm build
dsh plugin --profile web add --workspace-root "$PWD"
dsh --profile web --dump-config
dsh web

插件安装仍会链接到该检出内容。当宿主 TypeScript、原生模块、bundle patch 或包清单发生变化时，请重新构建已更改的源码并重启 DSH。仅客户端重新构建只需刷新浏览器。

创建第一个协作

1. 打开 Settings → Collab Agents。
2. 创建一个 Agent，填写名称、Charter、provider、model 和 Agent Preset。其 Workspace 由 DSH 管理。
3. 从 Sidebar 打开 Collab。
4. 创建一个 Channel，描述其用途，并将该 Agent 添加为初始成员。
5. 从 Channel 编辑器发送一条 Message。当该 Message 也应成为被跟踪的工作时，使用 As task。
6. 打开 Message 的回复入口以在 Thread 中继续，或切换到 Task 看板以认领工作并推动其完成生命周期。

Provider 凭据仍由 DSH 负责。在期望 Agent 生成模型回复之前，请先在 DSH 中配置所选 provider。

工作原理

1. 浏览器以固定的本地 Web User 身份发送经授权的 loopback RPC。
2. Rust 在一个 Turso 事务中提交 Message、收件人 Deliveries、wake watermark 和 change-ledger 事件。
3. 投递桥接以不含内容的通知唤醒每个当前 Agent runtime generation。
4. Agent 检查其持久收件箱，并接收确切的 Messages 以及稳定的身份、Charter、目标和带角色的成员上下文。
5. 模型已读回执和 Agent 写入受当前 Session generation 的围栏保护，因此过期的 Sessions 无法代表该 Agent 进行确认或操作。
6. SSE 使浏览器投射失效；客户端重新读取权威的 Rust/Turso 状态，而不是将事件流视为事实来源。

默认数据位置为：
$DSH_HOME/collab/state.db
$DSH_HOME/agents//

第一个路径是协作账本，包含有界的自定义 Agent 头像图片。第二个是每个稳定 Agent 的受管工作区根目录。

DSH 集成

| DSH 接缝 | 插件用途 |
| --- | --- |
| Cordis Service 生命周期 | 持有 Rust 句柄、运行时桥接、投递轮询器、保留任务以及关闭顺序。 |
| Agent 预设与目录 | 为每个 Agent 运行时解析提供方、模型、预设和提示词组合。 |
| Agent 循环与工具 | 恢复当前 Agent 会话，并从受信任的执行上下文推导工具身份。 |
| 连接 RPC 与 Web 服务器 | 暴露固定主体的回环 RPC 以及按接收方过滤的 SSE 重放。 |
| 侧边栏、设置与布局槽位 | 挂载 Collab 工作区和稳定 Agent 管理，而无需分叉 DSH 客户端。 |

任务与关注语义

- 任务状态遵循 todo → in_progress → in_review → done，仅允许显式允许的回退转换。
- 认领和状态变更使用乐观版本；并发认领只有一个胜出者。
- 线程可通过父级授权读取。关注影响普通投递和唤醒，而不影响已获授权的打开线程是否可以刷新。
- 活动 Done 是单调栅栏：更新的已提交消息会使对话重新变为活跃。
- SSE 携带失效和重放游标。快照和历史 RPC 仍然是权威来源。

配置

默认值适用于本地 DSH Web 配置文件。

| 字段 | 默认值 | 用途 |
| --- | --- | --- |
| path | $DSH_HOME/collab/state.db | 本地 Turso 数据库路径。 |
| deliveryPollMs | 500 | 扫描电平触发的待处理 Agent 唤醒的间隔。 |
| remoteEnabled | true | 启用回环浏览器 RPC 和 SSE 接口。 |
| webUserHandle | 操作系统用户 slug | 本地浏览器主体的稳定句柄；回退为 user。 |
| webUserDisplayName | 操作系统用户 | 本地浏览器主体的可选显示名称覆盖。 |
| sseHeartbeatMs | 15000 | 浏览器变更流的心跳间隔。 |

配置文件覆盖示例：

- id: dsh-chaos
config:
deliveryPollMs: 250
sseHeartbeatMs: 10000

数据与安全边界

- DSH 被视为本地产品。浏览器 RPC 和 SSE 接受受信任的回环、同源请求；此插件不添加远程多用户身份验证。
- 所有浏览器标签页共享一个固定的本地 Web 用户。浏览器不允许冒充 Agent。
- Agent 编写的工具调用从受信任的 DSH 执行上下文推导身份，而不是从调用方提供的 ID 推导。
- 每个新创建或重置的 Chaos Agent 会话，在其运行时绑定发布之前，都会被持久地固定到 DSH 的 danger-full-access 权限预设（sandbox: danger-full-access、approval: never）。恢复会话时会重放其固定的权限事实，而不是静默重写它们。
- 该插件存储 provider/model/Preset 引用，而非 provider 凭据。Provider 凭据保留在 DSH 中。
- Turso 是持久化的唯一事实来源。Provider 转录记录和浏览器缓存不是协作权威。
- 一个本地 DSH 宿主进程拥有数据库和运行时桥接。针对同一文件协调多个进程不在当前契约范围内。
- 已发布的安装包会自动选择特定于平台的本地包。0.1.2 中不支持 Linux arm64、Linux musl 和 Windows arm64。
- 在开发该插件时，源代码检出可以使用 Rust 在本地构建本地模块。

测试

运行隔离的官方宿主浏览器场景：

pnpm test:e2e

它会创建一个临时 DSH 配置文件，安装检出内容，在回环端口上启动 DSH 和 Chromium，创建并编辑一个 Channel，验证归档/恢复的只读行为，发送一条已提交的 Message，验证重新加载后的持久性，检查 650x800 布局，捕获截图，并在出现浏览器或请求错误时失败。它不需要 provider 凭据，也不会触碰默认的 DSH 配置文件。

有关快速重建循环、边界冒烟测试、E2E 控制、证据规则以及完整的本地门禁，请参阅测试。

文档

| 指南 | 涵盖内容 |
| --- | --- |
| 测试 | 快速验证、隔离的官方宿主 E2E、证据以及故障排查。 |
| 本地开发 | 链接式开发安装、重建/重启边界以及 tarball 测试。 |
| 发布 | 多平台本地包、npm/GitHub 发布顺序以及首次发布的凭据。 |
| 文档索引 | 受支持的产品和贡献者文档。 |

开发

pnpm typecheck
cargo test --workspace
pnpm build
pnpm smoke:native
pnpm smoke:service
pnpm smoke:runtime
pnpm smoke:remote
pnpm smoke:transport
pnpm smoke:client

托管的 CI 门禁还会强制执行 Rust 格式化以及启用所有特性的 Clippy，并将警告视为错误。用户可见和跨层的更改还应针对匹配的官方 DSH CLI 通过 pnpm test:e2e。

许可证

MIT