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/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 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..4172c1b --- /dev/null +++ b/docs/openclaw-integration/traceability.md @@ -0,0 +1,134 @@ +# Requirement → Scenario → Task 追踪表 + +所有状态为 NOT_RUN；文档场景不是测试执行结果。 + +| 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 @@ +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 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 @@ +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 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 @@ +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 diff --git a/docs/openclaw-integration/validation-summary.md b/docs/openclaw-integration/validation-summary.md new file mode 100644 index 0000000..55895c9 --- /dev/null +++ b/docs/openclaw-integration/validation-summary.md @@ -0,0 +1,32 @@ +# 文档检查结果 + +检查对象：OpenSpec 文档包 0.1.0-draft；下述结果记录首次文档编制阶段，仓库打包仅调整索引路径并无损压缩详细 JSON 报告。 + +## 实际执行 + +使用本次编写的文档结构检查器，对全部生成文件检查必需产物、schema/metadata、proposal 与 capability 的一一对应、Purpose 长度、Requirement/Scenario 格式、规范关键词、任务验收条件、未勾选状态、全局 ID 唯一性、场景到任务的引用、依赖无环、相对链接和代码围栏。 + +结果：内部结构检查通过，0 项失败；精确检查数量以 validation-report/ 中保存的完整报告为准。 + +这不是官方 OpenSpec CLI 输出，也不是产品测试通过数。 + +| 交付项目 | 数量 | +|---|---:| +| OpenSpec changes | 6 | +| Capability specs | 21 | +| Requirements | 64 | +| Scenarios | 128 | +| 实施任务 | 97 | +| 已完成实施任务 | 0 | + +## 尚未执行 + +官方 OpenSpec CLI validate：NOT_RUN。当前环境未安装 openspec，可联网安装尝试的 npm registry 查询因 EAI_AGAIN/DNS 解析失败而停止。CLI 版本未固定，不能声称官方 strict 校验通过。 + +Maven 构建、codegraph 索引、真实 Gateway 集成、漏洞扫描、资源/堆分析：均为 NOT_RUN。首次文档编制阶段没有修改用户电脑、GitHub 仓库或 SDK 代码；本次文档提交不包含 SDK 实现。 + +## 阶段结论 + +文档结构及引用检查通过，内容保持 DRAFT / REVIEW_REQUIRED。目标 Gateway 版本锁定、官方 CLI 校验、人审及所有实施验收仍未完成。评审应先从 G0 兼容治理和 G1 现有协议修正开始，而不是直接执行 G4/G5 的全部功能扩展。 + +详细逐项输出见 [完整报告与恢复说明](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..2de84c7 --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/design.md @@ -0,0 +1,54 @@ +# 建立版本与三分支兼容治理 — 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 + +采用共同契约、分支独立证据的方式，不把三个分支合并成一条开发线，也不新增统一发行版本。共享 fixture 的期望语义保持一致；Java 8 语法、Jackson 2/3 包名和宿主扩展点的差异记录到兼容清单。 + +已读取的 SDK HEAD 可精确固定；在线 OpenClaw 文档不等于已测试发布版本。因此先允许文档评审，实施前必须选定可获得的 Gateway 精确版本／提交与构建来源，并核实其协议文件、方法、事件和权限。当前没有选择或测试该版本，状态为 BLOCKED_VERSION_PIN。 + +不把根 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。 + +## 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/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/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..1e69e18 --- /dev/null +++ b/openspec/changes/establish-sdk-compatibility-governance/tasks.md @@ -0,0 +1,30 @@ +# 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 和获准差异清单；验收：同一行为具有共同场景标识，JSON 包名和 JDK 差异不被误判为功能分叉，行为差异不能被全局忽略。 +- [ ] 2.3 为 GOV-03 建立规范评审与归档检查步骤；验收：DRAFT、REVIEWED、IMPLEMENTED、VERIFIED 与 ARCHIVED 分开，未执行任务和缺证据场景可阻止本项目归档流程。 +- [ ] 2.4 逐项映射 traceability 中 GOV-01-S1 至 GOV-04-S2；验收：八个场景均有对应检查或人工审核记录，重写 README 不得替代证据校验。 + +## 3. 基线验证与文档同步 + +- [ ] 3.1 对锁定 Gateway 执行基础健康、认证成功及授权拒绝检查；验收：记录真实目标版本、认证模式及脱敏结果，现有缺陷如实登记，不以消除尚未实施功能的失败为本阶段前提。 +- [ ] 3.2 修正文档中的版本、JDK、依赖和支持等级漂移；验收：逐分支核对 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.1、3.2、3.5——原因逐条见 +evidence/2026-09-20-precursor-evidence.md「阻塞项」。G1 编码保持阻断，待人审批准。 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/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..7bf7a67 --- /dev/null +++ b/openspec/changes/fix-openclaw-protocol-contracts/tasks.md @@ -0,0 +1,44 @@ +# 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）；验收：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。 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 @@ +