CodeBuddy CLI 插件开发指南

一、插件是什么

插件（Plugin）是扩展 CodeBuddy Code 功能的机制。一句话理解：

把你写在项目 .codebuddy/ 目录里的自定义配置（技能、命令、钩子等），打包成一个带版本、可安装、可分享的标准包。

插件 vs 独立配置（怎么选）

💡 官方建议：先在 .codebuddy/ 快速迭代，需要共享时再转换为插件。

二、插件能包含的 6 类组件

三、标准目录结构

my-plugin/
├── .codebuddy-plugin/    # 元数据（必需），只放 plugin.json
│   └── plugin.json
├── commands/             # 斜杠命令（可选）
│   └── example.md
├── agents/               # 自定义代理（可选）
├── skills/               # 技能文件夹（可选）
│   └── code-review/
│       └── SKILL.md
├── hooks/                # 钩子配置（可选）
│   └── hooks.json
├── bin/                  # 插件启用时自动加入 PATH 的可执行文件（可选）
├── .mcp.json             # MCP 服务器配置（可选）
├── .lsp.json             # LSP 服务器配置（可选）
└── settings.json         # 插件默认设置（可选）

⚠️ 最常见的错误：commands/、agents/、skills/、hooks/ 这四个目录必须放在插件根目录，不能放进 .codebuddy-plugin/ 里面。

四、plugin.json（manifest）写法

位于 .codebuddy-plugin/plugin.json：

{
  "name": "my-plugin",
  "description": "插件描述（显示在插件管理器中）",
  "version": "1.0.0",
  "author": {
    "name": "作者名",
    "email": "author@example.com"
  },
  "homepage": "https://github.com/username/my-plugin",
  "repository": "https://github.com/username/my-plugin",
  "keywords": ["example"],
  "category": "开发工具",
  "commands": [],
  "agents": [],
  "skills": [],
  "hooks": "./hooks/hooks.json"
}

五、各组件开发要点

1. 技能（Skills）

• 每个技能是 skills/<技能名>/SKILL.md，文件夹名就是技能名
• Frontmatter 必填 name 和 description
• 加 disable-model-invocation: true 可以阻止模型自动调用
• 接收参数：用 $ARGUMENTS 占位符捕获用户输入，例如 /my-plugin:hello Alex

2. 斜杠命令（Commands）

• Markdown 文件，frontmatter 支持 description、argument-hint
• 注册后通过 /插件名:命令名 手动触发

3. 钩子（Hooks）

• 配置在 hooks/hooks.json，由事件触发
• 四种类型：command（执行命令）、prompt（小模型语义判定）、agent（subagent 验证）、http（POST/PUT/PATCH 到指定 URL）
• 插件 hooks 启用时与用户/项目级 hooks 合并（不是覆盖），且不受 allowUntrustedFrontmatterHooks 闸门约束
• 典型示例：PostToolUse 事件匹配 Write|Edit，用 jq 提取 file_path 后执行 npm run lint:fix

4. LSP 服务器（.lsp.json）

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": { ".go": "go" }
  }
}

• 限制：用户必须预装语言服务器二进制（如 gopls、pylsp、rust-analyzer）
• 建议：常见语言（TypeScript / Python / Rust 等）直接从市场安装预构建 LSP 插件，只为市场未覆盖的语言自建

5. 默认设置（settings.json）

• 目前仅支持 agent 键（激活插件中某个自定义代理为主线程）
• 优先级高于 plugin.json 中的 settings；未知键会被静默忽略

六、开发 → 测试 → 发布 全流程

前提条件：已安装并认证 CodeBuddy Code，且为最新版本（旧版本看不到 /plugin 命令）。

七、五分钟快速上手（官方示例流程）

# 1. 创建插件目录
mkdir my-first-plugin

# 2. 创建 manifest
#    my-first-plugin/.codebuddy-plugin/plugin.json

# 3. 创建第一个技能
#    my-first-plugin/skills/hello/SKILL.md

# 4. 启动并测试
codebuddy --plugin-dir ./my-first-plugin
# 在 CLI 中运行：/my-first-plugin:hello

# 5. 进阶：用 $ARGUMENTS 支持个性化参数
#    /my-first-plugin:hello Alex

八、从 .codebuddy/ 迁移为插件（4 步）

1. 创建 my-plugin/.codebuddy-plugin/plugin.json
2. 把 .codebuddy/ 下的 commands/、agents/、skills/ 复制到插件根目录
3. 把 settings.json 中的 hooks 对象复制到 hooks/hooks.json（格式相同）
4. 用 --plugin-dir 测试通过后，可删除原 .codebuddy/ 目录避免重复（插件版本优先）

九、最佳实践与安全提醒

开发建议

• 目录与命令统一用 kebab-case（短横线小写）命名
• 填写完整的 manifest 元数据
• 使用语义化版本号管理发布
• 写清晰的 README 文档
• 发布前务必本地测试，先让团队成员试用

安全注意（重要）

• ⚠️ 插件可以执行命令、访问文件系统，仅从可信来源安装
• 安装第三方插件前，先审查它的 commands 和 hooks 内容
• 通过权限系统限制插件的访问范围

故障排除速查表