企业官网建设流程全解析

在 .compound-engineering/config.yaml 中配置 docs_root 以重定位所有 CE 产物目录

【免费下载链接】compound-engineering-pluginOfficial Compound Engineering plugin for Claude Code, Codex, Cursor, and more项目地址: https://gitcode.com/GitHub_Trending/ev/compound-engineering-plugin

compound-engineering-plugin（Compound Engineering 插件）的 CE 技能默认把产物写进docs/：docs/plans/、docs/solutions/等目录都固定在那里。如果你的仓库里docs/已经被别的内容占用（例如 Obsidian vault、独立文档站点），CE 产物会和这些内容混在一起，CE 的研究子代理甚至会把外部文档当成自己的学习记录来读。docs_root配置项可以解决这个冲突：它在.compound-engineering/config.yaml中把全部 CE 产物目录整体搬到一个你指定的仓库相对目录，且搬过去之后docs/就不再是 CE 的读写位置。该配置适用于所有打开同一 checkout 的支持 harness（Claude Code、Codex、Cursor 等）。前提是插件已装好、当前在 git 仓库内。

docs_root 移动了哪些目录

按 配置参考 的说明：

• 默认情况下，每个 CE 写入的产物文件夹都在docs/下：docs/plans/、docs/solutions/等。
• 设置docs_root后，这些子目录改挂到你指定的根下，子目录名固定不变。配置模板列出的子目录包括：solutions、plans、ideation、explainers、pulse-reports、dogfood-reports、feedback-sweep、personas（见 config-template.yaml 的注释）。即配置根为X时得到X/solutions、X/plans等。
• 未设置时行为与默认完全一致（逐字节相同）。
• 已配置的根是 CE 唯一的读写位置：CE 不会对docs/做任何发现性读取，也不会静默回退到docs/。
• docs_root只从.compound-engineering/config.yaml读取；写在config.local.yaml里会被忽略。

还有一个行为上的关键点：docs_root是 fail closed（失败即停）的。其他配置项遇到无效值会继续向下取默认值，而无效的docs_root会让技能报错停下，因为静默回退到docs/等于把产物写进你刚配置掉的位置。

第一步：创建 .compound-engineering/config.yaml

在会话中运行：

/ce-setup

在 oh-my-pi 上调用方式是/skill:ce-setup；在 Codex 上使用美元前缀的技能时是$ce-setup。ce-setup只在你显式调用时运行。它会做几件与本文相关的事（见 ce-setup 指南）：

• 在 git 仓库内，始终用内置模板刷新已提交的.compound-engineering/config.example.yaml。
• 当.compound-engineering/config.yaml缺失时，询问你是否创建它。模板里所有键默认都是注释状态，只启用你需要的。
• 从不覆盖已有的config.yaml或config.local.yaml，也从不创建config.local.yaml。

如果你更想手动维护，config-template.yaml 的注释写明可以直接复制为项目根下的.compound-engineering/config.yaml（团队默认值文件）。两种途径得到的内容一致，选一种即可。两个文件里都不要放凭据、CLI 命令或 harness 参数。

第二步：设置 docs_root

在.compound-engineering/config.yaml中把模板里的注释行解开并改成你要的目录。模板中自带的示例是（原文来自 config-template.yaml）：

docs_root: .compound-engineering/artifacts # repo-relative dir (default: docs)

.compound-engineering/artifacts只是模板给出的例子，替换成你自己的仓库相对目录。该值必须通过以下校验（这是文档明确列出的规则）：

• 必须是仓库相对路径，不能是绝对路径；
• 不能用../或符号链接解析到仓库外（校验针对符号链接解析后的真实路径）；
• 不能是仓库根目录本身；
• 不能在.git/下；
• 指向的目录如果尚不存在，会在第一次写入时自动创建。拼错但结构合法的值不会报错，只会创建一个意料之外的目录，所以配置后务必核对。

为什么只允许写在config.yaml：已提交的config.yaml是同一项目所有 worktree 共享的，这样每个 clone 和 worktree 共用一棵产物树。写在本地文件里的docs_root会被直接忽略（本地文件如果还残留该键，/ce-setup会指出并提议帮你挪到config.yaml）。

第三步：用 /ce-setup 核对解析结果

再次运行/ce-setup。健康报告包含解析后的产物根以及是哪个配置层提供的它。报告中的相关行是固定措辞，尖括号处为运行时填入的值（来源是 check-health 健康检查脚本）：

Artifact root: docs/ (default — docs_root not set)

配置生效时：

Artifact root: <你配置的值>/ (from <来源层>)

配置无效时：

Invalid docs_root '<值>' in <来源层>: <拒绝原因> CE artifacts will not be written until docs_root is corrected or removed.

如果config.local.yaml里还有一个被忽略的docs_root，报告会提示：

Local docs_root '<值>' is ignored; set docs_root only in config.yaml

判断标准：报告出现Artifact root: <值>/ (from ...)且值就是你配置的值，说明配置已生效；此后再由任何 CE 技能写入产物时，目录会在首次写入时创建，产物落在<根>/<子目录>下。

文档报 docs_root 无效时如何修复

无效值的直接后果是 CE 产物在修好之前不会写入（fail closed 行为）。健康检查给出的拒绝原因包括：绝对路径、..路径穿越、解析到仓库外、解析到仓库根本身、解析到.git/内、指向已存在的非目录，或中间路径组件不是目录。

修复路径由/ce-setup提供（对应 repo-fixes.md 的 Step 6b）：

1. 重新运行/ce-setup，它会解释健康报告给出的具体拒绝原因；
2. 它会提供两个选项：把config.yaml中的值改成你指定的合法仓库相对目录，或直接从config.yaml删除这个键。删除后回到默认根docs/；
3. 只有在你批准后才会编辑这几个键，其余配置项保持不变；
4. 修复后重跑健康检查，要求报告能给出解析后的产物根，才算完成。

边界与已知限制

• docs_root不解决产物在临时工作区的存活问题：根在仓库内，随 checkout 生灭。
• 没有迁移机制：已有的docs/下产物不会自动或半自动搬走。该功能的计划文档 明确决定不做迁移，原因是 CE 无法可靠地区分自己的文件和与它共享目录的外部文件。
• 一个根目录移动所有产物类型，没有按产物类型分别覆盖的配置；需要把solutions和plans放在不同地方的项目不受此特性服务。
• 计划文档中记录的遗留例外：riffrec 分析脚本仍写向旧的docs/brainstorms/路径，属于本次范围之外，因此"CE 不向已配置根之外写入"在该点上尚非字面成立。
• 针对当前任务的直接指令仍然优先于配置：会话中已有的会话/项目指令可以覆盖或收窄它。

下一步

插件升级后重新运行/ce-setup，它会刷新已提交的示例配置，并诊断已退役或格式错误的设置（配置参考 的 Safe maintenance 部分）。如果报告再次标记docs_root无效，按上一节的修复流程处理即可。

【免费下载链接】compound-engineering-pluginOfficial Compound Engineering plugin for Claude Code, Codex, Cursor, and more项目地址: https://gitcode.com/GitHub_Trending/ev/compound-engineering-plugin