5 分钟第一个插件

本篇用最短路径做一个能看到的东西：一个 static 运行时的插件 —— 没有构建、没有依赖、没有后端进程，就两个文件。

1. 建目录

在插件安装目录下新建一个文件夹（dev. 前缀是开发插件的命名习惯，与正式 id 区分）：

mkdir -p ~/xinghan/plugins/dev.hello
cd ~/xinghan/plugins/dev.hello

2. 写 manifest

plugin.json：

{
  "id": "dev.hello",
  "name": "你好星汉",
  "version": "0.1.0",
  "description": "我的第一个插件",
  "runtime": "static",
  "ui": "ui",
  "capabilities": [],
  "contributes": {
    "views": [
      {
        "id": "panel",
        "title": "你好",
        "icon": "sparkles",
        "location": "right-drawer",
        "entry": "ui/index.html"
      }
    ]
  }
}

逐行说明：

• runtime: "static" —— 纯前端插件，宿主不为它起进程，直接静态服务 ui 目录（ui 字段指向它）。
• capabilities: [] —— 不需要任何宿主能力。static 插件通常为空。
• contributes.views —— 贡献一个视图：挂在右侧抽屉（right-drawer），入口是 ui/index.html，图标用 lucide 的图标名。

3. 写页面

ui/index.html：

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8" />
  <style>
    body {
      margin: 0; padding: 24px;
      font-family: system-ui, sans-serif;
      color: #333;
    }
  </style>
</head>
<body>
  <h2>你好，星汉 👋</h2>
  <p>这是一个插件面板。它就是一个普通网页，跑在 iframe 里。</p>
</body>
</html>

4. 让宿主发现它

重启星汉应用（插件在启动时扫描加载）。打开任意项目，右侧工具栏会多出一个 ✨ 图标 —— 点开，你的面板就在抽屉里。

没出现的话，按开发环境与调试排查：九成是 plugin.json 不合法（宿主对坏 manifest 的策略是跳过并打日志，不会阻塞其它插件）。

你已经学会的

• 插件 = 一个带 plugin.json 的目录，放进 ~/xinghan/plugins/ 即被发现；
• static 运行时零成本：manifest + 静态页面，没有进程；
• UI 的落点（抽屉/活动栏/设置页）由 manifest 声明，宿主统一渲染入口。

下一步

• 面板想读当前项目/表格的上下文，甚至读写数据？→ 做一个面板视图
• 想知道 manifest 还能声明什么？→ 插件解剖
• 开发时不想每次重启？→ 开发环境与调试