ce-compound

/ce-compound

**结果：**将一个符合条件的已解决问题写成持久化经验，保存到 <root>/solutions/，以当前代码树为依据，并便于下一个 Agent 查找。

**完成条件：**已编写或更新符合条件的文档，验证其 frontmatter 和声明，记录词汇采集结果，并输出该模式的完成报告；如果没有符合条件的经验，则不写入任何内容，并在报告中说明原因。

**每次运行记录一条经验。**一个会话中产出了多条经验时，必须分多次按顺序运行，不能一次批量处理。阅读 references/research.md；其中说明了批量处理会导致的问题。

前置条件

只记录已解决并经过验证的问题。

只有当经验包含持久有效的项目推理，而这些推理无法轻易从最终代码、测试、类型、注释或现有文档中还原，且遗失后可能导致问题再次发生、造成重大风险或需要大量重新调查时，才值得记录。应用以下反事实判断：如果这份经验文档消失，未来的工程师阅读最终实现后，是否仍可能重犯错误或不得不重新进行大量调查？任务是否完成、付出了多少努力以及 diff 的大小，都不能证明它符合记录条件。

如果反事实判断结果为否，则不写入任何内容，并说明原因。请根据会话内容作出判断，而不要提问。明确调用表示现在需要作出判断，但不会降低标准。

如果现有经验已严重失实或内容不完整，则符合记录条件，因为保留它会误导读者。应更新该经验，而不是另建重复文档。

ce-compound 不会初始化 CONCEPTS.md。它只会在记录经验时顺带为对应领域创建种子内容，不会覆盖整个仓库。若收到独立创建或初始化该文件的请求，应转交给 ce-compound-refresh，然后退出。

模式检测

/ce-compound [brief context]
/ce-compound mode:non-interactive depth:lightweight [context]
/ce-compound mode:non-interactive depth:full [context]

满足以下任一条件时，进入非交互模式：调用参数中包含 mode:non-interactive 标记或其弃用别名 mode:headless；或调用明确表达了非交互意图，例如调用方或常设指令要求以“headless”“non-interactively”“unattended”或“without prompts/questions”的方式运行 ce-compound。同时包含两个标记不构成冲突。单独出现“automatically”或“auto-run”不算非交互信号：它们指的是如何调用技能，而不是如何抑制提问。信号不明确或不存在时，默认采用交互模式。以 mode: 或 depth: 开头的标记是标志，不是上下文；在将其余内容作为简要上下文提示前，先移除这些标记。检测完成后，非交互模式适用于整个运行过程。

只有在非交互模式中，才可通过显式标记选择深度，且最多接受一个深度标记。depth:lightweight 会直接进入轻量模式。depth:full 或不带深度标记时，进入完整模式，包括自动探查会话历史。未携带深度标记的非交互调用会按原有方式运行。非交互轻量模式不会提出任何阻塞性问题，也不会启动子 Agent。如果调用包含未知的 depth: 标记、多个 depth: 标记，或在没有非交互意图时包含 depth: 标记，不要自行判断：输出非交互失败报告，并以 Documentation skipped 结束。

**非交互模式不提问。**在任何阶段都不会提出任何阻塞性问题，因为进入此路径的调用方没有人可以回答。所有非交互退出（包括任何阶段尚未运行便退出的情况）都必须以调用方可解析的终止信号结束：Documentation complete；或者在未编写文档时，以 Documentation skipped 及其原因结束。交互模式只会在步骤对应的参考文档要求时提问，包括“可发现性检查”的许可，以及涉及多份过时文档时需要选择运行哪项更新。

Artifact Root

首次组合 <root>/solutions/ 路径时，解析 <root>，并向子 Agent 传递解析后的路径，而不是配置文件。

组合任何 artifact 路径前，先解析 CE artifact root <root>。

• 读取 <repo-root>/.compound-engineering/config.yaml 中的 docs_root（<repo-root> = git rev-parse --show-toplevel）。不要从 config.local.yaml 读取。未设置时，<root> 为 docs，与之前完全相同。
• 验证已设置的值：它必须是仓库相对目录，其真实路径（解析符号链接后）仍位于仓库内，且既不能是仓库根目录，也不能位于 .git/ 下。否则停止并报错，指出 docs_root 和该值——绝不要回退到 docs。
• 使用 <root> 作为唯一的 artifact 位置：若不存在则创建；将每个路径组合为 <root>/<subdir>，其中 <subdir> 是此技能自己的子目录；绝不要同时读取 docs。

写入边界

只有编排器可以写入产品文件。 第 1 阶段的子 Agent 只能写入每次运行专用的临时目录，绝不能触碰 <root>/、项目指令文件或任何其他已跟踪路径。

编排器会在 <root>/solutions/ 下写入一条学习记录，并执行两项维护性副作用，具体步骤会另行说明：在词汇收集期间写入 CONCEPTS.md；并且——仅在交互式 Full 模式且获得同意后——在项目指令文件中添加一条简短的可发现性说明。另外两项写入仅在交互式 Full 模式下，且用户在汇编目标步骤中选择时才会发生：在一个可写的、已声明的 Compound Pack 中写入规则文件，并将 packs: 条目追加到 .compound-engineering/config.yaml。若 CONCEPTS.md 不存在，则创建它属于预期行为，不构成违规。指令文件只能编辑，不能创建。不得写入树中的其他内容。对其他文档的编辑属于 ce-compound-refresh；此技能只会建议或以有限范围调用它，绝不会代替它执行。

选择路径

步骤 1 前先阅读 references/modes.md。 交互式运行会自行选择深度，而不是询问用户；该参考文件说明了为何深度选择和会话历史都不是需要提问的事项。默认使用 Full。只有当会话接近上下文限制时，才选择 Lightweight。

Lightweight 模式完全跳过会话历史；非交互式 Full 运行会执行相同的自动探查，不会提问，因此符合非交互式约定。

Full 模式

按以下顺序执行。每个步骤指定的参考文件都是必读内容。

1. 研究——阅读 references/research.md。
2. 会话历史——阅读 references/session-history.md，并在派发 Related Docs Finder 之后启动会话历史检索，使其与起草并行，而不是串行执行。会话历史是第 1 阶段的最后一项输入，不是工作流的停止点。检索返回后（包括返回“没有相关的既往会话”时），直接进入汇编，不要暂停或总结。
3. 汇编与写入——等待所有第 1 阶段输入完成，然后阅读 references/assembly.md。
4. 刷新检查与可发现性——阅读 references/refresh-and-discoverability.md。
5. 可选增强——阅读 references/enhancement.md。仅限交互式运行。
6. 报告——阅读 references/report.md，了解此模式必须输出的报告格式，以及技能如何结束。

Lightweight 模式将步骤 1-6 替换为单次流程；阅读 references/lightweight.md，其中定义了两种模式各自的完成输出。