feat: VitePress documentation site with GitHub Pages deployment

- VitePress config with zh-CN (default) + English i18n - 12 content pages: landing page + 5 guide pages per locale - GitHub Actions workflow for auto-deploy on docs/** changes - Logo SVG + local search enabled - Homepage URL updated to https://fengshao1227.github.io/ccg-workflow/
2026-03-12 14:00:46 +08:00
1 parent d58968055c
commit c80f58b086
@@ -0,0 +1,55 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - run: pnpm install
+
+      - name: Build docs
+        run: pnpm docs:build
+
+      - uses: actions/configure-pages@v4
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
@@ -49,8 +49,11 @@ ceshi/
 # Local spec workflows (OpenSpec 本地数据)
 .spec-workflow/
 openspec/
-docs/
 AGENTS.md
+
+# VitePress build output
+docs/.vitepress/dist/
+docs/.vitepress/cache/
 WINDOWS_FIX.md

 # Temp verification/notes
@@ -0,0 +1,126 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'CCG',
+  description: 'Claude + Codex + Gemini 多模型协作开发系统',
+
+  base: '/ccg-workflow/',
+  lastUpdated: true,
+  cleanUrls: true,
+
+  head: [
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/ccg-workflow/logo.svg' }],
+  ],
+
+  locales: {
+    root: {
+      label: '简体中文',
+      lang: 'zh-CN',
+      themeConfig: {
+        nav: [
+          { text: '指南', link: '/guide/getting-started' },
+          { text: '命令', link: '/guide/commands' },
+          {
+            text: '更多',
+            items: [
+              { text: '工作流', link: '/guide/workflows' },
+              { text: 'MCP 配置', link: '/guide/mcp' },
+              { text: '配置', link: '/guide/configuration' },
+            ],
+          },
+        ],
+        sidebar: [
+          {
+            text: '入门',
+            items: [
+              { text: '快速开始', link: '/guide/getting-started' },
+              { text: '命令参考', link: '/guide/commands' },
+            ],
+          },
+          {
+            text: '进阶',
+            items: [
+              { text: '工作流指南', link: '/guide/workflows' },
+              { text: 'MCP 配置', link: '/guide/mcp' },
+              { text: '配置说明', link: '/guide/configuration' },
+            ],
+          },
+        ],
+        editLink: {
+          pattern: 'https://github.com/fengshao1227/ccg-workflow/edit/main/docs/:path',
+          text: '在 GitHub 上编辑此页',
+        },
+        footer: {
+          message: '基于 MIT 许可发布',
+          copyright: 'Copyright © 2025-present CCG Contributors',
+        },
+        docFooter: {
+          prev: '上一页',
+          next: '下一页',
+        },
+        outline: {
+          label: '页面导航',
+        },
+        lastUpdated: {
+          text: '最后更新于',
+        },
+        returnToTopLabel: '回到顶部',
+        sidebarMenuLabel: '菜单',
+        darkModeSwitchLabel: '主题',
+      },
+    },
+    en: {
+      label: 'English',
+      lang: 'en',
+      description: 'Claude + Codex + Gemini Multi-Model Collaboration System',
+      themeConfig: {
+        nav: [
+          { text: 'Guide', link: '/en/guide/getting-started' },
+          { text: 'Commands', link: '/en/guide/commands' },
+          {
+            text: 'More',
+            items: [
+              { text: 'Workflows', link: '/en/guide/workflows' },
+              { text: 'MCP Config', link: '/en/guide/mcp' },
+              { text: 'Configuration', link: '/en/guide/configuration' },
+            ],
+          },
+        ],
+        sidebar: [
+          {
+            text: 'Getting Started',
+            items: [
+              { text: 'Quick Start', link: '/en/guide/getting-started' },
+              { text: 'Command Reference', link: '/en/guide/commands' },
+            ],
+          },
+          {
+            text: 'Advanced',
+            items: [
+              { text: 'Workflow Guide', link: '/en/guide/workflows' },
+              { text: 'MCP Configuration', link: '/en/guide/mcp' },
+              { text: 'Configuration', link: '/en/guide/configuration' },
+            ],
+          },
+        ],
+        editLink: {
+          pattern: 'https://github.com/fengshao1227/ccg-workflow/edit/main/docs/:path',
+          text: 'Edit this page on GitHub',
+        },
+        footer: {
+          message: 'Released under the MIT License',
+          copyright: 'Copyright © 2025-present CCG Contributors',
+        },
+      },
+    },
+  },
+
+  themeConfig: {
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/fengshao1227/ccg-workflow' },
+    ],
+    search: {
+      provider: 'local',
+    },
+  },
+})
@@ -0,0 +1,158 @@
+# Command Reference
+
+CCG provides 28 slash commands covering the full development lifecycle. All commands are accessed via `/ccg:*`.
+
+## Development Workflow
+
+| Command | Description | Model |
+|---------|-------------|-------|
+| `/ccg:workflow` | Full 6-phase workflow (research → ideate → plan → execute → optimize → review) | Codex + Gemini |
+| `/ccg:plan` | Multi-model collaborative planning (Phase 1-2) | Codex + Gemini |
+| `/ccg:execute` | Multi-model collaborative execution (Phase 3-5) | Codex + Gemini + Claude |
+| `/ccg:codex-exec` | Codex full execution (plan → code → review) | Codex + multi-model review |
+| `/ccg:feat` | Smart feature development | Auto-routed |
+| `/ccg:frontend` | Frontend tasks (fast mode) | Gemini |
+| `/ccg:backend` | Backend tasks (fast mode) | Codex |
+
+### Usage Examples
+
+```bash
+# Full workflow
+/ccg:workflow implement user authentication
+
+# Planning only (no execution)
+/ccg:plan implement user authentication
+
+# Frontend fast mode
+/ccg:frontend optimize login page responsive layout
+```
+
+## Analysis & Quality
+
+| Command | Description | Model |
+|---------|-------------|-------|
+| `/ccg:analyze` | Technical analysis | Codex + Gemini |
+| `/ccg:debug` | Problem diagnosis + fix | Codex + Gemini |
+| `/ccg:optimize` | Performance optimization | Codex + Gemini |
+| `/ccg:test` | Test generation | Auto-routed |
+| `/ccg:review` | Code review (auto git diff) | Codex + Gemini |
+| `/ccg:enhance` | Prompt enhancement | Built-in |
+
+### Usage Examples
+
+```bash
+# No args — auto-review recent changes
+/ccg:review
+
+# Analyze a specific module
+/ccg:analyze src/auth/ security
+
+# Generate tests
+/ccg:test src/utils/validator.ts
+```
+
+## OPSX Spec-Driven
+
+Integrates [OPSX](https://github.com/fission-ai/opsx) architecture to turn requirements into constraints.
+
+| Command | Description |
+|---------|-------------|
+| `/ccg:spec-init` | Initialize OPSX environment |
+| `/ccg:spec-research` | Requirements → Constraints |
+| `/ccg:spec-plan` | Constraints → Zero-decision plan |
+| `/ccg:spec-impl` | Execute plan + archive |
+| `/ccg:spec-review` | Dual-model cross-review |
+
+### Usage Examples
+
+```bash
+/ccg:spec-init
+/ccg:spec-research implement user auth
+/ccg:spec-plan
+/ccg:spec-impl
+/ccg:spec-review
+```
+
+::: tip
+You can `/clear` between phases — state is persisted in the `openspec/` directory.
+:::
+
+## Agent Teams (v1.7.60+)
+
+Leverage Claude Code Agent Teams to spawn multiple Builder teammates for parallel coding.
+
+| Command | Description |
+|---------|-------------|
+| `/ccg:team-research` | Requirements → constraints (parallel exploration) |
+| `/ccg:team-plan` | Constraints → parallel implementation plan |
+| `/ccg:team-exec` | Spawn Builder teammates for parallel coding |
+| `/ccg:team-review` | Dual-model cross-review |
+
+::: warning Prerequisite
+Enable Agent Teams in `settings.json`:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+:::
+
+### Usage Examples
+
+```bash
+/ccg:team-research implement kanban API
+# /clear
+/ccg:team-plan kanban-api
+# /clear
+/ccg:team-exec
+# /clear
+/ccg:team-review
+```
+
+## Git Tools
+
+| Command | Description |
+|---------|-------------|
+| `/ccg:commit` | Smart commit (conventional commit format) |
+| `/ccg:rollback` | Interactive rollback |
+| `/ccg:clean-branches` | Clean merged branches |
+| `/ccg:worktree` | Worktree management |
+
+### Usage Examples
+
+```bash
+# Smart commit (auto-analyze diff)
+/ccg:commit
+
+# Interactive rollback
+/ccg:rollback
+
+# Clean merged branches (dry-run by default)
+/ccg:clean-branches
+```
+
+## Project Setup
+
+| Command | Description |
+|---------|-------------|
+| `/ccg:init` | Initialize project CLAUDE.md |
+| `/ccg:context` | Project context management (.context/ init, log, compress, history) |
+
+### Usage Examples
+
+```bash
+# Initialize project AI context
+/ccg:init
+
+# Initialize .context directory
+/ccg:context init
+
+# Log a decision
+/ccg:context log "Chose PostgreSQL for JSONB support"
+
+# View context history
+/ccg:context history
+```
@@ -0,0 +1,93 @@
+# Configuration
+
+## Directory Structure
+
+CCG installation layout:
+
+```
+~/.claude/
+├── commands/ccg/       # 28 slash commands
+├── agents/ccg/         # 4 sub-agents
+├── skills/ccg/         # Quality gates + multi-agent orchestration
+├── bin/codeagent-wrapper
+└── .ccg/
+    ├── config.toml     # CCG configuration
+    └── prompts/
+        ├── codex/      # 6 Codex expert prompts
+        └── gemini/     # 7 Gemini expert prompts
+```
+
+## Environment Variables
+
+Configure in `~/.claude/settings.json` under `"env"`:
+
+| Variable | Description | Default | When to change |
+|----------|-------------|---------|----------------|
+| `CODEAGENT_POST_MESSAGE_DELAY` | Wait after Codex completion (sec) | `5` | Set to `1` if Codex process hangs |
+| `CODEX_TIMEOUT` | Wrapper execution timeout (sec) | `7200` | Increase for very long tasks |
+| `BASH_DEFAULT_TIMEOUT_MS` | Claude Code Bash timeout (ms) | `120000` | Increase if commands time out |
+| `BASH_MAX_TIMEOUT_MS` | Claude Code Bash max timeout (ms) | `600000` | Increase for long builds |
+
+::: details Example settings.json
+
+```json
+{
+  "env": {
+    "CODEAGENT_POST_MESSAGE_DELAY": "1",
+    "CODEX_TIMEOUT": "7200",
+    "BASH_DEFAULT_TIMEOUT_MS": "600000",
+    "BASH_MAX_TIMEOUT_MS": "3600000"
+  }
+}
+```
+:::
+
+## Fixed Configuration
+
+Since v1.7.0, the following are no longer customizable:
+
+| Setting | Fixed Value | Reason |
+|---------|------------|--------|
+| Frontend model | Gemini | Best at UI/CSS/components |
+| Backend model | Codex | Best at logic/algorithms/debugging |
+| Collaboration mode | smart | Best practice |
+| Command count | 28 | All installed |
+
+## Utilities
+
+```bash
+npx ccg-workflow menu  # Select "Tools"
+```
+
+- **ccusage** — Claude Code usage analytics
+- **CCometixLine** — Status bar tool (Git + usage tracking)
+
+## FAQ
+
+### Codex CLI 0.80.0 process does not exit
+
+In `--json` mode, Codex does not automatically exit after output completion.
+
+**Fix**: Set `CODEAGENT_POST_MESSAGE_DELAY=1`.
+
+### Node 18 throws SyntaxError
+
+CCG depends on `ora@9.x`, which requires Node >= 20.
+
+**Fix**: Upgrade to Node 20+.
+
+### MCP tools not working
+
+**Fix**: Run `npx ccg-workflow diagnose-mcp` to check configuration.
+
+### Agent Teams commands unavailable
+
+**Fix**: Add to `settings.json`:
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
@@ -0,0 +1,103 @@
+# Getting Started
+
+## Architecture
+
+```
+Claude Code (Orchestrator)
+       │
+   ┌───┴───┐
+   ↓       ↓
+Codex   Gemini
+(Backend) (Frontend)
+   │       │
+   └───┬───┘
+       ↓
+  Unified Patch
+```
+
+External models have no write access — they only return patches, which Claude reviews before applying.
+
+## Prerequisites
+
+| Dependency | Required | Notes |
+|------------|----------|-------|
+| **Node.js 20+** | Yes | `ora@9.x` requires Node >= 20 |
+| **Claude Code CLI** | Yes | [Install guide](#install-claude-code) |
+| **jq** | Yes | Used for auto-authorization hook |
+| **Codex CLI** | No | Enables backend routing |
+| **Gemini CLI** | No | Enables frontend routing |
+
+## Installation
+
+```bash
+npx ccg-workflow
+```
+
+On first run, CCG prompts you to select a language (English / Chinese). This preference is saved for all future sessions.
+
+### Install jq
+
+::: code-group
+
+```bash [macOS]
+brew install jq
+```
+
+```bash [Debian / Ubuntu]
+sudo apt install jq
+```
+
+```bash [RHEL / CentOS]
+sudo yum install jq
+```
+
+```bash [Windows]
+choco install jq
+# or
+scoop install jq
+```
+
+:::
+
+### Install Claude Code
+
+```bash
+npx ccg-workflow menu  # Select "Install Claude Code"
+```
+
+Supports: npm, homebrew, curl, powershell, cmd.
+
+## Verify Installation
+
+After installation, type in Claude Code:
+
+```
+/ccg:workflow hello
+```
+
+If you see multi-model collaboration output, the installation is successful.
+
+## Update
+
+```bash
+# npx users
+npx ccg-workflow@latest
+
+# npm global users
+npm install -g ccg-workflow@latest
+```
+
+## Uninstall
+
+```bash
+npx ccg-workflow  # Select "Uninstall"
+
+# npm global users need this extra step
+npm uninstall -g ccg-workflow
+```
+
+## Next Steps
+
+- [Command Reference](/en/guide/commands) — See all 28 commands
+- [Workflow Guide](/en/guide/workflows) — Learn the three main workflows
+- [MCP Configuration](/en/guide/mcp) — Enhance code retrieval
@@ -0,0 +1,88 @@
+# MCP Configuration
+
+MCP (Model Context Protocol) tools enhance Claude Code's code retrieval and search capabilities. CCG supports multiple MCP providers.
+
+## Setup
+
+```bash
+npx ccg-workflow menu  # Select "Configure MCP"
+```
+
+## Code Retrieval (choose one)
+
+### ace-tool (Recommended)
+
+Code search service based on Augment Code, providing semantic retrieval via `search_context`.
+
+- **Pros**: High search quality, good context understanding
+- **Note**: Requires Augment Code account or third-party proxy
+- [Official](https://augmentcode.com/) | [Third-party proxy](https://acemcp.heroman.wtf/)
+
+### fast-context (Recommended)
+
+AI-powered code search based on Windsurf Fast Context, no full-repo indexing required.
+
+- **Pros**: No indexing needed, fast search
+- **Note**: Requires Windsurf account
+- Supports optional API Key and `FC_INCLUDE_SNIPPETS` mode
+
+### ContextWeaver (Alternative)
+
+Local hybrid search engine combining Embedding + Rerank.
+
+- **Pros**: Fully local, works offline
+- **Note**: Requires SiliconFlow API Key (free)
+
+## Optional Tools
+
+| Tool | Description | Requires API Key |
+|------|-------------|-----------------|
+| **Context7** | Latest library documentation | No (auto-installed) |
+| **Playwright** | Browser automation / testing | No |
+| **DeepWiki** | Knowledge base queries | No |
+| **Exa** | Search engine | Yes |
+
+## MCP Sync
+
+CCG automatically syncs MCP configuration to Codex and Gemini:
+
+- **Codex sync**: `~/.codex/config.toml` — Codex can use MCP search when running `/ccg:codex-exec`
+- **Gemini sync**: `~/.gemini/settings.json` — Gemini can use the same MCP tools
+
+Synced MCP server IDs: `grok-search`, `context7`, `ace-tool`, `contextweaver`, `fast-context`
+
+## Auto-Authorization Hook
+
+CCG automatically installs a Hook to authorize `codeagent-wrapper` commands (requires [jq](https://jqlang.github.io/jq/)).
+
+::: details Manual setup (for versions before v1.7.71)
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.command' 2>/dev/null | grep -q 'codeagent-wrapper' && echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\", \"permissionDecisionReason\": \"codeagent-wrapper auto-approved\"}}' || true",
+            "timeout": 1
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+:::
+
+## Diagnostics
+
+If MCP tools aren't working, run the diagnostic command:
+
+```bash
+npx ccg-workflow diagnose-mcp
+```
@@ -0,0 +1,123 @@
+# Workflow Guide
+
+CCG provides three main workflows for different scenarios.
+
+## Planning & Execution Separation
+
+The most basic workflow: plan first, execute later, with human review in between.
+
+```bash
+# 1. Generate implementation plan
+/ccg:plan implement user authentication
+
+# 2. Review the plan (editable)
+# Plan saved to .claude/plan/user-auth.md
+
+# 3a. Execute (Claude refactors) — fine-grained control
+/ccg:execute .claude/plan/user-auth.md
+
+# 3b. Execute (Codex does everything) — efficient, low Claude token usage
+/ccg:codex-exec .claude/plan/user-auth.md
+```
+
+### execute vs codex-exec
+
+| Dimension | `/ccg:execute` | `/ccg:codex-exec` |
+|-----------|---------------|-------------------|
+| Executor | Claude-led + Codex/Gemini assist | Codex handles everything |
+| Token cost | Higher (Claude processes each step) | Very low (Claude only reviews) |
+| Best for | Complex tasks needing fine control | Clear, independently executable tasks |
+| MCP search | Claude executes | Codex executes (needs MCP sync) |
+
+## OPSX Spec-Driven Workflow
+
+Integrates [OPSX](https://github.com/fission-ai/opsx) to turn requirements into constraints. Best for scenarios needing **strict control**.
+
+```bash
+/ccg:spec-init                          # Initialize OPSX environment
+/ccg:spec-research implement user auth  # Research → constraints
+/ccg:spec-plan                          # Parallel analysis → zero-decision plan
+/ccg:spec-impl                          # Execute the plan
+/ccg:spec-review                        # Independent review (anytime)
+```
+
+### Key Features
+
+- **Constraint-driven**: Requirements become verifiable constraints, not vague descriptions
+- **Zero-decision plan**: Execution requires no decisions — all decisions made during planning
+- **Persistent state**: State stored in `openspec/` directory, `/clear` between phases to free context
+
+::: tip
+`/ccg:spec-*` commands internally call `/opsx:*`. If using OPSX directly, use `/opsx:*` commands.
+:::
+
+## Agent Teams Parallel Workflow
+
+Leverage Claude Code Agent Teams to spawn multiple Builder teammates for parallel coding. Best for tasks **decomposable into 3+ independent modules**.
+
+```bash
+/ccg:team-research implement kanban API  # 1. Requirements → constraints
+# /clear
+/ccg:team-plan kanban-api               # 2. Plan → parallel tasks
+# /clear
+/ccg:team-exec                          # 3. Builders code in parallel
+# /clear
+/ccg:team-review                        # 4. Dual-model cross-review
+```
+
+### vs Traditional Workflow
+
+| Dimension | Traditional | Agent Teams |
+|-----------|------------|-------------|
+| Context | Continuous conversation | `/clear` between steps |
+| State passing | Conversation context | Files (.claude/plan/) |
+| Parallelism | Sequential | Multiple Builders in parallel |
+| Best for | General tasks | 3+ independent modules |
+
+### Workflow Diagram
+
+```
+team-research          team-plan           team-exec          team-review
+     │                    │                    │                   │
+  Analyze             Plan & split       Builder 1 ──┐       Codex review
+     │                    │              Builder 2 ──┤            │
+  Constraints          Parallel plan     Builder 3 ──┘       Gemini review
+     │                    │                    │                   │
+     ↓                    ↓                    ↓                   ↓
+  constraints.md    plan/*.md           Code output        Review report
+```
+
+## Full 6-Phase Workflow
+
+`/ccg:workflow` is the most complete workflow with 6 phases:
+
+1. **Research** — Analyze requirements, understand context
+2. **Ideate** — Propose solutions
+3. **Plan** — Create implementation plan (Codex + Gemini parallel analysis)
+4. **Execute** — Implement the plan (model routing: frontend → Gemini, backend → Codex)
+5. **Optimize** — Performance optimization and code quality
+6. **Review** — Multi-model cross-review
+
+```bash
+/ccg:workflow implement a complete user auth system with registration, login, and JWT tokens
+```
+
+::: info
+For large tasks, consider using `/ccg:plan` + `/ccg:execute` for step-by-step execution with plan review in between.
+:::
+
+## Workflow Selection Guide
+
+```
+Receive task
+  │
+  ├─ Simple / clear? ──────────→ /ccg:frontend or /ccg:backend
+  │
+  ├─ Needs planning? ──────────→ /ccg:plan + /ccg:execute
+  │
+  ├─ Needs strict constraints? ─→ /ccg:spec-* series
+  │
+  ├─ Decomposable into 3+ modules? → /ccg:team-* series
+  │
+  └─ Full end-to-end? ─────────→ /ccg:workflow
+```
@@ -0,0 +1,41 @@
+---
+layout: home
+
+hero:
+  name: CCG
+  text: Claude + Codex + Gemini
+  tagline: Multi-Model Collaboration System — Claude orchestrates, Codex handles backend, Gemini handles frontend
+  image:
+    src: /logo.svg
+    alt: CCG
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /en/guide/getting-started
+    - theme: alt
+      text: Commands
+      link: /en/guide/commands
+    - theme: alt
+      text: GitHub
+      link: https://github.com/fengshao1227/ccg-workflow
+
+features:
+  - icon: 🔀
+    title: Zero-Config Model Routing
+    details: Frontend tasks automatically go to Gemini, backend tasks to Codex. No manual switching.
+  - icon: 🔒
+    title: Security by Design
+    details: External models have no write access. They return patches; Claude reviews before applying.
+  - icon: 🛠️
+    title: 28 Slash Commands
+    details: From planning to execution, git workflow to code review, all accessible via /ccg:*.
+  - icon: 📐
+    title: Spec-Driven Development
+    details: Integrates OPSX to turn vague requirements into verifiable constraints, eliminating AI improvisation.
+  - icon: 👥
+    title: Agent Teams Parallel
+    details: Spawn multiple Builder teammates for parallel coding. Ideal for tasks with 3+ independent modules.
+  - icon: 📦
+    title: One-Line Install
+    details: npx ccg-workflow — supports macOS, Linux, and Windows.
+---
@@ -0,0 +1,158 @@
+# 命令参考
+
+CCG 提供 28 个斜杠命令，覆盖开发全流程。所有命令通过 `/ccg:*` 访问。
+
+## 开发工作流
+
+| 命令 | 说明 | 模型 |
+|------|------|------|
+| `/ccg:workflow` | 6 阶段完整工作流（研究→构思→计划→执行→优化→评审） | Codex + Gemini |
+| `/ccg:plan` | 多模型协作规划（Phase 1-2） | Codex + Gemini |
+| `/ccg:execute` | 多模型协作执行（Phase 3-5） | Codex + Gemini + Claude |
+| `/ccg:codex-exec` | Codex 全权执行（计划 → 代码 → 审核） | Codex + 多模型审核 |
+| `/ccg:feat` | 智能功能开发 | 自动路由 |
+| `/ccg:frontend` | 前端任务（快速模式） | Gemini |
+| `/ccg:backend` | 后端任务（快速模式） | Codex |
+
+### 使用示例
+
+```bash
+# 完整工作流
+/ccg:workflow 实现用户认证功能
+
+# 只做规划（不执行）
+/ccg:plan 实现用户认证功能
+
+# 前端快速模式
+/ccg:frontend 优化登录页面的响应式布局
+```
+
+## 分析与质量
+
+| 命令 | 说明 | 模型 |
+|------|------|------|
+| `/ccg:analyze` | 技术分析 | Codex + Gemini |
+| `/ccg:debug` | 问题诊断 + 修复 | Codex + Gemini |
+| `/ccg:optimize` | 性能优化 | Codex + Gemini |
+| `/ccg:test` | 测试生成 | 自动路由 |
+| `/ccg:review` | 代码审查（自动 git diff） | Codex + Gemini |
+| `/ccg:enhance` | Prompt 增强 | 内置 |
+
+### 使用示例
+
+```bash
+# 无参数自动审查最近改动
+/ccg:review
+
+# 分析特定模块
+/ccg:analyze src/auth/ 的安全性
+
+# 生成测试
+/ccg:test src/utils/validator.ts
+```
+
+## OPSX 规范驱动
+
+集成 [OPSX](https://github.com/fission-ai/opsx) 架构，把需求变成约束。
+
+| 命令 | 说明 |
+|------|------|
+| `/ccg:spec-init` | 初始化 OPSX 环境 |
+| `/ccg:spec-research` | 需求 → 约束集 |
+| `/ccg:spec-plan` | 约束 → 零决策计划 |
+| `/ccg:spec-impl` | 按计划执行 + 归档 |
+| `/ccg:spec-review` | 双模型交叉审查 |
+
+### 使用示例
+
+```bash
+/ccg:spec-init
+/ccg:spec-research 实现用户认证
+/ccg:spec-plan
+/ccg:spec-impl
+/ccg:spec-review
+```
+
+::: tip
+每阶段之间可 `/clear`，状态存在 `openspec/` 目录，不怕上下文爆。
+:::
+
+## Agent Teams（v1.7.60+）
+
+利用 Claude Code Agent Teams 实验特性，spawn 多个 Builder teammates 并行写代码。
+
+| 命令 | 说明 |
+|------|------|
+| `/ccg:team-research` | 需求 → 约束集（并行探索） |
+| `/ccg:team-plan` | 约束 → 并行实施计划 |
+| `/ccg:team-exec` | spawn Builder teammates 并行写代码 |
+| `/ccg:team-review` | 双模型交叉审查 |
+
+::: warning 前置条件
+需在 `settings.json` 中启用实验特性：
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
+:::
+
+### 使用示例
+
+```bash
+/ccg:team-research 实现实时协作看板 API
+# /clear
+/ccg:team-plan kanban-api
+# /clear
+/ccg:team-exec
+# /clear
+/ccg:team-review
+```
+
+## Git 工具
+
+| 命令 | 说明 |
+|------|------|
+| `/ccg:commit` | 智能提交（conventional commit 格式） |
+| `/ccg:rollback` | 交互式回滚 |
+| `/ccg:clean-branches` | 清理已合并分支 |
+| `/ccg:worktree` | Worktree 管理 |
+
+### 使用示例
+
+```bash
+# 智能提交（自动分析 diff）
+/ccg:commit
+
+# 交互式回滚
+/ccg:rollback
+
+# 清理已合并分支（默认 dry-run）
+/ccg:clean-branches
+```
+
+## 项目管理
+
+| 命令 | 说明 |
+|------|------|
+| `/ccg:init` | 初始化项目 CLAUDE.md |
+| `/ccg:context` | 项目上下文管理（.context 初始化/日志/压缩/历史） |
+
+### 使用示例
+
+```bash
+# 初始化项目 AI 上下文
+/ccg:init
+
+# 初始化 .context 目录
+/ccg:context init
+
+# 记录决策日志
+/ccg:context log "选择 PostgreSQL 因为需要 JSONB 支持"
+
+# 查看上下文历史
+/ccg:context history
+```
@@ -0,0 +1,93 @@
+# 配置说明
+
+## 目录结构
+
+CCG 安装后的文件布局：
+
+```
+~/.claude/
+├── commands/ccg/       # 28 个斜杠命令
+├── agents/ccg/         # 4 个子智能体
+├── skills/ccg/         # 质量关卡 + 多 Agent 协同
+├── bin/codeagent-wrapper
+└── .ccg/
+    ├── config.toml     # CCG 配置
+    └── prompts/
+        ├── codex/      # 6 个 Codex 专家提示词
+        └── gemini/     # 7 个 Gemini 专家提示词
+```
+
+## 环境变量
+
+在 `~/.claude/settings.json` 的 `"env"` 中配置：
+
+| 变量 | 说明 | 默认值 | 何时修改 |
+|------|------|--------|----------|
+| `CODEAGENT_POST_MESSAGE_DELAY` | Codex 完成后等待时间（秒） | `5` | Codex 进程挂起时设为 `1` |
+| `CODEX_TIMEOUT` | wrapper 执行超时（秒） | `7200` | 超长任务时增大 |
+| `BASH_DEFAULT_TIMEOUT_MS` | Claude Code Bash 超时（毫秒） | `120000` | 命令超时时增大 |
+| `BASH_MAX_TIMEOUT_MS` | Claude Code Bash 最大超时（毫秒） | `600000` | 长时间构建时增大 |
+
+::: details settings.json 示例
+
+```json
+{
+  "env": {
+    "CODEAGENT_POST_MESSAGE_DELAY": "1",
+    "CODEX_TIMEOUT": "7200",
+    "BASH_DEFAULT_TIMEOUT_MS": "600000",
+    "BASH_MAX_TIMEOUT_MS": "3600000"
+  }
+}
+```
+:::
+
+## 固定配置
+
+v1.7.0 起，以下配置不再支持自定义：
+
+| 项目 | 固定值 | 原因 |
+|------|--------|------|
+| 前端模型 | Gemini | 擅长 UI/CSS/组件 |
+| 后端模型 | Codex | 擅长逻辑/算法/调试 |
+| 协作模式 | smart | 最佳实践 |
+| 命令数量 | 28 个 | 全部安装 |
+
+## 实用工具
+
+```bash
+npx ccg-workflow menu  # 选择「实用工具」
+```
+
+- **ccusage** — Claude Code 用量分析
+- **CCometixLine** — 状态栏工具（Git + 用量跟踪）
+
+## 常见问题
+
+### Codex CLI 0.80.0 进程不退出
+
+`--json` 模式下 Codex 完成输出后进程不会自动退出。
+
+**解决**：将 `CODEAGENT_POST_MESSAGE_DELAY` 设为 `1`。
+
+### Node 18 报 SyntaxError
+
+CCG 依赖 `ora@9.x`，要求 Node >= 20。
+
+**解决**：升级到 Node 20+。
+
+### MCP 工具不生效
+
+**解决**：运行 `npx ccg-workflow diagnose-mcp` 检查配置。
+
+### Agent Teams 命令不可用
+
+**解决**：在 `settings.json` 中添加：
+
+```json
+{
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}
+```
@@ -0,0 +1,103 @@
+# 快速开始
+
+## 架构概览
+
+```
+Claude Code (编排)
+       │
+   ┌───┴───┐
+   ↓       ↓
+Codex   Gemini
+(后端)   (前端)
+   │       │
+   └───┬───┘
+       ↓
+  Unified Patch
+```
+
+外部模型无写入权限，仅返回 Patch，由 Claude 审核后应用。
+
+## 前置条件
+
+| 依赖 | 必需 | 说明 |
+|------|------|------|
+| **Node.js 20+** | 是 | `ora@9.x` 要求 Node >= 20 |
+| **Claude Code CLI** | 是 | [安装方法](#安装-claude-code) |
+| **jq** | 是 | 用于自动授权 Hook |
+| **Codex CLI** | 否 | 启用后端路由 |
+| **Gemini CLI** | 否 | 启用前端路由 |
+
+## 安装
+
+```bash
+npx ccg-workflow
+```
+
+首次运行会提示选择语言（简体中文 / English），选择后自动保存。
+
+### 安装 jq
+
+::: code-group
+
+```bash [macOS]
+brew install jq
+```
+
+```bash [Debian / Ubuntu]
+sudo apt install jq
+```
+
+```bash [RHEL / CentOS]
+sudo yum install jq
+```
+
+```bash [Windows]
+choco install jq
+# 或
+scoop install jq
+```
+
+:::
+
+### 安装 Claude Code
+
+```bash
+npx ccg-workflow menu  # 选择「安装 Claude Code」
+```
+
+支持：npm、homebrew、curl、powershell、cmd。
+
+## 验证安装
+
+安装完成后，在 Claude Code 中输入：
+
+```
+/ccg:workflow 你好
+```
+
+如果看到多模型协作输出，说明安装成功。
+
+## 更新
+
+```bash
+# npx 用户
+npx ccg-workflow@latest
+
+# npm 全局用户
+npm install -g ccg-workflow@latest
+```
+
+## 卸载
+
+```bash
+npx ccg-workflow  # 选择「卸载工作流」
+
+# npm 全局用户需额外执行
+npm uninstall -g ccg-workflow
+```
+
+## 下一步
+
+- [命令参考](/guide/commands) — 查看全部 28 个命令
+- [工作流指南](/guide/workflows) — 学习三种主要工作流
+- [MCP 配置](/guide/mcp) — 增强代码检索能力
@@ -0,0 +1,88 @@
+# MCP 配置
+
+MCP（Model Context Protocol）工具可以增强 Claude Code 的代码检索和搜索能力。CCG 支持多个 MCP 提供者。
+
+## 配置方式
+
+```bash
+npx ccg-workflow menu  # 选择「配置 MCP」
+```
+
+## 代码检索（多选一）
+
+### ace-tool（推荐）
+
+基于 Augment Code 的代码搜索服务，通过 `search_context` 提供语义检索。
+
+- **优势**：搜索质量高、上下文理解好
+- **注意**：需要 Augment Code 账号或第三方中转
+- [官方](https://augmentcode.com/) | [第三方中转](https://acemcp.heroman.wtf/)
+
+### fast-context（推荐）
+
+基于 Windsurf Fast Context 的 AI 驱动代码搜索，无需全量索引。
+
+- **优势**：无需索引、搜索速度快
+- **注意**：需要 Windsurf 账号
+- 支持可选 API Key 和 `FC_INCLUDE_SNIPPETS` 模式
+
+### ContextWeaver（备选）
+
+本地混合搜索引擎，结合 Embedding + Rerank。
+
+- **优势**：完全本地运行、可离线使用
+- **注意**：需要硅基流动 API Key（免费）
+
+## 辅助工具（可选）
+
+| 工具 | 说明 | 需要 API Key |
+|------|------|-------------|
+| **Context7** | 获取最新库文档 | 否（自动安装） |
+| **Playwright** | 浏览器自动化 / 测试 | 否 |
+| **DeepWiki** | 知识库查询 | 否 |
+| **Exa** | 搜索引擎 | 是 |
+
+## MCP 同步
+
+CCG 会自动将 MCP 配置同步到 Codex 和 Gemini：
+
+- **Codex 同步**：`~/.codex/config.toml` — 执行 `/ccg:codex-exec` 时 Codex 可直接使用 MCP 搜索
+- **Gemini 同步**：`~/.gemini/settings.json` — Gemini 可使用相同的 MCP 工具
+
+同步的 MCP 服务器 ID：`grok-search`、`context7`、`ace-tool`、`contextweaver`、`fast-context`
+
+## 自动授权 Hook
+
+CCG 安装时自动写入 Hook，授权 `codeagent-wrapper` 命令（需要 [jq](https://jqlang.github.io/jq/)）。
+
+::: details 手动配置（v1.7.71 之前的版本）
+
+在 `~/.claude/settings.json` 中添加：
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.command' 2>/dev/null | grep -q 'codeagent-wrapper' && echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\", \"permissionDecisionReason\": \"codeagent-wrapper auto-approved\"}}' || true",
+            "timeout": 1
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+:::
+
+## 诊断
+
+如果 MCP 工具不工作，运行诊断命令：
+
+```bash
+npx ccg-workflow diagnose-mcp
+```
@@ -0,0 +1,123 @@
+# 工作流指南
+
+CCG 提供三种主要工作流，适用于不同场景。
+
+## 规划与执行分离
+
+最基础的工作流：先规划，再执行，中间可以人工审查和修改计划。
+
+```bash
+# 1. 生成实施计划
+/ccg:plan 实现用户认证功能
+
+# 2. 审查计划（可修改）
+# 计划保存至 .claude/plan/user-auth.md
+
+# 3a. 执行计划（Claude 重构）— 精细控制
+/ccg:execute .claude/plan/user-auth.md
+
+# 3b. 执行计划（Codex 全权）— 高效执行，Claude token 极低
+/ccg:codex-exec .claude/plan/user-auth.md
+```
+
+### 选择 execute 还是 codex-exec？
+
+| 维度 | `/ccg:execute` | `/ccg:codex-exec` |
+|------|---------------|-------------------|
+| 执行者 | Claude 主导 + Codex/Gemini 辅助 | Codex 全权执行 |
+| Token 消耗 | 较高（Claude 处理每一步） | 极低（Claude 只审核） |
+| 适用场景 | 需要精细控制的复杂任务 | 明确的、可独立执行的任务 |
+| MCP 搜索 | Claude 执行 | Codex 执行（需同步 MCP） |
+
+## OPSX 规范驱动工作流
+
+集成 [OPSX](https://github.com/fission-ai/opsx) 架构，把需求变成约束，让 AI 没法自由发挥。适合需要**严格控制**的场景。
+
+```bash
+/ccg:spec-init                       # 初始化 OPSX 环境
+/ccg:spec-research 实现用户认证        # 研究需求 → 输出约束集
+/ccg:spec-plan                       # 并行分析 → 零决策计划
+/ccg:spec-impl                       # 按计划执行
+/ccg:spec-review                     # 独立审查（随时可用）
+```
+
+### 工作流特点
+
+- **约束驱动**：需求不再是模糊描述，而是可验证的约束条件
+- **零决策计划**：执行阶段不需要做任何决策，所有决策在规划阶段完成
+- **状态持久化**：状态存在 `openspec/` 目录，每阶段可 `/clear` 释放上下文
+
+::: tip
+`/ccg:spec-*` 命令内部调用 `/opsx:*`。如果你直接使用 OPSX，请使用 `/opsx:*` 命令。
+:::
+
+## Agent Teams 并行工作流
+
+利用 Claude Code Agent Teams 实验特性，spawn 多个 Builder teammates 并行写代码。适合**可拆分为 3+ 独立模块**的任务。
+
+```bash
+/ccg:team-research 实现实时协作看板 API  # 1. 需求 → 约束集
+# /clear
+/ccg:team-plan kanban-api               # 2. 规划 → 并行计划
+# /clear
+/ccg:team-exec                          # 3. Builder 并行写代码
+# /clear
+/ccg:team-review                        # 4. 双模型交叉审查
+```
+
+### vs 传统工作流
+
+| 维度 | 传统工作流 | Agent Teams |
+|------|-----------|-------------|
+| 上下文 | 连续对话 | 每步 `/clear` 隔离 |
+| 状态传递 | 对话上下文 | 文件（.claude/plan/） |
+| 并行度 | 串行 | 多 Builder 并行 |
+| 适用场景 | 通用 | 3+ 独立模块 |
+
+### 工作流图
+
+```
+team-research          team-plan           team-exec          team-review
+     │                    │                    │                   │
+  需求分析            规划拆分           Builder 1 ──┐         Codex 审查
+     │                    │            Builder 2 ──┤              │
+  约束输出            并行计划          Builder 3 ──┘         Gemini 审查
+     │                    │                    │                   │
+     ↓                    ↓                    ↓                   ↓
+  constraints.md    plan/*.md          代码产出            审查报告
+```
+
+## 完整 6 阶段工作流
+
+`/ccg:workflow` 是最完整的工作流，包含 6 个阶段：
+
+1. **研究** — 分析需求，理解上下文
+2. **构思** — 提出解决方案
+3. **计划** — 制定实施计划（Codex + Gemini 并行分析）
+4. **执行** — 按计划实施（模型路由：前端 → Gemini，后端 → Codex）
+5. **优化** — 性能优化和代码质量
+6. **评审** — 多模型交叉审查
+
+```bash
+/ccg:workflow 实现完整的用户认证系统，包含注册、登录、JWT 令牌
+```
+
+::: info
+对于大型任务，建议使用 `/ccg:plan` + `/ccg:execute` 分步执行，以便中间审查计划。
+:::
+
+## 工作流选择指南
+
+```
+收到任务
+  │
+  ├─ 简单/明确？ ────────────→ /ccg:frontend 或 /ccg:backend
+  │
+  ├─ 需要规划？ ─────────────→ /ccg:plan + /ccg:execute
+  │
+  ├─ 需要严格约束？ ─────────→ /ccg:spec-* 系列
+  │
+  ├─ 可拆分 3+ 模块？ ──────→ /ccg:team-* 系列
+  │
+  └─ 完整端到端？ ───────────→ /ccg:workflow
+```
@@ -0,0 +1,62 @@
+---
+layout: home
+
+hero:
+  name: CCG
+  text: Claude + Codex + Gemini
+  tagline: 多模型协作开发系统 — Claude 编排，Codex 后端，Gemini 前端
+  image:
+    src: /logo.svg
+    alt: CCG
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /guide/getting-started
+    - theme: alt
+      text: 命令参考
+      link: /guide/commands
+    - theme: alt
+      text: GitHub
+      link: https://github.com/fengshao1227/ccg-workflow
+
+features:
+  - icon: 🔀
+    title: 零配置模型路由
+    details: 前端任务自动走 Gemini，后端任务自动走 Codex，无需手动切换模型。
+  - icon: 🔒
+    title: 安全设计
+    details: 外部模型无写入权限，仅返回 Patch，由 Claude 审核后应用。
+  - icon: 🛠️
+    title: 28 个斜杠命令
+    details: 从规划到执行、Git 工作流到代码审查，通过 /ccg:* 一站式访问。
+  - icon: 📐
+    title: 规范驱动开发
+    details: 集成 OPSX，将模糊需求变成可验证约束，让 AI 没法自由发挥。
+  - icon: 👥
+    title: Agent Teams 并行
+    details: spawn 多个 Builder teammates 并行写代码，适合 3+ 独立模块的任务。
+  - icon: 📦
+    title: 一键安装
+    details: npx ccg-workflow 一行命令，支持 macOS、Linux、Windows 三平台。
+---
+
+<style>
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe 30%, #41d1ff);
+  --vp-home-hero-image-background-image: linear-gradient(-45deg, #bd34fe50 50%, #47caff50 50%);
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+</style>
@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" fill="none">
+  <defs>
+    <linearGradient id="g1" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#bd34fe"/>
+      <stop offset="100%" stop-color="#41d1ff"/>
+    </linearGradient>
+  </defs>
+  <rect width="128" height="128" rx="24" fill="url(#g1)"/>
+  <text x="64" y="52" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="22" font-weight="700" fill="white">CCG</text>
+  <text x="64" y="78" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="rgba(255,255,255,0.85)">Claude+Codex</text>
+  <text x="64" y="94" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="11" fill="rgba(255,255,255,0.85)">+Gemini</text>
+</svg>
@@ -77,7 +77,10 @@
    "prepublishOnly": "pnpm build",
    "test": "vitest run",
    "lint": "eslint",
-    "lint:fix": "eslint --fix"
+    "lint:fix": "eslint --fix",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
  },
  "dependencies": {
    "ansis": "^4.1.0",
@@ -90,6 +93,9 @@
    "pathe": "^2.0.3",
    "smol-toml": "^1.4.2"
  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild"]
+  },
  "devDependencies": {
    "@antfu/eslint-config": "^5.4.1",
    "@types/fs-extra": "^11.0.4",
@@ -98,6 +104,7 @@
    "tsx": "^4.20.5",
    "typescript": "^5.9.2",
    "unbuild": "^3.6.1",
+    "vitepress": "^1.6.4",
    "vitest": "^3.1.1"
  }
 }