feat: 增强 command-guide skill 支持深度命令分析和 CLI 辅助查询

新增 Mode 6: 深度命令分析
- 创建 reference 备份目录(80个文档:11 agents + 69 commands)
- 支持简单查询(直接文件查找)和复杂查询(CLI 辅助分析)
- 集成 gemini/qwen 进行跨命令对比、最佳实践、工作流分析
- 添加查询复杂度自动分类和降级策略

更新文档
- SKILL.md: 添加 Mode 6 说明和 Reference Documentation 章节
- implementation-details.md: 添加完整的 Mode 6 实现逻辑
- 版本更新至 v1.3.0

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-11-06 16:27:58 +08:00
parent 0ab3d0e1af
commit 1897ba4e82
85 changed files with 30439 additions and 199 deletions

View File

@@ -1,100 +1,475 @@
# 常见工作流模式
Gemini CLI 不仅提供单个命令,更能通过智能编排将一系列命令组合成强大的工作流,帮助您高效完成复杂任务。本指南将介绍几种常见的工作流模式。
> 学习如何组合命令完成复杂任务,提升开发效率
## 1. 工作流核心概念
## 🎯 什么是工作流?
在深入了解具体模式之前理解工作流的架构至关重要。Gemini CLI 的工作流管理系统旨在提供一个灵活、可扩展的框架,用于定义、执行和协调复杂的开发任务
工作流是**一系列命令的组合**用于完成特定的开发目标。Claude DMS3 提供了多种工作流模式,覆盖从规划到测试的完整开发周期
- **工作流 (Workflows)**:一系列任务的组合,旨在实现特定的开发目标。
- **任务 (Tasks)**:工作流中的独立工作单元,可以简单也可以复杂,有状态、输入和输出。
- **智能体 (Agents)**:通常由大型语言模型驱动,负责执行任务或在工作流中做出决策。
- **上下文 (Context)**当前工作流的相关动态信息,包括项目状态、代码片段、文档、用户输入等,是智能决策的关键。
- **记忆 (Memory)**:持久存储上下文、工作流历史和学习模式,支持工作流的恢复、适应和改进。
**核心概念**
- **工作流Workflow**:一组相关任务的集合
- **任务Task**:独立的工作单元,有明确的输入和输出
- **Session**:工作流的执行实例,记录所有任务状态
- **上下文Context**:任务执行所需的代码、文档、配置等信息
详情可参考 `../../workflows/workflow-architecture.md`
---
## 2. 规划 -> 执行 (Plan -> Execute) 模式
## 📋 Pattern 1: 规划→执行(最常用)
这是最基础也是最常用的工作流模式,它将一个大的目标分解为可执行的步骤,并逐步实现。
**适用场景**:实现新功能、新模块
**场景**: 您有一个需要从头开始实现的新功能或模块。
**流程**:规划 → 执行 → 查看状态
**主要命令**:
- `plan`: 启动高级规划过程,分解目标。
- `breakdown`: 进一步细化和分解 `plan` 生成的任务。
- `create`: 创建具体的实施任务。
- `execute`: 执行创建好的任务以实现代码或解决方案。
### 完整示例
**工作流示例**:
1. **启动规划**: `gemini plan "开发一个用户认证服务"`
- CLI 会与您互动,明确需求,并生成一个初步的规划(可能包含多个子任务)。
2. **任务分解** (可选,如果规划足够细致可跳过):
- 假设 `plan` 产生了一个任务 ID `task-auth-service`
- `gemini breakdown task-auth-service`
- 可能进一步分解为 `task-register`, `task-login`, `task-password-reset`等。
3. **创建具体实现任务**:
- `gemini create "实现用户注册 API 接口"`
- 这会生成一个专门针对此任务的 ID例如 `task-id-register-api`
4. **执行实现任务**:
- `gemini execute task-id-register-api`
- CLI 将调用智能体自动编写和集成代码。
```bash
# 步骤 1规划任务
/workflow:plan --agent "实现用户认证模块"
## 3. 测试驱动开发 (TDD) 模式
# 系统输出:
# ✅ 规划完成
# 📁 Session: WFS-20251106-123456
# 📋 生成 5 个任务
TDD 模式强调先编写测试再编写满足测试的代码然后重构。Gemini CLI 通过自动化 TDD 流程来支持这一模式。
# 步骤 2执行任务
/workflow:execute
**场景**: 您正在开发一个新功能,并希望通过 TDD 确保代码质量和正确性。
# 系统输出:
# ⏳ 执行 task-001-user-model...
# ✅ task-001 完成
# ⏳ 执行 task-002-login-api...
# ...
**主要命令**:
- `tdd-plan`: 规划 TDD 工作流,生成红-绿-重构任务链。
- `test-gen`: 根据功能描述生成测试用例。
- `execute`: 执行代码生成和测试。
- `tdd-verify`: 验证 TDD 工作流的合规性并生成质量报告。
# 步骤 3查看状态
/workflow:status
**工作流示例**:
1. **TDD 规划**: `gemini tdd-plan "实现一个购物车功能"`
- CLI 将为您创建一个 TDD 任务链,包括测试生成、代码实现和验证。
2. **生成测试**: (通常包含在 `tdd-plan` 的早期阶段,或可以单独调用)
- `gemini test-gen source-session-id` (如果已有一个实现会话)
- 这会产生失败的测试(红)。
3. **执行代码实现和测试**:
- `gemini execute task-id-for-code-implementation`
- 智能体会编写代码以通过测试,并将执行测试(变为绿)。
4. **TDD 验证**: `gemini tdd-verify`
- 验证整个 TDD 周期是否规范执行,以及生成测试覆盖率等报告。
# 系统输出:
# Session: WFS-20251106-123456
# Total: 5 | Completed: 5 | Pending: 0
```
## 4. UI 设计与实现工作流
**关键点**
- `--agent` 参数使用 AI 生成更详细的计划
- 系统自动发现最新 session无需手动指定
- 所有任务按依赖顺序自动执行
Gemini CLI 可以辅助您进行 UI 的设计、提取和代码生成,加速前端开发。
---
**场景**: 您需要基于一些设计稿或现有网站来快速构建 UI 原型或实现页面。
## 🧪 Pattern 2: TDD测试驱动开发
**主要命令**:
- `ui-designer`: 启动 UI 设计分析。
- `layout-extract`: 从参考图像或 URL 提取布局信息。
- `style-extract`: 从参考图像或 URL 提取设计风格。
- `generate`: 组合布局和设计令牌生成 UI 原型。
- `update`: 使用最终设计系统参考更新设计产物。
**适用场景**:需要高质量代码和测试覆盖
**工作流示例**:
1. **启动 UI 设计分析**: `gemini ui-designer`
- 开始一个引导式的流程,定义您的 UI 设计目标。
2. **提取布局**: `gemini layout-extract --urls "https://example.com/some-page"`
- 从给定 URL 提取页面布局结构。
3. **提取样式**: `gemini style-extract --images "./design-mockup.png"`
- 从设计图中提取颜色、字体等视觉风格。
4. **生成 UI 原型**: `gemini generate --base-path ./my-ui-project`
- 结合提取的布局和样式,生成可工作的 UI 代码或原型。
5. **更新与迭代**: `gemini update --session ui-design-session-id --selected-prototypes "proto-01,proto-03"`
- 根据反馈和最终设计系统,迭代并更新生成的 UI 产物。
**流程**TDD规划 → 执行(红→绿→重构)→ 验证
## 5. 上下文搜索策略
### 完整示例
所有这些工作流都依赖于高效的上下文管理。Gemini CLI 采用多层次的上下文搜索策略,以确保智能代理获得最相关的信息。
```bash
# 步骤 1TDD 规划
/workflow:tdd-plan --agent "实现购物车功能"
- **相关性优先**: 优先收集与当前任务直接相关的上下文,而非大量数据。
- **分层搜索**: 从最直接的来源(如当前打开文件)开始,逐步扩展到项目文件、记忆库和外部资源。
- **语义理解**: 利用智能搜索理解查询的意图,而非仅仅是关键词匹配。
# 系统输出:
# ✅ TDD 任务链生成
# 📋 Red-Green-Refactor 周期:
# - task-001-cart-tests (RED)
# - task-002-cart-implement (GREEN)
# - task-003-cart-refactor (REFACTOR)
更多细节请查阅 `../../workflows/context-search-strategy.md`
# 步骤 2执行 TDD 周期
/workflow:execute
# 系统会自动:
# 1. 生成失败的测试RED
# 2. 实现代码让测试通过GREEN
# 3. 重构代码REFACTOR
# 步骤 3验证 TDD 合规性
/workflow:tdd-verify
# 系统输出:
# ✅ TDD 周期完整
# ✅ 测试覆盖率: 95%
# ✅ Red-Green-Refactor 合规
```
**关键点**
- TDD 模式自动生成测试优先的任务链
- 每个任务有依赖关系,确保正确的顺序
- 验证命令检查 TDD 合规性
---
## 🔄 Pattern 3: 测试生成
**适用场景**:已有代码,需要生成测试
**流程**:分析代码 → 生成测试策略 → 执行测试生成
### 完整示例
```bash
# 步骤 1实现功能已完成
# 假设已经完成实现session 为 WFS-20251106-123456
# 步骤 2生成测试
/workflow:test-gen WFS-20251106-123456
# 系统输出:
# ✅ 分析实现代码
# ✅ 生成测试策略
# 📋 创建测试任务WFS-test-20251106-789
# 步骤 3执行测试生成
/workflow:test-cycle-execute --resume-session WFS-test-20251106-789
# 系统输出:
# ⏳ 生成测试用例...
# ⏳ 执行测试...
# ❌ 3 tests failed
# ⏳ 修复失败测试...
# ✅ All tests passed
```
**关键点**
- `test-gen` 分析现有代码生成测试
- `test-cycle-execute` 自动生成→测试→修复循环
- 最多迭代 N 次直到所有测试通过
---
## 🎨 Pattern 4: UI 设计工作流
**适用场景**:基于设计稿或现有网站实现 UI
**流程**:提取样式 → 提取布局 → 生成原型 → 更新
### 完整示例
```bash
# 步骤 1提取设计样式
/workflow:ui-design:style-extract \
--images "design/*.png" \
--mode imitate \
--variants 3
# 系统输出:
# ✅ 提取颜色系统
# ✅ 提取字体系统
# ✅ 生成 3 个样式变体
# 步骤 2提取页面布局
/workflow:ui-design:layout-extract \
--urls "https://example.com/dashboard" \
--device-type responsive
# 系统输出:
# ✅ 提取布局结构
# ✅ 识别组件层次
# ✅ 生成响应式布局
# 步骤 3生成 UI 原型
/workflow:ui-design:generate \
--style-variants 2 \
--layout-variants 2
# 系统输出:
# ✅ 生成 4 个原型组合
# 📁 输出:.workflow/ui-design/prototypes/
# 步骤 4更新最终版本
/workflow:ui-design:update \
--session ui-session-id \
--selected-prototypes "proto-1,proto-3"
# 系统输出:
# ✅ 应用最终设计系统
# ✅ 更新所有原型
```
**关键点**
- 支持从图片或 URL 提取设计
- 可生成多个变体供选择
- 最终更新使用确定的设计系统
---
## 🔍 Pattern 5: 代码分析→重构
**适用场景**:优化现有代码,提高可维护性
**流程**:分析现状 → 制定计划 → 执行重构 → 生成测试
### 完整示例
```bash
# 步骤 1分析代码质量
/cli:analyze --tool gemini --cd src/auth \
"评估认证模块的代码质量、可维护性和潜在问题"
# 系统输出:
# ✅ 识别 3 个设计问题
# ✅ 发现 5 个性能瓶颈
# ✅ 建议 7 项改进
# 步骤 2制定重构计划
/cli:mode:plan --tool gemini --cd src/auth \
"基于上述分析,制定认证模块重构方案"
# 系统输出:
# ✅ 重构计划生成
# 📋 包含 8 个重构任务
# 步骤 3执行重构
/cli:execute --tool codex \
"按照重构计划执行认证模块重构"
# 步骤 4生成测试确保正确性
/workflow:test-gen WFS-refactor-session-id
```
**关键点**
- Gemini 用于分析和规划(理解)
- Codex 用于执行实现(重构)
- 重构后必须生成测试验证
---
## 📚 Pattern 6: 文档生成
**适用场景**:为项目或模块生成文档
**流程**:分析代码 → 生成文档 → 更新索引
### 完整示例
```bash
# 方式 1为单个模块生成文档
/memory:docs src/auth --tool gemini --mode full
# 系统输出:
# ✅ 分析模块结构
# ✅ 生成 CLAUDE.md
# ✅ 生成 API 文档
# ✅ 生成使用指南
# 方式 2更新所有模块文档
/memory:update-full --tool gemini
# 系统输出:
# ⏳ 按层级更新文档...
# ✅ Layer 3: 12 modules updated
# ✅ Layer 2: 5 modules updated
# ✅ Layer 1: 2 modules updated
# 方式 3只更新修改过的模块
/memory:update-related --tool gemini
# 系统输出:
# ✅ 检测 git 变更
# ✅ 更新 3 个相关模块
```
**关键点**
- `--mode full` 生成完整文档
- `update-full` 适用于初始化或大规模更新
- `update-related` 适用于日常增量更新
---
## 🔄 Pattern 7: 恢复和继续
**适用场景**:中断后继续工作,或修复失败的任务
**流程**:查看状态 → 恢复 session → 继续执行
### 完整示例
```bash
# 步骤 1查看所有 session
/workflow:status
# 系统输出:
# Session: WFS-20251106-123456 (5/10 completed)
# Session: WFS-20251105-234567 (10/10 completed)
# 步骤 2恢复特定 session
/workflow:resume WFS-20251106-123456
# 系统输出:
# ✅ Session 恢复
# 📋 5/10 tasks completed
# ⏳ 待执行: task-006, task-007, ...
# 步骤 3继续执行
/workflow:execute --resume-session WFS-20251106-123456
# 系统输出:
# ⏳ 继续执行 task-006...
# ✅ task-006 完成
# ...
```
**关键点**
- 所有 session 状态都被保存
- 可以随时恢复中断的工作流
- 恢复时自动分析进度和待办任务
---
## 🎯 Pattern 8: 快速实现Codex YOLO
**适用场景**:快速实现简单功能,跳过规划
**流程**:直接执行 → 完成
### 完整示例
```bash
# 一键实现功能
/cli:codex-execute --verify-git \
"实现用户头像上传功能:
- 支持 jpg/png 格式
- 自动裁剪为 200x200
- 压缩到 100KB 以下
- 上传到 OSS
"
# 系统输出:
# ⏳ 分析需求...
# ⏳ 生成代码...
# ⏳ 集成现有代码...
# ✅ 功能实现完成
# 📁 修改文件:
# - src/api/upload.ts
# - src/utils/image.ts
```
**关键点**
- 适合简单、独立的功能
- `--verify-git` 确保 git 状态干净
- 自动分析需求并完整实现
---
## 🤝 Pattern 9: 多工具协作
**适用场景**:复杂任务需要多个 AI 工具配合
**流程**Gemini 分析 → Gemini/Qwen 规划 → Codex 实现
### 完整示例
```bash
# 步骤 1Gemini 深度分析
/cli:analyze --tool gemini \
"分析支付模块的安全性和性能问题"
# 步骤 2多工具讨论方案
/cli:discuss-plan --topic "支付模块重构方案" --rounds 3
# 系统输出:
# Round 1:
# Gemini: 建议方案 A关注安全
# Codex: 建议方案 B关注性能
# Round 2:
# Gemini: 综合分析...
# Codex: 技术实现评估...
# Round 3:
# 最终方案: 方案 C安全+性能)
# 步骤 3Codex 执行实现
/cli:execute --tool codex "按照方案 C 重构支付模块"
```
**关键点**
- `discuss-plan` 让多个 AI 讨论方案
- 每个工具贡献自己的专长
- 最终选择综合最优方案
---
## 📊 工作流选择指南
```mermaid
graph TD
A[我要做什么?] --> B{任务类型?}
B -->|新功能| C[规划→执行]
B -->|需要测试| D{代码是否存在?}
B -->|UI开发| E[UI设计工作流]
B -->|代码优化| F[分析→重构]
B -->|生成文档| G[文档生成]
B -->|快速实现| H[Codex YOLO]
D -->|不存在| I[TDD工作流]
D -->|已存在| J[测试生成]
C --> K[/workflow:plan<br/>↓<br/>/workflow:execute]
I --> L[/workflow:tdd-plan<br/>↓<br/>/workflow:execute]
J --> M[/workflow:test-gen<br/>↓<br/>/workflow:test-cycle-execute]
E --> N[/workflow:ui-design:*]
F --> O[/cli:analyze<br/>↓<br/>/cli:mode:plan<br/>↓<br/>/cli:execute]
G --> P[/memory:docs]
H --> Q[/cli:codex-execute]
```
---
## 💡 最佳实践
### ✅ 推荐做法
1. **复杂任务使用完整工作流**
```bash
/workflow:plan → /workflow:execute → /workflow:test-gen
```
2. **简单任务使用 Codex YOLO**
```bash
/cli:codex-execute "快速实现xxx"
```
3. **重要代码使用 TDD**
```bash
/workflow:tdd-plan → /workflow:execute → /workflow:tdd-verify
```
4. **定期更新文档**
```bash
/memory:update-related # 每次提交前
```
5. **善用恢复功能**
```bash
/workflow:status → /workflow:resume
```
---
### ❌ 避免做法
1. **不要跳过规划直接执行复杂任务**
- ❌ 直接 `/cli:execute` 实现复杂功能
- ✅ 先 `/workflow:plan` 再 `/workflow:execute`
2. **不要忽略测试**
- ❌ 实现完成后不生成测试
- ✅ 使用 `/workflow:test-gen` 生成测试
3. **不要遗忘文档**
- ❌ 代码实现后忘记更新文档
- ✅ 使用 `/memory:update-related` 自动更新
---
## 🔗 相关资源
- **快速入门**[Getting Started](getting-started.md) - 5分钟上手
- **CLI 工具**[CLI Tools Guide](cli-tools-guide.md) - Gemini/Qwen/Codex 详解
- **问题排查**[Troubleshooting](troubleshooting.md) - 常见问题解决
- **完整命令列表**:查看 `index/all-commands.json`
---
**最后更新**: 2025-11-06
记住:选择合适的工作流模式,事半功倍!不确定用哪个?使用 `ccw` 询问 Command Guide