From 05c155006db208a9678068b7371db399fdd401e2 Mon Sep 17 00:00:00 2001 From: Loong Wan Date: Sun, 20 Sep 2026 22:22:25 +0800 Subject: [PATCH 1/2] docs(openspec): add OpenClaw integration specifications and roadmap Add six draft changes, 21 capability specifications, 64 requirements, 128 scenarios, and 97 unchecked implementation tasks. Include source baselines, roadmap, acceptance plan, traceability and losslessly packaged document-validation evidence. Preserve existing SDK sources, tests, build files, and root READMEs. Documentation only: no implementation approval, official OpenSpec CLI validation, SDK builds, or live Gateway tests are claimed. --- docs/openclaw-integration/README.md | 32 +++++ docs/openclaw-integration/acceptance-plan.md | 70 +++++++++ docs/openclaw-integration/baseline.json | 122 ++++++++++++++++ .../openclaw-integration/coverage-baseline.md | 39 +++++ .../package-manifest.json | 1 + docs/openclaw-integration/roadmap.md | 53 +++++++ docs/openclaw-integration/source-register.md | 60 ++++++++ .../openclaw-integration/traceability.json.gz | Bin 0 -> 3246 bytes docs/openclaw-integration/traceability.md | 134 ++++++++++++++++++ .../validation-report/README.md | 22 +++ .../validation-report/part-001.b64 | 1 + .../validation-report/part-002.b64 | 1 + .../validation-report/part-003.b64 | 1 + .../validation-summary.md | 32 +++++ openspec/README.md | 7 + .../.openspec.yaml | 2 + .../design.md | 55 +++++++ .../proposal.md | 39 +++++ .../specs/agent-lifecycle/spec.md | 52 +++++++ .../specs/approval-control/spec.md | 52 +++++++ .../specs/session-control/spec.md | 52 +++++++ .../tasks.md | 32 +++++ .../add-gateway-operations/.openspec.yaml | 2 + .../changes/add-gateway-operations/design.md | 61 ++++++++ .../add-gateway-operations/proposal.md | 45 ++++++ .../specs/channel-node-control/spec.md | 52 +++++++ .../specs/configuration-control/spec.md | 52 +++++++ .../specs/cron-control/spec.md | 52 +++++++ .../specs/skill-plugin-lifecycle/spec.md | 52 +++++++ .../specs/task-audit-artifacts/spec.md | 52 +++++++ .../specs/tool-model-catalogs/spec.md | 52 +++++++ .../changes/add-gateway-operations/tasks.md | 50 +++++++ .../add-managed-gateway-client/.openspec.yaml | 2 + .../add-managed-gateway-client/design.md | 59 ++++++++ .../add-managed-gateway-client/proposal.md | 39 +++++ .../specs/gateway-recovery/spec.md | 52 +++++++ .../specs/managed-rpc/spec.md | 52 +++++++ .../specs/typed-event-delivery/spec.md | 52 +++++++ .../add-managed-gateway-client/tasks.md | 32 +++++ .../.openspec.yaml | 2 + .../add-optional-runtime-adapters/design.md | 57 ++++++++ .../add-optional-runtime-adapters/proposal.md | 39 +++++ .../specs/cli-typed-results/spec.md | 52 +++++++ .../specs/persistent-stdio-adapters/spec.md | 52 +++++++ .../specs/terminal-voice-adapters/spec.md | 52 +++++++ .../add-optional-runtime-adapters/tasks.md | 32 +++++ .../.openspec.yaml | 2 + .../design.md | 54 +++++++ .../proposal.md | 35 +++++ .../sdk-compatibility-governance/spec.md | 65 +++++++++ .../tasks.md | 24 ++++ .../.openspec.yaml | 2 + .../fix-openclaw-protocol-contracts/design.md | 65 +++++++++ .../proposal.md | 45 ++++++ .../specs/gateway-chat-events/spec.md | 52 +++++++ .../specs/gateway-device-auth/spec.md | 52 +++++++ .../specs/responses-streaming/spec.md | 52 +++++++ .../specs/session-history-contract/spec.md | 52 +++++++ .../specs/tools-invoke-contract/spec.md | 52 +++++++ .../fix-openclaw-protocol-contracts/tasks.md | 44 ++++++ openspec/config.yaml | 24 ++++ openspec/specs/.gitkeep | 1 + 62 files changed, 2524 insertions(+) create mode 100644 docs/openclaw-integration/README.md create mode 100644 docs/openclaw-integration/acceptance-plan.md create mode 100644 docs/openclaw-integration/baseline.json create mode 100644 docs/openclaw-integration/coverage-baseline.md create mode 100644 docs/openclaw-integration/package-manifest.json create mode 100644 docs/openclaw-integration/roadmap.md create mode 100644 docs/openclaw-integration/source-register.md create mode 100644 docs/openclaw-integration/traceability.json.gz create mode 100644 docs/openclaw-integration/traceability.md create mode 100644 docs/openclaw-integration/validation-report/README.md create mode 100644 docs/openclaw-integration/validation-report/part-001.b64 create mode 100644 docs/openclaw-integration/validation-report/part-002.b64 create mode 100644 docs/openclaw-integration/validation-report/part-003.b64 create mode 100644 docs/openclaw-integration/validation-summary.md create mode 100644 openspec/README.md create mode 100644 openspec/changes/add-agent-session-approval-control/.openspec.yaml create mode 100644 openspec/changes/add-agent-session-approval-control/design.md create mode 100644 openspec/changes/add-agent-session-approval-control/proposal.md create mode 100644 openspec/changes/add-agent-session-approval-control/specs/agent-lifecycle/spec.md create mode 100644 openspec/changes/add-agent-session-approval-control/specs/approval-control/spec.md create mode 100644 openspec/changes/add-agent-session-approval-control/specs/session-control/spec.md create mode 100644 openspec/changes/add-agent-session-approval-control/tasks.md create mode 100644 openspec/changes/add-gateway-operations/.openspec.yaml create mode 100644 openspec/changes/add-gateway-operations/design.md create mode 100644 openspec/changes/add-gateway-operations/proposal.md create mode 100644 openspec/changes/add-gateway-operations/specs/channel-node-control/spec.md create mode 100644 openspec/changes/add-gateway-operations/specs/configuration-control/spec.md create mode 100644 openspec/changes/add-gateway-operations/specs/cron-control/spec.md create mode 100644 openspec/changes/add-gateway-operations/specs/skill-plugin-lifecycle/spec.md create mode 100644 openspec/changes/add-gateway-operations/specs/task-audit-artifacts/spec.md create mode 100644 openspec/changes/add-gateway-operations/specs/tool-model-catalogs/spec.md create mode 100644 openspec/changes/add-gateway-operations/tasks.md create mode 100644 openspec/changes/add-managed-gateway-client/.openspec.yaml create mode 100644 openspec/changes/add-managed-gateway-client/design.md create mode 100644 openspec/changes/add-managed-gateway-client/proposal.md create mode 100644 openspec/changes/add-managed-gateway-client/specs/gateway-recovery/spec.md create mode 100644 openspec/changes/add-managed-gateway-client/specs/managed-rpc/spec.md create mode 100644 openspec/changes/add-managed-gateway-client/specs/typed-event-delivery/spec.md create mode 100644 openspec/changes/add-managed-gateway-client/tasks.md create mode 100644 openspec/changes/add-optional-runtime-adapters/.openspec.yaml create mode 100644 openspec/changes/add-optional-runtime-adapters/design.md create mode 100644 openspec/changes/add-optional-runtime-adapters/proposal.md create mode 100644 openspec/changes/add-optional-runtime-adapters/specs/cli-typed-results/spec.md create mode 100644 openspec/changes/add-optional-runtime-adapters/specs/persistent-stdio-adapters/spec.md create mode 100644 openspec/changes/add-optional-runtime-adapters/specs/terminal-voice-adapters/spec.md create mode 100644 openspec/changes/add-optional-runtime-adapters/tasks.md create mode 100644 openspec/changes/establish-sdk-compatibility-governance/.openspec.yaml create mode 100644 openspec/changes/establish-sdk-compatibility-governance/design.md create mode 100644 openspec/changes/establish-sdk-compatibility-governance/proposal.md create mode 100644 openspec/changes/establish-sdk-compatibility-governance/specs/sdk-compatibility-governance/spec.md create mode 100644 openspec/changes/establish-sdk-compatibility-governance/tasks.md create mode 100644 openspec/changes/fix-openclaw-protocol-contracts/.openspec.yaml create mode 100644 openspec/changes/fix-openclaw-protocol-contracts/design.md create mode 100644 openspec/changes/fix-openclaw-protocol-contracts/proposal.md create mode 100644 openspec/changes/fix-openclaw-protocol-contracts/specs/gateway-chat-events/spec.md create mode 100644 openspec/changes/fix-openclaw-protocol-contracts/specs/gateway-device-auth/spec.md create mode 100644 openspec/changes/fix-openclaw-protocol-contracts/specs/responses-streaming/spec.md create mode 100644 openspec/changes/fix-openclaw-protocol-contracts/specs/session-history-contract/spec.md create mode 100644 openspec/changes/fix-openclaw-protocol-contracts/specs/tools-invoke-contract/spec.md create mode 100644 openspec/changes/fix-openclaw-protocol-contracts/tasks.md create mode 100644 openspec/config.yaml create mode 100644 openspec/specs/.gitkeep diff --git a/docs/openclaw-integration/README.md b/docs/openclaw-integration/README.md new file mode 100644 index 0000000..4f2e7e2 --- /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 项，全部未执行；检查结果见 [文档检查结果](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、依赖或现有测试，也没有写入维护者的本机工作区。所有实施任务保持未勾选，人审批准和具体目标 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 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..b6070a1 --- /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":2635,"sha256":"2f795ec91ed8a83bd22907a2e334bd3ac3ad8a079b25c43b57ceff8251fb245b"},"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":3477,"sha256":"0348da728fc714498cab3f5796eabd38c45efd7d0df158db3fea34a508b2dd32"},"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":13478,"sha256":"cd1b647ab538953e299a1964e009fbb65b4212654dab678bfb05e4fd1bcd2a59"},"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":1794,"sha256":"c91cc48304a3318a337ff7881d05caa1b699b252105984e6fbfb05c8fdf2f6b4"},"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":4395,"sha256":"5eef818703376fa417abdff26f2b3ce0bc5761f643f4378cf985abc49dc35e92"},"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":2716,"sha256":"edd09e1dfd45f8f9b956ea4745b4cedad5686ce9cda5813c1cd463df3bf18e6a"},"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/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":4698,"sha256":"fd7a21979c085430e70479494b8f87c88e9746cf277463628a93a92a7932130a"},"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}} diff --git a/docs/openclaw-integration/roadmap.md b/docs/openclaw-integration/roadmap.md new file mode 100644 index 0000000..7d97a2a --- /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、依赖来源与发布限制。 + +## 准入状态 + +人审：尚未发生。目标 Gateway 精确版本／提交：尚未锁定，阻断编码而不阻断文档评审。官方 OpenSpec CLI：当前环境未安装，尝试获取时发生网络/DNS 解析失败；其校验是待补项。自定义文档结构检查只说明文档内部结构与引用，不代替官方 CLI、编译或协议测试。 + +## 尚未纳入强承诺的扩展 + +实时官方索引还可能包含新渠道、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 0000000000000000000000000000000000000000..85d0d48ed5a37e000c0e52847f530926ade63e82 GIT binary patch literal 3246 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 Date: Sun, 20 Sep 2026 23:59:41 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(g0):=20=E5=87=86=E5=85=A5=E8=AF=81?= =?UTF-8?q?=E6=8D=AE=E9=87=87=E9=9B=86=E2=80=94=E2=80=94=E7=89=88=E6=9C=AC?= =?UTF-8?q?=E9=94=81=E5=AE=9A=E3=80=81=E4=B8=89=E5=88=86=E6=94=AF=20codegr?= =?UTF-8?q?aph=E3=80=81=E6=9E=84=E5=BB=BA/=E6=B5=8B=E8=AF=95=E7=9F=A9?= =?UTF-8?q?=E9=98=B5=E3=80=81=E8=83=BD=E5=8A=9B=E6=B8=85=E5=8D=95=E3=80=81?= =?UTF-8?q?=E5=AE=98=E6=96=B9=20OpenSpec=20strict=20=E6=A0=A1=E9=AA=8C=206?= =?UTF-8?q?/6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 任务 1.2/1.3/2.1/3.3/3.4 完成并附证据工件（evidence/） - 1.1/2.2/2.3/2.4/3.1/3.2/3.5 标注人审或环境阻塞原因，G1 编码保持阻断 --- ...-1074-40c8-8d54-eb7e99fcf5d6.continue.json | 1 + .../evidence/2026-09-20-precursor-evidence.md | 39 +++++++++++++++++++ .../evidence/capability-inventory.json | 24 ++++++++++++ .../evidence/version-lock.md | 22 +++++++++++ .../tasks.md | 16 +++++--- 5 files changed, 97 insertions(+), 5 deletions(-) create mode 100644 .mimosa/hook-state/sess_aba26ad0-1074-40c8-8d54-eb7e99fcf5d6.continue.json create mode 100644 openspec/changes/establish-sdk-compatibility-governance/evidence/2026-09-20-precursor-evidence.md create mode 100644 openspec/changes/establish-sdk-compatibility-governance/evidence/capability-inventory.json create mode 100644 openspec/changes/establish-sdk-compatibility-governance/evidence/version-lock.md 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 new file mode 100644 index 0000000..0880c80 --- /dev/null +++ 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"} \ No newline at end of file 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/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/version-lock.md b/openspec/changes/establish-sdk-compatibility-governance/evidence/version-lock.md new file mode 100644 index 0000000..99ffe78 --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/evidence/version-lock.md @@ -0,0 +1,22 @@ +# 版本锁定记录（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 机器可读制品， +协议字段以文档 + 真实 Gateway 观察（任务 3.1，未执行）为准。人审通过前 G1 编码保持阻断。 diff --git a/openspec/changes/establish-sdk-compatibility-governance/tasks.md b/openspec/changes/establish-sdk-compatibility-governance/tasks.md index 3d42a13..1e69e18 100644 --- a/openspec/changes/establish-sdk-compatibility-governance/tasks.md +++ b/openspec/changes/establish-sdk-compatibility-governance/tasks.md @@ -5,12 +5,12 @@ ## 1. 评审与版本准入 - [ ] 1.1 评审 GOV-01 至 GOV-04 的八个场景和六组变更边界；验收：有范围、依赖、优先级、人审记录，不把文档生成记录当作批准。 -- [ ] 1.2 选择可获得的 OpenClaw 精确版本／提交与构建来源；验收：形成版本锁定记录及对应协议来源，未锁定时后续实施保持阻断。 -- [ ] 1.3 在独立检出目录核对三条 SDK HEAD、现有指令和代码图；验收：记录 codegraph 版本、实际执行命令与索引/查询结果；不支持 Java 或执行失败时明确标注，并保留源码核对证据，禁止冒充代码图结果。 +- [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. 能力证据和兼容治理 -- [ ] 2.1 为 GOV-01、GOV-04 建立机器可读的能力、版本和证据清单；验收：能区分静态存在、部分实现、CLI 透传、未封装、未验证与不适用，并演示缺失证据不能被标记为 live-pass。 +- [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 和获准差异清单；验收：同一行为具有共同场景标识，JSON 包名和 JDK 差异不被误判为功能分叉，行为差异不能被全局忽略。 - [ ] 2.3 为 GOV-03 建立规范评审与归档检查步骤；验收：DRAFT、REVIEWED、IMPLEMENTED、VERIFIED 与 ARCHIVED 分开，未执行任务和缺证据场景可阻止本项目归档流程。 - [ ] 2.4 逐项映射 traceability 中 GOV-01-S1 至 GOV-04-S2；验收：八个场景均有对应检查或人工审核记录，重写 README 不得替代证据校验。 @@ -19,6 +19,12 @@ - [ ] 3.1 对锁定 Gateway 执行基础健康、认证成功及授权拒绝检查；验收：记录真实目标版本、认证模式及脱敏结果，现有缺陷如实登记，不以消除尚未实施功能的失败为本阶段前提。 - [ ] 3.2 修正文档中的版本、JDK、依赖和支持等级漂移；验收：逐分支核对 pom、README、发布说明，快照版本和未验证状态一致，无声称全量支持的空泛结论。 -- [ ] 3.3 记录实际 JDK／Maven／依赖来源与构建结果；验收：每条分支都有独立结果，环境不足标为 BLOCKED，治理变更无运行资源触点时明确记录资源测试不适用原因。 -- [ ] 3.4 使用已固定版本的官方 OpenSpec CLI 校验全部变更并保存输出；验收：validate --all --strict --no-interactive --json 成功，不用自定义结构检查冒充官方校验。 +- [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.1、3.2、3.5——原因逐条见 +evidence/2026-09-20-precursor-evidence.md「阻塞项」。G1 编码保持阻断，待人审批准。