PilotDeck插件开发完全指南：用plugin.json注册工具、Hook与自定义记忆存储

PilotDeck插件开发完全指南用plugin.json注册工具、Hook与自定义记忆存储【免费下载链接】PilotDeckTask-oriented AI Agent productivity platform项目地址: https://gitcode.com/OpenBMB/PilotDeckPilotDeck 是一个任务导向的 AI Agent 生产力平台而插件系统是它最强大的扩展入口只需一个plugin.json清单文件就能为 AI Agent 注册自定义工具、拦截生命周期事件的 Hook、接入本地 MCP 服务如本地语音转写、浏览器自动化甚至挂载自定义的记忆与数据后端。本文将带你从零搭建第一个插件并逐字段拆解清单写法全程不需要阅读核心源码。插件在 PilotDeck 中的工作原理PilotDeck 启动时会自动发现并加载插件目录中的插件整个流程可以概括为三步发现Discovery扫描全局目录~/.pilotdeck/plugins/或项目级.pilotdeck/plugins/每个插件就是一个独立文件夹解析Parse读取插件根目录的plugin.json清单校验并规范化字段详见 parsePluginManifest.ts注册Register根据清单声明把工具、Hook、命令、技能、MCP 服务器等贡献点挂到运行时上核心类型定义见 manifest.ts。清单结构非常简单唯一的必填项是name其余全部可选{ name: my-plugin, version: 1.0.0, description: 一句话说明插件做什么, hooks: hooks/hooks.json, commands: [commands/audit-report.md], skills: skills, mcpServers: { } }仓库中提供了一个开箱即用的产品级示例插件建议对照阅读products/_example/plugins/example-compliance/plugin.json。plugin.json 字段速查6 个能力一次讲清字段类型作用name字符串插件唯一标识必填version/description字符串版本号与说明便于管理hooks字符串或对象Hook 配置指向hooks.json或内联声明commands字符串 / 数组注册斜杠命令Markdown 文件skills字符串 / 数组挂载技能目录SKILL.mdmcpServers对象声明本插件携带的 MCP 服务器此外还支持agents子智能体、outputStyles输出风格、settings自定义配置参数可传递记忆后端地址等和marketplace市场来源引用等字段完整定义见 manifest.ts。用插件注册自定义工具MCP 服务器方式PilotDeck 内置了标准工具集定义见 ToolContribution.ts而插件向 Agent 注入新能力的主流方式是mcpServers声明一个本地 MCP 服务器——Agent 会自动把 MCP 暴露的能力当作工具调用。官方内置插件就是最佳范本FunASR 本地语音转写声明了一个按需启动的本地 MCP 运行时字段包含command、args、perSession每会话一个实例、callTimeoutMs等完整清单见 funasr/plugin.jsonbrowser-use 浏览器自动化通过 Playwright MCP 让 Agent 直接操控 Chromium清单见 browser-use/plugin.json。 小技巧清单中的__PILOTDECK_NODE_EXECUTABLE__、__PILOTDECK_PROJECT_ROOT__这类占位符会在加载时被替换为真实路径让你可以免配置地引用 PilotDeck 自带的 Node 运行时。Hook拦截 Agent 全生命周期的 25 事件这是插件系统最迷人的部分。Hook 允许你在 Agent 运行的任意节点执行副作用——审计日志、环境检查、通知推送……官方内置了 25 余个事件类型包括PreToolUse、PostToolUse、SessionStart、PermissionRequest、PreCompact、WorktreeCreate等完整列表定义在 events.ts。Hook 配置支持 5 种执行器类型定义见 settings.ts类型说明command执行 shell 命令bash / powershellprompt用小模型跑一段提示词并处理输出http向指定 URL 发送 HTTP 请求agent启动一个子 Agent 执行任务callback调用运行时注册的回调来看仓库里的合规审计示例hooks.json 在每次工具调用前PreToolUse把工具名和时间戳追加写入审计日志matcher字段支持按tool_name精确匹配。把它挂到plugin.json的hooks字段插件即生效。自定义记忆存储用 mcpServers settings 挂载数据后端如果你希望 Agent 的记忆、会话数据或知识库落到自定义存储本地数据库、向量库、私有服务推荐的组合拳是在mcpServers中声明一个指向你存储服务的 MCP 服务器参考 funasr/plugin.json 的写法perSession: true保证多会话隔离用settings字段携带存储地址、密钥引用等参数供你的 MCP 服务读取Agent 侧的记忆与上下文机制位于 src/context/memory/会通过工具调用自然地读写这些数据。这样你无需改动 PilotDeck 一行代码就完成了AI 记忆后端的替换。部署与验证3 步让插件生效官方产品定制模板给出了标准流程完整说明见 products/_example/README.md复制模板以products/_example/plugins/下的示例插件为起点改名为你的插件链接到插件目录全局生效用ln -s 插件目录 ~/.pilotdeck/plugins/name项目级生效则放到.pilotdeck/plugins/启动验证运行npm run serverPilotDeck 自动发现并加载插件用PreToolUseHook 打一行日志即可确认链路打通。新手常见坑一次列全❌忘了name字段清单解析会直接抛错插件静默失败❌hooks指向不存在的文件hooks既可内联对象也可指向hooks.json文件路径注意相对路径❌命令未加超时command型 Hook 建议设置timeout避免拖慢主流程✅先跑通示例照着 example-compliance 改一个最小插件再逐步加能力是最快的上手路径。从一份plugin.json到工具、Hook、记忆后端的完整闭环——PilotDeck 的插件机制正是这种小清单、大能力的设计哲学。打开 products/_example/ 动手复制一个插件目录你的第一个插件十分钟内就能跑起来 【免费下载链接】PilotDeckTask-oriented AI Agent productivity platform项目地址: https://gitcode.com/OpenBMB/PilotDeck创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考