GJayun/dsh-goal-zcode-like

dsh-goal-zcode-like

参考 ZCode 目标模式 为 DeepSeek Harness 实现的长程目标管理插件。

仓库：

补上的是 DSH 原生目标循环缺的那一环：每轮结束后独立、证据化的校验。只有校验判定达成才收尾，否则自动进入下一轮——把「盯着 Agent 反复说继续」变成「设一个目标，等结果」。

安装

git clone https://github.com/GJayun/dsh-goal-zcode-like
dsh plugin --profile web add ./dsh-goal-zcode-like

装好后重启 DSH 实例并刷新浏览器。

该命令把参数原样转发给 profile 目录下的 pnpm；声明了 dsh.bundle.patch 的包会自动加入 profile 的 bundle 层栈。相对路径会锚定到执行命令的目录，上面的路径正是依赖这一点。github:GJayun/dsh-goal-zcode-like 同样可用；包发布到 registry 后也可以直接用包名 dsh-goal-zcode-like。

组合行 id 是 goal-zcode-like。台账目录与 HTTP 命名空间沿用不带 scope 的 dsh-goal-zcode-like，与包名无关。

设计立场

ctx.goals 是唯一权威：目标、阶段、revision、轮次数、activation 都由它拥有；轮次续跑由 @deepseek-ai/dsh-goal-round-driver 负责。插件只做增强层——因此内置 /goal、get_goal / create_goal / update_goal 工具、原生 goal 卡片全部照常工作，edit 与 revision 语义未被改动；默认也不注册任何命令，不存在 /goal 三方争抢。

校验轮通过 activation 插入，而不是另起一个循环：

原生轮次被认领  →  ctx.goals.disarm(agent)     driver 因此不会再排下一轮
轮次结束未校验  →  注入  校验轮
模型提交判定    →  resume 重新武装 → driver 开启下一轮
complete / block → 目标结束

disarm / resume 都是 ctx.goals 的公开契约，不涉及任何私有 API。

使用

目标仍由内置 /goal 设定：/goal  开始第 1 轮，/goal 查看状态，/goal pause|resume、/goal clear 行为不变。此后每一轮的收尾由插件接管，模型必须调用 goal_verify 才能闭合本轮，在此之前自动续跑保持暂停。把 command 配成 goalx 之类的名字可额外注册 /goalx status|verify。

| 工具 | 用途 |
|:---|:---|
| goal_plan(items, iteration_title?) | 把工作登记为具体清单项 |
| goal_progress(item_id\|title, status, notes?) | 推进单项状态 |
| goal_verify(achieved, evidence, next_step?, blocked?, blocked_reason?, checklist?, reasoning?) | 闭合本轮，提交判定 |
| goal_status() | 读取轮次台账、分组清单与逐轮证据 |

每轮契约

先用 goal_plan 规划（3-7 个具体、可校验的步骤），开始某项前标记 in_progress、真正做完才标记 completed，随手收集可核对产物，最后用 goal_verify 收尾——这是本轮唯一的闭合方式。

校验只认实据，不认努力：

| 情况 | 错误码 |
|:---|:---|
| achieved 但无实据 | EVIDENCE_REQUIRED（plan / todo / checklist / narration / summary 会被点名拒绝） |
| 仍有清单项未完成时的 achieved | OPEN_ITEMS_REMAIN |
| 未达成但没给 next_step | NEXT_STEP_REQUIRED |
| blocked 但没给 blocked_reason | BLOCKED_REASON_REQUIRED |

任何驳回都不会重新武装循环，因此被拒的判定绝不可能推进目标。

计划、清单项与判定都属于某个已被认领的轮次，因此在轮次之外会被拒绝：goal_plan 与 goal_verify 拒绝 roundsStarted  消息点名正在等待的句柄，并给出三个选择——做不依赖它们的工作、什么都不启动等着被唤醒、或现在就录一个判定立即续跑。只有当等待本身发生变化才会再问一次，且单次推迟最多 maxParallelOffers 次；offerParallelWork: false 恢复静默押后。

两条在飞信号必须都查，因为覆盖的路径不相交：ctx.jobs 管后台命令与后台一次性子代理；可延续子代理不注册 job，只能从 ctx.subagents.listChildren 的 activity 看到。分析见 docs/deferred-rounds.zh.md。

终止会话会中止目标；中止目标不会终止会话。 这个不对称是有意的。dsh-goal-round-driver 只在 activation === "armed" 时暂停被取消的轮次，而轮次被认领时就已 disarmed，该守卫永不成立，因此插件在轮次以 aborted 结束时自行暂停目标，并在静默后才提交持久 pause。反方向上，插件的面板暂停不打断当前回答：先执行的 disarm 不产生持久 goal/changed，driver 的取消分支不会触发；持久 pause() 只等 agent 空闲后才落地，此时 driver 的 agent.status === "running" 守卫不成立。原生卡片自身的暂停仍会取消回答，那是 driver 在 dsh-goal-round-driver:237 的监听器。

用时不含暂停区间。 goal 域只建模 createdAt，因此台账记录每一段暂停并由快照扣除；首次见到时已处于暂停的目标，该段以首次见到的时刻为起点。

工具审批只撤销续跑，不打断。 监听 approval/request（waterfall）且只观察——永远委托 next()，因此绝不会改变审批结果。点「允许」后照常继续；决定悬而未决时结束的轮次不会开启下一轮；一直无人应答则推迟超时 block 目标并点名在等的工具。注意事件目录里没有 approval/asked：订阅它、再用 ctx.on?.() 包住，既不报错也永不触发。

目标卡片

@deepseek-ai/dsh-client-ui-goal 注册 conversation.input.dock 的 id: "goal"，该槽 replaceRisk 为 none。插件用同一个 id、更低的 priority 注册并接管那一格：保留原生功能面（字形、阶段、截断目标、内联编辑、清除、内联失败），并补上按迭代分组的清单与逐轮证据、进度条与用时 / ETA、「等待判定」与「已押后推进」状态、不掐断当前回答的暂停，以及跟随目标语言的中英双语。清单项固定归属首次提出它的那一轮。

两处有意的偏离：等待校验判定时不提供恢复（原生卡片在 active + disarmed 时的恢复会让 driver 跳过校验）；已完成的目标保留可见并带关闭控件，而不是直接消失。

接管靠的是 priority 遮蔽，不是替换。list 槽的重复判断按 (id, priority) 成对比较并抛错，而渲染取每个 cell 中 priority 最低的条目：原生卡片是 0，本插件是 -1。抛错会被 try/catch 吞掉，因此注册失败的表现是「原生卡片照旧还在」——所以客户端半边会把注册失败打到浏览器 console。遮蔽只影响那一格，@deepseek-ai/dsh-client-ui-goal 仍然加载，它注册的 conversation.chat.node 视图照常工作。

配置

- id: goal-zcode-like
name: 'dsh-goal-zcode-like'
config:
command: ''                # 留空 = 不注册命令，与内置 /goal 共存
stallLimit: 3              # 同一 next_step 重复多少次后停止
unverifiedRoundLimit: 2    # 连续多少轮没有判定后停止
autoVerify: true           # 轮次结束是否自动排校验轮
announceProtocol: true     # 目标创建时是否给模型播报一轮契约
deferWhileBusy: true       # 后台任务在飞时押后下一轮，而不是开空轮
offerParallelWork: true    # 把这个判断交给模型，而不是假定它在等
offerOnApproval: true      # 等人审批时是否也发这个机会
maxParallelOffers: 3       # 单次推迟最多发几次
deferralTimeoutMs: 600000  # 推迟超过这个时长仍无结算就暂停目标
storagePath: ''            # 覆盖台账文件位置

offerOnApproval 用来区分「工作」与「人的决定」：悬而未决的审批挡住的正是那个本可去做别的事的回合，因此只有开启时才把它当作可绕开的工作。

架构

lib/overlay.js   按 goal id 的台账：迭代分组、判定、守卫、推迟记录、暂停时间核算、原子持久化
lib/verify.js    纯策略：证据规则、分组投影、卡顿签名、ETA
lib/pending.js   在飞任务探测与并行机会判定
lib/prompt.js    协议、校验轮、并行机会、收尾指令、分组报告（中英）
lib/resolve.js   事件与调用载荷的会话 / Agent 解析
lib/index.js     Cordis 宿主：goals/agents 依赖、disarm/resume 插入、推迟门、工具、HTTP
lib/client.js    Cordis 客户端：接管 conversation.input.dock 的 id "goal" 格子

前五个模块既不依赖 Cordis 也不依赖任何服务，可完整单测。宿主半边只通过 ctx.goals、ctx.agents、ctx.jobs、ctx.subagents、ctx.logger，以及注册的工具与路由接触 harness。

台账落在 $DSH_HOME/storages/dsh-goal-zcode-like/overlay.json（未设 DSH_HOME 时取 ~/.dsh），按 goal id 分键、原子写入；目标本身由 ctx.goals 经 session 日志持久化。

| 方法 | 路径 | 说明 |
|:---|:---|:---|
| GET | /dsh-goal-zcode-like/state?sessionId= | 合并后的快照 |
| GET | /dsh-goal-zcode-like/events?sessionId= | SSE 实时快照流 |
| POST | /dsh-goal-zcode-like/action | {sessionId, action, objective?}，action ∈ start pause resume edit verify clear |

开发

npm test                  # 57 项单元测试（verify、overlay、resolve、pending、client）
node scripts/smoke.mjs    # 21 个端到端场景：桩 ctx.goals/jobs/subagents + 真实 apply(ctx)

冒烟测试用一个记录每次调用的桩 ctx.goals 挂载插件，并按 harness 的方式驱动：认领轮次会 disarm 目标；未校验的轮次会被排校验轮；证据不足或清单未完成会被驳回且不 resume；未达成判定经 resume 重新武装并以 next_step 命名下一轮；达成判定调用 complete 并记录证据；连续未校验调用 block；有在飞任务时押后推进且并行机会只发一次；结算后针对原轮次排校验轮且轮次编号不前进；轮次被终止会暂停目标；悬而未决的审批被原样委托；销毁时所有 disposer 干净执行并刷盘。它不跑真实的 round driver。

边界

- 与真实 round driver 的交互是源码推断，未经运行时观察。 冒烟测试证明的是插件这一侧的契约；disarm 是否真能阻止 driver 排队，依据是 drive() 对 activation !== "armed" 的提前返回，以及 agent/inbox/claimed、agent/pre-step、turn/end 的先后关系。「任务结算后自动唤醒主代理」同理。见 docs/deferred-rounds.zh.md §10。
- 协议不走系统提示。 systemPrompt.section 的 text 回调收到的是不含会话身份的 AssembleContext { scope?, signal? }，因此契约改由目标创建时的一条  消息与每轮的校验提示传递。
- 接管机制已由源码确认，但未在浏览器里观察过。 若看到的仍是原生卡片，说明遮蔽未生效，客户端半边会把注册失败打到 console。接管该格也意味着上游卡片的后续改进不会再到达。
- 客户端观感只做了结构验证。 测试通过 hook 测试台渲染并断言分区、行预算、量出的高度与左右留白，开发环境没有可用浏览器。
- /goal pause 仍会取消当前回答，因为 dsh-command-goal 在服务端直接调用 ctx.goals.pause。修它就得由插件占住 /goal，那会把当初消掉的命令冲突请回来。
- 未实现：审批请求自动暂停、连续工具失败熔断、通知、快捷启动模板、设置卡位、Markdown 报告导出。

许可

MIT