接入你自己的Agent引擎：skill-up自定义引擎local与http传输完整指南

skill-up 自定义引擎让评测框架不再绑定内置 Agent：通过engine.custom声明local或http两种传输方式，你就能把自己的 CLI 工具、脚本或远程 Agent 服务接进 skill-up 的评测流水线，复用它的用例管理、判定（Judge）与报告能力。本指南带你在 10 分钟内完成一次自定义引擎的接入。

什么是 skill-up 自定义引擎（Custom Engine）

skill-up 内置了claude_code、codex、qodercli、qwen_code等引擎，但当engine.name与内置引擎都不匹配时，就必须提供engine.custom配置块，告诉 skill-up如何调用你的 Agent：

• local传输：在运行时工作区内直接执行一条本地命令（CLI 可执行文件、脚本、内部任务都行），命令读取SessionInput文件、写出SessionResultJSON。
• http传输：把SessionInput以 POST 请求发给远程（或本地）的 HTTP Agent 服务，从响应体读取SessionResult。

两者遵循同一份输入/输出契约，差别只在"如何传输"。完整契约见 docs/design/custom-engine.md，中文写作指南见 docs/zh/guide/writing-evals.md。

local 与 http 传输方式对照

💡 选择原则：Agent 就跑在评测机器上选local；Agent 是独立服务（或想复用团队的在线 Agent 平台）选http。

自定义引擎配置入口

在eval.yaml中声明engine.custom即可启用自定义引擎：

engine: name: my-agent # 不与内置引擎重名 custom: transport: local # local | http response_format: session_result timeout_seconds: 300

注意：如果engine.name既不是内置引擎、又没有提供engine.custom，会直接报配置错误unsupported agent "my-agent": missing engine.custom。

local 传输快速上手：最小可用配置

engine: name: review-cli custom: transport: local response_format: session_result env: OPENAI_API_KEY: ${api_key} local: command: ${REVIEW_AGENT_BIN} args: - run - --input - ${input_file} - --output - ${output_file}

调用流程只有 4 步：

1. skill-up 把标准SessionInput写入${input_file}（默认inputs/messages.json）；
2. 渲染并执行command+args，工作目录默认为${workspace}；
3. 你的命令在timeout_seconds内退出；
4. 结果优先从${output_file}读取，未配置时从 stdout 读取。

仓库里附了一个确定性的示例 Agent 脚本 e2e/testdata/custom-engine/agent.sh，配合 e2e/testdata/custom-engine/evals/eval.yaml 端到端演示了 local 传输：脚本读取输入文件，向 stdout 输出一段最小的SessionResult：

{ "exit_code": 0, "final_message": "custom-engine-handled" }

http 传输快速上手：最小可用配置

engine: name: remote-review-agent custom: transport: http response_format: session_result http: url: ${CUSTOM_AGENT_ENDPOINT}/v1/run method: POST headers: Authorization: Bearer ${api_key} request_body: ${session_input}

几个关键行为（完整规则见 docs/design/custom-engine.md）：

• 未配置request_body时默认就是${session_input}；值恰为${session_input}/${messages}/${kwargs}的字段会按JSON 结构注入而不是字符串；
• 配置了custom.http.files时请求自动变为 multipart：JSON 体移入payload字段，每个匹配文件作为files表单域上传，filename携带工作区相对路径，支持src/**/*.go这类 glob；
• 非 2xx 响应按"调用错误"处理，用例结果为ERROR；
• 结果中artifacts.files[].url声明的文件会被自动下载（仅限 http/https、不跟随重定向、有大小上限）归档到报告目录。

http 传输的完整示例配置见 e2e/testdata/custom-engine/evals/eval-http.yaml。

多轮会话：conversation_mode 选 batch 还是 stateful

• batch（默认）：一次性把所有messages发给引擎，你的 Agent 只需把它们当完整对话历史处理。
• stateful：每个用户轮次调用一次引擎。首次调用不带session_id，之后每轮的SessionResult必须返回session_id（可以每次轮换），skill-up 会把它原样放进下一轮的输入；HTTP 端可用${session_id}模板放进请求体。

仓库内的多轮用例 e2e/testdata/custom-engine/evals/cases/stateful.yaml 演示了 stateful 模式下的轮次断言、变量捕获与替换；local 与 http 两种传输的 stateful 配置分别在eval-stateful-local.yaml和eval-stateful-http.yaml中。

模板变量与自定义参数：kwargs 和 env 的分工

配置中的字符串字段支持两类变量：

kwargs与env的职责不同：env放凭据和敏感值，kwargs放行为参数（如profile、max_files）。kwargs只会通过你显式声明的模板进入引擎——local走args/cwd/env，http走headers/request_body——永远不会被偷偷塞进SessionInput。

安全约束与常见坑

接入时最容易踩的坑，全部来自 skill-up 的强制安全边界（实现见 internal/agent/custom.go 与 internal/config/customengine.go）：

• 🔒凭据禁止出现在命令行：${api_key}及名字像凭据的 kwargs（token、secret等）不能引用在command/args/cwd里，只能走custom.env或http.headers；http.url中渲染${api_key}也会被直接拒绝，防止密钥泄漏到请求日志；
• 🔒路径限制：local.cwd、input_file、output_file以及结果里声明的产物路径必须落在运行时工作区内，..穿越会被拒绝；
• 📄产物必须显式声明：skill-up 不会自动扫描工作区，想进报告目录的文件必须写进SessionResult.artifacts；
• ⏱超时会合成最小结果：引擎被用例截止时间杀掉时，skill-up 会生成exit_code: 124的最小session-result.json并归档，便于排查；
• 🧾结果要能解析：返回的 JSON 缺exit_code、字段类型错误都会让用例变ERROR，成功与失败路径都要返回可解析的SessionResult。

验证自定义引擎接入是否成功

先校验配置，再跑一个最小用例：

skill-up validate ./evals/eval.yaml skill-up run ./evals/eval.yaml

想本地拉取一份完整示例来对照调试，可以克隆仓库：

git clone https://gitcode.com/gh_mirrors/sk/skill-up

跑通后你会在报告里看到引擎的final_message、transcript 与产物；接入远程服务后还可以利用回归对比查看前后两次运行的通过率、耗时变化，这正是自定义引擎接入评测闭环的价值所在：

评测运行中的观察与反馈也可以回灌到 Skill 迭代流程：

接入检查清单

完成接入前，逐项确认你的 Agent：

• 能读取SessionInput.messages并视为完整对话历史
• 成功与失败都返回可解析的SessionResult（至少含exit_code和final_message）
• 需要的kwargs通过${kwargs.<key>}显式接入
• 需要归档的文件全部写入SessionResult.artifacts
• API Key 通过${api_key}引用，未硬编码进eval.yaml
• 不依赖跨用例、跨重试的隐式会话状态

更多字段细节（SessionInput/SessionResult全量 schema、产物契约、安全模型）请阅读 docs/design/custom-engine.md；编写评测用例的完整参考见 docs/zh/guide/writing-evals.md。