KasenRi/dsh-orbit

@kasenri/dsh-orbit

本仓库是 @kasenri/dsh-orbit 0.6.1 的可安装发布镜像。
规范源：https://github.com/KasenRi/dsh-orbit-browser-plugins/tree/main/packages/orbit
请勿在此处开发功能；请从规范源 monorepo 发布变更。
DeepSeek Harness（DSH）的社区插件。
与 DeepSeek 无关联，也未获得其认可。

让 AI 不只是“连续回答”，而是按照一个可恢复、可审核、有边界的工程流程把任务真正做完。

Orbit 是一个面向 DeepSeek Harness 的确定性长任务编排器。它把“规划、执行、审核、纠错、恢复、最终验收”拆成明确角色，并把真正的流程控制权留在 Supervisor，而不是交给模型自由循环。

从 v0.6.x 开始，Orbit 还可以选择性接入 MoA 多候选执行：当某个关键步骤存在多种合理实现路线时，Orbit 可以让多个 Candidate 独立给出方案，再由 Judge 做相对选优，最后仍由 Orbit 写回、真实验证并由 Commander 最终验收。

核心能力

- Commander：负责计划、步骤审核、最终审核和策略调整。
- Executor：一次只执行当前 Step，并负责真实工具调用与验证。
- Smart Watchdog：只在运行异常时介入诊断和恢复。
- Durable State：运行状态持久化到 /.cx/state.json，支持冷恢复。
- Bounded Loop：Plan、Correction、Watchdog 和 Append 都有明确上限。
- Route Freeze：Run 创建后冻结角色模型与 Reasoning，中途改 UI 只影响下一次 Run。
- Mutation Fence：一个 workspace 同一时间只允许合法的 Orbit 修改驱动者。
- 可选 MoA：高不确定 Step 可以走 2–4 候选 + Judge 的多方案竞争。
- 可选 Browser：需要真实网页操作时再配合 @kasenri/dsh-browser。

核心状态机：

PLAN → EXECUTE → EVALUATE → CORRECT / RECOVER → SUCCESS

普通 SINGLE Step：

Commander
↓
Executor
↓
真实测试 / Evidence
↓
Commander
↓
PASS / CORRECT / NEEDS_USER

MoA Step：

Commander
↓
Candidate 1 ─┐
Candidate 2 ─┼→ Judge → Winner
Candidate 3 ─┘              ↓
Orbit 受控写回
↓
Executor
↓
真验证
↓
Commander

MoA 是可选能力，不随 Orbit 自动安装

只安装 Orbit，就可以正常使用完整的 SINGLE 模式。

如果你希望在 Orbit 中开启：

MoA 多候选模式

需要自行另外安装 @goodandready/dsh-moa：

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

Orbit 当前接受：

@goodandready/dsh-moa >= 0.2.19

已在真实 DSH 环境验证：

0.2.19  ✓
0.2.20  ✓

更高版本不会被 Orbit 主动设置上限。如果上游未来发生真实 API 不兼容，再按实际故障修复。

安装 MoA 后，在 Orbit 菜单中打开：

MoA 多候选模式      [开关]  >

进入二级菜单配置候选数量、Candidate 模型、Judge、Reasoning、候选互评和每个 Run 最大 MoA Step 数。

开启 MoA 不代表每个 Step 都会运行多个模型。 Commander 仍然可以让普通步骤走 SINGLE，只在适合的高不确定步骤选择 MOA。

Orbit 与 MoA 的职责边界

Orbit 集成 MoA 后，顶层控制权不会改变：

- Orbit Supervisor 仍然是唯一流程控制者。
- Candidate / Judge 都是零工具模型调用，不能直接修改项目。
- 候选方案只写入 .cx/moa///candidate-N/。
- Judge 只能从已有成功候选中选择 Winner，不能自己生成新的“第四方案”。
- Judge 只做相对选优，不能决定 PASS_CURRENT_STEP。
- Winner 由 Orbit Supervisor 受控 Promotion 到项目目录。
- Promotion 后仍然必须让 Executor 做真实测试。
- 最终仍由 Commander 决定 PASS / CORRECT / NEEDS_USER。
- Orbit ACTIVE 时会阻止独立 /moa 抢占同一 workspace。

因此可以把两者理解成：

Orbit 决定任务怎么走；MoA 只负责在困难步骤里多想几个答案再选一个。

环境要求

| 组件 | 测试版本 |
|---|---|
| @deepseek-ai/dsh | 0.1.5-rc.2 |
| @deepseek-ai/cordis | 4.0.2 |
| @goodandready/dsh-moa（可选） | >=0.2.19；已验证 0.2.19、0.2.20 |
| Node.js | >= 22.19.0 |

需要 DSH 基础服务：agents、subagents、tools、sessions
（standard/web 配置文件会提供这些服务）。

安装

安装当前稳定的 Git 源，以便 DSH 可以将锁定的提交与仓库 HEAD 进行比较：

dsh plugin --profile web add github:KasenRi/dsh-orbit

规范的源 monorepo 还保留了带版本的 GitHub Release tarball，用于手动或离线安装。

用法

orbit_controller 工具驱动运行：

| 操作 | 含义 |
|---|---|
| run / start | 为某个目标启动一次运行（或继续当前运行）。 |
| resume | 在中断后继续已持久化的运行。 |
| status | 检查阶段、计划、循环预算和最后一次错误。 |
| stop | 关闭运行。 |
| doctor | 只读的环境和配置检查。 |

// orbit_controller
{
"action": "run",
"goal": "…",
"approved_loop_count": 4,
"user_hard_constraints": ["only touch src/"]
}

激活

Orbit 支持三种激活方式：

1. /agent-orbit  — 确定性的斜杠命令激活。在 Web
GUI 中，它会出现在 / 菜单中（使用 Orbit 确定性工程编排执行目标）；在无头/CLI 界面上，一条以 /agent-orbit 开头的真实用户消息
会直接激活 Orbit。原始
命令行会保留在对话中可见，目标会原样传递
而不被改写，并且不会出现目标要求提供目标而不是启动空运行的情况。
2. orbit模式 — 推荐的自然语言激活方式，例如
“用 orbit模式完成这个项目”。
3. cx模式 — 旧版兼容；仍会解析为 Orbit。

这三种途径都汇聚到现有的 orbit_controller 工具和
OrbitService；激活层绝不会自行启动运行。
在硬激活的运行达到 SUCCESS 后，发起会话会直接显示
最终 Commander 的用户可见结果，并带有 Commander 冻结的
provider/model 来源信息。父模型和父工具仍然被绕过。

模型配置（Web）

Orbit 模型控件是 conversation.input.right 中的最后一项，因此
其他编辑器侧控件（例如 DSH 的回滚控件）会留在它的
左侧，而原生 conversation.input.model 位置则紧挨着它的
右侧。它的按钮会显示 Commander 的模型。一级菜单保持紧凑：
Orbit 开关、Commander、Executor、Watchdog，以及一个 MoA 多候选模式 条目。所有
Candidate/Judge 细节都位于 MoA 二级菜单中。

- Commander 和 Watchdog 从同一个原生模型目录中选择，
并持久化到 DSH orbit 设置命名空间（settings.yaml）。选择
模型时会先打开推理选择；在用户选择
目录声明的 effort 或 provider 默认值之前，不会保存任何内容。不会推断任何 effort。
- Executor 遵循当前会话模型（“Follows current session
model”）。Orbit 行和原生位置读取和写入的是同一个
每个会话的 ModelDirectory，因此任一处的更改都会更新另一处。
- MoA Candidate / Judge 路由仅出现在 MoA 二级菜单内。
Candidate 数量和 max-MoA-step 值使用显式选择器，而不是
点击循环控件。

新运行会且仅会解析一次其路由——Commander/Watchdog 来自 orbit
设置，Executor 来自发起会话的当前选择——并将其冻结
到 state.routes 中。Orbit 不附带任何 provider/model 或 reasoning 默认值。
运行处于活动状态时所做的更改会应用于下一次运行；恢复的运行会保留
其冻结的路由。无头/CLI 允许显式 profile 路由：
Commander/Watchdog 先使用设置，再使用显式配置；Executor 使用 Session
选择，仅当没有 Session 时才使用显式配置。缺失或
不可用的角色会在任何子项启动之前阻止 Run 的创建。

可选的 MoA 执行模式

需要额外安装 @goodandready/dsh-moa。只安装 Orbit 时，SINGLE 模式仍然完整可用。

Orbit 可以把少量高不确定性步骤标记为 execution_mode: "MOA"。这不是新的顶层 Supervisor，也不会把状态机交给 MoA：

Commander PLAN
↓
SINGLE ─────────────→ Executor
\
MOA → Candidate 1 ─┐
Candidate 2 ─┼→ Judge → Orbit controlled promotion → Executor verification
Candidate 3 ─┘
↓
Commander STEP_EVALUATE

关键边界：

- Candidate 和 Judge 都是零工具的一次性模型调用，不能直接 write/edit/bash/subagent。
- 候选文件只写入 .cx/moa///candidate-N/，普通 Executor 不能修改 .cx。
- Judge 只负责在已有候选中做相对选择，必须返回 WINNER_CANDIDATE_INDEX；它不能决定 PASS_CURRENT_STEP，也不能生成新的综合实现。
- 胜出候选由 Orbit Supervisor 确定性提升到项目目录；之后仍由 Executor 运行真实测试，最后由 Commander 做绝对验收。
- 整个 MoA Step 只消耗一个 Orbit loop；候选和 Judge 的内部调用受独立的候选数和 maxMoaSteps 限制。
- 候选数固定为 2–4；至少需要 2 个成功候选。失败不会偷偷回退成单 Executor，也不会自动换 Judge 模型。
- peerCritique 默认关闭；开启时只允许一轮有界互评。
- 新 Run 会冻结 Candidate/Judge 的 provider、model、reasoningEffort、MoA policy，以及原版 MoA settings 中用户显式配置的价格表（如果存在）。中途修改 UI 只影响下一次 Run。
- Candidate/Judge 的 input/output/cache Token 来自 DSH 子 Session 的真实 assistant/message.usage；如果冻结的价格表能匹配对应 Route，同时记录美元成本；没有价格时只展示 Token，并明确标记无法计算成本，不猜价格。
- Orbit 会把一个不含目标正文、候选正文、Judge 推理或代码的有界运行快照写进所属 DSH Session projection。v0.6.1 的配置首页不再直接展开这些运行详情，而是保持紧凑；运行快照仍保留给会话恢复与后续运行态界面使用。
- 冷恢复按 durable phase 继续：JUDGE 不重跑 Candidate，SELECTED 不重跑 Candidate/Judge，PROMOTED 不重跑 Candidate/Judge/Promotion。
- Orbit ACTIVE 时会在下游 hook 之前阻止独立 /moa，避免原版 MoA 的自动 Promotion 与 Orbit 同时争夺 workspace。
- @goodandready/dsh-moa 是可选依赖；未安装时普通 SINGLE 模式完全不受影响。

当前兼容层接受 @goodandready/dsh-moa >=0.2.19，并已在 0.2.19 与 0.2.20 上完成真实 DSH 烟雾验证。更高版本不再被 Orbit 主动版本上限拦截；若上游未来发生实际 API 不兼容，再按真实故障修正。Orbit 只依赖它公开的项目上下文接口；候选调度、Judge、持久化与 Promotion 权限均由 moa-adapter.ts 封装。

状态机

PLAN → EXECUTE → EVALUATE → SUCCESS
│
├─ correction (bounded per step)
├─ append (bounded by remaining loop budget)
├─ NEEDS_USER
└─ BUDGET_EXHAUSTED

- 只有正常完成的 Executor 步骤才会从预算中消耗一次循环。
- 没有显式用户/工具预算的运行从历史下限 5 次循环开始；在 PLAN 之后，Orbit 会在已接受的基础计划之外确定性地预留两个额外的有界槽位（max(5, steps + 2)，因此对于 1–5 步的计划模式最多为 7）。显式的 approved_loop_count / max_loops 值永远不会被自动扩大。
- 修正按每个基础步骤进行限制，并为剩余的已计划步骤预留预算。
- Commander 决策在代码中验证（步骤评估使用 PASS_CURRENT_STEP / CORRECT_CURRENT_STEP / NEEDS_USER，最终评估使用 SUCCESS / APPEND / NEEDS_USER，策略重新考虑使用 KEEP_APPROACH / REPLACE_CURRENT_STEP / NEEDS_USER）。
- Commander 在自适应超时下运行：360 秒时进行软审查，600 秒时进行第二次审查，840 秒时达到确定性的硬上限；延长始终保留同一个子进程。
- Smart Watchdog 仅在运行时异常时被调用，每个步骤最多执行两次诊断，并且可以恢复同一个子进程，或在中断旧子进程后用新的子进程重启该步骤。
- 被阻止的工具是可恢复的：一次守卫拒绝只会停止该单次调用，而不会停止该轮次或该次运行。

安全边界

- Commander 和 Watchdog 接收只读工具允许列表。
- Executor 始终只接收基础读取工具（read/read_image/glob/grep）。每个 Step 显式声明 filesystem、shell、web 或 browser，以仅添加相应的工具。旧版 web-api-recon 会规范化为 web 加 browser。没有能力意味着没有 bash、写入器、web 或浏览器工具。
- 当 Orbit 拥有某个工作区时，其他顶层自主驱动程序（create_goal、ralph、workflow）会被拒绝，并且当某个活跃的 Goal 驱动程序拥有同一工作区时，Orbit 会拒绝启动。当 Orbit 拥有该工作区时，只有 Orbit 拥有的 Executor 子进程可以使用变更工具。
- 有界且经过脱敏的 step_results 保留每个 Step 的摘要、变更和测试证据。冷恢复会保留它们，并且 FINAL_EVALUATE 会看到每个 Step。
- .cx 持久状态仅由 Orbit 服务写入（原子写入、短锁事务、单调修订）。

配置

| 键 | 默认值 | 含义 |
|---|---|---|
| projectDir | 会话 cwd | 运行所操作的项目。 |
| routes.commander | 无 | 显式配置文件回退；通常由用户在 Orbit 设置中选择。 |
| routes.executor | 无 | 仅在没有 Session 时使用显式配置；否则遵循 DSH Session 选择。 |
| routes.watchdog | 无 | 显式配置文件回退；通常由用户在 Orbit 设置中选择。 |
| moa.enabled | false | 允许 Commander 为关键步骤选择 MOA 执行模式。 |
| moa.candidateCount | 3 | 固定候选数量，运行时只允许 2–4。 |
| moa.candidates | 无 | 用户显式选择的 Candidate routes；不会从 Executor 猜测或继承。 |
| moa.judge | 无 | 用户显式选择的 Judge route。 |
| moa.peerCritique | false | 是否启用一轮有界候选互评。 |
| moa.maxMoaSteps | 2 | 一个 Run 最多允许的 MoA 步骤数（上限受 1–5 步 Plan 约束）。 |
| MoA prices | none | 若 dsh-moa settings 已配置 prices，Orbit 在新 Run 冻结该表并据真实 Token 计算成本；否则不估价。 |
| executorTools | read/read_image/glob/grep | 基础只读子集；变更类工具需要 Step capabilities。 |
| browserTools | ["agent_browser"] | 浏览器能力工具名称。 |
| commanderReadOnlyTools | read/glob/grep/web… | Commander 允许列表。 |
| watchdogTools | read/glob/grep | Watchdog 允许列表。 |
| executorTimeoutMs | 480000 | 确定性执行器运行时超时。 |
| registerTool | true | 注册 orbit_controller 工具及旧版 cx_controller 别名。 |
| registerGuards | true | 注册可恢复的工具防护。 |
| slashCommand | true | 注册 /agent-orbit 宿主命令及手势边界。 |

Routes 是普通的 DSH 模型路由；请根据你自己的提供商和模型标识符进行配置。本包中不包含任何凭据。

可选浏览器能力

Orbit 不依赖 @kasenri/dsh-browser。声明了 capabilities: ["browser"] 的 Plan 步骤需要浏览器插件注册 agent_browser 工具；否则 Orbit 会报告 BROWSER_CAPABILITY_UNAVAILABLE，并让 Commander 决定如何处理。安装两个包即可使用该路径：

dsh plugin --profile web add github:KasenRi/dsh-browser
dsh plugin --profile web add github:KasenRi/dsh-orbit

从 dsh-cx 迁移

| CX | Orbit |
|---|---|
| dsh-cx | dsh-orbit |
| @kasenri/dsh-cx | @kasenri/dsh-orbit |
| cx_controller | orbit_controller |
| CX mode | Orbit mode（orbit模式；cx模式 仍可用） |
| ctx.cx | ctx.orbit（同一个 OrbitService 实例；ctx.cx 仍为别名） |

- .cx/state.json 路径保持不变；v0.6.0 写入 schema 3，旧 schema 2 状态可继续读取，并在下一次正常持久化时升级。
- 旧版 cx模式 仍受支持。
- 现有的持久化运行无需迁移：Orbit 读取同一个
.cx/state.json，包括历史 CX_* 错误字符串。
- 为与现有 CX 项目向后兼容，.cx 保留为持久化执行状态路径。

许可证

MIT