From 7b89510ffdd44def9e0bee0550e0e2ed62439c24 Mon Sep 17 00:00:00 2001 From: "sayurinana(vm)" Date: Fri, 12 Dec 2025 03:15:49 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=89=20init:=20=E5=88=9D=E5=A7=8B?= =?UTF-8?q?=E5=AD=98=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 1 + AGENTS.md | 14 + CLAUDE.md | 14 + ai-agent-memory/CLAUDE.md | 71 +++ ai-agent-memory/README.md | 85 ++++ .../ai-agent-exec/AI-AGENT_execution.md | 161 ++++++ ai-agent-memory/ai-agent-exec/CLAUDE.md | 34 ++ .../AI-AGENT_preparation.md | 110 +++++ .../ai-agent-task-builder/CLAUDE.md | 34 ++ .../ai-agent-task-builder/now-task.md | 4 + .../undetermined-template.md | 157 ++++++ aide-requirements.md | 416 ++++++++++++++++ cache/EVALUATION-REPORT.md | 378 +++++++++++++++ guide/01-自定义斜杠命令指南.md | 303 ++++++++++++ guide/02-技能指南.md | 457 ++++++++++++++++++ guide/03-插件指南.md | 436 +++++++++++++++++ guide/04-插件市场指南.md | 382 +++++++++++++++ 17 files changed, 3057 insertions(+) create mode 100644 .gitignore create mode 100755 AGENTS.md create mode 100755 CLAUDE.md create mode 100755 ai-agent-memory/CLAUDE.md create mode 100755 ai-agent-memory/README.md create mode 100755 ai-agent-memory/ai-agent-exec/AI-AGENT_execution.md create mode 100755 ai-agent-memory/ai-agent-exec/CLAUDE.md create mode 100755 ai-agent-memory/ai-agent-task-builder/AI-AGENT_preparation.md create mode 100755 ai-agent-memory/ai-agent-task-builder/CLAUDE.md create mode 100755 ai-agent-memory/ai-agent-task-builder/now-task.md create mode 100755 ai-agent-memory/ai-agent-task-builder/undetermined-template.md create mode 100755 aide-requirements.md create mode 100644 cache/EVALUATION-REPORT.md create mode 100755 guide/01-自定义斜杠命令指南.md create mode 100755 guide/02-技能指南.md create mode 100755 guide/03-插件指南.md create mode 100755 guide/04-插件市场指南.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..01dac5a --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +anthropic-agent-skills/ \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100755 index 0000000..68bbda5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,14 @@ +# AGENTS.md + +## 核心原则 + +- 所有对话、思考、文档与注释必须使用简体中文！ + +- 复杂或多模块任务必须调用Sequential-Thinking，输出计划后再进入执行。 + +- python脚本不允许直接使用全局命令`python`或`python3`解释运行.py脚本程序 + - 必须为含python脚本的项目创建由uv管理的虚拟环境，默认情况应创建于项目根目录下的`.venv`目录 + - 同时创建并维护项目README.md的相关部分信息和requirements.txt + - 运行.py脚本程序时必须使用激活相应项目目录的虚拟环境后的`python`或直接使用目标虚拟环境下`python`的完整路径 + +- 凡是将会涉及两个以上文件的移动、复制、重命名操作，必须在./cache/目录下创建临时.sh脚本，然后调用脚本完成文件操作， \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100755 index 0000000..c61369e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,14 @@ +# CLAUDE.md + +## 核心原则 + +- 所有对话、思考、文档与注释必须使用简体中文！ + +- 复杂或多模块任务必须调用Sequential-Thinking，输出计划后再进入执行。 + +- python脚本不允许直接使用全局命令`python`或`python3`解释运行.py脚本程序 + - 必须为含python脚本的项目创建由uv管理的虚拟环境，默认情况应创建于项目根目录下的`.venv`目录 + - 同时创建并维护项目README.md的相关部分信息和requirements.txt + - 运行.py脚本程序时必须使用激活相应项目目录的虚拟环境后的`python`或直接使用目标虚拟环境下`python`的完整路径 + +- 凡是将会涉及两个以上文件的移动、复制、重命名操作，必须在./cache/目录下创建临时.sh脚本，然后调用脚本完成文件操作， \ No newline at end of file diff --git a/ai-agent-memory/CLAUDE.md b/ai-agent-memory/CLAUDE.md new file mode 100755 index 0000000..aa64ba5 --- /dev/null +++ b/ai-agent-memory/CLAUDE.md @@ -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` 衔接 diff --git a/ai-agent-memory/README.md b/ai-agent-memory/README.md new file mode 100755 index 0000000..9fa0de0 --- /dev/null +++ b/ai-agent-memory/README.md @@ -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 拆分架构，任务优化与执行解耦 diff --git a/ai-agent-memory/ai-agent-exec/AI-AGENT_execution.md b/ai-agent-memory/ai-agent-exec/AI-AGENT_execution.md new file mode 100755 index 0000000..ae86fc2 --- /dev/null +++ b/ai-agent-memory/ai-agent-exec/AI-AGENT_execution.md @@ -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 ": <说明>"`：状态记录与提交必备命令。 +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 - ` +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`。 diff --git a/ai-agent-memory/ai-agent-exec/CLAUDE.md b/ai-agent-memory/ai-agent-exec/CLAUDE.md new file mode 100755 index 0000000..107f3ef --- /dev/null +++ b/ai-agent-memory/ai-agent-exec/CLAUDE.md @@ -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. 用户直接提供的任务细则 + +如需新增或调整项目约定，请在完成任务后同步更新本文件与相关规范文档。 diff --git a/ai-agent-memory/ai-agent-task-builder/AI-AGENT_preparation.md b/ai-agent-memory/ai-agent-task-builder/AI-AGENT_preparation.md new file mode 100755 index 0000000..b5ef0b6 --- /dev/null +++ b/ai-agent-memory/ai-agent-task-builder/AI-AGENT_preparation.md @@ -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部分的输入依赖。 diff --git a/ai-agent-memory/ai-agent-task-builder/CLAUDE.md b/ai-agent-memory/ai-agent-task-builder/CLAUDE.md new file mode 100755 index 0000000..9adfd5f --- /dev/null +++ b/ai-agent-memory/ai-agent-task-builder/CLAUDE.md @@ -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部分使用。 diff --git a/ai-agent-memory/ai-agent-task-builder/now-task.md b/ai-agent-memory/ai-agent-task-builder/now-task.md new file mode 100755 index 0000000..08fa483 --- /dev/null +++ b/ai-agent-memory/ai-agent-task-builder/now-task.md @@ -0,0 +1,4 @@ +# 现在的任务 + + + diff --git a/ai-agent-memory/ai-agent-task-builder/undetermined-template.md b/ai-agent-memory/ai-agent-task-builder/undetermined-template.md new file mode 100755 index 0000000..e7e2b0a --- /dev/null +++ b/ai-agent-memory/ai-agent-task-builder/undetermined-template.md @@ -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分）：可能在某些场景下有用 + +--- + +(其他待定项略……) +``` diff --git a/aide-requirements.md b/aide-requirements.md new file mode 100755 index 0000000..45a37a4 --- /dev/null +++ b/aide-requirements.md @@ -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 ''` - 添加待定项 +- `aide undetermined confirm` - 生成确认报告（给用户） +- `aide undetermined result` - 获取结果（给 LLM） + +**设计要点**： +- LLM 传入精简 JSON 数据 +- 程序渲染美化界面给用户 +- 返回精简决策结果给 LLM + +### 5.3 aide-workspace - 工作目录管理 + +**用途**：管理任务工作目录 + +**核心命令**： +- `aide workspace init ` - 创建工作目录 +- `aide workspace clean --keep=N` - 清理旧目录 + +### 5.4 aide-progress - 进度管理 + +**用途**：记录任务执行状态 + +**核心命令**： +- `aide progress init ` - 初始化状态 +- `aide progress update ` - 更新状态 + +**设计要点**： +- 替代手动编辑 CSV +- 提供动态反馈和步骤引导 +- 避免 LLM "跑飞" + +### 5.5 aide-version - 版本控制 + +**用途**：管理 CHANGELOG 和 Git 操作 + +**核心命令**： +- `aide version add ""` - 添加变更 +- `aide version commit ""` - Git 提交 +- `aide version release [level]` - 发布版本 + +**设计要点**： +- 封装 Git 操作，减少情况分析复杂度 +- 通过有限参数控制不同需求 + +### 5.6 aide-build - 构建工具 + +**用途**：编译 PlantUML 等 + +**核心命令**： +- `aide build plantuml ` - 编译 +- `aide build plantuml -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. 输出符合精简原则 diff --git a/cache/EVALUATION-REPORT.md b/cache/EVALUATION-REPORT.md new file mode 100644 index 0000000..50d4949 --- /dev/null +++ b/cache/EVALUATION-REPORT.md @@ -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____` 格式 | 添加 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____ [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 仓库内容生成。* diff --git a/guide/01-自定义斜杠命令指南.md b/guide/01-自定义斜杠命令指南.md new file mode 100755 index 0000000..99daf9c --- /dev/null +++ b/guide/01-自定义斜杠命令指南.md @@ -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____ [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) diff --git a/guide/02-技能指南.md b/guide/02-技能指南.md new file mode 100755 index 0000000..4e4d5e4 --- /dev/null +++ b/guide/02-技能指南.md @@ -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) diff --git a/guide/03-插件指南.md b/guide/03-插件指南.md new file mode 100755 index 0000000..663917f --- /dev/null +++ b/guide/03-插件指南.md @@ -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) diff --git a/guide/04-插件市场指南.md b/guide/04-插件市场指南.md new file mode 100755 index 0000000..7ff39f7 --- /dev/null +++ b/guide/04-插件市场指南.md @@ -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)