docs(openspec): add Hermes SDK optimization specs

Author: loong10k

docs/design/hermes-java-sdk-optimization-plan-v1.0.md

@@ -0,0 +1,131 @@
+# Hermes Java SDK · OpenSpec 计划与规范
+
+版本：V1.0；日期：2026-09-20；状态：**待实施的 OpenSpec 变更包**。
+
+本文件是总入口。四个变更使用官方默认 `spec-driven` 产物组织，每个有 proposal、design、tasks、逐能力 delta spec 和逐场景测试蓝图。已有技术方案保留为背景，不直接改名冒充 spec。
+
+**本次完成的是文档编写及有限的离线检查；不是 SDK 功能实现、真实联调或正式 OpenSpec CLI 校验通过。** 当前 CLI 下载受执行环境 DNS 限制，详细结果见 [验证报告](../../verification/openspec/REPORT.md)。没有远程提交，也没有在用户本机修改文件。
+
+## 1. 交付清单
+
+| Change | 能力域 | Requirement | Scenario | 待实施步骤 |
+|---|---:|---:|---:|---:|
+| `harden-hermes-transport` | 5 | 18 | 36 | 28 |
+| `complete-hermes-http-runtime` | 6 | 18 | 36 | 25 |
+| `enhance-hermes-cli-runtime` | 3 | 9 | 19 | 19 |
+| `add-hermes-acp-client` | 3 | 8 | 16 | 20 |
+
+本包共 17 个能力域、53 条 Requirement、107 个 Scenario、92 个待实施步骤。原方案的 28 个 H 任务和 28 个 T 验收编号全部保留映射，见 [traceability.md](traceability.md)。这些数字描述规划覆盖，不代表已实现/已测试的功能数量。
+
+## 2. 实施顺序与阶段门禁
+
+```text
+harden-hermes-transport
+        ↓ 正确性、身份与取消/所有权证据
+complete-hermes-http-runtime
+        ↓ Run/Responses/审批闭环与事实性观测
+ enhance-hermes-cli-runtime
+        ↓ 有界进程、JSONL 和平台回收
+   add-hermes-acp-client
+        ↓ 双向协议及权限互操作
+```
+
+这是项目级保守执行顺序，不是 OpenSpec CLI 自带的跨 change 调度。依赖也记录在 traceability.json；没有添加未经支持的 `.openspec.yaml` 依赖字段。四包可以同时评审，默认按上述顺序实施。CLI 的工程前置不要求运行时必须连接 HTTP。所有批次都执行三分支门禁，不把旧版本线测试拖到最后。
+
+| 批次 | 必须先证明 | 不在该批做 |
+|---|---|---|
+| 传输加固 | 可信本地无需测试旁路；Profile 不串用；标准帧正确；断线不重复 POST；公开取消与资源收敛 | 大升级依赖、全仓拆模块、ACP/A2A |
+| HTTP 闭环 | 提交→观察→审批→停止请求→真实终态；输出完整性与用量事实可解释 | 平台权限、账单定价、再实现 Agent Loop |
+| CLI 增强 | 退出前可消费事件；stdout/stderr/队列有界；Profile 不污染；回收按平台验证 | 自动浏览器授权、TUI 模拟、完整 ACP |
+| ACP | 真双向初始化/请求关联/权限应答；退出无悬挂；可选依赖不污染基础 SDK | 自动回退重做 prompt、宣称所有协议等价 |
+
+## 3. 规范基线和 ADDED 语义
+
+三个已观察 HEAD 均没有 openspec 根目录，见 [source-manifest.json](source-manifest.json)。因此这次建立的是新的规范基线，全部 delta 使用 `## ADDED Requirements`；不是宣称已有 HTTP/CLI 功能从未存在。提案中的 BREAKING 单独声明与现有代码的行为变化。
+
+`openspec/specs/` 当前只保留 `.gitkeep`。未来行为只写入 `openspec/changes/`，不预先复制到已实施基线，不为了产物“完整”提前归档或勾选任务。
+
+若把本包应用到更晚的分支且已经存在同名能力，先读取现有完整 spec 和 Scenario，转换对应 ADDED 为完整 MODIFIED 并重新校验；不要覆盖现有 config、AGENTS 或规范。
+
+## 4. 怎样阅读与执行
+
+先读该 change 的 proposal（为什么/范围），再读 specs（外部行为），再读 design（实现取舍、文件与接口），最后按 tasks 实施。`test-catalog.md` 将每个 Scenario 对应到拟新增测试文件、方法、输入和断言；不是已经运行的测试报告。
+
+每个数字任务都带验证条件。新增 API/类/测试是设计目标，不是现有可直接编译调用的接口。按照红→绿回归与最小改动推进；提交前审查 diff，将共同逻辑与 JDK/JSON 适配分开。当前任务均未勾选，因为目标 Hermes 与实现验证尚未完成。
+
+首批范围：原 H-001～H-004、H-101～H-106，以及当前包的 H-501～H-504 发布门禁。后续包里的 H-501～H-504 表示各批重复验收，不是要等到 ACP 才做基础检查。
+
+## 5. 三分支要求
+
+| 分支 | 已观察 HEAD | 要求维持的运行基线 |
+|---|---|---|
+| feature/1.0.x | 76710a9d7e72bd589d2244ecf9004a9bec3d3ed2 | Java 8 |
+| feature/2.0.x | c97b68698751b2560b2472ee96874ccb10494e46 | Java 17 |
+| feature/3.0.x | 3b3f148a09987442c71586cec809a62529f4c940 | Java 21 |
+
+基线来自原方案与本轮 GitHub 观察；实际 JDK/POM/依赖和目标服务端由 H-001 复核。三线共享 wire 样本与业务语义，不强求 Jackson/OkHttp import 或历史构造器字节完全相同。新增基础公开 API 不强制 record/sealed/Flow/虚拟线程，不新增 Spring/Reactor 强依赖。
+
+ACP 若不能满足某条线，隔离为可选适配范围并明确支持矩阵，不提高基础 SDK JDK。API Shape、Source Sync 和 fixtures hash 检查共同维护；仅在高 JDK 编译 --release 8 不足以证明 Java 8 运行支持。
+
+## 6. 验证与状态
+
+### 可直接运行的离线文档检查
+
+在本包根目录或应用后的仓库根目录执行：
+
+```bash
+python3 scripts/check-openspec-package.py --root . --json
+```
+
+它检查结构、标识、GIVEN/WHEN/THEN、需求/任务/原编号映射、相对链接和无环依赖，不等同于官方解析器、归档合并或业务测试。 实施开始后可加 `--allow-progress` 允许已有真实证据支持的勾选；该工具针对本变更集，新增/归档变更后应维护对应索引，不把它当通用 OpenSpec 校验器。
+
+### 官方 OpenSpec 检查
+
+使用已安装的官方 CLI；本包记录的目标版本为 1.13.1，官方文档要求 Node >=20.19。没有把该 Node 要求施加到 Java SDK 的运行时。
+
+```bash
+npm install -g @fission-ai/openspec@1.13.1
+bash scripts/validate-openspec-package.sh
+```
+
+脚本运行：
+
+```bash
+openspec --version
+openspec validate --all --strict --no-interactive --json
+openspec status --change harden-hermes-transport --json
+openspec status --change complete-hermes-http-runtime --json
+openspec status --change enhance-hermes-cli-runtime --json
+openspec status --change add-hermes-acp-client --json
+```
+
+本次没有成功运行这些官方命令。脚本在没有 CLI 时会非零退出，输出不冒充通过；不会自动安装依赖，不归档变更，也不修改任务完成状态。产物状态完整只表示 proposal/specs/design/tasks 已写出，不表示实现完成。
+
+### 代码与互操作验证
+
+由实施任务在三条真实 JDK 上运行 `mvn -B --no-transfer-progress clean verify` 和指定 contract 类。再执行固定版本 Hermes 的真实互操作及平台资源测试；本包尚未执行这些测试。原 CI 的 Maven verify 入口可作为参考，不把其历史绿色结果当成本批代码证据。
+
+## 7. 应用到仓库
+
+本文件包是仅新增路径的文档 overlay：openspec/、docs/openspec/、docs/design/ 中的方案副本、新校验脚本、verification/openspec/。不包含 SDK 源码、POM、根 README 覆盖、用户密钥或 node_modules。
+
+若使用随交付提供的 add-only patch，在目标 checkout 中先检查：
+
+```bash
+git status --short
+git apply --check /path/to/hermes-java-sdk-openspec-v1.0.patch
+git apply /path/to/hermes-java-sdk-openspec-v1.0.patch
+python3 scripts/check-openspec-package.py --root . --json
+```
+
+`/path/to/` 仅是补丁位置提示，替换为实际保存路径。应用前检查分支 HEAD 和已有文件；发生同名文件或已建规范时先合并，不加 --force 覆盖。补丁只在空隔离目录检查过语法/可应用性，不宣称已在用户三条真实 checkout 中应用。
+
+## 8. 归档与完成条件
+
+顺序为 proposal/spec review → 实现与三线测试 → 真实互操作/资源/迁移证据 → 官方 strict validate → 代码和规格一致性评审 → 明确批准发布 → archive。归档前每个能力保留完整 Purpose；不提前制造“已实施”的根 spec。
+
+发布不以任务数量或 Mock 绿色为依据。没有服务端版本、真实报文、JDK/OS 运行结果的支持声明必须留为未验证；详见 [协议采证门禁](protocol-evidence-gates.md)。
+
+## 9. 非目标和平台边界
+
+A2A、MCP Bridge、Dashboard/Admin、Browser Controller、Python Observer Bridge 另行立项。SDK 不直接依赖 Agent Fabric；平台适配器持久化审计、权限和费用规则。Agent-Job 与 Hermes Cron 同一任务只能有一个调度所有者，不能双方登记导致重复执行。工具事实、推理展示和最终答案不混淆，也不推断服务端未提供的内容。

docs/openspec/README.md

@@ -0,0 +1,17 @@
+# 实施前的协议采证门禁
+
+本文件将未确认的外部信息变成具体前置工作，不把未知问题藏进实现。待实施代码只需满足“不支持/未知”行为即可保持安全；不能提前承诺未固定 wire 的高级能力。
+
+| 门禁 | 需要固定的事实 | 产物 | 责任任务 | 未满足时 |
+|---|---|---|---|---|
+| G0 | 三分支源码、实际 JDK/Maven/依赖字节码 | verification/source-manifest.json | H-001 | 不声称三线构建通过 |
+| G1 | 授权目标 Hermes commit/version、启动方式与鉴权 | verification/server-compatibility.json | H-001/H-002 | 真实互操作保持未完成 |
+| G2 | API Chat/Responses/Run/Session 帧、终态、ID/游标 | src/test/resources/contracts/http/ 与 manifest | H-003/H-103/H-202 | 未确认解码能力为 UNKNOWN，禁止猜终态 |
+| G3 | 创建 Run 幂等键/载荷冲突/身份范围和 stop 应答 | 同上与运行控制 descriptor | H-203 | 不自动重试未知写，不提前报告停止 |
+| G4 | 审批原生挑战、决定、过期与拒绝表达 | approval descriptor/captures | H-204 | 不自动批准，不伪造 exactly-once |
+| G5 | 模型选择/会话/Jobs patch 和 capability/health 形状 | resources descriptor/captures | H-205 | 高层不支持或未知；raw 仍受安全约束 |
+| G6 | CLI 版本、只读帮助、机器模式、事件及退出码 | docs/compatibility/cli-command-matrix.md | H-301/H-302/H-304 | 不启动猜测命令或宣称交互完成 |
+| G7 | ACP 版本、framing、双向 RPC、能力、权限选项 | docs/compatibility/acp-contract.md | H-401 | 不发送猜测 RPC；基础 SDK 不受影响 |
+| G8 | Linux/macOS/Windows 所有权及后代回收能力 | verification/cli-runtime/ | H-303 | 未验证平台标 LIMITED/UNVERIFIED |
+
+门禁以固定来源、脱敏样本、可复现命令和测试结果为证据。不得为通过 CI 关闭全局权限控制或调用有副作用的生产工具；付费模型测试需显式预算和隔离环境。缺失真实实例不妨碍规格文档写作，但阻止相应实现/发布通过声明。

docs/openspec/protocol-evidence-gates.md

@@ -0,0 +1,99 @@
+{
+  "schema": "hermes-source-observation/v1",
+  "observation_date": "2026-09-20",
+  "repository": "easy-4-java/hermes-java-sdk",
+  "transport": "GitHub connector GET",
+  "branches": [
+    {
+      "branch": "feature/1.0.x",
+      "head": "76710a9d7e72bd589d2244ecf9004a9bec3d3ed2",
+      "required_java_baseline": 8,
+      "root_tree_url": "https://api.github.com/repos/easy-4-java/hermes-java-sdk/git/trees/76710a9d7e72bd589d2244ecf9004a9bec3d3ed2",
+      "root_paths": [
+        ".github",
+        ".gitignore",
+        ".mvn",
+        "LICENSE",
+        "README.md",
+        "README.zh-CN.md",
+        "maven",
+        "mvnw",
+        "mvnw.bat",
+        "mvnw.cmd",
+        "pom.xml",
+        "scripts",
+        "src"
+      ],
+      "response_truncated": false,
+      "openspec_root_present": false,
+      "note": "Java 基线沿用原方案；本次未执行 POM/依赖/JDK 构建验证"
+    },
+    {
+      "branch": "feature/2.0.x",
+      "head": "c97b68698751b2560b2472ee96874ccb10494e46",
+      "required_java_baseline": 17,
+      "root_tree_url": "https://api.github.com/repos/easy-4-java/hermes-java-sdk/git/trees/c97b68698751b2560b2472ee96874ccb10494e46",
+      "root_paths": [
+        ".github",
+        ".gitignore",
+        ".mvn",
+        "LICENSE",
+        "README.md",
+        "README.zh-CN.md",
+        "maven",
+        "mvnw",
+        "mvnw.bat",
+        "pom.xml",
+        "scripts",
+        "src"
+      ],
+      "response_truncated": false,
+      "openspec_root_present": false,
+      "note": "Java 基线沿用原方案；本次未执行 POM/依赖/JDK 构建验证"
+    },
+    {
+      "branch": "feature/3.0.x",
+      "head": "3b3f148a09987442c71586cec809a62529f4c940",
+      "required_java_baseline": 21,
+      "root_tree_url": "https://api.github.com/repos/easy-4-java/hermes-java-sdk/git/trees/3b3f148a09987442c71586cec809a62529f4c940",
+      "root_paths": [
+        ".github",
+        ".gitignore",
+        ".mvn",
+        "LICENSE",
+        "README.md",
+        "README.zh-CN.md",
+        "maven",
+        "mvnw",
+        "mvnw.bat",
+        "mvnw.cmd",
+        "pom.xml",
+        "scripts",
+        "src"
+      ],
+      "response_truncated": false,
+      "openspec_root_present": false,
+      "note": "Java 基线沿用原方案；本次未执行 POM/依赖/JDK 构建验证"
+    }
+  ],
+  "server_contract": {
+    "status": "NOT_PINNED",
+    "reason": "本次写规范；目标部署版本必须由 H-001 与协议分批采证固定"
+  },
+  "local_clone": {
+    "status": "FAILED",
+    "reason": "git clone could not resolve github.com in execution container"
+  },
+  "original_plan": {
+    "path": "docs/design/hermes-java-sdk-optimization-plan-v1.0.md",
+    "sha256": "92e94b92156ebf52fe03ede76f95a7cc9aa6b65473f6da9994a56b25a4f17b76"
+  },
+  "openspec_cli": {
+    "requested_version": "1.13.1",
+    "version_source": "https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/package.json",
+    "execution_status": "NOT_RUN",
+    "reason": "CLI not installed; npm registry request failed EAI_AGAIN"
+  },
+  "sdk_tests": "NOT_RUN",
+  "remote_writes": "NONE"
+}

docs/openspec/source-manifest.json

@@ -0,0 +1,30 @@
+# 来源、版本与证据边界
+
+## 已读取资料
+
+本包转换自用户会话中的《Hermes Java SDK 优化与能力补齐方案 V1.0》，原文保留在 [docs/design](../design/hermes-java-sdk-optimization-plan-v1.0.md)，SHA-256 见 [source-manifest.json](source-manifest.json)。该方案含 28 个 H 任务和 28 个 T 验收编号。
+
+本轮通过 GitHub 连接读取分支集合及三个指定 HEAD 的完整根 tree；它们均没有 openspec 根目录。树响应是完整根目录，并非用搜索无结果推断不存在。源码细节风险继承原方案的静态审计，本轮没有重新执行 SDK、codegraph 或真实 Hermes。
+
+| 资料 | 用途与边界 |
+|---|---|
+| [三分支观察清单](source-manifest.json) | 固定本次写作对象，不代表用户本机已 clone |
+| [OpenSpec 默认 schema](https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/schemas/spec-driven/schema.yaml) | proposal/specs/design/tasks，新增能力 Purpose 与 ADDED，要求和场景标题 |
+| [OpenSpec spec 模板](https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/schemas/spec-driven/templates/spec.md) | 四级 Scenario、规范强制词、可验证条件 |
+| [OpenSpec CLI 文档](https://openspec.dev/docs/cli) | validate/status、结构检查与归档边界 |
+| [OpenSpec package 描述](https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/package.json) | 本轮观察版本 1.13.1、Node >=20.19；npm 包本身未能下载验证 |
+| [OpenSpec 配置说明](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md) | config.yaml 中 schema/context/rules |
+
+这些官方文件读取于 2026-09-20，main 文档会变；运行正式 CLI 时以实际安装版本为准并记录版本。我们没有 vendoring 或改写 OpenSpec CLI，没有把自写检查器伪装为官方实现。
+
+## Hermes 依据的使用方式
+
+原方案附录中 C0～C5 为固定 SDK commit 源码，S1～S7 为 Hermes 官方 API/CLI/ACP/Cron/A2A/MCP/Profile 文档。用户给定全文入口为 <https://hermes-agent.nousresearch.com/docs/llms-full.txt>。
+
+本轮任务是将已形成方案转成行为规范，不额外宣称这些文档中的能力已经在目标服务部署、抓包或联调。任何 wire 字段、CLI 别名、ACP framing 或服务端终态须由实施前置任务固定。文档示例、人工样本、真实捕获在 fixtures manifest 中必须区分。
+
+## 当前验证边界
+
+离线检查只覆盖文档结构、编号、场景字段、任务/旧编号映射、相对链接、依赖无环与清单一致性；不执行 OpenSpec 官方解析器/归档合并，也不验证业务代码。官方 CLI 未安装；npm 访问 registry.npmjs.org 返回 EAI_AGAIN。此限制和实际离线检查结果记录在 verification/openspec/。
+
+本包没有提交 GitHub、没有改 SDK 源码、没有创建或归档已实现 spec。只在本次会话沙箱生成文档与校验工具。