catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-01 15:03:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add VitePress documentation site

Browse Source 
- Add docs directory with VitePress configuration
- Add GitHub Actions workflow for docs build and deploy
- Support bilingual (English/Chinese) documentation
- Include search, custom theme, and responsive design
This commit is contained in:
catlog22
2026-02-28 16:14:09 +08:00
parent ab65caec45
commit c3ddf7e322
136 changed files with 34486 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

524
docs/zh/agents/builtin.md Normal file
View File

@@ -0,0 +1,524 @@
# 内置智能体
CCW 包含 **21 个专业化智能体**，分为 5 个类别，每个智能体都针对特定的开发任务而设计。智能体可以独立工作，也可以编排组合以处理复杂的工作流。
## 类别概览
| 类别 | 数量 | 主要用途 |
|------|------|----------|
| [CLI 智能体](#cli-智能体) | 6 | 基于 CLI 的交互、探索和规划 |
| [开发智能体](#开发智能体) | 5 | 代码实现和调试 |
| [规划智能体](#规划智能体) | 4 | 战略规划和问题管理 |
| [测试智能体](#测试智能体) | 3 | 测试生成、执行和质量保证 |
| [文档智能体](#文档智能体) | 3 | 文档和设计系统 |
---
## CLI 智能体
### cli-explore-agent
**用途**: 专业化 CLI 探索，支持 3 种分析模式
**能力**:
- 快速扫描（仅 Bash）
- 深度扫描（Bash + Gemini）
- 依赖映射（图构建）
- 4 阶段工作流：任务理解 → 分析执行 → 模式验证 → 输出生成
**工具**: `Bash`, `Read`, `Grep`, `Glob`, `ccw cli (gemini/qwen/codex)`, `ACE search_context`
```javascript
Task({
subagent_type: "cli-explore-agent",
prompt: "Analyze authentication module dependencies"
})
```
### cli-discuss-agent
**用途**: 多 CLI 协作讨论，支持交叉验证
**能力**:
- 5 阶段工作流：上下文准备 → CLI 执行 → 交叉验证 → 综合 → 输出
- 加载讨论历史
- 跨会话维护上下文
**工具**: `Read`, `Grep`, `Glob`, `ccw cli`
**调用**: `cli-explore-agent` 用于讨论前的代码库发现
```javascript
Task({
subagent_type: "cli-discuss-agent",
prompt: "Discuss architecture patterns for microservices"
})
```
### cli-execution-agent
**用途**: 智能 CLI 执行，支持自动上下文发现
**能力**:
- 5 阶段工作流：任务理解 → 上下文发现 → 提示增强 → 工具执行 → 输出路由
- 后台执行支持
- 结果轮询
**工具**: `Bash`, `Read`, `Grep`, `Glob`, `ccw cli`, `TaskOutput`
**调用**: `cli-explore-agent` 用于执行前的发现
```javascript
Task({
subagent_type: "cli-execution-agent",
prompt: "Execute security scan on authentication module"
})
```
### cli-lite-planning-agent
**用途**: 轻量级规划，用于快速任务分解
**能力**:
- 创建简化的任务 JSON，无需复杂的模式验证
- 适用于简单的实现任务
**工具**: `Read`, `Write`, `Bash`, `Grep`
```javascript
Task({
subagent_type: "cli-lite-planning-agent",
prompt: "Plan user registration feature"
})
```
### cli-planning-agent
**用途**: 全功能规划，用于复杂实现
**能力**:
- 6 字段模式，支持上下文加载
- 流程控制和工件集成
- 全面的任务 JSON 生成
**工具**: `Read`, `Write`, `Bash`, `Grep`, `Glob`, `mcp__ace-tool__search_context`
```javascript
Task({
subagent_type: "cli-planning-agent",
prompt: "Plan microservices architecture migration"
})
```
### cli-roadmap-plan-agent
**用途**: 战略规划，用于路线图和里程碑生成
**能力**:
- 创建长期项目计划
- 生成史诗、里程碑和交付时间线
- 通过 ccw 创建问题
**工具**: `Read`, `Write`, `Bash`, `Grep`
```javascript
Task({
subagent_type: "cli-roadmap-plan-agent",
prompt: "Create Q1 roadmap for payment system"
})
```
---
## 开发智能体
### code-developer
**用途**: 核心代码执行，适用于任何实现任务
**能力**:
- 适应任何领域，同时保持质量标准
- 支持分析、实现、文档、研究
- 复杂的多步骤工作流
**工具**: `Read`, `Edit`, `Write`, `Bash`, `Grep`, `Glob`, `Task`, `mcp__ccw-tools__edit_file`, `mcp__ccw-tools__write_file`
```javascript
Task({
subagent_type: "code-developer",
prompt: "Implement user authentication with JWT"
})
```
### tdd-developer
**用途**: TDD 感知的代码执行，支持 Red-Green-Refactor 工作流
**能力**:
- 扩展 code-developer，增加 TDD 周期感知
- 自动测试-修复迭代
- CLI 会话恢复
**工具**: `Read`, `Edit`, `Write`, `Bash`, `Grep`, `Glob`, `ccw cli`
**扩展**: `code-developer`
```javascript
Task({
subagent_type: "tdd-developer",
prompt: "Implement payment processing with TDD"
})
```
### context-search-agent
**用途**: 专业化上下文收集器，用于头脑风暴工作流
**能力**:
- 分析现有代码库
- 识别模式
- 生成标准化上下文包
**工具**: `mcp__ace-tool__search_context`, `mcp__ccw-tools__smart_search`, `Read`, `Grep`, `Glob`, `Bash`
```javascript
Task({
subagent_type: "context-search-agent",
prompt: "Gather context for API refactoring"
})
```
### debug-explore-agent
**用途**: 调试专家，用于代码分析和问题诊断
**能力**:
- 基于假设的调试，支持 NDJSON 日志记录
- CLI 辅助分析
- 迭代验证
- 跟踪执行流程，识别故障点，分析故障时的状态
**工具**: `Read`, `Grep`, `Bash`, `ccw cli`
**工作流**: 问题分析 → 假设生成 → 插桩 → 日志分析 → 修复验证
```javascript
Task({
subagent_type: "debug-explore-agent",
prompt: "Debug memory leak in connection handler"
})
```
### universal-executor
**用途**: 通用执行器，高效实现任何任务
**能力**:
- 适应任何领域，同时保持质量标准
- 处理分析、实现、文档、研究
- 复杂的多步骤工作流
**工具**: `Read`, `Edit`, `Write`, `Bash`, `Grep`, `Glob`, `Task`, `mcp__ace-tool__search_context`, `mcp__exa__web_search_exa`
```javascript
Task({
subagent_type: "universal-executor",
prompt: "Implement GraphQL API with authentication"
})
```
---
## 规划智能体
### action-planning-agent
**用途**: 纯执行智能体，用于创建实现计划
**能力**:
- 将需求和头脑风暴工件转换为结构化计划
- 量化的可交付成果和可衡量的验收标准
- 执行模式的控制标志
**工具**: `Read`, `Write`, `Bash`, `Grep`, `Glob`, `mcp__ace-tool__search_context`, `mcp__ccw-tools__smart_search`
```javascript
Task({
subagent_type: "action-planning-agent",
prompt: "Create implementation plan for user dashboard"
})
```
### conceptual-planning-agent
**用途**: 高层规划，用于架构和概念设计
**能力**:
- 创建系统设计
- 架构模式
- 技术策略
**工具**: `Read`, `Write`, `Bash`, `Grep`, `ccw cli`
```javascript
Task({
subagent_type: "conceptual-planning-agent",
prompt: "Design event-driven architecture for order system"
})
```
### issue-plan-agent
**用途**: 问题解决规划，支持闭环探索
**能力**:
- 分析问题并生成解决方案计划
- 创建包含依赖和验收标准的任务 JSON
- 从探索到解决方案的 5 阶段任务
**工具**: `Read`, `Write`, `Bash`, `Grep`, `mcp__ace-tool__search_context`
```javascript
Task({
subagent_type: "issue-plan-agent",
prompt: "Plan resolution for issue #123"
})
```
### issue-queue-agent
**用途**: 解决方案排序智能体，用于队列形成
**能力**:
- 接收来自绑定问题的解决方案
- 使用 Gemini 进行智能冲突检测
- 生成有序的执行队列
**工具**: `Read`, `Write`, `Bash`, `ccw cli (gemini)`, `mcp__ace-tool__search_context`, `mcp__ccw-tools__smart_search`
**调用**: `issue-plan-agent`
```javascript
Task({
subagent_type: "issue-queue-agent",
prompt: "Form execution queue for issues #101, #102, #103"
})
```
---
## 测试智能体
### test-action-planning-agent
**用途**: 专业化智能体，用于测试规划文档
**能力**:
- 扩展 action-planning-agent 用于测试规划
- 渐进式 L0-L3 测试层（静态、单元、集成、端到端）
- AI 代码问题检测（L0.5），支持 CRITICAL/ERROR/WARNING 严重级别
- 项目特定模板
- 测试反模式检测和质量门禁
**工具**: `Read`, `Write`, `Bash`, `Grep`, `Glob`
**扩展**: `action-planning-agent`
```javascript
Task({
subagent_type: "test-action-planning-agent",
prompt: "Create test plan for payment module"
})
```
### test-context-search-agent
**用途**: 专业化上下文收集器，用于测试生成工作流
**能力**:
- 分析测试覆盖率
- 识别缺失的测试
- 从源会话加载实现上下文
- 生成标准化测试上下文包
**工具**: `mcp__ccw-tools__codex_lens`, `Read`, `Glob`, `Bash`, `Grep`
```javascript
Task({
subagent_type: "test-context-search-agent",
prompt: "Gather test context for authentication module"
})
```
### test-fix-agent
**用途**: 执行测试，诊断失败，并修复代码直到所有测试通过
**能力**:
- 多层测试执行（L0-L3）
- 分析失败并修改源代码
- 通过测试的质量门禁
**工具**: `Bash`, `Read`, `Edit`, `Write`, `Grep`, `ccw cli`
```javascript
Task({
subagent_type: "test-fix-agent",
prompt: "Run tests for user service and fix failures"
})
```
---
## 文档智能体
### doc-generator
**用途**: 文档生成，用于技术文档、API 参考和代码注释
**能力**:
- 从多个来源综合上下文
- 生成全面的文档
- 基于 flow_control 的任务执行
**工具**: `Read`, `Write`, `Bash`, `Grep`, `Glob`
```javascript
Task({
subagent_type: "doc-generator",
prompt: "Generate API documentation for REST endpoints"
})
```
### memory-bridge
**用途**: 文档更新协调器，用于复杂项目
**能力**:
- 编排并行的 CLAUDE.md 更新
- 使用 ccw tool exec update_module_claude
- 处理每个模块路径
**工具**: `Bash`, `ccw tool exec`, `TodoWrite`
```javascript
Task({
subagent_type: "memory-bridge",
prompt: "Update CLAUDE.md for all modules"
})
```
### ui-design-agent
**用途**: UI 设计令牌管理和原型生成
**能力**:
- 符合 W3C 设计令牌格式
- 基于状态的组件定义（默认、悬停、焦点、激活、禁用）
- 完整的组件库覆盖（12+ 交互组件）
- 动画-组件状态集成
- WCAG AA 合规性验证
- 令牌驱动的原型生成
**工具**: `Read`, `Write`, `Edit`, `Bash`, `mcp__exa__web_search_exa`, `mcp__exa__get_code_context_exa`
```javascript
Task({
subagent_type: "ui-design-agent",
prompt: "Generate design tokens for dashboard components"
})
```
---
## 编排模式
智能体可以通过以下编排模式组合使用：
### 继承链
智能体扩展另一个智能体的能力：
| 父智能体 | 子智能体 | 扩展内容 |
|----------|----------|----------|
| code-developer | tdd-developer | 添加 TDD Red-Green-Refactor 工作流、测试-修复周期 |
| action-planning-agent | test-action-planning-agent | 添加 L0-L3 测试层、AI 问题检测 |
### 顺序委托
智能体调用另一个智能体进行预处理：
| 调用者 | 被调用者 | 目的 |
|--------|----------|------|
| cli-discuss-agent | cli-explore-agent | 讨论前的代码库发现 |
| cli-execution-agent | cli-explore-agent | CLI 命令执行前的发现 |
### 队列形成
智能体收集多个智能体的输出并排序：
| 收集者 | 来源 | 目的 |
|--------|------|------|
| issue-queue-agent | issue-plan-agent | 收集解决方案、检测冲突、生成有序队列 |
### 上下文加载链
智能体生成执行智能体使用的上下文包：
| 上下文提供者 | 消费者 | 目的 |
|--------------|--------|------|
| context-search-agent | code-developer | 提供头脑风暴上下文包 |
| test-context-search-agent | test-fix-agent | 提供测试上下文包 |
### 质量门禁链
通过验证门禁的顺序执行：
```
code-developer (IMPL-001)
→ test-fix-agent (IMPL-001.3 validation)
→ test-fix-agent (IMPL-001.5 review)
→ test-fix-agent (IMPL-002 fix)
```
---
## 智能体选择指南
| 任务 | 推荐智能体 | 备选 |
|------|------------|------|
| 探索代码库 | cli-explore-agent | context-search-agent |
| 实现代码 | code-developer | tdd-developer |
| 调试问题 | debug-explore-agent | cli-execution-agent |
| 规划实现 | cli-planning-agent | action-planning-agent |
| 生成测试 | test-action-planning-agent | test-fix-agent |
| 审查代码 | test-fix-agent | doc-generator |
| 创建文档 | doc-generator | ui-design-agent |
| UI 设计 | ui-design-agent | - |
| 管理问题 | issue-plan-agent | issue-queue-agent |
---
## 工具依赖
### 核心工具
所有智能体都可以访问：`Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`
### MCP 工具
专业化智能体使用：`mcp__ace-tool__search_context`, `mcp__ccw-tools__smart_search`, `mcp__ccw-tools__edit_file`, `mcp__ccw-tools__write_file`, `mcp__ccw-tools__codex_lens`, `mcp__exa__web_search_exa`
### CLI 工具
支持 CLI 的智能体使用：`ccw cli`, `ccw tool exec`
### 工作流工具
协调智能体使用：`Task`, `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskOutput`, `TodoWrite`, `SendMessage`
::: info 另请参阅
- [智能体概述](./index.md) - 智能体系统介绍
- [自定义智能体](./custom.md) - 创建自定义智能体
- [团队技能](../skills/core-skills.md#team-skills) - 多智能体团队技能
:::

263
docs/zh/agents/custom.md Normal file
View File

@@ -0,0 +1,263 @@
# 自定义代理
创建和配置自定义 CCW 代理指南。
## 代理结构
```
~/.claude/agents/my-agent/
├── AGENT.md # 代理定义
├── index.ts # 代理逻辑
├── tools/ # 代理专用工具
└── examples/ # 使用示例
```
## 创建代理
### 1. 定义代理
创建 `AGENT.md`:
```markdown
---
name: my-agent
type: development
version: 1.0.0
capabilities: [react, typescript, testing]
---
# 我的自定义代理
专门用于 React 组件开发的 TypeScript 代理。
## 功能
- 使用 hooks 生成 React 组件
- TypeScript 类型定义
- Vitest 测试设置
- Tailwind CSS 样式
## 使用
\`\`\`javascript
Task({
subagent_type: "my-agent",
prompt: "创建用户配置文件组件"
})
\`\`\`
```
### 2. 实现代理逻辑
创建 `index.ts`:
```typescript
import type { AgentContext, AgentResult } from '@ccw/types'
export async function execute(
prompt: string,
context: AgentContext
): Promise<AgentResult> {
// 分析请求
const intent = analyzeIntent(prompt)
// 根据意图执行
switch (intent.type) {
case 'generate-component':
return await generateComponent(intent.options)
case 'add-tests':
return await addTests(intent.options)
default:
return await handleGeneral(prompt)
}
}
function analyzeIntent(prompt: string) {
// 从提示词解析用户意图
// 返回结构化意图对象
}
```
## 代理功能
### 代码生成
```typescript
async function generateComponent(options: ComponentOptions) {
return {
files: [
{
path: 'src/components/UserProfile.tsx',
content: generateReactComponent(options)
},
{
path: 'src/components/UserProfile.test.tsx',
content: generateTests(options)
}
]
}
}
```
### 分析
```typescript
async function analyzeCodebase(context: AgentContext) {
const files = await context.filesystem.read('src/**/*.ts')
const patterns = identifyPatterns(files)
return {
patterns,
recommendations: generateRecommendations(patterns)
}
}
```
### 测试
```typescript
async function generateTests(options: TestOptions) {
return {
framework: 'vitest',
files: [
{
path: `${options.file}.test.ts`,
content: generateTestCode(options)
}
]
}
}
```
## 代理工具
代理可以定义自定义工具:
```typescript
export const tools = {
'my-tool': {
description: '我的自定义工具',
parameters: {
type: 'object',
properties: {
input: { type: 'string' }
}
},
execute: async (params) => {
// 工具实现
}
}
}
```
## 代理通信
代理通过消息总线通信:
```typescript
// 向另一个代理发送消息
await context.messaging.send({
to: 'tester',
type: 'task-complete',
data: { files: generatedFiles }
})
// 接收消息
context.messaging.on('task-complete', async (message) => {
if (message.from === 'executor') {
await startTesting(message.data.files)
}
})
```
## 代理配置
在 `~/.claude/agents/config.json` 中配置代理:
```json
{
"my-agent": {
"enabled": true,
"priority": 10,
"capabilities": {
"frameworks": ["react", "vue"],
"languages": ["typescript", "javascript"],
"tools": ["vitest", "playwright"]
},
"limits": {
"maxFiles": 100,
"maxSize": "10MB"
}
}
}
```
## 代理最佳实践
### 1. 明确目的
定义特定的、集中的功能:
```markdown
# 好: 专注
name: react-component-agent
purpose: 使用 TypeScript 生成 React 组件
# 坏: 太宽泛
name: fullstack-agent
purpose: 处理一切
```
### 2. 工具选择
为任务使用适当的工具:
```typescript
// 文件操作
context.filesystem.read(path)
context.filesystem.write(path, content)
// 代码分析
context.codebase.search(query)
context.codebase.analyze(pattern)
// 通信
context.messaging.send(to, type, data)
```
### 3. 错误处理
```typescript
try {
const result = await executeTask(prompt)
return { success: true, result }
} catch (error) {
return {
success: false,
error: error.message,
recovery: suggestRecovery(error)
}
}
```
## 测试代理
```typescript
import { describe, it, expect } from 'vitest'
import { execute } from '../index'
describe('my-agent', () => {
it('应该生成组件', async () => {
const result = await execute(
'创建 UserCard 组件',
mockContext
)
expect(result.success).toBe(true)
expect(result.files).toHaveLength(2) // 组件 + 测试
})
})
```
::: info 另请参阅
- [内置代理](./builtin.md) - 预配置代理
- [代理概述](./index.md) - 代理系统介绍
:::

162
docs/zh/agents/index.md Normal file
View File

@@ -0,0 +1,162 @@
# 代理
CCW 为不同的开发工作流提供专用代理。
## 什么是代理?
代理是具有特定专业知识和工具的专用 AI 助手，用于软件开发的各个方面。
## 内置代理
### 前端代理
专注于 Web 前端开发。
**专长:**
- React、Vue、Angular
- CSS/Tailwind/样式
- 状态管理
- 组件架构
- 使用 Jest/Vitest/Playwright 测试
```javascript
Task({
subagent_type: "fe-developer",
prompt: "创建响应式仪表板"
})
```
### 后端代理
处理服务器端开发。
**专长:**
- Node.js、Python、Go
- API 设计 (REST/GraphQL)
- 数据库设计
- 身份验证/授权
- 性能优化
```javascript
Task({
subagent_type: "be-developer",
prompt: "实现用户身份验证 API"
})
```
### 测试代理
专注于测试和质量保证。
**专长:**
- 单元测试
- 集成测试
- E2E 测试
- 测试驱动开发
- 覆盖率分析
```javascript
Task({
subagent_type: "qa-agent",
prompt: "为用户服务编写测试"
})
```
### 文档代理
创建和维护文档。
**专长:**
- API 文档
- 用户指南
- 技术写作
- 图表和可视化
- 文档即代码工作流
```javascript
Task({
subagent_type: "doc-writer",
prompt: "记录 REST API"
})
```
## 代理通信
代理可以相互通信和协调:
```javascript
// 代理发送消息
SendMessage({
type: "message",
recipient: "tester",
content: "功能实现完成，准备测试"
})
// 代理通过系统接收消息
```
## 团队工作流
多个代理可以协同处理复杂任务:
```
[analyst] -> RESEARCH (需求分析)
|
v
[writer] -> DRAFT (规范创建)
|
v
[planner] -> PLAN (实现规划)
|
+--[executor] -> IMPL (代码实现)
| |
| v
+-----------[tester] -> TEST (测试)
|
v
[reviewer] -> REVIEW (代码审查)
```
## 使用代理
### CLI 集成
```bash
# 使用前端代理
ccw agent run fe-developer "创建响应式导航栏"
# 使用后端代理
ccw agent run be-developer "实现 JWT 身份验证"
```
### 编程方式使用
```javascript
// 在后台派生代理
Task({
subagent_type: "fe-developer",
run_in_background: true,
prompt: "实现用户仪表板"
})
```
### 配置
在 `~/.claude/agents/config.json` 中配置代理行为:
```json
{
"agents": {
"fe-developer": {
"framework": "vue",
"testing": "vitest",
"styling": "tailwind"
}
}
}
```
::: info 另请参阅
- [技能](../skills/) - 可重用技能库
- [工作流](../workflows/) - 编排系统
:::

889
docs/zh/cli/commands.md Normal file
View File

@@ -0,0 +1,889 @@
# CLI 命令参考
全部 **43 个 CCW 命令**的完整参考，按类别组织，包含 **7 条工作流链**用于常见开发场景。
## 命令类别
| 类别 | 命令数 | 描述 |
|----------|----------|-------------|
| [编排器](#编排器) | 3 | 主工作流编排 |
| [工作流命令](#工作流命令) | 10 | 项目初始化和管理 |
| [会话命令](#会话命令) | 6 | 会话生命周期管理 |
| [分析命令](#分析命令) | 4 | 代码分析和调试 |
| [规划命令](#规划命令) | 3 | 头脑风暴和规划 |
| [执行命令](#执行命令) | 1 | 通用执行引擎 |
| [UI 设计命令](#ui-设计命令) | 10 | 设计令牌提取和原型设计 |
| [问题命令](#问题命令) | 8 | 问题发现和解决 |
| [记忆命令](#记忆命令) | 2 | 记忆和上下文管理 |
| [CLI 命令](#cli-命令) | 2 | CLI 配置和审查 |
---
## 编排器
### ccw
**用途**：主工作流编排器 - 分析意图、选择工作流、执行命令链
**描述**：分析用户意图，选择适当的工作流，并在主进程中执行命令链。
**标志**：
- `-y, --yes` - 跳过所有确认
**映射技能**：
- workflow-lite-plan, workflow-plan, workflow-execute, workflow-tdd
- workflow-test-fix, workflow-multi-cli-plan, review-cycle, brainstorm
- team-planex, team-iterdev, team-lifecycle, team-issue
- team-testing, team-quality-assurance, team-brainstorm, team-uidesign
```bash
ccw -y
```
### ccw-coordinator
**用途**：具有外部 CLI 执行功能的命令编排工具
**描述**：分析需求、推荐链、按顺序执行并持久化状态。使用带钩子回调的后台任务。
**工具**：`Task`, `AskUserQuestion`, `Read`, `Write`, `Bash`, `Glob`, `Grep`
```bash
ccw-coordinator
```
### flow-create
**用途**：为 meta-skill/flow-coordinator 生成工作流模板
```bash
flow-create
```
---
## 工作流命令
### workflow init
**用途**：通过智能项目分析初始化项目级状态
**描述**：使用 cli-explore-agent 进行智能项目分析，生成 project-tech.json 和规范文件。
**标志**：
- `--regenerate` - 强制重新生成
- `--skip-specs` - 跳过规范生成
**输出**：
- `.workflow/project-tech.json`
- `.workflow/specs/*.md`
**委托给**：`cli-explore-agent`
```bash
workflow init --regenerate
```
### workflow init-specs
**用途**：创建单个规范或个人约束的交互式向导
**标志**：
- `--scope <global|project>` - 范围选择
- `--dimension <specs|personal>` - 维度选择
- `--category <general|exploration|planning|execution>` - 类别选择
```bash
workflow init-specs --scope project --dimension specs
```
### workflow init-guidelines
**用途**：基于项目分析填充 specs/*.md 的交互式向导
**标志**：
- `--reset` - 重置现有指南
```bash
workflow init-guidelines --reset
```
### workflow clean
**用途**：具有主线检测的智能代码清理
**描述**：发现过期工件并执行安全清理操作。
**标志**：
- `-y, --yes` - 跳过确认
- `--dry-run` - 预览而不更改
**委托给**：`cli-explore-agent`
```bash
workflow clean --dry-run
```
### workflow unified-execute-with-file
**用途**：用于任何规划/头脑风暴/分析输出的通用执行引擎
**标志**：
- `-y, --yes` - 跳过确认
- `-p, --plan <path>` - 规划文件路径
- `--auto-commit` - 执行后自动提交
**执行方法**：Agent, CLI-Codex, CLI-Gemini, Auto
**输出**：`.workflow/.execution/{session-id}/execution-events.md`
```bash
workflow unified-execute-with-file -p plan.json --auto-commit
```
### workflow brainstorm-with-file
**用途**：具有多 CLI 协作的交互式头脑风暴
**描述**：通过想法扩展记录思维演变。
**标志**：
- `-y, --yes` - 跳过确认
- `-c, --continue` - 继续上一次会话
- `-m, --mode <creative|structured>` - 头脑风暴模式
**委托给**：`cli-explore-agent`, `Multi-CLI (Gemini/Codex/Claude)`
**输出**：`.workflow/.brainstorm/{session-id}/synthesis.json`
```bash
workflow brainstorm-with-file -m creative
```
### workflow analyze-with-file
**用途**：具有文档化讨论的交互式协作分析
**标志**：
- `-y, --yes` - 跳过确认
- `-c, --continue` - 继续上一次会话
**委托给**：`cli-explore-agent`, `Gemini/Codex`
**输出**：`.workflow/.analysis/{session-id}/discussion.md`
```bash
workflow analyze-with-file
```
### workflow debug-with-file
**用途**：交互式假设驱动调试
**描述**：通过 Gemini 辅助校正记录探索过程。
**标志**：
- `-y, --yes` - 跳过确认
**输出**：`.workflow/.debug/{session-id}/understanding.md`
```bash
workflow debug-with-file
```
### workflow collaborative-plan-with-file
**用途**：使用规划笔记的协作规划
**描述**：并行代理填充预分配部分并进行冲突检测。
**标志**：
- `-y, --yes` - 跳过确认
- `--max-agents=5` - 最大并行代理数
**输出**：`.workflow/.planning/{session-id}/plan-note.md`
```bash
workflow collaborative-plan-with-file --max-agents=5
```
### workflow roadmap-with-file
**用途**：具有迭代分解的战略需求路线图
**标志**：
- `-y, --yes` - 跳过确认
- `-c, --continue` - 继续上一次会话
- `-m, --mode <progressive|direct|auto>` - 分解模式
**输出**：
- `.workflow/.roadmap/{session-id}/roadmap.md`
- `.workflow/issues/issues.jsonl`
**移交至**：`team-planex`
```bash
workflow roadmap-with-file -m progressive
```
---
## 会话命令
### workflow session start
**用途**：发现现有会话或启动新的工作流会话
**标志**：
- `--type <workflow|review|tdd|test|docs>` - 会话类型
- `--auto|--new` - 自动发现或强制新建
**首先调用**：`workflow init`
```bash
workflow session start --type tdd
```
### workflow session resume
**用途**：恢复最近暂停的工作流会话
```bash
workflow session resume
```
### workflow session list
**用途**：列出所有工作流会话并按状态过滤
```bash
workflow session list
```
### workflow session sync
**用途**：快速同步会话工作到 specs/*.md 和 project-tech
**标志**：
- `-y, --yes` - 跳过确认
**更新**：`.workflow/specs/*.md`, `.workflow/project-tech.json`
```bash
workflow session sync -y
```
### workflow session solidify
**用途**：将会话学习成果固化为永久项目指南
**标志**：
- `-y, --yes` - 跳过确认
- `--type <convention|constraint|learning|compress>` - 固化类型
- `--category <category>` - 指南类别
- `--limit <N>` - 压缩模式的限制
```bash
workflow session solidify --type learning
```
### workflow session complete
**用途**：将活动的工作流会话标记为完成
**描述**：归档经验教训，自动调用 sync。
**标志**：
- `-y, --yes` - 跳过确认
- `--detailed` - 详细完成报告
**自动调用**：`workflow session sync -y`
```bash
workflow session complete --detailed
```
---
## 分析命令
### workflow integration-test-cycle
**用途**：自迭代集成测试工作流
**描述**：具有反思驱动调整的自主测试-修复循环。
**标志**：
- `-y, --yes` - 跳过确认
- `-c, --continue` - 继续上一次会话
- `--max-iterations=N` - 最大迭代次数
**输出**：`.workflow/.integration-test/{session-id}/reflection-log.md`
```bash
workflow integration-test-cycle --max-iterations=5
```
### workflow refactor-cycle
**用途**：技术债务发现和自迭代重构
**标志**：
- `-y, --yes` - 跳过确认
- `-c, --continue` - 继续上一次会话
- `--scope=module|project` - 重构范围
**输出**：`.workflow/.refactor/{session-id}/reflection-log.md`
```bash
workflow refactor-cycle --scope project
```
---
## 规划命令
### workflow req-plan-with-file
**用途**：具有问题创建的需求级渐进式路线图规划
**描述**：将需求分解为收敛层或任务序列。
```bash
workflow req-plan-with-file
```
---
## 执行命令
### workflow execute
**用途**：协调工作流任务的代理执行
**描述**：自动会话发现、并行任务处理和状态跟踪。
**触发器**：`workflow:execute`
```bash
workflow execute
```
---
## UI 设计命令
### workflow ui-design style-extract
**用途**：从参考图像或文本提示中提取设计风格
**标志**：
- `-y, --yes` - 跳过确认
- `--design-id <id>` - 设计标识符
- `--session <id>` - 会话标识符
- `--images <glob>` - 图像文件模式
- `--prompt <desc>` - 文本描述
- `--variants <count>` - 变体数量
- `--interactive` - 交互模式
- `--refine` - 精化模式
**模式**：探索、精化
**输出**：`style-extraction/style-{id}/design-tokens.json`
```bash
workflow ui-design style-extract --images "design/*.png" --variants 3
```
### workflow ui-design layout-extract
**用途**：从参考图像或文本提示中提取结构布局
**标志**：
- `-y, --yes` - 跳过确认
- `--design-id <id>` - 设计标识符
- `--session <id>` - 会话标识符
- `--images <glob>` - 图像文件模式
- `--prompt <desc>` - 文本描述
- `--targets <list>` - 目标组件
- `--variants <count>` - 变体数量
- `--device-type <desktop|mobile|tablet|responsive>` - 设备类型
- `--interactive` - 交互模式
- `--refine` - 精化模式
**委托给**：`ui-design-agent`
**输出**：`layout-extraction/layout-*.json`
```bash
workflow ui-design layout-extract --prompt "dashboard layout" --device-type responsive
```
### workflow ui-design generate
**用途**：通过组合布局模板和设计令牌来组装 UI 原型
**标志**：
- `--design-id <id>` - 设计标识符
- `--session <id>` - 会话标识符
**委托给**：`ui-design-agent`
**前置条件**：`workflow ui-design style-extract`, `workflow ui-design layout-extract`
```bash
workflow ui-design generate --design-id dashboard-001
```
### workflow ui-design animation-extract
**用途**：提取动画和过渡模式
**标志**：
- `-y, --yes` - 跳过确认
- `--design-id <id>` - 设计标识符
- `--session <id>` - 会话标识符
- `--images <glob>` - 图像文件模式
- `--focus <types>` - 动画类型
- `--interactive` - 交互模式
- `--refine` - 精化模式
**委托给**：`ui-design-agent`
**输出**：`animation-extraction/animation-tokens.json`
```bash
workflow ui-design animation-extract --focus "transition,keyframe"
```
### workflow ui-design import-from-code
**用途**：从代码文件导入设计系统
**描述**：自动发现 CSS/JS/HTML/SCSS 文件。
**标志**：
- `--design-id <id>` - 设计标识符
- `--session <id>` - 会话标识符
- `--source <path>` - 源路径
**委托给**：Style Agent, Animation Agent, Layout Agent
**输出**：`style-extraction`, `animation-extraction`, `layout-extraction`
```bash
workflow ui-design import-from-code --source src/styles
```
### workflow ui-design codify-style
**用途**：从代码中提取样式并生成可共享的参考包
**标志**：
- `--package-name <name>` - 包名称
- `--output-dir <path>` - 输出目录
- `--overwrite` - 覆盖现有文件
**编排**：`workflow ui-design import-from-code`, `workflow ui-design reference-page-generator`
**输出**：`.workflow/reference_style/{package-name}/`
```bash
workflow ui-design codify-style --package-name my-design-system
```
### workflow ui-design reference-page-generator
**用途**：从设计运行提取生成多组件参考页面
**标志**：
- `--design-run <path>` - 设计运行路径
- `--package-name <name>` - 包名称
- `--output-dir <path>` - 输出目录
**输出**：`.workflow/reference_style/{package-name}/preview.html`
```bash
workflow ui-design reference-page-generator --design-run .workflow/design-run-001
```
### workflow ui-design design-sync
**用途**：将最终确定的设计系统参考同步到头脑风暴工件
**标志**：
- `--session <session_id>` - 会话标识符
- `--selected-prototypes <list>` - 选定的原型
**更新**：角色分析文档, context-package.json
```bash
workflow ui-design design-sync --session design-001
```
### workflow ui-design explore-auto
**用途**：具有以风格为中心的批量生成的交互式探索性 UI 设计
**标志**：
- `--input <value>` - 输入源
- `--targets <list>` - 目标组件
- `--target-type <page|component>` - 目标类型
- `--session <id>` - 会话标识符
- `--style-variants <count>` - 风格变体数
- `--layout-variants <count>` - 布局变体数
**编排**：`import-from-code`, `style-extract`, `animation-extract`, `layout-extract`, `generate`
```bash
workflow ui-design explore-auto --input "dashboard" --style-variants 3
```
### workflow ui-design imitate-auto
**用途**：具有直接代码/图像输入的 UI 设计工作流
**标志**：
- `--input <value>` - 输入源
- `--session <id>` - 会话标识符
**编排**：与 explore-auto 相同
```bash
workflow ui-design imitate-auto --input ./reference.png
```
---
## 问题命令
### issue new
**用途**：从 GitHub URL 或文本描述创建结构化问题
**标志**：
- `-y, --yes` - 跳过确认
- `--priority 1-5` - 问题优先级
**功能**：清晰度检测
**输出**：`.workflow/issues/issues.jsonl`
```bash
issue new --priority 3
```
### issue discover
**用途**：从多个视角发现潜在问题
**标志**：
- `-y, --yes` - 跳过确认
- `--perspectives=bug,ux,...` - 分析视角
- `--external` - 包含外部研究
**视角**：bug, ux, test, quality, security, performance, maintainability, best-practices
**委托给**：`cli-explore-agent`
**输出**：`.workflow/issues/discoveries/{discovery-id}/`
```bash
issue discover --perspectives=bug,security,performance
```
### issue discover-by-prompt
**用途**：通过用户提示和 Gemini 规划的探索发现问题
**标志**：
- `-y, --yes` - 跳过确认
- `--scope=src/**` - 文件范围
- `--depth=standard|deep` - 分析深度
- `--max-iterations=5` - 最大迭代次数
**委托给**：`Gemini CLI`, `ACE search`, `multi-agent exploration`
```bash
issue discover-by-prompt --depth deep --scope "src/auth/**"
```
### issue plan
**用途**：使用 issue-plan-agent 批量规划问题解决方案
**标志**：
- `-y, --yes` - 跳过确认
- `--all-pending` - 规划所有待处理问题
- `--batch-size 3` - 批量大小
**委托给**：`issue-plan-agent`
**输出**：`.workflow/issues/solutions/{issue-id}.jsonl`
```bash
issue plan --all-pending --batch-size 5
```
### issue queue
**用途**：从绑定的解决方案形成执行队列
**标志**：
- `-y, --yes` - 跳过确认
- `--queues <n>` - 队列数量
- `--issue <id>` - 特定问题
**委托给**：`issue-queue-agent`
**输出**：`.workflow/issues/queues/QUE-xxx.json`
```bash
issue queue --queues 2
```
### issue execute
**用途**：使用基于 DAG 的并行编排执行队列
**标志**：
- `-y, --yes` - 跳过确认
- `--queue <queue-id>` - 队列标识符
- `--worktree [<path>]` - 使用工作树隔离
**执行器**：Codex（推荐）, Gemini, Agent
```bash
issue execute --queue QUE-001 --worktree
```
### issue convert-to-plan
**用途**：将规划工件转换为问题解决方案
**标志**：
- `-y, --yes` - 跳过确认
- `--issue <id>` - 问题标识符
- `--supplement` - 补充现有解决方案
**来源**：lite-plan, workflow-session, markdown, json
```bash
issue convert-to-plan --issue 123 --supplement
```
### issue from-brainstorm
**用途**：将头脑风暴会话想法转换为具有可执行解决方案的问题
**标志**：
- `-y, --yes` - 跳过确认
- `--idea=<index>` - 想法索引
- `--auto` - 自动选择最佳想法
**输入来源**：`synthesis.json`, `perspectives.json`, `.brainstorming/**`
**输出**：`issues.jsonl`, `solutions/{issue-id}.jsonl`
```bash
issue from-brainstorm --auto
```
---
## 记忆命令
### memory prepare
**用途**：委托给 universal-executor 代理进行项目分析
**描述**：返回用于记忆加载的 JSON 核心内容包。
**标志**：
- `--tool gemini|qwen` - AI 工具选择
**委托给**：`universal-executor agent`
```bash
memory prepare --tool gemini
```
### memory style-skill-memory
**用途**：从样式参考生成 SKILL 记忆包
**标志**：
- `--regenerate` - 强制重新生成
**输入**：`.workflow/reference_style/{package-name}/`
**输出**：`.claude/skills/style-{package-name}/SKILL.md`
```bash
memory style-skill-memory --regenerate
```
---
## CLI 命令
### cli init
**用途**：生成 .gemini/ 和 .qwen/ 配置目录
**描述**：基于工作区技术检测创建 settings.json 和忽略文件。
**标志**：
- `--tool gemini|qwen|all` - 工具选择
- `--output path` - 输出路径
- `--preview` - 预览而不写入
**输出**：`.gemini/`, `.qwen/`, `.geminiignore`, `.qwenignore`
```bash
cli init --tool all --preview
```
### cli codex-review
**用途**：使用 Codex CLI 进行交互式代码审查
**标志**：
- `--uncommitted` - 审查未提交的更改
- `--base <branch>` - 与分支比较
- `--commit <sha>` - 审查特定提交
- `--model <model>` - 模型选择
- `--title <title>` - 审查标题
```bash
cli codex-review --base main --title "Security Review"
```
---
## 工作流链
用于常见开发场景的预定义命令组合：
### 1. 项目初始化链
**用途**：初始化项目状态和指南
```bash
workflow init
workflow init-specs --scope project
workflow init-guidelines
```
**输出**：`.workflow/project-tech.json`, `.workflow/specs/*.md`
---
### 2. 会话生命周期链
**用途**：完整的会话管理工作流
```bash
workflow session start --type workflow
# ... 处理任务 ...
workflow session sync -y
workflow session solidify --type learning
workflow session complete --detailed
```
---
### 3. 问题工作流链
**用途**：从问题发现到执行的完整周期
```bash
issue discover --perspectives=bug,security
issue plan --all-pending
issue queue --queues 2
issue execute --queue QUE-001
```
---
### 4. 头脑风暴到问题链
**用途**：将头脑风暴转换为可执行问题
```bash
workflow brainstorm-with-file -m creative
issue from-brainstorm --auto
issue queue
issue execute
```
---
### 5. UI 设计完整周期
**用途**：完整的 UI 设计工作流
```bash
workflow ui-design style-extract --images "design/*.png"
workflow ui-design layout-extract --images "design/*.png"
workflow ui-design generate --design-id main-001
```
---
### 6. 从代码提取 UI 设计链
**用途**：从现有代码提取设计系统
```bash
workflow ui-design import-from-code --source src/styles
workflow ui-design reference-page-generator --design-run .workflow/style-extraction
```
---
### 7. 路线图到团队执行链
**用途**：从战略规划到团队执行
```bash
workflow roadmap-with-file -m progressive
# 移交至 team-planex 技能
```
---
## 命令依赖
某些命令具有前置条件或调用其他命令：
| 命令 | 依赖 |
|---------|------------|
| `workflow session start` | `workflow init` |
| `workflow session complete` | `workflow session sync` |
| `workflow ui-design generate` | `style-extract`, `layout-extract` |
| `workflow ui-design codify-style` | `import-from-code`, `reference-page-generator` |
| `issue from-brainstorm` | `workflow brainstorm-with-file` |
| `issue queue` | `issue plan` |
| `issue execute` | `issue queue` |
| `memory style-skill-memory` | `workflow ui-design codify-style` |
---
## 代理委托
命令将工作委托给专门的代理：
| 代理 | 命令 |
|-------|----------|
| `cli-explore-agent` | `workflow init`, `workflow clean`, `workflow brainstorm-with-file`, `workflow analyze-with-file`, `issue discover` |
| `universal-executor` | `memory prepare` |
| `issue-plan-agent` | `issue plan` |
| `issue-queue-agent` | `issue queue` |
| `ui-design-agent` | `workflow ui-design layout-extract`, `generate`, `animation-extract` |
::: info 另请参阅
- [CLI 工具配置](../guide/cli-tools.md) - 配置 CLI 工具
- [技能库](../skills/core-skills.md) - 内置技能
- [代理](../agents/builtin.md) - 专门代理
:::

152
docs/zh/commands/claude/cli.md Normal file
View File

@@ -0,0 +1,152 @@
# CLI 工具命令
## 一句话定位
**CLI 工具命令是外部模型调用的桥梁** — 整合 Gemini、Qwen、Codex 等多模型能力到工作流中。
## 核心概念速览
| 概念 | 说明 | 配置 |
| --- | --- | --- |
| **CLI 工具** | 外部 AI 模型调用接口 | `cli-tools.json` |
| **端点** | 可用的模型服务 | gemini, qwen, codex, claude |
| **模式** | analysis / write / review | 权限级别 |
## 命令列表
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`cli-init`](#cli-init) | 生成配置目录和设置文件 | `/cli:cli-init [--tool gemini\|qwen\|all] [--output path] [--preview]` |
| [`codex-review`](#codex-review) | 使用 Codex CLI 进行交互式代码审查 | `/cli:codex-review [--uncommitted\|--base <branch>\|--commit <sha>] [prompt]` |
## 命令详解
### cli-init
**功能**: 根据工作空间技术检测生成 `.gemini/` 和 `.qwen/` 配置目录，包含 settings.json 和 ignore 文件。
**语法**:
```
/cli:cli-init [--tool gemini|qwen|all] [--output path] [--preview]
```
**选项**:
- `--tool=工具`: gemini, qwen 或 all
- `--output=路径`: 输出目录
- `--preview`: 预览模式（不实际创建）
**生成的文件结构**:
```
.gemini/
├── settings.json # Gemini 配置
└── ignore # 忽略模式
.qwen/
├── settings.json # Qwen 配置
└── ignore # 忽略模式
```
**技术检测**:
| 检测项 | 生成配置 |
| --- | --- |
| TypeScript | tsconfig 相关配置 |
| React | React 特定配置 |
| Vue | Vue 特定配置 |
| Python | Python 特定配置 |
**示例**:
```bash
# 初始化所有工具
/cli:cli-init --tool all
# 初始化特定工具
/cli:cli-init --tool gemini
# 指定输出目录
/cli:cli-init --output ./configs
# 预览模式
/cli:cli-init --preview
```
### codex-review
**功能**: 使用 Codex CLI 通过 ccw 端点进行交互式代码审查，支持可配置的审查目标、模型和自定义指令。
**语法**:
```
/cli:codex-review [--uncommitted|--base <branch>|--commit <sha>] [--model <model>] [--title <title>] [prompt]
```
**选项**:
- `--uncommitted`: 审查未提交的更改
- `--base <分支>`: 与分支比较
- `--commit <sha>`: 审查特定提交
- `--model <模型>`: 指定模型
- `--title <标题>`: 审查标题
**注意**: 目标标志和 prompt 是互斥的
**示例**:
```bash
# 审查未提交的更改
/cli:codex-review --uncommitted
# 与主分支比较
/cli:codex-review --base main
# 审查特定提交
/cli:codex-review --commit abc123
# 带自定义指令
/cli:codex-review --uncommitted "关注安全性问题"
# 指定模型和标题
/cli:codex-review --model gpt-5.2 --title "认证模块审查"
```
## CLI 工具配置
### cli-tools.json 结构
```json
{
"version": "3.3.0",
"tools": {
"gemini": {
"enabled": true,
"primaryModel": "gemini-2.5-flash",
"secondaryModel": "gemini-2.5-flash",
"tags": ["分析", "Debug"],
"type": "builtin"
},
"qwen": {
"enabled": true,
"primaryModel": "coder-model",
"tags": [],
"type": "builtin"
},
"codex": {
"enabled": true,
"primaryModel": "gpt-5.2",
"tags": [],
"type": "builtin"
}
}
}
```
### 模式说明
| 模式 | 权限 | 用途 |
| --- | --- | --- |
| `analysis` | 只读 | 代码审查、架构分析、模式发现 |
| `write` | 创建/修改/删除 | 功能实现、Bug 修复、文档创建 |
| `review` | Git 感知代码审查 | 审查未提交更改、分支差异、特定提交 |
## 相关文档
- [CLI 调用系统](../../features/cli.md)
- [核心编排](./core-orchestration.md)
- [工作流命令](./workflow.md)

166
docs/zh/commands/claude/core-orchestration.md Normal file
View File

@@ -0,0 +1,166 @@
# 核心编排命令
## 一句话定位
**核心编排命令是 Claude_dms3 的工作流大脑** — 分析任务意图、选择合适的工作流、自动执行命令链。
## 命令列表
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`/ccw`](#ccw) | 主工作流编排器 - 意图分析→工作流选择→命令链执行 | `/ccw "任务描述"` |
| [`/ccw-coordinator`](#ccw-coordinator) | 命令编排工具 - 链式命令执行和状态持久化 | `/ccw-coordinator "任务描述"` |
## 命令详解
### /ccw
**功能**: 主工作流编排器 - 意图分析→工作流选择→命令链执行
**语法**:
```
/ccw "任务描述"
```
**选项**:
- `--yes` / `-y`: 自动模式，跳过确认步骤
**工作流程**:
```mermaid
graph TD
A[用户输入] --> B[分析意图]
B --> C{清晰度评分}
C -->|≥2| D[直接选择工作流]
C -->|<2| E[需求澄清]
E --> D
D --> F[构建命令链]
F --> G{用户确认}
G -->|确认| H[执行命令链]
G -->|取消| I[结束]
H --> J{更多步骤?}
J -->|是| F
J -->|否| K[完成]
```
**任务类型检测**:
| 类型 | 触发关键词 | 工作流 |
| --- | --- | --- |
| **Bug 修复** | urgent, production, critical + fix, bug | lite-fix |
| **头脑风暴** | brainstorm, ideation, 头脑风暴, 创意 | brainstorm-with-file |
| **调试文档** | debug document, hypothesis, 假设验证 | debug-with-file |
| **协作分析** | analyze document, collaborative analysis | analyze-with-file |
| **协作规划** | collaborative plan, 协作规划 | collaborative-plan-with-file |
| **需求路线图** | roadmap, 需求规划 | req-plan-with-file |
| **集成测试** | integration test, 集成测试 | integration-test-cycle |
| **重构** | refactor, 重构 | refactor-cycle |
| **团队工作流** | team + 关键词 | 对应团队工作流 |
| **TDD** | tdd, test-first | tdd-plan → execute |
| **测试修复** | test fix, failing test | test-fix-gen → test-cycle-execute |
**示例**:
```bash
# 基础用法 - 自动选择工作流
/ccw "实现用户认证功能"
# Bug 修复
/ccw "修复登录失败的 bug"
# TDD 开发
/ccw "使用 TDD 实现支付功能"
# 团队协作
/ccw "team-planex 实现用户通知系统"
```
### /ccw-coordinator
**功能**: 命令编排工具 - 分析任务、推荐命令链、顺序执行、状态持久化
**语法**:
```
/ccw-coordinator "任务描述"
```
**最小执行单元**:
| 单元名称 | 命令链 | 输出 |
| --- | --- | --- |
| **快速实现** | lite-plan → lite-execute | 工作代码 |
| **多 CLI 规划** | multi-cli-plan → lite-execute | 工作代码 |
| **Bug 修复** | lite-plan (--bugfix) → lite-execute | 修复的代码 |
| **完整规划+执行** | plan → execute | 工作代码 |
| **验证规划+执行** | plan → plan-verify → execute | 工作代码 |
| **TDD 规划+执行** | tdd-plan → execute | 工作代码 |
| **测试生成+执行** | test-gen → execute | 生成的测试 |
| **审查循环** | review-session-cycle → review-cycle-fix | 修复的代码 |
| **Issue 工作流** | discover → plan → queue → execute | 完成的 Issue |
**工作流程**:
```mermaid
graph TD
A[任务分析] --> B[发现命令]
B --> C[推荐命令链]
C --> D{用户确认}
D -->|确认| E[顺序执行]
D -->|修改| F[调整命令链]
F --> D
E --> G[状态持久化]
G --> H{更多步骤?}
H -->|是| B
H -->|否| I[完成]
```
**示例**:
```bash
# 自动编排 Bug 修复
/ccw-coordinator "生产环境登录失败"
# 自动编排功能实现
/ccw-coordinator "添加用户头像上传功能"
```
## 自动模式
两个命令都支持 `--yes` 标志启用自动模式：
```bash
# 自动模式 - 跳过所有确认
/ccw "实现用户认证" --yes
/ccw-coordinator "修复登录 bug" --yes
```
**自动模式行为**:
- 跳过需求澄清
- 跳过用户确认
- 直接执行命令链
## 相关 Skills
| Skill | 功能 |
| --- | --- |
| `workflow-lite-plan` | 轻量级规划工作流 |
| `workflow-plan` | 完整规划工作流 |
| `workflow-execute` | 执行工作流 |
| `workflow-tdd` | TDD 工作流 |
| `review-cycle` | 代码审查循环 |
## 对比
| 特性 | /ccw | /ccw-coordinator |
| --- | --- | --- |
| **执行位置** | 主进程 | 外部 CLI + 后台任务 |
| **状态持久化** | 无 | 有 |
| **Hook 回调** | 不支持 | 支持 |
| **复杂工作流** | 简单链式 | 支持并行、依赖 |
| **适用场景** | 日常开发 | 复杂项目、团队协作 |
## 相关文档
- [工作流命令](./workflow.md)
- [会话管理](./session.md)
- [CLI 调用系统](../features/cli.md)

118
docs/zh/commands/claude/index.md Normal file
View File

@@ -0,0 +1,118 @@
# Claude Commands
## 一句话定位
**Claude Commands 是 Claude_dms3 的核心命令系统** — 通过斜杠命令调用各种工作流、工具和协作功能。
## 核心概念速览
| 类别 | 命令数量 | 功能说明 |
| --- | --- | --- |
| **核心编排** | 2 | 主工作流编排器 (ccw, ccw-coordinator) |
| **工作流** | 20+ | 规划、执行、审查、TDD、测试等工作流 |
| **会话管理** | 6 | 会话创建、列表、恢复、完成等 |
| **Issue 工作流** | 7 | Issue 发现、规划、队列、执行 |
| **Memory** | 8 | 记忆捕获、更新、文档生成 |
| **CLI 工具** | 2 | CLI 初始化、Codex 审查 |
| **UI 设计** | 10 | UI 设计原型生成、样式提取 |
## 命令分类
### 1. 核心编排命令
| 命令 | 功能 | 难度 |
| --- | --- | --- |
| [`/ccw`](./core-orchestration.md#ccw) | 主工作流编排器 - 意图分析→工作流选择→命令链执行 | Intermediate |
| [`/ccw-coordinator`](./core-orchestration.md#ccw-coordinator) | 命令编排工具 - 链式命令执行和状态持久化 | Intermediate |
### 2. 工作流命令
| 命令 | 功能 | 难度 |
| --- | --- | --- |
| [`/workflow:lite-lite-lite`](./workflow.md#lite-lite-lite) | 超轻量级多工具分析和直接执行 | Intermediate |
| [`/workflow:lite-plan`](./workflow.md#lite-plan) | 轻量级交互式规划工作流 | Intermediate |
| [`/workflow:lite-execute`](./workflow.md#lite-execute) | 基于内存计划执行任务 | Intermediate |
| [`/workflow:lite-fix`](./workflow.md#lite-fix) | 轻量级 Bug 诊断和修复 | Intermediate |
| [`/workflow:plan`](./workflow.md#plan) | 5 阶段规划工作流 | Intermediate |
| [`/workflow:execute`](./workflow.md#execute) | 协调代理执行工作流任务 | Intermediate |
| [`/workflow:replan`](./workflow.md#replan) | 交互式工作流重新规划 | Intermediate |
| [`/workflow:multi-cli-plan`](./workflow.md#multi-cli-plan) | 多 CLI 协作规划 | Intermediate |
| [`/workflow:review`](./workflow.md#review) | 实现后审查 | Intermediate |
| [`/workflow:clean`](./workflow.md#clean) | 智能代码清理 | Intermediate |
| [`/workflow:init`](./workflow.md#init) | 初始化项目状态 | Intermediate |
| [`/workflow:brainstorm-with-file`](./workflow.md#brainstorm-with-file) | 交互式头脑风暴 | Intermediate |
| [`/workflow:analyze-with-file`](./workflow.md#analyze-with-file) | 交互式协作分析 | Beginner |
| [`/workflow:debug-with-file`](./workflow.md#debug-with-file) | 交互式假设驱动调试 | Intermediate |
| [`/workflow:unified-execute-with-file`](./workflow.md#unified-execute-with-file) | 通用执行引擎 | Intermediate |
### 3. 会话管理命令
| 命令 | 功能 | 难度 |
| --- | --- | --- |
| [`/workflow:session:start`](./session.md#start) | 发现现有会话或启动新工作流会话 | Intermediate |
| [`/workflow:session:list`](./session.md#list) | 列出所有工作流会话 | Beginner |
| [`/workflow:session:resume`](./session.md#resume) | 恢复最近暂停的工作流会话 | Intermediate |
| [`/workflow:session:complete`](./session.md#complete) | 标记活动工作流会话为完成 | Intermediate |
| [`/workflow:session:solidify`](./session.md#solidify) | 将会话学习结晶为项目指南 | Intermediate |
### 4. Issue 工作流命令
| 命令 | 功能 | 难度 |
| --- | --- | --- |
| [`/issue:new`](./issue.md#new) | 从 GitHub URL 或文本描述创建结构化 Issue | Intermediate |
| [`/issue:discover`](./issue.md#discover) | 从多个角度发现潜在 Issue | Intermediate |
| [`/issue:discover-by-prompt`](./issue.md#discover-by-prompt) | 通过用户提示发现 Issue | Intermediate |
| [`/issue:plan`](./issue.md#plan) | 批量规划 Issue 解决方案 | Intermediate |
| [`/issue:queue`](./issue.md#queue) | 形成执行队列 | Intermediate |
| [`/issue:execute`](./issue.md#execute) | 执行队列 | Intermediate |
| [`/issue:convert-to-plan`](./issue.md#convert-to-plan) | 转换规划工件为 Issue 解决方案 | Intermediate |
### 5. Memory 命令
| 命令 | 功能 | 难度 |
| --- | --- | --- |
| [`/memory:compact`](./memory.md#compact) | 压缩当前会话记忆为结构化文本 | Intermediate |
| [`/memory:tips`](./memory.md#tips) | 快速笔记记录 | Beginner |
| [`/memory:load`](./memory.md#load) | 通过 CLI 分析项目加载任务上下文 | Intermediate |
| [`/memory:update-full`](./memory.md#update-full) | 更新所有 CLAUDE.md 文件 | Intermediate |
| [`/memory:update-related`](./memory.md#update-related) | 更新 git 变更模块的 CLAUDE.md | Intermediate |
| [`/memory:docs-full-cli`](./memory.md#docs-full-cli) | 使用 CLI 生成完整项目文档 | Intermediate |
| [`/memory:docs-related-cli`](./memory.md#docs-related-cli) | 生成 git 变更模块文档 | Intermediate |
| [`/memory:style-skill-memory`](./memory.md#style-skill-memory) | 从样式参考生成 SKILL 记忆包 | Intermediate |
### 6. CLI 工具命令
| 命令 | 功能 | 难度 |
| --- | --- | --- |
| [`/cli:cli-init`](./cli.md#cli-init) | 生成配置目录和设置文件 | Intermediate |
| [`/cli:codex-review`](./cli.md#codex-review) | 使用 Codex CLI 进行交互式代码审查 | Intermediate |
### 7. UI 设计命令
| 命令 | 功能 | 难度 |
| --- | --- | --- |
| [`/workflow:ui-design:explore-auto`](./ui-design.md#explore-auto) | 交互式探索性 UI 设计工作流 | Intermediate |
| [`/workflow:ui-design:imitate-auto`](./ui-design.md#imitate-auto) | 直接代码/图片输入的 UI 设计 | Intermediate |
| [`/workflow:ui-design:style-extract`](./ui-design.md#style-extract) | 从参考图片或提示提取设计样式 | Intermediate |
| [`/workflow:ui-design:layout-extract`](./ui-design.md#layout-extract) | 从参考图片提取布局信息 | Intermediate |
| [`/workflow:ui-design:animation-extract`](./ui-design.md#animation-extract) | 提取动画和过渡模式 | Intermediate |
| [`/workflow:ui-design:codify-style`](./ui-design.md#codify-style) | 从代码提取样式并生成可共享引用包 | Intermediate |
| [`/workflow:ui-design:generate`](./ui-design.md#generate) | 组合布局模板与设计令牌生成原型 | Intermediate |
## 自动模式
大多数命令支持 `--yes` 或 `-y` 标志，启用自动模式后跳过确认步骤。
```bash
# 标准模式 - 需要确认
/ccw "实现用户认证"
# 自动模式 - 跳过确认直接执行
/ccw "实现用户认证" --yes
```
## 相关文档
- [Skills 参考](../skills/)
- [CLI 调用系统](../features/cli.md)
- [工作流指南](../guide/ch04-workflow-basics.md)

294
docs/zh/commands/claude/issue.md Normal file
View File

@@ -0,0 +1,294 @@
# Issue 工作流命令
## 一句话定位
**Issue 工作流命令是问题管理的闭环系统** — 从发现、规划到执行，完整追踪问题解决全流程。
## 核心概念速览
| 概念 | 说明 | 存放位置 |
| --- | --- | --- |
| **Issue** | 结构化问题定义 | `.workflow/issues/ISS-*.json` |
| **解决方案** | 执行计划 | `.workflow/solutions/SOL-*.json` |
| **队列** | 执行队列 | `.workflow/queues/QUE-*.json` |
| **执行状态** | 进度跟踪 | 队列内状态 |
## 命令列表
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`new`](#new) | 从 GitHub URL 或文本描述创建结构化 Issue | `/issue:new [-y] <github-url \| 描述> [--priority 1-5]` |
| [`discover`](#discover) | 从多个角度发现潜在 Issue | `/issue:discover [-y] <路径模式> [--perspectives=维度] [--external]` |
| [`discover-by-prompt`](#discover-by-prompt) | 通过用户提示发现 Issue | `/issue:discover-by-prompt [-y] <提示> [--scope=src/**]` |
| [`plan`](#plan) | 批量规划 Issue 解决方案 | `/issue:plan [-y] --all-pending <issue-id>[,...] [--batch-size 3]` |
| [`queue`](#queue) | 形成执行队列 | `/issue:queue [-y] [--queues N] [--issue id]` |
| [`execute`](#execute) | 执行队列 | `/issue:execute [-y] --queue <queue-id> [--worktree [路径]]` |
| [`convert-to-plan`](#convert-to-plan) | 转换规划工件为 Issue 解决方案 | `/issue:convert-to-plan [-y] [--issue id] [--supplement] <来源>` |
## 命令详解
### new
**功能**: 从 GitHub URL 或文本描述创建结构化 Issue，支持需求清晰度检测。
**语法**:
```
/issue:new [-y|--yes] <github-url | 文本描述> [--priority 1-5]
```
**选项**:
- `--priority 1-5`: 优先级（1=关键，5=低）
**清晰度检测**:
| 输入类型 | 清晰度 | 行为 |
| --- | --- | --- |
| GitHub URL | 3 | 直接创建 |
| 结构化文本 | 2 | 直接创建 |
| 长文本 | 1 | 部分澄清 |
| 短文本 | 0 | 完全澄清 |
**Issue 结构**:
```typescript
interface Issue {
id: string; // GH-123 或 ISS-YYYYMMDD-HHMMSS
title: string;
status: 'registered' | 'planned' | 'queued' | 'in_progress' | 'completed' | 'failed';
priority: number; // 1-5
context: string; // 问题描述（单一真相源）
source: 'github' | 'text' | 'discovery';
source_url?: string;
// 绑定
bound_solution_id: string | null;
// 反馈历史
feedback?: Array<{
type: 'failure' | 'clarification' | 'rejection';
stage: string;
content: string;
created_at: string;
}>;
}
```
**示例**:
```bash
# 从 GitHub 创建
/issue:new https://github.com/owner/repo/issues/123
# 从文本创建（结构化）
/issue:new "登录失败：预期成功，实际 500 错误"
# 从文本创建（模糊 - 会询问）
/issue:new "认证有问题"
# 指定优先级
/issue:new --priority 2 "支付超时问题"
```
### discover
**功能**: 从多个角度（Bug、UX、测试、质量、安全、性能、可维护性、最佳实践）发现潜在 Issue。
**语法**:
```
/issue:discover [-y|--yes] <路径模式> [--perspectives=bug,ux,...] [--external]
```
**选项**:
- `--perspectives=维度`: 分析维度
- `bug`: 潜在 Bug
- `ux`: UX 问题
- `test`: 测试覆盖
- `quality`: 代码质量
- `security`: 安全问题
- `performance`: 性能问题
- `maintainability`: 可维护性
- `best-practices`: 最佳实践
- `--external`: 使用 Exa 外部研究（安全、最佳实践）
**示例**:
```bash
# 全面扫描
/issue:discover src/
# 特定维度
/issue:discover src/auth/ --perspectives=security,bug
# 带外部研究
/issue:discover src/payment/ --perspectives=security --external
```
### discover-by-prompt
**功能**: 通过用户提示发现 Issue，使用 Gemini 规划的迭代多代理探索，支持跨模块比较。
**语法**:
```
/issue:discover-by-prompt [-y|--yes] <提示> [--scope=src/**] [--depth=standard|deep] [--max-iterations=5]
```
**选项**:
- `--scope=路径`: 扫描范围
- `--depth=深度`: standard 或 deep
- `--max-iterations=N`: 最大迭代次数
**示例**:
```bash
# 标准扫描
/issue:discover-by-prompt "查找认证模块的问题"
# 深度扫描
/issue:discover-by-prompt "分析 API 性能瓶颈" --depth=deep
# 指定范围
/issue:discover-by-prompt "检查数据库查询优化" --scope=src/db/
```
### plan
**功能**: 批量规划 Issue 解决方案，使用 issue-plan-agent（探索+规划闭环）。
**语法**:
```
/issue:plan [-y|--yes] --all-pending <issue-id>[,<issue-id>,...] [--batch-size 3]
```
**选项**:
- `--all-pending`: 规划所有待规划的 Issue
- `--batch-size=N`: 每批处理的 Issue 数量
**示例**:
```bash
# 规划特定 Issue
/issue:plan ISS-20240115-001,ISS-20240115-002
# 规划所有待规划的 Issue
/issue:plan --all-pending
# 指定批次大小
/issue:plan --all-pending --batch-size 5
```
### queue
**功能**: 从绑定解决方案形成执行队列，使用 issue-queue-agent（解决方案级别）。
**语法**:
```
/issue:queue [-y|--yes] [--queues <n>] [--issue <id>]
```
**选项**:
- `--queues N`: 创建的队列数量
- `--issue id`: 特定 Issue
**示例**:
```bash
# 形成队列
/issue:queue
# 创建多个队列
/issue:queue --queues 3
# 特定 Issue
/issue:queue --issue ISS-20240115-001
```
### execute
**功能**: 执行队列，使用 DAG 并行编排（每个解决方案一次提交）。
**语法**:
```
/issue:execute [-y|--yes] --queue <queue-id> [--worktree [<existing-path>]]
```
**选项**:
- `--queue id`: 队列 ID
- `--worktree [路径]`: 可选的工作树路径
**示例**:
```bash
# 执行队列
/issue:execute --queue QUE-20240115-001
# 使用工作树
/issue:execute --queue QUE-20240115-001 --worktree ../feature-branch
```
### convert-to-plan
**功能**: 转换规划工件（lite-plan、工作流会话、markdown）为 Issue 解决方案。
**语法**:
```
/issue:convert-to-plan [-y|--yes] [--issue <id>] [--supplement] <来源>
```
**选项**:
- `--issue id`: 绑定到现有 Issue
- `--supplement`: 补充模式（添加到现有解决方案）
**来源类型**:
- lite-plan 工件
- 工作流会话
- Markdown 文件
**示例**:
```bash
# 从 lite-plan 转换
/issue:convert-to-plan .workflow/sessions/WFS-xxx/artifacts/lite-plan.md
# 绑定到 Issue
/issue:convert-to-plan --issue ISS-20240115-001 plan.md
# 补充模式
/issue:convert-to-plan --supplement additional-plan.md
```
### from-brainstorm
**功能**: 从头脑风暴会话想法转换为 Issue 并生成可执行解决方案。
**语法**:
```
/issue:from-brainstorm SESSION="会话-id" [--idea=<索引>] [--auto] [-y|--yes]
```
**选项**:
- `--idea=索引`: 特定想法索引
- `--auto`: 自动模式
**示例**:
```bash
# 转换所有想法
/issue:from-brainstorm SESSION="WFS-brainstorm-2024-01-15"
# 转换特定想法
/issue:from-brainstorm SESSION="WFS-brainstorm-2024-01-15" --idea=3
# 自动模式
/issue:from-brainstorm --auto SESSION="WFS-brainstorm-2024-01-15"
```
## Issue 工作流程
```mermaid
graph TD
A[发现 Issue] --> B[创建 Issue]
B --> C[规划解决方案]
C --> D[形成执行队列]
D --> E[执行队列]
E --> F{成功?}
F -->|是| G[完成]
F -->|否| H[反馈学习]
H --> C
```
## 相关文档
- [工作流命令](./workflow.md)
- [核心编排](./core-orchestration.md)
- [团队系统](../../features/)

262
docs/zh/commands/claude/memory.md Normal file
View File

@@ -0,0 +1,262 @@
# Memory 命令
## 一句话定位
**Memory 命令是跨会话知识持久化系统** — 捕获上下文、更新记忆、生成文档，让 AI 记住项目。
## 核心概念速览
| 概念 | 说明 | 存放位置 |
| --- | --- | --- |
| **记忆包** | 结构化项目上下文 | MCP core_memory |
| **CLAUDE.md** | 模块级项目指南 | 每个模块/目录 |
| **Tips** | 快速笔记 | `MEMORY.md` |
| **项目文档** | 生成的文档 | `docs/` 目录 |
## 命令列表
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`compact`](#compact) | 压缩当前会话记忆为结构化文本 | `/memory:compact [可选: 会话描述]` |
| [`tips`](#tips) | 快速笔记记录 | `/memory:tips <笔记内容> [--tag 标签] [--context 上下文]` |
| [`load`](#load) | 通过 CLI 分析项目加载任务上下文 | `/memory:load [--tool gemini\|qwen] "任务上下文描述"` |
| [`update-full`](#update-full) | 更新所有 CLAUDE.md 文件 | `/memory:update-full [--tool gemini\|qwen\|codex] [--path 目录]` |
| [`update-related`](#update-related) | 更新 git 变更模块的 CLAUDE.md | `/memory:update-related [--tool gemini\|qwen\|codex]` |
| [`docs-full-cli`](#docs-full-cli) | 使用 CLI 生成完整项目文档 | `/memory:docs-full-cli [路径] [--tool 工具]` |
| [`docs-related-cli`](#docs-related-cli) | 生成 git 变更模块文档 | `/memory:docs-related-cli [--tool 工具]` |
| [`style-skill-memory`](#style-skill-memory) | 从样式参考生成 SKILL 记忆包 | `/memory:style-skill-memory [包名] [--regenerate]` |
## 命令详解
### compact
**功能**: 压缩当前会话记忆为结构化文本，提取目标、计划、文件、决策、约束、状态，并通过 MCP core_memory 工具保存。
**语法**:
```
/memory:compact [可选: 会话描述]
```
**提取内容**:
- 目标 (objective)
- 计划 (plan)
- 文件 (files)
- 决策 (decisions)
- 约束 (constraints)
- 状态 (state)
**示例**:
```bash
# 基础压缩
/memory:compact
# 带描述
/memory:compact "用户认证实现会话"
```
### tips
**功能**: 快速笔记记录命令，捕获想法、片段、提醒和洞察供后续参考。
**语法**:
```
/memory:tips <笔记内容> [--tag <标签1,标签2>] [--context <上下文>]
```
**选项**:
- `--tag=标签`: 标签（逗号分隔）
- `--context=上下文`: 上下文信息
**示例**:
```bash
# 基础笔记
/memory:tips "记得使用 rate limiting 限制 API 调用"
# 带标签
/memory:tips "认证中间件需要处理 token 过期" --tag auth,api
# 带上下文
/memory:tips "使用 Redis 缓存用户会话" --context "登录优化"
```
### load
**功能**: 委托给 universal-executor 代理，通过 Gemini/Qwen CLI 分析项目并返回 JSON 核心内容包用于任务上下文。
**语法**:
```
/memory:load [--tool gemini|qwen] "任务上下文描述"
```
**选项**:
- `--tool=工具`: 使用的 CLI 工具
**输出**: JSON 格式的项目上下文包
**示例**:
```bash
# 使用默认工具
/memory:load "用户认证模块"
# 指定工具
/memory:load --tool gemini "支付系统架构"
```
### update-full
**功能**: 更新所有 CLAUDE.md 文件，使用基于层的执行（Layer 3→1），批量代理处理（4 模块/代理）和 gemini→qwen→codex 回退。
**语法**:
```
/memory:update-full [--tool gemini|qwen|codex] [--path <目录>]
```
**选项**:
- `--tool=工具`: 使用的 CLI 工具
- `--path=目录`: 特定目录
**层结构**:
- Layer 3: 项目级分析
- Layer 2: 模块级分析
- Layer 1: 文件级分析
**示例**:
```bash
# 更新整个项目
/memory:update-full
# 更新特定目录
/memory:update-full --path src/auth/
# 指定工具
/memory:update-full --tool qwen
```
### update-related
**功能**: 更新 git 变更模块的 CLAUDE.md 文件，使用批量代理执行（4 模块/代理）和 gemini→qwen→codex 回退。
**语法**:
```
/memory:update-related [--tool gemini|qwen|codex]
```
**选项**:
- `--tool=工具`: 使用的 CLI 工具
**示例**:
```bash
# 默认更新
/memory:update-related
# 指定工具
/memory:update-related --tool gemini
```
### docs-full-cli
**功能**: 使用 CLI 执行生成完整项目文档（Layer 3→1），批量代理处理（4 模块/代理）和 gemini→qwen→codex 回退，<20 模块使用直接并行。
**语法**:
```
/memory:docs-full-cli [路径] [--tool <gemini|qwen|codex>]
```
**示例**:
```bash
# 生成整个项目文档
/memory:docs-full-cli
# 生成特定目录文档
/memory:docs-full-cli src/
# 指定工具
/memory:docs-full-cli --tool gemini
```
### docs-related-cli
**功能**: 使用 CLI 执行生成 git 变更模块文档，批量代理处理（4 模块/代理）和 gemini→qwen→codex 回退，<15 模块使用直接执行。
**语法**:
```
/memory:docs-related-cli [--tool <gemini|qwen|codex>]
```
**示例**:
```bash
# 默认生成
/memory:docs-related-cli
# 指定工具
/memory:docs-related-cli --tool qwen
```
### style-skill-memory
**功能**: 从样式参考生成 SKILL 记忆包，便于加载和一致的设计系统使用。
**语法**:
```
/memory:style-skill-memory [包名] [--regenerate]
```
**选项**:
- `--regenerate`: 重新生成
**示例**:
```bash
# 生成样式记忆包
/memory:style-skill-memory my-design-system
# 重新生成
/memory:style-skill-memory my-design-system --regenerate
```
## Memory 系统工作流程
```mermaid
graph TD
A[会话中] --> B[捕获上下文]
B --> C{会话完成?}
C -->|是| D[压缩记忆]
C -->|否| E[继续工作]
D --> F[保存到 core_memory]
F --> G[更新 CLAUDE.md]
G --> H[生成文档]
H --> I[新会话开始]
I --> J[加载记忆包]
J --> K[恢复上下文]
K --> A
```
## CLAUDE.md 结构
```markdown
# 模块名称
## 一句话定位
模块的核心价值描述
## 技术栈
- 框架/库
- 主要依赖
## 关键文件
- 文件路径: 说明
## 代码约定
- 命名规范
- 架构模式
- 最佳实践
## 待办事项
- 计划中的功能
- 已知问题
```
## 相关文档
- [Memory 记忆系统](../../features/memory.md)
- [核心编排](./core-orchestration.md)
- [工作流指南](../../guide/ch03-core-concepts.md)

256
docs/zh/commands/claude/session.md Normal file
View File

@@ -0,0 +1,256 @@
# 会话管理命令
## 一句话定位
**会话管理命令是工作流的状态管理者** — 创建、跟踪、恢复和完成工作流会话。
## 核心概念速览
| 概念 | 说明 | 位置 |
| --- | --- | --- |
| **会话 ID** | 唯一标识符 (WFS-YYYY-MM-DD) | `.workflow/active/WFS-xxx/` |
| **会话类型** | workflow, review, tdd, test, docs | 会话元数据 |
| **会话状态** | active, paused, completed | workflow-session.json |
| **工件** | 规划、任务、TODO 等文件 | 会话目录 |
## 命令列表
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`start`](#start) | 发现现有会话或启动新工作流会话 | `/workflow:session:start [--type 类型] [--auto\|--new] [描述]` |
| [`list`](#list) | 列出所有工作流会话 | `/workflow:session:list` |
| [`resume`](#resume) | 恢复最近暂停的工作流会话 | `/workflow:session:resume` |
| [`complete`](#complete) | 标记活动工作流会话为完成 | `/workflow:session:complete [-y] [--detailed]` |
| [`solidify`](#solidify) | 将会话学习结晶为项目指南 | `/workflow:session:solidify [-y] [--type 类型] [--category 类别] "规则"` |
## 命令详解
### start
**功能**: 发现现有会话或启动新工作流会话，支持智能会话管理和冲突检测。
**语法**:
```
/workflow:session:start [--type <workflow|review|tdd|test|docs>] [--auto|--new] [可选: 任务描述]
```
**选项**:
- `--type=类型`: 会话类型
- `workflow`: 标准实现（默认）
- `review`: 代码审查
- `tdd`: TDD 开发
- `test`: 测试生成/修复
- `docs`: 文档会话
- `--auto`: 智能模式（自动检测/创建）
- `--new`: 强制创建新会话
**会话类型**:
| 类型 | 描述 | 默认来源 |
| --- | --- | --- |
| `workflow` | 标准实现 | workflow-plan skill |
| `review` | 代码审查 | review-cycle skill |
| `tdd` | TDD 开发 | workflow-tdd skill |
| `test` | 测试生成/修复 | workflow-test-fix skill |
| `docs` | 文档会话 | memory-manage skill |
**工作流程**:
```mermaid
graph TD
A[开始] --> B{项目状态存在?}
B -->|否| C[调用 workflow:init]
C --> D
B -->|是| D{模式}
D -->|默认| E[列出活动会话]
D -->|auto| F{活动会话数?}
D -->|new| G[创建新会话]
F -->|0| G
F -->|1| H[使用现有会话]
F -->|>1| I[用户选择]
E --> J{用户选择}
J -->|现有| K[返回会话 ID]
J -->|新建| G
G --> L[生成会话 ID]
L --> M[创建目录结构]
M --> N[初始化元数据]
N --> O[返回会话 ID]
```
**示例**:
```bash
# 发现模式 - 列出活动会话
/workflow:session:start
# 自动模式 - 智能选择/创建
/workflow:session:start --auto "实现用户认证"
# 新建模式 - 强制创建新会话
/workflow:session:start --new "重构支付模块"
# 指定类型
/workflow:session:start --type review "审查认证代码"
/workflow:session:start --type tdd --auto "实现登录功能"
```
### list
**功能**: 列出所有工作流会话，支持状态过滤，显示会话元数据和进度信息。
**语法**:
```
/workflow:session:list
```
**输出格式**:
| 会话 ID | 类型 | 状态 | 描述 | 进度 |
| --- | --- | --- | --- | --- |
| WFS-2024-01-15 | workflow | active | 用户认证 | 5/10 |
| WFS-2024-01-14 | review | paused | 代码审查 | 8/8 |
| WFS-2024-01-13 | tdd | completed | TDD 开发 | 12/12 |
**示例**:
```bash
# 列出所有会话
/workflow:session:list
```
### resume
**功能**: 恢复最近暂停的工作流会话，支持自动会话发现和状态更新。
**语法**:
```
/workflow:session:resume
```
**工作流程**:
```mermaid
graph TD
A[开始] --> B[查找暂停会话]
B --> C{找到暂停会话?}
C -->|是| D[加载会话]
C -->|否| E[错误提示]
D --> F[更新状态为 active]
F --> G[返回会话 ID]
```
**示例**:
```bash
# 恢复最近暂停的会话
/workflow:session:resume
```
### complete
**功能**: 标记活动工作流会话为完成，归档并学习经验，更新清单并移除活动标志。
**语法**:
```
/workflow:session:complete [-y|--yes] [--detailed]
```
**选项**:
- `--detailed`: 详细模式，收集更多经验教训
**工作流程**:
```mermaid
graph TD
A[开始] --> B[确认完成]
B --> C{详细模式?}
C -->|是| D[收集详细反馈]
C -->|否| E[收集基本反馈]
D --> F[生成学习文档]
E --> F
F --> G[归档会话]
G --> H[更新清单]
H --> I[移除活动标志]
I --> J[完成]
```
**示例**:
```bash
# 标准完成
/workflow:session:complete
# 详细完成
/workflow:session:complete --detailed
# 自动模式
/workflow:session:complete -y
```
### solidify
**功能**: 将会话学习和用户定义的约束结晶为永久项目指南。
**语法**:
```
/workflow:session:solidify [-y|--yes] [--type <convention|constraint|learning>] [--category <类别>] "规则或洞察"
```
**选项**:
- `--type=类型`:
- `convention`: 代码约定
- `constraint`: 约束条件
- `learning`: 经验学习
- `--category=类别`: 类别名称（如 `authentication`, `testing`）
**输出位置**:
- 约定: `.workflow/specs/conventions/<category>.md`
- 约束: `.workflow/specs/constraints/<category>.md`
- 学习: `.workflow/specs/learnings/<category>.md`
**示例**:
```bash
# 添加代码约定
/workflow:session:solidify --type=convention --category=auth "所有认证函数必须使用 rate limiting"
# 添加约束
/workflow:session:solidify --type=constraint --category=database "不使用 N+1 查询"
# 添加学习
/workflow:session:solidify --type=learning --category=api "REST API 设计经验"
```
## 会话目录结构
```
.workflow/
├── active/ # 活动会话
│ └── WFS-2024-01-15/ # 会话目录
│ ├── workflow-session.json # 会话元数据
│ ├── tasks/ # 任务定义
│ ├── artifacts/ # 工件文件
│ └── context/ # 上下文文件
└── archived/ # 归档会话
└── WFS-2024-01-14/
```
## 会话元数据
```json
{
"session_id": "WFS-2024-01-15",
"type": "workflow",
"status": "active",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T14:30:00Z",
"description": "用户认证功能实现",
"progress": {
"total": 10,
"completed": 5,
"percentage": 50
}
}
```
## 相关文档
- [工作流命令](./workflow.md)
- [核心编排](./core-orchestration.md)
- [工作流基础](../../guide/ch04-workflow-basics.md)

307
docs/zh/commands/claude/ui-design.md Normal file
View File

@@ -0,0 +1,307 @@
# UI 设计命令
## 一句话定位
**UI 设计命令是界面原型生成系统** — 从样式提取、布局分析到原型组装，完整覆盖 UI 设计流程。
## 核心概念速览
| 概念 | 说明 | 存放位置 |
| --- | --- | --- |
| **设计运行** | 设计会话目录 | `.workflow/ui-design-runs/<run-id>/` |
| **设计令牌** | 样式变量 | `design-tokens.json` |
| **布局模板** | 结构定义 | `layouts/` |
| **原型** | 生成的组件 | `prototypes/` |
## 命令列表
### 发现与提取
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`explore-auto`](#explore-auto) | 交互式探索性 UI 设计工作流 | `/workflow:ui-design:explore-auto [--input "值"] [--targets "列表"]` |
| [`imitate-auto`](#imitate-auto) | 直接代码/图片输入的 UI 设计 | `/workflow:ui-design:imitate-auto [--input "值"] [--session id]` |
| [`style-extract`](#style-extract) | 从参考图片或提示提取设计样式 | `/workflow:ui-design:style-extract [-y] [--design-id id]` |
| [`layout-extract`](#layout-extract) | 从参考图片提取布局信息 | `/workflow:ui-design:layout-extract [-y] [--design-id id]` |
| [`animation-extract`](#animation-extract) | 提取动画和过渡模式 | `/workflow:ui-design:animation-extract [-y] [--design-id id]` |
### 导入与导出
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`import-from-code`](#import-from-code) | 从代码文件导入设计系统 | `/workflow:ui-design:import-from-code [--design-id id] [--session id] [--source path]` |
| [`codify-style`](#codify-style) | 从代码提取样式并生成可共享引用包 | `/workflow:ui-design:codify-style <path> [--package-name name]` |
| [`reference-page-generator`](#reference-page-generator) | 从设计运行生成多组件参考页面 | `/workflow:ui-design:reference-page-generator [--design-run path]` |
### 生成与同步
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`generate`](#generate) | 组合布局模板与设计令牌生成原型 | `/workflow:ui-design:generate [--design-id id] [--session id]` |
| [`design-sync`](#design-sync) | 同步最终设计系统引用到头脑风暴工件 | `/workflow:ui-design:design-sync --session <session_id>` |
## 命令详解
### explore-auto
**功能**: 交互式探索性 UI 设计工作流，以样式为中心的批量生成，从提示/图片创建设计变体，支持并行执行和用户选择。
**语法**:
```
/workflow:ui-design:explore-auto [--input "<值>"] [--targets "<列表>"] [--target-type "page|component"] [--session <id>] [--style-variants <数量>] [--layout-variants <数量>]
```
**选项**:
- `--input=值`: 输入提示或图片路径
- `--targets=列表`: 目标组件列表（逗号分隔）
- `--target-type=类型`: page 或 component
- `--session=id`: 会话 ID
- `--style-variants=N`: 样式变体数量
- `--layout-variants=N`: 布局变体数量
**示例**:
```bash
# 页面设计探索
/workflow:ui-design:explore-auto --input "现代电商首页" --target-type page --style-variants 3
# 组件设计探索
/workflow:ui-design:explore-auto --input "用户卡片组件" --target-type component --layout-variants 5
# 多目标设计
/workflow:ui-design:explore-auto --targets "header,sidebar,footer" --style-variants 2
```
### imitate-auto
**功能**: UI 设计工作流，支持直接代码/图片输入进行设计令牌提取和原型生成。
**语法**:
```
/workflow:ui-design:imitate-auto [--input "<值>"] [--session <id>]
```
**选项**:
- `--input=值`: 代码文件路径或图片路径
- `--session=id`: 会话 ID
**示例**:
```bash
# 从代码模仿
/workflow:ui-design:imitate-auto --input "./src/components/Button.tsx"
# 从图片模仿
/workflow:ui-design:imitate-auto --input "./designs/mockup.png"
```
### style-extract
**功能**: 从参考图片或文本提示使用 Claude 分析提取设计样式，支持变体生成或精化模式。
**语法**:
```
/workflow:ui-design:style-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<描述>"] [--variants <数量>] [--interactive] [--refine]
```
**选项**:
- `--images=glob`: 图片 glob 模式
- `--prompt=描述`: 文本描述
- `--variants=N`: 变体数量
- `--interactive`: 交互模式
- `--refine`: 精化模式
**示例**:
```bash
# 从图片提取样式
/workflow:ui-design:style-extract --images "./designs/*.png" --variants 3
# 从提示提取
/workflow:ui-design:style-extract --prompt "深色主题，蓝色主色调，圆角设计"
# 交互精化
/workflow:ui-design:style-extract --images "reference.png" --refine --interactive
```
### layout-extract
**功能**: 从参考图片或文本提示使用 Claude 分析提取结构布局信息，支持变体生成或精化模式。
**语法**:
```
/workflow:ui-design:layout-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<描述>"] [--targets "<列表>"] [--variants <数量>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
```
**选项**:
- `--device-type=类型`: desktop, mobile, tablet 或 responsive
- 其他同 style-extract
**示例**:
```bash
# 提取桌面布局
/workflow:ui-design:layout-extract --images "desktop-mockup.png" --device-type desktop
# 提取响应式布局
/workflow:ui-design:layout-extract --prompt "三栏布局，响应式设计" --device-type responsive
# 多变体
/workflow:ui-design:layout-extract --images "layout.png" --variants 5
```
### animation-extract
**功能**: 从提示推断和图片引用提取动画和过渡模式，用于设计系统文档。
**语法**:
```
/workflow:ui-design:animation-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--focus "<类型>"] [--interactive] [--refine]
```
**选项**:
- `--focus=类型`: 特定动画类型（如 fade, slide, scale）
**示例**:
```bash
# 提取所有动画
/workflow:ui-design:animation-extract --images "./animations/*.gif"
# 提取特定类型
/workflow:ui-design:animation-extract --focus "fade,slide" --interactive
```
### import-from-code
**功能**: 从代码文件（CSS/JS/HTML/SCSS）导入设计系统，使用自动文件发现和并行代理分析。
**语法**:
```
/workflow:ui-design:import-from-code [--design-id <id>] [--session <id>] [--source <path>]
```
**选项**:
- `--source=路径`: 源代码目录
**示例**:
```bash
# 从项目导入
/workflow:ui-design:import-from-code --source "./src/styles/"
# 指定设计 ID
/workflow:ui-design:import-from-code --design-id my-design --source "./theme/"
```
### codify-style
**功能**: 编排器从代码提取样式并生成可共享引用包，支持预览（自动文件发现）。
**语法**:
```
/workflow:ui-design:codify-style <path> [--package-name <name>] [--output-dir <path>] [--overwrite]
```
**选项**:
- `--package-name=名称`: 包名称
- `--output-dir=路径`: 输出目录
- `--overwrite`: 覆盖现有文件
**示例**:
```bash
# 生成样式包
/workflow:ui-design:codify-style ./src/styles/ --package-name my-design-system
# 指定输出目录
/workflow:ui-design:codify-style ./theme/ --output-dir ./design-packages/
```
### reference-page-generator
**功能**: 从设计运行提取生成多组件参考页面和文档。
**语法**:
```
/workflow:ui-design:reference-page-generator [--design-run <path>] [--package-name <name>] [--output-dir <path>]
```
**示例**:
```bash
# 生成参考页面
/workflow:ui-design:reference-page-generator --design-run .workflow/ui-design-runs/latest/
# 指定包名
/workflow:ui-design:reference-page-generator --package-name component-library
```
### generate
**功能**: 组装 UI 原型，将布局模板与设计令牌（默认动画支持）组合，纯组装器无新内容生成。
**语法**:
```
/workflow:ui-design:generate [--design-id <id>] [--session <id>]
```
**示例**:
```bash
# 生成原型
/workflow:ui-design:generate
# 使用特定设计
/workflow:ui-design:generate --design-id my-design
```
### design-sync
**功能**: 同步最终设计系统引用到头脑风暴工件，准备供 `/workflow:plan` 消费。
**语法**:
```
/workflow:ui-design:design-sync --session <session_id> [--selected-prototypes "<列表>"]
```
**选项**:
- `--selected-prototypes=列表`: 选定的原型列表
**示例**:
```bash
# 同步所有原型
/workflow:ui-design:design-sync --session WFS-design-2024-01-15
# 同步选定原型
/workflow:ui-design:design-sync --session WFS-design-2024-01-15 --selected-prototypes "header,button,card"
```
## UI 设计工作流程
```mermaid
graph TD
A[输入] --> B{输入类型}
B -->|图片/提示| C[提取样式]
B -->|代码| D[导入样式]
C --> E[提取布局]
D --> E
E --> F[提取动画]
F --> G[设计运行]
G --> H[生成原型]
H --> I[同步到头脑风暴]
I --> J[规划工作流]
```
## 设计运行结构
```
.workflow/ui-design-runs/<run-id>/
├── design-tokens.json # 设计令牌
├── layouts/ # 布局模板
│ ├── header.json
│ ├── footer.json
│ └── ...
├── prototypes/ # 生成的原型
│ ├── header/
│ ├── button/
│ └── ...
└── reference-pages/ # 参考页面
```
## 相关文档
- [核心编排](./core-orchestration.md)
- [工作流命令](./workflow.md)
- [头脑风暴](../../features/)

338
docs/zh/commands/claude/workflow.md Normal file
View File

@@ -0,0 +1,338 @@
# 工作流命令
## 一句话定位
**工作流命令是 Claude_dms3 的执行引擎** — 提供从轻量级任务到复杂项目的完整工作流支持。
## 命令列表
### 轻量级工作流
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`lite-lite-lite`](#lite-lite-lite) | 超轻量级多工具分析和直接执行 | `/workflow:lite-lite-lite [-y] <任务>` |
| [`lite-plan`](#lite-plan) | 轻量级交互式规划工作流 | `/workflow:lite-plan [-y] [-e] "任务"` |
| [`lite-execute`](#lite-execute) | 基于内存计划执行任务 | `/workflow:lite-execute [-y] [--in-memory] [任务]` |
| [`lite-fix`](#lite-fix) | 轻量级 Bug 诊断和修复 | `/workflow:lite-fix [-y] [--hotfix] "Bug 描述"` |
### 标准工作流
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`plan`](#plan) | 5 阶段规划工作流 | `/workflow:plan [-y] "描述"\|file.md` |
| [`execute`](#execute) | 协调代理执行工作流任务 | `/workflow:execute [-y] [--resume-session=ID]` |
| [`replan`](#replan) | 交互式工作流重新规划 | `/workflow:replan [-y] [--session ID] [task-id] "需求"` |
### 协作工作流
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`multi-cli-plan`](#multi-cli-plan) | 多 CLI 协作规划 | `/workflow:multi-cli-plan [-y] <任务> [--max-rounds=N]` |
| [`brainstorm-with-file`](#brainstorm-with-file) | 交互式头脑风暴 | `/workflow:brainstorm-with-file [-y] [-c] "想法"` |
| [`analyze-with-file`](#analyze-with-file) | 交互式协作分析 | `/workflow:analyze-with-file [-y] [-c] "主题"` |
| [`debug-with-file`](#debug-with-file) | 交互式假设驱动调试 | `/workflow:debug-with-file [-y] "Bug 描述"` |
| [`unified-execute-with-file`](#unified-execute-with-file) | 通用执行引擎 | `/workflow:unified-execute-with-file [-y] [-p path] [上下文]` |
### TDD 工作流
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`tdd-plan`](#tdd-plan) | TDD 规划工作流 | `/workflow:tdd-plan "功能描述"` |
| [`tdd-verify`](#tdd-verify) | 验证 TDD 工作流合规性 | `/workflow:tdd-verify [--session ID]` |
### 测试工作流
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`test-fix-gen`](#test-fix-gen) | 创建测试修复工作流会话 | `/workflow:test-fix-gen (session-id\|"描述"\|file.md)` |
| [`test-gen`](#test-gen) | 从实现会话创建测试会话 | `/workflow:test-gen source-session-id` |
| [`test-cycle-execute`](#test-cycle-execute) | 执行测试修复工作流 | `/workflow:test-cycle-execute [--resume-session=ID]` |
### 审查工作流
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`review`](#review) | 实现后审查 | `/workflow:review [--type=类型] [--archived] [session-id]` |
| [`review-module-cycle`](#review-module-cycle) | 独立多维度代码审查 | `/workflow:review-module-cycle <路径> [--dimensions=维度]` |
| [`review-session-cycle`](#review-session-cycle) | 基于会话的审查 | `/workflow:review-session-cycle [session-id] [--dimensions=维度]` |
| [`review-cycle-fix`](#review-cycle-fix) | 自动修复审查发现 | `/workflow:review-cycle-fix <export-file\|review-dir>` |
### 专用工作流
| 命令 | 功能 | 语法 |
| --- | --- | --- |
| [`clean`](#clean) | 智能代码清理 | `/workflow:clean [-y] [--dry-run] ["焦点区域"]` |
| [`init`](#init) | 初始化项目状态 | `/workflow:init [--regenerate]` |
| [`plan-verify`](#plan-verify) | 验证规划一致性 | `/workflow:plan-verify [--session session-id]` |
## 命令详解
### lite-lite-lite
**功能**: 超轻量级多工具分析和直接执行。简单任务无工件，复杂任务自动在 `.workflow/.scratchpad/` 创建规划文档。
**语法**:
```
/workflow:lite-lite-lite [-y|--yes] <任务描述>
```
**使用场景**:
- 超简单快速任务
- 不需要规划文档的代码修改
- 自动工具选择
**示例**:
```bash
# 超简单任务
/workflow:lite-lite-lite "修复 header 样式"
# 自动模式
/workflow:lite-lite-lite -y "更新 README 链接"
```
### lite-plan
**功能**: 轻量级交互式规划工作流，支持内存规划、代码探索和执行到 lite-execute。
**语法**:
```
/workflow:lite-plan [-y|--yes] [-e|--explore] "任务描述" | file.md
```
**选项**:
- `-e, --explore`: 先执行代码探索
**示例**:
```bash
# 基础规划
/workflow:lite-plan "添加用户头像功能"
# 带探索
/workflow:lite-plan -e "重构认证模块"
```
### lite-execute
**功能**: 基于内存计划、提示描述或文件内容执行任务。
**语法**:
```
/workflow:lite-execute [-y|--yes] [--in-memory] ["任务描述" | file-path]
```
**选项**:
- `--in-memory`: 使用内存计划
**示例**:
```bash
# 执行任务
/workflow:lite-execute "实现头像上传 API"
# 使用内存计划
/workflow:lite-execute --in-memory
```
### lite-fix
**功能**: 轻量级 Bug 诊断和修复工作流，支持智能严重程度评估和可选的热修复模式。
**语法**:
```
/workflow:lite-fix [-y|--yes] [--hotfix] "Bug 描述或 Issue 引用"
```
**选项**:
- `--hotfix`: 热修复模式（生产事故快速修复）
**示例**:
```bash
# Bug 修复
/workflow:lite-fix "登录时出现 500 错误"
# 热修复
/workflow:lite-fix --hotfix "支付网关超时"
```
### plan
**功能**: 5 阶段规划工作流，输出 IMPL_PLAN.md 和任务 JSON。
**语法**:
```
/workflow:plan [-y|--yes] "文本描述" | file.md
```
**阶段**:
1. 会话初始化
2. 上下文收集
3. 规范加载
4. 任务生成
5. 验证/重新规划
**示例**:
```bash
# 从描述规划
/workflow:plan "实现用户通知系统"
# 从文件规划
/workflow:plan requirements.md
```
### execute
**功能**: 协调代理执行工作流任务，支持自动会话发现、并行任务处理和状态跟踪。
**语法**:
```
/workflow:execute [-y|--yes] [--resume-session="session-id"]
```
**示例**:
```bash
# 执行当前会话
/workflow:execute
# 恢复并执行会话
/workflow:execute --resume-session=WFS-2024-01-15
```
### replan
**功能**: 交互式工作流重新规划，支持会话级工件更新和边界澄清。
**语法**:
```
/workflow:replan [-y|--yes] [--session session-id] [task-id] "需求" | file.md [--interactive]
```
**示例**:
```bash
# 重新规划整个会话
/workflow:replan --session=WFS-xxx "添加用户权限检查"
# 重新规划特定任务
/workflow:replan TASK-001 "改为使用 RBAC"
```
### multi-cli-plan
**功能**: 多 CLI 协作规划工作流，使用 ACE 上下文收集和迭代交叉验证。
**语法**:
```
/workflow:multi-cli-plan [-y|--yes] <任务描述> [--max-rounds=3] [--tools=gemini,codex] [--mode=parallel|serial]
```
**选项**:
- `--max-rounds=N`: 最大讨论轮数
- `--tools=工具`: 使用的 CLI 工具
- `--mode=模式`: 并行或串行模式
**示例**:
```bash
# 多 CLI 规划
/workflow:multi-cli-plan "设计微服务架构"
# 指定工具和轮数
/workflow:multi-cli-plan --tools=gemini,codex --max-rounds=5 "数据库迁移方案"
```
### brainstorm-with-file
**功能**: 交互式头脑风暴，多 CLI 协作、想法扩展和文档化思维演化。
**语法**:
```
/workflow:brainstorm-with-file [-y|--yes] [-c|--continue] [-m|--mode creative|structured] "想法或主题"
```
**选项**:
- `-c, --continue`: 继续现有会话
- `-m, --mode=模式`: creative 或 structured
**示例**:
```bash
# 创意头脑风暴
/workflow:brainstorm-with-file --mode creative "用户增长策略"
# 结构化头脑风暴
/workflow:brainstorm-with-file --mode structured "API 版本控制方案"
```
### analyze-with-file
**功能**: 交互式协作分析，有文档化的讨论、CLI 辅助探索和演化理解。
**语法**:
```
/workflow:analyze-with-file [-y|--yes] [-c|--continue] "主题或问题"
```
**示例**:
```bash
# 分析主题
/workflow:analyze-with-file "认证架构设计"
# 继续讨论
/workflow:analyze-with-file -c
```
### debug-with-file
**功能**: 交互式假设驱动调试，有文档化的探索、理解演化和 Gemini 辅助修正。
**语法**:
```
/workflow:debug-with-file [-y|--yes] "Bug 描述或错误信息"
```
**示例**:
```bash
# 调试 Bug
/workflow:debug-with-file "WebSocket 连接随机断开"
# 调试错误
/workflow:debug-with-file "TypeError: Cannot read property 'id'"
```
### unified-execute-with-file
**功能**: 通用执行引擎，消费任何规划/头脑风暴/分析输出，支持最小进度跟踪、多代理协调和增量执行。
**语法**:
```
/workflow:unified-execute-with-file [-y|--yes] [-p|--plan <path>] [-m|--mode sequential|parallel] ["执行上下文"]
```
**示例**:
```bash
# 执行规划
/workflow:unified-execute-with-file -p plan.md
# 并行执行
/workflow:unified-execute-with-file -m parallel
```
## 工作流程图
```mermaid
graph TD
A[任务输入] --> B{任务复杂度}
B -->|简单| C[Lite 工作流]
B -->|标准| D[Plan 工作流]
B -->|复杂| E[Multi-CLI 工作流]
C --> F[直接执行]
D --> G[规划] --> H[执行]
E --> I[多 CLI 讨论] --> G
F --> J[完成]
H --> J
I --> J
```
## 相关文档
- [会话管理](./session.md)
- [核心编排](./core-orchestration.md)
- [工作流指南](../../guide/ch04-workflow-basics.md)

56
docs/zh/commands/codex/index.md Normal file
View File

@@ -0,0 +1,56 @@
# Codex Prompts
## 一句话定位
**Codex Prompts 是 Codex CLI 使用的提示模板系统** — 标准化的提示格式确保一致的代码质量和审查效果。
## 核心概念速览
| 概念 | 说明 | 用途 |
| --- | --- | --- |
| **Prep 提示** | 项目上下文准备提示 | 分析项目结构、提取相关文件 |
| **Review 提示** | 代码审查提示 | 多维度代码质量检查 |
## Prompt 列表
### Prep 系列
| 提示 | 功能 | 用途 |
| --- | --- | --- |
| [`memory:prepare`](./prep.md#memory-prepare) | 项目上下文准备 | 为任务准备结构化项目上下文 |
### Review 系列
| 提示 | 功能 | 用途 |
| --- | --- | --- |
| [`codex-review`](./review.md#codex-review) | 交互式代码审查 | 使用 Codex CLI 进行代码审查 |
## Prompt 模板格式
所有 Codex Prompts 遵循标准 CCW CLI 提示模板：
```
PURPOSE: [目标] + [原因] + [成功标准] + [约束/范围]
TASK: • [步骤 1] • [步骤 2] • [步骤 3]
MODE: review
CONTEXT: [审查目标描述] | Memory: [相关上下文]
EXPECTED: [交付格式] + [质量标准]
CONSTRAINTS: [关注约束]
```
## 字段说明
| 字段 | 说明 | 示例 |
| --- | --- | --- |
| **PURPOSE** | 目的和原因 | "识别安全漏洞，确保代码安全" |
| **TASK** | 具体步骤 | "• 扫描注入漏洞 • 检查认证逻辑" |
| **MODE** | 执行模式 | analysis, write, review |
| **CONTEXT** | 上下文信息 | "@CLAUDE.md @src/auth/**" |
| **EXPECTED** | 输出格式 | "结构化报告，包含严重程度级别" |
| **CONSTRAINTS** | 约束条件 | "关注可操作的建议" |
## 相关文档
- [Claude Commands](../claude/)
- [CLI 调用系统](../../features/cli.md)
- [代码审查](../../features/)

168
docs/zh/commands/codex/prep.md Normal file
View File

@@ -0,0 +1,168 @@
# Prep 提示
## 一句话定位
**Prep 提示是项目上下文准备的标准化模板** — 通过代理驱动分析生成结构化项目核心内容包。
## 核心内容包结构
```json
{
"task_context": "任务上下文描述",
"keywords": ["关键词1", "关键词2"],
"project_summary": {
"architecture": "架构描述",
"tech_stack": ["技术1", "技术2"],
"key_patterns": ["模式1", "模式2"]
},
"relevant_files": [
{
"path": "文件路径",
"relevance": "相关性说明",
"priority": "high|medium|low"
}
],
"integration_points": [
"集成点1",
"集成点2"
],
"constraints": [
"约束1",
"约束2"
]
}
```
## memory:prepare
**功能**: 委托给 universal-executor 代理，通过 Gemini/Qwen CLI 分析项目并返回 JSON 核心内容包用于任务上下文。
**语法**:
```
/memory:prepare [--tool gemini|qwen] "任务上下文描述"
```
**选项**:
- `--tool=工具`: 指定 CLI 工具（默认：gemini）
- `gemini`: 大上下文窗口，适合复杂项目分析
- `qwen`: Gemini 的替代方案，具有相似能力
**执行流程**:
```mermaid
graph TD
A[开始] --> B[分析项目结构]
B --> C[加载文档]
C --> D[提取关键词]
D --> E[发现文件]
E --> F[CLI 深度分析]
F --> G[生成内容包]
G --> H[加载到主线程记忆]
```
**代理调用提示**:
```
## Mission: Prepare Project Memory Context
**Task**: Prepare project memory context for: "{task_description}"
**Mode**: analysis
**Tool Preference**: {tool}
### Step 1: Foundation Analysis
1. Project Structure: get_modules_by_depth.sh
2. Core Documentation: CLAUDE.md, README.md
### Step 2: Keyword Extraction & File Discovery
1. Extract core keywords from task description
2. Discover relevant files using ripgrep and find
### Step 3: Deep Analysis via CLI
Execute Gemini/Qwen CLI for deep analysis
### Step 4: Generate Core Content Package
Return structured JSON with required fields
### Step 5: Return Content Package
Load JSON into main thread memory
```
**示例**:
```bash
# 基础用法
/memory:prepare "在当前前端基础上开发用户认证功能"
# 指定工具
/memory:prepare --tool qwen "重构支付模块API"
# Bug 修复上下文
/memory:prepare "修复登录验证错误"
```
**返回的内容包**:
```json
{
"task_context": "在当前前端基础上开发用户认证功能",
"keywords": ["前端", "用户", "认证", "auth", "login"],
"project_summary": {
"architecture": "TypeScript + React 前端，Vite 构建系统",
"tech_stack": ["React", "TypeScript", "Vite", "TailwindCSS"],
"key_patterns": [
"通过 Context API 进行状态管理",
"使用 Hooks 的函数组件模式",
"API 调用封装在自定义 hooks 中"
]
},
"relevant_files": [
{
"path": "src/components/Auth/LoginForm.tsx",
"relevance": "现有登录表单组件",
"priority": "high"
},
{
"path": "src/contexts/AuthContext.tsx",
"relevance": "认证状态管理上下文",
"priority": "high"
},
{
"path": "CLAUDE.md",
"relevance": "项目开发标准",
"priority": "high"
}
],
"integration_points": [
"必须与现有 AuthContext 集成",
"遵循组件组织模式: src/components/[Feature]/",
"API 调用应使用 src/hooks/useApi.ts 包装器"
],
"constraints": [
"保持向后兼容",
"遵循 TypeScript 严格模式",
"使用现有 UI 组件库"
]
}
```
## 质量检查清单
生成内容包前验证：
- [ ] 有效的 JSON 格式
- [ ] 所有必需字段完整
- [ ] relevant_files 包含最少 3-10 个文件
- [ ] project_summary 准确反映架构
- [ ] integration_points 清晰指定集成路径
- [ ] keywords 准确提取（3-8 个关键词）
- [ ] 内容简洁，避免冗余（< 5KB 总计）
## 记忆持久化
- **会话范围**: 内容包在当前会话有效
- **后续引用**: 所有后续代理/命令都可以访问
- **重新加载需要**: 新会话需要重新执行 `/memory:prepare`
## 相关文档
- [Memory 命令](../claude/memory.md)
- [Review 提示](./review.md)
- [CLI 调用系统](../../features/cli.md)

197
docs/zh/commands/codex/review.md Normal file
View File

@@ -0,0 +1,197 @@
# Review 提示
## 一句话定位
**Review 提示是代码审查的标准化模板** — 多维度代码质量检查，确保代码符合最佳实践。
## 审查维度
| 维度 | 检查项 | 严重程度 |
| --- | --- | --- |
| **正确性** | 逻辑错误、边界条件、类型安全 | Critical |
| **安全性** | 注入漏洞、认证、输入验证 | Critical |
| **性能** | 算法复杂度、N+1 查询、缓存机会 | High |
| **可维护性** | SOLID 原则、代码重复、命名规范 | Medium |
| **文档** | 注释完整性、README 更新 | Low |
## codex-review
**功能**: 使用 Codex CLI 通过 ccw 端点进行交互式代码审查，支持可配置的审查目标、模型和自定义指令。
**语法**:
```
/cli:codex-review [--uncommitted|--base <分支>|--commit <sha>] [--model <模型>] [--title <标题>] [提示]
```
**参数**:
- `--uncommitted`: 审查已暂存、未暂存和未跟踪的更改
- `--base <分支>`: 与基础分支比较更改
- `--commit <sha>`: 审查特定提交引入的更改
- `--model <模型>`: 覆盖默认模型（gpt-5.2, o3, gpt-4.1, o4-mini）
- `--title <标题>`: 审查摘要的可选提交标题
**注意**: 目标标志和提示互斥（见约束部分）
### 审查焦点选择
| 焦点 | 模板 | 关键检查 |
| --- | --- | --- |
| **综合审查** | 通用模板 | 正确性、风格、Bug、文档 |
| **安全焦点** | 安全模板 | 注入、认证、验证、暴露 |
| **性能焦点** | 性能模板 | 复杂度、内存、查询、缓存 |
| **代码质量** | 质量模板 | SOLID、重复、命名、测试 |
### 提示模板
#### 综合审查模板
```
PURPOSE: 综合代码审查以识别问题、改进质量并确保最佳实践；成功 = 可操作的反馈和清晰的优先级
TASK: • 审查代码正确性和逻辑错误 • 检查编码标准和一致性 • 识别潜在 Bug 和边界情况 • 评估文档完整性
MODE: review
CONTEXT: {目标描述} | Memory: 来自 CLAUDE.md 的项目约定
EXPECTED: 结构化审查报告，包含：严重程度级别（Critical/High/Medium/Low）、file:line 引用、具体改进建议、优先级排名
CONSTRAINTS: 关注可操作的反馈
```
#### 安全焦点模板
```
PURPOSE: 安全焦点代码审查以识别漏洞和安全风险；成功 = 所有安全问题记录有修复方案
TASK: • 扫描注入漏洞（SQL、XSS、命令） • 检查认证和授权逻辑 • 评估输入验证和清理 • 识别敏感数据暴露风险
MODE: review
CONTEXT: {目标描述} | Memory: 安全最佳实践、OWASP Top 10
EXPECTED: 安全报告，包含：漏洞分类、适用的 CVE 引用、修复代码片段、风险严重程度矩阵
CONSTRAINTS: 安全优先分析 | 标记所有潜在漏洞
```
#### 性能焦点模板
```
PURPOSE: 性能焦点代码审查以识别瓶颈和优化机会；成功 = 可衡量的改进建议
TASK: • 分析算法复杂度（Big-O） • 识别内存分配问题 • 检查 N+1 查询和阻塞操作 • 评估缓存机会
MODE: review
CONTEXT: {目标描述} | Memory: 性能模式和反模式
EXPECTED: 性能报告，包含：复杂度分析、瓶颈识别、优化建议及预期影响、基准建议
CONSTRAINTS: 性能优化焦点
```
#### 代码质量模板
```
PURPOSE: 代码质量审查以改进可维护性和可读性；成功 = 更清晰、更易维护的代码
TASK: • 评估 SOLID 原则遵守情况 • 识别代码重复和抽象机会 • 审查命名约定和清晰度 • 评估测试覆盖率影响
MODE: review
CONTEXT: {目标描述} | Memory: 项目编码标准
EXPECTED: 质量报告，包含：原则违规、重构建议、命名改进、可维护性评分
CONSTRAINTS: 代码质量和可维护性焦点
```
### 使用示例
#### 直接执行（无交互）
```bash
# 使用默认设置审查未提交的更改
/cli:codex-review --uncommitted
# 与主分支比较
/cli:codex-review --base main
# 审查特定提交
/cli:codex-review --commit abc123
# 使用自定义模型
/cli:codex-review --uncommitted --model o3
# 安全焦点审查
/cli:codex-review --uncommitted security
# 完整选项
/cli:codex-review --base main --model o3 --title "认证功能" security
```
#### 交互模式
```bash
# 启动交互式选择（引导流程）
/cli:codex-review
```
### 约束和验证
**重要**: 目标标志和提示互斥
Codex CLI 有一个约束，目标标志（`--uncommitted`, `--base`, `--commit`）不能与位置 `[PROMPT]` 参数一起使用：
```
error: the argument '--uncommitted' cannot be used with '[PROMPT]'
error: the argument '--base <BRANCH>' cannot be used with '[PROMPT]'
error: the argument '--commit <SHA>' cannot be used with '[PROMPT]'
```
**有效组合**:
| 命令 | 结果 |
| --- | --- |
| `codex review "关注安全"` | ✓ 自定义提示，审查未提交（默认） |
| `codex review --uncommitted` | ✓ 无提示，使用默认审查 |
| `codex review --base main` | ✓ 无提示，使用默认审查 |
| `codex review --commit abc123` | ✓ 无提示，使用默认审查 |
| `codex review --uncommitted "提示"` | ✗ 无效 - 互斥 |
| `codex review --base main "提示"` | ✗ 无效 - 互斥 |
| `codex review --commit abc123 "提示"` | ✗ 无效 - 互斥 |
**有效示例**:
```bash
# ✓ 有效: 仅提示（默认审查未提交）
ccw cli -p "关注安全" --tool codex --mode review
# ✓ 有效: 仅目标标志（无提示）
ccw cli --tool codex --mode review --uncommitted
ccw cli --tool codex --mode review --base main
ccw cli --tool codex --mode review --commit abc123
# ✗ 无效: 目标标志带提示（会失败）
ccw cli -p "审查这个" --tool codex --mode review --uncommitted
```
## 焦点区域映射
| 用户选择 | 提示焦点 | 关键检查 |
| --- | --- | --- |
| 综合审查 | 全面 | 正确性、风格、Bug、文档 |
| 安全焦点 | 安全优先 | 注入、认证、验证、暴露 |
| 性能焦点 | 优化 | 复杂度、内存、查询、缓存 |
| 代码质量 | 可维护性 | SOLID、重复、命名、测试 |
## 错误处理
### 无更改可审查
```
未找到审查目标的更改。建议：
- 对于 --uncommitted: 先进行一些代码更改
- 对于 --base: 确保分支存在并有分歧
- 对于 --commit: 验证提交 SHA 存在
```
### 无效分支
```bash
# 显示可用分支
git branch -a --list | head -20
```
### 无效提交
```bash
# 显示最近提交
git log --oneline -10
```
## 相关文档
- [Prep 提示](./prep.md)
- [CLI 工具命令](../claude/cli.md)
- [代码审查](../../features/)

34
docs/zh/commands/index.md Normal file
View File

@@ -0,0 +1,34 @@
# Commands Overview
## 一句话定位
**Commands 是 Claude_dms3 的命令系统** — 包含 Claude Code Commands 和 Codex Prompts 两大类别，提供从规范到实现到测试到审查的完整命令行工具链。
## 命令分类
| 类别 | 说明 | 路径 |
|------|------|------|
| **Claude Commands** | Claude Code 扩展命令 | `/commands/claude/` |
| **Codex Prompts** | Codex CLI 提示词 | `/commands/codex/` |
## 快速导航
### Claude Commands
- [核心编排](/commands/claude/) - ccw, ccw-coordinator
- [工作流](/commands/claude/workflow) - workflow 系列命令
- [会话管理](/commands/claude/session) - session 系列命令
- [Issue](/commands/claude/issue) - issue 系列命令
- [Memory](/commands/claude/memory) - memory 系列命令
- [CLI](/commands/claude/cli) - cli 系列命令
- [UI 设计](/commands/claude/ui-design) - ui-design 系列命令
### Codex Prompts
- [Prep](/commands/codex/prep) - prep-cycle, prep-plan
- [Review](/commands/codex/review) - review 提示
## 相关文档
- [Skills](/skills/) - 技能系统
- [Features](/features/spec) - 核心功能

394
docs/zh/features/api-settings.md Normal file
View File

@@ -0,0 +1,394 @@
# API 设置
## 一句话定位
**API 设置是统一的多端点配置管理** — 在一个地方配置所有 AI 服务商的 API Keys 和端点，支持多环境切换和密钥加密存储。
## 解决的痛点
| 痛点 | 现状 | API 设置方案 |
| --- | --- | --- |
| **配置分散** | API Keys 散落在各工具配置中 | 统一配置入口 |
| **安全性弱** | 明文存储密钥 | 支持密钥加密 |
| **切换困难** | 切换服务商需要修改多处 | 一个配置文件管理所有 |
| **环境隔离差** | 开发/生产环境混用 | 支持多环境配置 |
## 核心概念速览
| 概念 | 说明 | 位置 |
| --- | --- | --- |
| **API Keys** | 服务商认证密钥 | `settings.json` / `settings.local.json` |
| **Providers** | AI 服务提供商 | OpenAI, Anthropic, Gemini, LiteLLM |
| **Endpoints** | API 服务端点 | URL + 认证配置 |
| **LiteLLM** | 统一代理服务 | 支持 100+ 模型 |
| **本地配置** | 项目级配置 | `.cw/settings.json` |
| **全局配置** | 用户级配置 | `~/.claude/settings.json` |
## 配置层级
```
┌─────────────────────────────────────────────────────────────┐
│ 配置优先级 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. settings.local.json (最高优先级，不提交) │
│ └─ 本地开发配置，覆盖其他配置 │
│ │ │
│ ▼ │
│ 2. .cw/settings.json (项目配置) │
│ └─ 项目特定配置，团队成员共享 │
│ │ │
│ ▼ │
│ 3. ~/.claude/settings.json (全局配置) │
│ └─ 用户默认配置，所有项目共享 │
│ │ │
│ ▼ │
│ 4. 默认值 (最低优先级) │
│ └─ 系统内置默认配置 │
│ │
└─────────────────────────────────────────────────────────────┘
```
## 配置说明
### settings.json 结构
```json
{
"$schema": "https://cdn.jsdelivr.net/gh/your-repo/schema/settings-schema.json",
"providers": {
"openai": {
"apiKey": "sk-...",
"baseURL": "https://api.openai.com/v1",
"models": {
"gpt-4": "gpt-4-turbo",
"gpt-3.5": "gpt-3.5-turbo"
}
},
"anthropic": {
"apiKey": "sk-ant-...",
"baseURL": "https://api.anthropic.com/v1",
"models": {
"claude-opus": "claude-3-opus-20240229",
"claude-sonnet": "claude-3-sonnet-20240229"
}
},
"gemini": {
"apiKey": "AIza...",
"baseURL": "https://generativelanguage.googleapis.com/v1beta",
"models": {
"gemini-pro": "gemini-pro",
"gemini-flash": "gemini-1.5-flash"
}
},
"litellm": {
"apiKey": "sk-...",
"baseURL": "https://litellm.example.com/v1",
"models": {
"qwen-embed": "qwen/qwen3-embedding-sf"
}
}
},
"cw": {
"defaultTool": "gemini",
"promptFormat": "plain",
"smartContext": {
"enabled": false,
"maxFiles": 10
},
"nativeResume": true,
"recursiveQuery": true,
"cache": {
"injectionMode": "auto",
"defaultPrefix": "",
"defaultSuffix": ""
},
"codeIndexMcp": "ace"
},
"hooks": {
"prePrompt": [],
"postResponse": []
}
}
```
### Providers 配置详解
#### OpenAI
```json
{
"providers": {
"openai": {
"apiKey": "sk-proj-...",
"baseURL": "https://api.openai.com/v1",
"organization": "org-...",
"timeout": 60000,
"maxRetries": 3
}
}
}
```
#### Anthropic (Claude)
```json
{
"providers": {
"anthropic": {
"apiKey": "sk-ant-...",
"baseURL": "https://api.anthropic.com/v1",
"version": "2023-06-01",
"timeout": 60000,
"maxRetries": 3
}
}
}
```
#### Gemini (Google)
```json
{
"providers": {
"gemini": {
"apiKey": "AIza...",
"baseURL": "https://generativelanguage.googleapis.com/v1beta",
"timeout": 60000
}
}
}
```
#### LiteLLM (统一代理)
```json
{
"providers": {
"litellm": {
"apiKey": "sk-...",
"baseURL": "https://litellm.example.com/v1",
"dropParams": ["max_tokens"],
"timeout": 120000
}
}
}
```
### CCW 配置详解
```json
{
"cw": {
"defaultTool": "gemini",
"promptFormat": "plain",
"smartContext": {
"enabled": false,
"maxFiles": 10
},
"nativeResume": true,
"recursiveQuery": true,
"cache": {
"injectionMode": "auto",
"defaultPrefix": "",
"defaultSuffix": ""
},
"codeIndexMcp": "ace"
}
}
```
| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `defaultTool` | string | `gemini` | 默认 CLI 工具 |
| `promptFormat` | string | `plain` | Prompt 格式: `plain` / `yaml` / `json` |
| `smartContext.enabled` | boolean | `false` | 智能上下文开关 |
| `smartContext.maxFiles` | number | `10` | 最大文件数量 |
| `nativeResume` | boolean | `true` | 本地会话恢复 |
| `recursiveQuery` | boolean | `true` | 递归查询 |
| `cache.injectionMode` | string | `auto` | 缓存注入模式 |
| `codeIndexMcp` | string | `ace` | 代码索引 MCP: `codexlens` / `ace` / `none` |
### Hooks 配置
```json
{
"hooks": {
"prePrompt": [
{
"type": "command",
"command": "ccw",
"args": ["spec", "load", "--stdin"]
},
{
"type": "mcp",
"server": "cw-tools",
"tool": "core_memory",
"args": {
"operation": "search",
"query": "{{userPrompt}}",
"top_k": 5
}
}
],
"postResponse": [
{
"type": "command",
"command": "ccw",
"args": ["memory", "capture"]
}
]
}
}
```
## 操作步骤
### 初始化配置
```bash
# 在项目中初始化配置文件
ccw config init
# 编辑配置
ccw config edit
```
### 设置 API Keys
**方式 1: 编辑配置文件**
```bash
# 编辑项目配置
code .cw/settings.json
# 编辑全局配置
code ~/.claude/settings.json
```
**方式 2: 使用命令**
```bash
# 设置 OpenAI API Key
ccw config set providers.openai.apiKey "sk-proj-..."
# 设置 Anthropic API Key
ccw config set providers.anthropic.apiKey "sk-ant-..."
# 设置默认工具
ccw config set cw.defaultTool "codex"
```
**方式 3: 环境变量**
```bash
# 设置环境变量（优先级最高）
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AIza..."
```
### 本地配置 (不提交)
```bash
# 创建本地配置（自动添加到 .gitignore）
cat > .cw/settings.local.json << 'EOF'
{
"providers": {
"openai": {
"apiKey": "sk-proj-..."
}
}
}
EOF
```
### 验证配置
```bash
# 验证 API Keys
ccw config verify
# 测试连接
ccw cli -p "Hello" --tool gemini --mode analysis
```
## 配置文件位置
| 配置文件 | 位置 | 用途 | Git |
| --- | --- | --- | --- |
| 项目配置 | `.cw/settings.json` | 项目共享配置 | 提交 |
| 本地配置 | `.cw/settings.local.json` | 个人开发配置 | **不提交** |
| 全局配置 | `~/.claude/settings.json` | 用户默认配置 | 不适用 |
| CLI 工具配置 | `~/.claude/cli-tools.json` | CLI 工具定义 | 不适用 |
| CLI 设置 | `.cw/cli-settings.json` | CLI 行为配置 | 提交 |
## 常见问题
### Q1: API Key 存储安全吗？
A: 建议使用 `settings.local.json` 存储敏感信息：
- `settings.local.json` 自动被 `.gitignore` 排除
- 永不提交到仓库
- 优先级最高，覆盖其他配置
### Q2: 如何切换不同环境？
A: 使用多配置文件：
```bash
# 开发环境
.cw/settings.dev.json
# 生产环境
.cw/settings.prod.json
# 切换环境
cp .cw/settings.dev.json .cw/settings.local.json
```
### Q3: LiteLLM 如何配置？
A: 配置 LiteLLM 端点：
```json
{
"providers": {
"litellm": {
"apiKey": "sk-...",
"baseURL": "https://your-litellm-proxy.com/v1"
}
},
"cw": {
"defaultTool": "litellm"
}
}
```
### Q4: 配置不生效怎么办？
A: 检查优先级和语法：
```bash
# 验证配置语法
ccw config validate
# 查看有效配置
ccw config show
# 查看配置来源
ccw config --debug
```
## 相关功能
- [CLI 调用系统](./cli.md) — 使用 API Keys 执行命令
- [系统设置](./system-settings.md) — cli-tools.json 配置
- [Dashboard 面板](./dashboard.md) — 可视化配置管理
## 进阶阅读
- 配置加载: `ccw/src/config/settings-loader.ts`
- 配置验证: `ccw/src/config/settings-validator.ts`
- CLI 配置: `ccw/src/tools/claude-cli-tools.ts`
- Hooks 执行: `ccw/src/core/hooks/`

308
docs/zh/features/cli.md Normal file
View File

@@ -0,0 +1,308 @@
# CLI 调用系统
## 一句话定位
**CLI 调用系统是统一的多模型 AI 执行框架** — 一个命令调用多个 AI 工具 (Gemini、Qwen、Codex、Claude)，支持 analysis/write/review 模式，自动处理流式输出和错误恢复。
## 解决的痛点
| 痛点 | 现状 | CLI 调用系统方案 |
| --- | --- | --- |
| **多工具分散** | 不同 AI 工具命令格式不一致 | 统一 `ccw cli` 入口 |
| **模型切换困难** | 换模型要查文档记参数 | `--tool` + `--model` 简化切换 |
| **输出格式混乱** | 各工具输出格式不统一 | 统一 JSON Lines 流式输出 |
| **错误恢复缺失** | 工具失败只能手动重试 | 自动 fallback 到备用模型 |
| **上下文管理弱** | 多轮对话上下文不连贯 | Native Resume 自动管理 |
## 核心概念速览
| 概念 | 说明 | 示例 |
| --- | --- | --- |
| **Tool (工具)** | AI 执行端点 | `gemini`, `qwen`, `codex`, `claude`, `opencode` |
| **Mode (模式)** | 执行权限级别 | `analysis` (只读), `write` (读写), `review` (代码审查) |
| **Model (模型)** | 工具使用的具体模型 | `gemini-2.5-flash`, `gpt-5.2`, `coder-model` |
| **Fallback (备用)** | 主模型失败时的自动切换 | secondaryModel 配置 |
| **Resume (恢复)** | 多轮对话上下文管理 | `--resume` 参数 |
| **Session (会话)** | 命令执行的对话上下文 | Native UUID / 消息历史 |
## 使用场景
| 场景 | 推荐工具 | 推荐模式 |
| --- | --- | --- |
| **代码分析** | `gemini` / `qwen` | `analysis` |
| **代码生成** | `codex` / `gemini` | `write` |
| **代码审查** | `codex` | `review` |
| **架构设计** | `gemini` + `codex` 并行 | `analysis` |
| **Bug 调试** | `gemini` (分析) -> `codex` (修复) | `analysis` -> `write` |
| **文档生成** | `qwen` / `gemini` | `write` |
## 操作步骤
### 基础用法
```bash
# 分析代码（默认 analysis 模式）
ccw cli -p "分析 auth 模块的代码结构" --tool gemini
# 生成代码（write 模式）
ccw cli -p "创建一个 JWT 认证中间件" --tool codex --mode write
# 代码审查（review 模式，仅 codex）
ccw cli -p "审查本次提交的代码变更" --tool codex --mode review
# 指定模型
ccw cli -p "分析性能瓶颈" --tool gemini --model "gemini-2.5-pro" --mode analysis
```
### 从文件读取 Prompt
```bash
# 使用 -p @file 语法
ccw cli -p @prompt.txt --tool gemini
# 使用 -f 参数
ccw cli -f prompt.md --tool qwen --mode write
```
### 工作目录控制
```bash
# 在特定目录执行
ccw cli -p "分析当前项目" --tool gemini --cd /path/to/project
# 包含额外目录（用于跨项目分析）
ccw cli -p "分析 shared 和 current 项目的关系" \
--tool gemini \
--cd /path/to/current \
--includeDirs /path/to/shared
```
### 多轮对话 (Resume)
```bash
# 启动新会话
ccw cli -p "设计一个用户认证系统" --tool gemini
# 继续上一轮对话
ccw cli -p "现在实现登录接口" --tool gemini --resume
# 继续指定会话
ccw cli -p "修改登录接口返回 JWT" --tool gemini --resume abc123-def456
# 合并多个会话上下文
ccw cli -p "整合之前的讨论" --tool gemini --resume abc123,def456
```
### 代码审查模式 (Codex 专用)
```bash
# 审查未提交的变更
ccw cli --tool codex --mode review
# 审查与指定分支的差异
ccw cli --tool codex --mode review --base main
# 审查指定提交
ccw cli --tool codex --mode review --commit abc123
# 带标题的审查
ccw cli -p "关注安全性问题" --tool codex --mode review --uncommitted
```
### 使用规则模板
```bash
# 加载预定义模板
ccw cli -p "分析代码安全性" \
--tool gemini \
--mode analysis \
--rule analysis-assess-security-risks
# 查看可用模板
ccw cli --help
```
## 配置说明
### 配置文件结构
**全局配置**: `~/.claude/cli-tools.json`
```json
{
"version": "3.3.0",
"tools": {
"gemini": {
"enabled": true,
"primaryModel": "gemini-2.5-flash",
"secondaryModel": "gemini-2.5-flash",
"availableModels": [
"gemini-3-pro-preview",
"gemini-2.5-pro",
"gemini-2.5-flash",
"gemini-2.0-flash"
],
"tags": ["分析", "Debug"],
"type": "builtin"
},
"codex": {
"enabled": true,
"primaryModel": "gpt-5.2",
"secondaryModel": "gpt-5.2",
"tags": [],
"type": "builtin"
}
}
}
```
**设置文件**: `.cw/cli-settings.json`
```json
{
"$schema": "../cli-tools-schema.json",
"version": "1.0.0",
"defaultTool": "gemini",
"promptFormat": "plain",
"smartContext": {
"enabled": false,
"maxFiles": 10
},
"nativeResume": true,
"recursiveQuery": true,
"cache": {
"injectionMode": "auto",
"defaultPrefix": "",
"defaultSuffix": ""
},
"codeIndexMcp": "ace"
}
```
### 工具类型 (Type)
| 类型 | 说明 | 可用模型 | 支持 |
| --- | --- | --- | --- |
| `builtin` | 内置 CLI 工具 | 完整模型列表 | 分析 + 写入 |
| `cli-wrapper` | Claude CLI 包装 | settings.json 中的模型 | 分析 + 写入 |
| `api-endpoint` | LiteLLM 端点 | 端点配置的模型 | **仅分析** |
### 标签 (Tags) 路由
标签用于工具选择和路由：
| 标签 | 说明 | 适用工具 |
| --- | --- | --- |
| `分析` | 代码分析、架构审查 | gemini, qwen |
| `Debug` | 调试、错误诊断 | gemini, qwen |
| `实现` | 代码生成、功能实现 | codex, gemini |
## 输出格式
### JSON Lines 流式输出
所有工具统一使用 JSON Lines 输出：
```json
{"type": "status", "message": "Connecting to API..."}
{"type": "delta", "content": "基于代码分析"}
{"type": "delta", "content": "，auth 模块包含以下组件"}
{"type": "usage", "prompt_tokens": 1000, "completion_tokens": 500}
{"type": "error", "message": "API timeout, retrying..."}
{"type": "done", "finish_reason": "stop"}
```
### 输出类型
| 类型 | 说明 |
| --- | --- |
| `status` | 状态更新 |
| `delta` | 内容增量 |
| `usage` | Token 使用量 |
| `error` | 错误信息 |
| `done` | 完成标记 |
## Dashboard 中的 CLI 终端
### 终端面板功能
```
┌─────────────────────────────────────────────────────────────┐
│ CLI 终端面板 │
├─────────────────────────────────────────────────────────────┤
│ ┌───────────────────────────────────────────────────────┐ │
│ │ 工具选择: [gemini ▼] 模式: [analysis ▼] 模型: [...] │ │
│ │ 目录: /path/to/project 包含: [shared] │ │
│ └───────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Prompt 输入区 (支持多行) │ │
│ │ [执行] [规则模板] [恢复会话] │ │
│ └───────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ 输出区 (流式显示，支持 Markdown 渲染) │ │
│ │ - 代码高亮 │ │
│ │ - 错误高亮 │ │
│ │ - Token 统计 │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 功能按钮
- **工具选择**: 下拉选择可用工具
- **模式选择**: analysis / write / review
- **模型选择**: 工具可用模型列表
- **规则模板**: 快速加载预定义模板
- **恢复会话**: 选择历史会话继续
## 常见问题
### Q1: analysis 和 write 模式的区别？
A:
- **analysis**: 只读模式，AI 只能读取文件，不能创建/修改/删除
- **write**: 读写模式，AI 可以完整操作文件系统
- **review**: 仅 Codex 支持，Git 感知的代码审查模式
### Q2: 如何选择合适的工具？
A: 基于场景推荐：
- **代码分析/架构设计**: `gemini` (速度快，上下文大)
- **代码生成/Bug 修复**: `codex` (代码能力强)
- **中文任务**: `qwen` (中文优化)
- **长上下文**: `claude` (200K+ tokens)
### Q3: Fallback 机制如何工作？
A: 当主工具失败时：
1. 尝试 `secondaryModel` (同工具)
2. 尝试下一个启用的工具
3. 回退到默认工具
### Q4: 如何调试 CLI 调用？
A: 使用 `-d, --debug` 参数：
```bash
ccw cli -p "分析代码" --tool gemini -d
```
输出详细诊断信息，包括：
- 工具可用性检查
- 命令构建过程
- API 调用详情
- 错误堆栈
## 相关功能
- [Spec 规范系统](./spec.md) — 规范自动注入到 Prompt
- [Memory 记忆系统](./memory.md) — Resume 上下文管理
- [API 设置](./api-settings.md) — API Keys 配置
- [系统设置](./system-settings.md) — cli-tools.json 配置
## 进阶阅读
- CLI 执行核心: `ccw/src/tools/cli-executor-core.ts`
- CLI 工具管理: `ccw/src/tools/claude-cli-tools.ts`
- 命令路由: `ccw/src/commands/cli.ts`
- 前端终端: `ccw/frontend/src/components/terminal-dashboard/`

320
docs/zh/features/codexlens.md Normal file
View File

@@ -0,0 +1,320 @@
# CodexLens 代码索引
## 一句话定位
**CodexLens 是语义代码搜索引擎** — 基于向量嵌入和 LSP 集成，让 AI 理解代码语义而非仅匹配关键词，支持混合检索和实时引用分析。
## 解决的痛点
| 痛点 | 现状 | CodexLens 方案 |
| --- | --- | --- |
| **搜索不精确** | 关键词搜不到语义相关代码 | 向量嵌入语义搜索 |
| **无上下文** | 搜索结果缺少调用上下文 | LSP 引用链分析 |
| **类型信息缺失** | 不知道符号的定义和引用 | 全局符号索引 |
| **跨文件关联弱** | 看不到模块间依赖关系 | 图扩展搜索 |
| **搜索速度慢** | 大项目搜索响应慢 | HNSW 近似最近邻 |
## 核心概念速览
| 概念 | 说明 | 位置/命令 |
| --- | --- | --- |
| **索引 (Index)** | 代码向量化存储 | `~/.codexlens/indexes/{project}/` |
| **混合检索 (Hybrid)** | 向量 + 关键词 + 结构 | `HybridSearchEngine` |
| **级联搜索 (Cascade)** | 多阶段优化搜索 | `cascade_search()` |
| **全局符号索引** | 跨项目符号数据库 | `GlobalSymbolIndex` |
| **LSP 集成** | 编辑器功能增强 | `codexlens lsp` |
| **嵌入器 (Embedder)** | 向量生成引擎 | `qwen3-embedding-sf` via LiteLLM |
## 使用场景
| 场景 | 搜索方式 | 示例 |
| --- | --- | --- |
| **查找函数** | 语义搜索 | "如何验证用户身份" → `authenticate()` |
| **查找用法** | 引用搜索 | 找到 `Token` 类的所有引用 |
| **查找依赖** | 图扩展 | 找到调用 `AuthService` 的所有模块 |
| **代码审查** | 关键词 + 向量 | "安全问题" → 搜索 `auth`, `password`, `encrypt` |
| **重构支持** | 符号索引 | 找到接口的所有实现 |
## 操作步骤
### 初始化索引
```bash
# 初始化项目索引
codexlens init /path/to/project
# 更新索引（增量）
codexlens update /path/to/project
# 清理索引
codexlens clean /path/to/project
```
### 语义搜索
```bash
# 基础语义搜索
codexlens search "如何验证用户身份"
# 指定项目路径
codexlens search --path /path/to/project "authentication flow"
# 设置结果数量
codexlens search --limit 10 "API endpoint design"
# 纯向量搜索（语义最强）
codexlens search --pure-vector "database connection pool"
# 启用 LSP 图扩展
codexlens search --enable-lsp-graph "auth service"
```
### 级联搜索
```bash
# 二进制级联（默认，最快）
codexlens cascade "auth" --strategy binary
# 二进制 + 重排（平衡）
codexlens cascade "auth" --strategy binary_rerank
# 密集 + 重排（质量最高）
codexlens cascade "auth" --strategy dense_rerank
# 四阶段管道（完整）
codexlens cascade "auth" --strategy staged
```
### LSP 服务器
```bash
# 启动 LSP 服务器
codexlens lsp start /path/to/project
# 查看状态
codexlens lsp status
# 停止服务器
codexlens lsp stop
```
### 向量嵌入
```bash
# 生成嵌入
codexlens embeddings generate /path/to/project
# 使用集中式元数据存储（推荐）
codexlens embeddings generate --centralized /path/to/project
# 检查嵌入状态
codexlens embeddings status /path/to/project
# 删除嵌入
codexlens embeddings delete /path/to/project
```
## 配置说明
### 搜索策略对比
| 策略 | 速度 | 质量 | 适用场景 |
| --- | --- | --- | --- |
| `binary` | 最快 | 中等 | 快速查找，代码意图明确 |
| `binary_rerank` | 快 | 高 | 平衡速度和质量（推荐） |
| `dense_rerank` | 中 | 很高 | 复杂查询，语义模糊 |
| `staged` | 慢 | 最高 | 深度分析，需要上下文 |
| `hybrid` | 中 | 高 | 综合检索（RRF 融合） |
### 融合权重配置
```python
weights = {
"vector": 0.5, # 向量相似度权重
"structural": 0.3, # 结构相似度权重
"keyword": 0.2 # 关键词匹配权重
}
```
### 嵌入配置
```python
# codexlens/config.py
embedding_backend = "litellm" # 嵌入后端
embedding_model = "qwen3-embedding-sf" # 嵌入模型
embedding_use_gpu = True # 使用 GPU 加速
chunk_size = 500 # 分块大小
chunk_overlap = 50 # 分块重叠
```
## 索引结构
### 目录结构
```
~/.codexlens/
├── indexes/ # 索引存储
│ └── {project_hash}/
│ └── codex-lens/
│ ├── _index.db # 主索引数据库
│ ├── _vectors_meta.db # 向量元数据（集中式）
│ ├── _vectors/ # HNSW 向量索引
│ │ ├── dir1/
│ │ │ └── hnsw_index.bin
│ │ └── dir2/
│ │ └── hnsw_index.bin
│ └── _symbols.db # 全局符号索引
├── venv/ # Python 虚拟环境
└── config.yaml # 全局配置
```
### 数据库结构
**_index.db** (主索引):
- `chunks`: 代码块表
- `files`: 文件表
- `symbols`: 符号表
- `relationships`: 关系表
**_vectors_meta.db** (向量元数据):
- `chunk_metadata`: 向量块元数据
- `embedding_stats`: 嵌入统计
**_symbols.db** (全局符号):
- `global_symbols`: 跨项目符号
- `symbol_references`: 符号引用
## 搜索流程
### 混合检索流程
```
┌─────────────────────────────────────────────────────────────┐
│ 混合检索流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 查询分析 │
│ └─ 检测意图: KEYWORD / SEMANTIC / MIXED │
│ │
│ 2. 并行检索 │
│ ├─ 精确关键词 (BM25) │
│ ├─ 模糊关键词 (Fuzzy) │
│ └─ 向量相似度 (HNSW ANN) │
│ │
│ 3. 结果融合 (RRF) │
│ └─ Reciprocal Rank Fusion │
│ │
│ 4. (可选) LSP 图扩展 │
│ └─ 扩展引用链 │
│ │
│ 5. 重排序 │
│ └─ Cross-encoder / 规则调整 │
│ │
│ 6. 返回结果 │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 级联搜索流程
```
┌─────────────────────────────────────────────────────────────┐
│ 级联搜索流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Stage 1: 粗检索 (Coarse Retrieval) │
│ ├─ 二进制哈希快速筛选 │
│ └─ 返回 top-k 候选 (k=100) │
│ │ │
│ ▼ │
│ Stage 2: 精排序 (Fine Reranking) │
│ ├─ 密集向量重算相似度 │
│ ├─ (可选) Cross-encoder 重排 │
│ └─ 返回 top-k 结果 (k=20) │
│ │ │
│ ▼ │
│ Stage 3: LSP 扩展 (Graph Expansion, staged 策略) │
│ ├─ 查找符号引用 │
│ ├─ 扩展调用链 │
│ └─ 聚合去重 │
│ │ │
│ ▼ │
│ Stage 4: 聚类 (Clustering, staged 策略) │
│ └─ 按文件/模块聚类结果 │
│ │
└─────────────────────────────────────────────────────────────┘
```
## LSP 集成
### 支持的 LSP 功能
| 功能 | 说明 | 命令 |
| --- | --- | --- |
| **跳转到定义** | 跳转到符号定义 | `textDocument/definition` |
| **查找引用** | 查找所有引用 | `textDocument/references` |
| **自动完成** | 代码补全 | `textDocument/completion` |
| **悬停提示** | 显示类型和文档 | `textDocument/hover` |
| **工作区符号** | 搜索所有符号 | `workspace/symbol` |
### 启动 LSP 服务器
```bash
# CLI 启动
codexlens lsp start /path/to/project
# VS Code 集成
# 在 settings.json 中配置:
{
"codexlens.enabled": true,
"codexlens.lsp.port": 4389
}
```
## 常见问题
### Q1: 索引速度慢怎么办？
A: 优化策略：
- 使用 GPU 加速 (`embedding_use_gpu = True`)
- 减少分块大小 (`chunk_size = 300`)
- 限制索引范围（排除 `node_modules/`, `dist/` 等）
### Q2: 搜索结果不准确？
A: 调整搜索策略：
- 使用 `dense_rerank` 或 `staged` 策略
- 调整融合权重 (`--vector-weight`, `--structural-weight`)
- 使用纯向量搜索 (`--pure-vector`)
### Q3: LSP 功能不工作？
A: 检查：
```bash
# 检查 LSP 状态
codexlens lsp status
# 查看日志
codexlens lsp start --verbose /path/to/project
```
### Q4: 内存占用过高？
A: 优化配置：
- 减少并发索引数
- 使用增量更新 (`codexlens update`)
- 清理旧索引 (`codexlens clean`)
## 相关功能
- [Memory 记忆系统](./memory.md) — 向量嵌入共享
- [CLI 调用系统](./cli.md) — ccw search 命令
- [Dashboard 面板](./dashboard.md) — 搜索可视化
## 进阶阅读
- 搜索引擎: `codex-lens/src/codexlens/search/`
- 混合检索: `codex-lens/src/codexlens/search/hybrid_search.py`
- 级联搜索: `codex-lens/src/codexlens/search/chain_search.py`
- LSP 服务器: `codex-lens/src/codexlens/lsp/server.py`
- 嵌入器: `codex-lens/src/codexlens/semantic/`

338
docs/zh/features/dashboard.md Normal file
View File

@@ -0,0 +1,338 @@
# Dashboard 面板
## 一句话定位
**Dashboard 是 VS Code 内置的可视化管理中心** — 一个 Webview 界面统一管理 Specs、Skills、Memory、会话历史和 CLI 终端，无需离开编辑器。
## 解决的痛点
| 痛点 | 现状 | Dashboard 方案 |
| --- | --- | --- |
| **分散管理** | Specs、Skills、Memory 各自独立管理 | 统一界面集中管理 |
| **命令行操作** | 需要记住命令和参数 | 点击式 GUI 操作 |
| **状态不可见** | 后台任务执行状态不透明 | 实时状态展示 |
| **上下文切换** | 在终端和编辑器间频繁切换 | 集成在 VS Code 侧边栏 |
## 核心概念速览
| 概念 | 说明 | 入口 |
| --- | --- | --- |
| **首页** | 项目概览、快速入口 | Dashboard 主页 |
| **CLAUDE.md Manager** | 项目指令管理 | Specs 页面 |
| **Skills Manager** | 技能市场和管理 | Skills 页面 |
| **Core Memory 视图** | 记忆浏览和搜索 | Memory 页面 |
| **CLI 终端** | 统一命令执行 | Terminal 面板 |
| **会话历史** | 历史会话浏览 | Session 侧边栏 |
| **Graph Explorer** | 项目依赖可视化 | Graph 面板 |
## 使用场景
| 场景 | 使用页面 |
| --- | --- |
| **管理项目规范** | CLAUDE.md Manager |
| **安装/管理技能** | Skills Manager (Skill Hub) |
| **查看项目记忆** | Core Memory 视图 |
| **执行 CLI 命令** | CLI 终端 |
| **浏览会话历史** | Session 侧边栏 |
| **查看项目结构** | Graph Explorer |
## 操作步骤
### 启动 Dashboard
```bash
# 启动 Dashboard（默认端口 3456）
ccw view
# 指定端口
ccw view --port 8080
# 指定主机
ccw view --host 0.0.0.0
# 不自动打开浏览器
ccw view --no-browser
```
### Dashboard 布局
```
┌─────────────────────────────────────────────────────────────────┐
│ Dashboard 主界面 │
├───────────────────┬─────────────────────────────────────────────┤
│ │ │
│ 侧边栏导航 │ 主内容区 │
│ ┌─────────────┐ │ ┌─────────────────────────────────────┐ │
│ │ 首页 │ │ │ │ │
│ │ Specs │ │ │ 动态内容区域 │ │
│ │ Skills │ │ │ (根据导航变化) │ │
│ │ Memory │ │ │ │ │
│ │ Terminal │ │ │ │ │
│ │ Settings │ │ │ │ │
│ └─────────────┘ │ └─────────────────────────────────────┘ │
│ │ │
├───────────────────┴─────────────────────────────────────────────┤
│ 浮动面板 (可切换) │
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │
│ │ Queue 面板 │ │ Inspector 面板 │ │ File 侧边栏 │ │
│ │ (任务队列) │ │ (对象检查) │ │ │ │
│ └─────────────────┘ └─────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### CLAUDE.md Manager (Specs 页面)
管理项目规范文档 (`.cw/specs/` 和 `~/.cw/personal/`)
**功能**:
- 浏览所有规范文件
- 按维度/类别/关键词筛选
- 编辑规范内容
- 创建新规范
- 重建索引缓存
**操作**:
```
1. 导航到 Specs 页面
2. 选择维度筛选器: all / specs / personal
3. (可选) 按类别筛选: general / exploration / planning / execution
4. (可选) 搜索框输入关键词
5. 点击规范卡片查看详情
6. 编辑内容并保存
7. 点击 "重建索引" 更新缓存
```
### Skills Manager (Skills 页面)
统一管理 Claude Skills 和 Codex Skills
**功能**:
- 浏览已安装技能
- 技能市场 (Skill Hub)
- 安装/卸载技能
- 启用/禁用技能
- 技能详情查看
**Skill Hub**:
- 远程技能库
- 本地技能发现
- 一键安装
- 版本管理
**操作**:
```
1. 导航到 Skills 页面
2. 切换 CLI 模式: Claude / Codex
3. 筛选: 类别 / 来源 / 状态
4. 点击 "Skill Hub" 浏览市场
5. 选择技能点击 "安装"
6. 使用开关启用/禁用技能
7. 点击技能卡片查看详情
```
### Core Memory 视图 (Memory 页面)
浏览和搜索项目记忆
**功能**:
- 记忆列表分页浏览
- 标签筛选
- 语义搜索
- 查看记忆详情
- 生成 AI 摘要
- 管理标签
**操作**:
```
1. 导航到 Memory 页面
2. (可选) 输入标签筛选
3. (可选) 输入搜索查询
4. 点击记忆卡片查看详情
5. 点击 "生成摘要" 调用 AI
6. 添加/删除标签
7. 查看提取任务状态
```
### CLI 终端 (Terminal 页面)
统一的 CLI 执行界面
**功能**:
- 工具选择下拉
- 模式选择 (analysis/write/review)
- 模型选择
- 工作目录配置
- Prompt 输入 (支持多行)
- 流式输出显示
- 规则模板快速加载
- 会话恢复管理
**操作**:
```
1. 导航到 Terminal 页面
2. 选择工具: gemini / qwen / codex / claude
3. 选择模式: analysis / write
4. (可选) 选择具体模型
5. (可选) 设置工作目录
6. 输入 Prompt (支持多行)
7. 点击 "执行" 或按 Ctrl+Enter
8. 查看流式输出
9. (可选) 使用规则模板
10. (可选) 恢复历史会话
```
### 浮动面板
#### Queue 面板
显示任务队列状态:
- 当前执行任务
- 等待中任务
- 已完成任务
- 失败任务
#### Inspector 面板
检查对象详情:
- 文件元数据
- 符号信息
- 依赖关系
#### File 侧边栏
项目文件浏览:
- 文件树
- 快速打开
- 文件搜索
### 会话侧边栏
浏览历史会话：
```
┌─────────────────────────────┐
│ Sessions [清空历史] │
├─────────────────────────────┤
│ ┌───────────────────────┐ │
│ │ 今天 │ │
│ │ • 会话 1 │ │
│ │ • 会话 2 │ │
│ │ │ │
│ │ 昨天 │ │
│ │ • 会话 3 │ │
│ │ • 会话 4 │ │
│ └───────────────────────┘ │
└─────────────────────────────┘
```
### Graph Explorer
可视化项目依赖：
```
┌─────────────────────────────────────────┐
│ Graph Explorer │
├─────────────────────────────────────────┤
│ │
│ ┌─────┐ ┌─────┐ │
│ │ API │ ───> │ Auth│ │
│ └─────┘ └─────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────┐ ┌─────┐ │
│ │ DB │ <────│User │ │
│ └─────┘ └─────┘ │
│ │
└─────────────────────────────────────────┘
```
**功能**:
- 模块依赖图
- 调用关系图
- 缩放/平移
- 节点搜索
## 配置说明
### Dashboard 配置 (settings.json)
```json
{
"dashboard": {
"port": 3456,
"host": "127.0.0.1",
"openBrowser": true,
"immersiveMode": false
},
"panels": {
"queue": {
"enabled": true,
"width": 400
},
"inspector": {
"enabled": true,
"width": 360
}
}
}
```
### 功能开关
```typescript
const featureFlags = {
dashboardQueuePanelEnabled: boolean, // Queue 面板
dashboardInspectorEnabled: boolean, // Inspector 面板
dashboardGraphEnabled: boolean, // Graph Explorer
};
```
## 常见问题
### Q1: Dashboard 无法启动？
A: 检查端口是否被占用：
```bash
# 检查端口占用
lsof -i :3456 # macOS/Linux
netstat -ano | findstr :3456 # Windows
# 使用其他端口
ccw view --port 8080
```
### Q2: Dashboard 内容不刷新？
A: Dashboard 使用缓存，手动刷新：
- 点击页面刷新按钮
- 或使用 `ccw view --restart`
### Q3: 如何在全屏模式下使用？
A: 使用沉浸式模式：
- 点击工具栏的全屏按钮
- 或按 `F11` 键
### Q4: Skills Hub 无法连接？
A: 检查网络连接和 Hub 地址：
```json
{
"skillHub": {
"url": "https://skill-hub.example.com",
"timeout": 10000
}
}
```
## 相关功能
- [Spec 规范系统](./spec.md) — CLAUDE.md Manager 管理的内容
- [Memory 记忆系统](./memory.md) — Core Memory 视图的数据
- [CLI 调用系统](./cli.md) — Terminal 面板的功能
## 进阶阅读
- Dashboard 主页: `ccw/frontend/src/pages/TerminalDashboardPage.tsx`
- Specs 页面: `ccw/frontend/src/pages/SpecsSettingsPage.tsx`
- Skills 页面: `ccw/frontend/src/pages/SkillsManagerPage.tsx`
- 路由配置: `ccw/src/core/routes/`

289
docs/zh/features/memory.md Normal file
View File

@@ -0,0 +1,289 @@
# Memory 记忆系统
## 一句话定位
**Memory 记忆系统是跨会话知识持久化引擎** — 让 AI 记住项目架构、编码规范和过往决策，新会话自动继承上下文，避免重复解释项目背景。
## 解决的痛点
| 痛点 | 现状 | Memory 记忆系统方案 |
| --- | --- | --- |
| **AI 不理解项目** | 新会话要重新解释项目背景 | Memory 持久化项目上下文 |
| **决策丢失** | AI 的架构决策下次会话就忘了 | Memory 记录架构决策和设计模式 |
| **规范重复** | 每次都要强调编码规范 | CLAUDE.md 自动加载到 Memory |
| **搜索困难** | 找不到之前的讨论内容 | 向量搜索语义相关记忆 |
## 核心概念速览
| 概念 | 说明 | 命令/位置 |
| --- | --- | --- |
| **Core Memory** | 核心记忆，存储项目级知识 | `ccw core-memory` |
| **Memory ID** | 记忆唯一标识，格式 `CMEM-YYYYMMDD-HHMMSS` | 自动生成 |
| **Memory Cluster** | 记忆集群，相关记忆分组 | `.cw/memory/clusters/` |
| **Embedding** | 向量嵌入，支持语义搜索 | `core_memory(operation="embed")` |
| **Stage1 Output** | 会话原始输出，用于提取 | Memory V2 管道 |
| **Extraction Job** | 记忆提取任务，后台异步执行 | `ccw core-memory jobs` |
## 使用场景
| 场景 | 说明 | 操作 |
| --- | --- | --- |
| **架构决策** | 记录重要技术决策 | `core_memory(operation="import", text="决策内容")` |
| **编码规范** | 持久化 CLAUDE.md | 自动导入 |
| **设计模式** | 记录项目使用的设计模式 | 手动添加带标签的记忆 |
| **跨会话上下文** | 新会话加载项目记忆 | 自动加载（通过 hook） |
## 操作步骤
### Memory V2 管道
Memory V2 采用两阶段提取管道：
```
┌─────────────────────────────────────────────────────────────┐
│ Memory V2 提取管道 │
├─────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: 会话结束后提取 (Rollout Extraction) │
│ ┌─────────────┐ ┌──────────────┐ ┌────────────────┐ │
│ │ 会话结束 │ -> │ 压缩 Transcript│ -> │ Stage1 Output │ │
│ └─────────────┘ └──────────────┘ └────────────────┘ │
│ │ │
│ ▼ │
│ 提取任务调度器 │
│ │ │
│ Phase 2: 后台合并 (Consolidation) │
│ ┌───────────────┐ ┌──────────────┐ ┌─────────────┐│
│ │ 多个 Stage1 │ -> │ LLM 合并提取 │ -> │ Core Memory ││
│ └───────────────┘ └──────────────┘ └─────────────┘│
│ │
└─────────────────────────────────────────────────────────────┘
```
### 基础 Memory 操作
```bash
# 列出所有记忆
ccw core-memory list
# 列出特定标签的记忆
ccw core-memory list --tags "auth,api"
# 导入新记忆
ccw core-memory import --text "项目使用 JWT 进行身份验证，Token 有效期 24 小时"
# 导出记忆内容
ccw core-memory export --id CMEM-20240215-143000
# 生成 AI 摘要
ccw core-memory summary --id CMEM-20240215-143000 --tool gemini
# 搜索记忆（语义搜索）
ccw core-memory search --query "身份验证" --top-k 5
# 删除记忆
ccw core-memory delete --id CMEM-20240215-143000
```
### Memory 管理
```bash
# 查看提取任务状态
ccw core-memory jobs
# 查看特定类型的任务
ccw core-memory jobs --type phase1_extraction
# 按状态筛选
ccw core-memory jobs --status pending
# 手动触发提取
ccw core-memory extract --max-sessions 10
# 手动触发合并
ccw core-memory consolidate
```
### MCP 工具调用
在 Claude Code 中使用 MCP 工具：
```typescript
// 列出记忆
core_memory(operation="list")
// 带标签筛选
core_memory(operation="list", tags=["auth", "security"])
// 导入记忆
core_memory(operation="import", text="重要内容")
// 导出记忆
core_memory(operation="export", id="CMEM-xxx")
// 生成摘要
core_memory(operation="summary", id="CMEM-xxx", tool="gemini")
// 生成嵌入
core_memory(operation="embed", source_id="CMEM-xxx")
// 语义搜索
core_memory(operation="search", query="authentication", top_k=10, min_score=0.3)
// 检查嵌入状态
core_memory(operation="embed_status")
// 触发提取
core_memory(operation="extract", max_sessions=10)
// 检查提取状态
core_memory(operation="extract_status")
// 触发合并
core_memory(operation="consolidate")
// 检查合并状态
core_memory(operation="consolidate_status")
// 列出任务
core_memory(operation="jobs", kind="extraction", status_filter="pending")
```
## 配置说明
### Memory V2 配置 (memory-v2-config.ts)
| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `MAX_RAW_MEMORY_CHARS` | 300,000 | Stage1 原始记忆最大字符数 |
| `MAX_SUMMARY_CHARS` | 1,200 | 摘要最大字符数 |
| `MAX_ROLLOUT_BYTES_FOR_PROMPT` | 1,000,000 | 发送给 LLM 的最大字节数 |
| `MAX_RAW_MEMORIES_FOR_GLOBAL` | 64 | 合并时包含的原始记忆数量 |
### 存储路径
```
.cw/
├── memory/
│ ├── core-memory.db # SQLite 数据库
│ ├── clusters/ # 记忆集群
│ └── embeddings/ # 向量嵌入
```
### Memory 数据结构
```typescript
interface CoreMemory {
id: string; // CMEM-YYYYMMDD-HHMMSS
content: string; // 记忆内容
summary: string | null; // AI 生成摘要
raw_output?: string; // 原始输出（V2）
created_at: string; // ISO timestamp
updated_at: string; // ISO timestamp
archived: boolean; // 是否归档
metadata?: string; // JSON 元数据
tags?: string[]; // 标签数组
}
```
## Dashboard 中的 Memory 管理
### Core Memory 视图
Dashboard 提供 Memory 可视化管理界面：
```
┌─────────────────────────────────────────────────────────────┐
│ Core Memory 视图 │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 记忆列表 │ │ 记忆详情/编辑 │ │
│ │ - 搜索 │ │ - 内容显示 │ │
│ │ - 标签筛选 │ │ - 标签管理 │ │
│ │ - 排序 │ │ - 摘要生成 │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 提取任务状态 │ │
│ │ - Pending/Running/Done/Error 计数 │ │
│ │ - 任务列表 │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### 操作功能
- **浏览记忆**: 分页列表，支持搜索和标签筛选
- **编辑记忆**: 直接修改内容，自动更新时间戳
- **生成摘要**: 一键调用 AI 生成摘要
- **管理标签**: 添加/删除标签
- **删除记忆**: 软删除（归档）或硬删除
## 常见问题
### Q1: Memory 和 CLAUDE.md 的区别？
A:
- **CLAUDE.md**: 静态配置文件，手动编写，每次会话完整加载
- **Memory**: 动态数据库，自动/手动积累，按需搜索和加载
### Q2: 如何让 AI 在新会话中自动加载 Memory？
A: 在 `settings.json` 中配置 hook：
```json
{
"hooks": {
"prePrompt": [
{
"type": "mcp",
"server": "cw-tools",
"tool": "core_memory",
"args": {
"operation": "search",
"query": "{{userPrompt}}",
"top_k": 5
}
}
]
}
}
```
### Q3: Memory V2 管道何时触发？
A: 管道自动触发时机：
- **Phase 1**: 会话结束时自动提取（如果启用）
- **Phase 2**: 当 Stage1 outputs 数量达到阈值时自动合并
手动触发：
```bash
ccw core-memory extract
ccw core-memory consolidate
```
### Q4: 嵌入搜索需要什么条件？
A: 需要安装 CodexLens Python 环境：
```bash
# 检查嵌入状态
ccw core-memory embed-status
# 生成嵌入
ccw core-memory embed --source-id CMEM-xxx
```
## 相关功能
- [Spec 规范系统](./spec.md) — 规范自动注入
- [CLI 调用系统](./cli.md) — ccw core-memory 命令
- [CodexLens 代码索引](./codexlens.md) — 向量嵌入引擎
## 进阶阅读
- Memory 存储实现: `ccw/src/core/core-memory-store.ts`
- 提取管道: `ccw/src/core/memory-extraction-pipeline.ts`
- 任务调度器: `ccw/src/core/memory-job-scheduler.ts`
- 嵌入桥接: `ccw/src/core/memory-embedder-bridge.ts`
- MCP 工具: `ccw/src/tools/core-memory.ts`

283
docs/zh/features/spec.md Normal file
View File

@@ -0,0 +1,283 @@
# Spec 规范系统
## 一句话定位
**Spec 规范系统是项目约束的自动注入机制** — 通过 YAML 前置元数据定义的规范文档，在 AI 会话开始时自动加载相关约束，让 AI 遵守项目编码规范和架构要求。
## 解决的痛点
| 痛点 | 现状 | Spec 规范系统方案 |
| --- | --- | --- |
| **AI 不遵守规范** | CLAUDE.md 写了规范，AI 经常忽略 | 规范按 `readMode: required` 自动强制加载 |
| **规范难以维护** | 所有约束堆在一个文件里 | 按维度 (specs/personal) 和类别 (exploration/planning/execution) 分离 |
| **规范加载不智能** | 每次会话都要手动复制粘贴 | 根据用户 Prompt 关键词自动匹配相关规范 |
| **规范粒度太粗** | 只能全项目或全无 | 支持分类 (general/exploration/planning/execution) 按需加载 |
## 核心概念速览
| 概念 | 说明 | 位置/命令 |
| --- | --- | --- |
| **Dimension (维度)** | 规范所属的分类空间 | `specs` (项目规范) / `personal` (个人偏好) |
| **Category (类别)** | 工作流阶段分类 | `general` / `exploration` / `planning` / `execution` |
| **readMode (读取模式)** | 加载策略 | `required` (强制加载) / `optional` (关键词匹配时加载) |
| **priority (优先级)** | 规范展示顺序 | `critical` / `high` / `medium` / `low` |
| **keywords (关键词)** | 用于自动匹配的标签 | YAML 数组，与用户 Prompt 关键词取交集 |
| **Spec Index** | 规范索引缓存 | `.ccw/.spec-index/{dimension}.index.json` |
## Spec 文件结构
### 规范文件模板
```markdown
---
title: "文档标题"
dimension: "specs" # 规范维度: specs | personal
category: "general" # 工作流类别: general | exploration | planning | execution
keywords:
- keyword1
- keyword2
readMode: "required" # 读取模式: required | optional
priority: "high" # 优先级: critical | high | medium | low
---
# 规范内容（Markdown 正文）
这里是规范的具体内容...
```
### 规范目录结构
```
.cw/
├── specs/ # 项目规范（维度：specs）
│ ├── coding-conventions.md
│ ├── architecture-constraints.md
│ └── api-design-guidelines.md
├── personal/ # 个人偏好（维度：personal）
│ ├── coding-style.md
│ └── review-preferences.md
└── .spec-index/ # 索引缓存（自动生成）
├── specs.index.json
└── personal.index.json
```
## 使用场景
| 场景 | 说明 | 配置示例 |
| --- | --- | --- |
| **编码规范** | 强制 AI 遵守项目代码风格 | `dimension: specs`, `readMode: required` |
| **架构约束** | 定义模块边界和依赖规则 | `dimension: specs`, `category: planning` |
| **API 设计** | 规范 API 设计原则 | `dimension: specs`, `keywords: [api, rest, graphql]` |
| **个人偏好** | 个人的代码风格偏好 | `dimension: personal`, `readMode: optional` |
## 操作步骤
### 初始化 Spec 系统
```bash
# 在项目根目录初始化规范系统
ccw spec init
```
**输出**:
```
Initializing spec system...
Directories created:
+ .cw/specs/
+ .cw/personal/
+ .cw/.spec-index/
Seed files created:
+ .cw/specs/coding-conventions.md
+ .cw/specs/architecture-constraints.md
```
### 创建规范文件
```bash
# 手动创建规范文件
cat > .cw/specs/api-design.md << 'EOF'
---
title: "API Design Guidelines"
dimension: "specs"
category: "planning"
keywords:
- api
- rest
- endpoint
- http
readMode: "optional"
priority: "high"
---
# API 设计规范
## RESTful 约定
- 使用名词表示资源
- 使用 HTTP 方法表示操作
- 统一错误响应格式
## 命名约定
- 路径使用 kebab-case
- 查询参数使用 camelCase
EOF
```
### 加载规范
**CLI 模式**（查看规范内容）:
```bash
# 列出所有规范
ccw spec list
# 按维度列出
ccw spec list --dimension specs
# 加载特定类别的规范
ccw spec load --category planning
# 按关键词加载规范
ccw spec load --keywords "api rest"
# 重建索引缓存
ccw spec rebuild
```
**Hook 模式**（自动注入到 AI 上下文）:
在 `settings.json` 中配置 hook:
```json
{
"hooks": {
"prePrompt": [
{
"type": "command",
"command": "ccw",
"args": ["spec", "load", "--stdin"]
}
]
}
}
```
## 配置说明
### YAML 前置元数据字段
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `title` | string | 是 | 规范文档标题 |
| `dimension` | string | 是 | 维度：`specs` 或 `personal` |
| `category` | string | 否 | 类别：`general` / `exploration` / `planning` / `execution` |
| `keywords` | string[] | 是 | 关键词列表，用于自动匹配 |
| `readMode` | string | 是 | `required`（强制）或 `optional`（可选） |
| `priority` | string | 否 | 优先级：`critical` / `high` / `medium` / `low` |
### 类别 (category) 说明
| 类别 | 加载时机 | 适用场景 |
| --- | --- | --- |
| `general` | 始终加载（当 readMode=required） | 通用规范，如编码风格、命名约定 |
| `exploration` | 探索阶段 | 架构探索、技术选型指南 |
| `planning` | 规划阶段 | 设计模式、模块划分原则 |
| `execution` | 执行阶段 | 具体实现规范、测试要求 |
## 规范加载机制
### 加载流程
```
┌─────────────────────────────────────────────────────────────┐
│ Spec 加载流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 用户输入 Prompt │
│ │ │
│ ▼ │
│ 2. 关键词提取 (extractKeywords) │
│ │ │
│ ▼ │
│ 3. 读取索引缓存 (getDimensionIndex) │
│ │ │
│ ▼ │
│ 4. 过滤规范 (filterSpecs) │
│ ├─ required: 全部加载 │
│ └─ optional: 关键词匹配时加载 │
│ │ │
│ ▼ │
│ 5. 加载内容 (loadSpecContent) │
│ │ │
│ ▼ │
│ 6. 按优先级合并 (mergeByPriority) │
│ │ │
│ ▼ │
│ 7. 格式化输出 (CLI markdown / Hook JSON) │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 关键词匹配规则
- **英文关键词**: 转小写，移除停用词，取长度 >= 3 的词
- **中文关键词**: 提取连续 CJK 字符序列
- **匹配逻辑**: 用户关键词与规范关键词取交集，有交集即匹配
### 优先级合并顺序
```
critical > high > medium > low
```
同优先级内按 `dimension` 优先级：`specs` > `personal`
## 常见问题
### Q1: 规范文件修改后没有生效？
A: 规范内容通过索引缓存加载，修改后需要重建索引：
```bash
ccw spec rebuild
```
### Q2: 如何调试规范加载过程？
A: 使用 `--debug` 参数查看加载详情：
```bash
ccw spec load --keywords "auth" --debug
```
输出示例：
```
[specs] scanned=5 required=2 matched=1
Loaded: coding-conventions (required)
Loaded: auth-security (matched: auth)
Total: scanned=10 loaded=3
```
### Q3: required 和 optional 的区别？
A:
- `required`: 无论用户输入什么，都会加载（适用于通用规范）
- `optional`: 只有当用户 Prompt 包含匹配关键词时才加载（适用于特定场景规范）
### Q4: 个人偏好和项目规范冲突怎么办？
A: 优先级顺序为 `specs` > `personal`。项目规范会覆盖个人偏好。
## 相关功能
- [Memory 记忆系统](./memory.md) — 跨会话知识持久化
- [CLI 调用系统](./cli.md) — ccw spec 命令
- [系统设置](./system-settings.md) — Hook 配置
## 进阶阅读
- 规范索引实现: `ccw/src/tools/spec-index-builder.ts`
- 规范加载器: `ccw/src/tools/spec-loader.ts`
- 关键词提取: `ccw/src/tools/spec-keyword-extractor.ts`
- Dashboard Spec 管理: `ccw/frontend/src/pages/SpecsSettingsPage.tsx`

475
docs/zh/features/system-settings.md Normal file
View File

@@ -0,0 +1,475 @@
# 系统设置
## 一句话定位
**系统设置是 CCW 的全局配置中心** — 管理 CLI 工具定义、Hooks、代理、Agent 和行为偏好，控制整个 CCW 工作流的运行方式。
## 解决的痛点
| 痛点 | 现状 | 系统设置方案 |
| --- | --- | --- |
| **配置分散** | 配置散落多个文件 | 集中在 `~/.claude/` 目录 |
| **工具定义复杂** | 添加新工具需要修改代码 | JSON 配置定义工具 |
| **自动化困难** | 手动执行重复任务 | Hooks 自动化 |
| **行为不一致** | 不同项目行为差异大 | 全局配置统一行为 |
## 核心概念速览
| 概念 | 说明 | 位置 |
| --- | --- | --- |
| **cli-tools.json** | CLI 工具定义 | `~/.claude/cli-tools.json` |
| **settings.json** | 项目设置 | `.cw/settings.json` |
| **CLAUDE.md** | 项目指令 | `.cw/CLAUDE.md` |
| **Hooks** | 自动化钩子 | `settings.json` hooks |
| **Agents** | 智能代理配置 | `~/.claude/agents/` |
| **Proxy** | 网络代理配置 | `settings.json` proxy |
## 配置文件总览
```
~/.claude/ # 全局配置目录
├── cli-tools.json # CLI 工具定义
├── settings.json # 默认设置
├── agents/ # Agent 配置
│ ├── cli-execution-agent.md
│ └── ...
└── workflows/ # 工作流配置
└── ...
.cw/ # 项目配置目录
├── settings.json # 项目设置
├── settings.local.json # 本地设置（不提交）
├── CLAUDE.md # 项目指令
├── cli-settings.json # CLI 行为配置
├── specs/ # 项目规范
│ ├── coding-conventions.md
│ └── ...
└── personal/ # 个人偏好
└── ...
```
## 配置详解
### cli-tools.json (CLI 工具定义)
定义可用的 AI 工具及其配置：
```json
{
"version": "3.3.0",
"tools": {
"gemini": {
"enabled": true,
"primaryModel": "gemini-2.5-flash",
"secondaryModel": "gemini-2.5-flash",
"availableModels": [
"gemini-3-pro-preview",
"gemini-2.5-pro",
"gemini-2.5-flash",
"gemini-2.0-flash"
],
"tags": ["分析", "Debug"],
"type": "builtin"
},
"qwen": {
"enabled": true,
"primaryModel": "coder-model",
"secondaryModel": "coder-model",
"tags": [],
"type": "builtin"
},
"codex": {
"enabled": true,
"primaryModel": "gpt-5.2",
"secondaryModel": "gpt-5.2",
"tags": [],
"type": "builtin"
},
"claude": {
"enabled": true,
"primaryModel": "sonnet",
"secondaryModel": "haiku",
"tags": [],
"type": "builtin",
"settingsFile": "D:\\settings-glm5.json"
},
"opencode": {
"enabled": true,
"primaryModel": "opencode/glm-4.7-free",
"secondaryModel": "opencode/glm-4.7-free",
"tags": [],
"type": "builtin"
}
}
}
```
#### 字段说明
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `version` | string | 配置文件版本 |
| `tools` | object | 工具定义集合 |
| `enabled` | boolean | 是否启用 |
| `primaryModel` | string | 主模型 |
| `secondaryModel` | string | 备用模型 |
| `availableModels` | string[] | 可用模型列表 |
| `tags` | string[] | 能力标签 |
| `type` | string | 工具类型: `builtin` / `cli-wrapper` / `api-endpoint` |
### cli-settings.json (CLI 行为配置)
```json
{
"$schema": "../cli-tools-schema.json",
"version": "1.0.0",
"defaultTool": "gemini",
"promptFormat": "plain",
"smartContext": {
"enabled": false,
"maxFiles": 10
},
"nativeResume": true,
"recursiveQuery": true,
"cache": {
"injectionMode": "auto",
"defaultPrefix": "",
"defaultSuffix": ""
},
"codeIndexMcp": "ace"
}
```
#### 字段说明
| 字段 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `defaultTool` | string | `gemini` | 默认 CLI 工具 |
| `promptFormat` | string | `plain` | Prompt 格式 |
| `smartContext.enabled` | boolean | `false` | 智能上下文开关 |
| `smartContext.maxFiles` | number | `10` | 最大文件数 |
| `nativeResume` | boolean | `true` | 本地会话恢复 |
| `recursiveQuery` | boolean | `true` | 递归查询 |
| `cache.injectionMode` | string | `auto` | 缓存注入模式 |
| `codeIndexMcp` | string | `ace` | 代码索引 MCP |
### CLAUDE.md (项目指令)
全局项目指令：
```markdown
# Claude Instructions
## Coding Philosophy
- **Pursue good taste** - Eliminate edge cases
- **Embrace extreme simplicity**
- **Be pragmatic** - Solve real problems
## CLI Endpoints
- **CLI Tools Usage**: @~/.ccw/workflows/cli-tools-usage.md
- **CLI Endpoints Config**: @~/.claude/cli-tools.json
## Tool Execution
- **Always use `run_in_background: false`** for Task tool agent calls
- **Default: Use Bash `run_in_background: true`** for CLI calls
## Code Diagnostics
- **Prefer `mcp__ide__getDiagnostics`** for code error checking
```
### CLAUDE.md 结构
```markdown
# 全局指令 (~/)
├── Coding Philosophy # 编码哲学
├── CLI Endpoints # CLI 配置
├── Tool Execution # 工具执行规则
├── Code Diagnostics # 诊断规则
└── ...
# 项目指令 (.cw/)
├── Project Overview # 项目概述
├── Architecture # 架构说明
├── Conventions # 编码约定
└── Module Specifics # 模块特定规则
```
## Hooks 配置
### Hook 类型
| 类型 | 触发时机 | 用途 |
| --- | --- | --- |
| `prePrompt` | 发送 Prompt 前 | 注入上下文、规范 |
| `postResponse` | 收到响应后 | 捕获记忆、更新状态 |
| `preCommand` | 执行命令前 | 验证、修改参数 |
| `postCommand` | 执行命令后 | 清理、通知 |
### Hook 配置示例
```json
{
"hooks": {
"prePrompt": [
{
"type": "command",
"command": "ccw",
"args": ["spec", "load", "--stdin"],
"timeout": 5000
},
{
"type": "mcp",
"server": "cw-tools",
"tool": "core_memory",
"args": {
"operation": "search",
"query": "{{userPrompt}}",
"top_k": 5
}
},
{
"type": "file",
"path": ".cw/prompts/system-prefix.md"
}
],
"postResponse": [
{
"type": "command",
"command": "ccw",
"args": ["memory", "capture", "--auto"]
},
{
"type": "mcp",
"server": "cw-tools",
"tool": "core_memory",
"args": {
"operation": "import",
"text": "{{response}}",
"tags": ["auto-capture"]
}
}
]
}
}
```
## Agents 配置
### Agent 定义
Agent 定义文件位于 `~/.claude/agents/`：
```markdown
---
name: cli-execution-agent
version: "1.0.0"
description: Execute CLI tools with intelligent fallback
---
# CLI Execution Agent
## Phase 1: Intent Analysis
Analyze user prompt to determine:
- Task type (analyze/plan/execute/discuss)
- Tool selection (gemini/qwen/codex/claude)
- Mode (analysis/write/review)
## Phase 2: Tool Selection
| Task Type | Primary Tool | Fallback |
|-----------|--------------|----------|
| analyze | gemini | qwen |
| plan | gemini | codex |
| execute (simple) | gemini | qwen |
| execute (complex) | codex | gemini |
| discuss | multi | - |
## Phase 3: Execution
Build and execute CLI command with:
- Proper mode selection
- Model configuration
- Error handling
- Output formatting
```
### Agent 调用
```bash
# 调用 Agent
ccw agent execute cli-execution-agent \
--prompt "分析代码结构" \
--context @src/**/*.ts
```
## 代理配置
### HTTP 代理
```json
{
"proxy": {
"http": "http://proxy.example.com:8080",
"https": "https://proxy.example.com:8080",
"noProxy": ["localhost", "127.0.0.1", "*.local"]
}
}
```
### SOCKS 代理
```json
{
"proxy": {
"socks": "socks5://127.0.0.1:1080"
}
}
```
### 环境变量
```bash
# 设置代理环境变量
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"
```
## 操作步骤
### 初始化系统配置
```bash
# 初始化全局配置
ccw config init --global
# 初始化项目配置
ccw config init
# 查看当前配置
ccw config show
# 验证配置
ccw config validate
```
### 添加新工具
```bash
# 编辑 cli-tools.json
code ~/.claude/cli-tools.json
# 添加新工具定义
{
"tools": {
"new-tool": {
"enabled": true,
"primaryModel": "model-name",
"secondaryModel": "fallback-model",
"tags": ["tag1", "tag2"],
"type": "builtin"
}
}
}
```
### 配置 Hooks
```bash
# 编辑项目 settings.json
code .cw/settings.json
# 添加 prePrompt hook
{
"hooks": {
"prePrompt": [
{
"type": "command",
"command": "ccw",
"args": ["spec", "load", "--stdin"]
}
]
}
}
```
### 配置代理
```bash
# 编辑全局配置
code ~/.claude/settings.json
# 添加代理配置
{
"proxy": {
"http": "http://proxy.example.com:8080",
"https": "https://proxy.example.com:8080"
}
}
```
## 配置优先级
```
1. 环境变量 (最高)
2. settings.local.json
3. settings.json (项目)
4. settings.json (全局)
5. 默认值 (最低)
```
## 常见问题
### Q1: cli-tools.json 和 cli-settings.json 的区别？
A:
- **cli-tools.json**: 定义可用的工具（工具商店）
- **cli-settings.json**: 配置 CLI 的行为（偏好设置）
### Q2: Hooks 执行顺序？
A: 按数组顺序依次执行：
1. 数组前面的先执行
2. 失败会中断后续 Hook
3. 使用 `continueOnError: true` 忽略失败
### Q3: 如何调试配置？
A: 使用 debug 模式：
```bash
# 查看配置加载过程
ccw config show --debug
# 验证配置语法
ccw config validate
# 查看有效配置
ccw config effective
```
### Q4: 配置修改后不生效？
A: 检查：
1. 配置文件位置是否正确
2. JSON 语法是否正确
3. 配置优先级是否被覆盖
4. 是否需要重启服务
## 相关功能
- [API 设置](./api-settings.md) — API Keys 配置
- [CLI 调用系统](./cli.md) — CLI 工具使用
- [Spec 规范系统](./spec.md) — 规范文件配置
## 进阶阅读
- 配置加载器: `ccw/src/config/settings-loader.ts`
- CLI 工具管理: `ccw/src/tools/claude-cli-tools.ts`
- Hooks 执行: `ccw/src/core/hooks/hook-executor.ts`
- 代理处理: `ccw/src/utils/proxy-agent.ts`

87
docs/zh/guide/ch01-what-is-claude-dms3.md Normal file
View File

@@ -0,0 +1,87 @@
# Claude_dms3 是什么
## 一句话定位
**Claude_dms3 是 VS Code 的 AI 辅助开发工作台** — 通过语义代码索引、多模型 CLI 调用和团队协作系统，让 AI 深度理解项目并按规范生成高质量代码。
> AI 能力如藤蔓般生长 — Claude_dms3 是引导 AI 沿着您的项目架构、编码规范和团队工作流前行的支架。
---
## 1.1 解决的痛点
| 痛点 | 现状 | Claude_dms3 方案 |
|------|------|------------------|
| **AI 不理解项目** | 每次新会话都要重新解释项目背景、技术栈和编码规范 | Memory 系统持久化项目上下文，AI 跨会话记住项目知识 |
| **代码搜索困难** | 关键词搜索找不到语义相关代码，不知道函数在哪里被调用 | CodexLens 语义索引，支持自然语言搜索和调用链追踪 |
| **单模型局限** | 只能调用一个 AI 模型，不同模型擅长的场景不同 | CCW 统一调用框架，支持多模型协作（Gemini、Qwen、Codex、Claude） |
| **协作流程混乱** | 团队成员各自为战，代码风格不一致，规范难以落地 | 团队工作流系统（PlanEx、IterDev、Lifecycle）确保规范执行 |
| **规范难落地** | CLAUDE.md 写了但 AI 不遵守，项目约束被忽略 | Spec + Hook 自动注入，AI 强制遵循项目规范 |
---
## 1.2 vs 传统方式对比
| 维度 | 传统 AI 助手 | **Claude_dms3** |
|------|-------------|-----------------|
| **代码搜索** | 文本关键词搜索 | **语义向量搜索 + LSP 调用链** |
| **AI 调用** | 单一模型固定调用 | **多模型协作，按任务选择最优模型** |
| **项目记忆** | 每次会话重新解释 | **跨会话持久化 Memory** |
| **规范执行** | 依赖 Prompt 提醒 | **Spec + Hook 自动注入** |
| **团队协作** | 各自为战 | **结构化工作流系统** |
| **代码质量** | 取决于 AI 能力 | **多维度审查 + 自动修复循环** |
---
## 1.3 核心概念速览
| 概念 | 说明 | 位置/命令 |
|------|------|----------|
| **CodexLens** | 语义代码索引和搜索引擎 | `ccw search` |
| **CCW** | 统一 CLI 工具调用框架 | `ccw cli` |
| **Memory** | 跨会话知识持久化 | `ccw memory` |
| **Spec** | 项目规范和约束系统 | `.workflow/specs/` |
| **Hook** | 自动触发的上下文注入脚本 | `.claude/hooks/` |
| **Agent** | 专门角色的 AI 子进程 | `.claude/agents/` |
| **Skill** | 可复用的 AI 能力模块 | `.claude/skills/` |
| **Workflow** | 多阶段开发编排 | `/workflow:*` |
---
## 1.4 架构概览
```
┌─────────────────────────────────────────────────────────────┐
│ Claude_dms3 架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ CodexLens │ │ CCW │ │ Memory │ │
│ │ (语义索引) │ │ (CLI调用 │ │ (持久化 │ │
│ │ │ │ 框架) │ │ 上下文) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ │ Spec │ │
│ │ 规范系统 │ │
│ └─────┬─────┘ │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ │ │ │ │
│ ┌────┴────┐ ┌─────┴─────┐ ┌────┴────┐ │
│ │ Hooks │ │ Skills │ │ Agents │ │
│ │ (注入) │ │ (可复用) │ │ (角色) │ │
│ └─────────┘ └───────────┘ └─────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## 下一步
- [快速开始](ch02-getting-started.md) — 安装和配置
- [核心概念](ch03-core-concepts.md) — 理解基础知识
- [工作流基础](ch04-workflow-basics.md) — 开始你的第一个工作流

295
docs/zh/guide/ch02-getting-started.md Normal file
View File

@@ -0,0 +1,295 @@
# 快速开始
## 一句话定位
**快速开始是 5 分钟上手指南** — 安装配置、第一个命令、第一个工作流，快速体验 Claude_dms3 核心功能。
---
## 2.1 安装
### 2.1.1 前置要求
| 要求 | 版本 | 说明 |
| --- | --- | --- |
| **Node.js** | 18+ | CCW 模块需要 |
| **Python** | 3.10+ | CodexLens 模块需要 |
| **VS Code** | 最新版 | 扩展运行环境 |
| **Git** | 最新版 | 版本控制 |
### 2.1.2 克隆项目
```bash
# 克隆仓库
git clone https://github.com/your-repo/claude-dms3.git
cd claude-dms3
# 安装依赖
npm install
```
### 2.1.3 配置 API Keys
在 `~/.claude/settings.json` 中配置 API Keys：
```json
{
"openai": {
"apiKey": "sk-xxx"
},
"anthropic": {
"apiKey": "sk-ant-xxx"
},
"google": {
"apiKey": "AIza-xxx"
}
}
```
::: tip 提示
API Keys 也可以在项目级别配置 `.claude/settings.json`，项目级配置优先级高于全局配置。
:::
---
## 2.2 初始化项目
### 2.2.1 启动工作流会话
在 VS Code 中打开项目，然后运行：
```
/workflow:session:start
```
这会创建一个新的工作流会话，所有后续操作都会在这个会话上下文中进行。
### 2.2.2 初始化项目规范
```
/workflow:init
```
这会创建 `project-tech.json` 文件，记录项目的技术栈信息。
### 2.2.3 填充项目规范
```
/workflow:init-guidelines
```
交互式填充项目规范，包括编码风格、架构决策等信息。
---
## 2.3 第一个命令
### 2.3.1 代码分析
使用 CCW CLI 工具分析代码：
```bash
ccw cli -p "分析这个文件的代码结构和设计模式" --tool gemini --mode analysis
```
**参数说明**:
- `-p`: Prompt（任务描述）
- `--tool gemini`: 使用 Gemini 模型
- `--mode analysis`: 分析模式（只读，不修改文件）
### 2.3.2 代码生成
使用 CCW CLI 工具生成代码：
```bash
ccw cli -p "创建一个 React 组件，实现用户登录表单" --tool qwen --mode write
```
**参数说明**:
- `--mode write`: 写入模式（可以创建/修改文件）
::: danger 注意
`--mode write` 会修改文件，请确保代码已提交或有备份。
:::
---
## 2.4 第一个工作流
### 2.4.1 启动规划工作流
```
/workflow:plan
```
这会启动 PlanEx 工作流，包含以下步骤：
1. **分析需求** - 理解用户意图
2. **探索代码** - 搜索相关代码和模式
3. **生成计划** - 创建结构化任务列表
4. **执行任务** - 按计划执行开发
### 2.4.2 头脑风暴
```
/brainstorm
```
多视角头脑风暴，获取不同观点：
| 视角 | 角色 | 聚焦 |
| --- | --- | --- |
| Product | 产品经理 | 市场契合度、用户价值 |
| Technical | 技术负责人 | 可行性、技术债 |
| Quality | QA 负责人 | 完整性、可测试性 |
| Risk | 风险分析师 | 风险识别、依赖关系 |
---
## 2.5 使用 Memory
### 2.5.1 查看项目记忆
```bash
ccw memory list
```
显示所有项目记忆，包括 learnings、decisions、conventions、issues。
### 2.5.2 搜索相关记忆
```bash
ccw memory search "认证"
```
基于语义搜索与"认证"相关的记忆。
### 2.5.3 添加记忆
```
/memory-capture
```
交互式捕获当前会话中的重要知识点。
---
## 2.6 代码搜索
### 2.6.1 语义搜索
在 VS Code 中使用 CodexLens 搜索：
```bash
# 通过 CodexLens MCP 端点搜索
ccw search "用户登录逻辑"
```
### 2.6.2 调用链追踪
搜索函数的定义和所有调用位置：
```bash
ccw search --trace "authenticateUser"
```
---
## 2.7 Dashboard 面板
### 2.7.1 打开 Dashboard
在 VS Code 中运行：
```
ccw-dashboard.open
```
或使用命令面板（Ctrl+Shift+P）搜索 "CCW Dashboard"。
### 2.7.2 面板功能
| 功能 | 说明 |
| --- | --- |
| **技术栈** | 显示项目使用的框架和库 |
| **规范文档** | 快速查看项目规范 |
| **Memory** | 浏览和搜索项目记忆 |
| **代码搜索** | 集成 CodexLens 语义搜索 |
---
## 2.8 常见问题
### 2.8.1 API Key 配置
**Q: 在哪里配置 API Keys？**
A: 可以在两个位置配置：
- 全局配置: `~/.claude/settings.json`
- 项目配置: `.claude/settings.json`
项目配置优先级高于全局配置。
### 2.8.2 模型选择
**Q: 如何选择合适的模型？**
A: 根据任务类型选择：
- 代码分析、架构设计 → Gemini
- 通用代码开发 → Qwen
- 代码审查 → Codex (GPT)
- 长文本理解 → Claude
### 2.8.3 工作流选择
**Q: 什么时候使用哪个工作流？**
A: 根据任务目标选择：
- 新功能开发 → `/workflow:plan`
- 问题诊断 → `/debug-with-file`
- 代码审查 → `/review-code`
- 重构规划 → `/refactor-cycle`
- UI 开发 → `/workflow:ui-design`
---
## 2.9 快速参考
### 安装步骤
```bash
# 1. 克隆项目
git clone https://github.com/your-repo/claude-dms3.git
cd claude-dms3
# 2. 安装依赖
npm install
# 3. 配置 API Keys
# 编辑 ~/.claude/settings.json
# 4. 启动工作流会话
/workflow:session:start
# 5. 初始化项目
/workflow:init
```
### 常用命令
| 命令 | 功能 |
| --- | --- |
| `/workflow:session:start` | 启动会话 |
| `/workflow:plan` | 规划工作流 |
| `/brainstorm` | 头脑风暴 |
| `/review-code` | 代码审查 |
| `ccw memory list` | 查看 Memory |
| `ccw cli -p "..."` | CLI 调用 |
---
## 下一步
- [核心概念](ch03-core-concepts.md) — 深入理解 Commands、Skills、Prompts
- [工作流基础](ch04-workflow-basics.md) — 学习使用各种工作流命令
- [高级技巧](ch05-advanced-tips.md) — CLI 工具链、多模型协作、记忆管理优化

264
docs/zh/guide/ch03-core-concepts.md Normal file
View File

@@ -0,0 +1,264 @@
# 核心概念
## 一句话定位
**核心概念是理解 Claude_dms3 的基础** — Commands、Skills、Prompts 三层抽象，Workflow 会话管理，团队协作模式。
---
## 3.1 三层抽象
Claude_dms3 的命令系统分为三层抽象：
### 3.1.1 Commands - 内置命令
**Commands 是 Claude_dms3 的原子操作** — 预定义的可复用命令，完成特定任务。
| 类别 | 命令数量 | 说明 |
| --- | --- | --- |
| **核心编排** | 2 | ccw, ccw-coordinator |
| **CLI 工具** | 2 | cli-init, codex-review |
| **Issue 工作流** | 8 | discover, plan, execute, queue 等 |
| **Memory** | 2 | prepare, style-skill-memory |
| **Workflow 会话** | 6 | start, resume, list, complete 等 |
| **Workflow 分析** | 10+ | analyze, brainstorm, debug, refactor 等 |
| **Workflow UI 设计** | 9 | generate, import-from-code, style-extract 等 |
::: tip 提示
Commands 定义在 `.claude/commands/` 目录，每个命令是一个 Markdown 文件。
:::
### 3.1.2 Skills - 复合技能
**Skills 是 Commands 的组合封装** — 针对特定场景的可复用技能，包含多个步骤和最佳实践。
| Skill | 功能 | 触发方式 |
| --- | --- | --- |
| **brainstorm** | 多视角头脑风暴 | `/brainstorm` |
| **ccw-help** | CCW 命令帮助 | `/ccw-help` |
| **command-generator** | 生成 Claude 命令 | `/command-generator` |
| **issue-manage** | Issue 管理 | `/issue-manage` |
| **memory-capture** | Memory 压缩和捕获 | `/memory-capture` |
| **memory-manage** | Memory 更新 | `/memory-manage` |
| **review-code** | 多维度代码审查 | `/review-code` |
| **review-cycle** | 代码审查和修复循环 | `/review-cycle` |
| **skill-generator** | 生成 Claude 技能 | `/skill-generator` |
| **skill-tuning** | Skill 诊断和调优 | `/skill-tuning` |
::: tip 提示
Skills 定义在 `.claude/skills/` 目录，包含 SKILL.md 规范文件和参考文档。
:::
### 3.1.3 Prompts - Codex 提示
**Prompts 是 Codex 模型的指令模板** — 针对 Codex (GPT) 模型优化的提示模板。
| Prompt | 功能 |
| --- | --- |
| **prep-cycle** | Prep 周期提示 |
| **prep-plan** | Prep 规划提示 |
::: tip 提示
Codex Prompts 定义在 `.codex/prompts/` 目录，专为 Codex 模型优化。
:::
---
## 3.2 三层关系
```
┌─────────────────────────────────────────────────────┐
│ 用户请求 │
└────────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ ccw (编排器) │
│ 意图分析 → 工作流选择 → 命令链执行 │
└────────────────────┬────────────────────────────────┘
│
┌───────────┼───────────┐
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│ Command│ │ Skill │ │ Prompt │
│ (原子) │ │ (复合) │ │(模板) │
└────────┘ └────────┘ └────────┘
│ │ │
└───────────┼───────────┘
▼
┌────────────────┐
│ AI 模型调用 │
└────────────────┘
```
### 3.2.1 调用路径
1. **用户发起请求** → 在 VS Code 中输入命令或描述需求
2. **ccw 编排** → 意图分析，选择合适的工作流
3. **执行 Command** → 执行原子命令操作
4. **调用 Skill** → 如需复杂逻辑，调用组合技能
5. **使用 Prompt** → 如需特定模型，使用优化提示
6. **AI 模型执行** → 调用配置的 AI 模型
7. **返回结果** → 格式化输出给用户
---
## 3.3 Workflow 会话管理
### 3.3.1 会话生命周期
```
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Start │────▶│ Resume │────▶│ Execute │────▶│Complete │
│ 启动 │ │ 恢复 │ │ 执行 │ │ 完成 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ List │ │ Solidify│
│ 列出 │ │ 固化 │
└─────────┘ └─────────┘
```
### 3.3.2 会话命令
| 命令 | 功能 | 示例 |
| --- | --- | --- |
| **start** | 启动新会话 | `/workflow:session:start` |
| **resume** | 恢复已有会话 | `/workflow:session:resume <session-id>` |
| **list** | 列出所有会话 | `/workflow:session:list` |
| **sync** | 同步会话状态 | `/workflow:session:sync` |
| **complete** | 完成当前会话 | `/workflow:session:complete` |
| **solidify** | 固化会话成果 | `/workflow:session:solidify` |
### 3.3.3 会话目录结构
```
.workflow/
├── .team/
│ └── TC-<project>-<date>/ # 会话目录
│ ├── spec/ # 会话规范
│ │ ├── discovery-context.json
│ │ └── requirements.md
│ ├── artifacts/ # 会话产物
│ ├── wisdom/ # 会话智慧
│ │ ├── learnings.md
│ │ ├── decisions.md
│ │ ├── conventions.md
│ │ └── issues.md
│ └── .team-msg/ # 消息总线
```
---
## 3.4 团队协作模式
### 3.4.1 角色系统
Claude_dms3 支持 8 种团队工作流，每种工作流定义了不同的角色：
| 工作流 | 角色 | 说明 |
| --- | --- | --- |
| **PlanEx** | planner, executor | 规划执行分离 |
| **IterDev** | developer, reviewer | 迭代开发 |
| **Lifecycle** | analyzer, developer, tester, reviewer | 生命周期覆盖 |
| **Issue** | discoverer, planner, executor | Issue 驱动 |
| **Testing** | tester, developer | 测试驱动 |
| **QA** | qa, developer | 质量保证 |
| **Brainstorm** | facilitator, perspectives | 多视角分析 |
| **UIDesign** | designer, developer | UI 设计生成 |
### 3.4.2 消息总线
团队成员通过消息总线通信：
```
┌────────────┐ ┌────────────┐
│ Planner │ │ Executor │
└─────┬──────┘ └──────┬─────┘
│ │
│ [plan_ready] │
├────────────────────────────────▶
│ │
│ [task_complete]
│◀────────────────────────────────┤
│ │
│ [plan_approved] │
├────────────────────────────────▶
│ │
```
### 3.4.3 工作流选择指南
| 任务目标 | 推荐工作流 | 命令 |
| --- | --- | --- |
| 新功能开发 | PlanEx | `/workflow:plan` |
| Bug 修复 | Lifecycle | `/debug-with-file` |
| 代码重构 | IterDev | `/refactor-cycle` |
| 技术决策 | Brainstorm | `/brainstorm-with-file` |
| UI 开发 | UIDesign | `/workflow:ui-design` |
| 集成测试 | Testing | `/integration-test-cycle` |
| 代码审查 | QA | `/review-cycle` |
| Issue 管理 | Issue | `/issue` 系列 |
---
## 3.5 核心概念速览
| 概念 | 说明 | 位置/命令 |
| --- | --- | --- |
| **Command** | 原子操作命令 | `.claude/commands/` |
| **Skill** | 复合技能封装 | `.claude/skills/` |
| **Prompt** | Codex 提示模板 | `.codex/prompts/` |
| **Workflow** | 团队协作流程 | `/workflow:*` |
| **Session** | 会话上下文管理 | `/workflow:session:*` |
| **Memory** | 跨会话知识持久化 | `ccw memory` |
| **Spec** | 项目规范约束 | `.workflow/specs/` |
| **CodexLens** | 语义代码索引 | `.codex-lens/` |
| **CCW** | CLI 调用框架 | `ccw` 目录 |
---
## 3.6 数据流
```
用户请求
│
▼
┌──────────────┐
│ CCW 编排器 │ ──▶ 意图分析
└──────────────┘
│
├─▶ Workflow 选择
│ │
│ ├─▶ PlanEx
│ ├─▶ IterDev
│ ├─▶ Lifecycle
│ └─▶ ...
│
├─▶ Command 执行
│ │
│ ├─▶ 内置命令
│ └─▶ Skill 调用
│
├─▶ AI 模型调用
│ │
│ ├─▶ Gemini
│ ├─▶ Qwen
│ ├─▶ Codex
│ └─▶ Claude
│
└─▶ 结果返回
│
├─▶ 文件修改
├─▶ Memory 更新
└─▶ Dashboard 更新
```
---
## 下一步
- [工作流基础](ch04-workflow-basics.md) — 学习使用各种工作流命令
- [高级技巧](ch05-advanced-tips.md) — CLI 工具链、多模型协作
- [最佳实践](ch06-best-practices.md) — 团队协作规范、代码审查流程

320
docs/zh/guide/ch04-workflow-basics.md Normal file
View File

@@ -0,0 +1,320 @@
# 工作流基础
## 一句话定位
**工作流是团队协作的核心** — 8 种工作流覆盖开发全流程，从规划到执行，从分析到测试。
---
## 4.1 工作流概览
| 工作流 | 核心命令 | 适用场景 | 角色 |
| --- | --- | --- | --- |
| **PlanEx** | `/workflow:plan` | 新功能开发、需求实现 | planner, executor |
| **IterDev** | `/refactor-cycle` | 代码重构、技术债处理 | developer, reviewer |
| **Lifecycle** | `/unified-execute-with-file` | 完整开发周期 | analyzer, developer, tester, reviewer |
| **Issue** | `/issue:*` | Issue 驱动开发 | discoverer, planner, executor |
| **Testing** | `/integration-test-cycle` | 集成测试、测试生成 | tester, developer |
| **QA** | `/review-cycle` | 代码审查和质量保证 | qa, developer |
| **Brainstorm** | `/brainstorm-with-file` | 多视角分析、技术决策 | facilitator, perspectives |
| **UIDesign** | `/workflow:ui-design` | UI 设计和代码生成 | designer, developer |
---
## 4.2 PlanEx - 规划执行工作流
### 4.2.1 一句话定位
**PlanEx 是规划与执行分离的工作流** — 先规划再执行，确保任务清晰后再动手。
### 4.2.2 启动方式
```
/workflow:plan
```
或直接描述需求：
```
实现用户登录功能，支持邮箱和手机号登录
```
### 4.2.3 工作流程
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Planner │────▶│ Executor │────▶│ Reviewer │
│ 规划阶段 │ │ 执行阶段 │ │ 审查阶段 │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 需求分析 │ │ 任务执行 │ │ 代码审查 │
│ 任务分解 │ │ 代码生成 │ │ 质量检查 │
│ 计划生成 │ │ 测试编写 │ │ 反馈修复 │
└─────────────┘ └─────────────┘ └─────────────┘
```
### 4.2.4 输出产物
| 产物 | 位置 | 说明 |
| --- | --- | --- |
| **需求分析** | `artifacts/requirements.md` | 需求详细分析 |
| **任务计划** | `artifacts/plan.md` | 结构化任务列表 |
| **执行产物** | `artifacts/implementation/` | 代码和测试 |
| **智慧积累** | `wisdom/learnings.md` | 过程中学到的经验 |
---
## 4.3 IterDev - 迭代开发工作流
### 4.3.1 一句话定位
**IterDev 是迭代重构工作流** — 发现技术债、规划重构、迭代改进。
### 4.3.2 启动方式
```
/refactor-cycle
```
### 4.3.3 工作流程
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Discover │────▶│ Plan │────▶│ Refactor │
│ 发现阶段 │ │ 规划阶段 │ │ 重构阶段 │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 代码分析 │ │ 重构策略 │ │ 代码修改 │
│ 问题识别 │ │ 优先级排序 │ │ 测试验证 │
│ 技术债记录 │ │ 任务分解 │ │ 文档更新 │
└─────────────┘ └─────────────┘ └─────────────┘
```
### 4.3.4 使用场景
| 场景 | 示例 |
| --- | --- |
| **代码异味** | 函数过长、重复代码 |
| **架构改进** | 解耦合、模块化 |
| **性能优化** | 算法优化、缓存策略 |
| **安全加固** | 修复安全漏洞 |
| **规范统一** | 代码风格统一 |
---
## 4.4 Lifecycle - 生命周期工作流
### 4.4.1 一句话定位
**Lifecycle 是全生命周期覆盖工作流** — 从分析到测试到审查，完整闭环。
### 4.4.2 启动方式
```
/unified-execute-with-file <file>
```
### 4.4.3 角色职责
| 角色 | 职责 | 输出 |
| --- | --- | --- |
| **Analyzer** | 分析需求、探索代码 | 分析报告 |
| **Developer** | 实现功能、编写测试 | 代码 + 测试 |
| **Tester** | 运行测试、验证功能 | 测试报告 |
| **Reviewer** | 代码审查、质量检查 | 审查报告 |
### 4.4.4 工作流程
```
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│Analyzer │──▶│Developer│──▶│ Tester │──▶│Reviewer │
│ 分析 │ │ 开发 │ │ 测试 │ │ 审查 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │ │ │
▼ ▼ ▼ ▼
需求分析 代码实现 测试验证 质量把关
代码探索 单元测试 回归测试 最终确认
```
---
## 4.5 Issue - Issue 管理工作流
### 4.5.1 一句话定位
**Issue 是 Issue 驱动开发工作流** — 从 Issue 发现到规划到执行，完整追踪。
### 4.5.2 Issue 命令
| 命令 | 功能 | 示例 |
| --- | --- | --- |
| **discover** | 发现 Issue | `/issue discover https://github.com/xxx/issue/1` |
| **discover-by-prompt** | 从 Prompt 创建 | `/issue discover-by-prompt "登录失败"` |
| **from-brainstorm** | 从头脑风暴创建 | `/issue from-brainstorm` |
| **plan** | 批量规划 Issue | `/issue plan` |
| **queue** | 形成执行队列 | `/issue queue` |
| **execute** | 执行 Issue 队列 | `/issue execute` |
### 4.5.3 工作流程
```
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│Discover │──▶│ Plan │──▶│ Queue │──▶│ Execute │
│ 发现 │ │ 规划 │ │ 排队 │ │ 执行 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │ │ │
▼ ▼ ▼ ▼
识别问题 分析需求 优先级排序 实现方案
定义范围 制定计划 依赖关系 验证结果
```
---
## 4.6 Testing - 测试工作流
### 4.6.1 一句话定位
**Testing 是自迭代测试工作流** — 自动生成测试、迭代改进测试覆盖率。
### 4.6.2 启动方式
```
/integration-test-cycle
```
### 4.6.3 工作流程
```
┌─────────┐ ┌─────────┐ ┌─────────┐
│Generate │──▶│ Execute │──▶│ Verify │
│ 生成 │ │ 执行 │ │ 验证 │
└─────────┘ └─────────┘ └─────────┘
│ │ │
▼ ▼ ▼
测试用例 运行测试 覆盖率分析
Mock 数据 失败分析 缺口补充
```
---
## 4.7 QA - 质量保证工作流
### 4.7.1 一句话定位
**QA 是代码审查工作流** — 6 维度代码审查，自动发现问题。
### 4.7.2 启动方式
```
/review-cycle
```
### 4.7.3 审查维度
| 维度 | 检查项 |
| --- | --- |
| **正确性** | 逻辑正确、边界处理 |
| **性能** | 算法效率、资源使用 |
| **安全** | 注入漏洞、权限检查 |
| **可维护性** | 代码清晰、模块化 |
| **测试覆盖** | 单元测试、边界测试 |
| **规范符合** | 编码规范、项目约定 |
---
## 4.8 Brainstorm - 头脑风暴工作流
### 4.8.1 一句话定位
**Brainstorm 是多视角分析工作流** — 从多个视角分析问题，获得全面洞察。
### 4.8.2 启动方式
```
/brainstorm-with-file <file>
```
### 4.8.3 分析视角
| 视角 | 角色 | 聚焦 |
| --- | --- | --- |
| **Product** | 产品经理 | 市场契合、用户价值 |
| **Technical** | 技术负责人 | 可行性、技术债 |
| **Quality** | QA 负责人 | 完整性、可测试性 |
| **Risk** | 风险分析师 | 风险识别、依赖关系 |
### 4.8.4 输出格式
```markdown
## 一致结论
- [共识点 1]
- [共识点 2]
## 分歧点
- [分歧 1]
- 视角 A: ...
- 视角 B: ...
- 建议: ...
## 行动项
- [ ] [行动项 1]
- [ ] [行动项 2]
```
---
## 4.9 UIDesign - UI 设计工作流
### 4.9.1 一句话定位
**UIDesign 是 UI 设计生成工作流** — 从设计稿到代码，自动提取样式和布局。
### 4.9.2 UI 设计命令
| 命令 | 功能 |
| --- | --- |
| **generate** | 生成 UI 组件 |
| **import-from-code** | 从代码导入样式 |
| **style-extract** | 提取样式规范 |
| **layout-extract** | 提取布局结构 |
| **imitate-auto** | 模仿参考页面 |
| **codify-style** | 样式代码化 |
| **design-sync** | 同步设计变更 |
---
## 4.10 快速参考
### 工作流选择指南
| 需求 | 推荐工作流 | 命令 |
| --- | --- | --- |
| 新功能开发 | PlanEx | `/workflow:plan` |
| 代码重构 | IterDev | `/refactor-cycle` |
| 完整开发 | Lifecycle | `/unified-execute-with-file` |
| Issue 管理 | Issue | `/issue:*` |
| 测试生成 | Testing | `/integration-test-cycle` |
| 代码审查 | QA | `/review-cycle` |
| 多视角分析 | Brainstorm | `/brainstorm-with-file` |
| UI 开发 | UIDesign | `/workflow:ui-design` |
### 会话管理命令
| 命令 | 功能 |
| --- | --- |
| `/workflow:session:start` | 启动新会话 |
| `/workflow:session:resume` | 恢复会话 |
| `/workflow:session:list` | 列出会话 |
| `/workflow:session:complete` | 完成会话 |
| `/workflow:session:solidify` | 固化成果 |
---
## 下一步
- [高级技巧](ch05-advanced-tips.md) — CLI 工具链、多模型协作
- [最佳实践](ch06-best-practices.md) — 团队协作规范、代码审查流程

331
docs/zh/guide/ch05-advanced-tips.md Normal file
View File

@@ -0,0 +1,331 @@
# 高级技巧
## 一句话定位
**高级技巧是提升效率的关键** — CLI 工具链深度使用、多模型协作优化、记忆管理最佳实践。
---
## 5.1 CLI 工具链使用
### 5.1.1 CLI 配置
CLI 工具配置文件：`~/.claude/cli-tools.json`
```json
{
"version": "3.3.0",
"tools": {
"gemini": {
"enabled": true,
"primaryModel": "gemini-2.5-flash",
"secondaryModel": "gemini-2.5-flash",
"tags": ["分析", "Debug"],
"type": "builtin"
},
"qwen": {
"enabled": true,
"primaryModel": "coder-model",
"secondaryModel": "coder-model",
"tags": [],
"type": "builtin"
},
"codex": {
"enabled": true,
"primaryModel": "gpt-5.2",
"secondaryModel": "gpt-5.2",
"tags": [],
"type": "builtin"
}
}
}
```
### 5.1.2 标签路由
根据任务类型自动选择模型：
| 标签 | 适用模型 | 任务类型 |
| --- | --- | --- |
| **分析** | Gemini | 代码分析、架构设计 |
| **Debug** | Gemini | 根因分析、问题诊断 |
| **实现** | Qwen | 功能开发、代码生成 |
| **审查** | Codex | 代码审查、Git 操作 |
### 5.1.3 CLI 命令模板
#### 分析任务
```bash
ccw cli -p "PURPOSE: 识别安全漏洞
TASK: • 扫描 SQL 注入 • 检查 XSS • 验证 CSRF
MODE: analysis
CONTEXT: @src/auth/**/*
EXPECTED: 安全报告，含严重性分级和修复建议
CONSTRAINTS: 聚焦认证模块" --tool gemini --mode analysis --rule analysis-assess-security-risks
```
#### 实现任务
```bash
ccw cli -p "PURPOSE: 实现速率限制
TASK: • 创建中间件 • 配置路由 • Redis 后端
MODE: write
CONTEXT: @src/middleware/**/* @src/config/**/*
EXPECTED: 生产代码 + 单元测试 + 集成测试
CONSTRAINTS: 遵循现有中间件模式" --tool qwen --mode write --rule development-implement-feature
```
### 5.1.4 规则模板
| 规则 | 用途 |
| --- | --- |
| **analysis-diagnose-bug-root-cause** | Bug 根因分析 |
| **analysis-analyze-code-patterns** | 代码模式分析 |
| **analysis-review-architecture** | 架构审查 |
| **analysis-assess-security-risks** | 安全评估 |
| **development-implement-feature** | 功能实现 |
| **development-refactor-codebase** | 代码重构 |
| **development-generate-tests** | 测试生成 |
---
## 5.2 多模型协作
### 5.2.1 模型选择指南
| 任务 | 推荐模型 | 理由 |
| --- | --- | --- |
| **代码分析** | Gemini | 擅长深度代码理解和模式识别 |
| **Bug 诊断** | Gemini | 强大的根因分析能力 |
| **功能开发** | Qwen | 代码生成效率高 |
| **代码审查** | Codex (GPT) | Git 集成好，审查格式标准 |
| **长文本** | Claude | 上下文窗口大 |
### 5.2.2 协作模式
#### 串行协作
```bash
# 步骤 1: Gemini 分析
ccw cli -p "分析代码架构" --tool gemini --mode analysis
# 步骤 2: Qwen 实现
ccw cli -p "基于分析结果实现功能" --tool qwen --mode write
# 步骤 3: Codex 审查
ccw cli -p "审查实现代码" --tool codex --mode review
```
#### 并行协作
使用 `--tool gemini` 和 `--tool qwen` 同时分析同一问题：
```bash
# 终端 1
ccw cli -p "从性能角度分析" --tool gemini --mode analysis &
# 终端 2
ccw cli -p "从安全角度分析" --tool codex --mode analysis &
```
### 5.2.3 会话恢复
跨模型会话恢复：
```bash
# 第一次调用
ccw cli -p "分析认证模块" --tool gemini --mode analysis
# 恢复会话继续
ccw cli -p "基于上次分析，设计改进方案" --tool qwen --mode write --resume
```
---
## 5.3 Memory 管理
### 5.3.1 Memory 分类
| 分类 | 用途 | 示例内容 |
| --- | --- | --- |
| **learnings** | 学习心得 | 新技术使用经验 |
| **decisions** | 架构决策 | 技术选型理由 |
| **conventions** | 编码规范 | 命名约定、模式 |
| **issues** | 已知问题 | Bug、限制、TODO |
### 5.3.2 Memory 命令
| 命令 | 功能 | 示例 |
| --- | --- | --- |
| **list** | 列出所有记忆 | `ccw memory list` |
| **search** | 搜索记忆 | `ccw memory search "认证"` |
| **export** | 导出记忆 | `ccw memory export <id>` |
| **import** | 导入记忆 | `ccw memory import "..."` |
| **embed** | 生成嵌入 | `ccw memory embed <id>` |
### 5.3.3 Memory 最佳实践
::: tip 提示
- **定期整理**: 每周整理一次 Memory，删除过时内容
- **结构化**: 使用标准格式，便于搜索和复用
- **上下文**: 记录决策背景，不只是结论
- **链接**: 相关内容互相引用
:::
### 5.3.4 Memory 模板
```markdown
## 标题
### 背景
- **问题**: ...
- **影响**: ...
### 决策
- **方案**: ...
- **理由**: ...
### 结果
- **效果**: ...
- **经验**: ...
### 相关
- [相关记忆 1](memory-id-1)
- [相关文档](link)
```
---
## 5.4 CodexLens 高级用法
### 5.4.1 混合搜索
结合向量搜索和关键词搜索：
```bash
# 纯向量搜索
ccw search --mode vector "用户认证"
# 混合搜索（默认）
ccw search --mode hybrid "用户认证"
# 纯关键词搜索
ccw search --mode keyword "authenticate"
```
### 5.4.2 调用链追踪
追踪函数的完整调用链：
```bash
# 向上追踪（谁调用了我）
ccw search --trace-up "authenticateUser"
# 向下追踪（我调用了谁）
ccw search --trace-down "authenticateUser"
# 完整调用链
ccw search --trace-full "authenticateUser"
```
### 5.4.3 语义搜索技巧
| 技巧 | 示例 | 效果 |
| --- | --- | --- |
| **功能描述** | "处理用户登录" | 找到登录相关代码 |
| **问题描述** | "内存泄漏的地方" | 找到潜在问题 |
| **模式描述** | "单例模式的实现" | 找到设计模式 |
| **技术描述** | "使用 React Hooks" | 找到相关用法 |
---
## 5.5 Hook 自动注入
### 5.5.1 Hook 类型
| Hook 类型 | 触发时机 | 用途 |
| --- | --- | --- |
| **pre-command** | 命令执行前 | 注入规范、加载上下文 |
| **post-command** | 命令执行后 | 保存 Memory、更新状态 |
| **pre-commit** | Git 提交前 | 代码审查、规范检查 |
| **file-change** | 文件变更时 | 自动格式化、更新索引 |
### 5.5.2 Hook 配置
在 `.claude/hooks.json` 中配置：
```json
{
"pre-command": [
{
"name": "inject-specs",
"description": "注入项目规范",
"command": "cat .workflow/specs/project-constraints.md"
},
{
"name": "load-memory",
"description": "加载相关 Memory",
"command": "ccw memory search \"{query}\""
}
],
"post-command": [
{
"name": "save-memory",
"description": "保存重要决策",
"command": "ccw memory import \"{content}\""
}
]
}
```
---
## 5.6 性能优化
### 5.6.1 索引优化
| 优化项 | 说明 |
| --- | --- |
| **增量索引** | 只索引变更文件 |
| **并行索引** | 多进程并行处理 |
| **缓存策略** | 向量嵌入缓存 |
### 5.6.2 搜索优化
| 优化项 | 说明 |
| --- | --- |
| **结果缓存** | 相同查询返回缓存 |
| **分页加载** | 大结果集分页返回 |
| **智能去重** | 相似结果自动去重 |
---
## 5.7 快速参考
### CLI 命令速查
| 命令 | 功能 |
| --- | --- |
| `ccw cli -p "..." --tool gemini --mode analysis` | 分析任务 |
| `ccw cli -p "..." --tool qwen --mode write` | 实现任务 |
| `ccw cli -p "..." --tool codex --mode review` | 审查任务 |
| `ccw memory list` | 列出记忆 |
| `ccw memory search "..."` | 搜索记忆 |
| `ccw search "..."` | 语义搜索 |
| `ccw search --trace "..."` | 调用链追踪 |
### 规则模板速查
| 规则 | 用途 |
| --- | --- |
| `analysis-diagnose-bug-root-cause` | Bug 分析 |
| `analysis-assess-security-risks` | 安全评估 |
| `development-implement-feature` | 功能实现 |
| `development-refactor-codebase` | 代码重构 |
| `development-generate-tests` | 测试生成 |
---
## 下一步
- [最佳实践](ch06-best-practices.md) — 团队协作规范、代码审查流程、文档维护策略

330
docs/zh/guide/ch06-best-practices.md Normal file
View File

@@ -0,0 +1,330 @@
# 最佳实践
## 一句话定位
**最佳实践是团队高效协作的保障** — 规范制定、代码审查、文档维护、团队协作的实践经验总结。
---
## 6.1 团队协作规范
### 6.1.1 角色职责定义
| 角色 | 职责 | 技能要求 |
| --- | --- | --- |
| **Planner** | 需求分析、任务分解 | 架构思维、沟通能力 |
| **Developer** | 代码实现、单元测试 | 编码能力、测试意识 |
| **Reviewer** | 代码审查、质量把关 | 代码敏感度、规范理解 |
| **QA** | 质量保证、测试验证 | 测试设计、风险识别 |
| **Facilitator** | 协调沟通、进度跟踪 | 项目管理、冲突解决 |
### 6.1.2 工作流选择
| 场景 | 推荐工作流 | 理由 |
| --- | --- | --- |
| **新功能开发** | PlanEx | 规划与执行分离，降低风险 |
| **Bug 修复** | Lifecycle | 完整闭环，确保修复质量 |
| **代码重构** | IterDev | 迭代改进，持续优化 |
| **技术决策** | Brainstorm | 多视角分析，全面考虑 |
| **Issue 管理** | Issue | 可追溯，易管理 |
| **UI 开发** | UIDesign | 设计到代码无缝衔接 |
### 6.1.3 沟通协议
#### 消息格式
```
[<角色>] <操作> <对象>: <结果>
示例:
[Planner] 任务分解完成: 生成 5 个子任务
[Developer] 代码实现完成: user-auth.ts, 324 行
[Reviewer] 代码审查完成: 发现 2 个问题，建议 1 处优化
```
#### 状态报告
| 状态 | 含义 | 后续动作 |
| --- | --- | --- |
| **pending** | 待处理 | 等待依赖完成 |
| **in_progress** | 进行中 | 继续执行 |
| **completed** | 已完成 | 可以被依赖 |
| **blocked** | 被阻塞 | 需要人工介入 |
---
## 6.2 代码审查流程
### 6.2.1 审查维度
| 维度 | 检查项 | 严重性 |
| --- | --- | --- |
| **正确性** | 逻辑正确、边界处理 | HIGH |
| **性能** | 算法效率、资源使用 | MEDIUM |
| **安全** | 注入漏洞、权限检查 | HIGH |
| **可维护性** | 代码清晰、模块化 | MEDIUM |
| **测试覆盖** | 单元测试、边界测试 | MEDIUM |
| **规范符合** | 编码规范、项目约定 | LOW |
### 6.2.2 审查流程
```
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ 提交 │──▶│ 审查 │──▶│ 反馈 │──▶│ 修复 │
│ 代码 │ │ 代码 │ │ 意见 │ │ 问题 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │ │ │
▼ ▼ ▼ ▼
Push PR 自动审查 人工审查 修复验证
CI 检查 6 维度检查 代码走查 再次审查
```
### 6.2.3 审查清单
#### 代码正确性
- [ ] 逻辑正确，无 bug
- [ ] 边界条件处理
- [ ] 错误处理完整
- [ ] 资源释放正确
#### 性能
- [ ] 算法复杂度合理
- [ ] 无内存泄漏
- [ ] 无冗余计算
- [ ] 缓存策略合理
#### 安全
- [ ] 无 SQL 注入
- [ ] 无 XSS 漏洞
- [ ] 权限检查完整
- [ ] 敏感数据保护
#### 可维护性
- [ ] 命名清晰
- [ ] 模块化良好
- [ ] 注释充分
- [ ] 易于测试
#### 测试覆盖
- [ ] 单元测试完整
- [ ] 边界测试覆盖
- [ ] 异常情况测试
- [ ] 集成测试验证
#### 规范符合
- [ ] 编码风格统一
- [ ] 命名规范遵守
- [ ] 项目约定遵循
- [ ] 文档完整
### 6.2.4 反馈格式
```markdown
## 审查结果
### 问题
1. **[HIGH]** SQL 注入风险
- 位置: `src/auth/login.ts:45`
- 建议: 使用参数化查询
2. **[MEDIUM]** 性能问题
- 位置: `src/utils/cache.ts:78`
- 建议: 使用 LRU 缓存
### 建议
1. 命名优化: `data` → `userData`
2. 模块拆分: 建议将 Auth 逻辑独立
### 通过条件
- [ ] 修复 HIGH 问题
- [ ] 考虑 MEDIUM 建议
```
---
## 6.3 文档维护策略
### 6.3.1 文档分类
| 类型 | 位置 | 更新频率 | 负责人 |
| --- | --- | --- | --- |
| **规范文档** | `.workflow/specs/` | 按需 | 架构师 |
| **参考文档** | `docs/ref/` | 每次变更 | 开发者 |
| **指南文档** | `docs/guide/` | 每月 | 技术写手 |
| **API 文档** | `docs/api/` | 自动生成 | 工具 |
| **FAQ** | `docs/faq.md` | 每周 | 支持团队 |
### 6.3.2 文档更新触发
| 事件 | 更新内容 |
| --- | --- |
| **新增功能** | 添加功能文档和 API 参考 |
| **规范变更** | 更新规范文档和迁移指南 |
| **Bug 修复** | 更新 FAQ 和已知问题 |
| **架构变更** | 更新架构文档和决策记录 |
| **代码审查** | 补充缺失的注释和文档 |
### 6.3.3 文档质量标准
| 标准 | 要求 |
| --- | --- |
| **准确性** | 与实际代码一致 |
| **完整性** | 覆盖所有公开 API |
| **清晰性** | 易于理解，示例充分 |
| **时效性** | 及时更新，不滞后 |
| **可导航** | 结构清晰，易于查找 |
---
## 6.4 Memory 管理最佳实践
### 6.4.1 Memory 记录时机
| 时机 | 记录内容 |
| --- | --- |
| **架构决策** | 技术选型、设计决策 |
| **问题解决** | Bug 根因、解决方案 |
| **经验总结** | 最佳实践、避坑指南 |
| **规范约定** | 编码规范、命名约定 |
| **已知问题** | Bug、限制、TODO |
### 6.4.2 Memory 格式规范
```markdown
## [类型] 标题
### 背景
- **问题**: ...
- **影响**: ...
- **上下文**: ...
### 分析/决策
- **方案**: ...
- **理由**: ...
- **替代方案**: ...
### 结果
- **效果**: ...
- **数据**: ...
### 相关
- [相关记忆](memory-id)
- [相关代码](file-link)
- [相关文档](doc-link)
```
### 6.4.3 Memory 维护
| 维护项 | 频率 | 内容 |
| --- | --- | --- |
| **去重** | 每周 | 合并重复记忆 |
| **更新** | 按需 | 更新过时内容 |
| **归档** | 每月 | 归档历史记忆 |
| **清理** | 每季度 | 删除无用记忆 |
---
## 6.5 Hook 使用规范
### 6.5.1 Hook 类型
| Hook 类型 | 用途 | 示例 |
| --- | --- | --- |
| **pre-command** | 注入规范、加载上下文 | 自动加载 CLAUDE.md |
| **post-command** | 保存 Memory、更新索引 | 自动保存决策 |
| **pre-commit** | 代码审查、规范检查 | 自动运行 Lint |
| **file-change** | 自动格式化、更新索引 | 自动格式化代码 |
### 6.5.2 Hook 配置原则
| 原则 | 说明 |
| --- | --- |
| **最小化** | 只配置必要的 Hook |
| **幂等性** | Hook 执行结果可重复 |
| **可恢复** | Hook 失败不影响主流程 |
| **可观测** | Hook 执行有日志记录 |
---
## 6.6 团队协作技巧
### 6.6.1 冲突解决
| 冲突类型 | 解决策略 |
| --- | --- |
| **规范冲突** | 团队讨论，统一规范 |
| **技术分歧** | 头脑风暴，数据驱动 |
| **进度冲突** | 优先级排序，资源调整 |
| **质量冲突** | 制定标准，自动化检查 |
### 6.6.2 知识共享
| 方式 | 频率 | 内容 |
| --- | --- | --- |
| **技术分享** | 每周 | 新技术、最佳实践 |
| **代码走查** | 每次 PR | 代码逻辑、设计思路 |
| **文档同步** | 每月 | 文档更新、规范变更 |
| **问题复盘** | 每次事故 | 根因分析、改进措施 |
### 6.6.3 效率提升
| 技巧 | 效果 |
| --- | --- |
| **模板化** | 复用成功模式 |
| **自动化** | 减少重复工作 |
| **工具化** | 提升开发效率 |
| **标准化** | 降低沟通成本 |
---
## 6.7 快速参考
### 工作流选择指南
| 场景 | 工作流 | 命令 |
| --- | --- | --- |
| 新功能 | PlanEx | `/workflow:plan` |
| Bug 修复 | Lifecycle | `/unified-execute-with-file` |
| 重构 | IterDev | `/refactor-cycle` |
| 决策 | Brainstorm | `/brainstorm-with-file` |
| UI 开发 | UIDesign | `/workflow:ui-design` |
### 代码审查清单
- [ ] 正确性检查
- [ ] 性能检查
- [ ] 安全检查
- [ ] 可维护性检查
- [ ] 测试覆盖检查
- [ ] 规范符合检查
### Memory 维护
| 操作 | 命令 |
| --- | --- |
| 列出记忆 | `ccw memory list` |
| 搜索记忆 | `ccw memory search "..."` |
| 导入记忆 | `ccw memory import "..."` |
| 导出记忆 | `ccw memory export <id>` |
---
## 总结
Claude_dms3 的最佳实践可以总结为：
1. **规范先行** - 制定清晰的团队规范
2. **流程保障** - 使用合适的工作流
3. **质量把关** - 严格的代码审查
4. **知识沉淀** - 持续维护 Memory 和文档
5. **持续改进** - 定期复盘和优化
---
## 相关链接
- [Claude_dms3 是什么](ch01-what-is-claude-dms3.md)
- [快速开始](ch02-getting-started.md)
- [核心概念](ch03-core-concepts.md)
- [工作流基础](ch04-workflow-basics.md)
- [高级技巧](ch05-advanced-tips.md)

50
docs/zh/guide/getting-started.md Normal file
View File

@@ -0,0 +1,50 @@
# 快速入门
欢迎使用 CCW (Claude Code Workspace) - 一个先进的 AI 驱动开发环境，帮助您更快地编写更好的代码。
## 什么是 CCW？
CCW 是一个综合开发环境，结合了：
- **AI 驱动 CLI 工具**：使用多个 AI 后端进行分析、审查和实现代码
- **专业化代理**：前端、后端、测试和文档代理
- **工作流编排**：从规范到实现的 4 级工作流系统
- **可扩展技能**：27+ 内置技能，支持自定义技能
- **MCP 集成**：模型上下文协议，增强工具集成
## 快速开始
### 安装
```bash
# 全局安装 CCW
npm install -g @ccw/cli
# 或使用 npx
npx ccw --help
```
### 第一个工作流
在 5 分钟内创建一个简单工作流：
```bash
# 初始化新项目
ccw init my-project
# 分析现有代码
ccw cli -p "分析代码库结构" --mode analysis
# 实现新功能
ccw cli -p "添加用户认证" --mode write
```
## 下一步
- [安装指南](./installation.md) - 详细安装说明
- [第一个工作流](./first-workflow.md) - 30 分钟快速入门教程
- [配置指南](./configuration.md) - 自定义 CCW 设置
::: tip 需要帮助？
查看我们的 [GitHub Discussions](https://github.com/your-repo/ccw/discussions) 或加入 [Discord 社区](https://discord.gg/ccw)。
:::

118
docs/zh/guide/installation.md Normal file
View File

@@ -0,0 +1,118 @@
# 安装
了解如何在您的系统上安装和配置 CCW。
## 前置要求
安装 CCW 之前，请确保您有：
- **Node.js** >= 18.0.0
- **npm** >= 9.0.0 或 **yarn** >= 1.22.0
- **Git** 用于版本控制功能
## 安装 CCW
### 全局安装（推荐）
```bash
npm install -g @ccw/cli
```
### 项目特定安装
```bash
# 在您的项目目录中
npm install --save-dev @ccw/cli
# 使用 npx 运行
npx ccw [命令]
```
### 使用 Yarn
```bash
# 全局
yarn global add @ccw/cli
# 项目特定
yarn add -D @ccw/cli
```
## 验证安装
```bash
ccw --version
# 输出: CCW v1.0.0
ccw --help
# 显示所有可用命令
```
## 配置
### CLI 工具配置
创建或编辑 `~/.claude/cli-tools.json`：
```json
{
"version": "3.3.0",
"tools": {
"gemini": {
"enabled": true,
"primaryModel": "gemini-2.5-flash",
"secondaryModel": "gemini-2.5-flash",
"tags": ["分析", "调试"],
"type": "builtin"
},
"codex": {
"enabled": true,
"primaryModel": "gpt-5.2",
"secondaryModel": "gpt-5.2",
"tags": [],
"type": "builtin"
}
}
}
```
### CLAUDE.md 指令
在项目根目录创建 `CLAUDE.md`：
```markdown
# 项目指令
## 编码标准
- 使用 TypeScript 确保类型安全
- 遵循 ESLint 配置
- 为所有新功能编写测试
## 架构
- 前端: Vue 3 + Vite
- 后端: Node.js + Express
- 数据库: PostgreSQL
```
## 更新 CCW
```bash
# 更新到最新版本
npm update -g @ccw/cli
# 或安装特定版本
npm install -g @ccw/cli@latest
```
## 卸载
```bash
npm uninstall -g @ccw/cli
# 删除配置（可选）
rm -rf ~/.claude
```
::: info 下一步
安装完成后，查看[第一个工作流](./first-workflow.md)指南。
:::

11
docs/zh/index.md Normal file
View File

@@ -0,0 +1,11 @@
---
layout: page
title: CCW 文档
titleTemplate: Claude Code Workspace
---
<script setup>
import ProfessionalHome from '../.vitepress/theme/components/ProfessionalHome.vue'
</script>
<ProfessionalHome lang="zh" />

221
docs/zh/mcp/tools.md Normal file
View File

@@ -0,0 +1,221 @@
# MCP 工具参考
模型上下文协议 (MCP) 工具提供与外部系统和服务的增强集成。
## 什么是 MCP?
MCP 是一种协议，允许 CCW 通过标准化接口与外部工具、数据库和服务交互。
## 可用的 MCP 工具
### 文件操作
#### mcp__ccw-tools__read_file
读取支持分页的文件内容。
```json
{
"name": "read_file",
"parameters": {
"path": "string (必需)",
"offset": "number (可选)",
"limit": "number (可选)"
}
}
```
**用法:**
```javascript
read_file({ path: "src/index.ts" })
read_file({ path: "large-file.log", offset: 100, limit: 50 })
```
#### mcp__ccw-tools__write_file
写入或覆盖文件，支持目录创建。
```json
{
"name": "write_file",
"parameters": {
"path": "string (必需)",
"content": "string (必需)",
"createDirectories": "boolean (默认: true)",
"backup": "boolean (默认: false)"
}
}
```
**用法:**
```javascript
write_file({
path: "src/new-file.ts",
content: "// TypeScript 代码在这里"
})
```
#### mcp__ccw-tools__edit_file
使用字符串替换或基于行的操作编辑文件。
```json
{
"name": "edit_file",
"parameters": {
"path": "string (必需)",
"mode": "update | line (默认: update)",
"oldText": "string (更新模式)",
"newText": "string (更新模式)",
"line": "number (行模式)",
"operation": "insert_before | insert_after | replace | delete (行模式)"
}
}
```
**用法:**
```javascript
// 更新模式 - 字符串替换
edit_file({
path: "config.json",
oldText: '"version": "1.0.0"',
newText: '"version": "2.0.0"'
})
// 行模式 - 在第 10 行后插入
edit_file({
path: "index.ts",
mode: "line",
operation: "insert_after",
line: 10,
text: "// 新代码在这里"
})
```
### 搜索工具
#### mcp__ccw-tools__smart_search
统一搜索，支持内容搜索、文件发现和语义搜索。
```json
{
"name": "smart_search",
"parameters": {
"action": "search | find_files | init | status",
"query": "string (用于搜索)",
"pattern": "glob 模式 (用于 find_files)",
"mode": "fuzzy | semantic (默认: fuzzy)",
"output_mode": "full | files_only | count",
"maxResults": "number (默认: 20)"
}
}
```
**用法:**
```javascript
// 模糊搜索 (默认)
smart_search({
action: "search",
query: "身份验证逻辑"
})
// 语义搜索
smart_search({
action: "search",
query: "如何处理错误",
mode: "semantic"
})
// 按模式查找文件
smart_search({
action: "find_files",
pattern: "*.ts"
})
```
### 代码上下文
#### mcp__ace-tool__search_context
使用实时代码库索引的语义代码搜索。
```json
{
"name": "search_context",
"parameters": {
"project_root_path": "string (必需)",
"query": "string (必需)"
}
}
```
**用法:**
```javascript
search_context({
project_root_path: "/path/to/project",
query: "用户身份验证在哪里处理?"
})
```
### 记忆工具
#### mcp__ccw-tools__core_memory
跨会话记忆管理，用于战略上下文。
```json
{
"name": "core_memory",
"parameters": {
"operation": "list | import | export | summary | embed | search",
"text": "string (用于导入)",
"id": "string (用于导出/摘要)",
"query": "string (用于搜索)"
}
}
```
**用法:**
```javascript
// 列出所有记忆
core_memory({ operation: "list" })
// 导入新记忆
core_memory({
operation: "import",
text: "重要: 使用 JWT 进行身份验证"
})
// 搜索记忆
core_memory({
operation: "search",
query: "身份验证"
})
```
## MCP 配置
在 `~/.claude/mcp.json` 中配置 MCP 服务器:
```json
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
},
"git": {
"command": "npx",
"args": ["@modelcontextprotocol/server-git"]
}
}
}
```
## 工具优先级
使用 CCW 时，遵循此工具选择优先级:
1. **MCP 工具** (最高优先级) - 用于代码搜索、文件操作
2. **内置工具** - 用于简单、直接的操作
3. **Shell 命令** - MCP 不可用时的回退
::: info 另请参阅
- [CLI 参考](../cli/commands.md) - CLI 工具使用
- [代理](../agents/) - 代理工具集成
:::

332
docs/zh/skills/claude-collaboration.md Normal file
View File

@@ -0,0 +1,332 @@
# Claude Skills - 团队协作类
## 一句话定位
**团队协作类 Skills 是多角色协同工作的编排系统** — 通过协调器、工作者角色和消息总线实现复杂任务的并行处理和状态同步。
## 解决的痛点
| 痛点 | 现状 | Claude_dms3 方案 |
| --- | --- | --- |
| **单模型局限** | 只能调用一个 AI 模型 | 多角色并行协作，发挥各自专长 |
| **任务编排混乱** | 手动管理任务依赖和状态 | 自动任务发现、依赖解析、流水线编排 |
| **协作流程割裂** | 团队成员各自为战 | 统一消息总线、共享状态、进度同步 |
| **资源浪费** | 重复上下文加载 | Wisdom 累积、探索缓存、产物复用 |
## Skills 列表
| Skill | 功能 | 触发方式 |
| --- | --- | --- |
| `team-coordinate` | 通用团队协调器（动态角色生成） | `/team-coordinate` |
| `team-lifecycle-v5` | 全生命周期团队（规范→实现→测试→审查） | `/team-lifecycle` |
| `team-planex` | 规划-执行流水线（边规划边执行） | `/team-planex` |
| `team-review` | 代码审查团队（扫描→审查→修复） | `/team-review` |
| `team-testing` | 测试团队（策略→生成→执行→分析） | `/team-testing` |
## Skills 详解
### team-coordinate
**一句话定位**: 通用团队协调器 — 根据任务分析动态生成角色并编排执行
**触发**:
```
/team-coordinate <task-description>
/team-coordinate --role=coordinator <task>
/team-coordinate --role=<worker> --session=<path>
```
**功能**:
- 只有 coordinator 是内置的，所有工作者角色都是运行时动态生成
- 支持内循环角色（处理多个同前缀任务）
- Fast-Advance 机制跳过协调器直接派生后继任务
- Wisdom 累积跨任务知识
**角色注册表**:
| 角色 | 文件 | 任务前缀 | 类型 |
|------|------|----------|------|
| coordinator | roles/coordinator/role.md | (无) | 编排器 |
| (动态) | `<session>/roles/<role>.md` | (动态) | 工作者 |
**流水线**:
```
任务分析 → 生成角色 → 初始化会话 → 创建任务链 → 派生首批工作者 → 循环推进 → 完成报告
```
**会话目录**:
```
.workflow/.team/TC-<slug>-<date>/
├── team-session.json # 会话状态 + 动态角色注册表
├── task-analysis.json # Phase 1 输出
├── roles/ # 动态角色定义
├── artifacts/ # 所有 MD 交付产物
├── wisdom/ # 跨任务知识
├── explorations/ # 共享探索缓存
├── discussions/ # 内联讨论记录
└── .msg/ # 团队消息总线日志
```
---
### team-lifecycle-v5
**一句话定位**: 全生命周期团队 — 从规范到实现到测试到审查的完整流水线
**触发**:
```
/team-lifecycle <task-description>
```
**功能**:
- 基于 team-worker agent 架构，所有工作者共享同一代理定义
- 角色特定的 Phase 2-4 从 markdown 规范加载
- 支持规范流水线、实现流水线、前端流水线
**角色注册表**:
| 角色 | 规范 | 任务前缀 | 内循环 |
|------|------|----------|--------|
| coordinator | roles/coordinator/role.md | (无) | - |
| analyst | role-specs/analyst.md | RESEARCH-* | false |
| writer | role-specs/writer.md | DRAFT-* | true |
| planner | role-specs/planner.md | PLAN-* | true |
| executor | role-specs/executor.md | IMPL-* | true |
| tester | role-specs/tester.md | TEST-* | false |
| reviewer | role-specs/reviewer.md | REVIEW-* | false |
| architect | role-specs/architect.md | ARCH-* | false |
| fe-developer | role-specs/fe-developer.md | DEV-FE-* | false |
| fe-qa | role-specs/fe-qa.md | QA-FE-* | false |
**流水线定义**:
```
规范流水线 (6 任务):
RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001
实现流水线 (4 任务):
PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
全生命周期 (10 任务):
[规范流水线] → PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
前端流水线:
PLAN-001 → DEV-FE-001 → QA-FE-001 (GC 循环，最多 2 轮)
```
**质量关卡** (QUALITY-001 完成后):
```
═════════════════════════════════════════
SPEC PHASE COMPLETE
Quality Gate: <PASS|REVIEW|FAIL> (<score>%)
Dimension Scores:
Completeness: <bar> <n>%
Consistency: <bar> <n>%
Traceability: <bar> <n>%
Depth: <bar> <n>%
Coverage: <bar> <n>%
Available Actions:
resume -> Proceed to implementation
improve -> Auto-improve weakest dimension
improve <dimension> -> Improve specific dimension
revise <TASK-ID> -> Revise specific document
recheck -> Re-run quality check
feedback <text> -> Inject feedback, create revision
═════════════════════════════════════════
```
**用户命令** (唤醒暂停的协调器):
| 命令 | 动作 |
|------|------|
| `check` / `status` | 输出执行状态图，不推进 |
| `resume` / `continue` | 检查工作者状态，推进下一步 |
| `revise <TASK-ID> [feedback]` | 创建修订任务 + 级联下游 |
| `feedback <text>` | 分析反馈影响，创建定向修订链 |
| `recheck` | 重新运行 QUALITY-001 质量检查 |
| `improve [dimension]` | 自动改进 readiness-report 中最弱维度 |
---
### team-planex
**一句话定位**: 边规划边执行团队 — 通过逐 Issue 节拍流水线实现 planner 和 executor 并行工作
**触发**:
```
/team-planex <task-description>
/team-planex --role=planner <input>
/team-planex --role=executor --input <solution-file>
```
**功能**:
- 2 成员团队（planner + executor），planner 担任 lead 角色
- 逐 Issue 节拍：planner 每完成一个 issue 的 solution 后立即创建 EXEC-* 任务
- Solution 写入中间产物文件，executor 从文件加载
- 支持多种执行后端（agent/codex/gemini）
**角色注册表**:
| 角色 | 文件 | 任务前缀 | 类型 |
|------|------|----------|------|
| planner | roles/planner.md | PLAN-* | pipeline (lead) |
| executor | roles/executor.md | EXEC-* | pipeline |
**输入类型**:
| 输入类型 | 格式 | 示例 |
|----------|------|------|
| Issue IDs | 直接传入 ID | `--role=planner ISS-20260215-001 ISS-20260215-002` |
| 需求文本 | `--text '...'` | `--role=planner --text '实现用户认证模块'` |
| Plan 文件 | `--plan path` | `--role=planner --plan plan/2026-02-15-auth.md` |
**Wave Pipeline** (逐 Issue 节拍):
```
Issue 1: planner 规划 solution → 写中间产物 → 冲突检查 → 创建 EXEC-* → issue_ready
↓ (executor 立即开始)
Issue 2: planner 规划 solution → 写中间产物 → 冲突检查 → 创建 EXEC-* → issue_ready
↓ (executor 并行消费)
Issue N: ...
Final: planner 发送 all_planned → executor 完成剩余 EXEC-* → 结束
```
**执行方法选择**:
| 执行器 | 后端 | 适用场景 |
|--------|------|----------|
| `agent` | code-developer subagent | 简单任务、同步执行 |
| `codex` | `ccw cli --tool codex --mode write` | 复杂任务、后台执行 |
| `gemini` | `ccw cli --tool gemini --mode write` | 分析类任务、后台执行 |
**用户命令**:
| 命令 | 动作 |
|------|------|
| `check` / `status` | 输出执行状态图，不推进 |
| `resume` / `continue` | 检查工作者状态，推进下一步 |
| `add <issue-ids or --text '...' or --plan path>` | 追加新任务到 planner 队列 |
---
### team-review
**一句话定位**: 代码审查团队 — 统一的代码扫描、漏洞审查、优化建议和自动修复
**触发**:
```
/team-review <target-path>
/team-review --full <target-path> # scan + review + fix
/team-review --fix <review-files> # fix only
/team-review -q <target-path> # quick scan only
```
**功能**:
- 4 角色团队（coordinator, scanner, reviewer, fixer）
- 多维度审查：安全性、正确性、性能、可维护性
- 自动修复循环（审查 → 修复 → 验证）
**角色注册表**:
| 角色 | 文件 | 任务前缀 | 类型 |
|------|------|----------|------|
| coordinator | roles/coordinator/role.md | RC-* | 编排器 |
| scanner | roles/scanner/role.md | SCAN-* | 只读分析 |
| reviewer | roles/reviewer/role.md | REV-* | 只读分析 |
| fixer | roles/fixer/role.md | FIX-* | 代码生成 |
**流水线** (CP-1 Linear):
```
coordinator dispatch
→ SCAN-* (scanner: 工具链 + LLM 扫描)
→ REV-* (reviewer: 深度分析 + 报告)
→ [用户确认]
→ FIX-* (fixer: 规划 + 执行 + 验证)
```
**检查点**:
| 触发 | 位置 | 行为 |
|------|------|------|
| Review→Fix 过渡 | REV-* 完成 | 暂停，展示审查报告，等待用户 `resume` 确认修复 |
| 快速模式 (`-q`) | SCAN-* 后 | 流水线在扫描后结束，无审查/修复 |
| 仅修复模式 (`--fix`) | 入口 | 跳过扫描/审查，直接进入 fixer |
**审查维度**:
| 维度 | 检查点 |
|------|--------|
| 安全性 (sec) | 注入漏洞、敏感信息泄露、权限控制 |
| 正确性 (cor) | 边界条件、错误处理、类型安全 |
| 性能 (perf) | 算法复杂度、I/O 优化、资源使用 |
| 可维护性 (maint) | 代码结构、命名规范、注释质量 |
---
### team-testing
**一句话定位**: 测试团队 — 通过 Generator-Critic 循环实现渐进式测试覆盖
**触发**:
```
/team-testing <task-description>
```
**功能**:
- 5 角色团队（coordinator, strategist, generator, executor, analyst）
- 三种流水线：Targeted、Standard、Comprehensive
- Generator-Critic 循环自动改进测试覆盖率
**角色注册表**:
| 角色 | 文件 | 任务前缀 | 类型 |
|------|------|----------|------|
| coordinator | roles/coordinator.md | (无) | 编排器 |
| strategist | roles/strategist.md | STRATEGY-* | pipeline |
| generator | roles/generator.md | TESTGEN-* | pipeline |
| executor | roles/executor.md | TESTRUN-* | pipeline |
| analyst | roles/analyst.md | TESTANA-* | pipeline |
**三种流水线**:
```
Targeted (小范围变更):
STRATEGY-001 → TESTGEN-001(L1 unit) → TESTRUN-001
Standard (渐进式):
STRATEGY-001 → TESTGEN-001(L1) → TESTRUN-001(L1) → TESTGEN-002(L2) → TESTRUN-002(L2) → TESTANA-001
Comprehensive (完整覆盖):
STRATEGY-001 → [TESTGEN-001(L1) + TESTGEN-002(L2)](并行) → [TESTRUN-001(L1) + TESTRUN-002(L2)](并行) → TESTGEN-003(L3) → TESTRUN-003(L3) → TESTANA-001
```
**Generator-Critic 循环**:
```
TESTGEN → TESTRUN → (如果覆盖率 < 目标) → TESTGEN-fix → TESTRUN-2
(如果覆盖率 >= 目标) → 下一层或 TESTANA
```
**测试层定义**:
| 层级 | 覆盖目标 | 示例 |
|------|----------|------|
| L1: Unit | 80% | 单元测试、函数级测试 |
| L2: Integration | 60% | 集成测试、模块间交互 |
| L3: E2E | 40% | 端到端测试、用户场景 |
**共享内存** (shared-memory.json):
| 角色 | 字段 |
|------|------|
| strategist | `test_strategy` |
| generator | `generated_tests` |
| executor | `execution_results`, `defect_patterns` |
| analyst | `analysis_report`, `coverage_history` |
## 相关命令
- [Claude Commands - Workflow](../commands/claude/workflow.md)
- [Claude Commands - Session](../commands/claude/session.md)
## 最佳实践
1. **选择合适的团队类型**:
- 通用任务 → `team-coordinate`
- 完整功能开发 → `team-lifecycle`
- Issue 批处理 → `team-planex`
- 代码审查 → `team-review`
- 测试覆盖 → `team-testing`
2. **利用内循环角色**: 对于有多个同前缀串行任务的角色，设置 `inner_loop: true` 让单个工作者处理全部任务，避免重复派生开销
3. **Wisdom 累积**: 团队会话中的所有角色都会累积知识到 `wisdom/` 目录，后续任务可复用这些模式、决策和约定
4. **Fast-Advance**: 简单线性后继任务会自动跳过协调器直接派生，减少协调开销
5. **断点恢复**: 所有团队技能支持会话恢复，通过 `--resume` 或用户命令 `resume` 继续中断的会话

267
docs/zh/skills/claude-index.md Normal file
View File

@@ -0,0 +1,267 @@
# Claude Skills 总览
## 一句话定位
**Claude Skills 是 VS Code 扩展的 AI 技能系统** — 通过团队协作、工作流、记忆管理、代码审查和元技能五大类别，实现从规范到实现到测试到审查的完整开发流程自动化。
## vs 传统方法对比
| 维度 | 传统方式 | **Claude_dms3** |
| --- | --- | --- |
| 任务编排 | 手动管理 | 自动流水线编排 |
| AI 模型 | 单一模型 | 多模型并行协作 |
| 代码审查 | 手动审查 | 6 维度自动审查 |
| 知识管理 | 随会话丢失 | 跨会话持久化 |
| 开发流程 | 人工驱动 | AI 驱动自动化 |
## Skills 类别
| 类别 | 文档 | 说明 |
|------|------|------|
| **团队协作** | [collaboration.md](./claude-collaboration.md) | 多角色协同工作编排系统 |
| **工作流** | [workflow.md](./claude-workflow.md) | 任务编排和执行流水线 |
| **记忆管理** | [memory.md](./claude-memory.md) | 跨会话知识持久化 |
| **代码审查** | [review.md](./claude-review.md) | 多维度代码质量分析 |
| **元技能** | [meta.md](./claude-meta.md) | 创建和管理其他技能 |
## 核心概念速览
| 概念 | 说明 | 位置/命令 |
| --- | --- | --- |
| **team-coordinate** | 通用团队协调器（动态角色） | `/team-coordinate` |
| **team-lifecycle** | 全生命周期团队 | `/team-lifecycle` |
| **team-planex** | 边规划边执行团队 | `/team-planex` |
| **workflow-plan** | 统一规划技能 | `/workflow:plan` |
| **workflow-execute** | 代理协调执行 | `/workflow:execute` |
| **memory-capture** | 记忆捕获 | `/memory-capture` |
| **review-code** | 多维度代码审查 | `/review-code` |
| **brainstorm** | 头脑风暴 | `/brainstorm` |
| **spec-generator** | 规范生成器 | `/spec-generator` |
| **ccw-help** | 命令帮助系统 | `/ccw-help` |
## 团队协作 Skills
### 团队架构模型
Claude_dms3 支持两种团队架构模型：
1. **team-coordinate** (通用协调器)
- 只有 coordinator 是内置的
- 所有工作者角色都是运行时动态生成
- 支持任意任务类型的动态团队
2. **team-lifecycle-v5** (全生命周期团队)
- 基于 team-worker agent 架构
- 所有工作者共享同一代理定义
- 角色特定的 Phase 2-4 从 markdown 规范加载
### 团队类型对比
| 团队类型 | 角色 | 用途 |
|---------|------|------|
| **team-coordinate** | coordinator + 动态角色 | 通用任务编排 |
| **team-lifecycle** | 9 种预定义角色 | 规范→实现→测试→审查 |
| **team-planex** | planner + executor | 边规划边执行 |
| **team-review** | coordinator + scanner + reviewer + fixer | 代码审查和修复 |
| **team-testing** | coordinator + strategist + generator + executor + analyst | 测试覆盖 |
## 工作流 Skills
### 工作流级别
| 级别 | 名称 | 工作流 | 适用场景 |
|------|------|--------|----------|
| Level 1 | Lite-Lite-Lite | lite-plan | 超简单快速任务 |
| Level 2 | Rapid | plan → execute | Bug 修复、简单功能 |
| Level 2.5 | Rapid-to-Issue | plan → issue:new | 从快速规划到 Issue |
| Level 3 | Coupled | plan → execute | 复杂功能（规划+执行+审查+测试） |
| Level 4 | Full | brainstorm → plan → execute | 探索性任务 |
| With-File | 文档化探索 | analyze/brainstorm/debug-with-file | 多 CLI 协作分析 |
### 工作流选择指南
```
任务复杂度
↓
┌───┴────┬────────────┬─────────────┐
│ │ │ │
简单 中等 复杂 探索性
│ │ │ │
↓ ↓ ↓ ↓
lite-plan plan plan brainstorm
↓ ↓ ↓
execute brainstorm plan
↓ ↓
plan execute
↓
execute
```
## 记忆管理 Skills
### Memory 类型
| 类型 | 格式 | 用途 |
|------|------|------|
| **会话压缩** | 结构化文本 | 长对话后的完整上下文保存 |
| **快速笔记** | 带 tags 的笔记 | 快速记录想法和洞察 |
### Memory 存储
```
memory/
├── MEMORY.md # 主记忆文件（行数限制）
├── debugging.md # 调试模式和洞察
├── patterns.md # 代码模式和约定
├── conventions.md # 项目约定
└── [topic].md # 其他主题文件
```
## 代码审查 Skills
### 审查维度
| 维度 | 检查点 | 工具 |
|------|--------|------|
| **Correctness** | 逻辑正确性、边界条件 | review-code |
| **Readability** | 命名、函数长度、注释 | review-code |
| **Performance** | 算法复杂度、I/O 优化 | review-code |
| **Security** | 注入、敏感信息 | review-code |
| **Testing** | 测试充分性 | review-code |
| **Architecture** | 设计模式、分层 | review-code |
### 问题严重程度
| 级别 | 前缀 | 描述 | 所需操作 |
|------|------|------|----------|
| Critical | [C] | 阻塞性问题 | 合并前必须修复 |
| High | [H] | 重要问题 | 应该修复 |
| Medium | [M] | 建议改进 | 考虑修复 |
| Low | [L] | 可选优化 | 有则更好 |
| Info | [I] | 信息性建议 | 仅供参考 |
## 元技能
### 元技能列表
| 技能 | 功能 | 用途 |
|------|------|------|
| **spec-generator** | 6 阶段规范生成 | 产品简报、PRD、架构、Epics |
| **brainstorm** | 多角色并行分析 | 多视角头脑风暴 |
| **skill-generator** | Skill 创建 | 生成新的 Claude Skills |
| **skill-tuning** | Skill 调优 | 诊断和优化 |
| **ccw-help** | 命令帮助 | 搜索、推荐、文档 |
| **command-generator** | 命令生成 | 生成 Claude 命令 |
| **issue-manage** | Issue 管理 | Issue 创建和状态管理 |
## 快速开始
### 1. 选择团队类型
```bash
# 通用任务
/team-coordinate "Build user authentication system"
# 完整功能开发
/team-lifecycle "Create REST API for user management"
# Issue 批处理
/team-planex ISS-20260215-001 ISS-20260215-002
# 代码审查
/team-review src/auth/**
```
### 2. 选择工作流
```bash
# 快速任务
/workflow:lite-plan "Fix login bug"
# 完整开发
/workflow:plan "Add user notifications"
/workflow:execute
# TDD 开发
/workflow:tdd "Implement payment processing"
```
### 3. 使用记忆管理
```bash
# 压缩会话
/memory-capture compact
# 快速笔记
/memory-capture tip "Use Redis for rate limiting" --tag config
```
### 4. 代码审查
```bash
# 完整审查（6 维度）
/review-code src/auth/**
# 审查特定维度
/review-code --dimensions=sec,perf src/api/
```
### 5. 元技能
```bash
# 生成规范
/spec-generator "Build real-time collaboration platform"
# 头脑风暴
/brainstorm "Design payment system" --count 3
# 获取帮助
/ccw "Add JWT authentication"
```
## 最佳实践
1. **团队选择**:
- 通用任务 → `team-coordinate`
- 完整功能 → `team-lifecycle`
- Issue 批处理 → `team-planex`
- 代码审查 → `team-review`
- 测试覆盖 → `team-testing`
2. **工作流选择**:
- 超简单 → `workflow-lite-plan`
- 复杂功能 → `workflow-plan` → `workflow-execute`
- TDD → `workflow-tdd`
- 测试修复 → `workflow-test-fix`
3. **记忆管理**:
- 长对话后使用 `memory-capture compact`
- 快速记录想法使用 `memory-capture tip`
- 定期使用 `memory-manage full` 合并和压缩
4. **代码审查**:
- 执行审查前完整阅读规范文档
- 使用 `--dimensions` 指定关注维度
- 先快速扫描识别高风险，再深入审查
5. **元技能**:
- 使用 `spec-generator` 生成完整规范包
- 使用 `brainstorm` 获得多视角分析
- 使用 `ccw-help` 查找合适的命令
## 相关文档
- [Claude Commands](../commands/claude/)
- [Codex Skills](./codex-index.md)
- [功能文档](../features/)
## 统计数据
| 类别 | 数量 |
|------|------|
| 团队协作 Skills | 5 |
| 工作流 Skills | 8 |
| 记忆管理 Skills | 2 |
| 代码审查 Skills | 2 |
| 元技能 | 7 |
| **总计** | **24+** |

181
docs/zh/skills/claude-memory.md Normal file
View File

@@ -0,0 +1,181 @@
# Claude Skills - 记忆管理类
## 一句话定位
**记忆管理类 Skills 是跨会话知识持久化系统** — 通过 Memory 压缩、Tips 记录和 Memory 更新实现 AI 记忆项目上下文。
## 解决的痛点
| 痛点 | 现状 | Claude_dms3 方案 |
| --- | --- | --- |
| **新会话失忆** | 每次对话需要重新解释项目背景 | Memory 持久化上下文 |
| **知识流失** | 有价值的洞察和决策随会话消失 | Memory 压缩和 Tips 记录 |
| **上下文窗口限制** | 长对话后上下文超出窗口 | Memory 提取和合并 |
| **知识检索困难** | 难以找到历史记录 | Memory 搜索和嵌入 |
## Skills 列表
| Skill | 功能 | 触发方式 |
| --- | --- | --- |
| `memory-capture` | 统一记忆捕获（会话压缩/快速笔记） | `/memory-capture` |
| `memory-manage` | Memory 更新（全量/关联/单条） | `/memory-manage` |
## Skills 详解
### memory-capture
**一句话定位**: 统一记忆捕获 — 会话压缩或快速笔记的双模式路由
**触发**:
```
/memory-capture # 交互选择模式
/memory-capture compact # 会话压缩模式
/memory-capture tip "Note content" # 快速笔记模式
/memory-capture "Use Redis" --tag config # 带标签笔记
```
**功能**:
- 双模式路由：自动检测用户意图，路由到压缩模式或笔记模式
- **Compact 模式**: 压缩完整会话记忆为结构化文本，用于会话恢复
- **Tips 模式**: 快速记录想法、片段、洞察
**架构概览**:
```
┌─────────────────────────────────────────────┐
│ Memory Capture (Router) │
│ → 解析输入 → 检测模式 → 路由到阶段 │
└───────────────┬─────────────────────────────┘
│
┌───────┴───────┐
↓ ↓
┌───────────┐ ┌───────────┐
│ Compact │ │ Tips │
│ (Phase1) │ │ (Phase2) │
│ Full │ │ Quick │
│ Session │ │ Note │
└─────┬─────┘ └─────┬─────┘
│ │
└───────┬───────┘
↓
┌───────────────┐
│ core_memory │
│ (import) │
└───────────────┘
```
**自动路由规则**（优先级顺序）:
| 信号 | 路由 | 示例 |
|------|------|------|
| 关键词: compact, session, 压缩, recovery | → Compact | "压缩当前会话" |
| 关键词: tip, note, 记录, 快速 | → Tips | "记录一个想法" |
| 有 `--tag` 或 `--context` 标志 | → Tips | `"note content" --tag bug` |
| 短文本 (<100 字符) + 无会话关键词 | → Tips | "Remember to use Redis" |
| 模糊或无参数 | → **AskUserQuestion** | `/memory-capture` |
**Compact 模式**:
- 用途: 压缩当前完整会话记忆（用于会话恢复）
- 输入: 可选 `"session description"` 作为补充上下文
- 输出: 结构化文本 + Recovery ID
- 示例: `/memory-capture compact` 或 `/memory-capture "完成认证模块"`
**Tips 模式**:
- 用途: 快速记录一条笔记/想法/提示
- 输入:
- 必需: `<note content>` - 笔记文本
- 可选: `--tag <tag1,tag2>` 分类
- 可选: `--context <context>` 关联代码/功能引用
- 输出: 确认 + ID + tags
- 示例: `/memory-capture tip "Use Redis for rate limiting" --tag config`
**核心规则**:
1. **单阶段执行**: 每次调用只执行一个阶段 — 不同时执行两个
2. **内容忠实**: 阶段文件包含完整执行细节 — 完全遵循
3. **绝对路径**: 输出中的所有文件路径必须是绝对路径
4. **无摘要**: Compact 模式保留完整计划 — 永不缩写
5. **速度优先**: Tips 模式应该快速 — 最小分析开销
---
### memory-manage
**一句话定位**: Memory 更新 — 全量/关联/单条更新模式
**触发**:
```
/memory-manage # 交互模式
/memory-manage full # 全量更新
/memory-manage related <query> # 关联更新
/memory-manage single <id> <content> # 单条更新
```
**功能**:
- 三种更新模式：全量更新、关联更新、单条更新
- Memory 搜索和嵌入
- Memory 合并和压缩
**更新模式**:
| 模式 | 触发 | 说明 |
|------|------|------|
| **full** | `full` 或 `-f` | 重新生成所有 Memory |
| **related** | `related <query>` 或 `-r <query>` | 更新与查询相关的 Memory |
| **single** | `single <id> <content>` 或 `-s <id> <content>` | 更新单条 Memory |
**Memory 存储**:
- 位置: `C:\Users\dyw\.claude\projects\D--ccw-doc2\memory\`
- 文件: MEMORY.md（主记忆文件，行数超过 200 后截断）
- 主题文件: 按主题组织的独立记忆文件
**Memory 类型**:
| 类型 | 格式 | 说明 |
|------|------|------|
| `CMEM-YYYYMMDD-HHMMSS` | 时间戳格式 | 带时间戳的持久记忆 |
| Topic files | `debugging.md`, `patterns.md` | 按主题组织的记忆 |
**核心规则**:
1. **优先更新**: 在现有记忆上更新，而非写入重复内容
2. **主题组织**: 创建按主题分类的独立记忆文件
3. **删除过时**: 删除最终被证明错误或过时的记忆条目
4. **会话特定**: 不保存会话特定上下文（当前任务、进行中工作、临时状态）
## 相关命令
- [Memory 功能文档](../features/memory.md)
- [CCW CLI Tools](../features/cli.md)
## 最佳实践
1. **会话压缩**: 长对话后使用 `memory-capture compact` 保存完整上下文
2. **快速笔记**: 使用 `memory-capture tip` 快速记录想法和洞察
3. **标签分类**: 使用 `--tag` 为笔记添加标签，便于后续检索
4. **Memory 搜索**: 使用 `memory-manage related <query>` 查找相关记忆
5. **定期合并**: 定期使用 `memory-manage full` 合并和压缩记忆
## Memory 文件结构
```
memory/
├── MEMORY.md # 主记忆文件（行数限制）
├── debugging.md # 调试模式和洞察
├── patterns.md # 代码模式和约定
├── conventions.md # 项目约定
└── [topic].md # 其他主题文件
```
## 使用示例
```bash
# 压缩当前会话
/memory-capture compact
# 快速记录一个想法
/memory-capture tip "Use Redis for rate limiting" --tag config
# 记录带上下文的笔记
/memory-capture "认证模块使用 JWT" --context "src/auth/"
# 更新相关记忆
/memory-manage related "认证"
# 全量更新记忆
/memory-manage full
```

439
docs/zh/skills/claude-meta.md Normal file
View File

@@ -0,0 +1,439 @@
# Claude Skills - 元技能类
## 一句话定位
**元技能类 Skills 是创建和管理其他技能的工具系统** — 通过规范生成、Skill 生成、命令生成和帮助系统实现技能生态的可持续发展。
## 解决的痛点
| 痛点 | 现状 | Claude_dms3 方案 |
| --- | --- | --- |
| **Skill 创建复杂** | 手动创建 Skill 结构和文件 | 自动化 Skill 生成 |
| **规范缺失** | 项目规范散落各处 | 统一规范生成系统 |
| **命令发现困难** | 难以找到合适的命令 | 智能命令推荐和搜索 |
| **技能调优繁琐** | 技能优化缺乏指导 | 自动化诊断和调优 |
## Skills 列表
| Skill | 功能 | 触发方式 |
| --- | --- | --- |
| `spec-generator` | 规范生成器（6 阶段文档链） | `/spec-generator <idea>` |
| `brainstorm` | 头脑风暴（多角色并行分析） | `/brainstorm <topic>` |
| `skill-generator` | Skill 生成器（元技能） | `/skill-generator` |
| `skill-tuning` | Skill 调优诊断 | `/skill-tuning <skill-name>` |
| `command-generator` | 命令生成器 | `/command-generator` |
| `ccw-help` | CCW 命令帮助系统 | `/ccw-help` |
| `issue-manage` | Issue 管理 | `/issue-manage` |
## Skills 详解
### spec-generator
**一句话定位**: 规范生成器 — 6 阶段文档链生成完整规范包（产品简报、PRD、架构、Epics）
**触发**:
```
/spec-generator <idea>
/spec-generator --continue # 从断点恢复
/spec-generator -y <idea> # 自动模式
```
**功能**:
- 6 阶段文档链：发现 → 需求扩展 → 产品简报 → PRD → 架构 → Epics → 就绪检查
- 多视角分析：CLI 工具（Gemini/Codex/Claude）提供产品、技术、用户视角
- 交互式默认：每个阶段提供用户确认点；`-y` 标志启用全自动模式
- 可恢复会话：`spec-config.json` 跟踪已完成阶段；`-c` 标志从断点恢复
- 纯文档：无代码生成或执行 — 干净移交给现有执行工作流
**架构概览**:
```
Phase 0: Specification Study (Read specs/ + templates/ - mandatory prerequisite)
|
Phase 1: Discovery -> spec-config.json + discovery-context.json
|
Phase 1.5: Req Expansion -> refined-requirements.json (interactive discussion + CLI gap analysis)
| (-y auto mode: auto-expansion, skip interaction)
Phase 2: Product Brief -> product-brief.md (multi-CLI parallel analysis)
|
Phase 3: Requirements (PRD) -> requirements/ (_index.md + REQ-*.md + NFR-*.md)
|
Phase 4: Architecture -> architecture/ (_index.md + ADR-*.md, multi-CLI review)
|
Phase 5: Epics & Stories -> epics/ (_index.md + EPIC-*.md)
|
Phase 6: Readiness Check -> readiness-report.md + spec-summary.md
|
Handoff to execution workflows
```
**⚠️ 强制前置条件**:
> **不要跳过**: 在执行任何操作之前，**必须**完整阅读以下文档。
**规范文档**（必读）:
| 文档 | 用途 | 优先级 |
|------|------|--------|
| [specs/document-standards.md](specs/document-standards.md) | 文档格式、frontmatter、命名约定 | **P0 - 执行前必读** |
| [specs/quality-gates.md](specs/quality-gates.md) | 每阶段质量关卡标准和评分 | **P0 - 执行前必读** |
**模板文件**（生成前必读）:
| 文档 | 用途 |
|------|------|
| [templates/product-brief.md](templates/product-brief.md) | 产品简报文档模板 |
| [templates/requirements-prd.md](templates/requirements-prd.md) | PRD 文档模板 |
| [templates/architecture-doc.md](templates/architecture-doc.md) | 架构文档模板 |
| [templates/epics-template.md](templates/epics-template.md) | Epic/Story 文档模板 |
**输出结构**:
```
.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/
├── spec-config.json # 会话配置 + 阶段状态
├── discovery-context.json # 代码库探索结果（可选）
├── refined-requirements.json # Phase 1.5: 讨论后确认的需求
├── product-brief.md # Phase 2: 产品简报
├── requirements/ # Phase 3: 详细 PRD（目录）
│ ├── _index.md # 摘要、MoSCoW 表、可追溯性、链接
│ ├── REQ-NNN-{slug}.md # 单个功能需求
│ └── NFR-{type}-NNN-{slug}.md # 单个非功能需求
├── architecture/ # Phase 4: 架构决策（目录）
│ ├── _index.md # 摘要、组件、技术栈、链接
│ └── ADR-NNN-{slug}.md # 单个架构决策记录
├── epics/ # Phase 5: Epic/Story 分解（目录）
│ ├── _index.md # Epic 表、依赖图、MVP 范围
│ └── EPIC-NNN-{slug}.md # 单个 Epic 及 Stories
├── readiness-report.md # Phase 6: 质量报告
└── spec-summary.md # Phase 6: 一页执行摘要
```
**移交选项**（Phase 6 完成后）:
| 选项 | 说明 |
|------|------|
| `lite-plan` | 提取第一个 MVP Epic 描述 → 直接文本输入 |
| `plan` / `req-plan` | 创建 WFS 会话 + .brainstorming/ 桥接文件 |
| `issue:new` | 为每个 Epic 创建 Issue |
---
### brainstorm
**一句话定位**: 头脑风暴 — 交互式框架生成、多角色并行分析和跨角色综合
**触发**:
```
/brainstorm <topic>
/brainstorm --count 3 "Build platform"
/brainstorm -y "GOAL: Build SCOPE: Users" --count 5
/brainstorm system-architect --session WFS-xxx
```
**功能**:
- 双模式路由：交互式模式选择，支持参数自动检测
- **Auto 模式**: Phase 2 (artifacts) → Phase 3 (N×Role 并行) → Phase 4 (综合)
- **Single Role 模式**: Phase 3 (1×Role 分析)
- 渐进式阶段加载：阶段文件按需通过 `Ref:` 标记加载
- 会话连续性：所有阶段通过 workflow-session.json 共享会话状态
**架构概览**:
```
┌─────────────────────────────────────────────────────────────┐
│ /brainstorm │
│ Unified Entry Point + Interactive Routing │
└───────────────────────┬─────────────────────────────────────┘
│
┌─────────┴─────────┐
↓ ↓
┌─────────────────┐ ┌──────────────────┐
│ Auto Mode │ │ Single Role Mode │
│ (自动模式) │ │ (单角色分析模式) │
└────────┬────────┘ └────────┬─────────┘
│ │
┌────────┼────────┐ │
↓ ↓ ↓ ↓
Phase 2 Phase 3 Phase 4 Phase 3
Artifacts N×Role Synthesis 1×Role
(7步) Analysis (8步) Analysis
并行 (4步)
```
**可用角色**:
| 角色 ID | 标题 | 关注领域 |
|---------|------|----------|
| `data-architect` | 数据架构师 | 数据模型、存储策略、数据流 |
| `product-manager` | 产品经理 | 产品策略、路线图、优先级 |
| `product-owner` | 产品负责人 | 待办事项管理、用户故事、验收标准 |
| `scrum-master` | 敏捷教练 | 流程促进、障碍消除 |
| `subject-matter-expert` | 领域专家 | 领域知识、业务规则、合规性 |
| `system-architect` | 系统架构师 | 技术架构、可扩展性、集成 |
| `test-strategist` | 测试策略师 | 测试策略、质量保证 |
| `ui-designer` | UI设计师 | 视觉设计、原型、设计系统 |
| `ux-expert` | UX专家 | 用户研究、信息架构、旅程 |
**输出结构**:
```
.workflow/active/WFS-{topic}/
├── workflow-session.json # 会话元数据
├── .process/
│ └── context-package.json # Phase 0 输出（auto 模式）
└── .brainstorming/
├── guidance-specification.md # 框架（Phase 2, auto 模式）
├── feature-index.json # 功能索引（Phase 4, auto 模式）
├── synthesis-changelog.md # 综合决策审计跟踪（Phase 4, auto 模式）
├── feature-specs/ # 功能规范（Phase 4, auto 模式）
│ ├── F-001-{slug}.md
│ └── F-00N-{slug}.md
├── {role}/ # 角色分析（Phase 3 后不可变）
│ ├── {role}-context.md # 交互式问答响应
│ ├── analysis.md # 主/索引文档
│ ├── analysis-cross-cutting.md # 跨功能
│ └── analysis-F-{id}-{slug}.md # 每功能
└── synthesis-specification.md # 综合（Phase 4, 非 feature 模式）
```
**核心规则**:
1. **从模式检测开始**: 第一个动作是 Phase 1（解析参数 + 检测模式）
2. **交互式路由**: 如果模式无法从参数确定，ASK 用户
3. **无预分析**: 在 Phase 2 之前不分析主题
4. **解析每个输出**: 从每个阶段提取所需数据
5. **通过 TodoList 自动继续**: 检查 TodoList 状态自动执行下一个待处理阶段
6. **并行执行**: Auto 模式 Phase 3 同时附加多个代理任务用于并发执行
---
### skill-generator
**一句话定位**: Skill 生成器 — 元技能，用于创建新的 Claude Code Skills
**触发**:
```
/skill-generator
/create skill
/new skill
```
**功能**:
- 元技能，用于创建新的 Claude Code Skills
- 可配置执行模式：顺序（固定顺序）或自治（无状态自动选择）
- 用途：Skill 脚手架、Skill 创建、构建新工作流
**执行模式**:
| 模式 | 说明 | 用例 |
|------|------|------|
| **Sequential** | 传统线性执行，阶段按数字前缀顺序执行 | 流水线任务、强依赖、固定输出 |
| **Autonomous** | 智能路由，动态选择执行路径 | 交互任务、无强依赖、动态响应 |
**Phase 0**: **强制前置** — 规范研究（必须完成才能继续）
**⚠️ 强制前置条件**:
> **不要跳过**: 在执行任何操作之前，**必须**完整阅读以下文档。
**核心规范**（必读）:
| 文档 | 用途 | 优先级 |
|------|------|--------|
| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | 通用设计规范 — 定义所有 Skills 的结构、命名、质量标准 | **P0 - 关键** |
| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档生成规范 — 确保生成的 Skills 有适当的基于阶段的参考文档 | **P0 - 关键** |
**模板文件**（生成前必读）:
| 文档 | 用途 |
|------|------|
| [templates/skill-md.md](templates/skill-md.md) | SKILL.md 入口文件模板 |
| [templates/sequential-phase.md](templates/sequential-phase.md) | 顺序阶段模板 |
| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | 自治编排器模板 |
| [templates/autonomous-action.md](templates/autonomous-action.md) | 自治动作模板 |
**执行流程**:
```
Phase 0: 规范研究（强制）
- Read: ../_shared/SKILL-DESIGN-SPEC.md
- Read: All templates/*.md files
- 理解: 结构规则、命名约定、质量标准
Phase 1: 需求发现
- AskUserQuestion 收集需求
- 生成: skill-config.json
Phase 2: 结构生成
- Bash: mkdir -p directory structure
- Write: SKILL.md
Phase 3: 阶段/动作生成（模式依赖）
- Sequential → 生成 phases/*.md
- Autonomous → 生成 orchestrator + actions/*.md
Phase 4: 规范和模板
- 生成: domain specs, templates
Phase 5: 验证和文档
- 验证: 完整性检查
- 生成: README.md, validation-report.json
```
**输出结构** (Sequential):
```
.claude/skills/{skill-name}/
├── SKILL.md # 入口文件
├── phases/
│ ├── _orchestrator.md # 声明式编排器
│ ├── workflow.json # 工作流定义
│ ├── 01-{step-one}.md # Phase 1
│ ├── 02-{step-two}.md # Phase 2
│ └── 03-{step-three}.md # Phase 3
├── specs/
│ ├── {skill-name}-requirements.md
│ └── quality-standards.md
├── templates/
│ └── agent-base.md
├── scripts/
└── README.md
```
---
### ccw-help
**一句话定位**: CCW 命令帮助系统 — 命令搜索、推荐、文档查看
**触发**:
```
/ccw-help
/ccw "task description" # 自动选择工作流并执行
/ccw-help search <keyword> # 搜索命令
/ccw-help next <command> # 获取下一步建议
```
**功能**:
- 命令搜索、推荐、文档查看
- 自动工作流编排
- 新手入门引导
**操作模式**:
| 模式 | 触发 | 说明 |
|------|------|------|
| **Command Search** | "搜索命令", "find command" | 查询 command.json，过滤相关命令 |
| **Smart Recommendations** | "下一步", "what's next" | 查询 flow.next_steps |
| **Documentation** | "怎么用", "how to use" | 读取源文件，提供上下文示例 |
| **Beginner Onboarding** | "新手", "getting started" | 查询 essential_commands |
| **CCW Command Orchestration** | "ccw ", "自动工作流" | 分析意图，自动选择工作流 |
| **Issue Reporting** | "ccw-issue", "报告 bug" | 收集上下文，生成问题模板 |
**支持的 Workflows**:
- **Level 1** (Lite-Lite-Lite): 超简单快速任务
- **Level 2** (Rapid/Hotfix): Bug 修复、简单功能、文档
- **Level 2.5** (Rapid-to-Issue): 从快速规划桥接到 Issue 工作流
- **Level 3** (Coupled): 复杂功能（规划、执行、审查、测试）
- **Level 3 Variants**: TDD、Test-fix、Review、UI 设计工作流
- **Level 4** (Full): 探索性任务（头脑风暴）
- **With-File Workflows**: 文档化探索（多 CLI 协作）
- **Issue Workflow**: 批量 Issue 发现、规划、排队、执行
**Slash Commands**:
```bash
/ccw "task description" # 自动选择工作流并执行
/ccw-help # 帮助入口
/ccw-help search <keyword> # 搜索命令
/ccw-help next <command> # 下一步建议
/ccw-issue # Issue 报告
```
**CCW Command Examples**:
```bash
/ccw "Add user authentication" # → auto-select level 2-3
/ccw "Fix memory leak" # → auto-select bugfix
/ccw "Implement with TDD" # → detect TDD workflow
/ccw "头脑风暴: 用户通知系统" # → detect brainstorm
```
**统计数据**:
- **Commands**: 50+
- **Agents**: 16
- **Workflows**: 6 主层级 + 3 with-file 变体
- **Essential**: 10 核心命令
---
### skill-tuning
**一句话定位**: Skill 调优诊断 — 自动化诊断和优化建议
**触发**:
```
/skill-tuning <skill-name>
```
**功能**:
- 诊断 Skill 问题
- 提供优化建议
- 应用优化
- 验证改进
**诊断流程**:
```
分析 Skill → 识别问题 → 生成建议 → 应用优化 → 验证效果
```
---
### command-generator
**一句话定位**: 命令生成器 — 生成 Claude 命令
**触发**:
```
/command-generator
```
**功能**:
- 根据需求生成命令
- 遵循命令规范
- 生成命令文档
---
### issue-manage
**一句话定位**: Issue 管理 — Issue 创建、更新、状态管理
**触发**:
```
/issue-manage
/issue:new
```
**功能**:
- Issue 创建
- Issue 状态管理
- Issue 关联和依赖
## 相关命令
- [Claude Commands - CLI](../commands/claude/cli.md)
- [CCW CLI Tools](../features/cli.md)
## 最佳实践
1. **规范生成**: 使用 `spec-generator` 生成完整规范包，然后移交给执行工作流
2. **头脑风暴**: 使用 `brainstorm` 进行多角色分析，获得全面视角
3. **Skill 创建**: 使用 `skill-generator` 创建符合规范的 Skills
4. **命令帮助**: 使用 `ccw-help` 查找命令和工作流
5. **持续调优**: 使用 `skill-tuning` 定期优化 Skill 性能
## 使用示例
```bash
# 生成产品规范
/spec-generator "Build real-time collaboration platform"
# 头脑风暴
/brainstorm "Design payment system" --count 3
/brainstorm system-architect --session WFS-xxx
# 创建新 Skill
/skill-generator
# 获取帮助
/ccw "Add JWT authentication"
/ccw-help search "review"
# 管理 Issues
/issue-manage
```

238
docs/zh/skills/claude-review.md Normal file
View File

@@ -0,0 +1,238 @@
# Claude Skills - 代码审查类
## 一句话定位
**代码审查类 Skills 是多维度代码质量分析系统** — 通过结构化审查维度和自动化检查发现代码问题并提供修复建议。
## 解决的痛点
| 痛点 | 现状 | Claude_dms3 方案 |
| --- | --- | --- |
| **审查维度不全** | 手动审查容易遗漏维度 | 6 维度自动审查 |
| **问题分类混乱** | 难以区分严重程度 | 结构化问题分类 |
| **修复建议模糊** | 缺少具体修复方案 | 可执行的修复建议 |
| **审查流程重复** | 每次审查重复相同步骤 | 自动化扫描和报告 |
## Skills 列表
| Skill | 功能 | 触发方式 |
| --- | --- | --- |
| `review-code` | 多维度代码审查（6 维度） | `/review-code <target>` |
| `review-cycle` | 代码审查和修复循环 | `/review-cycle <target>` |
## Skills 详解
### review-code
**一句话定位**: 多维度代码审查 — 分析正确性、可读性、性能、安全性、测试、架构六大维度
**触发**:
```
/review-code <target-path>
/review-code src/auth/**
/review-code --dimensions=sec,perf src/**
```
**功能**:
- 6 维度审查：正确性、可读性、性能、安全性、测试覆盖、架构一致性
- 分层执行：快速扫描识别高风险区域，深入审查聚焦关键问题
- 结构化报告：按严重程度分类，提供文件位置和修复建议
- 状态驱动：自主模式，根据审查进度动态选择下一步动作
**架构概览**:
```
┌─────────────────────────────────────────────────────────────────┐
│ ⚠️ Phase 0: Specification Study (强制前置) │
│ → 阅读 specs/review-dimensions.md │
│ → 理解审查维度和问题分类标准 │
└───────────────┬─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Orchestrator (状态驱动决策) │
│ → 读取状态 → 选择审查动作 → 执行 → 更新状态 │
└───────────────┬─────────────────────────────────────────────────┘
│
┌───────────┼───────────┬───────────┬───────────┐
↓ ↓ ↓ ↓ ↓
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Collect │ │ Quick │ │ Deep │ │ Report │ │Complete │
│ Context │ │ Scan │ │ Review │ │ Generate│ │ │
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
↓ ↓ ↓ ↓
┌─────────────────────────────────────────────────────────────────┐
│ Review Dimensions │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Correctness│ │Readability│ │Performance│ │ Security │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ │
│ │ Testing │ │Architecture│ │
│ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
**⚠️ 强制前置条件**:
> **禁止跳过**: 在执行任何审查操作之前，**必须**完整阅读以下文档。
**规范文档**（必读）:
| 文档 | 用途 | 优先级 |
|------|------|--------|
| [specs/review-dimensions.md](specs/review-dimensions.md) | 审查维度定义和检查点 | **P0 - 最高** |
| [specs/issue-classification.md](specs/issue-classification.md) | 问题分类和严重程度标准 | **P0 - 最高** |
| [specs/quality-standards.md](specs/quality-standards.md) | 审查质量标准 | P1 |
**模板文件**（生成前必读）:
| 文档 | 用途 |
|------|------|
| [templates/review-report.md](templates/review-report.md) | 审查报告模板 |
| [templates/issue-template.md](templates/issue-template.md) | 问题记录模板 |
**执行流程**:
```
Phase 0: Specification Study (强制前置 - 禁止跳过)
→ Read: specs/review-dimensions.md
→ Read: specs/issue-classification.md
→ 理解审查标准和问题分类
Action: collect-context
→ 收集目标文件/目录
→ 识别技术栈和语言
→ Output: state.context
Action: quick-scan
→ 快速扫描整体结构
→ 识别高风险区域
→ Output: state.risk_areas, state.scan_summary
Action: deep-review (per dimension)
→ 逐维度深入审查
→ 记录发现的问题
→ Output: state.findings[]
Action: generate-report
→ 汇总所有发现
→ 生成结构化报告
→ Output: review-report.md
Action: complete
→ 保存最终状态
→ 输出审查摘要
```
**审查维度**:
| 维度 | 关注领域 | 关键检查 |
|------|----------|----------|
| **Correctness** | 逻辑正确性 | 边界条件、错误处理、null 检查 |
| **Readability** | 代码可读性 | 命名规范、函数长度、注释质量 |
| **Performance** | 性能效率 | 算法复杂度、I/O 优化、资源使用 |
| **Security** | 安全性 | 注入风险、敏感信息、权限控制 |
| **Testing** | 测试覆盖 | 测试充分性、边界覆盖、可维护性 |
| **Architecture** | 架构一致性 | 设计模式、分层结构、依赖管理 |
**问题严重程度**:
| 级别 | 前缀 | 描述 | 所需操作 |
|------|------|------|----------|
| **Critical** | [C] | 阻塞性问题，必须立即修复 | 合并前必须修复 |
| **High** | [H] | 重要问题，需要修复 | 应该修复 |
| **Medium** | [M] | 建议改进 | 考虑修复 |
| **Low** | [L] | 可选优化 | 有则更好 |
| **Info** | [I] | 信息性建议 | 仅供参考 |
**输出结构**:
```
.workflow/.scratchpad/review-code-{timestamp}/
├── state.json # 审查状态
├── context.json # 目标上下文
├── findings/ # 问题发现
│ ├── correctness.json
│ ├── readability.json
│ ├── performance.json
│ ├── security.json
│ ├── testing.json
│ └── architecture.json
└── review-report.md # 最终审查报告
```
---
### review-cycle
**一句话定位**: 代码审查和修复循环 — 审查代码、发现问题、修复验证的完整循环
**触发**:
```
/review-cycle <target-path>
/review-cycle --full <target-path>
```
**功能**:
- 审查代码发现问题
- 生成修复建议
- 执行修复
- 验证修复效果
- 循环直到通过
**循环流程**:
```
审查代码 → 发现问题 → [有问题] → 修复代码 → 验证 → [仍有问题] → 修复代码
↑______________|
```
**使用场景**:
- PR 审查前自查
- 代码质量改进
- 重构验证
- 安全审计
## 相关命令
- [Claude Commands - Workflow](../commands/claude/workflow.md)
- [Team Review 团队协作](./claude-collaboration.md#team-review)
## 最佳实践
1. **完整阅读规范**: 执行审查前必须阅读 specs/ 下的规范文档
2. **多维度审查**: 使用 `--dimensions` 指定关注的维度，或使用默认全维度
3. **快速扫描**: 先用 quick-scan 识别高风险区域，再深入审查
4. **结构化报告**: 利用生成的 review-report.md 作为修复指南
5. **循环改进**: 使用 review-cycle 持续改进直到达到质量标准
## 使用示例
```bash
# 完整审查（6 维度）
/review-code src/auth/**
# 只审查安全性和性能
/review-code --dimensions=sec,perf src/api/
# 审查并修复循环
/review-cycle --full src/utils/
# 审查特定文件
/review-code src/components/Header.tsx
```
## 问题报告示例
```
### [C] SQL Injection Risk
**Location**: `src/auth/login.ts:45`
**Issue**: User input directly concatenated into SQL query without sanitization.
**Severity**: Critical - Must fix before merge
**Recommendation**:
```typescript
// Before (vulnerable):
const query = `SELECT * FROM users WHERE username='${username}'`;
// After (safe):
const query = 'SELECT * FROM users WHERE username = ?';
await db.query(query, [username]);
```
**Reference**: [specs/review-dimensions.md](specs/review-dimensions.md) - Security section
```

347
docs/zh/skills/claude-workflow.md Normal file
View File

@@ -0,0 +1,347 @@
# Claude Skills - 工作流类
## 一句话定位
**工作流类 Skills 是任务编排和执行的流水线系统** — 从规划到执行到验证的全流程自动化工作流。
## 解决的痛点
| 痛点 | 现状 | Claude_dms3 方案 |
| --- | --- | --- |
| **手动任务拆解** | 人工分解任务，容易遗漏 | 自动化任务生成和依赖管理 |
| **执行状态分散** | 各工具独立，状态不统一 | 统一会话管理、TodoWrite 追踪 |
| **中断恢复困难** | 任务中断后难以恢复 | 会话持久化、断点续传 |
| **质量验证缺失** | 完成后无质量检查 | 内置质量关卡、验证报告 |
## Skills 列表
| Skill | 功能 | 触发方式 |
| --- | --- | --- |
| `workflow-plan` | 统一规划技能（4 阶段工作流） | `/workflow:plan` |
| `workflow-execute` | 代理协调执行 | `/workflow:execute` |
| `workflow-lite-plan` | 轻量级快速规划 | `/workflow:lite-plan` |
| `workflow-multi-cli-plan` | 多 CLI 协作规划 | `/workflow:multi-cli-plan` |
| `workflow-tdd` | TDD 工作流 | `/workflow:tdd` |
| `workflow-test-fix` | 测试修复工作流 | `/workflow:test-fix` |
| `workflow-skill-designer` | Skill 设计工作流 | `/workflow:skill-designer` |
| `workflow-wave-plan` | Wave 批处理规划 | `/workflow:wave-plan` |
## Skills 详解
### workflow-plan
**一句话定位**: 统一规划技能 — 4 阶段工作流、计划验证、交互式重规划
**触发**:
```
/workflow:plan <task-description>
/workflow:plan-verify --session <session-id>
/workflow:replan --session <session-id> [task-id] "requirements"
```
**功能**:
- 4 阶段工作流：会话发现 → 上下文收集 → 冲突解决 → 任务生成
- 计划验证（Phase 5）：只读验证 + 质量关卡
- 交互式重规划（Phase 6）：边界澄清 → 影响分析 → 备份 → 应用 → 验证
**模式检测**:
```javascript
// Skill 触发器决定模式
skillName === 'workflow:plan-verify' → 'verify'
skillName === 'workflow:replan' → 'replan'
default → 'plan'
```
**核心规则**:
1. **纯协调器**: SKILL.md 只路由和协调，执行细节在阶段文件中
2. **渐进式阶段加载**: 仅在阶段即将执行时读取阶段文档
3. **多模式路由**: 单一技能通过模式检测处理 plan/verify/replan
4. **任务附加模型**: 子命令任务被附加，顺序执行，然后折叠
5. **自动继续**: 每个阶段完成后自动执行下一个待处理阶段
6. **累积状态**: planning-notes.md 跨阶段携带上下文用于 N+1 决策
**计划模式数据流**:
```
用户输入（任务描述）
↓
[转换为结构化格式]
↓ 结构化描述:
↓ GOAL: [目标]
↓ SCOPE: [范围]
↓ CONTEXT: [背景]
↓
Phase 1: session:start --auto "structured-description"
↓ 输出: sessionId
↓ 写入: planning-notes.md (用户意图部分)
↓
Phase 2: context-gather --session sessionId "structured-description"
↓ 输入: sessionId + 结构化描述
↓ 输出: contextPath + conflictRisk
↓ 更新: planning-notes.md
↓
Phase 3: conflict-resolution [条件: conflictRisk ≥ medium]
↓ 输入: sessionId + contextPath + conflictRisk
↓ 输出: 修改后的头脑风暴产物
↓ 跳过如果 conflictRisk 是 none/low → 直接进入 Phase 4
↓
Phase 4: task-generate-agent --session sessionId
↓ 输入: sessionId + planning-notes.md + context-package.json
↓ 输出: IMPL_PLAN.md, task JSONs, TODO_LIST.md
↓
计划确认（用户决策门）:
├─ "验证计划质量"（推荐）→ Phase 5
├─ "开始执行" → Skill(skill="workflow-execute")
└─ "仅审查状态" → 内联展示会话状态
```
**TodoWrite 模式**:
- **任务附加**（阶段执行时）：子任务附加到协调器的 TodoWrite
- **任务折叠**（子任务完成后）：移除详细子任务，折叠为阶段摘要
- **持续执行**: 完成后自动进行到下一个待处理阶段
---
### workflow-execute
**一句话定位**: 代理协调执行 — 系统化任务发现、代理协调和状态跟踪
**触发**:
```
/workflow:execute
/workflow:execute --resume-session="WFS-auth"
/workflow:execute --yes
/workflow:execute -y --with-commit
```
**功能**:
- 会话发现：识别并选择活跃工作流会话
- 执行策略解析：从 IMPL_PLAN.md 提取执行模型
- TodoWrite 进度跟踪：整个工作流执行期间的实时进度跟踪
- 代理编排：协调具有完整上下文的专业代理
- 自主完成：执行所有任务直到工作流完成或达到阻塞状态
**自动模式默认值** (`--yes` 或 `-y`):
- **会话选择**: 自动选择第一个（最新）活跃会话
- **完成选择**: 自动完成会话（运行 `/workflow:session:complete --yes`）
**执行过程**:
```
Phase 1: 发现
├─ 计算活跃会话数
└─ 决策:
├─ count=0 → 错误：无活跃会话
├─ count=1 → 自动选择会话 → Phase 2
└─ count>1 → AskUserQuestion（最多 4 个选项）→ Phase 2
Phase 2: 规划文档验证
├─ 检查 IMPL_PLAN.md 存在
├─ 检查 TODO_LIST.md 存在
└─ 验证 .task/ 包含 IMPL-*.json 文件
Phase 3: TodoWrite 生成
├─ 更新会话状态为 "active"
├─ 解析 TODO_LIST.md 获取任务状态
├─ 为整个工作流生成 TodoWrite
└─ 准备会话上下文路径
Phase 4: 执行策略选择 & 任务执行
├─ Step 4A: 从 IMPL_PLAN.md 解析执行策略
└─ Step 4B: 延迟加载执行任务
└─ 循环:
├─ 从 TodoWrite 获取下一个 in_progress 任务
├─ 延迟加载任务 JSON
├─ 启动代理并传入任务上下文
├─ 标记任务完成
├─ [with-commit] 基于摘要提交更改
└─ 前进到下一个任务
Phase 5: 完成
├─ 更新任务状态
├─ 生成摘要
└─ AskUserQuestion: 选择下一步
```
**执行模型**:
| 模型 | 条件 | 模式 |
|------|------|------|
| Sequential | IMPL_PLAN 指定或无明确并行化指导 | 逐个执行 |
| Parallel | IMPL_PLAN 指定并行化机会 | 并行执行独立任务组 |
| Phased | IMPL_PLAN 指定阶段分解 | 按阶段执行，遵守阶段边界 |
| Intelligent Fallback | IMPL_PLAN 缺少执行策略细节 | 分析任务结构，应用智能默认值 |
**Lazy Loading 策略**:
- **TODO_LIST.md**: Phase 3 读取（任务元数据、状态、依赖）
- **IMPL_PLAN.md**: Phase 2 检查存在，Phase 4A 解析执行策略
- **Task JSONs**: 延迟加载 — 仅在任务即将执行时读取
**自动提交模式** (`--with-commit`):
```bash
# 1. 从 .summaries/{task-id}-summary.md 读取摘要
# 2. 从 "Files Modified" 部分提取文件
# 3. 提交: git add <files> && git commit -m "{type}: {title} - {summary}"
```
---
### workflow-lite-plan
**一句话定位**: 轻量级快速规划 — 超简单任务的快速规划和执行
**触发**:
```
/workflow:lite-plan <simple-task>
```
**功能**:
- 用于 Level 1 (Lite-Lite-Lite) 工作流
- 超简单快速任务的最小规划开销
- 直接文本输入，无需复杂分析
**适用场景**:
- 小 bug 修复
- 简单文档更新
- 配置调整
- 单函数修改
---
### workflow-multi-cli-plan
**一句话定位**: 多 CLI 协作规划 — 多个 CLI 工具协作的分析和规划
**触发**:
```
/workflow:multi-cli-plan <task>
```
**功能**:
- 调用多个 CLI 工具（Gemini、Codex、Claude）并行分析
- 综合多个视角的输入
- 生成综合规划
**使用场景**:
- 需要多视角分析的任务
- 复杂架构决策
- 跨领域问题
---
### workflow-tdd
**一句话定位**: TDD 工作流 — 测试驱动的开发流程
**触发**:
```
/workflow:tdd <feature-description>
```
**功能**:
- 先编写测试
- 实现功能
- 运行测试验证
- 循环直到通过
**流水线**:
```
规划测试 → 编写测试 → [失败] → 实现功能 → [通过] → 完成
↑___________|
```
---
### workflow-test-fix
**一句话定位**: 测试修复工作流 — 失败测试的诊断和修复
**触发**:
```
/workflow:test-fix <failing-tests>
```
**功能**:
- 诊断测试失败原因
- 修复代码或测试
- 验证修复
- 循环直到通过
**流水线**:
```
诊断失败 → 确定根因 → [代码问题] → 修复代码 → 验证
↑___________|
```
---
### workflow-skill-designer
**一句话定位**: Skill 设计工作流 — 创建新的 Claude Code Skills
**触发**:
```
/workflow:skill-designer <skill-idea>
```
**功能**:
- 需求发现
- 结构生成
- 阶段/动作生成
- 规范和模板生成
- 验证和文档
**输出结构**:
```
.claude/skills/{skill-name}/
├── SKILL.md # 入口文件
├── phases/
│ ├── orchestrator.md # 编排器
│ └── actions/ # 动作文件
├── specs/ # 规范文档
├── templates/ # 模板文件
└── README.md
```
---
### workflow-wave-plan
**一句话定位**: Wave 批处理规划 — 批量 Issue 的并行处理规划
**触发**:
```
/workflow:wave-plan <issue-list>
```
**功能**:
- 批量 Issue 分析
- 并行化机会识别
- Wave 调度（逐批处理）
- 执行队列生成
**Wave 模型**:
```
Wave 1: Issue 1-5 → 并行规划 → 并行执行
Wave 2: Issue 6-10 → 并行规划 → 并行执行
...
```
## 相关命令
- [Claude Commands - Workflow](../commands/claude/workflow.md)
- [Claude Skills - 团队协作](./claude-collaboration.md)
## 最佳实践
1. **选择合适的工作流**:
- 超简单任务 → `workflow-lite-plan`
- 复杂功能 → `workflow-plan` → `workflow-execute`
- TDD 开发 → `workflow-tdd`
- 测试修复 → `workflow-test-fix`
- Skill 创建 → `workflow-skill-designer`
2. **利用自动模式**: 使用 `--yes` 或 `-y` 跳过交互式确认，使用默认值
3. **会话管理**: 所有工作流支持会话持久化，可中断恢复
4. **TodoWrite 追踪**: 利用 TodoWrite 实时查看工作流执行进度
5. **Lazy Loading**: 任务 JSON 延迟加载，仅在执行时读取，提高性能

489
docs/zh/skills/codex-index.md Normal file
View File

@@ -0,0 +1,489 @@
# Codex Skills 总览
## 一句话定位
**Codex Skills 是 Codex 模型的专用技能系统** — 通过生命周期类、工作流类和专项类技能，实现多代理并行开发和协作分析。
## vs Claude Skills 对比
| 维度 | Claude Skills | Codex Skills |
|------|--------------|-------------|
| **模型** | Claude 模型 | Codex 模型 |
| **架构** | team-worker agent 架构 | spawn-wait-close 代理模式 |
| **子代理** | discuss/explore 子代理（内联调用） | discuss/explore 子代理（独立调用） |
| **协调器** | 内置协调器 + 动态角色 | 主流程内联编排 |
| **状态管理** | team-session.json | state 文件 |
| **缓存** | explorations/cache-index.json | shared discoveries.ndjson |
## Skills 类别
| 类别 | 文档 | 说明 |
|------|------|------|
| **生命周期** | [lifecycle.md](./codex-lifecycle.md) | 全生命周期编排 |
| **工作流** | [workflow.md](./codex-workflow.md) | 并行开发和协作工作流 |
| **专项** | [specialized.md](./codex-specialized.md) | 专项技能 |
## 核心概念速览
| 概念 | 说明 | 位置/命令 |
| --- | --- | --- |
| **team-lifecycle** | 全生命周期编排器 | `/team-lifecycle` |
| **parallel-dev-cycle** | 并行开发循环 | `/parallel-dev-cycle` |
| **analyze-with-file** | 协作分析 | `/analyze-with-file` |
| **brainstorm-with-file** | 头脑风暴 | `/brainstorm-with-file` |
| **debug-with-file** | 假设驱动调试 | `/debug-with-file` |
## 生命周期 Skills
### team-lifecycle
**一句话定位**: 全生命周期编排器 — 规范/实现/测试的 spawn-wait-close 流水线
**触发**:
```
/team-lifecycle <task-description>
```
**功能**:
- 5 阶段流水线：需求澄清 → 会话初始化 → 任务链创建 → 流水线协调 → 完成报告
- **Inline discuss**: 生产角色（analyst, writer, reviewer）内联调用 discuss 子代理，将规范流水线从 12 拍减少到 6 拍
- **Shared explore cache**: 所有代理共享集中式 `explorations/` 目录，消除重复代码库探索
- **Fast-advance spawning**: 代理完成后立即派生下一个线性后继者
- **Consensus severity routing**: 讨论结果通过 HIGH/MEDIUM/LOW 严重程度路由
**代理注册表**:
| 代理 | 角色 | 模式 |
|------|------|------|
| analyst | 种子分析、上下文收集、DISCUSS-001 | 2.8 Inline Subagent |
| writer | 文档生成、DISCUSS-002 到 DISCUSS-005 | 2.8 Inline Subagent |
| planner | 多角度探索、计划生成 | 2.9 Cached Exploration |
| executor | 代码实现 | 2.1 Standard |
| tester | 测试修复循环 | 2.3 Deep Interaction |
| reviewer | 代码审查 + 规范质量、DISCUSS-006 | 2.8 Inline Subagent |
| architect | 架构咨询（按需） | 2.1 Standard |
| fe-developer | 前端实现 | 2.1 Standard |
| fe-qa | 前端 QA、GC 循环 | 2.3 Deep Interaction |
**流水线定义**:
```
Spec-only (6 beats):
RESEARCH-001(+D1) → DRAFT-001(+D2) → DRAFT-002(+D3) → DRAFT-003(+D4) → DRAFT-004(+D5) → QUALITY-001(+D6)
Impl-only (3 beats):
PLAN-001 → IMPL-001 → TEST-001 || REVIEW-001
Full-lifecycle (9 beats):
[Spec pipeline] → PLAN-001 → IMPL-001 → TEST-001 || REVIEW-001
```
**Beat Cycle**:
```
event (phase advance / user resume)
↓
[Orchestrator]
+-- read state file
+-- find ready tasks
+-- spawn agent(s)
+-- wait(agent_ids, timeout)
+-- process results
+-- update state file
+-- close completed agents
+-- fast-advance: spawn next
+-- yield (wait for next event)
```
**会话目录**:
```
.workflow/.team/TLS-<slug>-<date>/
├── team-session.json # 流水线状态
├── spec/ # 规范产物
├── discussions/ # 讨论记录
├── explorations/ # 共享探索缓存
├── architecture/ # 架构评估
├── analysis/ # 分析师设计情报
├── qa/ # QA 审计报告
└── wisdom/ # 跨任务知识积累
```
---
### parallel-dev-cycle
**一句话定位**: 多代理并行开发循环 — 需求分析、探索规划、代码开发、验证
**触发**:
```
/parallel-dev-cycle TASK="Implement feature"
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
/parallel-dev-cycle --auto TASK="Add OAuth"
```
**功能**:
- 4 个专业工作者：RA（需求）、EP（探索）、CD（开发）、VAS（验证）
- 主流程内联编排（无单独编排器代理）
- 每个代理维护一个主文档（每次迭代完全重写）+ 辅助日志（追加）
- 自动归档旧版本到 `history/` 目录
**工作者**:
| 工作者 | 主文档 | 辅助日志 |
|--------|--------|----------|
| RA | requirements.md | changes.log |
| EP | exploration.md, architecture.md, plan.json | changes.log |
| CD | implementation.md, issues.md | changes.log, debug-log.ndjson |
| VAS | summary.md, test-results.json | changes.log |
**共享发现板**:
- 所有代理共享实时发现板 `coordination/discoveries.ndjson`
- 代理在开始时读取，工作时追加发现
- 消除冗余代码库探索
**会话结构**:
```
{projectRoot}/.workflow/.cycle/
├── {cycleId}.json # 主状态文件
├── {cycleId}.progress/
│ ├── ra/ # RA 代理产物
│ │ ├── requirements.md # 当前版本（完全重写）
│ │ ├── changes.log # NDJSON 完整历史（追加）
│ │ └── history/ # 归档快照
│ ├── ep/ # EP 代理产物
│ ├── cd/ # CD 代理产物
│ ├── vas/ # VAS 代理产物
│ └── coordination/ # 协调数据
│ ├── discoveries.ndjson # 共享发现板
│ ├── timeline.md # 执行时间线
│ └── decisions.log # 决策日志
```
**执行流程**:
```
Phase 1: 会话初始化
↓ cycleId, state, progressDir
Phase 2: 代理执行（并行）
├─ 派生 RA → EP → CD → VAS
└─ 等待所有代理完成
Phase 3: 结果聚合 & 迭代
├─ 解析 PHASE_RESULT
├─ 检测问题（测试失败、阻塞）
├─ 有问题 AND 迭代 < 最大值？
│ ├─ 是 → 发送反馈，循环回 Phase 2
│ └─ 否 → 进入 Phase 4
└─ 输出: parsedResults, iteration status
Phase 4: 完成和摘要
├─ 生成统一摘要报告
├─ 更新最终状态
├─ 关闭所有代理
└─ 输出: 最终循环报告
```
**版本控制**:
- 1.0.0: 初始循环 → 1.x.0: 每次迭代（次要版本递增）
- 每次迭代: 归档旧版本 → 完全重写 → 追加 changes.log
## 工作流 Skills
### analyze-with-file
**一句话定位**: 协作分析 — 文档化讨论、内联探索、理解演进的交互式分析
**触发**:
```
/analyze-with-file TOPIC="<question>"
/analyze-with-file TOPIC="--depth=deep"
```
**核心工作流**:
```
Topic → Explore → Discuss → Document → Refine → Conclude → (Optional) Quick Execute
```
**关键特性**:
- **文档化讨论时间线**: 捕获跨所有阶段的理解演进
- **每个关键点决策记录**: 强制记录关键发现、方向变更、权衡
- **多视角分析**: 支持最多 4 个分析视角（串行、内联）
- **交互式讨论**: 多轮 Q&A，用户反馈和方向调整
- **Quick execute**: 将结论直接转换为可执行任务
**决策记录协议**:
| 触发 | 记录内容 | 目标部分 |
|------|----------|----------|
| 方向选择 | 选择内容、原因、替代方案 | `#### Decision Log` |
| 关键发现 | 发现内容、影响范围、置信度 | `#### Key Findings` |
| 假设变更 | 旧假设 → 新理解、原因、影响 | `#### Corrected Assumptions` |
| 用户反馈 | 用户原始输入、采用/调整原因 | `#### User Input` |
---
### brainstorm-with-file
**一句话定位**: 多视角头脑风暴 — 4 视角（Product、Technical、Risk、User）并行分析
**触发**:
```
/brainstorm-with-file TOPIC="<idea>"
```
**功能**:
- 4 视角并行分析：Product、Technical、Risk、User
- 一致性评分和收敛判定
- 可行性建议和行动项
**视角**:
| 视角 | 关注领域 |
|------|----------|
| **Product** | 市场契合度、用户价值、业务可行性 |
| **Technical** | 可行性、技术债务、性能、安全 |
| **Risk** | 风险识别、依赖、失败模式 |
| **User** | 可用性、用户体验、采用障碍 |
---
### debug-with-file
**一句话定位**: 假设驱动调试 — 文档化探索、理解演进、分析辅助修正
**触发**:
```
/debug-with-file BUG="<bug description>"
```
**核心工作流**:
```
Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify
```
**关键增强**:
- **understanding.md**: 探索和学习的时间线
- **分析辅助修正**: 验证和修正假设
- **整合**: 简化已证明错误的理解，避免混乱
- **学习保留**: 保留从失败尝试中学到的内容
**会话文件夹结构**:
```
{projectRoot}/.workflow/.debug/DBG-{slug}-{date}/
├── debug.log # NDJSON 日志（执行证据）
├── understanding.md # 探索时间线 + 整合理解
└── hypotheses.json # 假设历史（带判定）
```
**模式**:
| 模式 | 触发条件 |
|------|----------|
| **Explore** | 无会话或无 understanding.md |
| **Continue** | 会话存在但无 debug.log 内容 |
| **Analyze** | debug.log 有内容 |
---
### collaborative-plan-with-file
**一句话定位**: 协作规划 — 多代理协作规划（替代 team-planex）
**触发**:
```
/collaborative-plan-with-file <task>
```
**功能**:
- 多代理协作规划
- planner 和 executor 并行工作
- 中间产物文件传递 solution
---
### unified-execute-with-file
**一句话定位**: 通用执行引擎 — 替代 workflow-execute
**触发**:
```
/unified-execute-with-file <session>
```
**功能**:
- 通用执行引擎
- 支持多种任务类型
- 自动会话恢复
---
### roadmap-with-file
**一句话定位**: 需求路线图规划
**触发**:
```
/roadmap-with-file <requirements>
```
**功能**:
- 需求到路线图的规划
- 优先级排序
- 里程碑定义
---
### review-cycle
**一句话定位**: 审查循环（Codex 版本）
**触发**:
```
/review-cycle <target>
```
**功能**:
- 代码审查
- 修复循环
- 验证修复效果
---
### workflow-test-fix-cycle
**一句话定位**: 测试修复工作流
**触发**:
```
/workflow-test-fix-cycle <failing-tests>
```
**功能**:
- 诊断测试失败原因
- 修复代码或测试
- 验证修复
- 循环直到通过
## 专项 Skills
### clean
**一句话定位**: 智能代码清理
**触发**:
```
/clean <target>
```
**功能**:
- 自动化代码清理
- 代码格式化
- 死代码移除
---
### csv-wave-pipeline
**一句话定位**: CSV 波处理管道
**触发**:
```
/csv-wave-pipeline <csv-file>
```
**功能**:
- CSV 数据处理
- 波次处理
- 数据转换和导出
---
### memory-compact
**一句话定位**: Memory 压缩（Codex 版本）
**触发**:
```
/memory-compact
```
**功能**:
- Memory 压缩和合并
- 清理冗余数据
- 优化存储
---
### ccw-cli-tools
**一句话定位**: CLI 工具执行规范
**触发**:
```
/ccw-cli-tools <command>
```
**功能**:
- CLI 工具标准化执行
- 参数规范
- 输出格式统一
---
### issue-discover
**一句话定位**: Issue 发现
**触发**:
```
/issue-discover <context>
```
**功能**:
- 从上下文发现 Issue
- Issue 分类
- 优先级评估
## 相关文档
- [Claude Skills](./claude-index.md)
- [功能文档](../features/)
## 最佳实践
1. **选择合适的团队类型**:
- 完整生命周期 → `team-lifecycle`
- 并行开发 → `parallel-dev-cycle`
- 协作分析 → `analyze-with-file`
2. **利用 Inline Discuss**: 生产角色内联调用 discuss 子代理，减少编排开销
3. **共享缓存**: 利用共享探索缓存，避免重复代码库探索
4. **Fast-Advance**: 线性后继任务自动跳过编排器，提高效率
5. **Consensus Routing**: 理解不同严重程度的共识路由行为
## 使用示例
```bash
# 全生命周期开发
/team-lifecycle "Build user authentication API"
# 并行开发
/parallel-dev-cycle TASK="Implement notifications"
# 协作分析
/analyze-with-file TOPIC="How to optimize database queries?"
# 头脑风暴
/brainstorm-with-file TOPIC="Design payment system"
# 调试
/debug-with-file BUG="System crashes intermittently"
# 测试修复
/workflow-test-fix-cycle "Unit tests failing"
```
## 统计数据
| 类别 | 数量 |
|------|------|
| 生命周期 | 2 |
| 工作流 | 8 |
| 专项 | 6 |
| **总计** | **16+** |

415
docs/zh/skills/codex-lifecycle.md Normal file
View File

@@ -0,0 +1,415 @@
# Codex Skills - 生命周期类
## 一句话定位
**生命周期类 Codex Skills 是全生命周期编排系统** — 通过 team-lifecycle 和 parallel-dev-cycle 实现从规范到实现到测试到审查的完整开发流程自动化。
## vs 传统方法对比
| 维度 | 传统方式 | **Codex Skills** |
| --- | --- | --- |
| 流水线编排 | 手动任务管理 | 自动 spawn-wait-close 流水线 |
| 代理通信 | 直接通信 | 子代理内联调用 |
| 代码库探索 | 重复探索 | 共享缓存系统 |
| 协调开销 | 每步协调 | Fast-advance 线性跳过 |
## Skills 列表
| Skill | 功能 | 触发方式 |
| --- | --- | --- |
| `team-lifecycle` | 全生命周期编排器 | `/team-lifecycle <task>` |
| `parallel-dev-cycle` | 多代理并行开发循环 | `/parallel-dev-cycle TASK="..."` |
## Skills 详解
### team-lifecycle
**一句话定位**: 全生命周期编排器 — 规范/实现/测试的 spawn-wait-close 流水线
**架构概览**:
```
+-------------------------------------------------------------+
| Team Lifecycle Orchestrator |
| Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 -> Phase 5 |
| Require Init Dispatch Coordinate Report |
+----------+------------------------------------------------+--+
|
+-----+------+----------+-----------+-----------+
v v v v v
+---------+ +---------+ +---------+ +---------+ +---------+
| Phase 1 | | Phase 2 | | Phase 3 | | Phase 4 | | Phase 5 |
| Require | | Init | | Dispatch| | Coord | | Report |
+---------+ +---------+ +---------+ +---------+ +---------+
| | | ||| |
params session tasks agents summary
/ | \
spawn wait close
/ | \
+------+ +-------+ +--------+
|agent1| |agent2 | |agent N |
+------+ +-------+ +--------+
| | |
(may call discuss/explore subagents internally)
```
**关键设计原则**:
1. **Inline discuss subagent**: 生产角色（analyst, writer, reviewer）内联调用 discuss 子代理，将规范流水线从 12 拍减少到 6 拍
2. **Shared explore cache**: 所有代理共享集中式 `explorations/` 目录，消除重复代码库探索
3. **Fast-advance spawning**: 代理完成后立即派生下一个线性后继者
4. **Consensus severity routing**: 讨论结果通过 HIGH/MEDIUM/LOW 严重程度路由
5. **Beat model**: 每个流水线步骤是一拍 — 派生代理、等待结果、处理输出、派生下一个
**代理注册表**:
| 代理 | 角色文件 | 职责 | 模式 |
|------|----------|------|------|
| analyst | ~/.codex/agents/analyst.md | 种子分析、上下文收集、DISCUSS-001 | 2.8 Inline Subagent |
| writer | ~/.codex/agents/writer.md | 文档生成、DISCUSS-002 到 DISCUSS-005 | 2.8 Inline Subagent |
| planner | ~/.codex/agents/planner.md | 多角度探索、计划生成 | 2.9 Cached Exploration |
| executor | ~/.codex/agents/executor.md | 代码实现 | 2.1 Standard |
| tester | ~/.codex/agents/tester.md | 测试修复循环 | 2.3 Deep Interaction |
| reviewer | ~/.codex/agents/reviewer.md | 代码审查 + 规范质量、DISCUSS-006 | 2.8 Inline Subagent |
| architect | ~/.codex/agents/architect.md | 架构咨询（按需） | 2.1 Standard |
| fe-developer | ~/.codex/agents/fe-developer.md | 前端实现 | 2.1 Standard |
| fe-qa | ~/.codex/agents/fe-qa.md | 前端 QA、GC 循环 | 2.3 Deep Interaction |
**子代理注册表**:
| 子代理 | 代理文件 | 可调用者 | 用途 |
|--------|----------|----------|------|
| discuss | ~/.codex/agents/discuss-agent.md | analyst, writer, reviewer | 通过 CLI 工具进行多视角批判 |
| explore | ~/.codex/agents/explore-agent.md | analyst, planner, 任意代理 | 带共享缓存的代码库探索 |
**流水线定义**:
```
Spec-only (6 beats):
RESEARCH-001(+D1) → DRAFT-001(+D2) → DRAFT-002(+D3) → DRAFT-003(+D4) → DRAFT-004(+D5) → QUALITY-001(+D6)
Impl-only (3 beats):
PLAN-001 → IMPL-001 → TEST-001 || REVIEW-001
Full-lifecycle (9 beats):
[Spec pipeline] → PLAN-001 → IMPL-001 → TEST-001 || REVIEW-001
```
**Beat Cycle**:
```
event (phase advance / user resume)
↓
[Orchestrator]
+-- read state file
+-- find ready tasks
+-- spawn agent(s)
+-- wait(agent_ids, timeout)
+-- process results (consensus routing, artifacts)
+-- update state file
+-- close completed agents
+-- fast-advance: immediately spawn next if linear successor
+-- yield (wait for next event or user command)
```
**Fast-Advance 决策表**:
| 条件 | 动作 |
|------|------|
| 1 个就绪任务、简单线性后继、无检查点 | 立即 `spawn_agent` 下一个任务（fast-advance） |
| 多个就绪任务（并行窗口） | 批量派生所有就绪任务，然后 `wait` 所有 |
| 无就绪任务、其他代理正在运行 | Yield，等待这些代理完成 |
| 无就绪任务、无运行中 | 流水线完成，进入 Phase 5 |
| 检查点任务完成（如 QUALITY-001） | 暂停，输出检查点消息，等待用户 |
**共识严重程度路由**:
| 判定 | 严重程度 | 编排器动作 |
|------|----------|-----------|
| consensus_reached | - | 正常进行，fast-advance 到下一个任务 |
| consensus_blocked | LOW | 带 notes 视为 reached，正常进行 |
| consensus_blocked | MEDIUM | 记录警告到 `wisdom/issues.md`，在下个任务上下文中包含分歧，继续 |
| consensus_blocked | HIGH | 创建修订任务 或暂停等待用户 |
| consensus_blocked | HIGH (DISCUSS-006) | 始终暂停等待用户决策（最终签署门） |
**修订任务创建** (HIGH 严重程度，非 DISCUSS-006):
```javascript
const revisionTask = {
id: "<original-task-id>-R1",
owner: "<same-agent-role>",
blocked_by: [],
description: "Revision of <original-task-id>: address consensus-blocked divergences.\n"
+ "Session: <session-dir>\n"
+ "Original artifact: <artifact-path>\n"
+ "Divergences: <divergence-details>\n"
+ "Action items: <action-items-from-discuss>\n"
+ "InlineDiscuss: <same-round-id>",
status: "pending",
is_revision: true
}
```
**会话目录结构**:
```
.workflow/.team/TLS-<slug>-<date>/
├── team-session.json # 流水线状态（替换 TaskCreate/TaskList）
├── spec/ # 规范产物
│ ├── spec-config.json
│ ├── discovery-context.json
│ ├── product-brief.md
│ ├── requirements/
│ ├── architecture/
│ ├── epics/
│ ├── readiness-report.md
│ └── spec-summary.md
├── discussions/ # 讨论记录（由 discuss 子代理写入）
├── plan/ # 计划产物
│ ├── plan.json
│ └── tasks/ # 详细任务规范
├── explorations/ # 共享探索缓存
│ ├── cache-index.json # { angle -> file_path }
│ └── explore-<angle>.json
├── architecture/ # 架构师评估 + design-tokens.json
├── analysis/ # 分析师 design-intelligence.json（UI 模式）
├── qa/ # QA 审计报告
├── wisdom/ # 跨任务知识积累
│ ├── learnings.md # 模式和洞察
│ ├── decisions.md # 架构和设计决策
│ ├── conventions.md # 代码库约定
│ └── issues.md # 已知风险和问题
└── shared-memory.json # 跨代理状态
```
**状态文件模式** (team-session.json):
```json
{
"session_id": "TLS-<slug>-<date>",
"mode": "<spec-only | impl-only | full-lifecycle | fe-only | fullstack | full-lifecycle-fe>",
"scope": "<project description>",
"status": "<active | paused | completed>",
"started_at": "<ISO8601>",
"updated_at": "<ISO8601>",
"tasks_total": 0,
"tasks_completed": 0,
"pipeline": [
{
"id": "RESEARCH-001",
"owner": "analyst",
"status": "pending | in_progress | completed | failed",
"blocked_by": [],
"description": "...",
"inline_discuss": "DISCUSS-001",
"agent_id": null,
"artifact_path": null,
"discuss_verdict": null,
"discuss_severity": null,
"started_at": null,
"completed_at": null,
"revision_of": null,
"revision_count": 0
}
],
"active_agents": [],
"completed_tasks": [],
"revision_chains": {},
"wisdom_entries": [],
"checkpoints_hit": [],
"gc_loop_count": 0
}
```
**用户命令**:
| 命令 | 动作 |
|------|------|
| `check` / `status` | 输出执行状态图（只读，无推进） |
| `resume` / `continue` | 检查代理状态，推进流水线 |
| 新会话请求 | Phase 0 检测，进入正常 Phase 1-5 流程 |
**状态图输出格式**:
```
[orchestrator] Pipeline Status
[orchestrator] Mode: <mode> | Progress: <completed>/<total> (<percent>%)
[orchestrator] Execution Graph:
Spec Phase:
[V RESEARCH-001(+D1)] -> [V DRAFT-001(+D2)] -> [>>> DRAFT-002(+D3)]
-> [o DRAFT-003(+D4)] -> [o DRAFT-004(+D5)] -> [o QUALITY-001(+D6)]
V=completed >>>=running o=pending .=not created
[orchestrator] Active Agents:
> <task-id> (<agent-role>) - running <elapsed>
[orchestrator] Commands: 'resume' to advance | 'check' to refresh
```
---
### parallel-dev-cycle
**一句话定位**: 多代理并行开发循环 — 需求分析、探索规划、代码开发、验证
**架构概览**:
```
┌─────────────────────────────────────────────────────────────┐
│ User Input (Task) │
└────────────────────────────┬────────────────────────────────┘
│
v
┌──────────────────────────────┐
│ Main Flow (Inline Orchestration) │
│ Phase 1 → 2 → 3 → 4 │
└──────────────────────────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
v v v
┌────────┐ ┌────────┐ ┌────────┐
│ RA │ │ EP │ │ CD │
│Agent │ │Agent │ │Agent │
└────────┘ └────────┘ └────────┘
│ │ │
└────────────────────┼────────────────────┘
│
v
┌────────┐
│ VAS │
│ Agent │
└────────┘
│
v
┌──────────────────────────────┐
│ Summary Report │
│ & Markdown Docs │
└──────────────────────────────┘
```
**关键设计原则**:
1. **主文档 + 辅助日志**: 每个代理维护一个主文档（每次迭代完全重写）和辅助日志（追加）
2. **基于版本的覆盖**: 主文档每次迭代完全重写；日志仅追加
3. **自动归档**: 旧主文档版本自动归档到 `history/` 目录
4. **完整审计跟踪**: Changes.log (NDJSON) 保留所有更改历史
5. **并行协调**: 四个代理同时启动；通过共享状态和内联主流程协调
6. **文件引用**: 使用短文件路径而非内容传递
7. **自我增强**: RA 代理基于上下文主动扩展需求
8. **共享发现板**: 所有代理通过 `discoveries.ndjson` 共享探索发现
**工作者**:
| 工作者 | 主文档（每次迭代重写） | 追加日志 |
|--------|------------------------|----------|
| **RA** | requirements.md | changes.log |
| **EP** | exploration.md, architecture.md, plan.json | changes.log |
| **CD** | implementation.md, issues.md | changes.log, debug-log.ndjson |
| **VAS** | summary.md, test-results.json | changes.log |
**共享发现板**:
- 所有代理共享实时发现板 `coordination/discoveries.ndjson`
- 代理在开始时读取，工作时追加发现
- 消除冗余代码库探索
**发现类型**:
| 类型 | 去重键 | 写入者 | 读取者 |
|------|--------|--------|--------|
| `tech_stack` | singleton | RA | EP, CD, VAS |
| `project_config` | `data.path` | RA | EP, CD |
| `existing_feature` | `data.name` | RA, EP | CD |
| `architecture` | singleton | EP | CD, VAS |
| `code_pattern` | `data.name` | EP, CD | CD, VAS |
| `integration_point` | `data.file` | EP | CD |
| `test_command` | singleton | CD, VAS | VAS, CD |
| `blocker` | `data.issue` | 任意 | 全部 |
**执行流程**:
```
Phase 1: 会话初始化
├─ 创建新循环 OR 恢复现有循环
├─ 初始化状态文件和目录结构
└─ 输出: cycleId, state, progressDir
Phase 2: 代理执行（并行）
├─ 附加任务: 派生 RA → 派生 EP → 派生 CD → 派生 VAS → 等待所有
├─ 并行派生 RA, EP, CD, VAS 代理
├─ 等待所有代理完成（带超时处理）
└─ 输出: agentOutputs (4 个代理结果)
Phase 3: 结果聚合 & 迭代
├─ 从每个代理解析 PHASE_RESULT
├─ 检测问题（测试失败、阻塞）
├─ 决策: 发现问题 AND 迭代 < 最大值？
│ ├─ 是 → 通过 send_input 发送反馈，循环回 Phase 2
│ └─ 否 → 进入 Phase 4
└─ 输出: parsedResults, 迭代状态
Phase 4: 完成和摘要
├─ 生成统一摘要报告
├─ 更新最终状态
├─ 关闭所有代理
└─ 输出: 最终循环报告和继续说明
```
**会话结构**:
```
{projectRoot}/.workflow/.cycle/
├── {cycleId}.json # 主状态文件
├── {cycleId}.progress/
│ ├── ra/ # RA 代理产物
│ │ ├── requirements.md # 当前版本（完全重写）
│ │ ├── changes.log # NDJSON 完整历史（追加）
│ │ └── history/ # 归档快照
│ ├── ep/ # EP 代理产物
│ │ ├── exploration.md # 代码库探索报告
│ │ ├── architecture.md # 架构设计
│ │ ├── plan.json # 结构化任务列表（当前版本）
│ │ ├── changes.log # NDJSON 完整历史
│ │ └── history/
│ ├── cd/ # CD 代理产物
│ │ ├── implementation.md # 当前版本
│ │ ├── debug-log.ndjson # 调试假设跟踪
│ │ ├── changes.log # NDJSON 完整历史
│ │ └── history/
│ ├── vas/ # VAS 代理产物
│ │ ├── summary.md # 当前版本
│ │ ├── changes.log # NDJSON 完整历史
│ │ └── history/
│ └── coordination/ # 协调数据
│ ├── discoveries.ndjson # 共享发现板（所有代理追加）
│ ├── timeline.md # 执行时间线
│ └── decisions.log # 决策日志
```
**版本控制**:
- 1.0.0: 初始循环 → 1.x.0: 每次迭代（次要版本递增）
- 每次迭代: 归档旧版本 → 完全重写 → 追加 changes.log
## 相关命令
- [Codex Skills - 工作流](./codex-workflow.md)
- [Codex Skills - 专项](./codex-specialized.md)
- [Claude Skills - 团队协作](./claude-collaboration.md)
## 最佳实践
1. **选择合适的团队类型**:
- 完整功能开发 → `team-lifecycle`
- 并行开发循环 → `parallel-dev-cycle`
2. **利用 Inline Discuss**: 生产角色内联调用 discuss 子代理，减少编排开销
3. **共享缓存**: 利用共享探索缓存，避免重复代码库探索
4. **Fast-Advance**: 线性后继任务自动跳过编排器，提高效率
5. **共识路由**: 理解不同严重程度的共识路由行为
## 使用示例
```bash
# 全生命周期开发
/team-lifecycle "Build user authentication API"
# 规范流水线
/team-lifecycle --mode=spec-only "Design payment system"
# 并行开发
/parallel-dev-cycle TASK="Implement notifications"
# 继续循环
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
# 自动模式
/parallel-dev-cycle --auto TASK="Add OAuth"
```

235
docs/zh/skills/codex-specialized.md Normal file
View File

@@ -0,0 +1,235 @@
# Codex Skills - 专项类
## 一句话定位
**专项类 Codex Skills 是特定领域的专用工具集** — 通过代码清理、数据管道、内存管理、CLI 工具和 Issue 发现等专项技能，解决特定领域的特定问题。
## Skills 列表
| Skill | 功能 | 触发方式 |
| --- | --- | --- |
| `clean` | 智能代码清理 | `/clean <target>` |
| `csv-wave-pipeline` | CSV 波处理管道 | `/csv-wave-pipeline <csv-file>` |
| `memory-compact` | Memory 压缩 | `/memory-compact` |
| `ccw-cli-tools` | CLI 工具执行规范 | `/ccw-cli-tools <command>` |
| `issue-discover` | Issue 发现 | `/issue-discover <context>` |
## Skills 详解
### clean
**一句话定位**: 智能代码清理 — 自动化代码清理、格式化、死代码移除
**功能**:
- 自动化代码清理
- 代码格式化
- 死代码移除
- 导入排序
- 注释整理
**清理类型**:
| 类型 | 说明 |
|------|------|
| **格式化** | 代码格式统一 |
| **死代码** | 移除未使用的代码 |
| **导入** | 排序和移除未使用导入 |
| **注释** | 整理和移除过时注释 |
| **命名** | 统一命名约定 |
**使用示例**:
```bash
# 清理当前目录
/clean .
# 清理特定目录
/clean src/
# 只格式化
/clean --format-only src/
# 只移除死代码
/clean --dead-code-only src/
```
---
### csv-wave-pipeline
**一句话定位**: CSV 波处理管道 — CSV 数据处理、波次处理、数据转换和导出
**功能**:
- CSV 数据读取和解析
- 波次处理（分批处理大数据）
- 数据转换和验证
- 导出为多种格式
**处理流程**:
```
读取 CSV → 验证数据 → 波次处理 → 转换数据 → 导出结果
```
**输出格式**:
| 格式 | 说明 |
|------|------|
| CSV | 标准 CSV 格式 |
| JSON | JSON 数组 |
| NDJSON | NDJSON（每行一个 JSON） |
| Excel | Excel 文件 |
**使用示例**:
```bash
# 处理 CSV
/csv-wave-pipeline data.csv
# 指定输出格式
/csv-wave-pipeline data.csv --output-format=json
# 指定波次大小
/csv-wave-pipeline data.csv --batch-size=1000
```
---
### memory-compact
**一句话定位**: Memory 压缩（Codex 版本） — Memory 压缩和合并、清理冗余数据、优化存储
**功能**:
- Memory 压缩和合并
- 清理冗余数据
- 优化存储
- 生成 Memory 摘要
**压缩类型**:
| 类型 | 说明 |
|------|------|
| **合并** | 合并相似条目 |
| **去重** | 移除重复条目 |
| **归档** | 归档旧条目 |
| **摘要** | 生成摘要 |
**使用示例**:
```bash
# 压缩 Memory
/memory-compact
# 合并相似条目
/memory-compact --merge
# 生成摘要
/memory-compact --summary
```
---
### ccw-cli-tools
**一句话定位**: CLI 工具执行规范 — CLI 工具标准化执行、参数规范、输出格式统一
**功能**:
- CLI 工具标准化执行
- 参数规范
- 输出格式统一
- 错误处理
**支持的 CLI 工具**:
| 工具 | 说明 |
|------|------|
| gemini | Gemini CLI |
| codex | Codex CLI |
| claude | Claude CLI |
| qwen | Qwen CLI |
**执行规范**:
```javascript
{
"tool": "gemini",
"mode": "write",
"prompt": "...",
"context": "...",
"output": "..."
}
```
**使用示例**:
```bash
# 执行 CLI 工具
/ccw-cli-tools --tool=gemini --mode=write "Implement feature"
# 批量执行
/ccw-cli-tools --batch tasks.json
```
---
### issue-discover
**一句话定位**: Issue 发现 — 从上下文发现 Issue、Issue 分类、优先级评估
**功能**:
- 从上下文发现 Issue
- Issue 分类
- 优先级评估
- 生成 Issue 报告
**Issue 类型**:
| 类型 | 说明 |
|------|------|
| **Bug** | 缺陷或错误 |
| **Feature** | 新功能请求 |
| **Improvement** | 改进建议 |
| **Task** | 任务 |
| **Documentation** | 文档问题 |
**优先级评估**:
| 优先级 | 标准 |
|--------|------|
| **Critical** | 阻塞性问题 |
| **High** | 重要问题 |
| **Medium** | 一般问题 |
| **Low** | 低优先级 |
**使用示例**:
```bash
# 从代码库发现 Issue
/issue-discover src/
# 从文档发现 Issue
/issue-discover docs/
# 从测试结果发现 Issue
/issue-discover test-results/
```
## 相关命令
- [Codex Skills - 生命周期](./codex-lifecycle.md)
- [Codex Skills - 工作流](./codex-workflow.md)
- [Claude Skills - 元技能](./claude-meta.md)
## 最佳实践
1. **代码清理**: 定期使用 `clean` 清理代码
2. **数据处理**: 使用 `csv-wave-pipeline` 处理大数据
3. **Memory 管理**: 定期使用 `memory-compact` 优化 Memory
4. **CLI 工具**: 使用 `ccw-cli-tools` 标准化 CLI 执行
5. **Issue 发现**: 使用 `issue-discover` 发现和分类 Issue
## 使用示例
```bash
# 清理代码
/clean src/
# 处理 CSV
/csv-wave-pipeline data.csv --output-format=json
# 压缩 Memory
/memory-compact --merge
# 执行 CLI 工具
/ccw-cli-tools --tool=gemini "Analyze code"
# 发现 Issue
/issue-discover src/
```

366
docs/zh/skills/codex-workflow.md Normal file
View File

@@ -0,0 +1,366 @@
# Codex Skills - 工作流类
## 一句话定位
**工作流类 Codex Skills 是协作分析和并行开发工作流系统** — 通过文档化讨论、多视角分析和协作规划实现高效的团队协作。
## 解决的痛点
| 痛点 | 现状 | Codex Skills 方案 |
| --- | --- | --- |
| **讨论过程丢失** | 讨论结果只保存结论 | 文档化讨论时间线 |
| **探索重复** | 每次分析重复探索代码库 | 共享发现板 |
| **调试盲目** | 缺少假设验证机制 | 假设驱动调试 |
| **协作割裂** | 各角色独立工作 | 多视角并行分析 |
## Skills 列表
| Skill | 功能 | 触发方式 |
| --- | --- | --- |
| `analyze-with-file` | 协作分析（4 视角） | `/analyze-with-file TOPIC="..."` |
| `brainstorm-with-file` | 头脑风暴（4 视角） | `/brainstorm-with-file TOPIC="..."` |
| `debug-with-file` | 假设驱动调试 | `/debug-with-file BUG="..."` |
| `collaborative-plan-with-file` | 协作规划 | `/collaborative-plan-with-file <task>` |
| `unified-execute-with-file` | 通用执行引擎 | `/unified-execute-with-file <session>` |
| `roadmap-with-file` | 需求路线图 | `/roadmap-with-file <requirements>` |
| `review-cycle` | 审查循环 | `/review-cycle <target>` |
| `workflow-test-fix-cycle` | 测试修复工作流 | `/workflow-test-fix-cycle <tests>` |
## Skills 详解
### analyze-with-file
**一句话定位**: 协作分析 — 文档化讨论、内联探索、理解演进的交互式分析
**核心工作流**:
```
Topic → Explore → Discuss → Document → Refine → Conclude → (Optional) Quick Execute
```
**关键特性**:
- **文档化讨论时间线**: 捕获跨所有阶段的理解演进
- **每个关键点决策记录**: 强制记录关键发现、方向变更、权衡
- **多视角分析**: 支持最多 4 个分析视角（串行、内联）
- **交互式讨论**: 多轮 Q&A，用户反馈和方向调整
- **Quick execute**: 将结论直接转换为可执行任务
**决策记录协议**:
| 触发 | 记录内容 | 目标部分 |
|------|----------|----------|
| **方向选择** | 选择内容、原因、替代方案 | `#### Decision Log` |
| **关键发现** | 发现内容、影响范围、置信度 | `#### Key Findings` |
| **假设变更** | 旧假设 → 新理解、原因、影响 | `#### Corrected Assumptions` |
| **用户反馈** | 用户原始输入、采用/调整原因 | `#### User Input` |
**分析视角** (串行、内联):
| 视角 | CLI 工具 | 角色 | 关注领域 |
|------|----------|------|----------|
| Product | gemini | 产品经理 | 市场契合度、用户价值、业务可行性 |
| Technical | codex | 技术主管 | 可行性、技术债务、性能、安全 |
| Quality | claude | QA 主管 | 完整性、可测试性、一致性 |
| Risk | gemini | 风险分析师 | 风险识别、依赖、失败模式 |
**会话文件夹结构**:
```
{projectRoot}/.workflow/.analyze/ANL-{slug}-{date}/
├── discussion.md # 讨论时间线 + 理解演进
├── explorations/ # 代码库探索报告
│ ├── exploration-summary.md
│ ├── relevant-files.md
│ └── patterns.md
└── conclusion.md # 最终结论 + Quick execute 任务
```
**执行流程**:
```
Phase 1: Topic Analysis
├─ 检测深度模式 (quick/standard/deep)
├─ 会话检测: {projectRoot}/.workflow/.analyze/ANL-{slug}-{date}/
└─ 输出: sessionId, depth, continueMode
Phase 2: Exploration
├─ 检测上下文: discovery-context.json, prep-package.json
├─ 代码库探索: Glob + Read + Grep 工具
├─ 写入: explorations/exploration-summary.md
└─ 输出: explorationResults
Phase 3: Discussion (Multiple Rounds)
├─ 初始化: discussion.md (Section: Exploration Summary)
├─ Round 1: 基于 explorationResults 生成初始分析
├─ 迭代: 用户反馈 → 修正理解 → 更新 discussion.md
└─ 每轮更新: Decision Log, Key Findings, Current Understanding
Phase 4: Refinement
├─ 合并: explorations/ 内容合并到 discussion.md
├─ 检查: 所有关键点已记录
└─ 输出: refinedDiscussion
Phase 5: Conclusion
├─ 生成: conclusion.md (Executive Summary, Findings, Recommendations)
└─ Quick Execute (可选): 生成可执行任务
Phase 6: (可选) Quick Execute
├─ 转换结论为: 任务 JSON 或 plan file
└─ 调用: workflow-execute 或直接执行
```
**深度模式**:
| 模式 | 探索范围 | 分析轮次 |
|------|----------|----------|
| quick | 基础搜索，10 文件 | 1 轮 |
| standard | 标准探索，30 文件 | 2-3 轮 |
| deep | 深度探索，100+ 文件 | 3-5 轮 |
---
### brainstorm-with-file
**一句话定位**: 多视角头脑风暴 — 4 视角（Product、Technical、Risk、User）并行分析
**关键特性**:
- 4 视角并行分析：Product、Technical、Risk、User
- 一致性评分和收敛判定
- 可行性建议和行动项
**视角**:
| 视角 | 关注领域 |
|------|----------|
| **Product** | 市场契合度、用户价值、业务可行性 |
| **Technical** | 可行性、技术债务、性能、安全 |
| **Risk** | 风险识别、依赖、失败模式 |
| **User** | 可用性、用户体验、采用障碍 |
**输出格式**:
```
## 一致性判定
状态: <consensus_reached | consensus_blocked>
平均评分: <N>/5
收敛点: <list>
分歧点: <list>
## 可行性建议
推荐: <proceed | proceed-with-caution | revise | reject>
理由: <reasoning>
行动项: <action items>
```
---
### debug-with-file
**一句话定位**: 假设驱动调试 — 文档化探索、理解演进、分析辅助修正
**核心工作流**:
```
Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify
```
**关键增强**:
- **understanding.md**: 探索和学习的时间线
- **分析辅助修正**: 验证和修正假设
- **整合**: 简化已证明错误的理解，避免混乱
- **学习保留**: 保留从失败尝试中学到的内容
**会话文件夹结构**:
```
{projectRoot}/.workflow/.debug/DBG-{slug}-{date}/
├── debug.log # NDJSON 日志（执行证据）
├── understanding.md # 探索时间线 + 整合理解
└── hypotheses.json # 假设历史（带判定）
```
**模式**:
| 模式 | 触发条件 | 行为 |
|------|----------|------|
| **Explore** | 无会话或无 understanding.md | 定位错误源，记录初始理解，生成假设，添加日志 |
| **Continue** | 会话存在但无 debug.log 内容 | 等待用户复现 |
| **Analyze** | debug.log 有内容 | 解析日志，评估假设，更新理解 |
**假设生成**:
基于错误模式生成针对性假设：
| 错误模式 | 假设类型 |
|----------|----------|
| not found / missing / undefined | data_mismatch |
| 0 / empty / zero / registered | logic_error |
| timeout / connection / sync | integration_issue |
| type / format / parse | type_mismatch |
**NDJSON 日志格式**:
```json
{"sid":"DBG-xxx-2025-01-21","hid":"H1","loc":"file.py:func:42","msg":"Check dict keys","data":{"keys":["a","b"],"target":"c","found":false},"ts":1734567890123}
```
**Understanding Document 模板**:
```markdown
# Understanding Document
**Session ID**: DBG-xxx-2025-01-21
**Bug Description**: [original description]
**Started**: 2025-01-21T10:00:00+08:00
---
## Exploration Timeline
### Iteration 1 - Initial Exploration (2025-01-21 10:00)
#### Current Understanding
...
#### Evidence from Code Search
...
#### Hypotheses Generated
...
---
## Current Consolidated Understanding
### What We Know
- [valid understanding points]
### What Was Disproven
- ~~[disproven assumptions]~~
### Current Investigation Focus
[current focus]
```
---
### collaborative-plan-with-file
**一句话定位**: 协作规划 — 多代理协作规划（替代 team-planex）
**功能**:
- 多代理协作规划
- planner 和 executor 并行工作
- 中间产物文件传递 solution
**Wave Pipeline** (逐 Issue 节拍):
```
Issue 1: planner 规划 solution → 写中间产物 → 冲突检查 → 创建 EXEC-* → issue_ready
↓ (executor 立即开始)
Issue 2: planner 规划 solution → 写中间产物 → 冲突检查 → 创建 EXEC-* → issue_ready
↓ (executor 并行消费)
Issue N: ...
Final: planner 发送 all_planned → executor 完成剩余 EXEC-* → 结束
```
---
### unified-execute-with-file
**一句话定位**: 通用执行引擎 — 替代 workflow-execute
**功能**:
- 通用执行引擎
- 支持多种任务类型
- 自动会话恢复
**会话发现**:
1. 计算 .workflow/active/ 中的活跃会话数
2. 决策:
- count=0 → 错误：无活跃会话
- count=1 → 自动选择会话
- count>1 → AskUserQuestion（最多 4 个选项）
---
### roadmap-with-file
**一句话定位**: 需求路线图规划
**功能**:
- 需求到路线图的规划
- 优先级排序
- 里程碑定义
**输出结构**:
```
.workflow/.roadmap/{session-id}/
├── roadmap.md # 路线图文档
├── milestones.md # 里程碑定义
└── priorities.json # 优先级排序
```
---
### review-cycle
**一句话定位**: 审查循环（Codex 版本）
**功能**:
- 代码审查
- 修复循环
- 验证修复效果
**循环流程**:
```
审查代码 → 发现问题 → [有问题] → 修复代码 → 验证 → [仍有问题] → 修复代码
↑______________|
```
---
### workflow-test-fix-cycle
**一句话定位**: 测试修复工作流
**功能**:
- 诊断测试失败原因
- 修复代码或测试
- 验证修复
- 循环直到通过
**流程**:
```
诊断失败 → 确定根因 → [代码问题] → 修复代码 → 验证
↑___________|
```
## 相关命令
- [Codex Skills - 生命周期](./codex-lifecycle.md)
- [Codex Skills - 专项](./codex-specialized.md)
- [Claude Skills - 工作流](./claude-workflow.md)
## 最佳实践
1. **选择合适的工作流**:
- 协作分析 → `analyze-with-file`
- 头脑风暴 → `brainstorm-with-file`
- 调试 → `debug-with-file`
- 规划 → `collaborative-plan-with-file`
2. **文档化讨论**: 利用文档化讨论时间线，捕获理解演进
3. **决策记录**: 在关键点记录决策，保留决策历史
4. **假设驱动调试**: 使用假设驱动调试，系统化解决问题
5. **多视角分析**: 利用多视角并行分析，获得全面理解
## 使用示例
```bash
# 协作分析
/analyze-with-file TOPIC="How to optimize database queries?"
# 深度分析
/analyze-with-file TOPIC="Architecture for microservices" --depth=deep
# 头脑风暴
/brainstorm-with-file TOPIC="Design payment system"
# 调试
/debug-with-file BUG="System crashes intermittently"
# 协作规划
/collaborative-plan-with-file "Add user notifications"
# 测试修复
/workflow-test-fix-cycle "Unit tests failing"
```

204
docs/zh/workflows/4-level.md Normal file
View File

@@ -0,0 +1,204 @@
# 四级工作流系统
CCW 四级工作流系统提供了一种从规格说明到部署的结构化软件开发方法。
## 概述
```
Level 1: 规格说明 → Level 2: 规划 → Level 3: 实现 → Level 4: 验证
```
## Level 1: 规格说明
**目标**: 定义构建什么以及为什么构建。
### 活动
| 活动 | 描述 | 产出 |
|------|------|------|
| 研究 | 分析需求和上下文 | 发现上下文 |
| 产品简报 | 定义产品愿景 | 产品简报 |
| 需求 | 创建带有验收标准的 PRD | 需求文档 |
| 架构 | 设计系统架构 | 架构文档 |
| 史诗与故事 | 分解为可跟踪的项目 | 史诗和用户故事 |
### 智能体
- **analyst**: 执行研究和分析
- **writer**: 创建规格说明文档
- **discuss-subagent**: 多视角评审
### 质量门禁
**QUALITY-001** 验证:
- 所有需求已文档化
- 架构已批准
- 风险已评估
- 验收标准已定义
### 示例任务
```
RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001
```
## Level 2: 规划
**目标**: 定义如何构建。
### 活动
| 活动 | 描述 | 产出 |
|------|------|------|
| 探索 | 多角度代码库分析 | 探索缓存 |
| 任务分解 | 创建实现任务 | 任务定义 |
| 依赖映射 | 识别任务依赖关系 | 依赖图 |
| 资源估算 | 估算工作量和复杂度 | 计划元数据 |
### 智能体
- **planner**: 创建实现计划
- **architect**: 提供技术咨询（按需）
- **explore-subagent**: 代码库探索
### 输出
```json
{
"epic_count": 5,
"total_tasks": 27,
"execution_order": [...],
"tech_stack": {...}
}
```
## Level 3: 实现
**目标**: 构建解决方案。
### 活动
| 活动 | 描述 | 产出 |
|------|------|------|
| 代码生成 | 编写源代码 | 源文件 |
| 单元测试 | 创建单元测试 | 测试文件 |
| 文档编写 | 记录代码和 API | 文档 |
| 自我验证 | 验证实现质量 | 验证报告 |
### 智能体
- **executor**: 协调实现
- **code-developer**: 简单、直接的编辑
- **ccw cli**: 复杂、多文件变更
### 执行策略
任务根据依赖关系按拓扑顺序执行:
```
TASK-001 (无依赖) → TASK-002 (依赖 001) → TASK-003 (依赖 002)
```
### 后端
| 后端 | 使用场景 |
|------|----------|
| agent | 简单、直接的编辑 |
| codex | 复杂、架构相关 |
| gemini | 分析密集型 |
## Level 4: 验证
**目标**: 确保质量。
### 活动
| 活动 | 描述 | 产出 |
|------|------|------|
| 集成测试 | 验证组件集成 | 测试结果 |
| QA 测试 | 用户验收测试 | QA 报告 |
| 性能测试 | 测量性能 | 性能指标 |
| 安全审查 | 安全漏洞扫描 | 安全发现 |
| 代码审查 | 最终质量检查 | 审查反馈 |
### 智能体
- **tester**: 执行测试-修复循环
- **reviewer**: 四维代码审查
### 审查维度
| 维度 | 关注点 |
|------|--------|
| 产品 | 需求对齐 |
| 技术 | 代码质量、模式 |
| 质量 | 测试、边界情况 |
| 覆盖 | 完整性 |
| 风险 | 安全、性能 |
## 工作流编排
### Beat 模型
事件驱动执行，由协调器编排:
```
Event Coordinator Workers
────────────────────────────────────────────────
callback/resume → handleCallback ─────────────────┐
→ mark completed │
→ check pipeline │
→ handleSpawnNext ──────────────┼───→ [Worker A]
→ find ready tasks │
→ spawn workers ─────────────────┼───→ [Worker B]
→ STOP (idle) ──────────────────┘ │
│
callback <──────────────────────────────────────────────┘
```
### 检查点
**规格检查点** (QUALITY-001 之后):
- 暂停等待用户确认
- 验证规格说明完整性
- 需要手动恢复才能继续
**最终门禁** (REVIEW-001 之后):
- 最终质量验证
- 所有测试必须通过
- 关键问题已解决
### 快速推进
对于简单的线性继任，工作器可以直接生成后继者:
```
[Worker A] complete
→ Check: 1 ready task? simple successor?
→ YES: Spawn Worker B directly
→ NO: SendMessage to coordinator
```
## 并行执行
某些史诗可以并行执行:
```
EPIC-003: Content Modules ──┐
├──→ EPIC-005: Interaction Features
EPIC-004: Search & Nav ────┘
```
## 错误处理
| 场景 | 解决方案 |
|------|----------|
| 语法错误 | 带错误上下文重试（最多 3 次） |
| 缺少依赖 | 向协调器请求 |
| 后端不可用 | 回退到替代方案 |
| 循环依赖 | 中止，报告依赖图 |
::: info 另见
- [最佳实践](./best-practices.md) - 工作流优化
- [智能体](../agents/) - 智能体专业化
:::

167
docs/zh/workflows/best-practices.md Normal file
View File

@@ -0,0 +1,167 @@
# 工作流最佳实践
优化您的 CCW 工作流以获得最高效率和质量。
## 规格说明阶段
### 应该做的
- **从明确的目标开始**: 提前定义成功标准
- **让利益相关者参与**: 从所有利益相关者收集需求
- **记录假设**: 将隐性知识显式化
- **及早识别风险**: 评估技术和项目风险
### 不应该做的
- 跳过研究阶段
- 未经验证就假设需求
- 忽略技术约束
- 过度设计解决方案
## 规划阶段
### 应该做的
- **分解任务**: 细粒度的任务更容易估算
- **映射依赖**: 及早识别任务关系
- **现实估算**: 使用历史数据进行估算
- **规划迭代**: 为未知因素预留缓冲
### 不应该做的
- 创建单体任务
- 忽略任务依赖
- 低估复杂度
- 提前规划所有内容
## 实现阶段
### 应该做的
- **遵循计划**: 相信规划过程
- **边写边测**: 与代码同步编写测试
- **记录变更**: 保持文档同步
- **频繁验证**: 每次变更后运行测试
### 不应该做的
- 未经讨论偏离计划
- 为了速度跳过测试
- 推迟文档编写
- 忽略反馈
## 验证阶段
### 应该做的
- **全面测试**: 覆盖正常路径和边界情况
- **审查代码**: 使用代码审查指南
- **衡量质量**: 使用自动化指标
- **记录发现**: 创建测试报告
### 不应该做的
- 跳过边界情况测试
- 忽略审查反馈
- 仅依赖手动测试
- 隐藏测试失败
## 团队协调
### 沟通
- **使用 SendMessage**: 始终通过协调器沟通
- **具体明确**: 清晰的消息减少来回沟通
- **报告进度**: 定期更新状态
- **上报阻塞**: 不要等待阻塞问题
### 协作
- **尊重边界**: 每个角色有特定职责
- **信任流程**: 工作流确保质量
- **分享知识**: 贡献智慧文件
- **从失败中学习**: 事后分析改进未来工作流
## 常见陷阱
### 规格说明
| 陷阱 | 影响 | 预防措施 |
|------|------|----------|
| 模糊的需求 | 返工 | 使用验收标准 |
| 缺少约束 | 实现失败 | 明确列出非功能性需求 |
| 范围不清 | 范围蔓延 | 定义范围内/范围外 |
### 规划
| 陷阱 | 影响 | 预防措施 |
|------|------|----------|
| 乐观估算 | 延误 | 使用不确定性锥 |
| 未知依赖 | 任务阻塞 | 先探索代码库 |
| 单线程规划 | 瓶颈 | 识别并行机会 |
### 实现
| 陷阱 | 影响 | 预防措施 |
|------|------|----------|
| 跳过测试 | 生产环境 Bug | 测试优先方法 |
| 忽略反馈 | PR 被拒绝 | 处理审查意见 |
| 镀金 | 交付延迟 | 遵循需求 |
## 工作流优化
### 减少周期时间
1. **批量处理相似任务**: 减少上下文切换
2. **自动化验证**: 持续集成
3. **并行执行**: 识别独立任务
4. **快速推进**: 对简单继任跳过协调器
### 提高质量
1. **早期验证**: 测试优先开发
2. **同行审查**: 多审查者视角
3. **自动化测试**: 全面的测试覆盖
4. **指标跟踪**: 衡量质量指标
### 有效扩展
1. **史诗分解**: 大项目 → 史诗 → 任务
2. **团队专业化**: 基于角色的智能体分配
3. **知识共享**: 智慧积累
4. **流程改进**: 持续改进
## 示例
### 良好的工作流
```
[Specification]
↓ Clear requirements with acceptance criteria
[Planning]
↓ Realistic estimates with identified dependencies
[Implementation]
↓ Tests pass, documentation updated
[Validation]
↓ All acceptance criteria met
[Complete]
```
### 有问题的工作流
```
[Specification]
↓ Vague requirements, no acceptance criteria
[Planning]
↓ Optimistic estimates, missed dependencies
[Implementation]
↓ No tests, incomplete documentation
[Validation]
↓ Failed tests, missing requirements
[Rework]
```
::: info 另见
- [四级系统](./4-level.md) - 详细工作流说明
- [智能体](../agents/) - 智能体能力
:::

183
docs/zh/workflows/index.md Normal file
View File

@@ -0,0 +1,183 @@
# 工作流系统
CCW 的 4 级工作流系统编排从需求到部署代码的整个开发生命周期。
## 工作流级别
```
Level 1: 规范
↓
Level 2: 规划
↓
Level 3: 实现
↓
Level 4: 验证
```
## Level 1: 规范
定义要构建的内容和原因。
**活动:**
- 需求收集
- 用户故事创建
- 验收标准定义
- 风险评估
**输出:**
- 产品简报
- 需求文档 (PRD)
- 架构设计
- Epics 和 Stories
**代理:** analyst, writer
## Level 2: 规划
定义如何构建。
**活动:**
- 技术规划
- 任务分解
- 依赖映射
- 资源估算
**输出:**
- 实现计划
- 任务定义
- 依赖图
- 风险缓解
**代理:** planner, architect
## Level 3: 实现
构建解决方案。
**活动:**
- 代码实现
- 单元测试
- 文档
- 代码审查
**输出:**
- 源代码
- 测试
- 文档
- 构建产物
**代理:** executor, code-developer
## Level 4: 验证
确保质量。
**活动:**
- 集成测试
- QA 测试
- 性能测试
- 安全审查
**输出:**
- 测试报告
- QA 发现
- 审查反馈
- 部署就绪性
**代理:** tester, reviewer
## 完整工作流示例
```bash
# Level 1: 规范
Skill(skill="team-lifecycle-v4", args="构建用户身份验证系统")
# => 创建 RESEARCH-001, DRAFT-001/002/003/004, QUALITY-001
# Level 2: 规划 (QUALITY-001 后自动触发)
# => 创建 PLAN-001 及任务分解
# Level 3: 实现 (PLAN-001 后自动触发)
# => 执行 IMPL-001 及代码生成
# Level 4: 验证 (IMPL-001 后自动触发)
# => 运行 TEST-001 和 REVIEW-001
```
## 工作流可视化
```
┌─────────────────────────────────────────────────────────────┐
│ 工作流编排 │
├─────────────────────────────────────────────────────────────┤
│ │
│ [RESEARCH-001] 产品发现 │
│ ↓ │
│ [DRAFT-001] 产品简报 │
│ ↓ │
│ [DRAFT-002] 需求 (PRD) │
│ ↓ │
│ [DRAFT-003] 架构设计 │
│ ↓ │
│ [DRAFT-004] Epics 和 Stories │
│ ↓ │
│ [QUALITY-001] 规范质量检查 ◄── 检查点 │
│ ↓ ↓ │
│ [PLAN-001] 实现计划 │
│ ↓ │
│ [IMPL-001] 代码实现 │
│ ↓ │
│ [TEST-001] ───┐ │
│ ├──► [REVIEW-001] ◄── 最终关卡 │
│ [REVIEW-001] ─┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
## 检查点
### 规范检查点 (QUALITY-001 后)
在实现前暂停以供用户确认。
**验证:**
- 所有需求已记录
- 架构已批准
- 风险已评估
- 验收标准已定义
### 最终关卡 (REVIEW-001 后)
部署前的最终质量关卡。
**验证:**
- 所有测试通过
- 关键问题已解决
- 文档完整
- 性能可接受
## 自定义工作流
为您的团队定义自定义工作流:
```yaml
# .ccw/workflows/my-workflow.yaml
name: "功能开发"
levels:
- name: "discovery"
agent: "analyst"
tasks: ["research", "user-stories"]
- name: "design"
agent: "architect"
tasks: ["api-design", "database-schema"]
- name: "build"
agent: "executor"
tasks: ["implementation", "unit-tests"]
- name: "verify"
agent: "tester"
tasks: ["integration-tests", "e2e-tests"]
```
::: info 另请参阅
- [4 级系统](./4-level.md) - 详细工作流说明
- [最佳实践](./best-practices.md) - 工作流优化技巧
:::