docs: 整合 HWLAB CLI 客户端规格

2026-06-15 02:11:14 +00:00
parent f3693bfd77
commit 5289f08682
4 changed files with 327 additions and 19 deletions
@@ -32,13 +32,14 @@

 ### 2.1 目的

-客户端负责 HWLAB 面向用户的统一入口，使 Web、CLI 和 HTTP API 围绕同一任务模型、权限模型、资源模型和结果模型协同演进。
+客户端负责 HWLAB 面向用户的统一入口，使 Web、HWLAB CLI 和 HTTP API 围绕同一任务模型、权限模型、资源模型、trace/result 模型和错误语义协同演进。

 ### 2.2 范围内

 - Cloud Web 工作台、登录后工作流、任务创建、会话入口、trace/result 展示和用户可见资源入口。
- `hwlab-cli`、HWPOD/CaseRun 相关用户命令的参数、输出、错误语义和脚本可用性。
- HTTP API 的参数、schema、错误语义和多端一致性。
+- HWLAB CLI 的运行端点解析、API key 鉴权入口、同源 API 调用、短连接命令、结构化输出、错误语义和脚本可用性。
+- 通过 HWLAB CLI 覆盖账号/额度、工作台、显式 Agent session、Agent 任务、trace/result、HWPOD/CaseRun 组合入口和必要管理入口的非视觉全流程复验。
+- HTTP API 的同源 path、schema、错误语义、鉴权主体和多端一致性。

 ### 2.3 范围外

@@ -53,9 +54,11 @@
 | 术语 | 定义 |
 | --- | --- |
 | Cloud Web | HWLAB 的 Web 用户入口，承载登录、工作台、任务、资源和管理页面。 |
-| hwlab-cli | HWLAB 命令行入口，用于脚本化访问 Agent、CaseRun、HWPOD、用户和管理能力。 |
+| HWLAB CLI | HWLAB 命令行入口，用于脚本化访问 Web 同源 API、Agent、CaseRun、HWPOD、用户和管理能力。 |
+| 同源 CLI | 与 Cloud Web 使用同一 Web origin、同一相对 API path 和同一用户身份语义的 HWLAB CLI 调用方式。 |
 | API 契约 | HTTP API 和错误语义的稳定调用约定。 |
 | 多客户端一致性 | 不同入口共享同一任务、权限、错误和结果语义。 |
+| 短连接命令 | 发起后快速返回可查询 ID 或紧凑结果，再通过 status、trace、result 或 watch 继续观察的 CLI 命令。 |

 ## 4. 系统边界和接口

@@ -64,10 +67,10 @@
 | 边界项 | 内容 |
 | --- | --- |
 | 外部使用者 | 硬件研发用户、自动化脚本使用者、平台管理员。 |
-| 外部输入 | 用户凭据、API key、任务请求、workspace/HWPOD 选择、Agent session 操作、CaseRun 操作和管理操作。 |
-| 受控资源 | Web 页面、CLI 命令和 HTTP API。 |
-| 外部输出 | 用户可见任务入口、资源入口、调用响应、错误语义和结果展示。 |
-| 用户接口 | Cloud Web、`hwlab-cli`、HTTP API。 |
+| 外部输入 | 用户凭据、API key、运行端点选择、任务请求、workspace/HWPOD 选择、Agent session 操作、CaseRun 操作和管理操作。 |
+| 受控资源 | Web 页面、HWLAB CLI 命令、HTTP API、共享 trace renderer 和同源 API 调用契约。 |
+| 外部输出 | 用户可见任务入口、资源入口、命令响应、HTTP 响应、错误语义、trace/result 摘要和结果展示。 |
+| 用户接口 | Cloud Web、HWLAB CLI、HTTP API。 |
 | 系统边界 | 客户端负责入口一致性和用户可见契约；不定义后端业务事实、硬件事实、评价语义、账本真相或发布机制。 |

 ## 5. 内部分工与规格索引
@@ -75,8 +78,8 @@
 | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
 | --- | --- | --- | --- | --- | --- |
 | PJ2026-010401 | Web工作台 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) | Cloud Web 用户工作流、会话输入、诊断反馈和响应式布局 | 用户管理、Agent编排、硬件池、HarnessRL、平台运维 | 用户和管理员 |
-| PJ2026-010402 | CLI入口 | 本规格 6.2 | 命令行参数、输出、错误和脚本可用性 | 全部业务 L1 | 用户脚本、自动化脚本 |
-| PJ2026-010403 | API契约 | 本规格 6.3 | HTTP API、schema、错误码和兼容性 | 用户管理、Agent编排、平台运维 | Web、CLI |
+| PJ2026-010402 | HWLAB CLI | [PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md) | 短连接命令、同源 API 调用、结构化输出、错误语义和非视觉全流程复验 | 全部业务 L1 | 用户脚本、自动化脚本、内测复现 |
+| PJ2026-010403 | API契约 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) | 同源 API path、schema、鉴权主体、错误码和兼容性 | 用户管理、Agent编排、硬件池、HarnessRL、平台运维 | Web、HWLAB CLI |

 ## 6. 原子需求

@@ -90,22 +93,28 @@

 Web 工作台只承载用户交互和展示契约。身份真相来自用户管理，任务事实来自 Agent编排，硬件事实来自硬件池，评价语义来自 HarnessRL，公开入口健康来自平台运维。具体工作台框架、会话输入、诊断反馈和响应布局由 [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) 约束。

-### 6.2 CLIENT-L1-REQ-002 CLI 入口
+### 6.2 CLIENT-L1-REQ-002 HWLAB CLI 入口

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| CLIENT-L1-REQ-002 | CLI入口 | PJ2026-010402 CLI入口 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[用户管理](PJ2026-0105-user-management.md) |
+| CLIENT-L1-REQ-002 | HWLAB CLI | [PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[用户管理](PJ2026-0105-user-management.md) |

-客户端应提供可脚本化的 CLI 入口，使用户和自动化脚本能用一致的参数、输出和错误语义访问 HWLAB 能力。
+客户端应提供可脚本化的 HWLAB CLI 入口，使用户和自动化脚本能用一致的运行端点、参数、输出和错误语义访问 HWLAB 能力。

-CLI 入口必须复用后端业务事实，不在命令行层重新定义 HWPOD、CaseRun、Agent session、用户额度或评价结果。命令行文本和 JSON 输出应服务于自动化使用和人工排障，但不替代业务模块的完成标准。
+HWLAB CLI 必须能以非视觉方式跑通内测和排障需要的完整用户流程：认证当前用户、恢复工作台、显式创建或选择 Agent session、提交任务、读取 result/trace、复现 Web trace renderer、触达 HWPOD/CaseRun 组合入口，并输出可继续查询的 sessionId、traceId、runId、commandId 或等价标识。
+
+CLI 入口必须复用后端业务事实，不在命令行层重新定义 HWPOD、CaseRun、Agent session、用户额度或评价结果。命令行文本和 JSON 输出服务于自动化使用和人工排障，但不替代业务模块的完成标准。

 ### 6.3 CLIENT-L1-REQ-003 API 契约

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| CLIENT-L1-REQ-003 | API契约 | PJ2026-010403 API契约 | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+| CLIENT-L1-REQ-003 | API契约 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |

-客户端应定义 HTTP API、schema、错误码和兼容性契约，使 Web、CLI 和自动化脚本围绕同一接口语义访问 HWLAB。
+客户端应定义 HTTP API、schema、错误码和兼容性契约，使 Web、HWLAB CLI 和自动化脚本围绕同一接口语义访问 HWLAB。

-API 契约负责调用形态、字段稳定性和错误表达，不拥有账号、任务、硬件或评价的业务真相。后端模块改变事实模型时，客户端负责把 Web、CLI 和 HTTP API 的入口契约以一致方式暴露。
+API 契约负责调用形态、字段稳定性和错误表达，不拥有账号、任务、硬件或评价的业务真相。后端模块改变事实模型时，客户端负责把 Web、HWLAB CLI 和 HTTP API 的入口契约以一致方式暴露。
+
+## 7. 过程控制
+
+本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。客户端方向的阶段活动材料应引用本规格和各 L2 规格，不在本规格正文中展开执行流水。
@@ -31,7 +31,7 @@

 Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同一 Web 工作面完成会话选择、任务输入、执行状态理解、结果查看和必要诊断。

-本课题的目标状态是：主任务入口优先、诊断信息低噪声、状态反馈及时、桌面和移动端都能直接找到输入区，并且用户可以从基本工作台发起最小 Agent 调用并获得可查询执行状态。
+本课题的目标状态是：主任务入口优先、诊断信息低噪声、状态反馈及时、桌面和移动端都能直接找到输入区，并且用户可以从基本工作台发起最小 Agent 调用并获得可查询执行状态。Web 工作台与 HWLAB CLI 必须共用同源 API、composer policy 和 trace renderer 语义，使浏览器问题可以通过同一运行端点的 CLI 非视觉复现。

 ### 2.2 范围内

@@ -40,6 +40,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
 - 基本工作台 Agent 调用，包括最小任务输入、发送、短返回执行标识、状态查询入口和失败原因展示。
 - 工作台诊断入口、运行状态摘要、probe/build/HWPOD/Agent 状态的低噪声展示方式。
 - 桌面多栏布局、侧栏折叠、移动端工作台布局和输入区可达性。
+- Web 与 HWLAB CLI 共用的 Code Agent composer policy、trace renderer 和同源 API 行为。
 - Web 入口对用户管理、Agent编排、硬件池、HarnessRL 和平台运维输出事实的展示契约。

 ### 2.3 范围外
@@ -61,6 +62,8 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
 | 诊断入口 | 用户主动打开的工作台状态详情入口，通常以 topbar 内的小型按钮或状态图标呈现。 |
 | 低噪声展示 | 诊断、trace、状态和辅助信息不抢占主任务区，也不伪装成用户或 Agent 正文。 |
 | 响应式工作台 | 同一工作台在桌面和移动端按不同可视空间重排，但仍优先保证任务输入和状态理解。 |
+| 同源业务入口 | Cloud Web 与 HWLAB CLI 通过同一 Web origin、相对 API path 和业务标识访问 HWLAB 能力的入口。 |
+| 共享 trace renderer | Web trace 面板和 HWLAB CLI `trace --render web` 共用的 trace row 转换语义。 |

 ## 4. 系统边界和接口

@@ -70,7 +73,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
 | --- | --- |
 | 外部使用者 | 硬件研发用户、平台管理员、需要通过浏览器提交或观察任务的操作人员。 |
 | 外部输入 | 登录后访问请求、页面导航、会话选择、任务文本、引导/取消/重试操作、诊断查看操作和管理入口点击。 |
-| 受控资源 | Cloud Web shell、工作台路由、会话面板、对话面板、命令输入区、诊断弹窗、导航和响应式布局。 |
+| 受控资源 | Cloud Web shell、工作台路由、会话面板、对话面板、命令输入区、诊断弹窗、导航、响应式布局、composer policy 和共享 trace renderer。 |
 | 外部输出 | 页面可见任务入口、会话状态、消息展示、命令反馈、诊断摘要、错误提示和可继续操作的 UI 状态。 |
 | 用户接口 | Cloud Web `/workbench` 及相关登录后页面。 |
 | 系统边界 | Web工作台负责浏览器入口的布局、交互和展示契约；不拥有账号、Agent、硬件、评价或发布事实，只消费这些模块的服务端输出并以一致、低噪声、可操作的方式呈现。 |
@@ -83,6 +86,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同
 | PJ2026-01040102 | 会话输入 | 本规格 6.2 | 会话选择、消息展示、命令输入和任务操作反馈 | Agent编排、用户管理 | 用户任务提交和继续操作 |
 | PJ2026-01040103 | 诊断反馈 | 本规格 6.3 | 诊断入口、状态摘要和低噪声详情展示 | Agent编排、硬件池、HarnessRL、平台运维 | 用户排障、管理员观察 |
 | PJ2026-01040104 | 响应布局 | 本规格 6.4 | 桌面多栏、侧栏折叠、移动端主任务区优先和输入区可达 | 全部工作台子模块 | 桌面和移动端用户 |
+| PJ2026-01040105 | 同源体验 | 本规格 6.5 | Web 与 CLI 共享 composer policy、trace renderer 和同源 API 行为 | HWLAB CLI、API契约、Agent编排 | Web/CLI 排障和内测复现 |

 ## 6. 原子需求

@@ -125,3 +129,17 @@ Web工作台应提供低噪声诊断反馈，使用户或管理员可以主动
 Web工作台应在桌面和移动端保持主任务区可用：桌面端可以展示会话、对话和辅助资源多栏布局，移动端必须优先展示 topbar、对话和命令输入区。

 响应布局负责把辅助面板、侧栏和诊断信息按可视空间收起、折叠或隐藏，使用户不需要滚动穿过导航和辅助面板才能找到输入区。桌面侧栏折叠必须真实释放宽度；移动端应避免页面外层滚动成为主要操作路径，主任务区内部可以按需要滚动。
+
+### 6.5 CLIENT-WB-REQ-005 同源体验
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-WB-REQ-005 | 同源体验 | PJ2026-01040105 同源体验 | [PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
+
+Web工作台应与 HWLAB CLI 共享 Code Agent composer policy、trace renderer 和同源 API 语义，使浏览器工作流问题能用同一运行端点的 CLI 非视觉复现。
+
+Web只负责浏览器交互与展示；CLI负责命令入口和结构化输出；API契约负责 path、schema 和错误语义；Agent编排负责执行事实。Web trace row 错乱、final response 缺失或发送状态异常等问题，应能先通过 CLI `trace --render web`、同源 request/rpc 和显式 Agent session 命令定位到共享 renderer、API 契约或浏览器表现层，不能让 Web 和 CLI 各自维护一套 trace 解释。
+
+## 7. 过程控制
+
+本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。
@@ -0,0 +1,142 @@
+# PJ2026-010402 HWLAB CLI
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010402 HWLAB CLI 需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010402 |
+| 短名 | HWLAB CLI |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB CLI 的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+HWLAB CLI 负责提供 Cloud Web 的非视觉同源业务入口，使用户、管理员和自动化脚本能够用短连接命令完成认证、工作台恢复、Agent session、任务提交、trace/result、HWPOD/CaseRun 组合入口和管理能力的真实复验。
+
+本课题的目标状态是：完整 HWLAB 内测和排障流程可以通过 CLI 从同一个运行端点跑通一遍；CLI 输出足够短、结构化、可继续查询，并且不绕过 Web/API 用户路径去直连内部服务、数据库、Kubernetes 或临时 fixture。
+
+### 2.2 范围内
+
+- 运行端点解析、lane/namespace 锁定、短连接行为和 fail-closed 语义。
+- CLI API key 鉴权入口、Web session 诊断边界和凭据脱敏输出。
+- `client auth`、`request`、`rpc`、`access`、`provider-profiles`、`workbench`、`agent`、`gateway`、`harness` 等同源业务命令的命令形态、输出和错误语义。
+- 显式 Agent session 创建、选择、状态、send、result、trace、inspect、steer、cancel 和 composer policy 等非视觉入口。
+- CaseRun 和 HWPOD 相关组合入口的身份、trace/result 和下一步命令提示；具体 HWPOD 语义和 CaseRun 评价由对应模块负责。
+- JSON 输出、默认摘要、`--full`/`--raw` 渐进披露、错误分类和敏感值不输出。
+
+### 2.3 范围外
+
+- HWPOD spec、设备身份、租约、node health 和硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。
+- HWPOD 工具的硬件动作语义归 [PJ2026-010102 HWPOD工具](PJ2026-010102-hwpod-tools.md)。
+- AgentRun run、command、runner job、session continuation 和 provider profile runtime 归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
+- CaseRun 定义、registry、评价、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。
+- 用户、组织、API key、额度、usage 和权限真相归 [用户管理](PJ2026-0105-user-management.md)。
+- 发布流水、GitOps、Secret 下发、FRP、Caddy 和 Prometheus 运维监控归 [平台运维](PJ2026-0106-platform-ops.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| 同源 CLI | 通过 Cloud Web origin 和相对 API path 访问 HWLAB 的命令行入口，与浏览器使用同一业务路径和错误语义。 |
+| 短连接命令 | 快速返回命令结果、查询标识或下一步命令的 CLI 调用，不用单个命令长期阻塞等待完整执行。 |
+| 运行端点解析 | 根据运行 lane、namespace 或受控环境声明解析 Web/API endpoint，并在锁定状态下拒绝人工 URL 覆盖。 |
+| 显式 Agent session | 用户明确创建或选择的 Code Agent session，是普通 `send` 的前置条件。 |
+| Web renderer | Web trace 展示和 CLI `trace --render web` 共同使用的 trace row 转换语义。 |
+| 组合入口 | 上层 CLI 只返回 ID、摘要和下一步命令，完整业务语义继续交给已有 HWPOD、Agent 或 CaseRun 入口。 |
+
+## 4. 系统边界和接口
+
+本规格把 HWLAB CLI 作为客户端方向下的命令行入口课题看待；本章只描述输入、输出和责任边界。
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 硬件研发用户、平台管理员、自动化脚本、内测执行者和排障人员。 |
+| 外部输入 | API key、运行端点选择、profile、请求 path、任务文本、sessionId、traceId、runId、caseId、HWPOD 选择和命令参数。 |
+| 受控资源 | CLI 命令树、运行端点解析、同源 HTTP 调用、结构化输出、状态文件摘要、trace renderer 调用和下一步命令提示。 |
+| 外部输出 | JSON 响应、HTTP route/status、sessionId、traceId、runId、commandId、错误分类、摘要 rows、脱敏凭据状态和可复制后续命令。 |
+| 用户接口 | `hwlab-cli client ...`、`hwlab-cli case ...`、HWPOD 工具组合入口。 |
+| 系统边界 | HWLAB CLI 负责命令入口、调用路径、输出和错误表达；不拥有账号、Agent、硬件、CaseRun 或发布事实。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01040201 | 端点鉴权 | 本规格 6.1 | 运行端点解析、API key 鉴权入口、Web session 诊断边界和脱敏输出 | 用户管理、平台运维 | 全部 CLI 命令 |
+| PJ2026-01040202 | 同源请求 | 本规格 6.2 | Cloud Web 相对 path、JSON-RPC、Admin Access、provider profile 和通用 request/rpc 命令 | API契约、用户管理 | Web 等价复验、自动化脚本 |
+| PJ2026-01040203 | Agent会话 | 本规格 6.3 | 显式 session、send、composer、steer、cancel 和短连接提交语义 | Agent编排、用户管理 | Web 工作台、内测任务 |
+| PJ2026-01040204 | Trace结果 | 本规格 6.4 | result/trace/inspect、Web renderer、sourceSeq 窗口和渐进披露 | Agent编排、Web工作台 | CaseRun、排障、阶段复现 |
+| PJ2026-01040205 | 全流程复验 | 本规格 6.5 | 用 CLI 串起账号、工作台、Agent、HWPOD/CaseRun 和管理能力的非视觉复验组合 | 全部业务 L1 | 内测、灰度、用户反馈复现 |
+
+## 6. 原子需求
+
+### 6.1 CLIENT-CLI-REQ-001 端点与鉴权
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-CLI-REQ-001 | 端点鉴权 | PJ2026-01040201 端点鉴权 | [用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+
+HWLAB CLI 应根据运行 lane、namespace 或受控环境声明解析目标 Web/API endpoint，并在端点锁定时拒绝人工 URL 覆盖，使 CLI 复验不会误打旧 DEV、legacy 或内部服务路径。
+
+CLI 鉴权入口只负责把用户提供的 API key 作为命令行调用凭据使用，并以脱敏方式输出 key presence、来源和 actor 摘要。API key 生命周期、用户身份和权限真相由用户管理负责；平台运维提供运行端点和公开入口支撑。
+
+### 6.2 CLIENT-CLI-REQ-002 同源请求
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-CLI-REQ-002 | 同源请求 | PJ2026-01040202 同源请求 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
+
+HWLAB CLI 应提供 Cloud Web 同源的 request、rpc、access、provider-profiles、workbench、gateway 和 harness 类命令，使非视觉复验能够访问与浏览器一致的业务 API、schema 和错误语义。
+
+同源请求不得把绝对 URL、内部 ClusterIP、Postgres、Kubernetes Service、Secret 或临时 fixture 当作正式用户入口。确需 Cloud API 直连的 gateway/HWPOD 诊断必须明确显示其诊断属性，不能替代 Web 用户流程通过结论。
+
+### 6.3 CLIENT-CLI-REQ-003 Agent 会话入口
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-CLI-REQ-003 | Agent会话 | PJ2026-01040203 Agent会话 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md) |
+
+HWLAB CLI 应提供显式 Code Agent session 创建、选择、状态、send、composer、steer 和 cancel 入口，使用户能够按与 Web 工作台一致的 session 语义提交任务和干预运行中任务。
+
+普通 `send` 必须绑定显式 session 或已显式选中的 session；session 缺失、failed、stale 或 canceled 时，CLI 应返回结构化 blocker 和下一步命令，不得自动创建、滚动或替换 session。AgentRun 执行生命周期和 provider profile runtime 事实仍由 Agent编排负责。
+
+### 6.4 CLIENT-CLI-REQ-004 Trace 与结果
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-CLI-REQ-004 | Trace结果 | PJ2026-01040204 Trace结果 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
+
+HWLAB CLI 应提供 result、trace、inspect 和 Web renderer 等入口，使用户能通过 traceId 查看终态结果、实时 trace 摘要、session 上下文、steer 归属和必要工具行。
+
+`trace --render web` 必须与 Web 工作台共享 trace row 语义，并支持默认摘要、sourceSeq 窗口、tail、tool summary 和完整展开。CLI 只呈现同一路径的 trace/result，不重新发明 final response、AgentRun events 过滤或 CaseRun aggregate 语义。
+
+### 6.5 CLIENT-CLI-REQ-005 全流程 CLI 复验
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-CLI-REQ-005 | 全流程复验 | PJ2026-01040205 全流程复验 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[用户管理](PJ2026-0105-user-management.md) |
+
+HWLAB CLI 应能串起一次完整非视觉业务复验：确认当前用户和额度边界、恢复账号工作台、显式创建 Agent session、提交嵌入式任务、读取 result/trace、通过 HWPOD 或 CaseRun 入口触达真实硬件能力，并把每一步的可查询标识返回给调用者。
+
+全流程复验是客户端入口能力，不是新的业务事实源。硬件池负责 HWPOD 和设备事实，Agent编排负责 run/command/session，HarnessRL 负责 CaseRun 和评价关系，用户管理负责账号和权限；CLI 只负责把这些能力组合成一致、可脚本化、可排障的用户入口。
+
+## 7. 过程控制
+
+本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。
@@ -0,0 +1,139 @@
+# PJ2026-010403 API契约
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010403 API契约需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010403 |
+| 短名 | API契约 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 API 契约的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 HTTP API 入口语义，使同一用户请求在 Web、CLI 和 HTTP 调用下使用一致的 path、schema、鉴权主体、错误语义和结果标识。
+
+本课题的目标状态是：客户端入口可以通过同源 API 证明业务路径是否可用；后端业务事实改变时，API 契约负责稳定暴露字段和错误，而不在客户端侧发明第二套事实模型。
+
+### 2.2 范围内
+
+- Cloud Web 同源相对 path、JSON-RPC envelope、REST path、route policy 和绝对 URL 禁止边界。
+- Web session、API key、AuthPrincipal、actor 摘要和权限错误在客户端入口中的表达。
+- Agent session、chat、steer、cancel、result、trace 和 inspect 的用户可见 API 形态。
+- Workbench workspace、Admin Access、provider profile、HWPOD node-ops、gateway 和性能摘要等入口的字段稳定性。
+- JSON 成功/失败响应、HTTP 状态、错误分类、脱敏、默认摘要和完整展开边界。
+
+### 2.3 范围外
+
+- 用户、组织、API key、额度、role、OpenFGA relation 和账本真相归 [用户管理](PJ2026-0105-user-management.md)。
+- AgentRun run、command、runner job、session continuation 和 provider runtime 归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
+- HWPOD 资源身份、硬件操作、node 路由和原始硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。
+- CaseRun、评价、aggregate、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。
+- 运行端点、FRP/Caddy、Secret、rollout 和 Prometheus 监控归 [平台运维](PJ2026-0106-platform-ops.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| 同源 API | Cloud Web origin 下的相对 HTTP API path，供浏览器和 HWLAB CLI 使用。 |
+| route policy | 哪些 path 可以通过 Cloud Web 代理、哪些只能作为显式 Cloud API 诊断或内部服务调用的边界规则。 |
+| AuthPrincipal | 后端根据 Web session 或 API key 恢复出的用户主体摘要。 |
+| 业务标识 | sessionId、traceId、runId、commandId、workspaceId、caseId 等用户可继续查询的稳定标识。 |
+| 错误语义 | HTTP status、错误码、blocker、failureKind、route 和下一步提示组成的可定位失败表达。 |
+
+## 4. 系统边界和接口
+
+本规格把 API契约作为客户端方向下的接口语义层看待；本章只描述输入、输出和责任边界。
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | Cloud Web、HWLAB CLI、自动化脚本、平台管理员和需要同源 API 的浏览器客户端。 |
+| 外部输入 | HTTP method、相对 path、JSON body、query、Web session cookie、Authorization header、traceId、sessionId、workspaceId 和业务参数。 |
+| 受控资源 | API path、schema、route policy、AuthPrincipal 摘要、错误码、响应摘要和兼容性契约。 |
+| 外部输出 | JSON 响应、HTTP status、route、actor、业务标识、错误分类、脱敏状态、trace/result 指针和下一步查询提示。 |
+| 用户接口 | Cloud Web 同源 API、HWLAB CLI 同源 request/rpc/client 命令、HTTP API。 |
+| 系统边界 | API契约负责接口形态和错误表达；不拥有用户、Agent、硬件、CaseRun、账本或发布事实。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01040301 | 同源路由 | 本规格 6.1 | Cloud Web 相对 path、JSON-RPC envelope、route policy 和绝对 URL 禁止边界 | 平台入口、Web工作台 | HWLAB CLI、Cloud Web |
+| PJ2026-01040302 | 鉴权主体 | 本规格 6.2 | Web session、API key、actor 摘要和权限错误表达 | 用户管理 | Web、CLI、业务 API |
+| PJ2026-01040303 | Agent接口 | 本规格 6.3 | session、chat、steer、cancel、result、trace 和 inspect API 形态 | Agent编排、用户管理 | Web工作台、HWLAB CLI |
+| PJ2026-01040304 | 资源接口 | 本规格 6.4 | workspace、access、provider、HWPOD node-ops、gateway 和性能摘要入口 | 全部业务 L1 | Web、CLI、admin |
+| PJ2026-01040305 | 错误输出 | 本规格 6.5 | JSON 成功/失败响应、错误码、route/status、脱敏和渐进披露 | 全部业务 L1 | 用户、脚本、排障 |
+
+## 6. 原子需求
+
+### 6.1 CLIENT-API-REQ-001 同源路由
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-API-REQ-001 | 同源路由 | PJ2026-01040301 同源路由 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+
+API契约应定义 Cloud Web origin 下的相对 path、JSON-RPC envelope 和 route policy，使浏览器与 HWLAB CLI 能通过同一同源入口访问业务 API。
+
+同源路由必须拒绝把绝对 URL、内部服务地址或旧运行面端口作为正式用户入口。平台运维提供公开入口和代理支撑；API契约只规定客户端可依赖的 path 和错误形态。
+
+### 6.2 CLIENT-API-REQ-002 鉴权主体
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-API-REQ-002 | 鉴权主体 | PJ2026-01040302 鉴权主体 | [用户管理](PJ2026-0105-user-management.md)、[PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md) |
+
+API契约应以 AuthPrincipal 摘要表达 Web session 和 API key 恢复出的当前用户，使 Web、CLI 和 HTTP API 可以一致处理未登录、无权限、账号禁用、额度不足和工具能力缺失。
+
+鉴权主体的真相由用户管理负责。API 响应只输出 actor、authMethod、requiredAuthMethod、role/status、scope 摘要和错误分类，不输出 session token、完整 API key、password hash、Secret value 或可复用凭据。
+
+### 6.3 CLIENT-API-REQ-003 Agent 用户接口
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-API-REQ-003 | Agent接口 | PJ2026-01040303 Agent接口 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) |
+
+API契约应定义显式 Agent session、chat、steer、cancel、result、trace 和 inspect 的用户可见 HTTP 形态，使 Web 和 HWLAB CLI 能围绕同一 sessionId、conversationId、threadId、traceId、runId 和 commandId 操作。
+
+Agent 接口不得通过 session latest、浏览器历史、旧 cache 或内部 manager 生成第二套 final response。Agent编排提供执行事实，用户管理校验 owner 和权限，客户端只稳定暴露用户入口。
+
+### 6.4 CLIENT-API-REQ-004 资源与管理接口
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-API-REQ-004 | 资源接口 | PJ2026-01040304 资源接口 | [硬件池](PJ2026-0101-hardware-pool.md)、[用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+
+API契约应定义 workbench workspace、Admin Access、provider profile、HWPOD node-ops、gateway 诊断和性能摘要等资源与管理入口，使 Web 和 HWLAB CLI 可以一致读取状态、提交操作和展示错误。
+
+资源与管理接口只定义调用形态和字段稳定性。HWPOD node-ops 的硬件语义归硬件池，provider profile runtime 归 Agent编排，权限和账号归用户管理，运行健康和公开入口归平台运维。
+
+### 6.5 CLIENT-API-REQ-005 错误与输出合同
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| CLIENT-API-REQ-005 | 错误输出 | PJ2026-01040305 错误输出 | [PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
+
+API契约应保证成功和失败都以可定位 JSON 形式表达，至少包含调用 route、HTTP status、错误码或 blocker、必要业务标识、脱敏 actor 或权限摘要，以及可继续查询的 result/trace/status 入口。
+
+默认响应不得输出爆炸或泄漏敏感值；需要完整 trace、原始响应或长日志时，必须通过显式展开参数、下载入口或已有业务产物获取。错误输出只负责说明失败，不替代缺失能力实现。
+
+## 7. 过程控制
+
+本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。