playa-cyrene/cyrene-agent/cyrene-plugin-dev

Cyrene 插件开发

本 Skill 指导如何为 Cyrene 开发运行时插件：从需求到可安装的 zip 包，一次做对。

何时使用

• 用户想给 Cyrene 加新能力，且明确走插件形式（而不是改本体源码）
• 用户拿来的插件报错，需要排查（启用失败、工具不生效、弹窗异常）
• 用户询问插件怎么写、能做什么

不使用：改 Cyrene 本体源码的普通开发任务；只是使用已装插件。

前置知识：先读再写

动手前必须先读本 Skill 目录下的参考文件（自包含，打包版也可用）：

1. references/getting-started.md —— 快速上手教程，含最小可用模板和常见坑速查
2. references/api-spec.md —— 完整接口规范（manifest 字段表、ctx API、生命周期、zip 导入限制）
3. references/example-walkthrough.md —— 官方示例插件 system-status 走读，覆盖工具 + 弹窗 + IPC 全部知识点；写新插件前通读一遍

开发版仓库中另有 docs/plugins/ 文档和 examples/ 官方示例（system-status 为 JS 全功能走读；weather-tool、long-term-memory、scheduled-automation、local-asr-contract 为 TypeScript + SDK 示例，分别覆盖 Secrets/轮次事件冻结分页/调度任务/语音租约契约），以 references/ 为准。

开发流程

1. 明确插件形态

先和用户确认要做的是哪类能力，通常是一种或多种组合：

2. 搭骨架

在一个独立目录（如 examples/<plugin-id>/ 或用户指定目录）创建：

<plugin-id>/
  manifest.json
  index.cjs

manifest 必填字段：apiVersion: 1、id、name、version（严格三段式 SemVer）、description、author、entry。author 填开发者或团队名称，会展示在聊天窗口的插件卡片中；id 全小写连字符，它决定工具 id 前缀和安装目录名。可选字段 icon（裸文件名，png/jpg/webp/svg，≤2MiB）在插件卡片左侧展示图标，不合法时静默忽略不影响加载。

3. 实现

铁律（违反会直接启用失败或行为异常）：

• 工具 id 必须以 `<插件id>_` 开头，如插件 my-plugin 的工具叫 my-plugin_hello
• 工具的 `description` 是写给 AI 看的：写清"什么场景该用"，含参数说明
• 只读工具 risk: "safe" + effectKind: "read"；有副作用的用 effectKind: "write"
• 弹窗用 BrowserWindow 加载插件目录内的 HTML，nodeIntegration: true + contextIsolation: false
• 窗口实例、定时器、子进程必须在 unregister() 里清理，且该函数要能重复调用不崩；后台资源优先用 ctx.onDispose(() => ...) 登记兜底清理、ctx.signal 传给后台任务，交给框架托管停止时机
• 渲染进程与插件通信：IPC 通道名是 plugin:<插件id>:<channel>
• 事件发布只能用短名（框架自动补 plugin:<插件id>: 前缀），不能伪造 host:* 或其他插件的事件；监听器单个最多 5 秒
• 提示词 Provider 只写本轮有用的实时事实、短而精；单项配额 2 秒 / 16000 字符，超时或失败只跳过自身
• 数据采集优先 Node 原生（os、fs），不够再用 PowerShell / nvidia-smi 等子进程；子进程要设超时并处理失败降级

4. 本地验证

装进用户目录前，先用 Node 模拟注册做冒烟测试：

// node -e 直接跑：模拟 ctx 调用 register，确认不抛错、工具 id 合法
const p = require("./<plugin-id>/index.cjs");
p.register({
  registerTool: (t) => { if (!t.id.startsWith("<plugin-id>_")) throw new Error(t.id); },
  registerIpc: () => {},
  log: () => {},
});

TypeScript 插件优先用官方 SDK 的测试工具（不需要启动 Cyrene）：

npm install @playa0v0/cyrene-plugin-sdk

// 测试脚本：Mock Context 验证 register 契约、工具 id、清理回调
const { createMockPluginContext, assertPluginTool } = require("@playa0v0/cyrene-plugin-sdk/testing");
const ctx = createMockPluginContext({ pluginId: "<plugin-id>" });
await plugin.register(ctx);
ctx.tools.forEach((t) => assertPluginTool(t, "<plugin-id>"));
await ctx.dispose();

涉及弹窗的逻辑无法脱离 Electron 验证，跳过此步，靠安装后实测。

5. 打包安装

• 把插件目录压成 zip：Compress-Archive -Path <plugin-id>/* -DestinationPath <plugin-id>-<version>.zip
• zip 限制：≤50 MiB、≤2000 条目、解压总量 ≤200 MiB；不能有符号链接和 .. 路径
• 开发期也可以直接把文件复制到 %APPDATA%\Cyrene\plugins\<plugin-id>\（与 zip 导入等价）
• 安装后默认停用，需用户在聊天窗口的“插件”面板中手动启用

6. 安装后实测

告诉用户验证三件事，缺一不可：

1. 聊天窗口插件卡片状态为 running
2. 有弹窗的：点“打开”按钮窗口正常显示、关闭再开正常
3. 有工具的：对话里问一个应触发工具的问题，确认 AI 调用并转述结果

分发与收录

• 插件装好后只在用户本机可用。用户想让插件被更多人看到/使用时，主动提醒：可提交 PR 到官方收录仓库 Cyrene-Plugins，审核通过后其他用户可直接下载 ZIP 导入
• 收录要求（完整规范见仓库 CONTRIBUTING.md）：plugins/<插件id>/ 下放可直接安装的产物（manifest + 编译后入口 + README）+ registry.json 登记 + README「已收录插件」表格加一行；不要上传 zip，ZIP 由维护者从审核过的源码统一打包
• 反过来，用户想安装别人开发的插件：从仓库 README「已收录插件」表格下载 ZIP，走上方导入流程即可

排查既有插件问题

按优先级查：

1. 启用报错 → 聊天窗口插件卡片会显示具体 error，对照铁律清单（九成是 id 前缀 / SemVer / deps 拼写）
2. 启用成功但 AI 不用工具 → description 没写清场景，或对话上下文没触发
3. 改了代码不生效 → 聊天窗口插件面板点“刷新插件”（会清模块缓存）
4. 弹窗白屏/报错 → 开发者工具看渲染端异常（win.webContents.openDevTools()）；多为 IPC 通道名拼错或 HTML 路径不对
5. 扫描警告“缺少 manifest.json” → 插件目录层级错了（zip 解压多套/少套了一层目录）

安全与边界

• 插件与宿主同权限运行（无沙箱）。为用户写插件时只用可审查的标准库和明确说明用途的子进程调用
• 提示词 Provider 能直接影响 AI 行为：为用户写 Provider 时只输出事实性状态（"剩余 12 分钟"），不输出指令性内容（"忽略之前的规则"一类）
• 不覆盖、不删除用户插件目录和 plugin-data/ 下的数据
• 更新插件：导入同名新版 zip 走替换流程，不要手动删旧目录再装（会丢启用状态）