sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📃 docs: 暂存

Browse Source
This commit is contained in:
sayurinana(vm)
2025-12-18 22:52:53 +08:00
parent 575b07e9e5
commit 0079bd5cd4
14 changed files with 93 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

303
docs/reference/01-自定义斜杠命令指南.md Executable file
View File

@@ -0,0 +1,303 @@
# Claude Code 自定义斜杠命令指南
## 概述
斜杠命令允许你将常用的提示定义为 Markdown 文件，Claude Code 可以直接执行这些命令。命令支持项目级和个人级两种范围，并通过目录结构支持命名空间。
**基本语法：**
```
/<命令名称> [参数]
```
## 命令类型与存储位置
| 命令类型 | 存储位置 | 说明 | 在 `/help` 中显示 |
|---------|----------|------|-------------------|
| 项目命令 | `.claude/commands/` | 存储在项目仓库中，与团队共享 | `(project)` |
| 个人命令 | `~/.claude/commands/` | 存储在用户目录，跨所有项目可用 | `(user)` |
> **优先级**：当项目命令和个人命令同名时，**项目命令优先**。
## 快速开始
### 创建项目命令
```bash
# 创建命令目录
mkdir -p .claude/commands
# 创建一个简单的优化命令
echo "分析这段代码的性能问题并提出优化建议：" > .claude/commands/optimize.md
```
### 创建个人命令
```bash
# 创建个人命令目录
mkdir -p ~/.claude/commands
# 创建安全审查命令
echo "审查这段代码的安全漏洞：" > ~/.claude/commands/security-review.md
```
## Frontmatter 配置
在命令文件开头使用 YAML frontmatter 来配置命令行为：
```yaml
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: 创建一个 git 提交
model: claude-3-5-haiku-20241022
disable-model-invocation: false
---
命令内容在这里
```
### 配置参数说明
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `allowed-tools` | 命令可使用的工具列表 | 继承自当前对话 |
| `argument-hint` | 参数提示信息（显示在自动补全中） | 无 |
| `description` | 命令的简短描述 | 提示内容的第一行 |
| `model` | 指定使用的模型 | 继承自当前对话 |
| `disable-model-invocation` | 是否禁止 SlashCommand 工具调用此命令 | false |
## 参数用法
### 获取所有参数：`$ARGUMENTS`
```markdown
# .claude/commands/fix-issue.md
修复问题 #$ARGUMENTS，遵循我们的编码规范
```
**使用方式：**
```
> /fix-issue 123 high-priority
# $ARGUMENTS 会被替换为: "123 high-priority"
```
### 获取单个参数：`$1`, `$2`, `$3` ...
```markdown
# .claude/commands/review-pr.md
审查 PR #$1，优先级为 $2，分配给 $3
```
**使用方式：**
```
> /review-pr 456 high alice
# $1 = "456", $2 = "high", $3 = "alice"
```
## 高级功能
### 文件引用
使用 `@` 前缀引用项目文件：
```markdown
# 引用单个文件
审查 @src/utils/helpers.js 的实现
# 引用多个文件
比较 @src/old-version.js 和 @src/new-version.js
```
### 执行 Bash 命令
使用 `` !`command` `` 语法执行 bash 命令并将结果嵌入：
```markdown
---
allowed-tools: Bash(git add:*), Bash(git status:*)
---
当前状态: !`git status`
变更内容: !`git diff`
```
> **注意**：使用 Bash 命令嵌入时，必须在 `allowed-tools` 中包含 `Bash` 工具。
### 命名空间（子目录组织）
通过子目录组织命令，形成命名空间：
```
.claude/commands/
├── frontend/
│ └── component.md # /component (project:frontend)
├── backend/
│ └── api.md # /api (project:backend)
└── optimize.md # /optimize (project)
```
### 扩展思考
斜杠命令可以通过在命令内容中包含扩展思考关键词来触发 Claude 的扩展思考模式。
## 插件命令
插件可以提供自定义斜杠命令：
- **格式**：`/plugin-name:command-name`（如无冲突，前缀可省略）
- **位置**：插件根目录的 `commands/` 目录
- **功能**：支持所有命令特性（参数、frontmatter、bash、文件引用）
## MCP 斜杠命令
MCP 服务器可以将 prompts 暴露为斜杠命令：
```
/mcp__<server-name>__<prompt-name> [arguments]
```
### 示例
```bash
/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high
```
使用 `/mcp` 命令可以：
- 查看已配置的 MCP 服务器
- 检查连接状态
- 进行 OAuth 服务器认证
- 查看可用的工具和 prompts
## SlashCommand 工具集成
Claude 可以通过 `SlashCommand` 工具程序化地执行自定义斜杠命令。
### 支持的命令
- 仅支持自定义用户定义命令（不支持内置命令如 `/compact`）
- 必须在 frontmatter 中填写 `description` 字段
### 禁用 SlashCommand 工具
```bash
/permissions
# 在拒绝规则中添加: SlashCommand
```
### 禁用特定命令被工具调用
在命令 frontmatter 中添加：
```markdown
---
disable-model-invocation: true
---
```
### 权限规则
```
SlashCommand:/commit # 精确匹配（无参数）
SlashCommand:/review-pr:* # 前缀匹配（带任意参数）
```
### 字符预算
- **默认限制**：15,000 字符
- **自定义限制**：通过 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量设置
- 用于防止可用命令过多时的 token 溢出
## 实用示例
### 示例1：Git 提交命令
```markdown
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [提交信息]
description: 创建 git 提交
---
## 上下文
- 当前 git 状态: !`git status`
- 当前变更 (暂存和未暂存): !`git diff HEAD`
- 当前分支: !`git branch --show-current`
- 最近提交: !`git log --oneline -10`
## 任务
根据以上变更，创建一个 git 提交，提交信息为: $ARGUMENTS
```
### 示例2：代码审查命令
```markdown
---
argument-hint: [pr编号] [优先级] [负责人]
description: 审查 Pull Request
---
审查 PR #$1，优先级为 $2，分配给 $3。
重点关注：安全性、性能和代码风格。
```
### 示例3：性能分析命令
```markdown
---
description: 分析代码性能问题
---
分析这段代码的性能问题并提出优化建议：
- 识别性能瓶颈
- 建议算法改进方案
- 推荐缓存策略
- 识别不必要的计算
```
### 示例4：生成测试命令
```markdown
---
description: 为函数生成单元测试
argument-hint: [文件路径]
---
为 @$ARGUMENTS 中的函数生成完整的单元测试：
- 覆盖正常情况
- 覆盖边界情况
- 覆盖错误处理
- 使用项目现有的测试框架
```
## 斜杠命令与技能的区别
| 方面 | 斜杠命令 | Agent Skills |
|------|----------|--------------|
| **调用方式** | 用户显式调用（`/command`） | 模型自动调用 |
| **发现机制** | 基于 `/` 前缀 | 基于 description |
| **复杂度** | 简单提示 | 复杂能力包 |
| **文件结构** | 单个 .md 文件 | 目录 + SKILL.md + 资源 |
| **适用场景** | 快速重复任务 | 扩展 Claude 能力 |
**选择建议**：
- 使用**斜杠命令**：快速、常用的提示（review、explain、optimize）
- 使用 **Skills**：包含脚本、跨文件知识、团队标准化的综合工作流
## 最佳实践
1. **命名清晰**：使用简短、有意义的命令名称
2. **提供描述**：始终在 frontmatter 中添加 `description`
3. **限制工具**：仅授予命令必需的工具权限
4. **参数提示**：使用 `argument-hint` 帮助用户理解参数用法
5. **组织结构**：使用子目录为相关命令分组
## 相关资源
- [Skills 技能指南](./02-技能指南.md)
- [Plugins 插件指南](./03-插件指南.md)
- [Plugin Marketplaces 插件市场指南](./04-插件市场指南.md)
- [官方文档：斜杠命令](https://code.claude.com/docs/en/slash-commands)

457
docs/reference/02-技能指南.md Executable file
View File

@@ -0,0 +1,457 @@
# Claude Code 技能（Skills）指南
## 概述
Agent Skills（技能）是模块化的能力包，用于扩展 Claude 的功能。与斜杠命令不同，技能是由 Claude 根据用户请求**自动激活**的，而非用户显式调用。
### 核心特性
- **模型调用**：Claude 根据任务上下文自主决定何时使用技能
- **可发现性**：Claude 通过技能的 description 了解何时使用
- **可共享**：通过 git 或插件在团队间分发
- **可组合**：多个技能可以协同处理复杂任务
## 技能存储位置
| 类型 | 位置 | 适用场景 |
|------|------|----------|
| 个人技能 | `~/.claude/skills/` | 个人工作流、实验性技能、跨所有项目可用 |
| 项目技能 | `.claude/skills/` | 团队工作流、项目特定专业知识、通过 git 自动共享 |
| 插件技能 | 插件 `skills/` 目录 | 通过插件安装自动可用 |
## 技能文件结构
### 基本结构
每个技能是一个包含 `SKILL.md` 文件的目录：
```
my-skill/
├── SKILL.md # 必需：技能定义文件
├── FORMS.md # 可选：专题文档
├── REFERENCE.md # 可选：API 参考
└── scripts/ # 可选：辅助脚本
└── helper.py
```
### SKILL.md 文件格式
```yaml
---
name: your-skill-name
description: 简要描述技能的功能和使用场景。当用户需要...时使用。
allowed-tools: Read, Grep, Glob # 可选：限制可用工具
---
# 技能名称
## 说明
提供清晰的分步指导。
## 示例
展示具体的使用示例。
```
### 字段要求
| 字段 | 要求 | 限制 |
|------|------|------|
| `name` | 必需 | 小写字母、数字和连字符，最多 64 字符 |
| `description` | 必需 | 描述功能和使用时机，最多 1024 字符 |
| `allowed-tools` | 可选 | 逗号分隔的工具列表，限制技能可使用的工具 |
## Description 编写指南
> **关键原则**：`description` 是技能的**主要发现机制**，Claude 根据它决定何时使用技能。
### 必须包含的内容
1. **技能做什么** - 核心功能描述
2. **什么时候使用它** - 明确的触发条件
3. **用户可能提到的关键词** - 帮助匹配用户请求
### 示例对比
❌ **太模糊**：
```yaml
description: Helps with documents
```
✅ **具体明确**：
```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
```
✅ **另一个好例子**：
```yaml
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
```
## 渐进式披露
技能使用渐进式披露来高效管理上下文：
- **SKILL.md** 仅在技能被触发时加载
- **附加文件**（如 FORMS.md、REFERENCE.md）仅在 Claude 需要时按需加载
这意味着你可以在技能目录中包含大量参考资料，而不会浪费上下文空间。
## 快速开始
### 创建个人技能
```bash
# 创建技能目录
mkdir -p ~/.claude/skills/commit-helper
# 创建 SKILL.md 文件
cat > ~/.claude/skills/commit-helper/SKILL.md << 'EOF'
---
name: commit-helper
description: 从 git diff 生成清晰的提交信息。当编写提交信息或审查暂存变更时使用。
---
# 提交信息生成器
## 说明
1. 运行 `git diff --staged` 查看变更
2. 我会建议一个提交信息，包含：
- 50 字符以内的摘要
- 详细描述
- 受影响的组件
## 最佳实践
- 使用现在时态
- 说明"做了什么"和"为什么"，而非"怎么做"
EOF
```
### 创建项目技能
```bash
# 创建项目技能目录
mkdir -p .claude/skills/code-reviewer
# 创建 SKILL.md 文件
cat > .claude/skills/code-reviewer/SKILL.md << 'EOF'
---
name: code-reviewer
description: 审查代码的最佳实践和潜在问题。当审查代码、检查 PR 或分析代码质量时使用。
allowed-tools: Read, Grep, Glob
---
# 代码审查器
## 审查清单
1. 代码组织和结构
2. 错误处理
3. 性能考虑
4. 安全隐患
5. 测试覆盖率
## 说明
1. 使用 Read 工具查看目标文件
2. 使用 Grep 搜索模式
3. 使用 Glob 查找相关文件
4. 提供详细的代码质量反馈
EOF
```
## 技能工作原理
### 自动发现机制
Claude 自动发现三个位置的技能：
- `~/.claude/skills/`（个人）
- `.claude/skills/`（项目）
- 已安装插件的技能目录
### 查看可用技能
```
有哪些可用的技能？
```
或
```
列出所有可用的技能
```
### 智能激活
技能通过 description 匹配自动激活：
```
# 用户请求
帮我从这个 PDF 中提取文本
# Claude 自动激活匹配的技能（如 pdf-processing 技能）
```
## 工具限制
使用 `allowed-tools` 限制技能可以使用的工具：
```yaml
---
name: safe-file-reader
description: 只读方式访问文件。当需要只读文件访问且不进行修改时使用。
allowed-tools: Read, Grep, Glob
---
```
**适用场景**：
- 只读技能（不应修改文件）
- 限定范围技能（仅数据分析，不写文件）
- 安全敏感工作流
## 实用示例
### 示例1：简单技能（单文件）
```yaml
---
name: api-documenter
description: 为 API 端点生成文档。当需要记录 REST API、GraphQL 接口或函数签名时使用。
---
# API 文档生成器
## 说明
1. 分析代码中的 API 端点
2. 生成包含以下内容的文档：
- 端点路径和方法
- 请求参数
- 响应格式
- 示例请求
## 文档格式
使用 OpenAPI 3.0 规范格式。
```
### 示例2：带工具限制的技能
```yaml
---
name: safe-file-reader
description: 只读方式访问文件。当需要只读文件访问且不进行修改时使用。
allowed-tools: Read, Grep, Glob
---
# 安全文件读取器
## 说明
此技能仅使用只读工具：
- Read：读取文件内容
- Grep：搜索文件内容
- Glob：查找文件
## 使用场景
- 代码审查（不修改）
- 日志分析
- 配置检查
```
### 示例3：多文件技能
**目录结构：**
```
pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
├── fill_form.py
└── validate.py
```
**SKILL.md：**
```yaml
---
name: pdf-processing
description: 提取文本、填写表单、合并 PDF。当处理 PDF 文件、表单或文档提取时使用。需要 pypdf 和 pdfplumber 包。
---
# PDF 处理
## 快速开始
提取文本：
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
text = pdf.pages[0].extract_text()
```
表单填写请参阅 [FORMS.md](FORMS.md)。
详细 API 参考请参阅 [REFERENCE.md](REFERENCE.md)。
## 依赖
```bash
pip install pypdf pdfplumber
```
```
### 示例4：数据库操作技能
```yaml
---
name: db-migration-helper
description: 帮助创建和管理数据库迁移。当需要创建迁移脚本、修改数据库架构或执行数据迁移时使用。
---
# 数据库迁移助手
## 支持的数据库
- PostgreSQL
- MySQL
- SQLite
## 迁移流程
1. 分析当前架构
2. 生成迁移脚本
3. 验证迁移安全性
4. 提供回滚方案
## 最佳实践
- 始终创建回滚脚本
- 在测试环境先验证
- 大表修改分批进行
```
## 团队共享技能
### 方式1：通过 Git（项目技能）
```bash
# 添加到项目
mkdir -p .claude/skills/team-skill
# 创建 SKILL.md...
# 提交到仓库
git add .claude/skills/
git commit -m "添加团队技能"
git push
# 团队成员拉取后自动可用
git pull
claude # 技能立即可用
```
### 方式2：通过插件（推荐）
1. 创建包含 `skills/` 目录的插件
2. 将插件添加到市场
3. 团队成员安装插件即可使用
## 管理技能
### 更新技能
```bash
# 编辑 SKILL.md
code ~/.claude/skills/my-skill/SKILL.md
# 重启 Claude Code 使更改生效
```
### 删除技能
```bash
# 删除个人技能
rm -rf ~/.claude/skills/my-skill
# 删除项目技能
rm -rf .claude/skills/my-skill
git commit -m "移除不再使用的技能"
```
## 故障排除
### Claude 没有使用我的技能
**检查1：Description 是否足够具体**
- 包含 WHAT（做什么）和 WHEN（何时使用）
- 使用用户可能提到的具体关键词
- 避免模糊描述
**检查2：YAML 语法是否有效**
```bash
# 查看 frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15
# 常见问题：
# - 缺少开头/结尾的 ---
# - 使用 Tab 而非空格
# - 特殊字符未加引号
```
**检查3：文件路径是否正确**
```bash
# 个人技能
ls ~/.claude/skills/*/SKILL.md
# 项目技能
ls .claude/skills/*/SKILL.md
```
**检查4：使用调试模式**
```bash
claude --debug
```
### 技能执行出错
- 检查依赖项是否已安装
- 确保脚本有执行权限：`chmod +x scripts/*.py`
- 使用正斜杠路径：`scripts/helper.py` ✅（而非 `scripts\helper.py` ❌）
## 技能与斜杠命令的区别
| 方面 | Agent Skills | 斜杠命令 |
|------|--------------|----------|
| **调用方式** | 模型自动调用 | 用户显式调用（`/command`） |
| **发现机制** | 基于 description | 基于 `/` 前缀 |
| **复杂度** | 复杂能力包 | 简单提示 |
| **文件结构** | 目录 + SKILL.md + 资源 | 单个 .md 文件 |
| **适用场景** | 扩展 Claude 能力 | 快速重复任务 |
**选择建议**：
- 使用**斜杠命令**：快速、常用的提示（review、explain、optimize）
- 使用 **Skills**：包含脚本、跨文件知识、团队标准化的综合工作流
## 最佳实践
| 实践 | 说明 |
|------|------|
| **保持专注** | 一个技能解决一个能力（如"PDF 表单填充"而非"文档处理"） |
| **清晰描述** | 包含具体触发条件，如"当处理 Excel 文件、电子表格时使用" |
| **测试验证** | 技能是否在预期情况下激活？说明是否清晰？ |
| **版本记录** | 在 SKILL.md 中记录版本历史 |
```markdown
# 我的技能
## 版本历史
- v2.0.0 (2025-10-01): 重大 API 变更
- v1.1.0 (2025-09-15): 添加新功能
- v1.0.0 (2025-09-01): 初始版本
```
## 相关资源
- [自定义斜杠命令指南](./01-自定义斜杠命令指南.md)
- [Plugins 插件指南](./03-插件指南.md)
- [Plugin Marketplaces 插件市场指南](./04-插件市场指南.md)
- [官方文档：Agent Skills](https://code.claude.com/docs/en/skills)

436
docs/reference/03-插件指南.md Executable file
View File

@@ -0,0 +1,436 @@
# Claude Code 插件（Plugins）指南
## 概述
插件是 Claude Code 的扩展功能系统，允许用户通过自定义命令、代理、钩子、技能和 MCP 服务器来扩展平台功能。插件可以在项目和团队之间共享，是分发 Claude Code 扩展的标准方式。
## 插件目录结构
```
my-plugin/
├── .claude-plugin/
│ └── plugin.json # 必需：插件元数据
├── commands/ # 可选：自定义斜杠命令
│ └── hello.md
├── agents/ # 可选：自定义代理
│ └── helper.md
├── skills/ # 可选：Agent Skills
│ └── my-skill/
│ └── SKILL.md
├── hooks/ # 可选：事件处理器
│ └── hooks.json
└── .mcp.json # 可选：MCP 服务器配置
```
## 插件组件说明
| 组件 | 功能 | 位置 |
|------|------|------|
| **Commands** | 自定义斜杠命令 | `commands/*.md` |
| **Agents** | 专门的代理（显示在 `/agents`） | `agents/*.md` |
| **Skills** | 扩展 Claude 能力（模型自动调用） | `skills/skill-name/SKILL.md` |
| **Hooks** | 事件处理和自动化 | `hooks/hooks.json` |
| **MCP** | 外部工具集成 | `.mcp.json` |
## 快速开始：创建第一个插件
### 步骤1：创建目录结构
```bash
# 创建插件目录
mkdir -p my-first-plugin/.claude-plugin
mkdir -p my-first-plugin/commands
mkdir -p my-first-plugin/skills/greeting-skill
```
### 步骤2：创建插件清单
```bash
cat > my-first-plugin/.claude-plugin/plugin.json << 'EOF'
{
"name": "my-first-plugin",
"description": "一个简单的问候插件，用于学习基础知识",
"version": "1.0.0",
"author": {
"name": "你的名字"
}
}
EOF
```
### 步骤3：添加自定义命令
```bash
cat > my-first-plugin/commands/hello.md << 'EOF'
---
description: 用个性化消息问候用户
argument-hint: [用户名]
---
# 问候命令
热情地问候用户 $ARGUMENTS，并询问今天有什么可以帮助的。让问候变得个性化和鼓励性。
EOF
```
### 步骤4：添加技能
```bash
cat > my-first-plugin/skills/greeting-skill/SKILL.md << 'EOF'
---
name: greeting-skill
description: 生成友好的问候语。当用户需要问候模板或社交礼仪建议时使用。
---
# 问候技能
## 说明
根据场景生成合适的问候语：
- 正式场合
- 非正式场合
- 电子邮件开头
- 即时消息
EOF
```
## plugin.json 配置详解
### 基本配置
```json
{
"name": "plugin-name",
"description": "插件功能描述",
"version": "1.0.0",
"author": {
"name": "作者名称",
"email": "author@example.com"
}
}
```
### 完整配置示例
```json
{
"name": "enterprise-tools",
"description": "企业级工作流自动化工具",
"version": "2.1.0",
"author": {
"name": "企业团队",
"email": "team@company.com"
},
"homepage": "https://docs.company.com/plugins/enterprise-tools",
"repository": "https://github.com/company/enterprise-plugin",
"license": "MIT",
"keywords": ["enterprise", "workflow", "automation"]
}
```
### 配置字段说明
| 字段 | 必需 | 说明 |
|------|------|------|
| `name` | 是 | 插件标识符（kebab-case 格式） |
| `description` | 否 | 插件功能简述 |
| `version` | 否 | 语义化版本号 |
| `author` | 否 | 作者信息对象（含 `name` 字段） |
| `homepage` | 否 | 文档或主页 URL |
| `repository` | 否 | 源代码仓库 URL |
| `license` | 否 | 许可证类型 |
| `keywords` | 否 | 关键词数组 |
## 安装和管理插件
### 安装插件
```bash
# 通过交互菜单浏览
/plugin
# 从市场直接安装
/plugin install formatter@your-org
# 从本地市场安装
/plugin install my-first-plugin@test-marketplace
```
### 管理已安装插件
```bash
# 启用插件
/plugin enable plugin-name@marketplace-name
# 禁用插件
/plugin disable plugin-name@marketplace-name
# 卸载插件
/plugin uninstall plugin-name@marketplace-name
```
### 验证安装
```bash
# 查看新命令是否出现
/help
# 管理插件
/plugin
```
## 本地开发和测试
### 开发工作流
```bash
# 1. 创建开发目录结构
mkdir dev-marketplace
cd dev-marketplace
mkdir my-plugin
# 2. 创建市场清单
mkdir .claude-plugin
cat > .claude-plugin/marketplace.json << 'EOF'
{
"name": "dev-marketplace",
"owner": {"name": "Developer"},
"plugins": [{
"name": "my-plugin",
"source": "./my-plugin",
"description": "开发中的插件"
}]
}
EOF
# 3. 从父目录启动 Claude Code
claude
# 4. 添加市场
/plugin marketplace add ./dev-marketplace
# 5. 安装插件
/plugin install my-plugin@dev-marketplace
```
### 迭代开发
```bash
# 修改插件代码后，重新安装
/plugin uninstall my-plugin@dev-marketplace
/plugin install my-plugin@dev-marketplace
```
## 高级功能
### 添加钩子（Hooks）
在 `hooks/hooks.json` 中定义事件处理器：
```json
{
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
}
]
}
]
}
```
> **注意**：`${CLAUDE_PLUGIN_ROOT}` 环境变量指向插件安装目录。
### 添加 MCP 服务器
在插件根目录创建 `.mcp.json`：
```json
{
"servers": {
"my-server": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
}
}
}
```
### 添加自定义代理
在 `agents/` 目录创建代理定义：
```markdown
# agents/code-assistant.md
---
description: 专注于代码质量的智能助手
allowed-tools: Read, Grep, Glob, Edit
---
# 代码助手代理
你是一个专注于代码质量的助手。
## 职责
1. 代码审查
2. 重构建议
3. 最佳实践指导
```
## 完整插件示例
### 示例：代码格式化插件
**目录结构：**
```
code-formatter/
├── .claude-plugin/
│ └── plugin.json
├── commands/
│ ├── format.md
│ └── lint.md
├── skills/
│ └── formatting-rules/
│ └── SKILL.md
└── scripts/
└── prettier-wrapper.sh
```
**plugin.json：**
```json
{
"name": "code-formatter",
"description": "自动代码格式化和 lint 检查",
"version": "1.0.0",
"author": {
"name": "DevTools Team"
},
"keywords": ["format", "lint", "prettier", "eslint"]
}
```
**commands/format.md：**
```markdown
---
description: 格式化当前文件或目录
argument-hint: [文件或目录路径]
allowed-tools: Bash(npx prettier:*), Read, Write
---
# 格式化命令
格式化指定的文件或目录：$ARGUMENTS
使用项目的 Prettier 配置进行格式化。
```
**commands/lint.md：**
```markdown
---
description: 运行 ESLint 检查
argument-hint: [文件或目录路径]
allowed-tools: Bash(npx eslint:*)
---
# Lint 检查命令
对指定的文件或目录运行 ESLint：$ARGUMENTS
报告所有问题并提供修复建议。
```
**skills/formatting-rules/SKILL.md：**
```yaml
---
name: formatting-rules
description: 了解项目的代码格式化规则。当需要手动格式化代码或解释格式化规则时使用。
---
# 格式化规则
## 常用规则
- 缩进：2 空格
- 分号：必需
- 引号：单引号
- 尾随逗号：ES5 兼容
## 配置文件
检查以下文件了解项目规则：
- `.prettierrc`
- `.eslintrc`
- `package.json` 中的 `prettier` 和 `eslintConfig`
```
## 团队插件配置
在仓库的 `.claude/settings.json` 中配置自动安装：
```json
{
"extraKnownMarketplaces": {
"team-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
}
}
```
当团队成员信任该仓库后：
- 市场会自动安装
- 通过 `enabledPlugins` 字段指定的插件会自动安装
## 调试和验证
### 调试技巧
1. **检查结构**：确保目录在插件根目录，而非 `.claude-plugin/` 内部
2. **单独测试**：分别检查每个命令、代理和钩子
3. **使用验证工具**：参见插件参考文档了解 CLI 调试命令
4. **验证安装**：运行 `/help` 查看新命令是否列出
### 检查清单
- [ ] `.claude-plugin/plugin.json` 存在且格式正确
- [ ] 组件目录（commands/、skills/ 等）在插件根目录
- [ ] 命令文件为 `.md` 格式
- [ ] 技能目录包含 `SKILL.md` 文件
- [ ] YAML frontmatter 语法正确
### 常见问题
**命令不显示：**
- 检查文件扩展名是否为 `.md`
- 验证 frontmatter 格式正确
- 重启 Claude Code
**技能不激活：**
- 检查 `description` 是否足够具体
- 验证 `SKILL.md` 路径正确
## 分享插件前的准备
在分发插件之前：
- 添加 `README.md` 包含安装和使用说明
- 在 `plugin.json` 中使用语义化版本号
- 创建或使用市场进行分发
- 在更广泛发布前与他人测试
## 相关资源
- [自定义斜杠命令指南](./01-自定义斜杠命令指南.md)
- [Skills 技能指南](./02-技能指南.md)
- [Plugin Marketplaces 插件市场指南](./04-插件市场指南.md)
- [官方文档：插件系统](https://code.claude.com/docs/en/plugins)
- [官方文档：子代理](https://code.claude.com/docs/en/sub-agents)
- [官方文档：钩子](https://code.claude.com/docs/en/hooks)
- [官方文档：MCP](https://code.claude.com/docs/en/mcp)

382
docs/reference/04-插件市场指南.md Executable file
View File

@@ -0,0 +1,382 @@
# Claude Code 插件市场（Plugin Marketplaces）指南
## 概述
插件市场是基于 JSON 的目录，用于集中发现、版本管理和团队分发 Claude Code 扩展。它支持来自多种来源（Git 仓库、GitHub、本地路径、包管理器）的插件。
### 核心功能
- **集中发现**：在一个地方浏览来自多个来源的插件
- **版本管理**：自动跟踪和更新插件版本
- **团队分发**：跨组织共享所需插件
- **灵活来源**：支持 Git 仓库、GitHub、本地路径等多种来源
- **环境变量**：使用 `${CLAUDE_PLUGIN_ROOT}` 引用插件安装目录
## 快速命令参考
```bash
# 添加 GitHub 市场
/plugin marketplace add owner/repo
# 添加 Git 仓库
/plugin marketplace add https://gitlab.com/company/plugins.git
# 添加本地市场
/plugin marketplace add ./my-marketplace
/plugin marketplace add ./path/to/marketplace.json
# 添加远程 URL
/plugin marketplace add https://url.of/marketplace.json
# 从市场安装插件
/plugin install plugin-name@marketplace-name
# 列出已配置市场
/plugin marketplace list
# 更新市场
/plugin marketplace update marketplace-name
# 删除市场
/plugin marketplace remove marketplace-name
```
## 市场结构
### 基本目录结构
在仓库根目录创建 `.claude-plugin/marketplace.json`：
```
my-marketplace/
├── .claude-plugin/
│ └── marketplace.json # 必需：市场索引文件
├── plugin-a/ # 本地插件 A
│ └── .claude-plugin/
│ └── plugin.json
├── plugin-b/ # 本地插件 B
│ └── .claude-plugin/
│ └── plugin.json
└── README.md # 可选：市场说明
```
### marketplace.json 基本格式
```json
{
"name": "company-tools",
"owner": {
"name": "DevTools Team",
"email": "team@example.com"
},
"plugins": [
{
"name": "code-formatter",
"source": "./plugins/formatter",
"description": "自动代码格式化"
}
]
}
```
## 市场索引字段说明
### 必需字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 市场标识符（kebab-case，无空格） |
| `owner` | object | 市场维护者信息 |
| `plugins` | array | 可用插件列表 |
### 可选元数据字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `metadata.description` | string | 市场简介 |
| `metadata.version` | string | 市场版本 |
| `metadata.pluginRoot` | string | 相对插件来源的基础路径 |
## 插件条目配置
### 必需字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 插件标识符（kebab-case，无空格） |
| `source` | string\|object | 插件来源位置 |
### 可选元数据字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `description` | string | 插件功能描述 |
| `version` | string | 插件版本 |
| `author` | object | 插件作者信息 |
| `homepage` | string | 插件主页或文档 URL |
| `repository` | string | 源代码仓库 URL |
| `license` | string | SPDX 许可证标识符（MIT、Apache-2.0 等） |
| `keywords` | array | 发现和分类标签 |
| `category` | string | 插件分类 |
| `tags` | array | 搜索标签 |
| `strict` | boolean | 是否要求文件夹中有 plugin.json（默认：true） |
### 组件配置字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `commands` | string\|array | 命令文件或目录的自定义路径 |
| `agents` | string\|array | 代理文件的自定义路径 |
| `hooks` | string\|object | 钩子配置或钩子文件路径 |
| `mcpServers` | string\|object | MCP 服务器配置或 MCP 配置文件路径 |
## 插件来源配置
### 相对路径（同一仓库内）
```json
{
"name": "my-plugin",
"source": "./plugins/my-plugin"
}
```
### GitHub 仓库
```json
{
"name": "github-plugin",
"source": {
"source": "github",
"repo": "owner/plugin-repo"
}
}
```
### Git 仓库（任意服务）
```json
{
"name": "git-plugin",
"source": {
"source": "url",
"url": "https://gitlab.com/team/plugin.git"
}
}
```
## 完整配置示例
### 市场配置
```json
{
"name": "enterprise-marketplace",
"owner": {
"name": "Enterprise Team",
"email": "enterprise@company.com"
},
"metadata": {
"description": "企业级 Claude Code 插件集合",
"version": "2.0.0"
},
"plugins": [
{
"name": "code-formatter",
"source": "./plugins/formatter",
"description": "自动代码格式化",
"version": "2.1.0"
},
{
"name": "security-scanner",
"source": {
"source": "github",
"repo": "company/security-plugin"
},
"description": "代码安全扫描"
}
]
}
```
### 高级插件条目
```json
{
"name": "enterprise-tools",
"source": {
"source": "github",
"repo": "company/enterprise-plugin"
},
"description": "企业工作流自动化工具",
"version": "2.1.0",
"author": {
"name": "Enterprise Team",
"email": "team@company.com"
},
"homepage": "https://docs.company.com/plugins/enterprise-tools",
"repository": "https://github.com/company/enterprise-plugin",
"license": "MIT",
"keywords": ["enterprise", "workflow", "automation"],
"category": "productivity",
"commands": [
"./commands/core/",
"./commands/enterprise/",
"./commands/experimental/preview.md"
],
"agents": [
"./agents/security-reviewer.md",
"./agents/compliance-checker.md"
],
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
}
]
}
]
},
"mcpServers": {
"enterprise-db": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
}
},
"strict": false
}
```
## 创建和使用市场
### 创建本地市场
```bash
# 1. 创建市场目录
mkdir -p my-marketplace/.claude-plugin
# 2. 创建市场索引
cat > my-marketplace/.claude-plugin/marketplace.json << 'EOF'
{
"name": "my-marketplace",
"owner": {
"name": "Your Name"
},
"plugins": []
}
EOF
# 3. 添加插件到市场
mkdir -p my-marketplace/hello-plugin/.claude-plugin
# ... 创建插件文件 ...
# 4. 更新市场索引添加插件条目
```
### 从市场安装插件
```bash
# 从已知市场安装
/plugin install plugin-name@marketplace-name
# 交互式浏览
/plugin
```
## 团队市场配置
在项目的 `.claude/settings.json` 中配置自动安装：
```json
{
"extraKnownMarketplaces": {
"team-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
},
"project-specific": {
"source": {
"source": "git",
"url": "https://git.company.com/project-plugins.git"
}
}
}
}
```
当团队成员信任该仓库文件夹后，Claude Code 会自动安装这些市场，以及通过 `enabledPlugins` 字段指定的任何插件。
## 托管和分发
### GitHub 托管（推荐）
1. 创建 GitHub 仓库
2. 添加 `.claude-plugin/marketplace.json`
3. 添加插件目录
4. 用户通过以下命令添加：
```bash
/plugin marketplace add owner/repo
```
### 其他 Git 服务
```bash
/plugin marketplace add https://gitlab.com/company/plugins.git
```
### 本地开发测试
```bash
/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace
```
## 验证和测试
```bash
# 验证市场 JSON 语法和结构
claude plugin validate .
# 添加本地市场测试
/plugin marketplace add ./path/to/marketplace
# 测试插件安装
/plugin install test-plugin@marketplace-name
```
## 故障排除
### 市场无法加载
- 验证市场 URL 可访问
- 检查 `.claude-plugin/marketplace.json` 存在
- 验证 JSON 语法有效
- 私有仓库需确保有访问权限
### 插件安装失败
- 验证插件源 URL 可访问
- 检查插件目录包含必需文件
- GitHub 源需确保仓库公开或有权限
- 验证插件来源可手动下载
## 最佳实践
1. **清晰命名**：使用有意义的市场和插件名称
2. **完整描述**：为每个插件提供清晰的功能描述
3. **版本管理**：使用语义化版本号
4. **文档齐全**：提供 README 和使用说明
5. **定期更新**：保持插件和市场元数据最新
## 相关资源
- [自定义斜杠命令指南](./01-自定义斜杠命令指南.md)
- [Skills 技能指南](./02-技能指南.md)
- [Plugins 插件指南](./03-插件指南.md)
- [官方文档：插件市场](https://code.claude.com/docs/en/plugin-marketplaces)

135
docs/reference/aide-overview.md Normal file
View File

@@ -0,0 +1,135 @@
# Aide 系统概述
## 一、系统简介
Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅助开发中的信息过载、操作不确定性和流程耦合问题。
系统通过 **Command + Skill + 专用程序** 的架构，将原本堆积在 CLAUDE.md 中的规则和流程转化为按需触发的模块化单元，实现：
- **CLAUDE.md 精简化**：仅保留项目结构说明，不再堆积规则和流程
- **流程按需触发**：通过 Command 主动触发流程指导
- **操作确定性封装**：通过 Skill + 程序简化操作，减少不确定性
---
## 二、核心设计原则
| 原则 | 说明 |
|------|------|
| **渐进式披露** | 信息按需加载，用户/LLM 主动调用时才加载相关指引 |
| **确定性封装** | 将可变过程转化为固定接口，只暴露程序和参数 |
| **信息隔离** | LLM 只传核心语义数据，程序负责格式化和渲染 |
| **核心与形式分离** | 核心信息（分析、决策）由 LLM 发挥，形式问题（状态记录、环境配置）由程序处理 |
---
## 三、系统架构
```
┌─────────────────────────────────────────────────────────────┐
│ 用户 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ aide-plugin │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ /aide:setup │ │ /aide:load │ │ /aide:docs │ │ /aide:run │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ aide skill │ Skill │
│ │ (aide 命令使用指南) │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼ 调用
┌─────────────────────────────────────────────────────────────┐
│ aide-program │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ init │ │ env │ │ flow │ │ decide │ 子命令 │
│ └────────┘ └────────┘ └────────┘ └────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ .aide/ 数据目录 │ │
│ │ config.toml | flow-status.json | decisions/ │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
**组件关系**：
- **Commands**：定义流程（做什么、按什么顺序做），指导 LLM 的思考方向
- **Skill**：定义工具使用方法（怎么调用 aide 程序），纯工具说明
- **Program**：执行具体操作（环境检测、进度追踪、待定项处理），返回精简结果
---
## 四、子区块索引
### 4.1 aide-plugin 区块
| 文档 | 位置 | 说明 |
|------|------|------|
| **导览** | [aide-plugin/docs/README.md](../aide-marketplace/aide-plugin/docs/README.md) | plugin 整体介绍和索引 |
| setup 命令 | [aide-plugin/docs/commands/setup.md](../aide-marketplace/aide-plugin/docs/commands/setup.md) | 环境配置（独立运行） |
| load 命令 | [aide-plugin/docs/commands/load.md](../aide-marketplace/aide-plugin/docs/commands/load.md) | 项目认知载入 |
| docs 命令 | [aide-plugin/docs/commands/docs.md](../aide-marketplace/aide-plugin/docs/commands/docs.md) | 项目文档管理（独立运行） |
| run 命令 | [aide-plugin/docs/commands/run.md](../aide-marketplace/aide-plugin/docs/commands/run.md) | 任务执行（核心命令） |
| aide skill | [aide-plugin/docs/skill/aide.md](../aide-marketplace/aide-plugin/docs/skill/aide.md) | aide 命令使用指南 |
| env-config skill | [aide-plugin/skills/env-config/SKILL.md](../aide-marketplace/aide-plugin/skills/env-config/SKILL.md) | 环境配置详细指南 |
### 4.2 aide-program 区块
| 文档 | 位置 | 说明 |
|------|------|------|
| **导览** | [aide-program/docs/README.md](../aide-program/docs/README.md) | program 整体介绍和索引 |
| env 子命令 | [aide-program/docs/commands/env.md](../aide-program/docs/commands/env.md) | 环境检测与修复 |
| flow 子命令 | [aide-program/docs/commands/flow.md](../aide-program/docs/commands/flow.md) | 进度追踪与 git 集成 |
| flow 详细设计 | [aide-program/docs/commands/flow/README.md](../aide-program/docs/commands/flow/README.md) | flow 实现细节与验证清单 |
| decide 子命令 | [aide-program/docs/commands/decide.md](../aide-program/docs/commands/decide.md) | 待定项 Web 确认 |
| init 子命令 | [aide-program/docs/commands/init.md](../aide-program/docs/commands/init.md) | 初始化 .aide 目录 |
| 配置格式 | [aide-program/docs/formats/config.md](../aide-program/docs/formats/config.md) | config.toml 规范 |
| 数据格式 | [aide-program/docs/formats/data.md](../aide-program/docs/formats/data.md) | 待定项、流程状态等格式 |
---
## 五、快速导航
### 想了解/修改 Commands 或 Skill
→ 阅读 [aide-plugin 导览](../aide-marketplace/aide-plugin/docs/README.md)
### 想了解/修改 aide 程序
→ 阅读 [aide-program 导览](../aide-program/docs/README.md)
### 想了解完整工作流程
```
/aide:setup /aide:docs /aide:run
(独立运行) (独立运行) (核心命令)
│ │ │
▼ ▼ ▼
环境配置 项目文档 任务执行
依赖分析 区块划分 ├─ task-optimize (任务准备)
模块检测 文档生成 │ ├─ 任务分析
问题修复 增量更新 │ ├─ 复杂度评估
│ ├─ 待定项处理
│ └─ 生成细则
├─ flow-design (流程设计)
│ └─ 创建流程图
├─ impl (迭代实现)
├─ verify (验证交付)
├─ docs (文档更新)
└─ finish (收尾)
```
> `/aide:load` 由 `/aide:run` 自动调用，用于按需载入项目文档。
---
## 六、版本信息
- 当前版本：2.0.0
- 更新日期：2025-12-15
- 主要变更：Commands 体系重组（setup/load/docs/run 替代 init/prep/exec）

273
docs/reference/project-details.md Normal file
View File

@@ -0,0 +1,273 @@
# Aide 项目状态文档
## 一、项目简介
Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅助开发中的信息过载、操作不确定性和流程耦合问题。
### 1.1 核心理念
将原本堆积在 CLAUDE.md 中的规则和流程转化为按需触发的模块化单元：
| 原有问题 | Aide 解决方案 |
|----------|---------------|
| CLAUDE.md 信息过载 | 流程按需触发（Command） |
| 操作不确定性 | 程序化封装（aide 程序） |
| 输出信息冗余 | 精简输出，静默即成功 |
| 流程耦合 | Command + Skill 分离职责 |
### 1.2 系统架构
```
用户
│
▼
aide-plugin (Claude Code 插件)
├── Commands:
│ ├── /aide:setup - 环境配置（独立运行）
│ ├── /aide:load - 项目认知载入
│ ├── /aide:docs - 项目文档管理（独立运行）
│ └── /aide:run - 任务执行（核心命令）
└── Skills:
├── aide - 基础命令指南
└── env-config - 环境配置详细指南
│
▼ 调用
aide-program (命令行工具)
├── aide init - 初始化配置
├── aide env - 环境检测（模块化）
├── aide config - 配置读写
├── aide flow - 进度追踪 + git 集成
│ ├── aide flow status - 查看当前任务状态
│ ├── aide flow list - 列出所有任务
│ └── aide flow show - 查看任务详细历史
└── aide decide - 待定项 Web 确认
```
---
## 二、项目结构
```
ccoptimize/
├── CLAUDE.md # 项目级指令
├── README.md # 本文档
│
├── docs/ # 总导览
│ ├── aide-overview.md # Aide 系统概述
│ ├── 01-自定义斜杠命令指南.md
│ ├── 02-技能指南.md
│ ├── 03-插件指南.md
│ ├── 04-插件市场指南.md
│ └── 为什么要更换到command+skill+专用处理程序.md
│
├── statements/ # 项目声明文档
│ └── optimize.md # 沟通准则
│
├── aide-marketplace/ # Claude Code 插件市场
│ ├── .claude-plugin/
│ │ └── marketplace.json
│ └── aide-plugin/ # Aide 插件
│ ├── .claude-plugin/
│ │ └── plugin.json
│ ├── commands/ # 执行文件（给 LLM）
│ │ ├── setup.md # 环境配置命令
│ │ ├── load.md # 项目认知载入命令
│ │ ├── docs.md # 项目文档管理命令
│ │ └── run.md # 任务执行命令（核心）
│ ├── skills/
│ │ ├── aide/
│ │ │ └── SKILL.md # 基础命令指南
│ │ └── env-config/
│ │ └── SKILL.md # 环境配置详细指南（按需触发）
│ └── docs/ # 设计文档（给人）
│ ├── README.md
│ ├── commands/
│ │ ├── init.md
│ │ ├── prep.md
│ │ └── exec.md
│ └── skill/
│ └── aide.md
│
└── aide-program/ # Aide 命令行工具
├── bin/
│ ├── aide.sh # Linux/Mac 入口
│ └── aide.bat # Windows 入口
├── aide/ # Python 代码
│ ├── __init__.py
│ ├── __main__.py
│ ├── main.py # CLI 路由
│ ├── core/
│ │ ├── config.py # 配置管理
│ │ └── output.py # 输出格式
│ ├── env/
│ ├── manager.py # 环境管理器
│ ├── registry.py # 模块注册表
│ └── modules/ # 环境检测模块
│ ├── base.py
│ ├── python.py, uv.py
│ ├── rust.py, node.py, flutter.py
│ ├── android.py, node_deps.py
│ ├── venv.py, requirements.py
│ └── ...
│ └── flow/ # 进度追踪（已实现）
│ └── ...
└── docs/ # 设计文档（给人）
├── README.md
├── commands/
│ ├── env.md
│ ├── flow.md
│ ├── flow/ # flow 详细设计（交接包）
│ ├── decide.md
│ └── init.md
└── formats/
├── config.md
└── data.md
```
---
## 三、实现状态
### 3.1 aide-plugin
| 组件 | 状态 | 说明 |
|------|------|------|
| /aide:init | ✅ 设计完成 | 项目认知与环境初始化 |
| /aide:prep | ✅ 设计完成 | 任务准备流程 |
| /aide:exec | ✅ 设计完成 | 任务执行流程 |
| aide skill | ✅ 设计完成 | aide 基础命令指南 |
| env-config skill | ✅ 设计完成 | 环境配置详细指南（按需触发） |
执行文件位于 `aide-marketplace/aide-plugin/commands/` 和 `skills/`
**Skill 设计理念**：
- `aide` skill：始终加载，提供基础命令用法
- `env-config` skill：按需触发，仅在 `aide env ensure` 失败时使用
### 3.2 aide-program
| 子命令 | 状态 | 说明 |
|--------|------|------|
| aide init | ✅ 已实现 | 初始化 .aide 目录和配置 |
| aide env list | ✅ 已实现 | 列出所有可用模块 |
| aide env ensure | ✅ 已实现 | 模块化环境检测与修复 |
| aide env set | ✅ 已实现 | 设置环境配置（带验证） |
| aide env ensure --runtime | ✅ 已实现 | 运行时环境检测 |
| aide env ensure --modules | ✅ 已实现 | 指定模块检测 |
| aide env ensure --all | ✅ 已实现 | 全量检测（仅检查） |
| aide env ensure --verbose | ✅ 已实现 | 详细配置输出 |
| aide config get/set | ✅ 已实现 | 配置读写 |
| aide flow | ✅ 已实现 | 进度追踪 + git 集成 |
| aide decide submit | ✅ 已实现 | 提交待定项并启动 Web 服务 |
| aide decide result | ✅ 已实现 | 获取用户决策结果 |
代码位于 `aide-program/aide/`
### 3.3 环境检测模块
| 模块 | 类型 | 能力 | 说明 |
|------|------|------|------|
| python | A | check | Python 解释器版本 |
| uv | A | check | uv 包管理器 |
| rust | A | check | Rust 工具链（rustc + cargo） |
| node | A | check | Node.js 运行时 |
| flutter | A | check | Flutter SDK |
| android | A | check | Android SDK |
| venv | B | check, ensure | Python 虚拟环境 |
| requirements | B | check, ensure | Python 依赖管理 |
| node_deps | B | check, ensure | Node.js 项目依赖 |
- 类型A：无需配置即可检测
- 类型B：需要配置路径才能检测
- 支持模块实例化命名：`模块类型:实例名`（如 `node_deps:react`）
### 3.4 设计文档
| 区块 | 状态 | 位置 |
|------|------|------|
| 总导览 | ✅ 完成 | `docs/aide-overview.md` |
| aide-plugin 设计文档 | ✅ 完成 | `aide-marketplace/aide-plugin/docs/` |
| aide-program 设计文档 | ✅ 完成 | `aide-program/docs/` |
---
## 四、文档导航
### 4.1 快速了解 Aide 系统
1. 阅读 [Aide 系统概述](docs/aide-overview.md) - 系统概述和架构
2. 阅读 [为什么要更换到command+skill+专用处理程序](docs/为什么要更换到command+skill+专用处理程序.md) - 设计理念
### 4.2 了解/修改 Commands 或 Skill
1. 阅读 [aide-plugin 导览](aide-marketplace/aide-plugin/docs/README.md)
2. 阅读对应 command 的设计文档
### 4.3 了解/修改 aide 程序
1. 阅读 [aide-program 导览](aide-program/docs/README.md)
2. 阅读对应子命令的设计文档（如 [flow 子命令概览](aide-program/docs/commands/flow.md)）
3. 深入 flow 实现细节：[`aide-program/docs/commands/flow/README.md`](aide-program/docs/commands/flow/README.md)
### 4.4 了解数据格式
- 配置文件：[aide-program/docs/formats/config.md](aide-program/docs/formats/config.md)
- 数据格式：[aide-program/docs/formats/data.md](aide-program/docs/formats/data.md)
---
## 五、待完成工作
### 5.1 扩展环境模块（可选）
可按需添加更多环境检测模块：
- java - Java JDK 检测
- go - Go 语言检测
- docker - Docker 环境检测
- cargo_deps - Rust 项目依赖（类似 node_deps）
- pub_deps - Flutter/Dart 项目依赖
### 5.2 整体验证
进行完整工作流验证：
1. `/aide:init` → `/aide:prep` → `/aide:exec` 完整流程测试
2. 验证 git 自动提交功能
3. 验证待定项 Web 界面（aide decide）
---
## 六、开发约束
### 6.1 文档约束
- 设计文档（`docs/`）给人看，包含完整上下文和流程图
- 执行文件（`commands/`、`skills/`）给 LLM 看，聚焦执行指令
- aide-program 设计文档不包含代码实现，仅使用 PlantUML 流程图和伪代码
### 6.2 代码约束
- Python >= 3.11
- 使用 uv 管理虚拟环境和依赖
- 所有输出使用 `core/output.py` 中的函数（✓/⚠/✗/→ 前缀）
- 遵循静默原则：无输出 = 正常完成
### 6.3 语言约束
- 所有对话、思考、文档与注释使用简体中文
---
## 七、版本信息
- 文档版本：1.3.0
- 更新日期：2025-12-15
- 项目阶段：设计完成，核心功能已实现
- 最近更新：
- aide decide 子命令实现（submit/result）
- 支持 Web 界面待定项确认
- 支持自定义监听地址（bind）和访问地址（url）配置
- 推荐选项默认选中
- aide flow 子命令实现
- 新增环境模块：rust, node, flutter, android, node_deps
- 支持模块实例化命名（多项目场景）
- Skill 拆分：aide（基础）+ env-config（按需）

245
docs/reference/为什么要更换到command+skill+专用处理程序.md Normal file
View File

@@ -0,0 +1,245 @@
# 核心指引
## 一、问题背景
在AI辅助开发的实践中，存在几个普遍性问题：
1. **信息过载**：每次交互都需要传递大量上下文，包括规则、流程、约束等，造成token消耗和注意力分散
2. **不确定性累积**：自然语言描述的流程存在歧义，多次执行可能产生不同结果
3. **重复劳动**：相似的操作模式反复出现，却每次都需要重新描述和执行
4. **认知负担**：复杂流程的完整规则难以在单次对话中完整呈现和遵循
## 二、核心理念
### 2.1 渐进式披露
**原则**：信息按需加载，而非一次性全量呈现。
传统做法是在CLAUDE.md中堆积所有规则和流程说明，导致：
- 初始上下文臃肿
- 大部分规则在当前任务中并不需要
- 规则之间可能存在冲突或优先级不明
改进方向是将规则和流程封装为可调用的单元，仅在需要时触发加载。
### 2.2 确定性封装
**原则**：将可变过程转化为固定接口。
自然语言描述的操作存在解释空间，例如"更新状态记录"可能被理解为：
- 直接编辑CSV文件
- 追加新行
- 修改现有行
- 重建整个文件
通过程序封装，将这种不确定性消除：
- 输入：明确的参数
- 输出：确定的结果
- 过程：固定的逻辑
### 2.3 关注点分离
**原则**：流程编排与具体执行分离。
- **Commands**：负责"做什么"和"按什么顺序做"
- **Skills**：负责"怎么做"的具体实现
这种分离使得：
- 流程调整不影响具体实现
- 实现优化不改变流程结构
- 各部分可独立演进
## 三、Commands的意义与原理
### 3.1 本质定位
Commands是**流程的触发器和编排器**。
它不执行具体操作，而是：
1. 定义一个完整流程的阶段划分
2. 规定各阶段的执行顺序和转换条件
3. 指明每个阶段应调用的Skills
4. 处理异常和分支情况
### 3.2 设计原理
Commands通过Markdown文件定义，包含：
```
命令名称 → 触发入口
前置条件 → 执行门槛
流程阶段 → 状态机定义
阶段动作 → Skills调用指引
异常处理 → 分支和恢复策略
```
当用户调用一个Command时，AI获得的是一份**结构化的执行指南**，而非散落的规则片段。
### 3.3 价值体现
| 传统方式 | Command方式 |
|---------|------------|
| 每次描述完整流程 | 一次定义，多次调用 |
| 流程步骤可能遗漏 | 阶段明确，不易遗漏 |
| 异常处理临时决定 | 预设异常处理策略 |
| 难以追踪执行进度 | 状态机明确当前位置 |
## 四、Skills的意义与原理
### 4.1 本质定位
Skills是**操作的标准化封装**。
它将一类具体操作：
1. 抽象为统一的接口
2. 隐藏内部实现细节
3. 提供确定性的输入输出
4. 减少执行过程中的信息噪声
### 4.2 设计原理
Skills通过SKILL.md定义接口，通过脚本实现逻辑：
```
接口定义（SKILL.md）：
- 功能说明
- 输入参数
- 输出格式
- 使用示例
实现脚本（*.py/*.sh）：
- 参数解析
- 业务逻辑
- 结果输出
- 错误处理
```
AI只需要知道"调用什么、传什么参数、期望什么结果"，无需关心内部如何实现。
### 4.3 价值体现
| 传统方式 | Skill方式 |
|---------|----------|
| 直接操作文件/命令 | 调用封装接口 |
| 输出信息冗长 | 输出精简有效 |
| 错误处理不一致 | 统一错误格式 |
| 操作结果不确定 | 结果格式固定 |
## 五、协作模式
### 5.1 调用关系
```
用户 → Command → 流程阶段 → Skill → 脚本 → 结果
↓ ↓ ↓
加载流程 状态流转 执行操作
```
### 5.2 信息流向
**向下传递**：
- Command向Skill传递必要的上下文参数
- Skill向脚本传递具体的操作参数
**向上返回**：
- 脚本返回执行结果（成功/失败/数据）
- Skill返回格式化的结果
- Command根据结果决定下一步流转
### 5.3 职责边界
| 层级 | 职责 | 不负责 |
|-----|------|-------|
| Command | 流程编排、状态管理、异常策略 | 具体操作实现 |
| Skill | 接口定义、参数校验、结果格式化 | 流程决策 |
| 脚本 | 具体逻辑执行 | 业务语义理解 |
## 六、设计原则
### 6.1 最小暴露原则
只暴露必要的接口和参数，隐藏实现细节。
**反例**：要求AI理解CSV文件格式并手动编辑
**正例**：提供`update_status(task_id, status)`接口
### 6.2 失败友好原则
预设失败场景的处理策略，而非依赖临时判断。
**反例**：遇到错误时"请自行判断如何处理"
**正例**：定义明确的错误码和对应的恢复动作
### 6.3 幂等性原则
相同输入产生相同结果，重复执行不产生副作用。
**反例**：每次执行都追加记录，导致重复数据
**正例**：基于唯一标识更新，存在则更新，不存在则创建
### 6.4 可观测原则
执行过程和结果应当可追踪、可验证。
**反例**：操作完成后无任何反馈
**正例**：返回结构化的执行报告，包含操作内容和结果
## 七、与传统方式的对比
### 7.1 上下文管理
| 方面 | 传统方式 | Commands + Skills |
|-----|---------|-------------------|
| 规则存放 | CLAUDE.md堆积 | 分散到各Command/Skill |
| 加载时机 | 对话开始全量加载 | 调用时按需加载 |
| 更新维护 | 修改单一大文件 | 修改对应模块 |
### 7.2 执行过程
| 方面 | 传统方式 | Commands + Skills |
|-----|---------|-------------------|
| 流程遵循 | 依赖AI记忆和理解 | 状态机强制约束 |
| 操作执行 | 自然语言描述 | 程序化调用 |
| 结果反馈 | 格式不固定 | 结构化输出 |
### 7.3 可维护性
| 方面 | 传统方式 | Commands + Skills |
|-----|---------|-------------------|
| 流程修改 | 修改描述文本 | 修改状态机定义 |
| 操作优化 | 重写描述 | 修改脚本实现 |
| 问题定位 | 回溯对话历史 | 检查对应模块 |
## 八、适用场景判断
### 8.1 适合封装为Command的场景
- 包含多个有序阶段的复杂流程
- 需要状态追踪和异常恢复
- 会被重复执行的标准化流程
- 涉及多个Skills协作的编排任务
### 8.2 适合封装为Skill的场景
- 单一职责的具体操作
- 输入输出可明确定义
- 执行逻辑相对固定
- 需要减少信息噪声的操作
### 8.3 不适合封装的场景
- 一次性的探索性任务
- 高度依赖上下文判断的决策
- 需要灵活调整的创意工作
- 简单到不值得封装的操作
## 九、总结
Commands和Skills体系的核心价值在于：
1. **降低认知负担**：将复杂流程分解为可管理的单元
2. **提高执行确定性**：用程序逻辑替代自然语言描述
3. **减少信息噪声**：只传递必要信息，隐藏实现细节
4. **增强可维护性**：模块化设计便于独立演进
这不是要限制AI的能力，而是为AI提供更清晰的执行框架，使其能够更专注于真正需要智能判断的部分，而非在重复性的流程遵循上消耗注意力。