DocsPlugins
Command scripts
A command is a function your plugin runs in the background. Both the UI and AI can call it. It runs in a separate Node process in the desktop app.
Write a command
Declare it under commands in the manifest, with handler pointing to the script:
JSON
{
"id": "transform",
"title": "Transform JSON",
"description": "Validate JSON, then format, minify or sort it by key.",
"handler": "scripts/transform.mjs",
"params": {
"type": "object",
"properties": {
"text": { "type": "string", "description": "JSON text to process" },
"action": { "type": "string", "enum": ["format", "minify", "sort"] }
},
"required": ["text"]
}
}The script default-exports a function:
JavaScript
// scripts/transform.mjs
/** @param {{ text: string, action?: string }} input */
export default async function (input, ctx) {
if (!input?.text) throw new Error('text is required')
const data = JSON.parse(input.text)
if (input.action === 'minify') return { result: JSON.stringify(data) }
return { result: JSON.stringify(data, null, 2) }
}| Description | |
|---|---|
input |
For AI calls, the arguments the model generated from params; for UI calls, the input passed to commands.run. |
ctx |
plugin (key / name / version), command, dir (plugin folder, use it to read packaged files), haozi.request(method, path, body) (calls DeepDoer APIs as the logged-in user; payment and credential APIs are blocked). |
| Return value | Plain data (structured-cloneable). Keep what you return to AI short. |
| Throwing | The call fails and the error message is returned as-is to the UI or AI. |
Runtime rules
- You can use all of Node, including
node:fs,fetchandchild_process. Ship third-party dependencies with the package, ideally bundled into one file. - If you use the network, files or child processes, declare it truthfully in
permissions; see permissions. - The default timeout is 30 seconds. UI calls to
commands.runcan passtimeoutMs(1 second to 5 minutes). - A timeout, cancellation or manual stop ends that plugin's command process, and other running commands of the same plugin fail too. Handlers must be safe to retry.
- Each plugin has one long-lived process, reclaimed after 60 seconds idle. Module top-level setup runs once, but do not keep state only in memory.
console.*output goes to the desktop app log (plugin:<key>).
Becoming an AI tool
- Every command with a
handleris registered as the toolplugin__<key>__<id>(invalid characters become_, total length within 64). - The model decides when to call it from
description, so say clearly what it does and when to use it. - Write
paramsand adescriptionfor each field. Withoutparams, the model can only pass a single string{ input }. - Users can set each tool to allow, ask or deny.
Problem with this page?Sent anonymously; your account is not recorded.