comet-dsh-plugin 0.0.0-stage → 0.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.en.md +176 -0
- package/README.md +152 -2
- package/client.js +349 -0
- package/cordis.patch.yml +4 -0
- package/icon.png +0 -0
- package/index.js +183 -0
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +58 -4
- package/rules/comet-workflow-guard.md +65 -0
- package/rules/migration-assets.json +218 -0
- package/server/comet-plugin-setup.mjs +192 -0
- package/skills/comet/SKILL.md +37 -0
- package/skills/comet/agents/openai.yaml +3 -0
- package/skills/comet/reference/change-walkthrough.md +77 -0
- package/skills/comet/reference/edit-review.md +26 -0
- package/skills/comet/reference/host-check.md +11 -0
- package/skills/comet/reference/platform-execution.md +34 -0
- package/skills/comet/reference/task-learning.md +39 -0
- package/skills/comet/runtime/classic/checks.yaml +6 -0
- package/skills/comet/runtime/classic/guardrails.yaml +13 -0
- package/skills/comet/runtime/classic/skill.yaml +122 -0
- package/skills/comet/scripts/comet-archive.mjs +310 -0
- package/skills/comet/scripts/comet-check.mjs +179 -0
- package/skills/comet/scripts/comet-entry-runtime.mjs +151 -0
- package/skills/comet/scripts/comet-env.mjs +15 -0
- package/skills/comet/scripts/comet-guard.mjs +335 -0
- package/skills/comet/scripts/comet-handoff.mjs +289 -0
- package/skills/comet/scripts/comet-hook-guard.mjs +295 -0
- package/skills/comet/scripts/comet-hook-router-guard.mjs +629 -0
- package/skills/comet/scripts/comet-hook-router.mjs +17 -0
- package/skills/comet/scripts/comet-intent.mjs +181 -0
- package/skills/comet/scripts/comet-plugin-hook.mjs +213 -0
- package/skills/comet/scripts/comet-resume-probe.mjs +205 -0
- package/skills/comet/scripts/comet-runtime.mjs +572 -0
- package/skills/comet/scripts/comet-state.mjs +381 -0
- package/skills/comet/scripts/comet-yaml-validate.mjs +182 -0
- package/skills/comet-any/SKILL.md +47 -0
- package/skills/comet-any/agents/openai.yaml +5 -0
- package/skills/comet-any/reference/sdk-creation.md +100 -0
- package/skills/comet-archive/SKILL.md +28 -0
- package/skills/comet-archive/agents/openai.yaml +5 -0
- package/skills/comet-archive/reference/compat.md +188 -0
- package/skills/comet-build/SKILL.md +35 -0
- package/skills/comet-build/agents/openai.yaml +5 -0
- package/skills/comet-build/reference/compat.md +191 -0
- package/skills/comet-classic/SKILL.md +98 -0
- package/skills/comet-classic/agents/openai.yaml +3 -0
- package/skills/comet-classic/reference/auto-transition.md +34 -0
- package/skills/comet-classic/reference/classic-layout.md +36 -0
- package/skills/comet-classic/reference/comet-yaml-fields.md +82 -0
- package/skills/comet-classic/reference/context-recovery.md +128 -0
- package/skills/comet-classic/reference/debug-gate.md +30 -0
- package/skills/comet-classic/reference/decision-point.md +109 -0
- package/skills/comet-classic/reference/dirty-worktree.md +59 -0
- package/skills/comet-classic/reference/file-structure.md +32 -0
- package/skills/comet-classic/reference/intent-frame.md +132 -0
- package/skills/comet-classic/reference/scripts.md +144 -0
- package/skills/comet-classic/reference/sdk-methods.md +136 -0
- package/skills/comet-classic/reference/subagent-dispatch.md +75 -0
- package/skills/comet-classic/reference/workspace.md +23 -0
- package/skills/comet-design/SKILL.md +25 -0
- package/skills/comet-design/agents/openai.yaml +5 -0
- package/skills/comet-design/reference/compat.md +191 -0
- package/skills/comet-hotfix/SKILL.md +46 -0
- package/skills/comet-hotfix/agents/openai.yaml +5 -0
- package/skills/comet-hotfix/reference/compat.md +240 -0
- package/skills/comet-memory/SKILL.md +68 -0
- package/skills/comet-memory/agents/openai.yaml +5 -0
- package/skills/comet-native/SKILL.md +139 -0
- package/skills/comet-native/agents/openai.yaml +3 -0
- package/skills/comet-native/reference/artifacts.md +118 -0
- package/skills/comet-native/reference/clarification.md +120 -0
- package/skills/comet-native/reference/commands.md +321 -0
- package/skills/comet-native/reference/edit-review.md +26 -0
- package/skills/comet-native/reference/recovery.md +64 -0
- package/skills/comet-native/reference/workspace.md +70 -0
- package/skills/comet-native/scripts/comet-native-archive.mjs +475 -0
- package/skills/comet-native/scripts/comet-native-cancel.mjs +461 -0
- package/skills/comet-native/scripts/comet-native-doctor.mjs +475 -0
- package/skills/comet-native/scripts/comet-native-hook-guard.mjs +470 -0
- package/skills/comet-native/scripts/comet-native-init.mjs +465 -0
- package/skills/comet-native/scripts/comet-native-new.mjs +478 -0
- package/skills/comet-native/scripts/comet-native-next.mjs +470 -0
- package/skills/comet-native/scripts/comet-native-root.mjs +472 -0
- package/skills/comet-native/scripts/comet-native-runtime.mjs +525 -0
- package/skills/comet-native/scripts/comet-native-select.mjs +468 -0
- package/skills/comet-native/scripts/comet-native-show.mjs +462 -0
- package/skills/comet-native/scripts/comet-native-spec.mjs +468 -0
- package/skills/comet-native/scripts/comet-native-status.mjs +467 -0
- package/skills/comet-native/scripts/comet-native-transfer.mjs +466 -0
- package/skills/comet-open/SKILL.md +265 -0
- package/skills/comet-open/agents/openai.yaml +5 -0
- package/skills/comet-open/reference/batch-changes.md +51 -0
- package/skills/comet-review/SKILL.md +121 -0
- package/skills/comet-review/agents/openai.yaml +5 -0
- package/skills/comet-tweak/SKILL.md +49 -0
- package/skills/comet-tweak/agents/openai.yaml +5 -0
- package/skills/comet-tweak/reference/compat.md +232 -0
- package/skills/comet-verify/SKILL.md +30 -0
- package/skills/comet-verify/agents/openai.yaml +5 -0
- package/skills/comet-verify/reference/compat.md +202 -0
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
# 上下文压缩恢复协议
|
|
2
|
+
|
|
3
|
+
规范路径:`comet-classic/reference/context-recovery.md`
|
|
4
|
+
|
|
5
|
+
## 阶段入口与按需恢复
|
|
6
|
+
|
|
7
|
+
先按 scripts.md 确认公开 CLI 和所选工作区。正常进入下一阶段时,优先按成功结果中的 `agent.continuation` 继续,并使用入口返回的状态信息;信息仍有效时不重复 next、select 或 check。只有这些信息缺失或失效时,才运行一次入口检查:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
comet state check <change-name> <phase> --json
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
普通入口和恢复入口都会返回 layout、configuration、`configurationReadiness`、nextAction、taskState、coordination 和 delivery。`configurationReadiness` 的 `missingFields` 与 `invalidFields` 为空时,表示当前执行配置可沿用;只根据其中列出的字段补问或修复,不逐字段重新查询。taskState 为 `{authority, total, completed, needsIds, next}`;coordination 为 `{path, stale, taskIds, stage, sessionId, reviewRounds, unresolved}`。按 classic-layout.md 确定各逻辑路径对应的目录,根据实际 phase 进入对应阶段。摘要中已有的字段不再逐个查询。状态写入,或工作区、需求发生变化后,重新读取受影响的状态。
|
|
14
|
+
|
|
15
|
+
需要展示或补齐配置时,SDK 与 Compat 均读取[执行配置展示](decision-point.md#执行配置展示),保留同一 change 的有效选择,并使用当前路径的原有保存方式。SDK 已有 Wait 继续复用;不因恢复或重新 Design 重问已确认配置,也不把其他 change 的选择当作本次批准。
|
|
16
|
+
|
|
17
|
+
恢复后先按 [任务上下文协议](scripts.md#任务上下文与产物语言) 执行 `contextRequest`,重新获取当前阶段适用的偏好和项目知识;协调检查点保存任务进度与证据,不替代记忆获取。换 Agent 时使用接收方会话标识;同一 Agent 恢复时沿用原标识并获取 snapshot。
|
|
18
|
+
|
|
19
|
+
SDK 响应先按 auto-transition.md 处理 `continuation.mode` 和 `waitReason`:手动衔接不是运行中任务,`running`/`unknown` 则先核对原执行者。当前 Run 的 `current.actions`、Action 输入和完成模板决定下一步;不从旧阶段名猜测 Skill。下文的任务与协调记录命令对两种 Runtime 都适用,但它们不推进 SDK Run。SDK 的归档和 Git 收尾只按当前 continuation 及 Archive 入口执行,不使用 Compat delivery 命令。
|
|
20
|
+
|
|
21
|
+
以下 `nextAction` 分类只解释 Compat 响应。nextAction 为 `{kind, reason, taskId?}`。先阅读 reason,再根据 kind 完成对应步骤:reconcile-task 表示核对实际成果,review 表示补充审查,checkoff 表示补记任务完成状态,check 表示补充检查,reconcile-plan 表示补齐旧计划与任务的对应关系或同步状态,plan 表示补充有效计划,configure 表示补齐配置,workspace 表示修复工作区归属,delivery 表示完成已授权的交付,continue-phase 表示按当前阶段继续未完成步骤,repair-design 表示修正设计文档关联,design/complete-design 表示补充或完成设计 handoff,transition/verify/archive/confirm-archive 表示按 reason 推进对应阶段动作,paused 表示按 reason 等待恢复条件。nextAction 不允许跳过验收;其中的 taskId 必须对应 tasks.md 中的任务。
|
|
22
|
+
|
|
23
|
+
仅在新会话没有先前上下文、对话被压缩或恢复证据不足时使用:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
comet state check <change-name> <phase> --recover --json
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
先用返回的恢复摘要确定未完成步骤。需要完整任务和检查点时,再加 `--details`;这会在 taskState 中增加 tasks,在 coordination 中增加 checkpoint:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
comet state check <change-name> <phase> --recover --details --json
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
只读取当前步骤还缺少的正文。Agent 判断原检查是否仍适用,并保留原执行来源。Runtime 返回实际可复用结果或需要恢复的原因;只补缺失或受影响检查。真实失败、未知执行和一次性操作按原记录处理,保留计划、任务、审查记录和原进度。
|
|
36
|
+
|
|
37
|
+
## Ambient Resume
|
|
38
|
+
|
|
39
|
+
用户未明确调用 Classic,但仓库可能存在未归档的 change 时,按 scripts.md 将当前请求通过 stdin 传给 `comet resume-probe . --stdin --json`。返回 auto_resume 才自动恢复;返回 ask_user 时按 `reason` 选择下面的问题和选项提问(遵循 `comet-classic/reference/decision-point.md`,优先使用 AskUserQuestion;选项必须是真实可选的动作,不得问没有选项的"是否继续");返回 out_of_scope/none 时不进入流程。
|
|
40
|
+
|
|
41
|
+
| reason | 问题与选项 |
|
|
42
|
+
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
43
|
+
| 多个 active change 需要点名 | 单选:列出全部活跃 change 名称与当前 phase,选择继续哪一个;用户也可以直接说明是哪个 change。 |
|
|
44
|
+
| 未提交改动需要归属 | 单选:归入当前 change;属于另一个 change(请用户说明名称);请用户自己说明归属。没有归属信息前不修改、不提交这些改动。 |
|
|
45
|
+
| active change 停在决策点 | 说明该 change 停在哪个阶段的确认项(按各阶段 skill 的确认清单),选项:恢复该阶段继续处理确认项;用户直接给出决定。 |
|
|
46
|
+
| OpenSpec change 缺少 Comet 状态 | 说明缺失内容,选项:按「入口错误与恢复」为它建立 Comet 状态;用户说明这不是 Comet 需求。 |
|
|
47
|
+
| 请求看似与现有 change 无关 | 单选:恢复现有 change(列出名称与 phase);本次请求是新的工作(请用户确认走新流程)。 |
|
|
48
|
+
|
|
49
|
+
## 入口错误与恢复
|
|
50
|
+
|
|
51
|
+
同一 change 下两种状态文件共存时(包括其中一个是失效符号链接),保留两个文件并停止,核对来源后再处理冲突;不能删除其中一个来强行继续。
|
|
52
|
+
|
|
53
|
+
命令失败、依赖不可用、状态缺失或产物不完整时,保留原错误并按对应原因处理。只有能根据当前输入确认正确的恢复动作才自动执行;恢复成功后,重新运行受影响的入口检查。
|
|
54
|
+
|
|
55
|
+
| 遇到的问题 | 如何恢复,以及何时必须停止 |
|
|
56
|
+
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
57
|
+
| `comet classic openspec -- list --json` 失败 | 核对 OpenSpec 是否已安装,并查看命令的实际错误。产物根目录缺失或损坏时,说明 `comet update --scope project` / `comet init --scope project` 可用于修复;不把命令失败当作“没有未归档的 change”,不擅自升级或重新初始化用户环境。 |
|
|
58
|
+
| 当前阶段要求的 Comet/OpenSpec/Superpowers Skill 不可用 | 停止依赖该 Skill 的动作,说明缺少哪个 Skill,以及需要安装或启用什么。必须使用的 Skill 不能用普通对话代替,也不能擅自更换用户选定的执行方式。 |
|
|
59
|
+
| `comet-state.yaml` 与 `.comet.yaml` 均缺失 | 先确认没有 SDK Run 或归属记录;已有归属时先用 Runtime 恢复投影,不能重新初始化。只有确认未初始化时,再从本次明确选择和可验证产物核对 workflow;full 返回 `/comet-open`,hotfix/tweak 返回对应预设的初始化步骤,完成初始化后再 `comet state select`。workflow 无法确定时请求用户选择,不默认改成 full。 |
|
|
60
|
+
| 实际状态文件格式异常 | 报告解析错误,从版本控制、备份或可验证产物恢复;不能用 `comet state set` 覆盖损坏文件,也不能根据现有文件猜测 phase 后推进。 |
|
|
61
|
+
| change 目录或必需产物不完整 | 按当前 workflow 的 Open 初始化规则,以及产物检查返回的依赖关系补齐文件。保留已有的有效产物;文件完整后仍需请用户最终检查并确认 Open 产物。 |
|
|
62
|
+
| 工作区绑定冲突或路径越界 | 按 workspace.md 核对绑定与实际路径;需要切回绑定分支或 rebind 时展示合法选项并等待明确选择,无法确认归属时停止写入。 |
|
|
63
|
+
| 构建、测试或手动验证失败 | 保留当前 change 与失败证据,按 debug-gate.md 调查。Build 失败时不能通过完成 Guard 进入下一阶段;Verify 失败时按该阶段规则修复并重新验证,不能用以前的通过结果覆盖本次失败。 |
|
|
64
|
+
|
|
65
|
+
## 任务核对与补勾
|
|
66
|
+
|
|
67
|
+
任务完成状态只以 `tasks.md` 为准,计划用于说明实施方法。任务未勾选不能直接作为重新实施的依据,已有勾选也不能替代当前验收证据。
|
|
68
|
+
|
|
69
|
+
1. 根据稳定的 task ID 和计划中的 base-ref,核对当前文件、Git diff/提交、检查结果、审查记录与未解决的反馈。未提交改动先按 dirty-worktree.md 核对来源和归属。
|
|
70
|
+
2. 实现、检查和所需审查均已满足:直接通过 task-complete 补勾,不重复实施。
|
|
71
|
+
3. 实现已完成但证据不足:仅补缺失检查或独立审查;已有部分实现时仅补剩余部分。TDD 历史 RED 缺失要如实记录,不能回退代码伪造证据或自行宣布满足 TDD。
|
|
72
|
+
4. 有效证据与当前输入不匹配时,只重新验证受影响部分;验收通过后再勾选。
|
|
73
|
+
5. 使用 `comet state task-complete <name> <task-id> --json`。由 Agent 对照任务要求核对实际完成结果,文件编辑不自动撤销任务完成记录。
|
|
74
|
+
|
|
75
|
+
旧计划中仍有任务复选框时,先明确每一项对应的 comet-task ID。task-complete 会根据 tasks.md 自动同步这些任务在旧计划中的状态;需要单独更新显示时运行:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
comet state sync-plan <name>
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
返回 `planSync: mapping-required` 时,补齐明确的 ID 对应关系后再运行 sync-plan,不重做实现,也不重新判定已完成任务。计划中的完成状态只是用于显示的副本,不能作为另一套完成依据。没有 ID 的任务,先由 tasks --assign-ids 分配稳定 ID;禁止按序号、位置或相似标题猜测对应关系。旧计划中额外存在的实际任务,先核对范围并纳入 tasks.md;无法确定对应关系时,记录 unresolved 并向用户澄清,不删除条目来通过检查。计划勾选本身不能证明实现完成。
|
|
82
|
+
|
|
83
|
+
## Runtime 协调记录
|
|
84
|
+
|
|
85
|
+
`state checkpoint` 管理的协调记录保存在 `<classic-change-dir>/.comet/coordination.json`,供人阅读的 Markdown 文件为 `.comet/subagent-progress.md`。`.comet/checkpoint.json` 由 Engine 使用,不属于协调记录;不得人工修改或覆盖,也不能将其作为 --file 的输出目标。
|
|
86
|
+
|
|
87
|
+
入口返回的 coordination 摘要已经足够时,不再重复读取。需要完整记录或保存状态时运行:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
comet state checkpoint <change-name>
|
|
91
|
+
comet state checkpoint <change-name> --file <json-path>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
JSON 必须包含 `schemaVersion: 1`,其余字段为 taskIds/stage/sessionId/evidence/unresolved/reviewRounds。以下示例中的任务 ID 和会话标识必须替换为本次实际值:
|
|
95
|
+
|
|
96
|
+
```json
|
|
97
|
+
{
|
|
98
|
+
"schemaVersion": 1,
|
|
99
|
+
"taskIds": ["task-1"],
|
|
100
|
+
"stage": "implementing",
|
|
101
|
+
"sessionId": "<implementer-session-id>",
|
|
102
|
+
"evidence": [],
|
|
103
|
+
"unresolved": [],
|
|
104
|
+
"reviewRounds": 0
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
evidence 保存实际提交、RED/GREEN 结果和审查证据的引用;unresolved 保存未解决事项,不复制完整对话。stage 记录当前处于执行、审查还是补记任务状态的步骤;reviewRounds 记录已经使用的复查次数。Runtime 检查数据后生成 Markdown;不手写 subagent-progress.md,也不把协调记录当作任务完成清单。
|
|
109
|
+
|
|
110
|
+
读取结果为 `{checkpoint, stale}`。stale 为 true 时,先核对任务范围和实际成果,不直接重新执行原步骤;checkpoint 为空也不表示尚未实施。补齐记录后重新读取确认,不能手写内部状态来绕过检查。
|
|
111
|
+
|
|
112
|
+
分配任务前,保存任务范围和协调会话信息;取得子代理会话 ID 后立即保存 sessionId,再继续等待或处理回复。在阶段交接、审查完成、验收或遇到阻塞时,保存新增证据和下一步安排。同一步骤的零碎消息可以合并,不逐条复制对话。保存失败时,停止继续分配任务和推进阶段,保留现有文件供核对。
|
|
113
|
+
|
|
114
|
+
记录缺失或会话失效时,先检查实际成果,重建恢复所需的记录;不能把“无检查点”解释为“无实现”。保留仍有效的审查结果和已用复查次数,不能因为换了会话就重新计算次数。
|
|
115
|
+
|
|
116
|
+
## 各阶段恢复
|
|
117
|
+
|
|
118
|
+
恢复时先取得当前 phase、configuration 和 nextAction,再进入对应阶段 Skill。状态记录与文件不一致时,处理入口报告的具体问题;不根据文件存在就推断阶段已完成,也不手改 phase。
|
|
119
|
+
|
|
120
|
+
- Open:状态文件缺失按上方“入口错误与恢复”核对 workflow 并完成相应初始化;格式损坏先修复来源。产物完整仍需核对 Open 用户确认,不能只凭文件推进。
|
|
121
|
+
- Build 暂停:`build_pause: plan-ready` 表示用户要求计划后暂停。有效计划与配置沿用;只有用户明确要求继续才清除暂停。仅在配置缺失或用户明确要求更改时,回到 Build 的写计划前步骤,一次确认需要补充的配置。不能因为恢复暂停任务就重新询问有效配置。计划缺失时核对文件与状态,修复后仍按用户要求保持暂停。
|
|
122
|
+
- Build 工作区:旧 change 缺 isolation 或目录不匹配时按 workspace.md 恢复 Open 的 workspace resolve/prepare;不在 Build 首次决定或切换工作区。
|
|
123
|
+
- 已记录验证失败:`verify_result: fail` → 自动调用 `/comet-build` 继续修复已记录的失败,不重复写入同一次 verify-fail;达到自动修复上限或需要接受偏差时,由 `/comet-verify` 根据实际失败次数向用户询问下一步。
|
|
124
|
+
|
|
125
|
+
- Build:继续使用有效计划和配置。autonomous 不加载外部执行 Skill;其他策略只在上下文缺少所需方法时加载。委派任务按 subagent-dispatch.md 恢复原先分配的任务范围,以及负责实现的子代理会话;subagent-driven-development 模式下,主会话不接管实现。全部任务完成后,返回 Build 执行退出检查,不恢复旧的 Build final-review/final-fix 步骤。
|
|
126
|
+
- Design:尚未确认的方案继续澄清;已确认的方案只补正式 Design Doc 或未完成的状态写入。按需读取 brainstorm-summary.md 和一份 Markdown 交接文件;供程序使用的 JSON 默认由 Runtime 校验,不重复读取全部上下文。
|
|
127
|
+
- Verify:核对报告、实际 diff 和有效的审查证据,只补充缺失的检查或受影响的审查,不从规模评估重新开始整个阶段。
|
|
128
|
+
- Archive:SDK 只按当前 continuation 和 Archive Skill 核对同一 Run 的交付,不调用 Compat `state delivery`。Compat 的普通入口和 delivery 读取不会访问网络。使用 `comet state delivery <change-name> --verify` 只读核对 Git、远端和 PR 状态,从返回的 `{delivery, verification}` 中确认授权与实际结果。已经归档的不再归档,已经提交的不再提交,远端已完成的操作不再重复 push 或创建 PR。不能根据 handled 推断已获得授权或交付成功;记录缺失或目标变化时,按 Archive 规则确认。
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# 异常调试协议
|
|
2
|
+
|
|
3
|
+
规范路径:`comet-classic/reference/debug-gate.md`
|
|
4
|
+
|
|
5
|
+
本协议由 build、hotfix、tweak 等会直接修改代码的 comet 子 skill 共享。当运行程序、测试、构建或手动验证时出现崩溃、异常行为、测试失败或构建失败,必须进入异常调试协议。
|
|
6
|
+
|
|
7
|
+
## 核心规则
|
|
8
|
+
|
|
9
|
+
例外:已核对失败原因、确实因尚未实现目标行为而失败的 TDD RED 属于正常开发证据,继续 RED-GREEN-REFACTOR,不加载调试技能。环境错误、测试加载失败、无关回归或原因不明的 RED 不属于此例外。
|
|
10
|
+
|
|
11
|
+
- `build_mode: autonomous` 直接按下述步骤调查、修复并验证,不强制加载外部 Skill;其他策略立即使用 Skill 工具加载 Superpowers `systematic-debugging`
|
|
12
|
+
- 在完成根因调查前,不得提出或实施源码修复
|
|
13
|
+
|
|
14
|
+
## 四阶段流程
|
|
15
|
+
|
|
16
|
+
1. 先复现并定位根因,读取完整错误、检查近期变更、追踪数据流
|
|
17
|
+
2. 若根因指向源码 bug,先补充能复现该崩溃/异常的最小失败测试,再修改源码
|
|
18
|
+
3. 修复后运行该失败测试、相关测试和项目构建/验证命令,确认全部通过
|
|
19
|
+
4. 测试、源码修复和 tasks.md 的完成记录都保留在当前 change 内;必须在当前 change 中完成修复和验证,不能另外创建一个“写测试用例”的 change 来代替
|
|
20
|
+
|
|
21
|
+
## 多个检查失败时如何调查和修复
|
|
22
|
+
|
|
23
|
+
同时出现多个失败时,先检查它们是否可能有相同根因、是否共享状态、是否涉及相同文件,再结合调查成本决定串行还是并发。失败数量不决定调度方式。尚不能确认问题彼此独立时,先做必要调查,不直接并发修改。
|
|
24
|
+
|
|
25
|
+
- 相关失败、共享状态或修改范围重叠:集中调查与整合,避免重复定位同一根因。
|
|
26
|
+
- 已确认问题彼此独立,而且并发节省的时间足以抵消任务分配和结果整合的成本:可以并发调查。autonomous 直接分配范围明确的调查任务;其他策略需要并发方法时,加载 Superpowers `dispatching-parallel-agents`。
|
|
27
|
+
|
|
28
|
+
向每个调查子代理说明具体失败、错误证据、允许调查的范围,以及需要返回哪些信息。调查子代理只返回根因和证据,**不直接提交修复**。主会话核对结论和实际依赖后,再安排修复。
|
|
29
|
+
|
|
30
|
+
修复时遵循已选 build_mode、各子代理的文件修改范围,以及 `comet-classic/reference/subagent-dispatch.md`。涉及共享状态或相同修改范围的修复,按顺序实施和整合。autonomous 只有确认任务独立、修改范围互斥且能分别验收时才可并发实施。其他执行方式保持已选方法,不能因为调试就擅自切换策略。根因未明前不得动源码;每项修复仍须在当前 change 中完成测试、审查和验收。
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# 用户决策点协议
|
|
2
|
+
|
|
3
|
+
规范路径:`comet-classic/reference/decision-point.md`
|
|
4
|
+
|
|
5
|
+
本协议由所有包含用户决策点的 comet 子 skill 共享。凡标注为“阻塞点”或“用户决策点”的步骤,都必须按本协议处理。
|
|
6
|
+
|
|
7
|
+
## 先判断是否真的需要用户决策
|
|
8
|
+
|
|
9
|
+
区分用户决策点、自动处理与停止条件:
|
|
10
|
+
|
|
11
|
+
- **用户决策点**:当前事项没有有效批准或委托授权,且选择会影响范围、行为、风险承担或不可逆结果时,请用户决定。用户明确要求逐阶段确认时遵守该要求;授权范围不清时先澄清
|
|
12
|
+
- **自动处理**:当前内容已有明确批准,或用户已明确委托 Agent 在约定范围内决定时,核对授权仍适用后继续。范围内原因明确的修复、根据证据补齐状态、重试幂等检查和按有效配置继续,也不额外要求确认
|
|
13
|
+
- **停止条件**:依赖缺失、状态损坏、路径越界或外部命令不可用,导致当前没有合法下一步;报告阻塞原因和恢复条件,不得伪造选项
|
|
14
|
+
- **手动衔接**:`NEXT: manual` 只是交还控制权,不是新的用户决策点;输出 `HINT` 后结束当前调用,不再询问“是否继续”
|
|
15
|
+
|
|
16
|
+
只有第一类需要等待用户作出决定。Open/Design 因为范围、方案或验收要求尚不明确而提问时,同样按下方格式呈现。需要用户提供事实、路径或其他缺失内容,且无法列出真实选项时,说明缺少什么并请求补充,不编造答案。
|
|
17
|
+
|
|
18
|
+
相关且可以同时回答的问题必须放在一起提出;已保存且仍有效的选择不得重复询问。不要仅为了预测后续工具或操作是否失败,就额外预检并排除选项。展示本工作流支持的全部选择;用户选择后执行相应动作,若失败则停止并报告原错误。若某配置字段只有一个符合工作流要求的值,说明原因后直接采用,不为它单独暂停;用户明确要求的逐阶段确认仍须遵守。
|
|
19
|
+
|
|
20
|
+
## 核心规则
|
|
21
|
+
|
|
22
|
+
暂停或停止只影响依赖该决定、或被当前问题阻塞的动作。同一已授权范围内,其他不依赖该决定的调查、证据整理和已允许工作可以继续。不得因此绕过阶段 Guard、提前实施尚未确认的范围,或替用户作出决定。
|
|
23
|
+
|
|
24
|
+
- 需要用户作出新决定时,暂停依赖该决定的动作,等待明确答复后继续
|
|
25
|
+
- 需要提问时,存在 `AskUserQuestion` 就使用它展示单选/多选选项;否则在对话中提出明确选项并结束当前回复,等待实际答复后再执行依赖该决定的命令。没有结构化提问工具不代表用户已经授权
|
|
26
|
+
- 若无法使用 `AskUserQuestion`,就记录本会话无法使用结构化提问;本会话后续决策点不得反复重试它,直接改用文本选项
|
|
27
|
+
- 不得用推荐规则、默认值、历史偏好或“用户应该会同意”的推断代替当前确认
|
|
28
|
+
- 用户明确选择前,不得写入对应状态字段、执行对应分支操作或自动继续下一阶段
|
|
29
|
+
|
|
30
|
+
授权可以来自当前请求或已有记录,不要求发生在产物生成之后。核对授权的对象、范围和条件与当前内容是否一致;仍然适用就复用,发生实质变化时只确认超出授权的部分。记录决定的真实依据,不把 Agent 自行选择写成“用户已确认”。
|
|
31
|
+
|
|
32
|
+
## 执行配置展示
|
|
33
|
+
|
|
34
|
+
SDK 与 Compat 需要展示、补齐或更改 Build 配置时,均按本节呈现,再使用当前 Runtime 路径的原有命令保存。根据当前 `configuration`、`configurationReadiness` 和已有用户决定,逐项列出当前值、自然语言含义,以及「已确认」「待补充」「需修正」或「用户要求更改」的状态;缺少值时如实说明,不把建议值写成已确认。`configurationReadiness` 只说明字段是否有效,不能代替本 change 的批准。只询问缺失、无效或用户要求更改的字段,在同一轮收集实际需要的选择。
|
|
35
|
+
|
|
36
|
+
每个新 full change 都确认本 change 的配置;项目默认值、推荐或其他 change 的选择不构成批准。同一 change 恢复或重新 Design 后,沿用仍有效的已确认选择;配置提案改变后按当前路径原有机制重新确认,不沿用过期批准。用户明确选择完整配置后,保存并简短回显,然后继续,不追加没有新决定的继续确认;缺少决定时继续等待。hotfix/tweak 只说明当前已选预设的值和含义,保留既有确认步骤,不增加独立 Build 配置批准。
|
|
37
|
+
|
|
38
|
+
执行方式、TDD 和审查深度分别说明。`tdd_mode: direct` 不要求 RED/GREEN,仍做相关检查与缺陷回归;`direct_override` 只对应 full 的 `build_mode: direct`,不因 `tdd_mode: direct` 自动启用。向用户解释派发与直接实施的实际影响,不把关联标志另列为需要猜测的布尔选项。各路径原有的 full direct 明确选择、autonomous 独立审查和子代理派发约束保持不变,非法组合仍按 Runtime 校验修正。
|
|
39
|
+
|
|
40
|
+
## 需求变化后的重新确认
|
|
41
|
+
|
|
42
|
+
SDK 与 Compat 在需求或验收变化后需要重新确认时,均先按本节说明,再沿当前路径的 Spec Patch、Design 或预设范围复核步骤处理。先区分已确认目标的实现遗漏、正式需求或验收变化、与当前 change 无关的请求。实现遗漏在原范围内修复;无关请求另行归属,不混入当前 change。
|
|
43
|
+
|
|
44
|
+
重新确认时,先说明相对上次批准方案的新增、删除和改变的行为、受影响验收、可保留成果与需要重做的步骤,再展示完整当前方案。比较只依据可读取的已批准提案、正式文件和用户明确决定;缺少可信旧方案时,说明无法可靠比较,只列能确定的变化,不编造差异或声称“其余不变”。初次确认无需制造前后差异。
|
|
45
|
+
|
|
46
|
+
变化摘要只帮助用户阅读,批准仍绑定完整当前提案及当前路径原有的批准身份。Design 中 Spec Patch 的事先授权、正式设计确认及预设范围复核均保留;现有 Build 配置按上节复用。重做范围依据 Runtime 当前动作和证据有效性说明,不承诺复用已失效的检查,不把旧验收结论用于新需求。失败、中断或未知结果如实保留,恢复不能跳过仍待用户决定的步骤。
|
|
47
|
+
|
|
48
|
+
## Classic 预设的文件数授权复用
|
|
49
|
+
|
|
50
|
+
hotfix 和 tweak 的文件数阈值只触发范围复核,不是实质升级信号。预设可以复用 `<classic-change-dir>/.comet/rulings.md` 中的 `Preset file-count authorization`,但只有 active、workflow 与当前 change 匹配,scope、验收和风险假设未变,且当前唯一触发条件是文件数超限时,才把它视为有效授权。记录必须包含 `status: active|invalidated`、`workflow`、`decision: continue-on-file-count-only`、授权范围、`allowed-file-categories`、`authorization-basis` 和 `reason`。
|
|
51
|
+
|
|
52
|
+
命中有效授权时,不重新提问,但先报告交付文件总数和分类、它们与确认范围的对应关系、ruling 记录,以及没有命中实质升级信号的依据。恢复任务也必须先读取同一 ruling,再按当前 scope 和 workflow 重新核对。交付文件只统计源码、测试、用户文档、配置和生成物,覆盖基线后提交、暂存、未暂存及未跟踪文件并去重;排除 change 目录中的 OpenSpec 产物、`.comet` 元数据和无关脏文件。有效授权只绕过“文件数超限且没有实质升级信号”的提问,不能绕过新增模块、公共 API、schema、capability、跨模块或架构风险的复核。
|
|
53
|
+
|
|
54
|
+
普通开始修复、Skill 调用、历史偏好或 Personal Memory 不能建立授权。用户撤销、切换 workflow、范围或验收变化、出现新实质升级信号,或文件落到授权类别之外时,将 ruling 标为 `invalidated`;rulings.md 缺失、不可读、含糊或已失效时,无有效授权,必须按现有暂停流程提问。升级到 full 时也将 ruling 标为 `invalidated`,之后不得继续复用该授权。
|
|
55
|
+
|
|
56
|
+
## `AskUserQuestion` 优先策略
|
|
57
|
+
|
|
58
|
+
使用结构化提问时:
|
|
59
|
+
|
|
60
|
+
- 单选决策点用 `AskUserQuestion` 的单选问题;多选决策点用多选问题
|
|
61
|
+
- 每个问题都要说明正在决定什么;每个选项都要有简短名称和影响说明。有依据时标出推荐项并说明理由,但不能替用户选择
|
|
62
|
+
- 若工具调用成功,等待用户通过该问题作答;不得同时再输出一套文本选项
|
|
63
|
+
- 若工具不存在或调用失败,记录“本会话结构化提问不可用”,然后改用文本选项
|
|
64
|
+
|
|
65
|
+
## 每个问题必须包含的信息
|
|
66
|
+
|
|
67
|
+
- **问题**:说明本题要决定什么,并提供作出判断所需的事实、约束,或待确认产物的引用;不能只列工具名或配置字段
|
|
68
|
+
- **推荐与理由**:有依据时给出推荐选项,说明它为什么适合当前需求、风险与已有配置;依据不足时明确说明暂不推荐,不以历史偏好代替确认
|
|
69
|
+
- **选项与影响**:给出清晰可选项,逐项说明选择后执行什么、改变什么范围/行为、承担什么代价或风险;需要用户单选时,选项必须互斥且可执行
|
|
70
|
+
- 改用文本提问时,必须标明“单选”或“多选”,列出选项编号和各项影响,并要求用户回复编号;随后暂停依赖该回答的步骤,等待回复
|
|
71
|
+
- 一次提出多个问题时,每个问题分别满足问题、推荐理由与各选项影响要求;不能只为整组问题写一条笼统推荐
|
|
72
|
+
- 推荐只能供用户参考,不能替代确认。工具返回空答案、用户未回复,或答复没有明确选择时,待定决定保持未确认
|
|
73
|
+
- 用户选择后,再执行对应命令或状态更新
|
|
74
|
+
|
|
75
|
+
### 批量文本提问格式
|
|
76
|
+
|
|
77
|
+
一次用文本提出多个问题时,保留 `Q1`、`Q2` 编号;每题分别写加粗标题、说明、选项和推荐回答。用 💬 标记问题、💡 标记推荐回答,题目之间用分隔线区分。每题按以下格式书写,并在同一条消息中完整发出:
|
|
78
|
+
|
|
79
|
+
```markdown
|
|
80
|
+
💬 **Q1|<问题标题>(单选)**
|
|
81
|
+
|
|
82
|
+
<说明背景,以及选择会改变什么;复杂问题可以分段。>
|
|
83
|
+
|
|
84
|
+
| 选项 | 方案 | 实际影响 |
|
|
85
|
+
| ---- | ------------ | -------------------------- |
|
|
86
|
+
| A | <方案短名称> | <选择后改变什么及相关代价> |
|
|
87
|
+
| B | <方案短名称> | <选择后改变什么及相关代价> |
|
|
88
|
+
|
|
89
|
+
💡 **推荐回答:A(<方案短名称>)**
|
|
90
|
+
|
|
91
|
+
推荐理由:<为什么适合当前需求与约束。>
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
题号保持稳定,追问沿用原题号;多选题标为“多选”。开放题标为“开放回答”,省略选项表,有可靠建议时给出“推荐回答”和理由;事实不足时明确写出“需要你补充”,只提供回答所需的背景或格式,不编造推荐内容。已有固定选项表时,保留原编号和完整影响说明,放在对应题目下,不为突出推荐而重新编号或删减选项。
|
|
97
|
+
|
|
98
|
+
全部问题之后统一说明答复方式,例如 `Q1:A;Q2:A+C;Q3:补充内容`,也允许用户按题号给出自己的答案;示例不代表默认选择。结构化工具可用时仍优先使用工具,把相同信息填入标题、说明和选项字段;不要求工具显示 Markdown 表格,调用成功后不再重复发送文本问题。
|
|
99
|
+
|
|
100
|
+
## 各阶段需要确认什么
|
|
101
|
+
|
|
102
|
+
当前阶段确实需要以下决定时,才读取对应阶段的详细规则;已保存且仍有效的授权或配置不重新确认。
|
|
103
|
+
|
|
104
|
+
- 入口/Open:目标 change 不明、是否拆分 PRD、如何隔离工作区仍需要选择时,把相关问题一起提出。Open 结束时一次确认名称、范围与产物;请求已经清晰时,不先单独要求批准摘要或命名。
|
|
105
|
+
- Design:brainstorming 形成可供检查的方案后,请用户确认正式设计。已有有效确认时,只补充尚未完成的产物和状态。
|
|
106
|
+
- Build:写计划前,仅在执行/TDD/review 配置缺失或用户要求更改时,一次确认相关配置;计划完成后默认继续。plan-ready 表示用户主动要求暂停,收到继续指令后沿用有效计划与配置,不重新发起配置决策。
|
|
107
|
+
- Verify:范围内原因明确且可以修复的失败,自动修复并重新验证。需要接受 WARNING/SUGGESTION 偏差、决定如何处理实现与 Spec 的不一致,或达到 Runtime 自动修复上限时,才询问用户。CRITICAL/IMPORTANT 问题必须解决。
|
|
108
|
+
- Archive:一次确认归档与 local/push/pr 交付方式。已有有效 delivery 授权且目标未变时,只完成剩余操作;实际结果不确定时,先只读核对。
|
|
109
|
+
- 范围改变:新增能力、公开行为或接口发生变化、验收要求或风险承担方式改变,以及出现预设规定的升级条件时,由对应阶段展示继续、调整或拆分等合法选择。任务拆细或数量增加本身,不代表范围扩大。
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Dirty Worktree 协议
|
|
2
|
+
|
|
3
|
+
规范路径:`comet-classic/reference/dirty-worktree.md`
|
|
4
|
+
|
|
5
|
+
所有涉及代码修改的 Comet 子 Skill 都遵循本协议。Agent 恢复上下文或继续执行时,必须按本协议处理工作区内尚未提交的改动。各阶段可以补充自己的处理规则,例如 Verify 对实现改动的特殊要求;具体以对应子 Skill 为准,本文件不重复这些规则。
|
|
6
|
+
|
|
7
|
+
## 1. 检查步骤
|
|
8
|
+
|
|
9
|
+
继续或开始修改前,必须先运行以下命令:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
git status --short
|
|
13
|
+
git diff --stat
|
|
14
|
+
git diff --cached --stat
|
|
15
|
+
git ls-files --others --exclude-standard
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
必要时再查看 `git diff` / `git diff --cached` / 新建文件内容。
|
|
19
|
+
|
|
20
|
+
## 2. 核心规则
|
|
21
|
+
|
|
22
|
+
- 用户可能不会说明自己改了哪里。只要工作区存在未提交改动(dirty worktree,包括 Git 状态中显示为 `??` 的新建文件),就先考虑这些改动可能来自用户,也可能由多方共同产生
|
|
23
|
+
- **排除构建产物**:`??` 文件若匹配 `.gitignore` 中的模式(如 `node_modules/`、`dist/`、`__pycache__/`、`*.o`、`target/`、`build/` 等),自动跳过来源核对,不视为用户改动
|
|
24
|
+
- 工作区中存在代码改动,不代表可以更新 `.comet.yaml` 的 `phase` 或勾选 `tasks.md`。必须先核对来源和归属、完成验证、同步必要文档,并通过对应阶段 guard,才能推进 Comet 状态
|
|
25
|
+
|
|
26
|
+
## 3. 判断改动属于哪项工作
|
|
27
|
+
|
|
28
|
+
将未提交的改动分为三类:
|
|
29
|
+
|
|
30
|
+
1. **属于当前 change**:文件和内容能对应当前 change 的目标、tasks.md、plan 或 delta spec。将其纳入当前任务继续,不重复改同一处
|
|
31
|
+
2. **不属于当前 change**:文件或内容与当前目标无关。暂停并询问用户:并入当前 change、拆成新 change、保留不处理,或明确授权丢弃
|
|
32
|
+
3. **来源不确定**:无法从 diff 和文档判断归属。暂停并向用户汇报文件列表和判断依据,不继续推进阶段
|
|
33
|
+
|
|
34
|
+
## 4. 常见处理模式
|
|
35
|
+
|
|
36
|
+
### 已实现但 tasks.md 未勾选
|
|
37
|
+
|
|
38
|
+
先验证实现(运行构建和测试),通过后补记任务完成状态。不要因为任务未勾选就重做一遍,也不要因为状态文件尚未更新就忽略已有实现。若当前子 Skill 有该阶段的特殊要求,以子 Skill 为准。
|
|
39
|
+
|
|
40
|
+
### 发现计划或范围变化时
|
|
41
|
+
|
|
42
|
+
按当前子 skill 的升级、增量更新或回退规则处理,本协议不重复阶段特例。
|
|
43
|
+
|
|
44
|
+
### 用户没有说明具体改动时
|
|
45
|
+
|
|
46
|
+
用户说“继续”“接着跑”“我改了一点”“刚才不满意”“重新弄”“代码动过”“先按现在的来”等话,但没有说明具体改动时,按本协议处理。不要要求用户先回忆自己改了哪里。
|
|
47
|
+
|
|
48
|
+
### open/design 阶段出现代码改动
|
|
49
|
+
|
|
50
|
+
若当前仍处于 `open` 或 `design`,但工作区已经有代码改动,先按本协议核对来源和归属,不要直接推进阶段:
|
|
51
|
+
|
|
52
|
+
- 属于当前 change 的改动:作为需求或设计输入记录到 proposal/design/spec/design doc/tasks 中;进入 build 前仍需完成对应阶段 guard
|
|
53
|
+
- 不属于当前 change 或来源不确定:暂停询问用户是并入当前 change、拆成新 change、保留不处理,还是明确授权丢弃
|
|
54
|
+
- 禁止在 open/design 阶段直接把代码改动当作已完成实现并推进到 verify
|
|
55
|
+
|
|
56
|
+
## 5. 禁令
|
|
57
|
+
|
|
58
|
+
- 未查清未提交改动的来源时,不得覆盖、回滚、通过格式化重写或忽略用户改动
|
|
59
|
+
- 未说明清楚这些改动的来源和归属时,不得判定验证通过
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# 文件结构参考
|
|
2
|
+
|
|
3
|
+
规范路径:`comet-classic/reference/file-structure.md`
|
|
4
|
+
|
|
5
|
+
本文件是 Comet 项目文件结构参考。按需查阅,不随 skill 一次性加载。
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
<classic-open-spec-root>/ # OpenSpec 需求与规格目录;由 Classic 路径解析结果提供
|
|
9
|
+
├── config.yaml
|
|
10
|
+
├── changes/
|
|
11
|
+
│ ├── <name>/ # 活跃 change
|
|
12
|
+
│ │ ├── .openspec.yaml
|
|
13
|
+
│ │ ├── comet-state.yaml
|
|
14
|
+
│ │ ├── proposal.md # 变更原因、目标与范围
|
|
15
|
+
│ │ ├── design.md # 高层架构决策
|
|
16
|
+
│ │ ├── specs/<capability>/spec.md # 本次变更对能力规格的增量修改(delta spec)
|
|
17
|
+
│ │ ├── .comet/handoff/ # 脚本生成的阶段交接包
|
|
18
|
+
│ │ └── tasks.md # 任务清单
|
|
19
|
+
│ └── archive/YYYY-MM-DD-<name>/ # 已归档
|
|
20
|
+
└── specs/<capability>/spec.md # 主规格(归档时按 OpenSpec 规则合并 delta spec)
|
|
21
|
+
|
|
22
|
+
<classic-superpowers-root>/ # Superpowers 设计与计划目录;由 Classic 路径解析结果提供
|
|
23
|
+
├── specs/YYYY-MM-DD-<topic>-design.md # 设计文档(技术 RFC,归档时标注状态)
|
|
24
|
+
└── plans/YYYY-MM-DD-<feature>.md # 实施计划(文件头含 change 关联元数据)
|
|
25
|
+
|
|
26
|
+
.comet/
|
|
27
|
+
└── config.yaml # Comet 项目配置(context_compression 默认 off,可设 beta)
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Classic SDK 新 change 使用 `comet-state.yaml`;历史 `.comet.yaml` 原地兼容,compat 初始化继续使用旧名。两种文件不能同时存在,包括其中一个是失效符号链接的情况。
|
|
31
|
+
|
|
32
|
+
本机 Run、执行证据、锁和事务保存在用户 Comet 数据目录,按 checkout 和 Git worktree 隔离;默认数据根为 `~/.comet`,可用 `COMET_DATA_DIR` 指定工作区外的绝对路径。上面的项目目录保留配置和用户可读产物,不是本机 Run 存储位置。以 Runtime 返回的路径为准,不手工编辑或复制本机执行文件。
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# CometIntentFrame 字段参考
|
|
2
|
+
|
|
3
|
+
启动新需求、目标 change 未明确,或需要了解路由字段时,读取本文件。已绑定 change 的正常阶段衔接直接按 Runtime 返回的 continuation 继续,不重新填写意图数据。
|
|
4
|
+
|
|
5
|
+
先运行 `comet classic openspec -- list --json` 获取未归档的 change 列表,再根据用户原话、列表和必要的仓库信息,填写下方示例中的字段。运行 `comet classic intent route --stdin` 后,由 Runtime 补齐省略字段,并计算最终 `route`。
|
|
6
|
+
|
|
7
|
+
**CometIntentFrame 最小示例**:
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"schema_version": "comet.intent.v1",
|
|
12
|
+
"utterance": "<用户原话>",
|
|
13
|
+
"intent": { "name": "start_change", "confidence": 0.8 },
|
|
14
|
+
"slots": {
|
|
15
|
+
"requested_action": "start",
|
|
16
|
+
"workflow_candidate": "full",
|
|
17
|
+
"user_explicit_workflow": null,
|
|
18
|
+
"change_id": null,
|
|
19
|
+
"existing_behavior": null,
|
|
20
|
+
"new_capability": null,
|
|
21
|
+
"public_api_change": null,
|
|
22
|
+
"schema_change": null,
|
|
23
|
+
"cross_module_change": null
|
|
24
|
+
},
|
|
25
|
+
"context": {
|
|
26
|
+
"active_changes_count": 0,
|
|
27
|
+
"active_change_names": []
|
|
28
|
+
},
|
|
29
|
+
"evidence": [],
|
|
30
|
+
"proposed_route": {
|
|
31
|
+
"name": "ask_user",
|
|
32
|
+
"confidence": 0.5
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**从用户请求中提取意图字段**:
|
|
38
|
+
通常按上方最小示例填写即可;字段含义见下文。以下规则用于提取信息,最终路由仍由 Runtime 计算。
|
|
39
|
+
|
|
40
|
+
- `fix_bug` 且 `existing_behavior: true`,没有新增能力、公共 API、schema 或跨模块变更 → 倾向 `hotfix`
|
|
41
|
+
- 用户明确说明这是一个可以在单一 OpenSpec change 内完成的轻量或中等变更,需要通过 OpenSpec apply 执行,但不需要完整 `/comet-classic` 的深度设计和实施计划 → 倾向 `tweak`
|
|
42
|
+
- 文案、配置、文档、提示词,或单一 OpenSpec change 内的轻量至中等修改 → 倾向 `tweak`
|
|
43
|
+
- 新增能力、公共 API 或 schema 变更、跨模块协调、架构调整 → 倾向 `full`
|
|
44
|
+
- 有多个未归档的 change,用户没有指定目标 → `ask_user`
|
|
45
|
+
- 置信度不足、缺少关键证据,或用户指定的 workflow 与实际风险不匹配 → `ask_user`
|
|
46
|
+
|
|
47
|
+
## 目标选择与路由
|
|
48
|
+
|
|
49
|
+
- `hotfix` / `tweak`:用户已明确选择,而且风险符合预设要求时,加载对应 Skill;由 Agent 推荐时,先按 decision-point.md 请用户确认,并保留 full 选项。
|
|
50
|
+
- `full`:按下表确定新建还是恢复;新建必须通过 `/comet-open` 同时创建 OpenSpec 产物与 `.comet.yaml` 状态文件。
|
|
51
|
+
- `resume`:目标明确后,返回入口绑定工作区;按 context-recovery.md 查询实际 phase 并恢复。
|
|
52
|
+
- `ask_user`:按 decision-point.md 等待目标或范围选择。
|
|
53
|
+
- `out_of_scope`:说明本次请求不涉及启动或恢复工作流,不初始化 change。
|
|
54
|
+
|
|
55
|
+
| 活跃 change | 用户输入 | 行为 |
|
|
56
|
+
| ----------- | -------------------------- | ----------------------------------------------------------------------- |
|
|
57
|
+
| 无 | `full` 路由 | → 调用 `/comet-open` |
|
|
58
|
+
| 恰好 1 个 | `/comet-classic <描述>` | → **询问**:继续该变更,还是创建新变更 |
|
|
59
|
+
| 多个 | `/comet-classic <描述>` | → **询问**:继续现有变更,还是创建新变更;若选继续 → 列出清单让用户选择 |
|
|
60
|
+
| 恰好 1 个 | `/comet-classic`(无描述) | → 自动选中,返回入口绑定工作区并读取状态 |
|
|
61
|
+
| 多个 | `/comet-classic`(无描述) | → 列出清单让用户选择 |
|
|
62
|
+
|
|
63
|
+
## 顶层字段
|
|
64
|
+
|
|
65
|
+
| 字段 | 含义 |
|
|
66
|
+
| ---------------- | --------------------------------------------------------------------------------------------- |
|
|
67
|
+
| `schema_version` | 意图数据的版本,当前固定为 `comet.intent.v1`。 |
|
|
68
|
+
| `utterance` | 触发 `/comet-classic` 的用户原话。 |
|
|
69
|
+
| `intent` | 用户希望执行的动作及判断置信度。置信度低于 Runtime 阈值时,路由到 `ask_user`。 |
|
|
70
|
+
| `slots` | 从用户原话中提取并按统一格式填写的路由信息。 |
|
|
71
|
+
| `context` | 从仓库状态读取的上下文,不是用户原话抽取结果。 |
|
|
72
|
+
| `evidence` | 支撑关键判断的证据。缺少关键证据时,Runtime 会倾向 `ask_user`。 |
|
|
73
|
+
| `proposed_route` | Agent 提交的候选路由。最小输入只需 `name` 和 `confidence`,Runtime 会复核并输出最终 `route`。 |
|
|
74
|
+
|
|
75
|
+
## `intent`
|
|
76
|
+
|
|
77
|
+
| 字段 | 含义 |
|
|
78
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
79
|
+
| `intent.name` | 用户希望执行的动作:启动、恢复、修复缺陷、小幅修改、提问或未知。 |
|
|
80
|
+
| `intent.confidence` | Agent 对高层意图判断的置信度。置信度不足时,Runtime 会据此转为询问用户;`proposed_route.confidence` 不参与。 |
|
|
81
|
+
|
|
82
|
+
## `slots`
|
|
83
|
+
|
|
84
|
+
| 字段 | 含义 |
|
|
85
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
86
|
+
| `requested_action` | 用户想执行的动作,例如 `start`、`resume`、`continue`、`fix`、`modify`、`create`、`verify`、`archive`、`question`。 |
|
|
87
|
+
| `workflow_candidate` | Agent 推断的候选流程:`full`、`hotfix`、`tweak` 或 `null`。这是推断值,Runtime 会复核。 |
|
|
88
|
+
| `user_explicit_workflow` | 用户是否明确指定流程。用户说“走 hotfix”时填 `hotfix`;没明确说时填 `null`。用户指定的流程与实际风险不匹配时,仍会 `ask_user`。 |
|
|
89
|
+
| `change_id` | 用户指定要恢复或操作的未归档 change 名称。没有指定时填 `null`。 |
|
|
90
|
+
| `existing_behavior` | 是否在修复已有行为或回归。`true` 且没有新增能力/API/schema/跨模块风险时倾向 `hotfix`。 |
|
|
91
|
+
| `new_capability` | 是否新增能力。存在这类变更时通常倾向 `full`。 |
|
|
92
|
+
| `public_api_change` | 是否改变用户可见接口或约定的行为,例如 CLI 参数、配置字段、输出 JSON、Skill 对外流程。存在这类变更时通常倾向 `full`。 |
|
|
93
|
+
| `schema_change` | 是否改变结构化数据格式,例如 `.comet.yaml`、`run-state.json`、eval manifest、bundle manifest、配置 schema。存在这类变更时通常倾向 `full`。 |
|
|
94
|
+
| `cross_module_change` | 是否需要跨模块协作,或涉及多个 workflow。存在这类变更时通常倾向 `full`。 |
|
|
95
|
+
| `target_area` | 可选解释字段,表示用户提到的目标区域。最小示例不需要填写。 |
|
|
96
|
+
| `scope` | 可选解释字段,表示粗略范围大小。Runtime 不会只凭这个字段决定路由,最小示例不需要填写。 |
|
|
97
|
+
|
|
98
|
+
## `context`
|
|
99
|
+
|
|
100
|
+
| 字段 | 含义 |
|
|
101
|
+
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
102
|
+
| `active_changes_count` | `comet classic openspec -- list --json` 得到的未归档的 change 数量。存在多个未归档的 change,且用户未指定 `change_id` 时会 `ask_user`。 |
|
|
103
|
+
| `active_change_names` | 未归档 change 的名称列表。用户指定 `change_id` 时,Runtime 用它检查 change 是否存在。 |
|
|
104
|
+
| `dirty_worktree` | 可选状态字段。入口路由的最小示例不需要填写;未提交改动的处理方式由 `comet-classic/reference/dirty-worktree.md` 专门处理。 |
|
|
105
|
+
|
|
106
|
+
## `evidence`
|
|
107
|
+
|
|
108
|
+
每条 evidence 证据记录包含:
|
|
109
|
+
|
|
110
|
+
| 字段 | 含义 |
|
|
111
|
+
| -------- | ------------------------------------------------------------------------ |
|
|
112
|
+
| `field` | 该证据对应的意图字段,例如 `intent.name` 或 `slots.workflow_candidate`。 |
|
|
113
|
+
| `quote` | 来自用户原话、仓库状态或 `.comet.yaml` 的证据片段。 |
|
|
114
|
+
| `source` | 证据来源:`user`、`repo` 或 `state`。 |
|
|
115
|
+
|
|
116
|
+
## `proposed_route`
|
|
117
|
+
|
|
118
|
+
| 字段 | 含义 |
|
|
119
|
+
| ----------------------- | ----------------------------------------------------------------------------------- |
|
|
120
|
+
| `name` | Agent 候选路由:`full`、`hotfix`、`tweak`、`resume`、`ask_user` 或 `out_of_scope`。 |
|
|
121
|
+
| `confidence` | Agent 对候选路由的置信度,只用于诊断,不用于决定是否因置信度不足而询问用户。 |
|
|
122
|
+
| `next_skill` | 派生字段,由 Runtime 统一计算;最小示例不需要填写。 |
|
|
123
|
+
| `requires_confirmation` | 派生字段,由 Runtime 统一计算;最小示例不需要填写。 |
|
|
124
|
+
| `fallback_reason` | 派生字段,由 Runtime 统一计算;最小示例不需要填写。 |
|
|
125
|
+
|
|
126
|
+
## 路由判断要点
|
|
127
|
+
|
|
128
|
+
- 修复已有异常、回归或错误行为,且没有新增能力、API、schema 或跨模块风险:倾向 `hotfix`。
|
|
129
|
+
- 文案、配置、文档、提示词,或单一 OpenSpec change 内的轻量至中等修改:倾向 `tweak`。
|
|
130
|
+
- 新增能力、公共 API 或 schema 变更、跨模块协调、架构调整:倾向 `full`。
|
|
131
|
+
- 有多个未归档的 change,用户没有指定目标:`ask_user`。
|
|
132
|
+
- 置信度低、缺少关键证据,或用户指定的流程与实际风险不匹配:`ask_user`。
|