跳到正文
Ankole

Worker CLI 能力

面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/cli-capabilities/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

在 Ankole 中,有一部分平台能力并不是作为每轮必带的模型工具(Tool)暴露给大模型,而是直接封装为 Agent Computer Worker 内的 Shell 命令行程序(CLI)。Agent 就像日常调用 kubectl 一样,直接在终端里运行它们——内置的 ankole-pod(涵盖 pages.*、base.*、applet build|publish|pull 与 jobs.*)、ankole-files、ankole-browser 以及 Webhook 端点管理命令,全部采用这种交付形态。

本页说明什么样的能力适合做成 CLI,以及如何在不注册模型工具、不塞入全局 Skill 索引、也不膨胀系统提示词的前提下,让 Agent 依然能够精准发现并正确调用这些命令。

什么时候 CLI 是正确形态

当一项能力同时符合以下三个特征时,做成 CLI 往往比做成模型工具更合适:

  • 天然融入 Shell 工作流:Agent 往往需要把它与其他终端命令串联组合使用,或者还需要在自动化脚本及后台 Agent 任务中直接调用它。
  • 仅在特定决策分支上才用得到:例如,一个从不需要配置外部事件接入的 Agent,压根不需要在日常每轮对话里都知道 create-webhook-cli 的存在。
  • 参数结构简单直观:无需让模型构造复杂的嵌套 JSON Schema,靠几个标准命令行参数(flag)就能清晰表达输入。

要知道,挂载在模型上下文里的可见工具在每一个对话回合都会消耗 Token 预算;而做成 CLI 的能力在 Agent 真正走到相关业务分支之前,上下文开销是零。

披露架构

为了让 Agent 无需全局工具表也能顺畅使用 CLI,我们用三条渐进式披露准则替代传统的工具注册与全局索引:

1. --help 本身就是权威契约文档。 CLI 输出的 --help 帮助信息直接承载 Agent 正确调用该能力所需的全部上下文:这项命令解决什么问题、背后的安全与信任模型、持久性与幂等保证,以及一次完整的端到端调用示例。帮助文本随二进制一起发布,调用方读取的是该实现版本随附的说明。编写 --help 时应面向零背景知识的读者,重点讲清目标与边界约束,而非罗列死板的机械步骤(可参考 create-webhook-cli --help 的写法)。

2. 把一句话指针放在必经的决策面上。 Agent 之所以能“想起来”有这个命令,靠的是埋在相邻决策节点上的一句话指针——它可以放在某个相邻工具的描述里、某个对接特定外部系统的 Skill 里,或是另一个关联 CLI 的 --help 末尾。每条指针只客观点明“在什么场景下需要用到该能力”以及“运行哪条 --help 查看详情”,绝不强行诱导模型调用。凡是做成 CLI 的能力,都必须在通往该场景的必经入口处至少留有一条指针:让这项能力派上用场的那条业务路径,天然就决定了应该把指针放在哪里。

3. 通用平台契约写在 --help,外部系统差异留在插件 Skill。 凡是适用于该 CLI 的通用规则,都应写进 --help。插件 Skill 说明外部服务的操作契约,并在需要时引导 Agent 使用平台能力。例如,Toolkit 上传操作需要 Pod 文件引用,因此 Skill 会引导 Agent 通过 pod-content 上传 Worker 文件,再调用外部上传操作。

自动化任务

自动化任务在 Function Runtime 中运行已发布的 Applet Action。Agent 使用 ankole-pod applet 构建并发布 Applet,再通过 ankole-pod (jobs.*) 查看 Action、创建或配置任务、管理定时与回调端点、检查运行记录。调用前应阅读 ankole-pod --help。

Applet 服务端导出 {routes, actions}。Action 声明处理函数、幂等性和并发策略,通过 ctx.signal、ctx.job.config 读取输入和配置,通过 ctx.state 保存游标,并可用 continueSlice() 在同一次运行中分段执行。外部调用使用 AnkoleRuntime.mcp;团队名义使用 AnkoleRuntime.admin.mcp。

Applet「自动化」面板及 SDK 的 useAppletJobs()、useJobSources(jobID) 提供相同的任务与触发源管理能力。测试触发后,应检查真实运行记录的输入、结果、错误和日志。权限与恢复方式见自动化任务。

新增 CLI 能力的要求

向代码库新增一项 Worker CLI 能力时,请遵循以下工程规范:

  • 实现代码统一放在 app/agent_computer/src/cli/ 下,每个命令族单独建一个子目录。
  • 无论传入 --help 还是 -h,都必须向标准输出打印完整的使用契约并以退出码 0 正常结束,且帮助输出不得依赖活跃回合上下文或网络连接。由于外层命令包装器可能会在参数前前置子命令名,请遍历整个参数列表在任意位置识别帮助标志。
  • 参数校验失败时仅输出简短的 usage 用法提示,不要把简短报错提示当作完整契约文档。
  • 在 Agent 可能用到该能力的每一个上游决策点补充一句话指针;措辞保持客观中立,只讲清适用条件并引导查阅 --help。
  • 当编写插件 Skill 将该 CLI 能力与某个外部系统结合时,在 Skill 开篇直接指向 --help,正文只写该外部系统特有的领域规则。