ce-explain

解释如何以及为何

撰写一份说明，回答范围明确的问题，并让使用者对预期用途有足够的理解。主题和目的来自请求及可用上下文，无论这些信息由人还是其他工作流提供。项目行为须以源代码证据为依据；区分文档中说明的理由、推断和未知事项。

**完成标准：**提供附有支持证据并列出重要未解问题的说明，或指出具体阻碍。如果请求提供某项产物，则交付该产物并说明其位置。发布是单独的操作，不是完成说明的前提。

使用者与交互

根据目标读者和用途调整深度与呈现方式。使用者可能需要可直接应用的答案；调用方 Agent 可能需要一份供他人学习的材料。不要仅凭调用方身份推断输出形式。参与正在进行的工作流时，应交付所请求的结果，并由其所有者（即调用方工作流）负责后续工作。返回时不要添加目标位置选项或后续协助提议。

先查明可获取的事实，再提问。只有当缺失信息会实质性改变答案，且无法从请求或证据中查明时，才提出问题。如果无法交互，应说明尚未解决的问题及其影响，而不是等待或编造答案。结果可以说明已核实的行为，同时报告其历史原因未知。

在依据证据、提出第一个阻塞性问题或派遣子 Agent 之前，请先阅读 references/orchestration.md。 该文件定义了证据收集、工具使用、模型层级及其备用方案。

产物根目录

只有将说明文档归档到仓库时，才将其放在 <root>/explainers/ 下；可以在 <root>/solutions/ 下查阅经验总结。仅在编写此类路径时解析 <root>；仅用于临时处理或解释外部概念的运行不会编写此类路径。将解析出的路径传递给任何子 Agent，而非配置文件。

在编写任何产物路径之前，先解析 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>，其中 <subdir> 为此技能专用的子目录；绝不要同时读取 docs。

执行流程

阶段 1：明确问题和用途

现在阅读 references/intake.md。该文件定义了如何确定主题和时间范围、输入标记，以及如何选择交付形式。只解释请求的主题。若直接调用时没有可确定的主题，应按上述交互规则请求澄清，而不是臆造主题或默认产物。

阶段 2：梳理依据

按照 references/orchestration.md 执行限定范围的证据核查。现有证据充分且仍有效时，直接使用；对于缺少依据、存在争议或受来源变更影响的说法，进行核查。

仅当需要保存产物或证据档案时，才创建运行目录。写入任一内容前，先使用以下代码块；它会拒绝符号链接或归其他用户所有的临时目录根路径：

SCRATCH_ROOT="/tmp/compound-engineering-$(id -u)";
[ ! -L "$SCRATCH_ROOT" ] && (umask 077; mkdir -p "$SCRATCH_ROOT") 2>/dev/null && [ ! -L "$SCRATCH_ROOT" ] && [ -O "$SCRATCH_ROOT" ] && [ -w "$SCRATCH_ROOT" ] || SCRATCH_ROOT="${TMPDIR:-/tmp}/compound-engineering-$(id -u)";
if [ -L "$SCRATCH_ROOT" ]; then echo "unsafe scratch root symlink: $SCRATCH_ROOT" >&2; exit 1; fi;
(umask 077; mkdir -p "$SCRATCH_ROOT") || exit 1;
if [ -L "$SCRATCH_ROOT" ] || [ ! -O "$SCRATCH_ROOT" ]; then echo "scratch root is not owned by the current user: $SCRATCH_ROOT" >&2; exit 1; fi;
chmod 700 "$SCRATCH_ROOT" || exit 1;
RUN_DIR="$SCRATCH_ROOT/ce-explain/$(date +%Y%m%d)-$(openssl rand -hex 3)";
(umask 077; mkdir -p "$RUN_DIR") || exit 1; chmod 700 "$RUN_DIR" || exit 1;
echo "$RUN_DIR";

如果行为追踪跨越多个所有权边界，则应编写侦察档案。派发这些侦察任务前，先创建此运行目录。

• 差异模式。 范围为空或缺少主题时，不要默默改为解释其他内容。应先报告这一情况，再解释相邻内容。仅当请求允许或用户同意时，才使用替代项；如有替代，须在结果和产物的 Subject 中注明。否则，将尚未解决的范围问题交还调用方。
• 回顾模式。 不要在主对话中预扫描、计数或描述时间窗口。应直接派发通用子 Agent，在提取层级开始工作；以 references/agents/work-recap-scout.md 为种子，并传入已解析的时间窗口、仓库根目录和 $RUN_DIR。**时间窗口为空：**报告没有活动记录，然后结束，不生成说明性产物。**当运行环境未提供子 Agent 原语时，**在当前流程中内联运行侦察任务，使用其提示词指定的来源和预算，仍然写入 recap-evidence.md，并在任务完成前不对时间窗口形成判断。如果派发失败，按照 references/orchestration.md 中的回退规则处理。

阶段 3：撰写说明

依据证据回答问题，保留重要限制条件和不确定性。交付前，逐一对照来源核查每项事实陈述。函数调用本身并不能证明其未检查过的实现具有什么保证。删除缺乏依据的说法，或在说法出现之处（包括图表和练习答案）注明其不确定性。选择有助于理解的文字、代码、表格或视觉材料；不要求采用特定编排方式。说明多人完成的工作时，准确标明贡献者。若证据多于请求范围或篇幅所能容纳的内容，须披露筛选情况；绝不可默默将部分说明呈现为完整说明。

对于答案或将由其他工作流纳入的材料，直接返回相应内容。每段内容都必须包含准确使用所需的限定条件，无需另附说明。当其他工作流将使用该答案时，返回内容还须包括证据、仍然适用的限制条件和未解答的问题。除非预期用途需要，否则不要创建独立产物。

对于独立产物，在撰写时阅读 references/explainer-html.md 或 references/explainer-markdown.md，以了解所选格式的兼容性和元数据要求。对于教学产物，还须阅读 references/check-in.md。运行流程不得因检查环节而阻塞；所有练习均为产物中的静态内容。写入 $RUN_DIR/explainer.html 或 explainer.md，然后提供内联摘要和文件路径。

阶段 4：交付

交付答案或本地产物，即完成说明工作。不要要求用户选择目的地，也不要凭空安排后续工作。如果用户指定了目的地，执行前阅读 references/destinations.md；其中定义了各个目的地及发布所需的同意。若调用工作流负责管理外围文档，应将内容返回给该工作流，而不是自行放置或发布。

发布到 ht-ml.app 绝不可在无交互情况下进行，也不得自行推断用户同意。提及该平台属于选择目的地，不代表用户在收到公开发布警告后已确认。如果无法取得确认，不要发布；保留规范版 HTML，并报告其本地路径 $RUN_DIR/explainer.html。

边界

• 使用 ce-pov 判断是否应采用或更改某种做法。解释过去的选择，并不代表如今仍然认可它。
• 使用 ce-compound 记录持久有效的项目经验。撰写说明并不意味着获准维护仓库记忆。
• 按照提供的内容解释想法；生成替代方案和界定实现范围分别属于 ce-ideate、ce-brainstorm 和 ce-plan。
• 需要诊断或修复的故障报告属于 ce-debug；对当前行为的事实性说明则仍属于此处。