@hunyed15/codecgc 0.2.3 → 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` 调用命令。推荐使用全局安装以获得更好的用户体验。
 
 ## 安装后生成的项目文件
 

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
@@ -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/templates/project/CLAUDE.md

@@ -53,9 +53,21 @@ cgc-review ...
 cgc-route ...
 ```
 
-## 安装边界
+## 安装方式
 
-CodeCGC 默认使用项目级安装。
+**推荐：全局安装 + 项目初始化**
+
+```bash
+npm install -g @hunyed15/codecgc
+cd your-project
+cgc-init
+```
+
+全局安装后，`cgc-init`、`cgc-status`、`cgc-doctor` 等命令在任何目录都可用。
+
+**项目初始化命令**：
+
+在 Claude 中：
 
 ```text
 /cgc-init
@@ -64,7 +76,7 @@ CodeCGC 默认使用项目级安装。
 /cgc-doctor
 ```
 
-CLI 回退：
+在命令行：
 
 ```bash
 cgc-init
@@ -73,10 +85,20 @@ cgc-status
 cgc-doctor
 ```
 
-规则：
+**备选：项目级安装**
+
+适用于 CI、Docker 或需要版本隔离的场景：
+
+```bash
+npm install @hunyed15/codecgc
+npx cgc-init
+```
+
+**规则**：
 
-- `/cgc-init` 和 `cgc-init` 默认写入当前项目。
-- 不要默认写入 `~/.claude`。
+- `cgc-init` 和 `/cgc-init` 默认写入当前项目，不写入 `~/.claude`。
+- 全局安装提供最佳用户体验，初始化命令全局可用。
+- 项目级安装需要通过 `npx` 调用命令。
 - Windows PowerShell 如拦截 `.ps1` shim，使用 `cgc-init.cmd`、`cgc-status.cmd`、`cgc-doctor.cmd`。
 
 ## 写入边界

package/mcp/codexmcp/src/codexmcp/server.py

@@ -20,6 +20,8 @@ import shutil
 
 mcp = FastMCP("Codex MCP Server-from guda.studio")
 
+DEFAULT_CODEX_TIMEOUT_SECONDS = 600
+
 # Mirror of model-routing.yaml frontend_paths — keep these hints in sync with
 # edit-guard.js and geminimcp/server.py BACKEND_PATH_HINTS.
 FRONTEND_PATH_HINTS = (
@@ -177,7 +179,25 @@ def _validate_backend_target_paths(target_paths: List[Path]) -> tuple[bool, List
     return True, policy_checks, ""
 
 
-def run_shell_command(cmd: list[str]) -> Generator[str, None, None]:
+def _terminate_process_tree(process: subprocess.Popen[str]) -> None:
+    """Terminate a process and its children best-effort."""
+    if process.poll() is not None:
+        return
+
+    if os.name == "nt":
+        subprocess.run(
+            ["taskkill", "/PID", str(process.pid), "/T", "/F"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        return
+
+    process.kill()
+
+
+def run_shell_command(cmd: list[str], timeout_seconds: int = DEFAULT_CODEX_TIMEOUT_SECONDS) -> Generator[str, None, None]:
     """Execute a command and stream its output line-by-line.
 
     Args:
@@ -204,6 +224,8 @@ def run_shell_command(cmd: list[str]) -> Generator[str, None, None]:
 
     output_queue: queue.Queue[str | None] = queue.Queue()
     GRACEFUL_SHUTDOWN_DELAY = 0.3
+    started_at = time.monotonic()
+    timed_out = False
 
     def is_turn_completed(line: str) -> bool:
         """Check if the line indicates turn completion via JSON parsing."""
@@ -237,13 +259,17 @@ def run_shell_command(cmd: list[str]) -> Generator[str, None, None]:
                 break
             yield line
         except queue.Empty:
+            if timeout_seconds > 0 and time.monotonic() - started_at > timeout_seconds:
+                timed_out = True
+                _terminate_process_tree(process)
+                break
             if process.poll() is not None and not thread.is_alive():
                 break
 
     try:
         process.wait(timeout=5)
     except subprocess.TimeoutExpired:
-        process.kill()
+        _terminate_process_tree(process)
         process.wait()
     thread.join(timeout=5)
 
@@ -255,6 +281,13 @@ def run_shell_command(cmd: list[str]) -> Generator[str, None, None]:
         except queue.Empty:
             break
 
+    if timed_out:
+        raise TimeoutError(
+            f"Codex CLI timed out after {timeout_seconds} seconds. "
+            "This usually means the CLI was waiting for interactive approval, "
+            "network/authentication, or a long-running tool call."
+        )
+
 
 def _execute_codex_session(
     *,
@@ -268,6 +301,7 @@ def _execute_codex_session(
     model: str,
     yolo: bool,
     profile: str,
+    timeout_seconds: int = DEFAULT_CODEX_TIMEOUT_SECONDS,
 ) -> Dict[str, Any]:
     """Execute Codex CLI and return the parsed MCP response payload."""
     if not cd.exists():
@@ -310,7 +344,7 @@ def _execute_codex_session(
     err_message = ""
     thread_id: Optional[str] = None
 
-    for line in run_shell_command(cmd):
+    for line in run_shell_command(cmd, timeout_seconds):
         try:
             line_dict = json.loads(line.strip())
             all_messages.append(line_dict)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunyed15/codecgc",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Claude-hosted multi-model workflow product shell for CodeCGC.",
   "license": "MIT",
   "type": "commonjs",
@@ -10,6 +10,7 @@
     "cgc-init": "bin/cgc-init.js",
     "cgc-status": "bin/cgc-status.js",
     "cgc-doctor": "bin/cgc-doctor.js",
+    "cgc-explain": "bin/cgc-explain.js",
     "cgc-package-audit": "bin/cgc-package-audit.js",
     "cgc-external-audit": "bin/cgc-external-audit.js",
     "cgc-external-status": "bin/cgc-external-status.js",

package/scripts/codecgc_error_catalog.py

@@ -0,0 +1,172 @@
+"""Error code classification and explanation for CodeCGC.
+
+Provides human-readable explanations and actionable suggestions for common error scenarios.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+# Error code to explanation mapping
+ERROR_CATALOG: dict[str, dict[str, str]] = {
+    "executor-crash": {
+        "title": "执行器内部异常",
+        "description": "执行器脚本在运行过程中异常退出，未能完成任务。",
+        "common_causes": [
+            "执行器环境配置不完整（缺少依赖、路径错误）",
+            "执行器超时或资源不足",
+            "执行器内部代码错误",
+        ],
+        "suggestions": [
+            "运行 cgc-doctor 检查执行器环境配置",
+            "查看审计文件中的详细错误日志",
+            "如果持续失败，尝试重新安装：cgc-init",
+        ],
+    },
+    "executor-failure": {
+        "title": "执行器任务失败",
+        "description": "执行器正常运行，但任务执行失败（如代码生成失败、测试未通过）。",
+        "common_causes": [
+            "目标路径不存在或不可访问",
+            "任务契约与实际代码不匹配",
+            "执行器返回的结果格式不正确",
+        ],
+        "suggestions": [
+            "检查审计文件中的执行器输出",
+            "确认目标路径在工作区中存在",
+            "如果是路径问题，回到 cgc-plan 修正步骤契约",
+        ],
+    },
+    "scope-error": {
+        "title": "任务范围错误",
+        "description": "当前步骤包含多个执行器归属的路径，需要拆分。",
+        "common_causes": [
+            "一个步骤同时包含前端和后端路径",
+            "一个步骤包含 shared 或 unknown 路径",
+        ],
+        "suggestions": [
+            "运行 cgc-plan 查看拆分建议",
+            "按执行器归属（frontend/backend）拆分成独立步骤",
+            "shared 路径需要先明确归属或单独处理",
+        ],
+    },
+    "design-gap": {
+        "title": "设计缺口",
+        "description": "当前步骤引用的路径或配置在路由策略中未覆盖，或目标文件不存在。",
+        "common_causes": [
+            "目标路径在 model-routing.yaml 中未定义",
+            "目标文件在工作区中不存在",
+            "路由规则与实际项目结构不匹配",
+        ],
+        "suggestions": [
+            "检查 model-routing.yaml 是否覆盖目标路径",
+            "确认目标文件在工作区中存在",
+            "回到 cgc-plan 修正目标路径或步骤契约",
+        ],
+    },
+    "environment-or-tooling": {
+        "title": "环境或工具问题",
+        "description": "执行器环境、依赖或外部工具不可用。",
+        "common_causes": [
+            "执行器 CLI 未安装或不在 PATH 中",
+            "执行器超时（网络、认证、长时间运行）",
+            "缺少必需的依赖或配置文件",
+        ],
+        "suggestions": [
+            "运行 cgc-doctor 检查执行器可用性",
+            "检查网络连接和认证状态",
+            "确认执行器 CLI 已正确安装",
+        ],
+    },
+    "workflow-state": {
+        "title": "工作流状态不满足",
+        "description": "当前工作流状态不允许执行请求的操作。",
+        "common_causes": [
+            "尝试执行 build/fix/test，但工作流还在 needs-planning 状态",
+            "尝试 review，但没有可审核的执行结果",
+            "工作流已关闭，但尝试继续执行",
+        ],
+        "suggestions": [
+            "运行 cgc-route 查看当前工作流状态和推荐命令",
+            "按推荐命令顺序执行（plan → build/fix → review）",
+            "如果工作流已关闭，使用 /cgc 开始新的工作流",
+        ],
+    },
+    "returned-to-planning": {
+        "title": "返回规划阶段",
+        "description": "执行器发现问题，需要回到规划阶段修正。",
+        "common_causes": [
+            "任务范围需要拆分（scope-error）",
+            "目标路径或契约有设计缺口（design-gap）",
+        ],
+        "suggestions": [
+            "运行 cgc-plan 查看问题详情和修正建议",
+            "根据建议修正步骤契约或拆分步骤",
+            "修正后重新执行 build/fix",
+        ],
+    },
+}
+
+
+def explain_error(error_code: str) -> dict[str, Any]:
+    """Get explanation for an error code.
+
+    Args:
+        error_code: Error code from failure_type field
+
+    Returns:
+        Dict with title, description, common_causes, and suggestions
+    """
+    if error_code not in ERROR_CATALOG:
+        return {
+            "error_code": error_code,
+            "title": "未知错误类型",
+            "description": f"错误代码 '{error_code}' 未在错误分类表中定义。",
+            "common_causes": [],
+            "suggestions": [
+                "查看完整错误信息中的 error 和 next 字段",
+                "运行 cgc-doctor 检查环境配置",
+                "如果问题持续，请报告此错误代码",
+            ],
+        }
+
+    explanation = ERROR_CATALOG[error_code].copy()
+    explanation["error_code"] = error_code
+    return explanation
+
+
+def list_error_codes() -> list[str]:
+    """List all available error codes."""
+    return sorted(ERROR_CATALOG.keys())
+
+
+def format_explanation(explanation: dict[str, Any]) -> str:
+    """Format explanation as human-readable text.
+
+    Args:
+        explanation: Result from explain_error
+
+    Returns:
+        Formatted text block
+    """
+    lines = [
+        f"错误代码: {explanation['error_code']}",
+        f"标题: {explanation['title']}",
+        "",
+        "说明:",
+        explanation['description'],
+        "",
+    ]
+
+    if explanation.get("common_causes"):
+        lines.append("常见原因:")
+        for cause in explanation["common_causes"]:
+            lines.append(f"  - {cause}")
+        lines.append("")
+
+    if explanation.get("suggestions"):
+        lines.append("建议操作:")
+        for suggestion in explanation["suggestions"]:
+            lines.append(f"  - {suggestion}")
+
+    return "\n".join(lines)

package/scripts/codecgc_error_formatter.py

@@ -0,0 +1,124 @@
+"""Error formatting and leveling for CodeCGC output.
+
+Provides three-level error display:
+- summary: User-friendly Chinese message for non-technical users
+- detail: Technical context for developers
+- debug: Full logs and tracebacks for troubleshooting
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def format_error_output(
+    result: dict[str, Any],
+    *,
+    level: str = "summary",
+) -> dict[str, Any]:
+    """Format error output with appropriate detail level.
+
+    Args:
+        result: Raw result dict from workflow execution
+        level: Display level - "summary", "detail", or "debug"
+
+    Returns:
+        Formatted result with error_display field
+    """
+    if result.get("success"):
+        return result
+
+    error_display = _build_error_display(result, level)
+    formatted = result.copy()
+    formatted["error_display"] = error_display
+    formatted["error_level"] = level
+
+    return formatted
+
+
+def _build_error_display(result: dict[str, Any], level: str) -> dict[str, Any]:
+    """Build error display structure based on level."""
+    display: dict[str, Any] = {
+        "level": level,
+    }
+
+    # Summary level: user-friendly Chinese only
+    if level == "summary":
+        display["message"] = _extract_user_message(result)
+        display["suggestion"] = _extract_user_suggestion(result)
+        return display
+
+    # Detail level: add technical context
+    if level == "detail":
+        display["message"] = _extract_user_message(result)
+        display["suggestion"] = _extract_user_suggestion(result)
+        display["technical_error"] = result.get("error", "")
+        display["failure_type"] = result.get("failure_type", "")
+        display["state"] = result.get("state", "")
+        display["audit_path"] = result.get("audit_path", "")
+        return display
+
+    # Debug level: everything
+    if level == "debug":
+        display["message"] = _extract_user_message(result)
+        display["suggestion"] = _extract_user_suggestion(result)
+        display["technical_error"] = result.get("error", "")
+        display["failure_type"] = result.get("failure_type", "")
+        display["state"] = result.get("state", "")
+        display["audit_path"] = result.get("audit_path", "")
+        display["full_result"] = result
+        return display
+
+    # Fallback
+    display["message"] = _extract_user_message(result)
+    return display
+
+
+def _extract_user_message(result: dict[str, Any]) -> str:
+    """Extract user-friendly error message."""
+    # Check for human_error first (from Phase 1)
+    execution = result.get("execution", {})
+    if isinstance(execution, dict):
+        exec_result = execution.get("result", {})
+        if isinstance(exec_result, dict):
+            human_error = exec_result.get("human_error", "").strip()
+            if human_error:
+                return human_error
+
+    # Check for next field (from flow control)
+    next_msg = result.get("next", "").strip()
+    if next_msg:
+        return next_msg
+
+    # Check for error field
+    error_msg = result.get("error", "").strip()
+    if error_msg:
+        # If it looks technical, provide generic message
+        if "failed with exit code" in error_msg.lower() or "traceback" in error_msg.lower():
+            return "执行步骤失败。请查看详细信息或运行 cgc-doctor 检查环境。"
+        return error_msg
+
+    return "执行失败，未提供详细信息。"
+
+
+def _extract_user_suggestion(result: dict[str, Any]) -> str:
+    """Extract user-friendly suggestion."""
+    # Check for suggestion field (from Phase 1)
+    execution = result.get("execution", {})
+    if isinstance(execution, dict):
+        exec_result = execution.get("result", {})
+        if isinstance(exec_result, dict):
+            suggestion = exec_result.get("suggestion", "").strip()
+            if suggestion:
+                return suggestion
+
+    # Check for recommended_command
+    recommended = result.get("recommended_command", "").strip()
+    if recommended:
+        return f"建议运行: {recommended}"
+
+    # Check for next field that contains suggestions
+    next_msg = result.get("next", "").strip()
+    if next_msg and ("建议" in next_msg or "请" in next_msg or "运行" in next_msg):
+        return next_msg
+
+    return "请稍后重试，或运行 cgc-doctor 检查环境配置。"

package/scripts/codecgc_flow_control.py

@@ -108,6 +108,17 @@ def classify_execution_failure(execution: dict[str, Any]) -> tuple[str, str, str
             "当前步骤引用的目标路径在工作区中不存在，请先回到 cgc-plan 修正目标路径或步骤契约。",
         )
 
+    if "failed with exit code" in combined:
+        human = str(result.get("human_error", "")).strip()
+        suggestion = str(result.get("suggestion", "")).strip()
+        next_msg = human + "\n" + suggestion if human else "执行器内部异常，请稍后重试。如果持续失败，运行 cgc-doctor 检查环境。"
+        return (
+            "blocked",
+            "executor-crash",
+            "",
+            next_msg,
+        )
+
     if outcome == "blocked" or "timeout" in combined or "does not exist" in combined:
         return (
             "blocked",

package/scripts/codecgc_runtime/console.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import os
 import sys
 from typing import Any
 
@@ -20,6 +21,14 @@ def configure_utf8_stdio() -> None:
 
 def print_json(payload: dict[str, Any], *, file: Any | None = None) -> None:
     target = file or sys.stdout
+
+    # Apply error formatting if this is an error result
+    if not payload.get("success") and "error_display" not in payload:
+        error_level = os.environ.get("CODECGC_ERROR_LEVEL", "summary")
+        if error_level in {"summary", "detail", "debug"}:
+            from codecgc_error_formatter import format_error_output
+            payload = format_error_output(payload, level=error_level)
+
     text = json.dumps(payload, ensure_ascii=False, indent=2)
     target.write(text)
     target.write("\n")

package/scripts/codecgc_runtime/workflow_runtime.py

@@ -14,6 +14,21 @@ WORKSPACE = PACKAGE_ROOT
 PROJECT_WORKSPACE = PROJECT_ROOT
 SCRIPTS_DIR = WORKSPACE / "scripts"
 
+_SCRIPT_OPERATION_NAMES = {
+    "plan_codecgc_workflow.py": "规划工作流",
+    "route_codecgc_workflow.py": "路由检查",
+    "run_codecgc_build.py": "构建执行",
+    "run_codecgc_fix.py": "修复执行",
+    "run_codecgc_test.py": "测试执行",
+    "review_codecgc_workflow.py": "审核调度",
+    "build_codecgc_task.py": "任务构建",
+    "write_codecgc_decision.py": "写入决策",
+    "write_codecgc_learning.py": "写入经验",
+    "write_codecgc_architecture.py": "写入架构",
+    "write_codecgc_requirement.py": "写入需求",
+    "init_codecgc_workflow.py": "初始化工作流",
+}
+
 
 def build_script_command(script_name: str, *args: str) -> list[str]:
     return [sys.executable, str(SCRIPTS_DIR / script_name), *args]
@@ -63,10 +78,13 @@ def run_json_script(script_name: str, *args: str) -> dict[str, Any]:
             parsed.setdefault("returncode", completed.returncode)
             return parsed
 
+    operation = _SCRIPT_OPERATION_NAMES.get(script_name, script_name)
     return {
         "success": False,
         "returncode": completed.returncode,
         "stdout": stdout,
         "stderr": stderr,
         "error": f"{script_name} failed with exit code {completed.returncode}.",
+        "human_error": f"{operation}步骤执行失败（内部脚本异常退出）。",
+        "suggestion": "请稍后重试。如果多次失败，运行 cgc-doctor 检查环境配置。",
     }

package/scripts/explain_codecgc_error.py

@@ -0,0 +1,71 @@
+"""cgc-explain: Explain CodeCGC error codes and provide actionable suggestions.
+
+Usage:
+    cgc-explain <error_code>
+    cgc-explain --list
+"""
+import argparse
+import sys
+
+from codecgc_console_io import configure_utf8_stdio
+from codecgc_console_io import print_json
+from codecgc_error_catalog import explain_error
+from codecgc_error_catalog import format_explanation
+from codecgc_error_catalog import list_error_codes
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Explain CodeCGC error codes and provide actionable suggestions."
+    )
+    parser.add_argument(
+        "error_code",
+        nargs="?",
+        help="Error code to explain (e.g., executor-crash, scope-error)",
+    )
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help="List all available error codes",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["json", "summary"],
+        default="summary",
+        help="Output format",
+    )
+    return parser
+
+
+def main() -> int:
+    configure_utf8_stdio()
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.list:
+        codes = list_error_codes()
+        if args.format == "json":
+            print_json({"success": True, "error_codes": codes})
+        else:
+            print("可用的错误代码:")
+            for code in codes:
+                print(f"  - {code}")
+            print("\n使用 cgc-explain <error_code> 查看详细说明")
+        return 0
+
+    if not args.error_code:
+        parser.print_help()
+        return 1
+
+    explanation = explain_error(args.error_code)
+
+    if args.format == "json":
+        print_json({"success": True, "explanation": explanation})
+    else:
+        print(format_explanation(explanation))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/install_codecgc.py

@@ -134,6 +134,27 @@ def build_project_onboarding_text() -> str:
 
 This file is generated by `cgc-init` for this project. It is intentionally project-relative and should not contain machine-specific install paths.
 
+## Installation
+
+**Recommended: Global Install + Project Init**
+
+```bash
+npm install -g @hunyed15/codecgc
+cd your-project
+cgc-init
+```
+
+After global installation, commands like `cgc-init`, `cgc-status`, `cgc-doctor` are available in any directory.
+
+**Alternative: Project-Level Install**
+
+For CI, Docker, or version isolation scenarios:
+
+```bash
+npm install @hunyed15/codecgc
+npx cgc-init
+```
+
 ## First Run
 
 Inside Claude:
@@ -910,10 +931,29 @@ def build_doctor_fix_command(workspace_root: Path) -> str:
     return f"cgc-init --workspace {shell_quote(str(workspace_root))}"
 
 
+def is_global_npm_install() -> bool:
+    """检测当前是否为全局安装的 CodeCGC"""
+    try:
+        # 检查是否在 npm 全局目录中
+        import sys
+        executable_path = Path(sys.executable).resolve()
+        # 简单启发式：如果在 node_modules/.bin 之外，可能是全局安装
+        # 更准确的方法是检查 cgc-init 命令是否在 PATH 中且不需要 npx
+        cgc_init_path = shutil.which("cgc-init")
+        if cgc_init_path:
+            # 如果能直接找到 cgc-init，说明是全局安装
+            return True
+    except Exception:
+        pass
+    return False
+
+
 def build_install_mode_summary(result: dict[str, Any]) -> str:
     mode = str(result.get("mode", "")).strip()
 
     if mode == "local":
+        is_global = is_global_npm_install()
+
         lines = [
             f"- 工作区: {result.get('workspace', '')}",
             "- 范围: 项目级 Claude 与 MCP 集成面",
@@ -926,8 +966,17 @@ def build_install_mode_summary(result: dict[str, Any]) -> str:
             f"- Hook 脚本: {result.get('hook_script', '')}",
             f"- Slash Commands: {result.get('commands_dir', '')}",
             f"- 新手入口: {result.get('onboarding_file', '')}",
-            "- 说明: 可选外部能力如 MemOS 不由 cgc-init 自动写入；如需启用，请在 Claude 中单独配置官方 MCP。",
         ]
+
+        if is_global:
+            lines.append("- 安装方式: 全局安装（推荐）")
+            lines.append("- 说明: 初始化完成。现在可以在 Claude 中使用 /cgc 或在命令行使用 cgc 命令。")
+        else:
+            lines.append("- 安装方式: 项目级安装")
+            lines.append("- 说明: 项目级安装需要通过 npx 调用命令。推荐全局安装：npm install -g @hunyed15/codecgc")
+
+        lines.append("- 提示: 可选外部能力如 MemOS 不由 cgc-init 自动写入；如需启用，请在 Claude 中单独配置官方 MCP。")
+
         next_actions = [
             "cgc-start",
             "cgc-status",

package/scripts/postinstall_codecgc.js

@@ -12,13 +12,31 @@ function isGlobalInstall() {
 }
 
 function main() {
-  if (!isGlobalInstall()) {
-    return 0;
+  const isGlobal = isGlobalInstall();
+
+  if (isGlobal) {
+    console.log("");
+    console.log("✓ CodeCGC 已全局安装");
+    console.log("");
+    console.log("下一步：");
+    console.log("  1. 进入项目目录：cd your-project");
+    console.log("  2. 初始化项目：cgc-init");
+    console.log("  3. 查看状态：cgc-status");
+    console.log("");
+    console.log("初始化后，可在 Claude 中使用 /cgc 或在命令行使用 cgc 命令。");
+    console.log("");
+  } else {
+    console.log("");
+    console.log("✓ CodeCGC 已安装到项目");
+    console.log("");
+    console.log("下一步：");
+    console.log("  运行 'npx cgc-init' 来初始化项目");
+    console.log("");
+    console.log("提示：推荐全局安装以获得更好的体验：");
+    console.log("  npm install -g @hunyed15/codecgc");
+    console.log("");
   }
 
-  console.warn("[codecgc] Global CLI installed.");
-  console.warn("[codecgc] CodeCGC no longer writes Claude user-level files during npm install.");
-  console.warn("[codecgc] Run `cgc-init` from each target project to create project-local .mcp.json, .claude/, and model-routing.yaml.");
   return 0;
 }