# 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。