mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-14 02:42:04 +08:00
feat: Add command relationships and essential commands JSON files
- Introduced command-relationships.json to define relationships between various commands. - Created essential-commands.json to provide detailed descriptions and usage scenarios for key commands. - Implemented update-index.sh script for maintaining command index files, including backup and validation processes. - Added templates for bug reports, feature requests, and questions to streamline issue reporting and feature suggestions.
This commit is contained in:
catlog22
64
.claude/skills/command-guide/guides/cli-tools-guide.md
Normal file
64
.claude/skills/command-guide/guides/cli-tools-guide.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# CLI 智能工具指南
|
||||
|
||||
Gemini CLI 能够集成多种智能工具（如大型语言模型 LLM），以增强您的开发工作流。本指南将帮助您理解这些智能工具如何工作，以及如何有效地利用它们。
|
||||
|
||||
## 1. 什么是智能工具？
|
||||
|
||||
智能工具是集成到 Gemini CLI 中的高级 AI 模型，它们能够理解自然语言、分析代码、生成文本和代码，并协助完成复杂的开发任务。它们就像您的智能助手，可以自动化重复性工作，提供洞察，并帮助您做出更好的决策。
|
||||
|
||||
## 2. 核心工作原理
|
||||
|
||||
Gemini CLI 中的智能工具遵循以下核心原则：
|
||||
|
||||
- **上下文感知**: 工具会理解您当前的项目状态、代码内容和开发意图，从而提供更相关的建议和操作。这意味着它们不会“凭空”回答问题，而是基于您的实际工作环境提供帮助。
|
||||
- **模块化**: 智能工具被设计为可互换的后端。您可以根据任务需求选择或组合不同的 LLM。例如，某些模型可能擅长代码生成，而另一些则擅长复杂推理。
|
||||
- **自动化与增强**: 智能工具可以自动化重复或复杂的任务（如生成样板代码、基础重构、测试脚手架），并通过提供智能建议、解释和问题解决协助来增强您的开发能力。
|
||||
- **用户控制与透明**: 您始终对工具的操作拥有最终控制权。工具会清晰地解释其建议的更改，并允许您轻松审查和修改。工具的选择和执行过程也是透明的。
|
||||
|
||||
详情可参考 `../../workflows/intelligent-tools-strategy.md`。
|
||||
|
||||
## 3. 智能工具的应用场景
|
||||
|
||||
智能工具被集成到 CLI 工作流的多个关键点，以提供全面的帮助：
|
||||
|
||||
- **提示增强**: 优化您的输入提示，使智能工具更好地理解您的需求。
|
||||
- **命令**: `enhance-prompt`
|
||||
- **代码分析与审查**: 快速洞察代码，识别潜在问题，并提出改进建议。
|
||||
- **命令**: `analyze`, `chat`, `code-analysis`, `bug-diagnosis`
|
||||
- **规划与任务分解**: 协助将复杂问题分解为可管理的小任务，并生成实施计划。
|
||||
- **命令**: `plan`, `discuss-plan`, `breakdown`
|
||||
- **代码生成与实现**: 根据您的规范生成代码片段、函数、测试甚至整个模块。
|
||||
- **命令**: `execute`, `create`, `codex-execute`
|
||||
- **测试与调试**: 生成测试用例，诊断错误，并建议修复方案。
|
||||
- **命令**: `test-gen`, `test-fix-gen`, `tdd-plan`, `tdd-verify`
|
||||
- **文档生成**: 自动化代码、API 和项目模块的文档创建。
|
||||
- **命令**: `docs`, `skill-memory`, `update-full`, `update-related`
|
||||
- **工作流编排**: 智能选择和协调工具与代理来执行复杂的工作流。
|
||||
- **命令**: `workflow:status`, `resume`, `plan`, `execute` (工作流级别)
|
||||
|
||||
## 4. 如何选择和使用工具
|
||||
|
||||
Gemini CLI 允许您使用 `--tool` 标志来指定用于特定操作的智能工具。这为您提供了灵活性，可以根据任务的性质选择最合适的模型。
|
||||
|
||||
- `--tool codex`: 优先使用 Codex（或兼容的专注于代码的 LLM）。非常适合精确的代码生成、重构和类似 linting 的任务。
|
||||
- **何时使用**: 当您需要生成高质量代码、进行代码审查或修复代码错误时。
|
||||
- `--tool gemini`: 优先使用 Gemini（或兼容的通用 LLM）。擅长复杂的推理、更广泛的分析、规划和自然语言理解任务。
|
||||
- **何时使用**: 当您需要进行高层次的规划、理解复杂概念或进行广泛的代码库分析时。
|
||||
- `--tool qwen`: 优先使用 Qwen（或兼容的特定领域/语言 LLM）。适用于需要专业知识或特定语言支持的任务。
|
||||
- **何时使用**: 当您的项目涉及特定技术栈或需要特定语言的专业知识时。
|
||||
- **(默认/自动)**: 如果未指定工具，CLI 会根据任务上下文和可用配置智能地选择最合适的工具。
|
||||
|
||||
**示例**:
|
||||
|
||||
```bash
|
||||
# 使用 Gemini 进行项目规划
|
||||
gemini plan --tool gemini "设计一个新的微服务架构"
|
||||
|
||||
# 使用 Codex 生成代码
|
||||
gemini execute --tool codex "task-id-for-code-generation"
|
||||
|
||||
# 使用 Qwen 分析特定领域的代码
|
||||
gemini analyze --tool qwen "分析医疗数据处理模块"
|
||||
```
|
||||
|
||||
通过理解这些智能工具及其用法，您可以更有效地利用 Gemini CLI，加速您的开发过程。
|
||||
537
.claude/skills/command-guide/guides/examples.md
Normal file
537
.claude/skills/command-guide/guides/examples.md
Normal file
@@ -0,0 +1,537 @@
|
||||
# Usage Examples
|
||||
|
||||
Comprehensive examples of command-guide skill in action across all 5 operation modes.
|
||||
|
||||
---
|
||||
|
||||
## Mode 1: Command Search 🔍
|
||||
|
||||
### Example 1: Keyword Search
|
||||
|
||||
**User**: "搜索包含 'execute' 的命令"
|
||||
|
||||
**Skill Response**:
|
||||
```
|
||||
找到 4 个相关命令：
|
||||
|
||||
1. **cli:execute** (高级)
|
||||
描述: Auto-execution of implementation tasks with YOLO permissions
|
||||
参数: [--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id
|
||||
场景: implementation
|
||||
|
||||
2. **task:execute** (中级)
|
||||
描述: Execute tasks with appropriate agents and context-aware orchestration
|
||||
参数: task-id
|
||||
场景: implementation
|
||||
|
||||
3. **workflow:execute** (中级)
|
||||
描述: Coordinate agents for existing workflow tasks with automatic discovery
|
||||
参数: [--resume-session="session-id"]
|
||||
场景: implementation
|
||||
|
||||
4. **codex-execute** (高级)
|
||||
描述: Automated task decomposition and execution with Codex
|
||||
参数: task description or task-id
|
||||
场景: implementation
|
||||
|
||||
💡 相关命令: workflow:plan, task:create
|
||||
📖 详细文档: [Implementation Commands](workflow-patterns.md#implementation)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Category Search
|
||||
|
||||
**User**: "cli 类别下有哪些命令？"
|
||||
|
||||
**Skill Response**:
|
||||
```
|
||||
CLI 类别包含 9 个命令：
|
||||
|
||||
**核心命令** (6个):
|
||||
- cli:analyze - Quick codebase analysis
|
||||
- cli:chat - Direct codebase interaction
|
||||
- cli:execute - Auto-execution with YOLO
|
||||
- cli:cli-init - Initialize CLI tool configs
|
||||
- cli:codex-execute - Codex-powered execution
|
||||
- cli:discuss-plan - Multi-model planning discussion
|
||||
|
||||
**模式命令** (3个):
|
||||
- cli:mode:plan - Project planning mode
|
||||
- cli:mode:code-analysis - Deep code analysis mode
|
||||
- cli:mode:bug-diagnosis - Bug diagnosis mode
|
||||
|
||||
📚 使用指南: [CLI Tools Guide](cli-tools-guide.md)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Use-Case Search
|
||||
|
||||
**User**: "planning 相关的命令有哪些？"
|
||||
|
||||
**Skill Response**:
|
||||
```
|
||||
Planning 场景包含 8 个命令：
|
||||
|
||||
**核心规划**:
|
||||
1. workflow:plan (高级) - 5阶段规划工作流
|
||||
2. cli:mode:plan (高级) - 项目规划和架构分析
|
||||
3. workflow:tdd-plan (高级) - TDD 规划工作流
|
||||
|
||||
**任务分解**:
|
||||
4. task:breakdown (中级) - 智能任务分解
|
||||
5. workflow:tools:task-generate (中级) - 生成任务 JSON
|
||||
|
||||
**架构设计**:
|
||||
6. workflow:brainstorm:system-architect (中级) - 系统架构师头脑风暴
|
||||
7. workflow:brainstorm:api-designer (中级) - API 设计师头脑风暴
|
||||
|
||||
**评估验证**:
|
||||
8. workflow:action-plan-verify (中级) - 规划质量验证
|
||||
|
||||
💡 常见工作流: Plan → Verify → Execute
|
||||
📖 模式参考: [Workflow Patterns](workflow-patterns.md#planning-workflow)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode 2: Smart Recommendations 🤖
|
||||
|
||||
### Example 1: After Planning
|
||||
|
||||
**User**: "执行完 /workflow:plan 后下一步做什么？"
|
||||
|
||||
**Skill Response**:
|
||||
```
|
||||
推荐的后续步骤：
|
||||
|
||||
**🎯 主要选择**:
|
||||
1. **/workflow:execute** - 开始执行规划的任务
|
||||
✅ 这是最常见的下一步
|
||||
作用: 实际执行 workflow:plan 生成的任务
|
||||
|
||||
**📋 可选步骤**:
|
||||
2. **/workflow:action-plan-verify** - 验证规划质量
|
||||
作用: 在执行前检查规划的一致性和完整性
|
||||
建议: 重要项目建议先验证
|
||||
|
||||
3. **/workflow:status** - 查看规划状态
|
||||
作用: 查看生成的任务和当前进度
|
||||
|
||||
**📚 完整工作流模式**:
|
||||
Plan → Verify (可选) → Execute → Review
|
||||
|
||||
详见: [Planning Workflow Pattern](workflow-patterns.md#planning-execution)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: After Execution
|
||||
|
||||
**User**: "workflow:execute 执行完成后，推荐做什么？"
|
||||
|
||||
**Skill Response**:
|
||||
```
|
||||
推荐的后续步骤：
|
||||
|
||||
**🎯 主要选择**:
|
||||
1. **/workflow:review** - 审查实现结果
|
||||
✅ 检查代码质量、安全性、架构
|
||||
参数: [--type=quality|security|architecture]
|
||||
|
||||
**📊 可选步骤**:
|
||||
2. **/workflow:status** - 查看执行状态
|
||||
作用: 确认所有任务都已完成
|
||||
|
||||
3. **/workflow:test-gen** - 生成测试
|
||||
作用: 为实现的功能创建测试用例
|
||||
|
||||
4. **/workflow:session:complete** - 完成会话
|
||||
作用: 标记工作流已完成，归档经验
|
||||
|
||||
**🔄 如果需要修改**:
|
||||
- /task:replan - 重新规划某个任务
|
||||
- /workflow:resume - 恢复工作流
|
||||
|
||||
详见: [Execution Review Pattern](workflow-patterns.md#execution-review)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode 3: Full Documentation 📖
|
||||
|
||||
### Example 1: Command Parameters
|
||||
|
||||
**User**: "/workflow:plan 的参数是什么？"
|
||||
|
||||
**Skill Response**:
|
||||
```
|
||||
# workflow:plan
|
||||
|
||||
**描述**: Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases
|
||||
|
||||
**参数**:
|
||||
```bash
|
||||
/workflow:plan [--agent] [--cli-execute] "text description"|file.md
|
||||
```
|
||||
|
||||
**参数说明**:
|
||||
- `--agent` (可选): 使用 agent 模式执行规划
|
||||
- `--cli-execute` (可选): 允许在规划阶段执行 CLI 命令
|
||||
- `"text description"`: 任务描述文本
|
||||
- `file.md`: 或者提供任务描述文件路径
|
||||
|
||||
**使用场景**: planning
|
||||
**难度级别**: 高级
|
||||
|
||||
**使用示例**:
|
||||
```bash
|
||||
# 基本用法
|
||||
/workflow:plan "实现用户认证功能"
|
||||
|
||||
# 使用 agent 模式
|
||||
/workflow:plan --agent "重构支付模块"
|
||||
|
||||
# 从文件读取
|
||||
/workflow:plan --agent feature-spec.md
|
||||
|
||||
# 允许 CLI 执行
|
||||
/workflow:plan --cli-execute "添加搜索功能"
|
||||
```
|
||||
|
||||
**执行流程**:
|
||||
1. 上下文收集
|
||||
2. 概念规划
|
||||
3. 实现规划
|
||||
4. 任务生成
|
||||
5. 质量验证
|
||||
|
||||
**相关命令**:
|
||||
- workflow:execute - 执行规划的任务
|
||||
- workflow:action-plan-verify - 验证规划质量
|
||||
- workflow:status - 查看规划状态
|
||||
|
||||
**详细文档**: ../../commands/workflow/plan.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode 4: Beginner Onboarding 🎓
|
||||
|
||||
### Example 1: Complete Beginner
|
||||
|
||||
**User**: "我是新手，如何开始使用工作流系统？"
|
||||
|
||||
**Skill Response**:
|
||||
```
|
||||
欢迎使用 Claude DMS3 工作流系统！🎉
|
||||
|
||||
## 🚀 快速开始（3 步）
|
||||
|
||||
### Step 1: 了解核心命令（Top 5）
|
||||
|
||||
1. **/workflow:plan** - 规划一个功能或任务
|
||||
用法: /workflow:plan "你想做的事情"
|
||||
|
||||
2. **/workflow:execute** - 执行规划的任务
|
||||
用法: /workflow:execute
|
||||
|
||||
3. **/cli:execute** - 快速自动执行
|
||||
用法: /cli:execute "实现XXX功能"
|
||||
|
||||
4. **/task:create** - 创建单个任务
|
||||
用法: /task:create "任务标题"
|
||||
|
||||
5. **/enhance-prompt** - 优化你的提示词
|
||||
用法: /enhance-prompt "你的想法"
|
||||
|
||||
### Step 2: 尝试第一个工作流
|
||||
|
||||
```bash
|
||||
# 1. 规划一个简单功能
|
||||
/workflow:plan "添加用户登录功能"
|
||||
|
||||
# 2. 执行规划
|
||||
/workflow:execute
|
||||
|
||||
# 3. 审查结果
|
||||
/workflow:review
|
||||
```
|
||||
|
||||
### Step 3: 学习资源
|
||||
|
||||
📖 **必读指南**:
|
||||
- [5分钟快速开始](getting-started.md)
|
||||
- [常见工作流模式](workflow-patterns.md)
|
||||
|
||||
🛠️ **工具指南**:
|
||||
- [CLI 工具使用](cli-tools-guide.md)
|
||||
- [问题排查](troubleshooting.md)
|
||||
|
||||
💡 **下一步建议**:
|
||||
1. 阅读 getting-started.md（5分钟）
|
||||
2. 尝试上面的第一个工作流
|
||||
3. 探索更多命令: 询问 "常用命令有哪些"
|
||||
|
||||
有问题随时问 "CCW-help"！
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Intermediate User
|
||||
|
||||
**User**: "常用命令有哪些？"
|
||||
|
||||
**Skill Response**:
|
||||
```
|
||||
## 核心命令列表（Top 14）
|
||||
|
||||
### 🎯 工作流管理 (5个)
|
||||
1. workflow:plan - 5阶段规划
|
||||
2. workflow:execute - 执行任务
|
||||
3. workflow:review - 审查实现
|
||||
4. workflow:tdd-plan - TDD 规划
|
||||
5. workflow:test-gen - 生成测试
|
||||
|
||||
### 🛠️ CLI 工具 (3个)
|
||||
6. cli:execute - 自动执行
|
||||
7. cli:mode:plan - 规划模式
|
||||
8. cli:analyze - 代码分析
|
||||
|
||||
### 📋 任务管理 (3个)
|
||||
9. task:create - 创建任务
|
||||
10. task:execute - 执行任务
|
||||
11. task:breakdown - 分解任务
|
||||
|
||||
### 🔧 实用工具 (2个)
|
||||
12. enhance-prompt - 提示词增强
|
||||
13. version - 版本信息
|
||||
|
||||
### 💡 使用频率
|
||||
- **每天**: workflow:plan, workflow:execute, cli:execute
|
||||
- **经常**: task:create, enhance-prompt
|
||||
- **按需**: workflow:review, test-gen, tdd-plan
|
||||
|
||||
📚 详细文档: [Index Structure](index-structure.md#essential-commands)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode 5: Issue Reporting 📝
|
||||
|
||||
### Example 1: Bug Report
|
||||
|
||||
**User**: "CCW-issue"
|
||||
|
||||
**Skill (Interactive)**:
|
||||
```
|
||||
请选择问题类型：
|
||||
1. 🐛 Bug 报告
|
||||
2. ✨ 功能请求
|
||||
3. ❓ 问题咨询
|
||||
```
|
||||
|
||||
**User**: "1"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
好的，我将帮您创建 Bug 报告。请回答以下问题：
|
||||
|
||||
1. 简要描述问题：
|
||||
```
|
||||
|
||||
**User**: "/workflow:plan 执行后没有生成任务文件"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
2. 您执行的完整命令是什么？
|
||||
```
|
||||
|
||||
**User**: "/workflow:plan '添加登录功能'"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
3. 期望的结果是什么？
|
||||
```
|
||||
|
||||
**User**: "应该在 .workflow/ 目录生成 task.json"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
4. 实际发生了什么？
|
||||
```
|
||||
|
||||
**User**: "命令执行了但没有生成文件"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
✅ Bug 报告已生成！
|
||||
|
||||
文件路径: templates/.generated/bug-2025-01-06-123456.md
|
||||
|
||||
--- 报告内容 ---
|
||||
# Bug 报告
|
||||
|
||||
## 问题描述
|
||||
/workflow:plan 执行后没有生成任务文件
|
||||
|
||||
## 执行的命令
|
||||
```bash
|
||||
/workflow:plan '添加登录功能'
|
||||
```
|
||||
|
||||
## 期望行为
|
||||
应该在 .workflow/ 目录生成 task.json
|
||||
|
||||
## 实际行为
|
||||
命令执行了但没有生成文件
|
||||
|
||||
## 环境信息
|
||||
- 操作系统: Windows
|
||||
- 报告日期: 2025-01-06
|
||||
- 相关命令: /workflow:plan
|
||||
|
||||
---
|
||||
|
||||
**下一步操作**:
|
||||
1. 复制以上内容到 GitHub Issues
|
||||
2. 或使用: gh issue create -F templates/.generated/bug-2025-01-06-123456.md
|
||||
|
||||
需要更多帮助？使用 "CCW-help"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Feature Request
|
||||
|
||||
**User**: "我想提个功能建议"
|
||||
|
||||
**Skill (Interactive)**:
|
||||
```
|
||||
请选择问题类型：
|
||||
1. 🐛 Bug 报告
|
||||
2. ✨ 功能请求
|
||||
3. ❓ 问题咨询
|
||||
```
|
||||
|
||||
**User**: "2"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
好的，功能请求。请描述：
|
||||
|
||||
1. 您希望添加什么功能？
|
||||
```
|
||||
|
||||
**User**: "希望 /workflow:plan 能自动估算任务时间"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
2. 这个功能解决什么问题？
|
||||
```
|
||||
|
||||
**User**: "帮助更好地规划项目进度和资源分配"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
3. 具体的使用场景是什么？（可选）
|
||||
```
|
||||
|
||||
**User**: "规划大型项目时，能看到预计完成时间"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
✅ 功能请求已生成！
|
||||
|
||||
文件路径: templates/.generated/feature-2025-01-06-123457.md
|
||||
|
||||
--- 内容预览 ---
|
||||
# 功能请求
|
||||
|
||||
## 功能概述
|
||||
希望 /workflow:plan 能自动估算任务时间
|
||||
|
||||
## 问题背景
|
||||
帮助更好地规划项目进度和资源分配
|
||||
|
||||
## 使用场景
|
||||
规划大型项目时，能看到预计完成时间
|
||||
|
||||
## 优先级
|
||||
- [ ] 高 - 严重影响工作效率
|
||||
- [x] 中 - 有明显改善但有变通方案
|
||||
- [ ] 低 - 锦上添花
|
||||
|
||||
---
|
||||
|
||||
可以复制到 GitHub 提交，或使用:
|
||||
gh issue create -F templates/.generated/feature-2025-01-06-123457.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases & Error Handling
|
||||
|
||||
### Case 1: No Results Found
|
||||
|
||||
**User**: "搜索 xyz 命令"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
❌ 未找到包含 "xyz" 的命令
|
||||
|
||||
💡 建议：
|
||||
1. 尝试更广泛的关键词（如 "plan", "execute", "test"）
|
||||
2. 按类别浏览：workflow, cli, memory, task
|
||||
3. 查看所有常用命令：询问 "常用命令"
|
||||
4. 需要帮助：使用 "CCW-help"
|
||||
|
||||
📚 快速参考：[All Commands Index](index-structure.md#all-commands)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Case 2: Ambiguous Query
|
||||
|
||||
**User**: "命令"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
您想了解什么？请选择：
|
||||
|
||||
1. 🔍 搜索特定命令
|
||||
2. 🤖 获取命令推荐
|
||||
3. 📖 查看命令文档
|
||||
4. 🎓 新手入门指导
|
||||
5. 📝 报告问题或建议
|
||||
|
||||
或者直接说出具体需求，例如：
|
||||
- "搜索 planning 命令"
|
||||
- "执行完 /workflow:plan 下一步做什么"
|
||||
- "/task:create 怎么用"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Case 3: Multiple Matches
|
||||
|
||||
**User**: "execute 命令"
|
||||
|
||||
**Skill**:
|
||||
```
|
||||
找到多个相关命令，请选择您需要的：
|
||||
|
||||
1. **cli:execute** - CLI 自动执行（推荐新手）
|
||||
2. **task:execute** - 执行单个任务
|
||||
3. **workflow:execute** - 执行整个工作流
|
||||
|
||||
或者询问：
|
||||
- "cli:execute 的详细文档"
|
||||
- "三者有什么区别"
|
||||
- "我该用哪个"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-06
|
||||
95
.claude/skills/command-guide/guides/getting-started.md
Normal file
95
.claude/skills/command-guide/guides/getting-started.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# 5分钟快速上手指南
|
||||
|
||||
欢迎来到 Gemini CLI！本指南将帮助您快速了解核心命令，并通过一个简单的工作流示例，让您在5分钟内开始使用。
|
||||
|
||||
## 1. Gemini CLI 简介
|
||||
|
||||
Gemini CLI 是一个强大的命令行工具，旨在通过智能代理和自动化工作流，提升您的开发效率。它能够帮助您进行代码分析、任务规划、代码生成、测试以及文档编写等。
|
||||
|
||||
## 2. 核心命令速览
|
||||
|
||||
以下是一些您将频繁使用的核心命令：
|
||||
|
||||
### `version` - 查看版本信息
|
||||
- **用途**: 检查当前 CLI 版本并获取更新信息。
|
||||
- **示例**:
|
||||
```bash
|
||||
gemini version
|
||||
```
|
||||
|
||||
### `enhance-prompt` - 智能提示增强
|
||||
- **用途**: 根据当前会话记忆和代码库分析，智能地优化您的输入提示，让代理更好地理解您的意图。
|
||||
- **示例**:
|
||||
```bash
|
||||
gemini enhance-prompt "如何修复这个bug？"
|
||||
```
|
||||
|
||||
### `analyze` - 快速代码分析
|
||||
- **用途**: 使用 CLI 工具（如 Codex, Gemini, Qwen）对代码库进行快速分析，获取洞察。
|
||||
- **示例**:
|
||||
```bash
|
||||
gemini analyze "分析 src/main.py 中的性能瓶颈"
|
||||
```
|
||||
|
||||
### `chat` - 交互式对话
|
||||
- **用途**: 与 CLI 进行简单的交互式对话，直接进行代码分析或提问。
|
||||
- **示例**:
|
||||
```bash
|
||||
gemini chat "解释一下 UserService.java 的主要功能"
|
||||
```
|
||||
|
||||
### `plan` - 项目规划与架构分析
|
||||
- **用途**: 启动项目规划和架构分析工作流，帮助您将复杂问题分解为可执行的任务。
|
||||
- **示例**:
|
||||
```bash
|
||||
gemini plan "实现用户认证模块"
|
||||
```
|
||||
|
||||
### `create` - 创建实现任务
|
||||
- **用途**: 根据上下文创建具体的实现任务。
|
||||
- **示例**:
|
||||
```bash
|
||||
gemini create "编写用户注册接口"
|
||||
```
|
||||
|
||||
### `execute` - 自动执行任务
|
||||
- **用途**: 自动执行实现任务，智能地推断上下文并协调代理完成工作。
|
||||
- **示例**:
|
||||
```bash
|
||||
gemini execute "task-id-123"
|
||||
```
|
||||
|
||||
## 3. 第一个工作流示例：规划与执行一个简单任务
|
||||
|
||||
让我们通过一个简单的例子来体验 Gemini CLI 的工作流：**规划并实现一个“Hello World”函数**。
|
||||
|
||||
1. **规划任务**:
|
||||
首先，我们使用 `plan` 命令来规划我们的“Hello World”功能。
|
||||
```bash
|
||||
gemini plan "实现一个打印 'Hello World!' 的 Python 函数"
|
||||
```
|
||||
CLI 将会启动一个规划工作流，可能会询问您一些问题，并最终生成一个或多个任务。
|
||||
|
||||
2. **创建具体任务**:
|
||||
假设 `plan` 命令为您生成了一个任务 ID，或者您想手动创建一个任务。
|
||||
```bash
|
||||
gemini create "编写 Python 函数 `say_hello` 打印 'Hello World!'"
|
||||
```
|
||||
这个命令会创建一个新的任务，并返回一个任务 ID。
|
||||
|
||||
3. **执行任务**:
|
||||
现在，我们使用 `execute` 命令来让 CLI 自动完成这个任务。请将 `your-task-id` 替换为上一步中获得的实际任务 ID。
|
||||
```bash
|
||||
gemini execute "your-task-id"
|
||||
```
|
||||
CLI 将会调用智能代理，根据任务描述生成代码，并尝试将其写入文件。
|
||||
|
||||
通过这三个简单的步骤，您就完成了一个从规划到执行的完整工作流。
|
||||
|
||||
## 4. 接下来做什么？
|
||||
|
||||
- 探索更多命令：使用 `gemini help` 查看所有可用命令。
|
||||
- 查阅其他指南：深入了解工作流模式、CLI 工具使用和故障排除。
|
||||
- 尝试更复杂的任务：挑战自己，使用 Gemini CLI 解决实际项目中的问题。
|
||||
|
||||
祝您使用愉快！
|
||||
526
.claude/skills/command-guide/guides/implementation-details.md
Normal file
526
.claude/skills/command-guide/guides/implementation-details.md
Normal file
@@ -0,0 +1,526 @@
|
||||
# Implementation Details
|
||||
|
||||
Detailed implementation logic for command-guide skill operation modes.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
User Query
|
||||
↓
|
||||
Intent Recognition
|
||||
↓
|
||||
Mode Selection (1 of 5)
|
||||
↓
|
||||
Index/File Query
|
||||
↓
|
||||
Response Formation
|
||||
↓
|
||||
User Output + Recommendations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Intent Recognition
|
||||
|
||||
### Step 1: Parse User Input
|
||||
|
||||
Analyze query for trigger keywords and patterns:
|
||||
|
||||
```javascript
|
||||
function recognizeIntent(userQuery) {
|
||||
const query = userQuery.toLowerCase();
|
||||
|
||||
// Mode 5: Issue Reporting (highest priority)
|
||||
if (query.includes('ccw-issue') || query.includes('ccw-help') ||
|
||||
query.match(/报告.*bug/) || query.includes('功能建议')) {
|
||||
return 'ISSUE_REPORTING';
|
||||
}
|
||||
|
||||
// Mode 1: Command Search
|
||||
if (query.includes('搜索') || query.includes('find') ||
|
||||
query.includes('search') || query.match(/.*相关.*命令/)) {
|
||||
return 'COMMAND_SEARCH';
|
||||
}
|
||||
|
||||
// Mode 2: Recommendations
|
||||
if (query.includes('下一步') || query.includes("what's next") ||
|
||||
query.includes('推荐') || query.match(/after.*\/\w+:\w+/)) {
|
||||
return 'RECOMMENDATIONS';
|
||||
}
|
||||
|
||||
// Mode 3: Documentation
|
||||
if (query.includes('参数') || query.includes('怎么用') ||
|
||||
query.includes('如何使用') || query.match(/\/\w+:\w+.*详情/)) {
|
||||
return 'DOCUMENTATION';
|
||||
}
|
||||
|
||||
// Mode 4: Onboarding
|
||||
if (query.includes('新手') || query.includes('入门') ||
|
||||
query.includes('getting started') || query.includes('常用命令')) {
|
||||
return 'ONBOARDING';
|
||||
}
|
||||
|
||||
// Default: Ask for clarification
|
||||
return 'CLARIFY';
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode 1: Command Search 🔍
|
||||
|
||||
### Trigger Analysis
|
||||
|
||||
**Keywords**: 搜索, find, search, [topic] 相关命令
|
||||
|
||||
**Examples**:
|
||||
- "搜索 planning 命令"
|
||||
- "find commands for testing"
|
||||
- "实现相关的命令有哪些"
|
||||
|
||||
### Processing Flow
|
||||
|
||||
```
|
||||
1. Extract Search Parameters
|
||||
↓
|
||||
2. Determine Search Type
|
||||
├─ Keyword Search (in name/description)
|
||||
├─ Category Search (workflow/cli/memory/task)
|
||||
└─ Use-Case Search (planning/implementation/testing)
|
||||
↓
|
||||
3. Query Appropriate Index
|
||||
├─ Keyword → all-commands.json
|
||||
├─ Category → by-category.json
|
||||
└─ Use-Case → by-use-case.json
|
||||
↓
|
||||
4. Filter and Rank Results
|
||||
↓
|
||||
5. Format Response
|
||||
├─ List matching commands
|
||||
├─ Show key metadata (name, description, args)
|
||||
└─ Suggest related commands
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
```javascript
|
||||
async function searchCommands(query, searchType) {
|
||||
let results = [];
|
||||
|
||||
switch (searchType) {
|
||||
case 'keyword':
|
||||
// Load all-commands.json
|
||||
const allCommands = await readIndex('all-commands.json');
|
||||
results = allCommands.filter(cmd =>
|
||||
cmd.name.toLowerCase().includes(query.toLowerCase()) ||
|
||||
cmd.description.toLowerCase().includes(query.toLowerCase())
|
||||
);
|
||||
break;
|
||||
|
||||
case 'category':
|
||||
// Load by-category.json
|
||||
const byCategory = await readIndex('by-category.json');
|
||||
const category = extractCategory(query); // e.g., "workflow"
|
||||
results = flattenCategory(byCategory[category]);
|
||||
break;
|
||||
|
||||
case 'use-case':
|
||||
// Load by-use-case.json
|
||||
const byUseCase = await readIndex('by-use-case.json');
|
||||
const useCase = extractUseCase(query); // e.g., "planning"
|
||||
results = byUseCase[useCase] || [];
|
||||
break;
|
||||
}
|
||||
|
||||
// Rank by relevance
|
||||
results = rankResults(results, query);
|
||||
|
||||
// Add related commands
|
||||
results = await enrichWithRelated(results);
|
||||
|
||||
return results;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode 2: Smart Recommendations 🤖
|
||||
|
||||
### Trigger Analysis
|
||||
|
||||
**Keywords**: 下一步, what's next, 推荐, after [command]
|
||||
|
||||
**Examples**:
|
||||
- "执行完 /workflow:plan 后做什么？"
|
||||
- "What's next after planning?"
|
||||
- "推荐下一个命令"
|
||||
|
||||
### Processing Flow
|
||||
|
||||
```
|
||||
1. Extract Context
|
||||
├─ Current/Last Command
|
||||
├─ Workflow State
|
||||
└─ User's Current Task
|
||||
↓
|
||||
2. Query Relationships
|
||||
└─ Load command-relationships.json
|
||||
↓
|
||||
3. Find Next Steps
|
||||
├─ Check next_steps array
|
||||
├─ Consider prerequisites
|
||||
└─ Check related_commands
|
||||
↓
|
||||
4. Generate Recommendations
|
||||
├─ Primary recommendation (most common next step)
|
||||
├─ Alternative options
|
||||
└─ Rationale for each
|
||||
↓
|
||||
5. Add Workflow Context
|
||||
└─ Link to workflow-patterns.md
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
```javascript
|
||||
async function getRecommendations(currentCommand) {
|
||||
// Load relationships
|
||||
const relationships = await readIndex('command-relationships.json');
|
||||
|
||||
// Get relationship data
|
||||
const cmdData = relationships[currentCommand];
|
||||
|
||||
if (!cmdData) {
|
||||
return defaultRecommendations();
|
||||
}
|
||||
|
||||
// Primary next steps
|
||||
const nextSteps = cmdData.next_steps || [];
|
||||
|
||||
// Alternative related commands
|
||||
const alternatives = cmdData.related_commands || [];
|
||||
|
||||
// Build recommendations
|
||||
const recommendations = {
|
||||
primary: await enrichCommand(nextSteps[0]),
|
||||
alternatives: await enrichCommands(alternatives),
|
||||
workflow_pattern: findWorkflowPattern(currentCommand),
|
||||
rationale: generateRationale(currentCommand, nextSteps[0])
|
||||
};
|
||||
|
||||
return recommendations;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode 3: Full Documentation 📖
|
||||
|
||||
### Trigger Analysis
|
||||
|
||||
**Keywords**: 参数, 怎么用, 如何使用, [command] 详情
|
||||
|
||||
**Examples**:
|
||||
- "/workflow:plan 的参数是什么？"
|
||||
- "如何使用 /cli:execute？"
|
||||
- "task:create 详细文档"
|
||||
|
||||
### Processing Flow
|
||||
|
||||
```
|
||||
1. Extract Command Name
|
||||
└─ Parse /workflow:plan or workflow:plan
|
||||
↓
|
||||
2. Locate in Index
|
||||
└─ Search all-commands.json
|
||||
↓
|
||||
3. Read Full Command File
|
||||
└─ Use file_path from index
|
||||
↓
|
||||
4. Extract Documentation
|
||||
├─ Parameters section
|
||||
├─ Arguments specification
|
||||
├─ Examples section
|
||||
└─ Best practices
|
||||
↓
|
||||
5. Format Response
|
||||
├─ Command overview
|
||||
├─ Full parameter list
|
||||
├─ Usage examples
|
||||
└─ Related commands
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
```javascript
|
||||
async function getDocumentation(commandName) {
|
||||
// Normalize command name
|
||||
const normalized = normalizeCommandName(commandName);
|
||||
|
||||
// Find in index
|
||||
const allCommands = await readIndex('all-commands.json');
|
||||
const command = allCommands.find(cmd => cmd.name === normalized);
|
||||
|
||||
if (!command) {
|
||||
return { error: 'Command not found' };
|
||||
}
|
||||
|
||||
// Read full command file
|
||||
const commandFilePath = path.join(
|
||||
'../commands',
|
||||
command.file_path
|
||||
);
|
||||
const fullDoc = await readCommandFile(commandFilePath);
|
||||
|
||||
// Parse sections
|
||||
const documentation = {
|
||||
name: command.name,
|
||||
description: command.description,
|
||||
arguments: command.arguments,
|
||||
difficulty: command.difficulty,
|
||||
usage_scenario: command.usage_scenario,
|
||||
parameters: extractSection(fullDoc, '## Parameters'),
|
||||
examples: extractSection(fullDoc, '## Examples'),
|
||||
best_practices: extractSection(fullDoc, '## Best Practices'),
|
||||
related: await getRelatedCommands(command.name)
|
||||
};
|
||||
|
||||
return documentation;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode 4: Beginner Onboarding 🎓
|
||||
|
||||
### Trigger Analysis
|
||||
|
||||
**Keywords**: 新手, 入门, getting started, 常用命令, 如何开始
|
||||
|
||||
**Examples**:
|
||||
- "我是新手，如何开始？"
|
||||
- "getting started with workflows"
|
||||
- "最常用的命令有哪些？"
|
||||
|
||||
### Processing Flow
|
||||
|
||||
```
|
||||
1. Assess User Level
|
||||
└─ Identify as beginner
|
||||
↓
|
||||
2. Load Essential Commands
|
||||
└─ Read essential-commands.json
|
||||
↓
|
||||
3. Build Learning Path
|
||||
├─ Step 1: Core commands (Top 5)
|
||||
├─ Step 2: Basic workflow
|
||||
├─ Step 3: Intermediate commands
|
||||
└─ Step 4: Advanced features
|
||||
↓
|
||||
4. Provide Resources
|
||||
├─ Link to getting-started.md
|
||||
├─ Link to workflow-patterns.md
|
||||
└─ Suggest first task
|
||||
↓
|
||||
5. Interactive Guidance
|
||||
└─ Offer to walk through first workflow
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
```javascript
|
||||
async function onboardBeginner() {
|
||||
// Load essential commands
|
||||
const essentialCommands = await readIndex('essential-commands.json');
|
||||
|
||||
// Group by difficulty
|
||||
const beginner = essentialCommands.filter(cmd =>
|
||||
cmd.difficulty === 'Beginner' || cmd.difficulty === 'Intermediate'
|
||||
);
|
||||
|
||||
// Create learning path
|
||||
const learningPath = {
|
||||
step1: {
|
||||
title: 'Core Commands (Start Here)',
|
||||
commands: beginner.slice(0, 5),
|
||||
guide: 'guides/getting-started.md'
|
||||
},
|
||||
step2: {
|
||||
title: 'Your First Workflow',
|
||||
pattern: 'Plan → Execute',
|
||||
commands: ['workflow:plan', 'workflow:execute'],
|
||||
guide: 'guides/workflow-patterns.md#basic-workflow'
|
||||
},
|
||||
step3: {
|
||||
title: 'Intermediate Skills',
|
||||
commands: beginner.slice(5, 10),
|
||||
guide: 'guides/workflow-patterns.md#common-patterns'
|
||||
}
|
||||
};
|
||||
|
||||
// Resources
|
||||
const resources = {
|
||||
getting_started: 'guides/getting-started.md',
|
||||
workflow_patterns: 'guides/workflow-patterns.md',
|
||||
cli_tools: 'guides/cli-tools-guide.md',
|
||||
troubleshooting: 'guides/troubleshooting.md'
|
||||
};
|
||||
|
||||
return {
|
||||
learning_path: learningPath,
|
||||
resources: resources,
|
||||
first_task: 'Try: /workflow:plan "create a simple feature"'
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode 5: Issue Reporting 📝
|
||||
|
||||
### Trigger Analysis
|
||||
|
||||
**Keywords**: CCW-issue, CCW-help, 报告 bug, 功能建议, 问题咨询
|
||||
|
||||
**Examples**:
|
||||
- "CCW-issue"
|
||||
- "我要报告一个 bug"
|
||||
- "CCW-help 有问题"
|
||||
- "想提个功能建议"
|
||||
|
||||
### Processing Flow
|
||||
|
||||
```
|
||||
1. Detect Issue Type
|
||||
└─ Use AskUserQuestion if unclear
|
||||
↓
|
||||
2. Select Template
|
||||
├─ Bug → templates/issue-bug.md
|
||||
├─ Feature → templates/issue-feature.md
|
||||
└─ Question → templates/issue-question.md
|
||||
↓
|
||||
3. Collect Information
|
||||
└─ Interactive Q&A
|
||||
├─ Problem description
|
||||
├─ Steps to reproduce (bug)
|
||||
├─ Expected vs actual (bug)
|
||||
├─ Use case (feature)
|
||||
└─ Context
|
||||
↓
|
||||
4. Generate Filled Template
|
||||
└─ Populate template with collected data
|
||||
↓
|
||||
5. Save or Display
|
||||
├─ Save to templates/.generated/
|
||||
└─ Display for user to copy
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
```javascript
|
||||
async function reportIssue(issueType) {
|
||||
// Determine type (bug/feature/question)
|
||||
if (!issueType) {
|
||||
issueType = await askUserQuestion({
|
||||
question: 'What type of issue would you like to report?',
|
||||
options: ['Bug Report', 'Feature Request', 'Question']
|
||||
});
|
||||
}
|
||||
|
||||
// Select template
|
||||
const templatePath = {
|
||||
'bug': 'templates/issue-bug.md',
|
||||
'feature': 'templates/issue-feature.md',
|
||||
'question': 'templates/issue-question.md'
|
||||
}[issueType.toLowerCase()];
|
||||
|
||||
const template = await readTemplate(templatePath);
|
||||
|
||||
// Collect information
|
||||
const info = await collectIssueInfo(issueType);
|
||||
|
||||
// Fill template
|
||||
const filledTemplate = fillTemplate(template, {
|
||||
...info,
|
||||
timestamp: new Date().toISOString(),
|
||||
auto_context: gatherAutoContext()
|
||||
});
|
||||
|
||||
// Save
|
||||
const outputPath = `templates/.generated/${issueType}-${Date.now()}.md`;
|
||||
await writeFile(outputPath, filledTemplate);
|
||||
|
||||
return {
|
||||
template: filledTemplate,
|
||||
file_path: outputPath,
|
||||
instructions: 'Copy content to GitHub Issues or use: gh issue create -F ' + outputPath
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Not Found
|
||||
```javascript
|
||||
if (results.length === 0) {
|
||||
return {
|
||||
message: 'No commands found matching your query.',
|
||||
suggestions: [
|
||||
'Try broader keywords',
|
||||
'Browse by category: workflow, cli, memory, task',
|
||||
'View all commands: essential-commands.json',
|
||||
'Need help? Ask: "CCW-help"'
|
||||
]
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Ambiguous Intent
|
||||
```javascript
|
||||
if (intent === 'CLARIFY') {
|
||||
return await askUserQuestion({
|
||||
question: 'What would you like to do?',
|
||||
options: [
|
||||
'Search for commands',
|
||||
'Get recommendations for next steps',
|
||||
'View command documentation',
|
||||
'Learn how to get started',
|
||||
'Report an issue or get help'
|
||||
]
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Optimization Strategies
|
||||
|
||||
### Caching
|
||||
```javascript
|
||||
// Cache indexes in memory after first load
|
||||
const indexCache = new Map();
|
||||
|
||||
async function readIndex(filename) {
|
||||
if (indexCache.has(filename)) {
|
||||
return indexCache.get(filename);
|
||||
}
|
||||
|
||||
const data = await readFile(`index/${filename}`);
|
||||
const parsed = JSON.parse(data);
|
||||
indexCache.set(filename, parsed);
|
||||
return parsed;
|
||||
}
|
||||
```
|
||||
|
||||
### Lazy Loading
|
||||
```javascript
|
||||
// Only load full command files when needed
|
||||
// Use index metadata for most queries
|
||||
// Read command file only for Mode 3 (Documentation)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-06
|
||||
326
.claude/skills/command-guide/guides/index-structure.md
Normal file
326
.claude/skills/command-guide/guides/index-structure.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# Index Structure Reference
|
||||
|
||||
Complete documentation for command index files and their data structures.
|
||||
|
||||
## Overview
|
||||
|
||||
The command-guide skill uses 5 JSON index files to organize and query 69 commands across the Claude DMS3 workflow system.
|
||||
|
||||
## Index Files
|
||||
|
||||
### 1. `all-commands.json`
|
||||
|
||||
**Purpose**: Complete catalog of all commands with full metadata
|
||||
|
||||
**Use Cases**:
|
||||
- Full-text search across all commands
|
||||
- Detailed command queries
|
||||
- Batch operations
|
||||
- Reference lookup
|
||||
|
||||
**Structure**:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "workflow:plan",
|
||||
"description": "Orchestrate 5-phase planning workflow with quality gate",
|
||||
"arguments": "[--agent] [--cli-execute] \"text description\"|file.md",
|
||||
"category": "workflow",
|
||||
"subcategory": "core",
|
||||
"usage_scenario": "planning",
|
||||
"difficulty": "Advanced",
|
||||
"file_path": "workflow/plan.md"
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
- `name` (string): Command name (e.g., "workflow:plan")
|
||||
- `description` (string): Brief functional description
|
||||
- `arguments` (string): Parameter specification
|
||||
- `category` (string): Primary category (workflow/cli/memory/task)
|
||||
- `subcategory` (string|null): Secondary grouping if applicable
|
||||
- `usage_scenario` (string): Primary use case (planning/implementation/testing/etc.)
|
||||
- `difficulty` (string): Skill level (Beginner/Intermediate/Advanced)
|
||||
- `file_path` (string): Relative path to command file
|
||||
|
||||
**Total Records**: 69 commands
|
||||
|
||||
---
|
||||
|
||||
### 2. `by-category.json`
|
||||
|
||||
**Purpose**: Hierarchical organization by category and subcategory
|
||||
|
||||
**Use Cases**:
|
||||
- Browse commands by category
|
||||
- Category-specific listings
|
||||
- Hierarchical navigation
|
||||
- Understanding command organization
|
||||
|
||||
**Structure**:
|
||||
```json
|
||||
{
|
||||
"workflow": {
|
||||
"core": [
|
||||
{
|
||||
"name": "workflow:plan",
|
||||
"description": "...",
|
||||
...
|
||||
}
|
||||
],
|
||||
"brainstorm": [...],
|
||||
"session": [...],
|
||||
"tools": [...],
|
||||
"ui-design": [...]
|
||||
},
|
||||
"cli": {
|
||||
"mode": [...],
|
||||
"core": [...]
|
||||
},
|
||||
"memory": [...],
|
||||
"task": [...]
|
||||
}
|
||||
```
|
||||
|
||||
**Category Breakdown**:
|
||||
- **workflow** (46 commands):
|
||||
- core: 11 commands
|
||||
- brainstorm: 12 commands
|
||||
- session: 4 commands
|
||||
- tools: 9 commands
|
||||
- ui-design: 10 commands
|
||||
- **cli** (9 commands):
|
||||
- mode: 3 commands
|
||||
- core: 6 commands
|
||||
- **memory** (8 commands)
|
||||
- **task** (4 commands)
|
||||
- **general** (2 commands)
|
||||
|
||||
---
|
||||
|
||||
### 3. `by-use-case.json`
|
||||
|
||||
**Purpose**: Commands organized by practical usage scenarios
|
||||
|
||||
**Use Cases**:
|
||||
- Task-oriented command discovery
|
||||
- "I want to do X" queries
|
||||
- Workflow planning
|
||||
- Learning paths
|
||||
|
||||
**Structure**:
|
||||
```json
|
||||
{
|
||||
"planning": [
|
||||
{
|
||||
"name": "workflow:plan",
|
||||
"description": "...",
|
||||
...
|
||||
},
|
||||
...
|
||||
],
|
||||
"implementation": [...],
|
||||
"testing": [...],
|
||||
"documentation": [...],
|
||||
"session-management": [...],
|
||||
"general": [...]
|
||||
}
|
||||
```
|
||||
|
||||
**Use Case Categories**:
|
||||
- **planning**: Architecture, task breakdown, design
|
||||
- **implementation**: Coding, development, execution
|
||||
- **testing**: Test generation, TDD, quality assurance
|
||||
- **documentation**: Docs generation, memory management
|
||||
- **session-management**: Workflow control, resumption
|
||||
- **general**: Utilities, versioning, prompt enhancement
|
||||
|
||||
---
|
||||
|
||||
### 4. `essential-commands.json`
|
||||
|
||||
**Purpose**: Curated list of 10-15 most frequently used commands
|
||||
|
||||
**Use Cases**:
|
||||
- Quick reference for beginners
|
||||
- Onboarding new users
|
||||
- Common workflow starters
|
||||
- Cheat sheet
|
||||
|
||||
**Structure**:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "enhance-prompt",
|
||||
"description": "Context-aware prompt enhancement",
|
||||
"arguments": "\"user input to enhance\"",
|
||||
"category": "general",
|
||||
"subcategory": null,
|
||||
"usage_scenario": "general",
|
||||
"difficulty": "Intermediate",
|
||||
"file_path": "enhance-prompt.md"
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
**Selection Criteria**:
|
||||
- Frequency of use in common workflows
|
||||
- Value for beginners
|
||||
- Core functionality coverage
|
||||
- Minimal overlap in capabilities
|
||||
|
||||
**Current Count**: 14 commands
|
||||
|
||||
**List**:
|
||||
1. `enhance-prompt` - Prompt enhancement
|
||||
2. `version` - Version info
|
||||
3. `cli:analyze` - Quick codebase analysis
|
||||
4. `cli:chat` - Direct CLI interaction
|
||||
5. `cli:execute` - Auto-execution
|
||||
6. `cli:mode:plan` - Planning mode
|
||||
7. `task:breakdown` - Task decomposition
|
||||
8. `task:create` - Create tasks
|
||||
9. `task:execute` - Execute tasks
|
||||
10. `workflow:execute` - Run workflows
|
||||
11. `workflow:plan` - Plan workflows
|
||||
12. `workflow:review` - Review implementation
|
||||
13. `workflow:tdd-plan` - TDD planning
|
||||
14. `workflow:test-gen` - Test generation
|
||||
|
||||
---
|
||||
|
||||
### 5. `command-relationships.json`
|
||||
|
||||
**Purpose**: Mapping of command dependencies and common sequences
|
||||
|
||||
**Use Cases**:
|
||||
- Next-step recommendations
|
||||
- Workflow pattern suggestions
|
||||
- Related command discovery
|
||||
- Smart navigation
|
||||
|
||||
**Structure**:
|
||||
```json
|
||||
{
|
||||
"workflow:plan": {
|
||||
"related_commands": [
|
||||
"workflow:execute",
|
||||
"workflow:action-plan-verify"
|
||||
],
|
||||
"next_steps": ["workflow:execute"],
|
||||
"prerequisites": []
|
||||
},
|
||||
"workflow:execute": {
|
||||
"related_commands": [
|
||||
"workflow:status",
|
||||
"workflow:resume",
|
||||
"workflow:review"
|
||||
],
|
||||
"next_steps": ["workflow:review", "workflow:status"],
|
||||
"prerequisites": ["workflow:plan"]
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**Fields**:
|
||||
- `related_commands` (array): Commonly used together
|
||||
- `next_steps` (array): Typical next commands
|
||||
- `prerequisites` (array): Usually run before this command
|
||||
|
||||
**Relationship Types**:
|
||||
1. **Sequential**: A → B (plan → execute)
|
||||
2. **Alternatives**: A | B (execute OR codex-execute)
|
||||
3. **Built-in**: A includes B (plan auto-includes context-gather)
|
||||
|
||||
---
|
||||
|
||||
## Query Patterns
|
||||
|
||||
### Pattern 1: Keyword Search
|
||||
```javascript
|
||||
// Search by keyword in name or description
|
||||
const results = allCommands.filter(cmd =>
|
||||
cmd.name.includes(keyword) ||
|
||||
cmd.description.toLowerCase().includes(keyword.toLowerCase())
|
||||
);
|
||||
```
|
||||
|
||||
### Pattern 2: Category Browse
|
||||
```javascript
|
||||
// Get all commands in a category
|
||||
const workflowCommands = byCategory.workflow;
|
||||
const coreWorkflow = byCategory.workflow.core;
|
||||
```
|
||||
|
||||
### Pattern 3: Use-Case Lookup
|
||||
```javascript
|
||||
// Find commands for specific use case
|
||||
const planningCommands = byUseCase.planning;
|
||||
```
|
||||
|
||||
### Pattern 4: Related Commands
|
||||
```javascript
|
||||
// Get next steps after a command
|
||||
const nextSteps = commandRelationships["workflow:plan"].next_steps;
|
||||
```
|
||||
|
||||
### Pattern 5: Essential Commands
|
||||
```javascript
|
||||
// Get beginner-friendly quick reference
|
||||
const quickStart = essentialCommands;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Regenerating Indexes
|
||||
|
||||
When commands are added/modified/removed:
|
||||
|
||||
```bash
|
||||
bash scripts/update-index.sh
|
||||
```
|
||||
|
||||
The script will:
|
||||
1. Scan all .md files in commands/
|
||||
2. Extract metadata from YAML frontmatter
|
||||
3. Analyze command relationships
|
||||
4. Identify essential commands
|
||||
5. Generate all 5 index files
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
After regeneration, verify:
|
||||
- [ ] All 5 JSON files are valid (no syntax errors)
|
||||
- [ ] Total command count matches (currently 69)
|
||||
- [ ] No missing fields in records
|
||||
- [ ] Category breakdown correct
|
||||
- [ ] Essential commands reasonable (10-15)
|
||||
- [ ] Relationships make logical sense
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
**Index Sizes**:
|
||||
- `all-commands.json`: ~28KB
|
||||
- `by-category.json`: ~31KB
|
||||
- `by-use-case.json`: ~29KB
|
||||
- `command-relationships.json`: ~7KB
|
||||
- `essential-commands.json`: ~5KB
|
||||
|
||||
**Total**: ~100KB (fast to load)
|
||||
|
||||
**Query Speed**:
|
||||
- In-memory search: < 1ms
|
||||
- File read + parse: < 50ms
|
||||
- Recommended: Load indexes once, cache in memory
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-06
|
||||
92
.claude/skills/command-guide/guides/troubleshooting.md
Normal file
92
.claude/skills/command-guide/guides/troubleshooting.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# 常见问题与解决方案
|
||||
|
||||
在使用 Gemini CLI 的过程中，您可能会遇到一些问题。本指南旨在帮助您诊断和解决这些常见问题，确保您能顺利使用 CLI。
|
||||
|
||||
## 1. 命令执行失败或未找到
|
||||
|
||||
**问题描述**:
|
||||
- 您输入的命令没有响应，或者系统提示“命令未找到”。
|
||||
- 命令执行后出现错误信息，但您不理解其含义。
|
||||
|
||||
**可能原因**:
|
||||
- 命令拼写错误。
|
||||
- CLI 未正确安装或环境变量配置不正确。
|
||||
- 命令所需的依赖项缺失。
|
||||
- 命令参数不正确或缺失。
|
||||
|
||||
**解决方案**:
|
||||
1. **检查拼写**: 仔细核对您输入的命令是否正确，包括命令名称和任何参数。
|
||||
2. **查看帮助**: 使用 `gemini help` 或 `gemini [command-name] --help` 来查看命令的正确用法、可用参数和示例。
|
||||
3. **验证安装**: 确保 Gemini CLI 已正确安装，并且其可执行文件路径已添加到系统的环境变量中。您可以尝试重新安装 CLI。
|
||||
4. **检查日志**: CLI 通常会生成日志文件。查看这些日志可以提供更详细的错误信息，帮助您定位问题。
|
||||
5. **更新 CLI**: 确保您使用的是最新版本的 Gemini CLI。旧版本可能存在已知错误，通过 `gemini version` 检查并更新。
|
||||
|
||||
## 2. 权限问题
|
||||
|
||||
**问题描述**:
|
||||
- CLI 尝试读取、写入或创建文件/目录时，提示“权限被拒绝”或类似错误。
|
||||
- 某些操作（如安装依赖、修改系统配置）失败。
|
||||
|
||||
**可能原因**:
|
||||
- 当前用户没有足够的权限执行该操作。
|
||||
- 文件或目录被其他程序占用。
|
||||
|
||||
**解决方案**:
|
||||
1. **以管理员身份运行**: 尝试以管理员权限（Windows）或使用 `sudo`（Linux/macOS）运行您的终端或命令提示符。
|
||||
```bash
|
||||
# Windows (在命令提示符或 PowerShell 中右键选择“以管理员身份运行”)
|
||||
# Linux/macOS
|
||||
sudo gemini [command]
|
||||
```
|
||||
2. **检查文件/目录权限**: 确保您对目标文件或目录拥有读/写/执行权限。您可能需要使用 `chmod` (Linux/macOS) 或修改文件属性 (Windows) 来更改权限。
|
||||
3. **关闭占用程序**: 确保没有其他程序正在使用您尝试访问的文件或目录。
|
||||
|
||||
## 3. 配置问题
|
||||
|
||||
**问题描述**:
|
||||
- CLI 行为异常，例如无法连接到 LLM 服务，或者某些功能无法正常工作。
|
||||
- 提示缺少 API 密钥或配置项。
|
||||
|
||||
**可能原因**:
|
||||
- 配置文件（如 `.gemini.json` 或相关环境变量）设置不正确。
|
||||
- API 密钥过期或无效。
|
||||
- 网络连接问题导致无法访问外部服务。
|
||||
|
||||
**解决方案**:
|
||||
1. **检查配置文件**: 仔细检查 Gemini CLI 的配置文件（通常位于用户主目录或项目根目录）中的设置。确保所有路径、API 密钥和选项都正确无误。
|
||||
2. **验证环境变量**: 确认所有必要的环境变量（如 `GEMINI_API_KEY`）都已正确设置。
|
||||
3. **网络连接**: 检查您的网络连接是否正常，并确保没有防火墙或代理设置阻止 CLI 访问外部服务。
|
||||
4. **重新初始化配置**: 对于某些配置问题，您可能需要使用 `gemini cli-init` 命令重新初始化 CLI 配置。
|
||||
```bash
|
||||
gemini cli-init
|
||||
```
|
||||
|
||||
## 4. 智能代理 (LLM) 相关问题
|
||||
|
||||
**问题描述**:
|
||||
- 智能代理的响应质量不佳，不相关或不准确。
|
||||
- 代理响应速度慢，或提示达到速率限制。
|
||||
|
||||
**可能原因**:
|
||||
- 提示不够清晰或缺乏上下文。
|
||||
- 选择了不适合当前任务的 LLM 模型。
|
||||
- LLM 服务提供商的速率限制或服务中断。
|
||||
|
||||
**解决方案**:
|
||||
1. **优化提示**: 尝试使用 `enhance-prompt` 命令来优化您的输入，提供更清晰、更具体的上下文信息。
|
||||
2. **选择合适的工具**: 根据任务类型，使用 `--tool` 标志选择最合适的 LLM 模型（如 `codex` 适用于代码生成，`gemini` 适用于复杂推理）。
|
||||
```bash
|
||||
gemini analyze --tool gemini "分析这个复杂算法"
|
||||
```
|
||||
3. **检查 API 密钥和配额**: 确保您的 LLM 服务 API 密钥有效，并且没有超出使用配额。
|
||||
4. **重试或等待**: 如果是速率限制或服务中断，请稍后重试或联系服务提供商。
|
||||
|
||||
## 5. 寻求帮助
|
||||
|
||||
如果以上解决方案都无法解决您的问题，您可以：
|
||||
|
||||
- **查阅官方文档**: 访问 Gemini CLI 的官方文档获取更全面的信息。
|
||||
- **社区支持**: 在相关的开发者社区或论坛中提问。
|
||||
- **提交问题**: 如果您认为是 CLI 的 bug，请在项目的问题跟踪器中提交详细的问题报告。
|
||||
|
||||
希望本指南能帮助您解决遇到的问题，让您更好地利用 Gemini CLI！
|
||||
100
.claude/skills/command-guide/guides/workflow-patterns.md
Normal file
100
.claude/skills/command-guide/guides/workflow-patterns.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# 常见工作流模式
|
||||
|
||||
Gemini CLI 不仅提供单个命令，更能通过智能编排将一系列命令组合成强大的工作流，帮助您高效完成复杂任务。本指南将介绍几种常见的工作流模式。
|
||||
|
||||
## 1. 工作流核心概念
|
||||
|
||||
在深入了解具体模式之前，理解工作流的架构至关重要。Gemini CLI 的工作流管理系统旨在提供一个灵活、可扩展的框架，用于定义、执行和协调复杂的开发任务。
|
||||
|
||||
- **工作流 (Workflows)**：一系列任务的组合，旨在实现特定的开发目标。
|
||||
- **任务 (Tasks)**：工作流中的独立工作单元，可以简单也可以复杂，有状态、输入和输出。
|
||||
- **智能体 (Agents)**：通常由大型语言模型驱动，负责执行任务或在工作流中做出决策。
|
||||
- **上下文 (Context)**：当前工作流的相关动态信息，包括项目状态、代码片段、文档、用户输入等，是智能决策的关键。
|
||||
- **记忆 (Memory)**：持久存储上下文、工作流历史和学习模式，支持工作流的恢复、适应和改进。
|
||||
|
||||
详情可参考 `../../workflows/workflow-architecture.md`。
|
||||
|
||||
## 2. 规划 -> 执行 (Plan -> Execute) 模式
|
||||
|
||||
这是最基础也是最常用的工作流模式，它将一个大的目标分解为可执行的步骤，并逐步实现。
|
||||
|
||||
**场景**: 您有一个需要从头开始实现的新功能或模块。
|
||||
|
||||
**主要命令**:
|
||||
- `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 将调用智能体自动编写和集成代码。
|
||||
|
||||
## 3. 测试驱动开发 (TDD) 模式
|
||||
|
||||
TDD 模式强调先编写测试，再编写满足测试的代码，然后重构。Gemini CLI 通过自动化 TDD 流程来支持这一模式。
|
||||
|
||||
**场景**: 您正在开发一个新功能，并希望通过 TDD 确保代码质量和正确性。
|
||||
|
||||
**主要命令**:
|
||||
- `tdd-plan`: 规划 TDD 工作流，生成红-绿-重构任务链。
|
||||
- `test-gen`: 根据功能描述生成测试用例。
|
||||
- `execute`: 执行代码生成和测试。
|
||||
- `tdd-verify`: 验证 TDD 工作流的合规性并生成质量报告。
|
||||
|
||||
**工作流示例**:
|
||||
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 周期是否规范执行，以及生成测试覆盖率等报告。
|
||||
|
||||
## 4. UI 设计与实现工作流
|
||||
|
||||
Gemini CLI 可以辅助您进行 UI 的设计、提取和代码生成，加速前端开发。
|
||||
|
||||
**场景**: 您需要基于一些设计稿或现有网站来快速构建 UI 原型或实现页面。
|
||||
|
||||
**主要命令**:
|
||||
- `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 产物。
|
||||
|
||||
## 5. 上下文搜索策略
|
||||
|
||||
所有这些工作流都依赖于高效的上下文管理。Gemini CLI 采用多层次的上下文搜索策略，以确保智能代理获得最相关的信息。
|
||||
|
||||
- **相关性优先**: 优先收集与当前任务直接相关的上下文，而非大量数据。
|
||||
- **分层搜索**: 从最直接的来源（如当前打开文件）开始，逐步扩展到项目文件、记忆库和外部资源。
|
||||
- **语义理解**: 利用智能搜索理解查询的意图，而非仅仅是关键词匹配。
|
||||
|
||||
更多细节请查阅 `../../workflows/context-search-strategy.md`。
|
||||
Reference in New Issue
Block a user