86 lines
2.8 KiB
Markdown
86 lines
2.8 KiB
Markdown
# 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。
|