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,91 @@
+# L1 · 工具与命令
+
+> 前置：[L0](./01-hello-plugin.md)。`api.pi` 就是 pi 的原生 `ExtensionAPI`——pi CLI 扩展能做的这里都能做，语义一致。
+
+## 1. 注册一个带参数的工具
+
+工具是 Agent 的「手」：注册后自动进入系统提示词与工具列表，受审批拦截管理。
+
+```js
+export default function definePlugin(api) {
+  api.pi.registerTool({
+    name: 'dice_roll',
+    description: '掷一个 N 面骰子，返回点数',
+    parameters: {
+      type: 'object',
+      properties: {
+        sides: { type: 'number', description: '面数，默认 6' }
+      }
+    },
+    async execute(_id, params) {
+      const sides = Number(params.sides) || 6
+      const value = 1 + Math.floor(Math.random() * sides)
+      api.log.info('dice rolled', { sides, value })
+      return { output: String(value), metadata: { sides, value } }
+    }
+  })
+}
+```
+
+要点：
+- `description` 会注入系统提示词，写清楚「什么时候该用这个工具」，Agent 的调用准确率取决于它
+- `execute` 返回 `{ output: string }`——output 是喂回模型的内容，保持精炼
+- 工具名全局唯一，用 `<插件名>_<动作>` 前缀避免撞名
+
+## 2. 注册斜杠命令
+
+命令是用户的「入口」：聊天框输入 `/` 出现，回车触发。
+
+```js
+export default function definePlugin(api) {
+  api.pi.registerCommand({
+    name: 'dice',
+    description: '掷骰子',
+    handler: async (ctx, args) => {
+      const sides = Number(args) || 6
+      ctx.notify(`🎲 ${1 + Math.floor(Math.random() * sides)} / ${sides}`)
+    }
+  })
+}
+```
+
+## 3. 订阅事件
+
+在 Agent 生命周期钩子上挂逻辑（发消息前注入、工具调用前后处理等）：
+
+```js
+export default function definePlugin(api) {
+  const off = api.pi.on('before_agent_start', (event) => {
+    api.log.debug('agent starting', { prompt: event.prompt?.slice(0, 50) })
+  })
+  // 返回的取消函数放进 dispose，宿主在禁用/重载时调用
+  return () => off()
+}
+```
+
+常用事件：`before_agent_start` / `agent_start` / `tool_call` / `tool_result` / `before_provider_request` / `agent_end`。全集见 pi 的 `ExtensionAPI` 类型（`@earendil-works/pi-coding-agent`）。
+
+## 4. 与插件私有存储配合
+
+需要跨回合记住状态时用 `api.storage`（按插件隔离，落盘 `aso-plugin-storage.json`）：
+
+```js
+let count = api.storage.get('count') ?? 0
+api.storage.set('count', ++count)
+```
+
+## 5. 验证
+
+1. 重载插件（开关切换或重启）
+2. 日志确认 `plugin activated`
+3. 聊天框输入 `/dice` 回车 → 收到点数；对 Agent 说「掷个 20 面骰」→ 观察它调用 `dice_roll`
+4. 日志中应出现 `dice rolled sides=20 value=…`
+
+## 排障
+
+- 工具没出现在 Agent 里：日志搜 `plugin activated` 确认激活成功；`registerTool` 抛错会记为 `plugin activation failed`
+- 命令没出现在 `/` 面板：命令名冲突（重名被去重），换名再试
+
+---
+
+**上一篇** [L0](./01-hello-plugin.md) · **下一篇**：[L2 设置表单](./03-settings.md)——让用户能配置你的插件。