AI Skills
ce-setup

ce-setup

热门

检查 Compound Engineering 环境健康度与仓库本地配置。

2.4万Star
1885Fork
更新于 2026/7/31
获取 Skill源代码

相关 Skills

blucli38万recsys-pipeline-architect24万academy-guide17万
SKILL.md
只读
名称
ce-setup
描述

检查 Compound Engineering 环境健康度与仓库本地配置。

Compound Engineering 配置与部署检查

交互方式

针对以下每个问题，请优先使用当前平台提供的阻塞式提问工具向用户发起询问：Claude Code 使用 AskUserQuestion（若未加载其 Schema，需先调用 ToolSearch 并设置 select:AskUserQuestion）；Codex 使用 request_user_input；Antigravity CLI（agy）使用 ask_question；Pi 使用 ask_user（需安装 pi-ask-user 扩展）。仅当当前环境不存在任何阻塞式工具或工具调用报错时，才退回到在对话框中输出带编号的列表。切勿静默跳过或擅自进行自动配置。

ce-setup 是一款轻量级的环境健康检查与仓库本地配置辅助工具。它不会一键批量安装所有可选依赖。缺失的工具会被标记为可选功能并输出报告，方便用户根据实际使用的工作流按需安装。

产物根目录解析（Artifact Root Resolution）

任何需要读写产物目录（如 solutions、plans、ideation 以及其它由 CE 管理的目录树）的 Compound Engineering Skill，都会按照以下规则来确定其根目录路径。ce-setup 包含了此规则的标准规范，并会打印解析后的根目录路径，以便开发者在运行其它 Skill 之前确认产物的实际落地位置。

<!-- ce-docs-root:start -->
在拼接任何产物路径之前，必须先解析出 CE 产物的根目录 <root>。

  • 读取：优先读取 <repo-root>/.compound-engineering/config.local.yaml 中的 docs_root 字段，其次读取 config.yaml；以首个非空配置值为准（其中 <repo-root> 通过 git rev-parse --show-toplevel 获取）。若均未配置，则 <root> 默认维持为 docs。
  • 校验：若配置了该值，必须为相对于仓库根目录的相对路径，且通过软链接解析后的真实路径必须保持在仓库内部，不能是仓库根目录本身，也不能位于 .git/ 之下。如果不满足此条件，必须立即抛错终止，并明确指出 docs_root 及其无效值——绝不能隐式退回到默认的 docs。
  • 使用：将 <root> 作为唯一的产物存放位置：若目录不存在则自动创建，后续每个 Skill 的路径均按 <root>/<subdir>（拼上对应 Skill 的子目录）进行组合，且不再去读取原有的 docs 目录。
    <!-- ce-docs-root:end -->

第一阶段：诊断（Diagnose）

步骤 1：获取插件版本号

若当前平台暴露了插件元数据或 Manifest，可以通过读取它们来检测已安装的 compound-engineering 插件版本。如果无法获取版本号，跳过此步骤即可。

如果成功获取到版本号，在后续调用检查脚本时通过 --version 参数传入；否则忽略该参数。

步骤 2：执行健康检查

在运行脚本前，先提示输出：

Compound Engineering -- checking your environment...

运行随 Skill 内置的检查脚本。将 SKILL_DIR 设为加载此 ce-setup SKILL.md 文件所在的绝对路径——因为 Bash 工具的当前工作目录（CWD）是用户的项目目录而不是 Skill 所在目录，直接使用相对路径 scripts/ 会导致找不到文件：

SKILL_DIR="<absolute path of the directory containing this SKILL.md>";
if [ -f "$SKILL_DIR/scripts/check-health" ]; then bash "$SKILL_DIR/scripts/check-health" --version VERSION; else echo "Bundled health script not found at $SKILL_DIR/scripts/check-health; run the inline checks from ce-setup instead."; fi

如果步骤 1 未能获取到版本号，使用去掉 --version VERSION 的同等命令。

若检测脚本不可用，请按顺序执行等价的内联检查：

  1. 使用 command -v 检查可选工具：agent-browser、gh、jq、ast-grep、ffmpeg。
  2. 若当前位于 Git 仓库内，使用 git rev-parse --show-toplevel 获取仓库根目录路径。
  3. 检查仓库根目录下是否存在已废弃的 compound-engineering.local.md 文件。
  4. 检查是否存在 .compound-engineering/config.local.yaml；若存在，验证 git check-ignore -q .compound-engineering/config.local.yaml 是否能执行成功（即确认已被 Git 忽略）。
  5. 若模板文件可读，将 .compound-engineering/config.local.example.yaml 与 references/config-template.yaml 进行比对；若无法读取模板，则提示用户需手动更新示例配置。

向用户展示诊断报告。缺少可选工具不属于配置失败。健康报告中包含了解析后的产物根目录路径以及提供该配置的具体层级（详见上方“产物根目录解析”）；请务必打印该行信息，以便开发者明确 CE 产物的最终写入路径。

步骤 3：判断是否需要修复

用户可执行命令的渲染规范：在配置总结中，默认使用 /ce-setup；仅当当前宿主平台为 Codex 或明确文档说明使用 $ 前缀来调用 Skill 时，才使用 $ce-setup。仅将命令本身渲染为行内代码，且只输出一种格式。

仅当存在以下一个或多个仓库本地的项目问题时，才进入“第二阶段”：

  • 仓库根目录残留已废弃的 compound-engineering.local.md
  • 存在 .compound-engineering/config.local.yaml 但未被 Git 安全忽略
  • .compound-engineering/config.local.example.yaml 缺失或已过期
  • 健康检查报告提示 ce-work Skill 的执行引擎不可用或无效、检测到已废弃的标量路由键，或报告休眠状态的 work_engine_preferences 格式错误
  • 健康检查报告提示 docs_root 无效（如 Invalid docs_root ...）——在此问题修复前，CE 产物将无法正常写入

若不存在任何项目问题，输出：

✅ Compound Engineering setup complete

Project config: ✅
Optional capabilities: see diagnostic report above

Run `<rendered invocation>` anytime to re-check.

若缺少可选工具，切勿提供批量一键安装选项。诊断结果中已打印相关的安装命令或项目链接。直接提示用户：“请仅针对你实际用到的工作流安装对应的可选工具。”

第二阶段：修复仓库本地问题（Fix Repo-Local Issues）

获取仓库根目录（通过 git rev-parse --show-toplevel）。以下涉及的所有路径均相对于仓库根目录，而非当前工作目录。

步骤 4：清理已废弃的本地配置

如果仓库根目录存在 compound-engineering.local.md，向用户说明该文件已被废弃，因为评审 Agent 的选择现已自动化，其余本机专属配置已迁移至 .compound-engineering/config.local.yaml。

询问用户是否立即删除。仅在获得用户确认后才执行删除。

步骤 5：刷新示例配置文件

将 references/config-template.yaml 复制到 <repo-root>/.compound-engineering/config.local.example.yaml（若目录不存在则自动创建）。该文件需要提交到仓库中，应当始终保持与最新可用设置同步。

若当前平台无法定位内置的模板文件，请打印寻找失败的源模板路径，并告知用户无法自动刷新示例配置文件。

步骤 6：按需创建本地配置文件

若 .compound-engineering/config.local.yaml 不存在，向用户提问：

Set up a local config file for this project?
This saves optional Compound Engineering preferences such as output formats and product pulse settings.
Everything starts commented out -- you only enable what you need.

1. Yes, create it
2. No thanks

如果用户同意，将 references/config-template.yaml 复制到 <repo-root>/.compound-engineering/config.local.yaml。

步骤 6a：修复无效的 CE Work 偏好设置

当健康检查报告指出 CE Work 执行引擎不可用或无效、检测到已废弃的标量路由键、或报告休眠状态的 work_engine_preferences 格式错误时，切勿盲目猜测用户预期的配置。向用户说明具体报错原因，根据用户指定的平台/模型顺序推导出合规且有序的 work_engine_preferences 配置块（或者在用户希望默认使用原生模式时，清除有误的休眠偏好并设置 work_engine_mode: off），同时移除所有已废弃的标量路由键，并展示完整的替换配置块预览。仅在用户确认预览后，修改与 CE Work 相关的键值，并保留所有无关的本地配置。修改完成后重新运行健康检查，必须确保健康报告显示为原生模式或符合预期的规范化有序列表后，方可完成配置。

步骤 6b：修复无效的 docs_root

当健康检查报告指出 docs_root 无效时，向用户说明诊断给出的具体原因（绝对路径、跨出仓库范围、包含 .. 路径遍历、指向仓库根目录、指向 .git/，或包含非目录组件）及其后果：由于 docs_root 校验失败时采取严格闭合策略（fail closed）、不会静默退回到 docs，因此在修复前 CE 产物将无法写入。docs_root 可能存在于已版本控制的 .compound-engineering/config.yaml 或本地的 config.local.yaml 中（遵循本地配置优先原则）。提供修复选项：可将该值修改为用户指定的有效相对路径目录，也可直接移除有问题的 docs_root 键。请向用户精准说明回退逻辑：移除该键会回退到下一层级设置的 docs_root（例如删除 config.local.yaml 中的错误配置后，若版本控制的 config.yaml 中仍有配置，则以 config.yaml 为准）；只有当所有层级均未设置该键时，才会最终退回默认的 docs——因此，如果两个配置文件中均存在错误配置，必须对每个贡献了错误值的配置文件分别进行修复或清理。仅在用户确认修改方案后编辑对应的键，并保留其它无关配置。修改完成后重新运行健康检查，必须确保健康报告能正常输出解析后的产物根目录路径，方可完成配置。

步骤 7：确保本地配置已被 Git 忽略

若存在 .compound-engineering/config.local.yaml 且未被 .gitignore 覆盖，提示用户添加：

.compound-engineering/*.local.yaml

仅在获得用户同意后，将该条目追加至仓库根目录下的 .gitignore 中。切勿覆盖其它无关的 .gitignore 内容。

第三阶段：总结（Summary）

展示简要的配置总结：

✅ Compound Engineering setup complete

Fixed:     <repo-local fixes applied, or none>
Skipped:   <repo-local fixes declined, or none>
Optional:  <missing optional tools, or all available>

Run `<rendered invocation>` anytime to re-check.