· 约 8 分钟 · 2,977 字

CoPaw 插件系统

copawpluginarchitecturedevelopmenthookprovidermcp

CoPaw 插件系统

CoPaw 的插件机制允许通过 plugin.json + plugin.py 扩展 Agent 的能力。 插件可以注册钩子（hooks）、提供者（providers）、命令（commands）和 MCP 工具。

插件生命周期

加载 → 初始化 → 注册钩子 → 运行 → 卸载
 │        │           │
plugin.json  plugin.py   钩子在运行时被调用
被读取      被导入        (on_tool_call / on_message 等)

插件结构

~/.copaw/plugins/<plugin-name>/
├── plugin.json    # 元数据 + 注册信息
└── plugin.py      # Python 实现

plugin.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "插件说明",
  "author": "作者",
  "hooks": {
    "on_tool_call": "on_tool_call",
    "on_message": "on_message"
  },
  "providers": ["channel", "mcp", "tool"],
  "dependencies": ["kanban"],
  "commands": {
    "/mycommand": "handle_command"
  }
}
字段说明
hooks运行时钩子，值是 plugin.py 中的方法名
providers插件提供的服务类型
commands斜杠命令映射
dependencies依赖的其他插件

支持的钩子

钩子触发时机方法签名
on_tool_call每次工具调用前on_tool_call(tool_name, params) → 可修改参数
on_tool_result工具返回后on_tool_result(tool_name, params, result)
on_message收到用户消息on_message(message)
on_llm_callLLM 调用前on_llm_call(messages)
on_llm_resultLLM 返回后on_llm_result(messages, response)
on_session_start会话启动on_session_start()
on_session_end会话结束on_session_end()

Providers

Provider说明
channel注册频道适配器（如 dingtalk、discord）
mcp注册 MCP 客户端/服务端
tool注册内置工具

已安装插件

插件plugin.json 关键内容功能
brain-bridgehooks: on_tool_call → interceptor拦截工具调用，记录到 Brain 记忆
kanbanproviders: mcp + tool, commands: /kanbanSQLite 看板 + MCP Server
health-monitorhooks: on_session_start/end健康状态监控
hello-world示例插件演示插件开发基础
orchestratorhooks: on_session_start任务编排与调度

Kanban 插件（参考实现）

Kanban 是功能最完整的参考插件：

  • 数据层：SQLite（~/.copaw/kanban.db）
  • MCP Server：通过 Node.js 进程暴露 9+ Kanban 工具
  • Commands：/kanban 命令查看看板
  • 核心能力：任务状态机（triage→todo→ready→running→done→archived）、Claim 机制（15min TTL）、心跳续约、依赖图

参考：kanban-system

插件开发 SOP

详见「plugin-dev」技能文档（skills/plugin-dev/SKILL.md），核心步骤：

  1. 创建 ~/.copaw/plugins/<name>/ 目录
  2. 编写 plugin.json（hooks/providers/commands）
  3. 编写 plugin.py（实现钩子方法）
  4. 调试：查看 copaw.log
  5. 发布：分享 plugin.json 即可

与 MCP 的关系

插件和 MCP 是两种不同的扩展机制：

维度插件MCP
语言Python任意语言（stdio/HTTP）
部署本地文件系统本地进程或远程服务
粒度钩子 + 提供者工具列表
配置位置~/.copaw/plugins/config.json → mcp.clients
典型用途拦截工具调用、频道适配提供新工具给 LLM

两者可以配合使用：插件内启动 MCP Server，Kanban 插件正是这种模式。

相关页面

评论