企业官网建设流程全解析

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-harness

Better Harness是一款开源的Harness Engineering 平台，用于AI 编程 Agent（Claude Code、Codex、Cursor、Copilot 等）的受控实验与证据分析。本文面向新手，带你走一遍Host Adapter（宿主适配器）的完整贡献流程：如何为 Better Harness 新增一个 AI 编程 Agent 宿主，从写 Spec、验证原生契约，到实现资产清单、会话证据、注册身份与更新Host Adapter Matrix，最终让你的贡献顺利合入。

提示：Better Harness 的哲学是"证据说话"——每一个支持声明（support claim）都必须有对应的验证路径，缺失的证据会被明确标注，而不是被猜测填补。

一、先搞懂：什么是 Host Adapter？

Host Adapter 不是一个简单的插件清单，而是一组独立验证的支持声明，它把 Better Harness 接到一个具体的 AI 编程 Agent 宿主上。按 docs/community.md 的定义，一个宿主适配由多个"切片（slice）"组成：

核心原则只有一条：壳（shell）不能证明会话支持，解析器也不能证明 Skill 可被原生发现。只实现宿主真正支持的切片，其余明确标注为 partial 或 unavailable。

当前已支持的宿主一览，见 docs/adapters/README.md（Host Adapter Matrix）：

• 完整能力宿主：Qoder、Cursor、Claude Code、Codex、Qwen Code、GitHub Copilot、Pi、Kimi Code、WorkBuddy、Grok、DeepSeek Harness（DSH）
• 每个宿主的"定位 / 壳 / 资产 / 会话证据 / 默认输出 / 冒烟命令"都在矩阵表格中一行列清

二、动手前：读这三份文档

在提交任何代码前，官方贡献指南 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/ 下写日期化 Spec

Spec 是整个贡献的"合同"。参考已合入的实例 docs/specs/2026-08-02-grok-host-adapter.md，它清楚列出了：

1. Host id 与已验证版本（如grok+ Grok CLI 0.2.x）
2. Support slices 表：每个切片是 Claimed / Partial / Unavailable，并写明 canonical owner
3. Acceptance ids：如Grok-A1、Grok-S2，每个 id 对应一条可验证的验收标准
4. 明确 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 为例，它做了四件关键的事：

1. 工作区限定：会话必须先匹配到请求的工作区（通过encodeURIComponent(cwd)编码目录名匹配），外来工作区的会话绝不进入报告
2. 归一化字段：只归一化"观察到的"字段；缺失的 token 用量标为unobserved而非 0
3. 未知事件保留：不认识的updates.jsonl事件作为元数据保留，不静默丢弃
4. 调用/结果关联：用原生 id + 确定性回退策略关联工具调用与结果

最终效果长这样——每个提示、工具调用与提交都有可见的证据来源：

如果本地会话不可用、不稳定、加密或无法安全匹配工作区，就如实把 session evidence 标注为 unavailable——壳和资产支持仍可独立合入。

八、步骤 6：传播宿主身份（有意识地）

在 scripts/host-support/index.mjs 中注册稳定身份、显示名、home-option 与独立验证的支持切片。不要默认声明所有能力：Kimi 和 Grok 就不出现在 Checkup 能力中，尽管它们的资产与会话适配器可用。

典型需要触碰的注册面：

⚠️ 黄金法则：宁可返回一个可见的"不支持"错误，也不要让 host id 悄悄落到另一个 Provider 上。目录推导出的门禁必须 fail closed。

九、步骤 7：搭证据阶梯 + 冒烟验证

把测试映射到 Spec 的 acceptance ids。最低限度覆盖以下风险：

提交前运行完整验证链：

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 --check

CI 必须覆盖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