Skip to main content

​
写一个插件

1

建目录与清单

清单是 .kova-plugin/plugin.json：
2

决定要做哪几层

skills/ 提供技能（agent 知道怎么做）， panels.json 注册面板（人能打开来用）， .mcp.json 贡献 MCP 服务器（agent 能调用）。 三层可以只做一层，也可以全做。
3

注册进市场

在 plugins/marketplace.json 里加一条，应用内的插件市场就能看到它。
4

构建产物并验证

面板 HTML 与内置 zip 是构建产物，不入库。 build:sidecar / test / smoke 会自动补齐缺失产物。
设计文档见仓库内 docs/plugin-system-design.md。

​
接一个 MCP 服务器

MCP 的接入设计见 docs/mcp-design.md。要点：
  • 多服务器连接池：多个 MCP 服务器并发连接，互不阻塞；
  • 配置双层合并：全局配置与工作区配置合并，工作区覆盖全局；
  • 输出防护：MCP 返回的内容视为不可信输入，注入内容会被隔离标记；
  • OAuth：支持需要授权的服务器；
  • 审批与审计：MCP 工具的调用与其他工具走同一套审批流程，并留下审计记录。
插件也可以通过清单里的 mcpServers 字段自带 MCP 服务器定义—— ui-design 就是这么做的，agent 因此能直接操作设计画布。

​
加一个技能

技能放在插件的 skills/ 目录，或由用户级配置提供。 技能是装进 agent 上下文的知识包，在设置 → 技能里装载与管理。 内置的 iOS / Material / 通用移动端设计规范就是以技能形式分发的， 可通过 use_skill 按需加载，而不是一次性全塞进上下文。

​
加一个内置工具

工具实现在 apps/sidecar/pi-agent/src/tools/，在 tools.ts 里注册。 新增工具时必须同时决定它的权限行为：
工具的”能不能用”由会话模式决定，“要不要问”由权限档位决定。 两者在 UI 上是分开的两个下拉。新增工具时要同时挂到正确的维度上， 否则会出现”在 plan 模式里居然能写文件”这类不一致。
修改权限枚举后记得同步更新 docs/permission-modes.md 里的枚举扩容检查表—— 那不是文档洁癖，是防止枚举与 UI 选项不同步。

​
NDJSON 协议与跨端契约

packages/pi-protocol 定义前后端共享的契约。 桌面前端、sidecar、移动端都从这里取类型。 改协议时改这里，不要在任何一端另写一份。
桌面宿主与 sidecar 之间的进程协议：一行一个 JSON 对象。 业务表的读写走 stdout 上的 host RPC， 所以日志与协议在通道上有明确区分。
同一个 sidecar 实例同时服务桌面直连与远程 /ws 连接， 所以任何改动都要考虑”多端同时在线”下的行为。

​
一键换品牌

这是模板仓库，换成自己的品牌：
覆盖品牌三形态（slug / Pascal / UPPER）、pi-desktop 内部 id、 Tauri 显示名与 bundle id、.kova-plugin 目录名等，改动前自动备份。
改名后记得同步更新 apps/desktop/src-tauri/tauri.dev.conf.json 里的 identifier——dev 与正式版靠它区分，靠脚本改容易漏。

下一步

怎么打包和发版。