ECC /project-init 实战指南：基于栈检测的 DRY-RUN 安全接入规划

导读

本文讲解 ECC（The agent harness performance optimization system）中的 /project-init 命令：它扫描当前项目根目录的包管理器、语言清单与框架配置文件，自动检测技术栈，并借助仓库内的安装清单（manifest）与栈映射表，生成一份默认只读、需显式批准后才落盘的 ECC 接入计划。读完本文，你将掌握 /project-init 的全部参数、安全规则、六步规划流程、输出契约，以及底层 install-plan.js / install-apply.js 的实现原理，从而为任意新项目安全、可审计地完成 ECC 初始化。

---

一、/project-init 是什么

/project-init 是 ECC 提供的项目接入入口命令，其定位是“为当前项目创建一份安全、可评审的 ECC 接入（onboarding）计划”。它的两个核心设计原则是：

1. 默认 dry-run（试运行）：命令启动时不写入任何文件，只有用户明确批准具体计划后才执行落盘。
2. 可审计、可回放：计划中记录每一步将发生什么变化、涉及哪些目标路径，方便在应用前评审。

从源码契约看，该命令被 agent.yaml 与 COMMAND-REGISTRY.json 注册，属于 ECC 命令体系的一部分；其英文规范文档位于 commands/project-init.md，日文版即本文依据的 docs/ja-JP/commands/project-init.md。

二、命令用法与参数速览

/project-init 支持以下调用形式（来自文档“使い方”一节）：

/project-init
/project-init --dry-run
/project-init --target claude
/project-init --target cursor
/project-init --skills continuous-learning-v2,security-review
/project-init --config ecc-install.json

各参数含义如下：

参数	作用	说明
（无参数）	全默认 dry-run 规划	默认目标 harness 为 claude，栈检测后给出最小可用计划
--dry-run	强制试运行	只生成计划与预览，不写任何文件
--target <name>	指定目标 harness	可选 claude、cursor、codex、gemini、opencode、codebuddy、joycode、qwen；不指定时默认 claude
--skills <id,id,...>	指定要接入的技能	例如 continuous-learning-v2,security-review，可同时传多个，逗号分隔
--config <path>	从安装意图文件生成计划	指向项目的 ecc-install.json，由它决定 profile/modules 选择

说明：--target 的可选值集合与安装器运行时的目标枚举一致。在 scripts/install-apply.js 的帮助文本中可以看到完整的目标清单，除文档列举的七个外，还包括 claude-project、antigravity、zed、hermes、kimi、openclaw、adal 等（详见下文“目标 harness 与安装目标”）。

三、安全规则：把“先看后动”落实到命令设计

/project-init 的核心价值在于其安全约束。文档明确列出五条安全规则，它们是使用该命令时必须遵守的行为契约：

1. 默认 dry-run。在用户批准具体计划之前，不得修改 CLAUDE.md、配置文件、规则、技能或安装状态。
2. 保留既有项目指南。如果项目中已存在 CLAUDE.md、.claude/settings.local.json、.cursor/、.codex/、.gemini/、.opencode/、.codebuddy/、.joycode/ 或 .qwen/，必须先检查其内容，并提出合并/追加计划，而不是直接覆盖。
3. 必须使用 ECC 的安装器与清单工具。禁止手工复制文件，或 clone 任意远程仓库作为安装捷径。
4. 权限保持最小化。生成的配置要与检测到的构建/测试/Lint 工具相匹配，避免授予宽泛的 shell 访问权限。
5. 应用前必须精确报告将改变什么。

这五条规则与底层的设计是自洽的：install-apply.js 提供 --dry-run 模式（previewInstallPlan），在拷贝任何文件之前先输出完整的操作清单与警告；而 schemas/ecc-install-config.schema.json 中 additionalProperties: false、严格枚举 target 的做法，也从配置层面限制了“意外的目标或属性”，降低误写风险。

四、检测输入：项目栈信号的来源

/project-init 读取当前项目根目录，从以下四类文件中检测栈信号：

• 包管理器文件：package.json、package-lock.json、pnpm-lock.yaml、yarn.lock、bun.lockb
• 语言清单：pyproject.toml、requirements.txt、go.mod、Cargo.toml、pom.xml、build.gradle、build.gradle.kts
• 框架文件：next.config.*、vite.config.*、tailwind.config.*、Dockerfile、docker-compose.yml
• ECC 配置：ecc-install.json
• 可选栈映射：ECC 仓库内的 config/project-stack-mappings.json

当 ECC checkout 可用时，/project-init 使用 config/project-stack-mappings.json 作为“栈 → 规则/技能”的引用依据；如果该文件不可用，则回退到已安装的 ECC 清单与用户的显式选择。

4.1 栈映射表的结构

config/project-stack-mappings.json 是一个 version: 1 的映射清单，核心结构为 stacks 数组，每个栈包含五个维度：

{
  "id": "python",
  "name": "Python",
  "indicators": [
    { "file": "pyproject.toml" },
    { "file": "requirements.txt" }
  ],
  "rules": ["common", "python"],
  "skills": ["python-patterns", "python-testing", "tdd-workflow", "verification-loop"],
  "commands": {
    "build": ["python -m build", "pip install -e ."],
    "test": ["pytest", "python -m pytest"],
    "lint": ["ruff check .", "flake8", "mypy ."],
    "format": ["ruff format .", "black ."]
  },
  "permissions": {
    "allow": ["python *", "pip install *", "pytest *", "ruff *", "black *", "mypy *", "flake8 *"],
    "deny": ["pip install --user *"]
  }
}

字段语义：

• indicators：触发该栈的文件信号，部分条目支持 contains 关键字做内容匹配（如 package.json 中是否包含 "react":），实现“文件存在 + 内容命中”双重判定；
• rules：接入该栈时挂载的规则目录（对应 rules/ 下的语言子目录）；
• skills：推荐的技能集，例如 Python 栈会同时推荐 python-patterns、python-testing、tdd-workflow、verification-loop；
• commands：构建、测试、Lint、格式化（部分栈含 dev）的候选命令，供生成 CLAUDE.md 起始模板使用；
• permissions：为该栈生成的权限白名单与黑名单，用于落实“权限保持最小化”的安全规则——例如 Python 栈 deny 了 pip install --user *，而 JavaScript/TypeScript 栈 deny 了 npm publish，Go 栈则只 allow 明确的 go build/go test/go mod 等命令。

当前映射表内置了 20 余个栈，覆盖 typescript、javascript、react、nextjs、golang、python、rust、java、springboot、kotlin、swift、dart-flutter、php-laravel、ruby、csharp-dotnet、cpp、perl、django、android、docker 等主流技术栈，基本可以覆盖绝大多数 Web、移动端、后端与容器化项目。

五、规划流程：从检测到批准的六步

文档给出的规划流程如下：

1. 识别目标 harness：除非用户明确要求 cursor、codex、gemini、opencode、codebuddy、joycode 或 qwen，否则默认 claude。
2. 从项目文件检测栈，并展示每个匹配项的证据（命中了哪个文件、哪条 indicators）。
3. 解析最小可用的 ECC 计划，按优先级：
   • 项目有 ecc-install.json：执行

     node scripts/install-plan.js --config ecc-install.json --json
     

   • 用户指定了 profile：执行

     node scripts/install-plan.js --profile <profile> --target <target> --json
     

   • 用户指定了技能：执行

     node scripts/install-plan.js --skills <skill-ids> --target <target> --json
     

   • 仅检测到语言栈：使用对应语言名的 legacy 语言安装 dry-run。
4. 写入前先执行 dry-run 应用命令：

   node scripts/install-apply.js --target <target> --dry-run --json <language-or-profile-args>
   

5. 汇总：检测到的栈、选中的模块/组件/技能、目标路径、被跳过的未支持模块、将被更改的文件。
6. 批准后才执行非 dry-run 命令。

5.1 计划解析的源码实现

规划的第 3 步对应 scripts/install-plan.js，其参数解析逻辑（parseArgs）支持 --list-profiles、--list-modules、--list-components、--family、--profile、--modules、--skills（含 skill: 前缀归一化）、--with / --without、--config、--target、--json 等选项。它本身“只读不改”——文件头注释即声明：“Inspect selective-install profiles and module plans without mutating targets”。

其核心调用链为：

parseArgs(process.argv)
  → loadInstallConfig(configPath)          // 从 ecc-install.json 读取安装意图
  → normalizeInstallRequest({...})          // 归一化 profile/modules/include/exclude/target
  → resolveInstallPlan({...})               // 基于 manifest 解析最终计划
  → 输出 JSON 或人类可读计划

当未传任何参数且当前目录存在默认的 ecc-install.json 时，install-plan.js 会自动加载它（findDefaultInstallConfigPath），这也解释了 /project-init 为什么能“零参数”工作。

5.2 dry-run 与 apply 的分离

规划的第 4 步与第 6 步分别对应 install-apply.js 的 --dry-run 与正式执行两种模式：

• --dry-run 时调用 previewInstallPlan(rawPlan)，输出“Dry-run install plan”，包含 Mode、Target、Adapter、Install root、Install-state、Selected/Skipped/Excluded modules、Warnings 以及完整的 Planned file operations（源相对路径 → 目标绝对路径）；
• 正式执行时调用 applyInstallPlan(rawPlan)，并在落盘后通过 projectCanonicalInstallState 对安装状态做健康投影（health projection），把警告合并进结果输出，同时将 install-state 写入安装状态文件。

这意味着 /project-init 生成的计划与安装器实际执行的逻辑共用同一套计划对象（createInstallPlanFromRequest），因此“批准前预览”与“批准后执行”在文件操作层面保持严格一致，不存在预览与实装漂移的问题。

5.3 安装意图文件 ecc-install.json

/project-init --config ecc-install.json 依赖项目的安装意图文件，其结构由 schemas/ecc-install-config.schema.json 约束。一个典型的 ecc-install.json 形如：

{
  "$schema": "https://example.com/ecc-install-config.schema.json",
  "version": 1,
  "target": "claude",
  "profile": "developer",
  "modules": ["framework-language", "database"],
  "include": ["lang:python", "framework:react"],
  "exclude": ["capability:media-generation"],
  "options": {}
}

关键约束：

• version 必须为整数 1；
• target 是严格枚举，与安装器支持的目标一致；
• include / exclude 条目必须匹配 ^(baseline|lang|framework|capability):[a-z0-9-]+$ 模式，即按“类别:标识”的冒号语法书写；
• 未知属性会被 schema 直接拒绝（additionalProperties: false），从源头防止拼写错误导致的意外行为。

六、输出契约：返回六类信息

/project-init 无论 dry-run 还是正式规划，都必须向用户返回以下六类信息（文档“出力契約”一节）：

1. 检测到的栈及其证据（命中了哪些文件/内容）
2. 建议的目标 harness
3. 实际使用的 dry-run 命令原文
4. 批准后将要执行的精确 apply 命令原文
5. 将被创建或修改的文件/目录清单
6. 关于既有文件、宽泛权限、缺失脚本、未支持目标的警告

其中第 5、6 项与 install-apply.js 的输出结构一一对应：plan.operations 列出 sourceRelativePath → destinationPath 的每一个文件操作，plan.warnings 集中列出所有警告，plan.skippedOperations 记录因目标不匹配等原因被跳过的操作。因此 /project-init 的产出既适合人类评审，也能在 --json 模式下被脚本消费。

七、CLAUDE.md 起始模板的生成规则

当用户要求生成 CLAUDE.md 起始模板时，文档要求与安装器计划分开生成，并且保持最小化。模板只包含（在检测到的情况下）：

• 构建命令（build）
• 测试命令（test）
• Lint / 类型检查命令（lint/typecheck）
• 开发服务器命令（dev server）
• 来自既有 package scripts 或 manifest 的仓库专属备注

这些命令的来源正是栈映射表中每个栈的 commands 字段（见 4.1 节），例如 Next.js 栈的 dev 命令为 ["npm run dev", "npx next dev"]，Go 栈的 test 为 ["go test ./..."]。因此生成出的 CLAUDE.md 是“项目真实可用命令的最小集合”，而不是大而全的模板。

同时有一条硬性规则：不得在未展示 diff 并获得批准的情况下替换既有的 CLAUDE.md——这与安全规则第 2 条（保留既有项目指南、合并而非覆盖）保持了一致。

八、与周边命令和工具的关系

/project-init 处于 ECC 接入流程的前置位置，与其协作的组件包括：

组件	路径	职责
栈映射表	config/project-stack-mappings.json	提供栈 → 规则/技能/命令/权限的映射提示
计划解析器	scripts/install-plan.js	确定性计划解析，只读不改
安装执行器	scripts/install-apply.js	dry-run 预览与正式应用操作
安装意图 schema	schemas/ecc-install-config.schema.json	约束 ecc-install.json 的字段与枚举
安装 profile	manifests/install-profiles.json	预置 minimal/core/developer/security/research/full 等模块组合
交互式发现命令	/ecc-guide	安装前的交互式功能发现（文档见 commands/ecc-guide.md）

8.1 目标 harness 与安装目标

/project-init 的 --target 选择会直接影响计划解析结果。底层 install-apply.js 支持更完整的目标枚举，包括 claude（默认，写入 ~/.claude/，规则管理在 rules/ecc、技能平铺在 skills/）、claude-project（写入项目内 ./.claude/）、cursor（写入 ./.cursor/）、antigravity（写入 ./.agents/）、codex（写入 ~/.codex/）、gemini（写入 ./.gemini/）、opencode（写入 OPENCODE_CONFIG_DIR 或 ~/.config/opencode/）、codebuddy（./.codebuddy/）、joycode（./.joycode/）、qwen（~/.qwen/）以及 zed、hermes、kimi、openclaw、adal 等。不同目标的落盘路径差异是 /project-init 汇总“目标路径”时必须精确列出的内容。

8.2 与 profile 的组合

当检测到栈但用户希望按预置组合接入时，/project-init 可委托 install-plan.js --profile <name>。例如 manifests/install-profiles.json 中的 developer profile 会安装 rules-core、agents-core、commands-core、hooks-runtime、platform-configs、workflow-quality、framework-language、database、orchestration 九个模块；security profile 则额外引入 security 模块；minimal profile 刻意不包含 hook 运行时。--skills 则按目录 ID 精确安装单个技能（如 continuous-learning-v2、security-review），并在内部归一化为 skill:<id> 组件形式。

九、实战建议

1. 新项目一律先 /project-init --dry-run：在完全不了解项目的情况下，先让命令展示检测证据与计划，再决定是否批准。
2. 优先使用 --config ecc-install.json 驱动接入：把安装意图显式化、可版本化，团队内可复用；schema 会在提交前校验字段合法性。
3. 既有项目务必走合并路径：若项目已存在 .cursor/、.codex/、CLAUDE.md 等，检查 /project-init 给出的 merge/append 计划与 diff，再行批准。
4. 善用 --skills 做增量接入：只安装当前阶段需要的技能（如 security-review），保持接入面最小，后续再逐步扩展。
5. 关注输出契约中的警告项：plan.warnings 中的“缺失脚本”“未支持目标”等提示往往反映了项目健康度问题，应在接入前解决。

十、小结

/project-init 是 ECC 接入流程中“先检测、先预览、后落盘”的安全入口：它以项目真实文件为证据源，以 config/project-stack-mappings.json 为映射基准，以 install-plan.js 做确定性计划解析、install-apply.js 做 dry-run 预览与正式应用，最终产出一份人类可评审、机器可消费的六项输出契约。理解它的安全规则与规划流程，就能在任何新项目或存量项目中，把 ECC 接入变成一次低风险、可回放、权限克制的受控操作。