mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-11 12:03:31 +08:00
docs(zh-CN): sync Chinese docs with latest upstream changes (#202)
* docs(zh-CN): sync Chinese docs with latest upstream changes * docs: improve Chinese translation consistency in go-test.md * docs(zh-CN): update image paths to use shared assets directory - Update image references from ./assets/ to ../../assets/ - Remove zh-CN/assets directory to use shared assets --------- Co-authored-by: neo <neo.dowithless@gmail.com>
This commit is contained in:
zdoc.app
274
docs/zh-CN/commands/go-test.md
Normal file
274
docs/zh-CN/commands/go-test.md
Normal file
@@ -0,0 +1,274 @@
|
||||
---
|
||||
description: 为Go强制执行TDD工作流程。首先编写表驱动测试，然后实现。使用go test -cover验证80%以上的覆盖率。
|
||||
---
|
||||
|
||||
# Go TDD 命令
|
||||
|
||||
此命令使用惯用的 Go 测试模式，为 Go 代码强制执行测试驱动开发方法。
|
||||
|
||||
## 此命令的作用
|
||||
|
||||
1. **定义类型/接口**：首先搭建函数签名
|
||||
2. **编写表驱动测试**：创建全面的测试用例（RED 阶段）
|
||||
3. **运行测试**：验证测试因正确原因而失败
|
||||
4. **实现代码**：编写最少的代码以通过测试（GREEN 阶段）
|
||||
5. **重构**：改进代码，同时保持测试通过
|
||||
6. **检查覆盖率**：确保 80% 以上的覆盖率
|
||||
|
||||
## 何时使用
|
||||
|
||||
在以下情况下使用 `/go-test`：
|
||||
|
||||
* 实现新的 Go 函数时
|
||||
* 为现有代码添加测试覆盖率时
|
||||
* 修复 bug 时（先编写失败的测试）
|
||||
* 构建关键业务逻辑时
|
||||
* 学习 Go 中的 TDD 工作流程时
|
||||
|
||||
## TDD 循环
|
||||
|
||||
```
|
||||
RED → Write failing table-driven test
|
||||
GREEN → Implement minimal code to pass
|
||||
REFACTOR → Improve code, tests stay green
|
||||
REPEAT → Next test case
|
||||
```
|
||||
|
||||
## 示例会话
|
||||
|
||||
````
|
||||
User: /go-test I need a function to validate email addresses
|
||||
|
||||
Agent:
|
||||
# TDD Session: Email Validator
|
||||
|
||||
## Step 1: Define Interface
|
||||
|
||||
```go
|
||||
// validator/email.go
|
||||
package validator
|
||||
|
||||
// ValidateEmail checks if the given string is a valid email address.
|
||||
// Returns nil if valid, error describing the issue otherwise.
|
||||
func ValidateEmail(email string) error {
|
||||
panic("not implemented")
|
||||
}
|
||||
```
|
||||
|
||||
## Step 2: Write Table-Driven Tests (RED)
|
||||
|
||||
```go
|
||||
// validator/email_test.go
|
||||
package validator
|
||||
|
||||
import (
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestValidateEmail(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
email string
|
||||
wantErr bool
|
||||
}{
|
||||
// Valid emails
|
||||
{"simple email", "user@example.com", false},
|
||||
{"with subdomain", "user@mail.example.com", false},
|
||||
{"with plus", "user+tag@example.com", false},
|
||||
{"with dots", "first.last@example.com", false},
|
||||
|
||||
// Invalid emails
|
||||
{"empty string", "", true},
|
||||
{"no at sign", "userexample.com", true},
|
||||
{"no domain", "user@", true},
|
||||
{"no local part", "@example.com", true},
|
||||
{"double at", "user@@example.com", true},
|
||||
{"spaces", "user @example.com", true},
|
||||
{"no tld", "user@example", true},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
err := ValidateEmail(tt.email)
|
||||
if tt.wantErr && err == nil {
|
||||
t.Errorf("ValidateEmail(%q) = nil; want error", tt.email)
|
||||
}
|
||||
if !tt.wantErr && err != nil {
|
||||
t.Errorf("ValidateEmail(%q) = %v; want nil", tt.email, err)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Step 3: Run Tests - Verify FAIL
|
||||
|
||||
```bash
|
||||
$ go test ./validator/...
|
||||
|
||||
--- FAIL: TestValidateEmail (0.00s)
|
||||
--- FAIL: TestValidateEmail/simple_email (0.00s)
|
||||
panic: not implemented
|
||||
|
||||
FAIL
|
||||
```
|
||||
|
||||
✓ Tests fail as expected (panic).
|
||||
|
||||
## Step 4: Implement Minimal Code (GREEN)
|
||||
|
||||
```go
|
||||
// validator/email.go
|
||||
package validator
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"regexp"
|
||||
)
|
||||
|
||||
var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
|
||||
|
||||
var (
|
||||
ErrEmailEmpty = errors.New("email cannot be empty")
|
||||
ErrEmailInvalid = errors.New("email format is invalid")
|
||||
)
|
||||
|
||||
func ValidateEmail(email string) error {
|
||||
if email == "" {
|
||||
return ErrEmailEmpty
|
||||
}
|
||||
if !emailRegex.MatchString(email) {
|
||||
return ErrEmailInvalid
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
## Step 5: Run Tests - Verify PASS
|
||||
|
||||
```bash
|
||||
$ go test ./validator/...
|
||||
|
||||
PASS
|
||||
ok project/validator 0.003s
|
||||
```
|
||||
|
||||
✓ All tests passing!
|
||||
|
||||
## Step 6: Check Coverage
|
||||
|
||||
```bash
|
||||
$ go test -cover ./validator/...
|
||||
|
||||
PASS
|
||||
coverage: 100.0% of statements
|
||||
ok project/validator 0.003s
|
||||
```
|
||||
|
||||
✓ Coverage: 100%
|
||||
|
||||
## TDD Complete!
|
||||
````
|
||||
|
||||
## 测试模式
|
||||
|
||||
### 表驱动测试
|
||||
|
||||
```go
|
||||
tests := []struct {
|
||||
name string
|
||||
input InputType
|
||||
want OutputType
|
||||
wantErr bool
|
||||
}{
|
||||
{"case 1", input1, want1, false},
|
||||
{"case 2", input2, want2, true},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
got, err := Function(tt.input)
|
||||
// assertions
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 并行测试
|
||||
|
||||
```go
|
||||
for _, tt := range tests {
|
||||
tt := tt // Capture
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
t.Parallel()
|
||||
// test body
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 测试辅助函数
|
||||
|
||||
```go
|
||||
func setupTestDB(t *testing.T) *sql.DB {
|
||||
t.Helper()
|
||||
db := createDB()
|
||||
t.Cleanup(func() { db.Close() })
|
||||
return db
|
||||
}
|
||||
```
|
||||
|
||||
## 覆盖率命令
|
||||
|
||||
```bash
|
||||
# Basic coverage
|
||||
go test -cover ./...
|
||||
|
||||
# Coverage profile
|
||||
go test -coverprofile=coverage.out ./...
|
||||
|
||||
# View in browser
|
||||
go tool cover -html=coverage.out
|
||||
|
||||
# Coverage by function
|
||||
go tool cover -func=coverage.out
|
||||
|
||||
# With race detection
|
||||
go test -race -cover ./...
|
||||
```
|
||||
|
||||
## 覆盖率目标
|
||||
|
||||
| 代码类型 | 目标 |
|
||||
|-----------|--------|
|
||||
| 关键业务逻辑 | 100% |
|
||||
| 公共 API | 90%+ |
|
||||
| 通用代码 | 80%+ |
|
||||
| 生成的代码 | 排除 |
|
||||
|
||||
## TDD 最佳实践
|
||||
|
||||
**应该做：**
|
||||
|
||||
* 先编写测试，再编写任何实现
|
||||
* 每次更改后运行测试
|
||||
* 使用表驱动测试以获得全面的覆盖率
|
||||
* 测试行为，而非实现细节
|
||||
* 包含边界情况（空值、nil、最大值）
|
||||
|
||||
**不应该做：**
|
||||
|
||||
* 在编写测试之前编写实现
|
||||
* 跳过 RED 阶段
|
||||
* 直接测试私有函数
|
||||
* 在测试中使用 `time.Sleep`
|
||||
* 忽略不稳定的测试
|
||||
|
||||
## 相关命令
|
||||
|
||||
* `/go-build` - 修复构建错误
|
||||
* `/go-review` - 在实现后审查代码
|
||||
* `/verify` - 运行完整的验证循环
|
||||
|
||||
## 相关
|
||||
|
||||
* 技能：`skills/golang-testing/`
|
||||
* 技能：`skills/tdd-workflow/`
|
||||
162
docs/zh-CN/commands/multi-backend.md
Normal file
162
docs/zh-CN/commands/multi-backend.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# 后端 - 后端导向开发
|
||||
|
||||
后端导向的工作流程（研究 → 构思 → 规划 → 执行 → 优化 → 评审），由 Codex 主导。
|
||||
|
||||
## 使用方法
|
||||
|
||||
```bash
|
||||
/backend <backend task description>
|
||||
```
|
||||
|
||||
## 上下文
|
||||
|
||||
* 后端任务：$ARGUMENTS
|
||||
* Codex 主导，Gemini 作为辅助参考
|
||||
* 适用场景：API 设计、算法实现、数据库优化、业务逻辑
|
||||
|
||||
## 你的角色
|
||||
|
||||
你是 **后端协调者**，为服务器端任务协调多模型协作（研究 → 构思 → 规划 → 执行 → 优化 → 评审）。
|
||||
|
||||
**协作模型**：
|
||||
|
||||
* **Codex** – 后端逻辑、算法（**后端权威，可信赖**）
|
||||
* **Gemini** – 前端视角（**后端意见仅供参考**）
|
||||
* **Claude (自身)** – 协调、规划、执行、交付
|
||||
|
||||
***
|
||||
|
||||
## 多模型调用规范
|
||||
|
||||
**调用语法**：
|
||||
|
||||
```
|
||||
# New session call
|
||||
Bash({
|
||||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend codex - \"$PWD\" <<'EOF'
|
||||
ROLE_FILE: <role prompt path>
|
||||
<TASK>
|
||||
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
|
||||
Context: <project context and analysis from previous phases>
|
||||
</TASK>
|
||||
OUTPUT: Expected output format
|
||||
EOF",
|
||||
run_in_background: false,
|
||||
timeout: 3600000,
|
||||
description: "Brief description"
|
||||
})
|
||||
|
||||
# Resume session call
|
||||
Bash({
|
||||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend codex resume <SESSION_ID> - \"$PWD\" <<'EOF'
|
||||
ROLE_FILE: <role prompt path>
|
||||
<TASK>
|
||||
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
|
||||
Context: <project context and analysis from previous phases>
|
||||
</TASK>
|
||||
OUTPUT: Expected output format
|
||||
EOF",
|
||||
run_in_background: false,
|
||||
timeout: 3600000,
|
||||
description: "Brief description"
|
||||
})
|
||||
```
|
||||
|
||||
**角色提示词**：
|
||||
|
||||
| 阶段 | Codex |
|
||||
|-------|-------|
|
||||
| 分析 | `~/.claude/.ccg/prompts/codex/analyzer.md` |
|
||||
| 规划 | `~/.claude/.ccg/prompts/codex/architect.md` |
|
||||
| 评审 | `~/.claude/.ccg/prompts/codex/reviewer.md` |
|
||||
|
||||
**会话复用**：每次调用返回 `SESSION_ID: xxx`，在后续阶段使用 `resume xxx`。在第 2 阶段保存 `CODEX_SESSION`，在第 3 和第 5 阶段使用 `resume`。
|
||||
|
||||
***
|
||||
|
||||
## 沟通准则
|
||||
|
||||
1. 在回复开头使用模式标签 `[Mode: X]`，初始值为 `[Mode: Research]`
|
||||
2. 遵循严格序列：`Research → Ideation → Plan → Execute → Optimize → Review`
|
||||
3. 需要时（例如确认/选择/批准）使用 `AskUserQuestion` 工具进行用户交互
|
||||
|
||||
***
|
||||
|
||||
## 核心工作流程
|
||||
|
||||
### 阶段 0：提示词增强（可选）
|
||||
|
||||
`[Mode: Prepare]` - 如果 ace-tool MCP 可用，调用 `mcp__ace-tool__enhance_prompt`，**用增强后的结果替换原始的 $ARGUMENTS，用于后续的 Codex 调用**
|
||||
|
||||
### 阶段 1：研究
|
||||
|
||||
`[Mode: Research]` - 理解需求并收集上下文
|
||||
|
||||
1. **代码检索**（如果 ace-tool MCP 可用）：调用 `mcp__ace-tool__search_context` 以检索现有的 API、数据模型、服务架构
|
||||
2. 需求完整性评分（0-10）：>=7 继续，<7 停止并补充
|
||||
|
||||
### 阶段 2：构思
|
||||
|
||||
`[Mode: Ideation]` - Codex 主导的分析
|
||||
|
||||
**必须调用 Codex**（遵循上述调用规范）：
|
||||
|
||||
* ROLE\_FILE：`~/.claude/.ccg/prompts/codex/analyzer.md`
|
||||
* 需求：增强后的需求（或未增强时的 $ARGUMENTS）
|
||||
* 上下文：来自阶段 1 的项目上下文
|
||||
* 输出：技术可行性分析、推荐解决方案（至少 2 个）、风险评估
|
||||
|
||||
**保存 SESSION\_ID**（`CODEX_SESSION`）以供后续阶段复用。
|
||||
|
||||
输出解决方案（至少 2 个），等待用户选择。
|
||||
|
||||
### 阶段 3：规划
|
||||
|
||||
`[Mode: Plan]` - Codex 主导的规划
|
||||
|
||||
**必须调用 Codex**（使用 `resume <CODEX_SESSION>` 以复用会话）：
|
||||
|
||||
* ROLE\_FILE：`~/.claude/.ccg/prompts/codex/architect.md`
|
||||
* 需求：用户选择的解决方案
|
||||
* 上下文：阶段 2 的分析结果
|
||||
* 输出：文件结构、函数/类设计、依赖关系
|
||||
|
||||
Claude 综合规划，在用户批准后保存到 `.claude/plan/task-name.md`。
|
||||
|
||||
### 阶段 4：实施
|
||||
|
||||
`[Mode: Execute]` - 代码开发
|
||||
|
||||
* 严格遵循已批准的规划
|
||||
* 遵循现有项目的代码规范
|
||||
* 确保错误处理、安全性、性能优化
|
||||
|
||||
### 阶段 5：优化
|
||||
|
||||
`[Mode: Optimize]` - Codex 主导的评审
|
||||
|
||||
**必须调用 Codex**（遵循上述调用规范）：
|
||||
|
||||
* ROLE\_FILE：`~/.claude/.ccg/prompts/codex/reviewer.md`
|
||||
* 需求：评审以下后端代码变更
|
||||
* 上下文：git diff 或代码内容
|
||||
* 输出：安全性、性能、错误处理、API 合规性问题列表
|
||||
|
||||
整合评审反馈，在用户确认后执行优化。
|
||||
|
||||
### 阶段 6：质量评审
|
||||
|
||||
`[Mode: Review]` - 最终评估
|
||||
|
||||
* 对照规划检查完成情况
|
||||
* 运行测试以验证功能
|
||||
* 报告问题和建议
|
||||
|
||||
***
|
||||
|
||||
## 关键规则
|
||||
|
||||
1. **Codex 的后端意见是可信赖的**
|
||||
2. **Gemini 的后端意见仅供参考**
|
||||
3. 外部模型**对文件系统零写入权限**
|
||||
4. Claude 处理所有代码写入和文件操作
|
||||
315
docs/zh-CN/commands/multi-execute.md
Normal file
315
docs/zh-CN/commands/multi-execute.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# 执行 - 多模型协同执行
|
||||
|
||||
多模型协同执行 - 从计划获取原型 → Claude 重构并实施 → 多模型审计与交付。
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
***
|
||||
|
||||
## 核心协议
|
||||
|
||||
* **语言协议**：与工具/模型交互时使用**英语**，与用户沟通时使用用户的语言
|
||||
* **代码主权**：外部模型**零文件系统写入权限**，所有修改由 Claude 执行
|
||||
* **脏原型重构**：将 Codex/Gemini 统一差异视为“脏原型”，必须重构为生产级代码
|
||||
* **止损机制**：当前阶段输出未经验证前，不得进入下一阶段
|
||||
* **前提条件**：仅在用户明确回复“Y”到 `/ccg:plan` 输出后执行（如果缺失，必须先确认）
|
||||
|
||||
***
|
||||
|
||||
## 多模型调用规范
|
||||
|
||||
**调用语法**（并行：使用 `run_in_background: true`）：
|
||||
|
||||
```
|
||||
# Resume session call (recommended) - Implementation Prototype
|
||||
Bash({
|
||||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
|
||||
ROLE_FILE: <role prompt path>
|
||||
<TASK>
|
||||
Requirement: <task description>
|
||||
Context: <plan content + target files>
|
||||
</TASK>
|
||||
OUTPUT: Unified Diff Patch ONLY. Strictly prohibit any actual modifications.
|
||||
EOF",
|
||||
run_in_background: true,
|
||||
timeout: 3600000,
|
||||
description: "Brief description"
|
||||
})
|
||||
|
||||
# New session call - Implementation Prototype
|
||||
Bash({
|
||||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
|
||||
ROLE_FILE: <role prompt path>
|
||||
<TASK>
|
||||
Requirement: <task description>
|
||||
Context: <plan content + target files>
|
||||
</TASK>
|
||||
OUTPUT: Unified Diff Patch ONLY. Strictly prohibit any actual modifications.
|
||||
EOF",
|
||||
run_in_background: true,
|
||||
timeout: 3600000,
|
||||
description: "Brief description"
|
||||
})
|
||||
```
|
||||
|
||||
**审计调用语法**（代码审查 / 审计）：
|
||||
|
||||
```
|
||||
Bash({
|
||||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
|
||||
ROLE_FILE: <role prompt path>
|
||||
<TASK>
|
||||
Scope: Audit the final code changes.
|
||||
Inputs:
|
||||
- The applied patch (git diff / final unified diff)
|
||||
- The touched files (relevant excerpts if needed)
|
||||
Constraints:
|
||||
- Do NOT modify any files.
|
||||
- Do NOT output tool commands that assume filesystem access.
|
||||
</TASK>
|
||||
OUTPUT:
|
||||
1) A prioritized list of issues (severity, file, rationale)
|
||||
2) Concrete fixes; if code changes are needed, include a Unified Diff Patch in a fenced code block.
|
||||
EOF",
|
||||
run_in_background: true,
|
||||
timeout: 3600000,
|
||||
description: "Brief description"
|
||||
})
|
||||
```
|
||||
|
||||
**模型参数说明**：
|
||||
|
||||
* `{{GEMINI_MODEL_FLAG}}`：当使用 `--backend gemini` 时，替换为 `--gemini-model gemini-3-pro-preview`（注意尾随空格）；对于 codex 使用空字符串
|
||||
|
||||
**角色提示**：
|
||||
|
||||
| 阶段 | Codex | Gemini |
|
||||
|-------|-------|--------|
|
||||
| 实施 | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/frontend.md` |
|
||||
| 审查 | `~/.claude/.ccg/prompts/codex/reviewer.md` | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
|
||||
|
||||
**会话重用**：如果 `/ccg:plan` 提供了 SESSION\_ID，使用 `resume <SESSION_ID>` 来重用上下文。
|
||||
|
||||
**等待后台任务**（最大超时 600000ms = 10 分钟）：
|
||||
|
||||
```
|
||||
TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
|
||||
```
|
||||
|
||||
**重要**：
|
||||
|
||||
* 必须指定 `timeout: 600000`，否则默认 30 秒会导致过早超时
|
||||
* 如果 10 分钟后仍未完成，继续使用 `TaskOutput` 轮询，**切勿终止进程**
|
||||
* 如果因超时而跳过等待，**必须调用 `AskUserQuestion` 询问用户是继续等待还是终止任务**
|
||||
|
||||
***
|
||||
|
||||
## 执行工作流
|
||||
|
||||
**执行任务**：$ARGUMENTS
|
||||
|
||||
### 阶段 0：读取计划
|
||||
|
||||
`[Mode: Prepare]`
|
||||
|
||||
1. **识别输入类型**：
|
||||
* 计划文件路径（例如 `.claude/plan/xxx.md`）
|
||||
* 直接任务描述
|
||||
|
||||
2. **读取计划内容**：
|
||||
* 如果提供了计划文件路径，读取并解析
|
||||
* 提取：任务类型、实施步骤、关键文件、SESSION\_ID
|
||||
|
||||
3. **执行前确认**：
|
||||
* 如果输入是“直接任务描述”或计划缺少 `SESSION_ID` / 关键文件：先与用户确认
|
||||
* 如果无法确认用户已回复“Y”到计划：在继续前必须再次确认
|
||||
|
||||
4. **任务类型路由**：
|
||||
|
||||
| 任务类型 | 检测 | 路由 |
|
||||
|-----------|-----------|-------|
|
||||
| **前端** | 页面、组件、UI、样式、布局 | Gemini |
|
||||
| **后端** | API、接口、数据库、逻辑、算法 | Codex |
|
||||
| **全栈** | 包含前端和后端 | Codex ∥ Gemini 并行 |
|
||||
|
||||
***
|
||||
|
||||
### 阶段 1：快速上下文检索
|
||||
|
||||
`[Mode: Retrieval]`
|
||||
|
||||
**必须使用 MCP 工具进行快速上下文检索，切勿手动逐个读取文件**
|
||||
|
||||
基于计划中的“关键文件”列表，调用 `mcp__ace-tool__search_context`：
|
||||
|
||||
```
|
||||
mcp__ace-tool__search_context({
|
||||
query: "<semantic query based on plan content, including key files, modules, function names>",
|
||||
project_root_path: "$PWD"
|
||||
})
|
||||
```
|
||||
|
||||
**检索策略**：
|
||||
|
||||
* 从计划的“关键文件”表中提取目标路径
|
||||
* 构建语义查询覆盖：入口文件、依赖模块、相关类型定义
|
||||
* 如果结果不足，添加 1-2 次递归检索
|
||||
* **切勿**使用 Bash + find/ls 手动探索项目结构
|
||||
|
||||
**检索后**：
|
||||
|
||||
* 组织检索到的代码片段
|
||||
* 确认实施所需的完整上下文
|
||||
* 进入阶段 3
|
||||
|
||||
***
|
||||
|
||||
### 阶段 3：原型获取
|
||||
|
||||
`[Mode: Prototype]`
|
||||
|
||||
**基于任务类型路由**：
|
||||
|
||||
#### 路由 A：前端/UI/样式 → Gemini
|
||||
|
||||
**限制**：上下文 < 32k 令牌
|
||||
|
||||
1. 调用 Gemini（使用 `~/.claude/.ccg/prompts/gemini/frontend.md`）
|
||||
2. 输入：计划内容 + 检索到的上下文 + 目标文件
|
||||
3. 输出：`Unified Diff Patch ONLY. Strictly prohibit any actual modifications.`
|
||||
4. **Gemini 是前端设计权威，其 CSS/React/Vue 原型是最终的视觉基线**
|
||||
5. **警告**：忽略 Gemini 的后端逻辑建议
|
||||
6. 如果计划包含 `GEMINI_SESSION`：优先使用 `resume <GEMINI_SESSION>`
|
||||
|
||||
#### 路由 B：后端/逻辑/算法 → Codex
|
||||
|
||||
1. 调用 Codex（使用 `~/.claude/.ccg/prompts/codex/architect.md`）
|
||||
2. 输入：计划内容 + 检索到的上下文 + 目标文件
|
||||
3. 输出：`Unified Diff Patch ONLY. Strictly prohibit any actual modifications.`
|
||||
4. **Codex 是后端逻辑权威，利用其逻辑推理和调试能力**
|
||||
5. 如果计划包含 `CODEX_SESSION`：优先使用 `resume <CODEX_SESSION>`
|
||||
|
||||
#### 路由 C：全栈 → 并行调用
|
||||
|
||||
1. **并行调用**（`run_in_background: true`）：
|
||||
* Gemini：处理前端部分
|
||||
* Codex：处理后端部分
|
||||
2. 使用 `TaskOutput` 等待两个模型的完整结果
|
||||
3. 每个模型使用计划中相应的 `SESSION_ID` 作为 `resume`（如果缺失则创建新会话）
|
||||
|
||||
**遵循上面 `IMPORTANT` 中的 `Multi-Model Call Specification` 指令**
|
||||
|
||||
***
|
||||
|
||||
### 阶段 4：代码实施
|
||||
|
||||
`[Mode: Implement]`
|
||||
|
||||
**Claude 作为代码主权执行以下步骤**：
|
||||
|
||||
1. **读取差异**：解析 Codex/Gemini 返回的统一差异补丁
|
||||
|
||||
2. **心智沙盒**：
|
||||
* 模拟将差异应用到目标文件
|
||||
* 检查逻辑一致性
|
||||
* 识别潜在冲突或副作用
|
||||
|
||||
3. **重构与清理**：
|
||||
* 将“脏原型”重构为**高度可读、可维护、企业级代码**
|
||||
* 移除冗余代码
|
||||
* 确保符合项目现有代码标准
|
||||
* **除非必要，不要生成注释/文档**，代码应具有自解释性
|
||||
|
||||
4. **最小范围**：
|
||||
* 更改仅限于需求范围
|
||||
* **强制审查**副作用
|
||||
* 进行针对性修正
|
||||
|
||||
5. **应用更改**：
|
||||
* 使用编辑/写入工具执行实际修改
|
||||
* **仅修改必要代码**，绝不影响用户的其他现有功能
|
||||
|
||||
6. **自验证**（强烈推荐）：
|
||||
* 运行项目现有的 lint / 类型检查 / 测试（优先考虑最小相关范围）
|
||||
* 如果失败：先修复回归问题，然后进入阶段 5
|
||||
|
||||
***
|
||||
|
||||
### 阶段 5：审计与交付
|
||||
|
||||
`[Mode: Audit]`
|
||||
|
||||
#### 5.1 自动审计
|
||||
|
||||
**更改生效后，必须立即并行调用** Codex 和 Gemini 进行代码审查：
|
||||
|
||||
1. **Codex 审查**（`run_in_background: true`）：
|
||||
* ROLE\_FILE：`~/.claude/.ccg/prompts/codex/reviewer.md`
|
||||
* 输入：更改的差异 + 目标文件
|
||||
* 重点：安全性、性能、错误处理、逻辑正确性
|
||||
|
||||
2. **Gemini 审查**（`run_in_background: true`）：
|
||||
* ROLE\_FILE：`~/.claude/.ccg/prompts/gemini/reviewer.md`
|
||||
* 输入：更改的差异 + 目标文件
|
||||
* 重点：可访问性、设计一致性、用户体验
|
||||
|
||||
使用 `TaskOutput` 等待两个模型的完整审查结果。优先重用阶段 3 的会话（`resume <SESSION_ID>`）以确保上下文一致性。
|
||||
|
||||
#### 5.2 整合与修复
|
||||
|
||||
1. 综合 Codex + Gemini 的审查反馈
|
||||
2. 按信任规则权衡：后端遵循 Codex，前端遵循 Gemini
|
||||
3. 执行必要的修复
|
||||
4. 根据需要重复阶段 5.1（直到风险可接受）
|
||||
|
||||
#### 5.3 交付确认
|
||||
|
||||
审计通过后，向用户报告：
|
||||
|
||||
```markdown
|
||||
## 执行完成
|
||||
|
||||
### 变更摘要
|
||||
| 文件 | 操作 | 描述 |
|
||||
|------|-----------|-------------|
|
||||
| path/to/file.ts | 已修改 | 描述 |
|
||||
|
||||
### 审计结果
|
||||
- Codex: <通过/发现 N 个问题>
|
||||
- Gemini: <通过/发现 N 个问题>
|
||||
|
||||
### 建议
|
||||
1. [ ] <建议的测试步骤>
|
||||
2. [ ] <建议的验证步骤>
|
||||
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 关键规则
|
||||
|
||||
1. **代码主权** – 所有文件修改由 Claude 执行，外部模型零写入权限
|
||||
2. **脏原型重构** – Codex/Gemini 输出视为草稿，必须重构
|
||||
3. **信任规则** – 后端遵循 Codex，前端遵循 Gemini
|
||||
4. **最小更改** – 仅修改必要代码，无副作用
|
||||
5. **强制审计** – 更改后必须执行多模型代码审查
|
||||
|
||||
***
|
||||
|
||||
## 使用方法
|
||||
|
||||
```bash
|
||||
# Execute plan file
|
||||
/ccg:execute .claude/plan/feature-name.md
|
||||
|
||||
# Execute task directly (for plans already discussed in context)
|
||||
/ccg:execute implement user authentication based on previous plan
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 与 /ccg:plan 的关系
|
||||
|
||||
1. `/ccg:plan` 生成计划 + SESSION\_ID
|
||||
2. 用户用“Y”确认
|
||||
3. `/ccg:execute` 读取计划，重用 SESSION\_ID，执行实施
|
||||
162
docs/zh-CN/commands/multi-frontend.md
Normal file
162
docs/zh-CN/commands/multi-frontend.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# 前端 - 前端聚焦开发
|
||||
|
||||
前端聚焦的工作流（研究 → 构思 → 规划 → 执行 → 优化 → 评审），由 Gemini 主导。
|
||||
|
||||
## 使用方法
|
||||
|
||||
```bash
|
||||
/frontend <UI task description>
|
||||
```
|
||||
|
||||
## 上下文
|
||||
|
||||
* 前端任务: $ARGUMENTS
|
||||
* Gemini 主导，Codex 作为辅助参考
|
||||
* 适用场景: 组件设计、响应式布局、UI 动画、样式优化
|
||||
|
||||
## 您的角色
|
||||
|
||||
您是 **前端协调器**，为 UI/UX 任务协调多模型协作（研究 → 构思 → 规划 → 执行 → 优化 → 评审）。
|
||||
|
||||
**协作模型**:
|
||||
|
||||
* **Gemini** – 前端 UI/UX（**前端权威，可信赖**）
|
||||
* **Codex** – 后端视角（**前端意见仅供参考**）
|
||||
* **Claude（自身）** – 协调、规划、执行、交付
|
||||
|
||||
***
|
||||
|
||||
## 多模型调用规范
|
||||
|
||||
**调用语法**:
|
||||
|
||||
```
|
||||
# New session call
|
||||
Bash({
|
||||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend gemini --gemini-model gemini-3-pro-preview - \"$PWD\" <<'EOF'
|
||||
ROLE_FILE: <role prompt path>
|
||||
<TASK>
|
||||
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
|
||||
Context: <project context and analysis from previous phases>
|
||||
</TASK>
|
||||
OUTPUT: Expected output format
|
||||
EOF",
|
||||
run_in_background: false,
|
||||
timeout: 3600000,
|
||||
description: "Brief description"
|
||||
})
|
||||
|
||||
# Resume session call
|
||||
Bash({
|
||||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend gemini --gemini-model gemini-3-pro-preview resume <SESSION_ID> - \"$PWD\" <<'EOF'
|
||||
ROLE_FILE: <role prompt path>
|
||||
<TASK>
|
||||
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
|
||||
Context: <project context and analysis from previous phases>
|
||||
</TASK>
|
||||
OUTPUT: Expected output format
|
||||
EOF",
|
||||
run_in_background: false,
|
||||
timeout: 3600000,
|
||||
description: "Brief description"
|
||||
})
|
||||
```
|
||||
|
||||
**角色提示词**:
|
||||
|
||||
| 阶段 | Gemini |
|
||||
|-------|--------|
|
||||
| 分析 | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
|
||||
| 规划 | `~/.claude/.ccg/prompts/gemini/architect.md` |
|
||||
| 评审 | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
|
||||
|
||||
**会话重用**: 每次调用返回 `SESSION_ID: xxx`，在后续阶段使用 `resume xxx`。在阶段 2 保存 `GEMINI_SESSION`，在阶段 3 和 5 使用 `resume`。
|
||||
|
||||
***
|
||||
|
||||
## 沟通指南
|
||||
|
||||
1. 以模式标签 `[Mode: X]` 开始响应，初始为 `[Mode: Research]`
|
||||
2. 遵循严格顺序: `Research → Ideation → Plan → Execute → Optimize → Review`
|
||||
3. 需要时（例如确认/选择/批准）使用 `AskUserQuestion` 工具进行用户交互
|
||||
|
||||
***
|
||||
|
||||
## 核心工作流
|
||||
|
||||
### 阶段 0: 提示词增强（可选）
|
||||
|
||||
`[Mode: Prepare]` - 如果 ace-tool MCP 可用，调用 `mcp__ace-tool__enhance_prompt`，**将原始的 $ARGUMENTS 替换为增强后的结果，用于后续的 Gemini 调用**
|
||||
|
||||
### 阶段 1: 研究
|
||||
|
||||
`[Mode: Research]` - 理解需求并收集上下文
|
||||
|
||||
1. **代码检索**（如果 ace-tool MCP 可用）: 调用 `mcp__ace-tool__search_context` 来检索现有的组件、样式、设计系统
|
||||
2. 需求完整性评分（0-10）: >=7 继续，<7 停止并补充
|
||||
|
||||
### 阶段 2: 构思
|
||||
|
||||
`[Mode: Ideation]` - Gemini 主导的分析
|
||||
|
||||
**必须调用 Gemini**（遵循上述调用规范）:
|
||||
|
||||
* ROLE\_FILE: `~/.claude/.ccg/prompts/gemini/analyzer.md`
|
||||
* 需求: 增强后的需求（或未经增强的 $ARGUMENTS）
|
||||
* 上下文: 来自阶段 1 的项目上下文
|
||||
* 输出: UI 可行性分析、推荐解决方案（至少 2 个）、UX 评估
|
||||
|
||||
**保存 SESSION\_ID**（`GEMINI_SESSION`）以供后续阶段重用。
|
||||
|
||||
输出解决方案（至少 2 个），等待用户选择。
|
||||
|
||||
### 阶段 3: 规划
|
||||
|
||||
`[Mode: Plan]` - Gemini 主导的规划
|
||||
|
||||
**必须调用 Gemini**（使用 `resume <GEMINI_SESSION>` 来重用会话）:
|
||||
|
||||
* ROLE\_FILE: `~/.claude/.ccg/prompts/gemini/architect.md`
|
||||
* 需求: 用户选择的解决方案
|
||||
* 上下文: 阶段 2 的分析结果
|
||||
* 输出: 组件结构、UI 流程、样式方案
|
||||
|
||||
Claude 综合规划，在用户批准后保存到 `.claude/plan/task-name.md`。
|
||||
|
||||
### 阶段 4: 实现
|
||||
|
||||
`[Mode: Execute]` - 代码开发
|
||||
|
||||
* 严格遵循批准的规划
|
||||
* 遵循现有项目设计系统和代码标准
|
||||
* 确保响应式设计、可访问性
|
||||
|
||||
### 阶段 5: 优化
|
||||
|
||||
`[Mode: Optimize]` - Gemini 主导的评审
|
||||
|
||||
**必须调用 Gemini**（遵循上述调用规范）:
|
||||
|
||||
* ROLE\_FILE: `~/.claude/.ccg/prompts/gemini/reviewer.md`
|
||||
* 需求: 评审以下前端代码变更
|
||||
* 上下文: git diff 或代码内容
|
||||
* 输出: 可访问性、响应式设计、性能、设计一致性等问题列表
|
||||
|
||||
整合评审反馈，在用户确认后执行优化。
|
||||
|
||||
### 阶段 6: 质量评审
|
||||
|
||||
`[Mode: Review]` - 最终评估
|
||||
|
||||
* 对照规划检查完成情况
|
||||
* 验证响应式设计和可访问性
|
||||
* 报告问题与建议
|
||||
|
||||
***
|
||||
|
||||
## 关键规则
|
||||
|
||||
1. **Gemini 的前端意见是可信赖的**
|
||||
2. **Codex 的前端意见仅供参考**
|
||||
3. 外部模型**没有文件系统写入权限**
|
||||
4. Claude 处理所有代码写入和文件操作
|
||||
270
docs/zh-CN/commands/multi-plan.md
Normal file
270
docs/zh-CN/commands/multi-plan.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# 计划 - 多模型协同规划
|
||||
|
||||
多模型协同规划 - 上下文检索 + 双模型分析 → 生成分步实施计划。
|
||||
|
||||
$ARGUMENTS
|
||||
|
||||
***
|
||||
|
||||
## 核心协议
|
||||
|
||||
* **语言协议**：与工具/模型交互时使用 **英语**，与用户沟通时使用其语言
|
||||
* **强制并行**：Codex/Gemini 调用 **必须** 使用 `run_in_background: true`（包括单模型调用，以避免阻塞主线程）
|
||||
* **代码主权**：外部模型 **零文件系统写入权限**，所有修改由 Claude 执行
|
||||
* **止损机制**：在当前阶段输出验证完成前，不进入下一阶段
|
||||
* **仅限规划**：此命令允许读取上下文并写入 `.claude/plan/*` 计划文件，但 **绝不修改生产代码**
|
||||
|
||||
***
|
||||
|
||||
## 多模型调用规范
|
||||
|
||||
**调用语法**（并行：使用 `run_in_background: true`）：
|
||||
|
||||
```
|
||||
Bash({
|
||||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
|
||||
ROLE_FILE: <role prompt path>
|
||||
<TASK>
|
||||
Requirement: <enhanced requirement>
|
||||
Context: <retrieved project context>
|
||||
</TASK>
|
||||
OUTPUT: Step-by-step implementation plan with pseudo-code. DO NOT modify any files.
|
||||
EOF",
|
||||
run_in_background: true,
|
||||
timeout: 3600000,
|
||||
description: "Brief description"
|
||||
})
|
||||
```
|
||||
|
||||
**模型参数说明**：
|
||||
|
||||
* `{{GEMINI_MODEL_FLAG}}`: 当使用 `--backend gemini` 时，替换为 `--gemini-model gemini-3-pro-preview`（注意尾随空格）；对于 codex 使用空字符串
|
||||
|
||||
**角色提示**：
|
||||
|
||||
| 阶段 | Codex | Gemini |
|
||||
|-------|-------|--------|
|
||||
| 分析 | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
|
||||
| 规划 | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
|
||||
|
||||
**会话复用**：每次调用返回 `SESSION_ID: xxx`（通常由包装器输出），**必须保存** 供后续 `/ccg:execute` 使用。
|
||||
|
||||
**等待后台任务**（最大超时 600000ms = 10 分钟）：
|
||||
|
||||
```
|
||||
TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
|
||||
```
|
||||
|
||||
**重要提示**：
|
||||
|
||||
* 必须指定 `timeout: 600000`，否则默认 30 秒会导致过早超时
|
||||
* 如果 10 分钟后仍未完成，继续使用 `TaskOutput` 轮询，**绝不终止进程**
|
||||
* 如果因超时而跳过等待，**必须调用 `AskUserQuestion` 询问用户是继续等待还是终止任务**
|
||||
|
||||
***
|
||||
|
||||
## 执行流程
|
||||
|
||||
**规划任务**：$ARGUMENTS
|
||||
|
||||
### 阶段 1：完整上下文检索
|
||||
|
||||
`[Mode: Research]`
|
||||
|
||||
#### 1.1 提示增强（必须先执行）
|
||||
|
||||
**必须调用 `mcp__ace-tool__enhance_prompt` 工具**：
|
||||
|
||||
```
|
||||
mcp__ace-tool__enhance_prompt({
|
||||
prompt: "$ARGUMENTS",
|
||||
conversation_history: "<last 5-10 conversation turns>",
|
||||
project_root_path: "$PWD"
|
||||
})
|
||||
```
|
||||
|
||||
等待增强后的提示，**将所有后续阶段的原始 $ARGUMENTS 替换为增强结果**。
|
||||
|
||||
#### 1.2 上下文检索
|
||||
|
||||
**调用 `mcp__ace-tool__search_context` 工具**：
|
||||
|
||||
```
|
||||
mcp__ace-tool__search_context({
|
||||
query: "<semantic query based on enhanced requirement>",
|
||||
project_root_path: "$PWD"
|
||||
})
|
||||
```
|
||||
|
||||
* 使用自然语言构建语义查询（Where/What/How）
|
||||
* **绝不基于假设回答**
|
||||
* 如果 MCP 不可用：回退到 Glob + Grep 进行文件发现和关键符号定位
|
||||
|
||||
#### 1.3 完整性检查
|
||||
|
||||
* 必须获取相关类、函数、变量的 **完整定义和签名**
|
||||
* 如果上下文不足，触发 **递归检索**
|
||||
* 输出优先级：入口文件 + 行号 + 关键符号名称；仅在必要时添加最小代码片段以消除歧义
|
||||
|
||||
#### 1.4 需求对齐
|
||||
|
||||
* 如果需求仍有歧义，**必须** 输出引导性问题给用户
|
||||
* 直到需求边界清晰（无遗漏，无冗余）
|
||||
|
||||
### 阶段 2：多模型协同分析
|
||||
|
||||
`[Mode: Analysis]`
|
||||
|
||||
#### 2.1 分发输入
|
||||
|
||||
**并行调用** Codex 和 Gemini（`run_in_background: true`）：
|
||||
|
||||
将 **原始需求**（不预设观点）分发给两个模型：
|
||||
|
||||
1. **Codex 后端分析**：
|
||||
* ROLE\_FILE：`~/.claude/.ccg/prompts/codex/analyzer.md`
|
||||
* 重点：技术可行性、架构影响、性能考虑、潜在风险
|
||||
* 输出：多视角解决方案 + 优缺点分析
|
||||
|
||||
2. **Gemini 前端分析**：
|
||||
* ROLE\_FILE：`~/.claude/.ccg/prompts/gemini/analyzer.md`
|
||||
* 重点：UI/UX 影响、用户体验、视觉设计
|
||||
* 输出：多视角解决方案 + 优缺点分析
|
||||
|
||||
使用 `TaskOutput` 等待两个模型的完整结果。**保存 SESSION\_ID**（`CODEX_SESSION` 和 `GEMINI_SESSION`）。
|
||||
|
||||
#### 2.2 交叉验证
|
||||
|
||||
整合视角并迭代优化：
|
||||
|
||||
1. **识别共识**（强信号）
|
||||
2. **识别分歧**（需要权衡）
|
||||
3. **互补优势**：后端逻辑遵循 Codex，前端设计遵循 Gemini
|
||||
4. **逻辑推理**：消除解决方案中的逻辑漏洞
|
||||
|
||||
#### 2.3（可选但推荐）双模型计划草案
|
||||
|
||||
为减少 Claude 综合计划中的遗漏风险，可以并行让两个模型输出“计划草案”（仍然 **不允许** 修改文件）：
|
||||
|
||||
1. **Codex 计划草案**（后端权威）：
|
||||
* ROLE\_FILE：`~/.claude/.ccg/prompts/codex/architect.md`
|
||||
* 输出：分步计划 + 伪代码（重点：数据流/边缘情况/错误处理/测试策略）
|
||||
|
||||
2. **Gemini 计划草案**（前端权威）：
|
||||
* ROLE\_FILE：`~/.claude/.ccg/prompts/gemini/architect.md`
|
||||
* 输出：分步计划 + 伪代码（重点：信息架构/交互/可访问性/视觉一致性）
|
||||
|
||||
使用 `TaskOutput` 等待两个模型的完整结果，记录它们建议的关键差异。
|
||||
|
||||
#### 2.4 生成实施计划（Claude 最终版本）
|
||||
|
||||
综合两个分析，生成 **分步实施计划**：
|
||||
|
||||
```markdown
|
||||
## 实施计划：<任务名称>
|
||||
|
||||
### 任务类型
|
||||
- [ ] 前端 (→ Gemini)
|
||||
- [ ] 后端 (→ Codex)
|
||||
- [ ] 全栈 (→ 并行)
|
||||
|
||||
### 技术解决方案
|
||||
<基于 Codex + Gemini 分析得出的最优解决方案>
|
||||
|
||||
### 实施步骤
|
||||
1. <步骤 1> - 预期交付物
|
||||
2. <步骤 2> - 预期交付物
|
||||
...
|
||||
|
||||
### 关键文件
|
||||
| 文件 | 操作 | 描述 |
|
||||
|------|-----------|-------------|
|
||||
| path/to/file.ts:L10-L50 | 修改 | 描述 |
|
||||
|
||||
### 风险与缓解措施
|
||||
| 风险 | 缓解措施 |
|
||||
|------|------------|
|
||||
|
||||
### SESSION_ID (供 /ccg:execute 使用)
|
||||
- CODEX_SESSION: <session_id>
|
||||
- GEMINI_SESSION: <session_id>
|
||||
|
||||
```
|
||||
|
||||
### 阶段 2 结束：计划交付（非执行）
|
||||
|
||||
**`/ccg:plan` 的职责到此结束，必须执行以下操作**：
|
||||
|
||||
1. 向用户呈现完整的实施计划（包括伪代码）
|
||||
|
||||
2. 将计划保存到 `.claude/plan/<feature-name>.md`（从需求中提取功能名称，例如 `user-auth`，`payment-module`）
|
||||
|
||||
3. 以 **粗体文本** 输出提示（必须使用实际保存的文件路径）：
|
||||
|
||||
***
|
||||
|
||||
**计划已生成并保存至 `.claude/plan/actual-feature-name.md`**
|
||||
|
||||
**请审阅以上计划。您可以：**
|
||||
|
||||
* **修改计划**：告诉我需要调整的内容，我会更新计划
|
||||
* **执行计划**：复制以下命令到新会话
|
||||
|
||||
```
|
||||
/ccg:execute .claude/plan/actual-feature-name.md
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
**注意**：上面的 `actual-feature-name.md` 必须替换为实际保存的文件名！
|
||||
|
||||
4. **立即终止当前响应**（在此停止。不再进行工具调用。）
|
||||
|
||||
**绝对禁止**：
|
||||
|
||||
* 询问用户“是/否”然后自动执行（执行是 `/ccg:execute` 的职责）
|
||||
* 任何对生产代码的写入操作
|
||||
* 自动调用 `/ccg:execute` 或任何实施操作
|
||||
* 当用户未明确请求修改时继续触发模型调用
|
||||
|
||||
***
|
||||
|
||||
## 计划保存
|
||||
|
||||
规划完成后，将计划保存至：
|
||||
|
||||
* **首次规划**：`.claude/plan/<feature-name>.md`
|
||||
* **迭代版本**：`.claude/plan/<feature-name>-v2.md`，`.claude/plan/<feature-name>-v3.md`...
|
||||
|
||||
计划文件写入应在向用户呈现计划前完成。
|
||||
|
||||
***
|
||||
|
||||
## 计划修改流程
|
||||
|
||||
如果用户请求修改计划：
|
||||
|
||||
1. 根据用户反馈调整计划内容
|
||||
2. 更新 `.claude/plan/<feature-name>.md` 文件
|
||||
3. 重新呈现修改后的计划
|
||||
4. 提示用户再次审阅或执行
|
||||
|
||||
***
|
||||
|
||||
## 后续步骤
|
||||
|
||||
用户批准后，**手动** 执行：
|
||||
|
||||
```bash
|
||||
/ccg:execute .claude/plan/<feature-name>.md
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 关键规则
|
||||
|
||||
1. **仅规划，不实施** – 此命令不执行任何代码更改
|
||||
2. **无是/否提示** – 仅呈现计划，让用户决定后续步骤
|
||||
3. **信任规则** – 后端遵循 Codex，前端遵循 Gemini
|
||||
4. 外部模型 **零文件系统写入权限**
|
||||
5. **SESSION\_ID 交接** – 计划末尾必须包含 `CODEX_SESSION` / `GEMINI_SESSION`（供 `/ccg:execute resume <SESSION_ID>` 使用）
|
||||
189
docs/zh-CN/commands/multi-workflow.md
Normal file
189
docs/zh-CN/commands/multi-workflow.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# 工作流程 - 多模型协同开发
|
||||
|
||||
多模型协同开发工作流程（研究 → 构思 → 规划 → 执行 → 优化 → 审查），带有智能路由：前端 → Gemini，后端 → Codex。
|
||||
|
||||
结构化开发工作流程，包含质量门控、MCP 服务和多模型协作。
|
||||
|
||||
## 使用方法
|
||||
|
||||
```bash
|
||||
/workflow <task description>
|
||||
```
|
||||
|
||||
## 上下文
|
||||
|
||||
* 待开发任务：$ARGUMENTS
|
||||
* 结构化的 6 阶段工作流程，包含质量门控
|
||||
* 多模型协作：Codex（后端） + Gemini（前端） + Claude（编排）
|
||||
* MCP 服务集成（ace-tool）以增强能力
|
||||
|
||||
## 你的角色
|
||||
|
||||
你是**编排者**，协调一个多模型协作系统（研究 → 构思 → 规划 → 执行 → 优化 → 审查）。为有经验的开发者进行简洁、专业的沟通。
|
||||
|
||||
**协作模型**：
|
||||
|
||||
* **ace-tool MCP** – 代码检索 + 提示词增强
|
||||
* **Codex** – 后端逻辑、算法、调试（**后端权威，可信赖**）
|
||||
* **Gemini** – 前端 UI/UX、视觉设计（**前端专家，后端意见仅供参考**）
|
||||
* **Claude（自身）** – 编排、规划、执行、交付
|
||||
|
||||
***
|
||||
|
||||
## 多模型调用规范
|
||||
|
||||
**调用语法**（并行：`run_in_background: true`，串行：`false`）：
|
||||
|
||||
```
|
||||
# New session call
|
||||
Bash({
|
||||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}- \"$PWD\" <<'EOF'
|
||||
ROLE_FILE: <role prompt path>
|
||||
<TASK>
|
||||
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
|
||||
Context: <project context and analysis from previous phases>
|
||||
</TASK>
|
||||
OUTPUT: Expected output format
|
||||
EOF",
|
||||
run_in_background: true,
|
||||
timeout: 3600000,
|
||||
description: "Brief description"
|
||||
})
|
||||
|
||||
# Resume session call
|
||||
Bash({
|
||||
command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--backend <codex|gemini> {{GEMINI_MODEL_FLAG}}resume <SESSION_ID> - \"$PWD\" <<'EOF'
|
||||
ROLE_FILE: <role prompt path>
|
||||
<TASK>
|
||||
Requirement: <enhanced requirement (or $ARGUMENTS if not enhanced)>
|
||||
Context: <project context and analysis from previous phases>
|
||||
</TASK>
|
||||
OUTPUT: Expected output format
|
||||
EOF",
|
||||
run_in_background: true,
|
||||
timeout: 3600000,
|
||||
description: "Brief description"
|
||||
})
|
||||
```
|
||||
|
||||
**模型参数说明**：
|
||||
|
||||
* `{{GEMINI_MODEL_FLAG}}`: 当使用 `--backend gemini` 时，替换为 `--gemini-model gemini-3-pro-preview`（注意末尾空格）；对于 codex 使用空字符串
|
||||
|
||||
**角色提示词**：
|
||||
|
||||
| 阶段 | Codex | Gemini |
|
||||
|-------|-------|--------|
|
||||
| 分析 | `~/.claude/.ccg/prompts/codex/analyzer.md` | `~/.claude/.ccg/prompts/gemini/analyzer.md` |
|
||||
| 规划 | `~/.claude/.ccg/prompts/codex/architect.md` | `~/.claude/.ccg/prompts/gemini/architect.md` |
|
||||
| 审查 | `~/.claude/.ccg/prompts/codex/reviewer.md` | `~/.claude/.ccg/prompts/gemini/reviewer.md` |
|
||||
|
||||
**会话复用**：每次调用返回 `SESSION_ID: xxx`，在后续阶段使用 `resume xxx` 子命令（注意：`resume`，而非 `--resume`）。
|
||||
|
||||
**并行调用**：使用 `run_in_background: true` 启动，使用 `TaskOutput` 等待结果。**必须等待所有模型返回后才能进入下一阶段**。
|
||||
|
||||
**等待后台任务**（使用最大超时 600000ms = 10 分钟）：
|
||||
|
||||
```
|
||||
TaskOutput({ task_id: "<task_id>", block: true, timeout: 600000 })
|
||||
```
|
||||
|
||||
**重要**：
|
||||
|
||||
* 必须指定 `timeout: 600000`，否则默认 30 秒会导致过早超时。
|
||||
* 如果 10 分钟后仍未完成，继续使用 `TaskOutput` 轮询，**切勿终止进程**。
|
||||
* 如果因超时而跳过等待，**必须调用 `AskUserQuestion` 询问用户是继续等待还是终止任务。切勿直接终止。**
|
||||
|
||||
***
|
||||
|
||||
## 沟通指南
|
||||
|
||||
1. 回复以模式标签 `[Mode: X]` 开头，初始为 `[Mode: Research]`。
|
||||
2. 遵循严格顺序：`Research → Ideation → Plan → Execute → Optimize → Review`。
|
||||
3. 每个阶段完成后请求用户确认。
|
||||
4. 当评分 < 7 或用户不批准时强制停止。
|
||||
5. 需要时（例如确认/选择/批准）使用 `AskUserQuestion` 工具进行用户交互。
|
||||
|
||||
***
|
||||
|
||||
## 执行工作流程
|
||||
|
||||
**任务描述**：$ARGUMENTS
|
||||
|
||||
### 阶段 1：研究与分析
|
||||
|
||||
`[Mode: Research]` - 理解需求并收集上下文：
|
||||
|
||||
1. **提示词增强**：调用 `mcp__ace-tool__enhance_prompt`，**将所有后续对 Codex/Gemini 的调用中的原始 $ARGUMENTS 替换为增强后的结果**
|
||||
2. **上下文检索**：调用 `mcp__ace-tool__search_context`
|
||||
3. **需求完整性评分** (0-10)：
|
||||
* 目标清晰度 (0-3)，预期成果 (0-3)，范围边界 (0-2)，约束条件 (0-2)
|
||||
* ≥7：继续 | <7：停止，询问澄清问题
|
||||
|
||||
### 阶段 2：解决方案构思
|
||||
|
||||
`[Mode: Ideation]` - 多模型并行分析：
|
||||
|
||||
**并行调用** (`run_in_background: true`)：
|
||||
|
||||
* Codex：使用分析器提示词，输出技术可行性、解决方案、风险
|
||||
* Gemini：使用分析器提示词，输出 UI 可行性、解决方案、UX 评估
|
||||
|
||||
使用 `TaskOutput` 等待结果。**保存 SESSION\_ID** (`CODEX_SESSION` 和 `GEMINI_SESSION`)。
|
||||
|
||||
**遵循上方 `Multi-Model Call Specification` 中的 `IMPORTANT` 说明**
|
||||
|
||||
综合两项分析，输出解决方案比较（至少 2 个选项），等待用户选择。
|
||||
|
||||
### 阶段 3：详细规划
|
||||
|
||||
`[Mode: Plan]` - 多模型协作规划：
|
||||
|
||||
**并行调用**（使用 `resume <SESSION_ID>` 恢复会话）：
|
||||
|
||||
* Codex：使用架构师提示词 + `resume $CODEX_SESSION`，输出后端架构
|
||||
* Gemini：使用架构师提示词 + `resume $GEMINI_SESSION`，输出前端架构
|
||||
|
||||
使用 `TaskOutput` 等待结果。
|
||||
|
||||
**遵循上方 `Multi-Model Call Specification` 中的 `IMPORTANT` 说明**
|
||||
|
||||
**Claude 综合**：采纳 Codex 后端计划 + Gemini 前端计划，在用户批准后保存到 `.claude/plan/task-name.md`。
|
||||
|
||||
### 阶段 4：实施
|
||||
|
||||
`[Mode: Execute]` - 代码开发：
|
||||
|
||||
* 严格遵循批准的计划
|
||||
* 遵循现有项目代码标准
|
||||
* 在关键里程碑请求反馈
|
||||
|
||||
### 阶段 5：代码优化
|
||||
|
||||
`[Mode: Optimize]` - 多模型并行审查：
|
||||
|
||||
**并行调用**：
|
||||
|
||||
* Codex：使用审查者提示词，关注安全性、性能、错误处理
|
||||
* Gemini：使用审查者提示词，关注可访问性、设计一致性
|
||||
|
||||
使用 `TaskOutput` 等待结果。整合审查反馈，在用户确认后执行优化。
|
||||
|
||||
**遵循上方 `Multi-Model Call Specification` 中的 `IMPORTANT` 说明**
|
||||
|
||||
### 阶段 6：质量审查
|
||||
|
||||
`[Mode: Review]` - 最终评估：
|
||||
|
||||
* 对照计划检查完成情况
|
||||
* 运行测试以验证功能
|
||||
* 报告问题和建议
|
||||
* 请求最终用户确认
|
||||
|
||||
***
|
||||
|
||||
## 关键规则
|
||||
|
||||
1. 阶段顺序不可跳过（除非用户明确指示）
|
||||
2. 外部模型**对文件系统零写入权限**，所有修改由 Claude 执行
|
||||
3. 当评分 < 7 或用户不批准时**强制停止**
|
||||
283
docs/zh-CN/commands/pm2.md
Normal file
283
docs/zh-CN/commands/pm2.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# PM2 初始化
|
||||
|
||||
自动分析项目并生成 PM2 服务命令。
|
||||
|
||||
**命令**: `$ARGUMENTS`
|
||||
|
||||
***
|
||||
|
||||
## 工作流程
|
||||
|
||||
1. 检查 PM2（如果缺失，通过 `npm install -g pm2` 安装）
|
||||
2. 扫描项目以识别服务（前端/后端/数据库）
|
||||
3. 生成配置文件和各命令文件
|
||||
|
||||
***
|
||||
|
||||
## 服务检测
|
||||
|
||||
| 类型 | 检测方式 | 默认端口 |
|
||||
|------|-----------|--------------|
|
||||
| Vite | vite.config.\* | 5173 |
|
||||
| Next.js | next.config.\* | 3000 |
|
||||
| Nuxt | nuxt.config.\* | 3000 |
|
||||
| CRA | package.json 中的 react-scripts | 3000 |
|
||||
| Express/Node | server/backend/api 目录 + package.json | 3000 |
|
||||
| FastAPI/Flask | requirements.txt / pyproject.toml | 8000 |
|
||||
| Go | go.mod / main.go | 8080 |
|
||||
|
||||
**端口检测优先级**: 用户指定 > .env 文件 > 配置文件 > 脚本参数 > 默认端口
|
||||
|
||||
***
|
||||
|
||||
## 生成的文件
|
||||
|
||||
```
|
||||
project/
|
||||
├── ecosystem.config.cjs # PM2 config
|
||||
├── {backend}/start.cjs # Python wrapper (if applicable)
|
||||
└── .claude/
|
||||
├── commands/
|
||||
│ ├── pm2-all.md # Start all + monit
|
||||
│ ├── pm2-all-stop.md # Stop all
|
||||
│ ├── pm2-all-restart.md # Restart all
|
||||
│ ├── pm2-{port}.md # Start single + logs
|
||||
│ ├── pm2-{port}-stop.md # Stop single
|
||||
│ ├── pm2-{port}-restart.md # Restart single
|
||||
│ ├── pm2-logs.md # View all logs
|
||||
│ └── pm2-status.md # View status
|
||||
└── scripts/
|
||||
├── pm2-logs-{port}.ps1 # Single service logs
|
||||
└── pm2-monit.ps1 # PM2 monitor
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## Windows 配置（重要）
|
||||
|
||||
### ecosystem.config.cjs
|
||||
|
||||
**必须使用 `.cjs` 扩展名**
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
apps: [
|
||||
// Node.js (Vite/Next/Nuxt)
|
||||
{
|
||||
name: 'project-3000',
|
||||
cwd: './packages/web',
|
||||
script: 'node_modules/vite/bin/vite.js',
|
||||
args: '--port 3000',
|
||||
interpreter: 'C:/Program Files/nodejs/node.exe',
|
||||
env: { NODE_ENV: 'development' }
|
||||
},
|
||||
// Python
|
||||
{
|
||||
name: 'project-8000',
|
||||
cwd: './backend',
|
||||
script: 'start.cjs',
|
||||
interpreter: 'C:/Program Files/nodejs/node.exe',
|
||||
env: { PYTHONUNBUFFERED: '1' }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**框架脚本路径:**
|
||||
|
||||
| 框架 | script | args |
|
||||
|-----------|--------|------|
|
||||
| Vite | `node_modules/vite/bin/vite.js` | `--port {port}` |
|
||||
| Next.js | `node_modules/next/dist/bin/next` | `dev -p {port}` |
|
||||
| Nuxt | `node_modules/nuxt/bin/nuxt.mjs` | `dev --port {port}` |
|
||||
| Express | `src/index.js` 或 `server.js` | - |
|
||||
|
||||
### Python 包装脚本 (start.cjs)
|
||||
|
||||
```javascript
|
||||
const { spawn } = require('child_process');
|
||||
const proc = spawn('python', ['-m', 'uvicorn', 'app.main:app', '--host', '0.0.0.0', '--port', '8000', '--reload'], {
|
||||
cwd: __dirname, stdio: 'inherit', windowsHide: true
|
||||
});
|
||||
proc.on('close', (code) => process.exit(code));
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 命令文件模板（最简内容）
|
||||
|
||||
### pm2-all.md (启动所有 + 监控)
|
||||
|
||||
````markdown
|
||||
启动所有服务并打开 PM2 监控器。
|
||||
```bash
|
||||
cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 monit"
|
||||
```
|
||||
````
|
||||
|
||||
### pm2-all-stop.md
|
||||
|
||||
````markdown
|
||||
停止所有服务。
|
||||
```bash
|
||||
cd "{PROJECT_ROOT}" && pm2 stop all
|
||||
```
|
||||
````
|
||||
|
||||
### pm2-all-restart.md
|
||||
|
||||
````markdown
|
||||
重启所有服务。
|
||||
```bash
|
||||
cd "{PROJECT_ROOT}" && pm2 restart all
|
||||
```
|
||||
````
|
||||
|
||||
### pm2-{port}.md (启动单个 + 日志)
|
||||
|
||||
````markdown
|
||||
启动 {name} ({port}) 并打开日志。
|
||||
```bash
|
||||
cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs --only {name} && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 logs {name}"
|
||||
```
|
||||
````
|
||||
|
||||
### pm2-{port}-stop.md
|
||||
|
||||
````markdown
|
||||
停止 {name} ({port})。
|
||||
```bash
|
||||
cd "{PROJECT_ROOT}" && pm2 stop {name}
|
||||
```
|
||||
````
|
||||
|
||||
### pm2-{port}-restart.md
|
||||
|
||||
````markdown
|
||||
重启 {name} ({port})。
|
||||
```bash
|
||||
cd "{PROJECT_ROOT}" && pm2 restart {name}
|
||||
```
|
||||
````
|
||||
|
||||
### pm2-logs.md
|
||||
|
||||
````markdown
|
||||
查看所有 PM2 日志。
|
||||
```bash
|
||||
cd "{PROJECT_ROOT}" && pm2 logs
|
||||
```
|
||||
````
|
||||
|
||||
### pm2-status.md
|
||||
|
||||
````markdown
|
||||
查看 PM2 状态。
|
||||
```bash
|
||||
cd "{PROJECT_ROOT}" && pm2 status
|
||||
```
|
||||
````
|
||||
|
||||
### PowerShell 脚本 (pm2-logs-{port}.ps1)
|
||||
|
||||
```powershell
|
||||
Set-Location "{PROJECT_ROOT}"
|
||||
pm2 logs {name}
|
||||
```
|
||||
|
||||
### PowerShell 脚本 (pm2-monit.ps1)
|
||||
|
||||
```powershell
|
||||
Set-Location "{PROJECT_ROOT}"
|
||||
pm2 monit
|
||||
```
|
||||
|
||||
***
|
||||
|
||||
## 关键规则
|
||||
|
||||
1. **配置文件**: `ecosystem.config.cjs` (不是 .js)
|
||||
2. **Node.js**: 直接指定 bin 路径 + 解释器
|
||||
3. **Python**: Node.js 包装脚本 + `windowsHide: true`
|
||||
4. **打开新窗口**: `start wt.exe -d "{path}" pwsh -NoExit -c "command"`
|
||||
5. **最简内容**: 每个命令文件只有 1-2 行描述 + bash 代码块
|
||||
6. **直接执行**: 无需 AI 解析，直接运行 bash 命令
|
||||
|
||||
***
|
||||
|
||||
## 执行
|
||||
|
||||
基于 `$ARGUMENTS`，执行初始化：
|
||||
|
||||
1. 扫描项目服务
|
||||
2. 生成 `ecosystem.config.cjs`
|
||||
3. 为 Python 服务生成 `{backend}/start.cjs`（如果适用）
|
||||
4. 在 `.claude/commands/` 中生成命令文件
|
||||
5. 在 `.claude/scripts/` 中生成脚本文件
|
||||
6. **更新项目 CLAUDE.md**，添加 PM2 信息（见下文）
|
||||
7. **显示完成摘要**，包含终端命令
|
||||
|
||||
***
|
||||
|
||||
## 初始化后：更新 CLAUDE.md
|
||||
|
||||
生成文件后，将 PM2 部分追加到项目的 `CLAUDE.md`（如果不存在则创建）：
|
||||
|
||||
````markdown
|
||||
## PM2 服务
|
||||
|
||||
| 端口 | 名称 | 类型 |
|
||||
|------|------|------|
|
||||
| {port} | {name} | {type} |
|
||||
|
||||
**终端命令：**
|
||||
```bash
|
||||
pm2 start ecosystem.config.cjs # First time
|
||||
pm2 start all # After first time
|
||||
pm2 stop all / pm2 restart all
|
||||
pm2 start {name} / pm2 stop {name}
|
||||
pm2 logs / pm2 status / pm2 monit
|
||||
pm2 save # Save process list
|
||||
pm2 resurrect # Restore saved list
|
||||
```
|
||||
````
|
||||
|
||||
**更新 CLAUDE.md 的规则：**
|
||||
|
||||
* 如果存在 PM2 部分，替换它
|
||||
* 如果不存在，追加到末尾
|
||||
* 保持内容精简且必要
|
||||
|
||||
***
|
||||
|
||||
## 初始化后：显示摘要
|
||||
|
||||
所有文件生成后，输出：
|
||||
|
||||
```
|
||||
## PM2 Init Complete
|
||||
|
||||
**Services:**
|
||||
|
||||
| Port | Name | Type |
|
||||
|------|------|------|
|
||||
| {port} | {name} | {type} |
|
||||
|
||||
**Claude Commands:** /pm2-all, /pm2-all-stop, /pm2-{port}, /pm2-{port}-stop, /pm2-logs, /pm2-status
|
||||
|
||||
**Terminal Commands:**
|
||||
## First time (with config file)
|
||||
pm2 start ecosystem.config.cjs && pm2 save
|
||||
|
||||
## After first time (simplified)
|
||||
pm2 start all # Start all
|
||||
pm2 stop all # Stop all
|
||||
pm2 restart all # Restart all
|
||||
pm2 start {name} # Start single
|
||||
pm2 stop {name} # Stop single
|
||||
pm2 logs # View logs
|
||||
pm2 monit # Monitor panel
|
||||
pm2 resurrect # Restore saved processes
|
||||
|
||||
**Tip:** Run `pm2 save` after first start to enable simplified commands.
|
||||
```
|
||||
Reference in New Issue
Block a user