开发文档插件开发
命令脚本
命令是插件在后台执行的函数,界面和 AI 都能调用。它运行在桌面端的独立 Node 进程里。
写一个命令
在 manifest 的 commands 里声明,handler 指向脚本:
JSON
{
"id": "transform",
"title": "转换 JSON",
"description": "校验 JSON,并按选择格式化、压缩或按键名排序。",
"handler": "scripts/transform.mjs",
"params": {
"type": "object",
"properties": {
"text": { "type": "string", "description": "待处理的 JSON 文本" },
"action": { "type": "string", "enum": ["format", "minify", "sort"] }
},
"required": ["text"]
}
}脚本默认导出一个函数:
JavaScript
// scripts/transform.mjs
/** @param {{ text: string, action?: string }} input */
export default async function (input, ctx) {
if (!input?.text) throw new Error('text 不能为空')
const data = JSON.parse(input.text)
if (input.action === 'minify') return { result: JSON.stringify(data) }
return { result: JSON.stringify(data, null, 2) }
}| 说明 | |
|---|---|
input |
AI 调用时是模型按 params 生成的参数;界面调用时是 commands.run 传入的 input。 |
ctx |
plugin(key / name / version)、command、dir(插件目录,读包内文件用它)、haozi.request(method, path, body)(带用户登录态调用 DeepDoer 接口,资金和凭证类接口禁止调用)。 |
| 返回值 | 纯数据(可结构化克隆)。返回给 AI 的内容尽量精简。 |
| 抛错 | 调用失败,错误信息原样返回给界面或 AI。 |
运行规则
- 可以用
node:fs、fetch、child_process等全部 Node 能力。第三方依赖要随包带上,建议打包成单个文件。 - 用到网络、文件或子进程时,在
permissions里如实声明,见 权限。 - 默认超时 30 秒,界面调用
commands.run时可传timeoutMs(1 秒到 5 分钟)。 - 超时、取消或手动终止会结束这个插件的命令进程,同一插件正在运行的其他命令也会失败。handler 要能安全重试。
- 每个插件一个常驻进程,空闲 60 秒回收。模块顶层的初始化只执行一次,但不要把状态只放在内存里。
console.*输出写入桌面端日志(plugin:<key>)。
成为 AI 工具
- 每个带
handler的命令都会注册为工具plugin__<key>__<id>(非法字符替换为_,总长 64 以内)。 - 模型靠
description决定何时调用,写清楚做什么、什么时候用。 - 写好
params和每个字段的description。不写params时模型只能传一个字符串{ input }。 - 用户可以对每个工具设置允许、询问或禁止。
这篇文档有问题?匿名提交,不记录账号。