jqopenclaw-node-invoker - SKILL.md Agent Skill

name: jqopenclaw-node-invoker description: 统一通过 Gateway 的 node.invoke 调用 JQOpenClawNode 能力（file.read、file.write、process.exec、system.info、system.screenshot）。当用户需要远程文件读写、文件移动/删除、远程进程执行、系统信息采集、截图采集、节点命令可用性排查或修复 node.invoke 参数错误时使用。

JQOpenClaw Node Invoker

快速流程

确定目标 nodeId（用户给定优先）。
调用 node.describe 检查节点在线状态，并按“节点识别规则”确认是否为 JQOpenClawNode。
若命令未声明或被网关策略拦截，先输出阻断原因，再给修复建议。
按 references/command-spec.md 构造 node.invoke 请求。
每次调用使用新的 idempotencyKey（UUID）。
输出结果时先给结论，再给关键字段，不直接堆原始 JSON。

节点识别规则

先读 node.describe 返回的 modelIdentifier、commands、displayName、nodeId。
强匹配（可直接判定为 JQOpenClawNode）：
- modelIdentifier 非空，且满足以下任一条件：
  - 等于 JQOpenClawNode。
  - 以 JQOpenClawNode 开头（如 JQOpenClawNode(Qt/C++)）。
弱匹配（仅在 modelIdentifier 为空时使用）：
- commands 同时包含：file.read、file.write、process.exec、system.info、system.screenshot。
- 且 displayName 或 nodeId 包含 JQOpenClaw。
拒绝匹配：
- modelIdentifier 明确存在但不匹配 JQOpenClawNode*，即使命令集合相似也不按本技能处理。
不确定处理：
- 若仅满足部分条件，先明确告知“节点类型不确定”，并要求用户指定目标 nodeId 或修正节点 modelIdentifier 后再执行。

命令映射

文件读取：file.read
文件写入/移动/删除：file.write
远程进程执行：process.exec
系统基础信息：system.info
屏幕截图：system.screenshot

调用规则

统一使用 node.invoke。
params 必须是对象，字段类型严格匹配。
节点侧仅接受 node.invoke.request.payload.paramsJSON，且 paramsJSON 必须解析为对象。
paramsJSON 缺失或 null 时按空对象处理；若存在但不是字符串、为空字符串、或解析后不是对象，按 INVALID_PARAMS 处理。
file.write 必须显式传 allowWrite=true 才允许执行；未显式授权时应返回阻断提示。
timeoutMs 需按任务复杂度设置：
- file.read / file.write：5000-30000
- process.exec：5000-120000
- system.info：30000
- system.screenshot：60000
node.invoke.timeoutMs 可省略；若传入，必须为非负整数（毫秒），否则按 INVALID_PARAMS 处理。其中 0 视为立即超时。
node.invoke.timeoutMs 会参与请求预算裁剪；节点会将 process.exec.params.timeoutMs 与 file.read(operation=rg) 的内部超时裁剪到该预算内（取更小值）。
即便省略 node.invoke.timeoutMs，网关/调用端仍有等待超时（当前 OpenClaw 常见默认约 30000ms，CLI openclaw nodes invoke 默认 15000ms）。
实际可用执行时长取决于最先触发的超时层：调用端/网关等待超时、node.invoke.timeoutMs（若传入）、能力内部超时。
process.exec 支持 program + arguments 模式。
process.exec 不支持 command 字段（command mode）；传入会返回 INVALID_PARAMS。
file.read 支持 operation=read/lines/list/rg/stat。大文件建议使用 read + offsetBytes + maxBytes 分块读取；按行区间读取使用 lines + startLine/endLine；目录遍历可用 list + recursive + glob；元信息查询使用 stat。
file.write 默认禁用；需显式 allowWrite=true。开启后默认 operation=write；移动用 operation=move（配 destinationPath/toPath）；删除用 operation=delete（走回收站删除）。

网关阻断处理

command not allowlisted：
- 说明这是 Gateway 策略拦截。
- 提示管理员在 Gateway 配置添加 gateway.nodes.allowCommands（如 file.read、file.write）。
command not declared by node / node did not declare commands：
- 先看 node.describe.commands。
- 要求节点端先声明命令再调用。

错误处理规范

INVALID_PARAMS：参数缺失、类型不匹配或超出范围（含 file.read / file.write / process.exec 的参数校验失败）。指出具体字段问题并给出可直接重试的参数。
TIMEOUT：可能为网关等待超时，或显式传入 timeoutMs=0 触发立即超时。建议增大 timeoutMs 或缩小任务范围。
FILE_READ_FAILED / FILE_WRITE_FAILED：用于非参数类失败。输出失败原因并给路径、权限、目录存在性、回收站可用性等排查建议。
PROCESS_EXEC_FAILED：用于非参数类失败（程序不存在、权限不足、启动失败等无法产出结构化执行结果）。输出节点返回错误并给程序路径、工作目录、权限、目标进程状态排查建议。
SYSTEM_INFO_FAILED：系统信息采集失败。建议检查节点系统命令可用性与权限。
SCREENSHOT_CAPTURE_FAILED / SCREENSHOT_UPLOAD_FAILED：截图采集或上传失败。建议检查显示环境、file-server-uri、file-server-token 与网络连通性。
COMMAND_NOT_SUPPORTED：改用已声明命令或升级节点版本。

输出规范

成功时：
- 先一句话结论。
- 再列关键字段（例如 bytesWritten、exitCode、timedOut、url）。
- 对 process.exec，若 timedOut=true 或 resultClass=timeout，按“命令超时”给出失败结论与重试建议（即使 node.invoke 本身返回成功结构）。
失败时：
- 先给 error.code、error.message。
- 再给一条可执行的下一步操作。

安全边界

file.write 与 process.exec 默认按最小必要原则执行。
对可能破坏状态的操作（删除、覆盖、重置、停服务）先征得用户明确确认。
不自行提升权限，不绕过网关策略。

参考

references/command-spec.md