夜雨聆风课程概述:从零开始掌握 Claude Code 插件开发
欢迎来到 Claude Code 插件开发实战教程!这门课程将带你从零开始,完整学习如何开发一个功能强大的 Claude Code 插件。
为什么学习 Claude Code 插件开发?
Claude Code 是 Anthropic 推出的 AI 编程助手工具,它不仅能帮你写代码,还支持通过插件扩展功能。开发 Claude Code 插件可以:
• 自动化重复任务:比如自动生成测试、格式化代码、部署应用 • 增强 AI 能力:给 Claude 添加"记忆",让它记住你之前的决策和解决方案 • 集成外部工具:连接数据库、调用 API、对接其他开发工具 • 提升开发效率:定制专属的编程辅助工具
本课程以 claude-mem 项目为实战案例,这是一个"跨会话持久化记忆"插件,能让 Claude 记住你在不同会话中做过的工作。
一、Claude Code 插件基础概念
1.1 什么是 Claude Code 插件?
Claude Code 插件是扩展 Claude Code 功能的机制,通过插件你可以:
1. 拦截 Claude 的操作:在 Claude 执行工具(如 Read、Write)前后插入自定义逻辑 2. 提供新技能:封装复杂操作序列,让 Claude 一键执行 3. 展示可视化界面:通过网页界面展示数据、统计、图表 4. 对接 AI 服务:调用 Claude Agent SDK、其他 AI API
1.2 插件的四大核心能力
Claude Code 插件通过四种方式扩展功能:
(1) Hooks - 生命周期拦截器
Hooks 是插件最核心的能力,可以在 Claude 的特定时机执行自定义代码:
• Setup:插件安装时执行(初始化、版本检查) • SessionStart:会话开始时执行(初始化会话数据) • UserPromptSubmit:用户输入提交前执行(预处理输入) • PreToolUse:工具调用前执行(拦截工具、注入上下文) • PostToolUse:工具调用后执行(捕获输出、记录数据) • Stop:会话结束时执行(总结会话、清理数据)
实际应用:claude-mem 使用 PostToolUse Hook 拦截 Claude 的工具输出,记录每一次操作。
(2) Skills - 可复用操作序列
Skills 是封装好的操作步骤,用户可以通过关键词触发或手动调用:
• HTTP Skill:调用 HTTP API 执行操作(如搜索历史记忆) • 编排 Skill:使用 AI 子代理执行复杂任务(如制定实现计划) • MCP Skill:调用 MCP Server 工具(如向量搜索)
实际应用:claude-mem 提供 mem-search Skill,用户说"搜索历史"就能查询过去的记录。
(3) UI - 可视化界面
插件可以提供 React 网页界面,展示数据、图表、交互控件:
• Viewer UI:React 应用,在浏览器中查看记忆数据 • 统计面板:展示会话数量、工具使用频率 • 时间线:按时间排列历史操作
实际应用:claude-mem 的 Viewer UI 在 http://127.0.0.1:37700/ 展示所有记忆。
(4) MCP Server - AI 工具集成
插件可以启动 MCP Server,为 Claude 提供新工具:
• 向量搜索工具:让 Claude 使用 Chroma 搜索 • 数据库工具:让 Claude 直接操作 SQLite • API 调用工具:封装外部 API 调用
实际应用:claude-mem 启动 MCP Server 提供 mcp-search 工具给 Claude 使用。
二、claude-mem 项目介绍 - 你的实战案例
2.1 项目目标:让 Claude 记住你做过什么
claude-mem 的核心目标是跨会话持久化记忆:
• 问题:每次重启 Claude Code,它都"忘记"你之前的会话 • 解决:自动记录每次操作,存储到本地数据库,下次会话自动注入历史信息 • 价值:Claude 能理解你的项目历史,提供更精准的建议
2.2 核心功能详解
功能 1:观察生成(Observation Generation)
每当 Claude 使用工具(Read、Write、Edit 等),PostToolUse Hook 拦截输出:
Claude 读取了 /src/app.ts
↓ [PostToolUse Hook]
claude-mem 拦截工具输出
↓ [Claude Agent SDK]
AI 生成一句话观察:"读取了 app.ts,包含 Router 配置"
↓ [存储]
SQLite + Chroma价值:压缩工具输出,用一句话记录关键信息。
功能 2:上下文注入(Context Injection)
当 Claude 下次读取文件时,PreToolUse Hook 查询历史:
Claude 要读取 /src/app.ts
↓ [PreToolUse Hook]
claude-mem 查询:"上次读过 app.ts 吗?"
↓ [Chroma 向量搜索]
找到相似文件:/src/utils.ts
↓ [SQLite 查询]
找到历史观察:"上次读取 app.ts 时,还修改了 config.ts"
↓ [注入到 Claude]
Claude 系统提示:"上次你读取 app.ts 时,还修改了 config.ts..."价值:Claude 看到历史信息,理解文件之间的关联。
功能 3:语义搜索(Semantic Search)
用户可以通过 Skill 搜索历史:
用户: "搜索之前做的配置修改"
↓ [mem-search Skill]
Chroma 向量搜索:"配置修改"
↓ [SQLite 关键词搜索]
返回历史观察:
- "修改了 config.ts,增加环境变量"
- "更新数据库配置,优化连接池"价值:快速找到过去的决策和解决方案。
2.3 技术栈全景
claude-mem 使用以下核心技术:
| Bun | ||
| SQLite | ||
| Chroma | ||
| React | ||
| Express | ||
| Claude Agent SDK |
三、开发环境准备 - 10分钟快速上手
3.1 克隆项目代码
首先克隆 claude-mem 项目到本地:
# 1. 克隆仓库
git clone https://github.com/thedotmack/claude-mem.git
# 2. 进入项目目录
cd claude-mem3.2 安装依赖
安装项目所需的依赖包:
# 1. 安装 npm 依赖
npm install
# 输出类似:
# added 500 packages in 30s依赖包括:
• @anthropic-ai/sdk:Claude Agent SDK• express:HTTP API 服务器• sqlite3:SQLite 数据库驱动• chromadb:Chroma 向量数据库客户端• react:UI 组件库
3.3 安装 Bun Runtime
Bun 是 claude-mem 的核心运行环境,比 Node.js 更快:
macOS/Linux 安装
curl -fsSL https://bun.sh/install | bashWindows 安装
powershell -c"irm bun.sh/install.ps1 | iex"验证安装:
bun --version
# 输出: 1.1.x 或更高版本3.4 安装 uv (可选,用于 Chroma)
Chroma 需要 Python 环境,uv 是快速的 Python 包管理器:
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"验证安装:
uv --version
# 输出: 0.x.x 或更高版本3.5 构建插件
运行构建命令,编译 TypeScript、打包 Worker、构建 UI:
npm run build-and-sync构建流程:
npm run build-and-sync
↓
1. 编译 TypeScript → JavaScript
↓
2. 打包 Worker Service → worker-service.cjs
↓
3. 构建 React UI → viewer.html
↓
4. 同步到 marketplace → ~/.claude/plugins/
↓
5. 重启 Worker 进程预期输出:
✓ TypeScript compiled
✓ Hooks built
✓ Viewer UI built
✓ Plugin synced to marketplace
✓ Worker restarted on port 377003.6 验证插件安装
检查插件是否成功安装到 Claude Code:
# 1. 查看 marketplace 目录
ls ~/.claude/plugins/marketplaces/thedotmack/
# 应该看到:
# hooks.json
# scripts/worker-service.cjs
# ui/viewer.html
# skills/mem-search/SKILL.md
# 2. 检查数据库文件
ls ~/.claude-mem/
# 应该看到:
# claude-mem.db (SQLite 数据库)
# chroma/ (Chroma 向量数据)
# logs/ (Worker 日志)
# settings.json (插件设置)四、项目结构概览 - 理解代码组织
4.1 核心目录结构
claude-mem 项目分为两大区域:
(1) plugin/ - 插件声明式配置
这是 Claude Code 加载的目录,包含:
plugin/
├─ hooks/
│ ├─ hooks.json # Claude Code Hook 配置
│ └─ codex-hooks.json # Codex CLI Hook 配置
├─ scripts/
│ ├─ bun-runner.js # Bun 进程管理器
│ ├─ worker-service.cjs # Worker HTTP API(编译后)
│ ├─ mcp-server.cjs # MCP Server(编译后)
│ └─ version-check.js # Setup Hook:版本检查
├─ skills/
│ ├─ mem-search/
│ │ └─ SKILL.md # 搜索历史 Skill
│ ├─ make-plan/
│ │ └─ SKILL.md # 创建计划 Skill
│ └─ do/
│ └─ SKILL.md # 执行计划 Skill
└─ ui/
└─ viewer.html # React UI(编译后)关键文件:
• hooks.json: 定义 6 个生命周期 Hook 的配置 • bun-runner.js: 启动 Bun Worker,处理 stdin/stdout • worker-service.cjs: Express HTTP API,处理 Hook 请求 • SKILL.md: Skill 的声明式配置,定义触发条件和执行逻辑
(2) src/ - 源代码实现
这是开发时的 TypeScript 源代码:
src/
├─ hooks/ # Hook 实现
│ ├─ session-start.ts # SessionStart Hook
│ ├─ pre-tool-use.ts # PreToolUse Hook
│ ├─ post-tool-use.ts # PostToolUse Hook
│ └─ stop.ts # Stop Hook
├─ services/ # 核心服务
│ ├─ worker-service.ts # Express HTTP API
│ ├─ sqlite/ # SQLite 数据库
│ ├─ sync/ # Chroma 同步
│ └─ sdk/ # Claude Agent SDK
├─ storage/ # 数据持久化
├─ ui/viewer/ # React UI 源代码
└─ utils/ # 工具函数4.2 关键文件详解
(1) hooks.json - Hook 配置文件
这是插件的核心配置,告诉 Claude Code 在什么时候执行什么命令:
{
"hooks":[
{
"lifecycle":"Setup",
"command":"node plugin/scripts/version-check.js",
"timeout":30000
},
{
"lifecycle":"SessionStart",
"command":"node plugin/scripts/bun-runner.js session-init",
"timeout":5000
},
{
"lifecycle":"PreToolUse",
"matcher":"Read",
"command":"node plugin/scripts/bun-runner.js file-context",
"timeout":10000
},
{
"lifecycle":"PostToolUse",
"command":"node plugin/scripts/bun-runner.js observation",
"timeout":15000
},
{
"lifecycle":"Stop",
"command":"node plugin/scripts/bun-runner.js summarize",
"timeout":20000
}
]
}字段解释:
• lifecycle: Hook 的生命周期阶段 • command: Hook 执行的命令 • matcher: 过滤条件(只拦截特定工具) • timeout: Hook 执行超时时间(毫秒)
(2) worker-service.ts - Worker HTTP API
这是核心 HTTP 服务,提供 API 供 Hook 调用:
// src/services/worker-service.ts
import express from'express';
const app = express();
const port = 37700; // Worker 默认端口
// API 路由
app.post('/api/session-init', handleSessionInit);
app.post('/api/observation', handleObservation);
app.post('/api/file-context', handleFileContext);
app.post('/api/summarize', handleSummarize);
app.get('/health', handleHealthCheck);
app.listen(port, () => {
console.log(`Worker running on port ${port}`);
});(3) SQLite Schema - 数据库结构
SQLite 存储会话和观察数据:
-- Sessions 表
CREATE TABLE sessions (
session_id TEXT PRIMARY KEY,
created_at TEXT,
ended_at TEXT,
summary TEXT
);
-- Observations 表
CREATE TABLE observations (
observation_id TEXT PRIMARY KEY,
session_id TEXT,
tool_name TEXT,
observation_text TEXT,
timestamp TEXT,
FOREIGN KEY (session_id) REFERENCES sessions(session_id)
);(4) SKILL.md - Skill 配置
定义 Skill 的触发条件和执行逻辑:
---
name: mem-search
description: Search past work and memories. Use when the user asks about history.
---
# Memory Search Skill
Search historical observations from previous sessions.
## API Endpoint
POST /api/search
## Input
{
"query": "关键词"
}
## Output
{
"results": [...]
}五、实践任务 - 亲手验证插件工作
任务 1:启动 Claude Code 并观察 Hook 触发
目标:验证插件正常工作,观察 Hook 的触发顺序。
步骤:
1. 启动 Claude Code
claude-code2. 执行一个简单操作
在 Claude Code 中输入:
请读取 package.json 文件3. 查看 Worker 日志
# 打开日志文件
tail -f ~/.claude-mem/logs/worker.log
# 应该看到类似的输出:
[SessionStart] Session initialized: abc-123
[PreToolUse] Intercepting Read tool: package.json
[PostToolUse] Observation queued: job_id=xxx
[Queue] Processing observation...
[Claude SDK] Generating observation...
[SQLite] Observation stored: "读取了 package.json,版本 13.3.0"
[Chroma] Observation indexed观察要点:
• SessionStart Hook 在会话开始时触发 • PreToolUse Hook 在 Read 工具调用前触发 • PostToolUse Hook 在 Read 工具调用后触发 • Worker 后台异步处理 observation 生成
任务 2:检查 SQLite 数据库
目标:查看插件存储的实际数据。
步骤:
1. 打开 SQLite 数据库
sqlite3 ~/.claude-mem/claude-mem.db2. 查询 sessions 表
SELECT*FROM sessions;
-- 输出类似:
session_id | created_at | ended_at | summary
abc-123|2026-05-28T10:00:00Z |NULL|NULL3. 查询 observations 表
SELECT observation_text, tool_name FROM observations LIMIT 5;
-- 输出类似:
observation_text | tool_name
读取了 package.json,版本 13.3.0| Read
修改了 README.md,添加了新章节 | Edit4. 退出 SQLite
.quit任务 3:使用 mem-search Skill
目标:体验 Skill 的自动触发和手动调用。
步骤:
1. 自动触发 Skill
在 Claude Code 中输入:
帮我搜索之前读取的文件Claude 应该自动识别关键词"搜索"、"之前",触发 mem-search Skill。
2. 手动调用 Skill
在 Claude Code 中输入:
/mem-search query="package.json"3. 查看返回结果
Claude 应该返回:
找到以下历史记录:
1. 2026-05-28: 读取了 package.json,版本 13.3.0
2. 2026-05-27: 修改了 package.json,增加了依赖任务 4:打开 Viewer UI
目标:查看插件的可视化界面。
步骤:
1. 浏览器访问
打开浏览器,访问:
http://127.0.0.1:37700/2. 查看 UI 组件
应该看到:
• 统计面板:显示 session 数量、observation 数量 • 观察列表:列出最近的观察记录 • 搜索框:输入关键词搜索历史
3. 检查端口
如果端口不是 37700,查看 Worker 日志找到实际端口:
grep "Worker running on port" ~/.claude-mem/logs/worker.log六、关键学习点总结
6.1 插件架构核心概念
(1) 声明式配置
插件通过 plugin/ 目录的 JSON/YAML 文件声明功能:
• hooks.json: 定义 Hook • SKILL.md: 定义 Skill • plugin.json: 描述插件元数据
优点:无需编写复杂代码,通过配置即可定义功能。
(2) 生命周期 Hook
6 个 Hook 在 Claude 的不同时机执行:
• Setup: 插件安装时 • SessionStart: 会话开始 • PreToolUse: 工具调用前 • PostToolUse: 工具调用后 • Stop: 会话结束
设计:Hook 同步执行,快速响应,调用 Worker 异步处理。
(3) Worker Service
Worker 是独立进程,提供 HTTP API:
• Express API: 处理 Hook 请求 • 异步队列: 后台处理耗时操作(AI 生成) • SQLite: 持久化数据 • Chroma: 向量索引
价值:Worker 让 Hook 不阻塞 Claude,实现异步处理。
(4) Skills 系统
Skill 是封装好的操作序列:
• HTTP Skill: 调用 Worker API • 编排 Skill: 使用 Agent tool 执行复杂任务 • 自动触发: 关键词匹配自动调用
优点:用户无需了解实现细节,通过关键词即可使用。
6.2 数据流概览
完整的数据流从 Hook 到存储再到注入:
[用户使用 Claude Code]
↓
[SessionStart Hook]
→ Worker 初始化 session
→ SQLite 存储 session_id
↓
[用户提问]
↓
[PreToolUse Hook]
→ Worker 查询 Chroma(相似文件)
→ Worker 查询 SQLite(历史观察)
→ 注入历史信息到 Claude 系统提示
↓
[Claude 执行工具]
↓
[PostToolUse Hook]
→ Worker 接收工具输出
→ 后台队列排队
→ Claude SDK 生成观察(一句话总结)
→ SQLite 存储 + Chroma 索引
↓
[会话继续...]
↓
[Stop Hook]
→ Worker 生成会话总结
→ SQLite 更新 session 结束时间关键点:
• Hook 是同步拦截点,快速响应 • Worker 是异步处理器,后台运行 • SQLite 持久化数据,Chroma 索引向量 • PreToolUse 是注入点,PostToolUse 是收集点
6.3 插件核心价值
(1) 持久化
插件让 Claude 的"记忆"跨会话保存:
• 下次会话,Claude 知道你之前做过什么 • 不需要重复解释项目背景
(2) 自动化
Hook 自动触发,无需手动调用:
• 每次工具调用都自动记录 • 用户无感知,不影响使用体验
(3) 检索
语义搜索而非关键词匹配:
• Chroma 向量搜索理解语义 • "修改了配置"能找到"编辑了 config.ts"
七、下一步学习计划
7.1 第二章预告
下一章将深入学习:
• 整体架构设计: 6 Hook + Worker + 数据流的完整视图 • Hook 时序: 每个 Hook 的触发时机和职责 • Worker API: Express HTTP API 的设计模式 • 数据流: 从 Hook 到 SQLite 到 Chroma 的完整路径
7.2 学习建议
对于初学者
• 先完成本章所有实践任务 • 理解 Hook、Worker、Skill 的基本概念 • 熟悉项目结构和关键文件 • 建立对插件的整体认知
对于有经验者
• 可以跳过部分基础讲解 • 直接阅读源代码深入理解 • 尝试修改配置文件实验功能 • 为下一步开发做准备
八、常见问题解答
Q1:Worker 端口是多少?
A: Worker 默认端口是 37700 + (uid % 100)。
• 查看实际端口: grep "Worker running on port" ~/.claude-mem/logs/worker.log• 自定义端口: 设置环境变量 CLAUDE_MEM_WORKER_PORT
Q2:插件不工作怎么办?
A: 检查以下步骤:
1. 确认已运行 npm run build-and-sync2. 查看 Worker 日志是否有错误 3. 检查 hooks.json 是否正确加载 4. 验证 SQLite 数据库文件存在
Q3:Chroma 为什么需要 Python?
A: Chroma 是 Python 编写的向量数据库。
• 安装 uv 会自动管理 Python 环境 • 如果不想安装 Chroma,插件仍可工作(仅缺少语义搜索)
Q4:如何卸载插件?
A: 删除 marketplace 目录:
rm -rf ~/.claude/plugins/marketplaces/thedotmack/Q5:如何调试插件?
A: 查看 Worker 日志:
tail -f ~/.claude-mem/logs/worker.log九、本章总结
本章建立了 Claude Code 插件的整体认知:
• 理解了插件的四大核心能力(Hook、Skill、UI、MCP) • 掌握了开发环境的搭建(克隆、安装、构建) • 了解了项目结构(plugin/ 和 src/) • 完成了实践任务(观察日志、检查数据库、使用 Skill) • 理解了数据流和核心价值
下一章:我们将深入学习整体架构设计,理解 6 Hook 的触发时序、Worker API 的设计模式、完整的数据流路径。这将为你后续开发打下坚实基础。
