ds-harness-remote-fast/docs/design/protocol-schema-alignment.md

49 lines
3.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Protocol Schema 对齐设计
更新时间:2026-10-08;关联 [Issue #34](https://github.com/liguobao/ds-harness-remote/issues/34)。
## 目标与当前状态
[protocol.md](../protocol.md)是 wire contract 权威来源,`packages/protocol` 提供共享类型与运行时校验。
已有 Control / Account / Connect / Relay 等 schema、frame/counter 边界测试、Noise IK vector 和跨仓库 fixtures。
Control 全部帧类型和 Relay data envelope 已有 conformance fixtures。
完整 schema 逐项对齐、剩余 golden vectors、独立加密审查与真实 runtime conformance 仍见[TODO](../TODO.md)。
不把 fixture 通过描述成所有领域 schema 已齐全或所有平台已验收。
## 对齐范围
- hello/hello.ack 的版本拒绝、capability 协商与 limits。
- Account authorization、Host 注册码、设备注册/刷新与 Browser 授权交换。
- Connect、Noise 握手 forwarding、Relay、Signaling、Error 和关闭状态。
- Harness Typert tunnel、事件及有界 transfer。
- CodeX / ACP 独立 RPC、stream、transfer、capability 和工作区类型。
- 原生只读文件、终端输入权、loopback 固定目标限制,以及各领域工具 scope。
不复制 Harness 官方业务对象的完整 schema,不新增另一套 Session / Message / Permission wire format。
本仓库最小 Server 复用规定的子集;完整 Server / Remote Web runtime 仍由独立仓库维护。
## 变更流程
1. 对照协议章节、共享 schema 和消费端列出具体差异。
2. 明确字段的必需性、未知字段策略、版本兼容、capability 与限额。
3. 同步更新协议、共享类型和实际 Host/Client 接入;新增字段采用可验证的加法兼容。
4. 为核心安全边界补正反场景;同一契约的变体用命名场景矩阵,共享 hooks,失败后报告具体场景并继续同组其他场景。
5. 将可跨仓库复用的场景保存在 `fixtures/protocol/v1`;不使用生产账号、真实凭据或用户数据。
6. 在消费端检查其独有的接入、状态与恢复行为;跨端 conformance 在真实目标 runtime 执行。
## 验证入口
- `packages/protocol/tests/conformance-fixtures.test.ts` 按操作及 Control frame 类型组织 fixtures。
- `fixtures/crypto/v1/noise-ik.json` 与 Crypto 测试验证确定性 Noise vector。
- Plugin、client-core 与 transport 测试分别覆盖 allowlist、关联、权限、隔离与恢复。
- 最小 Server 测试覆盖其授权、Control 和 Relay 子集;不代表完整 Server 或部署 E2E。
数量以当前 CI 为准,不因矩阵合并减少边界场景,不通过 skip/exclude 隐藏失败。
单纯源码字符串、布局、图标、配色、文案不属于协议测试预算。
## 完成标准
每项差异有文档/schema/消费端一致的证据,非法版本、字段、尺寸、counter、scope 与权限均 fail closed。
fixtures 可离线、隔离地执行;跨仓库合同和真实 runtime 的验收分别记录。
共享类型/生产构建、核心测试与 Bundle 校验通过后,仍需明确未覆盖的平台和部署边界。