开发文档插件开发

命令脚本

命令是插件在后台执行的函数,界面和 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 }。
  • 用户可以对每个工具设置允许、询问或禁止。