L0 · 第一个插件

目标：10 分钟内拥有一个被宿主装载、可在日志里看到自己痕迹的最小插件。不需要构建工具。

1. 建目录

放在全局插件目录（所有工作区可见；项目级放 <工作区>/.pi/extensions/，见 README）：

~/.pi/agent/extensions/hello/
  manifest.json
  main.mjs

Windows 下即 C:\Users\<你>\.pi\agent\extensions\hello\。

2. manifest.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。

3. main.mjs

// 默认导出一个工厂：宿主激活插件时调用，返回的函数在禁用/重载时被调用
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。

4. 验证

重启应用（pnpm dev；扫描发生在启动与插件重载时）
打开设置 → Agent 能力 → 插件 → 全局作用域，应看到「Hello v0.1.0」，开关为「已启用」
打开日志文件 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 工具与命令——把真正的能力交给 Agent。

2.8 KiB Raw Blame History Unescape Escape