自定義外掛開發

Claude Code最強大的功能就是外掛系統。

開發自定義外掛能把團隊工作流程、編碼規範、最佳實踐封裝成可重用元件,大幅提升開發效率。

今天帶你從零開始掌握Claude Code外掛開發。

什麼是Claude Code外掛

Claude Code外掛是一種打包分發自定義功能的方式,類似於VS Code擴充套件或Chrome外掛。一個外掛可以包含:

• Slash命令(斜槓命令): 快速執行的快捷指令
• SubAgent(子代理): 專注於特定任務的AI助手
• MCP伺服器: Model Context Protocol整合,連線外部資料來源
• Hooks(鉤子): 在特定事件觸發時自動執行的指令碼

外掛的價值

1. 知識封裝 把複雜工作流程、編碼規範封裝成外掛,新成員安裝後就能獲得最佳實踐

2. 團隊協作 透過Git共享外掛,確保團隊用統一的工具和規範

3. 效率提升 一鍵執行復雜任務,減少重複勞動

4. 可擴充套件性 無縫整合外部工具和服務(Jira、GitHub、Slack等)

外掛開發環境搭建

前置要求

在開始之前,確保你已經:

1. 安裝了Claude Code CLI
2. 熟悉基本的命令列操作
3. 瞭解Node.js和npm(用於某些高階外掛)
4. 有一個用於測試的專案目錄

安裝Claude Code

# macOS/Linux
curl -fsSL https://claude.ai/install.sh | bash

# 验证安装
claude --version

建立測試專案

# 创建插件开发测试目录
mkdir claude-plugin-dev
cd claude-plugin-dev

# 初始化项目
npm init -y

# 创建基本的项目结构
mkdir -p src/components
mkdir -p src/utils
mkdir -p tests

外掛目錄結構

一個標準的Claude Code外掛專案結構如下:

my-claude-plugin/
├── .claude/                 # Claude配置目录
│   ├── plugin.json         # 插件清单文件
│   ├── commands/           # Slash命令定义
│   │   ├── deploy.md
│   │   └── test.md
│   ├── agents/             # SubAgent定义
│   │   └── code-reviewer.md
│   └── hooks/              # Hooks脚本
│       └── pre-commit.sh
├── README.md               # 插件说明文档
└── package.json            # 如果需要npm依赖

建立你的第一個外掛

第一步:建立外掛清單檔案

在專案根目錄建立.claude/plugin.json:

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "我的第一个Claude Code插件",
  "author": "Your Name <your.email@example.com>",
  "license": "MIT",
  "claude": {
    "minVersion": "1.0.0"
  },
  "commands": [
    {
      "name": "hello",
      "description": "打招呼命令",
      "file": "commands/hello.md"
    }
  ],
  "agents": [],
  "hooks": {}
}

第二步:建立Slash命令

建立.claude/commands/hello.md:

---
description: 向用户打招呼并显示项目信息
---

# Hello命令

欢迎使用Claude Code插件!

请执行以下操作:
1. 读取项目的package.json文件
2. 显示项目名称和版本
3. 打印一条友好的欢迎消息

示例输出格式:

👋 你好!

專案: [專案名稱] 版本: [版本號] 當前目錄: [當前工作目錄]

祝你編碼愉快! 🚀

第三步:測試外掛

# 在项目目录启动Claude Code
claude

# 使用你的自定义命令
/hello

預期輸出:

👋 你好!

项目: my-first-plugin
版本: 1.0.0
当前目录: /Users/username/claude-plugin-dev

祝你编码愉快! 🚀

恭喜!你已經成功建立了第一個Claude Code外掛。

Slash命令開發

Slash命令是外掛中最常用的元件,它允許你透過簡短的指令執行復雜任務。

命令檔案結構

一個完整的Slash命令檔案包含YAML frontmatter和Markdown內容:

---
description: 命令的简短描述
usage: 命令的使用示例(可选)
parameters:  # 可选的参数定义
  - name: param1
    description: 参数1的说明
    required: true
tags:  # 可选的标签
  - deployment
  - testing
---

# 命令标题

这里是命令的详细说明和执行逻辑...

實戰示例1:程式碼部署命令

建立.claude/commands/deploy.md:

---
description: 自动化部署流程
usage: /deploy [环境]
parameters:
  - name: 环境
    description: 部署目标环境(dev/staging/prod)
    required: false
tags:
  - deployment
  - automation
---

# 部署命令

执行以下部署流程:

## 1. 环境检查
- 检查Git工作区是否干净
- 检查当前分支
- 验证环境变量

## 2. 测试
- 运行单元测试: `npm test`
- 运行linting: `npm run lint`
- 构建项目: `npm run build`

## 3. 部署
根据指定环境执行部署:

**开发环境** (默认):
```bash
npm run deploy:dev

预发布环境:

npm run deploy:staging

生产环境:

npm run deploy:prod

4. 验证

• 检查部署状态
• 运行冒烟测试
• 发送通知

注意事项

⚠️ 生产环境部署需要额外确认 ⚠️ 部署前确保所有测试通过 ⚠️ 记录部署日志用于回滚

**使用示例:**

```bash
# 部署到开发环境
/deploy

# 部署到生产环境
/deploy prod

實戰示例2:資料庫遷移命令

建立.claude/commands/migrate.md:

---
description: 数据库迁移管理工具
usage: /migrate [action] [options]
parameters:
  - name: action
    description: 操作类型(create/up/down/status)
    required: true
  - name: options
    description: 额外选项
    required: false
---

# 数据库迁移命令

## 使用方法

### 创建新迁移
```bash
/migrate create add_users_table

执行:

1. 生成迁移文件
2. 添加时间戳
3. 打开编辑器供你编辑迁移内容

执行迁移

/migrate up

执行:

1. 检查待执行的迁移
2. 显示迁移预览
3. 要求确认
4. 执行迁移
5. 更新数据库版本

回滚迁移

/migrate down

执行:

1. 显示最近一次迁移
2. 要求确认
3. 执行回滚
4. 更新数据库版本

查看状态

/migrate status

显示:

• 当前数据库版本
• 待执行的迁移
• 已执行的迁移历史

安全检查

执行迁移前自动检查:

• 数据库连接正常
• 备份已完成(生产环境)
• 有足够的磁盘空间
• 没有长时间运行的查询

错误处理

如果迁移失败:

1. 回滚所有更改
2. 显示详细错误信息
3. 保存日志到文件
4. 提供修复建议

### 實戰示例3:程式碼審查命令

建立`.claude/commands/review.md`:

```markdown
---
description: 智能代码审查助手
usage: /review [文件路径或分支]
tags:
  - code-quality
  - best-practices
---

# 代码审查命令

## 审查流程

### 1. 收集信息
- 如果指定了文件路径,审查该文件
- 如果指定了分支,审查与main的差异
- 如果没有参数,审查当前所有更改

### 2. 审查维度

**代码质量:**
- [ ] 代码可读性
- [ ] 命名规范
- [ ] 代码复杂度
- [ ] 重复代码

**最佳实践:**
- [ ] 设计模式应用
- [ ] 错误处理
- [ ] 资源管理
- [ ] 性能考虑

**安全性:**
- [ ] SQL注入风险
- [ ] XSS漏洞
- [ ] 敏感信息泄露
- [ ] 权限检查

**测试:**
- [ ] 单元测试覆盖
- [ ] 边界条件
- [ ] 错误场景

### 3. 输出格式

```markdown
## 程式碼審查報告

### 總體評分: ⭐⭐⭐⭐☆ (4/5)

### 發現的問題

#### 🔴 嚴重問題(1)
1. **SQL隱碼攻擊風險** - `src/user.js:45`
   - 使用字串拼接構建SQL查詢
   - 建議:使用引數化查詢

#### 🟡 警告(2)
1. **缺少錯誤處理** - `src/api.js:23`
2. **未使用的變數** - `src/utils.js:12`

#### 🟢 建議(3)
1. 可以使用可選鏈簡化程式碼
2. 建議提取常量
3. 新增JSDoc註釋

### 優點
✅ 良好的程式碼組織
✅ 適當的註釋
✅ 一致的程式碼風格

### 改進建議
- 增加單元測試覆蓋率到80%以上
- 使用ESLint規則自動檢測問題
- 新增pre-commit hook

4. 自动修复

对于简单的问题(如格式化、未使用导入),自动修复:

eslint --fix [檔案]

5. 生成报告

将审查报告保存到文件:

/review > code-review-$(date +%Y%m%d).md

## SubAgent開發

SubAgent是專注於特定任務的AI代理,它們擁有專門的指令集,可以處理特定領域的複雜任務。

### SubAgent基本結構

建立`.claude/agents/code-reviewer.md`:

```markdown
---
name: code-reviewer
description: 专业代码审查代理
version: 1.0.0
---

# 代码审查专家

你是一位资深的代码审查专家,拥有15年软件工程经验。

## 你的专长
- 多种编程语言(Python, JavaScript, TypeScript, Java, Go)
- 代码质量最佳实践
- 安全漏洞检测
- 性能优化
- 设计模式
- Clean Code原则

## 审查原则
1. **建设性反馈**: 指出问题的同时提供解决方案
2. **上下文感知**: 考虑项目的编码规范和团队习惯
3. **优先级排序**: 优先标记严重问题和安全隐患
4. **教育导向**: 解释为什么某个做法有问题,帮助开发者成长

## 审查流程

### 第一阶段:快速扫描
1. 检查明显的语法错误
2. 识别代码异味(code smells)
3. 标注潜在的安全问题

### 第二阶段:深度分析
1. 分析代码复杂度
2. 评估性能影响
3. 检查错误处理
4. 验证边界条件

### 第三阶段:建议优化
1. 提出重构建议
2. 推荐最佳实践
3. 建议测试策略
4. 文档改进建议

## 输出格式

始终使用结构化的审查报告:

```markdown
## 📊 程式碼審查報告

**檔案**: [檔案路徑]
**作者**: [提交者]
**日期**: [審查日期]

### 🎯 總體評估
- 程式碼質量: ⭐⭐⭐⭐☆
- 可維護性: ⭐⭐⭐☆☆
- 安全性: ⭐⭐⭐⭐☆
- 效能: ⭐⭐⭐⭐☆

### 🔴 必須修復的問題
...

### 🟡 建議改進
...

### 🟢 優點
...

### 📚 學習資源
...

特殊关注点

安全问题

• SQL注入
• XSS攻击
• CSRF保护
• 敏感数据泄露
• 认证/授权缺陷

性能问题

• N+1查询
• 内存泄漏
• 不必要的循环
• 缺少缓存
• 大文件处理

可维护性

• 代码重复
• 过长函数
• 深层嵌套
• 魔法数字
• 缺少注释

交互风格

• 使用友好、鼓励的语气
• 提供具体的代码示例
• 解释"为什么"而不仅仅是"是什么"
• 承认代码的好的部分
• 在批评之前先理解上下文

### 呼叫SubAgent

在Claude Code中,你可以這樣呼叫SubAgent:

```bash
# 让code-reviewer代理审查文件
@code-reviewer 请审查 src/user.js 文件

# 审查整个PR
@code-reviewer 请审查 feature/new-auth 分支的所有更改

# 针对性审查
@code-reviewer 请关注安全性问题,审查 src/auth/ 目录

實戰示例:效能最佳化專家

建立.claude/agents/performance-expert.md:

---
name: performance-expert
description: 性能优化专家代理
version: 1.0.0
---

# 性能优化专家

你是一位性能优化专家,擅长识别和解决各种性能瓶颈。

## 专长领域
- 前端性能(渲染优化、资源加载)
- 后端性能(API响应时间、数据库查询)
- 算法优化(时间复杂度、空间复杂度)
- 缓存策略(浏览器缓存、CDN、Redis)
- 并发处理(异步操作、线程池)

## 分析框架

### 前端性能
```javascript
// 檢查清單
1. 資源載入
   - [ ] 圖片懶載入
   - [ ] 程式碼分割
   - [ ] Tree shaking
   - [ ] Gzip壓縮

2. 渲染最佳化
   - [ ] 虛擬滾動(長列表)
   - [ ] 防抖/節流
   - [ ] 避免強制同步佈局
   - [ ] 使用CSS transforms動畫

3. 記憶體管理
   - [ ] 事件監聽器清理
   - [ ] 定時器清除
   - [ ] 避免記憶體洩漏

后端性能

// 檢查清單
1. 資料庫最佳化
   - [ ] 索引最佳化
   - [ ] 查詢最佳化(避免N+1)
   - [ ] 連線池配置
   - [ ] 慢查詢監控

2. 快取策略
   - [ ] Redis快取熱點資料
   - [ ] CDN快取靜態資源
   - [ ] 瀏覽器快取策略
   - [ ] 查詢結果快取

3. 併發處理
   - [ ] 非同步I/O
   - [ ] 執行緒池/協程池
   - [ ] 批次處理
   - [ ] 請求合併

算法优化

// 分析維度
1. 時間複雜度
   - O(1): 雜湊表查詢
   - O(log n): 二分查詢
   - O(n): 線性遍歷
   - O(n log n): 排序演算法
   - O(n²): 巢狀迴圈(需要最佳化)

2. 空間複雜度
   - 避免不必要的資料複製
   - 使用生成器處理大資料
   - 及時釋放大物件

性能分析流程

步骤1:性能剖析

运行性能分析工具:

# Node.js
node --prof app.js
node --prof-process isolate-*.log > profile.txt

# 前端
# 使用Chrome DevTools Performance面板

# 資料庫
EXPLAIN ANALYZE [查詢]

步骤2:瓶颈识别

找出:

• 最慢的函数/方法
• 最耗时的查询
• 频繁调用的代码
• 内存占用高的地方

步骤3:优化实施

按优先级实施优化:

1. 高优先级:影响大,改动小
2. 中优先级:影响中等,改动中等
3. 低优先级:影响小,改动大

步骤4:效果验证

对比优化前后的性能指标:

• 响应时间
• 吞吐量
• 内存使用
• CPU使用率

常见优化模式

模式1:缓存结果

// 最佳化前
function getUser(id) {
  return database.query(`SELECT * FROM users WHERE id = ${id}`);
}

// 最佳化後
const cache = new Map();
function getUser(id) {
  if (cache.has(id)) {
    return cache.get(id);
  }
  const user = database.query(`SELECT * FROM users WHERE id = ${id}`);
  cache.set(id, user);
  return user;
}

模式2:批量处理

// 最佳化前
for (const id of userIds) {
  const user = await getUser(id);
  // 處理使用者
}

// 最佳化後
const users = await getUsers(userIds); // 批次查詢
for (const user of users) {
  // 處理使用者
}

模式3:惰性加载

// 最佳化前
const data = loadHugeData(); // 啟動時載入所有資料

// 最佳化後
function getData() {
  if (!data) {
    data = loadHugeData(); // 首次使用時才載入
  }
  return data;
}

输出格式

## 🚀 效能最佳化報告

### 📊 當前效能指標
- API響應時間: 850ms
- 資料庫查詢時間: 620ms
- 記憶體使用: 512MB
- CPU使用率: 75%

### 🔍 發現的瓶頸

#### 🔴 嚴重瓶頸(2)
1. **N+1查詢問題** - `UserService.js:45`
   - 影響:每次請求執行1000次資料庫查詢
   - 建議:使用JOIN或批次查詢
   - 預期提升:響應時間減少80%

2. **缺少快取** - `ProductController.js:23`
   - 影響:熱門商品每次都查詢資料庫
   - 建議:使用Redis快取,設定5分鐘過期
   - 預期提升:資料庫負載降低90%

#### 🟡 中等瓶頸(3)
...

### ✅ 最佳化建議(按優先順序排序)

#### 優先順序1:解決N+1查詢
```javascript
// 当前代码
for (const orderId of orders) {
  const items = await db.query(
    `SELECT * FROM items WHERE order_id = ${orderId}`
  );
}

// 优化后
const items = await db.query(`
  SELECT * FROM items
  WHERE order_id IN (${orders.join(',')})
`);

預期提升:響應時間從850ms降至170ms

優先順序2:新增Redis快取

...

📈 預期收益

實施所有高優先順序最佳化後:

• API響應時間: 850ms → 170ms (減少80%)
• 資料庫查詢: 1000次 → 2次 (減少99.8%)
• 吞吐量: 12 req/s → 60 req/s (增加400%)

🔄 持續監控

建議設定以下監控指標:

• p50/p95/p99響應時間
• 錯誤率
• 資料庫連線池使用率
• Redis快取命中率

## 性能测试命令

```bash
# API效能測試
ab -n 1000 -c 10 http://localhost:3000/api/users

# 資料庫效能測試
pgbench -c 10 -j 2 -t 1000 mydb

# 前端效能測試
lighthouse http://localhost:3000 --view

## Hooks開發

Hooks允許你在特定事件發生時自動執行指令碼,實現自動化工作流。

### Hooks型別

Claude Code支援以下Hooks:

| Hook名稱 | 觸發時機 | 用途示例 |
|---------|---------|---------|
| `pre-commit` | Git提交前 | 執行測試、lint檢查 |
| `post-commit` | Git提交後 | 傳送通知、更新文件 |
| `pre-push` | Git推送前 | 執行完整測試套件 |
| `post-push` | Git推送後 | 通知團隊、部署 |
| `pre-edit` | 檔案編輯前 | 備份檔案 |
| `post-edit` | 檔案編輯後 | 格式化程式碼 |
| `on-error` | 命令失敗時 | 記錄錯誤、傳送告警 |

### 建立Hook:pre-commit

建立`.claude/hooks/pre-commit.sh`:

```bash
#!/bin/bash
# Pre-commit hook: 在提交前自动检查代码质量

set -e  # 遇到错误立即退出

echo "🔍 运行pre-commit检查..."

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# 1. 检查是否有未完成的TODO
echo "📝 检查TODO注释..."
if git diff --cached | grep -i "TODO" > /dev/null; then
    echo -e "${YELLOW}⚠️  警告: 代码中包含TODO注释${NC}"
    echo "请确认是否继续提交"
    read -p "按Enter继续,Ctrl+C取消"
fi

# 2. 运行ESLint
echo "🔎 运行ESLint..."
if command -v eslint &> /dev/null; then
    # 只检查暂存的文件
    FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.js$\|\.jsx$' || true)
    if [ -n "$FILES" ]; then
        eslint $FILES
        echo -e "${GREEN}✅ ESLint检查通过${NC}"
    fi
fi

# 3. 运行TypeScript类型检查
echo "🔬 运行TypeScript类型检查..."
if command -v tsc &> /dev/null; then
    tsc --noEmit
    echo -e "${GREEN}✅ TypeScript类型检查通过${NC}"
fi

# 4. 运行单元测试
echo "🧪 运行单元测试..."
if [ -f "package.json" ] && grep -q "test" package.json; then
    npm test -- --passWithNoTests
    echo -e "${GREEN}✅ 测试通过${NC}"
fi

# 5. 检查文件大小
echo "📏 检查文件大小..."
MAX_SIZE=102400  # 100KB
FILES=$(git diff --cached --name-only | grep '\.js$\|\.jsx$\|\.ts$\|\.tsx$' || true)
for FILE in $FILES; do
    if [ -f "$FILE" ]; then
        SIZE=$(stat -f%z "$FILE" 2>/dev/null || stat -c%s "$FILE" 2>/dev/null || echo 0)
        if [ $SIZE -gt $MAX_SIZE ]; then
            echo -e "${YELLOW}⚠️  警告: $FILE 文件大小超过100KB${NC}"
        fi
    fi
done

# 6. 检查敏感信息
echo "🔒 检查敏感信息..."
SENSITIVE_PATTERNS=(
    "password.*=.*['\"].*['\"]"
    "api_key.*=.*['\"].*['\"]"
    "secret.*=.*['\"].*['\"]"
    "token.*=.*['\"].*['\"]"
)

for PATTERN in "${SENSITIVE_PATTERNS[@]}"; do
    if git diff --cached | grep -iE "$PATTERN" > /dev/null; then
        echo -e "${RED}❌ 错误: 检测到可能的敏感信息!${NC}"
        echo "请移除密码、API密钥等敏感信息"
        exit 1
    fi
done

echo -e "${GREEN}✨ 所有检查通过!${NC}"
exit 0

設定可執行許可權:

chmod +x .claude/hooks/pre-commit.sh

建立Hook:post-commit

建立.claude/hooks/post-commit.sh:

#!/bin/bash
# Post-commit hook: 提交后执行的操作

echo "📝 提交完成!执行post-commit操作..."

# 1. 显示提交信息
echo "📄 最新提交:"
git log -1 --pretty=format:"%h - %s (%an, %ar)" HEAD

# 2. 统计本次提交
echo "📊 提交统计:"
git diff --stat HEAD~1 HEAD

# 3. 更新CHANGELOG(可选)
if command -v conventional-changelog &> /dev/null; then
    echo "📝 更新CHANGELOG..."
    conventional-changelog -p angular -i CHANGELOG.md -s
    git add CHANGELOG.md
fi

# 4. 发送桌面通知(仅macOS)
if [[ "$OSTYPE" == "darwin"* ]]; then
    commit_msg=$(git log -1 --pretty=%s HEAD)
    terminal-notifier -title "Git提交成功" -message "$commit_msg" 2>/dev/null || true
fi

# 5. 记录提交日志
LOG_FILE=".claude/commits.log"
echo "[$(date '+%Y-%m-%d %H:%M:%S')] $(git log -1 --pretty=%H HEAD)" >> $LOG_FILE

echo "✅ Post-commit操作完成"

建立Hook:on-error

建立.claude/hooks/on-error.sh:

#!/bin/bash
# On-error hook: 当命令失败时执行

echo "❌ 检测到错误!执行错误处理..."

ERROR_LOG=".claude/errors.log"
ERROR_TIME=$(date '+%Y-%m-%d %H:%M:%S')

# 记录错误
echo "[$ERROR_TIME] 命令失败" >> $ERROR_LOG
echo "工作目录: $(pwd)" >> $ERROR_LOG
echo "Git状态:" >> $ERROR_LOG
git status -s >> $ERROR_LOG
echo "---" >> $ERROR_LOG

# 发送通知
if command -v terminal-notifier &> /dev/null; then
    terminal-notifier -title "Claude Code错误" \
                      -message "命令执行失败,请检查日志" \
                      -sound default 2>/dev/null || true
fi

# 自动创建问题报告
REPORT_FILE=".claude/error-report-$(date +%Y%m%d-%H%M%S).md"
cat > $REPORT_FILE << EOF
# 错误报告

**时间**: $ERROR_TIME
**项目**: $(basename $(pwd))
**分支**: $(git branch --show-current)

## 环境信息
\`\`\`
Node.js: $(node --version 2>/dev/null || echo "未安装")
npm: $(npm --version 2>/dev/null || echo "未安装")
OS: $(uname -s) $(uname -r)
\`\`\`

## Git状态
\`\`\`
$(git status -s)
\`\`\`

## 最近提交
\`\`\`
$(git log -3 --oneline)
\`\`\`

## 系统日志
请查看: \`$ERROR_LOG\`

## 下一步
1. 检查错误日志
2. 查看Git状态
3. 尝试撤销操作: \`git reset --soft HEAD~1\`
EOF

echo "📄 错误报告已生成: $REPORT_FILE"

註冊Hooks

在plugin.json中註冊hooks:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "hooks": {
    "pre-commit": ".claude/hooks/pre-commit.sh",
    "post-commit": ".claude/hooks/post-commit.sh",
    "on-error": ".claude/hooks/on-error.sh"
  }
}

外掛除錯技巧

1. 啟用除錯模式

# 启动Claude Code时启用详细日志
CLAUDE_DEBUG=1 claude

# 或者设置环境变量
export CLAUDE_DEBUG=1
claude

2. 測試單個命令

# 直接测试命令文件
claude --command .claude/commands/deploy.md

# 查看命令解析结果
claude --parse .claude/commands/deploy.md

3. 驗證外掛清單

# 验证plugin.json语法
cat .claude/plugin.json | jq .

# 检查插件完整性
claude --validate-plugin

4. 除錯Hooks

# 手动运行hook测试
.claude/hooks/pre-commit.sh

# 查看hook输出
bash -x .claude/hooks/pre-commit.sh

# 测试hook是否被调用
echo "测试pre-commit" > test.txt
git add test.txt
git commit -m "test"  # 应该触发pre-commit hook

5. 檢視日誌

# Claude Code日志位置
~/.claude/logs/

# 查看最新日志
tail -f ~/.claude/logs/claude-code.log

# 搜索错误
grep "ERROR" ~/.claude/logs/claude-code.log

6. 使用除錯輸出

在命令檔案中新增除錯資訊:

---
description: 调试示例命令
---

# 调试命令

## 调试信息
当前时间: \`$(date)\`
当前目录: \`$(pwd)\`
用户: \`$(whoami)\`

## 执行步骤
1. 第一步...
2. 第二步...

---
**调试提示**: 查看详细日志请运行 \`tail -f ~/.claude/logs/*.log\`
---

外掛釋出和分享

1. 準備釋出

完善README.md:

# My Claude Code Plugin

## 简介
这个插件提供了XXX功能,帮助您...

## 安装

\`\`\`bash
# 方法1: 从GitHub安装
claude plugin install username/my-claude-plugin

# 方法2: 从本地安装
claude plugin install ./my-claude-plugin

# 方法3: 从URL安装
claude plugin install https://github.com/username/my-claude-plugin
\`\`\`

## 功能

### 命令
- \`/hello\`: 打招呼
- \`/deploy\`: 部署应用
- \`/review\`: 代码审查

### SubAgents
- \`@code-reviewer\`: 代码审查专家
- \`@performance-expert\`: 性能优化专家

### Hooks
- \`pre-commit\`: 提交前检查
- \`post-commit\`: 提交后通知

## 使用示例

\`\`\`bash
# 使用deploy命令
claude
/deploy prod

# 调用code-reviewer
@code-reviewer 请审查 src/user.js
\`\`\`

## 配置

插件支持以下配置选项:

\`\`\`json
{
  "deploy": {
    "defaultEnv": "dev",
    "autoConfirm": false
  },
  "review": {
    "strictMode": true,
    "maxComplexity": 10
  }
}
\`\`\`

## 开发

\`\`\`bash
# 克隆仓库
git clone https://github.com/username/my-claude-plugin.git
cd my-claude-plugin

# 安装依赖
npm install

# 运行测试
npm test

# 本地测试
claude --plugin ./
\`\`\`

## 贡献

欢迎提交Issue和Pull Request!

## 许可证

MIT License

建立CHANGELOG.md:

# 更新日志

## [1.0.0] - 2025-01-15

### 新增
- 添加deploy命令
- 添加review命令
- 添加code-reviewer SubAgent
- 添加pre-commit和post-commit hooks

### 改进
- 优化错误处理
- 改进日志输出

### 修复
- 修复hook权限问题

2. 版本控制

使用語義化版本:

# 主版本.次版本.修订号
1.0.0  # 初始版本
1.1.0  # 添加新功能(向后兼容)
1.1.1  # Bug修复
2.0.0  # 重大变更(不向后兼容)

釋出新版本:

# 1. 更新版本号
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

# 2. 更新CHANGELOG.md
# 手动添加变更说明

# 3. 提交更改
git add .
git commit -m "chore: release v1.1.0"
git tag v1.1.0
git push origin main --tags

3. 釋出到GitHub

# 1. 创建GitHub仓库
gh repo create my-claude-plugin --public --description "My Claude Code Plugin"

# 2. 推送到GitHub
git remote add origin https://github.com/username/my-claude-plugin.git
git push -u origin main

# 3. 创建GitHub Release
gh release create v1.0.0 \
  --title "v1.0.0" \
  --notes "第一个正式版本"

4. 釋出到npm(可選)

如果你的外掛包含Node.js依賴,可以釋出到npm:

# 登录npm
npm login

# 发布包
npm publish

# 查看已发布的包
npm view my-claude-plugin

5. 分享外掛

方式1: GitHub連結

# 用户可以通过GitHub链接安装
claude plugin install https://github.com/username/my-claude-plugin

方式2: 直接目錄

# 用户克隆后本地安装
git clone https://github.com/username/my-claude-plugin.git
cd my-claude-plugin
claude plugin install ./

方式3: 團隊共享

# 将插件放在团队共享的Git仓库中
# 在项目CLAUDE.md中添加安装说明

實用技巧和最佳實踐

1. 命令設計原則

好的命令:

• ✅ 名稱簡短、易記(/deploy, /test)
• ✅ 功能單一、專注
• ✅ 有清晰的描述和用法示例
• ✅ 錯誤處理完善
• ✅ 提供進度反饋

不好的命令:

• ❌ 名稱過長(/deploy-to-production-server)
• ❌ 功能混雜(既部署又測試)
• ❌ 缺少使用說明
• ❌ 靜默失敗

2. SubAgent設計技巧

明確角色定位:

# ❌ 太宽泛
你是一个全栈开发工程师...

# ✅ 定位清晰
你是一位专注于React性能优化的前端专家...

提供上下文模板:

## 分析模板
1. 收集信息: [具体步骤]
2. 分析问题: [检查清单]
3. 提出方案: [决策树]
4. 验证结果: [测试方法]

結構化輸出:

## 📊 分析报告

### 问题诊断
...

### 解决方案
1. 方案A(推荐)
   - 优点:...
   - 缺点:...
   - 适用场景:...

2. 方案B
   - ...

3. Hook最佳實踐

快速失敗:

#!/bin/bash
set -e  # 遇到错误立即退出
set -u  # 使用未定义变量时报错
set -o pipefail  # 管道命令失败时退出

冪等性:

#!/bin/bash
# ✅ 好的设计: 可以多次运行
npm install  # 如果已安装会跳过

# ❌ 不好的设计: 不能重复运行
rm -rf node_modules
npm install

使用者友好:

#!/bin/bash
# 提供清晰的输出
echo "✅ 检查通过"
echo "⚠️  警告: ..."
echo "❌ 错误: ..."

# 允许用户跳过(对于非关键检查)
if [ "$SKIP_TESTS" = "true" ]; then
    echo "跳过测试(用户设置)"
    exit 0
fi

4. 效能最佳化

快取結果:

# 使用缓存避免重复计算
\`\`\`bash
# 检查缓存
CACHE_FILE=".claude/cache/deps.txt"
if [ -f "$CACHE_FILE" ] && [ $(find "$CACHE_FILE" -mtime -1) ]; then
    echo "使用缓存的依赖信息"
    cat "$CACHE_FILE"
    exit 0
fi

# 生成并缓存
npm list > "$CACHE_FILE"
\`\`\`

並行執行:

#!/bin/bash
# ✅ 并行执行(更快)
npm run lint &
LINT_PID=$!
npm run test &
TEST_PID=$!

wait $LINT_PID
wait $TEST_PID

# ❌ 串行执行(较慢)
npm run lint
npm run test

5. 錯誤處理

優雅降級:

# 当可选工具不可用时提供替代方案
\`\`\`bash
# 尝试使用jq格式化JSON
if command -v jq &> /dev/null; then
    echo '{"name": "value"}' | jq .
else
    echo '{"name": "value"}'  # 直接输出
fi
\`\`\`

詳細錯誤資訊:

## 错误处理

如果命令失败,请提供:
1. **错误消息**: 清晰描述问题
2. **原因分析**: 解释为什么失败
3. **解决方案**: 提供修复建议
4. **相关链接**: 指向文档或资源

示例:
\`\`\`
❌ 部署失败

错误: 无法连接到生产服务器

原因:
- 服务器可能正在维护
- 网络连接可能中断
- 认证凭据可能已过期

解决方案:
1. 检查网络连接: \`ping server.example.com\`
2. 验证认证: \`aws sts get-caller-identity\`
3. 查看服务器状态: https://status.example.com
4. 重试命令: /deploy prod

帮助文档: https://docs.example.com/deployment
\`\`\`

6. 文件和註釋

自文件化程式碼:

# 使用清晰的标题和结构
## 步骤1:环境检查
## 步骤2:运行测试
## 步骤3:部署

# 使用注释说明为什么这样做
# 使用Git而不是直接拷贝,以便保留历史
git clone $REPO_URL

# 设置超时避免长时间等待
timeout 300 npm test

示例驅動:

## 使用示例

### 基础用法
\`\`\`bash
/review
\`\`\`

### 高级用法
\`\`\`bash
# 审查特定文件
/review src/user.js

# 审查并生成报告
/review > report.md

# 审查并自动修复
/review --fix
\`\`\`

### 实际场景
\`\`\`bash
# 场景1: PR审查前
/review feature/new-auth

# 场景2: 每日代码质量检查
/review --daily

# 场景3: 性能问题排查
@performance-expert 分析 src/api.js 的性能瓶颈
\`\`\`

7. 團隊協作

統一配置:

// .claude/plugin.json
{
  "name": "team-standards",
  "version": "1.0.0",
  "config": {
    "lint": {
      "rules": ["airbnb", "plugin:react/recommended"],
      "autoFix": true
    },
    "test": {
      "framework": "jest",
      "coverage": 80
    }
  }
}

版本管理:

# 在README中说明兼容性
## 兼容性
- Claude Code: >= 1.0.0
- Node.js: >= 16.14.0
- macOS/Linux/Windows

## 版本策略
- 遵循语义化版本
- 主版本更新可能包含不兼容变更
- 建议使用固定版本号: `"version": "1.2.3"`

變更日誌:

# 保持详细的CHANGELOG.md
## [1.2.0] - 2025-01-20
### Added
- 新增--watch选项

### Changed
- 默认超时时间从30秒增加到60秒

### Deprecated
- --old-flag将在2.0.0中移除

### Fixed
- 修复Windows路径问题

### Security
- 更新依赖版本修复CVE-2025-1234

常見問題解答(FAQ)

Q1: 如何除錯命令沒有執行的問題?

A: 按以下步驟排查:

1. 檢查命令檔案路徑:

# 确认路径正确
cat .claude/plugin.json | grep commands

# 验证文件存在
ls -la .claude/commands/

2. 檢查命令檔案格式:

# 确保有YAML frontmatter
head -5 .claude/commands/mycommand.md

# 应该看到:
# ---
# description: 命令描述
# ---

3. 啟用除錯模式:

# 查看详细日志
CLAUDE_DEBUG=1 claude

# 尝试命令
/mycommand

4. 驗證命令語法:

# 检查Markdown语法
npx markdownlint .claude/commands/mycommand.md

Q2: Hook指令碼沒有被執行?

A: 檢查以下幾點:

1. 許可權問題:

# 确保脚本可执行
chmod +x .claude/hooks/*.sh

# 检查权限
ls -la .claude/hooks/

2. Shebang行:

# 必须有shebang
head -1 .claude/hooks/pre-commit.sh
# 应该是: #!/bin/bash 或 #!/bin/sh

3. 手動測試:

# 直接运行脚本
./.claude/hooks/pre-commit.sh

# 查看详细输出
bash -x .claude/hooks/pre-commit.sh

4. 註冊狀態:

# 检查plugin.json中的hooks配置
cat .claude/plugin.json | jq .hooks

Q3: 如何在命令中使用環境變數?

A: 有三種方式:

1. 在專案中定義:

# .env
DEPLOY_API_URL=https://api.example.com
DEPLOY_API_KEY=your_key_here

# 在命令中引用
\`\`\`bash
curl -H "Authorization: Bearer $DEPLOY_API_KEY" \
     $DEPLOY_API_URL/deploy
\`\`\`

2. 在命令檔案中動態獲取:

## 配置
API_URL: \`$(grep API_URL .env | cut -d= -f2)\`

3. 透過Claude Code環境:

# 在Claude Code启动时设置
export MY_PLUGIN_CONFIG=/path/to/config
claude

Q4: SubAgent無法正常工作?

A: 檢查以下幾點:

1. Agent定義完整性:

# 检查必须的字段
cat .claude/agents/myagent.md | head -10

# 应该包含:
# ---
# name: agent-name
# description: agent description
# version: 1.0.0
# ---

2. 呼叫語法:

# ✅ 正确
@code-reviewer 请审查这个文件

# ❌ 错误
@code_reviewer 请审查这个文件
@codeReviewer 请审查这个文件

3. Agent可見性:

# 列出所有可用的agents
claude --list-agents

# 验证你的agent在列表中

Q5: 如何處理跨平臺的路徑問題?

A: 使用跨平臺相容的方式:

#!/bin/bash
# ❌ 不好的方式(仅适用于特定平台)
DIR="/Users/username/project"

# ✅ 好的方式(跨平台)
PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"

# ✅ 或使用相对路径
SCRIPT_DIR="$(dirname "$0")"

# 对于文件操作,使用跨平台工具
if [[ "$OSTYPE" == "darwin"* ]]; then
    # macOS specific
    STAT_FORMAT="-f%z"
else
    # Linux
    STAT_FORMAT="-c%s"
fi

Q6: 外掛之間有衝突怎麼辦?

A: 按優先順序解決:

1. 檢查命令名稱:

# 列出所有命令
claude --list-commands

# 如果冲突,重命名你的命令
# 或者卸载冲突的插件

2. 名稱空間:

// 为命令添加前缀避免冲突
{
  "commands": [
    {
      "name": "myplugin:deploy",  // 添加前缀
      "description": "My plugin deploy"
    }
  ]
}

3. 載入順序:

# 插件按加载顺序,后加载的优先级更高
# 在~/.claude/plugins.json中调整顺序

Q7: 如何測試外掛的相容性?

A: 建立測試流程:

1. 多版本測試:

# 测试不同Claude Code版本
docker run claude:v1.0.0 claude --plugin ./
docker run claude:v1.1.0 claude --plugin ./

2. 環境測試:

# .github/workflows/test.yml
name: Test Plugin
on: [push, pull_request]
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [16.x, 18.x, 20.x]
    steps:
      - uses: actions/checkout@v2
      - name: Test plugin
        run: |
          npm install
          npm test

3. 整合測試:

# 创建测试项目
mkdir test-project
cd test-project
claude plugin install ../my-plugin
claude
/mycommand

Q8: 如何最佳化外掛效能?

A: 最佳化策略:

1. 懶載入:

// 只在需要时加载
{
  "commands": [
    {
      "name": "heavy-command",
      "lazy": true  // 延迟加载
    }
  ]
}

2. 快取:

# 缓存依赖结果
CACHE_DIR=".claude/cache"
CACHE_FILE="$CACHE_DIR/dependencies.json"

if [ -f "$CACHE_FILE" ]; then
    cat "$CACHE_FILE"
else
    npm list --json > "$CACHE_FILE"
    cat "$CACHE_FILE"
fi

3. 並行處理:

# 使用GNU parallel或xargs -P
find . -name "*.js" | parallel -j 4 eslint {}

總結

Claude Code外掛系統強大靈活,能顯著提升開發效率。透過本教程,你已經學會:

核心概念

• ✅ 外掛的基本組成(命令、SubAgent、Hooks)
• ✅ 外掛檔案結構和清單配置
• ✅ 開發環境搭建

實戰技能

• ✅ 建立Slash命令
• ✅ 開發專業SubAgent
• ✅ 編寫自動化Hooks
• ✅ 除錯和測試外掛

釋出分享

• ✅ 版本管理和釋出流程
• ✅ 文件編寫最佳實踐
• ✅ 團隊協作方法

最佳實踐

• ✅ 程式碼質量和效能最佳化
• ✅ 錯誤處理和使用者體驗
• ✅ 跨平臺相容性

下一步行動

1. 立即實踐

   • 為你的專案建立第一個外掛
   • 封裝常用命令和指令碼
   • 建立團隊外掛庫

2. 深入學習

   • 研究優秀開源外掛原始碼
   • 探索MCP整合高階用法
   • 學習更多Shell指令碼技巧

3. 社羣貢獻

   • 分享外掛到GitHub
   • 貢獻給Claude Code社羣
   • 幫助其他開發者

參考資源

官方文件:

• Claude Code官方文件
• 外掛開發指南
• MCP協議規範

社羣資源:

• Awesome Claude Code
• Claude Code外掛示例
• Claude Code中文社羣

相關教程:

• MCP整合完整指南
• Think模式深度解析
• 實戰案例：快速原型開發

---

Sources:

• Claude Code: Best practices for agentic coding
• Understanding Claude Code's Full Stack: MCP, Skills...
• Claude Code五件套一篇全解（Plugins/Skills/MCP/...）
• The Ultimate Claude Code Guide
• Awesome Claude Code
• Claude Code Cheatsheet
• Claude Code CLI Cheatsheet