changan-su/forsion/forsion-plugin

Forsion 扩展开发

扩展默认按 bundle 发行：一个 Forsion 插件目录内嵌 UI / 引擎插件 / Agent / 技能 / Space，后续追加其他层无需迁移。四类单体形态仍支持，纯数据主题或 Space 可单独发行。先复制 `samples/` 中对应的官方模板再改。

⚠️ "插件"有两个互不相干的系统,先分清用户要哪个:

- 引擎插件(本技能 samples/forsion-sample-plugin):后端/Agent 层,tangu-plugin.json + activate(ctx),给模型加工具。

- Amadeus/Forsion 桌面插件:UI 层,manifest.json + 裸 main.js(宿主 new Function('ctx', code) 跑 —— 文件本身就是 `setup(ctx)` 的函数体,顶层直接 ctx.registerView(…);别包成 function setup(ctx) { … },没人调用它 = 零注册、零报错),加命令/斜杠项/视图/文件类型。桌面端 设置 → 插件 有一键脚手架(hello-amadeus);捆绑包模板的根即这一形态。

要"一套功能跨两层发行"(UI+工具+Agent+Space)时,用捆绑包把它们装进一个目录。

Reference files (read the one you need)

Read the matching references/ file before using an API listed below or following a section's reference:

• references/host-ui-mounts.md: 可复用 UI 组件：ctx.ui.mountChatBox; 原生 Markdown 编辑器 ctx.ui.mountMarkdownEditor(vault: true 接当前库双链); 只读 Markdown ctx.ui.mountMarkdown; 原生悬浮目录 ctx.ui.mountFloatingToc; View modes: ctx.ui.setViewModes; Tooltips and motion tokens: ctx.ui.attachTooltip; Selection bar: ctx.ui.mountSelectionBar and registerSelectionAction scopes; Host parts (dialogs, toolbar controls, menus, popovers, empty states, icons, view head, i18n, bare elements, failed mount card): ctx.ui.confirm / openDialog / mountControl / contextMenu / popover / mountEmptyState / mountWebCard / icon / setViewHead / mount, ctx.addStyle, ctx.i18n.define; Settings parts: ctx.ui.mountSettingsPage / mountSettingsItem; 白板层 ctx.ui.mountBoard / ctx.ui.boardToSvg; 仪表盘 ctx.dashboard; 原生多维表 ctx.table.mount
• references/tangu-host-apis.md: 当前模型与当前 Space:ctx.tangu; Agent 状态:agentStatus / subscribeAgentStatus; Agent 名册:agents; 开新对话:startChat; 把对话挂进自己的视图:mountChat; 新对话输入区:mountComposer; 正文 AI:ctx.tangu.complete 与 registerSelectionAction; 翻译:ctx.tangu.translate; 行内补全:ctx.tangu.fim; Agent Desk 伴随面:ctx.desk; 摘要栏插件卡:ctx.summary; 自动化规则播种:ctx.automation; agent 自建 Space 的数据:section ctx.agent
• references/plugin-skill-providers.md: engine ctx.registerSkillProvider for live external skills.
• references/plugin-model-providers.md: engine ctx.registerModelProvider for native single-inference sources.
• references/mini-panel.md: a Space's small floating window (mini in space.json)
• references/bundle-mcp-hooks.md: stdio MCP servers and observe-only hooks a bundle declares in its manifest
• references/note-editor-surfaces.md: 块表面 ctx.app.getPage / mountBlocks / insertMarkdown; ctx.registerEditorExtension / registerSettingsView / loadData / saveData / watchFile
• references/work-folder-migration.md: one-time upgrade of old plugin data into the working folder (Identity and destination; Request and result; Upgrade sequence; Acceptance cases; Ordinary writes after upgrade)

Troubleshooting an installed plugin: Space missing, view blank, "stopped working after an update" (2026-10-10)

When a user says a plugin's Space / view / command is gone, or that a plugin broke after updating the app or the plugin, run the checker first — before reading the code, and before asking the user for logs:

node "<Skill folder>/tools/check-plugin.mjs"                      # every plugin installed in ~/.forsion/plugins
node "<Skill folder>/tools/check-plugin.mjs" <plugin folder>      # one plugin, e.g. the project you are developing
node "<Skill folder>/tools/check-plugin.mjs" <plugin folder> --style   # also: its CSS against the host style contract (report only)

Then read references/troubleshooting.md: what each mark means, how the host hides a Space, the plugin-status UI command, and running without node on PATH. Do not send the user to the developer console or ask for logs before the checker and plugin-status have both come back without an answer. Plugin authors: run the same checker before every release.

Verify a desktop plugin in the plugin sandbox before installing it (2026-10-23+)

When plugin_sandbox is in your tool catalog (the desktop app, a work session on this computer), verify every desktop plugin you write there before you tell the user it works, and never install it into their Forsion yourself:

1. plugin_sandbox {"action":"start","path":"<plugin folder with manifest.json>"} (relative paths resolve against the working folder). You get the load status (registered views, hidden Spaces, setup error, mount errors, the plugin's own console) and a screenshot of the sandbox window, with the plugin's first view open.
2. Fix what you see in the files. Saving reloads the sandbox by itself; look again with plugin_sandbox_inspect (status, screenshot with an optional view id, logs).
3. Exercise behaviour with plugin_sandbox_inspect {"action":"command","command":"<command id>","args":{...}}: it runs a command the plugin registered with ctx.registerCommand, passing args to run(args). Register the actions you need to test as commands.
4. Tell the user it is running in the sandbox. They can open the window from the sandbox card in the chat, try it, report a problem back to this chat, and install it with Install in my Forsion, which asks them first.

What the sandbox is: a separate Forsion with its own empty vault and data, signed out, without the Tangu engine, where only this plugin is loaded. So a bundle's engine half (plugins/, agents/, skills/), anything that needs a signed-in account or cloud sync, and plugins that declare fileExtensions (blocked for dev copies) cannot be verified there; say so and test those after the user installs. Only one sandbox runs at a time; reset wipes its data and starts fresh; stop closes it.

No plugin_sandbox (mobile, web, cloud sessions, older desktop builds)? Fall back to tools/check-plugin.mjs and ask the user to try it. Coding Studio's Sandbox panel also has a My Forsion tier: that one loads the dev copy into the user's real app and real notes and is not isolated.

通用纪律

1. 先有动机再做:每个扩展要能指回一条真实痛点,说不出就别做。
2. 注入模型的文本一律英文:工具 description、参数说明、promptSection —— 给模型读的全英文;用户可见字段用 name/nameEn、description/descriptionEn 双语镜像。
3. Stable English IDs: external plugin manifest IDs must match ^[a-z0-9][a-z0-9-]{0,63}$ (lowercase ASCII letters, digits and hyphens, 1–64 characters). Use an English name for new IDs; keep existing published IDs stable. Localized name / nameEn are display labels, never storage identities. Namespace command/slash/tool IDs because they share global registries; a theme ID is its data-theme value. Store installs use the host's immutable market-<UUID> effective ID; do not replace it with the manifest ID or rename historical install-folder aliases.
4. 交付=能跑+能回归:非平凡逻辑留一个 check.mjs(node check.mjs 一条命令),范式见 forsion-plugin-mindmap / activitywatch 的 check 模式。
5. 动作性能力住引擎侧,渲染端命令只做导航(2026-08-24 拍板):注册任何入口前先问一句——这是导航(开视图/切面板)还是动作(带参数、可 headless 完成的活,比如「分析这条链接」)?动作不要做成命令面板命令:Command.run(): void 类型上就没有参数位,而且命令表活在渲染进程,聊天 agent 与自动化都够不着。正确做法=把能力做成捆绑包的引擎侧资产,零通道基建。先选对形态:靠引擎已有工具就能复现的动作 → 包根 skills/<slug>/SKILL.md(全局技能,默认选它,进所有 agent 的技能目录,use_skill 直接用);要专属人设 / 独立上下文预算 / 稳定的自动化入口 → 才建 agents/<slug>/ 具名 agent(+ 它自己的 skills/),聊天 agent 经 delegate(agentSlug)、自动化经 agent_run 调用(⚠️agent_run 必须指名 agentSlug,只发全局技能的 bundle 靠被指名的那个 agent 身上带着这份技能来够到)。需要桌面主进程能力时引擎侧已有桥工具(如 transcribe_audio 语音转写)。范式=青鸟收藏夹:工作台 UI 归渲染端插件,分析管线归 bundle 内嵌的 bluebird agent+技能,两个入口(人点工作台 / agent 委派)共用同一条引擎管线。

Desktop plugin UI: use the host's parts (2026-10-29+)

A view that draws its own dropdowns, menus, dialogs or tab bars looks foreign in Forsion and stops following the user's theme, language, UI zoom and every later host fix. The host draws these for you: reach for a part first, and hand-draw only what no part covers (your content itself: rows, cards, charts, canvases).

Signatures and details: references/host-ui-mounts.md, section "Host parts" and the one for each mount. The bundle template's counter view (samples/forsion-sample-bundle/main.js) uses the parts; copy from it.

Check it. node tools/check-plugin.mjs <plugin folder> --style lists, under "UI parts", what the plugin still draws itself where a part exists, and plugin_sandbox adds the same list to every status it returns. It reports, never blocks: fix what you can and keep the rest only on purpose. A plugin whose UI is a web page in an iframe is still allowed (host tokens and theme don't reach it); mark that page's CSS lines /* forsion-style: off */.

样式契约:能依赖的宿主类名与 token(2026-10-26 起)

宿主把插件可以依赖的类名和 CSS 变量发布在 tools/plugin-contract.json(每个带用途,随 apiVersion 升级)。清单外的宿主类名 / 变量 随时可能改名或删掉:不报错,只是某天界面塌了或变了色。