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. 明确插件形态

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

形态	特征
纯工具插件	只注册 registerTool，AI 对话中自动调用（最常见）
带界面插件	额外实现 open() 弹独立窗口
事件驱动插件	ctx.events.on/emit：监听宿主生命周期（如关机前收尾）、与其他插件互通
动态上下文插件	ctx.registerPromptProvider：让昔涟主动感知实时状态（天气/日程/番茄钟），无需用户开口问
调用 LLM 的插件	manifest 声明 "deps": ["llm"]
渠道插件	ctx.registerChannelAdapter（进阶，先确认用户真的需要）
数据服务插件	deps 声明后经 ctx.deps 使用：secrets（密钥保管）、conversations（只读对话分页）、workspace（工作区只读绑定）、scheduler（自有定时任务）
语音输入插件	deps: ["speech-input"]：自带 ASR 模型，取独占语音租约后把识别文本提交进正常对话

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 等子进程；子进程要设超时并处理失败降级