c7e9f305b7
- 新增 agent/plugin_hook_loader.py：支持通过 .claude-plugin/plugin.json 配置 hooks 和 mcpServers - 修改 agent/prompt_loader.py：集成 PrePrompt hooks，优先读取 skill MCP 配置 - 修改 routes/chat.py：添加 PostAgent 和 PreSave hooks - 修改 routes/skill_manager.py：优先从 plugin.json 读取 name/description，fallback 到 SKILL.md - 删除旧的 agent/skill_hook_loader.py - 新增示例 skill user-context-loader，演示完整的 hooks 用法 Hook 类型： - PrePrompt: 在 system_prompt 加载时注入内容 - PostAgent: 在 agent 执行后处理 - PreSave: 在消息保存前处理 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
154 lines
3.5 KiB
Markdown
154 lines
3.5 KiB
Markdown
# User Context Loader
|
||
|
||
用户上下文加载器示例 Skill，演示 Claude Plugins 模式的 hooks 机制。
|
||
|
||
## 功能说明
|
||
|
||
本 Skill 演示了三种 Hook 类型：
|
||
|
||
### PrePrompt Hook
|
||
在 system_prompt 加载时执行，动态注入用户上下文信息。
|
||
- 文件: `hooks/pre_prompt.py`
|
||
- 用途: 查询用户信息、偏好设置、历史记录等，注入到 prompt 中
|
||
|
||
### PostAgent Hook
|
||
在 agent 执行完成后执行，用于后处理。
|
||
- 文件: `hooks/post_agent.py`
|
||
- 用途: 记录分析数据、触发异步任务、发送通知等
|
||
|
||
### PreSave Hook
|
||
在消息保存前执行，用于内容处理。
|
||
- 文件: `hooks/pre_save.py`
|
||
- 用途: 内容过滤、敏感信息脱敏、格式转换等
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
user-context-loader/
|
||
├── README.md # Skill 说明文档
|
||
├── .claude-plugin/
|
||
│ └── plugin.json # Hook 和 MCP 配置文件
|
||
└── hooks/
|
||
├── pre_prompt.py # PrePrompt hook 脚本
|
||
├── post_agent.py # PostAgent hook 脚本
|
||
└── pre_save.py # PreSave hook 脚本
|
||
```
|
||
|
||
## plugin.json 格式
|
||
|
||
```json
|
||
{
|
||
"name": "user-context-loader",
|
||
"description": "用户上下文加载器示例 Skill",
|
||
"hooks": {
|
||
"PrePrompt": [
|
||
{
|
||
"type": "command",
|
||
"command": "python hooks/pre_prompt.py"
|
||
}
|
||
],
|
||
"PostAgent": [
|
||
{
|
||
"type": "command",
|
||
"command": "python hooks/post_agent.py"
|
||
}
|
||
],
|
||
"PreSave": [
|
||
{
|
||
"type": "command",
|
||
"command": "python hooks/pre_save.py"
|
||
}
|
||
]
|
||
},
|
||
"mcpServers": {
|
||
"server-name": {
|
||
"command": "node",
|
||
"args": ["path/to/server.js"],
|
||
"env": {
|
||
"API_KEY": "${API_KEY}"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Hook 脚本格式
|
||
|
||
Hook 脚本通过子进程执行，通过环境变量接收参数，通过 stdout 返回结果。
|
||
|
||
### 可用环境变量
|
||
|
||
| 环境变量 | 说明 | 适用于 |
|
||
|---------|------|--------|
|
||
| `BOT_ID` | Bot ID | 所有 hook |
|
||
| `USER_IDENTIFIER` | 用户标识 | 所有 hook |
|
||
| `SESSION_ID` | 会话 ID | 所有 hook |
|
||
| `LANGUAGE` | 语言代码 | 所有 hook |
|
||
| `HOOK_TYPE` | Hook 类型 | 所有 hook |
|
||
| `CONTENT` | 消息内容 | PreSave |
|
||
| `ROLE` | 消息角色 | PreSave |
|
||
| `RESPONSE` | Agent 响应 | PostAgent |
|
||
| `METADATA` | 元数据 JSON | PostAgent |
|
||
|
||
### PrePrompt 示例
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
import os
|
||
import sys
|
||
|
||
def main():
|
||
user_identifier = os.environ.get('USER_IDENTIFIER', '')
|
||
bot_id = os.environ.get('BOT_ID', '')
|
||
|
||
# 输出要注入到 prompt 中的内容
|
||
print(f"## User Context\n\n用户: {user_identifier}")
|
||
return 0
|
||
|
||
if __name__ == '__main__':
|
||
sys.exit(main())
|
||
```
|
||
|
||
### PreSave 示例
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
import os
|
||
import sys
|
||
|
||
def main():
|
||
content = os.environ.get('CONTENT', '')
|
||
|
||
# 处理内容并输出
|
||
print(content) # 输出处理后的内容
|
||
return 0
|
||
|
||
if __name__ == '__main__':
|
||
sys.exit(main())
|
||
```
|
||
|
||
### PostAgent 示例
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
import os
|
||
import sys
|
||
|
||
def main():
|
||
response = os.environ.get('RESPONSE', '')
|
||
session_id = os.environ.get('SESSION_ID', '')
|
||
|
||
# 记录日志（输出到 stderr）
|
||
print(f"Session {session_id}: Response length {len(response)}", file=sys.stderr)
|
||
return 0
|
||
|
||
if __name__ == '__main__':
|
||
sys.exit(main())
|
||
```
|
||
|
||
## 使用场景
|
||
|
||
1. **PrePrompt**: 用户登录时自动加载其偏好设置、历史订单等
|
||
2. **PostAgent**: 记录对话分析数据，触发后续业务流程
|
||
3. **PreSave**: 敏感信息脱敏后再存储，如手机号、邮箱等
|