headless-adapters

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Headless Adapters

Headless 适配器

Purpose

用途

Schema-driven adapter for headless CLI agents. No code required - just define a JSON schema describing how to interact with the CLI.

Use Case	Tool
Wrap headless CLI agent	`headless` command
Create new schemas	Schema Creation Guide

面向Headless CLI Agent的Schema驱动适配器。无需编写代码——只需定义一个JSON schema来描述与CLI的交互方式。

使用场景	工具
封装Headless CLI Agent	`headless` 命令
创建新Schema	Schema创建指南

Quick Start

快速开始

Check if a schema exists in schemas/

Run the adapter:

bash

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

检查schemas/目录中是否已有对应Schema

运行适配器：

bash

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

CLI Commands

CLI 命令

headless

Schema-driven adapter for ANY headless CLI agent.

bash

bunx @plaited/agent-eval-harness headless --schema <path>

Options:

Flag	Description	Required
`-s, --schema`	Path to adapter schema (JSON)	Yes

Schema Format:

json

{
  "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:

Mode	Description	Use When
`stream`	Keep process alive, multi-turn via stdin	CLI supports session resume
`iterative`	New process per turn, accumulate history	CLI is stateless

面向任意Headless CLI Agent的Schema驱动适配器。

bash

bunx @plaited/agent-eval-harness headless --schema <path>

选项：

标识	描述	是否必填
`-s, --schema`	适配器Schema（JSON）的路径	是

Schema格式：

json

{
  "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"
  }
}

会话模式：

模式	描述	使用场景
`stream`	保持进程存活，通过标准输入实现多轮交互	CLI支持会话恢复
`iterative`	每轮交互启动新进程，累积历史记录	CLI无状态

Pre-built Schemas

预构建Schema

Tested schemas are available in schemas/:

Schema	Agent	Mode	Auth Env Var	Status
`claude-headless.json`	Claude Code	stream	`ANTHROPIC_API_KEY`	Tested
`gemini-headless.json`	Gemini CLI	iterative	`GEMINI_API_KEY`	Tested

Usage:

bash

undefined

已测试的Schema可在schemas/目录中获取：

Schema	Agent	模式	认证环境变量	状态
`claude-headless.json`	Claude Code	stream	`ANTHROPIC_API_KEY`	已测试
`gemini-headless.json`	Gemini CLI	iterative	`GEMINI_API_KEY`	已测试

使用示例：

bash

undefined

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

undefined

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

undefined

Creating a Schema

创建Schema

Explore the CLI's
```
--help
```
to identify prompt, output, and auto-approve flags
Capture sample JSON output from the CLI
Map JSONPath patterns to output events
Create schema file based on an existing template
Test with
```
headless
```
command

See Schema Creation Guide for the complete workflow.

查看CLI的
```
--help
```
信息，识别提示、输出和自动批准标识
捕获CLI的JSON输出示例
将JSONPath模式映射到输出事件
基于现有模板创建Schema文件
使用
```
headless
```
命令进行测试

完整工作流请参考Schema创建指南。

Troubleshooting

故障排除

Common Issues

常见问题

Issue	Likely Cause	Solution
Tool calls not captured	JSONPath not iterating arrays	Use `[*]` wildcard syntax - see guide
"unexpected argument" error	Stdin mode misconfigured	Use `stdin: true` - see guide
401 Authentication errors	API key not properly configured	Set the correct API key environment variable (see Pre-built Schemas table)
Timeout on prompt	JSONPath not matching	Capture raw CLI output, verify paths - see guide
Empty responses	Content extraction failing	Check extract paths - see guide

Complete troubleshooting documentation: Troubleshooting Guide

问题	可能原因	解决方案
工具调用未被捕获	JSONPath未遍历数组	使用 `[*]` 通配符语法 - 查看指南
"unexpected argument"错误	标准输入模式配置错误	设置 `stdin: true` - 查看指南
401认证错误	API密钥配置不正确	设置正确的API密钥环境变量（请参考预构建Schema表格）
提示超时	JSONPath不匹配	捕获CLI原始输出，验证路径 - 查看指南
空响应	内容提取失败	检查提取路径 - 查看指南

完整故障排除文档： 故障排除指南

External Resources

外部资源

AgentSkills Spec: agentskills.io

AgentSkills 规范: agentskills.io

headless-adapters

Original

Translation

Headless Adapters

Headless 适配器

Purpose

用途

Quick Start

快速开始

CLI Commands

CLI 命令

headless

headless

Pre-built Schemas

预构建Schema

Claude Code

Claude Code

Gemini CLI

Gemini CLI

Creating a Schema

创建Schema

Troubleshooting

故障排除

Common Issues

常见问题

External Resources

外部资源

Related

相关内容