Terminus-KIRA原生工具调用实战:告别ICL解析,用tools参数让AI稳定执行终端命令

原创2026-10-23 20:06:291,829 阅读

Terminus-KIRA原生工具调用实战:告别ICL解析,用tools参数让AI稳定执行终端命令

Terminus-KIRA 是 KIRA 项目中的核心 Agent 框架,专为 Terminal-Bench 打造。它用 LLM 原生的 tools 参数实现原生工具调用(Native Tool Calling),彻底告别 ICL(In-Context Learning)JSON/XML 文本解析,让 AI 模型稳定、结构化地执行终端命令,从而显著提升前沿大模型在终端任务上的表现。

KIRA 桌面端 KiraClaw 界面,展示 Agent 工具调用与终端执行环境

为什么 ICL 解析靠不住?

早期的终端 Agent(如 Terminus 2)采用典型的 ICL 方案:在系统提示词里详细规定"请输出如下 JSON 格式的回复",然后用正则/JSON 解析器从模型自由文本里抠出命令。这种方式有两个固有痛点:

  • 格式漂移:模型偶尔会输出 XML、带 Markdown 围栏的 JSON、甚至夹带解释文字,解析器一旦失败就整轮空转;
  • 提示词冗长:为了保证格式,系统提示词里塞满了 JSON Schema 说明,挤占宝贵的上下文空间。

Terminus-KIRA 的思路非常直接:既然各家 LLM API 都支持 tools 参数,那就把"输出格式约定"交给 API 层,让模型返回结构化的 tool call,代码侧完全不需要写解析容错逻辑。 相关演进记录见 README.md。

KIRA Slack Bot 环境变量配置界面,展示工具调用的配置方式

3个原生工具一次讲清

所有工具定义集中在 terminus_kira/terminus_kira.py 的 TOOLS 列表中,通过 litellm.acompletion 的 tools=TOOLS 直接传给模型:

工具名 作用 关键参数
execute_commands 执行终端命令 analysis(当前状态分析)、plan(下一步计划)、commands(含 keystrokes 与 duration 的命令数组)
task_complete 声明任务完成(触发双重确认) 无参数
image_read 视觉分析图片文件 file_path、image_read_instruction

其中 execute_commands 的参数设计值得学习:analysis 和 plan 是必填字段,强制模型在敲命令前先"看懂现状、说清计划",相当于把思维链固化进了结构里,这也是输出更稳定的重要原因。

从模型响应到命令执行:完整执行回路

整个链路在 TerminusKira 类中实现,分为四步:

  1. 绕过基础 Chat 类,直连 LLM:_call_llm_with_tools 直接调用 litellm.acompletion 并传入 tools,从而拿到 API 原生的 tool_calls 字段,而不是解析自由文本;
  2. 结构化解析:_parse_tool_calls 把 tool call 还原为可执行命令。由于参数本身就是合法 JSON,只需 json.loads 一次即可,遇到未知工具名会向模型回传 WARNINGS 让它自我纠正;
  3. 标记轮询执行:_execute_commands 在每条命令后追加 echo '__CMDEND__<seq>__' 标记,若标记在 duration 内出现就立即推进下一条命令,快速命令可以省去大部分等待时间;
  4. 写回对话历史:每个 tool call 都会以 role: "tool" 的结果消息写回上下文,保证多轮工具调用符合 OpenAI 风格 API 的消息规范。

4个让 Agent 更稳的工程优化

原生工具调用之外,Terminus-KIRA 还叠加了几个"小而有效"的 harness 层改进:

  • 提示词瘦身:迁移到 tools 参数后,系统提示词删除了大段 JSON 格式说明,只剩十几行,见 prompt-templates/terminus-kira.txt;
  • Prompt 缓存:anthropic_caching.py 对最近 3 条消息打 ephemeral 缓存标记,降低 Anthropic 模型的延迟与费用;
  • 输出截断防护:终端输出限制在 30 KB,防止上下文被长日志撑爆;
  • 双重完成确认:模型第一次调用 task_complete 时,框架会回传一份"测试工程师 / QA 工程师 / 用户"三重视角检查清单,要求模型确认无误后再确认一次,减少"假装完成"。

快速上手:一条命令跑起 Agent

项目已内置本地与云端三类执行脚本,分别对应 Docker、Daytona、Runloop 环境:

核心运行命令如下(以 Docker 环境为例):

uv run harbor run \
    --dataset terminal-bench-sample@2.0 \
    --n-tasks 1 \
    --agent-import-path "terminus_kira.terminus_kira:TerminusKira" \
    --model anthropic/claude-opus-4-6 \
    --env docker \
    -n 1

需要自行部署时,先克隆仓库:

git clone https://gitcode.com/gh_mirrors/kira3/KIRA
cd KIRA

小结

Terminus-KIRA 的实践说明:结构化输出不是靠提示词"求"出来的,而是靠 API 能力"给"出来的。 把命令执行从 ICL 文本解析迁移到 tools 参数后,解析代码更简单、系统提示词更短、模型行为更可控——这正是它在 Codex 5.3、Opus 4.6、Gemini 3.1 Pro 等前沿模型上能取得 75% 左右 Terminal-Bench 成绩的关键。如果你有自己维护的终端 Agent,这套"工具定义 + 标记轮询 + 双重确认"的组合也完全可以照搬复用。

登录后查看全文
KIRA