mcpField
H
headless-adapters

headless-adapters

github.com/youdotcom-ossAgent 工作流9744 次安装今天更新
代码仓库

关于 headless-adapters

headless-adapters 是用于封装无头 CLI Agent 的配置驱动技能，无需编写适配代码。它提供经过测试的 Claude Code 和 Gemini CLI 配置，并支持流式与迭代式会话模式。

主要功能

  1. 01基于 JSON Schema 的 CLI 适配器
  2. 02流式与迭代式会话模式
  3. 03经过测试的 Claude Code 和 Gemini CLI 配置
  4. 04基于 JSONPath 的输出映射

适用场景

  1. 01为评估封装无头 CLI Agent
  2. 02用迭代会话适配无状态 CLI
  3. 03用流式会话连接可恢复会话的 CLI

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/youdotcom-oss/agent-skills --skill headless-adapters

安装后在 Claude Code 中输入/headless-adapters确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
schema-creation-guide.md
troubleshooting-guide.md
schemas/
claude-headless.json
gemini-headless.json

详细介绍

无头适配器

用途

面向无头 CLI Agent 的架构驱动适配器。无需编写代码——只需定义描述如何与 CLI 交互的 JSON 架构。

用例工具
封装无头 CLI Agentheadless 命令
创建新架构架构创建指南

快速入门

  1. 检查是否已有架构：schemas/
  2. 运行适配器： 
    ANTHROPIC_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/claude-headless.json

CLI 命令

headless

适用于任意无头 CLI Agent 的架构驱动适配器。

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

选项：

标志描述必需
-s, --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保持进程运行，通过 stdin 进行多轮交互CLI 支持会话恢复
iterative每轮启动新进程，累积历史记录CLI 为无状态

预构建架构

已测试的架构可在 schemas/ 中找到：

架构Agent模式认证环境变量状态
claude-headless.jsonClaude CodestreamANTHROPIC_API_KEY已测试
gemini-headless.jsonGemini CLIiterativeGEMINI_API_KEY已测试

用法：

# 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

创建架构

  1. 浏览 CLI 的 --help，找出提示词、输出和自动批准标志
  2. 从 CLI 捕获示例 JSON 输出
  3. 将 JSONPath 模式映射到输出事件
  4. 根据现有模板创建架构文件
  5. 使用 headless 命令进行测试

完整工作流请参阅架构创建指南。

故障排除

常见问题
问题可能原因解决方案
未捕获工具调用JSONPath 未遍历数组使用 [*] 通配符语法——参阅指南
“unexpected argument”错误Stdin 模式配置错误使用 stdin: true——参阅指南
401 身份验证错误API 密钥配置不正确设置正确的 API 密钥环境变量（参见“预构建架构”表）
提示词超时JSONPath 未匹配捕获原始 CLI 输出并验证路径——参阅指南
响应为空内容提取失败检查提取路径——参阅指南

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

外部资源

相关内容

评论

支持 Markdown