前置条件
- Node 或 Bun。
- 用于安装和调试插件的 Astravia 桌面客户端（安装与热更新都要求它正在运行）。
不需要 Astravia 的源码仓库。
一条命令起工程
npx @astravia-org/plugin-cli init --id my-plugin --name "My Plugin"
cd my-plugin && npm install脚手架会落下 plugin.json、Vite + Module Federation 配置、Tailwind 入口，以及一份 AGENTS.md。
开发闭环
npm run dev # Vite + Module Federation 开发服务器
npm run validate # 校验清单与构建产物
npm run install:astravia # 构建、打包并装进正在运行的 Astravia
npx astravia-plugin-cli watch # 热更新：宿主改从本工程目录加载，改完即生效
npx astravia-plugin-cli reload <id> # 提示有 pending 版本时切换过去
npx astravia-plugin-cli uninstall # 卸载install:astravia 把归档交给正在运行的桌面端校验、授权、安装，不会直接写 ~/.astravia/plugins。
安装一个更新版本只被记录为 pending，应用继续加载当前活动版本，直到 reload 才切换。改了代码却看不到变化时，先确认 plugin.json 的 version 已经提升。
项目结构
plugin.json
package.json
tsconfig.json
vite.config.ts
index.tsx
style.css
配置构建
通过 @astravia-org/plugin-vite 配置 Module Federation：
import tailwindcss from "@tailwindcss/vite";
import { astraviaPluginFederation } from "@astravia-org/plugin-vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [
tailwindcss(),
astraviaPluginFederation({
name: "my_plugin",
entry: "./src/index.tsx",
expose: "./plugin",
}),
],
esbuild: { jsx: "automatic", jsxImportSource: "react" },
});创建入口
import { definePlugin } from "@astravia-org/plugin-sdk";
function MyPanel() {
return <div className="p-3 text-sm text-foreground">插件已加载</div>;
}
export default definePlugin({
activate(ctx) {
ctx.ui.registerGlobalSlot({ id: "root", component: MyPanel });
},
});构建与加载
按开发调试与正式发布选择路径：
使用 bunx astravia-plugin dev 启动插件开发服务，再通过 Astravia 的开发链接加载。改动后可快速验证界面与工具注册，但发布前仍要执行生产构建并测试 ZIP 安装流程。
发布多个能力：能力市场仓库
一个仓库要上架多个能力（插件、MCP、Skill、场景）时，用市场骨架：
npx @astravia-org/plugin-cli init hub --name my-market \
--repository https://github.com/me/my-market --min-app-version 0.55.0它生成 .astravia/marketplace.json 索引、abilities/ 目录约定、一份仓库级 AGENTS.md，以及跑
sync --check 的 CI。之后在 abilities/plugins/<slug> 里照常 init 即可——开发命令一律作用于
最近的那个能力目录，所以在市场仓库里开发与开发单插件完全一样。
索引里的 version、config.api_version、config.permissions 都是从能力包推导的派生字段，
由工具对账：
npx @astravia-org/plugin-cli sync # 回填派生字段，并推进 marketplaceVersion
npx @astravia-org/plugin-cli sync --check # 只报不写，非零退出（CI 用）