@hunyed15/codecgc 0.2.2 → 0.2.5

package/README.md

@@ -25,25 +25,26 @@ CLI 仍然保留，用于本地调试、CI 检查和 MCP 不可用时的回退
 
 ## 安装
 
-全局安装 CLI：
+### 推荐：全局安装（用户级）
 
 ```bash
 npm install -g @hunyed15/codecgc --registry=https://registry.npmjs.org/
 ```
 
-全局安装只提供 `cgc*` 命令，不会默认写入用户级 Claude 配置。
+全局安装后，`cgc-init`、`cgc-status`、`cgc-doctor` 等命令在任何目录都可用。
 
-然后在每个目标项目根目录执行项目级安装：
+### 项目初始化
+
+在项目目录下运行：
 
 ```bash
 cd your-project
 cgc-init
-cgc-start
-cgc-status
-cgc-doctor
 ```
 
-在 Claude 中可以使用对应 slash command：
+这会初始化项目配置并注册 `/cgc` skill 到 Claude Code。
+
+在 Claude 中也可以使用：
 
 ```text
 /cgc-init
@@ -52,7 +53,28 @@ cgc-doctor
 /cgc-doctor
 ```
 
-`/cgc-init` 和 `cgc-init` 默认都是项目级安装。它们会把集成文件写入当前项目，不会写入 `~/.claude` 等全局目录。
+初始化完成后，可以直接使用：
+
+```text
+/cgc "新增一个登录页面"
+```
+
+或在命令行：
+
+```bash
+cgc "新增一个登录页面"
+```
+
+### 备选：项目级安装
+
+如果需要版本隔离（CI、Docker 等场景）：
+
+```bash
+npm install @hunyed15/codecgc
+npx cgc-init
+```
+
+**注意**：项目级安装需要通过 `npx` 调用命令。推荐使用全局安装以获得更好的用户体验。
 
 ## 安装后生成的项目文件
 
@@ -64,7 +86,7 @@ model-routing.yaml
 .claude/
   settings.local.json
   hooks/
-    route-edit.ps1
+    edit-guard.js
   commands/
     cgc*.md
 .codex/
@@ -88,7 +110,7 @@ codecgc/
 
 在 CodeCGC 源码仓库中，`.mcp.json`、`.claude/settings.local.json`、`.claude/commands/`、`.codex/`、`.gemini/`、`codecgc/START_HERE.md` 以及实时 workflow 输出目录会被忽略，因为它们是机器相关或项目安装生成的内容。
 
-源码仓库会保留可发布运行时、参考文档、命令模板、测试 fixtures，以及 `.claude/hooks/route-edit.ps1` 这个 hook 模板。
+源码仓库会保留可发布运行时、参考文档、命令模板、测试 fixtures，以及 `.claude/hooks/edit-guard.js` 这个 hook 模板。
 
 ## 角色与路由策略
 

package/bin/cgc-build.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-build";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-doctor.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-doctor";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-entry.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-entry";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-explain.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+process.env.CODECGC_BIN_NAME = "cgc-explain";
+require("./codecgc.js");

package/bin/cgc-external-audit.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-external-audit";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-external-status.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-external-status";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-fix.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-fix";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-history.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-history";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-init.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-init";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-lifecycle.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-lifecycle";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-package-audit.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-package-audit";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-plan.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-plan";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-release-readiness.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-release-readiness";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-review.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-review";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-route.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-route";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-start.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-start";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-status.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-status";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/cgc-test.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 
 process.env.CODECGC_BIN_NAME = "cgc-test";
-require("./codecgc.js");
+require("./codecgc.js");

package/bin/codecgc.js

@@ -8,7 +8,7 @@ const path = require("node:path");
 const repoRoot = path.resolve(__dirname, "..");
 const invocationCwd = process.cwd();
 const args = process.argv.slice(2);
-const invokedBinary = (process.env.CODECGC_BIN_NAME || path.basename(process.argv[1] || "cgc")).toLowerCase();
+const invokedBinary = (process.env.CODECGC_BIN_NAME || path.parse(process.argv[1] || "cgc").name).toLowerCase();
 const packageJson = JSON.parse(readFileSync(path.join(repoRoot, "package.json"), "utf8"));
 const productVersion = packageJson.version || "0.0.0";
 const DIRECT_COMMANDS = new Set([
@@ -16,6 +16,7 @@ const DIRECT_COMMANDS = new Set([
   "install",
   "status",
   "doctor",
+  "explain",
   "package-audit",
   "external-audit",
   "external-status",
@@ -45,6 +46,7 @@ const helpText = `CodeCGC 命令入口
   cgc-init [--mode local|status|doctor|start] [--workspace <dir>]
   cgc-status [--format json|summary]
   cgc-doctor [--format json|summary]
+  cgc-explain <error_code> | --list [--format json|summary]
   cgc-package-audit [--format json|summary]
   cgc-external-audit [--format json|summary] [--workspace <dir>]
   cgc-external-status [--format json|summary] [--workspace <dir>]
@@ -88,6 +90,8 @@ const helpText = `CodeCGC 命令入口
     cgc-status
   我想知道运行前置和执行器能不能真正启动
     cgc-doctor
+  我想查看某个错误代码的详细说明和修复建议
+    cgc-explain executor-crash
   我想确认发布包没有漏掉运行时文件
     cgc-package-audit
   我想确认第三方能力接入策略和本地 MCP 注册状态
@@ -110,6 +114,7 @@ const helpText = `CodeCGC 命令入口
   cgc-init        同步项目级集成面
   cgc-status         检查集成是否就绪，并给出下一步
   cgc-doctor         检查运行前置、执行器导入与项目集成状态
+  cgc-explain        查看错误代码的详细说明和修复建议
   cgc-package-audit  检查发布包是否覆盖运行时依赖
   cgc-external-audit 检查外部能力白名单、接入声明与本地 MCP 观测一致性
   cgc-external-status 查看外部能力状态面板与本地 MCP 观测结果
@@ -151,6 +156,8 @@ const helpText = `CodeCGC 命令入口
   cgc-status
   cgc-status --format summary
   cgc-doctor --format summary
+  cgc-explain executor-crash
+  cgc-explain --list
   cgc-package-audit --format summary
   cgc-external-status --format summary
   cgc-external-audit --format summary
@@ -163,6 +170,7 @@ const helpText = `CodeCGC 命令入口
 环境变量:
   CODECGC_PYTHON_COMMAND  覆盖产品壳与生成的 MCP 配置所使用的 Python 命令
   CODECGC_WORKSPACE_ROOT  当当前 shell 目录不是目标项目根目录时，显式覆盖目标工作区
+  CODECGC_ERROR_LEVEL     错误输出详细级别：summary（默认，小白可读）、detail（技术细节）、debug（完整日志）
 `;
 
 const startHelpText = `CodeCGC Start
@@ -201,7 +209,7 @@ const installHelpText = `CodeCGC 安装与自检
 
 模式:
   local
-    把项目级 .mcp.json、.claude/settings.json 与 route-edit.ps1 hook 同步到目标工作区。
+    把项目级 .mcp.json、.claude/settings.json 与 edit-guard.js hook 同步到目标工作区。
   status
     检查项目级集成是否就绪。
   doctor
@@ -270,6 +278,41 @@ const statusHelpText = `CodeCGC 安装状态
     同步或修复当前项目集成面。
   cgc-doctor
     检查运行前置、执行器导入和项目集成状态。
+  cgc-explain
+    查看错误代码的详细说明和修复建议。
+`;
+
+const explainHelpText = `CodeCGC Explain
+
+用法:
+  cgc-explain <error_code>
+  cgc-explain --list [--format <summary|json>]
+
+用途:
+  查看 CodeCGC 错误代码的详细说明、常见原因和修复建议。
+
+默认行为:
+  传入错误代码时，输出该错误的中文说明和建议操作。
+  使用 --list 时，列出所有可用的错误代码。
+
+主要参数:
+  <error_code>
+    要查询的错误代码，例如 executor-crash、scope-error、design-gap。
+  --list
+    列出所有可用的错误代码。
+  --format <summary|json>
+    summary 用于人类可读输出，json 用于程序消费。
+
+推荐用法:
+  cgc-explain executor-crash
+  cgc-explain scope-error
+  cgc-explain --list
+
+相关命令:
+  cgc-doctor
+    检查运行前置和执行器环境。
+  cgc-route
+    查看当前工作流状态和推荐命令。
 `;
 
 const doctorHelpText = `CodeCGC Doctor

package/codecgc/cgc-onboard/SKILL.md

@@ -28,7 +28,7 @@ Also inspect:
 
 - `.mcp.json`
 - `.claude/settings.json`
-- `.claude/hooks/route-edit.ps1`
+- `.claude/hooks/edit-guard.js`
 - `model-routing.yaml`
 
 ## Rules

package/codecgc/reference/execution-model.md

@@ -47,7 +47,7 @@ CodeCGC 把“工作流控制”和“代码执行”明确分层。
 - `.claude/settings.local.json`
 - `.codex/codecgcrc.json`
 - `.gemini/policies/codecgc-policy.toml`
-- `.claude/hooks/route-edit.ps1`
+- `.claude/hooks/edit-guard.js`
 
 这些文件一起负责“不能越界”。
 

package/codecgc/reference/policy-routing.md

@@ -43,8 +43,7 @@ This creates project-local `.mcp.json`, `.claude/`, `model-routing.yaml`, and th
 
 `scripts/codecgc_policy.py` evaluates the policy for every entry point that needs write ownership:
 
-- Claude hook guardrail via `.claude/hooks/route-edit.ps1` for `Edit`, `Write`, and `MultiEdit`
-- Claude shell guardrail via the same hook for `Bash` and `PowerShell`
+- Claude hook guardrail via `.claude/hooks/edit-guard.js` for `Edit`, `Write`, and `MultiEdit`
 - task payload construction via `scripts/build_codecgc_task.py`
 - build/fix/test wrappers before executor dispatch
 - status and doctor checks through `model-routing.yaml` validation

package/codecgc/reference/project-structure.md

@@ -16,7 +16,7 @@ mcp/
   geminimcp/
 codecgc/reference/
 codecgc/cgc*/
-.claude/hooks/route-edit.ps1
+.claude/hooks/edit-guard.js
 model-routing.yaml
 ```
 
@@ -43,7 +43,7 @@ codecgc/architecture/
 codecgc/docs/
 ```
 
-Keep `.claude/hooks/route-edit.ps1` in source control because it is the packaged hook template copied into target projects.
+Keep `.claude/hooks/edit-guard.js` in source control because it is the packaged hook template copied into target projects.
 
 Keep `codecgc/fixtures/`, `codecgc/reference/`, `codecgc/roadmap/`, and `codecgc/compound/` when they are used as packaged examples, release-maintenance assets, or regression fixtures.
 
@@ -57,7 +57,7 @@ model-routing.yaml
 .claude/
   settings.local.json
   hooks/
-    route-edit.ps1
+    edit-guard.js
   commands/
     cgc*.md
 .codex/

package/codecgc/reference/quickstart.md

@@ -32,7 +32,7 @@ The project install syncs:
 .mcp.json
 model-routing.yaml
 .claude/settings.local.json
-.claude/hooks/route-edit.ps1
+.claude/hooks/edit-guard.js
 .claude/commands/cgc*.md
 .codex/codecgcrc.json
 .gemini/policies/codecgc-policy.toml

package/codecgc/reference/shared-conventions.md

@@ -38,7 +38,7 @@
 这套规则通过两层落地：
 
 1. 工作流层：`cgc-build` 与 `cgc-fix`
-2. guardrail 层：`.claude/hooks/route-edit.ps1`
+2. guardrail 层：`.claude/hooks/edit-guard.js`
 
 ## 4. 当前公开命令面
 

package/codecgc/templates/project/CLAUDE.md

@@ -0,0 +1,214 @@
+<!-- codecgc:claude-md:v1 -->
+# CodeCGC Claude 默认提示词
+
+## 核心身份
+
+你是 CodeCGC 工作流中的 Claude 主控层。你的职责是把用户需求组织成可追踪、可审核、可恢复的工作流，而不是默认直接修改所有代码。
+
+默认分工：
+
+- Claude：需求澄清、规划、设计、文档、审核、验收、状态解释、失败恢复。
+- Codex：后端代码、后端测试、后端修复。
+- Gemini：前端代码、前端测试、前端修复。
+- CodeCGC：路由策略、执行审计、review 回写、工作流状态闭环。
+
+## 语言与输出
+
+- 默认用中文回复用户。
+- 回复先给结论，再给下一步。
+- 命令、路径、文件名、工具名使用反引号。
+- 不输出冗长背景；只保留完成任务需要的信息。
+- 涉及日期、版本、路径和命令时使用精确值。
+
+## 首选入口
+
+普通需求优先使用 CodeCGC 单入口：
+
+```text
+/cgc <自然语言需求>
+```
+
+MCP 可用时优先调用 CodeCGC MCP 工具：
+
+- `codecgc.entry`
+- `codecgc.continue`
+- `codecgc.explain`
+- `codecgc.plan`
+- `codecgc.build`
+- `codecgc.fix`
+- `codecgc.test`
+- `codecgc.review`
+- `codecgc.route`
+- `codecgc.history`
+
+CLI 只作为 MCP 不可用、本地调试或 CI 回退：
+
+```bash
+cgc "<自然语言需求>"
+cgc-plan ...
+cgc-build ...
+cgc-fix ...
+cgc-test ...
+cgc-review ...
+cgc-route ...
+```
+
+## 安装方式
+
+**推荐：全局安装 + 项目初始化**
+
+```bash
+npm install -g @hunyed15/codecgc
+cd your-project
+cgc-init
+```
+
+全局安装后，`cgc-init`、`cgc-status`、`cgc-doctor` 等命令在任何目录都可用。
+
+**项目初始化命令**：
+
+在 Claude 中：
+
+```text
+/cgc-init
+/cgc-start
+/cgc-status
+/cgc-doctor
+```
+
+在命令行：
+
+```bash
+cgc-init
+cgc-start
+cgc-status
+cgc-doctor
+```
+
+**备选：项目级安装**
+
+适用于 CI、Docker 或需要版本隔离的场景：
+
+```bash
+npm install @hunyed15/codecgc
+npx cgc-init
+```
+
+**规则**：
+
+- `cgc-init` 和 `/cgc-init` 默认写入当前项目，不写入 `~/.claude`。
+- 全局安装提供最佳用户体验，初始化命令全局可用。
+- 项目级安装需要通过 `npx` 调用命令。
+- Windows PowerShell 如拦截 `.ps1` shim，使用 `cgc-init.cmd`、`cgc-status.cmd`、`cgc-doctor.cmd`。
+
+## 写入边界
+
+`model-routing.yaml` 是路径归属的唯一策略来源。
+
+Claude 可以直接处理：
+
+- `codecgc/**`
+- `.claude/**`
+- `.mcp.json`
+- `model-routing.yaml`
+- `README.md`
+- `docs/**`
+- `CHANGELOG.md`
+
+Claude 不应直接修改产品源码：
+
+- 后端源码和后端测试应交给 Codex。
+- 前端源码和前端测试应交给 Gemini。
+- shared 路径必须先拆分再执行。
+- unknown 路径必须先澄清或更新路由策略。
+
+如果 hook 拦截写入，不要绕过。应解释路径归属，并通过 `/cgc` 或 CodeCGC MCP 重新路由。
+
+## 标准闭环
+
+默认流程：
+
+```text
+需求 -> 规划 -> 路由 -> Codex/Gemini 执行 -> audit -> Claude 审核 -> 继续或关闭
+```
+
+稳定状态：
+
+- `needs-planning`：先由 Claude 补充或修复规划。
+- `awaiting-build`：feature 步骤可执行。
+- `awaiting-fix`：issue 修复步骤可执行。
+- `awaiting-review`：已有 audit，等待审核。
+- `closed`：当前 workflow 已结束。
+
+## 审核规则
+
+`/cgc-review` 是控制点，不是简单写“通过”。
+
+接受前必须确认：
+
+- audit 是真实执行，不是 dry-run。
+- executor 归属正确。
+- 变更路径符合 `model-routing.yaml`。
+- 执行结果成功且有证据。
+- 验收标准已满足。
+
+必须驳回或保持 `changes-requested`：
+
+- 只有 dry-run。
+- 执行器失败、超时或输出无效。
+- 路径越界。
+- 前后端执行器归属错误。
+- mixed/shared/unknown 路径未拆分。
+- 证据不足或本地事实与执行器自报不一致。
+
+## 失败恢复
+
+- executor failure：检查 audit 和执行器输出，不要假装完成。
+- review changes-requested：保持同一 workflow，继续执行推荐的 build/fix/test。
+- mixed ownership：回到 plan，拆成 backend/frontend/docs/orchestration 子步骤。
+- test step：使用 `cgc-test`，不要用 build/fix 代替。
+- session continue：只在同一 task id 和 artifact class 内复用 session id。
+
+## 文档放置
+
+普通项目文档：
+
+```text
+docs/
+README.md
+CHANGELOG.md
+```
+
+CodeCGC 工作流和治理产物：
+
+```text
+codecgc/features/
+codecgc/issues/
+codecgc/execution/
+codecgc/requirements/
+codecgc/architecture/
+codecgc/roadmap/
+codecgc/compound/
+codecgc/docs/
+codecgc/reference/
+```
+
+长期文档和 audit 使用项目相对路径，不固化某台机器的安装目录或 npx 临时缓存路径。
+
+## 硬规则
+
+- 不要为了速度绕过 CodeCGC 直接改产品代码。
+- 用户要求实现功能或修复代码时，优先进入 `/cgc` 工作流。
+- 用户要求修改文档、规划、验收或审核说明时，Claude 可直接处理。
+- dry-run 不是完成证据。
+- 没有 audit 不要宣称执行器任务完成。
+- 不要把 Codex/Gemini 当只读分析模型；它们在 CodeCGC 中是代码执行器。
+
+## 记忆口诀
+
+```text
+Claude 负责想清楚、写清楚、审清楚。
+Codex 负责后端代码。
+Gemini 负责前端代码。
+CodeCGC 负责路由、证据、状态和闭环。
+```