docs: 渐进式插件教程（L0→L5）+ DESIGN.md 视觉规范 + plugin-template 脚手架

2026-09-11 02:18:01 +08:00
parent 8e4b5496e8
commit 4ed31a34fc
16 changed files with 844 additions and 1 deletions
@@ -0,0 +1,85 @@
+# L0 · 第一个插件
+
+> 目标：10 分钟内拥有一个被宿主装载、可在日志里看到自己痕迹的最小插件。不需要构建工具。
+
+## 1. 建目录
+
+放在**全局**插件目录（所有工作区可见；项目级放 `<工作区>/.pi/extensions/`，见 README）：
+
+```
+~/.pi/agent/extensions/hello/
+  manifest.json
+  main.mjs
+```
+
+> Windows 下即 `C:\Users\<你>\.pi\agent\extensions\hello\`。
+
+## 2. manifest.json
+
+```json
+{
+  "id": "hello",
+  "name": "Hello",
+  "version": "0.1.0",
+  "minContract": "0.1.0",
+  "description": "我的第一个插件"
+}
+```
+
+字段规则：`id` 必须匹配 `^[a-z][a-z0-9-]*$`；`version` 是 semver；`minContract` 是要求的宿主契约版本（当前 `0.2.0`，填 `0.1.0` 即可向后兼容）。全字段见 [../plugins.md](../plugins.md#manifestjson)。
+
+## 3. main.mjs
+
+```js
+// 默认导出一个工厂：宿主激活插件时调用，返回的函数在禁用/重载时被调用
+export default function definePlugin(api) {
+  api.log.info('hello activated', { version: api.manifest.version })
+
+  // 演示：往 Agent 可见的目录里注册一个极简工具
+  api.pi.registerTool({
+    name: 'hello_now',
+    description: '返回当前时间的问候语',
+    parameters: {},
+    async execute() {
+      api.log.debug('hello_now called')
+      return { output: `Hello! 现在是 ${new Date().toISOString()}` }
+    }
+  })
+
+  return () => {
+    api.log.info('hello disposed')
+  }
+}
+```
+
+> `api` 的完整形状（pi / ui / storage / log / manifest）见 [../plugins.md](../plugins.md#主进程插件契约aso-plugin-sdk-主入口)。
+
+## 4. 验证
+
+1. 重启应用（`pnpm dev`；扫描发生在启动与插件重载时）
+2. 打开 设置 → Agent 能力 → 插件 → **全局** 作用域，应看到「Hello v0.1.0」，开关为「已启用」
+3. 打开日志文件 `userData/logs/main-YYYY-MM-DD.log`，应能搜到：
+
+```
+<时间> INFO  [plugin-host] external main loaded pluginId=hello version=0.1.0
+<时间> INFO  [plugin-host] plugin activated pluginId=hello source=external
+<时间> INFO  [plugin] hello activated pluginId=hello version=0.1.0
+```
+
+## 5. 改代码后如何生效
+
+- 改 `main.mjs`：设置 → 插件页任意开关触发重载，或重启应用（宿主以 cache-bust 重新 import）
+- 改 `manifest.json`：同上；`id` 变了等于新插件
+
+## 常见装载失败
+
+| 现象（日志里搜） | 原因 |
+|---|---|
+| `external main load failed` | main.mjs 语法错误 / import 了不存在的模块 |
+| `external main invalid export` | 忘了 `export default`，或默认导出不是函数 |
+| `需要契约版本 >=` | manifest.minContract 高于当前宿主契约（0.2.0） |
+| 插件页全局作用域为空 | 目录放错（注意是 `extensions` 复数）；或用户版构建（装载关闭） |
+
+---
+
+**下一篇**：[L1 工具与命令](./02-tools-and-commands.md)——把真正的能力交给 Agent。