headless-adapters

用途

Headless Adapters 是面向无头（headless）CLI 智能体的模式驱动适配器。其特点是不需要编写代码，只需定义一份描述如何与该 CLI 交互的 JSON schema 即可完成适配，用于发现、创建和验证智能体的集成适配器，并提供脚手架工具与基于 schema 的合规性测试。

典型使用场景：包装（Wrap）无头 CLI 智能体时使用 headless 命令；创建新 schema 时参考 Schema Creation Guide。

主要能力

该方案提供 headless 命令，作为面向任意无头 CLI 智能体的模式驱动适配器，通过 --schema 参数指定适配器 schema 的 JSON 路径（必填，短参数为 -s）。

Schema 格式示例：

{
  "version": 1,
  "name": "my-agent",
  "command": ["my-agent-cli"],
  "sessionMode": "stream",
  "prompt": { "flag": "-p" },
  "output": { "flag": "--output-format", "value": "stream-json" },
  "autoApprove": ["--allow-all"],
  "outputEvents": [
    {
      "match": { "path": "$.type", "value": "message" },
      "emitAs": "message",
      "extract": { "content": "$.text" }
    }
  ],
  "result": {
    "matchPath": "$.type",
    "matchValue": "result",
    "contentPath": "$.content"
  }
}

会话模式（Session Modes）有两种：

模式	说明	适用情况
stream	保持进程存活，通过 stdin 进行多轮交互	CLI 支持会话恢复
iterative	每轮新建进程，累积历史记录	CLI 是无状态的

预置 schema 中提供了经过测试的适配文件：

Schema	智能体	模式	认证环境变量	状态
claude-headless.json	Claude Code	stream	ANTHROPIC_API_KEY	Tested
gemini-headless.json	Gemini CLI	iterative	GEMINI_API_KEY	Tested

使用方式

先检查 schemas/ 目录下是否已存在所需 schema，然后运行适配器。

Claude Code 用法：

ANTHROPIC_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/claude-headless.json

Gemini CLI 用法：

GEMINI_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/gemini-headless.json

创建新 schema 的流程：

查看该 CLI 的 --help，识别 prompt、output 与 auto-approve 相关参数；
捕获 CLI 的示例 JSON 输出；
将 JSONPath 模式映射到输出事件；
基于已有模板创建 schema 文件；
使用 headless 命令进行测试。

完整流程参见 Schema Creation Guide。

适用场景

需要将无头 CLI 智能体统一接入智能体评估流程（agent integration）。
需要为尚不支持的 CLI 快速建立适配 schema 并进行合规性测试。
已提供 Claude Code 与 Gemini CLI 的可用 schema，可直接复用。

限制与故障排查

常见问题与处理方式：

问题	可能原因	解决方案
工具调用未被捕获	JSONPath 未遍历数组	使用 [*] 通配符语法，参见指南
“unexpected argument” 错误	Stdin 模式配置错误	使用 stdin: true，参见指南
401 认证错误	API key 未正确配置	设置正确的 API key 环境变量（见预置 schema 表）
prompt 超时	JSONPath 未匹配	捕获原始 CLI 输出，核对路径，参见指南
响应为空	内容提取失败	检查 extract 路径，参见指南

完整故障排查文档参见 Troubleshooting Guide。

技能介绍

用途

主要能力

使用方式

适用场景

限制与故障排查

相关资源