ce-optimize

优化可衡量的目标

**成果：**已确认对指定目标的改进位于 optimize/<spec-name> 分支上，并有磁盘日志。收尾时由用户接手。

**意图：**下一步应是能改变实现内容的成本最低的步骤。在搜索实现方案之前，先核算指定工作负载的成本。搜索并保留经过评分的变体空间，无需先进行性能分析。

**完成条件：**已达到停止标准，所有声明为必需的目标均已达成，或先达到了其他停止条件；最终状态已写入磁盘并经过验证；并已向用户提供完成后的选项。如果运行因无法通过某项检查而停止，请说明阻碍所在。

调用此技能即授权读取代码库、构建测试框架，并在 Phase 1 审批关卡之后进行隔离实验，以及在 optimize/<spec-name> 分支上提交保留或回退变更。当支出没有上限、出现新的依赖项、收尾将推送变更或创建 PR，或者只有用户才能在完成后的选项中做出选择时，请先询问。在这些限制范围内，继续运行下一项实验时无需再次询问。

独立的调用和任务分派放在同一条回复中；只有存在实际依赖关系时才串行执行。

报告发现、用户决定、阻碍和结果。较长的工作过程中，适时更新已了解的情况和剩余事项。常规准备以及阶段或批次转换无需公告。除非会影响当前决策，否则将核算信息保留在日志和最终总结中。

用日常任务语言说明目标、证据和决策。工作流标签（例如“测试框架”）应保留在产物中，除非用户询问相关机制。时长或成本未知时应明确说明未知；上限是限制，不是预测。

只有实际执行后，步骤才算完成。描述测量、任务分派或检查点，不等于完成它。只要范围内仍有工作尚未完成，就不要结束当前轮次。只有在存在经过验证的检查点，并且具备有界的自动续行机制或明确的手动恢复交接时，未完成的工作才可以跨越当前轮次；具体定义见 references/persistence.md。

交互方式

使用当前工具列表中已有的宿主阻塞式提问工具（按能力匹配，而非按宿主特定名称匹配）。工具出现在当前工具列表中，即证明该工具存在；切勿调用面向用户的提问工具来确认其是否存在。如果列表中有匹配的工具但尚未加载，使用宿主的工具发现原语加载该能力：不要搜索其他宿主的工具名称。只有当列表中不存在此类工具，或实际提问调用出错时，才在宿主的聊天界面中提供编号选项。绝不要默默跳过提问。

执行环境

三种能力决定运行状态存放位置、循环如何等待，以及实验在哪里运行。持久状态根目录是测试框架指定的可写位置，能在轮次和上下文重置后继续保留，且位于代码库检出目录之外；如果没有，则状态存放在 .context/compound-engineering/ce-optimize/<spec-name>/ 下。轮次结束后唤醒是指一种机制，可通过外部事件或计时器重新调用，而无需让工具调用持续占用；如果没有，则循环在当前会话内运行，无法持续等待时，会将轮次作为检查点结束，并附上恢复调用。分离式工作进程是指一种任务分派，其结果通过推送的 ref、存储文件或宿主传递的消息到达，而不是作为本地工作树中的编辑到达；execution.backend: remote 需要此能力；如果没有，该规范将在 worktree 上运行。当前工具列表中，或测试框架提供的上下文中出现某项能力，即为其存在的证明；缺少某个二进制文件或环境变量不构成反证。直接采用回退方案，无需询问。

Artifact 根目录

在编写任何制品路径之前，先解析 CE 制品根目录 <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> 作为唯一的制品位置：若不存在则创建；将每个路径组成为 <root>/<subdir>，其中子目录使用此技能自身的子目录；绝不另外读取 docs。

持久化规范

磁盘上的实验日志是事实来源。写入顺序为：测量、写入、验证，然后向用户展示。现在读取 references/persistence.md，了解检查点 CP-0 至 CP-5、状态根目录布局和恢复流程。

阶段

四个阶段按顺序执行；每个阶段都指定了必须先读取的参考文档。全新运行不得跳过任何阶段：优化越困难，在某个阶段花费的时间越长，而不是减少阶段。

恢复运行不等于全新运行。 恢复时，只需重新进入阶段 0，检测运行状态并找回日志中缺失的任何 result.yaml 标记。然后从日志记录的阶段继续，并跳过已有完成凭据的工作。检查点可证明生成它的工作已完成；用户决策仅在日志中有记录时有效。阶段 1 的批准记录与规范摘要及其批准的上限绑定；如果该记录不存在或不再匹配，则再次展示该批准环节。

阶段 0：设置。 输入为目标或规范 YAML 路径，由用户或调用技能提供。读取 references/spec.md：如果用户和调用方都未提供输入，该文档会要求提供输入，然后加载或构建要保存的规范（CP-0）。读取 references/measurement.md，了解阶段 0 的其余步骤和阶段 1。

阶段 1：测量脚手架。 构建或验证测试框架，写入基线（CP-1），探测并行度，检查工作树预算。两个关卡会阻止运行继续：

• 干净工作树关卡。 只要 scope.mutable 或 scope.immutable 中的任何文件存在未提交更改，就不得继续。参考文档定义了检查方式以及需要询问的内容。
• 用户批准关卡。 展示阶段 1 的准备结果，并提供继续、修复问题和调整规范等选项；参考文档列出了应包含的内容。说明哪些支出设有上限，哪些没有上限。在用户明确批准之前，不得进入阶段 2。 随后记录批准，并从磁盘重新读取规范和基线。

阶段 2：生成假设。 分析当前方案，为假设排序，并记录待办清单（CP-2）。如果更低成本的定位测量会改变保留或跳过的决定，则不得启动实现实验。读取 references/loop.md，了解本阶段和阶段 3。一个关卡：必须对所有假设中的每项新依赖进行依赖预批准，并一次性列出全部依赖。

阶段 3：优化循环。 遵循 references/loop.md 中的单轮协议，包括逐结果持久化和批次检查点。只要满足以下八项标准中的任意一项，就立即停止：所有声明的必需目标均已达成、达到最大迭代次数、达到最长有效时长、达到墙上时钟截止时间、达到支出上限、进入平台期、用户中断，或没有可运行的假设。references/loop.md 对每项标准都有明确说明。否则开始下一轮。

阶段 4：收尾。 读取 references/wrap-up.md，了解摘要以及完成后的可选操作。CP-5 表示日志已最终定稿。只有在用户选择了不会返回阶段 3 的选项后，才能写入该检查点。 有两个选项会返回阶段 3：继续，以及批准一项延后处理的依赖。