diff --git a/project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md b/project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md index 12cd0666..26ee6a7e 100644 --- a/project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md +++ b/project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md @@ -38,8 +38,8 @@ HWLAB 的中心目标是把真实硬件资源、Agent 执行、Harness/RL 验收 - 真实硬件资源池：板卡、probe、HWPOD 节点、设备注册、占用、健康、可用性和原始硬件事实。 - Agent 执行编排：Code Agent、AgentRun、workspace、session、provider profile、任务生命周期和任务恢复。 -- Harness/RL 验收闭环：harness、CaseRun、ioProbe、执行事实、评估、回放、训练反馈和 RL 闭环。 -- 用户入口：Web、CLI、HTTP API、SDK/IDE 插件、webhook、公开文档、兼容性、任务入口和结果获取。 +- Harness/RL 验收闭环：harness、CaseRun、HWPOD 观测引用、执行事实、评估、回放、训练反馈和 RL 闭环。 +- 用户入口：Web、CLI、HTTP API、兼容性、任务入口、状态查看和结果获取。 - 用户与运营管理：用户、注册登录、权限、API key、credit、usage、billing、admin 和租户隔离。 - 系统可用性与服务保障：入口可访问、任务可恢复、资源使用可控、运行状态可观察和故障可处理。 @@ -60,7 +60,7 @@ HWLAB 的中心目标是把真实硬件资源、Agent 执行、Harness/RL 验收 | 硬件池 | 管理真实硬件资源身份、能力声明、占用释放、健康状态和原始硬件事实的内部模块。 | | Agent编排 | 管理 Code Agent、AgentRun、workspace、session、provider profile、任务生命周期和任务恢复的内部模块。 | | HarnessRL | 将硬件执行结果转化为执行事实、aggregate、评估、回放和训练反馈的内部模块。 | -| 客户端 | 面向用户或外部系统的 Web、CLI、HTTP API、SDK/IDE 插件、webhook 和公开文档入口。 | +| 客户端 | 面向用户的 Web、CLI 和 HTTP API 入口。 | | 用户管理 | 管理用户身份、权限、API key、credit、usage、billing、admin 和租户隔离的内部模块。 | | 平台运维 | 管理 CI/CD、git mirror、YAML-first 配置、Secret 下发、rollout、observability、GC 和平台发布的内部模块。 | | 执行事实 | 可审计、可复验的硬件执行材料，包括硬件事实、执行 trace、ioProbe 数据、case registry、评估结果和必要日志摘要。 | @@ -73,11 +73,11 @@ HWLAB 的中心目标是把真实硬件资源、Agent 执行、Harness/RL 验收 | 边界项 | 内容 | | --- | --- | -| 外部使用者 | 硬件研发用户、训练任务、外部自动化系统、平台管理员。 | +| 外部使用者 | 硬件研发用户、训练任务、平台管理员。 | | 外部输入 | 硬件研发任务、源码或工程 workspace、目标设备或 HWPOD 选择、构建/下载/调试/采样指令、用户身份凭据、API key、额度和资源约束。 | | 受控资源 | 真实板卡、debug probe、io probe、HWPOD node、Agent 执行环境、provider profile、用户账号、额度和任务产物存储。 | | 外部输出 | 任务状态、执行结果、构建/下载/调试产物、硬件采样数据、评估摘要、错误语义、usage/credit 记录和可复验运行记录。 | -| 用户接口 | Web、CLI、HTTP API、SDK/IDE 插件、webhook。 | +| 用户接口 | Web、CLI、HTTP API。 | | 硬件接口 | HWPOD spec、HWPOD 工具、HWPOD 服务、AI 网关、debug probe、UART、board-comm、ioProbe。 | | 系统边界 | HWLAB 负责把用户任务连接到受控 Agent 和真实硬件，并返回可理解、可审计、可复用的结果；不替代用户对硬件设计目标、工程代码正确性和业务取舍的判断。 | @@ -89,8 +89,8 @@ L1 划分保持现有六个内部能力模块；本章同时作为内部模块 | --- | --- | --- | --- | --- | --- | | PJ2026-0101 | 硬件池 | [PJ2026-0101 硬件池](PJ2026-0101-hardware-pool.md) | 板卡、探针、HWPOD node、设备注册、资源占用、设备健康、可用性 | [平台运维](PJ2026-0106-platform-ops.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) | | PJ2026-0102 | Agent编排 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | Code Agent、AgentRun、workspace、session、provider profile、任务生命周期、任务恢复 | [硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md)、[用户管理](PJ2026-0105-user-management.md) | [HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) | -| PJ2026-0103 | HarnessRL | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | harness、CaseRun、ioProbe、执行事实、评估、回放、训练反馈、RL 闭环 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) | -| PJ2026-0104 | 客户端 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | Web、CLI、HTTP API、SDK/IDE 插件、webhook、公开文档、兼容性、用户任务入口与结果获取 | [用户管理](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) | 用户入口和集成调用 | +| PJ2026-0103 | HarnessRL | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | harness、CaseRun、HWPOD 观测引用、执行事实、评估、回放、训练反馈、RL 闭环 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) | +| PJ2026-0104 | 客户端 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | Web、CLI、HTTP API、兼容性、用户任务入口与结果获取 | [用户管理](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) | 用户入口 | | PJ2026-0105 | 用户管理 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | 用户、注册登录、权限、API key、credit、usage、billing、admin、租户隔离 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | | PJ2026-0106 | 平台运维 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | CI/CD、git mirror、YAML-first、Secret 下发、rollout、observability、GC、平台发布 | 全部 L1 的发布/配置/观测需求 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) | @@ -138,11 +138,11 @@ HarnessRL 负责执行事实、aggregate、评估、回放和训练反馈。硬 | --- | --- | --- | --- | | HWLAB-L0-REQ-004 | 统一客户端入口 | [PJ2026-0104 客户端](PJ2026-0104-client.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) | -HWLAB 应提供统一客户端入口，使 Web、CLI、API、SDK/IDE plugin 和 Webhook 围绕同一任务模型、权限模型和结果模型协同演进。 +HWLAB 应提供统一客户端入口，使 Web、CLI 和 HTTP API 围绕同一任务模型、权限模型和结果模型协同演进。 -统一客户端入口要求不同用户界面共享同一任务、权限、错误和结果语义。Web、CLI、API 和 SDK 可以有不同交互形态，但不能各自定义一套状态机、错误口径或结果读取路径。 +统一客户端入口要求不同用户界面共享同一任务、权限、错误和结果语义。Web、CLI 和 HTTP API 可以有不同交互形态，但不能各自定义一套状态机、错误口径或结果读取路径。 -客户端负责 Web、CLI、HTTP API、SDK/IDE 插件、webhook 和公开文档的一致入口。用户管理提供身份权限，Agent编排、硬件池、HarnessRL 和平台运维提供后端能力；客户端不重新定义这些后端事实。 +客户端负责 Web、CLI 和 HTTP API 的一致入口。用户管理提供身份权限，Agent编排、硬件池、HarnessRL 和平台运维提供后端能力；客户端不重新定义这些后端事实。 ### 6.5 HWLAB-L0-REQ-005 用户与运营管理 diff --git a/project-management/PJ2026-01/specs/PJ2026-0101-hardware-pool.md b/project-management/PJ2026-01/specs/PJ2026-0101-hardware-pool.md index 215806b8..7a9ad9c8 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0101-hardware-pool.md +++ b/project-management/PJ2026-01/specs/PJ2026-0101-hardware-pool.md @@ -46,7 +46,7 @@ - Agent run、command、session、provider profile 和 workspace 生命周期归 [Agent编排](PJ2026-0102-agent-orchestration.md)。 - CaseRun 评价、pass/fail、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。 -- Web、CLI、API、SDK 和 Webhook 的通用用户入口体验归 [客户端](PJ2026-0104-client.md)。 +- Web、CLI 和 HTTP API 的通用用户入口体验归 [客户端](PJ2026-0104-client.md)。 - 用户身份、API key、额度、账本和租户策略归 [用户管理](PJ2026-0105-user-management.md)。 - CI/CD、Git mirror、Secret、发布、公开入口和运行保障归 [平台运维](PJ2026-0106-platform-ops.md)。 diff --git a/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md b/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md index b1fbe57c..8d7f00dc 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md +++ b/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md @@ -46,7 +46,7 @@ Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执 - HWPOD 资源身份、inventory、租约、健康和硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。 - CaseRun 评价、pass/fail、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。 -- Web、CLI、API、SDK 和 Webhook 的用户体验归 [客户端](PJ2026-0104-client.md)。 +- Web、CLI 和 HTTP API 的用户体验归 [客户端](PJ2026-0104-client.md)。 - 用户身份、API key、额度、账本和租户策略归 [用户管理](PJ2026-0105-user-management.md)。 - Git mirror、Secret sync、rollout、namespace、数据库和日志指标基础设施归 [平台运维](PJ2026-0106-platform-ops.md)。 - AgentRun 自身产品路线和内部执行基础设施归 `pikasTech/agentrun`。 diff --git a/project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md b/project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md index afc7f110..6ef50cb6 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md +++ b/project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md @@ -38,7 +38,7 @@ HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较 - CaseRun case definition、stage model、postValidation、run-local workspace 和 case registry 语义。 - HWPOD raw output、Agent trace、artifact、diff、final response 和硬件观测之间的验证事实关系。 -- ioProbe 外部观测模型，包括 probeId、单位、采样、统计和与硬件动作的关联。 +- CaseRun 对 HWPOD 服务返回观测事实的引用，包括 probeId、单位、采样、统计和与硬件动作的关联；ioProbe 是其中一种 HWPOD 观测输入。 - aggregate、评价、baseline、replay、失败分类和可复验比较。 - 训练反馈、失败标签、reward、prompt/skill/case 改进数据和 RL 闭环。 @@ -46,7 +46,7 @@ HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较 - 真实硬件资源、probe 能力、HWPOD node 和原始硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。 - Agent run、command、session、workspace 和 provider profile 生命周期归 [Agent编排](PJ2026-0102-agent-orchestration.md)。 -- Web、CLI、API、SDK 和 Webhook 的用户入口体验归 [客户端](PJ2026-0104-client.md)。 +- Web、CLI 和 HTTP API 的用户入口体验归 [客户端](PJ2026-0104-client.md)。 - 用户身份、额度、账本和租户策略归 [用户管理](PJ2026-0105-user-management.md)。 - CI/CD、registry 保留、日志基础设施和平台发布归 [平台运维](PJ2026-0106-platform-ops.md)。 @@ -57,7 +57,7 @@ HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较 | CaseRun | 按 case definition 执行硬件研发任务并形成 registry 记录的 Harness 运行。 | | case registry | CaseRun 的结构化结果登记，用于保存 case、run、stage、artifact 和评价关系。 | | aggregate | 面向人工和客户端的低噪声结果摘要，不替代原始执行事实。 | -| ioProbe | 对板外物理状态的外部观测探针，输出带单位、采样和统计语义的数据。 | +| ioProbe | 由 HWPOD 服务管理的板外物理状态观测探针，输出带单位、采样和统计语义的数据。 | | replay | 基于同一 case 和验证事实关系复核执行结果的能力。 | | 训练反馈 | 从成功/失败路径中沉淀出的 prompt、skill、case、reward 或策略改进材料。 | @@ -68,7 +68,7 @@ HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较 | 边界项 | 内容 | | --- | --- | | 外部使用者 | Agent编排、客户端、用户管理、硬件池和训练任务。 | -| 外部输入 | case definition、workspace commit、HWPOD raw output、Agent trace、artifact、diff、ioProbe samples、run context 和用户/资源摘要。 | +| 外部输入 | case definition、workspace commit、HWPOD raw output、HWPOD 服务观测结果、Agent trace、artifact、diff、run context 和用户/资源摘要。 | | 受控资源 | CaseRun 定义、case registry、aggregate、评价模型、replay 入口、训练反馈样本和失败标签。 | | 外部输出 | CaseRun 结果、aggregate、评价结论、replay 线索、失败分类、训练反馈和可复验的验证关系。 | | 用户接口 | CaseRun CLI/API、case registry、aggregate、评价/回放入口、Agent Review 后端语义。 | @@ -79,7 +79,7 @@ HarnessRL 负责把真实硬件执行组织成可审计、可复验、可比较 | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | | --- | --- | --- | --- | --- | --- | | PJ2026-010301 | CaseRun规格 | 本规格 6.1 | case definition、stage model、postValidation、registry 语义 | Agent编排、硬件池、平台运维 | 客户端、用户管理 | -| PJ2026-010302 | ioProbe建模 | 本规格 6.2 | 外部观测数据、单位、采样、统计和硬件动作关联 | 硬件池 | CaseRun、评价回放 | +| PJ2026-010302 | 观测引用 | 本规格 6.2 | CaseRun 中引用 HWPOD 服务返回的外部观测、单位、采样、统计和硬件动作关联 | [硬件池](PJ2026-0101-hardware-pool.md) 的 PJ2026-010103 HWPOD服务 | CaseRun、评价回放 | | PJ2026-010303 | 评估回放 | 本规格 6.3 | aggregate、baseline、judge、replay 和失败分类 | CaseRun、Agent编排、硬件池 | 客户端、训练反馈 | | PJ2026-010304 | 训练反馈 | 本规格 6.4 | reward、失败标签、prompt/skill/case 改进样本 | 评估回放、Agent编排 | Agent编排、用户管理 | @@ -95,15 +95,17 @@ HarnessRL 应定义 CaseRun 的 case definition、stage model、postValidation CaseRun 语义必须引用 Agent 执行上下文和硬件事实，但不接管这些事实的生产。Agent编排提供 run/session/workspace 指针，硬件池提供真实硬件输出，平台运维提供 registry 和运行支撑。 -### 6.2 HARNESS-L1-REQ-002 外部观测模型 +### 6.2 HARNESS-L1-REQ-002 CaseRun 观测引用 | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | -| HARNESS-L1-REQ-002 | 外部观测模型 | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[客户端](PJ2026-0104-client.md) | +| HARNESS-L1-REQ-002 | 观测引用 | [PJ2026-0103 HarnessRL](PJ2026-0103-harness-rl.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[客户端](PJ2026-0104-client.md) | -HarnessRL 应定义 ioProbe 外部观测模型，使外部读数具备 probeId、单位、采样、统计和硬件动作关联。 +HarnessRL 应在 CaseRun 语义中引用 HWPOD 服务提供的外部观测结果，使外部读数能够与 case stage、硬件动作、评价和回放关系稳定关联。 -外部观测模型必须区分板内 echo、日志输出和板外真实读数。硬件池负责 probe 能力和物理接入，HarnessRL 负责把外部读数转化为可评价的验证材料，客户端只负责展示。 +ioProbe 只是 HWPOD 观测输入的一种。probe 能力、probe 绑定、物理采样、HWPOD node 路由和原始硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md) 的 PJ2026-010103 HWPOD服务负责；HarnessRL 不自建 ioProbe 硬件模型，也不绕过 HWPOD 服务直接管理 probe。 + +HarnessRL 只负责把 HWPOD 服务返回的观测事实纳入 CaseRun stage、postValidation、评估和回放关系，并区分板内 echo、日志输出和板外真实读数。客户端只负责展示这些结果，不重新定义观测来源。 ### 6.3 HARNESS-L1-REQ-003 评估与回放 diff --git a/project-management/PJ2026-01/specs/PJ2026-0104-client.md b/project-management/PJ2026-01/specs/PJ2026-0104-client.md index 294fa46a..431da73f 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0104-client.md +++ b/project-management/PJ2026-01/specs/PJ2026-0104-client.md @@ -32,14 +32,13 @@ ### 2.1 目的 -客户端负责 HWLAB 面向用户和外部系统的统一入口，使 Web、CLI、HTTP API、SDK/IDE 插件、Webhook 和公开文档围绕同一任务模型、权限模型、资源模型和结果模型协同演进。 +客户端负责 HWLAB 面向用户的统一入口，使 Web、CLI 和 HTTP API 围绕同一任务模型、权限模型、资源模型和结果模型协同演进。 ### 2.2 范围内 - Cloud Web 工作台、登录后工作流、任务创建、会话入口、trace/result 展示和用户可见资源入口。 - `hwlab-cli`、HWPOD/CaseRun 相关用户命令的参数、输出、错误语义和脚本可用性。 -- HTTP API、WebSocket、SDK/IDE plugin、Webhook 和外部系统集成契约。 -- 公开文档、示例、兼容性说明和多客户端一致性。 +- HTTP API 的参数、schema、错误语义和多端一致性。 ### 2.3 范围外 @@ -55,9 +54,7 @@ | --- | --- | | Cloud Web | HWLAB 的 Web 用户入口，承载登录、工作台、任务、资源和管理页面。 | | hwlab-cli | HWLAB 命令行入口，用于脚本化访问 Agent、CaseRun、HWPOD、用户和管理能力。 | -| API 契约 | HTTP API、WebSocket 和错误语义的稳定调用约定。 | -| SDK/IDE 插件 | 外部开发工具对 HWLAB 能力的封装入口。 | -| Webhook | HWLAB 向外部系统发送事件或回调的集成方式。 | +| API 契约 | HTTP API 和错误语义的稳定调用约定。 | | 多客户端一致性 | 不同入口共享同一任务、权限、错误和结果语义。 | ## 4. 系统边界和接口 @@ -66,11 +63,11 @@ | 边界项 | 内容 | | --- | --- | -| 外部使用者 | 硬件研发用户、外部自动化系统、IDE/SDK 使用者、平台管理员。 | -| 外部输入 | 用户凭据、API key、任务请求、workspace/HWPOD 选择、Agent session 操作、CaseRun 操作、管理操作和外部回调配置。 | -| 受控资源 | Web 页面、CLI 命令、HTTP API、SDK/IDE 插件、Webhook、公开文档和示例。 | -| 外部输出 | 用户可见任务入口、资源入口、调用响应、错误语义、结果展示、Webhook 投递和公开文档。 | -| 用户接口 | Cloud Web、`hwlab-cli`、HTTP API、WebSocket、SDK/IDE 插件、Webhook。 | +| 外部使用者 | 硬件研发用户、自动化脚本使用者、平台管理员。 | +| 外部输入 | 用户凭据、API key、任务请求、workspace/HWPOD 选择、Agent session 操作、CaseRun 操作和管理操作。 | +| 受控资源 | Web 页面、CLI 命令和 HTTP API。 | +| 外部输出 | 用户可见任务入口、资源入口、调用响应、错误语义和结果展示。 | +| 用户接口 | Cloud Web、`hwlab-cli`、HTTP API。 | | 系统边界 | 客户端负责入口一致性和用户可见契约；不定义后端业务事实、硬件事实、评价语义、账本真相或发布机制。 | ## 5. 内部分工与规格索引 @@ -78,9 +75,8 @@ | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | | --- | --- | --- | --- | --- | --- | | PJ2026-010401 | Web工作台 | 本规格 6.1 | Cloud Web 用户工作流和页面入口 | 用户管理、Agent编排、硬件池、HarnessRL、平台运维 | 用户和管理员 | -| PJ2026-010402 | CLI入口 | 本规格 6.2 | 命令行参数、输出、错误和脚本可用性 | 全部业务 L1 | 用户脚本、自动化系统 | -| PJ2026-010403 | API契约 | 本规格 6.3 | HTTP API、WebSocket、schema、错误码和兼容性 | 用户管理、Agent编排、平台运维 | Web、CLI、SDK、Webhook | -| PJ2026-010404 | 外部集成 | 本规格 6.4 | SDK/IDE 插件、Webhook、公开文档和示例 | API契约、全部业务 L1 | 外部开发者和自动化系统 | +| PJ2026-010402 | CLI入口 | 本规格 6.2 | 命令行参数、输出、错误和脚本可用性 | 全部业务 L1 | 用户脚本、自动化脚本 | +| PJ2026-010403 | API契约 | 本规格 6.3 | HTTP API、schema、错误码和兼容性 | 用户管理、Agent编排、平台运维 | Web、CLI | ## 6. 原子需求 @@ -100,7 +96,7 @@ Web 工作台只承载用户交互和展示契约。身份真相来自用户管 | --- | --- | --- | --- | | CLIENT-L1-REQ-002 | CLI入口 | [PJ2026-0104 客户端](PJ2026-0104-client.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 能力。 +客户端应提供可脚本化的 CLI 入口，使用户和自动化脚本能用一致的参数、输出和错误语义访问 HWLAB 能力。 CLI 入口必须复用后端业务事实，不在命令行层重新定义 HWPOD、CaseRun、Agent session、用户额度或评价结果。命令行文本和 JSON 输出应服务于自动化使用和人工排障，但不替代业务模块的完成标准。 @@ -110,16 +106,6 @@ CLI 入口必须复用后端业务事实，不在命令行层重新定义 HWPOD | --- | --- | --- | --- | | CLIENT-L1-REQ-003 | API契约 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) | -客户端应定义 HTTP API、WebSocket、schema、错误码和兼容性契约，使 Web、CLI、SDK 和外部系统围绕同一接口语义集成。 +客户端应定义 HTTP API、schema、错误码和兼容性契约，使 Web、CLI 和自动化脚本围绕同一接口语义访问 HWLAB。 -API 契约负责调用形态、字段稳定性和错误表达，不拥有账号、任务、硬件或评价的业务真相。后端模块改变事实模型时，客户端负责把外部契约以一致方式暴露。 - -### 6.4 CLIENT-L1-REQ-004 外部集成与公开文档 - -| 编号 | 短名 | 主责模块 | 关联模块 | -| --- | --- | --- | --- | -| CLIENT-L1-REQ-004 | 外部集成 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | [用户管理](PJ2026-0105-user-management.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | - -客户端应提供 SDK/IDE 插件、Webhook 和公开文档，使外部开发者和自动化系统能够按稳定任务模型接入 HWLAB。 - -外部集成必须表达与 Web、CLI 和 API 相同的身份、任务、资源、错误和结果语义。公开文档只解释对外使用方式，不承载内部治理、阶段报告或执行流水。 +API 契约负责调用形态、字段稳定性和错误表达，不拥有账号、任务、硬件或评价的业务真相。后端模块改变事实模型时，客户端负责把 Web、CLI 和 HTTP API 的入口契约以一致方式暴露。 diff --git a/project-management/PJ2026-01/specs/PJ2026-0105-user-management.md b/project-management/PJ2026-01/specs/PJ2026-0105-user-management.md index 053a2c78..70d62604 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0105-user-management.md +++ b/project-management/PJ2026-01/specs/PJ2026-0105-user-management.md @@ -45,7 +45,7 @@ ### 2.3 范围外 -- Web、CLI、API、SDK 和 Webhook 的入口体验归 [客户端](PJ2026-0104-client.md)。 +- Web、CLI 和 HTTP API 的入口体验归 [客户端](PJ2026-0104-client.md)。 - Agent run、command、session、workspace 和 provider profile 生命周期归 [Agent编排](PJ2026-0102-agent-orchestration.md)。 - HWPOD 资源身份、硬件事实、租约和物理资源状态归 [硬件池](PJ2026-0101-hardware-pool.md)。 - CaseRun 评价、回放、训练反馈和执行结果语义归 [HarnessRL](PJ2026-0103-harness-rl.md)。 @@ -57,7 +57,7 @@ | --- | --- | | 用户 | HWLAB 中拥有身份、权限、额度和资源消费记录的主体。 | | 会话 | 用户完成身份认证后获得的登录状态和服务端可检查的访问上下文。 | -| API key | 用户或外部系统用于调用 HWLAB API 的凭据，与用户身份、scope 和额度约束绑定。 | +| API key | 用户或自动化脚本用于调用 HWLAB API 的凭据，与用户身份、scope 和额度约束绑定。 | | 权限 | 用户对管理操作、任务操作、资源操作和账单操作的访问许可。 | | 配额 | 用户在并发、频率、资源类型或资源数量上的可消费上限。 | | 计量账本 | 记录 reservation、usage、credit 增减和补偿关系的用户消费真相。 | @@ -69,7 +69,7 @@ | 边界项 | 内容 | | --- | --- | -| 外部使用者 | 硬件研发用户、外部自动化系统、平台管理员、Agent编排、客户端和需要授权判断的内部模块。 | +| 外部使用者 | 硬件研发用户、自动化脚本、平台管理员、Agent编排、客户端和需要授权判断的内部模块。 | | 外部输入 | 登录凭据、API key、权限请求、计划和配额配置、任务消费事件、硬件资源约束、管理员操作和充值/兑换请求。 | | 受控资源 | 用户记录、会话、API key、角色、计划、额度、credit ledger、usage record、billing summary、admin 操作记录和租户边界。 | | 外部输出 | 用户身份、会话状态、API key 摘要、授权预检结果、额度状态、usage/credit 记录、账单摘要、管理员查询结果和租户隔离判断。 | @@ -81,7 +81,7 @@ | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | | --- | --- | --- | --- | --- | --- | | PJ2026-010501 | 账号会话 | 本规格 6.1 | 用户注册、登录、登出、session 和身份 source-of-truth | 客户端入口、平台数据库与 Secret | 客户端、Agent编排、管理后台 | -| PJ2026-010502 | APIKey | 本规格 6.2 | API key 生命周期、scope、脱敏展示、轮换和调用身份绑定 | 账号会话、平台 Secret 支撑 | CLI、API、SDK、Agent编排 | +| PJ2026-010502 | APIKey | 本规格 6.2 | API key 生命周期、scope、脱敏展示、轮换和调用身份绑定 | 账号会话、平台 Secret 支撑 | CLI、API、Agent编排 | | PJ2026-010503 | 权限配额 | 本规格 6.3 | role、admin、plan、entitlement、quota 和资源授权预检 | 用户身份、硬件资源事实、平台配置 | Agent编排、硬件池、客户端 | | PJ2026-010504 | 计量账本 | 本规格 6.4 | credit ledger、reservation、usage record、幂等和补偿 | Agent/Harness 消费事件、平台数据库 | billing、admin、运营分析 | | PJ2026-010505 | 账单后台 | 本规格 6.5 | billing summary、admin 调账、报表、导出、充值和兑换 | 计量账本、账号权限、客户端入口 | 用户、管理员、运营流程 | @@ -105,7 +105,7 @@ | --- | --- | --- | --- | | USER-L1-REQ-002 | APIKey | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) | -用户管理应提供 API key 生命周期能力，使用户和外部系统能够创建、撤销、轮换并以受限 scope 调用 HWLAB 服务。 +用户管理应提供 API key 生命周期能力，使用户和自动化脚本能够创建、撤销、轮换并以受限 scope 调用 HWLAB 服务。 API key 必须绑定用户身份、权限和额度约束，并在展示和日志中只暴露安全摘要。客户端负责入口和输出形态，平台运维负责 Secret 运行支撑，业务模块只消费校验结果和调用身份。 diff --git a/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md b/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md index bdaa5927..ebcc772d 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md +++ b/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md @@ -51,7 +51,7 @@ - Agent run、command、session、workspace 和 provider profile 语义归 [Agent编排](PJ2026-0102-agent-orchestration.md)。 - HWPOD 资源、硬件事实和 probe 能力归 [硬件池](PJ2026-0101-hardware-pool.md)。 - CaseRun 评价、回放、训练反馈和执行结果语义归 [HarnessRL](PJ2026-0103-harness-rl.md)。 -- Web、CLI、API、SDK 和 Webhook 的用户入口体验归 [客户端](PJ2026-0104-client.md)。 +- Web、CLI 和 HTTP API 的用户入口体验归 [客户端](PJ2026-0104-client.md)。 ## 3. 术语表