用途:为 HeartReverie 的 manifest 驱动插件系统创建新插件,适用于用户想创建、添加、脚手架化或构建插件时。插件放在 plugins/<name>/,通过 plugin.json 声明能力。
主要能力与流程:先确定插件名称(kebab-case,须与目录名一致,不能含 ..、\0、/、\)、目录与用途;再按需求选择类型:prompt-only(仅向 LLM 系统提示注入文本)、full-stack(提示片段、后端钩子、前端渲染任意组合)、hook-only(仅后端生命周期钩子)、frontend-only(仅浏览器端渲染),不确定时让用户四选一。
清单:plugin.json 必填 name、displayName、version、description、type;displayName 是侧边栏与设置页标题显示的用户可见标签,缺失或空白会被拒绝加载。可选字段包括 promptFragments、frontendModule、backendModule、tags、promptStripTags、displayStripTags、hooks 等。新插件必须声明 hooks,需枚举 register() 中每个 hooks.register("<stage>", ...) 调用;加载器启动时比对清单与运行时注册,不一致会以 declaredOnly/registeredOnly 错误回滚,并支撑 Hook Inspector 页面与 deno task introspect:hooks。reads/writes 用于冲突检测(C1 两插件写同一字段;C2 读无写者)。完全省略 hooks 会进入 legacy 模式(无校验),仅用于迁移中无人维护的第三方插件。
提示片段:创建清单声明的 Markdown 文件,并在 system.md 相应位置加入 {{ variable_name }};优先级 10 开头、100 默认、800 强化、900 结尾。
标签:LLM 输出自定义 XML 标签时,将标签名加入 tags、promptStripTags(从 previousContext 剥离,避免回显给 LLM)、displayStripTags(从读者显示中剥离)。简单标签用纯文本,带属性标签用正则。
后端模块:导出 register({ hooks, logger, getSettings }),可另导出 registerRoutes(context) 在 /api/plugins/<name>/* 挂载自定义 HTTP 端点。代码风格 ESM、双引号、分号、async/await、JSDoc,钩子内用 context.logger ?? logger。
前端模块:register(hooks, context),可用 hooks.register 或别名 hooks.on,register 可为 async。多数阶段同步,action-button:click 为异步。共享工具在 /plugins/_shared/,用相对路径导入;同目录 .js 导入须在 manifest.frontendImports 声明,否则 404。前端为原生 ESM、单引号、无构建、无框架。
前端钩子阶段包括 frontend-render、chapter:render:after、chapter:dom:ready、chapter:dom:dispose、chat:send:before、notification、story:switch/chapter:change、action-button:click。浮动面板应挂载到 #plugin-panel-slot,并用 MutationObserver 在插槽重建时重挂。
操作按钮(可选):向主布局贡献按钮,点击派发 action-button:click,处理器通常调用 context.runPluginPrompt(...)。需确定按钮 id、label、visibleWhen、提示文件名、可选 appendTag。
限制:资料未提供安装命令、收费、价格、平台与效果信息;具体字段与完整示例需阅读 references/manifest-schema.md 与 references/hook-api.md。