Surface 一致性与互操作

互操作意味着独立客户端与宿主在可观察协议行为上达成一致。它不要求双方使用 Pling 包、共享数据库，或通过一份未公开的厂商清单。

0.1 仓库没有发布第三方 Surface 认证计划。不存在公开一致性徽章、认证厂商名单，也不声称通过仓库内测试就等于符合行业标准。现有的是可执行参考实现、包级测试、委托与连续性的适配器一致性工具，以及可复现案例。这些是证据，不是认证。

Surface 必须具备的行为

声称实现 pling.surface/0.1 的实现，应能展示以下可观察契约。

1. 版本与方法

• 接受精确协议字符串 pling.surface/0.1；
• 其他版本返回 PROTOCOL_VERSION_UNSUPPORTED；
• 只实现 describe 与 invoke；
• 对 attach、observe、handoff、detach 或未知方法返回 METHOD_NOT_SUPPORTED，除非未来版本明确规定；
• 只要请求 id 可解析，响应必须保留它。

2. 能力投影

• 返回稳定能力 id、说明、效果、输入 schema、确认要求、保真度与适用的记录模板元数据；
• 站点白名单与会话范围取交集；
• 不暴露执行器实际无法路由的能力；
• 禁止的 id 应表现为不可见，而不是泄露内部拒绝细节；
• 区分 read、write、destructive；
• 宿主支持派生时，保留开发者声明与派生来源。

3. 有界上下文

• 只返回调用方请求且受宿主上限约束的记录窗口；
• 记录被截断时报告总数与窗口信息；
• recordIds 足以引用视口外记录，但不能把不可见记录描述成可见；
• 排除原始 DOM、截图、Cookie、token 与无关 store 状态；
• 使用与页面内助手相同的脱敏规则。

4. 调用

• 在副作用前校验能力与输入；
• 可用性、确认、人工接力、期望与证据都复用现有执行器；
• 业务拒绝返回成功协议包络中的 result.error；
• 不把业务错误变成协议错误，也不把协议错误说成重试指令；
• 只在确有变化且有界时返回增量 after 观察；
• 不执行会话暴露范围之外的能力。

5. 会话与访问控制

• 身份只来自已验证传输或后端；
• 会话缺失、非法、过期、撤销或跨用户时 fail-closed；
• 会话范围或有效期变化时重置能力缓存；
• token 解析不进入协议内核；
• 撤销必须在下一个副作用之前生效，而不是等通知到达后。

6. 限流与防重放

• 按已验证会话或开放模式桶执行限流；
• 限流时尽可能返回 retryAfterMs；
• 共享限流器或防重放守卫不可用时 fail-closed；
• 在 invoke 副作用前占用 (session, request.id)；
• 重复意图不得再次执行；
• 不得声称防重放缓存了响应；客户端必须核对业务状态。

7. 审计

• 记录身份、能力、请求 id、结果、稳定错误码、耗时与可用的审批关联；
• 默认排除参数、响应正文、凭证与服务商密钥；
• 审计出口失败必须进入可观察错误路径；
• 审批回执 token 或哈希不得进入 Agent 可见响应。

传输互操作

协议不强制单一传输。合法适配器可以使用 HTTP JSON、浏览器 postMessage、进程内函数调用或 MCP facade。适配器仍负责：

• 验证调用方；
• 执行来源与 CSRF 规则；
• 校验请求体大小与媒体类型；
• 在不改变错误语义的前提下映射协议包络；
• 注册工具时不凭空增加能力；
• 返回完整协议响应，包括 ok: false；
• 保留请求 id，不静默重试副作用。

MCP 客户端应看到每项投影能力对应一个工具，schema 来自 describe。通用 click(selector)、eval、原始 fetch 或“执行任意 JavaScript”工具不属于本协议，即使 MCP server 技术上可以做到。

现有自动检查

范围	现有检查	能证明什么	不能证明什么
Surface 内核	packages/surface/test/surface.test.ts	投影、会话、限流、防重放、审计与包络的参考行为	另一个实现符合协议
委托存储	assertDelegationStoreConformance()	token 脱敏、范围归一化、轮换、绑定、撤销、过期	测试命名空间之外的企业 SSO 或数据库事务一定正确
委托事件	assertDelegationEventBusConformance()	按用户隔离与事件字段白名单	真实拓扑中的 Redis/NATS/outbox 投递
连续性后端	assertContinuityBackendConformance()	租约、revision、所有权、接管、过期与用户隔离	浏览器 UI 正确解释每种失败
MCP 适配	本地 MCP 参考实现	一条经过现有执行器的具体外部工具链	对所有 MCP 客户端的通用认证
基准工具	订单与入网向导基准夹具	两份冻结任务集上的可重复结果	普遍的 token 或成功率优势

基准报告的范围很窄。单站点订单任务集报告 Surface/MCP 与 DOM/Playwright 均为 60/60 通过，中位步数比为 0.4286，token 比为 0.5085。供应商入驻任务集是第二份独立任务集，结果混合，并且没有在不同厂商模型上复现 token 优势。两者都不是跨站点或统计保证。

一项实用的互操作测试

让两个独立客户端跑同一个小应用：

1. 从未登录状态调用 describe，应得到会话失败，而不是空的成功响应。
2. 授权两个普通能力与一个记录级动作。
3. 确认 describe 只暴露这些 id，并返回一页有界记录。
4. 用不同请求 id 调用两次只读能力，都可成功。
5. 用稳定 id 调用写入能力，再重放同一包络，确认没有第二次副作用。
6. 调用隐藏能力 id，确认得到 CAPABILITY_NOT_EXPOSED，且业务存储未变化。
7. 过期或撤销会话后重试，确认执行器之前就得到会话错误。
8. 令审计出口失败，确认业务响应仍有定义，失败在运维侧可观察。
9. 写入过程中关闭传输，重连后先核对业务状态，再判断新请求 id 是否安全。

记录实现版本、协议版本、传输、身份适配器、任务集与精确构建。缺少这些字段的结果不构成可复现证据。

措辞边界

应使用精确说法：

• “在参考测试套件中实现了 pling.surface/0.1 的 describe 与 invoke 行为。”
• “在一次性命名空间上通过仓库的委托存储一致性检查。”
• “在记录模型与构建的单站点订单任务集上复现。”

避免：

• “Pling Surface 认证。”
• “符合行业标准。”
• “对所有 Agent 都安全。”
• “兼容所有 MCP 客户端。”
• 没有任务集、基线与指标时宣称“比浏览器自动化更快”。

未来可能出现公开一致性套件；在它被版本化、发布并可独立使用之前，任何页面或实现都不应暗示它已经存在。

版本与兼容性

项目	取值
适用版本	@plingjs/surface 0.1.0-alpha.2
协议	pling.surface/0.1（Draft）
引入版本	0.1.0-alpha.2（首个发布的 alpha）
运行环境	支持 ES2022 模块的浏览器；Node 侧使用需 Node.js 20 或更高版本
Peer 依赖	无
稳定性	草案协议；不提供公开认证声明

仓库中的夹具通过，只能证明该夹具下的结果，不能据此宣称兼容所有传输、身份提供方或 MCP 客户端。每次记录结果时都应写明包版本、协议版本、传输与夹具。