企业官网建设流程全解析

openharness（Autonomous Harness）是一个"指挥中心"，把 Claude Code、Codex 等所有编码 Agent 和你的多台机器集中管理。而它的Provider 规范，正是把你自己的 Agent 平台变成 openharness 里一台"机器"（machine）的标准协议：用户只需填入一个 URL + 一个凭证，就能从 Web 应用或桌面设备直接驱动你的 Agent 后端。本文完整解读这套 provider 规范的数据模型、8 个方法、事件流与合规检测，帮你快速自建可接入的 Agent 后端。

什么是 Provider 机器？

通常 openharness 的"机器"跑的是用户自己电脑上的 CLI。而Provider 机器把这台机器背后的引擎换成你的 Agent 平台——你暴露一个 HTTPS 接口，openharness 负责把会话、取消、历史这些交互转发给你。

关键卖点：JSON-RPC 2.0 over HTTPS，单个 URL，8 个方法，无 SDK，无需能力协商。只要能返回 JSON over HTTPS，一个下午就能实现。

完整契约见 provider/spec/README.md，入门清单见 provider/spec/onboarding.md。

核心模型：machine / agent / turn

Provider 规范只有三层概念，没有 session、thread、conversation：

machine 一个 provider 端点 + 一个凭证 ← 用户创建并付费的对象 └── agent 其中一个工作单元 ← 用户挑选并对话的对象 └── turn 一条用户消息直到 Agent 停止

一个 agent 就是一份连续记录（transcript）。openharness 对 provider 机器不存储任何记录，所以历史必须保存在你那边——这也是agent.history成为必选方法的原因。

八个方法速览

8 个方法全部必选，这就是全部接口，无需声明任何能力：

⚠️"必选"不等于"硬装"。如果你的 Agent 在自家产品内部管理，不要用假实现糊弄——直接返回带提示语的invalid_request（如"Agents are managed in Example Co"），这条消息会直接展示给用户。同理，从不生成摘要的 provider 就返回空recap，openharness 会从 turn 自身文本推导一个。

认证与安全

• 凭证由用户在 Web 应用里粘贴，随后每个请求都通过Authorization: Bearer <credential>发送。固定一个头部约定，无需额外声明。
• 一个凭证只对应一个租户，不能越权访问。
• 凭证被拒必须返回unauthenticated错误码（并建议 HTTP 401），而非通用失败——否则产品无法区分"凭证填错了"和"provider 挂了"。

所有错误码都是字符串：

安全要求：全程 TLS，端点必须是稳定、可公开解析的 HTTPS URL（不能是 IP 或移动隧道）。Provider 发送的一切都视为不可信输入，openharness 后端会逐帧校验与白名单。

事件流与事件词汇表

agent.send返回Content-Type: text/event-stream，每帧一个 JSON 对象（data:帧）。流式不可选，因为产品边到边渲染。事件对象扁平且自描述，同一 schema 既用于实时流、也用于agent.history，保证"回放的历史"和"实时画面"不会对同一事件产生分歧（见 provider/spec/schema/event.json）。

两条流保证：

1. 它必然结束，且恰好一次。每条流以一个终结帧收尾：turn_completed/turn_failed/turn_cancelled/turn_input_required。
2. 帧内内容可渲染。事件按kind区分；不认识的kind被忽略而非致命。若完全没有kind但带text，是合规的，渲染为纯助手输出——最小的合规 provider 就是发一条{"text":"…"}再发{"kind":"turn_completed"}。

常用kind（工具调用必须携带同一且 turn 内唯一的toolId）：

向用户提问：以turn_input_required（携带prompt）结束流，随后接受一个相同turnId、resume:true的agent.send作为回答，继续同一 turn。流会刻意关闭而非保持挂起——因为人的决策没有时间边界。

合规检测（conformance）

reference-provider自带一个合规运行器，指向任意provider 端点即可自检。通过标准：零失败（warnings / skips 属正常，会打印原因）。

cd provider/reference-provider npm run conformance -- --url https://your-endpoint --key <credential> \ --bad-key <故意无效的凭证> --ask-phrase "<会触发提问的 prompt>"

每个检查项都有稳定id，一行红字就指向一条具体规则，而不是模糊的"某处错了"。运行器覆盖 25 项检查（可达性、HTTPS、凭证被拒、agent 列表、SSE 流、恰好一个终结帧、取消支持、历史匹配流、事件种类、工具配对、recap 等）。其中 5 项无法从外部验证、需人工复核：租户隔离、截断标志、统计伪造、速率限制、凭证是否被记录。

两个官方示例

• reference-provider（provider/reference-provider/）：不跑任何模型，纯node:http，可从头读到尾，还内置了"敌对"场景（缺终结帧、发 JSON 而非 SSE、坏凭证被接受……）用来硬化客户端。
• example-provider（provider/example-provider/）：真实驱动 Claude CLI，回答"真实 Agent 流部分 token、调工具、恢复会话、自管历史"时协议是否依然成立。其src/mapper.ts是唯一把 Claude 形态映射成 provider 事件的地方，实时与历史两条路径共用，从根上避免"刷新后视图"与"实时视图"打架。

两者还有跨实现的端到端测试 provider/e2e/README.md，用 fakeclaude跑，验证规范不仅自洽、还可被独立实现。

快速上手：从"看它跑起来"到"接入产品"

1. 先跑通参考实现：cd provider/reference-provider && npm install && npm run dev，再用curl发一个agent.list，看到text/event-stream响应。
2. 实现你的 8 个方法：单 URL、JSON-RPC 2.0 over HTTPS、agent.send走 SSE。
3. 用运行器自检：把上面 conformance 命令指向你的端点，零失败才算达标。
4. 提交接入：把端点 URL、合规输出、人工复核问题的书面答复、技术联系人发给 openharness（见 provider/spec/onboarding.md）。
5. 进入浸泡测试：openharness 会用真实流量压你的端点（完整 turn、早期取消、提问往返、刷新重建记录、端点抖动、凭证吊销提示），通过后才在产品中可选。

小结

openharness 的 Provider 规范把"接入你自己的 Agent 后端"压缩到一个 URL + 一个凭证 + 八个方法：模型只有 machine/agent/turn 三层，历史与摘要都在你侧，事件流靠"恰好一个终结帧"和"帧内自描述"两条保证，再用零失败的合规运行器自检。无论用脚本化的 reference-provider 还是真实驱动的 example-provider 起步，你都能在半天内让自家 Agent 平台出现在 openharness 的指挥中心里。