朱潮 c7e9f305b7 feat: 实现 Claude Plugins 模式的 Hook 机制

- 新增 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>

2026-02-06 20:15:54 +08:00

3.5 KiB

Raw Blame History

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 格式

{
  "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 示例

#!/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 示例

#!/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 示例

#!/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())

使用场景

PrePrompt: 用户登录时自动加载其偏好设置、历史订单等
PostAgent: 记录对话分析数据，触发后续业务流程
PreSave: 敏感信息脱敏后再存储，如手机号、邮箱等

3.5 KiB Raw Blame History Unescape Escape