Better Harness开发者指南如何为项目新增一个AI编程Agent宿主Host Adapter Matrix全流程【免费下载链接】better-harnessAn open-source Harness Engineering platform for coding agents—define harnesses as code, run controlled experiments, inspect evidence, and compare outcomes. Turn task evidence into actionable team and organization insights.项目地址: https://gitcode.com/gh_mirrors/be/better-harnessBetter Harness是一款开源的Harness Engineering 平台用于AI 编程 AgentClaude Code、Codex、Cursor、Copilot 等的受控实验与证据分析。本文面向新手带你走一遍Host Adapter宿主适配器的完整贡献流程如何为 Better Harness 新增一个 AI 编程 Agent 宿主从写 Spec、验证原生契约到实现资产清单、会话证据、注册身份与更新Host Adapter Matrix最终让你的贡献顺利合入。提示Better Harness 的哲学是证据说话——每一个支持声明support claim都必须有对应的验证路径缺失的证据会被明确标注而不是被猜测填补。一、先搞懂什么是 Host AdapterHost Adapter 不是一个简单的插件清单而是一组独立验证的支持声明它把 Better Harness 接到一个具体的 AI 编程 Agent 宿主上。按 docs/community.md 的定义一个宿主适配由多个切片slice组成切片说明归属路径原生契约宿主的版本、安装命令、发现顺序docs/specs/中的日期化 Spec宿主壳Shell安装/发现元数据如.claude-plugin/、qwen-extension.json各宿主元数据根目录已配置资产Configured Assets清点用户/项目/插件各作用域的 Skills、Rules、MCP 等scripts/agent-customize/providers/会话证据Session Evidence读取本地会话记录并归一到工作区scripts/session-analysis/platforms/输出与打包Canvas / HTML / Markdown 报告路由、npm 打包templates/reporting/核心原则只有一条壳shell不能证明会话支持解析器也不能证明 Skill 可被原生发现。只实现宿主真正支持的切片其余明确标注为 partial 或 unavailable。当前已支持的宿主一览见 docs/adapters/README.mdHost Adapter Matrix完整能力宿主Qoder、Cursor、Claude Code、Codex、Qwen Code、GitHub Copilot、Pi、Kimi Code、WorkBuddy、Grok、DeepSeek HarnessDSH每个宿主的定位 / 壳 / 资产 / 会话证据 / 默认输出 / 冒烟命令都在矩阵表格中一行列清二、动手前读这三份文档在提交任何代码前官方贡献指南 docs/adapters/contributing-new-coding-agent.md 要求你先读完以下材料确保理解目录归属与契约边界 AGENTS.md仓库级 Agent 指令含 Spec 撰写要求 CONTRIBUTING.md贡献流程与项目搭建 docs/ARCHITECTURE.md架构原则与 docs/adrs/directory-structure.md目录归属 ADR下面按 8 个步骤走完全流程。三、步骤 1在 docs/specs/ 下写日期化 SpecSpec 是整个贡献的合同。参考已合入的实例 docs/specs/2026-08-02-grok-host-adapter.md它清楚列出了Host id 与已验证版本如grok Grok CLI 0.2.xSupport slices 表每个切片是 Claimed / Partial / Unavailable并写明 canonical ownerAcceptance ids如Grok-A1、Grok-S2每个 id 对应一条可验证的验收标准明确 Non-goals例如本 PR 不做 npm 打包、不读auth.json密钥对不确定的宿主契约用[NEEDS CLARIFICATION: ...]标注绝不靠猜测。四、步骤 2验证原生宿主契约最关键一步官方强调Do not derive a new host contract by renaming another adapter——不要通过复制改名另一个宿主的适配器来发明契约。你需要用宿主的版本化官方文档或源码验证原生 manifest 文件名、schema、发现顺序、安装/链接命令配置、运行时、缓存、会话根目录以及环境变量与 CLI 覆盖的优先级工作区身份识别与路径归一化空格、Unicode、Windows 盘符、大小写、符号链接会话事件结构、调用/结果关联、终态状态、压缩与子 Agent 字段隐私边界哪些字段含凭证或用户内容、绝不能离开本地机器 仓库提供了现成的检索命令帮你做身份清单rg -n host-id|Host Display Name scripts test references templates docs package.json把真实宿主数据仅用于有界的本地冒烟提交的是确定性的、合成且脱敏的 fixture永不提交原始会话、提示词或凭证。五、步骤 3保持宿主壳Shell足够薄只有当宿主原生需要时才添加元数据根目录如.kimi-plugin/plugin.json。壳的职责仅仅是安装与发现元数据、指向 canonical 根 Skills❌ 不能把产品判断、评分规则、证据规则、报告契约复制进壳里✅ canonical 判断始终留在skills/、models/、references/、templates/与能力自有的scripts/capability/如果壳要随公开 npm 包发布需对齐包版本、加入包白名单与校验器并用真实宿主 CLI 证明原生发现能力。六、步骤 4实现 Configured-Asset Provider在 scripts/agent-customize/providers/ 下新增host.mjs例如 grok.mjs。Provider 需要做到区分 Plugin / user / project / inherited 各作用域遵循原生优先级与生效启用判断尊重宿主文档化的 CLI 与环境变量覆盖包括空值与畸形值不静默回退到无关数据输出审查所需元数据但不序列化秘密值身份/信任/归属不明时fail closed明确失败而非猜测实现后在 scripts/agent-customize/providers/index.mjs 的PROVIDER_COLLECTORS中注册并顺着 host id 追踪所有声称支持配置资产的公开路径inventory、lint、evidence-bundle、help、report。七、步骤 5实现 Session Evidence只有站得住脚才做在 scripts/session-analysis/platforms/ 下新增host.mjs。以 grok.mjs 为例它做了四件关键的事工作区限定会话必须先匹配到请求的工作区通过encodeURIComponent(cwd)编码目录名匹配外来工作区的会话绝不进入报告归一化字段只归一化观察到的字段缺失的 token 用量标为unobserved而非 0未知事件保留不认识的updates.jsonl事件作为元数据保留不静默丢弃调用/结果关联用原生 id 确定性回退策略关联工具调用与结果最终效果长这样——每个提示、工具调用与提交都有可见的证据来源如果本地会话不可用、不稳定、加密或无法安全匹配工作区就如实把 session evidence 标注为 unavailable——壳和资产支持仍可独立合入。八、步骤 6传播宿主身份有意识地在 scripts/host-support/index.mjs 中注册稳定身份、显示名、home-option 与独立验证的支持切片。不要默认声明所有能力Kimi 和 Grok 就不出现在 Checkup 能力中尽管它们的资产与会话适配器可用。典型需要触碰的注册面注册面路径作用生命周期影子 Profilescripts/host-support/profiles/声明 install/status/verify 处置用共享构造器勿复制注册逻辑资产 Provider 索引scripts/agent-customize/providers/index.mjs配置资产清点路由会话分析器scripts/session-analysis/analyzer.mjs平台加载与 help 契约证据包scripts/harness-analysis/evidence-bundle/Provider 校验与路由⚠️ 黄金法则宁可返回一个可见的不支持错误也不要让 host id 悄悄落到另一个 Provider 上。目录推导出的门禁必须 fail closed。九、步骤 7搭证据阶梯 冒烟验证把测试映射到 Spec 的 acceptance ids。最低限度覆盖以下风险风险需要的 fixture / 检查发明原生契约钉住的官方文档引用 原生 CLI 冒烟路径不匹配POSIX 与 Windows 路径、空格、Unicode、大小写、符号链接错误的 home 或优先级CLI 覆盖、环境变量覆盖、默认值、空值与畸形值外来工作区证据正向 负向工作区限定 fixture事件丢失或虚增未知事件、缺失字段、调用/结果关联、所有终态状态秘密泄漏凭证形态 fixture 值级不泄露断言打包漂移manifest 存在性/版本断言 npm run pack:verify提交前运行完整验证链node scripts/doc-link-graph/cli.mjs skills/better-harness npx vitest run test/skills-docs/doc-link-graph.test.mjs npm test npm run pack:verify git diff --checkCI 必须覆盖Windows、macOS、Linux三个平台跨平台路径行为。原生冒烟应分别证明原生发现、配置资产、会话源/事实、证据包传播、验证过的报告渲染——参考 Codex 宿主的 marketplace 安装方式做对照十、步骤 8更新 Host Adapter Matrix 与交付边界最后一步是文档在 docs/adapters/README.md 的矩阵中新增一行写明定位、壳、配置资产、会话证据、默认输出、Rules/Prompts、可复现冒烟路径。只有满足Split Triggers发现/冒烟指引超一屏、独立发布生命周期、证据被两个以上能力引用、prompt 契约改变生成物、矩阵难以浏览才为宿主单独建docs/adapters/host.md页面。Pull Request 中需要说明宿主/版本与主要契约证据、声明与不可用的切片、Spec 与 acceptance ids、聚焦/全量/原生/跨平台/打包测试结果、隐私与回滚风险、AI 参与度与人工验证内容。十一、Definition of Done 快速自检清单合入前对照 docs/adapters/contributing-new-coding-agent.md 的完成定义过一遍✅ Spec 逐条点名了 claimed / partial / unavailable 切片✅ 每个发现与数据布局声明都有原生宿主/版本证据背书✅ 壳元数据足够薄存在时独立冒烟✅ 注册与实际实现的能力一致不存在跨宿主回退✅ 每个宿主的 lifecycle profile 可独立导入argv 数组 契约证据齐全✅ 矩阵、能力参考、安装文档与实际交付行为一致写在最后为 Better Harness 新增一个 AI 编程 Agent 宿主本质是用证据链把支持二字说扎实一份日期化 Spec、一条可复现的冒烟命令、一行清晰的 Host Adapter Matrix 记录。你可以从 docs/adapters/contributing-new-coding-agent.md 入手参考 docs/specs/2026-07-30-kimi-host-support.md 与 docs/specs/2026-08-02-grok-host-adapter.md 两个真实案例——它们分别演示了部分适配器先行和资产会话HTML 渲染一步到位两种落地节奏。祝你贡献顺利【免费下载链接】better-harnessAn open-source Harness Engineering platform for coding agents—define harnesses as code, run controlled experiments, inspect evidence, and compare outcomes. Turn task evidence into actionable team and organization insights.项目地址: https://gitcode.com/gh_mirrors/be/better-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考