easy-4-java · loong10k · Sep 20, 2026 · Sep 20, 2026
diff --git a/.mimosa/hook-state/sess_aba26ad0-1074-40c8-8d54-eb7e99fcf5d6.continue.json b/.mimosa/hook-state/sess_aba26ad0-1074-40c8-8d54-eb7e99fcf5d6.continue.json
@@ -0,0 +1 @@
+{"schemaVersion":"mimosa-stop-continuation/v1","generation":"mu5amxzk-35945-ec5bb1c135","used":false,"reportPersisted":false,"claim":null,"updatedAt":"2026-09-17T08:54:37.777Z"}
diff --git a/docs/openclaw-integration/README.md 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 项，全部未执行；检查结果见 [文档检查结果](validation-summary.md)。
+
+## 阅读顺序
+
+1. [总体路线与依赖](roadmap.md)。
+2. [当前覆盖与风险基线](coverage-baseline.md)及[来源登记](source-register.md)。
+3. `openspec/changes/<change-id>/proposal.md` → `specs/*/spec.md` → `design.md` → `tasks.md`。
+4. [验收计划](acceptance-plan.md)及[逐场景追踪表](traceability.md)。
+
+## 交付边界
+
+本目录及 openspec/ 以独立文档提交交付；没有修改任何 SDK Java 源码、pom、依赖或现有测试，也没有写入维护者的本机工作区。所有实施任务保持未勾选，人审批准和具体目标 Gateway 版本锁定仍是下一阶段前提。
+
+官方 OpenSpec CLI 在当前环境不可用，尝试获取时因 DNS/网络解析失败而未能安装。因此只报告实际完成的自定义文档结构检查，不声称执行过官方 validate。也没有执行 codegraph、Maven 或真实 Gateway 测试。
+
+## 合入方式
+
+`openspec/` 和 `docs/openclaw-integration/` 按仓库相对路径组织。先在文档专用分支审查再合入；如果目标分支后来已有同名规范或目录，需合并而不是覆盖。本文是迁入文档目录后的交付索引，不覆盖原仓库 README。
+
+本轮没有创建任何生效 capability spec；`openspec/specs/` 只有占位文件。待变更实现、验收和人审完成后，再按项目流程归档。根目录 `openspec/config.yaml` 定义 spec-driven 模式和项目规则。
+
+## 快速核对
+
+查看 `docs/openclaw-integration/baseline.json` 确认 SDK 提交及明确未验证的上游版本。参照 acceptance-plan 中的命令使用官方 OpenSpec CLI 校验；切勿把 artifact 已齐全或状态命令的 isComplete 字段解释为产品实现完成。
+
+## 发布打包说明
+
+原始文档包的 traceability.json 使用 gzip 保存为 .json.gz；validation-report.json 使用 gzip + Base64 分段保存在 [validation-report/](validation-report/README.md)，该目录说明如何恢复原始 JSON。解压后的内容与原包逐字节一致；Markdown 追踪表与检查摘要保留直接可读版本。仓库路径与文件校验值见 [package-manifest.json](package-manifest.json)。此打包调整不改变任何 Requirement、Scenario 或实施任务。
diff --git a/docs/openclaw-integration/acceptance-plan.md 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
@@ -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
@@ -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 完整条目，不能直接覆盖或重复新增。
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		{"schemaVersion":"mimosa-stop-continuation/v1","generation":"mu5amxzk-35945-ec5bb1c135","used":false,"reportPersisted":false,"claim":null,"updatedAt":"2026-09-17T08:54:37.777Z"}