{"slug":"plugin-workbench","title":"plugin-workbench","summary":"Create, implement, build, pack, install, reload, and manage Astravia desktop plugins for non-developers. Use whenever the user wants a Astravia plugin, plugin scaffolding, apply a `.astraviapkg` package to Astravia, edit plugin.json name/guidingWords, or debug plugin load/install","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-25T10:12:15.543489Z","repo":{"url":"https://github.com/maomaochong-ai/open-astravia","stars":53,"forks":25,"license":"Apache-2.0","updatedAt":"2026-11-13T19:28:52Z"},"bodyHtml":"<hr>\n<h2>name: plugin-workbench\ndescription: &gt;\nCreate, implement, build, pack, install, reload, and manage Astravia desktop plugins\nfor non-developers. Use whenever the user wants a Astravia plugin, plugin scaffolding,\napply a <code>.astraviapkg</code> package to Astravia, edit plugin.json name/guidingWords, or debug plugin load/install.\nRequires the Plugin Workbench input-bar toggle (hard isolation). The plugin handbook ships\ninside the project's own @astravia-org/plugin-sdk; locate it with the bundled CLI's docs command.</h2>\n<h1>制作插件（完整流水线）</h1>\n<p>面向<strong>不懂开发的用户</strong>：你读规范、写代码、跑标准脚本、装进本机；用户只回答问题与点确认。</p>\n<p><strong>质量底线</strong>：没有读过插件手册就动手写实现 = 禁止。凭记忆编造 SDK API 很容易装上不能用。</p>\n<hr>\n<h2>0. 解析工作台根目录（先做）</h2>\n<pre><code>workbenchRoot = listPlugins() 中 id === \"plugin-workbench\" 的 rootPath\n</code></pre>\n<p>若拿不到：用宿主 <code>plugins.query</code> list，或面板/会话上下文；失败则 AskUserQuestion 请用户确认 App 已启用系统插件「制作插件」。</p>\n<table>\n<thead>\n<tr>\n<th>资源</th>\n<th>绝对路径</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><strong>插件 CLI（内置）</strong></td>\n<td><code>{workbenchRoot}/agent/cli/astravia-plugin-cli.js</code></td>\n</tr>\n<tr>\n<td>文档索引（本 skill 附件）</td>\n<td>本 skill 目录 <code>references/doc-index.md</code></td>\n</tr>\n<tr>\n<td>实现模板摘要</td>\n<td>本 skill 目录 <code>references/templates.md</code></td>\n</tr>\n<tr>\n<td>标准脚本</td>\n<td><code>{workbenchRoot}/scripts/*.mjs</code></td>\n</tr>\n</tbody>\n</table>\n<p><strong>手册不在工作台里</strong>，它随 <code>@astravia-org/plugin-sdk</code> 装进<strong>被编辑工程自己的</strong> <code>node_modules</code>。\n这是刻意的：那份手册与该工程实际编译的 SDK 版本一致，而随 App 发版的内嵌副本做不到。用内置\nCLI 解析它的位置（工程 <code>npm install</code> 之后）：</p>\n<pre><code>node \"{workbenchRoot}/agent/cli/astravia-plugin-cli.js\" docs --json\n</code></pre>\n<p>返回 <code>manualDir</code>（手册目录绝对路径）、<code>entry</code>（README.md）、<code>sdkVersion</code>，以及当前命中的插件工程。\n<strong>不要硬编码 node_modules 路径</strong>：工作区可能把依赖提升到上层，一仓多插件时各插件还可能钉不同版本。</p>\n<hr>\n<h2>1. 强制读文档（不可跳过）</h2>\n<p>用 <strong>read 工具</strong>打开文件（绝对路径），不要只 skim 本 skill。</p>\n<h3>1.1 每次创建或大改插件</h3>\n<p>先用上面的 <code>docs --json</code> 拿到 <code>manualDir</code>，然后（<code>{manualDir}</code> 代指它）：</p>\n<ol>\n<li><code>read {manualDir}/README.md</code> — 能力矩阵与导航</li>\n<li><code>read {manualDir}/getting-started.md</code> — 工程结构、MF、构建安装</li>\n<li><code>read {manualDir}/manifest.md</code> — plugin.json</li>\n<li><code>read {manualDir}/permissions.md</code> — 权限清单</li>\n</ol>\n<p>工程若还没 <code>npm install</code>，<code>docs</code> 会明确告诉你先装 SDK——那一步本来也绕不过去，构建需要它。</p>\n<h3>1.2 按用户目标追加（实现前）</h3>\n<table>\n<thead>\n<tr>\n<th>用户意图</th>\n<th>必读</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>侧栏面板 / 活动 Tab</td>\n<td><code>ui-slots.md</code>（activity-tab）</td>\n</tr>\n<tr>\n<td>整页工作区视图 / 接管宿主页头</td>\n<td><code>ui-slots.md</code>（workspace-view + setWorkspaceViewHeader）</td>\n</tr>\n<tr>\n<td>视图要随宿主侧边栏收缩自适应</td>\n<td><code>ui-slots.md</code>（useSidebarState；沉浸式页头尤其需要）</td>\n</tr>\n<tr>\n<td>输入栏按钮</td>\n<td><code>ui-slots.md</code>（input-action）</td>\n</tr>\n<tr>\n<td>新会话页摆素材 / 选完智能体的第一屏</td>\n<td><code>ui-slots.md</code>（new-session-context）</td>\n</tr>\n<tr>\n<td>插件自带人设 / 团队</td>\n<td><code>manifest.md</code>（贡献智能体与团队）</td>\n</tr>\n<tr>\n<td>文件预览</td>\n<td><code>ui-slots.md</code>（file-preview + <strong>notify 错误上报</strong>）+ <code>styling-and-pitfalls.md</code>（<strong>面板布局边界</strong>）</td>\n</tr>\n<tr>\n<td>全局弹层</td>\n<td><code>ui-slots.md</code>（global）</td>\n</tr>\n<tr>\n<td>任何可能失败的 IO/解析</td>\n<td><code>ui-slots.md</code>（<strong>notify</strong>）+ <code>styling-and-pitfalls.md</code>（错误必须上报）</td>\n</tr>\n<tr>\n<td>Agent 工具 / 读写文件 / 对话</td>\n<td><code>conversation-and-agent.md</code></td>\n</tr>\n<tr>\n<td>消息下方卡片</td>\n<td><code>message-cards.md</code></td>\n</tr>\n<tr>\n<td>插件自带 MCP</td>\n<td><code>mcp.md</code></td>\n</tr>\n<tr>\n<td>样式 / 布局逃逸 / 不生效 / 缓存</td>\n<td><code>styling-and-pitfalls.md</code>（含<strong>面板类 slot 禁止 viewport fixed</strong>）</td>\n</tr>\n<tr>\n<td>引导词 / 设置项</td>\n<td><code>manifest.md</code> 对应章节</td>\n</tr>\n</tbody>\n</table>\n<h3>1.3 实现时</h3>\n<ul>\n<li>API 名、权限、scope_use fail-closed、返回值形状 <strong>以手册为准</strong>。</li>\n<li>模板摘要见 <code>references/templates.md</code>，但细节冲突时以 <code>{manualDir}/*</code> 为准。</li>\n<li>不确定就再 read 对应章节，或 AskUserQuestion。</li>\n</ul>\n<hr>\n<h2>2. 前置条件</h2>\n<ol>\n<li>用户已打开输入栏 <strong>「制作插件」</strong> toggle（硬隔离；关着则 skill/agent 贡献不可见）。</li>\n<li>工程在<strong>当前会话 cwd</strong>（或一层子目录），无特殊工场目录。</li>\n<li>用户插件依赖：<code>@astravia-org/plugin-sdk</code> / <code>@astravia-org/plugin-vite</code> 用 <strong>registry 已发布 semver</strong>（<code>init</code> 默认 sdk <code>^0.3.1</code> / vite <code>^0.2.0</code>，两者版本独立；若 install 失败问用户 registry/版本）。</li>\n<li>构建用 <strong>托管 Node + npm</strong>；标准脚本封装，禁止随意手搓另一套 pack（除非用户明确要求且你已读 getting-started 的打包约定）。</li>\n</ol>\n<hr>\n<h2>3. 禁止臆测（必须 AskUserQuestion 或等价确认）</h2>\n<table>\n<thead>\n<tr>\n<th>项</th>\n<th>原因</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>插件 <code>id</code></td>\n<td>全局唯一，装后难改</td>\n</tr>\n<tr>\n<td>展示名 <code>name</code></td>\n<td>用户可见品牌</td>\n</tr>\n<tr>\n<td><code>permissions</code> 列表</td>\n<td>安全；对照 permissions.md 向用户解释再写入</td>\n</tr>\n<tr>\n<td>要解决的问题 / MVP 范围</td>\n<td>避免一次做全家桶</td>\n</tr>\n<tr>\n<td>是否立即安装到本机</td>\n<td>构建后是否引导用户在面板点「应用到 Astravia」</td>\n</tr>\n<tr>\n<td>扩展点类型（用户没说时）</td>\n<td>activity-tab / 工具 / 引导词 / 预览 / …</td>\n</tr>\n</tbody>\n</table>\n<hr>\n<h2>4. 端到端流水线</h2>\n<h3>4.1 澄清</h3>\n<p>AskUserQuestion 收齐 §3；对照 README 能力矩阵选定扩展点 → 列出要读的文档章节 → <strong>先 read 再写代码</strong>。</p>\n<h3>4.2 Scaffold</h3>\n<pre><code>node \"{workbenchRoot}/agent/cli/astravia-plugin-cli.js\" init --id {id} --name \"{name}\" \"{cwd}/{plugin-id}\"\ncd \"{cwd}/{plugin-id}\" &amp;&amp; npm install\n</code></pre>\n<p>脚手架同时落一份 <code>AGENTS.md</code>（该读哪些手册、不可违反的几条）。<strong>先读它</strong>，它与本 skill 同源。</p>\n<p>然后按文档改：</p>\n<ul>\n<li><code>plugin.json</code>：permissions、guidingWords、agent、styles、moduleFederation…（<code>agent_mode</code> 已废弃，不要写，见 manifest.md）</li>\n<li><code>src/index.tsx</code>：register* / registerTool 等（遵守 styling 顶层 JSX 规则）</li>\n<li>需要 skill/prompt 时按 manifest 建目录</li>\n</ul>\n<p>可选：</p>\n<pre><code>node \"{workbenchRoot}/scripts/check-manifest.mjs\" \"{pluginRoot}\"\n</code></pre>\n<h3>4.3 实现质量检查（自检清单）</h3>\n<p>对照已读文档确认：</p>\n<ul>\n<li><input disabled=\"disabled\" type=\"checkbox\"> 每个用到的 API 都在 <code>permissions</code> 里声明</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> 会话页 UI / 工具都写了合理的 <code>scope_use</code>（fail-closed）</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> 工具 description 写清何时调用</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> 无 MF 顶层 JSX 陷阱</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <strong>样式：只用 Tailwind className；未手写业务 .css / 未用全局选择器</strong>（<code>style.css</code> 仅 theme+utilities 入口，见 styling-and-pitfalls）</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <strong>面板布局：file-preview / activity-tab 内无 <code>fixed</code> 贴视口、无超高 z-index、无 portal 到 <code>document.body</code></strong>；面板内浮层用 <code>relative</code>+<code>absolute</code>；全局浮层用 <code>registerGlobalSlot</code>，Toast 用 <code>notify</code>（见 styling-and-pitfalls → 面板类 slot 布局边界）</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> 用户工程无 <code>workspace:*</code></li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> i18n：若要宿主渲染中文 label，按手册用 catalog / <code>%key%</code>（desktop 用户文案规范）</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <strong>错误可排查：所有可能失败的路径（读文件/解析/网络/外部库）在 catch 里调用 <code>ctx.ui.notify({ message, error })</code></strong>，禁止只写死「失败」文案、丢掉原始 error；<code>notify</code> 无需权限，有 <code>error</code> 时宿主 Toast 可一键复制堆栈（见 <code>ui-slots.md</code> → notify）</li>\n</ul>\n<h3>4.3.5 热更新感知（改已装插件前必查）</h3>\n<p>改一个<strong>已安装</strong>的插件前，先 <code>plugins.query</code> → <code>get {id}</code> 看返回项有没有 <code>devWatch</code> 字段：</p>\n<ul>\n<li><strong><code>devWatch</code> 存在（热更新已开启）</strong>：改完工程源码或 <code>plugin.json</code> 即结束——vite watch 构建成功后自动重载；dev 会话内新增 permissions/commands 也会自动放行。<strong>禁止</strong>再走 4.4/4.5 或 reload。若 <code>devWatch.status === \"error\"</code>，提示用户看面板错误或拨一下热更新开关。仅当用户明确要<strong>持久</strong>写入注册表（关热更新/重启后仍生效）时，才用 <code>workbench_offer_reinstall</code> 让用户点卡片「重新安装」。</li>\n<li><strong><code>devWatch</code> 不存在</strong>：走 4.4→4.5 常规流程（构建打包后引导用户在面板点「应用到 Astravia」）。</li>\n</ul>\n<h3>4.4 构建打包（强制脚本）</h3>\n<pre><code>node \"{workbenchRoot}/scripts/build-and-pack.mjs\" \"{pluginRoot}\"\n</code></pre>\n<ul>\n<li>默认：patch bump → <code>npm install</code> → <code>npm run build</code> → <code>release/{id}-{version}.astraviapkg</code></li>\n<li>解析 stdout JSON：<code>packagePath</code>、<code>id</code>、<code>version</code></li>\n<li>失败：读 stderr，按 getting-started / styling 修；缺依赖或 registry 问题 → AskUserQuestion</li>\n</ul>\n<h3>4.5 安装到本机 Astravia（引导用户在面板点击，不要弹确认）</h3>\n<p>打包完成后<strong>不要调用</strong> <code>plugins.manage</code> 的 <code>install-from-path</code>（会弹确认 sheet，工作台流程已废弃此路径）。改为告知用户：</p>\n<blockquote>\n<p>打开右侧活动面板「制作插件」→ 对应工程卡片 → 点 <strong>「应用到 Astravia」</strong>（面板安装一次完成授权 + 启用，无确认弹窗）。</p>\n</blockquote>\n<ul>\n<li>应用成功后面板会<strong>默认开启「热更新」</strong>：之后你改源码即自动构建+重载（§4.3.5），无需再次应用。用户可手动关掉。</li>\n<li>再次应用（热更新被关掉时）：build-and-pack 后再请用户点「应用到 Astravia」（应用后会重新默认开启热更新）。</li>\n<li>不可覆盖系统插件 id。</li>\n</ul>\n<h3>4.6 改 name / guidingWords</h3>\n<p>只改 <strong>工程源码</strong> <code>plugin.json</code>，再 4.4 → 4.5。禁止改 <code>~/.astravia/plugins/...</code> 已装目录当真相源。</p>\n<h3>4.7 卸载 / 重载 / 重新安装</h3>\n<ul>\n<li><code>plugins.manage</code>：<code>uninstall</code> / <code>reload</code>（系统插件不可卸）。</li>\n<li><strong>重新安装</strong>（权限/命令等安装态变更）：工具 <code>workbench_offer_reinstall</code> 出消息卡，或面板「重新安装」——<strong>不要</strong> <code>install-from-path</code>。</li>\n</ul>\n<hr>\n<h2>5. 运维面板</h2>\n<p>Activity Tab「制作插件」（同样受 toggle 硬隔离）：扫描 cwd、构建、应用、卸载、重载、改 name/引导词。与对话同一规则与同一脚本。</p>\n<p>每张工程卡片有 <strong>「热更新」开关（已安装后默认开）</strong>：宿主把插件 dev 链接到工程目录并常驻 <code>astravia-plugin dev</code>；React / CSS 走 HMR，其余资源定向重载（无需 bump/重打包/手动 reload）。适合迭代调试。</p>\n<p>已安装时还有 <strong>「重新安装」</strong>（与消息卡按钮同路径）：强制 build-and-pack → 把权限/命令<strong>持久写入注册表</strong> → <strong>刷新整个 Astravia 窗口</strong>。日常改代码 / 改 plugin.json 靠热更新即可（dev 会话内权限声明自动放行）；重新安装用于落盘授权或热更新异常时兜底。首次安装仍用「应用到 Astravia」。</p>\n<hr>\n<h2>6. 排错</h2>\n<table>\n<thead>\n<tr>\n<th>现象</th>\n<th>处理</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>Skill/工具不可见</td>\n<td>是否打开工作台 toggle；系统插件是否启用</td>\n</tr>\n<tr>\n<td>npm install 失败</td>\n<td>registry、网络、sdk 版本；AskUserQuestion</td>\n</tr>\n<tr>\n<td>构建失败</td>\n<td>读完整错误；对照 getting-started / 依赖版本</td>\n</tr>\n<tr>\n<td>装上无效果</td>\n<td>permissions 是否授予；scope_use；插件 enabled；reload + version</td>\n</tr>\n<tr>\n<td>反复改 UI 调试</td>\n<td>已安装工程默认开热更新：保存即自动构建+重载（见 §5）；若被关掉可再打开</td>\n</tr>\n<tr>\n<td>UI 不出现</td>\n<td>ui-slots 权限与 scope_use；activity tab 是否 attach</td>\n</tr>\n<tr>\n<td>样式/缓存怪</td>\n<td>styling-and-pitfalls；bump version</td>\n</tr>\n<tr>\n<td>运行时「失败」但不知原因</td>\n<td>插件是否 <code>notify({ message, error })</code>？让用户右下角 Toast 点「复制堆栈」贴给你；没有则补 notify 后热更新再复现</td>\n</tr>\n<tr>\n<td>只显示红字无堆栈</td>\n<td>实现遗漏：catch 必须把原始 <code>error</code> 传给 <code>ctx.ui.notify</code>（见 §4.3 与 ui-slots notify）</td>\n</tr>\n</tbody>\n</table>\n<hr>\n<h2>7. 边界</h2>\n<ul>\n<li>不发布插件市场、不拖拽式 no-code 搭建</li>\n<li>不保证任意原生/C++ 依赖在托管 Node 下可构建</li>\n<li>细粒度权限仍可在设置页调整</li>\n<li>用户自建插件默认 <strong>不要</strong> 开 hardIsolation（除非用户明确要求模式开关）</li>\n</ul>\n<hr>\n<h2>8. 附件</h2>\n<ul>\n<li><code>references/doc-index.md</code> — 手册路径与阅读表</li>\n<li><code>references/templates.md</code> — 常见扩展点代码起点</li>\n</ul>\n<p><strong>再次强调</strong>：实现前先 <code>docs --json</code> 拿到 <code>manualDir</code>，再 <code>read</code> 其中对应的章节。手册随工程自己的\n<code>@astravia-org/plugin-sdk</code> 发布，因此它描述的合同就是这个工程即将编译的合同。</p>\n","files":[{"path":"references/doc-index.md","sizeBytes":3581,"isText":true},{"path":"references/templates.md","sizeBytes":6832,"isText":true},{"path":"SKILL.md","sizeBytes":12362,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-25T10:15:02.777848Z","sha256":"1578C76C8CB9C5933A63815A513ED41B2017B0963D6FD8AA7E92339841110AEB","sizeBytes":12303},"review":null,"source":{"repositoryUrl":"https://github.com/maomaochong-ai/open-astravia","path":"packages/plugins/presets/plugin-workbench/agent/skills/plugin-workbench","license":"Apache-2.0","commit":"a22aa035efb630d8fdf1b71cbf2e8a0bf351f978","subtreeSha":"C0C24026A400E73F2DD0306AF7D48864188091B6468EC761089E05A402941E13","lastSyncedAt":"2026-11-14T00:40:19.636889Z"},"reviewedAt":"2026-10-25T10:20:22.416273Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/maomaochong-ai/open-astravia/tree/main/packages/plugins/presets/plugin-workbench/agent/skills/plugin-workbench"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install maomaochong-ai-open-astravia@llmmart"},{"target":"git","command":"git clone https://github.com/maomaochong-ai/open-astravia.git"}]}