Orbit 编排与浏览器插件 KasenRi/dsh-orbit-browser-plugins

DSH Orbit + Browser 插件

DeepSeek Harness（DSH）的社区插件。
与 DeepSeek 无隶属关系，也未获其背书。

让 AI 不只是回答问题，而是能持续执行、比较方案、验证结果，直到把任务真正做完。

这个仓库包含两个独立插件：

- @kasenri/dsh-orbit：确定性的长任务编排与审核系统。
- @kasenri/dsh-browser：受控浏览器自动化能力。

Orbit 可以独立使用；Browser 和 MoA 都是按需增强能力，不安装也不会影响 Orbit 的基础 SINGLE 执行模式。

Orbit 是什么

Orbit 的目标不是做一个「无限自动继续」的 Loop，而是给 DSH 增加一条有状态、有边界、可恢复、会自我审核的工程执行轨道。

你只需要给出最终目标，Orbit 会：

- 让 Commander（指挥官）规划 1–5 个明确步骤；
- 让 Executor（执行员）一次只执行当前步骤；
- 每个步骤完成后重新交给 Commander 审核；
- 发现问题时进入有界修正，而不是直接宣告成功；
- 发生超时、卡死或中断时，让 Smart Watchdog（监控模型）参与恢复；
- 将每个 DSH Session 的运行状态独立持久化到 .cx/sessions/<session-key>/state.json，支持中断后继续；
- 在最终成功前再次执行 Final Evaluation，而不是只相信 Executor 的自述。

核心流程：

用户目标 ↓ Commander 规划 ↓ 当前 Step ↓ SINGLE / MOA ↓ 真实执行与验证 ↓ Commander 审核 ↓ PASS / CORRECT / NEEDS_USER ↓ 下一步 ↓ Final Evaluation ↓ Final Watchdog Audit ↓ Commander Terminal Confirm ↓ SUCCESS

v0.6.2：Persistent Role Sessions

从 v0.6.2 开始，一个 Orbit Run 不再为每次 Commander / Executor 交接都创建全新的角色会话：

- PLAN、STEP_EVALUATE、STRATEGY_RECONSIDER、FINAL_EVALUATE 默认继续同一个 Commander Session；
- 连续 Step 的工具权限集合一致时，默认继续同一个 Executor Session；
- Executor 权限集合发生变化时会自动轮换，避免为了复用上下文而扩大权限；
- Commander 可以在结构化决策里请求 executor_session: RESET，但真正的关闭/创建仍由 Supervisor 执行；
- Watchdog、MoA Candidate、MoA Judge 继续保持一次性隔离调用；
- 角色 Session ID、generation、turns、resets 与 Token usage 会写入当前 Run 的 durable state 中，用于恢复和诊断。

因此默认路径会从「每个阶段一个新 Agent」变成「一个 Run 主要只有一个 Commander + 一个 Executor」，减少重复项目探索和重复上下文建立，同时保留权限隔离和确定性轮换。

v0.6.3：Trusted Execution Evidence

v0.6.3 补齐 Executor → Supervisor → Commander 的可信执行证据链：Orbit 会从已结算的 DSH tool/call + tool/result 中提取经过脱敏和限长的真实结果摘要、显式 exit code，以及可识别的测试命令。对于 run_code 中可确定识别的字面 tools.bash({ command: ... })，Orbit 会把嵌套 shell 命令与对应真实输出关联起来。Commander 会明确区分 [TRUSTED_TOOL_EVENTS] 与 [EXECUTOR_SUMMARY_UNVERIFIED]，因此已有真实 stdout / exit code / 测试汇总时，不再需要为了重复证明而申请 shell 或让 Executor 额外落盘临时 evidence 文件。

v0.6.4：Heartbeat Watchdog & Deterministic Completion Gate

v0.6.4 把 Watchdog 从「出错后才介入」扩展为 事件触发 + 周期主动巡检 两条路径。默认每 120 秒进行一次 one-shot Heartbeat Review；连续健康后可退避到 180 秒，可疑状态会缩短到 60 秒复查。Heartbeat 读取 Supervisor 生成的有界运行快照，包括 meaningful progress、Session generation、当前工具和真实事件年龄，但它本身不会消耗 Orbit loop，也不会占用 runtime Watchdog 的每 Step 恢复次数。Watchdog 返回时 Supervisor 会重新核对 run/phase/step/child/generation 指纹；运行已经推进时，旧决策被标记为 STALE_HEARTBEAT 并丢弃。

最终关闭流程也改为 fail-closed：Commander 的 FINAL_EVALUATE → SUCCESS 只是完成候选，随后必须通过 one-shot FINAL_AUDIT，再由 Persistent Commander 在 TERMINAL_CONFIRM 阶段调用专用 orbit_run_complete({ signal: "COMPLETE" })。Supervisor 最后还会机械检查所有 Step 已通过、没有活动执行步骤、Final Audit 指纹仍有效且没有等待用户输入，全部满足后才写入真正的 SUCCESS / CLOSED。普通文本「完成」不会关闭 Run。

v0.6.5：Session Persistence Hotfix

真实 Web Profile Live Apply 暴露了一个 DSH 兼容性边界：当前 DSH 的 Session.append() 还没有给外部插件开放 envelope-level ignorable: true 写入接口，而持久化 reader 会拒绝未知且非 ignorable 的自定义 Session event。v0.6.5 因此停止在当前 Harness 上持久化未被核心词汇识别的 orbit/runtime event，避免 Session 在冷读取/重启后变成不可恢复日志。Orbit 的权威运行状态仍然保存在项目 .cx durable state 中；v0.6.6 起新 Run 使用 Session-scoped 路径。只有未来 Harness 原生识别 orbit/runtime 时才会恢复该 Session runtime projection。

v0.6.6：Session-scoped Runs

v0.6.6 修复了此前「同一项目只有一个 .cx/state.json，导致一个聊天会话的活动 Run 阻塞所有其他会话」的问题。现在每个 DSH Session 都拥有独立的 Orbit Run、状态文件和 persistent Commander / Executor：

同一项目 ├─ Session A → .cx/sessions//state.json → 独立 Orbit Run ├─ Session B → .cx/sessions//state.json → 独立 Orbit Run └─ Session C → .cx/sessions/<C>/state.json → 独立 Orbit Run

- Session A 的 NEEDS_USER、active Run 或 stop/status 不再锁住 Session B。
- v0.6.5 及更早版本的 .cx/state.json 如果带有 owner_session_id，会在所属 Session 下一次写入时自动迁移到新的 Session 路径。
- 多个 Session 可以同时规划、审核和推进；如果它们共享同一个物理 checkout，可写 Executor turn 会按 workspace 串行，避免同一时刻交叉写文件。
- Orbit 与 Goal / Workflow / Ralph / 独立 /moa 的顶层 mutation fence 仍然按整个 workspace 生效。

v0.6.7 Session resume hotfix

v0.6.7 补齐显式 resume 路径的 Session 传递：当调用方已经给出当前 DSH Session，NEEDS_USER 恢复重新进入 run() 时会继续显式携带同一个 owner_session_id，不依赖隐式 initiator 上下文。Session-scoped Runs、旧状态迁移和 workspace mutation lease 语义均保持不变。

v0.6.x：Orbit 接入 MoA 多候选执行

从 v0.6.0 开始，Orbit 可以把少量高不确定性步骤交给 MoA 多候选模式。

这不是让 MoA 接管 Orbit，也不是启动另一套顶层工作流。Orbit 仍然是唯一的 Supervisor；MoA 只负责在某个 Step 内：

1. 让 2–4 个 Candidate 独立提出方案；
2. 让 Judge 比较已有候选并选出一个 Winner；
3. 由 Orbit Supervisor 受控写回胜出候选；
4. 再交给普通 Executor 做真实测试和验证；
5. 最后仍由 Commander 判断当前 Step 是否真正通过。

Orbit Supervisor
│
┌────────────┴────────────┐
│ │
SINGLE MOA
│ │
Executor ┌───────────┼───────────┐
│ ↓ ↓ ↓
│ Candidate 1 Candidate 2 Candidate 3
│ └───────────┼───────────┘
│ ↓
│ Judge
│ ↓
│ Winner
│ ↓
│ Orbit 受控 Promotion │ ↓ └──────────────────── Executor ↓ 真验证 ↓ Commander ↓ PASS / CORRECT / NEEDS_USER

几个关键边界：

- Candidate 和 Judge 都是零工具模型调用，不能直接修改项目。
- 候选方案只写入 .cx/moa/<run>/<step>/candidate-N/ 隔离区。
- Judge 只负责判断「哪个候选相对更好」，不能决定 Step PASS。
- Winner 写回后，仍然必须经过 Executor 的真实测试和 Commander 的最终验收。
- 一个 MoA Step 只消耗一个 Orbit loop，但调用候选模型会额外产生 Token / 成本。
- MoA Route、候选数、Judge、Reasoning 等在创建 Run 时冻结，中途修改 UI 只影响下一个 Run。
- Orbit ACTIVE 时会阻止独立的 /moa 抢占同一个 workspace。

启用 MoA：需要自行安装 dsh-moa

MoA 不是 Orbit 的内置依赖。

只安装 Orbit 时，SINGLE 模式完全可用；如果希望在 Orbit 中启用「MoA 多候选模式」，必须另外安装：

dsh plugin --profile web add @goodandready/dsh-moa

Orbit 当前接受：

@goodandready/dsh-moa >= 0.2.19

已在真实 DSH 环境验证：

0.2.19 ✓
0.2.20 ✓

Orbit 不会主动给更高版本设置版本上限；如果未来 MoA 的公开 API 出现实际破坏性变化，再按真实故障修复。

安装完成后，在 Orbit 的模型菜单中：

MoA 多候选模式 [开关] >

进入二级菜单配置：

- 候选数量：2–4；
- Candidate 1–4 的模型与 Reasoning；
- Judge 评审模型与 Reasoning；
- 是否启用一轮候选互评；
- 每个 Run 最多允许多少个 MoA Step。

开启 MoA 只是允许 Commander 为合适的步骤选择 MOA，并不意味着每一步都会强制运行多个模型。

Browser：需要网页操作时再安装

@kasenri/dsh-browser 给 DSH 增加真实浏览器操作能力。Orbit 不依赖 Browser；只有当某个 Step 声明 browser capability 时才需要它。

Browser 可以打开网页、点击、输入、读取页面、下载文件，并带有域名限制、状态保护和 stale-ref 检查等安全边界。

组合起来，一个工程任务可以同时拥有：

Orbit
├─ 多步骤规划 / 审核 / 恢复 ├─ SINGLE 执行 ├─ 可选 MoA 多候选选优 └─ 可选 Browser 网页操作

技术概览

这个 monorepo 发布两个独立的 Cordis 插件：

| 包 | 角色 |
| @kasenri/dsh-orbit | 确定性工程编排（orbit_controller 工具 + OrbitService）。 |
| @kasenri/dsh-browser | 受控浏览器自动化（agent_browser 工具 + BrowserAutomationService）。 |

Orbit 采用有界的 Commander / Executor / Smart Watchdog 架构：

PLAN → EXECUTE → EVALUATE → CORRECT / RECOVER → SUCCESS

DeepSeek Harness
│
├─ Native infrastructure: agents / subagents / tools / sessions
│
├─ @kasenri/dsh-orbit
│ ├─ OrbitService (per-Session durable state in <project>/.cx/sessions/...)
│ ├─ Deterministic Supervisor
│ ├─ Commander / Executor / Smart Watchdog
│ ├─ Optional MoA Adapter → Candidate fan-out / Judge / controlled promotion
│ └─ Recoverable guards
│
├─ @goodandready/dsh-moa (optional, required only for Orbit MoA mode)
│
└─ @kasenri/dsh-browser
└─ agent_browser → agent-browser CLI → Chromium / Chrome / CDP

环境要求

| 组件 | 测试版本 |
| @deepseek-ai/dsh | 0.1.5-rc.2 |
| @deepseek-ai/cordis | 4.0.2 |
| @goodandready/dsh-moa（仅 Orbit MoA 模式需要） | >=0.2.19；已验证 0.2.19、0.2.20 |
| agent-browser (browser plugin) | 0.33.2 |
| Node.js | >= 22.19.0 |

DSH 目前处于开发者预览阶段；这些插件只针对上述版本做过测试，不保证兼容未来的每一个 DSH 版本。

安装

两个包都已发布到 npm Registry。pnpm 必须在 PATH 中。

Orbit plugin only
dsh plugin --profile web add @kasenri/dsh-orbit

Browser plugin only
dsh plugin --profile web add @kasenri/dsh-browser

Both (Orbit browser-capability steps may then use the browser plugin)
dsh plugin --profile web add @kasenri/dsh-orbit
dsh plugin --profile web add @kasenri/dsh-browser

可选：启用 Orbit MoA 候选模式（需单独安装）
dsh plugin --profile web add @goodandready/dsh-moa

专用的 Git 分发镜像（github:KasenRi/dsh-orbit 和 github:KasenRi/dsh-browser）跟踪镜像仓库的 HEAD，当你更倾向用 Git 源时仍可使用；源码 monorepo 的带版本 GitHub Release tarball 则保留给手动安装或离线安装。

每个包都声明了 dsh.bundle 清单，因此 dsh plugin add 会自动安装它，并把它注册为配置档层。配置说明见各包的 README：

- Orbit 配置
- Browser 配置

快速开始

启动 Orbit 最确定的方式是用斜杠命令：

/agent-orbit 修复当前项目的 TypeScript 错误并运行测试

如果另外安装了 @goodandready/dsh-moa，可以在 Orbit 菜单中开启 MoA 多候选模式。开启后只是允许 Commander 为少量高不确定步骤选择 MOA；普通步骤仍然可以继续使用 SINGLE Executor。没有安装 MoA 时，Orbit 的基础功能完全不受影响。

Orbit 支持三种激活方式：

1. /agent-orbit <goal> —— 确定性的斜杠命令激活（Web GUI 斜杠菜单，或在 headless/CLI 界面上真实的用户消息手势）。
2. orbit模式 —— 推荐的自然语言激活方式。
3. cx模式 —— 旧版兼容；仍然会解析到 Orbit。

在 Web GUI 中，Orbit 模型控件紧挨着原生模型座位左侧。Commander/Watchdog 会持久化到 DSH 设置，Executor 跟随当前会话模型，可选的 MoA Candidate/Judge 路由放在专门的二级菜单里。每次新运行都会为它需要的每条生效路由做快照；恢复运行时沿用这些冻结的路由。

Orbit（typed tool，与斜杠命令激活的是同一个入口）
orbit_controller { "action": "run", "goal": "…", "approved_loop_count": 4 }
orbit_controller { "action": "status" }

Browser
agent_browser { "args": ["open", "https://example.com"] }
agent_browser { "args": ["snapshot", "-i"] }
agent_browser { "args": ["click", "@e2"] }
agent_browser { "args": ["snapshot", "-i"] }

安全

- Orbit：Commander 和 Watchdog 使用只读允许列表，Executor 使用写入允许列表，浏览器工具只对声明了相应能力的步骤开放，单变更所有者围栏，有界纠正与循环预算，以及可恢复的守卫拒绝——只停掉一次工具调用，而不是整个运行。
- Browser：页面作用域引用与过期引用拦截，标签页漂移检测并配一次确定性恢复，产物校验，受保护的浏览器状态拦截，凭据脱敏，严格的 allowedDomains 限制，且不绕过 CAPTCHA/OTP/2FA。

从 CX 迁移

见 packages/orbit/README.md。简而言之：dsh-cx → dsh-orbit，cx_controller → orbit_controller，CX 模式 → Orbit 模式，ctx.cx → ctx.orbit。旧版 .cx/state.json 仍然可读、按所有者隔离的状态会自动迁移到 .cx/sessions/...；旧版 cx模式 仍然支持。

开发

npm install
npm run typecheck
npm test # unit tests
npm run test:e2e # real Cordis host end-to-end
npm run test:smoke # real Chromium / CDP / Orbit browser smokes
npm run build # emit lib/ for both packages

测试套件覆盖单元测试、runner 集成测试、真实 Cordis 主机的端到端测试，以及真实 Chromium 的冒烟测试。DeepSeek Orbit 冒烟测试（npm run smoke:deepseek）需要真实模型凭据，不在默认套件内。

分发镜像

本仓库是权威源码 monorepo。npm Registry 承载主发布；可安装的 Git 源是生成的发布镜像 KasenRi/dsh-orbit 和 KasenRi/dsh-browser。不要在镜像里开发功能。发布测试和 npm run build 通过后，用下面的命令同步一个明确的稳定版本：

npm run sync:distribution -- 0.5.7 --push

脚本只复制每个包的 package.json、cordis.patch.yml、README.md、LICENSE 和预构建的 lib/。它会更新镜像的 main 分支，并创建缺失的包版本 tag；普通开发提交永远不会自动发布到镜像。本仓库 GitHub Releases 里的版本化 tarball 仍可用于手动或离线回退。

许可证

MIT