---
title: 常见问题（FAQ）
sidebar_label: 常见问题
sidebar_position: 99
---

import Details from '@theme/Details';

# 常见问题（FAQ）

关于 CCW、工作流、命令与排错的常见问题汇总。

## 通用问题

### CCW 是什么？

CCW（Claude Code Workflows）是一套面向工程实践的工作流自动化平台：将 AI 能力与结构化开发流程结合，提供 40+ 命令与 15 个集成工作流，帮助你更快、更稳地完成开发，同时保持质量标准。

**核心特性：**
- AI 驱动的代码分析 / 生成 / Review
- 15 个工作流级别：从快速执行到智能编排
- Session 管理：完整状态持久化，可暂停/恢复
- 多 Agent 并行协作：支持并行任务与依赖分析
- 内置测试、验证与代码审查

### 系统要求是什么？

**最低要求：**
- Node.js 16.x 或更高
- Git 2.x 或更高
- 可用内存 4GB
- 磁盘空间 500MB

**推荐配置：**
- Node.js 18.x LTS
- 可用内存 8GB
- 磁盘空间 2GB（用于 artifacts 与 sessions）

### 如何安装 CCW？

```bash
# npm 全局安装
npm install -g @ccw/cli

# 或使用 npx（无需安装）
npx @ccw/cli init

# 在项目中初始化
ccw init
```

### CCW 是否免费？

是的，CCW 开源且免费使用。但 CCW 会集成第三方 AI 服务（Gemini、Codex、Claude、Qwen 等），这些服务可能有各自的计费方式。你需要为所使用的 AI 服务配置对应的 API Key。

### 支持哪些编程语言？

CCW 支持所有编程语言。AI 模型可以分析与生成任意语言代码，例如：

- **Web**：JavaScript、TypeScript、Python、PHP、Ruby
- **Mobile**：Swift、Kotlin、React Native、Flutter
- **Systems**：Rust、Go、C、C++
- **Data**：Python、R、SQL
- **Enterprise**：Java、C#、.NET

## 工作流选择

### 如何选择合适的工作流？

<Details>
<summary>决策框架</summary>

可以用下面这棵“快速决策树”：

1. **是开发后期维护（合并后修复/增强）？** → 使用 [Issue Workflow](/workflows/faq#what-is-the-difference-between-main-workflow-and-issue-workflow)
2. **不确定该用哪些命令？** → 用 `ccw-coordinator`（Level 5）
3. **需求不清晰/要探索方案？** → 用 `brainstorm:auto-parallel`（Level 4）
4. **需要可恢复的持久 session？**
   - 标准开发 → `plan` → `execute`（Level 3）
   - TDD → `tdd-plan` → `execute`（Level 3）
   - 修复测试 → `test-fix-gen` → `test-cycle-execute`（Level 3）
5. **需要多视角对比分析？** → 用 `multi-cli-plan`（Level 2）
6. **要修 Bug？** → 用 `lite-fix`（Level 2）
7. **需要简单规划？** → 用 `lite-plan` → `lite-execute`（Level 2）
8. **只是很快的小任务？** → 用 `lite-lite-lite`（Level 1）

</Details>

### Main Workflow 与 Issue Workflow 有什么区别？

<Details>
<summary>对比说明</summary>

**Main Workflow** 用于主开发流程：
- 功能开发（Levels 1-5）
- 处于活跃开发阶段
- 基于依赖的并行
- 在当前分支工作

**Issue Workflow** 用于开发后期维护：
- 合并后的 bug 修复与增强
- 主工作流完成之后
- 可选 worktree 隔离
- 保持主分支稳定

| 维度 | Main Workflow | Issue Workflow |
|------|---------------|----------------|
| **目的** | 功能开发 | 开发后修复 |
| **时机** | 开发阶段 | 主工作流完成之后 |
| **范围** | 完整功能实现 | 定点修复/增强 |
| **并行策略** | 依赖分析 | worktree 隔离（可选） |
| **分支模型** | 当前分支开发 | 可使用隔离 worktree |

</Details>

### 什么是“最小执行单元”（Minimum Execution Units）？

<Details>
<summary>解释</summary>

**最小执行单元** 指的是必须作为一个原子组一起执行的一组命令，用来达成“有意义的里程碑”。如果把这些命令拆开执行，逻辑链条会被打断，容易产生不完整状态。

**常见最小执行单元：**

| 单元 | 命令 | 目的 |
|------|----------|---------|
| 快速实现 | `lite-plan` → `lite-execute` | 轻量规划 + 执行 |
| 多 CLI 规划 | `multi-cli-plan` → `lite-execute` | 多视角分析 + 执行 |
| Bug 修复 | `lite-fix` → `lite-execute` | 诊断 + 修复执行 |
| 可验证规划 | `plan` → `plan-verify` → `execute` | 规划 + 验证 + 执行 |
| TDD 规划 | `tdd-plan` → `execute` | 测试驱动的规划与执行 |
| 测试修复循环 | `test-fix-gen` → `test-cycle-execute` | 生成测试任务 + 执行修复循环 |

**示例**：`lite-plan → lite-execute` 必须配套完成。如果只做到 `lite-plan` 就停下，会得到一个计划但没有实现。

</Details>

### 各个工作流级别分别适用于什么场景？

<Details>
<summary>级别选择指南</summary>

**Level 1（lite-lite-lite）：**
- 快速修补（拼写、轻微调整）
- 简单功能（单函数、小工具）
- 配置修改（环境变量、超时）
- 文档更新

**Level 2（lite-plan、lite-fix、multi-cli-plan）：**
- 单模块功能
- Bug 诊断与修复
- 技术选型决策
- 方案对比

**Level 3（plan、tdd-plan、test-fix-gen）：**
- 多模块变更
- 重构
- TDD
- 测试失败修复

**Level 4（brainstorm:auto-parallel）：**
- 新功能设计
- 系统架构重构
- 探索性需求
- 多维权衡

**Level 5（ccw-coordinator）：**
- 复杂多步工作流
- 不确定使用哪些命令
- 端到端自动化
- 团队协作

**Issue Workflow：**
- 开发后期的 Issue 修复
- 维护主分支稳定性

</Details>

## 命令使用

### 工作流命令怎么用？

<Details>
<summary>常见命令模式</summary>

**基本格式：**
```bash
ccw &lt;command&gt; &lt;arguments&gt;
```

**示例：**
```bash
# Level 1 - 直接执行
ccw lite-lite-lite "Fix login button"

# Level 2 - 轻量规划
ccw lite-plan "Add user profile page"
ccw lite-execute --in-memory

# Level 3 - 完整工作流
ccw workflow:plan "Implement OAuth2"
ccw workflow:execute --session WFS-oauth-auth

# Level 4 - 头脑风暴
ccw brainstorm:auto-parallel "Design notification system"

# Level 5 - 智能编排
ccw ccw-coordinator "Refactor API layer"
```

</Details>

### lite-execute 与 execute 有什么区别？

<Details>
<summary>对比</summary>

**lite-execute（Level 2）：**
```bash
ccw lite-execute --in-memory
```
- 面向 Level 2 工作流
- 内存规划（不生成 session 文件）
- 可对独立任务并行执行
- 可选代码审查

**execute（Level 3）：**
```bash
ccw workflow:execute --session WFS-{session-id}
```
- 面向 Level 3 工作流
- 基于 session 的执行
- 依赖分析
- 完整状态跟踪，可暂停/恢复
- 任务完成总结

</Details>

### 如何使用 hotfix 模式？

<Details>
<summary>Hotfix 用法</summary>

**Hotfix 模式** 用于生产环境紧急修复：

```bash
ccw lite-fix --hotfix "Production database connection failing"
```

**它会做什么：**
- 跳过大多数诊断阶段
- 最小化规划（更偏向直接执行）
- 自动生成后续任务，用于完整修复与复盘（post-mortem）

**何时使用：**
- 生产事故
- 需要立刻修复的严重 bug
- 宕机与服务中断

**修复之后：**
CCW 会自动生成后续任务，包括：
- 完整根因分析
- 全面修复
- 复盘文档

</Details>

### 如何恢复（resume）一个暂停的 session？

<Details>
<summary>Session 恢复</summary>

```bash
# 恢复最近的 session
ccw workflow:session:resume

# 恢复指定 session
ccw workflow:session:resume WFS-user-auth-v2

# 列出全部 session
ccw workflow:session:list
```

**Session 状态：**
- **active**：正在运行
- **paused**：暂停，可恢复
- **completed**：已完成并归档

</Details>

## AI 模型

### CCW 支持哪些 AI 模型？

<Details>
<summary>支持的模型</summary>

CCW 通过 CLI 端点支持多个模型：

| 模型 | 能力 | 最适合 |
|-------|--------------|----------|
| **Gemini** | Analysis + Write | Code review、调试、重构 |
| **Codex** | Analysis + Write + Review | Git-aware review、实现 |
| **Claude** | Analysis + Write | 复杂推理、文档 |
| **Qwen** | Analysis + Write | 代码生成、模式匹配 |

可在 `~/.claude/cli-tools.json` 中配置模型端点。

</Details>

### 如何配置 API Key？

<Details>
<summary>API Key 配置</summary>

**使用环境变量：**

```bash
# Gemini
export GEMINI_API_KEY="your-key-here"

# OpenAI (Codex)
export OPENAI_API_KEY="your-key-here"

# Anthropic (Claude)
export ANTHROPIC_API_KEY="your-key-here"

# Qwen
export DASHSCOPE_API_KEY="your-key-here"
```

**或在 `.env` 文件中配置：**
```env
GEMINI_API_KEY=your-key-here
OPENAI_API_KEY=your-key-here
ANTHROPIC_API_KEY=your-key-here
DASHSCOPE_API_KEY=your-key-here
```

</Details>

### 什么是 multi-CLI 协作？

<Details>
<summary>multi-CLI 说明</summary>

**multi-CLI 协作** 会让多个 AI 模型从不同视角并行分析同一个问题：

```bash
ccw multi-cli-plan "Compare Redis vs RabbitMQ for message queuing"
```

**工作方式：**
1. 多个模型独立分析
2. 各自给出洞察与建议
3. 汇总为更完整的分析结论
4. 在决策前获得更多视角

**适用场景：**
- 技术选型
- 架构决策
- 方案对比
- 权衡分析

</Details>

## 测试

### 如何为存量代码补充测试？

<Details>
<summary>生成测试</summary>

**Session 模式（基于已有 session）：**
```bash
ccw test-fix-gen WFS-user-auth-v2
```

**Prompt 模式（直接描述需求）：**
```bash
ccw test-fix-gen "Add unit tests for the auth API"
```

**CCW 会：**
1. 分析代码结构
2. 生成合适的测试用例
3. 按项目模式创建测试文件
4. 编写断言并实现测试

</Details>

### 如何修复失败的测试？

<Details>
<summary>测试修复流程</summary>

```bash
# 生成测试修复任务
ccw test-fix-gen "Tests failing for user registration"

# 执行 test-fix 循环
ccw test-cycle-execute
```

**流程：**
1. 分析测试失败原因
2. 定位根因
3. 迭代修复
4. 验证通过率 >= 95%
5. 通过则停止，否则在达到最大迭代次数后停止

</Details>

### 什么是 TDD（测试驱动开发）？

<Details>
<summary>TDD 说明</summary>

**TDD** 遵循“Red-Green-Refactor”循环：

1. **Red**：先写一个失败的测试
2. **Green**：写最少的代码让测试通过
3. **Refactor**：在保持测试通过的前提下改进代码

**铁律：**
```
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
```

**为什么要先写测试？**

| 维度 | Test-First | Test-After |
|--------|-----------|------------|
| **证据** | 先失败再实现（能证明实现有效） | 立即通过（证明不了什么） |
| **发现** | 编码前发现边界条件 | 编码后才发现边界条件 |
| **验证** | 验证需求 | 验证实现 |

</Details>

## 故障排查

### 我的工作流失败了，该怎么办？

<Details>
<summary>排查步骤</summary>

1. **查看报错信息** - 识别根因线索
2. **检查 session 状态** - 查看 `.workflow/.ccw-coordinator/{session}/state.json`
3. **恢复 session** - 使用 `ccw workflow:session:resume` 继续
4. **调整后重试** - 根据错误调整方案

**常见修复：**
- **API key 错误**：确认环境变量已设置
- **Module not found**：运行 `npm install` 或 `pip install`
- **Git 错误**：确保 git 状态干净（`git status`）
- **超时错误**：在任务 JSON 中增加超时时间

</Details>

### 如何跳过一个失败的任务？

<Details>
<summary>跳过任务</summary>

编辑任务 JSON，把 status 设置为 `"completed"`：

```bash
jq '.status = "completed"' .workflow/active/WFS-{session}/.task/IMPL-001.json
```

**谨慎使用**：跳过任务可能导致工作流处于不完整状态。

</Details>

### 如何清理旧的 sessions？

<Details>
<summary>清理命令</summary>

```bash
# 列出 sessions
ccw workflow:session:list

# 删除指定 session
rm -rf .workflow/active/WFS-{session-id}

# 清理所有已完成 sessions
ccw workflow:clean
```

**自动清理：**
- 已完成 sessions 会归档到 `.workflow/completed/`
- 旧 sessions（> 30 天）通常可安全删除

</Details>

### 为什么我的工作流很慢？

<Details>
<summary>性能建议</summary>

**可能原因：**

1. **代码库很大**：CCW 会分析整个项目
   - **建议**：使用 `--focus-paths` 限制分析范围

2. **依赖很多**：AI 响应慢
   - **建议**：用更快的模型（如 Gemini Flash）先做初步分析

3. **任务串行**：在等依赖任务完成
   - **建议**：在 `plan-verify` 中检查依赖关系

4. **网络问题**：访问 AI 服务的 API 慢
   - **建议**：检查网络与服务状态

**优化示例：**
```bash
# 限制分析范围
ccw plan "Add login" --focus-paths src/auth

# 先用更快的模型
ccw cli -p "Quick analysis" --model gemini-2.0-flash --mode analysis

# 尽量并行
ccw workflow:execute --parallel 4
```

</Details>

### 如何调试工作流问题？

<Details>
<summary>调试工作流</summary>

**开启 debug 日志：**
```bash
DEBUG=ccw:* ccw workflow:plan "My feature"
```

**查看 session 日志：**
```bash
# 查看 session 状态
cat .workflow/active/WFS-{session}/workflow-session.json

# 查看任务进度
cat .workflow/active/WFS-{session}/TODO_LIST.md
```

**使用 debug 工作流：**
```bash
ccw workflow:debug-with-file "Debug memory leak in connection handler"
```

该工作流会以“假设驱动”的方式调试，并把探索过程文档化。

</Details>

## 集成

### CCW 能否集成到现有的 CI/CD？

<Details>
<summary>CI/CD 集成</summary>

可以。CCW 可用于 CI/CD 流程，例如：

**GitHub Actions 示例：**
```yaml
- name: Run CCW Workflow
  run: |
    ccw workflow:plan "Implement feature"
    ccw workflow:execute --session WFS-feature
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
```

**最佳实践：**
- 在 CI 中用 `--mode analysis` 做代码审查
- API key 存放在 secrets 管理中
- 在隔离环境中运行工作流
- 归档 sessions 便于审计追踪

</Details>

### CCW 支持 monorepo 吗？

<Details>
<summary>Monorepo 支持</summary>

支持。

**面向 workspace 的执行：**
```bash
# 在指定 package 中执行
ccw plan "Add auth to frontend" --cd packages/frontend

# 跨多个 package 执行
ccw plan "Update API contracts" --include-dir packages/api,packages/shared
```

**好处：**
- 依赖感知的任务分发
- 跨包并行执行
- 共享 session 状态
- 跨 workspace 协同变更

</Details>

### 如何从其他工具迁移？

<Details>
<summary>迁移指南</summary>

**从基础 Git 工作流迁移：**
```bash
# 之前：手工规划
git checkout -b feature
# ... manual planning ...

# 之后：用 CCW 做规划
ccw plan "Add feature"
ccw execute --session WFS-feature
```

**从其他 AI 工具迁移：**
- CCW 提供结构化工作流（而非零散提示）
- Session 管理（而非依赖聊天记录）
- 多 Agent 协作（而非单一 AI）
- 持久化产物（而非一次性输出）

**迁移步骤：**
1. 安装 CCW：`npm install -g @ccw/cli`
2. 初始化：`ccw init`
3. 从 Level 2 工作流开始熟悉
4. 逐步在更复杂任务中采用更高等级

</Details>

## 最佳实践

### 工作流最佳实践有哪些？

<Details>
<summary>最佳实践</summary>

**1. 先从简单开始**
- 使用能满足需求的最低工作流级别
- 不要为简单任务过度工程化
- 随着复杂度增加再升级工作流

**2. 先规划再执行**
- 有验证步骤就尽量使用
- 执行前先 review 生成的计划
- 根据项目上下文调整任务

**3. 持续测试**
- 将测试融入工作流
- 关键功能使用 TDD
- 每次迭代后运行测试

**4. Review 代码**
- 使用内置 review 工作流
- 利用 multi-CLI 获得多视角反馈
- 迭代式合并 review 建议

**5. 记录关键决策**
- 复杂决策用 brainstorm 工作流
- 保留 session artifacts 便于复盘
- 归档已完成 sessions

**6. 维护 session 卫生**
- 结束后及时 complete session
- 定期清理旧 sessions
- 归档重要 sessions

</Details>

### 如何最大化 AI 辅助收益？

<Details>
<summary>AI 最佳实践</summary>

**1. 提示要具体**
```
Bad: "Fix the bug"
Good: "Fix the 500 error when users update their profile picture"
```

**2. 提供上下文**
```bash
ccw plan "Add OAuth2" \
  --context "Using Express.js, MongoDB, Passport.js" \
  --reference "Similar to existing Google OAuth implementation"
```

**3. 使用 multi-CLI 协作**
```bash
# 获取多个视角
ccw multi-cli-plan "Architecture decision"
```

**4. 利用 memory**
```bash
# 基于已有工作继续推进
ccw plan "Continue auth refactor" --memory WFS-auth-v1
```

**5. 选择合适模型**
- **Gemini Flash**：快，适合初步分析
- **Gemini Pro**：深度推理，适合复杂任务
- **Codex**：代码 review 与实现（git-aware）
- **Claude**：文档与复杂推理

</Details>

## 相关文档

- [工作流介绍](/workflows/introduction) - 完整工作流指南
- [工作流 FAQ](/workflows/faq) - 工作流相关问题
- [命令参考](/commands/general/ccw) - 全部命令

---

**仍有疑问？** 欢迎在 GitHub 提交 [Issue](https://github.com/ccw/ccw/issues) 或查看 [讨论区](https://github.com/ccw/ccw/discussions)。