comet-dsh-plugin 0.0.0-stage → 0.5.3
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 +57 -4
- package/rules/comet-workflow-guard.md +63 -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 +294 -0
- package/skills/comet/scripts/comet-hook-router-guard.mjs +628 -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 +571 -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 +464 -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,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: comet-any
|
|
3
|
+
description: '根据目标调查 Skills,创作 Native 扩展、Classic 编排或独立应用的完整入口 Skill 与业务 Rule;确认后由 SDK 装配 Runtime、接入 Hook 并预览安装。不用于一般 Skill 的整理或评审。'
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Comet Any
|
|
8
|
+
|
|
9
|
+
根据用户目标调查真实 Skills,创作组合应用的正文、流程和业务实现。通过 `comet creator` 保存方案与进度,每完成一个阶段就读取当前动作,推进到完成、需要用户决定或外部能力阻塞。
|
|
10
|
+
|
|
11
|
+
Agent 编写入口 Skill、业务 Rule、执行端口与验证器;SDK 保留正文,追加执行协议和通用保护规则,并装配 Runtime。业务 Rule 描述业务约束,Runtime 与 Guard 控制动作、批准和写入权限。安装使用 SDK 正式分发。
|
|
12
|
+
|
|
13
|
+
## 开始或继续
|
|
14
|
+
|
|
15
|
+
1. 已知创作名称时运行 `comet creator status <name> --project <项目> --json`,再执行 `comet creator next <name> --project <项目> --json`。保留原名称与 Run;中断后先查询原 Action,不重复发起已完成工作。
|
|
16
|
+
2. 新创作先读取 `comet creator guide --project <项目> --json`。从用户描述确定目标与安装位置;只有无法调查且会改变结果的选择才询问用户。使用 `comet creator start <name> --project <项目> --goal <用户目标> --install-target <相对目录> --host codex|claude-code --json` 启动。
|
|
17
|
+
3. 首次领取或提交动作前,读取[创作动作与恢复](reference/sdk-creation.md)。使用返回的 Action、attempt、inputHash 和本次宿主会话标识;当前动作没有所需能力时明确阻塞,保留现场。
|
|
18
|
+
|
|
19
|
+
## 分析与方案
|
|
20
|
+
|
|
21
|
+
`analyze` 由宿主调查和创作。需要委派时,传递原目标、当前动作、工作范围和固定依赖。
|
|
22
|
+
|
|
23
|
+
1. 用 `comet creator candidates --project <项目> --json` 发现候选;读取候选的 `SKILL.md`、脚本和必要资源。检查实际输入、输出、授权、宿主能力、结束条件、失败与恢复;不按名称推测能力,不改第三方原文件。
|
|
24
|
+
2. 对方案中必须使用的 Skill:
|
|
25
|
+
|
|
26
|
+
**立即执行:** 使用 Skill 工具加载 <skill-name> 技能。禁止跳过此步骤。
|
|
27
|
+
|
|
28
|
+
技能加载后,依据实际内容填写适配契约与内容摘要;自行审批或发布的 Skill 须声明相应能力与副作用。
|
|
29
|
+
|
|
30
|
+
3. 选择用户需要的起点:Native 增加步骤、指导和审查;Classic 在 full、hotfix、tweak 的允许位置编排;独立流程声明顺序、分支、汇合、子流程和有界修复。将用户交互、共同理解确认和实施步骤纳入 Runtime。
|
|
31
|
+
4. 编写完整入口 Skill:frontmatter 的 name 等于应用 id,description 写清触发场景;正文说明输入、依赖 Skill 的调用、交互与审批、产物、验收、失败和恢复。业务 Rule 约束具体业务行为;详细材料按需放入 references,并写明读取条件。
|
|
32
|
+
5. 按参考中的 `documents` 结构回传正文,与流程和业务端口组成当前方案。逐阶段填写 `manifest.artifactContracts`:有必需文件时声明真实引用、内容条件和必要的业务验证器;没有强制文件时填写 `noArtifactsReason`。每个必需产物阶段提供 `artifactTests` 正常样例,业务验证器还需提供通过通用文件检查的异常样例。条件不明确时先澄清,不能用自报完成代替。具体结构见[创作动作与恢复](reference/sdk-creation.md)。缺少正文、实现、验证器、依赖或能力时补齐分析;已有方案则走 revise 后重新确认。
|
|
33
|
+
|
|
34
|
+
## 确认、验证与交付
|
|
35
|
+
|
|
36
|
+
1. `next` 到达方案确认时,展示完整正文、内容摘要、实际步骤、Skill 绑定、产物、检查、失败路径与能力限制,并说明编译后可选择 Eval。
|
|
37
|
+
2. 用户明确确认当前方案后,提交当前 `confirm-plan` 的用户决定。摘要只是方案标识;得到摘要不等于获得授权。拒绝则保留现场;修改方案走 `revise`,受影响的确认与验证重新执行。
|
|
38
|
+
3. 连续调用 `next` 完成编译、实际加载和阶段产物验收。SDK 在隔离目录检查正常样例能完成,并自动构造缺文件、空文件、内容变化等反例,核对原 Action 未被推进。业务异常样例须被实际验证器拒绝。这些本地检查必须通过才可安装,跳过模型 Eval 不会跳过它们。失败时保留现场,修正方案或产物后沿原 Action 恢复。
|
|
39
|
+
4. 到达 `confirm-eval` 时,展示 Agent、模型、用例数、交互轮数和总时限,让用户选择 evaluate、skip 或 revise。evaluate 后调用 `next` 执行并保存报告;重试复用原用例,修订应用后优先沿用。失败或未完成时停在 `review-eval`,展示报告与未覆盖路径,让用户选择 retry、revise 或明确 skip;跳过仍保留实际状态。
|
|
40
|
+
5. 安装前展示导出目录、平台入口、固定依赖、Runtime、Rule/Hook 配置、冲突与 Eval 状态;预览不写安装目标。`install-target` 使用与平台入口分开的导出目录,例如 `.comet/creator/exports/<应用名>`。只在用户明确批准当前预览后提交 `confirm-install`,由 Creator 导出并正式安装。预览失败或安装中断时,按参考中的恢复步骤处理;目标、依赖、文件、配置或评估报告变化后重新确认。
|
|
41
|
+
6. 交付包与入口位置、实际检查、Eval 报告、未执行项和限制。分别列出真实 Skill 加载、Rule 配置、Hook 执行、SDK Run 和业务断言的结果;配置安装成功不代表 Hook 已生效。
|
|
42
|
+
|
|
43
|
+
## 恢复边界
|
|
44
|
+
|
|
45
|
+
- 使用原 Run ID、当前 Action/Wait 和输入摘要继续,不复用陈旧请求。
|
|
46
|
+
- 未知执行先核对原实验、进程或产物;无法确认时保留现场并阻塞,不盲目重试。
|
|
47
|
+
- 凭据仅通过执行环境注入,不写入方案、源码、生成包、Run 或报告。
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# 创作动作与恢复
|
|
2
|
+
|
|
3
|
+
仅在领取、回传、确认或恢复当前 Creator 动作时读取本页。请求存入临时 JSON,运行 `comet creator dispatch <name> --project <项目> --request <临时JSON> --json`;不编辑 Runtime 状态。
|
|
4
|
+
|
|
5
|
+
## 分析动作
|
|
6
|
+
|
|
7
|
+
宿主只领取 `analyze`,调查真实 Skills 并回传创作结果。compile / verify / eval-preview / evaluate / preview / install 由 `next` 的固定 `creator-local` 执行器完成,不领取或代回报这些机器 Action。`next` 停下后处理返回的 Action 或 Wait。
|
|
8
|
+
|
|
9
|
+
先读取当前 `actions` 中的 `analyze`,提交 `operation: claim`,保留 `runId`、`actionId`、`attempt`、`inputHash`;使用 `executorId: creator-host`、实际 `sessionId`、唯一且稳定的 `claimToken`,并提供实际具备的 `capabilities: [skill-load, handoff]`。领取成功后才执行分析。
|
|
10
|
+
|
|
11
|
+
回传 `operation: record-outcome`。`outcome` 保留相同 Action 身份与 claimToken,并使用唯一 outcomeId、真实 status 和 output。成功 output 包含:
|
|
12
|
+
|
|
13
|
+
- `summary`:说明目标与所选流程。
|
|
14
|
+
- `failurePaths`:至少一个具体失败与恢复路径。
|
|
15
|
+
- `limitations`:说明能力与证据边界。
|
|
16
|
+
- `proposal`:公开 `@rpamis/comet/applications/compiler` 接受的声明式方案,包含 `schema: comet.workflow.application.plan.v1`、manifest、composition、modules;由组合器生成 workflows,不拷贝完整手写 createApplication。
|
|
17
|
+
- `proposal.documents`:Agent 创作的完整入口 `SKILL.md` 与 `rules/workflow-guard.md` 业务规则;可补充正文实际引用的 `references/*.md`。两份必需正文缺失或为空时,Creator 拒绝分析、准备或确认,不以模板补齐后宣称创作完成。
|
|
18
|
+
- `evaluation`(可选):agent、model、judgeAgent、judgeModel、maxTurns、timeoutSeconds,也可通过 `--eval-config <JSON文件>` 提供;实际设置在评估预览中确认。凭据仅从执行环境读取。
|
|
19
|
+
|
|
20
|
+
manifest 指定应用身份、基础流程、Runtime 版本和 Skill 依赖。依赖填写绝对目录、实际内容摘要与适配契约,由组合器读取固定字节。SDK 保留 `documents` 正文,并在同一文件后追加执行协议和通用保护规则;Rule 由 manifest.rule 引用。modules 提供业务执行端口、验证器和已声明的纯转移处理器,不接管 SDK 状态机。额外 Guard 只能收紧保护,不能允许写入 SDK 控制资源;业务 Rule 不授予 Runtime 权限,也不代替用户批准。
|
|
21
|
+
|
|
22
|
+
`documents` 示例(与 manifest / composition / modules 一起放入 proposal):
|
|
23
|
+
|
|
24
|
+
```json
|
|
25
|
+
{
|
|
26
|
+
"documents": {
|
|
27
|
+
"SKILL.md": "---\nname: report-review\ndescription: 根据来源生成报告,审阅后发布。\n---\n\n# 报告审阅\n\n用户需要审阅后发布报告时启动。先读取目标和来源,调用已固定的报告 Skill 生成草稿;展示当前草稿并等待用户批准,随后发布该草稿。拒绝时保留草稿;修订后重新审阅。完成前校验报告、来源引用和发布产物。详细来源检查见 references/source-review.md。\n",
|
|
28
|
+
"rules/workflow-guard.md": "# 报告业务规则\n\n只使用已提供的来源,结论须能追溯。保留拒绝的草稿和审阅记录。内容变化后重新审阅,发布内容必须与获批草稿一致。\n",
|
|
29
|
+
"references/source-review.md": "# 来源检查\n\n在生成草稿前逐项核对来源,记录每个结论对应的证据;缺失证据时先澄清。\n"
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
示例 id 为 report-review;实际 frontmatter name 必须匹配 manifest.id,description 和正文均非空。`plan.documents` 原文参与当前方案摘要;改变正文须沿 revise 重新确认。
|
|
35
|
+
|
|
36
|
+
分析成功后运行 `next`,取得实际装配结果,结合有效图检查步骤、产物、Skill 绑定和能力限制,再展示方案。
|
|
37
|
+
|
|
38
|
+
## 阶段产物与本地验收
|
|
39
|
+
|
|
40
|
+
新创作在 `proposal.manifest.artifactContracts` 中声明阶段产物。独立流程的每个执行步骤必须有契约;Native、Classic 保留原领域验收,为绑定的新增或替换 Skill 声明契约。需要文件时填写 `artifacts`;没有强制文件时填写非空 `noArtifactsReason`。两者不能同时填写。路径或内容条件不明确时先澄清,不按 Skill 名称推断。
|
|
41
|
+
|
|
42
|
+
每个契约用 `workflowId`、`stepId` 绑定实际步骤。产物使用安全相对路径 `ref`,或用 `refFrom` 从当前步骤 output 读取路径。默认要求非空;可追加 `schema`(同步 JSON Schema)、`requiredText`、`requiredHeadings`。已有输出包含 SHA-256 时用 `sha256From` 指定字段,否则回报的 `outcome.artifacts` 必须包含对应 `uri` 和真实 `sha256`;SDK 执行端口会自动收集实际文件证据。不能把 `exists: true` 或路径字符串当成文件已完成。
|
|
43
|
+
|
|
44
|
+
子流程的完成结果由 SDK 管理,产物契约必须用 `sha256From` 指向子流程输出中的实际摘要。Action 绑定含 `workspaceFrom` 时,产物相对该次激活的实际工作区检查。
|
|
45
|
+
|
|
46
|
+
例如设计步骤必须生成文档,方案包含:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"manifest": {
|
|
51
|
+
"artifactContracts": [
|
|
52
|
+
{
|
|
53
|
+
"workflowId": "design-build",
|
|
54
|
+
"stepId": "design",
|
|
55
|
+
"artifacts": [{ "ref": "docs/design.md", "requiredHeadings": ["目标", "验收"] }]
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
"workflowId": "design-build",
|
|
59
|
+
"stepId": "review",
|
|
60
|
+
"artifacts": [],
|
|
61
|
+
"noArtifactsReason": "此步骤只收集审阅意见,不生成新文件。"
|
|
62
|
+
}
|
|
63
|
+
]
|
|
64
|
+
},
|
|
65
|
+
"artifactTests": [
|
|
66
|
+
{
|
|
67
|
+
"workflowId": "design-build",
|
|
68
|
+
"stepId": "design",
|
|
69
|
+
"output": {},
|
|
70
|
+
"files": { "docs/design.md": "# 目标\n\n实现用户需求。\n\n## 验收\n\n检查实际结果。\n" }
|
|
71
|
+
}
|
|
72
|
+
]
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
这段是补充到完整 manifest、composition、modules、documents 的字段示例。业务特有条件写入固定模块中的验证器,并绑定到步骤的 `validator`。`artifactTests` 的正常样例必须通过实际检查;有业务验证器时,提供 `invalidCases: [{ name, files, output? }]`,异常材料必须仍通过通用文件和回报结构检查,以证明拒绝来自业务验证器。样例是隔离测试数据,不得包含用户真实凭据。需要当前输入或激活数据时填写样例 `input`、`activation`;验证器应只读本地材料。
|
|
77
|
+
|
|
78
|
+
验收结果绑定当前 Run、Action、输入和实际文件摘要。后续动作启动前复验其依赖的原结果;内容变化后保留现场并重新检查。显式修复步骤可在契约 `replaces` 中列出同一流程要重做的产物步骤,修订后的结果替代旧证据;不能隐式忽略变化。检查代码、契约或样例变化后走 revise,重新确认和编译。
|
|
79
|
+
|
|
80
|
+
报告样板由 SDK 提供对应契约与样例,应用本身的来源真实性或其他业务条件仍需单独验证。Creator 本地验收不执行真实宿主、模型或外部服务,不取代业务评估。
|
|
81
|
+
|
|
82
|
+
本地验收失败进入 `review-verification`:retry 重跑本地检查;revise 返回分析并重新确认方案;rejected 停止并保留现场。此等待点没有 skip 选项,跳过可选模型 Eval 不会跳过必需的本地验收。
|
|
83
|
+
|
|
84
|
+
## 用户决定
|
|
85
|
+
|
|
86
|
+
当前 `waits` 中只有待处理的 Wait 能接受决定。取得用户明确选择后,提交 `operation: resolve-wait`,保留 `runId`、`waitId`、`proposalHash`,附唯一 decisionId 和当前 Wait 支持的 choice。不要替用户审批或选择跳过。
|
|
87
|
+
|
|
88
|
+
方案与安装分别通过 confirm-plan、confirm-install 批准。旧摘要或内容漂移时走 revise,重新分析并展示方案。安装 preview 的 files / target 是导出计划,distribution 是固定版本、依赖、宿主入口和 Rule/Hook 配置计划;两部分由当前安装 Wait 一起批准,任一部分变化后重新确认。平台缺少 Hook 支持或需要启用时,在预览中说明。
|
|
89
|
+
|
|
90
|
+
编译验证后,confirm-eval 接受 evaluate / skip / revise。evaluate 固定完整应用快照和实验身份;通过后进入安装预览,失败或未完成进入 review-eval(retry / revise / skip)。重试复用原用例,修订后优先沿用;skip 保留实际失败或未评估状态。
|
|
91
|
+
|
|
92
|
+
install-target 是项目内导出目录,应与 SDK 管理目录和平台 Skill 入口分开。批准后由 Creator 导出固定字节,并通过正式 SDK 安装项目入口、Rule/Hook 和 Runtime 依赖,无需应用私有安装器。用户级安装、升级和卸载使用 SDK 分发入口。
|
|
93
|
+
|
|
94
|
+
只读预览失败进入 review-install,回报包含 reason 与 noFilesWritten。retry 重新生成预览并等待新的 confirm-install;revise 返回 analyze;rejected 停止并保留现场。已发生写入或结果未知时,按下节核对。
|
|
95
|
+
|
|
96
|
+
## 中断与结果未知
|
|
97
|
+
|
|
98
|
+
新进程调用 status / next 读取同一 Run。running 或 unknown Action 先核对原执行是否发生。需要标记未知时使用 mark-unknown,保留原 Action 和 attempt;retry 必须携带当前恢复 proposalHash 和实际 reconciliation。不能以超时为理由重新运行已经发生的安装。
|
|
99
|
+
|
|
100
|
+
核对编译包、导出包和正式平台安装的实际文件,不能只看到导出目录就回报完成。部分写入、文件漂移或无法确认的结果保持阻塞;恢复时保留无关文件与已有安装。
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: comet-archive
|
|
3
|
+
description: '归档并交付 Classic change。在用户调用 /comet-archive,或 Classic Runtime 进入 Archive、恢复交付时使用。'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Comet 阶段 5:归档(Archive)
|
|
7
|
+
|
|
8
|
+
首次进入阶段、交接给新 Agent 或上下文恢复后,读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言),优先采用当前 continuation 或已领取 Action 的 `contextRequest`;同一阶段连续执行不重复获取。
|
|
9
|
+
|
|
10
|
+
收到入口返回的 layout 后,首次接收阶段或绑定变化时执行[阶段共用入口](../comet-classic/reference/scripts.md#阶段共用入口),复用仍有效的 [layout](../comet-classic/reference/classic-layout.md),无需先额外运行 root show;遇编辑判断时按共用入口加载编辑后续行协议。
|
|
11
|
+
|
|
12
|
+
## SDK Run 路径
|
|
13
|
+
|
|
14
|
+
首次进入当前 SDK 阶段、换 Agent 或恢复上下文时,读取[阶段入口与恢复](../comet-classic/reference/sdk-methods.md#阶段入口与恢复)及该参考的当前阶段章节;本会话已有且仍有效时直接复用。下文按当前阶段执行;`nextAction.kind` 的恢复路由只适用于没有 continuation mode 的旧响应。
|
|
15
|
+
|
|
16
|
+
优先复用同一 change、工作区和 Run 的最新有效响应中的 `agent.continuation`、`data.nextAction`、phase、revision 和路径摘要。只有冷恢复、工作区或外部状态变化、响应版本已过期或缺少当前步骤必要信息时,才运行 `comet state next <change-name> --json`;不要因加载下一 Skill 再读一次。后续写操作仍由 Runtime 校验当前版本与证据,不能用缓存跳过检查或批准。确认 `data.runtimeFormat: sdk`、phase 和 `nextAction.kind`,在已绑定的 `projectRoot` 执行;路径缺失或绑定发生变化时才运行 `comet classic workspace resolve <change-name> --json`。SDK Run 的 Verify 收据必须仍有效;状态文件和验证报告存在并不表示已获归档授权。`reconcile` 时运行 `comet state check <change-name> archive --recover --json` 核对原 Action 与磁盘、Git 证据,结果未明时不重做归档、提交、push 或 PR。
|
|
17
|
+
|
|
18
|
+
1. 复用当前有效的状态、工作区和证据摘要;缺少时运行 `comet state check <change-name> archive --json`。按 SDK 方法参考的 Archive 与 Git 交付章节 核对验证结论、当前绑定分支、归档影响和无关改动。需要推送或 PR 时,先确认 remote 和 PR base;多个可选目标不能猜测。用当前目标与效果摘要运行 `comet state propose-archive <change-name> --summary "<delivery-summary>"`,需要时附 `--remote <name>`、`--pr-base <branch>`。保存返回的 `data.wait.proposalHash` 为 `<proposalHash>`;恢复已有待决定 Wait 时复用它,不重复提案。
|
|
19
|
+
2. 按 decision-point.md 展示当前提案和 SDK 方法参考的 Archive 与 Git 交付选项。已有明确授权覆盖当前归档影响和相同交付目标时沿用;否则等待用户选择。用 `comet state decide-archive <change-name> --proposal-hash <proposalHash> --choice <local|push|pr|reverify|later>` 提交当前选择:local 仅归档并提交,push 再推送,pr 推送并创建 PR,reverify 返回 Verify,later 保留当前工作并停止本次调用。目标或 Verify 证据改变时重新核对并取得新的决定;旧提案哈希不能继续使用。
|
|
20
|
+
3. 只有 Run 记录了有效的 `local|push|pr` 决定,才直接运行 `comet guard <change-name> archive --apply`。Guard 核对授权、分支和 Verify 收据,在同一 Run 中完成一次 OpenSpec 归档。中断后先看 `state next --json` 与 `--recover` 返回的 Action;已应用的归档不能再次发送。
|
|
21
|
+
4. 按 SDK 方法参考的 Archive 与 Git 交付章节核对 dirty-worktree,显式暂存本 change 的实现、归档目录、主 spec 及 Design Doc/Plan 标注,检查 staged diff,再创建唯一归档提交。SDK Guard 不代替 Agent 执行 Git;不调用旧 `state set branch_status`、`state delivery` 或 `archive-confirm`。选择 `push` 时推送已批准的 remote/分支;选择 `pr` 时先推送再创建目标匹配的 PR。调用结果未知时先只读核对远端或 PR,不盲目重试。
|
|
22
|
+
5. 使用真实提交 SHA 运行 `comet state complete-delivery <change-name> --commit <sha>`;PR 选择还需附 `--pr-url <url>`。该命令只核对归档提交及已批准的远端/PR 结果并结束 Run,不执行提交、push 或建 PR。验证失败时保留原 Run 与选择,按返回的具体缺口恢复;只有同次结果表明 Run 已完成且 continuation 为 done,才宣告交付完成;结果未提供终态时才运行 `comet state next <change-name> --json` 核对。
|
|
23
|
+
|
|
24
|
+
## Compat 路径
|
|
25
|
+
|
|
26
|
+
以下旧 Runtime 步骤仅用于 `runtimeFormat: compat`。必须读取 [Compat 操作](reference/compat.md),按其中当前阶段继续;SDK 不加载该参考。
|
|
27
|
+
|
|
28
|
+
项目 `change_walkthrough` 默认开启,已有 `walkthrough.html` 随 change 材料归档,完成回复给出实际归档文件的打开链接;关闭时也保留已有页面。缺页不补生成、不阻塞归档,不为展示增加检查、阶段或确认。
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
# comet-archive Compat 操作
|
|
2
|
+
|
|
3
|
+
仅在 `runtimeFormat: compat` 时读取。SDK 使用主 Skill 与 SDK 方法参考。
|
|
4
|
+
|
|
5
|
+
## 前置条件
|
|
6
|
+
|
|
7
|
+
- 验证已通过(阶段 4 完成)
|
|
8
|
+
- 归档或所选交付动作尚未完成;恢复不要求 branch_status 仍为 pending
|
|
9
|
+
- `<classic-change-dir>/.comet.yaml` 中 `verify_result: pass`
|
|
10
|
+
|
|
11
|
+
## 步骤
|
|
12
|
+
|
|
13
|
+
### 0. 设置输出语言
|
|
14
|
+
|
|
15
|
+
归档摘要和流程完成说明,使用本轮入口返回的 configuration.language,不再单独查询语言。
|
|
16
|
+
|
|
17
|
+
### 0b. 入口状态验证(Entry Check)
|
|
18
|
+
|
|
19
|
+
按 `comet-classic/reference/scripts.md` 使用正式支持的 `comet` CLI,执行以下入口验证。从任意入口恢复任务时,先按 `comet-classic/reference/context-recovery.md` 检查恢复状态:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
comet state select <change-name>
|
|
23
|
+
comet state check <name> archive --json
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
上一阶段 guard 已成功返回本阶段状态信息时,直接使用其中的状态与 `agent.continuation` 继续,不重复 select/check;恢复任务、工作区变化或外部状态变化时,才执行上述入口验证。使用入口返回的 layout、configuration、nextAction 和 delivery 摘要继续。丢失上下文后恢复任务时,按 context-recovery.md 读取所需详情。已有授权仍然有效、交付目标也没有变化时,只继续未完成的动作,不重复询问。失败时,处理返回的具体原因。
|
|
27
|
+
|
|
28
|
+
若上述 `select` / `check` 输出 `BLOCKED` 或分支绑定 `ERROR`,且原因是 `bound_branch` 与当前分支不一致,立即按 `comet-classic/reference/decision-point.md` 暂停,让用户单选:切回绑定分支后重新运行入口验证,或在用户明确确认当前分支应接管该 change 后运行 `comet state rebind <change-name>` 并重新入口验证。不得自行切换分支,不得自行换绑。
|
|
29
|
+
|
|
30
|
+
### 1. 请用户确认归档与交付方式
|
|
31
|
+
|
|
32
|
+
读取入口返回的 configuration.isolation 与 delivery。没有有效授权,或交付目标发生变化时,**按 decision-point.md 暂停,请用户确认归档和交付方式**。已有授权时,先由 Runtime 核对实际 Git 状态和交付进度,再按 nextAction 继续。不能仅凭 branch_status: handled 就认定用户已授权归档、push 或创建 PR,也不能在获得授权前运行 archive-confirm 或 archive。
|
|
33
|
+
|
|
34
|
+
确认前必须向用户展示简短摘要:
|
|
35
|
+
|
|
36
|
+
- change 名称
|
|
37
|
+
- 验证报告路径和结论
|
|
38
|
+
- 当前分支、工作区,以及未提交改动分别属于哪些工作的核对结果
|
|
39
|
+
- 本次归档将执行的不可逆动作:按 OpenSpec delta 语义合并主 spec、标注 design doc / plan、移动 change 到 archive 目录
|
|
40
|
+
- 归档完成后将采用的提交处理方式:只保留在本地、推送当前绑定分支,或推送后创建 PR
|
|
41
|
+
|
|
42
|
+
Git 协调根的用户确认问题必须以单选题形式呈现,包含以下全部选项。文本降级模式必须使用下表;使用结构化提问时,将“方式”作为短标签、“实际影响”作为说明,不得缩短为含义不明确的选项:
|
|
43
|
+
|
|
44
|
+
| 选项 | 方式 | 实际影响 |
|
|
45
|
+
| ---- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
46
|
+
| A | 仅归档(不推送) | 完成归档并创建唯一归档提交;提交只保留在当前绑定分支,不推送、不创建 PR |
|
|
47
|
+
| B | 「确认归档并立即推送」 | 完成归档并创建唯一归档提交,然后推送当前绑定分支;不创建 PR |
|
|
48
|
+
| C | 「确认归档、立即推送并创建 PR」 | 完成归档并创建唯一归档提交,推送当前绑定分支,然后创建 PR |
|
|
49
|
+
| D | 「需要调整或重新验证」 | 不归档;运行 `comet state transition <change-name> archive-reopen` 回到 `phase: verify`,再调用 `/comet-verify`;若确认需要修复,再按验证失败决策回到 `/comet-build` |
|
|
50
|
+
| E | 「暂不归档」 | 不运行 `archive-confirm` 或归档命令,不提交、不推送;保留未归档的 change、`phase: archive` 和 `branch_status: pending`,等待稍后再次调用 `/comet-archive` |
|
|
51
|
+
|
|
52
|
+
若协调根目录本身不属于 Git 工作树,而业务代码在独立的子仓库,改为向用户确认“仅归档协调文档”或选择 D/E。说明该方式会合并主 spec、移动并保存归档文档,在协调根的 `.comet/classic-deliveries/` 留下文件摘要回执;子仓库的提交和推送须按各仓库单独核对,不能作为协调文档的归档提交。用户确认后写入 `{ "action": "archive-only" }`,不填写 `targetBranch`、`remote`、`commit` 或 `prUrl`。该方式仅适用于非 Git 协调根;Git 项目仍使用 A/B/C。
|
|
53
|
+
|
|
54
|
+
只有用户选择 A、B、C 或明确确认上述“仅归档协调文档”后,才将选择保存为 JSON 并通过 Runtime 记录,再确认归档:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
comet state delivery <change-name> --file <json-path>
|
|
58
|
+
comet state transition <change-name> archive-confirm
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Git 交付的 JSON 包含 action(A=local、B=push、C=pr)、targetBranch,以及可选的 remote、commit 和 prUrl。文档归档的 JSON 只包含 `action: archive-only`。初次记录时,只填写已确认的动作和目标;尚不知道的 commit/prUrl 不得伪造,等操作实际完成后再补写。
|
|
62
|
+
|
|
63
|
+
targetBranch 是接收归档提交的绑定分支,与 PR 的 base 分支含义不同。PR base 使用已有的明确配置;存在歧义时先澄清。存在多个 remote 时,明确推送目的地,不自行猜测。例如,用户已确认推送时:
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"action": "push",
|
|
68
|
+
"targetBranch": "<confirmed-bound-branch>",
|
|
69
|
+
"remote": "<confirmed-remote>"
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
用文件工具保存 JSON,再传给 delivery --file。输入文件放在 change 目录之外(例如仓库根的 `delivery-input.json`),用后删除;不得写进 change 目录,尤其不得使用 `<change-dir>/.comet/delivery.json`——那是 Runtime 的交付记录,Runtime 会识别同一路径的大小写写法和文件系统别名,并直接报告输入路径冲突。输入只包含 action、targetBranch 和可选的 remote、commit、prUrl;schemaVersion 等字段属于 Runtime 记录,不得出现在输入中。归档提交确认后,在同一完整记录中追加 `"commit": "<actual-archive-commit-sha>"`;action 为 pr 且 PR 已创建时,再追加真实 prUrl。commit 由 Runtime 保存在 Git 忽略的交付回执中,change 目录内被跟踪的 `delivery.json` 始终不含 commit;归档提交后 change 目录必须与该提交保持零差异,不得在其中新增、修改或删除文件,否则完整性校验失败。local 示例只需 action:local 和已确认 targetBranch,不要求 remote。
|
|
74
|
+
|
|
75
|
+
普通 `comet state delivery <change-name>` 只读取已保存的记录,入口摘要也不访问网络。恢复远端交付、上次调用没有返回明确结果,或准备宣告完成时,必须显式运行:
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
comet state delivery <change-name> --verify
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
返回结果为 `{delivery, verification}`。delivery 是已保存的用户选择和执行进度,verification 是 Runtime 对实际 Git、远端分支和 PR 的只读核对结果。仅有 delivery 记录或入口检查成功,不能证明远端交付已经完成。按核对结果处理:
|
|
82
|
+
|
|
83
|
+
- 已确认 not-yet-delivered,例如尚未首次 push,或已推送但尚未创建 PR:授权和目标仍然有效时,继续未完成的动作,再用 --verify 核对;不能仅因为 notVerified/needsVerification 就停止。
|
|
84
|
+
- unavailable,即网络、权限或服务故障导致无法确定实际结果,或出现目标冲突、结果不确定:保留记录并停止。先解决只读核对遇到的问题,不盲目重试 push,也不重复创建 PR。
|
|
85
|
+
|
|
86
|
+
delivery 写入或 transition 失败均停止。只有两者成功才继续 Step 2。用户选择 D 时运行 archive-reopen,旧交付授权应失效,重新验证后重新确认;选择 E 直接停止,不归档、提交、推送或设置 handled。
|
|
87
|
+
|
|
88
|
+
### 2. 执行归档
|
|
89
|
+
|
|
90
|
+
运行归档脚本:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
comet archive "<change-name>"
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
脚本自动执行:
|
|
97
|
+
|
|
98
|
+
1. 入口状态验证(phase=archive, verify_result=pass, archive_confirmation=confirmed, archived=false)
|
|
99
|
+
2. 在归档前更新 Design Doc 的元数据(archived-with, status)
|
|
100
|
+
3. 在归档前更新 Plan 的元数据(archived-with)
|
|
101
|
+
4. 调用 OpenSpec archive 按 delta 语义合并主 spec 并移动 change 到归档目录
|
|
102
|
+
5. 检查主 spec 中没有残留仅用于增量规格的章节标题(delta-only section)
|
|
103
|
+
6. 在 OpenSpec 实际归档目录中更新 archived 状态,并处理 pending recovery 元数据,保证中断后能够恢复
|
|
104
|
+
|
|
105
|
+
如脚本返回非零退出码,报告错误并停止。
|
|
106
|
+
如脚本返回零退出码,归档完成。
|
|
107
|
+
|
|
108
|
+
脚本摘要中的 `X/Y steps succeeded` 以真实执行步骤计数,不会因 delta spec 同步或文档标注重复累计。
|
|
109
|
+
|
|
110
|
+
脚本会调用 OpenSpec 归档能力按 `ADDED/MODIFIED/REMOVED/RENAMED` 语义合并主 spec,并在归档后校验主 spec 中没有残留 delta-only section 标题。
|
|
111
|
+
|
|
112
|
+
如需预览而不实际执行,使用 `--dry-run` 参数。
|
|
113
|
+
|
|
114
|
+
### 3. Spec 流程完成
|
|
115
|
+
|
|
116
|
+
Spec 从需求讨论到归档的完整流程如下,到此全部完成:
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
brainstorming → delta spec → 实施 → 验证 → 主 spec 合并 → design doc 标注 → 归档
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### 4. 精确提交归档改动
|
|
123
|
+
|
|
124
|
+
若 delivery 的 action 为 `archive-only`,归档命令已将 `branch_status` 设为 `handled`,并在最终完整性检查后记录归档目录中全部文件(含归档时的主 spec 快照)的 SHA-256 摘要。运行 `comet guard <change-name> archive` 和 `comet state delivery <change-name> --verify`;只有返回 `verification.status: complete`,且归档目录、主 spec 快照和回执均保留时才清除 current selection。此路径不执行以下 Git 提交、push 或 PR 步骤;子仓库交付由各仓库自己的记录证明。归档文件之后发生增删改时,回执校验会退回 `needsVerification`,先恢复或重新处理文档,不覆盖已封存回执。
|
|
125
|
+
|
|
126
|
+
归档脚本只移动文件和合并 spec,不会自动提交。归档完成后工作区会有以下未提交改动:
|
|
127
|
+
|
|
128
|
+
- change 目录从 `<classic-change-dir>/` 移动到 `<classic-archive-root>/YYYY-MM-DD-<name>/`
|
|
129
|
+
- 主 spec 按 delta 语义合并的内容
|
|
130
|
+
- design doc / plan 的归档元数据标注
|
|
131
|
+
|
|
132
|
+
确认 delivery 中的实际授权仍有效,再写入兼容字段并运行最终 archive guard(前一条成功后才执行后一条):
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
comet state set <change-name> branch_status handled && comet guard <change-name> archive
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
handled 只是兼容旧流程的状态字段,不能表示用户已授权 local/push/pr,也不能证明这些动作已成功。授权与执行结果以 delivery 记录和 Runtime 对实际 Git、远端的核对为准。状态写入或 guard 失败时停止。恢复任务时,先核对归档提交是否已经存在;存在就复用,不再创建第二个归档提交。
|
|
139
|
+
|
|
140
|
+
归档后读取 `git status --short`,与归档前按 dirty-worktree 协议记录的改动归属逐项核对。只允许暂存明确属于当前 change 的路径:change 原来所在的路径、脚本输出的实际 archive 路径、归档目录中已更新为 `branch_status: handled` 的 `.comet.yaml`、被本次 delta 更新的 main specs,以及当前 Design Doc/Plan 的归档元数据。无法确定某个路径的改动归属时,停止并请用户处理。
|
|
141
|
+
|
|
142
|
+
使用显式 pathspec 暂存核对后的路径,再检查 staged diff;不得使用全仓库暂存,也不得把用户已有改动混入归档提交:
|
|
143
|
+
|
|
144
|
+
提交说明沿用已生效的项目格式、语言和正文要求;已有明确规范时直接准备,无需额外询问。下方消息占位符必须替换为实际说明,不能把示例英文模板当作项目规范。项目 Git Hooks 正常执行;被拒绝时保留暂存内容,修正说明后继续同一次提交。提交调用中断或结果不确定时,先核对实际 Git 记录,不盲目重提,也不绕过 Hook。
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
git add -- <逐项核对后的归档路径...>
|
|
148
|
+
git diff --cached --stat
|
|
149
|
+
git commit -m "<符合项目规范的归档说明>"
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
提交失败或 staged diff 含无关路径时停止,不得继续分支处理。
|
|
153
|
+
|
|
154
|
+
### 5. 交付归档提交并完成
|
|
155
|
+
|
|
156
|
+
归档提交成功后,用 `state delivery --file` 补写实际 commit,再由 Runtime 核对归档提交与交付目标。根据核对结果,只执行已授权且未完成的动作。记录失败时停止交付,不重新提交;恢复时,先核对已有 Git 提交和分支状态,再补齐记录。交付回执由 Runtime 保存,不能为了记录 commit 而反复创建归档提交。
|
|
157
|
+
|
|
158
|
+
- A「仅归档(不推送)」:不执行任何远端操作,归档提交只保留在当前绑定分支。
|
|
159
|
+
- B「确认归档并立即推送」:推送当前绑定分支一次。
|
|
160
|
+
- C「确认归档、立即推送并创建 PR」:先推送当前绑定分支一次,再通过已配置的 GitHub 集成创建 PR;Step 1 的明确选择就是创建 PR 的授权,不得再次改成其他分支处置方式。
|
|
161
|
+
|
|
162
|
+
push 或 PR 调用后,使用 delivery --verify 核对实际远端分支和 PR。PR 创建成功后,通过 delivery --file 补写实际 prUrl,并保留此前的 action、目标和 commit。调用超时或没有返回明确结果时,先查询实际结果,不能盲目重试。失败时保留 delivery 和 current selection,只继续已授权但尚未完成的动作;不得改写、删除或切换分支。
|
|
163
|
+
|
|
164
|
+
local 由 Runtime 确认归档提交存在;push 还需确认远端包含该提交;pr 还需确认对应 PR 存在且目标匹配。仅填写 commit/prUrl 不等于交付成功。所选动作全部经 Runtime 核对完成后,才运行 clear-selection 并宣告完成。
|
|
165
|
+
|
|
166
|
+
归档阶段不再调用 Superpowers `finishing-a-development-branch`,也不提供本地合并、切换、删除或变基等分支拓扑操作。用户只想完成本地归档时,必须在 Step 1 选择 A;用户尚不想归档时,选择 E。
|
|
167
|
+
|
|
168
|
+
## 退出条件
|
|
169
|
+
|
|
170
|
+
- 归档脚本执行成功(退出码 0)
|
|
171
|
+
- 归档目录 `<classic-archive-root>/YYYY-MM-DD-<change-name>/` 存在
|
|
172
|
+
- 归档后的 `.comet.yaml` 中 `archived: true`
|
|
173
|
+
- 归档状态中的 `branch_status: handled` 已包含在唯一归档提交中;`archive-only` 时包含在文件摘要回执中
|
|
174
|
+
- `comet guard <change-name> archive` 通过
|
|
175
|
+
- 唯一归档提交已按用户在归档前确认的方式处理:选择 A 时只保留本地,选择 B 时已成功推送,选择 C 时已成功推送并创建 PR;`archive-only` 时由 Runtime 验证本地文档回执
|
|
176
|
+
- current selection 已在所选处理方式完成后清除
|
|
177
|
+
|
|
178
|
+
归档脚本会把 `<classic-change-dir>/` 移动到 `<classic-archive-root>/YYYY-MM-DD-<name>/`。
|
|
179
|
+
|
|
180
|
+
`comet guard <change-name> archive` 会按原 change 名解析实际归档目录;不要手工拼接日期目录名。
|
|
181
|
+
|
|
182
|
+
## 完成
|
|
183
|
+
|
|
184
|
+
Comet Classic 流程全部完成。如需开始新的 Classic 工作,调用 `/comet-classic` 或 `/comet-open`。
|
|
185
|
+
|
|
186
|
+
## 上下文压缩恢复
|
|
187
|
+
|
|
188
|
+
按 context-recovery.md 执行,phase 为 archive。读取已保存的 delivery 记录,不能依赖当前对话回忆用户选过 A、B 还是 C。Runtime 核对归档目录、提交、远端和 PR 后,只继续尚未完成的动作;local 不执行远端操作。旧 change 只有 handled 记录、缺少授权、交付目标发生变化,或分支关系与记录不一致时,停止并请用户明确确认。不能自行推断授权,也不能自动调整分支关系。
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: comet-build
|
|
3
|
+
description: '制定计划、实施并验收 Classic 任务。在用户调用 /comet-build,或 Classic Runtime 进入 Build、返回 Build 修复时使用。'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Comet 阶段 3:计划与构建(Build)
|
|
7
|
+
|
|
8
|
+
首次进入阶段、交接给新 Agent 或上下文恢复后,读取并执行 [任务上下文与产物语言](../comet-classic/reference/scripts.md#任务上下文与产物语言),优先采用当前 continuation 或已领取 Action 的 `contextRequest`;同一阶段连续执行不重复获取。
|
|
9
|
+
|
|
10
|
+
收到入口返回的 layout 后,首次接收阶段或绑定变化时执行[阶段共用入口](../comet-classic/reference/scripts.md#阶段共用入口),复用仍有效的 [layout](../comet-classic/reference/classic-layout.md),无需先额外运行 root show;遇编辑判断时按共用入口加载编辑后续行协议。
|
|
11
|
+
|
|
12
|
+
## SDK Run 路径
|
|
13
|
+
|
|
14
|
+
先读取并执行[普通命令与检查](../comet/reference/platform-execution.md)。新旧 Run 均使用平台工具执行普通命令,在原 Run 提交实际检查报告;自动升级不恢复旧检查执行器。阶段准备、用户选择、任务完成和验收要求继续有效。
|
|
15
|
+
|
|
16
|
+
首次进入当前 SDK 阶段、换 Agent 或恢复上下文时,读取[阶段入口与恢复](../comet-classic/reference/sdk-methods.md#阶段入口与恢复)及该参考的当前阶段章节;本会话已有且仍有效时直接复用。下文按当前阶段执行;`nextAction.kind` 的恢复路由只适用于没有 continuation mode 的旧响应。
|
|
17
|
+
|
|
18
|
+
优先复用当前有效结果中的 `agent.continuation` / `data.nextAction` 与已绑定状态;只有冷恢复、外部状态变化或缺少必要信息时,才运行 `comet state next <change-name> --json`。`data.runtimeFormat` 为 `sdk` 时,只按本节推进 Run;SDK 方法参考的执行策略选项、计划内容要求、实施与审查方法仍适用,状态和证据通过本节命令提交。`data.phase` 必须为 `build`。已有有效 layout 与当前配置时直接复用;缺少时运行 `comet state check <change-name> build --json`;若 `nextAction.kind` 为 `reconcile`,运行 `comet state check <change-name> build --recover --json` 核对原 Action 的结果,在结果明确前不重发外部工作。
|
|
19
|
+
|
|
20
|
+
先核对有效配置中的 `workflow` 或当前 `nextAction.stepId`。`tweak.build.*` / `workflow: tweak`:**立即执行:** 使用 Skill 工具加载 comet-tweak 技能。禁止跳过此步骤。`hotfix.build.*` / `workflow: hotfix`:**立即执行:** 使用 Skill 工具加载 comet-hotfix 技能。禁止跳过此步骤。技能加载后,传入同一 change、工作区、phase、Run revision 和 continuation,从该预设的 SDK Build 步骤继续,不要求 full Design Doc 或完整计划,也不重跑 Open。旧 Run 的原始 Action 仍可能引用 `comet-build`,同样按此规则路由。已批准升级且当前步骤为 `full.build.*` 时,执行下列 full 路径。
|
|
21
|
+
|
|
22
|
+
1. `full.build.configure` 待执行时,按 SDK 方法参考的 [Build 配置说明](../comet-classic/reference/sdk-methods.md#build)展示值、含义及确认状态,只补真正缺失、无效或用户要求更改的执行方式、TDD 和审查决定。将已确认的 `build_mode`、`tdd_mode`、`review_mode`、`subagent_dispatch` 和需要时的 `direct_override` 写入仓库内的临时 JSON;用户已明确选择这份完整配置时,运行 `comet state propose-build <change-name> --file <configuration-json> --confirmed` 一次保存提案与批准;尚未决定时运行 `comet state propose-build <change-name> --file <configuration-json>`。仅在仍有待决定 Wait 时,从返回的 `data.wait.proposalHash` 保存 `<proposalHash>`,向用户展示实际配置并按 decision-point.md 等待确认。确认或拒绝时运行 `comet state decide-build <change-name> --proposal-hash <proposalHash> --choice <approved|rejected>`;拒绝后从新配置重新提案。恢复已有待决定 Wait 时复用原提案,不重复提问或新建配置 Action。保存批准后简短回显并继续,不再增加一次继续确认。
|
|
23
|
+
2. `full.build.plan` 待执行时,按 SDK 方法参考的 Build 章节创建或核对计划。计划引用当前 Design Doc 和 tasks.md,以 `<!-- comet-task-authority: <classic-task-authority-ref> -->` 及 `<!-- comet-task-ref:<task-id> -->` 映射任务,不能另建 checkbox。运行 `comet state submit-plan <change-name> --plan <plan-ref>` 提交计划及证据。只有用户明确要求写完计划暂停时加 `--pause`;恢复 `plan-ready` Wait 时,必须等用户明确继续,再用该 Wait 的当前哈希运行 `comet state continue-plan <change-name> --proposal-hash <proposalHash>`。计划或任务要求变化后不复用原批准。
|
|
24
|
+
3. `full.build.execute` 待执行时,按 SDK 方法参考的 Build 章节的已选方法实施、做任务级或分段审查并运行相关检查。任务实际完成且审查合格后勾选同一 tasks.md;任务 ID、勾选和协调进度使用共享参考中的 `state tasks`、`state task-complete`、`state checkpoint`;这些命令不推进 SDK Run。SDK 不调用旧 `comet handoff --write`。核对计划、任务和工作区后运行 `comet state complete-build <change-name> --session <builder-execution-ref> --checks <checks-json-file>`,由 Run 进入 Verify。实现或计划与已接受证据不一致时先解决具体漂移,不绕过 SDK 校验。
|
|
25
|
+
|
|
26
|
+
每次推进后,优先使用同次结果的 `agent.continuation` / `data.nextAction`;状态仍有效且信息完整时,不重复 next、select 或 check。仅在冷恢复、外部状态变化或缺少必要信息时补读。只有 `action` 且指向下一阶段时才加载下一 Skill。`decision`、`evidence`、`reconcile` 均先完成当前 Run 的恢复或用户决定。
|
|
27
|
+
SDK Build 使用真实的 `--session <builder-execution-ref>` 关联执行;已经携带时无需再次传入。
|
|
28
|
+
|
|
29
|
+
## Compat 路径
|
|
30
|
+
|
|
31
|
+
以下旧 Runtime 步骤仅用于 `runtimeFormat: compat`。必须读取 [Compat 操作](reference/compat.md),按其中当前阶段继续;SDK 不加载该参考。
|
|
32
|
+
|
|
33
|
+
## 可选变更说明
|
|
34
|
+
|
|
35
|
+
Build 收尾和 Verify 展示结果前,先核对项目 `.comet/config.yaml` 的 `change_walkthrough`(默认开启;仅显式 `false` 关闭)。开启时读取并执行[变更说明](../comet/reference/change-walkthrough.md),用共享模板生成或更新同一 `walkthrough.html` 并给出打开链接;关闭时跳过额外讲解、详细指引和渲染,保留原有摘要。Archive 只随现有材料保存已有页面并提供实际归档链接,不补生成、不新增确认、不为页面更新重跑代码检查。
|