Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
05c1550
docs(openspec): add OpenClaw integration specifications and roadmap
loong10k Sep 20, 2026
03a964e
docs(g0): 准入证据采集——版本锁定、三分支 codegraph、构建/测试矩阵、能力清单、官方 OpenSpec strict …
loong10k Sep 20, 2026
60d3518
docs: reconcile OpenClaw draft with G0 evidence
loong10k Nov 17, 2026
fe0c14f
Merge pull request #6 from easy-4-java/feature/REQ-20261118-wandl-ope…
loong10k Nov 17, 2026
e2c76c7
docs: align OpenClaw roadmap with G0 evidence
loong10k Nov 17, 2026
c059f0c
Merge pull request #8 from easy-4-java/feature/REQ-20261118-wandl-ope…
loong10k Nov 17, 2026
c9760ea
docs: record OpenClaw Gateway baseline across SDK lines
loong10k Nov 18, 2026
37afb64
Merge OpenClaw Gateway evidence into test/20261118
loong10k Nov 18, 2026
883db70
docs: record generated schema for locked OpenClaw Gateway
loong10k Nov 18, 2026
a191fa9
Merge locked Gateway schema evidence into test/20261118
loong10k Nov 18, 2026
12d5938
docs: record OpenClaw SDK maintenance-line compatibility audit
loong10k Nov 18, 2026
8dad870
Merge maintenance-line compatibility evidence into test/20261118
loong10k Nov 18, 2026
a0c1d08
docs: reconcile Gateway evidence and review gates
loong10k Nov 18, 2026
9a2bfe1
Merge Gateway governance review evidence into test/20261118
loong10k Nov 18, 2026
b3e4bf4
test: add shared OpenClaw Gateway compatibility fixture
loong10k Nov 18, 2026
b6ef194
Merge shared Gateway compatibility fixture into test/20261118
loong10k Nov 18, 2026
97b4cdb
docs: audit OpenClaw governance scenarios against versioned evidence
loong10k Nov 18, 2026
22d38c4
Merge governance scenario evidence into test/20261118
loong10k Nov 18, 2026
bedd330
test: verify unavailable Gateway methods across SDK lines
loong10k Nov 18, 2026
5e9ff0d
Merge removed Gateway method evidence into test/20261118
loong10k Nov 18, 2026
665cef6
docs: record Gateway streaming isolation verification
loong10k Nov 18, 2026
fc9c74a
Merge Gateway streaming isolation findings into test/20261118
loong10k Nov 18, 2026
c447d6d
docs: verify isolated Gateway chat run routing on all Java lines
loong10k Nov 18, 2026
259fdf1
Merge chat stream routing verification into test/20261118
loong10k Nov 18, 2026
2f71b5c
Review OpenClaw Tools Invoke on two live Gateway versions
loong10k Nov 18, 2026
48c95fc
Review session history cursors on both OpenClaw Gateway versions
loong10k Nov 18, 2026
3c4197e
Review Responses SSE terminals and continuation across Gateway versions
loong10k Nov 18, 2026
140ae19
Verify Responses disconnect releases the upstream provider socket
loong10k Nov 18, 2026
3456591
docs: verify chat replacement and terminal snapshots on both Gateway …
loong10k Nov 19, 2026
440f050
docs: verify Responses empty tool output on both Gateway versions
loong10k Nov 19, 2026
2554092
docs: verify configured OpenClaw Responses tool continuation
loong10k Nov 19, 2026
7a007c2
docs: reproduce OpenClaw Responses JSON entry gap on three JDKs
loong10k Nov 19, 2026
c5cd03a
docs: review OpenClaw device handshake on 2026.11.5
loong10k Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions docs/openclaw-integration/README.md
Original file line number Diff line number Diff line change
@@ -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/<change-id>/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。
70 changes: 70 additions & 0 deletions docs/openclaw-integration/acceptance-plan.md
Original file line number Diff line number Diff line change
@@ -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 个产品验收场景已经执行。
122 changes: 122 additions & 0 deletions docs/openclaw-integration/baseline.json
Original file line number Diff line number Diff line change
@@ -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"
]
}
]
}
39 changes: 39 additions & 0 deletions docs/openclaw-integration/coverage-baseline.md
Original file line number Diff line number Diff line change
@@ -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 完整条目,不能直接覆盖或重复新增。
Loading
Loading