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

🎉 init: 初始存档

Browse Source
This commit is contained in:
sayurinana(vm)
2025-12-12 03:15:49 +08:00
commit 7b89510ffd
17 changed files with 3057 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored Normal file
View File

@@ -0,0 +1 @@
anthropic-agent-skills/

14
AGENTS.md Executable file
View File

@@ -0,0 +1,14 @@
# AGENTS.md
## 核心原则
- 所有对话、思考、文档与注释必须使用简体中文！
- 复杂或多模块任务必须调用Sequential-Thinking，输出计划后再进入执行。
- python脚本不允许直接使用全局命令`python`或`python3`解释运行.py脚本程序
- 必须为含python脚本的项目创建由uv管理的虚拟环境，默认情况应创建于项目根目录下的`.venv`目录
- 同时创建并维护项目README.md的相关部分信息和requirements.txt
- 运行.py脚本程序时必须使用激活相应项目目录的虚拟环境后的`python`或直接使用目标虚拟环境下`python`的完整路径
- 凡是将会涉及两个以上文件的移动、复制、重命名操作，必须在./cache/目录下创建临时.sh脚本，然后调用脚本完成文件操作，

14
CLAUDE.md Executable file
View File

@@ -0,0 +1,14 @@
# CLAUDE.md
## 核心原则
- 所有对话、思考、文档与注释必须使用简体中文！
- 复杂或多模块任务必须调用Sequential-Thinking，输出计划后再进入执行。
- python脚本不允许直接使用全局命令`python`或`python3`解释运行.py脚本程序
- 必须为含python脚本的项目创建由uv管理的虚拟环境，默认情况应创建于项目根目录下的`.venv`目录
- 同时创建并维护项目README.md的相关部分信息和requirements.txt
- 运行.py脚本程序时必须使用激活相应项目目录的虚拟环境后的`python`或直接使用目标虚拟环境下`python`的完整路径
- 凡是将会涉及两个以上文件的移动、复制、重命名操作，必须在./cache/目录下创建临时.sh脚本，然后调用脚本完成文件操作，

71
ai-agent-memory/CLAUDE.md Executable file
View File

@@ -0,0 +1,71 @@
# AGENTS.md - AI Agent 指令体系 v6
!!! 本指令体系采用 AB 双流程架构，请根据当前任务阶段选择对应的子目录指引。
## 架构概览
```
用户需求 → A部分（任务前置准备） → task-spec.md → B部分（任务执行） → 交付成果
```
## 目录结构
| 目录 | 职责 | 入口文件 |
| --- | --- | --- |
| `ai-agent-task-builder/` | A部分：任务前置准备，优化任务描述 | `claude.md` |
| `ai-agent-exec/` | B部分：任务执行，完整实施闭环 | `claude.md` |
## 快速导航
### A部分：任务前置准备
- **入口**：`ai-agent-task-builder/claude.md`
- **核心文件**：
- `AI-AGENT_preparation.md`：完整流程规范
- `now-task.md`：用户任务描述输入
- `undetermined-template.md`：待定项记录模板
- **产出**：`task-spec.md`（任务细则）
### B部分：任务执行
- **入口**：`ai-agent-exec/claude.md`
- **核心文件**：
- `AI-AGENT_execution.md`：完整执行流程规范
- `task-spec.md`：任务细则（来自A部分或用户提供）
- **产出**：按任务要求的交付成果
## 使用流程
### 场景一：完整流程（推荐）
1. 用户在 `ai-agent-task-builder/now-task.md` 填写任务需求
2. 进入 A 部分，阅读 `ai-agent-task-builder/claude.md`
3. A 部分产出 `task-spec.md`
4. 进入 B 部分，阅读 `ai-agent-exec/claude.md`
5. B 部分按 `task-spec.md` 执行并交付
### 场景二：跳过A部分
若用户已有清晰明确的任务细则，可直接：
1. 将任务细则保存为 `task-spec.md`
2. 进入 B 部分执行
## AB 部分差异对照
| 维度 | A部分（任务前置准备） | B部分（任务执行） |
| --- | --- | --- |
| 核心目标 | 优化任务描述，产出清晰的任务细则 | 按任务细则执行，完成交付 |
| 运行模式 | 轻量化，无状态记录和git提交 | 完整流程，含状态记录和git提交 |
| 用户交互 | 频繁确认（待定项、优化结果） | 按需交互（阻塞、验证） |
| 产出物 | `task-spec.md` | 按任务要求的交付成果 |
| 返工机制 | 根据用户意见返回分析优化阶段 | 回退到相应环节并记录原因 |
## 通用约定
1. **语言**：所有记录与沟通统一使用简体中文。
2. **MCP调用**：优先使用本地工具；调用MCP前确认权限。
3. **复杂任务**：建议调用 `mcp-sequential-thinking` 进行结构化分析。
4. **时间戳**：所有时间戳必须由 `mcp-time` 服务获取。
## 版本说明
本指令体系为 v6 版本，采用 AB 拆分架构：
- A部分专注任务优化，轻量运行
- B部分专注任务执行，完整闭环
- 两部分通过 `task-spec.md` 衔接

85
ai-agent-memory/README.md Executable file
View File

@@ -0,0 +1,85 @@
# AI Agent 指令体系 v6
面向 AI Agent 的任务执行指令框架，采用 AB 双流程架构实现任务优化与执行的解耦。
## 特性
- **AB 拆分架构**：A 部分专注任务优化，B 部分专注任务执行
- **轻重分离**：A 部分轻量运行，B 部分完整闭环
- **标准化衔接**：通过 `task-spec.md` 连接两部分
- **灵活入口**：支持完整流程或跳过 A 部分直接执行
## 目录结构
```
ai-agent-memo-6/
├── claude.md # 顶层入口指引
├── README.md # 本文件
├── ai-agent-task-builder/ # A部分：任务前置准备
│ ├── claude.md # A部分入口
│ ├── AI-AGENT_preparation.md # 前置准备流程规范
│ ├── now-task.md # 用户任务描述输入
│ └── undetermined-template.md # 待定项记录模板
└── ai-agent-exec/ # B部分：任务执行
├── claude.md # B部分入口
└── AI-AGENT_execution.md # 执行流程规范
```
## 快速开始
### 完整流程（推荐）
1. 在 `ai-agent-task-builder/now-task.md` 填写任务需求
2. AI Agent 阅读 `ai-agent-task-builder/claude.md` 进入 A 部分
3. A 部分完成后产出 `task-spec.md`
4. AI Agent 阅读 `ai-agent-exec/claude.md` 进入 B 部分
5. B 部分按任务细则执行并交付
### 跳过 A 部分
若已有清晰的任务细则：
1. 将任务细则保存为 `task-spec.md`
2. AI Agent 直接进入 B 部分执行
## 流程概览
### A部分：任务前置准备
```
now-task.md → 分析优化 → undetermined.md → 用户确认 → optimized-task.md → 用户确认 → task-spec.md
```
- **目标**：优化任务描述，产出清晰可执行的任务细则
- **特点**：轻量运行，无状态记录和 git 提交
- **产出**：`task-spec.md`
### B部分：任务执行
```
task-spec.md → 流程设计 → 任务主体流程循环 → 验证结果 → 文档更新 → 收尾
```
- **目标**：按任务细则执行，完成交付
- **特点**：完整闭环，含状态记录和 git 提交
- **产出**：按任务要求的交付成果
## 核心文件说明
| 文件 | 用途 |
| --- | --- |
| `now-task.md` | 用户填写原始任务需求 |
| `undetermined.md` | A 部分产出的待定项列表（需用户确认） |
| `optimized-task.md` | A 部分优化后的任务描述 |
| `task-spec.md` | 最终任务细则，AB 部分的衔接文件 |
| `AI-AGENT_working-status.csv` | B 部分的状态记录文件 |
## 适用场景
- 需要 AI Agent 执行复杂软件工程任务
- 任务描述需要优化和明确
- 需要完整的执行过程追踪
- 多轮迭代的任务开发
## 版本历史
- **v6**：AB 拆分架构，任务优化与执行解耦

161
ai-agent-memory/ai-agent-exec/AI-AGENT_execution.md Executable file
View File

@@ -0,0 +1,161 @@
# AI-AGENT_execution.md
## 使用说明
1. 工作前先阅读本文件，确保理解整体流程。
2. 所有记录、提交与沟通统一使用简体中文。
3. 使用`ai-agent-output/YYYY-MM-DDTHH-MM-SS_UTC+8_任务简述/`集中存放`AI-AGENT_working-status.csv`及其他辅助文档。
4. 每次更新`AI-AGENT_working-status.csv`后立即执行`git add .`并提交，保持变更可追溯。
5. 复杂或多模块任务必须调用Sequential-Thinking，输出计划后再进入执行。
## 全程通用
### 核心必做
1. 全程按照"流程设计 → 任务主体流程循环 → 验证结果 → 文档更新 → 收尾"顺序执行。
2. 每进入/退出环节立即在`AI-AGENT_working-status.csv`记录状态并创建提交。
3. 关键决策、风险与假设同步写入相关设计文档。
4. 优先使用本地工具；调用任何MCP前需确认权限并在状态记录中注明。
5. Git提交保持原子化，提交信息简洁说明变更影响。
6. 所有辅助脚本、模板、日志按目录约定整理归档。
### 补充细则
1. 进入任务前确认当前Git分支正确，必要时记录新分支信息。
2. 执行测试或命令前评估副作用，必要时说明降级方案。
3. 遇到阻塞或需求变化，及时回退到相应环节并记录原因。
4. 计划内未完成项需在收尾阶段明确遗留与责任人。
### 模板/命令
1. `git add .`、`git status -sb`、`git commit -m "<type>: <说明>"`：状态记录与提交必备命令。
2. `java -jar "/home/sayurinana/env-hub/my-tools/jar/plantuml.jar" program_flowchart/src -tpng -o ../png`：生成流程图时必须使用，需保证`@startuml`下一行包含`skinparam defaultFontName "PingFang SC"`。
3. `mcp-time`：所有时间戳必须由该服务获取。
4. `mcp-sequential-thinking`：多模块或决策复杂的任务必须调用并记录结果。
### MCP 调用基准表
| 服务 | 典型场景 | 最低记录要求 |
| --- | --- | --- |
| mcp-sequential-thinking | 需求包含多子目标、存在多方案对比时 | 在状态记录注明调用与结论摘要 |
| mcp-desktop-commander | 运行终端命令、读写文件、搜索内容 | 说明命令目的、关键输出或影响 |
| mcp-serena | 需要符号级检索或结构化代码编辑 | 记录操作目标文件/符号及影响范围 |
| mcp-context7 | 查询外部官方文档或API说明 | 标注查询库ID、主题与主要引用 |
| mcp-web-search | 调研最新资讯或缺失文档时 | 说明关键词、来源筛选与可信度 |
> 若某次调用具有风险或异常，请在`AI-AGENT_working-status.csv`中补充说明。
## 1. 流程设计
### 核心必做
1. 读取`task-spec.md`，理解任务目标和执行步骤。
2. 读取项目文件，综合任务细则和项目信息进行分析。
3. 创建工作目录`ai-agent-output/YYYY-MM-DDTHH-MM-SS_UTC+8_任务简述/`。
4. 创建`AI-AGENT_working-status.csv`，记录进入流程设计环节。
5. 制作PlantUML流程图，输出流程设计文档（如`flow-design.md`），列出交付物、依赖与风险。
6. 在状态记录标注进入流程设计及完成时间，保持提交。
### 补充细则
1. 对可能的实现分支制定回退或降级方案。
2. 需要流程图时使用PlantUML生成PNG并与文本说明一并存档。
3. 设计评审通过后再进入实施阶段，若设计变化需回写文档。
### 模板/命令
1. `program_flowchart/src/*.txt` + PlantUML命令：绘制并导出流程图。
2. `flow-design.md`：记录子步骤、依赖、风险与验证计划。
## 2. 任务主体流程循环
### 核心必做
1. 按设计逐项实现，每个子环节完成后更新状态并提交。
2. 重要决策、风险、返工原因同步写入执行记录。
3. 实现功能或文档内容后立即编写/更新对应测试或自检内容。
4. 遇到阻塞时记录原因并视需要回退到流程设计。
### 补充细则
1. 保持提交原子性，跨文件改动需说明关联。
2. 重要修改前可使用Serena定位符号，确保编辑范围准确。
### 模板/命令
1. `git status -sb`：监控改动范围。
2. `mcp-serena`相关操作：find_symbol、replace_symbol_body 等（视任务需求）。
3. `TodoWrite`或等效工具：跟踪子任务与计划提交。
## 3. 验证结果
### 核心必做
1. 对照`task-spec.md`逐项验证产出。
2. 运行必要的测试、lint或手动演示，并在状态中记录结论。
3. 如验证失败，说明原因、拟采取的补救措施并回到相应环节。
### 补充细则
1. 收集关键输出（测试结果、截图等）作为验证凭证。
2. 评估剩余风险或技术债，必要时列入后续任务。
### 模板/命令
1. 依项目脚本运行测试（例如`scripts/test.py`）；若无脚本需记录替代方法。
2. 在执行记录"验证结果"段落写入结论。
## 4. 文档更新
### 核心必做
1. 更新受影响的文档（如`README.md`、`CHANGELOG.md`、设计文档）。
2. 维护`CHANGELOG.md`：
- 将本次变更写入新的版本号段落并注明日期。
- 重建空的`[Unreleased]`区块。
3. 在状态记录描述已更新文档范围，并提交保存。
### 补充细则
1. 若流程或约定有调整，更新本文件或相关规范并说明原因。
2. Formal 文档放入`docs/`，讨论/复盘材料放入`discuss/`。
3. 如生成流程图，确保PNG与源文件一致。
### 模板/命令
1. `CHANGELOG.md`语义化更新模板：
- `[Unreleased]`
- `## YYYY-MM-DD - <version>`
2. `git add .`（提交前）与说明性提交信息。
## 5. 收尾
### 核心必做
1. 清理临时文件、调试脚本与冗余日志，保证仓库整洁。
2. 在状态记录新增最终条目，概述交付成果、遗留问题与建议。
3. 核对Git提交与计划一致，并准备后续任务交接信息。
### 补充细则
1. 保留`ai-agent-output/`下的任务目录作为历史记录。
2. 若需继续新任务，提示用户准备新的`task-spec.md`并重启流程。
3. 对遗留问题提供可行的后续处理建议或计划。
### 模板/命令
1. `git status -sb`确保提交前工作区干净。
2. `AI-AGENT_working-status.csv`最终记录模板，概述成果与风险。
## 执行自检表
| 环节 | 核对要点 | 勾选（✓/✗） |
| --- | --- | --- |
| 全程通用 | 已重读本文件，状态记录与提交保持一致 | |
| 流程设计 | PlantUML流程图已生成，设计文档完成 | |
| 任务主体流程循环 | 子环节执行有记录、测试/验证脚本已准备 | |
| 验证结果 | 所有验证通过并记录结论/风险 | |
| 文档更新 | `CHANGELOG.md`更新并创建新版本号段落 | |
| 收尾 | 仓库整洁、最终记录已写入 | |
> 在正式收尾前务必完成自检表勾选，并将结论写入`AI-AGENT_working-status.csv`。

34
ai-agent-memory/ai-agent-exec/CLAUDE.md Executable file
View File

@@ -0,0 +1,34 @@
# AGENTS.md - B部分：任务执行
!!! 在开始任务执行工作前，必须先阅读本文件，并查阅`ai-agent-exec/`目录中的所有指引。
## 快速指引
- `ai-agent-exec/AI-AGENT_execution.md`：任务执行的完整流程规范（5个环节）。
- `ai-agent-exec/task-spec.md`：任务细则（由A部分产出或用户直接提供）。
## 职责定位
B部分依据**通用守则模板**和**任务细则**，执行完整的任务实施闭环。
## 核心流程
```
task-spec.md → 读取项目文件 → 制作PlantUML流程图 → 流程设计 → 任务主体流程循环 → 验证结果 → 文档更新 → 收尾 → B结束
```
## 工作要求摘要
1. **工作状态同步**：首次进入"流程设计"环节时创建`AI-AGENT_working-status.csv`，并将其与辅助文档统一存放在`ai-agent-output/YYYY-MM-DDTHH-MM-SS_UTC+8_任务简述/`目录下，按环节维护记录并在每次更新该文件后立即创建git提交以保留状态变更轨迹。
2. **流程驱动执行**：严格遵循"流程设计 → 任务主体流程循环 → 验证结果 → 文档更新 → 收尾"的顺序执行，返工时需回退环节并记录原因。
3. **信息留痕**：所有阶段性成果、关键决策、风险与约定必须记录在相应文档中。
4. **交付完成标准**：验证交付物满足task-spec.md中的成功标准后方可收尾。
5. **提交顺序要求**：每次准备提交前先运行`git add .`；在"文档更新"环节务必先维护`CHANGELOG.md`并生成新的版本号段落，然后创建提交。
## 输入依赖
B部分的输入是`task-spec.md`，可来源于：
1. A部分的最终产出
2. 用户直接提供的任务细则
如需新增或调整项目约定，请在完成任务后同步更新本文件与相关规范文档。

110
ai-agent-memory/ai-agent-task-builder/AI-AGENT_preparation.md Executable file
View File

@@ -0,0 +1,110 @@
# AI-AGENT_preparation.md
## 使用说明
1. 工作前先阅读本文件与同目录的模板文件，确保理解整体流程。
2. 所有记录与沟通统一使用简体中文。
3. 复杂或多模块任务建议调用Sequential-Thinking，输出分析结论后再进入优化。
4. 临时约定统一记录在`optimized-task.md`的"执行前约束"表格，确认后标记状态。
## 全程通用
### 核心必做
1. 全程按照"任务分析 → 任务内容优化 → 待定项处理 → 优化结果生成"顺序执行。
2. 关键决策、风险与假设同步写入`optimized-task.md`。
3. 优先使用本地工具；调用任何MCP前需确认权限。
### 补充细则
1. 遇到模糊需求时主动询问，不做假设。
2. 遇到阻塞或需求变化，及时回退到相应阶段并向用户说明原因。
### MCP 调用基准表
| 服务 | 典型场景 | 最低记录要求 |
| --- | --- | --- |
| mcp-sequential-thinking | 需求包含多子目标、存在多方案对比时 | 在optimized-task.md注明调用与结论摘要 |
| mcp-desktop-commander | 运行终端命令、读写文件、搜索内容 | 说明命令目的、关键输出或影响 |
| mcp-context7 | 查询外部官方文档或API说明 | 标注查询库ID、主题与主要引用 |
| mcp-web-search | 调研最新资讯或缺失文档时 | 说明关键词、来源筛选与可信度 |
## 1. 任务分析阶段
### 核心必做
1. **全面分析now-task.md内容**
- 理解任务的核心目标和具体要求
- 识别任务的复杂度和涉及范围
- 分析任务与项目现有结构的关系
2. **项目环境分析**
- 根据任务复杂度审阅相关内容
- 分析项目结构、现有规范、相关文档
- 研究类似任务的处理方式和经验
3. **复杂度评估**
- 判断是否需要使用Sequential-Thinking进行结构化分析
- 识别任务中的多层含义、多个子目标或复杂业务逻辑
## 2. 任务内容优化阶段
### 核心必做
1. **准确性优化**
- 检查任务描述的准确性和完整性
- 识别歧义和不明确之处
- 明确任务边界和成功标准
2. **简洁性优化**
- 识别和处理冗余表述
- 区分真实冗余与必要的重复强调
- 确保表达简洁但不失准确性
3. **可执行性优化**
- 将抽象要求转化为具体可执行的步骤
- 确保每个步骤都有明确的输入、输出和验证标准
- 考虑执行顺序和依赖关系
- 按`undetermined-template.md`列出所有优化或替代方案，写入`undetermined.md`并标注优势/风险
## 3. 待定项处理机制
### 核心必做
1. **记录待定项**：参考`undetermined-template.md`格式，将待定项写入`undetermined.md`
2. **统一确认**：完整分析后统一向用户确认所有待定项
3. **结果整理**：用户确认后删除不采纳的待定项，多方案待定项仅保留采纳方案
4. **方案唯一性**：确保每个保留待定项只有唯一实施方案
### 补充细则
1. 在未获得用户统一确认前，禁止进入下一阶段或修改`optimized-task.md`
2. 用户不配合删除待定项时再次澄清确认
## 4. 优化结果生成
### 核心必做
1. **生成optimized-task.md**
- 包含优化后的完整任务描述
- 明确的执行步骤和验证标准
- 整合用户确认的待定项结果
2. **质量验证**
- 确保优化后的任务描述清晰、准确、可执行
- 验证任务目标与原始需求的一致性
- 确认所有关键决策点都已明确
3. **用户最终确认**
- 向用户展示optimized-task.md
- 若用户满意，重命名为`task-spec.md`，A过程结束
- 若用户不满意，根据用户意见返工到分析优化阶段
## 返工机制
- 若用户对`undetermined.md`有异议：根据意见调整待定项，重新生成`undetermined.md`
- 若用户对`optimized-task.md`不满意：根据用户提出的具体意见，返工到分析优化阶段，重新产出中间文档
## 最终产出
A过程的最终产出物是`task-spec.md`（由`optimized-task.md`重命名而来），作为B部分的输入依赖。

34
ai-agent-memory/ai-agent-task-builder/CLAUDE.md Executable file
View File

@@ -0,0 +1,34 @@
# AGENTS.md - A部分：任务前置准备
!!! 在开始任何工作前，必须先阅读本文件，并查阅`ai-agent-task-builder/`目录中的所有指引。
## 快速指引
- `ai-agent-task-builder/AI-AGENT_preparation.md`：任务前置准备的完整流程规范。
- `ai-agent-task-builder/undetermined-template.md`：待定项记录的格式模板。
- `ai-agent-task-builder/now-task.md`：待用户填写的任务描述文件。
## 职责定位
A部分专注于**任务前置准备**，引导用户优化任务描述，产出清晰明确、可落地的最终任务细则。
## 核心流程
```
now-task.md → 分析优化 → undetermined.md → 用户确认 → optimized-task.md → 用户确认
↑ ↓
└────────────── 不满意：根据用户意见返工 ←─────────────────────┘
↓
满意 → 重命名为task-spec.md → A结束
```
## 工作要点
1. **轻量化运行**：A过程不使用csv状态记录和git提交操作，专注于任务优化。
2. **待定项处理**：所有优化方案必须经用户确认后方可纳入最终任务细则。
3. **返工机制**：若用户不满意，根据具体意见返工到分析优化环节。
4. **最终产出**：`task-spec.md`，作为B部分的输入依赖。
## 产出物说明
A过程结束后，将`optimized-task.md`重命名为`task-spec.md`，交付给B部分使用。

4
ai-agent-memory/ai-agent-task-builder/now-task.md Executable file
View File

@@ -0,0 +1,4 @@
# 现在的任务
<!-- 在此处描述您的任务需求 -->

157
ai-agent-memory/ai-agent-task-builder/undetermined-template.md Executable file
View File

@@ -0,0 +1,157 @@
# 概述
本文档用于描述待定内容的规范模板
# 格式要求
## 基本规范
1. **评分制**：使用-100到100的分数评分，分数应反映方案的综合价值
2. **独立决策**：每个待定项必须能够独立决策，采纳或去除
3. **方案分离**：同一问题的不同解决方案必须分别创建不同的方案编号
4. **排序规则**：同一待定项内的方案按评分从低到高排序，最高分方案放在最后
5. **具体描述**：优化方案中直接描述具体内容，避免抽象的可能性列举
6. **权衡透明**：每个方案必须明确列出优势和风险的具体分数
## 编号规范
- 格式：`U<待定项编号>S<方案编号>`
- **待定项编号**：使用U前缀（如U001、U002、U003），不同的问题使用不同的编号，可以独立决策互不冲突
- **方案编号**：使用S前缀（如S001、S002、S003），同一问题的不同解决方案使用不同的方案编号，用户只能从中选择一个
- 示例：
- **待定项U001**（表述优化问题）：`U001S001`、`U001S002`、`U001S003` - 用户只能选择其中一个方案
- **待定项U002**（功能范围问题）：`U002S001`、`U002S002`、`U002S003` - 用户只能选择其中一个方案
- 用户可以同时选择`U001S002`和`U002S003`，因为它们是不同待定项的方案
- 按评分从低到高排序，最高分的放在最后
# 模板
```
## 🔍 待定项U<编号> - <问题描述>
### ✅ 方案S<编号> - 【建议采纳 +<分数>分】
**📍 原文位置**：（<文件路径>，第<行数>行）
> 原文内容
**🎯 优化方案**：
> 具体的优化方案描述
**⚖️ 权衡分析**：
- ✅ **优势**（+<分数>分）：……
- ✅ **优势**（+<分数>分）：……
- ❌ **风险**（-<分数>分）：……
---
```
或
```
## 🔍 待定项U<编号> - <问题描述>
### ❌ 方案S<编号> - 【建议去除 -<分数>分】
**📍 原文位置**：（<文件路径>，第<行数>行）
> 原文内容
**🎯 优化方案**：
> 具体的优化方案描述（如删除该内容或替换为其他内容）
**⚖️ 权衡分析**：
- ❌ **问题**（-<分数>分）：……
- ✅ **潜在价值**（+<分数>分）：……
---
```
# 示例
> 假设当前工作目录在/path/to/workspace，有一个用于描述任务的文件是/path/to/workspace/ai-agent-memory/now-task.md。
>
> 然后对其进行分析和优化，将优化后需要询问用户的待定项写入到`undetermined.md`。
`undetermined.md`的内容应该类似下面所示：
```markdown
## 🔍 待定项U001 - 表述冗杂优化
### ✅ 方案S001 - 【建议采纳 +85分】
**📍 原文位置**：（tasks/task-1.md，第15-17行）
> （文内容第15行，含有目标原文的部分）
> （文内容第16行）
> （文内容第17行，含有目标原文的部分）
**🎯 优化方案**：
> 消除冗杂表述的具体优化方案
**⚖️ 权衡分析**：
- ✅ **优势**（+60分）：消除冗杂，提高可读性
- ✅ **优势**（+30分）：表述更加简洁清晰
- ❌ **风险**（-5分）：可能丢失部分细节
---
## 🔍 待定项U002 - 路径接收方式
### ✅ 方案S001 - 【建议采纳 +60分】
**📍 原文位置**：（tasks/task-1.md，第20行）
> 接收路径参数
**🎯 优化方案**：
> 通过命令行参数接收路径
**⚖️ 权衡分析**：
- ✅ **优势**（+70分）：实现简单，符合标准CLI工具惯例
- ❌ **风险**（-10分）：功能相对单一
---
### ✅ 方案S002 - 【建议采纳 +80分】
**📍 原文位置**：（tasks/task-1.md，第20行）
> 接收路径参数
**🎯 优化方案**：
> 支持通过命令行参数和Windows拖拽两种方式接收路径
**⚖️ 权衡分析**：
- ✅ **优势**（+50分）：兼顾命令行和图形界面用户习惯
- ✅ **优势**（+40分）：与拖拽要求呼应
- ❌ **风险**（-10分）：实现复杂度适中
---
### ✅ 方案S003 - 【建议采纳 +90分】
**📍 原文位置**：（tasks/task-1.md，第20行）
> 接收路径参数
**🎯 优化方案**：
> 支持多种路径输入方式：命令行参数、Windows拖拽、交互式输入
**⚖️ 权衡分析**：
- ✅ **优势**（+70分）：用户体验最佳，适应各种使用场景
- ✅ **优势**（+30分）：功能完整全面
- ❌ **风险**（-10分）：实现复杂度较高
---
## 🔍 待定项U003 - 冗余功能清理
### ❌ 方案S001 - 【建议去除 -30分】
**📍 原文位置**：（tasks/task-1.md，第25行）
> 某个冗余的功能描述
**🎯 优化方案**：
> 删除该冗余描述
**⚖️ 权衡分析**：
- ❌ **问题**（-40分）：功能冗余，增加复杂度
- ✅ **潜在价值**（+10分）：可能在某些场景下有用
---
(其他待定项略……)
```

416
aide-requirements.md Executable file
View File

@@ -0,0 +1,416 @@
# Aide 系统需求规格
## 一、项目背景
### 1.1 现状问题
原有 `ai-agent-memory/` 体系存在以下问题：
| 问题类型 | 具体表现 |
|---------|---------|
| 信息过载 | CLAUDE.md 包含完整流程规范，每次对话都需加载 |
| 操作繁琐 | CSV 状态需手动编辑、PlantUML 命令冗长、Git 多步操作 |
| 输出冗余 | 命令执行输出大量日志，无论成功失败 |
| 流程耦合 | AB 部分虽拆分但仍需手动切换和阅读大量文档 |
### 1.2 转型目标
将原有内容体系转化为 Command + Skill 体系：
- **CLAUDE.md 精简化**：仅保留项目文件结构说明，不再指导规则和流程
- **流程按需触发**：通过 Command 主动触发流程指导和规则启示
- **操作确定性封装**：通过 Skill + 定制脚本简化操作，减少不确定性
---
## 二、核心设计原则
### 2.1 渐进式披露
- 按需调用、触发
- 不在 CLAUDE.md 中堆积所有规则
- 用户/LLM 主动调用时才加载相关指引
### 2.2 确定性封装
- 将可变过程转化为固定接口
- 只暴露脚本程序和参数信息
- 内部处理流程固定化，减少多余输出
### 2.3 信息隔离
- LLM 只传核心语义数据
- 程序负责格式化、渲染、美化
- 返回结果极简，只含决策所需信息
### 2.4 核心与形式分离
| 类型 | 定义 | 处理方式 |
|------|------|----------|
| 核心信息 | 分析思考、优化思考、业务决策 | LLM 自由发挥，不受限制 |
| 形式问题 | 待定项呈现、状态记录、环境配置 | 程序封装，减少 token 污染 |
---
## 三、组件职责定义
### 3.1 Command（命令）
**本质**：对 LLM 的要求和规则
**内容焦点**：
- 思考方法论：怎么分析、怎么优化、怎么执行
- 流程指导：阶段划分、核心必做、质量要求
- 决策边界：哪些由 LLM 自主完成，哪些需要用户确认
**设计要求**：
- 聚焦核心思考，不涉及工具调用细节
- 指导方向而非限制形式
- 结果输出不受格式约束，让 LLM 竭尽全力发挥
### 3.2 Skill（技能）
**本质**：告诉 LLM 有什么工具可用
**内容焦点**：
- 工具使用说明：命令、参数、输出格式
- 调用示例：典型场景的命令示例
- 输出解读：各种输出前缀的含义
**设计要求**：
- 纯工具说明，不涉及流程指导
- 精简明确，便于快速查阅
- 封装形式问题，减少 LLM 认知负担
---
## 四、命令清单
### 4.1 /aide:init - 认知初始化
**触发时机**：进入项目开始工作时
**职责**：
1. 介绍 aide 流程体系
2. 列出可用能力（Skills）
3. 说明环境和版本控制约定
**特点**：
- 不执行实际操作
- 提供认知框架
### 4.2 /aide:prep - 任务准备
**触发时机**：准备开始新任务时
**职责**：
1. 任务分析（理解目标、识别复杂度、分析环境）
2. 任务优化（准确性、简洁性、可执行性）
3. 待定项处理（通过 aide 程序化呈现）
4. 结果生成（LLM 自由发挥，产出 task-spec.md）
**核心原则**：
- 分析和优化阶段：指导 LLM 思考方向，让其竭尽全力发挥
- 待定项处理：程序化呈现，减少 token 污染
- 结果生成：不受格式限制，由用户直接审阅
**运行特点**：
- 轻量化：不创建工作目录、不记录状态、不 git 提交
### 4.3 /aide:exec - 任务执行
**触发时机**：任务准备完成，开始执行时
**职责**：
1. 流程规划（理解细则、制定计划、环境准备）
2. 迭代实现（按计划执行、状态同步、阻塞处理）
3. 验证交付（对照标准、功能验证）
4. 文档收尾（变更记录、版本发布）
**核心原则**：
- 业务代码编写：LLM 自由发挥，不加程序约束
- 状态管理、版本控制：通过 aide 程序处理，避免信息污染
---
## 五、技能清单
### 5.1 aide-env - 环境管理
**用途**：检测和修复项目开发环境
**核心命令**：
- `aide env check` - 检测环境（只读）
- `aide env ensure` - 检测并修复
**设计要点**：
- 成功时输出极简：`✓ 环境就绪 (python:3.12)`
- 自动修复小问题时简短提示
- 仅无法修复时才需要 LLM 关注
### 5.2 aide-undetermined - 待定项处理
**用途**：程序化呈现待定项，获取用户确认
**核心命令**：
- `aide undetermined add '<json>'` - 添加待定项
- `aide undetermined confirm` - 生成确认报告（给用户）
- `aide undetermined result` - 获取结果（给 LLM）
**设计要点**：
- LLM 传入精简 JSON 数据
- 程序渲染美化界面给用户
- 返回精简决策结果给 LLM
### 5.3 aide-workspace - 工作目录管理
**用途**：管理任务工作目录
**核心命令**：
- `aide workspace init <name>` - 创建工作目录
- `aide workspace clean --keep=N` - 清理旧目录
### 5.4 aide-progress - 进度管理
**用途**：记录任务执行状态
**核心命令**：
- `aide progress init <name>` - 初始化状态
- `aide progress update <phase> <status>` - 更新状态
**设计要点**：
- 替代手动编辑 CSV
- 提供动态反馈和步骤引导
- 避免 LLM "跑飞"
### 5.5 aide-version - 版本控制
**用途**：管理 CHANGELOG 和 Git 操作
**核心命令**：
- `aide version add <type> "<desc>"` - 添加变更
- `aide version commit "<msg>"` - Git 提交
- `aide version release [level]` - 发布版本
**设计要点**：
- 封装 Git 操作，减少情况分析复杂度
- 通过有限参数控制不同需求
### 5.6 aide-build - 构建工具
**用途**：编译 PlantUML 等
**核心命令**：
- `aide build plantuml <src>` - 编译
- `aide build plantuml <src> -c` - 语法检查
**设计要点**：
- 集成语法检查、编译、简要输出
- 替代冗长的 java -jar 命令
---
## 六、信息流设计
### 6.1 待定项处理流程
```
LLM 程序 用户
│ │ │
│ JSON (精简数据) │ │
│─────────────────────→│ │
│ │ 渲染美化界面 │
│ │─────────────────────→│
│ │ │
│ │ 用户选择 │
│ │←─────────────────────│
│ JSON (决策结果) │ │
│←─────────────────────│ │
```
### 6.2 输出精简原则
| 场景 | 输出策略 |
|------|----------|
| 成功 | 极简确认：`✓ 操作完成` |
| 自动修复 | 简短提示：`✓ 已修复: xxx` |
| 警告 | 告知但可继续：`⚠ 警告内容` |
| 失败 | 详细原因：`✗ 失败原因及建议` |
---
## 七、LLM 自由发挥边界
### 7.1 需要程序约束的场景
- 环境检测与修复
- 待定项呈现与确认
- 状态记录与更新
- 版本控制操作
- 构建工具调用
### 7.2 不需要程序约束的场景
- 任务分析思考
- 任务优化思考
- 业务决策判断
- 任务细则编写（task-spec.md）
- 业务代码编写
- 结果文档产出
---
## 八、数据格式规范
### 8.1 待定项数据格式
**输入格式（LLM → 程序）**：
```json
{
"items": [
{
"id": "唯一标识符",
"question": "问题标题",
"description": "详细说明（可选）",
"options": [
{"value": "程序值", "label": "显示文本", "score": 0-100}
],
"recommend": "推荐选项的 value",
"reason": "推荐理由"
}
]
}
```
**输出格式（程序 → LLM）**：
```json
{
"decisions": [
{"id": "标识符", "chosen": "选择的 value", "custom": "自定义内容或 null"}
]
}
```
### 8.2 输出前缀规范
| 前缀 | 函数 | 用途 |
|------|------|------|
| ✓ | `ok` | 成功 |
| ⚠ | `warn` | 警告（可继续） |
| ✗ | `err` | 失败 |
| → | `info` | 进行中 |
| [n/m] | `step` | 步骤进度 |
### 8.3 配置文件 aide.toml
```toml
[env]
modules = ["python", "uv"]
[env.python]
version = ">=3.10"
venv = ".venv"
requirements = "requirements.txt"
[workspace]
output = "ai-agent-output"
format = "{timestamp}_{name}"
[progress]
phases = ["规划", "实现", "验证", "文档", "收尾"]
[version]
changelog = "CHANGELOG.md"
```
---
## 九、实施结构
### 9.1 插件目录结构
```
aide-plugin/
├── .claude-plugin/
│ └── plugin.json
├── commands/
│ ├── init.md
│ ├── prep.md
│ └── exec.md
└── skills/
├── aide-env/SKILL.md
├── aide-undetermined/SKILL.md
├── aide-workspace/SKILL.md
├── aide-progress/SKILL.md
├── aide-version/SKILL.md
└── aide-build/SKILL.md
```
### 9.2 运行时脚本结构
```
aide/
├── aide.sh # 统一入口
├── lib/
│ ├── output.sh # 输出函数（ok/warn/err/info/step）
│ └── config.py # 配置读取
├── env/
│ └── check.py # 环境检测
├── undetermined/
│ └── handler.py # 待定项处理
├── workspace/
│ └── manager.py # 工作目录管理
├── progress/
│ └── tracker.py # 进度管理
├── version/
│ ├── changelog.py # CHANGELOG 管理
│ └── git.sh # Git 操作
└── build/
└── plantuml.sh # PlantUML 编译
```
### 9.3 安装方式
```bash
export AIDE_ROOT="/path/to/aide"
ln -s "$AIDE_ROOT/aide.sh" ~/.local/bin/aide
```
---
## 十、实施检查清单
### 10.1 插件部分
- [ ] plugin.json 元数据
- [ ] commands/init.md - 认知初始化
- [ ] commands/prep.md - 任务准备方法论
- [ ] commands/exec.md - 任务执行方法论
- [ ] skills/aide-env/SKILL.md
- [ ] skills/aide-undetermined/SKILL.md
- [ ] skills/aide-workspace/SKILL.md
- [ ] skills/aide-progress/SKILL.md
- [ ] skills/aide-version/SKILL.md
- [ ] skills/aide-build/SKILL.md
### 10.2 运行时部分
- [ ] aide.sh 入口脚本
- [ ] lib/output.sh 输出函数
- [ ] lib/config.py 配置读取
- [ ] env/check.py 环境检测
- [ ] undetermined/handler.py 待定项处理
- [ ] workspace/manager.py 工作目录
- [ ] progress/tracker.py 进度管理
- [ ] version/changelog.py CHANGELOG
- [ ] version/git.sh Git 操作
- [ ] build/plantuml.sh PlantUML
### 10.3 验收标准
1. 三个 Command 能正确触发对应流程
2. 六个 Skill 的 aide 命令能正常执行
3. 待定项能正确渲染和返回结果
4. 输出符合精简原则

378
cache/EVALUATION-REPORT.md vendored Normal file
View File

@@ -0,0 +1,378 @@
# Guide 指南评估报告（更新版）
**评估日期**: 2025-12-11
**评估依据**:
- Claude Code 官方文档：https://code.claude.com/docs/en/slash-commands
- Claude Code 官方文档：https://code.claude.com/docs/en/plugins
- Claude Code 官方文档：https://code.claude.com/docs/en/skills
- Claude Code 官方文档：https://code.claude.com/docs/en/plugin-marketplaces
- anthropic-agent-skills 官方仓库
**评估对象**: guide/ 目录下的四份指南文档
---
## 一、总体评价
| 维度 | 评分 | 说明 |
|------|------|------|
| 结构完整性 | ★★★★☆ | 分层清晰，覆盖了主要概念 |
| 内容准确性 | ★★★★☆ | 与官方文档高度一致，仅有少量偏差 |
| 最佳实践 | ★★★☆☆ | 缺少部分官方强调的设计原则 |
| 实用性 | ★★★★☆ | 提供了丰富的示例和命令 |
| 中文本地化 | ★★★★★ | 良好的中文表述，便于中文用户理解 |
**更新说明**：基于官方文档的验证，guide 的内容准确性比之前评估的更高。大部分内容与官方一致，只有少量遗漏和细节差异。
---
## 二、各文档详细评估
### 2.1 01-自定义斜杠命令指南.md
**状态**: ✅ 基本正确
**与官方文档对比** (https://code.claude.com/docs/en/slash-commands)：
#### 正确的内容
| 内容 | 状态 | 说明 |
|------|------|------|
| 命令存储位置 | ✅ | `.claude/commands/`（项目）和 `~/.claude/commands/`（个人）正确 |
| Frontmatter 字段 | ✅ | `allowed-tools`、`argument-hint`、`description`、`model` 正确 |
| 参数用法 | ✅ | `$ARGUMENTS`、`$1`、`$2` 等正确 |
| 文件引用 | ✅ | `@` 前缀引用文件正确 |
| Bash 命令嵌入 | ✅ | `` !`command` `` 语法正确 |
| 命名空间 | ✅ | 子目录组织形成命名空间正确 |
#### 遗漏内容
| 遗漏 | 官方说明 | 建议补充 |
|------|----------|----------|
| `disable-model-invocation` 字段 | 防止 SlashCommand 工具调用此命令 | 在 frontmatter 配置中补充此字段 |
| 命令优先级 | 项目命令覆盖同名用户命令 | 添加优先级说明 |
| MCP 斜杠命令 | `/mcp__<server-name>__<prompt-name>` 格式 | 添加 MCP 命令章节 |
| 插件命令格式 | `/plugin-name:command-name` | 添加插件命令说明 |
| SlashCommand 工具集成 | 字符预算限制、权限规则等 | 添加工具集成章节 |
| Extended Thinking | 斜杠命令可触发扩展思考 | 添加相关说明 |
#### 轻微问题
| 问题 | 详情 |
|------|------|
| 命名空间格式 | 官方格式为 `(project:frontend)`，guide 写的也正确 |
| 默认值说明 | 官方表格更清晰，建议参照官方格式 |
---
### 2.2 02-技能指南.md
**状态**: ✅ 基本正确，有遗漏
**与官方文档对比** (https://code.claude.com/docs/en/skills)：
#### 正确的内容
| 内容 | 状态 | 说明 |
|------|------|------|
| 技能存储位置 | ✅ | 个人、项目、插件三种位置正确 |
| SKILL.md 结构 | ✅ | YAML frontmatter + Markdown body 正确 |
| name 字段要求 | ✅ | 小写字母、数字、连字符，最多64字符 |
| description 字段 | ✅ | 最多1024字符 |
| allowed-tools | ✅ | 可选工具限制正确 |
| 目录结构 | ✅ | 多文件技能结构正确 |
#### 与之前评估的修正
| 之前评估 | 实际情况 |
|----------|----------|
| ❌ 认为缺少 "name 必须与目录名匹配" 的约束 | 官方文档未明确要求此约束，但 anthropic-agent-skills 规范中有此要求 |
| ❌ 认为缺少 license 和 metadata 字段 | 官方 Claude Code 文档确实未提及这些字段，但 Agent Skills Spec 中有 |
#### 遗漏内容
| 遗漏 | 官方说明 | 建议补充 |
|------|----------|----------|
| Progressive Disclosure | 官方提及 "Claude only reads additional files when needed" | 添加渐进式披露原则说明 |
| Description 最佳实践 | 官方强调包含 "what it does AND when to use it" | 补充 description 编写指南 |
| 调试方法 | `claude --debug` 模式 | 添加调试章节 |
| 脚本权限 | `chmod +x` 设置执行权限 | 已提及但可更详细 |
| Skills vs Slash Commands 对比 | 官方有详细对比表 | 添加对比章节 |
#### 优化建议
官方 description 最佳实践示例：
```yaml
# ❌ 太模糊
description: Helps with documents
# ✅ 具体
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.
```
建议在指南中添加类似的正反例。
---
### 2.3 03-插件指南.md
**状态**: ✅ 正确
**与官方文档对比** (https://code.claude.com/docs/en/plugins)：
#### 正确的内容
| 内容 | 状态 | 说明 |
|------|------|------|
| 插件目录结构 | ✅ | `.claude-plugin/`、`commands/`、`agents/`、`skills/`、`hooks/` 完全正确 |
| plugin.json 结构 | ✅ | `name`、`description`、`version`、`author` 字段正确 |
| 安装命令 | ✅ | `/plugin install plugin-name@marketplace-name` 正确 |
| 管理命令 | ✅ | `enable`、`disable`、`uninstall` 命令正确 |
#### 与之前评估的修正
| 之前评估 | 实际情况 |
|----------|----------|
| ⚠️ 怀疑 agents/ 目录 | **官方确认** agents/ 目录是有效的插件组件 |
| ⚠️ 怀疑 plugin.json vs marketplace.json 混淆 | **两者是不同的文件**：plugin.json 用于单个插件，marketplace.json 用于市场索引 |
#### 遗漏内容
| 遗漏 | 官方说明 | 建议补充 |
|------|----------|----------|
| `.mcp.json` 位置 | 用于 MCP 服务器配置 | 已提及，可更详细说明 |
| 调试技巧 | 检查结构、单独测试组件等 | 添加调试章节 |
| 分享前准备 | README、语义化版本等 | 添加分发准备说明 |
---
### 2.4 04-插件市场指南.md
**状态**: ⚠️ 需要更正
**与官方文档对比** (https://code.claude.com/docs/en/plugin-marketplaces)：
#### 正确的内容
| 内容 | 状态 | 说明 |
|------|------|------|
| marketplace.json 结构 | ✅ | `name`、`owner`、`plugins` 字段正确 |
| 插件条目字段 | ✅ | `name`、`source`、`description` 等正确 |
| 插件来源格式 | ✅ | 相对路径、GitHub、Git URL 格式正确 |
| 安装命令 | ✅ | `/plugin marketplace add` 系列命令正确 |
| 团队配置 | ✅ | `.claude/settings.json` 中的 `extraKnownMarketplaces` 正确 |
#### 需要更正的内容
| 问题 | 当前文档 | 官方正确信息 |
|------|----------|--------------|
| 官方示例仓库命令 | `/plugin marketplace add anthropics/claude-code` | 应为官方实际仓库地址（需验证） |
| 验证命令 | 未提及 | `claude plugin validate .` |
**注意**：官方文档未明确给出 `anthropics/skills` 或 `anthropics/claude-code` 作为示例仓库地址。建议删除或更新此引用。
#### 遗漏的插件条目字段
官方支持但 guide 未提及的字段：
| 字段 | 类型 | 说明 |
|------|------|------|
| `category` | string | 插件分类 |
| `tags` | array | 搜索标签 |
| `strict` | boolean | 是否要求 plugin.json（默认 true） |
| `commands` | string\|array | 自定义命令路径 |
| `agents` | string\|array | 自定义代理路径 |
| `hooks` | string\|object | 钩子配置或路径 |
| `mcpServers` | string\|object | MCP 服务器配置 |
**好消息**：guide 中提到的这些扩展字段（commands、agents、hooks、mcpServers）**都是官方支持的**！
---
## 三、问题汇总（修订版）
### 3.1 需要更正的问题
| 编号 | 文档 | 问题 | 建议修正 |
|------|------|------|----------|
| C1 | 04-插件市场指南 | 官方示例仓库地址不确定 | 删除或验证后更新 |
### 3.2 建议补充的内容
| 编号 | 文档 | 遗漏内容 | 优先级 |
|------|------|----------|--------|
| A1 | 01-斜杠命令 | `disable-model-invocation` 字段 | 高 |
| A2 | 01-斜杠命令 | MCP 斜杠命令格式 | 中 |
| A3 | 01-斜杠命令 | 插件命令格式 `/plugin-name:command-name` | 中 |
| A4 | 01-斜杠命令 | SlashCommand 工具字符预算 | 低 |
| A5 | 02-技能指南 | Description 最佳实践（正反例） | 高 |
| A6 | 02-技能指南 | Skills vs Slash Commands 对比表 | 中 |
| A7 | 02-技能指南 | `claude --debug` 调试模式 | 中 |
| A8 | 03-插件指南 | 调试技巧章节 | 中 |
| A9 | 04-插件市场 | `strict` 字段说明 | 中 |
| A10 | 04-插件市场 | `claude plugin validate .` 验证命令 | 高 |
| A11 | 04-插件市场 | `category` 和 `tags` 字段 | 低 |
### 3.3 之前评估的修正
| 之前判断 | 修正后判断 | 说明 |
|----------|------------|------|
| ❌ agents/ 目录存疑 | ✅ 官方确认支持 | 是有效的插件组件 |
| ❌ commands/agents/hooks/mcpServers 字段存疑 | ✅ 官方确认支持 | 都是有效的插件条目字段 |
| ❌ name 必须与目录名匹配 | ⚠️ 仅在 Agent Skills Spec 中要求 | Claude Code 官方文档未明确要求 |
---
## 四、改进建议（更新版）
### 4.1 高优先级补充
#### 1. 补充 `disable-model-invocation` 字段
在 01-斜杠命令指南的 Frontmatter 配置表中添加：
```markdown
| `disable-model-invocation` | 是否禁止 SlashCommand 工具调用此命令 | false |
```
#### 2. 补充 Description 最佳实践
在 02-技能指南中添加：
```markdown
### Description 编写指南
**关键原则**：description 是技能的**主要发现机制**，必须同时说明：
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.
```
```
#### 3. 补充验证命令
在 04-插件市场指南中添加：
```markdown
### 验证和测试
```bash
# 验证市场 JSON 语法和结构
claude plugin validate .
# 添加本地市场测试
/plugin marketplace add ./path/to/marketplace
# 测试插件安装
/plugin install test-plugin@marketplace-name
```
```
### 4.2 中优先级补充
#### 4. 添加 Skills vs Slash Commands 对比表
在 02-技能指南末尾添加：
```markdown
## Skills 与斜杠命令的区别
| 方面 | Agent Skills | 斜杠命令 |
|------|--------------|----------|
| **调用方式** | 模型自动调用 | 用户显式调用（`/command`） |
| **发现机制** | 基于 description | 基于 `/` 前缀 |
| **复杂度** | 复杂能力包 | 简单提示 |
| **文件结构** | 目录 + SKILL.md + 资源 | 单个 .md 文件 |
| **适用场景** | 扩展 Claude 能力 | 快速重复任务 |
**选择建议**：
- 使用**斜杠命令**：快速、常用的提示（review、explain、optimize）
- 使用 **Skills**：包含脚本、跨文件知识、团队标准化的综合工作流
```
#### 5. 添加 MCP 斜杠命令说明
在 01-斜杠命令指南中添加：
```markdown
## 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 连接状态和可用工具。
```
### 4.3 低优先级补充
- 添加 `category` 和 `tags` 字段说明
- 添加 SlashCommand 工具字符预算说明
- 补充 Extended Thinking 触发说明
---
## 五、结论（更新版）
基于对 Claude Code 官方文档的详细比对，guide/ 目录下的指南文档**质量较高**，大部分内容与官方一致。主要问题已从"严重错误"降级为"建议补充"。
### 评估结果变化
| 维度 | 之前评分 | 更新评分 | 变化原因 |
|------|----------|----------|----------|
| 内容准确性 | ★★★☆☆ | ★★★★☆ | 官方确认 agents/、扩展字段等都正确 |
| 最佳实践 | ★★☆☆☆ | ★★★☆☆ | 缺失内容比预期少 |
### 建议行动
1. **立即修正**：验证或删除官方仓库地址引用（C1）
2. **优先补充**：高优先级内容（A1、A5、A10）
3. **逐步完善**：中低优先级内容
4. **保持更新**：关注 Claude Code 官方文档变化
### 指南优点（保持）
1. ✅ 清晰的中文结构化文档
2. ✅ 与官方一致的技术内容
3. ✅ 丰富的命令和代码示例
4. ✅ 表格化参数说明
5. ✅ 文档间交叉引用
---
## 附录：官方文档参考链接
- 斜杠命令：https://code.claude.com/docs/en/slash-commands
- 插件系统：https://code.claude.com/docs/en/plugins
- Agent Skills：https://code.claude.com/docs/en/skills
- 插件市场：https://code.claude.com/docs/en/plugin-marketplaces
- 子代理：https://code.claude.com/docs/en/sub-agents
- 钩子：https://code.claude.com/docs/en/hooks
- MCP：https://code.claude.com/docs/en/mcp
- 插件参考：https://code.claude.com/docs/en/plugins-reference
---
*本报告基于 Claude Code 官方文档和 anthropic-agent-skills 仓库内容生成。*

303
guide/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
guide/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
guide/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
guide/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)