@hunyed15/codecgc 0.1.6 → 0.1.8

package/INSTALLATION.md

@@ -1,573 +1,206 @@
-# CodeCGC 安装与使用指南
+# CodeCGC 安装指南
 
-## 目录
+本文说明如何从 npm 安装 CodeCGC，并把它接入到具体项目中。
 
-1. [系统要求](#系统要求)
-2. [安装 CodeCGC](#安装-codecgc)
-3. [安装 Python 依赖](#安装-python-依赖)
-4. [安装 MCP 服务器](#安装-mcp-服务器)
-5. [初始化项目](#初始化项目)
-6. [验证安装](#验证安装)
-7. [快速开始](#快速开始)
-8. [常见问题](#常见问题)
+## 环境要求
 
----
+- Node.js >= 20
+- npm >= 9
+- Python >= 3.10
+- 可选：Claude Code、Codex CLI、Gemini CLI
 
-## 系统要求
+CodeCGC 的 npm 包提供 `cgc*` 命令；Python 运行时负责 MCP 编排器、执行器桥接、路由策略检查和工作流脚本。
 
-### 必需环境
-
-- **Node.js**: >= 20.0.0
-- **Python**: >= 3.10
-- **npm**: >= 9.0.0 (随 Node.js 安装)
-- **操作系统**: Windows 10+, macOS 10.15+, Linux (Ubuntu 20.04+)
-
-### 检查当前环境
-
-```bash
-node --version    # 应显示 v20.x.x 或更高
-python --version  # 应显示 Python 3.10.x 或更高
-npm --version     # 应显示 9.x.x 或更高
-```
-
----
-
-## 安装 CodeCGC
-
-### 方式 1：从 npm 全局安装（推荐）
+## 1. 全局安装 CLI
 
 ```bash
-# 使用 npm 官方源安装
 npm install -g @hunyed15/codecgc --registry=https://registry.npmjs.org/
 ```
 
-安装完成后，CodeCGC 会尝试自动执行一次用户级 Claude 集成，相当于：
-
-```bash
-cgc-install --mode user
-```
-
-这会写入：
-
-- `~/.claude/mcp.json`
-- `~/.claude/hooks/route-edit.ps1`
-- `~/.claude/commands/cgc.md`
-- `~/.claude/commands/cgc-install.md`
-- `~/.claude/commands/cgc-status.md`
-- `~/.claude/commands/cgc-doctor.md`
-
-写入完成后，可以在 Claude 中直接输入：
-
-```text
-/cgc
-/cgc-install
-/cgc-status
-/cgc-doctor
-```
-
-如果安装阶段因为 Python 未就绪而跳过了这一步，可以在装好 Python 后手动补执行该命令。
-
-安装后，以下命令将全局可用：
-- `cgc`
-- `cgc-install`
-- `cgc-status`
-- `cgc-doctor`
-- `cgc-plan`
-- `cgc-build`
-- `cgc-fix`
-- `cgc-test`
-- `cgc-review`
-- `cgc-route`
-- 等等...
-
-### 方式 2：从源码本地安装
-
-```bash
-# 1. 进入您的项目目录
-cd your-project
+全局安装只注册命令，不会默认写入 `~/.claude`。这是当前主线设计：每个业务项目通过项目级安装生成自己的 `.mcp.json`、`.claude/` 和 `model-routing.yaml`。
 
-# 2. 安装 CodeCGC（指向 release 目录）
-npm install /path/to/codecgc/release
-```
+验证命令：
 
-使用时需要通过 `npx` 调用：
 ```bash
-npx cgc --help
-npx cgc-install
-```
-
-### 方式 3：直接使用（无需安装）
-
-```bash
-# 进入 release 目录
-cd /path/to/codecgc/release
-
-# 直接运行命令
-node bin/cgc.js --help
-node bin/cgc-install.js
-```
-
-### 验证安装
-
-```bash
-cgc --version
 cgc --help
+cgc-install --help
+cgc-doctor --help
 ```
 
-**注意**: 如果使用方式 2 或方式 3，需要将 `/path/to/codecgc/release` 替换为实际的 release 目录路径。
-
----
-
-## 安装 Python 依赖
+## 2. 在目标项目执行项目级安装
 
-CodeCGC 的 Python 脚本需要以下依赖：
-
-### 核心依赖
+进入你要使用 CodeCGC 的项目根目录：
 
 ```bash
-pip install pyyaml>=6.0
+cd your-project
+cgc-install
 ```
 
-### 开发依赖（可选，用于运行测试）
+默认安装模式是项目级安装，等价于：
 
 ```bash
-pip install -r requirements-dev.txt
-```
-
-`requirements-dev.txt` 内容：
+cgc-install --mode local --workspace .
 ```
-pytest>=8.0.0
-pytest-cov>=4.1.0
-pyyaml>=6.0
-```
-
-### 一键安装所有依赖
-
-在 CodeCGC 项目根目录执行：
 
-```bash
-pip install -r requirements.txt
-```
+安装会创建或同步：
 
----
-
-## 安装 MCP 服务器
-
-CodeCGC 依赖两个 MCP 服务器来执行代码：
-
-### 1. Codex MCP（后端执行器）
-
-**位置**: `codexmcp/` 目录
-
-**安装步骤**:
-
-```bash
-cd codexmcp
-pip install -e .
+```text
+.mcp.json
+model-routing.yaml
+.claude/
+  settings.json
+  hooks/
+    route-edit.ps1
+  commands/
+    cgc*.md
+codecgc/
+  START_HERE.md
+  features/
+  issues/
+  execution/
+  requirements/
+  architecture/
+  roadmap/
+  compound/
+  docs/
+  reference/
+  fixtures/
+```
+
+这些文件属于目标项目的 CodeCGC 集成面。不同电脑、不同项目的安装路径可能不同，因此应由 `cgc-install` 在本机生成，不应从 CodeCGC 源码仓库复制固定路径。
+
+## 3. 首次启动和自检
+
+安装后执行：
+
+```bash
+cgc-start
+cgc-status
+cgc-doctor
 ```
 
-**验证安装**:
+在 Claude 中也可以使用：
 
-```bash
-python -m codexmcp.server --help
+```text
+/cgc-start
+/cgc-status
+/cgc-doctor
 ```
 
-**功能**: 执行后端代码任务（Python, Go, Rust, Java 等）
-
----
-
-### 2. Gemini MCP（前端执行器）
-
-**位置**: `geminimcp/` 目录
-
-**安装步骤**:
+`cgc-start` 是只读的新手入口，会提示当前项目的最短使用路径。`cgc-status` 检查项目级集成文件是否齐全。`cgc-doctor` 检查 Python、MCP 运行时、执行器导入和项目集成状态。
 
-```bash
-cd geminimcp
-pip install -e .
-```
-
-**验证安装**:
+## 4. 日常使用
 
-```bash
-python -m geminimcp.server --help
-```
+推荐从一个入口开始：
 
-**功能**: 执行前端代码任务（TypeScript, React, Vue 等）
-
----
-
-### MCP 服务器配置
-
-CodeCGC 会自动在项目中生成 `.mcp.json` 配置文件：
-
-```json
-{
-  "mcpServers": {
-    "codexmcp": {
-      "command": "python",
-      "args": ["-m", "codexmcp.server"],
-      "env": {}
-    },
-    "geminimcp": {
-      "command": "python",
-      "args": ["-m", "geminimcp.server"],
-      "env": {}
-    }
-  }
-}
+```text
+/cgc 新增一个登录页，放在 src/components/LoginForm.tsx
 ```
 
-**注意**: 如果 Python 命令在您的系统上是 `python3`，请手动修改 `command` 字段。
-
----
-
-## 初始化项目
-
-### 1. 进入您的项目目录
+命令行回退路径：
 
 ```bash
-cd /path/to/your/project
+cgc "新增一个登录页，放在 src/components/LoginForm.tsx"
 ```
 
-### 2. 运行安装命令
+CodeCGC 会根据工作流状态决定下一步是规划、执行、审核、继续还是收尾。只有在你明确知道当前阶段时，才需要直接使用子命令：
 
 ```bash
-cgc-install
-```
-
-这会创建以下文件和目录：
-
-```
-your-project/
-├── .claude/
-│   ├── hooks/
-│   │   └── route-edit.ps1       # 路由钩子（阻止 Claude 直接编辑代码）
-│   └── settings.json            # Claude 配置
-├── .mcp.json                    # MCP 服务器注册
-├── model-routing.yaml           # 路由规则配置
-└── codecgc/                     # 工作流产物存储
-    ├── product/
-    │   ├── feature/             # 功能开发工作流
-    │   ├── issue/               # Bug 修复工作流
-    │   └── execution/           # 执行审计记录
-    ├── architecture/            # 架构文档
-    ├── requirements/            # 需求文档
-    ├── decisions/               # 技术决策
-    ├── learnings/               # 经验总结
-    └── roadmap/                 # 路线图
+cgc-plan ...
+cgc-build ...
+cgc-fix ...
+cgc-test ...
+cgc-review ...
+cgc-route ...
+cgc-history ...
 ```
 
-### 3. 配置路由规则
-
-编辑 `model-routing.yaml`，定义前端和后端的文件路径模式：
-
-```yaml
-# 前端文件路径模式
-frontend_paths:
-  - "src/components/**"
-  - "src/pages/**"
-  - "src/ui/**"
-  - "*.tsx"
-  - "*.jsx"
-  - "*.vue"
-
-# 后端文件路径模式
-backend_paths:
-  - "src/api/**"
-  - "src/server/**"
-  - "src/db/**"
-  - "*.py"
-  - "*.go"
-  - "*.java"
-
-# 共享路径（需要特殊处理）
-shared_paths:
-  - "src/types/**"
-  - "src/utils/**"
-
-# 路由规则
-rules:
-  frontend_executor: geminimcp    # 前端使用 Gemini
-  backend_executor: codexmcp      # 后端使用 Codex
-  shared_policy: split-first      # 共享文件优先拆分
-  claude_role: plan-review-accept-only  # Claude 只规划和审查
-```
-
----
+## 5. 角色与写入边界
 
-## 验证安装
+CodeCGC 的默认协作边界是：
 
-### 1. 检查环境
+- Claude：需求、规划、设计、文档、审核、验收和工作流状态。
+- Codex：后端代码和后端测试。
+- Gemini：前端代码和前端测试。
 
-```bash
-cgc-doctor
-```
+`model-routing.yaml` 是项目内路由策略的唯一来源。Claude 的 hook 不承载业务规则，只把 `Edit`、`Write`、`MultiEdit` 写入请求交给同一套策略检查器，从而避免 Claude 绕过路由边界直接修改代码。
 
-**预期输出**:
-```
-✓ Python 可用: python 3.10.x
-✓ Codex MCP 可导入
-✓ Gemini MCP 可导入
-✓ 项目集成就绪
-✓ .mcp.json 存在
-✓ model-routing.yaml 存在
-```
-
-### 2. 检查项目状态
-
-```bash
-cgc-status
-```
-
-**预期输出**:
-```
-项目集成状态: 就绪
-工作流目录: codecgc/
-MCP 配置: .mcp.json
-路由配置: model-routing.yaml
-```
+## 6. 用户级安装
 
-### 3. 运行测试（可选）
+用户级安装不是默认路径。只有在你明确希望同步 `~/.claude` 时才使用：
 
 ```bash
-cd /path/to/codecgc
-pytest tests/ -v
+cgc-install --mode user-dry-run
+cgc-install --mode user
 ```
 
----
+建议先使用 `user-dry-run` 预览变更。普通项目接入场景应使用默认项目级安装。
 
-## 快速开始
+## 7. 发布包维护者检查
 
-### 示例 1：新增功能
+维护 CodeCGC 包时，建议在源码仓库运行：
 
 ```bash
-# 1. 提交需求
-cgc "新增用户登录页面，包含用户名密码输入框和登录按钮"
-
-# 2. 系统自动生成规划
-# 输出: 已创建 feature 工作流 2026-05-04-user-login-page
-
-# 3. 查看生成的文件
-ls codecgc/product/feature/2026-05-04-user-login-page/
-# - 2026-05-04-user-login-page-design.md
-# - 2026-05-04-user-login-page-checklist.yaml
-
-# 4. 执行第一个步骤
-cgc-build --slug 2026-05-04-user-login-page
-
-# 5. 审查执行结果
-cgc-review --audit-file codecgc/product/execution/.../xxx.json --decision accepted
-
-# 6. 继续执行后续步骤
-cgc-build --slug 2026-05-04-user-login-page
-
-# 7. 查询下一步
-cgc-route --slug 2026-05-04-user-login-page
+python -m pytest tests --basetemp D:\tmp\codecgc-pytest
+python -m compileall -q scripts codecgcmcp\src codexmcp\src geminimcp\src
+python scripts\audit_codecgc_package_runtime.py --format json
+python scripts\audit_codecgc_release_readiness.py --format json
+npm pack --dry-run --json
 ```
 
-### 示例 2：修复 Bug
+如果默认临时目录受限，可以指定发布探针目录：
 
 ```bash
-# 1. 提交问题
-cgc "用户列表页面加载很慢，需要优化"
-
-# 2. 系统自动生成 issue 工作流
-# 输出: 已创建 issue 工作流 2026-05-04-slow-user-list
-
-# 3. 执行修复
-cgc-fix --slug 2026-05-04-slow-user-list
-
-# 4. 审查修复结果
-cgc-review --audit-file ... --decision accepted
+set CODECGC_RELEASE_PROBE_ROOT=D:\tmp
+python scripts\audit_codecgc_release_readiness.py --format json
 ```
 
-### 示例 3：查看历史
-
-```bash
-# 查看所有开放的功能工作流
-cgc-history --flow feature --status open
+## 8. 常见问题
 
-# 查看最近 10 个工作流
-cgc-history --last 10
-
-# 查看项目生命周期
-cgc-lifecycle
-```
+### `cgc` 命令找不到
 
----
+确认 npm 全局 bin 目录已经加入 `PATH`：
 
-## 常见问题
-
-### Q1: `cgc` 命令找不到
-
-**原因**: 全局安装失败或 npm 全局路径未加入 PATH
-
-**解决**:
 ```bash
-# 检查全局安装路径
 npm config get prefix
-
-# 将该路径添加到系统 PATH
-# Windows: 添加到环境变量
-# macOS/Linux: 添加到 ~/.bashrc 或 ~/.zshrc
-export PATH="$PATH:$(npm config get prefix)/bin"
 ```
 
-### Q2: `ModuleNotFoundError: No module named 'yaml'`
+然后检查对应系统的全局 bin 路径是否在环境变量中。
 
-**原因**: PyYAML 未安装
+### `cgc-doctor` 提示 Python 或 MCP 依赖缺失
 
-**解决**:
-```bash
-pip install pyyaml
-```
-
-### Q3: MCP 服务器无法启动
+先确认 Python 可用：
 
-**原因**: MCP 服务器未正确安装
-
-**解决**:
 ```bash
-# 重新安装 Codex MCP
-cd codexmcp
-pip uninstall codexmcp -y
-pip install -e .
-
-# 重新安装 Gemini MCP
-cd geminimcp
-pip uninstall geminimcp -y
-pip install -e .
-
-# 验证
-python -m codexmcp.server --help
-python -m geminimcp.server --help
+python --version
 ```
 
-### Q4: `cgc-doctor` 报告 Python 不可用
-
-**原因**: Python 命令名称不匹配
+再安装核心依赖：
 
-**解决**:
 ```bash
-# 如果您的系统使用 python3
-which python3
-
-# 创建软链接或别名
-# Linux/macOS:
-sudo ln -s $(which python3) /usr/local/bin/python
-
-# Windows: 在 .mcp.json 中修改 command 为 "python3"
+python -m pip install -r requirements.txt
 ```
 
-### Q5: 执行步骤时超时
-
-**原因**: 默认 120 秒超时不够
-
-**解决**: 在 checklist.yaml 中为该步骤指定更长的超时
-```yaml
-steps:
-  - action: "复杂重构任务"
-    status: pending
-    codecgc:
-      kind: backend
-      task_summary: "重构认证模块"
-      target_paths: ["src/auth/"]
-      timeout_seconds: 600  # 10 分钟
-```
+如果是在源码开发环境中，可以按 `cgc-doctor` 输出的建议执行 editable install。
 
-### Q6: 路由规则不生效
+### 项目级集成缺失或过期
 
-**原因**: `model-routing.yaml` 格式错误或路径模式不匹配
+在目标项目根目录重新执行：
 
-**解决**:
 ```bash
-# 检查 YAML 语法
-python -c "import yaml; yaml.safe_load(open('model-routing.yaml'))"
-
-# 测试路径匹配
-cgc-route --slug your-workflow-slug
-```
-
-### Q7: 如何卸载 CodeCGC
-
-```bash
-# 卸载全局包
-npm uninstall -g codecgc
-
-# 卸载 MCP 服务器
-pip uninstall codexmcp geminimcp -y
-
-# 删除项目集成文件（可选）
-rm -rf .claude .mcp.json model-routing.yaml codecgc/
-```
-
----
-
-## 进阶配置
-
-### 自定义执行器沙箱模式
-
-在 checklist.yaml 中为每个步骤指定沙箱策略：
-
-```yaml
-steps:
-  - action: "只读分析"
-    codecgc:
-      kind: backend
-      codex_sandbox: read-only  # 只读模式
-
-  - action: "工作区写入"
-    codecgc:
-      kind: backend
-      codex_sandbox: workspace-write  # 可写工作区
-
-  - action: "完全访问"
-    codecgc:
-      kind: backend
-      codex_sandbox: danger-full-access  # 完全访问（危险）
-```
-
-### 保持执行器会话
-
-通过 `session_id` 在多个步骤间保持上下文：
-
-```yaml
-steps:
-  - action: "步骤 1"
-    codecgc:
-      kind: backend
-      session_id: my-session-123
-
-  - action: "步骤 2"
-    codecgc:
-      kind: backend
-      session_id: my-session-123  # 复用同一会话
-```
-
-### 获取完整执行日志
-
-```yaml
-steps:
-  - action: "调试任务"
-    codecgc:
-      kind: backend
-      return_all_messages: true  # 返回完整消息历史
+cgc-install
+cgc-status
 ```
 
----
-
-## 技术支持
-
-- **GitHub Issues**: https://github.com/hunyed15/CodeCGC/issues
-- **文档**: 查看 `codecgc/` 目录下的参考文档
-- **审计报告**: `codecgc/architecture/code-audit-2026-05-04.md`
+### 写入被 hook 拦截
 
----
+检查 `model-routing.yaml`。如果目标路径属于 unknown 或 shared，应该先明确文件归属或拆分任务，而不是绕过 hook。
 
-## 版本信息
+## 参考
 
-- **CodeCGC 版本**: 0.1.0
-- **最后更新**: 2026-05-04
-- **Python 要求**: >= 3.10
-- **Node.js 要求**: >= 20.0.0
+- `README.md`
+- `codecgc/reference/quickstart.md`
+- `codecgc/reference/onboarding.md`
+- `codecgc/reference/project-structure.md`
+- `codecgc/reference/policy-routing.md`
+- `codecgc/reference/troubleshooting.md`