diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..a0449cc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,38 @@ +--- +name: Bug Report +about: Report a bug in CCG workflow +title: "[bug] " +labels: bug +assignees: '' +--- + +## Environment + +- **CCG version**: (e.g., 1.7.75) +- **Node.js version**: (e.g., 20.11.0) +- **OS**: (e.g., macOS 15.1 / Ubuntu 24.04 / Windows 11) +- **Claude Code version**: (e.g., 1.0.26) + +## Description + + + +## Expected Behavior + + + +## Steps to Reproduce + +1. ... +2. ... +3. ... + +## Error Output + +``` + +``` + +## Additional Context + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..c2174f2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: Feature Request +about: Suggest a new feature or improvement +title: "[feat] " +labels: enhancement +assignees: '' +--- + +## Problem + + + +## Proposed Solution + + + +## Alternatives Considered + + + +## Additional Context + + diff --git a/.github/ISSUE_TEMPLATE/good_first_issue.md b/.github/ISSUE_TEMPLATE/good_first_issue.md new file mode 100644 index 0000000..eb302f7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/good_first_issue.md @@ -0,0 +1,47 @@ +--- +name: Good First Issue +about: A well-scoped task for new contributors +title: "[good first issue] " +labels: good first issue +assignees: '' +--- + +## Description + + + +## Acceptance Criteria + +- [ ] +- [ ] +- [ ] Tests pass: `pnpm test` +- [ ] Build succeeds: `pnpm build` + +## Relevant Files + + + +- `src/utils/example.ts:42-58` — the function to modify +- `tests/example.test.ts` — add tests here + +## Similar PRs + + + +- #N/A + +## Getting Started + +1. Fork and clone the repo +2. `cd skills-v2 && pnpm install` +3. Read [CONTRIBUTING.md](../../CONTRIBUTING.md) +4. Make changes in the files listed above +5. `pnpm test` to verify +6. `pnpm build` to ensure build passes + +## Scope + + + +**In scope**: ... +**Out of scope**: ... diff --git a/CHANGELOG.md b/CHANGELOG.md index dbcc29f..1f1f80c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 --- +## [1.7.76] - 2026-03-10 + +### 📝 文档 + +- **README 重构**：命令分组展示（7 类）、新增「Why CCG?」价值主张、架构图上移、Prerequisites 合并、环境变量增加「何时修改」列、FAQ/Hook 配置去重折叠 +- **新增 CONTRIBUTING.md**：开发环境搭建、PR 流程、Commit 规范、代码标准、Good First Issue 指南 +- **新增 Issue 模板**：`.github/ISSUE_TEMPLATE/` 下 3 套模板（bug report / feature request / good first issue） + +--- + ## [1.7.75] - 2026-03-10 ### 🐛 修复 diff --git a/CLAUDE.md b/CLAUDE.md index 31b85a7..2f8690c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ > [根目录](../CLAUDE.md) > **skills-v2** -**Last Updated**: 2026-03-10 (v1.7.75) +**Last Updated**: 2026-03-10 (v1.7.76) --- @@ -10,6 +10,9 @@ > 完整变更历史请查看 [CHANGELOG.md](./CHANGELOG.md) +### 2026-03-10 (v1.7.76) +- 📝 **README 重构**：命令分组（7 类）、新增 Why CCG? + CONTRIBUTING.md + Issue 模板 x3、配置章节去重折叠 + ### 2026-03-10 (v1.7.75) - 🐛 **Skills 命名空间隔离**：`skills/` → `skills/ccg/`，卸载不再误删用户自建 skill + 旧版自动迁移 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..78fbd48 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,134 @@ +# Contributing to CCG + +Thanks for your interest in contributing to CCG! This guide will help you get started. + +## Development Setup + +### Prerequisites + +- Node.js 20+ +- pnpm (`npm install -g pnpm`) +- Go 1.21+ (only for `codeagent-wrapper` changes) + +### Getting Started + +```bash +# Clone the repository +git clone https://github.com/fengshao1227/ccg-workflow.git +cd ccg-workflow/skills-v2 + +# Install dependencies +pnpm install + +# Build +pnpm build + +# Run tests +pnpm test +``` + +### Project Structure + +``` +skills-v2/ +├── src/ # TypeScript source +│ ├── cli.ts # CLI entry point +│ ├── commands/ # CLI commands (init, update, menu, etc.) +│ └── utils/ # Shared utilities +├── templates/ # Installed to ~/.claude/ +│ ├── commands/ # 26 slash command templates (.md) +│ ├── prompts/ # Expert prompts (codex/ + gemini/) +│ └── skills/ # Quality gates + orchestration +├── codeagent-wrapper/ # Go binary source +├── tests/ # Vitest test files +└── bin/ # Build output + pre-compiled binaries +``` + +### Key Files + +| File | Purpose | +|------|---------| +| `src/utils/installer.ts` | Core installation logic | +| `src/utils/config.ts` | Configuration management | +| `src/utils/mcp.ts` | MCP tool integration | +| `templates/commands/*.md` | Slash command templates | +| `templates/prompts/` | Expert prompts for Codex/Gemini | + +## How to Contribute + +### Find an Issue + +- Check [`good first issue`](https://github.com/fengshao1227/ccg-workflow/labels/good%20first%20issue) for beginner-friendly tasks +- Check [`help wanted`](https://github.com/fengshao1227/ccg-workflow/labels/help%20wanted) for tasks needing assistance +- Or open a new issue to propose your idea + +### Development Workflow + +1. Fork the repository +2. Create a feature branch: `git checkout -b feat/your-feature` +3. Make your changes +4. Run tests: `pnpm test` +5. Build: `pnpm build` +6. Commit with conventional format: `git commit -m "feat: add something"` +7. Push and create a Pull Request + +### Commit Convention + +We use [Conventional Commits](https://www.conventionalcommits.org/): + +| Prefix | Usage | +|--------|-------| +| `feat:` | New feature | +| `fix:` | Bug fix | +| `docs:` | Documentation changes | +| `test:` | Adding or updating tests | +| `refactor:` | Code refactoring (no behavior change) | +| `chore:` | Build, CI, dependency updates | + +### Code Standards + +- **TypeScript**: Follow existing patterns in `src/` +- **Templates**: Markdown files in `templates/commands/` — use `{{VARIABLE}}` for template variables +- **Tests**: Use Vitest, place tests in `tests/` mirroring `src/` structure +- **Metrics**: Function complexity < 10, single function < 50 lines, single file < 500 lines + +### What Makes a Good PR + +- **Focused**: One concern per PR +- **Tested**: Include tests for new functionality +- **Documented**: Update README if adding user-facing features +- **Small**: Prefer multiple small PRs over one large one + +## Good First Issues + +Good first issues are designed to be completable in ~2 hours. They typically involve: + +- **Documentation**: Fix typos, improve examples, add missing descriptions +- **i18n**: Add missing translations in command templates +- **Tests**: Write tests for untested utility functions +- **Templates**: Improve slash command templates with better examples +- **Small fixes**: Single-file bug fixes in `src/utils/` + +Each good first issue includes: +- Clear problem description +- Specific files to modify +- Acceptance criteria +- Verification commands + +## Review Process + +| Event | Timeline | +|-------|----------| +| Issue claimed | Assigned within 1 day | +| PR submitted | First review within 3 days | +| After review feedback | Contributor has 5 days to respond | +| No response | Issue unassigned (you can reclaim later) | + +## Questions? + +- Open a [Discussion](https://github.com/fengshao1227/ccg-workflow/discussions) +- Check existing [Issues](https://github.com/fengshao1227/ccg-workflow/issues) + +--- + +Thank you for contributing! diff --git a/README.md b/README.md index be8e5fa..f5dfa7e 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ [![npm version](https://img.shields.io/npm/v/ccg-workflow.svg)](https://www.npmjs.com/package/ccg-workflow) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)](https://claude.ai/code) +[![Tests](https://img.shields.io/badge/Tests-131%20passed-brightgreen.svg)]() [简体中文](./README.zh-CN.md) | English @@ -12,98 +13,136 @@ A multi-model collaboration development system where Claude Code orchestrates Codex + Gemini. Frontend tasks route to Gemini, backend tasks route to Codex, and Claude handles orchestration and code review. -## Installation +## Why CCG? + +- **Zero-config model routing** — Frontend tasks automatically go to Gemini, backend tasks to Codex. No manual switching. +- **Security by design** — External models have no write access. They return patches; Claude reviews before applying. +- **26 slash commands** — From planning to execution, git workflow to code review, all accessible via `/ccg:*`. +- **Spec-driven development** — Integrates [OPSX](https://github.com/fission-ai/opsx) to turn vague requirements into verifiable constraints, eliminating AI improvisation. + +## 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. + +## Quick Start + +### Prerequisites + +| Dependency | Required | Notes | +|------------|----------|-------| +| **Node.js 20+** | Yes | `ora@9.x` requires Node >= 20. Node 18 causes `SyntaxError` | +| **Claude Code CLI** | Yes | [Install guide](#install-claude-code) | +| **jq** | Yes | Used for auto-authorization hook ([install](#install-jq)) | +| **Codex CLI** | No | Enables backend routing | +| **Gemini CLI** | No | Enables frontend routing | + +### Installation ```bash npx ccg-workflow ``` -**Requirements**: Claude Code CLI, Node.js 20+ +On first run, CCG prompts you to select a language (English / Chinese). This preference is saved for all future sessions. -> **Important**: This project depends on `ora@9.x` and `string-width@8.x`, which require Node.js >= 20. Using Node.js 18 will cause `SyntaxError: Invalid regular expression flags`. Please upgrade to Node.js 20 or higher. +### Install jq -**Optional**: Codex CLI (backend), Gemini CLI (frontend) +```bash +# macOS +brew install jq -## First-Time Setup +# Linux (Debian/Ubuntu) +sudo apt install jq -On first run, CCG will prompt you to select your preferred language (English or Chinese). This preference is saved and used for all subsequent sessions. +# Linux (RHEL/CentOS) +sudo yum install jq + +# 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. ## Commands +### Development Workflow + +| Command | Description | Model | +|---------|-------------|-------| +| `/ccg:workflow` | Full 6-phase development workflow | 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 | + +### 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 | + +### OPSX Spec-Driven + | Command | Description | |---------|-------------| -| `/ccg:workflow` | Full 6-phase development workflow | -| `/ccg:plan` | Multi-model collaborative planning (Phase 1-2) | -| `/ccg:execute` | Multi-model collaborative execution (Phase 3-5) | -| `/ccg:feat` | Smart feature development | -| `/ccg:frontend` | Frontend tasks (Gemini) | -| `/ccg:backend` | Backend tasks (Codex) | -| `/ccg:analyze` | Technical analysis | -| `/ccg:debug` | Problem diagnosis | -| `/ccg:optimize` | Performance optimization | -| `/ccg:test` | Test generation | -| `/ccg:review` | Code review | -| `/ccg:commit` | Git commit | -| `/ccg:rollback` | Git rollback | -| `/ccg:clean-branches` | Clean branches | -| `/ccg:worktree` | Worktree management | -| `/ccg:init` | Initialize CLAUDE.md | -| `/ccg:enhance` | Prompt enhancement | | `/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 | -| `/ccg:team-research` | Agent Teams requirements → constraints | -| `/ccg:team-plan` | Agent Teams constraints → parallel plan | -| `/ccg:team-exec` | Agent Teams parallel execution | -| `/ccg:team-review` | Agent Teams dual-model review | -| `/ccg:codex-exec` | Codex full execution (plan → code → review) | -### OPSX Spec-Driven (v1.7.52+) +### Agent Teams (v1.7.60+) -Integrates [OPSX architecture](https://github.com/fission-ai/opsx) to turn requirements into constraints, eliminating AI improvisation: +| 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 | -```bash -# Initialize OPSX environment -/ccg:spec-init +> **Prerequisite**: Enable Agent Teams in `settings.json`: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` -# Research requirements → output constraints -/ccg:spec-research implement user authentication +### Git Tools -# Parallel analysis → zero-decision plan -/ccg:spec-plan +| Command | Description | +|---------|-------------| +| `/ccg:commit` | Smart commit (conventional commit format) | +| `/ccg:rollback` | Interactive rollback | +| `/ccg:clean-branches` | Clean merged branches | +| `/ccg:worktree` | Worktree management | -# Execute the plan -/ccg:spec-impl +### Project Setup -# Independent review (available anytime) -/ccg:spec-review -``` +| Command | Description | +|---------|-------------| +| `/ccg:init` | Initialize project CLAUDE.md | -**Note**: `/ccg:spec-*` commands are CCG's wrapper around OPSX, internally calling `/opsx:*` commands. You can `/clear` between phases — state is persisted in the `openspec/` directory, so context overflow is not a concern. - -### Agent Teams Parallel Execution (v1.7.60+) - -Leverage Claude Code Agent Teams experimental feature to spawn multiple Builder teammates for parallel coding: - -```bash -# 1. Requirements research → constraints (recommended for complex projects) -/ccg:team-research implement real-time collaboration kanban API - -# 2. /clear then plan → zero-decision parallel plan -/ccg:team-plan kanban-api - -# 3. /clear then parallel execution → Builder teammates write code in parallel -/ccg:team-exec - -# 4. /clear then review → dual-model cross-review -/ccg:team-review -``` - -**Prerequisite**: Manually enable Agent Teams (`settings.json`: set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) - -**vs Traditional Workflow**: Team series uses `/clear` between steps to isolate context, passing state through files. Builders work in parallel, ideal for tasks decomposable into 3+ independent modules. +## Workflow Guides ### Planning & Execution Separation @@ -121,31 +160,66 @@ Leverage Claude Code Agent Teams experimental feature to spawn multiple Builder /ccg:codex-exec .claude/plan/user-auth.md ``` +### OPSX Spec-Driven Workflow + +Integrates [OPSX architecture](https://github.com/fission-ai/opsx) to turn requirements into constraints, eliminating AI improvisation: + +```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) +``` + +> **Tip**: `/ccg:spec-*` commands internally call `/opsx:*`. You can `/clear` between phases — state is persisted in the `openspec/` directory. + +### Agent Teams Parallel Workflow + +Leverage Claude Code Agent Teams to spawn multiple Builder teammates for parallel coding: + +```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**: Team series uses `/clear` between steps to isolate context, passing state through files. Ideal for tasks decomposable into 3+ independent modules. + ## Configuration ### Directory Structure ``` ~/.claude/ -├── commands/ccg/ # Slash commands +├── commands/ccg/ # 26 slash commands ├── agents/ccg/ # Sub-agents -├── skills/ # Quality gates + multi-agent orchestration +├── skills/ccg/ # Quality gates + multi-agent orchestration ├── bin/codeagent-wrapper └── .ccg/ - ├── config.toml - └── prompts/{codex,gemini}/ + ├── config.toml # CCG configuration + └── prompts/ + ├── codex/ # 6 Codex expert prompts + └── gemini/ # 7 Gemini expert prompts ``` ### Environment Variables -| Variable | Description | Default | -|----------|-------------|---------| -| `CODEAGENT_POST_MESSAGE_DELAY` | Wait time after Codex completion (seconds) | 5 | -| `CODEX_TIMEOUT` | codeagent-wrapper execution timeout (seconds) | 7200 | -| `BASH_DEFAULT_TIMEOUT_MS` | Claude Code Bash default timeout (ms) | 120000 | -| `BASH_MAX_TIMEOUT_MS` | Claude Code Bash max timeout (ms) | 600000 | +Configure in `~/.claude/settings.json` under `"env"`: -Configuration in `~/.claude/settings.json`: +| 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 | + +
+Example settings.json ```json { @@ -158,79 +232,32 @@ Configuration in `~/.claude/settings.json`: } ``` -### codeagent-wrapper Auto-Authorization - -CCG automatically installs a Hook in `settings.json` to auto-authorize codeagent-wrapper commands, so you don't have to manually approve each collaboration call. - -**Requirement**: `jq` must be installed on your system. - -```bash -# macOS -brew install jq - -# Linux (Debian/Ubuntu) -sudo apt install jq - -# Linux (RHEL/CentOS) -sudo yum install jq - -# Windows -choco install jq -# or -scoop install jq -``` +
### MCP Configuration -Code retrieval MCP (choose one): -- **ace-tool** (recommended) - Code search via `search_context` (note: `enhance_prompt` is no longer available). [Official](https://augmentcode.com/) | [Third-party proxy (recommended)](https://acemcp.heroman.wtf/) -- **ContextWeaver** (alternative) - Local hybrid search, requires SiliconFlow API Key (free) - -Optional MCP tools: -- **Context7** - Latest library documentation -- **Playwright** - Browser automation/testing -- **DeepWiki** - Knowledge base queries -- **Exa** - Search engine (requires API Key) - ```bash -# Configure MCP npx ccg-workflow menu # Select "Configure MCP" ``` -## Tools +**Code retrieval** (choose one): +- **ace-tool** (recommended) — Code search via `search_context`. [Official](https://augmentcode.com/) | [Third-party proxy](https://acemcp.heroman.wtf/) +- **ContextWeaver** (alternative) — Local hybrid search, requires SiliconFlow API Key (free) -```bash -npx ccg-workflow menu # Select "Tools" -``` +**Optional tools**: +- **Context7** — Latest library documentation (auto-installed) +- **Playwright** — Browser automation / testing +- **DeepWiki** — Knowledge base queries +- **Exa** — Search engine (requires API Key) -- **ccusage** - Claude Code usage analytics -- **CCometixLine** - Status bar tool (Git + usage tracking) +### Auto-Authorization Hook -## Install Claude Code +CCG automatically installs a Hook to auto-authorize `codeagent-wrapper` commands (requires [jq](#install-jq)). -```bash -npx ccg-workflow menu # Select "Install Claude Code" -``` +
+Manual setup (for versions before v1.7.71) -Supports multiple installation methods: npm, homebrew, curl, powershell, cmd - -## Update / Uninstall - -```bash -# Update -npx ccg-workflow@latest # npx users -npm install -g ccg-workflow@latest # npm global users - -# Uninstall -npx ccg-workflow # Select "Uninstall" -npm uninstall -g ccg-workflow # npm global users need this extra step -``` - -## FAQ - -### 1. How to auto-authorize codeagent-wrapper without manual approval? - -CCG automatically installs the Hook during setup (v1.7.71+). If you installed an older version, add this to `~/.claude/settings.json`: +Add to `~/.claude/settings.json`: ```json { @@ -251,37 +278,49 @@ CCG automatically installs the Hook during setup (v1.7.71+). If you installed an } ``` -> **Note**: Requires `jq` installed on your system. See [codeagent-wrapper Auto-Authorization](#codeagent-wrapper-auto-authorization) for install instructions. +
-### 2. Codex CLI 0.80.0 process does not exit +## Utilities + +```bash +npx ccg-workflow menu # Select "Tools" +``` + +- **ccusage** — Claude Code usage analytics +- **CCometixLine** — Status bar tool (Git + usage tracking) + +## Update / Uninstall + +```bash +# Update +npx ccg-workflow@latest # npx users +npm install -g ccg-workflow@latest # npm global users + +# Uninstall +npx ccg-workflow # Select "Uninstall" +npm uninstall -g ccg-workflow # npm global users need this extra step +``` + +## 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` +**Fix**: Set `CODEAGENT_POST_MESSAGE_DELAY=1` in your environment variables. -## Architecture +## Contributing -``` -Claude Code (Orchestrator) - │ - ┌───┴───┐ - ↓ ↓ -Codex Gemini -(Backend) (Frontend) - │ │ - └───┬───┘ - ↓ - Unified Patch -``` +We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. -External models have no write access — they only return patches, which Claude reviews before applying. +Looking for a place to start? Check out issues labeled [`good first issue`](https://github.com/fengshao1227/ccg-workflow/labels/good%20first%20issue). ## Credits -- [cexll/myclaude](https://github.com/cexll/myclaude) - codeagent-wrapper -- [UfoMiao/zcf](https://github.com/UfoMiao/zcf) - Git tools -- [GudaStudio/skills](https://github.com/GuDaStudio/skills) - Routing design -- [ace-tool](https://linux.do/t/topic/1344562) - MCP tool +- [cexll/myclaude](https://github.com/cexll/myclaude) — codeagent-wrapper +- [UfoMiao/zcf](https://github.com/UfoMiao/zcf) — Git tools +- [GudaStudio/skills](https://github.com/GuDaStudio/skills) — Routing design +- [ace-tool](https://linux.do/t/topic/1344562) — MCP tool ## Star History @@ -293,4 +332,4 @@ MIT --- -v1.7.75 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) +v1.7.76 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md) diff --git a/README.zh-CN.md b/README.zh-CN.md index 45e7cfb..50325de 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,10 +1,11 @@ -# CCG - Claude + Codex + Gemini Multi-Model Collaboration +# CCG - Claude + Codex + Gemini 多模型协作
[![npm version](https://img.shields.io/npm/v/ccg-workflow.svg)](https://www.npmjs.com/package/ccg-workflow) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)](https://claude.ai/code) +[![Tests](https://img.shields.io/badge/Tests-131%20passed-brightgreen.svg)]() 简体中文 | [English](./README.md) @@ -12,254 +13,12 @@ Claude Code 编排 Codex + Gemini 的多模型协作开发系统。前端任务路由至 Gemini，后端任务路由至 Codex，Claude 负责编排决策和代码审核。 -## 安装 +## 为什么选择 CCG？ -```bash -npx ccg-workflow -``` - -**要求**：Claude Code CLI、Node.js 20+ - -> **重要**：本项目依赖 `ora@9.x` 和 `string-width@8.x`，这些包要求 Node.js >= 20。使用 Node.js 18 会导致 `SyntaxError: Invalid regular expression flags` 错误。请确保升级到 Node.js 20 或更高版本。 - -**可选**：Codex CLI（后端）、Gemini CLI（前端） - -## 首次设置 - -首次运行时，CCG 会提示你选择语言（简体中文 / English）。选择后自动保存，后续使用无需再选。 - -## 命令 - -| 命令 | 说明 | -|------|------| -| `/ccg:workflow` | 6 阶段完整工作流 | -| `/ccg:plan` | 多模型协作规划 (Phase 1-2) | -| `/ccg:execute` | 多模型协作执行 (Phase 3-5) | -| `/ccg:feat` | 新功能开发 | -| `/ccg:frontend` | 前端任务 (Gemini) | -| `/ccg:backend` | 后端任务 (Codex) | -| `/ccg:analyze` | 技术分析 | -| `/ccg:debug` | 问题诊断 | -| `/ccg:optimize` | 性能优化 | -| `/ccg:test` | 测试生成 | -| `/ccg:review` | 代码审查 | -| `/ccg:commit` | Git 提交 | -| `/ccg:rollback` | Git 回滚 | -| `/ccg:clean-branches` | 清理分支 | -| `/ccg:worktree` | Worktree 管理 | -| `/ccg:init` | 初始化 CLAUDE.md | -| `/ccg:enhance` | Prompt 增强 | -| `/ccg:spec-init` | 初始化 OPSX 环境 | -| `/ccg:spec-research` | 需求 → 约束集 | -| `/ccg:spec-plan` | 约束 → 零决策计划 | -| `/ccg:spec-impl` | 按计划执行 + 归档 | -| `/ccg:spec-review` | 双模型交叉审查 | -| `/ccg:team-research` | Agent Teams 需求 → 约束集 | -| `/ccg:team-plan` | Agent Teams 约束 → 并行计划 | -| `/ccg:team-exec` | Agent Teams 并行实施 | -| `/ccg:team-review` | Agent Teams 双模型审查 | -| `/ccg:codex-exec` | Codex 全权执行（计划 → 代码 → 审核） | - -### OPSX 规范驱动（v1.7.52+） - -集成 [OPSX 架构](https://github.com/fission-ai/opsx)，把需求变成约束，让 AI 没法自由发挥： - -```bash -# 初始化 OPSX 环境 -/ccg:spec-init - -# 研究需求 → 输出约束集 -/ccg:spec-research 实现用户认证 - -# 并行分析 → 零决策计划 -/ccg:spec-plan - -# 按计划执行 -/ccg:spec-impl - -# 独立审查（随时可用） -/ccg:spec-review -``` - -**说明**：`/ccg:spec-*` 命令是 CCG 对 OPSX 的封装，内部调用 `/opsx:*` 命令。每阶段之间可 `/clear`，状态存在 `openspec/` 目录，不怕上下文爆。 - -### Agent Teams 并行实施（v1.7.60+） - -利用 Claude Code Agent Teams 实验特性，spawn 多个 Builder teammates 并行写代码： - -```bash -# 1. 需求研究 → 约束集（复杂项目推荐，简单项目可跳过） -/ccg:team-research 实现实时协作看板 API - -# 2. /clear 后规划 → 零决策并行计划 -/ccg:team-plan kanban-api - -# 3. /clear 后并行实施 → Builder teammates 并行写代码 -/ccg:team-exec - -# 4. /clear 后审查 → 双模型交叉审查 -/ccg:team-review -``` - -**前置条件**：需手动启用 Agent Teams（`settings.json` 中设置 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`） - -**vs 传统工作流**：Team 系列每步 `/clear` 隔离上下文，通过文件传递状态。Builder 并行实施，适合可拆分为 3+ 独立模块的任务。 - -### 规划与执行分离 - -v1.7.39 新增 `/ccg:plan` 和 `/ccg:execute` 命令，将规划与执行解耦： - -```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 -``` - -## 配置 - -### 目录结构 - -``` -~/.claude/ -├── commands/ccg/ # 斜杠命令 -├── agents/ccg/ # 子智能体 -├── skills/ # 质量关卡 + 多 Agent 协同 -├── bin/codeagent-wrapper -└── .ccg/ - ├── config.toml - └── prompts/{codex,gemini}/ -``` - -### 环境变量 - -| 变量 | 说明 | 默认值 | -|------|------|--------| -| `CODEAGENT_POST_MESSAGE_DELAY` | Codex 完成后等待时间（秒） | 5 | -| `CODEX_TIMEOUT` | codeagent-wrapper 执行超时（秒） | 7200 | -| `BASH_DEFAULT_TIMEOUT_MS` | Claude Code Bash 默认超时（毫秒） | 120000 | -| `BASH_MAX_TIMEOUT_MS` | Claude Code Bash 最大超时（毫秒） | 600000 | - -配置方式（`~/.claude/settings.json`）： - -```json -{ - "env": { - "CODEAGENT_POST_MESSAGE_DELAY": "1", - "CODEX_TIMEOUT": "7200", - "BASH_DEFAULT_TIMEOUT_MS": "600000", - "BASH_MAX_TIMEOUT_MS": "3600000" - } -} -``` - -### codeagent-wrapper 自动授权 - -CCG 安装时会自动向 `settings.json` 写入 Hook 配置，自动授权 codeagent-wrapper 命令，无需每次手动确认。 - -**前置条件**：需要系统安装 `jq` 命令。 - -```bash -# macOS -brew install jq - -# Linux (Debian/Ubuntu) -sudo apt install jq - -# Linux (RHEL/CentOS) -sudo yum install jq - -# Windows -choco install jq -# 或 -scoop install jq -``` - -### MCP 配置 - -代码检索 MCP（二选一）： -- **ace-tool**（推荐）- 代码检索 `search_context` 可用（注：`enhance_prompt` 已不可用）。[官方](https://augmentcode.com/) | [第三方中转（推荐）](https://acemcp.heroman.wtf/) -- **ContextWeaver**（备选）- 本地混合搜索，需要硅基流动 API Key（免费） - -辅助工具 MCP（可选）： -- **Context7** - 获取最新库文档 -- **Playwright** - 浏览器自动化/测试 -- **DeepWiki** - 知识库查询 -- **Exa** - 搜索引擎（需 API Key） - -```bash -# 配置 MCP -npx ccg-workflow menu # 选择「配置 MCP」 -``` - -## 实用工具 - -```bash -npx ccg-workflow menu # 选择「实用工具」 -``` - -- **ccusage** - Claude Code 用量分析 -- **CCometixLine** - 状态栏工具（Git + 用量跟踪） - -## 安装 Claude Code - -```bash -npx ccg-workflow menu # 选择「安装 Claude Code」 -``` - -支持多种安装方式：npm、homebrew、curl、powershell、cmd - -## 更新 / 卸载 - -```bash -# 更新 -npx ccg-workflow@latest # npx 用户 -npm install -g ccg-workflow@latest # npm 全局用户 - -# 卸载 -npx ccg-workflow # 选择 "卸载工作流" -npm uninstall -g ccg-workflow # npm 全局用户需额外执行 -``` - -## 常见问题 - -### 1. 如何让 codeagent-wrapper 无需手动同意即可运行？ - -v1.7.71+ 安装时会自动写入 Hook。如果你是旧版本用户，可手动在 `~/.claude/settings.json` 中添加： - -```json -{ - "hooks": { - "PreToolUse": [ - { - "matcher": "Bash", - "hooks": [ - { - "type": "command", - "command": "jq -r '.tool_input.command' | grep -q 'codeagent-wrapper' && echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\", \"permissionDecisionReason\": \"codeagent-wrapper 命令自动通过\"}}' || exit 1", - "timeout": 1 - } - ] - } - ] - } -} -``` - -> **注**：需要确保电脑已经安装了 `jq` 命令。安装方法见 [codeagent-wrapper 自动授权](#codeagent-wrapper-自动授权)。 - -### 2. Codex CLI 0.80.0 进程不退出 - -`--json` 模式下 Codex 完成输出后进程不会自动退出。 - -解决：设置 `CODEAGENT_POST_MESSAGE_DELAY=1` +- **零配置模型路由** — 前端任务自动走 Gemini，后端任务自动走 Codex，无需手动切换。 +- **安全设计** — 外部模型无写入权限，仅返回 Patch，由 Claude 审核后应用。 +- **26 个斜杠命令** — 从规划到执行、Git 工作流到代码审查，通过 `/ccg:*` 一站式访问。 +- **规范驱动开发** — 集成 [OPSX](https://github.com/fission-ai/opsx)，将模糊需求变成可验证约束，让 AI 没法自由发挥。 ## 架构 @@ -278,12 +37,290 @@ Codex Gemini 外部模型无写入权限，仅返回 Patch，由 Claude 审核后应用。 +## 快速开始 + +### 前置条件 + +| 依赖 | 必需 | 说明 | +|------|------|------| +| **Node.js 20+** | 是 | `ora@9.x` 要求 Node >= 20，Node 18 会报 `SyntaxError` | +| **Claude Code CLI** | 是 | [安装方法](#安装-claude-code) | +| **jq** | 是 | 用于自动授权 Hook（[安装方法](#安装-jq)） | +| **Codex CLI** | 否 | 启用后端路由 | +| **Gemini CLI** | 否 | 启用前端路由 | + +### 安装 + +```bash +npx ccg-workflow +``` + +首次运行会提示选择语言（简体中文 / English），选择后自动保存，后续无需再选。 + +### 安装 jq + +```bash +# macOS +brew install jq + +# Linux (Debian/Ubuntu) +sudo apt install jq + +# Linux (RHEL/CentOS) +sudo yum install jq + +# Windows +choco install jq # 或: scoop install jq +``` + +### 安装 Claude Code + +```bash +npx ccg-workflow menu # 选择「安装 Claude Code」 +``` + +支持：npm、homebrew、curl、powershell、cmd。 + +## 命令 + +### 开发工作流 + +| 命令 | 说明 | 模型 | +|------|------|------| +| `/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 | + +### 分析与质量 + +| 命令 | 说明 | 模型 | +|------|------|------| +| `/ccg:analyze` | 技术分析 | Codex + Gemini | +| `/ccg:debug` | 问题诊断 + 修复 | Codex + Gemini | +| `/ccg:optimize` | 性能优化 | Codex + Gemini | +| `/ccg:test` | 测试生成 | 自动路由 | +| `/ccg:review` | 代码审查（自动 git diff） | Codex + Gemini | +| `/ccg:enhance` | Prompt 增强 | 内置 | + +### OPSX 规范驱动 + +| 命令 | 说明 | +|------|------| +| `/ccg:spec-init` | 初始化 OPSX 环境 | +| `/ccg:spec-research` | 需求 → 约束集 | +| `/ccg:spec-plan` | 约束 → 零决策计划 | +| `/ccg:spec-impl` | 按计划执行 + 归档 | +| `/ccg:spec-review` | 双模型交叉审查 | + +### Agent Teams（v1.7.60+） + +| 命令 | 说明 | +|------|------| +| `/ccg:team-research` | 需求 → 约束集（并行探索） | +| `/ccg:team-plan` | 约束 → 并行实施计划 | +| `/ccg:team-exec` | spawn Builder teammates 并行写代码 | +| `/ccg:team-review` | 双模型交叉审查 | + +> **前置条件**：需在 `settings.json` 中启用：`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` + +### Git 工具 + +| 命令 | 说明 | +|------|------| +| `/ccg:commit` | 智能提交（conventional commit 格式） | +| `/ccg:rollback` | 交互式回滚 | +| `/ccg:clean-branches` | 清理已合并分支 | +| `/ccg:worktree` | Worktree 管理 | + +### 项目管理 + +| 命令 | 说明 | +|------|------| +| `/ccg:init` | 初始化项目 CLAUDE.md | + +## 工作流指南 + +### 规划与执行分离 + +```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 +``` + +### 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 # 独立审查（随时可用） +``` + +> **提示**：`/ccg:spec-*` 命令内部调用 `/opsx:*`。每阶段之间可 `/clear`，状态存在 `openspec/` 目录，不怕上下文爆。 + +### Agent Teams 并行工作流 + +利用 Claude Code Agent Teams 实验特性，spawn 多个 Builder teammates 并行写代码： + +```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 传统工作流**：Team 系列每步 `/clear` 隔离上下文，通过文件传递状态。适合可拆分为 3+ 独立模块的任务。 + +## 配置 + +### 目录结构 + +``` +~/.claude/ +├── commands/ccg/ # 26 个斜杠命令 +├── agents/ccg/ # 子智能体 +├── 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` | 长时间构建时增大 | + +
+settings.json 示例 + +```json +{ + "env": { + "CODEAGENT_POST_MESSAGE_DELAY": "1", + "CODEX_TIMEOUT": "7200", + "BASH_DEFAULT_TIMEOUT_MS": "600000", + "BASH_MAX_TIMEOUT_MS": "3600000" + } +} +``` + +
+ +### MCP 配置 + +```bash +npx ccg-workflow menu # 选择「配置 MCP」 +``` + +**代码检索**（二选一）： +- **ace-tool**（推荐）— 代码检索 `search_context` 可用。[官方](https://augmentcode.com/) | [第三方中转](https://acemcp.heroman.wtf/) +- **ContextWeaver**（备选）— 本地混合搜索，需要硅基流动 API Key（免费） + +**辅助工具**（可选）： +- **Context7** — 获取最新库文档（自动安装） +- **Playwright** — 浏览器自动化 / 测试 +- **DeepWiki** — 知识库查询 +- **Exa** — 搜索引擎（需 API Key） + +### 自动授权 Hook + +CCG 安装时自动写入 Hook，自动授权 `codeagent-wrapper` 命令（需 [jq](#安装-jq)）。 + +
+手动配置（v1.7.71 之前的版本） + +在 `~/.claude/settings.json` 中添加： + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "jq -r '.tool_input.command' | grep -q 'codeagent-wrapper' && echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\", \"permissionDecisionReason\": \"codeagent-wrapper auto-approved\"}}' || exit 1", + "timeout": 1 + } + ] + } + ] + } +} +``` + +
+ +## 实用工具 + +```bash +npx ccg-workflow menu # 选择「实用工具」 +``` + +- **ccusage** — Claude Code 用量分析 +- **CCometixLine** — 状态栏工具（Git + 用量跟踪） + +## 更新 / 卸载 + +```bash +# 更新 +npx ccg-workflow@latest # npx 用户 +npm install -g ccg-workflow@latest # npm 全局用户 + +# 卸载 +npx ccg-workflow # 选择「卸载工作流」 +npm uninstall -g ccg-workflow # npm 全局用户需额外执行 +``` + +## 常见问题 + +### Codex CLI 0.80.0 进程不退出 + +`--json` 模式下 Codex 完成输出后进程不会自动退出。 + +**解决**：将 `CODEAGENT_POST_MESSAGE_DELAY` 设为 `1`，详见[环境变量](#环境变量)。 + +## 参与贡献 + +欢迎贡献！请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解开发指南。 + +想找一个入手点？查看标记为 [`good first issue`](https://github.com/fengshao1227/ccg-workflow/labels/good%20first%20issue) 的 Issue。 + ## 致谢 -- [cexll/myclaude](https://github.com/cexll/myclaude) - codeagent-wrapper -- [UfoMiao/zcf](https://github.com/UfoMiao/zcf) - Git 工具 -- [GudaStudio/skills](https://github.com/GuDaStudio/skills) - 路由设计 -- [ace-tool](https://linux.do/t/topic/1344562) - MCP 工具 +- [cexll/myclaude](https://github.com/cexll/myclaude) — codeagent-wrapper +- [UfoMiao/zcf](https://github.com/UfoMiao/zcf) — Git 工具 +- [GudaStudio/skills](https://github.com/GuDaStudio/skills) — 路由设计 +- [ace-tool](https://linux.do/t/topic/1344562) — MCP 工具 ## Star History @@ -295,4 +332,4 @@ MIT --- -v1.7.75 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) +v1.7.76 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [参与贡献](./CONTRIBUTING.md) diff --git a/package.json b/package.json index c37230e..b2f66bf 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ccg-workflow", - "version": "1.7.75", + "version": "1.7.76", "description": "Claude + Codex + Gemini multi-model collaboration system - smart routing development workflow", "type": "module", "packageManager": "pnpm@10.17.1",