@kasenri/dsh-orbit

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

@kasenri/dsh-orbit

Community plugin for DeepSeek Harness (DSH).

Not affiliated with or endorsed by DeepSeek.

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

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

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

从 v0.6.2 开始，Commander 与 Executor 在同一个 Run 内默认使用 Persistent Role Sessions：PLAN、Step Review、Final Review 会继续同一个 Commander Session；权限集合不变的连续 Step 会继续同一个 Executor Session。这样角色无需在每次交接时重新理解项目。只有权限变化、Watchdog 要求重启、Commander 显式请求 RESET、恢复失败或异常时，Supervisor 才会确定性轮换角色 Session。Watchdog、MoA Candidate 和 Judge 仍保持一次性隔离调用。

从 v0.6.3 开始，Orbit 增加 Trusted Execution Evidence：Supervisor 会从已结算的 DSH tool/call + tool/result 中确定性提取真实工具结果摘要、exit code 和测试证据，并能识别 run_code 内字面 tools.bash({ command: ... }) 的嵌套 shell 命令。Commander 会明确区分 [TRUSTED_TOOL_EVENTS] 和 [EXECUTOR_SUMMARY_UNVERIFIED]，避免已经有真实 stdout / exit code / test summary 时仍重复申请 shell 或要求 Executor 把证据写入临时文件。

从 v0.6.4 开始，Watchdog 变为 Heartbeat Watchdog：保留原有 runtime/timeout/guard/strategy 的即时触发，同时默认每 120 秒主动巡检一次 Commander、Executor 或 MoA 活跃阶段。Heartbeat one-shot 不继承自己的历史，不消耗 loop，不占 runtime Watchdog cap；Supervisor 会记录 meaningful progress 和事件年龄，并用状态指纹丢弃 stale Watchdog 决策。最终关闭也必须经过 FINAL_VERIFY → FINAL_AUDIT → TERMINAL_CONFIRM：只有 Final Watchdog 批准、Commander 真正调用 orbit_run_complete({ signal: "COMPLETE" })，且 Supervisor 的机械关闭条件全部满足，Run 才进入 SUCCESS / CLOSED。

v0.6.5 修复真实 Web Profile Live Apply 发现的 Session 持久化兼容问题：当前 DSH 尚未给第三方插件开放 Session.append() 的 ignorable: true envelope 写入接口，因此未知的 orbit/runtime 自定义事件会让冷读取 reader 拒绝整个 Session。Orbit 现在只在 Harness 原生识别 orbit/runtime 时才写该事件；否则跳过 Session runtime projection，以 .cx 下的 Orbit durable state 作为权威来源，避免污染聊天 Session。

v0.6.6 把 Orbit Run 从“项目唯一”升级为 Session-scoped Runs。每个 DSH Session 都有独立的 .cx/sessions/<session-key>/state.json、Run ID、persistent Commander / Executor 和 NEEDS_USER 状态；一个会话的活动 Run 不再阻止另一个会话在同一项目启动 Orbit。旧 .cx/state.json 会由其 owner_session_id 所属 Session 在下一次写入时自动迁移。多个 Session 共用同一个物理 checkout 时，可写 Executor turn 会按 workspace 串行，保留 mutation safety。

v0.6.7 补齐显式 resume 的 Session 透传：NEEDS_USER 恢复重新进入 run() 时继续使用同一个 owner_session_id，避免工具调用路径依赖隐式 initiator 上下文。

核心能力

• Commander：负责计划、步骤审核、最终审核和策略调整；一个 Run 内默认持续使用同一个 Commander Session。
• Executor：一次只执行当前 Step，并负责真实工具调用与验证；权限集合不变时跨 Step 复用同一个 Executor Session。
• Heartbeat Watchdog：异常时即时介入，并周期主动巡检长执行是否仍在健康推进；Watchdog 本身始终 one-shot。
• Durable State：每个 DSH Session 的 Run 独立持久化到 <project>/.cx/sessions/<session-key>/state.json，支持冷恢复；旧 .cx/state.json 兼容迁移。
• Bounded Loop：Plan、Correction、Watchdog 和 Append 都有明确上限。
• Route Freeze：Run 创建后冻结角色模型与 Reasoning，中途改 UI 只影响下一次 Run。
• Persistent Role Sessions：Commander / Executor 会话身份、轮次、轮换次数和 Token 使用写入 durable state；正常交接不重新创建角色。
• Mutation Fence：多个 Orbit Session 可以共存；同一物理 checkout 的可写 Executor turn 串行，非 Orbit 顶层 mutation driver 仍与活动 Orbit workspace 互斥。
• 可选 MoA：高不确定 Step 可以走 2–4 候选 + Judge 的多方案竞争。
• 可选 Browser：需要真实网页操作时再配合 @kasenri/dsh-browser。

核心状态机：

PLAN → EXECUTE → EVALUATE → CORRECT / RECOVER → FINAL_VERIFY → TERMINAL_CONFIRM → 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/<run>/<step>/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 只负责在困难步骤里多想几个答案再选一个。

Requirements

Component · Tested with

@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

Requires the DSH base services: agents, subagents, tools, sessions

(the standard/web profile provides them).

Install

只使用 Orbit：

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

启用 Orbit + MoA：

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

Git 发行镜像：

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

The package declares a dsh.bundle patch, so dsh plugin add registers it as a

profile layer automatically.

The canonical source is maintained in the

source monorepo.

The source monorepo's versioned Release tarballs remain available for manual or

offline fallback, but the Market uses this dedicated Git repository so updates

can compare the locked commit with HEAD.

Usage

The `orbit_controller

…(truncated)