Qulierm/orbital-agents

Orbital Agents

两个协同工作的 DSH 智能体，作为一个配对来规划和执行。Orbital Agents 是项目和仓库标识；发布的包名为 dsh-orbital-agents（前身名称 dsh-endeavour 已被取代，并在 npm 上弃用）。

Endeavour 智能体负责调查、编写计划并验证结果。其持久的 Challenger 对等体是第二个普通聊天，负责执行计划并通过持久协议回报。该配对只创建一次，并在之后每个计划中复用，因此两个智能体始终处于同一轨道，而不是为每个任务重新生成。

- 目标运行时：DeepSeek Harness v0.1.5-rc.2（Cordis 4.0.2），由第三方社区 DSH Desktop v2.0.11 捆绑的系列。这是社区集成；它不是 DeepSeek 的官方产品。
- 全局捆绑包仅提供持久编排服务。四个面向模型的工具由 Endeavour 预设中作用域为 dsh-orbital-agents/tools 的行注册，因此标准预设永远不会看到它们。
- 用户可见的任务状态恰好有四种：waiting、running、succeeded、failed —— 显示为 Waiting to start、Working、Finished、Confirmed 和 Failed 显示阶段。
- 只有 Endeavour 在快速验收检查后记录成功或失败；Challenger 永远不能授权最终成功。

使用它

1. 安装包和用户预设（见下文），然后重启 DSH Desktop，以便加载配置文件捆绑行和预设：
osascript -e 'quit app "DSH Desktop"' 然后 open "/Applications/DSH Desktop.app"。
2. 开始一个 New Chat 并选择 Endeavour 预设。
3. 在编辑器中正常选择规划模型（普通模型选择），并使用统一模型控件——一个仅图标按钮，分别为 Endeavour 和 Challenger 打开 Model/Thinking 行。
4. 用普通语言描述任务并发送。这是唯一需要提供商凭据的步骤。
5. 观察 Endeavour 聊天中的计划卡片：进度、持久任务状态、每个运行任务的实时计时器，以及验证后的冻结时长。Open Challenger 打开执行任务的配对聊天。

两个普通预设一起提供：Endeavour（规划器：endeavour_plan、endeavour_verify）和 Challenger（执行器：challenger_start_task、challenger_report）。计划会一次性交付给与其 Endeavour 会话配对的持久 Challenger 会话；该伙伴永远不是子智能体，并且会被该配对的之后每个计划复用。

配对的 Endeavour 会话会在 Chat 和 Trajectory 旁边显示一个原生 Challenger 视图标签，而 Challenger 会话会显示对应的 Endeavour 标签；任一标签都会打开该配对中的另一个普通会话（见 docs/architecture.md）。

安装

git clone git@github.com:Qulierm/orbital-agents.git
cd orbital-agents
pnpm install --frozen-lockfile
pnpm run build
pnpm packsh
node scripts/install-local.mjs --tarball ./dsh-orbital-agents-0.2.4.tgz

安装程序会先备份桌面配置文件以及任何现有的用户预设，然后将软件包安装到 ~/.dsh/profiles/desktop，保留现有的插件顺序，并将自有的用户预设安装到 ~/.dsh/.agent-presets/endeavour 和 ~/.dsh/.agent-presets/challenger。重新运行它是幂等的；同名/同版本但内容已更改的 tarball 仍会刷新已安装的产物（先移除再添加）。完整生命周期请参见 docs/install.md。

npm 包

同一份源码以 dsh-orbital-agents（MIT）为名发布到公共 npm 注册表，因此可以按版本检查或获取已发布的产物，而无需在本地构建：
sh
npm view dsh-orbital-agents version # 最新发布版本
npm pack dsh-orbital-agents@0.2.4   # 下载确切已发布的 tarball
node scripts/install-local.mjs --tarball ./dsh-orbital-agents-0.2.4.tgz

npm pack 会将已发布的 tarball 写入当前目录，安装程序则在本仓库的克隆中、以该路径运行——也就是 docs/install.md 中记录的同一个安装程序。将该软件包作为普通库依赖安装，并不是将其加载到 DSH Desktop 的受支持方式：该插件由桌面配置文件及其预设挂载，而这正是安装程序所配置的内容。

为什么是两个 agent

想象一次在轨交会：一辆飞行器负责规划并掌管检查清单，另一辆执行点火。两者都不是乘客，也都不是一次性抛弃的级段——只要任务持续，它们就一直对接在一起。

两个持久的普通会话，而不是一个子代理系统。 Endeavour 和 Challenger 是两个配对一次的常规聊天。Challenger 拥有自己的对话、自己的模型选择以及自己的历史记录；它通过与 UI 所使用的相同的普通会话路径来配置，绝不会按计划重新创建，也绝不会作为子代理生成。连接它们的是一个持久协议，而不是父进程：Endeavour 一次性发送整个计划，Challenger 回报证据，Endeavour 再以裁决作答。

工作划分。 Endeavour 负责需求分析、架构、验收标准和验证。Challenger 接收已完成的计划，并执行其中范围明确、按顺序排列的任务，为每一项任务报告摘要、所触及的文件、实际运行的验证，以及——当出现问题时——阻塞或失败。随后 Endeavour 依据自己写下的标准逐项接受或拒绝。只有在这次审查之后，任务才会变为 Confirmed；在此之前它保持 Finished。由于计划约束了执行，Challenger 的工作通常比规划者更窄：遵循决策、运行检查、如实报告。

为什么这可能很经济。 这种形态让你可以在两半上以不同方式投入。把一
在Endeavour上使用昂贵、推理能力强的模型，由它来决定计划、约束条件和验收检查；而在Challenger上使用更快、成本更低的模型，因为那里的工作已经被该计划限定，并且每个任务之后都会被验证。根据你的提供商和定价，与对所有事情都使用最强模型相比，这种分工可以降低长时间运行的成本，而且这两条路线是独立配置的——参见模型选择。人们为这两个角色使用的示例，纯粹是依赖提供商的说明，并不表示本项目支持什么或任何提供商提供什么：

- 高级规划和审查路线，与Opus 5、Fable 5.1、GPT 6 Astra或GPT 5.6 Sol属于同一类；
- 经济型执行路线，与DeepSeek 4.1 Flash或GPT 5.6 Luna属于同一类。

无论你选择什么，都要在你自己的提供商设置中决定：存在哪些模型、它们的成本是多少以及它们的行为如何，都是你的部署的属性，而不是Orbital Agents的属性。节省是这种分工可能带来的结果，而不是保证；质量由Endeavour的验收标准及其对Challenger证据的审查来支撑——而不是由这种配对来承诺。

面板是协议的可视化呈现。 就在输入框正上方（并作为记录中的一张卡片），计划面板实时显示运行情况：有多少任务已确认、当前是哪个任务、工作行上的实时计时器，以及之后的冻结时长。它的各行是持久化的任务状态，而不是装饰——Waiting to start、Working、Finished（已报告，等待审查）、Confirmed（在Endeavour检查后接受）和Failed。行的颜色让各个阶段一目了然：等待时是灰色圆环，工作时是蓝色动画圆环，任务被报告后是绿色对勾，Endeavour接受后是同一对勾变为紫色，失败时是红色叉号。

当Challenger停止时，计划会说明这一点。 如果配对的Challenger会话不再运行，而计划仍期望执行工作——该轮次被停止、出错，或会话消失——计划正在等待的那一行会切换为Challenger stopped，并显示一个静态的橙色圆圈感叹号，在输入框上方的面板和记录卡片上都是如此。它涵盖在第一个任务之前停止、在某个任务进行中停止，以及在顺序任务之间停止的情况，并且一旦Challenger再次运行，它就会自行清除。这故意不是第五种持久任务状态：它是从官方会话列表读取的实时会话活动，因此记录的计划的任何内容、其事件或协议都不会改变。已经开始的任务在等待恢复期间会继续累计其已用时间，而打开Challenger仍然只需一次普通聊天。

重启Desktop

DSH Desktop为该插件提供服务，因此退出它也会终止其中正在运行的任何工具调用。
这使应用内重启变得不对称：手动重启始终是安全的，而由代理驱动的重启必须在报告任何内容之前先安排好。

- 手动： 你自己退出并重新打开 DSH Desktop（osascript -e 'quit app "DSH Desktop"'，然后
open "/Applications/DSH Desktop.app"），或者直接使用应用自带的退出功能。无需其他操作。
- 代理安全调度： 打包的辅助脚本
node "$HOME/.dsh/.agent-presets/challenger/node_modules/dsh-orbital-agents/scripts/schedule-desktop-restart.mjs" --delay-seconds 45 会验证 macOS，将其日志写入
~/.dsh/backups/endeavour/restarts，生成一个分离的 worker 并立即返回，同时给出一个
调度 id 和日志路径。该 worker 会等待、退出应用、等待旧进程离开、
重新打开应用包，并在该日志中记录 ready 或 failed。
- 重启是计划的最后一项任务。执行器会报告 restart scheduled，并附上调度
id 和日志路径，然后停止；没有人会声称应用已恢复，因为能够观察到这一点的
宿主正是被重启的那个。之后请阅读日志以了解真实结果。
- 绝不要让调用跨越重启而保持存活：在退出步骤之后，不要使用 sleep、不要使用 tail、不要使用 ps/lsof 轮询。DSH 会将此类调用记录为已中断且结果未知，报告也会丢失。

--delay-seconds 的下限是 30 秒，因此报告总能在 worker
执行之前有时间送达。

模型选择

编辑器带有一个统一控件：一个仅图标按钮（id endeavour-models），它会打开
一个菜单，其中包含一个 Endeavour 部分和一个 Challenger 部分，每个部分都有自己的 Model 和
Thinking 行。两个角色都从这一个菜单进行配置，并保持独立：

- 每次读取、订阅、目录加载和写入都通过目标会话的官方模型目录进行——
即渲染该控件的 Endeavour 会话及其配对的 Challenger；
- 选择模型会通过该角色的目录进行写入，并仅将该角色的思考强度
重置为模型目录中的默认值；
- 宿主的原生 Endeavour 选择器仅在统一控件渲染时通过 CSS 隐藏，
因此 Standard 和未配对的聊天会保留其普通选择器；
- 当计划处于活动状态时，整个控件会被禁用，这会使所有路由在运行期间保持冻结。

配对会话投影中的临时缺口不会导致控件卸载：在首次看到配对后，准入会被锁定，
并且经过验证的 Challenger 身份会被保留，因此模型目录暂时不可用的角色会显示本地不可用/重试状态，而不是控件消失。请参阅 docs/configuration.md。

生命周期

- 备份位于 ~/.dsh/backups/endeavour//（profile/、preset/、state.json）。
- --list-backups 会列出它们；--rollback  会精确恢复配置文件
和预设状态。
- --uninstall 会移除该插件、其 bundle 行，以及仅属于此包的预设（已有的用户自建预设将保持不变）。
- 冲突处理：已有的非本包所有的预设绝不会被覆盖；传入 --force 可在自动备份后将其替换。
- 安装时会先对真实会话存储执行一次只读的旧版计划预检：仅含 childId 的 NONTERMINAL 计划会在任何变更发生前中止安装（并给出受影响的会话 id 及修复建议）；终态的历史计划则被允许，且保持可读。

完整生命周期参见 docs/install.md，不变量参见 docs/architecture.md。

截图

以下均为使用该插件的 DSH Desktop 运行会话的真实截图——并非离线渲染或模拟图。

实时计划

正在运行的计划卡片：一行“已完成”，一行“进行中”及其计时器，两行“等待中”，下方为输入框

卡片会实时跟踪计划进展：Challenger 已报告的行显示绿色对勾，正在处理的行显示带实时计时器的蓝色动画圆环，尚未开始的行则显示灰色圆环。

统一的模型菜单

模型菜单展开，包含 Endeavour 区和 Challenger 区，每区各有 Model 和 Effort 行

一个控件即可配置这对会话中的两个普通会话：Endeavour 区和 Challenger 区各自拥有独立的 Model 和 Effort。

配对的会话

侧边栏显示同一工作区中的 Endeavour 会话及其配对的 Challenger 会话

这对会话作为两个普通会话存在于工作区侧边栏中，并标注共享的配对代码。

Challenger 视图标签页

会话头部带有 Chat、Trajectory、Context 和 Challenger 标签页

会话头部带有可打开配对 Challenger 的标签页，因此执行者自己的聊天仅一键之遥。

更新这些截图

插件注册表会从本仓库根目录读取 screenshots.json，因此 Market 卡片和安装对话框会在下一次注册表构建时自动获取这些图片——更改它们无需提交拉取请求。若要替换某张图，只需在 screenshots.json 中声明的相同相对路径放入新的 PNG 即可。

scripts/screenshots/ 中有一个离线测试工具，它使用插件自身的组件针对固定数据渲染计划卡片和模型控件；默认输出到 scripts/screenshots/out/，且绝不会改动上述已提交的截图。

许可证

MIT——参见 LICENSE。