docs: restructure README + add CONTRIBUTING.md + issue templates v1.7.76
- README: group 26 commands into 7 categories, add "Why CCG?" section, move architecture diagram up, consolidate prerequisites, deduplicate jq instructions, add "When to change" column for env vars, fold settings.json and Hook config into <details> - Add CONTRIBUTING.md with dev setup, PR workflow, commit conventions - Add .github/ISSUE_TEMPLATE/ (bug report, feature request, good first issue) - EN and ZH README mirrored (335 lines each, 13 sections)
This commit is contained in:
li committed
1 parent
aada7260fc
commit
5769a1dbe6
9 files changed
+745
-414
No files matched your search
@@ -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
|
||||
|
||||
<!-- What happened? -->
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
<!-- What should have happened? -->
|
||||
|
||||
## Steps to Reproduce
|
||||
|
||||
1. ...
|
||||
2. ...
|
||||
3. ...
|
||||
|
||||
## Error Output
|
||||
|
||||
```
|
||||
<!-- Paste error messages or logs here -->
|
||||
```
|
||||
|
||||
## Additional Context
|
||||
|
||||
<!-- Screenshots, related issues, etc. -->
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
name: Feature Request
|
||||
about: Suggest a new feature or improvement
|
||||
title: "[feat] "
|
||||
labels: enhancement
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
## Problem
|
||||
|
||||
<!-- What problem does this feature solve? -->
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
<!-- How should it work? -->
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
<!-- What other approaches did you consider? -->
|
||||
|
||||
## Additional Context
|
||||
|
||||
<!-- Mockups, related projects, references, etc. -->
|
||||
@@ -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
|
||||
|
||||
<!-- Clear explanation of what needs to change and why -->
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] <!-- Specific, testable outcome 1 -->
|
||||
- [ ] <!-- Specific, testable outcome 2 -->
|
||||
- [ ] Tests pass: `pnpm test`
|
||||
- [ ] Build succeeds: `pnpm build`
|
||||
|
||||
## Relevant Files
|
||||
|
||||
<!-- Link to specific files and line numbers -->
|
||||
|
||||
- `src/utils/example.ts:42-58` — the function to modify
|
||||
- `tests/example.test.ts` — add tests here
|
||||
|
||||
## Similar PRs
|
||||
|
||||
<!-- Reference past PRs that did something similar -->
|
||||
|
||||
- #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
|
||||
|
||||
<!-- Explicitly state what is NOT in scope -->
|
||||
|
||||
**In scope**: ...
|
||||
**Out of scope**: ...
|
||||
@@ -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
|
||||
|
||||
### 🐛 修复
|
||||
|
||||
@@ -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 + 旧版自动迁移
|
||||
|
||||
|
||||
+134
@@ -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!
|
||||
@@ -5,6 +5,7 @@
|
||||
[](https://www.npmjs.com/package/ccg-workflow)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://claude.ai/code)
|
||||
[]()
|
||||
|
||||
[简体中文](./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 |
|
||||
|
||||
<details>
|
||||
<summary>Example settings.json</summary>
|
||||
|
||||
```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
|
||||
```
|
||||
</details>
|
||||
|
||||
### 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"
|
||||
```
|
||||
<details>
|
||||
<summary>Manual setup (for versions before v1.7.71)</summary>
|
||||
|
||||
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.
|
||||
</details>
|
||||
|
||||
### 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)
|
||||
+290
-253
@@ -1,10 +1,11 @@
|
||||
# CCG - Claude + Codex + Gemini Multi-Model Collaboration
|
||||
# CCG - Claude + Codex + Gemini 多模型协作
|
||||
|
||||
<div align="center">
|
||||
|
||||
[](https://www.npmjs.com/package/ccg-workflow)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://claude.ai/code)
|
||||
[]()
|
||||
|
||||
简体中文 | [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` | 长时间构建时增大 |
|
||||
|
||||
<details>
|
||||
<summary>settings.json 示例</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"CODEAGENT_POST_MESSAGE_DELAY": "1",
|
||||
"CODEX_TIMEOUT": "7200",
|
||||
"BASH_DEFAULT_TIMEOUT_MS": "600000",
|
||||
"BASH_MAX_TIMEOUT_MS": "3600000"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### 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)）。
|
||||
|
||||
<details>
|
||||
<summary>手动配置（v1.7.71 之前的版本）</summary>
|
||||
|
||||
在 `~/.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
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 实用工具
|
||||
|
||||
```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)
|
||||
+1
-1
@@ -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",
|
||||
|
||||
Reference in new issue
Block a user