diff --git a/docs/openclaw-integration/README.md b/docs/openclaw-integration/README.md new file mode 100644 index 0000000..5d5c673 --- /dev/null +++ b/docs/openclaw-integration/README.md @@ -0,0 +1,32 @@ +# openclaw-java-sdk · OpenSpec 文档包 + +版本 0.1.0-draft · 2026-09-20 · **待评审,未实施,未归档** + +这是一套仓库内的 OpenSpec 变更草案,不是仅供讨论的差距清单。包含六组 proposal/design/tasks、21 个 capability spec、64 条 Requirement 和 128 个 Scenario;任务共 97 项,其中 7 项 G0 准入证据任务已勾选,90 项待完成。SDK 功能尚未按这些草案实施;检查结果见 [文档检查结果](validation-summary.md)。 + +## 阅读顺序 + +1. [总体路线与依赖](roadmap.md)。 +2. [当前覆盖与风险基线](coverage-baseline.md)及[来源登记](source-register.md)。 +3. `openspec/changes//proposal.md` → `specs/*/spec.md` → `design.md` → `tasks.md`。 +4. [验收计划](acceptance-plan.md)及[逐场景追踪表](traceability.md)。 + +## 交付边界 + +本目录及 openspec/ 以独立文档提交交付;没有修改任何 SDK Java 源码、pom、依赖或现有测试。G0 已记录目标版本和来源,但该锁定仍待人审确认;G1 编码继续受评审门禁约束。 + +首次文档编制时仅执行自定义结构检查;后续 G0 证据提交记录了三分支 CodeGraph、Maven 构建与测试,以及 OpenSpec 1.8.0 strict 校验。2026-11-18 使用 OpenSpec 1.14.1 对本分支再次执行 `openspec validate --all --strict --no-interactive --json`,6/6 changes 有效。历史构建证据对应 2026-09-20 的 SDK 提交。2026-11-18 补充了 [真实 Gateway 基线验证](../../openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-live-gateway.md),覆盖三条维护线并记录默认分支的兼容缺口。 + +## 合入方式 + +`openspec/` 和 `docs/openclaw-integration/` 按仓库相对路径组织。先在文档专用分支审查再合入;如果目标分支后来已有同名规范或目录,需合并而不是覆盖。本文是迁入文档目录后的交付索引,不覆盖原仓库 README。 + +本轮没有创建任何生效 capability spec;`openspec/specs/` 只有占位文件。待变更实现、验收和人审完成后,再按项目流程归档。根目录 `openspec/config.yaml` 定义 spec-driven 模式和项目规则。 + +## 快速核对 + +查看 `docs/openclaw-integration/baseline.json` 确认首次文档编制时的 SDK 提交,再阅读 G0 的 `evidence/` 目录了解后续验证。OpenSpec 格式校验通过不代表产品实现完成。 + +## 发布打包说明 + +原始文档包的 traceability.json 使用 gzip 保存为 .json.gz;validation-report.json 使用 gzip + Base64 分段保存在 [validation-report/](validation-report/README.md),该目录说明如何恢复原始 JSON。两份解压后的 JSON 与原包逐字节一致;README 和检查摘要已按后续证据修订,当前文件校验值见 [package-manifest.json](package-manifest.json)。修订不改变任何 Requirement 或 Scenario。 diff --git a/docs/openclaw-integration/acceptance-plan.md b/docs/openclaw-integration/acceptance-plan.md new file mode 100644 index 0000000..97ef840 --- /dev/null +++ b/docs/openclaw-integration/acceptance-plan.md @@ -0,0 +1,70 @@ +# 验收计划与证据模板 + +本文件定义未来验收要求,不记录已通过的产品测试。本轮仅执行文档内部检查。 + +## 1. 验证层级 + +| 层级 | 内容 | 可支持的结论 | +|---|---|---| +| L0 文档结构 | 四类产物、格式、ID、来源、依赖、任务引用 | 文档内部一致;不证明产品行为 | +| L1 契约样本 | 固定版本的请求/响应/事件黄金样本 | 序列化、解析与本地状态规则 | +| L2 模拟故障 | MockWebServer、受控 WS 端点、虚拟时钟、测试子进程 | 并发、顺序、关闭和错误路径 | +| L3 分支构建 | JDK 8、17、21 对应分支和真实依赖源 | 各自构建及实际执行的测试结果 | +| L4 真实集成 | 固定版本 Gateway、受控账户/工作目录、明确授权 | 指定版本、场景、权限配置的真实兼容 | +| L5 发布审查 | API、依赖、扫描、许可证、资源与文档 | 有边界的发布准入,不是绝对无漏洞保证 | + +L1/L2 的模拟成功不能替代 L4。静态找不到关闭路径可以作为风险线索,但不自动断言已经证明堆泄漏。 + +## 2. 最低核心场景 + +Responses:JSON 入口误用流式、多个输出项、工具参数增量、空工具输出续接、completed/incomplete/failed、EOF、取消、格式错误。WS:追加、替换、快照对账、未知 runId、双流交错、终态重复、会话 reset 后旧事件。认证:challenge/计时器竞争、有/无 deviceToken、可信与不可信引导、轮换、scope 拒绝。恢复:断线前后写入结果未知、订阅/快照交错、错误回调、资源释放、用户关闭后零重连。 + +控制面:agent 受理与 pending 等待、远端取消未确认、并发审批已决、配置 hash 冲突、保存/应用分离、Cron 按准确 runId 查询。运营面:目录不等于权限、工具业务 ok=false、扩展发布部分成功、目标账户隔离、Node 执行状态未知、用量缺省、产物下载过期与跨域。可选适配:终端附着不重跑、语音输出取消、MCP/ACP 初始化、双向管道、stderr 分离、进程退出、CLI JSON 模式和 Windows/POSIX 参数。 + +## 3. 资源检查的可测口径 + +在受控环境执行 1000 次请求/订阅生命周期(成功、失败、取消、超时各不少于 200 次,其余用于断线和回调错误)。每轮结束后等待有界清理预算(测试基线建议 5 秒,若需调整必须记录理由),确认 pending 请求、活动订阅和定时任务注册归零;关闭后自有 executor 终止、HTTP ResponseBody 关闭,共享连接仍可供第二客户端使用。 + +这不是对堆大小强行断言恒定。若出现持续增长,应采集堆转储、线程转储、对象引用与文件描述符证据,并在稳定负载和 GC 条件下定位。不得通过关掉断言或增大无限队列来“修复”检查。 + +## 4. 安全与错误语义 + +必须确认:不以 dryRun 当作无副作用;不以共享 Gateway Token 的 scope 头当作租户隔离;不自动批准;不自动读取宿主凭据或降级权限;不记录 Token、签名、短期下载地址或原始敏感业务内容。取消/等待超时/结果不确定/远端失败分开;工具、配置、插件等分阶段结果不被压成一个布尔成功。 + +真实写操作测试只能在获准的隔离环境运行,使用临时命名空间和明确清理步骤。文档任务不会授权访问真实客户、发送业务消息或修改生产配置。 + +## 5. 证据记录字段 + +```yaml +change_id: fix-openclaw-protocol-contracts +requirement_id: CHAT-01 +scenario_id: CHAT-01-S1 +branch: feature/2.0.x +sdk_commit: null +openclaw_version: null +openclaw_commit: null +protocol_version: null +jdk_version: null +maven_version: null +auth_mode: null +test_command: null +executed_tests: 0 +result: NOT_RUN +evidence_path: null +known_limitations: [] +``` + +null 明确表示尚未运行,不得提交为 PASS。PASS 记录须填精确值;缺环境填 BLOCKED,未跑填 NOT_RUN,失败填 FAIL。测试基线版本改变需要重新执行。 + +## 6. 官方 OpenSpec 校验命令(待实际运行) + +先在可联网、受信任环境安装并记录官方 OpenSpec 的确定版本,再从仓库根目录运行: + +```bash +openspec --version +openspec list --json +openspec validate --all --strict --no-interactive --json +openspec status --change fix-openclaw-protocol-contracts --json +``` + +不使用 latest 作为可复现 CI 的版本锁。不在本轮执行 apply、archive 或产品代码生成。官方 CLI 结构通过也不等于 128 个产品验收场景已经执行。 diff --git a/docs/openclaw-integration/baseline.json b/docs/openclaw-integration/baseline.json new file mode 100644 index 0000000..2bdaea1 --- /dev/null +++ b/docs/openclaw-integration/baseline.json @@ -0,0 +1,122 @@ +{ + "documentVersion": "0.1.0-draft", + "date": "2026-09-20", + "repository": "easy-4-java/openclaw-java-sdk", + "sdkBaseline": { + "feature/1.0.x": "8cfbeb880a6c6ae5390fab0f9fe65e06938907be", + "feature/2.0.x": "48309d7bc34c4298cdfa1c52db06114b2e7e9f17", + "feature/3.0.x": "3687fcb09e75ec4c2ecb522877e9a27c1f1955aa", + "main": "c4ddcd3fa86d8fb5352b722813268760c35636b2" + }, + "upstream": { + "documentationBasis": "live-official-documentation", + "documentationObservedDate": "2026-09-20", + "documentedProtocol": "v4", + "testedGatewayVersion": null, + "testedGatewayCommit": null, + "pinStatus": "BLOCKED_VERSION_PIN", + "rawPageSnapshotArchived": false + }, + "verification": { + "sourceReview": "static-review-only", + "codegraphExecuted": false, + "sdkBuildExecuted": false, + "liveGatewayTestsExecuted": false, + "officialOpenSpecValidationExecuted": false, + "structuralValidation": "see validation-report.json" + }, + "approval": { + "state": "DRAFT", + "implementationAuthorized": false, + "archiveAuthorized": false + }, + "delivery": { + "createdIn": "conversation-sandbox", + "githubCommitted": false, + "userMachineModified": false + }, + "changes": [ + { + "id": "establish-sdk-compatibility-governance", + "priority": "P0", + "dependsOn": [], + "state": "DRAFT", + "capabilities": [ + "sdk-compatibility-governance" + ] + }, + { + "id": "fix-openclaw-protocol-contracts", + "priority": "P0", + "dependsOn": [ + "establish-sdk-compatibility-governance" + ], + "state": "DRAFT", + "capabilities": [ + "responses-streaming", + "gateway-chat-events", + "gateway-device-auth", + "session-history-contract", + "tools-invoke-contract" + ] + }, + { + "id": "add-managed-gateway-client", + "priority": "P0", + "dependsOn": [ + "establish-sdk-compatibility-governance", + "fix-openclaw-protocol-contracts" + ], + "state": "DRAFT", + "capabilities": [ + "managed-rpc", + "gateway-recovery", + "typed-event-delivery" + ] + }, + { + "id": "add-agent-session-approval-control", + "priority": "P1", + "dependsOn": [ + "add-managed-gateway-client" + ], + "state": "DRAFT", + "capabilities": [ + "agent-lifecycle", + "session-control", + "approval-control" + ] + }, + { + "id": "add-gateway-operations", + "priority": "P1/P2", + "dependsOn": [ + "add-managed-gateway-client", + "add-agent-session-approval-control" + ], + "state": "DRAFT", + "capabilities": [ + "configuration-control", + "cron-control", + "tool-model-catalogs", + "skill-plugin-lifecycle", + "channel-node-control", + "task-audit-artifacts" + ] + }, + { + "id": "add-optional-runtime-adapters", + "priority": "P2", + "dependsOn": [ + "add-managed-gateway-client", + "add-agent-session-approval-control" + ], + "state": "DRAFT", + "capabilities": [ + "terminal-voice-adapters", + "persistent-stdio-adapters", + "cli-typed-results" + ] + } + ] +} diff --git a/docs/openclaw-integration/coverage-baseline.md b/docs/openclaw-integration/coverage-baseline.md new file mode 100644 index 0000000..1a17eac --- /dev/null +++ b/docs/openclaw-integration/coverage-baseline.md @@ -0,0 +1,39 @@ +# 官方能力与 SDK 静态覆盖基线 + +状态:静态观察,不是验收报告。完整来源见 [source-register](source-register.md)。 + +## 证据等级 + +`PARTIAL_STATIC` 表示已读代码存在相关实现但契约不完整;`CLI_ONLY_IN_REVIEWED_SURFACE` 表示已有 CLI 而本次检查的公共 WS 面未见对应类型化实现;`NOT_WRAPPED_IN_REVIEWED_SURFACE` 不等于全仓库永远无法间接调用;`VERIFY_SCOPE` 需要进一步逐版本核实。所有条目的真实集成状态均为 NOT_RUN。 + +| 能力 | 静态状态 | 观察边界 | 源码 | 对应规范 | +|---|---|---|---|---| +| Responses JSON / SSE | PARTIAL_STATIC | 普通 Responses 路径传递 stream 字段后仍按 JSON 解析;Chat SSE 入口不能证明 Responses SSE 已实现。 | C01,C08 | `responses-streaming` | +| Chat replace 与运行关联 | PARTIAL_STATIC | 所读 handler 追加文本,未知 runId 有活动流回退;属于静态风险,未运行复现。 | C02 | `gateway-chat-events` | +| 设备握手结果 | PARTIAL_STATIC | 此前所读 HelloOk 未完整接收设备 Token 和快照,输入配置不等于认证闭环。 | C03 | `gateway-device-auth` | +| 历史与分页恢复 | PARTIAL_STATIC | 已有历史查询,恢复和分页元数据需要补齐;不宣称当前完全不能查历史。 | C04 | `session-history-contract` | +| Tools Invoke | PARTIAL_STATIC | 已有请求和执行面;字段、dryRun 说明及安全语义需要修正。 | C05 | `tools-invoke-contract` | +| 公共受管理 RPC | NOT_WRAPPED_IN_REVIEWED_SURFACE | 现有通用请求管理为 private;底层可发原始帧不是公共受管理 API。 | C02 | `managed-rpc` | +| 自动连接恢复 | PARTIAL_STATIC | 已有连接与断线清理;尚未形成本文定义的恢复、对账和重放策略。 | C02 | `gateway-recovery` | +| 类型化事件 | PARTIAL_STATIC | 原始事件 listener 已有;不能把没有类型化 DTO 写成所有事件收不到。 | C02 | `typed-event-delivery` | +| Agent 生命周期 | CLI_OR_PARTIAL_STATIC | 有 Agent CLI、聊天和身份查询;缺本文定义的原生运行闭环。 | C02,C06 | `agent-lifecycle` | +| Session 控制 | CLI_OR_PARTIAL_STATIC | 有 list/send 与聊天 history/abort,其他控制与订阅需补齐。 | C02,C06 | `session-control` | +| Approval 闭环 | CLI_ONLY_IN_REVIEWED_SURFACE | 有审批 CLI;所读 WS 公共业务方法没有专用审批客户端。 | C02,C06 | `approval-control` | +| Config / Secrets | CLI_OR_PARTIAL_STATIC | 有 config.get 与 CLI;写入冲突和运行时生效契约需补齐。 | C02,C06 | `configuration-control` | +| Cron | CLI_OR_PARTIAL_STATIC | 有 cron.list 与 CLI;手动排队与准确 runId 跟踪需补齐。 | C02,C06 | `cron-control` | +| Tools / Models 目录 | CLI_OR_PARTIAL_STATIC | 已有部分 HTTP/CLI;WS 目录、有效权限和业务结果需专门封装。 | C02,C06 | `tool-model-catalogs` | +| Skills / Plugins | CLI_ONLY_IN_REVIEWED_SURFACE | 有 CLI;远程原生领域客户端和运行时阶段反馈未见于所读公共 WS 面。 | C02,C06 | `skill-plugin-lifecycle` | +| Channels / Devices / Nodes | CLI_ONLY_IN_REVIEWED_SURFACE | 有相关 CLI 和握手字段;不是完整远程控制和 node 执行闭环。 | C02,C06 | `channel-node-control` | +| Tasks / Audit / Usage / Artifacts | VERIFY_SCOPE | 部分有 CLI,本文定义的台账查询、用量与产物下载需逐版本核实。 | C02,C06 | `task-audit-artifacts` | +| Terminal / Talk / TTS | VERIFY_SCOPE | Terminal CLI 不等于交互终端客户端;语音协议要独立验证。 | C06,C07 | `terminal-voice-adapters` | +| MCP / ACP | CLI_ONLY_IN_REVIEWED_SURFACE | 已有启动命令,但一次性 executor 不等于持久双向协议适配。 | C06,C07 | `persistent-stdio-adapters` | +| Browser / Infer / CLI DTO | PARTIAL_STATIC | 已有自由参数入口;缺机器输出版本契约和精确支持等级。 | C06,C07 | `cli-typed-results` | +| 三分支发布证据 | VERIFY_SCOPE | 先前类数量和 blob 对比不等于行为或运行兼容证明。 | SDK HEAD | `sdk-compatibility-governance` | + +## 不能沿用的推断 + +有 stream 字段不等于完成 SSE;存在 idempotencyKey 不等于恰好一次;HTTP 的共享 Token 加窄 scope 头不等于租户隔离;协议常量为 4 不等于完整支持所有 v4 事件;CLI 命令存在不等于原生协议或稳定机器输出。依据分别见 O03、O07、O02、O04 与 C06/C07。 + +## 现有行为与新规范的关系 + +本包未建立“已实现全功能”的根规范。全部拟实现契约放在 changes 下,修正既有代码的规范也是首次建档的 ADDED Requirements。后续如已存在同名生效规范,合并本包时必须改用匹配原规范的 MODIFIED 完整条目,不能直接覆盖或重复新增。 diff --git a/docs/openclaw-integration/package-manifest.json b/docs/openclaw-integration/package-manifest.json new file mode 100644 index 0000000..378fc7e --- /dev/null +++ b/docs/openclaw-integration/package-manifest.json @@ -0,0 +1 @@ +{"scope":"repository documentation; paths relative to repository root; manifest excludes itself","source_package":"openclaw-java-sdk-openspec-draft-2026-09-20.zip","source_package_sha256":"f8eedbb0356b34ecde22584b57fdc9d375fa7409c36d6931b7faca36f4919468","files":{"docs/openclaw-integration/README.md":{"bytes":2882,"sha256":"7af61aea4d0c57c7e1f2c2b83a52126c4ab5b00f6a98962ead41687128789225"},"docs/openclaw-integration/acceptance-plan.md":{"bytes":4591,"sha256":"4875a07fd14cd9771d610d221ab8e666bf2801341b3ccc21302627f06fa2089f"},"docs/openclaw-integration/baseline.json":{"bytes":3221,"sha256":"b5b13dd410d068a5b07b4c27be01658aa94bb626dce9beffc44ebce9565789ab"},"docs/openclaw-integration/coverage-baseline.md":{"bytes":4792,"sha256":"ae4b7783b718a268c697fdd85f1f24800f838cb1063ae90e4324c224efc7f820"},"docs/openclaw-integration/roadmap.md":{"bytes":3880,"sha256":"edb7e1a9717f05e1128eda44fb41fbddcd595cfd2e165ab1ea6d920ca38d5aa6"},"docs/openclaw-integration/source-register.md":{"bytes":5424,"sha256":"992bf67dd8da00cccaeaf4a93ed594b2877d832ed3015b402c3a4eabb0b523f0"},"docs/openclaw-integration/traceability.json.gz":{"bytes":3246,"sha256":"75386731e6f4b685d61a8c582e18edbdc86577e717039716c1c908f8422befcd","decompressed_sha256":"da585354d01fb0f687d764840f7512259de832896db051fe450ac667fd6bf6bb"},"docs/openclaw-integration/traceability.md":{"bytes":13633,"sha256":"2eee7ecf7b4e7db906226082a130d4b80b9bd44be7d4d699aeeb8ada749f3384"},"docs/openclaw-integration/validation-report/README.md":{"bytes":1113,"sha256":"b67e0eb4a969e742b6e30e35883dcac0c3cc15aca0005e6d66377b99995e2932"},"docs/openclaw-integration/validation-report/part-001.b64":{"bytes":2601,"sha256":"9570f3b3818b997c948cb9ee4a5c4885d664cacdfec18e0b3d1e9858ae695a32"},"docs/openclaw-integration/validation-report/part-002.b64":{"bytes":2601,"sha256":"d57ebdd3717bab8648f4f98a70430515d0750ebb38cd72a970e246ddeb049952"},"docs/openclaw-integration/validation-report/part-003.b64":{"bytes":2537,"sha256":"61a7c754d543e645ad6b705add8f183ac0e6605340f0993b9bc5cb4647fef85b"},"docs/openclaw-integration/validation-summary.md":{"bytes":2141,"sha256":"40e31c0cd1ebb639cf1e852b0b0180bda27e28c16dcba9b90e3cb8aabd0f6d10"},"openspec/README.md":{"bytes":611,"sha256":"58a1b2615971f2c7fb56f069006b8559cf5cf1548c01b29c83758c894ec79f20"},"openspec/changes/add-agent-session-approval-control/.openspec.yaml":{"bytes":40,"sha256":"dc10040214104474c4e34e5b38359540c882aa7cfb6e7221e5d0614f1dba8fd7"},"openspec/changes/add-agent-session-approval-control/design.md":{"bytes":4797,"sha256":"95794f1f71841a3d6a5ca61d10bbffaf5be029f8284cf75ac4b6020e4564d3d1"},"openspec/changes/add-agent-session-approval-control/proposal.md":{"bytes":1936,"sha256":"da5665faa52a3e14e756e021e2b9dec56c5f6bb5d73af277e756050a4399c741"},"openspec/changes/add-agent-session-approval-control/specs/agent-lifecycle/spec.md":{"bytes":2664,"sha256":"0b12b0240d1a5d37bcaa8c69604ca53ca67c4a372440262d14ed01b0ffd1a174"},"openspec/changes/add-agent-session-approval-control/specs/approval-control/spec.md":{"bytes":2549,"sha256":"3b979ba5b34b8aa1e1fef3a216e663b5b194b7bce713092d73cc4eed83f0c09b"},"openspec/changes/add-agent-session-approval-control/specs/session-control/spec.md":{"bytes":2543,"sha256":"ecf939250f43f526c1d78a5a2bc2902e5889cf13474a7c80e440e7232d5c24fb"},"openspec/changes/add-agent-session-approval-control/tasks.md":{"bytes":3242,"sha256":"782b9f42a8b58fab966c04920d27a98ea77d588102594219572eae5b17cbad11"},"openspec/changes/add-gateway-operations/.openspec.yaml":{"bytes":40,"sha256":"dc10040214104474c4e34e5b38359540c882aa7cfb6e7221e5d0614f1dba8fd7"},"openspec/changes/add-gateway-operations/design.md":{"bytes":5441,"sha256":"d07d9f9c3c5da092be96a18f0e6c35be53fe06f2eda9f540ef993961be8f247d"},"openspec/changes/add-gateway-operations/proposal.md":{"bytes":2342,"sha256":"c6081bd3692307909e736b7d84ccc34828b4fa5152a118f86dc577fa6ac3d47f"},"openspec/changes/add-gateway-operations/specs/channel-node-control/spec.md":{"bytes":2663,"sha256":"4350182f113da6caff9cd0eb81f2cb5173be374bd2f6665e16a9f93111fb4649"},"openspec/changes/add-gateway-operations/specs/configuration-control/spec.md":{"bytes":2432,"sha256":"cf8839be9d8c9015cfb855422fcdfdfaee02275965f2b3a12b42ce4987b8b3c1"},"openspec/changes/add-gateway-operations/specs/cron-control/spec.md":{"bytes":2453,"sha256":"8f86038254595e09c705b4b680d41aed60b2332f019139e35b5a65c329774274"},"openspec/changes/add-gateway-operations/specs/skill-plugin-lifecycle/spec.md":{"bytes":2551,"sha256":"01ef9d030ab116a21bcca1ff7f8d9ced27968015939cd1bf4c2ed99955f445bd"},"openspec/changes/add-gateway-operations/specs/task-audit-artifacts/spec.md":{"bytes":2597,"sha256":"8d2cb83159ed06b09358d3f950ae20489ea964a864c289168ab2c5a8e57ffadb"},"openspec/changes/add-gateway-operations/specs/tool-model-catalogs/spec.md":{"bytes":2463,"sha256":"a424d99c94d69cb61fa9e3f0efeb9dc8c1702d37c397f789c3363a79066df547"},"openspec/changes/add-gateway-operations/tasks.md":{"bytes":5352,"sha256":"12b19adb7b2a84e0fc263e8a8378719d2f5978f2dc5f619f3c856eb70a66b4f5"},"openspec/changes/add-managed-gateway-client/.openspec.yaml":{"bytes":40,"sha256":"dc10040214104474c4e34e5b38359540c882aa7cfb6e7221e5d0614f1dba8fd7"},"openspec/changes/add-managed-gateway-client/design.md":{"bytes":5113,"sha256":"162801004ae85138dc1d03ecb0654506986c26053bfe6fa9e72704edb01de6a2"},"openspec/changes/add-managed-gateway-client/proposal.md":{"bytes":2019,"sha256":"a91469801a7becd8ab01272697394c1d44c367ac2ae0666814b6f6b5706a01cf"},"openspec/changes/add-managed-gateway-client/specs/gateway-recovery/spec.md":{"bytes":2762,"sha256":"af082acc14c97793b8f9231b500e86e8e5c77455ae04a88b0b24fdfa4ed3335e"},"openspec/changes/add-managed-gateway-client/specs/managed-rpc/spec.md":{"bytes":2624,"sha256":"6aa6031b61a113443b8d560e58baae1c041ddc465630b736fa9a23b1fdb4408d"},"openspec/changes/add-managed-gateway-client/specs/typed-event-delivery/spec.md":{"bytes":2613,"sha256":"c5def41f0c9510153b5eb773521778d6121cad2ca4b2bdc733e9cfaa40275552"},"openspec/changes/add-managed-gateway-client/tasks.md":{"bytes":3249,"sha256":"978d020d94027db3801c090dd7e86bbd65b2568c64880950320e57087ee96970"},"openspec/changes/add-optional-runtime-adapters/.openspec.yaml":{"bytes":40,"sha256":"dc10040214104474c4e34e5b38359540c882aa7cfb6e7221e5d0614f1dba8fd7"},"openspec/changes/add-optional-runtime-adapters/design.md":{"bytes":4940,"sha256":"65332fcd6d91ff4ca9e77d53f606caccec2795fae74160bb95d357da482546c9"},"openspec/changes/add-optional-runtime-adapters/proposal.md":{"bytes":2065,"sha256":"a32b0507234b8e78719cb7716dc484212797b3c0259daa76931bf2c7820b4b3e"},"openspec/changes/add-optional-runtime-adapters/specs/cli-typed-results/spec.md":{"bytes":2609,"sha256":"2f9836a84b4b5ae66abae680ef1ec52c35531029b4682a75cc5a3c2e8cc6c67f"},"openspec/changes/add-optional-runtime-adapters/specs/persistent-stdio-adapters/spec.md":{"bytes":2509,"sha256":"ea7d2f8599d97c4ccd8f23ada658f636be62d2bdb715ed82f026a22286a7a3db"},"openspec/changes/add-optional-runtime-adapters/specs/terminal-voice-adapters/spec.md":{"bytes":2620,"sha256":"77fbb21d872b83da1cda418e6a7e1d94b0ea496ac566e6808225f2031a1c39a0"},"openspec/changes/add-optional-runtime-adapters/tasks.md":{"bytes":3318,"sha256":"a86f42485573c87ffa97e3296c3c20cfc128b63db40166a28ee7daf48e1b9f0c"},"openspec/changes/establish-sdk-compatibility-governance/.openspec.yaml":{"bytes":40,"sha256":"dc10040214104474c4e34e5b38359540c882aa7cfb6e7221e5d0614f1dba8fd7"},"openspec/changes/establish-sdk-compatibility-governance/design.md":{"bytes":5448,"sha256":"d3150d2e298788a186c934920cb111bdef4b6801e6c34052741b61895c4dd372"},"openspec/changes/establish-sdk-compatibility-governance/evidence/2026-09-20-precursor-evidence.md":{"bytes":2383,"sha256":"e55309e91a1f190e62b3c29de385509def154a9d534f2963d8f4b69c4fd27db4"},"openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-live-gateway.md":{"bytes":6012,"sha256":"8a39e6c4943c4d5fadfd5ed8000d54510b5ba53dc7ab4ca8a594f0ed142b5b8c"},"openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-locked-gateway-schema.md":{"bytes":2169,"sha256":"6728253fe492a99ebc24eb8c3bc261331317a6324db7c3a168610883ab41048f"},"openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-19-governance-scenario-audit.md":{"bytes":6323,"sha256":"b9398fe3e22fd27de725abdf4134017087dc761cfa27e5e42a18d795ff527ae3"},"openspec/changes/establish-sdk-compatibility-governance/evidence/capability-inventory.json":{"bytes":2118,"sha256":"c8148e22712176d1991cec37e8f80861996053c693f76a2998a3f7a37fd00822"},"openspec/changes/establish-sdk-compatibility-governance/evidence/fixtures/GatewayCompatibilityFixtureTest.java":{"bytes":3177,"sha256":"7e13d512dccef6b533f5bf04caa1556b97cc7c9a97f8776204196d71c87d38f8"},"openspec/changes/establish-sdk-compatibility-governance/evidence/fixtures/RemovedGatewayMethodFixtureTest.java":{"bytes":3990,"sha256":"1009dec97bed823f1aefa6dac4c822ca3d71c909e27f45df1e101024ce5d0024"},"openspec/changes/establish-sdk-compatibility-governance/evidence/version-lock.md":{"bytes":1139,"sha256":"7d53174fb9aad9244934bafec50f364ce869f8bcb92445b96aba2c2af64e67f3"},"openspec/changes/establish-sdk-compatibility-governance/proposal.md":{"bytes":1789,"sha256":"88e18f4f66ebccace6da321cb7d0a6b4d788e8e84cc933ab3678a5389b459ed6"},"openspec/changes/establish-sdk-compatibility-governance/specs/sdk-compatibility-governance/spec.md":{"bytes":3830,"sha256":"3d14086cef101a78b83ef953e16cea13b4b341ca9c9552c62596ee9ab85131a1"},"openspec/changes/establish-sdk-compatibility-governance/tasks.md":{"bytes":4229,"sha256":"6e1bf576141cbf53a07cc6648b60a2624ee9fd2ad1f695127ef6f3f8f1c65931"},"openspec/changes/fix-openclaw-protocol-contracts/.openspec.yaml":{"bytes":40,"sha256":"dc10040214104474c4e34e5b38359540c882aa7cfb6e7221e5d0614f1dba8fd7"},"openspec/changes/fix-openclaw-protocol-contracts/design.md":{"bytes":5675,"sha256":"10966f9bc03d3b34138539aeeb4b7ad884b28763cc2290c1f95926b69335dbbb"},"openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-gateway-chat-isolation.md":{"bytes":4335,"sha256":"5ba24fe93389c94273c60efb5aed1da80d91f414b5cd8307d76febe544a8176d"},"openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/GatewayStreamingLiveFixtureTest.java":{"bytes":4205,"sha256":"fd66cbff962ac8f87b699fb05c4e3f643411dc799d1a1b9cd65d815a1fb35912"},"openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/run-gateway-streaming.py":{"bytes":6109,"sha256":"56f353850bfb3c3bc11ce49f025c1aae960882251d2d24f9714f5eec7b957298"},"openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/strict-run-id-review.patch":{"bytes":3239,"sha256":"b86234e6d5b2354ca037d183dfb9f34ee15fe00300fb23da21eac1b20ab60191"},"openspec/changes/fix-openclaw-protocol-contracts/proposal.md":{"bytes":2418,"sha256":"11a51837e386f1068004c526673547610a5b84dca8b42fc6d9484da02cc9b270"},"openspec/changes/fix-openclaw-protocol-contracts/specs/gateway-chat-events/spec.md":{"bytes":2622,"sha256":"3564b6061b568c1d30577fc8b228243f21df756321de9e50dd4a763529afb5b9"},"openspec/changes/fix-openclaw-protocol-contracts/specs/gateway-device-auth/spec.md":{"bytes":2806,"sha256":"2a6d8d7d5202495cdace92ffd12a500ee9f0266a172aa4147852e4cf43ee2a4a"},"openspec/changes/fix-openclaw-protocol-contracts/specs/responses-streaming/spec.md":{"bytes":2695,"sha256":"1ca9b80db706c236ca32ae0acd8a02a190fc3644959aa58af4379035923c3b82"},"openspec/changes/fix-openclaw-protocol-contracts/specs/session-history-contract/spec.md":{"bytes":2651,"sha256":"7fcc7baab4e3d9f10dd86adb03e00f78b07a7f011747a744224ca3dadf89168c"},"openspec/changes/fix-openclaw-protocol-contracts/specs/tools-invoke-contract/spec.md":{"bytes":2681,"sha256":"f255110ecff5a9479b780ec81dce1c451d638fe69259196e0ef063c5343a62f1"},"openspec/changes/fix-openclaw-protocol-contracts/tasks.md":{"bytes":4800,"sha256":"ed10a362a65f6bb47de5469bf2c861b4dc436af152b8910e6909a0a7b30c0698"},"openspec/config.yaml":{"bytes":1862,"sha256":"151f5ce61678f2d47d19a1c21168936f7ad5c6f05adec25db6a0e8a70f1f8ba9"},"openspec/specs/.gitkeep":{"bytes":1,"sha256":"01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"}},"split_report":{"path":"docs/openclaw-integration/validation-report","encoding":"concatenated-base64-of-gzip","original_bytes":127699,"original_sha256":"a689415d7e7c1a28cc50a97179c797adc29080b30f5ec929aa8ed23227a1a598","parts":3},"source_package_note":"The source package hash identifies the original 2026-09-20 bundle. The file inventory also includes subsequent G0 evidence and documentation edits."} diff --git a/docs/openclaw-integration/roadmap.md b/docs/openclaw-integration/roadmap.md new file mode 100644 index 0000000..01d4490 --- /dev/null +++ b/docs/openclaw-integration/roadmap.md @@ -0,0 +1,53 @@ +# OpenClaw Java SDK:官方能力整合路线与 OpenSpec 变更图 + +版本:0.1.0-draft · 日期:2026-09-20 · 状态:待评审。 + +## 目标与边界 + +把官方能力差距分析转成可审查、可验证和可分批实现的行为规范。首先修正已有协议行为,再建立受管理客户端,然后扩展领域操作。现有 HTTP、SSE、WS 与 CLI 的分工继续保留;Java 8/17/21 三条发行线保持同一已批准语义。 + +不在本轮执行范围:修改 SDK、添加依赖、运行真实 Agent、批准工具执行、创建发布、写入用户电脑或推送仓库。本包只交付文档。 + +## 变更依赖 + +```text +G0 版本与兼容治理 + └─ G1 协议契约修正 + └─ G2 RPC / 连接恢复 / 事件交付 + └─ G3 Agent / Session / Approval + ├─ G4 Gateway 运营管理 + └─ G5 可选运行时适配 +``` + +六组按独立变更保存。G4 和 G5 是较大领域集合,应按各自 capability 分批实现并逐项审查;仅有当前提案不授权并行大改。 + +| 编号 | Change ID | 优先级 | 规范数 | +|---|---|---|---| +| G0 | `establish-sdk-compatibility-governance` | P0 | 1 | +| G1 | `fix-openclaw-protocol-contracts` | P0 | 5 | +| G2 | `add-managed-gateway-client` | P0 | 3 | +| G3 | `add-agent-session-approval-control` | P1 | 3 | +| G4 | `add-gateway-operations` | P1/P2 | 6 | +| G5 | `add-optional-runtime-adapters` | P2 | 3 | + +## 设计职责 + +proposal 解释为什么、范围与破坏性变化;specs 只写外部行为和验收场景;design 解释组件划分、候选方案、风险与迁移;tasks 把场景映射到可验收的工作项。类名和文件路径属于 design/tasks,而不是需求本身。 + +## 三分支协作 + +以 2.x 作为本次公共源码阅读参照,不因此指定它为未来唯一开发主干。每次实现必须明确起始分支,并把相同业务修改同步到其他适用分支;不能直接整分支合并来覆盖 JDK、Jackson 或 Maven 的发行线差异。已批准功能的测试场景和语义相同,二进制 ABI 不要求跨 Jackson 主版本一致。 + +建议根文档由文档专用提交维护,版本线只同步明确的文档和实现提交,不把本包当成已合并到 main 的事实。各条线独立记录测试 SHA、依赖来源与发布限制。 + +## 准入状态 + +人审:尚未发生。G0 证据已记录本机可获得的 OpenClaw `2026.7.1-2 (0790d9f)` 及来源,并完成 [真实 Gateway 基线验证](../../openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-live-gateway.md)。锁定版的 [机器可读协议 schema](../../openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-locked-gateway-schema.md) 已按上游源码生成。版本锁定待人审确认,G1 编码保持阻断。首次文档编制时 OpenSpec CLI 不可用;后续 G0 证据记录了 OpenSpec 1.8.0 strict 校验和三分支构建结果,2026-11-18 又以 OpenSpec 1.14.1 strict 校验 6/6 通过。CLI 格式校验和历史构建不代替当前 SDK 行为或真实 Gateway 验收。 + +## 尚未纳入强承诺的扩展 + +实时官方索引还可能包含新渠道、A2A、云会话/Worker、ClawHub 独立服务等。上一轮差距清单并非官方目录的穷尽审计;这些能力必须单独完成需求与版本评估,不因本文已有 21 个 capability 就宣称全覆盖。Gateway 内部 worker 私有协议、模型/沙箱内核与原生插件运行时不属于本 Java 外部 SDK 的默认实现职责。 + +## 完成定义 + +文档完成:四类产物齐全、结构与引用可检查,保持待评审。能力完成:目标版本锁定、场景真正执行、每个适用分支有证据、兼容差异获准、人审接受。规范生效:满足本项目归档条件后才更新根 specs;不得把“任务已生成”写成“功能已实现”。 diff --git a/docs/openclaw-integration/source-register.md b/docs/openclaw-integration/source-register.md new file mode 100644 index 0000000..51a742d --- /dev/null +++ b/docs/openclaw-integration/source-register.md @@ -0,0 +1,60 @@ +# 来源登记与证据边界 + +文档日期:2026-09-20。SDK 提交可以精确定位;上游页面为本轮读取的在线文档,不是已归档的版本化原文,也不是已运行验证的 Gateway 版本。O16 为文档索引指向的 CLI 参考入口,本轮未按全部子命令逐项复核。 + +## 官方规范来源 + +| ID | 内容 | 原始来源 | +|---|---|---| +| S01 | OpenSpec 概念与变更目录 | https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md | +| S02 | OpenSpec spec-driven schema | https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml | +| S03 | OpenSpec CLI validate 与状态命令 | https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md | +| O00 | OpenClaw 文档索引 | https://docs.openclaw.ai/llms.txt | +| O01 | 外部应用接入边界 | https://docs.openclaw.ai/gateway/external-apps | +| O02 | 协议版本与客户端恢复边界 | https://docs.openclaw.ai/gateway/protocol/versioning | +| O03 | Responses HTTP 与 SSE | https://docs.openclaw.ai/gateway/openresponses-http-api | +| O04 | 会话启动、快照及事件语义 | https://docs.openclaw.ai/gateway/protocol/rpc-bootstrap-and-events | +| O05 | Gateway 握手与设备凭据 | https://docs.openclaw.ai/gateway/protocol/handshake | +| O06 | 会话控制与历史 | https://docs.openclaw.ai/gateway/protocol/rpc-session-control | +| O07 | HTTP Tools Invoke 与认证语义 | https://docs.openclaw.ai/gateway/tools-invoke-http-api | +| O08 | 设备、Node、审批与 Cron RPC | https://docs.openclaw.ai/gateway/protocol/rpc-devices-nodes-and-approvals | +| O09 | Config RPC 更新与生效 | https://docs.openclaw.ai/gateway/configuration/config-rpc | +| O10 | 工具、模型与 Skills 管理 | https://docs.openclaw.ai/gateway/protocol/operator-methods | +| O11 | Talk、Agent 与产物 RPC | https://docs.openclaw.ai/gateway/protocol/rpc-talk-config-and-agents | +| O12 | 系统、渠道、插件与终端 RPC | https://docs.openclaw.ai/gateway/protocol/rpc-system-and-channels | +| O13 | 任务、审计及用量台账 | https://docs.openclaw.ai/gateway/protocol/ledgers | +| O14 | MCP serve | https://docs.openclaw.ai/cli/mcp/serve | +| O15 | ACP bridge | https://docs.openclaw.ai/cli/acp | +| O16 | CLI 参考入口 | https://docs.openclaw.ai/cli | + +OpenSpec schema 本轮读取的 Git blob:`688c38a20bd0350bf27003ccdb78215562b1a334`。这标识所读文件,不代表本环境安装了对应 CLI 发布版。 + +## SDK 提交与源码入口 + +| 分支 | 精确提交 | +|---|---| +| feature/1.0.x | 8cfbeb880a6c6ae5390fab0f9fe65e06938907be | +| feature/2.0.x | 48309d7bc34c4298cdfa1c52db06114b2e7e9f17 | +| feature/3.0.x | 3687fcb09e75ec4c2ecb522877e9a27c1f1955aa | +| main | c4ddcd3fa86d8fb5352b722813268760c35636b2 | + +以 2.x 的固定提交列出共用静态分析入口。三分支差异必须在实施前复核,不能把单个入口的观察扩张为全仓库、全版本安全审计。 + +- C01:[Responses 普通 JSON 路径](https://github.com/easy-4-java/openclaw-java-sdk/blob/48309d7bc34c4298cdfa1c52db06114b2e7e9f17/src/main/java/io/github/easy4j/openclaw/api/OpenClawResponsesClient.java)。 +- C02:[WS RPC 与聊天事件路由](https://github.com/easy-4-java/openclaw-java-sdk/blob/48309d7bc34c4298cdfa1c52db06114b2e7e9f17/src/main/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClient.java)。 +- C03:[HelloOk 响应模型](https://github.com/easy-4-java/openclaw-java-sdk/blob/48309d7bc34c4298cdfa1c52db06114b2e7e9f17/src/main/java/io/github/easy4j/openclaw/ws/protocol/HelloOk.java)。 +- C04:[历史请求与结果](https://github.com/easy-4-java/openclaw-java-sdk/blob/48309d7bc34c4298cdfa1c52db06114b2e7e9f17/src/main/java/io/github/easy4j/openclaw/ws/protocol/result/ChatHistoryResult.java)。 +- C05:[HTTP 工具请求模型](https://github.com/easy-4-java/openclaw-java-sdk/blob/48309d7bc34c4298cdfa1c52db06114b2e7e9f17/src/main/java/io/github/easy4j/openclaw/api/model/ToolInvokeRequest.java)。 +- C06:[CLI 命令门面](https://github.com/easy-4-java/openclaw-java-sdk/blob/48309d7bc34c4298cdfa1c52db06114b2e7e9f17/src/main/java/io/github/easy4j/openclaw/cli/OpenClawCli.java)。 +- C07:[CLI 一次性执行器](https://github.com/easy-4-java/openclaw-java-sdk/blob/48309d7bc34c4298cdfa1c52db06114b2e7e9f17/src/main/java/io/github/easy4j/openclaw/cli/OpenClawCliExecutor.java)。 +- C08:[现有 Chat SSE 订阅](https://github.com/easy-4-java/openclaw-java-sdk/blob/48309d7bc34c4298cdfa1c52db06114b2e7e9f17/src/main/java/io/github/easy4j/openclaw/api/OpenClawSseClient.java)。 + +C01 和 C02 的相关实现本轮再次读取;其余入口沿用同一会话前轮静态核查,HEAD 本轮再次核对无变化。它们不是运行证据。 + +## 本轮未执行的事项 + +未运行 codegraph、Maven 构建、真实 Gateway 集成、漏洞扫描、堆/线程分析或生产就绪检查。尝试在沙箱获取仓库及 OpenSpec CLI 时遇到 DNS/网络解析失败;没有把此前本机 Tunnel 的状态推断为本轮状态。首次文档编制阶段没有修改用户本机,也没有提交 GitHub;本次文档提交保留该阶段的证据边界。 + +## 实施前必须补全 + +固定目标 Gateway 的精确版本/提交、可复现构建来源和协议文件;保存脱敏 wire 样本与命令结果;记录测试环境和认证模式。无法核实的上游字段、方法和权限保持待验证,不猜测其在某发行版中的可用性。 diff --git a/docs/openclaw-integration/traceability.json.gz b/docs/openclaw-integration/traceability.json.gz new file mode 100644 index 0000000..85d0d48 Binary files /dev/null and b/docs/openclaw-integration/traceability.json.gz differ diff --git a/docs/openclaw-integration/traceability.md b/docs/openclaw-integration/traceability.md new file mode 100644 index 0000000..405f871 --- /dev/null +++ b/docs/openclaw-integration/traceability.md @@ -0,0 +1,134 @@ +# Requirement → Scenario → Task 追踪表 + +表中状态记录首次编制时的基线。八个治理场景的后续验证见 [G0 场景证据核对](../../openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-19-governance-scenario-audit.md)。 + +| Change | Capability | Requirement | Scenario | Tasks | 状态 | +|---|---|---|---|---|---| +| establish-sdk-compatibility-governance | sdk-compatibility-governance | GOV-01 | GOV-01-S1 | 1.2, 2.1, 3.1, 2.4 | NOT_RUN | +| establish-sdk-compatibility-governance | sdk-compatibility-governance | GOV-01 | GOV-01-S2 | 1.2, 2.1, 3.1, 2.4 | NOT_RUN | +| establish-sdk-compatibility-governance | sdk-compatibility-governance | GOV-02 | GOV-02-S1 | 2.2, 3.2, 3.3, 2.4 | NOT_RUN | +| establish-sdk-compatibility-governance | sdk-compatibility-governance | GOV-02 | GOV-02-S2 | 2.2, 3.2, 3.3, 2.4 | NOT_RUN | +| establish-sdk-compatibility-governance | sdk-compatibility-governance | GOV-03 | GOV-03-S1 | 1.1, 2.3, 3.5, 2.4 | NOT_RUN | +| establish-sdk-compatibility-governance | sdk-compatibility-governance | GOV-03 | GOV-03-S2 | 1.1, 2.3, 3.5, 2.4 | NOT_RUN | +| establish-sdk-compatibility-governance | sdk-compatibility-governance | GOV-04 | GOV-04-S1 | 1.2, 2.1, 3.2, 2.4 | NOT_RUN | +| establish-sdk-compatibility-governance | sdk-compatibility-governance | GOV-04 | GOV-04-S2 | 1.2, 2.1, 3.2, 2.4 | NOT_RUN | +| fix-openclaw-protocol-contracts | responses-streaming | RSP-01 | RSP-01-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | responses-streaming | RSP-01 | RSP-01-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | responses-streaming | RSP-02 | RSP-02-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | responses-streaming | RSP-02 | RSP-02-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | responses-streaming | RSP-03 | RSP-03-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | responses-streaming | RSP-03 | RSP-03-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-chat-events | CHAT-01 | CHAT-01-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-chat-events | CHAT-01 | CHAT-01-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-chat-events | CHAT-02 | CHAT-02-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-chat-events | CHAT-02 | CHAT-02-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-chat-events | CHAT-03 | CHAT-03-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-chat-events | CHAT-03 | CHAT-03-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-device-auth | AUTH-01 | AUTH-01-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-device-auth | AUTH-01 | AUTH-01-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-device-auth | AUTH-02 | AUTH-02-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-device-auth | AUTH-02 | AUTH-02-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-device-auth | AUTH-03 | AUTH-03-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | gateway-device-auth | AUTH-03 | AUTH-03-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | session-history-contract | HIST-01 | HIST-01-S1 | 5.1, 5.2, 5.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | session-history-contract | HIST-01 | HIST-01-S2 | 5.1, 5.2, 5.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | session-history-contract | HIST-02 | HIST-02-S1 | 5.1, 5.2, 5.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | session-history-contract | HIST-02 | HIST-02-S2 | 5.1, 5.2, 5.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | session-history-contract | HIST-03 | HIST-03-S1 | 5.1, 5.2, 5.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | session-history-contract | HIST-03 | HIST-03-S2 | 5.1, 5.2, 5.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | tools-invoke-contract | TOOL-01 | TOOL-01-S1 | 6.1, 6.2, 6.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | tools-invoke-contract | TOOL-01 | TOOL-01-S2 | 6.1, 6.2, 6.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | tools-invoke-contract | TOOL-02 | TOOL-02-S1 | 6.1, 6.2, 6.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | tools-invoke-contract | TOOL-02 | TOOL-02-S2 | 6.1, 6.2, 6.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | tools-invoke-contract | TOOL-03 | TOOL-03-S1 | 6.1, 6.2, 6.3 | NOT_RUN | +| fix-openclaw-protocol-contracts | tools-invoke-contract | TOOL-03 | TOOL-03-S2 | 6.1, 6.2, 6.3 | NOT_RUN | +| add-managed-gateway-client | managed-rpc | RPC-01 | RPC-01-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-managed-gateway-client | managed-rpc | RPC-01 | RPC-01-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-managed-gateway-client | managed-rpc | RPC-02 | RPC-02-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-managed-gateway-client | managed-rpc | RPC-02 | RPC-02-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-managed-gateway-client | managed-rpc | RPC-03 | RPC-03-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-managed-gateway-client | managed-rpc | RPC-03 | RPC-03-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-managed-gateway-client | gateway-recovery | REC-01 | REC-01-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-managed-gateway-client | gateway-recovery | REC-01 | REC-01-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-managed-gateway-client | gateway-recovery | REC-02 | REC-02-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-managed-gateway-client | gateway-recovery | REC-02 | REC-02-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-managed-gateway-client | gateway-recovery | REC-03 | REC-03-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-managed-gateway-client | gateway-recovery | REC-03 | REC-03-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-managed-gateway-client | typed-event-delivery | EVT-01 | EVT-01-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-managed-gateway-client | typed-event-delivery | EVT-01 | EVT-01-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-managed-gateway-client | typed-event-delivery | EVT-02 | EVT-02-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-managed-gateway-client | typed-event-delivery | EVT-02 | EVT-02-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-managed-gateway-client | typed-event-delivery | EVT-03 | EVT-03-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-managed-gateway-client | typed-event-delivery | EVT-03 | EVT-03-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-agent-session-approval-control | agent-lifecycle | AGENT-01 | AGENT-01-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-agent-session-approval-control | agent-lifecycle | AGENT-01 | AGENT-01-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-agent-session-approval-control | agent-lifecycle | AGENT-02 | AGENT-02-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-agent-session-approval-control | agent-lifecycle | AGENT-02 | AGENT-02-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-agent-session-approval-control | agent-lifecycle | AGENT-03 | AGENT-03-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-agent-session-approval-control | agent-lifecycle | AGENT-03 | AGENT-03-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-agent-session-approval-control | session-control | SESS-01 | SESS-01-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-agent-session-approval-control | session-control | SESS-01 | SESS-01-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-agent-session-approval-control | session-control | SESS-02 | SESS-02-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-agent-session-approval-control | session-control | SESS-02 | SESS-02-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-agent-session-approval-control | session-control | SESS-03 | SESS-03-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-agent-session-approval-control | session-control | SESS-03 | SESS-03-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-agent-session-approval-control | approval-control | APR-01 | APR-01-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-agent-session-approval-control | approval-control | APR-01 | APR-01-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-agent-session-approval-control | approval-control | APR-02 | APR-02-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-agent-session-approval-control | approval-control | APR-02 | APR-02-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-agent-session-approval-control | approval-control | APR-03 | APR-03-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-agent-session-approval-control | approval-control | APR-03 | APR-03-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-gateway-operations | configuration-control | CFG-01 | CFG-01-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-gateway-operations | configuration-control | CFG-01 | CFG-01-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-gateway-operations | configuration-control | CFG-02 | CFG-02-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-gateway-operations | configuration-control | CFG-02 | CFG-02-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-gateway-operations | configuration-control | CFG-03 | CFG-03-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-gateway-operations | configuration-control | CFG-03 | CFG-03-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-gateway-operations | cron-control | CRON-01 | CRON-01-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-gateway-operations | cron-control | CRON-01 | CRON-01-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-gateway-operations | cron-control | CRON-02 | CRON-02-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-gateway-operations | cron-control | CRON-02 | CRON-02-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-gateway-operations | cron-control | CRON-03 | CRON-03-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-gateway-operations | cron-control | CRON-03 | CRON-03-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-gateway-operations | tool-model-catalogs | CAT-01 | CAT-01-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-gateway-operations | tool-model-catalogs | CAT-01 | CAT-01-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-gateway-operations | tool-model-catalogs | CAT-02 | CAT-02-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-gateway-operations | tool-model-catalogs | CAT-02 | CAT-02-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-gateway-operations | tool-model-catalogs | CAT-03 | CAT-03-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-gateway-operations | tool-model-catalogs | CAT-03 | CAT-03-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-gateway-operations | skill-plugin-lifecycle | EXT-01 | EXT-01-S1 | 5.1, 5.2, 5.3 | NOT_RUN | +| add-gateway-operations | skill-plugin-lifecycle | EXT-01 | EXT-01-S2 | 5.1, 5.2, 5.3 | NOT_RUN | +| add-gateway-operations | skill-plugin-lifecycle | EXT-02 | EXT-02-S1 | 5.1, 5.2, 5.3 | NOT_RUN | +| add-gateway-operations | skill-plugin-lifecycle | EXT-02 | EXT-02-S2 | 5.1, 5.2, 5.3 | NOT_RUN | +| add-gateway-operations | skill-plugin-lifecycle | EXT-03 | EXT-03-S1 | 5.1, 5.2, 5.3 | NOT_RUN | +| add-gateway-operations | skill-plugin-lifecycle | EXT-03 | EXT-03-S2 | 5.1, 5.2, 5.3 | NOT_RUN | +| add-gateway-operations | channel-node-control | CN-01 | CN-01-S1 | 6.1, 6.2, 6.3 | NOT_RUN | +| add-gateway-operations | channel-node-control | CN-01 | CN-01-S2 | 6.1, 6.2, 6.3 | NOT_RUN | +| add-gateway-operations | channel-node-control | CN-02 | CN-02-S1 | 6.1, 6.2, 6.3 | NOT_RUN | +| add-gateway-operations | channel-node-control | CN-02 | CN-02-S2 | 6.1, 6.2, 6.3 | NOT_RUN | +| add-gateway-operations | channel-node-control | CN-03 | CN-03-S1 | 6.1, 6.2, 6.3 | NOT_RUN | +| add-gateway-operations | channel-node-control | CN-03 | CN-03-S2 | 6.1, 6.2, 6.3 | NOT_RUN | +| add-gateway-operations | task-audit-artifacts | OBS-01 | OBS-01-S1 | 7.1, 7.2, 7.3 | NOT_RUN | +| add-gateway-operations | task-audit-artifacts | OBS-01 | OBS-01-S2 | 7.1, 7.2, 7.3 | NOT_RUN | +| add-gateway-operations | task-audit-artifacts | OBS-02 | OBS-02-S1 | 7.1, 7.2, 7.3 | NOT_RUN | +| add-gateway-operations | task-audit-artifacts | OBS-02 | OBS-02-S2 | 7.1, 7.2, 7.3 | NOT_RUN | +| add-gateway-operations | task-audit-artifacts | OBS-03 | OBS-03-S1 | 7.1, 7.2, 7.3 | NOT_RUN | +| add-gateway-operations | task-audit-artifacts | OBS-03 | OBS-03-S2 | 7.1, 7.2, 7.3 | NOT_RUN | +| add-optional-runtime-adapters | terminal-voice-adapters | TV-01 | TV-01-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-optional-runtime-adapters | terminal-voice-adapters | TV-01 | TV-01-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-optional-runtime-adapters | terminal-voice-adapters | TV-02 | TV-02-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-optional-runtime-adapters | terminal-voice-adapters | TV-02 | TV-02-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-optional-runtime-adapters | terminal-voice-adapters | TV-03 | TV-03-S1 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-optional-runtime-adapters | terminal-voice-adapters | TV-03 | TV-03-S2 | 2.1, 2.2, 2.3 | NOT_RUN | +| add-optional-runtime-adapters | persistent-stdio-adapters | STDIO-01 | STDIO-01-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-optional-runtime-adapters | persistent-stdio-adapters | STDIO-01 | STDIO-01-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-optional-runtime-adapters | persistent-stdio-adapters | STDIO-02 | STDIO-02-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-optional-runtime-adapters | persistent-stdio-adapters | STDIO-02 | STDIO-02-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-optional-runtime-adapters | persistent-stdio-adapters | STDIO-03 | STDIO-03-S1 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-optional-runtime-adapters | persistent-stdio-adapters | STDIO-03 | STDIO-03-S2 | 3.1, 3.2, 3.3 | NOT_RUN | +| add-optional-runtime-adapters | cli-typed-results | CLI-01 | CLI-01-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-optional-runtime-adapters | cli-typed-results | CLI-01 | CLI-01-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-optional-runtime-adapters | cli-typed-results | CLI-02 | CLI-02-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-optional-runtime-adapters | cli-typed-results | CLI-02 | CLI-02-S2 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-optional-runtime-adapters | cli-typed-results | CLI-03 | CLI-03-S1 | 4.1, 4.2, 4.3 | NOT_RUN | +| add-optional-runtime-adapters | cli-typed-results | CLI-03 | CLI-03-S2 | 4.1, 4.2, 4.3 | NOT_RUN | diff --git a/docs/openclaw-integration/validation-report/README.md b/docs/openclaw-integration/validation-report/README.md new file mode 100644 index 0000000..8d28576 --- /dev/null +++ b/docs/openclaw-integration/validation-report/README.md @@ -0,0 +1,22 @@ +# 完整文档结构检查报告(无损分段) + +原始报告为 `validation-report.json`,127699 字节。为避免连接器长内容传递被截断,使用 gzip + Base64 并分为 3 段存储;不删改原报告的任何字段、检查项或格式。Markdown 摘要见 [validation-summary.md](../validation-summary.md)。 + +## 恢复原始 JSON + +从仓库根目录运行以下命令,输出到当前目录的 `validation-report.json`: + +```bash +python3 - <<'PYCODE' +import base64, gzip, hashlib +from pathlib import Path +parts = Path("docs/openclaw-integration/validation-report") +encoded = "".join(p.read_text().strip() for p in sorted(parts.glob("part-*.b64"))) +raw = gzip.decompress(base64.b64decode(encoded, validate=True)) +assert hashlib.sha256(raw).hexdigest() == "a689415d7e7c1a28cc50a97179c797adc29080b30f5ec929aa8ed23227a1a598" +Path("validation-report.json").write_bytes(raw) +PYCODE +``` + +原始 JSON SHA-256:`a689415d7e7c1a28cc50a97179c797adc29080b30f5ec929aa8ed23227a1a598`。 +原始报告保留首次文档编制阶段的检查结果;不是官方 OpenSpec CLI 或 SDK 产品测试结果。 diff --git a/docs/openclaw-integration/validation-report/part-001.b64 b/docs/openclaw-integration/validation-report/part-001.b64 new file mode 100644 index 0000000..e63b114 --- /dev/null +++ b/docs/openclaw-integration/validation-report/part-001.b64 @@ -0,0 +1 @@ +H4sIAAAAAAAC/9Wdb2/bVtLF3/dTEOnLLRN7xs0+7b5yE24SILWDWOEaWCyKa/JaZk2RXJJyIiz63Z9L6m8dypIbnUMaCIKEknhmRj/eOxzdO/zfd573rLRFXtajWWGf/ew9i6ZVnU/8OI+mE5vVflWX06ieltaPbmx062d57efX10mUmNTPC5tVhY38KE2e/dCcLCqtqW18Wn+qo+Z0ciQv/aOffDkaHevP8vLnH4+eHx2f/KTHfzs6+vnoaPGpfJrVlXv//9z/mv/fmGxsmwMvf1gcMYW5StKkTtrDcrw4Xtr/TpPSNqa2bz9ZHK8im5kyyZuDx/J/i6O1qW6bIz/9fXnafFKk1hk8Wrxy5I7/0dpUTScTU842jXL+t+c7Pl5+vjBVZeM/H7s2SdoeW59rGbBzF68LF6/QpEls6iTP1qevalNPm9M/Ozsf/fbx09mzlYumat/4bBluz36x0bQ2V6n13PfhJZn7cOpE/+FlxcQr7ThxX9vMS/P8dlp4c4O8z0l94wWn7347fXP67sx7fXbh2bLMy6WO/eJO7ULxKneOZ/GfBO/mBlvP952Q+9udP4lq948s95OstqWJ6uSuef33xtiV50WZx46fTofj21+mSRp3uBzlsR2XprjpeC11Mm+cKZ/NrOPVygWmTOrZRWSyzlhW+bSM7Icyv3Y0ZePN96yMXn3T/24/NbfXHc/MZH6N5Nl1Mvamla285VfrtddBXDrrMq9yZ5iYhehcdprWzUc/nF5crI/HtnbfTXP8WXvojx+6Ba9MZZ211n21UV7Glbe8PNuQ+nmWzrwFPwfTbOLs3dmycgpeUjnmitR5Wjuphjn3SnKdOM4PJlglX7wiNVnmWF0MAE7UkXw4CVs1F01S3fgOPr+5+F0A22Fl5o9z51JmsqiJcjuoxJ4p6+TakV3RTZi407kLxtCF3QVb5JXj+fvvvX/dzHrWN7X3ajEX9GnIq83Zp0dDvvfO7OcBWfNrHreDwGBM8t6590R1byb4qzxl5l0lv7v5tJnyHmHNsRfbKDVlO7BX3gvv2HMTlQvqIazMHDzOQK/5WOXd2itz5QyuLD1cTQ5xPW2ySq9Nybxp1s65h5xOHmHK3IYb4ya85SznmSiyRd28hW5SY46XxG56by6usolO8t/pAe14UP06KavaUZjWxqvmADfT/4dp6QhnGbFQ81KbjV3W6qaB1GXBtffjUZMaNMmmiwvJlja7On39OnjtXedlcxG5/y8TsCZXgYx9+yQo7V2PG3ts5f5xOOk356F/dOyN0/zKXR2zg+O3OP+NqVwmWU5Me+Nw8fb0/XvPxffXTxejg2utAKo/59763vDAMv4FPGqNxJt3YXDm/eut+2vk/jq8hOC9ELAXaBeEiK9w8BU8voLHV/D4Ch5fBbugRHyVg6/i8VU8vorHV/H4noBdOCHie8LB9wSP7wke3xM8vidQfE0c+3nR3PS4m/ly6m7BJtY3sSmaGw5oYfBh5cPXAx/Wg5UBHyOLqP7tr4+pae2tj6z1PcIIcIlv/6/j0JW9/ZS/uaCn9wt6uk9B72Hj8HW8h/UZ5bvdFrCqdg9bAi/WOZVJ0kjf5Um0Icyq023TJ5fotpnRT3VumzXYwtwIW5cb8cpyI0pVbgQvyo3gNbkRvCQ3glfkRtiC3IhXjxtRynEjeDVuBC/GjeC1uBG8FDfCVuJGvELciFKHG8HLcCN4FW4EL8KN4DW4KE38elbY2J+fiZcsfq1MThO/NqCfBPFrO7Cp4av376C54eL8lMFqoYUereYy0OFqLQG71pcSgvdCwF6gXRAivsLBV/D4Ch5fweMreHwV7IIS8VUOvorHV/H4Kh5fbL5YNKv8q3q+3SdOcn6RcbsF5PxxuyH95JHb7cHmkxej1+/OoRnlSoEyqq3U0OPaUgg6sm2KwEaFtYgwPBG4J3g3hAqzsGAWBszCgFkYMAsDZoW7oVSYlQWzMmBWBszKgBmbeV4nX9pN5FFqPvtFmdd5lKd+lGd1k9lhF1zt0j78kqtdirBFV48TRiy7eowFmJVGj7AAufTqUWaAF1895ks59PKrfbW/eQHWj/cXYP24zwKsXebhl2DtsoCxCGsfG1jLsHbZAl+I5T5fOIJs1TS/sGaSZGNafaRLm1wZ6TKhn5pIlyXYasjHiw/QWsji/JR8e6GFzrbnMtBcey0By0+XEoL3QsBeoF0QIr7CwVfw+AoeX8HjK3h8FeyCEvFVDr6Kx1fx+CoeX2yNo87ztPKT7C6/tat8lbd8v1OdvXi/04ielu532gJeuH9+/h67dH8hwFlMuhCDLyed62AXlK41cEtKlxpC8EPQfsCdECbFQqJYCBQLgWIhUCwEihXthDIpVhLFSqBYCRQrgWJsUlnZqmnM6t8kVZ2XM35eudUAduu2bXb01LZtmznYBPPtu4sRNMFcClAGtaUYelBb6EAHtQ0N2GCw0hCCH4L2A+6EMCkWEsVCoFgIFAuBYiFQrGgnlEmxkihWAsVKoFgJFGMTzPH8EQt+bO/aDhdTl8uxcssubXJa2WVCPxlllyXYZPL00+gtNJlcClAGsKUYegBb6EAHsA0N2IW/0hCCH4L2A+6E diff --git a/docs/openclaw-integration/validation-report/part-002.b64 b/docs/openclaw-integration/validation-report/part-002.b64 new file mode 100644 index 0000000..a10fe7a --- /dev/null +++ b/docs/openclaw-integration/validation-report/part-002.b64 @@ -0,0 +1 @@ +MCkWEsVCoFgIFAuBYiFQrGgnlEmxkihWAsVKoFgJFHOSSZep1b69a9MWdjK5qd1TMrlpQr/J5KYl4MYkb0+xlcmlAGdz/EIMvjt+roPdHr/WwO2PX2oIwQ9B+wF3QpgUC4liIVAsBIqFQLEQKFa0E8qkWEkUK4FiJVCsBIoV3qJ/mcfkhV1u7EL35u+QxDTl7xCCduPfqYdqw79DGNdw/mFhdOP9XeqEjvs7Io9otf+A5Ddv8Xx5f4vny3177HdYxWmu3yHM6qq/RZrZTr/DBPj2zajMs/lynDzl9UPdFGW3Qt3U7qkL6qYJ4DrDx/MzbJ1hIcDJbRdi8Nx2roPNbdcauNx2qSEEPwTtB9wJYVIsJIqFQLEQKBYCxUKgWNFOKJNiJVGsBIqVQLESKAZ30Xf3vJlN/SyPLT9x7BJnJ5BdNvSUSHaZAk4owekkMZnkpJL4RBKfRuKTSHwKCU4giekjJ3nEp474xBGfNuKTRnDKSEwYOekiPlnEp4r4RBGeJjaFS99M46T2V7888bp7dImzm3t02dBTb48uU7Bp4vkvF9A8cXF+ysC10EKPXHMZ6NC1loBd90sJwXshYC/QLggRX+HgK3h8BY+v4PEVPL4KdkGJ+CoHX8Xjq3h8FY8vuMSYZ9fJeDr/DZxfY+xUZxcZO43oqcrYaQu4zPjPN9g64/z8nBvfuRb8zreVwd76riRw974LCcF7IWAv0C4IEV/h4Ct4fAWPr+DxFTy+CnZBifgqB1/F46t4fBWPL761sD/JXaroR6Y2aT6uqI2F72v30Fb4vgn9NRW+bwk4b0Rvq2TuqiRtqiTsqSRsqSTsqCRsqETvp2RupyTtpiRspiTspSRspSTspERvpGTuoyRtoyTsoiRsoiTsocRvoaxukzT1i3Q6TjI/Ta5tNItSy+sd3C3P7hzcbUVPfYO7jcHmkMElNodcnJ8yii200KPYXAY6iq0lYNf/UkLwXgjYC7QLQsRXOPgKHl/B4yt4fAWPr4JdUCK+ysFX8fgqHl/F44tvwzExmRnb9X7uKE1cggJvxbFFFtOOY4sYtCXHXpqothx7iOM6U+wWR7fn2McCQouOPb4FRJuOHbLf3KpD77fq0H1bdWyxjNOuY4s4q2XHA/LMth1bzIC37qhnhVNt21X6sU1dHlPOeL9zdYmzf+jqsqGnX7q6TAGXKUJwmSIklilCTpkixJcpQnyZIsSXKUJ8mSIElylCYpki5JQpQnyZIsSXKUJ8mSLElylCcJkiJJYpQk6ZIsSXKUJ8mSLElylCeJlimbOWRURLGTc1yZnipnQ/CeKmBdi88OOHV9C8cHF+ysi00EKPTHMZ6Mi0loBd00sJwXshYC/QLggRX+HgK3h8BY+v4PEVPL4KdkGJ+CoHX8Xjq3h8FY8v55FEpY1yaj3xK+GeHka00u/3SUQrM8C5YgDOFQNirhhwcsUAnysG+FwxwOeKAT5XDMC5YkDMFQNOrhjgc8UAnysG+FwxwOeKAThXDIi5YsDJFQN8rhjgc8UAnysGrxhLncy4+cWzslXV9IYwRVHmd816iD83iYAtedohj1n6tEMUugTqUdqopVCPMAK3Emh/I9BLox5jCWGJ1CO+HcRSqT3le1wytcNCztKpHUawllDtYQZzKdUOc+BLqub6/K1f93XJxY/78v3UPu5bgS19nL4JzrALqFYKnIfIL9XgT5FfCGEfI78hgnuO/EpEGJ4I3BO8G0KFWVgwCwNmYcAsDJiFAbPC3VAqzMqCWRkwKwNmZcAMLpLcz2FpKeV9YXZOeV+/p6RyS0kKlVV++IjNKefn54xbcy34qNXKYMeslQRuxFpICN4LAXuBdkGI+AoHX8HjK3h8BY+v4PFVsAtKxFc5+CoeX8Xjq3h8wf2nFnVPdqp4X5fdceqefE+tpu5Zgc0TL4IL7AOSlgKUsWophh6sFjrQ0WpDA3ahrzSE4Ieg/YA7IUyKhUSxECgWAsVCoFgIFCvaCWVSrCSKlUCxEihWAsXghyat11PknzOXoN0kxcEdmZgk86rCRpXX5EnN/7J8sabDZWZX9sbcJXl5QK/KvKr8qF3F5DLhwmaxzaKZNy5NcdMkw6b5rTiJDtjJw+W3dhnJdhF+5dl2Kf7yIvLsF5cCp80WgUOuf3hzHi7yjtYErzBl00ZmvtyhniGESnttnUhknYtfkqpOsvF8uQdCzH6x0bS9h6lqU1vv7Hz028dPZ4eXElYAhRlAIQVQWAQKk0DhESgsAoVJoPAIVBaByiRQeQQqi0BlEqg8Ak9YBJ4wCTzhEXjCIvCESeAJhcCPFx84eeBaiBDAtRgtgMIKoDADyCJQWAQKk0DhESgsAoVJoPAIVBaByiRQeQQqi0BlEsjJA1+9XT2zDhzBDSVCCDfUeDEUWgyFGkMah0LjUKgcCpFDoXEoVA6FyKHSOFQqh0rkUGkcKpVDzrx8+mn0ljMvbygRYrihxouh0GIo1BjSOBQah0LlUIgcCo1DoXIoRA6VxqFSOVQih0rjUKkccublt+8uSPfLG0qEGG6o8WIotBgKNYY0DoXGoVA5FCKHQuNQqBwKkUOlcahUDpXIodI4VCqHnHl5dH7+njMv diff --git a/docs/openclaw-integration/validation-report/part-003.b64 b/docs/openclaw-integration/validation-report/part-003.b64 new file mode 100644 index 0000000..ced11fe --- /dev/null +++ b/docs/openclaw-integration/validation-report/part-003.b64 @@ -0,0 +1 @@ +bygRYrihxouh0GIo1BjSOBQah0LlUIgcCo1DoXIoRA6VxqFSOVQih0rjUKkccubl9fOA0D/Qr4QYP9CvxGgBFFYAhRlAFoHCIlCYBAqPQGERKEwChUegsghUJoHKI1BZBCqTQNIsHLBm4YA5Cwe8WThgzcIBcxYOeLNwwJqFA+YsHPBm4YA1CwfMWTjgzcIBaxYOmLNwwJuFA9YsHDBn4YA2C7fPu2bMwmshQgDXYrQACiuAwgwgi0BhEShMAoVHoLAIFCaBwiNQWQQqk0DlEagsApVJIGll9cYjN9DL4DakGOvgNuSIYRReGIUbRh6NwqNRuDQKk0bh0ShcGoVJo/JoVC6NyqRReTQql0bOTL3RohYcxQ0lQhA31HgxFFoMhRpDGodC41CoHAqRQ6FxKFQOhcih0jhUKodK5FBpHCqVQ9Id9OoxQ+jkZiXESG1WYrQACiuAwgwgi0BhEShMAoVHoLAIFCaBwiNQWQQqk0DlEagsApVJIKlz1z/fkBp3rYQYPVZWYrQACiuAwgwgi0BhEShMAoVHoLAIFCaBwiNQWQQqk0DlEagsApVJIGkW/nh+RpqG10qMEK7VeDEUWgyFGkMah0LjUKgcCpFDoXEoVA6FyKHSOFQqh0rkUGkcKpVD0rxMa2tN7WpNbGpN62lNbWlN7GhNa2hN7WdNbGdN62ZNbWZN7GVNa2VN7WRNbGRN62NNbWPN62IdXLJ2PF0ydzxd8nY8XbJ2PF0ydzxd8nY8XbJ2PF0ydzxd8nY8XbJ2PF0ydzxd8nY8XbJ2PF0ydzxd8nY8XbJ2PF0ydzxd0mbhV6wKNbM+zatOs2rTzMo0ry7Nqkoza9K8ijSrHs2sRvNq0axKNLMOzatCs2rQzAo0rf58/gtp69JaiBC/tRgtgMIKoDADyCJQWAQKk0DhESgsAoVJoPAIVBaByiRQeQQqi0BlEkh6KkRIeiZESHwiREh7HkRIehpESHwWREh7EkRIeg5ESHwKREh7BkRIegJESHz+Q0h7+kNIevZDSHzyQ0h77kNIeupDSHzmQ0jr2jF6/e6c1LZjQ4qxx3pDjhhG4YVRuGHk0Sg8GoVLozBpFB6NwqVRmDQqj0bl0qhMGpVHo3JpJP0u/P4d6YfhlRCjxr8SowVQWAEUZgBZBAqLQGESKDwChUWgMAkUHoHKIlCZBCqPQGURqEwCWc9mOn39a/B8Eju/UlMnd9ZLk+zWi/OoepEXzs/UfPaTrLbj0jSGvLgzaRK3//Sr6WRiypn7dJ8GlbmJJ6bo2Yoov7OlGVv/ylTWvdf2bE+VT8vI+qUdO0Zt2bM1JopsURt31fhFarKerWnHCnOVpG6IAJmS5d40u06ypLqxsed8juxNnsa2RIhdmbQJbexFeWy963ZwOpxOE8KqsNELqncdqlg398aF4f3+xvQVlK/Hl37j0mFPX6FZT0j9hmTDjr5C8fW4329IOuzpKzSdedS9KWzjPaUt8rJ+/nuVZ/1Z1+t3121SX19fV75379tDpmCPNKzXL67TIlLOEt2YbGyrF9bdP12lzn2/im/9KJ8Uzrb5LOqPG/uyxpoXsa2Scfb1V/n8+Yv5n75uAHpwCJYlf7svzPzzLxs5TMKLMi/yyqQDD+OmmcMMZFvzGXgUVzaSQ2ji2M+LZhQxqV9OszqZWN/EpnDTYPWEBlmYH7yxdV8X+qB4X9sGRW/fA+j+1g0qbL0Ol3uaRg7YdfLFX40O7our8yhP3WCeNaND/ZTGSaAnvJFyfyf6QHh/6wZGcd/j5WPsG1joeh0z9zauh2lmbGr72cwa++bDxFNLKg/rADebfND2vmb3B40aBqFDSBx3mDWMQPWeKj5kUw8hmpjMjU5rs6I0sVn9xEa8wzvBHfV22t8XrDsNGw6xQxgB9zBtOAHrfSTcZVcPoXL2ZLVf2apqfgk0hfvm7swiMc3TJzYq4pzhjo57+9EXyHsbODyihzBqPsLE4QWw91F0X/uGF7rm/e6N7ZvS5NpGsyi17dEBx/Nhowcb5K7Dw4/yNquHGubly08qytuMHk6mOreznhXuJXvXuBS7FMrlU7PeI/zXLR5aeJcvlkU07Kh2GTq0YC4PlrbN+wfO6VZrh1GymxsZlQMaWB9n5aDC6N6U2dTPnClPIJwPWTuksDZptm+mcVL7pqyT6/ZXrMGG9UFrB0Vr7uI2ns4PPgFcHzR3ULzmeepPnB0uGzS1SfPxkHF9wNghBbW6TdLUL9LpOMkGdEf7V+0d2IKFuc1OtnAe2Mqv6tKaSZKNew3wt1s9yDA3l1zlJ9ldfmtXLz6BQD9s9yBDvbz/vkmqOi9nTynaO00fZMCX42Fs75LIujyovnkCsX7I6kGH2X2qnhdBqicU5i6rB7XmeTHe2dJNJu71u7ylYvPVYS6I3s/uAYY6ShN/XtGbyw8/yNstHmB4XXJaNVtZm4J1HSf502F5t+XD3GS2mMN3vWXg29Ae4QX2a4hyh0flTUwd3XiN+F1iP/+F07u//9O8+syWZV5W7pV//+e7P777f8zCSQ7T8gEA diff --git a/docs/openclaw-integration/validation-summary.md b/docs/openclaw-integration/validation-summary.md new file mode 100644 index 0000000..3222db2 --- /dev/null +++ b/docs/openclaw-integration/validation-summary.md @@ -0,0 +1,33 @@ +# 文档检查结果 + +检查对象:OpenSpec 文档包 0.1.0-draft。本页先保留首次文档编制的检查记录,再列出后续 G0 证据和当前校验;压缩报告只对应首次检查。 + +## 实际执行 + +首次编制时使用文档结构检查器,检查必需产物、schema/metadata、proposal 与 capability 的一一对应、Purpose 长度、Requirement/Scenario 格式、规范关键词、任务验收条件、初始任务状态、全局 ID 唯一性、场景到任务的引用、依赖无环、相对链接和代码围栏。 + +结果:内部结构检查通过,0 项失败;精确检查数量以 validation-report/ 中保存的完整报告为准。 + +这不是官方 OpenSpec CLI 输出,也不是产品测试通过数。 + +| 交付项目 | 数量 | +|---|---:| +| OpenSpec changes | 6 | +| Capability specs | 21 | +| Requirements | 64 | +| Scenarios | 128 | +| 实施任务 | 97 | +| 已勾选 G0 准入证据任务 | 6 | +| 待完成任务 | 91 | + +## 后续验证与剩余门禁 + +首次编制时官方 OpenSpec CLI 校验为 NOT_RUN;后续 G0 证据提交使用 OpenSpec 1.8.0 strict 校验 6/6 通过。2026-11-18 使用 OpenSpec 1.14.1 对本分支执行 `openspec validate --all --strict --no-interactive --json`,6/6 changes 有效,0 个 issues。 + +后续 G0 证据还记录了三分支 CodeGraph、Maven 构建和测试,详情及当时的 SDK SHA 见 `openspec/changes/establish-sdk-compatibility-governance/evidence/2026-09-20-precursor-evidence.md`。2026-11-18 完成 [真实 Gateway 基线验证](../../openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-live-gateway.md)。三条维护线通过健康、认证和读取权限检查,默认分支握手失败。漏洞扫描、资源和堆分析尚待执行。 + +## 阶段结论 + +文档结构检查和当前 OpenSpec strict 校验通过,内容保持 DRAFT / REVIEW_REQUIRED。目标 Gateway 版本已有记录但待人审确认;G0 剩余任务和完整 SDK 功能验收仍待完成。评审先从 G0 兼容治理和 G1 现有协议修正开始。 + +详细逐项输出见 [完整报告与恢复说明](validation-report/README.md)。 diff --git a/openspec/README.md b/openspec/README.md new file mode 100644 index 0000000..059904b --- /dev/null +++ b/openspec/README.md @@ -0,0 +1,7 @@ +# OpenSpec 工作区说明 + +模式:spec-driven。项目状态与阅读入口见 [文档索引](../docs/openclaw-integration/README.md) 和 [总体路线](../docs/openclaw-integration/roadmap.md)。 + +六组 active changes 都是待评审提案,尚未执行实现。specs/ 根目录有意保持没有生效 capability,防止把未来行为伪装成已经实现。 + +ADDED 是首次建立规范条目,不说明此前不存在相关 SDK 代码;后续合入已有规范时,必须核对同名能力并按实际基线选择 MODIFIED 完整条目。不要仅为通过格式校验随意切换 delta 类型。 diff --git a/openspec/changes/add-agent-session-approval-control/.openspec.yaml b/openspec/changes/add-agent-session-approval-control/.openspec.yaml new file mode 100644 index 0000000..cbd245e --- /dev/null +++ b/openspec/changes/add-agent-session-approval-control/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-09-20 diff --git a/openspec/changes/add-agent-session-approval-control/design.md b/openspec/changes/add-agent-session-approval-control/design.md new file mode 100644 index 0000000..5a6f18a --- /dev/null +++ b/openspec/changes/add-agent-session-approval-control/design.md @@ -0,0 +1,55 @@ +# 建立 Agent、Session 与 Approval 执行闭环 — Technical Design + +状态:DRAFT / REVIEW_REQUIRED。下述新类与模块名称为拟议设计,不是仓库已存在能力。 + +## Context + +动机与范围见 proposal.md;固定的 SDK HEAD、静态观察和证据等级见 [coverage-baseline](../../../docs/openclaw-integration/coverage-baseline.md)。当前文档基于公开协议说明和此前源码静态核查,不包含真实 Gateway 验证。在线文档随时间变化;目标版本锁定仍是实施前的阻断条件。 + +## Goals / Non-Goals + +用可观察契约约束新增或修正行为;保留三条 Java 发行线的既有基线与可行的源码兼容。只引入本变更需要的组件,不进行无关重构。SDK 不代替 Gateway 做权限裁定,也不代替宿主存储或授予长期凭据。 + +## Decisions + +新增组合式 AgentClient、SessionClient 和 ApprovalClient,复用受管理 RPC 与事件交付;不继续把所有方法堆到 OpenClawClient。门面仅提供领域入口与少量兼容便捷方法。 + +RunHandle 保存已知的 agentId、sessionKey、sessionId、runId、关联任务与本地等待状态。远端运行事实和本地 Future 状态分开存储,wait timeout 不等于 runtime failure,local cancel 不等于 remote cancel。取消方法需从锁定目标版本中明确映射,不能臆造 agent.cancel。 + +Agent 定义与文件管理绑定明确目标。Session 控制支持创建、解析、描述、修改、重置、删除、压缩和准确订阅;以服务端实际返回身份更新状态,不盲目把 sessionKey 当物理身份。 + +审批读取、事件和决策分别建模,保留审批类型与有效决策,服务端决定唯一权威终态。不会在构造器、事件监听器或恢复流程里自动批准。并发已决、过期、拒绝、权限不足与断线不确定均为一等结果。 + +备选方案是统一成一个 Object/Map 管理客户端,扩展快但下游难以正确处理生命周期;另一方案是把审批放在本地自动策略中,越过了宿主授权意图。本方案选择窄领域 API 和服务端权威结果。 + +## Technical Approach + +Agent 提交 → RunHandle → 订阅/等待 → 审批事实通知 → 宿主显式决策 → 远端状态对账 → 最终结果 + +错误类型和状态转换由共享协议层统一;本地超时/取消与远端失败/取消分开。以下源码触点仅用于实施规划,新增路径在接入前需核对实际工作树,不把不存在的文件列为已修改: + +- `src/main/java/io/github/easy4j/openclaw/ws/(新增 Agent 领域客户端与运行句柄)` +- `src/main/java/io/github/easy4j/openclaw/ws/protocol/params/` +- `src/main/java/io/github/easy4j/openclaw/ws/protocol/result/` +- `src/main/java/io/github/easy4j/openclaw/ws/(新增 Session 领域客户端)` +- `src/main/java/io/github/easy4j/openclaw/ws/(新增 Approval 领域客户端)` + +## Risks / Trade-offs + +本地与远端状态混淆 → 在类型和测试中分开表示;事件早于受理响应 → 在受管理层预登记关联并通过服务端身份对账。 + +所有新状态、上限和取消语义必须进入验收;不得使用修改测试预期、跳过不兼容分支或放宽权限来消除失败。 + +## Migration Plan + +先记录对应旧行为并建立最小失败样本,再实施局部修正或加法 API,最后同步其余分支与文档。按 capability 小批提交,避免跨无关领域的大规模替换。回滚只回退该功能变更和明确可逆状态;配置落盘、已执行工具或已投递消息的外部副作用不宣称自动撤销。根 specs 的更新留到经批准的归档阶段。 + +## Validation Strategy + +需求与场景的逐项映射见 [traceability](../../../docs/openclaw-integration/traceability.md)。每项能力须完成固定样本验证、受控模拟、适用分支构建及真实 Gateway 验收。资源测试至少覆盖成功、失败、取消、deadline、断线和用户回调异常。缺失环境的测试记录 BLOCKED,不记录 PASS。 + +## Sources + +[O01 外部应用接入边界](https://docs.openclaw.ai/gateway/external-apps);[O04 会话启动、快照及事件语义](https://docs.openclaw.ai/gateway/protocol/rpc-bootstrap-and-events);[O06 会话控制与历史](https://docs.openclaw.ai/gateway/protocol/rpc-session-control);[O08 设备、Node、审批与 Cron RPC](https://docs.openclaw.ai/gateway/protocol/rpc-devices-nodes-and-approvals);[O11 Talk、Agent 与产物 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-talk-config-and-agents) + +上游文档用于需求依据;本 SDK 的方法签名、状态名与组件结构属于本方案设计。每个 wire 字段和方法在实施前还须与锁定版本确认,不能凭字符串拼接猜测。 diff --git a/openspec/changes/add-agent-session-approval-control/proposal.md b/openspec/changes/add-agent-session-approval-control/proposal.md new file mode 100644 index 0000000..d28d4fc --- /dev/null +++ b/openspec/changes/add-agent-session-approval-control/proposal.md @@ -0,0 +1,39 @@ +# 建立 Agent、Session 与 Approval 执行闭环 + +状态:DRAFT / REVIEW_REQUIRED。文档已提出,未批准实现,未归档。优先级:P1。 + +## Why + +Java 应用需要管理运行而不只是发送一条聊天消息。补齐运行句柄、会话生命周期和人工审批,才能准确表达受理、等待、决策、取消与最终结果。 + +## What Changes + +- `agent-lifecycle`: Agent 运行与定义管理。 +- `session-control`: 会话控制与订阅。 +- `approval-control`: 人工审批闭环。 + +此次交付只创建 OpenSpec 文档与证据清单,不修改 Java 代码、构建文件、测试、依赖或发布配置。本提案描述后续拟实施行为,不证明这些能力现在已完成。 + +## Capabilities + +### New Capabilities + +- `agent-lifecycle`: Agent 运行与定义管理。 +- `session-control`: 会话控制与订阅。 +- `approval-control`: 人工审批闭环。 + +### Modified Capabilities + +无现有同名 OpenSpec 生效规范可修改。本次是首次引入这些能力的正式规范条目,因此使用 ADDED Requirements;并不意味着仓库中不存在相关旧代码。 + +## Impact + +适用分支为 feature/1.0.x、feature/2.0.x、feature/3.0.x。具体源码触点见 design.md;可观测行为见 specs/;验证与执行步骤见 tasks.md。main 不作为第四条已验证发行线。 + +依赖变更:`add-managed-gateway-client` + +不在范围:重写 OpenClaw 内部模型引擎、原生插件运行时、沙箱内核或 Gateway 私有 worker 协议;不提供自动授权、跨租户共享密钥隔离或恰好一次执行保证。 + +## Review and Entry Criteria + +必须完成人工范围评审、锁定目标 Gateway 构建与协议映射,并完成依赖变更的必要验收后,才能进入本变更实现。OpenSpec 的 artifact 完整性状态不等于人审通过或产品已完成。具体门禁是本项目约定,而非声称 OpenSpec 官方强制该流程。 diff --git a/openspec/changes/add-agent-session-approval-control/specs/agent-lifecycle/spec.md b/openspec/changes/add-agent-session-approval-control/specs/agent-lifecycle/spec.md new file mode 100644 index 0000000..3251fab --- /dev/null +++ b/openspec/changes/add-agent-session-approval-control/specs/agent-lifecycle/spec.md @@ -0,0 +1,52 @@ +# Agent 运行与定义管理 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的Agent 运行与定义管理定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: AGENT-01 受理和执行结果分离 +SDK SHALL 区分运行请求受理、执行中、等待到期、远端失败与远端成功;运行句柄 SHALL 保留已返回的 runId 及作用域身份,不能以受理成功代替完成。 + +#### Scenario: AGENT-01-S1 运行已受理 +- **GIVEN** 提交有效 Agent 运行且服务端返回运行标识 +- **WHEN** SDK 返回受理结果 +- **THEN** 状态为已受理而非已完成,并提供后续等待或查询入口 + +#### Scenario: AGENT-01-S2 等待返回 pending +- **GIVEN** 运行仍在进行 +- **WHEN** 一次等待到期或返回 pending +- **THEN** 保留仍在运行或未知状态,不将其改为远端执行失败 + +### Requirement: AGENT-02 运行取消使用正式控制路径 +SDK SHALL 区分停止本地等待与请求远端取消;远端取消 SHALL 使用目标版本明确支持的作用域和方法,并以确认或后续状态判定结果。 + +#### Scenario: AGENT-02-S1 请求取消 +- **GIVEN** 运行标识已知且宿主具有权限 +- **WHEN** 用户显式请求远端取消 +- **THEN** 按正式控制路径发出并保留确认,不擅自杀死 Gateway 进程 + +#### Scenario: AGENT-02-S2 取消未确认 +- **GIVEN** 取消请求发出后连接断开 +- **WHEN** SDK 结束本地等待 +- **THEN** 报告取消结果不确定而非已取消,允许以运行身份对账 + +### Requirement: AGENT-03 定义和文件管理有明确作用域 +SDK SHALL 提供目标版本支持的 Agent 列表、创建、更新、删除与文件管理契约;文件和删除请求 SHALL 保留目标 Agent 和路径范围,不能自动跨 Agent 回退。 + +#### Scenario: AGENT-03-S1 Agent 文件更新 +- **GIVEN** 指定 Agent 与允许路径 +- **WHEN** 提交文件内容 +- **THEN** 只返回该目标的服务端结果和版本事实 + +#### Scenario: AGENT-03-S2 拒绝越界 +- **GIVEN** 路径或 Agent 不获授权 +- **WHEN** 服务端拒绝文件操作 +- **THEN** 保留错误,禁止改写到其他目录或以 CLI 提权补做 + +## Sources + +[O01 外部应用接入边界](https://docs.openclaw.ai/gateway/external-apps);[O11 Talk、Agent 与产物 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-talk-config-and-agents) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-agent-session-approval-control/specs/approval-control/spec.md b/openspec/changes/add-agent-session-approval-control/specs/approval-control/spec.md new file mode 100644 index 0000000..59252c3 --- /dev/null +++ b/openspec/changes/add-agent-session-approval-control/specs/approval-control/spec.md @@ -0,0 +1,52 @@ +# 人工审批闭环 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的人工审批闭环定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: APR-01 审批对象及类型可区分 +SDK SHALL 支持目标版本的审批读取、决策和历史,并区分通用、exec 与 plugin 审批对象;呈现经授权的范围、请求原因、期限和有效决策,不自动批准。 + +#### Scenario: APR-01-S1 显示待审批项 +- **GIVEN** 收到获准可见的审批事件 +- **WHEN** 上层读取审批详情 +- **THEN** 得到准确审批 ID、类型、可用决策和有效期限 + +#### Scenario: APR-01-S2 权限不足 +- **GIVEN** 连接没有审批查询或决策权限 +- **WHEN** 访问审批 +- **THEN** 得到真实授权错误,不从其他会话泄露详情 + +### Requirement: APR-02 并发决策尊重服务端终态 +SDK SHALL 将服务端已决、已过期或不存在结果映射为可辨识状态;重复或竞争决策 MUST NOT 被当成新的执行授权。 + +#### Scenario: APR-02-S1 另一操作员已处理 +- **GIVEN** 两个操作员读取同一待审批对象 +- **WHEN** 第二人提交过时决定 +- **THEN** 显示已有终态或冲突并刷新,禁止覆盖或二次执行 + +#### Scenario: APR-02-S2 过期审批 +- **GIVEN** 审批期限已到 +- **WHEN** 调用者提交决定 +- **THEN** 显示过期状态,SDK 不为其重建新的审批以规避限制 + +### Requirement: APR-03 审批事件是事实而非执行指令 +审批通知 SHALL 只改变审批视图与对应运行状态;SDK MUST NOT 因收到请求事件自动执行命令,断线恢复 SHALL 通过权威查询弥补事件缺失。 + +#### Scenario: APR-03-S1 收到请求 +- **GIVEN** 一个 exec 审批请求事件到达 +- **WHEN** 事件被处理 +- **THEN** 只通知宿主等待决策,不执行命令 + +#### Scenario: APR-03-S2 丢失已决事件 +- **GIVEN** 断线期间审批已结束 +- **WHEN** 客户端重新连接 +- **THEN** 重新读取审批真相并更新状态,不永久停留在等待 + +## Sources + +[O08 设备、Node、审批与 Cron RPC](https://docs.openclaw.ai/gateway/protocol/rpc-devices-nodes-and-approvals);[O04 会话启动、快照及事件语义](https://docs.openclaw.ai/gateway/protocol/rpc-bootstrap-and-events) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-agent-session-approval-control/specs/session-control/spec.md b/openspec/changes/add-agent-session-approval-control/specs/session-control/spec.md new file mode 100644 index 0000000..63bd0f1 --- /dev/null +++ b/openspec/changes/add-agent-session-approval-control/specs/session-control/spec.md @@ -0,0 +1,52 @@ +# 会话控制与订阅 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的会话控制与订阅定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: SESS-01 会话身份和生命周期管理 +SDK SHALL 提供经目标版本确认的会话创建、解析、描述、修改、重置、删除与压缩入口;同一 sessionKey 不得被视为永久不变的物理会话身份。 + +#### Scenario: SESS-01-S1 重置形成新代际 +- **GIVEN** 调用者重置会话并获得新状态 +- **WHEN** 后续调用使用该会话 +- **THEN** 缓存与订阅更新为新代际,旧状态不可覆盖 + +#### Scenario: SESS-01-S2 压缩未确认 +- **GIVEN** 压缩请求收到受理但无完成事实 +- **WHEN** 返回调用结果 +- **THEN** 只宣告已受理,不伪造历史已压缩结果 + +### Requirement: SESS-02 订阅意图与授权范围明确 +SDK SHALL 提供会话列表订阅和准确会话消息订阅的建立、取消与恢复;列表快照过滤条件 MUST NOT 被宣传为同一连接事件订阅的安全隔离边界。 + +#### Scenario: SESS-02-S1 订阅列表并取快照 +- **GIVEN** 调用者提供非空列表参数 +- **WHEN** 订阅请求成功 +- **THEN** 返回快照与订阅状态,并处理订阅期间交错事件 + +#### Scenario: SESS-02-S2 取消准确订阅 +- **GIVEN** 某会话订阅已建立 +- **WHEN** 调用者关闭订阅 +- **THEN** 释放相应监听与远端订阅,不影响其他会话订阅 + +### Requirement: SESS-03 会话发送区分投递和生成 +SDK SHALL 对发送、历史注入与触发生成保持不同语义,保留服务端返回的运行和投递关联;不以投递确认推断目标 Agent 已完成回复。 + +#### Scenario: SESS-03-S1 投递确认 +- **GIVEN** 消息发送方法返回确认 +- **WHEN** SDK 转换结果 +- **THEN** 保留发送结果而不制造完整 Agent 输出 + +#### Scenario: SESS-03-S2 无执行权限 +- **GIVEN** 用户只能读取会话 +- **WHEN** 尝试发送或触发执行 +- **THEN** 保留权限拒绝且不换用工具或 CLI 绕过 + +## Sources + +[O06 会话控制与历史](https://docs.openclaw.ai/gateway/protocol/rpc-session-control);[O04 会话启动、快照及事件语义](https://docs.openclaw.ai/gateway/protocol/rpc-bootstrap-and-events) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-agent-session-approval-control/tasks.md b/openspec/changes/add-agent-session-approval-control/tasks.md new file mode 100644 index 0000000..6b20a56 --- /dev/null +++ b/openspec/changes/add-agent-session-approval-control/tasks.md @@ -0,0 +1,32 @@ +# Implementation Tasks + +状态:全部未执行。本清单是后续实施计划,不是本轮文档生成记录。 + +## 1. 准入与证据 + +- [ ] 1.1 取得本变更的人审结论并核验依赖;验收:评审记录包含范围、行为收紧、三分支要求和批准的 change ID。 +- [ ] 1.2 锁定目标 OpenClaw 精确版本/提交、构建来源及协议映射;验收:方法、事件、字段、scope 与拒绝样本均有版本化来源,未锁定时停止编码。 + +## 2. Agent 运行与定义管理 + +- [ ] 2.1 为 `agent-lifecycle` 建立契约样本及回归基线(AGENT-01, AGENT-02, AGENT-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 2.2 按 design.md 实施 `agent-lifecycle` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 2.3 在三条适用分支验证 `agent-lifecycle` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 3. 会话控制与订阅 + +- [ ] 3.1 为 `session-control` 建立契约样本及回归基线(SESS-01, SESS-02, SESS-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 3.2 按 design.md 实施 `session-control` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 3.3 在三条适用分支验证 `session-control` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 4. 人工审批闭环 + +- [ ] 4.1 为 `approval-control` 建立契约样本及回归基线(APR-01, APR-02, APR-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 4.2 按 design.md 实施 `approval-control` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 4.3 在三条适用分支验证 `approval-control` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 5. 集成、资源与归档门禁 + +- [ ] 5.1 对本变更执行真实 Gateway 场景;验收:固定服务端版本、认证方式、运行命令与脱敏证据,成功和拒绝均有真实观察,SDK 本地 fixture 通过不能替代。 +- [ ] 5.2 完成适用的资源、故障与兼容检查;验收:1000 次受控请求/订阅周期后活动注册归零,自有线程在测试预算内终止,共享资源仍可使用;治理类变更检查无运行资源触点并记录不适用理由。 +- [ ] 5.3 更新覆盖矩阵并执行规范校验;验收:官方 OpenSpec validate 输出通过、无未解释的三分支差异、所有必需任务有证据且人审允许归档,随后才更新生效 specs。 diff --git a/openspec/changes/add-gateway-operations/.openspec.yaml b/openspec/changes/add-gateway-operations/.openspec.yaml new file mode 100644 index 0000000..cbd245e --- /dev/null +++ b/openspec/changes/add-gateway-operations/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-09-20 diff --git a/openspec/changes/add-gateway-operations/design.md b/openspec/changes/add-gateway-operations/design.md new file mode 100644 index 0000000..ed30b8e --- /dev/null +++ b/openspec/changes/add-gateway-operations/design.md @@ -0,0 +1,61 @@ +# 补齐 Gateway 运营与管理能力 — Technical Design + +状态:DRAFT / REVIEW_REQUIRED。下述新类与模块名称为拟议设计,不是仓库已存在能力。 + +## Context + +动机与范围见 proposal.md;固定的 SDK HEAD、静态观察和证据等级见 [coverage-baseline](../../../docs/openclaw-integration/coverage-baseline.md)。当前文档基于公开协议说明和此前源码静态核查,不包含真实 Gateway 验证。在线文档随时间变化;目标版本锁定仍是实施前的阻断条件。 + +## Goals / Non-Goals + +用可观察契约约束新增或修正行为;保留三条 Java 发行线的既有基线与可行的源码兼容。只引入本变更需要的组件,不进行无关重构。SDK 不代替 Gateway 做权限裁定,也不代替宿主存储或授予长期凭据。 + +## Decisions + +按 Config、Cron、Catalog、Skills/Plugins、Channels/Devices/Nodes、Tasks/Audit/Usage/Artifacts 分组实现。每个组具有独立 DTO、测试和方法映射,共用 RPC/事件核心,不新增多套连接。 + +Config 保存 snapshot hash,读改写带 baseHash;数组替换按 replacePaths 契约处理。持久化与运行时生效分别呈现;不要把失败后的自动覆盖或回滚当成默认恢复。 + +Cron 手动触发只返回排队结果,按准确 runId 查询历史。工具目录与当前有效权限分开;WS 外层 ok 与工具业务 ok 分层。Skills/Plugins 的发现、包传输、安装和运行时发布分别记录;即使新包文件已落盘,也不代表插件已加载。 + +渠道发送保持账户和线程身份;Node 控制区分 operator 与 node 角色。Node 的具体执行处理器由宿主注册且按允许命令执行,不提供默认任意命令处理器。设备配对和凭据操作不自动升级权限。 + +任务、审计、用量和产物是只读/受控查询面。产物下载另用最小权限请求,不携带 Gateway 凭据跨域;流式大小限制和过期处理与正常内容错误分离。 + +备选方案是全部转调 CLI,复用简单但远程场景需要本地二进制且错误语义不稳定;全部动态 Map RPC 则失去类型价值。本方案保留 CLI 兼容,同时提供独立的原生领域 API。 + +## Technical Approach + +领域请求 → 作用域与版本映射 → Gateway RPC → 分阶段结果 → 事件失效通知 → 权威查询/分页 + +错误类型和状态转换由共享协议层统一;本地超时/取消与远端失败/取消分开。以下源码触点仅用于实施规划,新增路径在接入前需核对实际工作树,不把不存在的文件列为已修改: + +- `src/main/java/io/github/easy4j/openclaw/ws/protocol/result/ConfigGetResult.java` +- `src/main/java/io/github/easy4j/openclaw/ws/(新增 Config 领域客户端)` +- `src/main/java/io/github/easy4j/openclaw/ws/protocol/result/CronListResult.java` +- `src/main/java/io/github/easy4j/openclaw/ws/(新增 Cron 领域客户端)` +- `src/main/java/io/github/easy4j/openclaw/ws/(新增 Catalog 领域客户端)` +- `src/main/java/io/github/easy4j/openclaw/api/OpenClawToolInvokeClient.java` +- `src/main/java/io/github/easy4j/openclaw/ws/(新增 Skills 与 Plugins 管理客户端)` +- `src/main/java/io/github/easy4j/openclaw/ws/(新增 Channels、Devices 与 Node 控制客户端)` +- `src/main/java/io/github/easy4j/openclaw/ws/(新增 Tasks、Audit、Usage 与 Artifacts 查询客户端)` + +## Risks / Trade-offs + +一次变更范围大 → 按 capability 与任务组分批实现和审查,未通过的能力不标为支持;高权限操作误触发 → 默认不执行管理写入,仅显式方法调用生效。 + +所有新状态、上限和取消语义必须进入验收;不得使用修改测试预期、跳过不兼容分支或放宽权限来消除失败。 + +## Migration Plan + +先记录对应旧行为并建立最小失败样本,再实施局部修正或加法 API,最后同步其余分支与文档。按 capability 小批提交,避免跨无关领域的大规模替换。回滚只回退该功能变更和明确可逆状态;配置落盘、已执行工具或已投递消息的外部副作用不宣称自动撤销。根 specs 的更新留到经批准的归档阶段。 + +## Validation Strategy + +需求与场景的逐项映射见 [traceability](../../../docs/openclaw-integration/traceability.md)。每项能力须完成固定样本验证、受控模拟、适用分支构建及真实 Gateway 验收。资源测试至少覆盖成功、失败、取消、deadline、断线和用户回调异常。缺失环境的测试记录 BLOCKED,不记录 PASS。 + +## Sources + +[O08 设备、Node、审批与 Cron RPC](https://docs.openclaw.ai/gateway/protocol/rpc-devices-nodes-and-approvals);[O09 Config RPC 更新与生效](https://docs.openclaw.ai/gateway/configuration/config-rpc);[O10 工具、模型与 Skills 管理](https://docs.openclaw.ai/gateway/protocol/operator-methods);[O11 Talk、Agent 与产物 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-talk-config-and-agents);[O12 系统、渠道、插件与终端 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-system-and-channels);[O13 任务、审计及用量台账](https://docs.openclaw.ai/gateway/protocol/ledgers) + +上游文档用于需求依据;本 SDK 的方法签名、状态名与组件结构属于本方案设计。每个 wire 字段和方法在实施前还须与锁定版本确认,不能凭字符串拼接猜测。 diff --git a/openspec/changes/add-gateway-operations/proposal.md b/openspec/changes/add-gateway-operations/proposal.md new file mode 100644 index 0000000..01da85b --- /dev/null +++ b/openspec/changes/add-gateway-operations/proposal.md @@ -0,0 +1,45 @@ +# 补齐 Gateway 运营与管理能力 + +状态:DRAFT / REVIEW_REQUIRED。文档已提出,未批准实现,未归档。优先级:P1/P2。 + +## Why + +CLI 入口覆盖不等于远程管理闭环。需要为配置、调度、扩展、设备、投递和审计提供可独立调用、明确授权和返回阶段的 Java 领域接口。 + +## What Changes + +- `configuration-control`: 配置与密钥管理。 +- `cron-control`: 定时任务与运行跟踪。 +- `tool-model-catalogs`: 工具与模型目录。 +- `skill-plugin-lifecycle`: Skills 与 Plugins 生命周期。 +- `channel-node-control`: 渠道、设备和 Node 控制。 +- `task-audit-artifacts`: 任务、审计、用量与产物。 + +此次交付只创建 OpenSpec 文档与证据清单,不修改 Java 代码、构建文件、测试、依赖或发布配置。本提案描述后续拟实施行为,不证明这些能力现在已完成。 + +## Capabilities + +### New Capabilities + +- `configuration-control`: 配置与密钥管理。 +- `cron-control`: 定时任务与运行跟踪。 +- `tool-model-catalogs`: 工具与模型目录。 +- `skill-plugin-lifecycle`: Skills 与 Plugins 生命周期。 +- `channel-node-control`: 渠道、设备和 Node 控制。 +- `task-audit-artifacts`: 任务、审计、用量与产物。 + +### Modified Capabilities + +无现有同名 OpenSpec 生效规范可修改。本次是首次引入这些能力的正式规范条目,因此使用 ADDED Requirements;并不意味着仓库中不存在相关旧代码。 + +## Impact + +适用分支为 feature/1.0.x、feature/2.0.x、feature/3.0.x。具体源码触点见 design.md;可观测行为见 specs/;验证与执行步骤见 tasks.md。main 不作为第四条已验证发行线。 + +依赖变更:`add-managed-gateway-client`, `add-agent-session-approval-control` + +不在范围:重写 OpenClaw 内部模型引擎、原生插件运行时、沙箱内核或 Gateway 私有 worker 协议;不提供自动授权、跨租户共享密钥隔离或恰好一次执行保证。 + +## Review and Entry Criteria + +必须完成人工范围评审、锁定目标 Gateway 构建与协议映射,并完成依赖变更的必要验收后,才能进入本变更实现。OpenSpec 的 artifact 完整性状态不等于人审通过或产品已完成。具体门禁是本项目约定,而非声称 OpenSpec 官方强制该流程。 diff --git a/openspec/changes/add-gateway-operations/specs/channel-node-control/spec.md b/openspec/changes/add-gateway-operations/specs/channel-node-control/spec.md new file mode 100644 index 0000000..9efb2f6 --- /dev/null +++ b/openspec/changes/add-gateway-operations/specs/channel-node-control/spec.md @@ -0,0 +1,52 @@ +# 渠道、设备和 Node 控制 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的渠道、设备和 Node 控制定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: CN-01 渠道操作有明确账户作用域 +SDK SHALL 保留渠道、账户、目标和线程身份,区分登录流程、发送受理与投递结果;二维码或临时凭据 SHALL 仅在明确请求的范围内处理。 + +#### Scenario: CN-01-S1 明确目标投递 +- **GIVEN** 存在多个渠道账户 +- **WHEN** 指定一个账户和线程发送 +- **THEN** 只返回该目标的结果,不广播或换账户重试 + +#### Scenario: CN-01-S2 登录等待到期 +- **GIVEN** web.login 等流程尚未完成 +- **WHEN** 本地等待预算到期 +- **THEN** 保持未完成或已过期状态,不宣告已登录,临时凭据不进入日志 + +### Requirement: CN-02 设备配对与凭据轮换受控 +SDK SHALL 暴露经授权的设备和 Node 列表、配对决策、Token 轮换与撤销结果;支持范围 SHALL 由目标版本与权限决定,不调用已移除的配对协议。 + +#### Scenario: CN-02-S1 撤销设备 Token +- **GIVEN** 操作者具有对应权限 +- **WHEN** 服务端确认撤销 +- **THEN** 保留操作结果并使关联本地认证状态可失效 + +#### Scenario: CN-02-S2 操作需要额外授权 +- **GIVEN** 当前权限不足以配对或轮换 +- **WHEN** 请求失败 +- **THEN** 返回授权要求,不切换成共享管理员凭据 + +### Requirement: CN-03 Node 调用与回传按身份关联 +SDK SHALL 区分 operator 发起 Node 调用与 node 角色接收执行请求,保留 command、requestId、runId、session 身份及 deadline;Node 回传不得串用另一调用的关联信息。 + +#### Scenario: CN-03-S1 合法调用回传 +- **GIVEN** 已认证 Node 获得允许命令的准确请求 +- **WHEN** 回传结果 +- **THEN** 使用原请求身份且保留退出、拒绝或超时结果 + +#### Scenario: CN-03-S2 执行状态未知 +- **GIVEN** 请求已经可能运行但连接断开 +- **WHEN** 宿主处理失败 +- **THEN** 报告不确定,不套用未执行拒绝才可重试的规则重复执行 + +## Sources + +[O12 系统、渠道、插件与终端 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-system-and-channels);[O08 设备、Node、审批与 Cron RPC](https://docs.openclaw.ai/gateway/protocol/rpc-devices-nodes-and-approvals) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-gateway-operations/specs/configuration-control/spec.md b/openspec/changes/add-gateway-operations/specs/configuration-control/spec.md new file mode 100644 index 0000000..b6312dc --- /dev/null +++ b/openspec/changes/add-gateway-operations/specs/configuration-control/spec.md @@ -0,0 +1,52 @@ +# 配置与密钥管理 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的配置与密钥管理定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: CFG-01 并发配置更新不覆盖他人修改 +SDK SHALL 保留配置版本 hash,并按目标方法契约提交 baseHash 和 replacePaths;冲突时 MUST NOT 自动覆盖最新配置或移除并发校验条件。 + +#### Scenario: CFG-01-S1 带版本更新 +- **GIVEN** 调用者读取版本 H 并提交修改 +- **WHEN** 服务端仍是 H +- **THEN** 按 patch 或 apply 契约更新并返回新版本 + +#### Scenario: CFG-01-S2 版本冲突 +- **GIVEN** 另一操作者已写入 H2 +- **WHEN** 旧 baseHash=H 的写入被拒绝 +- **THEN** 向调用者暴露冲突,要求重新读取和重新决策 + +### Requirement: CFG-02 持久化与运行时生效分离 +SDK SHALL 区分配置写入、运行时应用、重启中、应用失败与结果不确定;不得把 config.set 的持久化确认自动描述为运行时已生效。 + +#### Scenario: CFG-02-S1 只持久化 +- **GIVEN** 目标方法仅保证配置落盘 +- **WHEN** 服务端确认写入 +- **THEN** 返回 persisted 而非 runtime-applied 的事实 + +#### Scenario: CFG-02-S2 应用失败 +- **GIVEN** 配置已持久化但运行时应用失败 +- **WHEN** 服务端返回阶段性结果 +- **THEN** 保留两个阶段结果,禁止自动覆盖或未经请求回滚 + +### Requirement: CFG-03 Schema 与密钥访问受权限制 +SDK SHALL 暴露目标版本支持的配置 schema 和经授权的密钥管理结果,保留 SecretRef 等引用语义;敏感内容 MUST NOT 自动进入诊断或缓存导出。 + +#### Scenario: CFG-03-S1 读取 schema +- **GIVEN** 宿主有配置读取权限 +- **WHEN** 查询支持的配置项 +- **THEN** 返回 schema 与版本信息,不静默扩展未知配置字段 + +#### Scenario: CFG-03-S2 密钥操作失败 +- **GIVEN** 密钥权限或安全策略拒绝访问 +- **WHEN** 执行管理调用 +- **THEN** 保留脱敏错误,不把密钥值或访问凭据写入日志 + +## Sources + +[O09 Config RPC 更新与生效](https://docs.openclaw.ai/gateway/configuration/config-rpc) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-gateway-operations/specs/cron-control/spec.md b/openspec/changes/add-gateway-operations/specs/cron-control/spec.md new file mode 100644 index 0000000..2d0c404 --- /dev/null +++ b/openspec/changes/add-gateway-operations/specs/cron-control/spec.md @@ -0,0 +1,52 @@ +# 定时任务与运行跟踪 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的定时任务与运行跟踪定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: CRON-01 调度管理契约完整 +SDK SHALL 对目标版本的 cron get/list/status/add/update/remove 提供类型化操作,保留计划、时区、payload 与投递模式的区分;本地 SDK 不承担服务端到点执行承诺。 + +#### Scenario: CRON-01-S1 创建调度 +- **GIVEN** 调用者给出合法计划和时区 +- **WHEN** 创建请求成功 +- **THEN** 保留服务端任务标识与计划信息,不自行计算不同的下次触发时间 + +#### Scenario: CRON-01-S2 非法计划 +- **GIVEN** 计划不符合目标版本规则 +- **WHEN** 提交创建或修改 +- **THEN** 保留校验错误,不擅自更换时区或调度周期 + +### Requirement: CRON-02 手动运行是排队不是完成 +SDK SHALL 把 cron.run 的受理视为排队结果,并使用返回 runId 查询 cron.runs;不得使用同任务最近一条历史代替本次运行身份。 + +#### Scenario: CRON-02-S1 并发手动触发 +- **GIVEN** 同一任务短时间内触发两次 +- **WHEN** 查询第一条 runId 的运行结果 +- **THEN** 只绑定第一条运行,不混入第二条结果 + +#### Scenario: CRON-02-S2 排队超时 +- **GIVEN** 任务仍排队而本地等待预算到期 +- **WHEN** 结束等待 +- **THEN** 返回等待到期并保留 runId,不标记任务执行失败 + +### Requirement: CRON-03 管理写入不可盲重放 +SDK SHALL 对新增、删除、更新及手动运行保留失败阶段和结果不确定性;自动重试 SHALL 受目标契约和明确策略约束。 + +#### Scenario: CRON-03-S1 删除已确认 +- **GIVEN** 服务端确认指定任务删除 +- **WHEN** 重复读取该任务 +- **THEN** 如实展示不存在,不自动重建 + +#### Scenario: CRON-03-S2 创建确认丢失 +- **GIVEN** 服务端可能已新增任务 +- **WHEN** 连接在确认前断开 +- **THEN** 报告结果不确定并允许查询,不自动重复新增 + +## Sources + +[O08 设备、Node、审批与 Cron RPC](https://docs.openclaw.ai/gateway/protocol/rpc-devices-nodes-and-approvals) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-gateway-operations/specs/skill-plugin-lifecycle/spec.md b/openspec/changes/add-gateway-operations/specs/skill-plugin-lifecycle/spec.md new file mode 100644 index 0000000..3e1d201 --- /dev/null +++ b/openspec/changes/add-gateway-operations/specs/skill-plugin-lifecycle/spec.md @@ -0,0 +1,52 @@ +# Skills 与 Plugins 生命周期 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的Skills 与 Plugins 生命周期定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: EXT-01 发现与安装状态区分 +SDK SHALL 支持目标契约内的 Skills 与 Plugins 状态、发现、详情和管理动作,区分可发现、已安装、已启用、运行时已加载及不可用。 + +#### Scenario: EXT-01-S1 已安装未加载 +- **GIVEN** 插件安装记录存在但运行时未加载 +- **WHEN** 查询状态 +- **THEN** 分别呈现磁盘和运行时状态,不把安装成功当作可调用 + +#### Scenario: EXT-01-S2 安装来源受限 +- **GIVEN** 来源不符合宿主或 Gateway 策略 +- **WHEN** 请求安装 +- **THEN** 返回拒绝结果,不禁用校验或从替代来源暗中下载 + +### Requirement: EXT-02 包传输有界且可取消 +对目标版本提供的分块上传,SDK SHALL 遵守顺序、大小、完整性和终结规则,传输可取消且不得无限缓冲;不支持分块时不得伪造协议。 + +#### Scenario: EXT-02-S1 受控上传 +- **GIVEN** 包满足大小与来源要求 +- **WHEN** 完成全部块并提交 +- **THEN** 只有服务端确认后才报告包传输完成 + +#### Scenario: EXT-02-S2 中途失败 +- **GIVEN** 上传中断或完整性检查失败 +- **WHEN** 执行失败清理 +- **THEN** 报告未完成并按目标协议释放暂存,不宣告安装成功 + +### Requirement: EXT-03 运行时发布按阶段反馈 +SDK SHALL 保留启停、更新、重载和卸载的持久化与运行时发布结果;更新通知 SHALL 触发状态查询而非自动重做安装。 + +#### Scenario: EXT-03-S1 发布变化 +- **GIVEN** 收到 plugins.changed 或技能失效事件 +- **WHEN** 刷新状态 +- **THEN** 读取权威状态并区分新 generation,不无条件重装 + +#### Scenario: EXT-03-S2 部分阶段失败 +- **GIVEN** 持久化已成功但运行时发布失败 +- **WHEN** 返回结果 +- **THEN** 保留部分完成事实和可用恢复建议,不盲目重新安装 + +## Sources + +[O10 工具、模型与 Skills 管理](https://docs.openclaw.ai/gateway/protocol/operator-methods);[O12 系统、渠道、插件与终端 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-system-and-channels) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-gateway-operations/specs/task-audit-artifacts/spec.md b/openspec/changes/add-gateway-operations/specs/task-audit-artifacts/spec.md new file mode 100644 index 0000000..ac94653 --- /dev/null +++ b/openspec/changes/add-gateway-operations/specs/task-audit-artifacts/spec.md @@ -0,0 +1,52 @@ +# 任务、审计、用量与产物 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的任务、审计、用量与产物定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: OBS-01 任务查询和取消保留运行归属 +SDK SHALL 支持目标版本的任务列表、详情与取消,并保留其关联 Agent、session、run 等身份;任务取消受理不得替代所有底层工作的终态。 + +#### Scenario: OBS-01-S1 按任务读取 +- **GIVEN** 任务有明确执行关联 +- **WHEN** 查询任务详情 +- **THEN** 返回准确状态和可用的相关运行标识 + +#### Scenario: OBS-01-S2 取消后仍终结中 +- **GIVEN** 取消已受理但底层工作未报告结束 +- **WHEN** 上层查看状态 +- **THEN** 显示取消中或服务端状态,不伪造所有资源已释放 + +### Requirement: OBS-02 审计与用量查询不混淆缺省 +SDK SHALL 对审计、执行检查和用量提供授权范围内的分页与时间窗口,保留币种、单位、时间和未知值;没有数据 MUST NOT 自动变成零成本或无事件。 + +#### Scenario: OBS-02-S1 分页审计 +- **GIVEN** 用户读取指定时间和执行范围 +- **WHEN** 返回带游标结果 +- **THEN** 保留分页续读和执行身份,不越权合并其他用户数据 + +#### Scenario: OBS-02-S2 用量缺省 +- **GIVEN** 响应没有某项用量或成本 +- **WHEN** 展示查询结果 +- **THEN** 保留未知,不输出已验证零成本 + +### Requirement: OBS-03 产物下载受权且保护短期地址 +SDK SHALL 保留 artifact 与运行归属、过期信息及内容限制;下载凭据不得跨域转发,过期地址 SHALL 重新向权威接口请求而非无限重试。 + +#### Scenario: OBS-03-S1 有效产物下载 +- **GIVEN** 用户有权读取目标产物 +- **WHEN** 下载有效地址 +- **THEN** 按大小限制流式读取并在结束后关闭资源 + +#### Scenario: OBS-03-S2 过期或跨域重定向 +- **GIVEN** 地址过期或重定向到非获准目标 +- **WHEN** 下载请求继续 +- **THEN** 停止或经授权重新取址,不把 Gateway Token 或签名链接写入日志 + +## Sources + +[O13 任务、审计及用量台账](https://docs.openclaw.ai/gateway/protocol/ledgers);[O11 Talk、Agent 与产物 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-talk-config-and-agents) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-gateway-operations/specs/tool-model-catalogs/spec.md b/openspec/changes/add-gateway-operations/specs/tool-model-catalogs/spec.md new file mode 100644 index 0000000..bee5f8e --- /dev/null +++ b/openspec/changes/add-gateway-operations/specs/tool-model-catalogs/spec.md @@ -0,0 +1,52 @@ +# 工具与模型目录 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的工具与模型目录定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: CAT-01 目录与有效工具分开 +SDK SHALL 区分所有目录条目、当前会话有效工具及实际可调用状态;展示目录中存在的工具 MUST NOT 等价于拥有执行权限。 + +#### Scenario: CAT-01-S1 目录含受限工具 +- **GIVEN** 工具出现在 catalog 但不在当前 effective 集合 +- **WHEN** 用户查看可用工具 +- **THEN** 保留来源并显示当前不可用,不提升权限 + +#### Scenario: CAT-01-S2 会话条件变化 +- **GIVEN** 会话或权限已改变 +- **WHEN** 重新查询 effective 工具 +- **THEN** 返回当前授权下的新结果,不复用其他会话缓存 + +### Requirement: CAT-02 RPC 成功与工具成功分开 +SDK SHALL 为 WS 工具调用保留传输、RPC 与工具业务结果层次及请求身份;业务 ok=false SHALL 不被正常 Future 完成掩盖为操作成功。 + +#### Scenario: CAT-02-S1 业务拒绝 +- **GIVEN** RPC 外层成功、工具结果失败 +- **WHEN** 上层检查执行结果 +- **THEN** 能读取明确失败、原因与可用输出 + +#### Scenario: CAT-02-S2 写工具确认未知 +- **GIVEN** 工具可能产生副作用但连接中断 +- **WHEN** 处理错误 +- **THEN** 不给出安全重试结论,也不透明地切换 HTTP 再执行 + +### Requirement: CAT-03 模型及命令目录按能力刷新 +SDK SHALL 读取目标版本支持的模型和命令目录,保留服务端标识及能力限制;缓存失效后 SHALL 重新确认,不能用旧别名或未获授权的模型替换请求。 + +#### Scenario: CAT-03-S1 目录变化 +- **GIVEN** 服务端通知相关目录失效 +- **WHEN** 下一次获取目录 +- **THEN** 刷新后使用服务端标识并保留元信息 + +#### Scenario: CAT-03-S2 模型不支持 +- **GIVEN** 目标模型或命令不在获准支持范围 +- **WHEN** 调用者请求使用 +- **THEN** 返回明确不可用原因,不静默选用成本或权限不同的替代项 + +## Sources + +[O10 工具、模型与 Skills 管理](https://docs.openclaw.ai/gateway/protocol/operator-methods) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-gateway-operations/tasks.md b/openspec/changes/add-gateway-operations/tasks.md new file mode 100644 index 0000000..1d81efb --- /dev/null +++ b/openspec/changes/add-gateway-operations/tasks.md @@ -0,0 +1,50 @@ +# Implementation Tasks + +状态:全部未执行。本清单是后续实施计划,不是本轮文档生成记录。 + +## 1. 准入与证据 + +- [ ] 1.1 取得本变更的人审结论并核验依赖;验收:评审记录包含范围、行为收紧、三分支要求和批准的 change ID。 +- [ ] 1.2 锁定目标 OpenClaw 精确版本/提交、构建来源及协议映射;验收:方法、事件、字段、scope 与拒绝样本均有版本化来源,未锁定时停止编码。 + +## 2. 配置与密钥管理 + +- [ ] 2.1 为 `configuration-control` 建立契约样本及回归基线(CFG-01, CFG-02, CFG-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 2.2 按 design.md 实施 `configuration-control` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 2.3 在三条适用分支验证 `configuration-control` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 3. 定时任务与运行跟踪 + +- [ ] 3.1 为 `cron-control` 建立契约样本及回归基线(CRON-01, CRON-02, CRON-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 3.2 按 design.md 实施 `cron-control` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 3.3 在三条适用分支验证 `cron-control` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 4. 工具与模型目录 + +- [ ] 4.1 为 `tool-model-catalogs` 建立契约样本及回归基线(CAT-01, CAT-02, CAT-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 4.2 按 design.md 实施 `tool-model-catalogs` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 4.3 在三条适用分支验证 `tool-model-catalogs` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 5. Skills 与 Plugins 生命周期 + +- [ ] 5.1 为 `skill-plugin-lifecycle` 建立契约样本及回归基线(EXT-01, EXT-02, EXT-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 5.2 按 design.md 实施 `skill-plugin-lifecycle` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 5.3 在三条适用分支验证 `skill-plugin-lifecycle` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 6. 渠道、设备和 Node 控制 + +- [ ] 6.1 为 `channel-node-control` 建立契约样本及回归基线(CN-01, CN-02, CN-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 6.2 按 design.md 实施 `channel-node-control` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 6.3 在三条适用分支验证 `channel-node-control` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 7. 任务、审计、用量与产物 + +- [ ] 7.1 为 `task-audit-artifacts` 建立契约样本及回归基线(OBS-01, OBS-02, OBS-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 7.2 按 design.md 实施 `task-audit-artifacts` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 7.3 在三条适用分支验证 `task-audit-artifacts` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 8. 集成、资源与归档门禁 + +- [ ] 8.1 对本变更执行真实 Gateway 场景;验收:固定服务端版本、认证方式、运行命令与脱敏证据,成功和拒绝均有真实观察,SDK 本地 fixture 通过不能替代。 +- [ ] 8.2 完成适用的资源、故障与兼容检查;验收:1000 次受控请求/订阅周期后活动注册归零,自有线程在测试预算内终止,共享资源仍可使用;治理类变更检查无运行资源触点并记录不适用理由。 +- [ ] 8.3 更新覆盖矩阵并执行规范校验;验收:官方 OpenSpec validate 输出通过、无未解释的三分支差异、所有必需任务有证据且人审允许归档,随后才更新生效 specs。 diff --git a/openspec/changes/add-managed-gateway-client/.openspec.yaml b/openspec/changes/add-managed-gateway-client/.openspec.yaml new file mode 100644 index 0000000..cbd245e --- /dev/null +++ b/openspec/changes/add-managed-gateway-client/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-09-20 diff --git a/openspec/changes/add-managed-gateway-client/design.md b/openspec/changes/add-managed-gateway-client/design.md new file mode 100644 index 0000000..a94b821 --- /dev/null +++ b/openspec/changes/add-managed-gateway-client/design.md @@ -0,0 +1,59 @@ +# 建立受管理 RPC、连接恢复和事件交付 — Technical Design + +状态:DRAFT / REVIEW_REQUIRED。下述新类与模块名称为拟议设计,不是仓库已存在能力。 + +## Context + +动机与范围见 proposal.md;固定的 SDK HEAD、静态观察和证据等级见 [coverage-baseline](../../../docs/openclaw-integration/coverage-baseline.md)。当前文档基于公开协议说明和此前源码静态核查,不包含真实 Gateway 验证。在线文档随时间变化;目标版本锁定仍是实施前的阻断条件。 + +## Goals / Non-Goals + +用可观察契约约束新增或修正行为;保留三条 Java 发行线的既有基线与可行的源码兼容。只引入本变更需要的组件,不进行无关重构。SDK 不代替 Gateway 做权限裁定,也不代替宿主存储或授予长期凭据。 + +## Decisions + +采用组合式 GatewayConnectionManager + GatewayRpcClient + SubscriptionRegistry 的逻辑分层。这些是拟议内部组件名,不是现有 API。兼容保留旧 OpenClawGatewayWsClient 入口;底层 transport 可更换,但业务契约不绑定具体 WebSocket 类。 + +异步调用为基础,同步调用作为受约束等待的适配层。统一处理序列化、登记、发送、响应、deadline、取消与断线;所有出口都清理 pending 和超时任务。避免在事件交付线程中执行阻塞等待,以免自锁。 + +状态机采用 NEW → CONNECTING → AUTHENTICATING → READY;故障进入 RECONNECT_WAIT/FAILED,关闭进入 CLOSING → CLOSED。只有显式重连策略可以重新连接;关闭是终结态。重连预算、退避、抖动、服务端 retryAfter、liveness 和连接代际统一管理。 + +恢复先重建订阅,再读取快照并处理交错事件;使用版本化身份而非简单按 key 覆盖。默认不重放写请求,已发送无确认则产生 OutcomeUnknown 类本地状态。此名为拟议本地分类,不能假装服务端返回这个错误码。 + +事件交付使用有界队列和回调异常隔离。能力清单只做兼容预检,不作为授权;被上游有意省略的发现项可通过明确版本映射和宿主意图调用,最终以服务端授权为准。 + +备选方案是在单个 WS 类中不断增加字段和锁,改动少但耦合与测试成本持续上升;完全替换公共类则破坏下游。本方案将新职责内聚为组合组件。 + +## Technical Approach + +领域调用 → 公共异步 RPC → 连接/权限预检 → 请求注册 → transport → 响应或事件分发 → 终态与清理 + +错误类型和状态转换由共享协议层统一;本地超时/取消与远端失败/取消分开。以下源码触点仅用于实施规划,新增路径在接入前需核对实际工作树,不把不存在的文件列为已修改: + +- `src/main/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClient.java` +- `src/main/java/io/github/easy4j/openclaw/OpenClawClient.java` +- `src/main/java/io/github/easy4j/openclaw/exception/(新增本地状态异常或结果类型)` +- `src/main/java/io/github/easy4j/openclaw/ws/(组合式连接管理器与订阅注册表,新增)` +- `src/main/java/io/github/easy4j/openclaw/OpenClawHttpClientConfig.java` +- `src/main/java/io/github/easy4j/openclaw/ws/OpenClawWsListener.java` +- `src/main/java/io/github/easy4j/openclaw/ws/protocol/EventFrame.java` + +## Risks / Trade-offs + +恢复流程引入新的竞态 → 使用虚拟时间、连接代际与确定性事件序列测试;缓存不能保证事件全量恢复 → 明确 gap 并读取权威快照。 + +所有新状态、上限和取消语义必须进入验收;不得使用修改测试预期、跳过不兼容分支或放宽权限来消除失败。 + +## Migration Plan + +先记录对应旧行为并建立最小失败样本,再实施局部修正或加法 API,最后同步其余分支与文档。按 capability 小批提交,避免跨无关领域的大规模替换。回滚只回退该功能变更和明确可逆状态;配置落盘、已执行工具或已投递消息的外部副作用不宣称自动撤销。根 specs 的更新留到经批准的归档阶段。 + +## Validation Strategy + +需求与场景的逐项映射见 [traceability](../../../docs/openclaw-integration/traceability.md)。每项能力须完成固定样本验证、受控模拟、适用分支构建及真实 Gateway 验收。资源测试至少覆盖成功、失败、取消、deadline、断线和用户回调异常。缺失环境的测试记录 BLOCKED,不记录 PASS。 + +## Sources + +[O01 外部应用接入边界](https://docs.openclaw.ai/gateway/external-apps);[O02 协议版本与客户端恢复边界](https://docs.openclaw.ai/gateway/protocol/versioning);[O04 会话启动、快照及事件语义](https://docs.openclaw.ai/gateway/protocol/rpc-bootstrap-and-events);[O05 Gateway 握手与设备凭据](https://docs.openclaw.ai/gateway/protocol/handshake) + +上游文档用于需求依据;本 SDK 的方法签名、状态名与组件结构属于本方案设计。每个 wire 字段和方法在实施前还须与锁定版本确认,不能凭字符串拼接猜测。 diff --git a/openspec/changes/add-managed-gateway-client/proposal.md b/openspec/changes/add-managed-gateway-client/proposal.md new file mode 100644 index 0000000..ee7cab4 --- /dev/null +++ b/openspec/changes/add-managed-gateway-client/proposal.md @@ -0,0 +1,39 @@ +# 建立受管理 RPC、连接恢复和事件交付 + +状态:DRAFT / REVIEW_REQUIRED。文档已提出,未批准实现,未归档。优先级:P0。 + +## Why + +仅有原始 WebSocket 和 private RPC 帮助方法,不足以支持完整 Java 控制面。需要统一请求生命周期、连接恢复和资源所有权,避免每个新业务方法重复实现。 + +## What Changes + +- `managed-rpc`: 受管理的公共 RPC。 +- `gateway-recovery`: 连接恢复与订阅对账。 +- `typed-event-delivery`: 类型化事件与资源边界。 + +此次交付只创建 OpenSpec 文档与证据清单,不修改 Java 代码、构建文件、测试、依赖或发布配置。本提案描述后续拟实施行为,不证明这些能力现在已完成。 + +## Capabilities + +### New Capabilities + +- `managed-rpc`: 受管理的公共 RPC。 +- `gateway-recovery`: 连接恢复与订阅对账。 +- `typed-event-delivery`: 类型化事件与资源边界。 + +### Modified Capabilities + +无现有同名 OpenSpec 生效规范可修改。本次是首次引入这些能力的正式规范条目,因此使用 ADDED Requirements;并不意味着仓库中不存在相关旧代码。 + +## Impact + +适用分支为 feature/1.0.x、feature/2.0.x、feature/3.0.x。具体源码触点见 design.md;可观测行为见 specs/;验证与执行步骤见 tasks.md。main 不作为第四条已验证发行线。 + +依赖变更:`establish-sdk-compatibility-governance`, `fix-openclaw-protocol-contracts` + +不在范围:重写 OpenClaw 内部模型引擎、原生插件运行时、沙箱内核或 Gateway 私有 worker 协议;不提供自动授权、跨租户共享密钥隔离或恰好一次执行保证。 + +## Review and Entry Criteria + +必须完成人工范围评审、锁定目标 Gateway 构建与协议映射,并完成依赖变更的必要验收后,才能进入本变更实现。OpenSpec 的 artifact 完整性状态不等于人审通过或产品已完成。具体门禁是本项目约定,而非声称 OpenSpec 官方强制该流程。 diff --git a/openspec/changes/add-managed-gateway-client/specs/gateway-recovery/spec.md b/openspec/changes/add-managed-gateway-client/specs/gateway-recovery/spec.md new file mode 100644 index 0000000..de1b720 --- /dev/null +++ b/openspec/changes/add-managed-gateway-client/specs/gateway-recovery/spec.md @@ -0,0 +1,52 @@ +# 连接恢复与订阅对账 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的连接恢复与订阅对账定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: REC-01 有界重连与关闭语义 +SDK SHALL 暴露连接状态、重试预算、退避及停止原因;用户关闭后 SHALL 停止重连;重连只恢复连接,不自动重放业务写请求。 + +#### Scenario: REC-01-S1 暂时不可用 +- **GIVEN** Gateway 返回可重试失败和 retryAfterMs +- **WHEN** 重试预算未耗尽 +- **THEN** 在预算内遵守等待并采用带抖动退避,不并发发起无限连接 + +#### Scenario: REC-01-S2 主动关闭 +- **GIVEN** 客户端正在等待下一次重连 +- **WHEN** 宿主关闭客户端 +- **THEN** 取消重连与相关定时器,不再创建新连接 + +### Requirement: REC-02 重连恢复先订阅再快照对账 +成功重连后 SDK SHALL 根据显式订阅意图重新订阅并获取权威快照;必须考虑订阅和快照交错事件,不声称可以重放所有丢失事件。 + +#### Scenario: REC-02-S1 快照期间变化 +- **GIVEN** 连接恢复且订阅已注册 +- **WHEN** 快照生成时收到失效事件 +- **THEN** 合并可用事实并执行必要尾随刷新 + +#### Scenario: REC-02-S2 数据不能重放 +- **GIVEN** 断线期间存在不可恢复的临时进度事件 +- **WHEN** 恢复连接 +- **THEN** 暴露恢复缺口并以当前权威状态继续,不伪造缺失事件 + +### Requirement: REC-03 执行不确定性必须显式暴露 +对已经发送但未收到确认的有副作用请求,SDK SHALL 暴露结果不确定,并提供已存在关联信息供查询;只有经目标契约证明安全且宿主明确配置的请求才可自动重试。 + +#### Scenario: REC-03-S1 执行后断线 +- **GIVEN** 创建运行的请求可能已在服务端生效 +- **WHEN** 确认到达前断线 +- **THEN** 不自动再次创建,保留关联并允许后续查询 + +#### Scenario: REC-03-S2 可重试只读查询 +- **GIVEN** 请求是经分类的只读查询且宿主允许重试 +- **WHEN** 瞬态断线后恢复 +- **THEN** 在预算内重试并记录次数,不将此策略推广至写请求 + +## Sources + +[O02 协议版本与客户端恢复边界](https://docs.openclaw.ai/gateway/protocol/versioning);[O04 会话启动、快照及事件语义](https://docs.openclaw.ai/gateway/protocol/rpc-bootstrap-and-events);[O05 Gateway 握手与设备凭据](https://docs.openclaw.ai/gateway/protocol/handshake) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-managed-gateway-client/specs/managed-rpc/spec.md b/openspec/changes/add-managed-gateway-client/specs/managed-rpc/spec.md new file mode 100644 index 0000000..d14a9bb --- /dev/null +++ b/openspec/changes/add-managed-gateway-client/specs/managed-rpc/spec.md @@ -0,0 +1,52 @@ +# 受管理的公共 RPC — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的受管理的公共 RPC定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: RPC-01 公开的同步和异步请求契约 +SDK SHALL 提供受管理的通用 RPC 调用,公开方法标识、参数、结果类型、deadline 与取消语义;类型化业务方法 SHALL 复用一致的关联和错误规则。 + +#### Scenario: RPC-01-S1 响应乱序 +- **GIVEN** 两个请求有不同 ID +- **WHEN** 响应逆序到达 +- **THEN** 各自 Future 仅由匹配 ID 的响应完成 + +#### Scenario: RPC-01-S2 未认证调用 +- **GIVEN** 连接尚未完成握手 +- **WHEN** 调用需要认证的业务方法 +- **THEN** 得到明确状态错误,不发送未授权业务帧 + +### Requirement: RPC-02 所有失败路径释放等待者 +请求成功、序列化失败、发送失败、deadline、中断、取消与断线时,SDK SHALL 终止等待并清理相关注册;本地取消 MUST NOT 被描述为已经取消远端工作。 + +#### Scenario: RPC-02-S1 发送之前失败 +- **GIVEN** 请求已登记但发送抛出异常 +- **WHEN** 失败处理完成 +- **THEN** Future 失败且 pending 数量恢复,不留下定时器或注册 + +#### Scenario: RPC-02-S2 deadline 到期 +- **GIVEN** 远端是否执行未知且无响应 +- **WHEN** 本地等待到期 +- **THEN** 以等待超时或结果不确定结束,之后迟到响应不能复活已结束请求 + +### Requirement: RPC-03 能力预检不是安全授权 +SDK SHALL 使用版本清单与服务端能力信息进行预检,保留明确受版本约束的未广播方法调用途径;发现列表缺省 MUST NOT 等价于绝对不存在,预检通过 MUST NOT 等价于被授权。 + +#### Scenario: RPC-03-S1 已知不可用 +- **GIVEN** 版本清单明确目标版本不支持某方法 +- **WHEN** 调用类型化入口 +- **THEN** 在发送前返回不可用原因 + +#### Scenario: RPC-03-S2 未广播方法 +- **GIVEN** 经评审的版本清单允许调用某未广播方法 +- **WHEN** 宿主显式调用且服务端随后拒绝权限 +- **THEN** 保留真实拒绝结果,不尝试提权或绕过 + +## Sources + +[O01 外部应用接入边界](https://docs.openclaw.ai/gateway/external-apps);[O02 协议版本与客户端恢复边界](https://docs.openclaw.ai/gateway/protocol/versioning) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-managed-gateway-client/specs/typed-event-delivery/spec.md b/openspec/changes/add-managed-gateway-client/specs/typed-event-delivery/spec.md new file mode 100644 index 0000000..62c2a54 --- /dev/null +++ b/openspec/changes/add-managed-gateway-client/specs/typed-event-delivery/spec.md @@ -0,0 +1,52 @@ +# 类型化事件与资源边界 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的类型化事件与资源边界定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: EVT-01 类型化事件与原始兼容通道并存 +SDK SHALL 对已承诺支持的事件族提供类型化结果,并保留原始事件扩展路径;未知事件 SHALL 可观测而不导致整条连接解析失败。 + +#### Scenario: EVT-01-S1 新增可选事件 +- **GIVEN** 服务端发送 SDK 尚不认识的事件类型 +- **WHEN** 事件被接收 +- **THEN** 通过原始通道暴露且已有订阅继续工作 + +#### Scenario: EVT-01-S2 已知事件错误 +- **GIVEN** 已知事件缺失必需关联字段 +- **WHEN** 解析失败 +- **THEN** 产生限定于该事件的诊断,不误投其他运行 + +### Requirement: EVT-02 有序交付与回调异常隔离 +SDK SHALL 在承诺的订阅范围内保持事件顺序并隔离用户回调异常;队列有界且溢出策略 SHALL 可观察,不得静默丢失审批与终态。 + +#### Scenario: EVT-02-S1 回调抛异常 +- **GIVEN** 监听器 A 抛出异常 +- **WHEN** 同一事件需通知监听器 B +- **THEN** B 仍得到事件,异常进入诊断且清理继续 + +#### Scenario: EVT-02-S2 消费积压 +- **GIVEN** 有界队列已满且到来关键终态 +- **WHEN** 执行溢出策略 +- **THEN** 产生明确中断或恢复信号,禁止谎称终态已交付 + +### Requirement: EVT-03 资源归属清楚且可验证释放 +关闭订阅或客户端 SHALL 释放其拥有的请求、响应体、队列与调度资源;共享外部客户端或执行器 MUST NOT 被无条件关闭,关闭动作 SHALL 幂等。 + +#### Scenario: EVT-03-S1 关闭自有资源 +- **GIVEN** 客户端拥有网络与线程资源 +- **WHEN** 重复调用关闭 +- **THEN** 活动注册最终归零且自有线程在规定预算内终止,无重复业务回调 + +#### Scenario: EVT-03-S2 共享资源 +- **GIVEN** 两个客户端复用宿主传入的连接资源 +- **WHEN** 只关闭其中一个 +- **THEN** 另一个仍可执行请求,宿主继续拥有共享资源生命周期 + +## Sources + +[O04 会话启动、快照及事件语义](https://docs.openclaw.ai/gateway/protocol/rpc-bootstrap-and-events);[O02 协议版本与客户端恢复边界](https://docs.openclaw.ai/gateway/protocol/versioning) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-managed-gateway-client/tasks.md b/openspec/changes/add-managed-gateway-client/tasks.md new file mode 100644 index 0000000..7983142 --- /dev/null +++ b/openspec/changes/add-managed-gateway-client/tasks.md @@ -0,0 +1,32 @@ +# Implementation Tasks + +状态:全部未执行。本清单是后续实施计划,不是本轮文档生成记录。 + +## 1. 准入与证据 + +- [ ] 1.1 取得本变更的人审结论并核验依赖;验收:评审记录包含范围、行为收紧、三分支要求和批准的 change ID。 +- [ ] 1.2 锁定目标 OpenClaw 精确版本/提交、构建来源及协议映射;验收:方法、事件、字段、scope 与拒绝样本均有版本化来源,未锁定时停止编码。 + +## 2. 受管理的公共 RPC + +- [ ] 2.1 为 `managed-rpc` 建立契约样本及回归基线(RPC-01, RPC-02, RPC-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 2.2 按 design.md 实施 `managed-rpc` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 2.3 在三条适用分支验证 `managed-rpc` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 3. 连接恢复与订阅对账 + +- [ ] 3.1 为 `gateway-recovery` 建立契约样本及回归基线(REC-01, REC-02, REC-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 3.2 按 design.md 实施 `gateway-recovery` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 3.3 在三条适用分支验证 `gateway-recovery` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 4. 类型化事件与资源边界 + +- [ ] 4.1 为 `typed-event-delivery` 建立契约样本及回归基线(EVT-01, EVT-02, EVT-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 4.2 按 design.md 实施 `typed-event-delivery` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 4.3 在三条适用分支验证 `typed-event-delivery` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 5. 集成、资源与归档门禁 + +- [ ] 5.1 对本变更执行真实 Gateway 场景;验收:固定服务端版本、认证方式、运行命令与脱敏证据,成功和拒绝均有真实观察,SDK 本地 fixture 通过不能替代。 +- [ ] 5.2 完成适用的资源、故障与兼容检查;验收:1000 次受控请求/订阅周期后活动注册归零,自有线程在测试预算内终止,共享资源仍可使用;治理类变更检查无运行资源触点并记录不适用理由。 +- [ ] 5.3 更新覆盖矩阵并执行规范校验;验收:官方 OpenSpec validate 输出通过、无未解释的三分支差异、所有必需任务有证据且人审允许归档,随后才更新生效 specs。 diff --git a/openspec/changes/add-optional-runtime-adapters/.openspec.yaml b/openspec/changes/add-optional-runtime-adapters/.openspec.yaml new file mode 100644 index 0000000..cbd245e --- /dev/null +++ b/openspec/changes/add-optional-runtime-adapters/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-09-20 diff --git a/openspec/changes/add-optional-runtime-adapters/design.md b/openspec/changes/add-optional-runtime-adapters/design.md new file mode 100644 index 0000000..1b3fbdf --- /dev/null +++ b/openspec/changes/add-optional-runtime-adapters/design.md @@ -0,0 +1,57 @@ +# 增加终端、语音、MCP、ACP 与 CLI 可选适配 — Technical Design + +状态:DRAFT / REVIEW_REQUIRED。下述新类与模块名称为拟议设计,不是仓库已存在能力。 + +## Context + +动机与范围见 proposal.md;固定的 SDK HEAD、静态观察和证据等级见 [coverage-baseline](../../../docs/openclaw-integration/coverage-baseline.md)。当前文档基于公开协议说明和此前源码静态核查,不包含真实 Gateway 验证。在线文档随时间变化;目标版本锁定仍是实施前的阻断条件。 + +## Goals / Non-Goals + +用可观察契约约束新增或修正行为;保留三条 Java 发行线的既有基线与可行的源码兼容。只引入本变更需要的组件,不进行无关重构。SDK 不代替 Gateway 做权限裁定,也不代替宿主存储或授予长期凭据。 + +## Decisions + +核心 SDK 继续保持无 Spring 强制依赖;可选适配优先逻辑包隔离和显式构造,只有依赖无法兼容三条基线时才引入独立制品。物理模块拆分须另记决策,不能在本轮文档阶段先修改 pom。 + +终端和语音按服务端会话、调用身份、连接归属及输出流管理。重连附着不重跑命令;采音、终端启动和额外敏感配置读取必须由宿主显式发起,不随连接自动发生。 + +MCP 与 ACP 独立协商各自协议版本。使用 PersistentStdioSession 逻辑组件处理双向管道、帧关联、通知、取消、stderr、进程退出及关闭;不能复用“等待子进程结束再返回结果”的一次性 executor。先评估能满足 Java 8/17/21 的成熟协议库,不在规范中假定某库已兼容或已安装。 + +CLI 保留通用 argv 入口;仅为锁定版本中有稳定机器输出的 browser/infer 等动作逐步增加 DTO。自由参数透传仍标为透传。所有执行明确字面参数、工作目录、输出限制、超时、取消与敏感参数脱敏;Windows 与 POSIX 分别验证。 + +备选方案是强制引入一个全功能协议框架,集成快但可能提高 Java 基线;另一方案是继续透传原始 stdout,无法管理交互协议。本方案将适配器作为可选扩展,不改变核心默认运行行为。 + +## Technical Approach + +宿主显式授权与选择适配器 → 版本协商/进程启动 → 双向会话 → 事件与取消 → 关闭自有资源 + +错误类型和状态转换由共享协议层统一;本地超时/取消与远端失败/取消分开。以下源码触点仅用于实施规划,新增路径在接入前需核对实际工作树,不把不存在的文件列为已修改: + +- `可选适配包:terminal、talk、tts(最终物理路径须在实施前与项目模块布局核对)` +- `src/main/java/io/github/easy4j/openclaw/cli/support/(独立持久 stdio 会话适配,不复用一次性结果语义)` +- `可选适配包:mcp、acp(不得引入核心模块的必需运行依赖)` +- `src/main/java/io/github/easy4j/openclaw/cli/OpenClawCli.java` +- `src/main/java/io/github/easy4j/openclaw/cli/OpenClawCliExecutor.java` +- `src/main/java/io/github/easy4j/openclaw/cli/OpenClawCliResult.java` +- `src/main/java/io/github/easy4j/openclaw/cli/opts/` + +## Risks / Trade-offs + +协议库最低 JDK 高于 1.x → 选型门禁与独立制品,不悄悄提高核心基线;长时间交互与输出过量 → 有界缓冲、超时和进程清理验证。 + +所有新状态、上限和取消语义必须进入验收;不得使用修改测试预期、跳过不兼容分支或放宽权限来消除失败。 + +## Migration Plan + +先记录对应旧行为并建立最小失败样本,再实施局部修正或加法 API,最后同步其余分支与文档。按 capability 小批提交,避免跨无关领域的大规模替换。回滚只回退该功能变更和明确可逆状态;配置落盘、已执行工具或已投递消息的外部副作用不宣称自动撤销。根 specs 的更新留到经批准的归档阶段。 + +## Validation Strategy + +需求与场景的逐项映射见 [traceability](../../../docs/openclaw-integration/traceability.md)。每项能力须完成固定样本验证、受控模拟、适用分支构建及真实 Gateway 验收。资源测试至少覆盖成功、失败、取消、deadline、断线和用户回调异常。缺失环境的测试记录 BLOCKED,不记录 PASS。 + +## Sources + +[O11 Talk、Agent 与产物 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-talk-config-and-agents);[O12 系统、渠道、插件与终端 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-system-and-channels);[O14 MCP serve](https://docs.openclaw.ai/cli/mcp/serve);[O15 ACP bridge](https://docs.openclaw.ai/cli/acp);[O16 CLI 参考入口](https://docs.openclaw.ai/cli) + +上游文档用于需求依据;本 SDK 的方法签名、状态名与组件结构属于本方案设计。每个 wire 字段和方法在实施前还须与锁定版本确认,不能凭字符串拼接猜测。 diff --git a/openspec/changes/add-optional-runtime-adapters/proposal.md b/openspec/changes/add-optional-runtime-adapters/proposal.md new file mode 100644 index 0000000..5847ea0 --- /dev/null +++ b/openspec/changes/add-optional-runtime-adapters/proposal.md @@ -0,0 +1,39 @@ +# 增加终端、语音、MCP、ACP 与 CLI 可选适配 + +状态:DRAFT / REVIEW_REQUIRED。文档已提出,未批准实现,未归档。优先级:P2。 + +## Why + +一次性 CLI 执行不能代替交互终端、实时语音或持久 stdio 协议。可选适配需先确定生命周期、安全边界和依赖隔离,避免拖累纯 HTTP/Gateway 用户。 + +## What Changes + +- `terminal-voice-adapters`: 远程终端与实时语音。 +- `persistent-stdio-adapters`: MCP 与 ACP 持久协议适配。 +- `cli-typed-results`: CLI 类型化结果和可选动作。 + +此次交付只创建 OpenSpec 文档与证据清单,不修改 Java 代码、构建文件、测试、依赖或发布配置。本提案描述后续拟实施行为,不证明这些能力现在已完成。 + +## Capabilities + +### New Capabilities + +- `terminal-voice-adapters`: 远程终端与实时语音。 +- `persistent-stdio-adapters`: MCP 与 ACP 持久协议适配。 +- `cli-typed-results`: CLI 类型化结果和可选动作。 + +### Modified Capabilities + +无现有同名 OpenSpec 生效规范可修改。本次是首次引入这些能力的正式规范条目,因此使用 ADDED Requirements;并不意味着仓库中不存在相关旧代码。 + +## Impact + +适用分支为 feature/1.0.x、feature/2.0.x、feature/3.0.x。具体源码触点见 design.md;可观测行为见 specs/;验证与执行步骤见 tasks.md。main 不作为第四条已验证发行线。 + +依赖变更:`add-managed-gateway-client`, `add-agent-session-approval-control` + +不在范围:重写 OpenClaw 内部模型引擎、原生插件运行时、沙箱内核或 Gateway 私有 worker 协议;不提供自动授权、跨租户共享密钥隔离或恰好一次执行保证。 + +## Review and Entry Criteria + +必须完成人工范围评审、锁定目标 Gateway 构建与协议映射,并完成依赖变更的必要验收后,才能进入本变更实现。OpenSpec 的 artifact 完整性状态不等于人审通过或产品已完成。具体门禁是本项目约定,而非声称 OpenSpec 官方强制该流程。 diff --git a/openspec/changes/add-optional-runtime-adapters/specs/cli-typed-results/spec.md b/openspec/changes/add-optional-runtime-adapters/specs/cli-typed-results/spec.md new file mode 100644 index 0000000..37302f2 --- /dev/null +++ b/openspec/changes/add-optional-runtime-adapters/specs/cli-typed-results/spec.md @@ -0,0 +1,52 @@ +# CLI 类型化结果和可选动作 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的CLI 类型化结果和可选动作定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: CLI-01 命令存在与支持等级分别声明 +SDK SHALL 区分类型化命令、自由参数透传、仅可启动进程及已完成协议集成;CLI 可用性检查 SHALL 记录可执行文件和精确版本,不把 --version 成功当成全部命令可用。 + +#### Scenario: CLI-01-S1 自由参数透传 +- **GIVEN** browser 或 infer 通过自由参数运行 +- **WHEN** 生成能力清单 +- **THEN** 仅标记透传,不标记全量类型化或真实集成通过 + +#### Scenario: CLI-01-S2 可执行但命令缺失 +- **GIVEN** --version 成功但命令在目标版本中不存在 +- **WHEN** 调用该命令 +- **THEN** 保留不支持结果,不生成虚假的成功 DTO + +### Requirement: CLI-02 机器输出与执行状态分开 +支持机器输出的命令 SHALL 提供版本化解析与原始输出保留,区分退出失败、超时、取消、输出不合法和业务失败;交互式命令 SHALL 不冒充非交互 JSON API。 + +#### Scenario: CLI-02-S1 合法机器输出 +- **GIVEN** 目标命令支持 JSON 且退出成功 +- **WHEN** 解析输出 +- **THEN** 同时提供类型化业务结果和执行元数据 + +#### Scenario: CLI-02-S2 输出不是预期 JSON +- **GIVEN** 命令退出为零但只输出交互提示或未知格式 +- **WHEN** 解析结果 +- **THEN** 报告解析或模式不兼容,不把空结果当成功 + +### Requirement: CLI-03 参数与输出受控且跨平台验证 +CLI 调用 SHALL 保留字面 argv、UTF-8 语义、输出上限、工作目录和取消语义;浏览器、媒体推理及管理动作 SHALL 经过显式能力与权限策略,不默认经 shell 解释。 + +#### Scenario: CLI-03-S1 多词中文参数 +- **GIVEN** 参数含空格、中文或引号 +- **WHEN** 在已声明支持的平台执行 +- **THEN** 进程收到原始参数内容,输出按约定解码 + +#### Scenario: CLI-03-S2 超量输出或交互不退出 +- **GIVEN** 命令持续输出或等待输入 +- **WHEN** 达到输出或时间上限 +- **THEN** 受控终止并保留截断与超时原因,不耗尽内存或占用无限并发 + +## Sources + +[O16 CLI 参考入口](https://docs.openclaw.ai/cli) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-optional-runtime-adapters/specs/persistent-stdio-adapters/spec.md b/openspec/changes/add-optional-runtime-adapters/specs/persistent-stdio-adapters/spec.md new file mode 100644 index 0000000..5e498f6 --- /dev/null +++ b/openspec/changes/add-optional-runtime-adapters/specs/persistent-stdio-adapters/spec.md @@ -0,0 +1,52 @@ +# MCP 与 ACP 持久协议适配 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的MCP 与 ACP 持久协议适配定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: STDIO-01 持久双向协议而非一次性 stdout +MCP 和 ACP 适配器 SHALL 保持独立的持久双向 stdio 会话,处理请求、响应与通知;初始化完成前 SHALL 不宣称协议会话可用。 + +#### Scenario: STDIO-01-S1 协议初始化 +- **GIVEN** 目标进程支持所选协议 +- **WHEN** 双方初始化与能力协商成功 +- **THEN** 返回持续可用的会话,而非等待进程退出才返回 stdout + +#### Scenario: STDIO-01-S2 进程提前退出 +- **GIVEN** 进程在初始化或响应前退出 +- **WHEN** 处理 EOF 和退出码 +- **THEN** 失败所有待处理请求并报告阶段,不悬挂等待 + +### Requirement: STDIO-02 MCP 与 ACP 能力分别协商 +适配器 SHALL 分别遵循锁定版本的 MCP 与 ACP 生命周期,支持其声明的工具或会话、prompt、通知和取消能力;不得用同一 DTO 假定两个协议兼容。 + +#### Scenario: STDIO-02-S1 ACP 会话恢复 +- **GIVEN** 目标 ACP 版本支持恢复且 session 已知 +- **WHEN** 恢复后提交 prompt +- **THEN** 保留会话身份并正确接收流式更新 + +#### Scenario: STDIO-02-S2 MCP 能力缺省 +- **GIVEN** 目标 MCP 服务未声明所需能力 +- **WHEN** 请求该能力 +- **THEN** 明确返回不支持,不以任意 CLI 拼接替代协议 + +### Requirement: STDIO-03 协议帧、诊断和进程关闭隔离 +适配器 SHALL 区分 stdout 协议帧与 stderr 诊断,使用有界帧和缓冲限制,提供取消与幂等关闭;关闭仅处理自己拥有的进程资源。 + +#### Scenario: STDIO-03-S1 诊断穿插 +- **GIVEN** 进程持续在 stderr 写诊断 +- **WHEN** stdout 有合法响应帧 +- **THEN** 协议解析不受诊断影响且日志脱敏 + +#### Scenario: STDIO-03-S2 关闭或帧溢出 +- **GIVEN** 进程不退出或帧超过上限 +- **WHEN** 执行关闭或故障处理 +- **THEN** 在有界预算内终止自有进程与等待者,并保留失败证据 + +## Sources + +[O14 MCP serve](https://docs.openclaw.ai/cli/mcp/serve);[O15 ACP bridge](https://docs.openclaw.ai/cli/acp) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-optional-runtime-adapters/specs/terminal-voice-adapters/spec.md b/openspec/changes/add-optional-runtime-adapters/specs/terminal-voice-adapters/spec.md new file mode 100644 index 0000000..c01f761 --- /dev/null +++ b/openspec/changes/add-optional-runtime-adapters/specs/terminal-voice-adapters/spec.md @@ -0,0 +1,52 @@ +# 远程终端与实时语音 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的远程终端与实时语音定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: TV-01 终端会话全生命周期 +终端适配器 SHALL 支持目标版本的 open、input、resize、attach、list 和 close,输出与退出事件按终端身份关联;权限不足或不支持时不得降级为任意 shell 执行。 + +#### Scenario: TV-01-S1 终端输入输出 +- **GIVEN** 终端已明确建立且宿主授权 +- **WHEN** 写入输入并收到输出事件 +- **THEN** 只有该终端的消费者收到输出与退出事实 + +#### Scenario: TV-01-S2 断线重新附着 +- **GIVEN** 终端连接断开 +- **WHEN** 宿主请求 attach +- **THEN** 按服务端拥有者和目标身份恢复;不保证重放缺失输出,也不自动重开并重跑命令 + +### Requirement: TV-02 语音会话区分会话和输出取消 +语音适配器 SHALL 区分会话创建、音频输入、输出事件、输出取消、工具回填及会话关闭;音频格式与大小 SHALL 依目标能力协商。 + +#### Scenario: TV-02-S1 取消输出 +- **GIVEN** 语音会话保持连接且正在输出 +- **WHEN** 调用者仅取消当前输出 +- **THEN** 停止对应输出而不擅自关闭整个会话 + +#### Scenario: TV-02-S2 不支持格式 +- **GIVEN** 输入音频格式不在已确认支持范围 +- **WHEN** 提交音频 +- **THEN** 明确拒绝或请求转换策略,不伪造格式成功或无限缓冲 + +### Requirement: TV-03 高风险适配默认不自动启用 +远程终端、麦克风输入和敏感 Talk 配置 SHALL 需要显式宿主授权及对应服务端权限;SDK 构造或连接握手 MUST NOT 自动启动这些能力。 + +#### Scenario: TV-03-S1 显式启用 +- **GIVEN** 宿主明确允许某语音或终端操作 +- **WHEN** 调用对应入口 +- **THEN** 仅执行被允许操作并保留生命周期句柄 + +#### Scenario: TV-03-S2 默认连接 +- **GIVEN** 应用只创建普通 Gateway 客户端 +- **WHEN** 完成连接 +- **THEN** 不会打开终端、采集音频或读取额外敏感配置 + +## Sources + +[O12 系统、渠道、插件与终端 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-system-and-channels);[O11 Talk、Agent 与产物 RPC](https://docs.openclaw.ai/gateway/protocol/rpc-talk-config-and-agents) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/add-optional-runtime-adapters/tasks.md b/openspec/changes/add-optional-runtime-adapters/tasks.md new file mode 100644 index 0000000..dfe8ccd --- /dev/null +++ b/openspec/changes/add-optional-runtime-adapters/tasks.md @@ -0,0 +1,32 @@ +# Implementation Tasks + +状态:全部未执行。本清单是后续实施计划,不是本轮文档生成记录。 + +## 1. 准入与证据 + +- [ ] 1.1 取得本变更的人审结论并核验依赖;验收:评审记录包含范围、行为收紧、三分支要求和批准的 change ID。 +- [ ] 1.2 锁定目标 OpenClaw 精确版本/提交、构建来源及协议映射;验收:方法、事件、字段、scope 与拒绝样本均有版本化来源,未锁定时停止编码。 + +## 2. 远程终端与实时语音 + +- [ ] 2.1 为 `terminal-voice-adapters` 建立契约样本及回归基线(TV-01, TV-02, TV-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 2.2 按 design.md 实施 `terminal-voice-adapters` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 2.3 在三条适用分支验证 `terminal-voice-adapters` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 3. MCP 与 ACP 持久协议适配 + +- [ ] 3.1 为 `persistent-stdio-adapters` 建立契约样本及回归基线(STDIO-01, STDIO-02, STDIO-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 3.2 按 design.md 实施 `persistent-stdio-adapters` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 3.3 在三条适用分支验证 `persistent-stdio-adapters` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 4. CLI 类型化结果和可选动作 + +- [ ] 4.1 为 `cli-typed-results` 建立契约样本及回归基线(CLI-01, CLI-02, CLI-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 4.2 按 design.md 实施 `cli-typed-results` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 4.3 在三条适用分支验证 `cli-typed-results` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 5. 集成、资源与归档门禁 + +- [ ] 5.1 对本变更执行真实 Gateway 场景;验收:固定服务端版本、认证方式、运行命令与脱敏证据,成功和拒绝均有真实观察,SDK 本地 fixture 通过不能替代。 +- [ ] 5.2 完成适用的资源、故障与兼容检查;验收:1000 次受控请求/订阅周期后活动注册归零,自有线程在测试预算内终止,共享资源仍可使用;治理类变更检查无运行资源触点并记录不适用理由。 +- [ ] 5.3 更新覆盖矩阵并执行规范校验;验收:官方 OpenSpec validate 输出通过、无未解释的三分支差异、所有必需任务有证据且人审允许归档,随后才更新生效 specs。 diff --git a/openspec/changes/establish-sdk-compatibility-governance/.openspec.yaml b/openspec/changes/establish-sdk-compatibility-governance/.openspec.yaml new file mode 100644 index 0000000..cbd245e --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-09-20 diff --git a/openspec/changes/establish-sdk-compatibility-governance/design.md b/openspec/changes/establish-sdk-compatibility-governance/design.md new file mode 100644 index 0000000..a44944e --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/design.md @@ -0,0 +1,66 @@ +# 建立版本与三分支兼容治理 — Technical Design + +状态:DRAFT / REVIEW_REQUIRED。下述新类与模块名称为拟议设计,不是仓库已存在能力。 + +## Context + +动机与范围见 [proposal](proposal.md)。首次静态核查的 SDK 提交与证据等级见 [coverage-baseline](../../../docs/openclaw-integration/coverage-baseline.md)。G0 后续验证覆盖三条维护线和默认分支,具体运行结果见 [真实 Gateway 基线验证](evidence/2026-11-18-live-gateway.md)。 + +## Goals / Non-Goals + +用可观察契约约束新增或修正行为;保留三条 Java 发行线的既有基线与可行的源码兼容。只引入本变更需要的组件,不进行无关重构。SDK 不代替 Gateway 做权限裁定,也不代替宿主存储或授予长期凭据。 + +## Decisions + +采用共同契约、分支独立证据的方式,不把三个分支合并成一条开发线,也不新增统一发行版本。共享 fixture 的期望语义保持一致;Java 8 语法、Jackson 2/3 包名和宿主扩展点的差异记录到兼容清单。 + +G0 记录的目标是 OpenClaw 2026.7.1-2(`0790d9f`)。[版本锁定记录](evidence/version-lock.md) 和 [官方生成的协议 schema](evidence/2026-11-18-locked-gateway-schema.md) 提供版本与契约依据。2026.11.5 的运行结果用于候选比较。目标版本和实施范围仍需人审确认,后续能力还需按锁定版本逐项核对方法、事件和权限。 + +不把根 specs 填成未来蓝图。由于仓库尚无本轮能力的生效规范,这些能力首次以 ADDED Requirements 建档;ADDED 指新增规范条目,不断言全部代码此前不存在。归档是未来行为,需经过本项目人审和实施证据核验。 + +备选方案是复制 README 作为基线,成本低但会继承错误版本说明;另一方案是先全量重写 SDK 再补文档,无法约束实现范围。本方案优先构建可复核的能力矩阵。 + +## Technical Approach + +核对 SDK 提交 → 锁定目标 Gateway → 映射方法/事件/权限 → 共享场景 → 三分支验证 → 精确能力声明 + +错误类型和状态转换由共享协议层统一;本地超时/取消与远端失败/取消分开。以下源码触点仅用于实施规划,新增路径在接入前需核对实际工作树,不把不存在的文件列为已修改: + +- `docs/openclaw-integration/source-register.md` +- `docs/openclaw-integration/coverage-baseline.md` +- `docs/openclaw-integration/acceptance-plan.md` +- `README.md` +- `README.zh-CN.md` +- `.github/workflows/(实施时核对已有文件后扩展)` + +## Risks / Trade-offs + +文档与运行时漂移 → 将版本锁定作为编码入口门禁;缺少某分支构建环境 → 保留该分支未验证,不复制其他分支通过结果。 + +所有新状态、上限和取消语义必须进入验收;不得使用修改测试预期、跳过不兼容分支或放宽权限来消除失败。 + +## Migration Plan + +先记录对应旧行为并建立最小失败样本,再实施局部修正或加法 API,最后同步其余分支与文档。按 capability 小批提交,避免跨无关领域的大规模替换。回滚只回退该功能变更和明确可逆状态;配置落盘、已执行工具或已投递消息的外部副作用不宣称自动撤销。根 specs 的更新留到经批准的归档阶段。 + +## Validation Strategy + +需求与场景的逐项映射见 [traceability](../../../docs/openclaw-integration/traceability.md)。每项能力须完成固定样本验证、受控模拟、适用分支构建及真实 Gateway 验收。资源测试至少覆盖成功、失败、取消、deadline、断线和用户回调异常。缺失环境的测试记录 BLOCKED,不记录 PASS。 + +## 评审与归档判定 + +| 状态 | 进入条件 | +|---|---| +| DRAFT | 提案可审阅,任务和场景按现有证据标明进度。当前属于此状态。 | +| REVIEWED | 维护者在 PR 记录通过的范围、依赖、目标版本和对应提交。 | +| IMPLEMENTED | 已批准的变更落到目标分支。记录实现提交和执行结果。 | +| VERIFIED | 按场景核对每条适用维护线的提交、命令、运行结果与证据。适用范围例外须有评审记录。 | +| ARCHIVED | 维护者复核归档资格,同步该变更的增量规范并确认归档结果。 | + +评审时以 [场景追踪表](../../../docs/openclaw-integration/traceability.md) 和 [任务清单](tasks.md) 对照每项证据。任何必需任务未完成、场景失败或证据缺失,都应在 PR 上列出对应编号并暂停归档。OpenSpec strict 校验用于校验规格结构,归档资格由维护者按本表复核。当前缺少范围批准、三线共享协议样本和逐场景证据,归档条件尚未满足。 + +## Sources + +[O00 OpenClaw 文档索引](https://docs.openclaw.ai/llms.txt);[O01 外部应用接入边界](https://docs.openclaw.ai/gateway/external-apps);[O02 协议版本与客户端恢复边界](https://docs.openclaw.ai/gateway/protocol/versioning);[S01 OpenSpec 概念与变更目录](https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md);[S02 OpenSpec spec-driven schema](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml) + +上游文档用于需求依据;本 SDK 的方法签名、状态名与组件结构属于本方案设计。每个 wire 字段和方法在实施前还须与锁定版本确认,不能凭字符串拼接猜测。 diff --git a/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-09-20-precursor-evidence.md b/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-09-20-precursor-evidence.md new file mode 100644 index 0000000..f3cd9af --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-09-20-precursor-evidence.md @@ -0,0 +1,39 @@ +# G0 准入证据(2026-09-20 采集) + +## 任务 1.2 版本锁定 +见 `version-lock.md`。OpenClaw `2026.7.1-2 (0790d9f)`,npm 全局安装,Node v24.18.0。 + +## 任务 1.3 codegraph 证据(三分支独立检出) +| 分支 | SHA | 执行方式 | 结果 | +|---|---|---|---| +| feature/3.0.x | 3687fcb | codegraph MCP build(主 worktree) | head_matches_build=true,增量 23 文件 / 420 节点 | +| feature/2.0.x | 48309d7 | 同上(切分支后增量) | head_matches_build=true,16 文件 / 275 节点 | +| feature/1.0.x | 8cfbeb8 | 独立 worktree /tmp/wt-oc-1.0.x 全量 | 200 文件 / 2324 节点 / 13840 边 | + +Java 支持正常,无执行失败项。命令:`build_or_update_graph_tool`(MCP)/ `codegraph` CLI 等价。 + +## 任务 3.3 构建与测试证据(每条分支独立) +| 分支 | JDK | Maven | 构建 | 测试 | +|---|---|---|---|---| +| feature/3.0.x | 21 (ms-21.0.12.1) | wrapper Maven 4 (./mvnw) | clean deploy BUILD SUCCESS | 155/155 绿 | +| feature/2.0.x | 17 (corretto-17.0.20.1) | 3.9.16 (mvn) | clean deploy BUILD SUCCESS | 155/155 绿 | +| feature/1.0.x | 8 (corretto-1.8.0_504) | 3.9.16 (mvn) | clean deploy BUILD SUCCESS | 155/155 绿 | + +非零执行测试数:0。CI(GitHub Actions):三分支最新 run 均 success。 + +## 任务 3.4 官方 OpenSpec CLI 校验 +`openspec validate --all --strict --no-interactive --json`(CLI 1.8.0): +6/6 changes valid(establish-sdk-compatibility-governance、fix-openclaw-protocol-contracts、 +add-managed-gateway-client、add-agent-session-approval-control、add-gateway-operations、 +add-optional-runtime-adapters),issues 均为空。 + +## 任务 2.1 能力证据清单 +见 `capability-inventory.json`。静态存在 8 项(HTTP 五客户端、CLI、WS core、Spring 装配)、 +未封装 4 项(G2-G5 目标能力);全部 liveVerified=false,无任何 live-pass 标记。 + +## 阻塞项(人审/环境门禁,未勾选原因) +- 1.1 / 2.3 / 3.5:需人审记录(范围、批准、归档资格),AI 会话不能冒充。 +- 2.2:三分支协议 fixture 与获准差异清单,待 1.1 批准后建立。 +- 2.4:traceability 逐项映射,依赖 2.1-2.3 产物。 +- 3.1:真实 Gateway 健康/认证/授权检查,需启动真实 Gateway(本机 openclaw 2026.7.1-2 可执行,未在本轮启动)。 +- 3.2:文档漂移修正,随 G1 实施时逐分支核对。 diff --git a/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-live-gateway.md b/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-live-gateway.md new file mode 100644 index 0000000..7261074 --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-live-gateway.md @@ -0,0 +1,66 @@ +# G0 真实 Gateway 基线验证(2026-11-18) + +两次 Gateway 启动都只监听回环地址,使用独立状态目录、临时 Token,并关闭插件。SDK 测试仅执行握手和会话列表查询。 + +| Gateway | SDK 维护线 | 源码 SHA | JDK | 验证 | +|---|---|---|---|---| +| 2026.7.1-2 | feature/1.0.x | `8cfbeb880a6c6ae5390fab0f9fe65e06938907be` | 1.8.0_504 | 3 项通过 | +| 2026.7.1-2 | feature/2.0.x | `48309d7bc34c4298cdfa1c52db06114b2e7e9f17` | 17.0.21 | 3 项通过 | +| 2026.7.1-2 | feature/3.0.x | `87c21133aba6364f64ed0edbefab2d821564ede0` | 21.0.13.0.2 | 3 项通过 | +| 2026.11.5 | feature/1.0.x | `8cfbeb880a6c6ae5390fab0f9fe65e06938907be` | 1.8.0_504 | 3 项通过 | +| 2026.11.5 | feature/2.0.x | `48309d7bc34c4298cdfa1c52db06114b2e7e9f17` | 17.0.21 | 3 项通过 | +| 2026.11.5 | feature/3.0.x | `87c21133aba6364f64ed0edbefab2d821564ede0` | 21.0.13.0.2 | 3 项通过 | + +每组验证包括正确 Token 握手并协商协议 4、错误 Token 被 Gateway 拒绝、使用 operator.read 读取会话列表。JDK 8 和 17 通过系统 Maven 执行,JDK 21 使用仓库 Wrapper。 + +## 追加权限与默认分支验证 + +同一有效 Token,在三条维护线均可建立 WebSocket 握手。客户端请求空权限集合时,两版 Gateway 均拒绝 `sessions.list`,SDK 收到结构化错误 `missing scope: operator.read`。此前用读取权限执行的正向查询均成功。 + +默认分支 `ee0474ea597551a613291134858dbc83b815b20e` 使用有效 Token 发起握手,两版 Gateway 均返回 `invalid connect params`。服务端记录显示 `client.id` 校验失败,锁定版本的首次探测还报告了 `client.mode`。旧分支源码声明协议 1。实际握手在元数据校验阶段被拒绝,本次运行未到达协议协商阶段。 + +追加验证共 8 项,零失败、零跳过。两次默认分支测试以验证拒绝为预期结果。真实模型调用和 G0/G1 范围审批仍待验收。 + +## 复核方法 + +使用官方 npm 发布包 `openclaw@2026.7.1-2` 和 `openclaw@2026.11.5`,以 Node 24.18.0 分别启动 `openclaw gateway run`。确认两次 `GET /readyz` 均返回 `ready: true` 后,将 SDK WebSocket URI 指向对应的本地端口。表中的 SHA 对应独立检出目录的源码。 + +每条维护线使用 `OpenClawGatewayWsClient.connectHandshake()` 检查服务端返回的协议号,并调用 `sessionsList()`。认证失败由 Gateway 的 Token 不匹配记录确认。权限不足由 SDK 的 `OpenClawWsRpcException` 确认,异常保留方法名 `sessions.list` 和服务端的结构化错误。报告省略临时 Token 和连接标识。 + +锁定版本的基础运行检查满足 G0 任务 3.1。候选版本的结果用于后续版本选择评审。默认分支的兼容缺口计入后续 G1 握手工作。此检查未调用模型,版本与范围审批仍待人审。 + +## 维护线文档一致性 + +三条维护线分别比较 POM、Wrapper 配置、中英文 README 与 GitHub Release 说明。两份 README 的 Maven 和 Gradle 示例都使用该维护线 POM 中的快照版本。GitHub Release 说明使用同一版本号的非快照标签,说明原有版本的维护线,未附带 Maven 制品或 Gateway 兼容性测试结果。 + +| 维护线 | POM 快照版本 | JDK / Wrapper | Jackson databind | 文档提交 | 测试分支 CI | +|---|---|---|---|---|---| +| feature/1.0.x | 1.0.x.20260630-SNAPSHOT | 8 / 3.9.16 | com.fasterxml.jackson.core 2.18.9 | 3dc46a0e58200b086efc59029a43aa5c136bf61b | [成功](https://github.com/easy-4-java/openclaw-java-sdk/actions/runs/44335946637) | +| feature/2.0.x | 2.0.x.20260630-SNAPSHOT | 17 / 3.9.16 | com.fasterxml.jackson.core 2.22.1 | 9293a8cd2580435ec076b076d98c7965b77f0049 | [成功](https://github.com/easy-4-java/openclaw-java-sdk/actions/runs/44335947125) | +| feature/3.0.x | 3.0.x.20260630-SNAPSHOT | 21 / 4.0.0-rc-5 | tools.jackson.core 3.2.1 | 34b003b5c2c2158e536d3290ef67de7932ab78ef | [成功](https://github.com/easy-4-java/openclaw-java-sdk/actions/runs/44335951638) | + +三个提交仅修改各自的两份 README,已推送到对应的维护线。六份 README 均通过快照坐标、依赖版本、JDK、Wrapper、Release 标签和验证范围核对。文档明确记录实测的协议 4 握手、Token 认证和会话列表的读取权限检查,并标明 HTTP、SSE、CLI、模型调用及其余 RPC 的真实兼容性待验证。 + +## 三条维护线共用的 Gateway 测试样本 + +[GatewayCompatibilityFixtureTest.java](fixtures/GatewayCompatibilityFixtureTest.java) 在三条维护线上使用同一份源码。它通过公开 SDK API 验证协议 4 握手、无效 Token、`operator.read` 下的 `sessions.list` 以及缺少权限时的结构化拒绝。无效 Token 场景的客户端断言检查握手异常,服务端日志同时确认了 `token_mismatch`,因此可以区分认证拒绝和网络故障。 + +| SDK 源码 | JDK | Maven | Gateway 2026.7.1-2 | Gateway 2026.11.5 | +|---|---|---|---|---| +| `8cfbeb8` | 1.8.0_504 | 3.9.16 | 4 项通过 | 4 项通过 | +| `48309d7` | 17.0.21 | 3.9.16 | 4 项通过 | 4 项通过 | +| `87c2113` | 21.0.13.0.2 | 4.0.0-rc-5 | 4 项通过 | 4 项通过 | + +六次执行均无失败、错误或跳过,两个 Gateway 均通过 `/readyz`。不同 JDK 和 Jackson 包名无需分叉这四个场景。默认分支握手差异保留在上文的独立记录中。GOV-02 的其它协议行为及差异清单批准仍待验收。 + +复核时在三条维护线的独立检出目录中,将样本放到 `src/test/java/io/github/easy4j/openclaw/ws/`。按上文使用独立状态目录和临时 Token 启动本地 Gateway,只绑定回环地址并关闭插件。将 `SDK_PROBE_URL` 和 `OPENCLAW_GATEWAY_TOKEN` 传给测试进程。请勿使用线上 Token 或生产 Gateway。 + +```bash +# JDK 8 and JDK 17 +mvn -B -ntp -Dtest=GatewayCompatibilityFixtureTest test + +# JDK 21 +./mvnw -B -ntp -Dtest=GatewayCompatibilityFixtureTest test +``` + +每个版本均复核服务端认证拒绝原因、四条 JUnit 测试记录及 Maven 退出码。 diff --git a/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-locked-gateway-schema.md b/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-locked-gateway-schema.md new file mode 100644 index 0000000..bf616fb --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-18-locked-gateway-schema.md @@ -0,0 +1,27 @@ +# 锁定版 Gateway 协议 schema(2026-11-18) + +`v2026.7.1-2` 对应提交 `0790d9f593ad30c940ed93b5872a8cf6d6f3cf8c`。该版本将 `@openclaw/gateway-protocol` 定义为私有工作区包,npm 注册表没有同版本制品。使用该提交的官方生成器和原始协议定义生成了 Draft-07 JSON Schema。[上游包定义](https://github.com/openclaw/openclaw/blob/0790d9f593ad30c940ed93b5872a8cf6d6f3cf8c/packages/gateway-protocol/package.json) · [上游生成器](https://github.com/openclaw/openclaw/blob/0790d9f593ad30c940ed93b5872a8cf6d6f3cf8c/scripts/protocol-gen.ts) + +| 检查 | 结果 | +|---|---| +| 生成环境 | Node 24.18.0、tsx 4.22.4、typebox 1.3.3 | +| 产物 | `dist/protocol.schema.json`,714085 字节,322 项定义 | +| SHA-256 | `0c5758a9750691b6fb070c6344297bce6ddeba89afd715e45531a9508a168699` | +| 可复现性 | 连续执行两次生成器,结果逐字节一致。所有本地 definition 引用均可解析。 | +| ConnectParams | `gateway-client/backend` 通过校验。默认分支的 `openclaw-java-sdk/operator` 在两个枚举字段上均被拒绝。 | + +## 复现 + +将以下命令放在独立临时目录中执行。安装只用于运行锁定版生成器的依赖,源码与 SDK 工作区保持原状。 + +```bash +git clone --depth 1 --filter=blob:none --sparse --branch v2026.7.1-2 https://github.com/openclaw/openclaw.git source +git -C source sparse-checkout set --no-cone /packages/gateway-protocol/ /scripts/protocol-gen.ts /package.json +test "$(git -C source rev-parse HEAD)" = 0790d9f593ad30c940ed93b5872a8cf6d6f3cf8c +npm install --prefix tooling --ignore-scripts --no-audit --no-fund tsx@4.22.4 typebox@1.3.3 +ln -s "$(pwd)/tooling/node_modules" source/node_modules +(cd source && node --import tsx scripts/protocol-gen.ts) +shasum -a 256 source/dist/protocol.schema.json +``` + +使用锁定版 Gateway 安装包中的 Ajv 校验 `ConnectParams`。失败路径与此前运行中的 Gateway 拒绝结果一致。离线校验只覆盖字段结构和枚举,认证、服务器协商协议版本以及授权结果见 [真实 Gateway 基线验证](2026-11-18-live-gateway.md)。本记录不改变待评审的目标版本。 diff --git a/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-19-governance-scenario-audit.md b/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-19-governance-scenario-audit.md new file mode 100644 index 0000000..edd9d37 --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/evidence/2026-11-19-governance-scenario-audit.md @@ -0,0 +1,48 @@ +# G0 场景证据核对(2026-11-19) + +[规格场景](../specs/sdk-compatibility-governance/spec.md)的当前检查记录如下。原始追踪表保留首次编制时的历史状态。真实 Gateway 验证结果以对应 SDK 提交、目标版本和具体调用为准。 + +| 场景 | 已核对的证据 | 剩余验收 | +|---|---|---| +| GOV-01-S1 真实通过可追溯 | [实测记录](2026-11-18-live-gateway.md)绑定三条维护线、两版 Gateway、JDK、Maven、命令和四项测试。 | 核对发布兼容矩阵的实际内容及评审记录。 | +| GOV-01-S2 缺少运行证据 | [能力清单](capability-inventory.json)保留静态存在、未封装以及 `liveVerified=false`。维护线 README 仅声明已实测的 WebSocket 范围。 | 发布时逐项核对能力声明。 | +| GOV-02-S1 依赖适配差异 | [共用样本](fixtures/GatewayCompatibilityFixtureTest.java)在 Java 8、17、21 上执行,两版 Gateway 共通过 24 项检查。 | [真实 Gateway 并发串流](../../fix-openclaw-protocol-contracts/evidence/2026-11-19-gateway-chat-isolation.md)三线均失败。流重建、终态语义及允许差异清单待验收。 | +| GOV-02-S2 单分支缺测 | [实测记录](2026-11-18-live-gateway.md)为各维护线分别列出结果,并独立记录默认分支拒绝;其它协议能力仍未标记为通过。 | 用只验证一条线的样本演示发布流程如何阻止全线声明。 | +| GOV-03-S1 文档评审 | [设计稿](../design.md)标明草案,[任务清单](../tasks.md)保留未完成项。 | 维护者记录范围、版本和依赖审批。 | +| GOV-03-S2 提前归档 | [归档判定](../design.md#评审与归档判定)列明阻断项,生效规范尚未更新。 | 维护者确认归档拒绝条件和验收记录。 | +| GOV-04-S1 版本升级 | 本页对两个精确提交的官方 schema 进行离线比较。候选版握手与会话读取有独立实测。 | 确认候选字段的样本、语义和采用范围。 | +| GOV-04-S2 已移除调用 | 锁定版核心注册表声明 `tasks.list`,候选版核心方法清单与连接公告均缺少该项。三条维护线实测候选版返回 `FORBIDDEN`,SDK 保留错误并全程使用原权限。 | 当前 SDK 未封装该调用。显式的能力级不可用结果仍待验收。 | + +## 锁定版与候选版 schema 差异 + +| Gateway | 上游提交 | 定义数 | 生成产物 SHA-256 | +|---|---|---:|---| +| 2026.7.1-2 | `0790d9f593ad30c940ed93b5872a8cf6d6f3cf8c` | 322 | `0c5758a9750691b6fb070c6344297bce6ddeba89afd715e45531a9508a168699` | +| 2026.11.5 | `e13cf15ece9bbd969b7362927c315362c90c97ff` | 1149 | `fd29d1da7e6ebd0c1014617611ff442164495b3130bbdaea79ca87925324b8b6` | + +两份产物均为 Draft-07,全部本地 JSON Pointer 引用均可解析。按定义名称比较原始 JSON 对象,共有 275 项同名定义,其中 126 项相同、149 项不同;874 个名称仅在候选版出现,47 个名称仅在锁定版出现。候选版还生成 559 条核心方法元数据。定义数受展开方式和生成器变化影响,方法是否存在应通过注册表及运行验证确认。 + +- `ConnectParams` 新增 `computerUse`、`includeSessionMessageBodies`、`modelCatalog` 和 `workerRuns` 字段,顶层必填字段列表相同。 +- `SessionsListParams` 新增 `rowMode`、`ownerId`、`ifRowsRevision` 等字段。候选版元数据将 `sessions.list` 归到 `operator.read`。两版运行验证均覆盖读取成功及缺少权限的拒绝。 +- `RequestFrame` 新增 `expectedProfileId`、`traceparent`,`EventFrame` 新增 `recipientProfileId`。此次未对新增字段执行运行验证。 + +候选版使用原始 [上游生成器](https://github.com/openclaw/openclaw/blob/e13cf15ece9bbd969b7362927c315362c90c97ff/scripts/protocol-gen.ts),环境为 Node 24.18.0、tsx 4.23.15 和 typebox 1.4.2。临时检出按同一 tag 补齐 `packages/gateway-protocol`、`packages/normalization-core`、`scripts`、`src/gateway` 和 `src/shared`。其中 `@openclaw/normalization-core` 的构建导出使用同版本 npm 发布包的 `dist/normalization-core`,由临时符号链接提供给检出目录的包导出入口。生成器调用 `node --import ./scripts/tsx.mjs scripts/protocol-gen.ts --out <临时路径>`,执行两次,两个文件逐字节相同。上游检出中的跟踪文件未修改。 + +本次对照保留原目标版本及评审状态。候选版新增行为应按规格另行验收。 + +## 核心方法移除后的运行验证 + +锁定版 [核心方法表](https://github.com/openclaw/openclaw/blob/0790d9f593ad30c940ed93b5872a8cf6d6f3cf8c/src/gateway/methods/core-descriptors.ts)将只读方法 `tasks.list` 归入 `operator.read`。候选版官方生成器输出的核心方法表无此项。两版真实 Gateway 均关闭插件,分别用 `hello.features.methods` 确认方法公告存在与缺失。 + +[RemovedGatewayMethodFixtureTest.java](fixtures/RemovedGatewayMethodFixtureTest.java)复用相同的临时 Token 类型、协议 4 握手和仅 `operator.read` 的连接权限。通过反射调用 SDK 的内部 RPC 路径,测试分别观察: + +| Gateway | 三条维护线结果 | +|---|---| +| 2026.7.1-2 | 公告中含 `tasks.list`,只读调用返回结果。 | +| 2026.11.5 | 公告中缺少 `tasks.list`,同一调用被拒绝。SDK 保留原方法名、`FORBIDDEN` 和服务端权限错误。 | + +候选版首次探测按假设期待 `INVALID_REQUEST`,三条线均观测到 `FORBIDDEN`。Gateway 日志确认拒绝发生在权限检查。最终断言使用观测到的错误码,在原权限下复验。两版各 3 项通过,零失败、零跳过。每次只发送一次目标调用。测试随后独立发起 `sessions.list`,验证原会话仍可用。测试记录所有发送的方法名,确认序列只含握手、目标调用和后续显式检查。 + +该调用没有公开的 typed SDK 封装。证据覆盖核心公告、当前权限下的拒绝和 SDK 内部错误保留。候选版未新增权限或替代方法调用,能力级不可用语义仍待验收。 + +复核使用 [共用样本的本地启动方法](2026-11-18-live-gateway.md#三条维护线共用的-gateway-测试样本),将测试文件换为本样本,并将 `SDK_PROBE_TARGET` 分别设为 `locked` 或 `candidate`。运行对应 JDK 的 Maven `-Dtest=RemovedGatewayMethodFixtureTest test`。 diff --git a/openspec/changes/establish-sdk-compatibility-governance/evidence/capability-inventory.json b/openspec/changes/establish-sdk-compatibility-governance/evidence/capability-inventory.json new file mode 100644 index 0000000..da3b662 --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/evidence/capability-inventory.json @@ -0,0 +1,24 @@ +{ + "generatedAt": "2026-09-20", + "openclawVersion": "2026.7.1-2 (0790d9f)", + "branches": { + "feature/1.0.x": {"sha": "8cfbeb8", "jdk": 8, "tests": "155 green", "graph": "2324 nodes / 13840 edges"}, + "feature/2.0.x": {"sha": "48309d7", "jdk": 17, "tests": "155 green", "graph": "indexed, head_matches_build=true"}, + "feature/3.0.x": {"sha": "3687fcb", "jdk": 21, "tests": "155 green", "graph": "indexed, head_matches_build=true"} + }, + "capabilities": [ + {"id": "http-chat", "status": "static-present", "evidence": "OpenClawChatClient + 单测", "liveVerified": false}, + {"id": "http-responses", "status": "static-present", "evidence": "OpenClawResponsesClient + SSE reader + 单测", "liveVerified": false}, + {"id": "http-embeddings", "status": "static-present", "evidence": "OpenClawEmbeddingsClient + 单测", "liveVerified": false}, + {"id": "http-tool-invoke", "status": "static-present", "evidence": "OpenClawToolInvokeClient + 单测", "liveVerified": false}, + {"id": "http-webhook", "status": "static-present", "evidence": "OpenClawWebhookClient + 单测", "liveVerified": false}, + {"id": "cli-commands", "status": "static-present", "evidence": "OpenClawCli 81+ 方法 + 参数装配测试 + UTF-8 回归", "liveVerified": false}, + {"id": "ws-gateway-core", "status": "static-present", "evidence": "OpenClawGatewayWsClient chat/sessions/cron/config + 本地 fixture 集成测试", "liveVerified": false}, + {"id": "spring-boot-autoconfig", "status": "static-present", "evidence": "spring/boot 包", "liveVerified": false}, + {"id": "gateway-reconnect-reconciliation", "status": "not-wrapped", "evidence": null, "liveVerified": false}, + {"id": "approval-execution-loop", "status": "not-wrapped", "evidence": null, "liveVerified": false}, + {"id": "gateway-ops-rpcs", "status": "not-wrapped", "evidence": null, "liveVerified": false}, + {"id": "terminal-voice-adapters", "status": "not-wrapped", "evidence": null, "liveVerified": false} + ], + "rule": "liveVerified=false 或 evidence=null 的条目不得标记为 live-pass;CLI 透传不计为已封装能力。" +} diff --git a/openspec/changes/establish-sdk-compatibility-governance/evidence/fixtures/GatewayCompatibilityFixtureTest.java b/openspec/changes/establish-sdk-compatibility-governance/evidence/fixtures/GatewayCompatibilityFixtureTest.java new file mode 100644 index 0000000..3709334 --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/evidence/fixtures/GatewayCompatibilityFixtureTest.java @@ -0,0 +1,77 @@ +package io.github.easy4j.openclaw.ws; + +import io.github.easy4j.openclaw.OpenClawHttpClientConfig; +import io.github.easy4j.openclaw.exception.OpenClawWsRpcException; +import io.github.easy4j.openclaw.ws.protocol.HelloOk; +import org.junit.jupiter.api.Test; + +import java.net.URI; +import java.util.Collections; +import java.util.List; +import java.util.Objects; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +final class GatewayCompatibilityFixtureTest { + + @Test + void handshakeNegotiatesProtocolFour() throws Exception { + try (OpenClawGatewayWsClient client = client(requireEnv("OPENCLAW_GATEWAY_TOKEN"), + Collections.singletonList("operator.read"))) { + HelloOk hello = client.connectHandshake(); + assertEquals(4, hello.getProtocol()); + assertNotNull(hello.getServer()); + } + } + + @Test + void handshakeRejectsInvalidToken() { + try (OpenClawGatewayWsClient client = client("invalid-" + requireEnv("OPENCLAW_GATEWAY_TOKEN"), + Collections.singletonList("operator.read"))) { + assertThrows(RuntimeException.class, client::connectHandshake); + } + } + + @Test + void sessionsListAllowsOperatorRead() throws Exception { + try (OpenClawGatewayWsClient client = client(requireEnv("OPENCLAW_GATEWAY_TOKEN"), + Collections.singletonList("operator.read"))) { + assertEquals(4, client.connectHandshake().getProtocol()); + assertNotNull(client.sessionsList()); + } + } + + @Test + void sessionsListRejectsMissingReadScope() throws Exception { + try (OpenClawGatewayWsClient client = client(requireEnv("OPENCLAW_GATEWAY_TOKEN"), + Collections.emptyList())) { + assertEquals(4, client.connectHandshake().getProtocol()); + OpenClawWsRpcException failure = assertThrows(OpenClawWsRpcException.class, client::sessionsList); + assertEquals("sessions.list", failure.getMethod()); + assertTrue(failure.getError().getMessage().contains("missing scope: operator.read")); + } + } + + private OpenClawGatewayWsClient client(String token, List scopes) { + URI gateway = URI.create(requireEnv("SDK_PROBE_URL")); + assertEquals("ws", gateway.getScheme()); + assertEquals("127.0.0.1", gateway.getHost()); + + OpenClawHttpClientConfig config = new OpenClawHttpClientConfig(); + config.setBaseUrl(gateway.toString().replaceFirst("^ws:", "http:")); + config.setGatewayClientId("gateway-client"); + config.setGatewayClientMode("backend"); + config.setGatewayAuthToken(token); + config.setGatewayScopes(scopes); + return new OpenClawGatewayWsClient(config, gateway); + } + + private static String requireEnv(String name) { + String value = Objects.requireNonNull(System.getenv(name), name + " is required"); + assertTrue(!value.isEmpty(), name + " must not be empty"); + return value; + } +} diff --git a/openspec/changes/establish-sdk-compatibility-governance/evidence/fixtures/RemovedGatewayMethodFixtureTest.java b/openspec/changes/establish-sdk-compatibility-governance/evidence/fixtures/RemovedGatewayMethodFixtureTest.java new file mode 100644 index 0000000..13e35bd --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/evidence/fixtures/RemovedGatewayMethodFixtureTest.java @@ -0,0 +1,88 @@ +package io.github.easy4j.openclaw.ws; + +import io.github.easy4j.openclaw.OpenClawHttpClientConfig; +import io.github.easy4j.openclaw.exception.OpenClawWsRpcException; +import io.github.easy4j.openclaw.ws.protocol.HelloOk; +import org.junit.jupiter.api.Test; + +import java.lang.reflect.InvocationTargetException; +import java.lang.reflect.Method; +import java.net.URI; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.List; +import java.util.Map; +import java.util.Objects; +import java.util.concurrent.CopyOnWriteArrayList; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +final class RemovedGatewayMethodFixtureTest { + private static final String METHOD = "tasks.list"; + private static final Pattern RPC_METHOD = Pattern.compile("\"method\"\\s*:\\s*\"([^\"]+)\""); + + @Test + void reportsRemovedReadMethodWithoutRetryOrFallback() throws Exception { + String target = Objects.requireNonNull(System.getenv("SDK_PROBE_TARGET")); + assertTrue("locked".equals(target) || "candidate".equals(target)); + boolean advertised = "locked".equals(target); + URI endpoint = URI.create(Objects.requireNonNull(System.getenv("SDK_PROBE_URL"))); + assertEquals("ws", endpoint.getScheme()); + assertEquals("127.0.0.1", endpoint.getHost()); + + OpenClawHttpClientConfig config = new OpenClawHttpClientConfig(); + config.setBaseUrl(endpoint.toString().replaceFirst("^ws:", "http:")); + config.setGatewayClientId("gateway-client"); + config.setGatewayClientMode("backend"); + config.setGatewayAuthToken(Objects.requireNonNull(System.getenv("OPENCLAW_GATEWAY_TOKEN"))); + config.setGatewayScopes(Collections.singletonList("operator.read")); + + try (RecordingClient client = new RecordingClient(config, endpoint)) { + HelloOk hello = client.connectHandshake(); + assertEquals(4, hello.getProtocol()); + assertEquals(advertised, hello.getFeatures().getMethods().contains(METHOD)); + + Method invoke = OpenClawGatewayWsClient.class.getDeclaredMethod("invokeRpc", + String.class, Object.class, Class.class, long.class); + invoke.setAccessible(true); + if (advertised) { + Object result = invoke.invoke(client, METHOD, Collections.emptyMap(), Map.class, 5000L); + assertNotNull(result); + } else { + InvocationTargetException thrown = assertThrows(InvocationTargetException.class, + () -> invoke.invoke(client, METHOD, Collections.emptyMap(), Map.class, 5000L)); + assertTrue(thrown.getCause() instanceof OpenClawWsRpcException); + OpenClawWsRpcException error = (OpenClawWsRpcException) thrown.getCause(); + assertEquals(METHOD, error.getMethod()); + assertEquals("FORBIDDEN", error.getError().getCode()); + assertEquals("missing scope: operator.admin", error.getError().getMessage()); + } + + assertNotNull(client.sessionsList()); + assertEquals(Arrays.asList("connect", METHOD, "sessions.list"), new ArrayList<>(client.methods)); + } + } + + private static final class RecordingClient extends OpenClawGatewayWsClient { + private final List methods = new CopyOnWriteArrayList<>(); + + RecordingClient(OpenClawHttpClientConfig config, URI endpoint) { + super(config, endpoint); + } + + @Override + public void send(String text) { + Matcher match = RPC_METHOD.matcher(text); + if (match.find()) { + methods.add(match.group(1)); + } + super.send(text); + } + } +} diff --git a/openspec/changes/establish-sdk-compatibility-governance/evidence/version-lock.md b/openspec/changes/establish-sdk-compatibility-governance/evidence/version-lock.md new file mode 100644 index 0000000..9b5e7b0 --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/evidence/version-lock.md @@ -0,0 +1,21 @@ +# 版本锁定记录(G0 任务 1.2) + +锁定日期:2026-09-20。锁定人:hiwepy(经 AI 会话采集,待人审确认)。 + +## 目标 OpenClaw 版本 + +| 项 | 值 | 来源 | +|---|---|---| +| 版本 | `2026.7.1-2` | `openclaw --version` 实测输出 | +| 提交 | `0790d9f` | 同上(版本串内嵌短提交) | +| 构建来源 | npm 全局安装 | `~/.local/bin/openclaw` → `../lib/node_modules/openclaw/openclaw.mjs`(node 启动器) | +| Node 运行时 | v24.18.0(nvm) | `node --version` | + +## 协议来源 + +- Gateway 协议:docs.openclaw.ai `/gateway/protocol/*`(protocol、auth、handshake、rpc-methods、rpc-session-control、transport、versioning)。 +- CLI 命令树:docs.openclaw.ai `/cli`(含 infer=capability 别名、policy/voicecall/file-transfer 为可选插件等备注)。 + +## 声明 + +已用锁定提交的官方生成器产出 [机器可读协议 schema](2026-11-18-locked-gateway-schema.md)。该版本的协议包属于上游私有工作区。运行时行为见 [真实 Gateway 基线验证](2026-11-18-live-gateway.md)。G0 任务 3.1 已执行,版本锁定和 G1 编码仍待人审。 diff --git a/openspec/changes/establish-sdk-compatibility-governance/proposal.md b/openspec/changes/establish-sdk-compatibility-governance/proposal.md new file mode 100644 index 0000000..4860c82 --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/proposal.md @@ -0,0 +1,35 @@ +# 建立版本与三分支兼容治理 + +状态:DRAFT / REVIEW_REQUIRED。文档已提出,未批准实现,未归档。优先级:P0。 + +## Why + +当前资料存在静态能力、CLI 透传和真实集成证据混用的风险。先规定证据来源、版本准入和三分支同步方式,才能有依据地接受后续功能。 + +## What Changes + +- `sdk-compatibility-governance`: 兼容性与证据治理。 + +此次交付只创建 OpenSpec 文档与证据清单,不修改 Java 代码、构建文件、测试、依赖或发布配置。本提案描述后续拟实施行为,不证明这些能力现在已完成。 + +## Capabilities + +### New Capabilities + +- `sdk-compatibility-governance`: 兼容性与证据治理。 + +### Modified Capabilities + +无现有同名 OpenSpec 生效规范可修改。本次是首次引入这些能力的正式规范条目,因此使用 ADDED Requirements;并不意味着仓库中不存在相关旧代码。 + +## Impact + +适用分支为 feature/1.0.x、feature/2.0.x、feature/3.0.x。具体源码触点见 design.md;可观测行为见 specs/;验证与执行步骤见 tasks.md。main 不作为第四条已验证发行线。 + +依赖变更:无;本变更是后续实施的证据与兼容准入基础。 + +不在范围:重写 OpenClaw 内部模型引擎、原生插件运行时、沙箱内核或 Gateway 私有 worker 协议;不提供自动授权、跨租户共享密钥隔离或恰好一次执行保证。 + +## Review and Entry Criteria + +必须完成人工范围评审、锁定目标 Gateway 构建与协议映射,并完成依赖变更的必要验收后,才能进入本变更实现。OpenSpec 的 artifact 完整性状态不等于人审通过或产品已完成。具体门禁是本项目约定,而非声称 OpenSpec 官方强制该流程。 diff --git a/openspec/changes/establish-sdk-compatibility-governance/specs/sdk-compatibility-governance/spec.md b/openspec/changes/establish-sdk-compatibility-governance/specs/sdk-compatibility-governance/spec.md new file mode 100644 index 0000000..d0471f8 --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/specs/sdk-compatibility-governance/spec.md @@ -0,0 +1,65 @@ +# 兼容性与证据治理 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的兼容性与证据治理定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: GOV-01 发布能力必须有版本化证据 +SDK 的能力声明 SHALL 绑定 SDK 分支与提交、OpenClaw 精确版本或提交、协议版本和验证层级;文档阅读、字段存在、CLI 透传均 MUST NOT 被标记为真实集成通过。 + +#### Scenario: GOV-01-S1 真实通过可追溯 +- **GIVEN** 已锁定目标 Gateway 构建且场景已执行 +- **WHEN** 维护者发布兼容矩阵 +- **THEN** 矩阵记录双方提交、运行命令、环境、测试结果与证据文件位置 + +#### Scenario: GOV-01-S2 缺少运行证据 +- **GIVEN** 只有当前在线文档及源码静态审查 +- **WHEN** 生成发布说明 +- **THEN** 状态保持未验证,禁止宣称生产就绪或全量协议支持 + +### Requirement: GOV-02 三分支语义一致而非字节相同 +同一已批准能力的三条版本线 SHALL 使用相同请求与响应语义、错误分类、权限边界和验收样本;语言及依赖适配差异 SHALL 单独登记,未经评审 MUST NOT 形成隐藏功能分叉。 + +#### Scenario: GOV-02-S1 依赖适配差异 +- **GIVEN** 1.x、2.x、3.x 使用不同 JDK 或 JSON 库 +- **WHEN** 同一协议样本在各分支执行 +- **THEN** 序列化、流重建和终态结果一致,获准差异可追溯 + +#### Scenario: GOV-02-S2 单分支缺测 +- **GIVEN** 某次修复只通过 3.x 的验收 +- **WHEN** 准备宣称三个版本都支持 +- **THEN** 其余分支保持未验证或明确不支持,不用 cherry-pick 成功代替测试 + +### Requirement: GOV-03 提案与生效规范分离 +未评审或未实现的行为 SHALL 保留为变更提案;实现任务 MUST 保持未完成状态直至对应证据通过;规范归档 SHALL 以本项目规定的人审与验收条件为前提。 + +#### Scenario: GOV-03-S1 文档评审 +- **GIVEN** proposal、design、specs、tasks 已写好但未实现 +- **WHEN** 评审者查看变更 +- **THEN** 显示草案状态和未完成任务,不把 artifact 齐全解释为功能完成 + +#### Scenario: GOV-03-S2 提前归档 +- **GIVEN** 存在失败或缺失的必需验收证据 +- **WHEN** 尝试更新生效规范 +- **THEN** 本项目流程阻止归档并列出缺失项;不声称 OpenSpec CLI 自带这些业务审批门禁 + +### Requirement: GOV-04 版本漂移和移除能力可见 +SDK SHALL 为不适用、已移除、实验性或仅某认证模式支持的能力保留明确说明;目标版本改变后 SHALL 重新核对契约,不得以较新的在线文档替代目标版本事实。 + +#### Scenario: GOV-04-S1 版本升级 +- **GIVEN** 候选 Gateway 提交改变方法或事件字段 +- **WHEN** 执行兼容复核 +- **THEN** 差异进入规范与样本评审,旧证据不自动继承 + +#### Scenario: GOV-04-S2 已移除调用 +- **GIVEN** 上游版本已移除某方法 +- **WHEN** 调用该能力 +- **THEN** 返回明确的不可用结果且不尝试以更高权限或未评审替代方法绕过 + +## Sources + +[O00 OpenClaw 文档索引](https://docs.openclaw.ai/llms.txt);[O01 外部应用接入边界](https://docs.openclaw.ai/gateway/external-apps);[O02 协议版本与客户端恢复边界](https://docs.openclaw.ai/gateway/protocol/versioning);[S01 OpenSpec 概念与变更目录](https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md);[S02 OpenSpec spec-driven schema](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/establish-sdk-compatibility-governance/tasks.md b/openspec/changes/establish-sdk-compatibility-governance/tasks.md new file mode 100644 index 0000000..96a43de --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/tasks.md @@ -0,0 +1,34 @@ +# Implementation Tasks + +状态:已收集部分准入证据,治理流程待评审。 + +## 1. 评审与版本准入 + +- [ ] 1.1 评审 GOV-01 至 GOV-04 的八个场景和六组变更边界;验收:有范围、依赖、优先级、人审记录,不把文档生成记录当作批准。 +- [x] 1.2 选择可获得的 OpenClaw 精确版本/提交与构建来源;(证据:evidence/2026-09-20-precursor-evidence.md、version-lock.md)验收:形成版本锁定记录及对应协议来源,未锁定时后续实施保持阻断。 +- [x] 1.3 在独立检出目录核对三条 SDK HEAD、现有指令和代码图;(证据:evidence/2026-09-20-precursor-evidence.md §1.3)验收:记录 codegraph 版本、实际执行命令与索引/查询结果;不支持 Java 或执行失败时明确标注,并保留源码核对证据,禁止冒充代码图结果。 + +## 2. 能力证据和兼容治理 + +- [x] 2.1 为 GOV-01、GOV-04 建立机器可读的能力、版本和证据清单;(证据:evidence/2026-09-20-precursor-evidence.md、capability-inventory.json——8 项静态存在均 liveVerified=false,4 项未封装,无 live-pass 标记)验收:能区分静态存在、部分实现、CLI 透传、未封装、未验证与不适用,并演示缺失证据不能被标记为 live-pass。 +- [ ] 2.2 为 GOV-02 建立三分支协议 fixture 和获准差异清单;[共用 Gateway 测试样本](evidence/2026-11-18-live-gateway.md#三条维护线共用的-gateway-测试样本)已实测握手、认证和读取权限,完整协议范围与差异清单待评审。验收:同一行为具有共同场景标识,JSON 包名和 JDK 差异不被误判为功能分叉,行为差异不能被全局忽略。 +- [ ] 2.3 为 GOV-03 建立规范评审与归档检查步骤;验收:DRAFT、REVIEWED、IMPLEMENTED、VERIFIED 与 ARCHIVED 分开,未执行任务和缺证据场景可阻止本项目归档流程。 +- [ ] 2.4 逐项映射 traceability 中 GOV-01-S1 至 GOV-04-S2;[场景证据核对](evidence/2026-11-19-governance-scenario-audit.md)已标注各项核查与缺口。验收:八个场景均有对应检查或人工审核记录,重写 README 不得替代证据校验。 + +## 3. 基线验证与文档同步 + +- [x] 3.1 对锁定 Gateway 执行基础健康、认证成功及授权拒绝检查;验收:记录真实目标版本、认证模式及脱敏结果,现有缺陷如实登记,不以消除尚未实施功能的失败为本阶段前提。证据见 [真实 Gateway 基线验证](evidence/2026-11-18-live-gateway.md)。 +- [x] 3.2 修正文档中的版本、JDK、依赖和支持等级漂移;证据见 [维护线文档一致性](evidence/2026-11-18-live-gateway.md#维护线文档一致性)。验收:逐分支核对 pom、README、发布说明,快照版本和未验证状态一致,无声称全量支持的空泛结论。 +- [x] 3.3 记录实际 JDK/Maven/依赖来源与构建结果;(证据:evidence/2026-09-20-precursor-evidence.md §3.3)验收:每条分支都有独立结果,环境不足标为 BLOCKED,治理变更无运行资源触点时明确记录资源测试不适用原因。 +- [x] 3.4 使用已固定版本的官方 OpenSpec CLI 校验全部变更并保存输出;openspec CLI 1.8.0,`validate --all --strict --no-interactive --json`:6/6 changes valid,issues 为空(证据:evidence/2026-09-20-precursor-evidence.md §3.4)验收:validate --all --strict --no-interactive --json 成功,不用自定义结构检查冒充官方校验。 +- [ ] 3.5 评审治理变更的归档资格;验收:全部必需任务有证据、获准三分支规则已记录,只有治理规范本身可归档,后续功能提案不随之归档。 + +## 执行记录(2026-09-20) + +已由 AI 会话完成并附证据:1.2、1.3、2.1、3.3、3.4(见 evidence/ 目录)。 +当时未勾选(人审/环境门禁):1.1、2.2、2.3、2.4、3.2、3.5——原因逐条见 +evidence/2026-09-20-precursor-evidence.md「阻塞项」。G1 编码保持阻断,待人审批准。 + +## 执行记录(2026-11-18) + +锁定 Gateway 的运行验证已完成,补验了候选版本和默认分支。证据见 [G0 真实 Gateway 基线验证](evidence/2026-11-18-live-gateway.md)。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/.openspec.yaml b/openspec/changes/fix-openclaw-protocol-contracts/.openspec.yaml new file mode 100644 index 0000000..cbd245e --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-09-20 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/design.md b/openspec/changes/fix-openclaw-protocol-contracts/design.md new file mode 100644 index 0000000..11ad486 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/design.md @@ -0,0 +1,65 @@ +# 修正现有 HTTP、SSE 与 WS 协议契约 — Technical Design + +状态:DRAFT / REVIEW_REQUIRED。下述新类与模块名称为拟议设计,不是仓库已存在能力。 + +## Context + +动机与范围见 proposal.md;固定的 SDK HEAD、静态观察和证据等级见 [coverage-baseline](../../../docs/openclaw-integration/coverage-baseline.md)。当前文档基于公开协议说明和此前源码静态核查,不包含真实 Gateway 验证。在线文档随时间变化;目标版本锁定仍是实施前的阻断条件。 + +## Goals / Non-Goals + +用可观察契约约束新增或修正行为;保留三条 Java 发行线的既有基线与可行的源码兼容。只引入本变更需要的组件,不进行无关重构。SDK 不代替 Gateway 做权限裁定,也不代替宿主存储或授予长期凭据。 + +## Decisions + +保留已有 HTTP、SSE、WebSocket 与 CLI 分工。Responses 使用独立事件解码与聚合,不将 ChatChunk 直接套用;复用有界读取与取消的传输基础,不复制另一套无界线程池。 + +聊天聚合以准确运行身份与连接代际为键。追加、替换、完整快照和终态通过明确事件区分;当 runId 未知时隔离诊断。不能采用“找最后一个活动流”的宽松回退。旧监听器通过适配或新增默认方法兼容;替换无法表示为旧追加回调时应使用完整结果/新事件接口并明确迁移,不向旧接口投递会产生错误文本的伪增量。 + +HelloOk 补齐设备凭据、快照与策略,并通过宿主 CredentialStore 和签名策略处理。Java 8 不假定内置 Ed25519 提供者;保留宿主签名接口,任何可选密码学提供者应独立评审。 + +历史 DTO 保留可选字段的缺省与 null 语义。Tools Invoke 增补已核实字段,但保留兼容 dryRun 字段并明确其不是安全预演。JSON Responses 入口的 stream=true 改为发送前拒绝,是显式的行为收紧。 + +备选方案是继续宽容解析并在 README 警告,不能消除错误路由;另一方案是强制所有用户迁移新门面,会扩大破坏面。本方案采用局部修正与加法式 API。 + +## Technical Approach + +请求校验 → 正确传输入口 → 独立解码 → 身份关联/状态聚合 → 明确终态 → finally 清理 + +错误类型和状态转换由共享协议层统一;本地超时/取消与远端失败/取消分开。以下源码触点仅用于实施规划,新增路径在接入前需核对实际工作树,不把不存在的文件列为已修改: + +- `src/main/java/io/github/easy4j/openclaw/api/OpenClawResponsesClient.java` +- `src/main/java/io/github/easy4j/openclaw/api/OpenClawSseClient.java` +- `src/main/java/io/github/easy4j/openclaw/api/model/ResponseRequest.java` +- `src/main/java/io/github/easy4j/openclaw/api/model/ResponseResult.java` +- `src/main/java/io/github/easy4j/openclaw/api/sse/(新增 Responses 流事件与订阅适配)` +- `src/main/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClient.java` +- `src/main/java/io/github/easy4j/openclaw/ws/ChatStreamHandler.java` +- `src/main/java/io/github/easy4j/openclaw/ws/protocol/HelloOk.java` +- `src/main/java/io/github/easy4j/openclaw/ws/OpenClawGatewayDeviceIdentity.java` +- `src/main/java/io/github/easy4j/openclaw/OpenClawHttpClientConfig.java` +- `src/main/java/io/github/easy4j/openclaw/ws/protocol/params/ChatHistoryParams.java` +- `src/main/java/io/github/easy4j/openclaw/ws/protocol/result/ChatHistoryResult.java` +- `src/main/java/io/github/easy4j/openclaw/ws/protocol/result/SessionsListResult.java` +- `src/main/java/io/github/easy4j/openclaw/api/model/ToolInvokeRequest.java` +- `src/main/java/io/github/easy4j/openclaw/api/OpenClawToolInvokeClient.java` + +## Risks / Trade-offs + +行为收紧影响依赖旧错误行为的用户 → 记录 BREAKING 行为说明并给出迁移示例;新增字段在旧 Gateway 缺省 → 通过旧版本样本验证兼容。 + +所有新状态、上限和取消语义必须进入验收;不得使用修改测试预期、跳过不兼容分支或放宽权限来消除失败。 + +## Migration Plan + +先记录对应旧行为并建立最小失败样本,再实施局部修正或加法 API,最后同步其余分支与文档。按 capability 小批提交,避免跨无关领域的大规模替换。回滚只回退该功能变更和明确可逆状态;配置落盘、已执行工具或已投递消息的外部副作用不宣称自动撤销。根 specs 的更新留到经批准的归档阶段。 + +## Validation Strategy + +需求与场景的逐项映射见 [traceability](../../../docs/openclaw-integration/traceability.md)。每项能力须完成固定样本验证、受控模拟、适用分支构建及真实 Gateway 验收。资源测试至少覆盖成功、失败、取消、deadline、断线和用户回调异常。缺失环境的测试记录 BLOCKED,不记录 PASS。 + +## Sources + +[O02 协议版本与客户端恢复边界](https://docs.openclaw.ai/gateway/protocol/versioning);[O03 Responses HTTP 与 SSE](https://docs.openclaw.ai/gateway/openresponses-http-api);[O04 会话启动、快照及事件语义](https://docs.openclaw.ai/gateway/protocol/rpc-bootstrap-and-events);[O05 Gateway 握手与设备凭据](https://docs.openclaw.ai/gateway/protocol/handshake);[O06 会话控制与历史](https://docs.openclaw.ai/gateway/protocol/rpc-session-control);[O07 HTTP Tools Invoke 与认证语义](https://docs.openclaw.ai/gateway/tools-invoke-http-api) + +上游文档用于需求依据;本 SDK 的方法签名、状态名与组件结构属于本方案设计。每个 wire 字段和方法在实施前还须与锁定版本确认,不能凭字符串拼接猜测。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-chat-history-version-review.md b/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-chat-history-version-review.md new file mode 100644 index 0000000..6828ec5 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-chat-history-version-review.md @@ -0,0 +1,14 @@ +# 会话历史的 2026.11.5 范围评审 + +使用 OpenClaw 2026.7.1-2、2026.11.5 和 Node 24.18.0。两个 Gateway 分别使用临时工作区、状态与令牌,只监听回环地址。用 Gateway RPC 创建测试会话并写入四条合成消息,再以两条消息为一页读取。测试只使用临时会话,未启动模型推理。 [候选版本会话控制契约](https://github.com/openclaw/openclaw/blob/v2026.11.5/docs/gateway/protocol/rpc-session-control.md) + +| 场景 | 2026.7.1-2 | 2026.11.5 | +| --- | --- | --- | +| 读取最新两条 | 返回物理会话 ID、两个消息 ID 及已知空闲状态。响应无游标和 `nextOffset`。 | 同样返回两条和空闲状态,另有 `hasMore=true`、`nextOffset`、`olderCursor` 和 `deltaCursor`。 | +| 继续分页 | 提交 `cursor` 返回 `INVALID_REQUEST`。 | 使用 `olderCursor` 得到前两条且没有更旧游标。使用该页的 `newerCursor` 回到原消息 ID,末页没有更新游标。 | +| 使用 `deltaCursor` | 请求字段不受支持。 | 无变化时得到 `kind=delta` 和空消息列表。增加一条后,续读只返回新增消息。 | +| 重置临时会话,续读旧游标 | 本轮覆盖旧版对游标字段的拒绝。 | 旧游标得到 `kind=reset`。重新读取普通尾页得到一条 `system` 重置记录,原消息 ID 不再出现在尾页。 | + +三条 Java 发行线 `3dc46a0`、`9293a8c`、`34b003b` 的 `ChatHistoryParams` 已有 `offset`,缺少 `cursor`。三线的 `ChatHistoryResult` 均缺少 `kind`、续页游标及 `sessionInfo`。本轮建议保留 HIST-01 的服务端续页信息、HIST-02 的状态缺省语义和 HIST-03 的重置后重读。受过滤消息和空页影响的续页、并发刷新与迟到事件仍需独立验证。SDK 实施以及目标版本审批保持待完成。 + +用 Node 24.18.0 运行 [review-chat-history.mjs](fixtures/review-chat-history.mjs),位置参数依次为已安装的 2026.7.1-2 和 2026.11.5 包目录。脚本验证版本、启动各自 Gateway,经 WebSocket 实际执行请求并断言响应,最后清理临时状态。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-device-auth-version-review.md b/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-device-auth-version-review.md new file mode 100644 index 0000000..63c2b44 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-device-auth-version-review.md @@ -0,0 +1,26 @@ +# OpenClaw 2026.11.5 设备握手范围复评 + +G1 的 AUTH-01 仍适用于 2026.11.5。候选版在 hello-ok 中增加了认证方法等元数据,设备 Token 缺省仍是正常成功路径。SDK 需要保留 Gateway 实际返回的认证结果和权限。凭据存储、轮换以及权限变更由后续批准的契约和验证决定。 + +## 真实 Gateway + +使用两个 npm 发布版,在 Node 24.18.0 上分别启动只监听回环地址的 Gateway。每版使用独立配置、状态目录和临时 Token,关闭插件、发现、定时任务、Control UI。使用各版本自带的 GatewayClient,请求 `operator.read`。握手响应只记录字段是否存在。输入 Java 验证的样本用占位值替换凭据和连接 ID。 + +| Gateway | 无设备身份的 backend 握手 | 设备签名 CLI 握手 | `auth.method` | +| --- | --- | --- | --- | +| `2026.7.1-2` | 成功,无 `deviceToken` | 成功,有 `deviceToken` | 缺省 | +| `2026.11.5` | 成功,无 `deviceToken` | 成功,有 `deviceToken` | 均为 `token` | + +四次握手均协商协议 4,返回 `snapshot`、`role=operator` 和 `scopes=[operator.read]`。这组连接全部只涉及 operator 角色,均未出现额外 `deviceTokens`。之前带设备签名的 backend 握手在两版同样成功,均未签发设备 Token。 + +## Java SDK 基线 + +将两版各两份脱敏 hello-ok 样本输入 SDK 使用的 Jackson 映射。三个 JDK 各执行 1 项测试,覆盖四份样本,均无失败、错误或跳过。SDK 保留协议、服务端版本、角色和 scopes,映射后的 `HelloOk` 缺少 `snapshot`、`deviceToken`、`issuedAtMs` 和候选版新增的 `auth.method`。 + +| JDK | SDK 提交 | +| --- | --- | +| 8 | `3dc46a0e58200b086efc59029a43aa5c136bf61b` | +| 17 | `9293a8cd2580435ec076b076d98c7965b77f0049` | +| 21 | `34b003b5c2c2158e536d3290ef67de7932ab78ef` | + +候选版生成的 schema 还声明了可选的 `recoveryMigrationAllowed`、`recoveryScope`、`roleAllowsAdmin`、`sessionCap`。本次样本仅用于 AUTH-01 静态比较和真实握手观察。多角色 `deviceTokens`、宿主凭据保存和隔离、轮换与权限升级拒绝待真实验收。G0 版本锁定与 G1 实施范围待维护者批准。[上游协议 schema](https://github.com/openclaw/openclaw/tree/e13cf15ece9bbd969b7362927c315362c90c97ff/packages/gateway-protocol) · [版本及基础 Gateway 验证](../../establish-sdk-compatibility-governance/evidence/2026-11-18-live-gateway.md) diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-gateway-chat-isolation.md b/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-gateway-chat-isolation.md new file mode 100644 index 0000000..094cd6d --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-gateway-chat-isolation.md @@ -0,0 +1,53 @@ +# Gateway 聊天串流隔离测试(2026-11-19) + +对应 [CHAT-02-S1 并发隔离](../specs/gateway-chat-events/spec.md#scenario-chat-02-s1-并发隔离),以及 [GOV-02-S1 三条维护线的终态一致性](../../establish-sdk-compatibility-governance/specs/sdk-compatibility-governance/spec.md#scenario-gov-02-s1-依赖适配差异)。 + +实测使用官方 Gateway `2026.7.1-2` 与 `2026.11.5`。每次单独起一个 Gateway,绑定回环地址,使用独立配置、状态目录和临时凭据,关闭插件。模型后端为本机 OpenAI 兼容的确定性 SSE 样本,返回三个固定文本片段和正常终止标记。每次执行记录了 3 次本地模型请求,均为 `/v1/chat/completions`,`stream=true`。 + +| SDK 源码提交 | JDK | 锁定版串行 / 并行 | 候选版串行 / 并行 | +|---|---|---|---| +| `8cfbeb880a6c6ae5390fab0f9fe65e06938907be` | 1.8.0_504 | 通过 / 失败 | 通过 / 失败 | +| `48309d7bc34c4298cdfa1c52db06114b2e7e9f17` | 17.0.21 | 通过 / 失败 | 通过 / 失败 | +| `87c21133aba6364f64ed0edbefab2d821564ede0` | 21.0.13.0.2 | 通过 / 失败 | 通过 / 失败 | + +串行对照的 6 项全部通过。并行对照的 6 项均在最终文本断言处失败,所有执行均无跳过。每组都收到终态事件。结果限制为临时测试环境的合成输入,G1 的运行身份隔离和完整终态验收仍待实施。 + +验证命令为 `mvn -B -ntp -Dtest=GatewayStreamingLiveFixtureTest test`。Java 21 使用 4.0.0-rc-5 Wrapper,Java 8 和 17 使用系统 Maven 3.9.16。每次执行保存了独立的构建结果及模型请求计数。 + +## 候选补丁复核 + +旧实现会把未登记的运行事件送给任意活动流。候选补丁只将字符串 `runId` 精确匹配到本客户端登记的流。Gateway 在 RPC 应答里返回替代运行 ID 时仍可正常接收增量和终态。未知和缺失 ID 的帧仍能由通用事件监听器观察。 + +| 测试基线 | JDK | WebSocket 回归 | Gateway 2026.7.1-2 并发 | Gateway 2026.11.5 并发 | Maven `clean verify` | +| --- | --- | --- | --- | --- | --- | +| `3dc46a0e58200b086efc59029a43aa5c136bf61b` | 8 | 6 通过 | 旧代码失败,补丁通过 | 补丁通过 | 152 通过,3 跳过 | +| `9293a8cd2580435ec076b076d98c7965b77f0049` | 17 | 6 通过 | 旧代码失败,补丁通过 | 补丁通过 | 152 通过,3 跳过 | +| `34b003b5c2c2158e536d3290ef67de7932ab78ef` | 21 | 6 通过 | 旧代码失败,补丁通过 | 补丁通过 | 152 通过,3 跳过 | + +三条线的 WebSocket 夹具在修改生产源码前均复现 `foreignunidentifiedmodern-event`,应用补丁后均返回 `modern-event`。真实 Gateway 夹具用本地模型端点将三个请求同步到同一起点。每个 SDK 都通过通用事件监听器确认在当前流结束前有其他运行的增量,再断言自己的增量、终态文本和完成次数。两轮补丁验证均记录 3 个本地模型请求。六项真实测试全部通过,无跳过。旧代码在锁定版 Gateway 的同一夹具上把三条流的文本拼到一起。常规构建的 3 个跳过项来自需要主动启用的 `openclaw.realIntegration` 夹具。 + +### 复现 + +1. 在临时目录分别准备上表三个源码提交,命名为 `sdk-1`、`sdk-2`、`sdk-3`。应用[候选补丁](fixtures/strict-run-id-review.patch)后运行 `mvn -Dtest=OpenClawGatewayWsClientIntegrationTest test`。Java 21 使用 `./mvnw`。 +2. 运行真实联调前,将 [GatewayStreamingLiveFixtureTest.java](fixtures/GatewayStreamingLiveFixtureTest.java) 复制到三个源码树各自的 `src/test/java/io/github/easy4j/openclaw/ws/`。在临时目录按版本准备官方 npm 构建,分别放在 `locked-runtime/node_modules/openclaw` 和 `runtime/node_modules/openclaw`。macOS 启动器使用 `java_home` 选取 JDK,从同级 `m2-1`、`m2-2`、`m2-3` 的已预热 Maven 缓存离线构建。 +3. 将[启动器](fixtures/run-gateway-streaming.py)复制到同一临时目录,分别运行 `python3 run-gateway-streaming.py locked` 和 `python3 run-gateway-streaming.py candidate`。它会启动独立的回环 Gateway 和本地模型夹具,并写出三条版本线的测试日志。 + +候选补丁和测试证据供评审,SDK 分支仍指向表中的基线。该结果覆盖 CHAT-02-S1。版本确认、人审、会话代际和其他 G1 场景沿用现有验收项。 + +## CHAT-01 替换事件与最终快照 + +在上述三个 SDK 基线上,用通用事件监听器采集同一 `runId` 的原始 `chat` 事件,并核对每帧的 `sessionKey`。两个官方 Gateway 版本分别运行在回环地址,使用本地固定 SSE 模型和独立状态目录。每个版本分别发出三个模型请求,三条 Java 线共执行六项测试,零失败、零错误、零跳过。 + +| Gateway | 普通增量拼接结果 | `replace=true` 事件 | `final.message.content` 文本 | +| --- | --- | --- | --- | +| `2026.7.1-2` | `Gateway fixture ✓` | 0 次 | `Gateway fixture ✓` | +| `2026.11.5` | `Gateway fixture ✓` | 1 次,`deltaText=""` | `Gateway fixture ✓` | + +候选版在普通增量之后、最终帧之前发送空文本替换。空字符串是实际事件值,最终帧仍携带完整文本。这个序列为 CHAT-01 的替换与最终快照对账提供真实输入。非空替换、重复终态和 SDK 如何把替换通知给旧回调仍需按相应场景验收。 + +在前述临时源码树中复制 [GatewayChatSnapshotFixtureTest.java](fixtures/GatewayChatSnapshotFixtureTest.java),逐个启动 Gateway 以隔离 Maven 构建目录,重放命令如下。 + +```bash +FIXTURE_WORKERS=1 FIXTURE_TEST=GatewayChatSnapshotFixtureTest python3 run-gateway-streaming.py locked +FIXTURE_WORKERS=1 FIXTURE_TEST=GatewayChatSnapshotFixtureTest python3 run-gateway-streaming.py candidate +``` diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-responses-version-review.md b/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-responses-version-review.md new file mode 100644 index 0000000..ab1d70b --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-responses-version-review.md @@ -0,0 +1,50 @@ +# Responses 的 2026.11.5 范围评审 + +在回环地址分别启动 OpenClaw 2026.7.1-2 和 2026.11.5,启用 `/v1/responses`。Gateway 请求由本地确定性的 OpenAI Chat Completions 模型桩响应。工作区、状态与令牌均为临时测试值。使用 Node 24.18.0,禁用插件、计划任务及候选版远端模型目录刷新。 [候选版 Responses 契约](https://github.com/openclaw/openclaw/blob/v2026.11.5/docs/gateway/openresponses-http-api.md) + +| 真实 Gateway 请求 | 2026.7.1-2 | 2026.11.5 | +| --- | --- | --- | +| 正常文本 SSE | 两条文本增量,唯一终态 `response.completed`,随后 `[DONE]` | 相同 | +| 模型桩报告输出长度耗尽 | 事件名为 `response.completed`,终态资源却标记 `failed` | `response.incomplete` 与资源 `incomplete` 一致 | +| 要求客户端工具而模型只生成文本 | `response.failed`,随后 `[DONE]` | 相同 | +| JSON 请求首次设置 `store=false`,再以有效 ID 续接 | 两次均完成 | 两次均完成 | +| 同令牌、同 agent,改动 JSON 的 `user` 后继续使用有效 ID | 请求成功 | 请求成功 | +| 使用有效 ID 但切换显式会话请求头 | 本轮未测 | HTTP 400,模型桩收不到此请求 | +| JSON 与 SSE 分别使用不存在的旧 ID | 两次都返回 HTTP 200,模型桩实际收到调用 | 两次都返回 HTTP 400 `invalid_request_error`,模型桩均未被调用 | +| 使用正常文本响应的有效 ID,以合成 `call_id` 提交空字符串工具输出 | JSON 和 SSE 均在调用模型前返回 HTTP 400 | JSON 和 SSE 均只调用模型一次,终态为 `completed` | +| 模型桩只给出合成客户端工具调用 | 取得 `function_call`,仅提交空的工具输出续接会返回 HTTP 400 | 本模型桩组合得到 HTTP 500 `api_error` | +| 模型桩给出文本与工具调用,客户端使用 SSE | 两个输出项,终态事件 `response.completed` 的资源状态为 `incomplete`,保留文本、调用 ID、参数和用量。工具项在 `output_item.done` 带 `status=completed`,最终快照省略该字段 | 本模型桩组合得到 `response.failed`,错误码 `api_error` | + +候选版应让 SDK 同时保留 SSE 事件名和资源状态。旧版长度耗尽响应说明,仅看事件名会误判成功。续接拒绝时应保留 400,宿主需要显式选择是否携带完整历史重开。JSON `user` 在本次共享令牌模式中不是独立身份约束。候选实现以认证主体、agent 和显式会话请求头查找对应关系。 [候选版续接实现](https://github.com/openclaw/openclaw/blob/v2026.11.5/src/gateway/openresponses-http.ts) + +前表的空字符串对照使用正常文本响应的有效 ID 和合成调用 ID。候选版标记的上游测试也覆盖工具结果续接,其中 agent 运行结果来自 mock。 [候选版空结果续接测试](https://github.com/openclaw/openclaw/blob/v2026.11.5/src/gateway/openresponses-http.test.ts#L1454) + +现有三条 Java 发行线的 `OpenClawResponsesClient` JSON 路径将 `stream` 透传后再按 `ResponseResult` 解析。评审范围保留发送前拒绝错误入口和独立 SSE 解码。Java 的混合输出重建、空工具输出序列化、主动取消、终态前断流和流式入口仍需实施和验收。 + +运行 [review-responses.py](fixtures/review-responses.py),位置参数依次为两个已安装的 OpenClaw 包目录。脚本检查版本并在进程退出前清理模型桩和 Gateway。工具桩只返回合成协议帧,未执行实际工具。 + + +## 候选版显式工具配置 + +默认配置的候选版模型请求没有直接列出合成客户端工具。另起一个回环 Gateway,只允许 `fixture_result`,关闭工具发现,并将模型桩的上下文声明设为 262144。该配置仅用于验证客户端显式传入的合成工具。全程没有执行该工具。 + +- 首次 JSON 请求返回 `function_call`。续接请求重新提供工具声明,并使用原响应 ID、Gateway 返回的 `call_id` 和空字符串结果。真实 Gateway 只调用模型桩一次,模型输入携带相同工具 ID,SSE 以唯一的 `response.completed` 和 `[DONE]` 结束。 +- 混合 SSE 请求在两个不同的 `output_index` 结束文本和工具项,终态保留相同项、调用 ID、参数与用量。候选版的最终资源和工具项都携带 `status=completed`。 + +这两项可作为 RSP-02-S1 与 RSP-03-S1 的 Gateway 输入样本。验收仍需覆盖 Java 协议层及部署所用的工具配置。 + +## 下游断开与上游连接回收 + +模型桩在发送文本增量后保持连接,既不发送终态也不自行关闭。客户端收到首个文本增量后关闭 SSE。两版 Gateway 均在桩的 8 秒保持窗口内关闭模型连接,桩通过 TCP EOF 或连接重置确认。每版的被取消请求只进入模型桩一次。同一 JSON user 和 agent 随后的非流式请求成功完成。此处验证 Gateway 对真实断开的处理。Java SDK 主动取消、调用方收到的终态,以及无终态断流仍需实施后验证。 + +## RSP-01-S2 的 Java 基线 + +[共享回环夹具](fixtures/ResponsesJsonEntryFixtureTest.java)在三条 Java 发行线各执行一项测试,均零失败、零错误、零跳过。每项先用普通 JSON 请求确认控制组成功,再向同一个 JSON 入口传 `stream=true`。回环服务器实际收到两次 HTTP 请求,其中一次带 `stream=true`。返回 SSE 后客户端才抛出 JSON 解析异常。该结果记录了现状,并验证了请求发出前拦截的验收缺口。 + +| Java | 发行线验证提交 | +| --- | --- | +| 8 | `3dc46a0e58200b086efc59029a43aa5c136bf61b` | +| 17 | `9293a8cd2580435ec076b076d98c7965b77f0049` | +| 21 | `34b003b5c2c2158e536d3290ef67de7932ab78ef` | + +将夹具放入各提交的 `src/test/java/io/github/easy4j/openclaw/`,使用对应 JDK,运行 `mvn -B -ntp -Dtest=ResponsesJsonEntryFixtureTest test`。Java 21 使用 `./mvnw`。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-tools-invoke-version-review.md b/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-tools-invoke-version-review.md new file mode 100644 index 0000000..319bbb0 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/2026-11-19-tools-invoke-version-review.md @@ -0,0 +1,19 @@ +# Tools Invoke 的 2026.11.5 范围评审 + +用已锁定的 OpenClaw 2026.7.1-2 和候选 2026.11.5 各启动一个临时回环 Gateway。Node 版本为 24.18.0。Gateway 使用临时共享令牌、隔离配置和状态目录,禁用插件、计划任务及 mDNS。唯一执行的工具是只读 `sessions_list`,使用空测试工作区。 + +| 场景 | 2026.7.1-2 | 2026.11.5 | +| --- | --- | --- | +| 缺少令牌 | HTTP 401,`unauthorized` | 相同 | +| 错误令牌 | HTTP 401,`unauthorized` | 相同 | +| 有效共享令牌,读取会话列表 | HTTP 200,`ok=true`,有 `result` | 相同 | +| 有效令牌并声明 `operator.read`,读取会话列表 | HTTP 200,`ok=true`,有 `result` | 相同 | +| `dryRun=true` 并带固定的 `idempotencyKey`,读取会话列表 | HTTP 200,`ok=true`,有 `result` | 相同 | +| 不存在的工具名 | HTTP 404,`ok=false`,`not_found` | 相同 | +| `agentId` 与显式 `sessionKey` 不一致 | HTTP 400,`ok=false`,`invalid_request` | 相同 | + +上述两轮共 14 个实际 HTTP 交换。共享令牌的授权范围和 `dryRun` 的保留字段语义以锁定版上游契约为准。只读工具在窄请求头下成功,无法单独证明实际授予了哪些 scopes。带 `dryRun` 的请求仍返回工具结果,候选版官方文档明确该字段当前被忽略。一次带键请求仅证明请求可接受,幂等执行语义仍待独立验证。 [候选版 Tools Invoke 文档](https://github.com/openclaw/openclaw/blob/v2026.11.5/docs/gateway/tools-invoke-http-api.md) + +当前 SDK 的 Java 8 `3dc46a0`、Java 17 `9293a8c`、Java 21 `34b003b` 的 `ToolInvokeRequest` 均缺少 `agentId` 和 `idempotencyKey` 字段,`dryRun` 的 Javadoc 仍描述为仅校验。建议候选范围保留 TOOL-01 的显式关联、身份冲突及 TOOL-02 的文档修正和宿主策略。真实代理身份认证、SDK 对工具业务失败的结构化处理、生产网关及实施审批仍待后续验收。 + +复跑入口为 [review-tools-invoke.py](fixtures/review-tools-invoke.py)。给定两个已安装的 OpenClaw 包目录,依次传入 2026.7.1-2 和 2026.11.5;脚本检查包版本、启动和退出两个隔离 Gateway,并断言各场景的 HTTP 状态及响应字段。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/GatewayChatSnapshotFixtureTest.java b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/GatewayChatSnapshotFixtureTest.java new file mode 100644 index 0000000..b1b4cb2 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/GatewayChatSnapshotFixtureTest.java @@ -0,0 +1,107 @@ +package io.github.easy4j.openclaw.ws; + +import io.github.easy4j.openclaw.OpenClawHttpClientConfig; +import io.github.easy4j.openclaw.ws.protocol.ChatSendParams; +import io.github.easy4j.openclaw.ws.protocol.EventFrame; +import org.junit.jupiter.api.Test; + +import java.net.URI; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Map; +import java.util.List; +import java.util.Objects; +import java.util.UUID; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +final class GatewayChatSnapshotFixtureTest { + @Test + void recordsReplacementAndFinalSnapshotForTheRequestedRun() throws Exception { + URI endpoint = URI.create(Objects.requireNonNull(System.getenv("SDK_PROBE_URL"))); + assertEquals("ws", endpoint.getScheme()); + assertEquals("127.0.0.1", endpoint.getHost()); + + OpenClawHttpClientConfig config = new OpenClawHttpClientConfig(); + config.setBaseUrl(endpoint.toString().replaceFirst("^ws:", "http:")); + config.setGatewayAuthToken(Objects.requireNonNull(System.getenv("OPENCLAW_GATEWAY_TOKEN"))); + config.setGatewayClientId("gateway-client"); + config.setGatewayClientMode("backend"); + config.setGatewayScopes(Arrays.asList("operator.read", "operator.write")); + + CountDownLatch finalReceived = new CountDownLatch(1); + List> chatEvents = new ArrayList<>(); + String runId = "sdk-chat-snapshot-" + UUID.randomUUID(); + String sessionKey = "agent:main:" + runId; + try (OpenClawGatewayWsClient client = new OpenClawGatewayWsClient(config, endpoint)) { + client.addListener(new OpenClawWsListener() { + @Override + public void onEvent(EventFrame frame) { + if (!"chat".equals(frame.getEvent()) || finalReceived.getCount() == 0) { + return; + } + if (!(frame.getPayload() instanceof Map)) { + return; + } + Map payload = (Map) frame.getPayload(); + if (!runId.equals(payload.get("runId"))) { + return; + } + chatEvents.add(payload); + if ("final".equals(payload.get("state"))) { + finalReceived.countDown(); + } + } + }); + assertEquals(4, client.connectHandshake().getProtocol()); + client.chatSend(ChatSendParams.builder() + .sessionKey(sessionKey) + .message("Return the local fixture response.") + .idempotencyKey(runId) + .timeoutMs(30000) + .build(), new ChatStreamHandler() { + @Override public void onDelta(String text) { } + @Override public void onComplete(String text) { } + @Override public void onError(String message) { } + }); + assertTrue(finalReceived.await(45, TimeUnit.SECONDS), "Expected the selected run's final frame"); + } + + StringBuilder appendText = new StringBuilder(); + List replacements = new ArrayList<>(); + for (Map event : chatEvents) { + assertEquals(sessionKey, event.get("sessionKey")); + if ("delta".equals(event.get("state")) && event.get("deltaText") instanceof String) { + String text = (String) event.get("deltaText"); + if (Boolean.TRUE.equals(event.get("replace"))) { + replacements.add(text); + } else { + appendText.append(text); + } + } + } + Map terminal = chatEvents.get(chatEvents.size() - 1); + Map message = (Map) terminal.get("message"); + List blocks = (List) message.get("content"); + List finalText = new ArrayList<>(); + for (Object value : blocks) { + Map block = (Map) value; + if ("text".equals(block.get("type"))) { + finalText.add((String) block.get("text")); + } + } + System.out.printf("chat snapshot append=%s replacementCount=%d replacementLengths=%s finalText=%s%n", + appendText, replacements.size(), replacements.stream().map(String::length) + .collect(java.util.stream.Collectors.toList()), finalText); + assertEquals("Gateway fixture ✓", appendText.toString()); + assertEquals(Arrays.asList("Gateway fixture ✓"), finalText); + if ("candidate".equals(System.getenv("SDK_FIXTURE_VERSION"))) { + assertEquals(Arrays.asList(""), replacements); + } else { + assertTrue(replacements.isEmpty()); + } + } +} diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/GatewayStreamingLiveFixtureTest.java b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/GatewayStreamingLiveFixtureTest.java new file mode 100644 index 0000000..4b08db6 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/GatewayStreamingLiveFixtureTest.java @@ -0,0 +1,90 @@ +package io.github.easy4j.openclaw.ws; + +import io.github.easy4j.openclaw.OpenClawHttpClientConfig; +import io.github.easy4j.openclaw.ws.protocol.ChatSendParams; +import io.github.easy4j.openclaw.ws.protocol.EventFrame; +import org.junit.jupiter.api.Test; + +import java.net.URI; +import java.util.Arrays; +import java.util.Map; +import java.util.Objects; +import java.util.UUID; +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.atomic.AtomicReference; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +final class GatewayStreamingLiveFixtureTest { + @Test + void reconstructsStreamingTextAndCompletesOnce() throws Exception { + URI endpoint = URI.create(Objects.requireNonNull(System.getenv("SDK_PROBE_URL"))); + assertEquals("ws", endpoint.getScheme()); + assertEquals("127.0.0.1", endpoint.getHost()); + OpenClawHttpClientConfig config = new OpenClawHttpClientConfig(); + config.setBaseUrl(endpoint.toString().replaceFirst("^ws:", "http:")); + config.setGatewayAuthToken(Objects.requireNonNull(System.getenv("OPENCLAW_GATEWAY_TOKEN"))); + config.setGatewayClientId("gateway-client"); + config.setGatewayClientMode("backend"); + config.setGatewayScopes(Arrays.asList("operator.read", "operator.write")); + + CountDownLatch terminal = new CountDownLatch(1); + StringBuffer deltas = new StringBuffer(); + AtomicInteger fragments = new AtomicInteger(); + AtomicInteger foreignDeltasBeforeTerminal = new AtomicInteger(); + AtomicInteger completions = new AtomicInteger(); + AtomicReference finalText = new AtomicReference<>(); + AtomicReference error = new AtomicReference<>(); + String turn = "sdk-stream-fixture-" + UUID.randomUUID(); + try (OpenClawGatewayWsClient client = new OpenClawGatewayWsClient(config, endpoint)) { + client.addListener(new OpenClawWsListener() { + @Override + public void onEvent(EventFrame frame) { + if ("chat".equals(frame.getEvent()) && frame.getPayload() instanceof Map) { + Map payload = (Map) frame.getPayload(); + if ("delta".equals(payload.get("state"))) { + if (!turn.equals(payload.get("runId")) && terminal.getCount() > 0) { + foreignDeltasBeforeTerminal.incrementAndGet(); + } + } + } + } + }); + assertEquals(4, client.connectHandshake().getProtocol()); + client.chatSend(ChatSendParams.builder() + .sessionKey("agent:main:" + turn) + .message("Return the local fixture response.") + .idempotencyKey(turn) + .timeoutMs(30000) + .build(), new ChatStreamHandler() { + @Override public void onDelta(String text) { + deltas.append(text); + fragments.incrementAndGet(); + } + + @Override public void onComplete(String text) { + finalText.set(text); + completions.incrementAndGet(); + terminal.countDown(); + } + + @Override public void onError(String message) { + error.set(message); + terminal.countDown(); + } + }); + + assertTrue(terminal.await(45, TimeUnit.SECONDS), "Gateway chat did not reach a terminal state"); + assertNull(error.get(), error.get()); + assertEquals("Gateway fixture ✓", finalText.get()); + assertEquals("Gateway fixture ✓", deltas.toString()); + assertTrue(fragments.get() >= 1); + assertTrue(foreignDeltasBeforeTerminal.get() > 0, "Expected an overlapping foreign run"); + assertEquals(1, completions.get()); + } + } +} diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/ResponsesJsonEntryFixtureTest.java b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/ResponsesJsonEntryFixtureTest.java new file mode 100644 index 0000000..ec51962 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/ResponsesJsonEntryFixtureTest.java @@ -0,0 +1,64 @@ +package io.github.easy4j.openclaw; + +import com.sun.net.httpserver.HttpServer; +import io.github.easy4j.openclaw.api.OpenClawResponsesClient; +import io.github.easy4j.openclaw.api.model.ResponseRequest; +import io.github.easy4j.openclaw.exception.OpenClawHttpException; +import org.junit.jupiter.api.Test; + +import java.io.IOException; +import java.io.OutputStream; +import java.net.InetSocketAddress; +import java.nio.charset.StandardCharsets; +import java.util.Scanner; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +class ResponsesJsonEntryFixtureTest { + + @Test + void existingJsonEntrySendsStreamRequestAndAttemptsJsonParsing() throws IOException { + AtomicInteger requests = new AtomicInteger(); + AtomicInteger streamRequests = new AtomicInteger(); + HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0); + server.createContext("/v1/responses", exchange -> { + try (Scanner body = new Scanner(exchange.getRequestBody(), "UTF-8")) { + requests.incrementAndGet(); + String json = body.useDelimiter("\\A").next(); + boolean stream = json.contains("\"stream\":true"); + if (stream) { + streamRequests.incrementAndGet(); + } + String payload = stream + ? "event: response.completed\ndata: {\"type\":\"response.completed\"," + + "\"response\":{\"id\":\"resp_fixture\",\"status\":\"completed\"}}\n\ndata: [DONE]\n\n" + : "{\"id\":\"resp_fixture\",\"status\":\"completed\",\"output\":[]}"; + byte[] bytes = payload.getBytes(StandardCharsets.UTF_8); + exchange.getResponseHeaders().set("Content-Type", stream ? "text/event-stream" : "application/json"); + exchange.sendResponseHeaders(200, bytes.length); + try (OutputStream output = exchange.getResponseBody()) { + output.write(bytes); + } + } finally { + exchange.close(); + } + }); + server.start(); + OpenClawHttpClientConfig config = new OpenClawHttpClientConfig(); + config.setBaseUrl("http://127.0.0.1:" + server.getAddress().getPort()); + try (OpenClawResponsesClient client = new OpenClawResponsesClient(config)) { + assertEquals("resp_fixture", client.createResponse( + ResponseRequest.builder().model("openclaw").input("fixture").build()).getId()); + OpenClawHttpException failure = assertThrows(OpenClawHttpException.class, () -> client.createResponse( + ResponseRequest.builder().model("openclaw").input("fixture").stream(true).build())); + assertTrue(failure.getMessage().contains("parse"), failure.getMessage()); + assertEquals(2, requests.get()); + assertEquals(1, streamRequests.get()); + } finally { + server.stop(0); + } + } +} diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/review-chat-history.mjs b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/review-chat-history.mjs new file mode 100644 index 0000000..2e9dc8d --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/review-chat-history.mjs @@ -0,0 +1,174 @@ +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import { randomBytes } from 'node:crypto'; +import { once } from 'node:events'; +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import net from 'node:net'; +import { tmpdir } from 'node:os'; +import path from 'node:path'; +import { setTimeout as delay } from 'node:timers/promises'; + +const sessionKey = 'agent:main:history-review'; +const scopes = ['operator.read', 'operator.write', 'operator.admin']; + +async function probe(base, token, version) { + const socket = new WebSocket(base.replace('http:', 'ws:')); + let challenge; + const challengeReady = new Promise(resolve => { challenge = resolve; }); + const pending = new Map(); + let id = 0; + socket.addEventListener('message', event => { + const frame = JSON.parse(event.data); + if (frame.event === 'connect.challenge') challenge(); + if (frame.type === 'res') pending.get(frame.id)?.(frame); + }); + function rpc(method, params) { + return new Promise((resolve, reject) => { + const key = String(++id); + const timeout = setTimeout(() => { + pending.delete(key); + reject(new Error('RPC timeout: ' + method)); + }, 8000); + pending.set(key, frame => { + clearTimeout(timeout); + pending.delete(key); + resolve(frame); + }); + socket.send(JSON.stringify({ type: 'req', id: key, method, params })); + }); + } + async function ok(method, params) { + const response = await rpc(method, params); + assert.equal(response.ok, true, method + ': ' + JSON.stringify(response.error)); + return response.payload; + } + try { + await Promise.race([challengeReady, delay(8000, null, { ref: false }).then(() => { throw new Error('challenge timeout'); })]); + await ok('connect', { + minProtocol: 4, maxProtocol: 4, + client: { id: 'gateway-client', mode: 'backend', version: 'history-review', platform: 'node' }, + role: 'operator', scopes, auth: { token }, + }); + const created = await ok('sessions.create', { key: sessionKey }); + assert.equal(created.runStarted, false); + for (let n = 1; n <= 4; ++n) { + await ok('chat.inject', { sessionKey, message: 'history-review-' + n }); + } + const tail = await ok('chat.history', { sessionKey, limit: 2 }); + const ids = result => result.messages.map(message => { + const id = message.__openclaw?.id ?? message.messageId ?? message.id; + assert.equal(typeof id, 'string', 'message identity is missing'); + return id; + }); + const tailIds = ids(tail); + assert.equal(tail.sessionId, created.sessionId); + assert.equal(tailIds.length, 2); + assert.equal(tail.sessionInfo.hasActiveRun, false); + assert.deepEqual(tail.sessionInfo.activeRunIds, []); + if (version === '2026.7.1-2') { + for (const key of ['olderCursor', 'newerCursor', 'deltaCursor', 'nextOffset']) { + assert.equal(Object.hasOwn(tail, key), false, key + ' must be absent on the locked release'); + } + const cursor = await rpc('chat.history', { sessionKey, cursor: 'history-fixture-cursor' }); + assert.equal(cursor.ok, false); + assert.equal(cursor.error.code, 'INVALID_REQUEST'); + console.log(version, 'tail and idle state available; cursor absent and cursor input rejected'); + return; + } + assert.equal(tail.hasMore, true); + assert.equal(typeof tail.olderCursor, 'string'); + assert.equal(typeof tail.deltaCursor, 'string'); + assert.equal(typeof tail.nextOffset, 'number'); + const older = await ok('chat.history', { sessionKey, cursor: tail.olderCursor, limit: 2 }); + const olderIds = ids(older); + assert.equal(olderIds.length, 2); + assert.equal(older.sessionId, tail.sessionId); + assert.equal(new Set([...tailIds, ...olderIds]).size, 4); + assert.equal(Object.hasOwn(older, 'olderCursor'), false); + assert.equal(typeof older.newerCursor, 'string'); + const newer = await ok('chat.history', { sessionKey, cursor: older.newerCursor, limit: 2 }); + assert.deepEqual(ids(newer), tailIds); + assert.equal(Object.hasOwn(newer, 'newerCursor'), false); + + const unchanged = await ok('chat.history', { sessionKey, cursor: tail.deltaCursor }); + assert.equal(unchanged.kind, 'delta'); + assert.deepEqual(unchanged.messages, []); + assert.equal(unchanged.sessionInfo.sessionId, tail.sessionId); + assert.equal(typeof unchanged.deltaCursor, 'string'); + + await ok('chat.inject', { sessionKey, message: 'history-review-5' }); + const delta = await ok('chat.history', { sessionKey, cursor: unchanged.deltaCursor }); + assert.equal(delta.kind, 'delta'); + const deltaIds = ids(delta); + assert.equal(deltaIds.length, 1); + assert.equal(new Set([...tailIds, ...olderIds, ...deltaIds]).size, 5); + assert.equal(typeof delta.deltaCursor, 'string'); + + await ok('sessions.reset', { key: sessionKey }); + const stale = await ok('chat.history', { sessionKey, cursor: delta.deltaCursor }); + assert.equal(stale.kind, 'reset'); + assert.equal(Object.hasOwn(stale, 'messages'), false); + const fresh = await ok('chat.history', { sessionKey, limit: 2 }); + assert.equal(fresh.messages.length, 1); + assert.equal(fresh.messages[0].role, 'system'); + assert.equal(fresh.messages[0].__openclaw.kind, 'reset'); + assert.equal(new Set([...tailIds, ...olderIds, ...deltaIds, ...ids(fresh)]).size, 6); + console.log(version, 'directional pages, empty and one-message deltas, and reset verified'); + } finally { + socket.close(); + } +} + +async function release(runtime, version) { + const { version: actual } = JSON.parse(await readFile(path.join(runtime, 'package.json'))); + assert.equal(actual, version); + const work = await mkdtemp(path.join(tmpdir(), 'openclaw-history-review-')); + const reserved = net.createServer(); + reserved.listen(0, '127.0.0.1'); + await once(reserved, 'listening'); + const port = reserved.address().port; + reserved.close(); + await once(reserved, 'close'); + const base = 'http://127.0.0.1:' + port; + const config = path.join(work, 'gateway.json'); + const token = randomBytes(24).toString('hex'); + await writeFile(config, JSON.stringify({ + gateway: { mode: 'local', bind: 'loopback', port, auth: { mode: 'token', allowTailscale: false }, + controlUi: { enabled: false } }, + agents: { defaults: { workspace: path.join(work, 'workspace'), skipBootstrap: true } }, + discovery: { mdns: { mode: 'off' } }, cron: { enabled: false }, plugins: { enabled: false }, + })); + const child = spawn(process.execPath, [path.join(runtime, 'openclaw.mjs'), 'gateway', 'run'], { + cwd: work, + env: { PATH: process.env.PATH, OPENCLAW_HOME: work, OPENCLAW_CONFIG_PATH: config, + OPENCLAW_STATE_DIR: path.join(work, 'state'), OPENCLAW_GATEWAY_TOKEN: token, OPENCLAW_DISABLE_BONJOUR: '1' }, + stdio: ['ignore', 'ignore', 'ignore'], + }); + try { + for (let attempt = 0; attempt < 100; ++attempt) { + assert.equal(child.exitCode, null, 'Gateway exited before readiness'); + const ready = await fetch(base + '/readyz', { signal: AbortSignal.timeout(1000) }).catch(() => null); + if (ready?.ok) { + await ready.body.cancel(); + await probe(base, token, version); + return; + } + await delay(250); + } + throw new Error('Gateway did not become ready'); + } finally { + if (child.exitCode === null && child.signalCode === null) { + const stopped = once(child, 'exit'); + child.kill(); + await stopped; + } + await rm(work, { recursive: true }); + } +} + +if (process.argv.length !== 4) { + throw new Error('usage: node review-history.mjs LOCKED_PACKAGE_DIR CANDIDATE_PACKAGE_DIR'); +} +for (let index = 0; index < 2; ++index) { + await release(path.resolve(process.argv[index + 2]), ['2026.7.1-2', '2026.11.5'][index]); +} diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/review-responses.py b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/review-responses.py new file mode 100644 index 0000000..1d024c9 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/review-responses.py @@ -0,0 +1,323 @@ +"""Observe Responses HTTP and SSE behavior through a disposable real Gateway.""" +import json +import os +import secrets +import select +import socket +import subprocess +import sys +import tempfile +import threading +import time +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path +from urllib.error import HTTPError +from urllib.request import ProxyHandler, Request, build_opener + +OPENER = build_opener(ProxyHandler({})) +TOOLS = [{"type": "function", "name": "fixture_result", "parameters": {"type": "object", "properties": {}}}] + + +class Provider(BaseHTTPRequestHandler): + def log_message(self, *_args): + pass + + def do_POST(self): + body = json.loads(self.rfile.read(int(self.headers["Content-Length"]))) + if self.path != "/v1/chat/completions" or body.get("model") != "local-fixture" or not body.get("stream"): + self.send_error(400) + return + mode = self.server.mode + self.server.requests += 1 + self.server.last_model_messages = body["messages"] + self.send_response(200) + self.send_header("Content-Type", "text/event-stream") + self.end_headers() + + def emit(delta, reason=None): + out = {"id": "fixture", "object": "chat.completion.chunk", "created": 1, + "model": "local-fixture", "choices": [{"index": 0, "delta": delta, "finish_reason": reason}]} + self.wfile.write(("data: " + json.dumps(out) + "\n\n").encode()) + self.wfile.flush() + + emit({"role": "assistant"}) + if mode in ("tool", "mixed"): + if mode == "mixed": + emit({"content": "Mixed fixture"}) + emit({"tool_calls": [{"index": 0, "id": "call_fixture", "type": "function", + "function": {"name": "fixture_result", "arguments": "{}"}}]}) + emit({}, "tool_calls") + else: + emit({"content": "Gateway "}) + time.sleep(0.1) + emit({"content": "fixture"}) + if mode == "hold": + deadline = time.monotonic() + 8 + while time.monotonic() < deadline and not self.server.finished_hold.is_set(): + readable, _, _ = select.select([self.connection], [], [], 0.2) + if readable: + try: + if self.connection.recv(1, socket.MSG_PEEK): + continue + except ConnectionResetError: + pass + self.server.cancelled_connection.set() + return + emit({}, "length" if mode == "length" else "stop") + usage = {"id": "fixture", "object": "chat.completion.chunk", "created": 1, "model": "local-fixture", + "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 2, "total_tokens": 10}} + self.wfile.write(("data: " + json.dumps(usage) + "\n\ndata: [DONE]\n\n").encode()) + self.wfile.flush() + + +def open_request(base, token, user, mode, provider, session_header=None, **parameters): + provider.mode = mode + body = {"model": "openclaw", "user": user, **parameters} + headers = {"Authorization": "Bearer " + token, "Content-Type": "application/json"} + if session_header is not None: + headers["x-openclaw-session-key"] = session_header + req = Request(base + "/v1/responses", json.dumps(body).encode(), headers) + try: + return OPENER.open(req, timeout=25) + except HTTPError as error: + return error + + +def request(*args, **kwargs): + with open_request(*args, **kwargs) as response: + if response.headers.get_content_type() != "text/event-stream": + return response.status, json.load(response) + frames = [] + event = None + for raw in response: + line = raw.decode().rstrip("\r\n") + if line.startswith("event: "): + event = line[7:] + if line.startswith("data: "): + data = line[6:] + frames.append(("done", None) if data == "[DONE]" else (event, json.loads(data))) + return response.status, frames + + +def probe(base, token, provider, candidate): + modes = ( + ("normal", {}, "response.completed", "completed", ["Gateway", " fixture"]), + ("length", {}, "response.incomplete" if candidate else "response.completed", + "incomplete" if candidate else "failed", ["Gateway", " fixture"]), + ("no-required-tool", {"tools": TOOLS, "tool_choice": "required"}, "response.failed", "failed", []), + ) + for mode, parameters, event, state, text in modes: + code, frames = request(base, token, mode, mode, provider, input="fixture", stream=True, **parameters) + assert code == 200 and isinstance(frames, list), (mode, code, frames) + terminal = [(name, (data or {}).get("response", {}).get("status")) + for name, data in frames if name in ("response.completed", "response.failed", + "response.incomplete", "done")] + assert terminal == [(event, state), ("done", None)], (mode, terminal) + assert [data.get("delta") for name, data in frames if name == "response.output_text.delta"] == text + print(mode, event, state, flush=True) + + code, first = request(base, token, "continuation", "normal", provider, input="first", store=False) + assert code == 200 and first["status"] == "completed" + response_id = first["id"] + code, second = request(base, token, "continuation", "normal", provider, + input="continue", previous_response_id=response_id) + assert code == 200 and second["status"] == "completed" + + code, changed_user = request(base, token, "other-user", "normal", provider, + input="continue", previous_response_id=response_id) + assert code == 200 and changed_user["status"] == "completed" + if candidate: + before = provider.requests + code, scoped = request(base, token, "continuation", "normal", provider, + session_header="agent:main:fixture-other", input="continue", + previous_response_id=response_id) + assert code == 400 and scoped["error"]["type"] == "invalid_request_error" + assert provider.requests == before + print("explicit session mismatch rejected before model", flush=True) + print("valid continuation and changed JSON user both accepted", flush=True) + + for stream in (False, True): + before = provider.requests + code, unknown = request(base, token, "unknown-" + str(stream), "normal", provider, + previous_response_id="resp_fixture_missing", input="fixture", stream=stream) + if candidate: + assert code == 400 and unknown["error"]["type"] == "invalid_request_error" + assert provider.requests == before + else: + assert code == 200 and provider.requests > before + print("unknown continuation", "SSE" if stream else "JSON", code, flush=True) + + empty_result = [{"type": "function_call_output", "call_id": "call_fixture", "output": ""}] + for stream in (False, True): + before = provider.requests + status, result = request(base, token, "continuation", "normal", provider, + previous_response_id=response_id, input=empty_result, stream=stream) + if candidate: + assert status == 200 and provider.requests == before + 1 + if stream: + assert [(name, payload["response"]["status"]) for name, payload in result + if name in ("response.completed", "response.incomplete", "response.failed")] == [ + ("response.completed", "completed")] + assert result[-1] == ("done", None) + else: + assert result["status"] == "completed" + else: + assert status == 400 and result["error"]["message"] == "Missing user message in `input`." + assert provider.requests == before + print("synthetic empty tool result", "SSE" if stream else "JSON", status, flush=True) + + code, tool = request(base, token, "tool", "tool", provider, input="fixture", tools=TOOLS) + if candidate: + assert code == 500 and tool["status"] == "failed" and tool["error"]["code"] == "api_error" + print("candidate could not generate a tool call from this model fixture", flush=True) + else: + assert code == 200 and tool["status"] == "incomplete" + call, = [item for item in tool["output"] if item.get("type") == "function_call"] + code, continuation = request(base, token, "tool", "normal", provider, previous_response_id=tool["id"], + input=[{"type": "function_call_output", "call_id": call["call_id"], "output": ""}]) + assert code == 400 and continuation["error"]["type"] == "invalid_request_error" + print("locked release returned a tool call and rejected empty tool output", flush=True) + + verify_mixed_tool_stream(base, token, provider, candidate) + + +def verify_mixed_tool_stream(base, token, provider, candidate, inline_tools=False): + status, frames = request(base, token, "mixed", "mixed", provider, input="fixture", tools=TOOLS, stream=True) + assert status == 200 and frames[-1] == ("done", None) + terminal, = [(name, data["response"]) for name, data in frames + if name in ("response.completed", "response.incomplete", "response.failed")] + event, response = terminal + if candidate and not inline_tools: + assert (event, response["status"]) == ("response.failed", "failed") + assert response["error"]["code"] == "api_error" + else: + assert (event, response["status"]) == ("response.completed", "completed" if candidate else "incomplete") + text, call = response["output"] + assert text["content"][0]["text"] == "Mixed fixture" + assert call["type"] == "function_call" and call["name"] == "fixture_result" + assert call["call_id"] and json.loads(call["arguments"]) == {} + assert response["usage"]["total_tokens"] == 10 + items = [(data["output_index"], data["item"]) for name, data in frames + if name == "response.output_item.done"] + assert items == [(0, text), (1, {**call, "status": "completed"})] + print("mixed text and tool", event, response["status"], flush=True) + + +def verify_inline_tool_continuation(base, token, provider): + status, first = request(base, token, "inline-tool", "tool", provider, input="fixture", tools=TOOLS) + assert status == 200 and first["status"] == "completed" + call, = first["output"] + assert call["type"] == "function_call" and call["name"] == "fixture_result" and call["call_id"] + before = provider.requests + status, frames = request(base, token, "inline-tool", "normal", provider, previous_response_id=first["id"], + input=[{"type": "function_call_output", "call_id": call["call_id"], "output": ""}], + tools=TOOLS, stream=True) + assert status == 200 and provider.requests == before + 1 and frames[-1] == ("done", None) + terminal, = [(name, data["response"]) for name, data in frames + if name in ("response.completed", "response.incomplete", "response.failed")] + event, response = terminal + assert (event, response["status"]) == ("response.completed", "completed") + assert response["output"][0]["content"][0]["text"] == "Gateway fixture" + assert f'Tool:{call["call_id"]}:' in json.dumps(provider.last_model_messages) + print("returned call ID accepted with empty output in SSE continuation", flush=True) + verify_mixed_tool_stream(base, token, provider, candidate=True, inline_tools=True) + + +def verify_disconnect(base, token, provider): + provider.cancelled_connection = threading.Event() + provider.finished_hold = threading.Event() + before = provider.requests + try: + with open_request(base, token, "cancel-probe", "hold", provider, input="fixture", stream=True) as response: + assert response.status == 200 + assert response.headers.get_content_type() == "text/event-stream" + for raw in response: + if raw.startswith(b"event: response.output_text.delta"): + break + else: + raise AssertionError("expected a text delta before disconnect") + started = time.monotonic() + assert provider.cancelled_connection.wait(timeout=9), "provider socket remained open after disconnect" + print(f"downstream disconnect closed provider socket in {time.monotonic() - started:.3f}s", flush=True) + finally: + provider.finished_hold.set() + assert provider.requests == before + 1 + status, next_turn = request(base, token, "cancel-probe", "normal", provider, input="after disconnect") + assert status == 200 and next_turn["status"] == "completed" + print("same session accepted another turn", flush=True) + + +def release(runtime, version, inline_tools=False): + assert json.loads((runtime / "package.json").read_bytes())["version"] == version + with tempfile.TemporaryDirectory(prefix="openclaw-responses-review-") as tmp, \ + ThreadingHTTPServer(("127.0.0.1", 0), Provider) as provider: + state = Path(tmp) + provider.mode = "normal" + provider.requests = 0 + server_thread = threading.Thread(target=provider.serve_forever, daemon=True) + server_thread.start() + token = secrets.token_hex(24) + with socket.socket() as reserved: + reserved.bind(("127.0.0.1", 0)) + port = reserved.getsockname()[1] + base = f"http://127.0.0.1:{port}" + candidate = version == "2026.11.5" + catalog = {"catalogRefresh": {"enabled": False}} if candidate else {} + config = state / "gateway.json" + tool_policy = {"tools": {"allow": ["fixture_result"], "toolSearch": False}} if inline_tools else {} + config.write_text(json.dumps({ + **tool_policy, + "gateway": {"mode": "local", "bind": "loopback", "port": port, + "auth": {"mode": "token", "allowTailscale": False}, + "http": {"endpoints": {"responses": {"enabled": True}}}, + "controlUi": {"enabled": False}}, + "agents": {"defaults": {"workspace": str(state / "workspace"), "skipBootstrap": True, + "model": {"primary": "localprobe/local-fixture", "fallbacks": []}}}, + "models": {"mode": "replace", **catalog, "providers": { + "localprobe": {"baseUrl": f"http://127.0.0.1:{provider.server_port}/v1", + "apiKey": "local-fixture-key", "api": "openai-completions", + "models": [{"id": "local-fixture", "name": "Local fixture", "reasoning": False, + "input": ["text"], "contextWindow": 262144 if inline_tools else 32768, + "maxTokens": 1024}]}}}, + "discovery": {"mdns": {"mode": "off"}}, "cron": {"enabled": False}, "plugins": {"enabled": False}, + })) + env = {"PATH": os.environ["PATH"], "OPENCLAW_HOME": tmp, "OPENCLAW_CONFIG_PATH": str(config), + "OPENCLAW_STATE_DIR": str(state / "state"), "OPENCLAW_GATEWAY_TOKEN": token, + "OPENCLAW_DISABLE_BONJOUR": "1", "OPENCLAW_NO_AUTO_UPDATE": "1"} + log_path = state / "gateway.log" + with log_path.open("w") as log: + child = subprocess.Popen(["node", str(runtime / "openclaw.mjs"), "gateway", "run"], + cwd=state, env=env, stdout=log, stderr=log) + try: + for _ in range(100): + if child.poll() is not None: + raise RuntimeError("Gateway exited: " + log_path.read_text()[-1500:]) + try: + with OPENER.open(base + "/readyz", timeout=1): + break + except OSError: + time.sleep(0.25) + else: + raise RuntimeError("Gateway did not start") + print(version, flush=True) + if inline_tools: + verify_inline_tool_continuation(base, token, provider) + else: + probe(base, token, provider, candidate) + verify_disconnect(base, token, provider) + finally: + child.terminate() + try: + child.wait(timeout=10) + except subprocess.TimeoutExpired: + child.kill() + child.wait() + provider.shutdown() + + +if __name__ == "__main__": + if len(sys.argv) != 3: + raise SystemExit("usage: review-responses.py LOCKED_PACKAGE_DIR CANDIDATE_PACKAGE_DIR") + for directory, version in zip(sys.argv[1:], ("2026.7.1-2", "2026.11.5"), strict=True): + release(Path(directory).resolve(), version) + release(Path(sys.argv[2]).resolve(), "2026.11.5", inline_tools=True) diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/review-tools-invoke.py b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/review-tools-invoke.py new file mode 100644 index 0000000..7c950a8 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/review-tools-invoke.py @@ -0,0 +1,118 @@ +"""Compare the two locked OpenClaw releases on disposable loopback Gateways.""" +import json +import os +import secrets +import socket +import subprocess +import sys +import tempfile +import time +from pathlib import Path +from urllib.error import HTTPError +from urllib.request import ProxyHandler, Request, build_opener + +SAFE_REQUEST = {"tool": "sessions_list", "args": {"limit": 1}, "sessionKey": "main"} +URL_OPENER = build_opener(ProxyHandler({})) + + +def request(base, body, token=None, scopes=None): + headers = {"Content-Type": "application/json"} + if token is not None: + headers["Authorization"] = "Bearer " + token + if scopes is not None: + headers["x-openclaw-scopes"] = scopes + call = Request(base + "/tools/invoke", json.dumps(body).encode(), headers) + try: + with URL_OPENER.open(call, timeout=8) as response: + return response.status, json.load(response) + except HTTPError as failure: + with failure: + return failure.code, json.load(failure) + + +def release(runtime, version): + assert json.loads((runtime / "package.json").read_bytes())["version"] == version + with tempfile.TemporaryDirectory(prefix="openclaw-tools-review-") as tmp: + state = Path(tmp) + token = secrets.token_hex(24) + with socket.socket() as selected: + selected.bind(("127.0.0.1", 0)) + port = selected.getsockname()[1] + base = f"http://127.0.0.1:{port}" + config = state / "config.json" + config.write_text(json.dumps({ + "gateway": {"mode": "local", "bind": "loopback", "port": port, + "auth": {"mode": "token", "allowTailscale": False}, + "controlUi": {"enabled": False}}, + "agents": {"defaults": {"workspace": str(state / "workspace"), "skipBootstrap": True}}, + "discovery": {"mdns": {"mode": "off"}}, + "cron": {"enabled": False}, "plugins": {"enabled": False}, + })) + env = { + "PATH": os.environ["PATH"], "OPENCLAW_HOME": tmp, + "OPENCLAW_CONFIG_PATH": str(config), "OPENCLAW_STATE_DIR": str(state / "state"), + "OPENCLAW_GATEWAY_TOKEN": token, "OPENCLAW_DISABLE_BONJOUR": "1", + } + log_path = state / "gateway.log" + with log_path.open("w") as log: + process = subprocess.Popen(["node", str(runtime / "openclaw.mjs"), "gateway", "run"], + cwd=state, env=env, stdout=log, stderr=log) + try: + for _ in range(100): + if process.poll() is not None: + raise RuntimeError("Gateway exited: " + log_path.read_text()[-2000:]) + try: + with URL_OPENER.open(base + "/readyz", timeout=1): + break + except OSError: + time.sleep(0.25) + else: + raise RuntimeError("Gateway did not start") + results = {} + for label, payload, bearer, scopes in ( + ("absent-token", SAFE_REQUEST, None, None), + ("incorrect-token", SAFE_REQUEST, "fixture-invalid", None), + ("shared-token", SAFE_REQUEST, token, None), + ("read-header", SAFE_REQUEST, token, "operator.read"), + ("dry-run", {**SAFE_REQUEST, "dryRun": True, "idempotencyKey": "fixture-v1"}, token, None), + ("missing-tool", {**SAFE_REQUEST, "tool": "scope_review_missing_tool"}, token, None), + ("mismatched-agent", {**SAFE_REQUEST, "sessionKey": "agent:main:main", + "agentId": "fixture-other"}, token, None)): + code, body = request(base, payload, bearer, scopes) + error = body.get("error") + results[label] = {"status": code, "ok": body.get("ok"), + "errorType": error.get("type") if isinstance(error, dict) else None, + "hasResult": "result" in body} + return results + finally: + process.terminate() + try: + process.wait(timeout=10) + except subprocess.TimeoutExpired: + process.kill() + process.wait() + + +def main(): + if len(sys.argv) != 3: + raise SystemExit("usage: review-tools-invoke.py LOCKED_PACKAGE_DIR CANDIDATE_PACKAGE_DIR") + expected = { + "absent-token": (401, None, "unauthorized", False), + "incorrect-token": (401, None, "unauthorized", False), + "shared-token": (200, True, None, True), + "read-header": (200, True, None, True), + "dry-run": (200, True, None, True), + "missing-tool": (404, False, "not_found", False), + "mismatched-agent": (400, False, "invalid_request", False), + } + for path, version in zip(sys.argv[1:], ("2026.7.1-2", "2026.11.5"), strict=True): + actual = release(Path(path).resolve(), version) + for label, result in actual.items(): + observed = tuple(result[key] for key in ("status", "ok", "errorType", "hasResult")) + if observed != expected[label]: + raise AssertionError(f"{version} {label}: expected {expected[label]}, observed {observed}") + print(version, json.dumps(actual, sort_keys=True), flush=True) + + +if __name__ == "__main__": + main() diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/run-gateway-streaming.py b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/run-gateway-streaming.py new file mode 100644 index 0000000..19c8168 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/run-gateway-streaming.py @@ -0,0 +1,131 @@ +import concurrent.futures +import re +import json +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +import threading +import os +from pathlib import Path +import secrets +import signal +import socket +import subprocess +import time +from urllib.request import urlopen + +root = Path(__file__).resolve().parent + +class LocalModel(BaseHTTPRequestHandler): + def log_message(self, format, *args): + pass + + def do_POST(self): + payload = json.loads(self.rfile.read(int(self.headers["Content-Length"]))) + with (root / (prefix + "provider.log")).open("a") as report: + report.write(json.dumps({"path": self.path, "model": payload.get("model"), + "stream": payload.get("stream")}) + "\n") + if self.path != "/v1/chat/completions" or payload.get("model") != "local-fixture" or not payload.get("stream"): + self.send_error(400) + return + streams_started.wait(timeout=25) + self.send_response(200) + self.send_header("Content-Type", "text/event-stream; charset=utf-8") + self.end_headers() + def chunk(delta, finish=None): + message = {"id": "local-run", "object": "chat.completion.chunk", "created": 1, + "model": "local-fixture", "choices": [{"index": 0, "delta": delta, "finish_reason": finish}]} + self.wfile.write(("data: " + json.dumps(message, ensure_ascii=False) + "\n\n").encode()) + self.wfile.flush() + chunk({"role": "assistant"}) + for content in ("Gateway ", "fixture ", "✓"): + chunk({"content": content}) + time.sleep(0.25) + chunk({}, "stop") + self.wfile.write(b"data: [DONE]\n\n") + self.wfile.flush() + +provider = ThreadingHTTPServer(("127.0.0.1", 0), LocalModel) +threading.Thread(target=provider.serve_forever, daemon=True).start() +version = os.sys.argv[1] +workers = int(os.environ.get("FIXTURE_WORKERS", "3")) +streams_started = threading.Barrier(workers) +fixture = os.environ.get("FIXTURE_TEST", "GatewayStreamingLiveFixtureTest") +fixture_labels = { + "GatewayStreamingLiveFixtureTest": "provenance", + "GatewayChatSnapshotFixtureTest": "snapshot-wire", +} +prefix = f"chat-{fixture_labels[fixture]}-{workers}-{version}-" +runtime = root / (("locked-" if version == "locked" else "") + "runtime/node_modules/openclaw") +token = secrets.token_hex(24) +with socket.socket() as reservation: + reservation.bind(("127.0.0.1", 0)) + port = reservation.getsockname()[1] +http = f"http://127.0.0.1:{port}" +config = root / (prefix + "gateway.json") +config.write_text(json.dumps({ + "gateway": {"mode": "local", "bind": "loopback", "port": port, + "auth": {"mode": "token", "allowTailscale": False}, "controlUi": {"enabled": False}}, + "agents": {"defaults": {"workspace": str(root / (prefix + "workspace")), "skipBootstrap": True, + "model": {"primary": "localprobe/local-fixture", "fallbacks": []}}}, + "models": {"mode": "replace", "providers": { + "localprobe": {"baseUrl": f"http://127.0.0.1:{provider.server_port}/v1", + "apiKey": "local-fixture-key", "api": "openai-completions", + "models": [{"id": "local-fixture", "name": "Local fixture", "reasoning": False, + "input": ["text"], "contextWindow": 32768, "maxTokens": 1024}]} + }}, + "discovery": {"mdns": {"mode": "off"}}, + "cron": {"enabled": False}, + "plugins": {"enabled": False} +})) +isolated_home = root / (prefix + "gateway-home") +isolated_home.mkdir(exist_ok=True) +gateway_env = {"PATH": os.environ["PATH"], "HOME": str(isolated_home), + "OPENCLAW_CONFIG_PATH": str(config), "OPENCLAW_STATE_DIR": str(root / (prefix + "gateway-state")), + "OPENCLAW_GATEWAY_TOKEN": token, "OPENCLAW_DISABLE_BONJOUR": "1"} +def verify(args): + line, jdk, test = args + java = subprocess.check_output(["/usr/libexec/java_home", "-v", jdk], text=True).strip() + env = dict(os.environ, JAVA_HOME=java, + PATH=java + "/bin:" + os.environ["PATH"], SDK_PROBE_URL=f"ws://127.0.0.1:{port}", + OPENCLAW_GATEWAY_TOKEN=token, SDK_FIXTURE_VERSION=version) + with (root / f"{prefix}tests-{line}.log").open("w") as log: + mvn = ["bash", "./mvnw"] if line == 3 else ["mvn"] + subprocess.run(mvn + ["-version"], env=env, cwd=root / f"sdk-{line}", stdout=log, stderr=log) + build = subprocess.run(mvn + ["-B", "-ntp", "-o", + "-Dmaven.repo.local=" + str(root / f"m2-{line}"), + "-Dmaven.repo.local.tail=" + str(Path.home() / ".m2/repository"), + "-Dtest=" + test, "clean", "test"], + env=env, cwd=root / f"sdk-{line}", stdout=log, stderr=log, timeout=120) + return line, build.returncode + +with (root / (prefix + "gateway-live.log")).open("w") as log: + proc = subprocess.Popen(["node", str(runtime / "openclaw.mjs"), "gateway", "run"], env=gateway_env, + stdout=log, stderr=log, start_new_session=True) + try: + for attempt in range(100): + if proc.poll() is not None: + raise RuntimeError(f"Gateway exited with {proc.returncode}") + try: + with urlopen(http + "/readyz", timeout=1) as response: + reply = json.load(response) + (root / (prefix + "ready.json")).write_text(json.dumps(reply)) + print("Gateway ready", flush=True) + break + except OSError: + time.sleep(0.25) + else: + raise RuntimeError("Gateway did not become ready") + runs = [] + with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor: + for line, result in executor.map(verify, tuple((line, jdk, fixture) for line, jdk in ((1, "1.8"), (2, "17"), (3, "21")))): + print(f"SDK line {line}: Maven exit {result}", flush=True) + runs.append(result) + if any(runs): + raise SystemExit(1) + finally: + if proc.poll() is None: + os.killpg(proc.pid, signal.SIGTERM) + try: + proc.wait(timeout=15) + except subprocess.TimeoutExpired: + os.killpg(proc.pid, signal.SIGKILL) + proc.wait() diff --git a/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/strict-run-id-review.patch b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/strict-run-id-review.patch new file mode 100644 index 0000000..cd9b535 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/evidence/fixtures/strict-run-id-review.patch @@ -0,0 +1,56 @@ +diff --git a/src/main/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClient.java b/src/main/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClient.java +index 4bb2ccb..589c433 100644 +--- a/src/main/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClient.java ++++ b/src/main/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClient.java +@@ -987,29 +987,21 @@ public class OpenClawGatewayWsClient extends WebSocketClient implements AutoClos + } + } + +- String runId = (String) p.get("runId"); ++ Object runId = p.get("runId"); ++ if (!(runId instanceof String)) { ++ return; ++ } ++ ChatStreamCollector collector = activeChatStreams.get(runId); ++ if (Objects.isNull(collector)) { ++ return; ++ } ++ + String state = p.get("state") instanceof String ? (String) p.get("state") : null; + boolean done = Boolean.TRUE.equals(p.get("done")) || "final".equals(state); + String delta = p.get("deltaText") instanceof String + ? (String) p.get("deltaText") + : (String) p.get("delta"); + +- // 匹配到活跃的 chat stream +- ChatStreamCollector collector = null; +- if (runId != null) { +- collector = activeChatStreams.get(runId); +- } +- // 旧版 Gateway 可能省略 runId;仅作兼容性回退,优先最近登记的活动流。 +- if (collector == null && !activeChatStreams.isEmpty()) { +- collector = activeChatStreams.values().stream() +- .reduce((first, second) -> second) +- .orElse(null); +- } +- +- if (collector == null) { +- return; +- } +- + if (delta != null) { + collector.textBuilder.append(delta); + collector.handler.onDelta(delta); +diff --git a/src/test/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClientIntegrationTest.java b/src/test/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClientIntegrationTest.java +index 6030e14..03ab45b 100644 +--- a/src/test/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClientIntegrationTest.java ++++ b/src/test/java/io/github/easy4j/openclaw/ws/OpenClawGatewayWsClientIntegrationTest.java +@@ -308,6 +308,8 @@ class OpenClawGatewayWsClientIntegrationTest { + chatSendRequest.set(request); + if ("modern-event".equals(request.path("params").path("message").asText())) { + conn.send(response(id, true, Collections.singletonMap("runId", "gateway-run-1"))); ++ conn.send("{\"type\":\"event\",\"event\":\"chat\",\"payload\":{\"runId\":\"another-run\",\"state\":\"delta\",\"deltaText\":\"foreign\"}}"); ++ conn.send("{\"type\":\"event\",\"event\":\"chat\",\"payload\":{\"state\":\"delta\",\"deltaText\":\"unidentified\"}}"); + conn.send("{\"type\":\"event\",\"event\":\"chat\",\"payload\":{\"runId\":\"gateway-run-1\",\"state\":\"delta\",\"deltaText\":\"modern-event\",\"seq\":1}}"); + conn.send("{\"type\":\"event\",\"event\":\"chat\",\"payload\":{\"runId\":\"gateway-run-1\",\"state\":\"final\",\"seq\":2}}"); + return; diff --git a/openspec/changes/fix-openclaw-protocol-contracts/proposal.md b/openspec/changes/fix-openclaw-protocol-contracts/proposal.md new file mode 100644 index 0000000..2442f7d --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/proposal.md @@ -0,0 +1,45 @@ +# 修正现有 HTTP、SSE 与 WS 协议契约 + +状态:DRAFT / REVIEW_REQUIRED。文档已提出,未批准实现,未归档。优先级:P0。 + +## Why + +现有通信面已存在,但静态核查发现部分行为与文档契约不一致。应先修正可能拼错内容、串流或误导副作用判断的行为,再扩展新方法。 + +## What Changes + +- `responses-streaming`: Responses 流式契约。 +- `gateway-chat-events`: Gateway 聊天事件语义。 +- `gateway-device-auth`: 设备握手与凭据生命周期。 +- `session-history-contract`: 会话历史与分页契约。 +- `tools-invoke-contract`: Tools Invoke 真实调用语义。 + +- **BREAKING(行为收紧,待评审)**:普通 Responses JSON 方法拒绝 stream=true;未知运行不再回退至任意流;未经验证的危险重试与权限回退禁止。 + +此次交付只创建 OpenSpec 文档与证据清单,不修改 Java 代码、构建文件、测试、依赖或发布配置。本提案描述后续拟实施行为,不证明这些能力现在已完成。 + +## Capabilities + +### New Capabilities + +- `responses-streaming`: Responses 流式契约。 +- `gateway-chat-events`: Gateway 聊天事件语义。 +- `gateway-device-auth`: 设备握手与凭据生命周期。 +- `session-history-contract`: 会话历史与分页契约。 +- `tools-invoke-contract`: Tools Invoke 真实调用语义。 + +### Modified Capabilities + +无现有同名 OpenSpec 生效规范可修改。本次是首次引入这些能力的正式规范条目,因此使用 ADDED Requirements;并不意味着仓库中不存在相关旧代码。 + +## Impact + +适用分支为 feature/1.0.x、feature/2.0.x、feature/3.0.x。具体源码触点见 design.md;可观测行为见 specs/;验证与执行步骤见 tasks.md。main 不作为第四条已验证发行线。 + +依赖变更:`establish-sdk-compatibility-governance` + +不在范围:重写 OpenClaw 内部模型引擎、原生插件运行时、沙箱内核或 Gateway 私有 worker 协议;不提供自动授权、跨租户共享密钥隔离或恰好一次执行保证。 + +## Review and Entry Criteria + +必须完成人工范围评审、锁定目标 Gateway 构建与协议映射,并完成依赖变更的必要验收后,才能进入本变更实现。OpenSpec 的 artifact 完整性状态不等于人审通过或产品已完成。具体门禁是本项目约定,而非声称 OpenSpec 官方强制该流程。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/specs/gateway-chat-events/spec.md b/openspec/changes/fix-openclaw-protocol-contracts/specs/gateway-chat-events/spec.md new file mode 100644 index 0000000..505eb88 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/specs/gateway-chat-events/spec.md @@ -0,0 +1,52 @@ +# Gateway 聊天事件语义 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的Gateway 聊天事件语义定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: CHAT-01 追加与替换事件区分 +SDK SHALL 依据目标协议区分 deltaText 追加与 replace=true 替换;存在完整 message 快照时 SHALL 按其契约对账,不能把快照再次当作增量追加。 + +#### Scenario: CHAT-01-S1 替换更新 +- **GIVEN** 缓存文本为 A +- **WHEN** 收到 replace=true 且 deltaText=ABC +- **THEN** 缓存变为 ABC 而不是 AABC,并将替换事实暴露给订阅者 + +#### Scenario: CHAT-01-S2 普通增量 +- **GIVEN** 缓存文本为 A +- **WHEN** 收到追加 deltaText=B 后收到内容为 AB 的最终快照 +- **THEN** 最终文本为 AB,不重复拼接 + +### Requirement: CHAT-02 运行身份严格关联 +SDK SHALL 使用可获得的 agent、sessionKey、sessionId、runId 与连接代际明确关联事件;未知 runId MUST NOT 被路由到任意活动流;缺少标识时只有经目标版本验证且唯一无歧义的兼容路径才可接收。 + +#### Scenario: CHAT-02-S1 并发隔离 +- **GIVEN** A 与 B 两个运行并发 +- **WHEN** A 的事件与未知运行 C 的事件交错到达 +- **THEN** A 只收到自己的事件,C 被隔离诊断且不进入 B + +#### Scenario: CHAT-02-S2 生命周期切换 +- **GIVEN** 会话已 reset 并产生新代际 +- **WHEN** 收到旧连接或旧 sessionId 的迟到事件 +- **THEN** 不污染新运行;必要时触发权威状态刷新 + +### Requirement: CHAT-03 终态错误和积压处理 +SDK SHALL 以至多一次方式完成、取消或失败单次聊天流;回调异常、异常事件和流量溢出 SHALL 不导致其他流串扰或无限缓存。 + +#### Scenario: CHAT-03-S1 重复终态 +- **GIVEN** 一个流已收到 final +- **WHEN** 再收到同一流的重复 final 或迟到 delta +- **THEN** 终态只通知一次,迟到事件不改变已完成结果 + +#### Scenario: CHAT-03-S2 缓冲上限 +- **GIVEN** 消费者持续慢于事件生产且达到配置上限 +- **WHEN** 下一个不可丢失事件到达 +- **THEN** 产生明确溢出或恢复信号并执行受控终止,不静默丢弃或无限扩容 + +## Sources + +[O04 会话启动、快照及事件语义](https://docs.openclaw.ai/gateway/protocol/rpc-bootstrap-and-events) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/specs/gateway-device-auth/spec.md b/openspec/changes/fix-openclaw-protocol-contracts/specs/gateway-device-auth/spec.md new file mode 100644 index 0000000..619623a --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/specs/gateway-device-auth/spec.md @@ -0,0 +1,52 @@ +# 设备握手与凭据生命周期 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的设备握手与凭据生命周期定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: AUTH-01 握手结果完整且向前兼容 +SDK SHALL 读取目标契约定义的 protocol、server、features、snapshot、policy、auth;设备 Token 缺省 SHALL 与认证失败区分,未知可选字段 SHALL 不破坏已知字段解析。 + +#### Scenario: AUTH-01-S1 签发设备凭据 +- **GIVEN** 可信连接成功并返回 deviceToken 与 deviceTokens +- **WHEN** 解析 hello-ok +- **THEN** 保留 role、有效 scopes 和各凭据关联,向调用者提供完整结果 + +#### Scenario: AUTH-01-S2 不签发设备凭据 +- **GIVEN** 允许的认证路径成功但不返回 deviceToken +- **WHEN** 解析 hello-ok +- **THEN** 连接仍可成功,不覆盖宿主已有合法凭据为空值 + +### Requirement: AUTH-02 凭据持久化由宿主控制 +SDK SHALL 支持宿主控制的签名与凭据存储策略;持久凭据 SHALL 按 Gateway 身份、设备、角色分区并脱敏;不可信传输上的引导结果 MUST NOT 自动持久化,临时 bootstrap 密钥 MUST NOT 写入日志。 + +#### Scenario: AUTH-02-S1 可信轮换 +- **GIVEN** 宿主配置了安全存储且 wss 握手签发新 Token +- **WHEN** 保存凭据 +- **THEN** 原子更新对应分区,不改其他 Gateway 或角色的凭据 + +#### Scenario: AUTH-02-S2 不可信引导 +- **GIVEN** 非可信远程明文传输返回引导凭据 +- **WHEN** 触发自动保存路径 +- **THEN** 拒绝持久化并报告原因,日志不出现密钥、签名或 Token + +### Requirement: AUTH-03 握手和权限失败不自动提权 +单次连接尝试 SHALL 只发送一个有效 connect 握手;设备身份要求、nonce 和权限 SHALL 服从目标版本;认证拒绝 MUST NOT 自动改用高权限共享密钥或删除授权要求。 + +#### Scenario: AUTH-03-S1 挑战竞争 +- **GIVEN** 挑战事件与等待计时器同时触发 +- **WHEN** SDK 发起握手 +- **THEN** 只有一个请求关联和一次终态通知,旧挑战不能复用 + +#### Scenario: AUTH-03-S2 权限升级要求 +- **GIVEN** 服务端拒绝请求并要求重新配对 +- **WHEN** 连接失败 +- **THEN** 保留结构化错误并停止自动提权;由宿主显式处理配对 + +## Sources + +[O05 Gateway 握手与设备凭据](https://docs.openclaw.ai/gateway/protocol/handshake);[O02 协议版本与客户端恢复边界](https://docs.openclaw.ai/gateway/protocol/versioning) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/specs/responses-streaming/spec.md b/openspec/changes/fix-openclaw-protocol-contracts/specs/responses-streaming/spec.md new file mode 100644 index 0000000..6714a21 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/specs/responses-streaming/spec.md @@ -0,0 +1,52 @@ +# Responses 流式契约 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的Responses 流式契约定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: RSP-01 JSON 与 SSE 入口明确分离 +SDK SHALL 区分普通 Responses JSON 响应和 Responses SSE 流;普通 JSON 入口接到 stream=true 时 SHALL 在发出请求前拒绝并指向流式入口,流式入口 SHALL 使用独立事件解析而非 Chat Completions chunk 解析。 + +#### Scenario: RSP-01-S1 启动 Responses 流 +- **GIVEN** 用户选择流式入口且请求有效 +- **WHEN** 服务端返回 text/event-stream +- **THEN** 返回可取消订阅并逐项分发 Responses 事件 + +#### Scenario: RSP-01-S2 错误入口 +- **GIVEN** 用户向普通 JSON 入口传 stream=true +- **WHEN** 提交请求 +- **THEN** 在网络发送前获得参数错误,不把 SSE 当作完整 JSON 解析 + +### Requirement: RSP-02 流式终态与内容重建 +SDK SHALL 保留 output item、content part、工具调用标识及用量,并区分 completed、incomplete、failed 与本地取消;每条订阅的终态回调 SHALL 至多发生一次。 + +#### Scenario: RSP-02-S1 多输出项完成 +- **GIVEN** 同一响应含文本和 function_call 输出项 +- **WHEN** 增量事件及 completed 到达 +- **THEN** 分别重建输出项,保留 call_id、参数与用量,完成一次 + +#### Scenario: RSP-02-S2 未完成或传输中断 +- **GIVEN** 服务端返回 incomplete、failed 或未终态即 EOF +- **WHEN** 流结束 +- **THEN** 报告相应远程终态或传输中断,禁止当成 completed + +### Requirement: RSP-03 续接与被忽略参数保持真实语义 +SDK SHALL 保留 previous_response_id、function_call_output 的调用关联及空字符串输出;对目标版本接收但忽略的参数 SHALL 明确说明,不承诺这些字段带来存储、推理或工具次数限制效果。 + +#### Scenario: RSP-03-S1 空工具输出续接 +- **GIVEN** 已有 function_call 的 call_id +- **WHEN** 以空字符串输出继续该响应 +- **THEN** 原样保留标识和空值并形成有效续接输入 + +#### Scenario: RSP-03-S2 参数被忽略 +- **GIVEN** 目标契约声明 store 或 reasoning 被忽略 +- **WHEN** 调用者设置该字段 +- **THEN** 文档与诊断说明不保证执行效果,SDK 不伪造生效证明 + +## Sources + +[O03 Responses HTTP 与 SSE](https://docs.openclaw.ai/gateway/openresponses-http-api) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/specs/session-history-contract/spec.md b/openspec/changes/fix-openclaw-protocol-contracts/specs/session-history-contract/spec.md new file mode 100644 index 0000000..0eafb71 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/specs/session-history-contract/spec.md @@ -0,0 +1,52 @@ +# 会话历史与分页契约 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的会话历史与分页契约定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: HIST-01 分页遵守服务端游标 +SDK SHALL 保留目标版本返回的 hasMore、nextOffset 或游标、稳定锚点及消息身份;MUST NOT 以显示消息数或列表条数自行推算下一页。 + +#### Scenario: HIST-01-S1 过滤后的历史页 +- **GIVEN** 历史返回条数不等于服务端扫描或分页步长 +- **WHEN** 读取下一页 +- **THEN** 使用返回的 nextOffset 或游标并按消息身份去重,不从显示条数推算 + +#### Scenario: HIST-01-S2 没有下一页 +- **GIVEN** 响应明确表示结束或没有合法续页信息 +- **WHEN** 使用分页迭代器 +- **THEN** 终止迭代,不重复请求最后一页 + +### Requirement: HIST-02 恢复元数据保留缺省语义 +SDK SHALL 保留 sessionInfo、inFlightRun 及目标版本提供的生命周期元数据,区分字段缺省、明确 null 与已知值;不适用字段 SHALL 按目标版本兼容说明处理。 + +#### Scenario: HIST-02-S1 历史携带运行 +- **GIVEN** 历史结果含可恢复 runId 和会话身份 +- **WHEN** 调用恢复逻辑 +- **THEN** 只关联该准确身份,不猜测最近活动运行 + +#### Scenario: HIST-02-S2 未知活动状态 +- **GIVEN** activeRunIds 或恢复信息缺省或为 null +- **WHEN** 合并状态 +- **THEN** 按对应契约保留未更新或标记未知,不能无条件视为无运行 + +### Requirement: HIST-03 历史刷新不跨会话代际 +SDK SHALL 防止慢历史响应覆盖更新的会话身份、reset 或删除结果;快照读取期间收到的失效事件 SHALL 触发必要的尾随刷新。 + +#### Scenario: HIST-03-S1 读取期间有更新 +- **GIVEN** 历史读取尚未返回 +- **WHEN** 收到改变同一会话的事件 +- **THEN** 记录失效并在响应后对账,必要时再次刷新 + +#### Scenario: HIST-03-S2 旧代际删除 +- **GIVEN** 相同 sessionKey 已对应新的 sessionId +- **WHEN** 旧 sessionId 的删除事件迟到 +- **THEN** 保留新会话,不依据 key 单独删除新代际 + +## Sources + +[O06 会话控制与历史](https://docs.openclaw.ai/gateway/protocol/rpc-session-control);[O04 会话启动、快照及事件语义](https://docs.openclaw.ai/gateway/protocol/rpc-bootstrap-and-events) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/specs/tools-invoke-contract/spec.md b/openspec/changes/fix-openclaw-protocol-contracts/specs/tools-invoke-contract/spec.md new file mode 100644 index 0000000..20216b2 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/specs/tools-invoke-contract/spec.md @@ -0,0 +1,52 @@ +# Tools Invoke 真实调用语义 — Spec Delta + +## Purpose + +为 openclaw-java-sdk 的Tools Invoke 真实调用语义定义可独立验证的外部行为、失败边界和授权约束,使三条 Java 发行线能够依据同一版本化契约实现并接受验收,而不是依据类名或接口存在推断功能已完成。 + +## ADDED Requirements + +### Requirement: TOOL-01 调用字段与关联保真 +SDK SHALL 支持目标契约的 agentId、sessionKey、idempotencyKey 和工具参数,保留工具调用关联;MUST NOT 把幂等标识存在解释为跨故障恰好一次执行保证。 + +#### Scenario: TOOL-01-S1 显式关联 +- **GIVEN** 调用者给出 agentId、sessionKey 和 idempotencyKey +- **WHEN** 请求被序列化 +- **THEN** 字段按目标契约发出,返回结果保留可用的调用关联 + +#### Scenario: TOOL-01-S2 身份冲突 +- **GIVEN** agentId 与显式 sessionKey 指向不同智能体 +- **WHEN** 服务端拒绝请求 +- **THEN** 保留错误,不擅自删去身份字段重试 + +### Requirement: TOOL-02 dryRun 不提供虚假的无副作用保障 +SDK 文档与 API 说明 SHALL 明确目标版本中 dryRun 是否被忽略;当该字段被忽略时,调用路径 MUST NOT 标记为安全预演或无副作用执行。 + +#### Scenario: TOOL-02-S1 兼容字段仍可传递 +- **GIVEN** 调用者显式设置 dryRun=true 且目标版本忽略它 +- **WHEN** 执行实际调用 +- **THEN** 兼容透传但说明仍可能产生副作用,不产生预演成功标志 + +#### Scenario: TOOL-02-S2 宿主要求只验证 +- **GIVEN** 宿主明确禁止工具执行 +- **WHEN** 没有可验证的服务端预演能力 +- **THEN** 在宿主执行策略层拒绝实际调用,而不是依赖 dryRun + +### Requirement: TOOL-03 认证模式与执行失败分层 +SDK SHALL 区分传输错误、RPC 拒绝、工具业务失败与结果不确定;共享 Gateway 密钥 MUST NOT 被宣传为按租户受限凭据,scopes 请求头 MUST NOT 被当成此模式下的隔离保证。 + +#### Scenario: TOOL-03-S1 工具业务失败 +- **GIVEN** 传输或 RPC 成功但工具结果 ok=false +- **WHEN** 转换结果 +- **THEN** 保留工具业务错误,不返回成功值或自动二次执行 + +#### Scenario: TOOL-03-S2 窄 scopes 请求头 +- **GIVEN** 调用者使用共享操作员 Token 并填写较窄 scopes +- **WHEN** 构造安全说明或访问策略 +- **THEN** 明确其不构成租户隔离,且不把密钥交给不受信任调用方 + +## Sources + +[O07 HTTP Tools Invoke 与认证语义](https://docs.openclaw.ai/gateway/tools-invoke-http-api) + +本文件是待实施规范,不是运行测试报告;所属 proposal 与 design 定义版本准入和实施边界。 diff --git a/openspec/changes/fix-openclaw-protocol-contracts/tasks.md b/openspec/changes/fix-openclaw-protocol-contracts/tasks.md new file mode 100644 index 0000000..cc8bbd6 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/tasks.md @@ -0,0 +1,52 @@ +# Implementation Tasks + +状态:全部未执行。本清单是后续实施计划,不是本轮文档生成记录。 + +## 1. 准入与证据 + +- [ ] 1.1 取得本变更的人审结论并核验依赖;验收:评审记录包含范围、行为收紧、三分支要求和批准的 change ID。 +- [ ] 1.2 锁定目标 OpenClaw 精确版本/提交、构建来源及协议映射;验收:方法、事件、字段、scope 与拒绝样本均有版本化来源,未锁定时停止编码。 + +## 2. Responses 流式契约 + +- [ ] 2.1 为 `responses-streaming` 建立契约样本及回归基线(RSP-01, RSP-02, RSP-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 2.2 按 design.md 实施 `responses-streaming` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 2.3 在三条适用分支验证 `responses-streaming` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 3. Gateway 聊天事件语义 + +- [ ] 3.1 为 `gateway-chat-events` 建立契约样本及回归基线(CHAT-01, CHAT-02, CHAT-03);[CHAT-02-S1 并发隔离](evidence/2026-11-19-gateway-chat-isolation.md)已在两版 Gateway 复现。验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 3.2 按 design.md 实施 `gateway-chat-events` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 3.3 在三条适用分支验证 `gateway-chat-events` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 4. 设备握手与凭据生命周期 + +- [ ] 4.1 为 `gateway-device-auth` 建立契约样本及回归基线(AUTH-01, AUTH-02, AUTH-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 4.2 按 design.md 实施 `gateway-device-auth` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 4.3 在三条适用分支验证 `gateway-device-auth` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 5. 会话历史与分页契约 + +- [ ] 5.1 为 `session-history-contract` 建立契约样本及回归基线(HIST-01, HIST-02, HIST-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 5.2 按 design.md 实施 `session-history-contract` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 5.3 在三条适用分支验证 `session-history-contract` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 6. Tools Invoke 真实调用语义 + +- [ ] 6.1 为 `tools-invoke-contract` 建立契约样本及回归基线(TOOL-01, TOOL-02, TOOL-03);验收:spec.md 的 6 个场景全部映射到 fixture 或人工验收步骤,已存在问题有最小复现且测试确实执行。 +- [ ] 6.2 按 design.md 实施 `tools-invoke-contract` 并保持旧入口的已声明兼容范围;验收:对应成功、拒绝、边界和生命周期场景通过,错误与权限语义不被吞并。 +- [ ] 6.3 在三条适用分支验证 `tools-invoke-contract` 并同步示例;验收:记录每条分支 SHA、JDK、构建命令、非零执行测试数和结果,获准差异逐项列出,缺测不得勾选。 + +## 7. 集成、资源与归档门禁 + +- [ ] 7.1 对本变更执行真实 Gateway 场景;验收:固定服务端版本、认证方式、运行命令与脱敏证据,成功和拒绝均有真实观察,SDK 本地 fixture 通过不能替代。 +- [ ] 7.2 完成适用的资源、故障与兼容检查;验收:1000 次受控请求/订阅周期后活动注册归零,自有线程在测试预算内终止,共享资源仍可使用;治理类变更检查无运行资源触点并记录不适用理由。 +- [ ] 7.3 更新覆盖矩阵并执行规范校验;验收:官方 OpenSpec validate 输出通过、无未解释的三分支差异、所有必需任务有证据且人审允许归档,随后才更新生效 specs。 + +Tools Invoke 的锁定版与 2026.11.5 两轮真实回环验证及 Java DTO 差距见 [版本评审](evidence/2026-11-19-tools-invoke-version-review.md)。 + +会话历史的两版真实 Gateway 游标、增量及重置差异见 [版本评审](evidence/2026-11-19-chat-history-version-review.md)。 + +Responses 的两版真实 Gateway 终态及续接差异见 [版本评审](evidence/2026-11-19-responses-version-review.md)。 + +设备身份握手的两版真实 Gateway 观察与三条 Java 发行线的 hello-ok 映射差距见 [设备认证版本复评](evidence/2026-11-19-device-auth-version-review.md)。 diff --git a/openspec/config.yaml b/openspec/config.yaml new file mode 100644 index 0000000..1f9aa06 --- /dev/null +++ b/openspec/config.yaml @@ -0,0 +1,24 @@ +schema: spec-driven +context: | + Repository: easy-4-java/openclaw-java-sdk. + Language: Chinese prose; keep normative OpenSpec headings and SHALL/MUST in English. + Release lines: feature/1.0.x (JDK 8), feature/2.0.x (JDK 17), feature/3.0.x (JDK 21). + Keep wire behavior and shared acceptance fixtures aligned; do not assume binary ABI identity across Jackson/JDK lines. + This package contains proposed changes only. No implementation, Gateway live test, or archive is authorized by artifact presence. + The SDK commit baseline is recorded in docs/openclaw-integration/baseline.json. + A precise tested OpenClaw version/commit is not yet selected; version pinning is a pre-implementation gate. + Preserve HTTP, SSE, WebSocket, and CLI boundaries. A CLI wrapper is not a native RPC or a persistent protocol client. + Host application owns credential persistence, execution authorization, tenant isolation, and injected shared resources. + Do not claim that dryRun, scope headers with shared credentials, or idempotency keys imply safety or exactly-once execution. +rules: + proposal: + - State in-scope, non-goals, affected branches, dependencies, and behavioral breaking changes. + - Declare exact capability paths; do not invent MODIFIED targets without existing main specs. + specs: + - Write observable behavior, not internal classes; each SHALL/MUST requirement needs WHEN/THEN scenarios. + - Cover success and rejection or failure paths and preserve transport versus remote execution semantics. + design: + - Identify proposed components separately from existing code and document alternatives, migration, and rollback limits. + tasks: + - Every numbered checkbox must include acceptance evidence and remain unchecked until actually executed. + - Do not archive before human review and required branch and live-Gateway evidence are complete. diff --git a/openspec/specs/.gitkeep b/openspec/specs/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/openspec/specs/.gitkeep @@ -0,0 +1 @@ +