From af7baca595858a0dbfdccef34eecc7dd16d5fdfe Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 15 Jun 2026 00:33:32 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=BF=81=E7=A7=BB=20AgentRun=20?= =?UTF-8?q?=E8=A7=84=E6=A0=BC=E5=88=B0=20OA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/unidesk-oa/SKILL.md | 6 +- .../specs/PJ2026-0102-agent-orchestration.md | 48 ++++--- .../specs/PJ2026-010201-agentrun-core.md | 135 +++++++++++++++++ .../specs/PJ2026-010202-runtime-assembly.md | 136 ++++++++++++++++++ .../specs/PJ2026-010203-queue-session.md | 125 ++++++++++++++++ .../specs/PJ2026-010204-backend-profile.md | 135 +++++++++++++++++ .../specs/PJ2026-010205-hwlab-dispatch.md | 134 +++++++++++++++++ .../specs/PJ2026-0106-platform-ops.md | 8 +- .../specs/PJ2026-010601-controlled-release.md | 128 +++++++++++++++++ ...2026-01060105-agentrun-v01-release-lane.md | 119 +++++++++++++++ .../specs/PJ2026-010602-source-sync.md | 127 ++++++++++++++++ ...2026-01060205-agentrun-v01-source-truth.md | 110 ++++++++++++++ .../PJ2026-01/specs/spec-governance.md | 8 ++ 13 files changed, 1198 insertions(+), 21 deletions(-) create mode 100644 project-management/PJ2026-01/specs/PJ2026-010201-agentrun-core.md create mode 100644 project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md create mode 100644 project-management/PJ2026-01/specs/PJ2026-010203-queue-session.md create mode 100644 project-management/PJ2026-01/specs/PJ2026-010204-backend-profile.md create mode 100644 project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md create mode 100644 project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md create mode 100644 project-management/PJ2026-01/specs/PJ2026-01060105-agentrun-v01-release-lane.md create mode 100644 project-management/PJ2026-01/specs/PJ2026-010602-source-sync.md create mode 100644 project-management/PJ2026-01/specs/PJ2026-01060205-agentrun-v01-source-truth.md diff --git a/.agents/skills/unidesk-oa/SKILL.md b/.agents/skills/unidesk-oa/SKILL.md index fb760493..45029364 100644 --- a/.agents/skills/unidesk-oa/SKILL.md +++ b/.agents/skills/unidesk-oa/SKILL.md @@ -9,7 +9,7 @@ description: UniDesk 项目管理运行技能。用户提到 UniDesk 项目管 ## 仓库 -- UniDesk 项目管理真相源：`/root/unidesk/project-management/PJ2026-01`，其中 `specs/PJ2026-01-HWLAB.md` 是 L0 总规格和项目索引，随 `pikasTech/unidesk` 的 `master` 分支版本化。 +- UniDesk 项目管理真相源：`/root/unidesk/project-management/PJ2026-01`，其中 `specs/PJ2026-01-HWLAB.md` 是 L0 总规格和项目索引，随 `pikasTech/unidesk` 的 `master` 分支版本化。AgentRun 作为 HWLAB Agent编排的执行基础设施归入 `PJ2026-0102` 及其平台运维支撑规格，不单独创建新的 L0 项目。 - 迁移前 HWLabOA 仓库：`/root/HWLabOA` 只作为历史材料和对照来源，不再作为 HWLAB Cloud M1 规格真相源。 - 使用 UniDesk GitHub CLI、修改本技能或修改项目管理文档前，必须在 `/root/unidesk` 执行 `git status --short --branch` 和 `git pull --ff-only origin master`。 @@ -19,6 +19,7 @@ description: UniDesk 项目管理运行技能。用户提到 UniDesk 项目管 - 将 GitHub issue 视为执行控制面、历史讨论入口和长证据承载处：状态、讨论、跨仓引用、PR 链接和收口证据可以在 issue 中流转，但规格正文不得只写在 issue 中。 - 长证据、trace、CaseRun registry、运行日志、历史 issue 摘要和证据索引保留在 GitHub issue 或具体执行 issue 中，禁止以 `evidence/` 目录或长证据文件形式污染 `project-management/PJ2026-01`。 - `project-management/PJ2026-01/specs/*.md` 规格文件不保留单独的迁移来源块；历史来源只写在修改历史 `v0.1` 的变更说明中，格式为 `迁移来源 /#`。规格文件引用其他规格必须使用同目录相对路径 Markdown 链接，禁止引用其他规格的 GitHub issue、证据 issue、PR 或裸 `#`。 +- AgentRun 仓库内 `docs/reference/spec-v01-*.md` 不再承载规格正文；迁移后只保留指向 UniDesk OA 规格的交叉引用 stub，避免 AgentRun repo 与 `project-management/PJ2026-01` 双份规格漂移。AgentRun 专项内容按职责落到 `project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md`、`project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md` 或 `project-management/PJ2026-01/specs/PJ2026-010602-source-sync.md` 及其 L3，不创建 `PJ2026-02`。 - 写入 GitHub issue/PR 正文或评论时，issue/PR 引用必须写成 `[#](https://github.com///issues/)` 或 `[#](https://github.com///pull/)`，显示短号、链接目标保留完整 URL；不要显示裸长链接、裸井号编号或 `owner/repo` 加井号编号。CLI 参数中的 `owner/repo#number` shorthand 只作为命令输入例外。 - 不要让日报或阶段报告成为总规划。阶段报告只总结相对总规格的移动，不能替代中心规划。 - 当任务缺少上级方向、验收标准或原始验证入口时，先归类为规划/调查，不要直接变成实现任务。 @@ -38,10 +39,13 @@ description: UniDesk 项目管理运行技能。用户提到 UniDesk 项目管 - 不要为了凑全局原子需求条数自动添加次要派生能力。证据收集、硬编码诊断、硬编码建议、任务状态收集、结果包/结果收集等需求，除非用户明确授意，不得写入 OA 规格或 L0 原子需求。 - 平台运维在 L0 中只能作为支撑后勤职责出现；对外需求应写成系统可用性、可恢复、资源可控等用户可感知能力，不写成“HWLAB 对外提供平台运维能力”。 - 单一主责、关闭验收、规格沉淀、回写和偏离判定是治理规则，不得伪装成 L0 原子需求。 +- L2 是稳定能力域，不是仓库文件名或原始 spec 文档一比一搬运目录。单个 L1 下的 L2 通常不超过 6 个；从仓库参考文档迁移过来的大量细项应合并到少量 L2，并把更细的服务、lane、source truth、验证切片放到 L3 或正文分工中。 +- 运维交付内容必须按职责归位：通用 CI/CD、发布判定、镜像 promotion 放到平台运维的发布流水；通用 Git mirror、source truth、GitOps branch、artifact catalog 放到源码同步；Secret/YAML/sourceRef/targetKey/fingerprint 放到 YAML运维。只有能抽象到多服务共用的规则才放通用 L2；AgentRun 固定 branch、namespace、Pipeline、GitOps path、真实 provider turn 等专项细节放到这些通用规格下的 AgentRun 专项 L3，`PJ2026-0102 Agent编排` 只引用这些支撑规格，不把运维后勤 L2 塞进 Agent编排。 ## HWLAB 标准 issue 锚点 - L0 总规格：`project-management/PJ2026-01/specs/PJ2026-01-HWLAB.md`，历史 issue `[#1194](https://github.com/pikasTech/HWLAB/issues/1194)`。 +- AgentRun 规格入口：`project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md`；核心 L2 为 `PJ2026-010201` AgentRun核心、`PJ2026-010202` Runtime装配、`PJ2026-010203` 队列会话、`PJ2026-010204` 后端Profile、`PJ2026-010205` HWLAB接入。发布/source 支撑入口为 `PJ2026-010601` 发布流水、`PJ2026-010602` 源码同步和 `PJ2026-010603` YAML运维，其中 AgentRun 专项 L3 只承载 AgentRun 固定 lane/source 事实。 - 长期导航面板：`[#645](https://github.com/pikasTech/HWLAB/issues/645)`（`HWLAB 长期总面板`）。这是面板，不是规格书。 - 当前 Cloud M1 阶段规格：`project-management/PJ2026-01/specs/stage-cloud-spec-20260601.md`，历史 issue `[#644](https://github.com/pikasTech/HWLAB/issues/644)`。 - 创建或更新 HWLAB 项目管理 issue 时，非平凡 L1/L2/L3/L4 工作都要链接回 `project-management/PJ2026-01` 中的对应规格文件，并保持 `[#645](https://github.com/pikasTech/HWLAB/issues/645)` 只作为导航索引。 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 814d419f..e7baedb4 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md +++ b/project-management/PJ2026-01/specs/PJ2026-0102-agent-orchestration.md @@ -37,8 +37,9 @@ Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执 ### 2.2 范围内 - HWLAB 入口到 AgentRun run、command、runner job 的提交、短返回、轮询和终态管理。 -- task、run、command、runner job、session、thread、conversation、cancel、timeout 和恢复语义。 +- Queue task、run、command、runner job、session、thread、conversation、cancel、timeout、恢复和 read cursor 语义。 - RuntimeAssembly 装配，包括 BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef、gitbundle、promptRefs、skills、tools、workspaceFiles、SecretRef、provider profile 和模型配置。 +- Backend adapter、Codex stdio backend、provider profile、profile 管理和 profile 隔离。 - workspace 物化、source commit、bundle 摘要、运行输入证明和下游可消费的执行事实指针。 - HWLAB 与 AgentRun 的职责边界、错误语义消费和跨模块交接。 @@ -48,8 +49,8 @@ Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执 - CaseRun 评价、pass/fail、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.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`。 +- 发布流水、Git mirror、source truth、Secret sync、rollout、namespace 和日志指标基础设施归 [平台运维](PJ2026-0106-platform-ops.md)，其中 AgentRun `v0.1` 发布细则见 [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)，源码真相见 [AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md)。 +- AgentRun 仓库中的实现、代码组织和运行面部署操作不替代本文档中的需求规格；仓库本地 SPEC 只保留到 OA 规格的交叉引用。 ## 3. 术语表 @@ -58,9 +59,11 @@ Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执 | run | AgentRun 中承载一次 Agent 执行生命周期的顶层资源。 | | command | run 内的一次用户或系统指令，具备独立终态和结果语义。 | | runner job | 实际执行 Agent command 的运行单元。 | +| Queue task | AgentRun Queue 中的任务资源，可被 dispatch 为 run/command/runner job。 | | SessionRef | 指向可续跑 Agent session/thread 的引用。 | | RuntimeAssembly | HWLAB 为 runner 准备镜像、profile、资源包、workspace、工具、Secret 和执行参数的装配结果。 | | ResourceBundleRef | 指向 gitbundle、工具、prompt、skill 和 workspaceFiles 的资源装配引用。 | +| Backend Profile | AgentRun 中选择具体 Codex-compatible provider/profile 的配置边界。 | ## 4. 系统边界和接口 @@ -79,47 +82,60 @@ Agent编排负责把用户、训练任务或系统任务送入受控 Agent 执 | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | | --- | --- | --- | --- | --- | --- | -| PJ2026-010201 | 任务生命周期 | 本规格 6.1、6.3 | 提交、run/command/runner job、session、cancel、timeout、恢复和终态 | 客户端入口、用户权限、硬件资源提示、平台运行面 | 客户端、HarnessRL、用户管理 | -| PJ2026-010202 | 资源装配 | 本规格 6.2、6.4 | RuntimeAssembly、ResourceBundleRef、provider profile、workspace materialization 和 SecretRef | 硬件池、平台运维、用户管理 | AgentRun runner、HarnessRL、客户端 | +| PJ2026-010201 | AgentRun核心 | [PJ2026-010201 AgentRun核心](PJ2026-010201-agentrun-core.md) | run、command、event、runner job、durable facts、terminal status 和 failureKind | 客户端入口、用户权限、平台运行面 | 队列会话、HWLAB接入、HarnessRL、客户端 | +| PJ2026-010202 | Runtime装配 | [PJ2026-010202 Runtime装配](PJ2026-010202-runtime-assembly.md) | BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef、SecretRef、gitbundle、AipodSpec 和 runtime home | [源码同步](PJ2026-010602-source-sync.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、硬件资源提示 | AgentRun核心、后端Profile、HWLAB接入 | +| PJ2026-010203 | 队列会话 | [PJ2026-010203 队列会话](PJ2026-010203-queue-session.md) | Queue task、attempt、Session API、read cursor、commander 和 scheduler deferred 边界 | AgentRun核心、Runtime装配 | 客户端、UniDesk Code Queue 迁移、HWLAB接入 | +| PJ2026-010204 | 后端Profile | [PJ2026-010204 后端Profile](PJ2026-010204-backend-profile.md) | Backend adapter、Codex stdio backend、provider profile、profile 管理、failureKind 和 redaction | Runtime装配、YAML运维、provider SecretRef | AgentRun核心、HWLAB接入 | +| PJ2026-010205 | HWLAB接入 | [PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md) | HWLAB dispatcher 到 AgentRun run/command/runner job 的映射、手动调度和结果转换 | 客户端、用户管理、硬件池、AgentRun核心、Runtime装配 | HWLAB Agent API、HarnessRL、客户端 | ## 6. 原子需求 -### 6.1 AGENT-L1-REQ-001 Agent 执行生命周期 +### 6.1 AGENT-L1-REQ-001 AgentRun 执行核心 | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | -| AGENT-L1-REQ-001 | 执行生命周期 | PJ2026-010201 任务生命周期 | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) | +| AGENT-L1-REQ-001 | 执行核心 | [PJ2026-010201 AgentRun核心](PJ2026-010201-agentrun-core.md) | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[发布流水](PJ2026-010601-controlled-release.md) | Agent编排应通过 AgentRun durable resource 模型创建和跟踪 Agent 执行，使 run、command 和 runner job 能短返回、可轮询、可取消、可超时收口并进入明确终态。 该能力定义任务从 HWLAB 入口进入执行面后的生命周期事实。客户端展示生命周期，用户管理提供提交前后的权限与额度约束，平台运维提供运行支撑；这些模块不重写 run/command/runner job 的执行事实。 -### 6.2 AGENT-L1-REQ-002 资源装配 +### 6.2 AGENT-L1-REQ-002 Runtime 装配 | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | -| AGENT-L1-REQ-002 | 资源装配 | PJ2026-010202 资源装配 | [硬件池](PJ2026-0101-hardware-pool.md)、[平台运维](PJ2026-0106-platform-ops.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | +| AGENT-L1-REQ-002 | Runtime装配 | [PJ2026-010202 Runtime装配](PJ2026-010202-runtime-assembly.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[源码同步](PJ2026-010602-source-sync.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | Agent编排应按 RuntimeAssembly 装配 BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef、workspace、tools、skills、promptRefs、provider profile 和 SecretRef。 资源装配必须能说明 runner 实际使用了哪个 repo/ref、actual commit、bundle、profile、session 和工具输入。硬件池提供 HWPOD hint 或分配结果，平台运维提供 Git mirror、Secret 和运行面支撑，HarnessRL 消费执行上下文。 -### 6.3 AGENT-L1-REQ-003 会话连续性 +### 6.3 AGENT-L1-REQ-003 队列与会话 | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | -| AGENT-L1-REQ-003 | 会话连续性 | PJ2026-010201 任务生命周期 | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md) | +| AGENT-L1-REQ-003 | 队列会话 | [PJ2026-010203 队列会话](PJ2026-010203-queue-session.md) | [客户端](PJ2026-0104-client.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) | -Agent编排应支持 SessionRef、thread continuation、session send、同 run 多 command 和 runner replacement，使用户任务可以在受控上下文中续跑。 +Agent编排应提供 Queue task、attempt、Session API、read cursor、commander 和 session send 能力，使用户任务可以进入队列、派发到 AgentRun 执行，并在受控会话中读取输出、trace、follow-up 和终态。 -会话连续性不得通过拼接历史 prompt 或伪造 resume 实现。无法续接时，Agent编排必须给出属于执行生命周期的明确失败事实；客户端只负责把该事实暴露给用户。 +Queue 只管理 task、attempt、summary 和 Session 引用，不代理完整输出或 trace；Session 负责输出、trace、read、cancel 和 send。会话连续性不得通过拼接历史 prompt 或伪造 resume 实现，无法续接时必须给出明确失败事实。 -### 6.4 AGENT-L1-REQ-004 HWLAB 与 AgentRun 合同边界 +### 6.4 AGENT-L1-REQ-004 Backend Profile | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | -| AGENT-L1-REQ-004 | AgentRun 合同 | PJ2026-010202 资源装配 | [平台运维](PJ2026-0106-platform-ops.md)、[客户端](PJ2026-0104-client.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | +| AGENT-L1-REQ-004 | Backend Profile | [PJ2026-010204 后端Profile](PJ2026-010204-backend-profile.md) | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[用户管理](PJ2026-0105-user-management.md)、[客户端](PJ2026-0104-client.md) | + +Agent编排应提供 backend adapter、Codex stdio backend、provider profile 管理、profile 隔离、failureKind 和 redaction 能力，使不同 Codex-compatible provider 能共享同一执行合同并保持凭据、模型和 runtime home 隔离。 + +Backend Profile 不承担 HWLAB 用户鉴权，不保存 Secret value，不因某个 profile 缺失或失败 fallback 到另一个 profile。HWLAB 后端完成自身鉴权后可以委托 AgentRun 管理 profile Secret/config 和 canary validation。 + +### 6.5 AGENT-L1-REQ-005 HWLAB 与 AgentRun 合同边界 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AGENT-L1-REQ-005 | HWLAB接入 | [PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md) | Agent编排应原样消费 AgentRun 的 run、command、runner job、event、terminal status、liveness 和 failure kind 合同，并把这些事实映射为 HWLAB 可消费的执行语义。 -HWLAB 不应在客户端、adapter 或 prompt 中推断或补造 AgentRun 没有发出的事实。AgentRun 已正确输出时，HWLAB 负责消费和业务映射；AgentRun 合同缺失或行为错误时，应回到 AgentRun 仓库修复。 +HWLAB 不应在客户端、adapter 或 prompt 中推断或补造 AgentRun 没有发出的事实。AgentRun 已正确输出时，HWLAB 负责消费和业务映射；AgentRun 合同缺失或行为错误时，应回到 AgentRun 实现与对应 OA 规格修复。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010201-agentrun-core.md b/project-management/PJ2026-01/specs/PJ2026-010201-agentrun-core.md new file mode 100644 index 00000000..2250b63b --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-010201-agentrun-core.md @@ -0,0 +1,135 @@ +# PJ2026-010201 AgentRun核心 + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | + +当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 + +## 正文 + +## PJ2026-010201 AgentRun核心需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PJ2026-010201 | +| 短名 | AgentRun核心 | +| 层级 | L2 课题 | +| 状态 | 已生效 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | +| 上级规格 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | +| 规格治理索引 | [规格治理](spec-governance.md) | + +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 AgentRun 核心执行面的稳定使命、范围、术语、系统边界、内部分工和原子需求。 + +## 2. 目的和范围 + +### 2.1 目的 + +AgentRun核心负责把 HWLAB Agent 任务转化为可持久查询、可调度执行、可恢复收口的 run、command、runner job、event 和 terminal status。它是 Agent编排内部的 durable execution authority，业务客户端、CLI、Queue、runner 和后端适配层都不得绕过它直接改写执行事实。 + +### 2.2 范围内 + +- `agentrun-mgr` 的公共 REST API、Runner 私有 API、run/command/event/result 查询和手动 runner job API。 +- `agentrun-runner` 的 register、claim、lease heartbeat、command poll、ack、event append 和 terminal status 上报。 +- Postgres durable store 中 runs、commands、events、runner jobs、sessions、backends、leases、Queue 引用和 migration ledger 的事实持久化。 +- command 终态、run 终态、failureKind、result envelope、event 分页和日志/trace 脱敏边界。 +- runner job identity、attempt、logPath、pod identity、stale lease recovery 和 runner replacement 的核心执行语义。 + +### 2.3 范围外 + +- BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef 和 SecretRef 的装配模型归 [PJ2026-010202 Runtime装配](PJ2026-010202-runtime-assembly.md)。 +- Queue task、attempt、read cursor、commander 和 Session 用户控制面归 [PJ2026-010203 队列会话](PJ2026-010203-queue-session.md)。 +- Codex stdio backend、profile 隔离和 provider profile 管理归 [PJ2026-010204 后端Profile](PJ2026-010204-backend-profile.md)。 +- HWLAB 业务任务如何映射到 AgentRun run/command 归 [PJ2026-010205 HWLAB接入](PJ2026-010205-hwlab-dispatch.md)。 +- CI/CD、版本 lane 和综合联调发布判定归 [发布流水](PJ2026-010601-controlled-release.md)，AgentRun `v0.1` 专项发布细则归 [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)，source truth 归 [AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md)。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| agentrun-mgr | AgentRun 的长驻管理服务，提供 REST API、durable facts authority、runner claim 和 event/status authority。 | +| agentrun-runner | 执行单元，以 Kubernetes Job 或受控进程形态 claim run、调用 backend 并回写事件和状态。 | +| run | AgentRun 中承载一次 Agent 执行生命周期的顶层 durable resource。 | +| command | run 内的一次 turn、steer、interrupt 或 cancel 指令，具备独立状态和终态。 | +| event | 单 run 内 append-only、按 `seq` 单调递增的执行事实记录。 | +| terminal status | command 或 run 的权威终态，不由 partial output、stdout、transport close 或 idle timeout 推断。 | +| failureKind | AgentRun 对 schema、tenant policy、Secret、runner、backend、provider、infra 和 cancel 等失败的结构化分类。 | +| durable facts | Postgres 中可重启后查询的 run、command、event、runner、job、session、backend、lease 和 migration 事实。 | + +## 4. 系统边界和接口 + +本规格把 AgentRun核心作为 Agent编排内的执行事实系统看待；本章只描述外部输入、外部输出和责任边界。 + +| 边界项 | 内容 | +| --- | --- | +| 外部使用者 | HWLAB Agent API、AgentRun CLI、Queue/Session 控制面、runner job、backend adapter 和平台运维。 | +| 外部输入 | run 创建请求、command payload、executionPolicy、backendProfile、workspaceRef、traceSink、runner claim、heartbeat、event 和 status 上报。 | +| 受控资源 | AgentRun REST API、durable store、runner lease、runner job record、event stream、command result 和 failureKind。 | +| 外部输出 | runId、commandId、runnerJobId、attemptId、event cursor、terminal status、result envelope、failureKind、logPath 和 redacted health/readiness。 | +| 用户接口 | `agentrun-mgr` REST API、AgentRun CLI 中的 runs/commands/runner 查询与调度命令。 | +| 系统边界 | AgentRun核心负责执行事实的创建、持久化、调度入口和终态收口；不负责业务授权、硬件事实、provider 协议细节、GitOps 发布或客户端展示。 | + +## 5. 内部分工与规格索引 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| PJ2026-01020101 | Manager API | 本规格 6.1、6.2 | run、command、event、result、runner job 和 health/readiness API authority | 客户端请求、Queue、HWLAB 接入 | Runner、CLI、HarnessRL、客户端 | +| PJ2026-01020102 | Runner执行 | 本规格 6.3 | runner register、claim、lease、poll、ack、append events 和 terminal status | Manager API、Runtime 装配、Backend Profile | Manager、HWLAB 接入、Queue 会话 | +| PJ2026-01020103 | Durable事实 | 本规格 6.4 | Postgres 表、migration ledger、事务和重启后查询 | Manager API、平台运维数据库支撑 | 全部 AgentRun 查询和恢复 | +| PJ2026-01020104 | 终态结果 | 本规格 6.5 | command/run 终态分离、result envelope、failureKind 和 event 分页 | Runner执行、Backend Profile | HWLAB 接入、客户端、HarnessRL | + +## 6. 原子需求 + +### 6.1 AR-CORE-REQ-001 Durable Resource 模型 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-CORE-REQ-001 | Durable Resource | PJ2026-01020101 Manager API | [队列会话](PJ2026-010203-queue-session.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) | + +AgentRun核心应以 run、command、event、runner job、session projection、backend 和 lease 等 durable resource 表达 Agent 执行事实，使创建、查询、轮询、取消、恢复和审计都通过同一资源模型完成。 + +run 和 command 必须短返回并可后续轮询。业务客户端不得依赖长同步 turn、临时进程 stdout 或 Kubernetes Job 名称推断执行事实；这些运行面信息只能作为 durable resource 的 redacted identity 或状态摘要出现。 + +### 6.2 AR-CORE-REQ-002 Manager Authority + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-CORE-REQ-002 | Manager Authority | PJ2026-01020101 Manager API | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[后端Profile](PJ2026-010204-backend-profile.md)、[发布流水](PJ2026-010601-controlled-release.md) | + +`agentrun-mgr` 应作为 AgentRun 公共 API、Runner 私有 API、durable facts、tenant policy boundary、runner claim、event append 和 terminal status 的唯一 authority。 + +Manager 只执行通用 schema、allowlist、idempotency、secret scope 和 executionPolicy 范围检查，不内建 HWLAB 用户角色、HWPOD 授权或 UniDesk 业务策略。业务授权由调用方完成后再委托 AgentRun，AgentRun 保存可审计字段和失败事实。 + +### 6.3 AR-CORE-REQ-003 Runner Claim 与回写 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-CORE-REQ-003 | Runner回写 | PJ2026-01020102 Runner执行 | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[后端Profile](PJ2026-010204-backend-profile.md) | + +`agentrun-runner` 应先 register、claim run 并取得 lease，再 poll command、ack command、调用 backend、append events、续租 heartbeat 并上报 command terminal status。 + +Runner 不得直连 Postgres，不得从本地文件、临时参数或 prompt 伪造正式 command。普通 command 完成后 runner 应在 idle timeout 内继续 poll 同一 run 的后续 command；只有 run cancel、lease 冲突、idle timeout 或 runner 级不可恢复失败才结束 runner loop。 + +### 6.4 AR-CORE-REQ-004 Postgres Durable Store + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-CORE-REQ-004 | Durable Store | PJ2026-01020103 Durable事实 | [发布流水](PJ2026-010601-controlled-release.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) | + +AgentRun核心应使用 Postgres 作为 `v0.1` 唯一 durable store，保存 runs、commands、events、runners、runner jobs、sessions、backends、leases、Queue facts 和 migration ledger。 + +file、sqlite、JSONL、内存对象或 Pod 本地目录只能用于自测试或临时诊断，不能成为运行面事实来源。Manager readiness 必须能说明数据库 reachable、migration ready、adapter 类型和 redacted DSN 状态；缺 migration 或数据库不可用时应 fail fast。 + +### 6.5 AR-CORE-REQ-005 终态与结果语义 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-CORE-REQ-005 | 终态结果 | PJ2026-01020104 终态结果 | [HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[后端Profile](PJ2026-010204-backend-profile.md)、[客户端](PJ2026-0104-client.md) | + +AgentRun核心应分离 command terminal 与 run terminal，并以 result envelope、event cursor、terminal status 和 failureKind 提供可判定的执行结果。 + +partial assistant 文本、stdout 存在、transport close、idle timeout 或日志尾部都不能单独升级为 `completed`。成功和失败都必须能通过 command record 与 command-scoped events 查询；run 级终态只用于 run cancel、runner 级不可恢复失败或明确 run terminal。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md b/project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md new file mode 100644 index 00000000..45cb0744 --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md @@ -0,0 +1,136 @@ +# PJ2026-010202 Runtime装配 + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | + +当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 + +## 正文 + +## PJ2026-010202 Runtime装配需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PJ2026-010202 | +| 短名 | Runtime装配 | +| 层级 | L2 课题 | +| 状态 | 已生效 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | +| 上级规格 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | +| 规格治理索引 | [规格治理](spec-governance.md) | + +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 RuntimeAssembly、SecretRef、AipodSpec、gitbundle、session 和工具凭据装配的稳定使命、范围、术语、系统边界、内部分工和原子需求。 + +## 2. 目的和范围 + +### 2.1 目的 + +Runtime装配负责把一次 AgentRun 执行需要的镜像、provider profile、session、Git 资源、prompt、skills、tools 和工具凭据统一为受控 RuntimeAssembly，使 runner/backend 启动前的所有运行输入都有可追溯来源和明确边界。 + +### 2.2 范围内 + +- `BackendImageRef`、`ProfileRef`、`SessionRef`、`ResourceBundleRef` 四个一等运行时要素。 +- provider credential、Git resource credential、tool credential 和 short-lived execution context 的 SecretRef/projection/redaction 归属。 +- Git-only `ResourceBundleRef.kind="gitbundle"`、`bundles[]`、`promptRefs[]`、`requiredSkills[]`、workspace materialization 和实际 commit 摘要。 +- AipodSpec YAML、`imageRef`、env image reuse、Artificer 默认装配和 `--aipod` render 入口。 +- SessionRef 到 PVC 直接挂载、`CODEX_HOME`、profile runtime home 和 Secret projection 分离。 + +### 2.3 范围外 + +- run、command、event、runner lease 和 terminal status 的 durable authority 归 [AgentRun核心](PJ2026-010201-agentrun-core.md)。 +- Codex app-server stdio、backend adapter 和 provider profile 管理归 [后端Profile](PJ2026-010204-backend-profile.md)。 +- Queue task、Session API 和 scheduler 归 [队列会话](PJ2026-010203-queue-session.md)。 +- YAML-first 平台配置真相、Secret sourceRef 下发和公共 ops primitive 归 [YAML运维](PJ2026-010603-yaml-first-ops.md)。 +- GitOps、CI/CD、lane 和发布验收归 [发布流水](PJ2026-010601-controlled-release.md)，source truth 和 mirror 归 [源码同步](PJ2026-010602-source-sync.md)。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| RuntimeAssembly | runner/backend 启动前的装配模型，声明一次执行使用的镜像、profile、session、资源包和凭据范围。 | +| BackendImageRef | 描述 env/backend/runner 镜像来源和 digest-pinned image 的运行时要素。 | +| ProfileRef | 描述 backend profile 与 provider credential SecretRef 的运行时要素。 | +| SessionRef | 描述 backend 会话、thread、PVC 和续跑状态的运行时要素。 | +| ResourceBundleRef | 描述 Git-only 资源包、工具、skill、prompt 和实际物化 commit 的运行时要素。 | +| AipodSpec | 声明式 agent 装配 YAML，用于集中描述 imageRef、backendProfile、executionPolicy、resourceBundleRef 和 payloadDefaults。 | +| toolCredentials | 运行时工具授权的 SecretRef 装配项，例如 GitHub PR token、GitHub SSH key 或 UniDesk SSH passthrough token。 | +| transientEnv | 单次 runner job 的短期运行上下文，通过短期 Secret 投影，不作为 run durable fact。 | + +## 4. 系统边界和接口 + +本规格把 Runtime装配作为 AgentRun 运行输入的装配系统看待；本章只描述输入、输出和责任边界。 + +| 边界项 | 内容 | +| --- | --- | +| 外部使用者 | AgentRun核心、队列会话、HWLAB接入、后端Profile、runner job 和平台运维。 | +| 外部输入 | AipodSpec、run executionPolicy、backendProfile、SecretRef、gitbundle repo/ref、promptRefs、requiredSkills、sessionRef、toolCredentials 和 transientEnv。 | +| 受控资源 | RuntimeAssembly、Secret projection intent、git materialization、workspace、runtime home、session PVC、image identity 和 redacted assembly summary。 | +| 外部输出 | backend image digest/source、profile SecretRef 摘要、session/PVC 摘要、actual commit、bundle/skill/tool 摘要、projection intent 和 `valuesPrinted=false`。 | +| 用户接口 | AgentRun run 创建、Queue dispatch、Session send、AipodSpec render/apply 和 runner job dry-run。 | +| 系统边界 | Runtime装配负责运行输入的受控声明、解析和投影；不执行 backend turn，不决定业务授权，不把 Secret value、host path 或 prompt 内隐式环境变成运行事实。 | + +## 5. 内部分工与规格索引 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| PJ2026-01020201 | 四要素模型 | 本规格 6.1 | BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef 字段和边界 | AgentRun 核心 run policy | Runner、Backend、HWLAB 接入 | +| PJ2026-01020202 | Secret投影 | 本规格 6.2 | provider/tool/Git credential、projection 和 redaction | YAML运维、平台 Secret 来源 | Runner、Backend、Provider Profile | +| PJ2026-01020203 | GitBundle物化 | 本规格 6.3 | repo/ref、actual commit、bundles、promptRefs、skills、tools | Git mirror、AipodSpec、HWLAB repo | Backend、HarnessRL、Agent 执行 | +| PJ2026-01020204 | Session持久 | 本规格 6.4 | SessionRef、threadId、PVC 直接挂载和 profile 隔离 | AgentRun 核心 session facts | Queue会话、HWLAB接入 | +| PJ2026-01020205 | AipodSpec | 本规格 6.5 | imageRef、backendProfile、executionPolicy、resourceBundleRef 和 payloadDefaults | 发布流水 env image、源码同步 source truth | Queue会话、Session send、Artificer | + +## 6. 原子需求 + +### 6.1 AR-RUNTIME-REQ-001 四要素装配模型 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-RUNTIME-REQ-001 | 四要素模型 | PJ2026-01020201 四要素模型 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[后端Profile](PJ2026-010204-backend-profile.md) | + +Runtime装配应将一次执行收敛为 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef` 四个一等要素，使 runner/backend 启动前能够明确镜像、profile、session 和资源来源。 + +executionPolicy、observabilityPolicy、tool credential、initial prompt、skill 注入、network 和 GC 不应成为第五个杂项运行时路径；它们必须归属到四要素或 run policy，并可追溯到 Git、SecretRef、配置引用或显式 null。 + +### 6.2 AR-RUNTIME-REQ-002 SecretRef 与敏感输出 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-RUNTIME-REQ-002 | Secret投影 | PJ2026-01020202 Secret投影 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[后端Profile](PJ2026-010204-backend-profile.md)、[发布流水](PJ2026-010601-controlled-release.md) | + +Runtime装配应通过 SecretRef 和 projection intent 分发 provider credential、Git resource credential、tool credential 和短期 transientEnv，使 Secret value 不进入 Git source、GitOps branch、Postgres、event、trace、日志或 CLI 输出。 + +输出只能包含 SecretRef 名称、key 名、projection kind、presence、hash/fingerprint、ownerReference 状态和 `valuesPrinted=false`。provider API key、Codex `auth.json`、`config.toml`、DSN、token、SSH private key 和 transientEnv value 都不得以明文形式出现在响应、dry-run、event 或日志中。 + +### 6.3 AR-RUNTIME-REQ-003 GitBundle 资源物化 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-RUNTIME-REQ-003 | GitBundle | PJ2026-01020203 GitBundle物化 | [HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[源码同步](PJ2026-010602-source-sync.md)、[AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md) | + +Runtime装配应以 `ResourceBundleRef.kind="gitbundle"` 物化代码、工具、skill 和 prompt，使 runner 使用的 repo URL、requested ref、actual commit、tree、bundles、promptRefs 和 requiredSkills 都能被查询。 + +gitbundle 不得引用 host path、Secret volume、用户上传临时目录、inline skill manifest 或旧 inline seed。required skill 缺失必须在 backend 启动前结构化失败，不能通过模型默认 skill、prompt 猜测或运行时补文件绕过。 + +### 6.4 AR-RUNTIME-REQ-004 SessionRef 持久化 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-RUNTIME-REQ-004 | Session持久 | PJ2026-01020204 Session持久 | [队列会话](PJ2026-010203-queue-session.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md)、[后端Profile](PJ2026-010204-backend-profile.md) | + +Runtime装配应支持 SessionRef 到 backend thread/cache 的稳定映射，并在启用持久会话时使用 per-session RWO PVC 直接挂载到 `${CODEX_HOME}/`。 + +Session PVC 只保存 Codex rollout 会话文件；provider Secret、完整 `CODEX_HOME`、Git workspace、auth/config、state sqlite、tmp 和 skills 不进入 PVC。runner replacement 必须复用同一 sessionId、threadId、profile 和 PVC；不得通过新 session、拼接历史 prompt 或伪造 resume 形成续跑表象。 + +### 6.5 AR-RUNTIME-REQ-005 AipodSpec 声明式装配 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-RUNTIME-REQ-005 | AipodSpec | PJ2026-01020205 AipodSpec | [队列会话](PJ2026-010203-queue-session.md)、[发布流水](PJ2026-010601-controlled-release.md)、[源码同步](PJ2026-010602-source-sync.md) | + +Runtime装配应提供 AipodSpec YAML，使 imageRef、backendProfile、executionPolicy、resourceBundleRef、model 和 payloadDefaults 可以从声明式规格进入 Queue submit 或 Session send。 + +AipodSpec 只声明装配意图，不保存 API key、SSH private key、token、`auth.json`、`config.toml` 或其他 Secret 明文。`imageRef` 必须指向可追溯的 env image Dockerfile source 和完整 commit，最终 runner job 只能使用解析后的 digest-pinned image 或结构化报告 build-required。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010203-queue-session.md b/project-management/PJ2026-01/specs/PJ2026-010203-queue-session.md new file mode 100644 index 00000000..df364b19 --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-010203-queue-session.md @@ -0,0 +1,125 @@ +# PJ2026-010203 队列会话 + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | + +当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 + +## 正文 + +## PJ2026-010203 队列会话需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PJ2026-010203 | +| 短名 | 队列会话 | +| 层级 | L2 课题 | +| 状态 | 已生效 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | +| 上级规格 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | +| 规格治理索引 | [规格治理](spec-governance.md) | + +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 AgentRun Queue、Session API、read cursor、commander 和 scheduler 边界的稳定使命、范围、术语、系统边界、内部分工和原子需求。 + +## 2. 目的和范围 + +### 2.1 目的 + +队列会话负责把 UniDesk Code Queue 的新任务入口收敛到 AgentRun Queue，并把用户可见任务队列、attempt、Session 输出、trace、read cursor 和 commander 聚合分层管理，避免 Queue、Session 和 Core execution trace 互相替代。 + +### 2.2 范围内 + +- AgentRun Queue task、attempt、priority、retry policy、judge、summary、stats、read cursor 和 commander 聚合。 +- Session API/CLI 的输出、trace、命令流、debug/audit 详情、read 状态和会话控制。 +- Queue task 到 Core run/command/runner job/session 的引用关系和 sessionPath 输出。 +- `sessions send`、session continuation、unread/default/all 状态和 terminal projection。 +- 自动 scheduler 的 deferred 边界、future pending scan、capacity selection、runner assignment 和 stale lease recovery 方向。 + +### 2.3 范围外 + +- run、command、event、runner job 和 terminal status 的执行事实归 [AgentRun核心](PJ2026-010201-agentrun-core.md)。 +- RuntimeAssembly、AipodSpec、gitbundle 和 SecretRef 装配归 [Runtime装配](PJ2026-010202-runtime-assembly.md)。 +- Codex backend、provider profile 和 backend capability 归 [后端Profile](PJ2026-010204-backend-profile.md)。 +- 旧 UniDesk Code Queue API/UI/CLI 长期兼容层不属于本规格范围；旧数据只读归档由 UniDesk 侧单独处理。 +- GitHub sink、OA sink、notification sink、Event System 或外部 integrations 表不是 Queue 首版能力。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| AgentRun Queue | AgentRun 内部任务队列基础设施，承载 task、attempt、summary、stats、read cursor 和 commander 聚合。 | +| Queue task | 用户或系统提交到 AgentRun Queue 的任务资源，可 dispatch 为 Core run/command。 | +| attempt | Queue task 的一次执行尝试，引用 runId、commandId、runnerJobId 和 sessionId。 | +| Session | 面向用户的执行会话控制面，承载 output、trace、read、send、cancel 和 terminal projection。 | +| sessionPath | Queue task 返回的 Session API 路径，用于读取输出和 trace。 | +| read cursor | 按 readerId 记录的已读水位，用于默认列表只显示 running 或 unread session/task。 | +| commander | Queue 侧的聚合视图，用于展示队列状态、最新 attempt 和下一步操作摘要。 | +| Scheduler | 后续自动调度器，负责 pending scan 和 runner assignment；`v0.1` 第一阶段不作为发布前置。 | + +## 4. 系统边界和接口 + +本规格把队列会话作为 AgentRun 的任务队列和用户会话控制系统看待；本章只描述输入、输出和责任边界。 + +| 边界项 | 内容 | +| --- | --- | +| 外部使用者 | UniDesk 用户、HWLAB Agent 入口、CLI 操作者、Artificer/Aipod、AgentRun 核心和平台运维。 | +| 外部输入 | Queue task JSON、dispatch body、sessionId、prompt、run base、readerId、backendProfile、resourceBundleRef、cancel/read/send 控制请求。 | +| 受控资源 | Queue task、attempt、summary、stats、read cursor、Session projection、session trace/output 和 scheduler deferred 状态。 | +| 外部输出 | taskId、attemptId、sessionId、sessionPath、queue stats、commander summary、unread/default/all 列表、output/trace cursor 和控制结果。 | +| 用户接口 | AgentRun REST Queue/Session API、`./scripts/agentrun queue ...`、`./scripts/agentrun sessions ...`。 | +| 系统边界 | 队列会话负责任务队列和会话控制语义；不代理 Core trace 为 Queue output，不直接执行 backend，不决定 tenant 业务授权，不维护旧 Code Queue 兼容入口。 | + +## 5. 内部分工与规格索引 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| PJ2026-01020301 | Queue任务 | 本规格 6.1 | task、attempt、summary、stats、read cursor 和 commander | UniDesk/HWLAB 提交入口 | AgentRun Core、Session API | +| PJ2026-01020302 | Session控制 | 本规格 6.2 | output、trace、send、read、cancel、default/unread/all 视图 | Core events、Runtime session | CLI、客户端、用户 | +| PJ2026-01020303 | 分层边界 | 本规格 6.3 | Queue、Session、Core 和 Scheduler 的职责分离 | Queue任务、Session控制 | 发布流水、客户端 | +| PJ2026-01020304 | Scheduler边界 | 本规格 6.4 | 自动调度 deferred、future scan/assignment/recovery | Queue pending facts、capacity | Runner job、AgentRun Core | + +## 6. 原子需求 + +### 6.1 AR-QUEUE-REQ-001 Queue Task 与 Attempt + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-QUEUE-REQ-001 | Queue任务 | PJ2026-01020301 Queue任务 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) | + +队列会话应提供 AgentRun Queue task 和 attempt 模型，使新任务能够直接进入 AgentRun Queue，并通过 dispatch 生成 Core run、command、runner job 和 Session 引用。 + +AgentRun Queue 直接吸收 UniDesk Code Queue 的新任务入口，不做 adapter 过渡、双写或长期兼容旧 Code Queue API/CLI/UI。旧 UniDesk Code Queue 只保留历史归档或只读查询，不再接收新任务。 + +### 6.2 AR-QUEUE-REQ-002 Session 输出与控制 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-QUEUE-REQ-002 | Session控制 | PJ2026-01020302 Session控制 | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md)、[客户端](PJ2026-0104-client.md) | + +队列会话应提供 Session API 和 CLI，使用户能够查看执行输出、trace、debug/audit 摘要，发送 follow-up，执行 read/cancel，并按 default、running、unread、terminal、idle 或 all 状态读取会话。 + +Queue task 详情只能返回 `sessionPath` 和有界摘要，不代理完整输出或 trace。输出、trace 和会话控制必须从 Session API/CLI 进入，避免 Queue 列表视图反推 Core event stream 或展开执行细节。 + +### 6.3 AR-QUEUE-REQ-003 Queue/Session/Core 分层 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-QUEUE-REQ-003 | 分层边界 | PJ2026-01020303 分层边界 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[后端Profile](PJ2026-010204-backend-profile.md) | + +队列会话应保持 Queue、Session、Core 和 Scheduler 分层：Queue 管 task/attempt/summary，Session 管输出和会话控制，Core 管 run/command/runner facts，Scheduler 未来只做 pending scan 和 runner assignment。 + +Queue 不维护 OA、notification、GitHub action 或外部协作 sink，不从 Session trace 反推 overview，也不把 Core event stream 暴露成 Queue output。需要执行详情时，调用方必须用 sessionId 或 runId 进入对应正式 API。 + +### 6.4 AR-QUEUE-REQ-004 Scheduler Deferred 边界 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-QUEUE-REQ-004 | Scheduler | PJ2026-01020304 Scheduler边界 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[发布流水](PJ2026-010601-controlled-release.md) | + +队列会话应保留自动 scheduler 的规格边界，但 `v0.1` 第一阶段不得因为 scheduler 未实现而阻塞最小真实闭环。 + +在 scheduler 启用前，CLI/manual dispatch 必须能启动真实 runner，manager durable facts、runner claim、backend turn、events 和 terminal status 必须真实可用。未来 scheduler 只能通过 manager API 和 Kubernetes runner Job 改变调度状态，不得直接写 Postgres 或直接执行 backend。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010204-backend-profile.md b/project-management/PJ2026-01/specs/PJ2026-010204-backend-profile.md new file mode 100644 index 00000000..d969b237 --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-010204-backend-profile.md @@ -0,0 +1,135 @@ +# PJ2026-010204 后端Profile + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | + +当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 + +## 正文 + +## PJ2026-010204 后端Profile需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PJ2026-010204 | +| 短名 | 后端Profile | +| 层级 | L2 课题 | +| 状态 | 已生效 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | +| 上级规格 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | +| 规格治理索引 | [规格治理](spec-governance.md) | + +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 backend adapter、Codex stdio backend、provider profile、profile 管理和 redaction/failureKind 的稳定使命、范围、术语、系统边界、内部分工和原子需求。 + +## 2. 目的和范围 + +### 2.1 目的 + +后端Profile负责把 AgentRun runner 与具体 Code Agent provider 隔离开来，使 `codex`、`deepseek`、`minimax-m3`、`dsflash-go` 和动态 Codex-compatible profile 能通过同一 backend adapter、同一 Codex app-server stdio 协议和同一 redaction/failureKind 语义执行。 + +### 2.2 范围内 + +- Backend adapter 合同：profile resolution、prepare、startTurn、interrupt、finalize 和 redact。 +- Codex CLI app-server JSON-RPC over stdio backend kind，包括 thread start/resume、turn start/steer/interrupt 和 normalized events。 +- `codex`、`deepseek`、`minimax-m3`、`dsflash-go` profile 的 SecretRef、config、model catalog、CODEX_HOME 隔离和切换不污染。 +- Provider profile 管理 API：list/show/delete/config/credential/validate 和 canary 聚合。 +- provider/auth/backend/protocol/timeout/cancel 错误到 failureKind 的映射，以及 credential redaction。 + +### 2.3 范围外 + +- provider credential 的 SecretRef 投影和 runtime home 装配归 [Runtime装配](PJ2026-010202-runtime-assembly.md)。 +- run、command、event 和 terminal status authority 归 [AgentRun核心](PJ2026-010201-agentrun-core.md)。 +- HWLAB 用户鉴权、管理页表单和业务授权归 [用户管理](PJ2026-0105-user-management.md) 与 [客户端](PJ2026-0104-client.md)。 +- DeepSeek、MiniMax 或其他 provider 的外部 upstream 可用性不由 AgentRun 伪装成功；失败只能结构化归因。 +- 旧 MiniMax/OpenCode 直连路线不作为 fallback、judge backend 或 Queue 首版能力。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| Backend adapter | runner 与具体 Code Agent 工具之间的适配层，负责协议调用、事件归一化、失败映射和 redaction。 | +| backendProfile | run 中选择的 provider/profile slug，例如 `codex`、`deepseek`、`minimax-m3`、`dsflash-go` 或动态 slug。 | +| backendKind | backend 协议实现类型；`v0.1` 固定使用 `codex-app-server-stdio`。 | +| Codex stdio backend | 通过 `codex app-server --listen stdio://` 执行 JSON-RPC over stdio turn 的 backend kind。 | +| Provider Profile 管理 | Manager 提供的服务端委托 API，用于 profile 状态查询、API key/config 写入和 canary 验证。 | +| profile isolation | 不同 profile 的 SecretRef、CODEX_HOME、model、model catalog 和 upstream 配置互不污染。 | +| model-catalog | `dsflash-go` 等 profile 使用的模型目录文件，用于声明模型元数据和上下文能力。 | + +## 4. 系统边界和接口 + +本规格把后端Profile作为 AgentRun 的 provider/backend 适配系统看待；本章只描述输入、输出和责任边界。 + +| 边界项 | 内容 | +| --- | --- | +| 外部使用者 | AgentRun runner、AgentRun核心、Runtime装配、HWLAB provider 管理入口、CLI 和平台运维。 | +| 外部输入 | backendProfile、ProfileRef、SecretRef projection、command payload、SessionRef/threadId、initialPrompt、skill summary 和 provider profile 管理请求。 | +| 受控资源 | backend adapter、Codex app-server stdio 子进程、profile capability、provider profile Secret/config、canary run 和 redaction policy。 | +| 外部输出 | normalized events、assistant message、tool call、command output、terminal status、failureKind、backend capability、profile status 和 validation result。 | +| 用户接口 | `GET /api/v1/backends`、Provider Profile 管理 API、AgentRun CLI provider/backends 命令和 HWLAB 委托管理 API。 | +| 系统边界 | 后端Profile负责 provider 协议和 profile 管理合同；不保存 Secret value，不判断 HWLAB 用户权限，不扩大 executionPolicy，不用另一个 profile 隐式 fallback。 | + +## 5. 内部分工与规格索引 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| PJ2026-01020401 | Adapter合同 | 本规格 6.1 | resolve/prepare/start/interrupt/finalize/redact 和事件归一化 | AgentRun Core、RuntimeAssembly | Runner、Result envelope | +| PJ2026-01020402 | Codex协议 | 本规格 6.2 | Codex app-server stdio JSON-RPC、thread/turn/steer/interrupt | Adapter合同、ProfileRef | 真实 provider turn | +| PJ2026-01020403 | Profile隔离 | 本规格 6.3 | codex/deepseek/minimax-m3/dsflash-go/dynamic profile capability 和隔离 | Secret投影、Runtime home | Backend adapter、验证模型 | +| PJ2026-01020404 | Profile管理 | 本规格 6.4 | provider profile status、config/key 写入、delete 和 canary validation | HWLAB 后端委托、Kubernetes Secret | 客户端管理页、CLI | +| PJ2026-01020405 | 失败脱敏 | 本规格 6.5 | provider/auth/backend/protocol failureKind 和 redaction | Backend adapter、SecretRef | Core result、HWLAB 接入 | + +## 6. 原子需求 + +### 6.1 AR-BACKEND-REQ-001 Backend Adapter 合同 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-BACKEND-REQ-001 | Adapter合同 | PJ2026-01020401 Adapter合同 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) | + +后端Profile应提供稳定 Backend adapter 合同，使 runner 能按 `backendProfile` 解析 capability，准备 execution context，启动 turn，尝试 interrupt，归一化终态，并对输出做 redaction。 + +Adapter 输入必须来自 manager 持久化后的 run/command 和 RuntimeAssembly Secret projection，不得从 CLI 参数、临时环境变量或 Git 文件读取 provider credential 明文。unknown profile 必须结构化失败，不得静默映射到默认 `codex`。 + +### 6.2 AR-BACKEND-REQ-002 Codex Stdio Backend + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-BACKEND-REQ-002 | Codex协议 | PJ2026-01020402 Codex协议 | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md) | + +后端Profile应以 Codex CLI app-server JSON-RPC over stdio 作为 `v0.1` 第一真实 backend kind，按 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`、`turn/steer` 和 `turn/interrupt` 处理真实 Code Agent turn。 + +直接 Responses HTTP、OpenAI SDK wrapper、`codex exec` 一次性输出、fake provider、固定文本回复或本地 shell 模拟不能作为正式 backend 实现或综合联调通过证据。裸 HTTP 或 `codex exec --json` 只能作为 provider/upstream 诊断辅助。 + +### 6.3 AR-BACKEND-REQ-003 Profile 隔离与切换 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-BACKEND-REQ-003 | Profile隔离 | PJ2026-01020403 Profile隔离 | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) | + +后端Profile应支持 `codex`、`deepseek`、`minimax-m3`、`dsflash-go` 和符合规则的动态 Codex-compatible profile，并保证它们共享协议但隔离 SecretRef、CODEX_HOME、model、model catalog 和 upstream 配置。 + +任一 profile 的 SecretRef 缺失、config 缺失或 provider 失败都不得 fallback 到另一个 profile。`dsflash-go` 必须携带 profile-scoped `model-catalog.json`；缺少 model catalog 时应在 provider 调用前结构化失败。 + +### 6.4 AR-BACKEND-REQ-004 Provider Profile 管理 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-BACKEND-REQ-004 | Profile管理 | PJ2026-01020404 Profile管理 | [客户端](PJ2026-0104-client.md)、[用户管理](PJ2026-0105-user-management.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) | + +后端Profile应由 `agentrun-mgr` 提供 provider profile 状态查询、config/API key 写入、Secret/config 更新、删除和 canary 验证 API，使 HWLAB 后端能在完成自身鉴权后委托 AgentRun 更新受控 profile。 + +AgentRun 不承担 HWLAB 用户鉴权，不保存浏览器 session、用户角色或 OpenFGA decision。管理 API 只校验调用来源、profile allowlist、SecretRef scope、payload schema、redaction 和幂等性；响应只返回 profile、SecretRef、hash 后缀、validation result、run/command/job identity 和 failureKind。 + +### 6.5 AR-BACKEND-REQ-005 FailureKind 与 Redaction + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-BACKEND-REQ-005 | 失败脱敏 | PJ2026-01020405 失败脱敏 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[HWLAB接入](PJ2026-010205-hwlab-dispatch.md) | + +后端Profile应把 provider auth failure、provider unavailable、backend protocol error、thread resume failure、timeout、cancel 和 unsupported capability 映射为 AgentRun 可消费的 failureKind。 + +event、trace、日志、health、diagnostics、CLI 输出和 provider profile 响应不得打印 API key、Authorization header、DSN password、token、URL credential、Codex `auth.json`、Codex `config.toml` 或 Secret value。可以输出 request id、HTTP status 分类、SecretRef、profile、backendKind、protocol 和 redacted details。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md b/project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md new file mode 100644 index 00000000..32abfb93 --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md @@ -0,0 +1,134 @@ +# PJ2026-010205 HWLAB接入 + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | + +当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 + +## 正文 + +## PJ2026-010205 HWLAB接入需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PJ2026-010205 | +| 短名 | HWLAB接入 | +| 层级 | L2 课题 | +| 状态 | 已生效 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | +| 上级规格 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) | +| 规格治理索引 | [规格治理](spec-governance.md) | + +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 HWLAB 通过 AgentRun 执行 Code Agent 的接入目标、合同边界、术语、系统边界、内部分工和原子需求。 + +## 2. 目的和范围 + +### 2.1 目的 + +HWLAB接入负责把 HWLAB Cloud API、Workbench、CLI、HWPOD 运行上下文和 AgentRun durable execution 合同连接起来，使 HWLAB 能以手动调度 API 完成 Code Agent canary，并逐步收敛到可续跑、可取消、可追踪、可映射结果的 AgentRun 执行路径。 + +### 2.2 范围内 + +- HWLAB 业务 dispatcher 创建 AgentRun run、command 和 runner job 的字段映射。 +- `POST /api/v1/runs/:runId/runner-jobs` 手动调度 API、idempotency、短返回和 runner job identity。 +- HWLAB session/provider/profile、conversation、workspace、gitbundle、promptRefs、requiredSkills 和 toolCredentials 的接入口径。 +- HWLAB HWPOD/runtime 短期上下文通过 transientEnv 或 tool credential 进入 runner job 的边界。 +- AgentRun events、command result、terminal status、failureKind 和 result envelope 到 HWLAB trace/result 的映射。 + +### 2.3 范围外 + +- HWPOD 设备身份、inventory、租约、健康和硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。 +- CaseRun 评价、pass/fail、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。 +- HWLAB 用户鉴权、组织、API key、额度和账本归 [用户管理](PJ2026-0105-user-management.md)。 +- Web/CLI 展示、管理页和用户交互归 [客户端](PJ2026-0104-client.md)。 +- 自动 scheduler 和跨 backend 自动路由不是 HWLAB canary 前置条件。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| HWLAB dispatcher | HWLAB Cloud API 中完成业务鉴权、资源选择和 AgentRun 委托调用的服务端组件。 | +| 手动调度 API | AgentRun 为已存在 run/command 显式创建 runner Job 的短返回 API。 | +| HWLAB canary | HWLAB v0.2 通过 AgentRun 执行真实 Code Agent turn 的最小接入闭环。 | +| result envelope | AgentRun command result 的结构化输出，包含 status、terminalStatus、reply、failureKind、events 和 artifact 摘要。 | +| HWPOD runtime context | HWLAB dispatcher 为单次 runner job 提供的 owner-scoped 硬件运行上下文。 | +| transientEnv | 单次 runner job 的短期 env 上下文，由 AgentRun 转为短期 Secret 投影并脱敏输出。 | + +## 4. 系统边界和接口 + +本规格把 HWLAB接入作为 HWLAB 到 AgentRun 的服务端委托系统看待；本章只描述输入、输出和责任边界。 + +| 边界项 | 内容 | +| --- | --- | +| 外部使用者 | HWLAB Cloud API、HWLAB Cloud Web、HWLAB CLI、AgentRun核心、Runtime装配、后端Profile、硬件池和 HarnessRL。 | +| 外部输入 | HWLAB 用户任务、session/conversation、workspace/ref、provider profile、HWPOD/runtime context、resourceBundleRef、promptRefs、requiredSkills 和 trace correlation。 | +| 受控资源 | AgentRun run/command/runner job 映射、manual dispatch payload、transientEnv Secret projection、event/result mapping 和 cancel/session continuation。 | +| 外部输出 | runId、commandId、runnerJobId、attemptId、jobName、terminalStatus、reply/finalResponse、failureKind、blocker、artifact summary 和 HWLAB trace 指针。 | +| 用户接口 | HWLAB Agent API、Cloud Web/CLI Agent 入口和 AgentRun manual dispatch API。 | +| 系统边界 | HWLAB接入负责服务端委托与结果映射；AgentRun 不解释 HWPOD 权限，不判断 HWLAB 用户授权，不把业务 token 固化为 durable fact。 | + +## 5. 内部分工与规格索引 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| PJ2026-01020501 | 手动调度 | 本规格 6.1 | runner-jobs API、idempotency、短返回和 job identity | AgentRun Core run/command | HWLAB canary | +| PJ2026-01020502 | 字段映射 | 本规格 6.2 | HWLAB task/session/workspace/profile 到 AgentRun run/command 映射 | 客户端、用户管理、Runtime装配 | AgentRun Core、Backend Profile | +| PJ2026-01020503 | 结果映射 | 本规格 6.3 | events/result/terminal/failureKind 到 HWLAB trace/result | AgentRun Core、Backend Profile | 客户端、HarnessRL | +| PJ2026-01020504 | 硬件上下文 | 本规格 6.4 | HWPOD/runtime transientEnv 和 tool credential 边界 | 硬件池、Runtime装配 | Runner job、Agent 执行 | +| PJ2026-01020505 | 取消续跑 | 本规格 6.5 | durable cancel、SessionRef 和 same-run multi-command 接入 | Queue会话、Runtime装配 | HWLAB Workbench、CLI | + +## 6. 原子需求 + +### 6.1 AR-HWLAB-REQ-001 手动调度入口 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-HWLAB-REQ-001 | 手动调度 | PJ2026-01020501 手动调度 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) | + +HWLAB接入应通过 AgentRun 手动调度 API 为已创建的 run/command 显式创建 runner Job，并快速返回 job identity、attempt、logPath 或 pod identity 以及后续轮询入口。 + +手动调度只启动当前 run/command 的 runner Job，不扫描 pending queue，不等待完整模型 turn，也不把 Kubernetes Job 删除作为正式取消语义。重复提交必须按 idempotency key 返回既有 job 或结构化失败。 + +### 6.2 AR-HWLAB-REQ-002 HWLAB 到 AgentRun 字段映射 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-HWLAB-REQ-002 | 字段映射 | PJ2026-01020502 字段映射 | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[用户管理](PJ2026-0105-user-management.md)、[客户端](PJ2026-0104-client.md) | + +HWLAB接入应把 HWLAB session、conversation、workspace、provider profile、resource bundle、promptRefs、requiredSkills、toolCredentials 和 trace correlation 映射为 AgentRun run、command 和 RuntimeAssembly 输入。 + +AgentRun `tenantId`、`projectId`、`providerId`、`backendProfile` 是 AgentRun policy 字段，不等同于 HWLAB Workbench project。HWLAB 业务 project/workspace 只能进入 metadata 或 workspaceRef 子字段，不能覆盖 AgentRun 的通用 policy 边界。 + +### 6.3 AR-HWLAB-REQ-003 结果与 Trace 映射 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-HWLAB-REQ-003 | 结果映射 | PJ2026-01020503 结果映射 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[后端Profile](PJ2026-010204-backend-profile.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | + +HWLAB接入应消费 AgentRun events、command result、terminal status、failureKind 和 result envelope，并转换为 HWLAB 可展示、可追踪、可供 HarnessRL 引用的执行结果。 + +HWLAB 不得用 partial assistant、stdout、transport close、idle timeout 或日志尾部推断 completed。`eventsCapped=true`、final assistant 截断或 command 未终态时，HWLAB 应继续读取 AgentRun events/trace，而不是把当前摘要当作完整归档。 + +### 6.4 AR-HWLAB-REQ-004 HWPOD Runtime Context + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-HWLAB-REQ-004 | 硬件上下文 | PJ2026-01020504 硬件上下文 | [硬件池](PJ2026-0101-hardware-pool.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) | + +HWLAB接入应把 HWPOD/runtime 的短期、owner-scoped 执行上下文作为单次 runner job 的 transientEnv 或受控 tool credential 传入，使 Agent 能访问授权范围内的 HWLAB runtime 而不获得长期平台凭据。 + +AgentRun 只负责投影、脱敏和限制扩散，不解释 HWPOD 权限，也不把业务 token 写入 run、command、event、result 或通用授权配置。provider API key、GitHub token、UniDesk SSH token 和 SSH private key 不得通过 transientEnv 注入。 + +### 6.5 AR-HWLAB-REQ-005 取消与会话续跑 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-HWLAB-REQ-005 | 取消续跑 | PJ2026-01020505 取消续跑 | [队列会话](PJ2026-010203-queue-session.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md) | + +HWLAB接入应使用 AgentRun durable cancel、SessionRef、thread continuation 和 same-run multi-command loop 实现用户可见的取消、follow-up、steer 和续跑。 + +取消必须幂等并写入 command/run 状态与 event；pending command 被取消后不得再创建 runner Job。会话续跑只认标准 SessionRef/threadId；无法续接时必须返回明确失败事实，不能拼接历史 prompt 或伪造继续会话。 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 970bf4c9..b14080fb 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md +++ b/project-management/PJ2026-01/specs/PJ2026-0106-platform-ops.md @@ -80,8 +80,8 @@ | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | | --- | --- | --- | --- | --- | --- | -| PJ2026-010601 | 发布流水 | 本规格 6.1 | CI/CD、PipelineRun、image、rollout、trigger-current 和发布状态 | Git commit、镜像配置、各 L1 发布需求 | 全部 L1 | -| PJ2026-010602 | 源码同步 | 本规格 6.2 | Git mirror、source commit authority、bundle/mirror URL 和 lane source truth | Git remote、运行 lane、Agent 资源装配需求 | Agent编排、HarnessRL、客户端 | +| PJ2026-010601 | 发布流水 | [PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md) | CI/CD、PipelineRun、image、rollout、trigger-current 和发布状态 | Git commit、镜像配置、各 L1 发布需求 | 全部 L1 | +| PJ2026-010602 | 源码同步 | [PJ2026-010602 源码同步](PJ2026-010602-source-sync.md) | Git mirror、source commit authority、bundle/mirror URL 和 lane source truth | Git remote、运行 lane、Agent 资源装配需求 | Agent编排、HarnessRL、客户端 | | PJ2026-010603 | YAML-first运维 | [PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md) | YAML-first 自动化分布式运维；SecretRef、targetKey、fingerprint 是其密钥分发子项 | 各 L1 配置需求、密钥来源 | 全部 L1 | | PJ2026-010604 | 公开入口 | 本规格 6.4 | FRP、Caddy、domain、TLS、public health 和入口漂移处理 | 客户端/API 服务、运行 lane | 客户端、用户管理、Agent编排 | | PJ2026-010605 | 运维监控 | 本规格 6.5 | Prometheus metrics、scrape target、alert rule、服务健康指标和资源指标 | 运行面 metrics endpoint、各 L1 服务健康指标 | 全部 L1 | @@ -92,7 +92,7 @@ | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | -| OPS-L1-REQ-001 | 受控发布 | PJ2026-010601 发布流水 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | +| OPS-L1-REQ-001 | 受控发布 | [PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | 平台运维应提供受控发布能力，使 HWLAB 服务变更能够通过标准 CI/CD、镜像构建、rollout、trigger-current 和状态查询进入目标运行面。 @@ -102,7 +102,7 @@ | 编号 | 短名 | 主责模块 | 关联模块 | | --- | --- | --- | --- | -| OPS-L1-REQ-002 | 源码同步 | PJ2026-010602 源码同步 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) | +| OPS-L1-REQ-002 | 源码同步 | [PJ2026-010602 源码同步](PJ2026-010602-source-sync.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[客户端](PJ2026-0104-client.md) | 平台运维应提供源码同步与运行真相能力，使目标 lane 使用明确的 Git mirror、source commit、bundle/mirror URL 和 GitOps 来源。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md b/project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md new file mode 100644 index 00000000..2cd06c3b --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md @@ -0,0 +1,128 @@ +# PJ2026-010601 发布流水 + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | + +当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 + +## 正文 + +## PJ2026-010601 发布流水需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PJ2026-010601 | +| 短名 | 发布流水 | +| 层级 | L2 课题 | +| 状态 | 已生效 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | +| 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | +| 规格治理索引 | [规格治理](spec-governance.md) | + +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留受控发布、版本 lane、CI/CD、运行面发布判定和发布入口的通用稳定使命、范围、术语、系统边界、内部分工和原子需求。 + +## 2. 目的和范围 + +### 2.1 目的 + +发布流水负责把 HWLAB 平台服务从 source commit 通过受控 CI/CD、镜像、GitOps 和 rollout 交付到目标 runtime，使发布状态、运行版本、镜像来源和发布判定可追踪、可恢复、可审查。具体服务的固定 branch、namespace、pipeline、镜像、验证组合和 lane 数值只进入对应服务专项规格，不写成通用发布规则。 + +### 2.2 范围内 + +- HWLAB 各服务 lane 的通用发布模型、runtime namespace、CI pipeline、GitOps promotion 和 rollout 入口。 +- Tekton PipelineRun、Argo CD sync、runtime image、env image reuse、digest-pinned image 和 artifact promotion。 +- 发布候选判定中 source revision、GitOps desired state、runtime live state、Postgres migration、SecretRef presence 和 workload readiness 的一致性。 +- UniDesk 受控 CI/CD CLI、服务自有 CLI 和服务 health/readiness 在发布验收中的正式入口边界。 +- 自测试和综合联调在发布决策中的分层口径：自测试允许 mock，综合联调必须使用真实运行面。 + +### 2.3 范围外 + +- Git mirror、source commit authority、bundle/mirror URL 和 artifact catalog 的来源真相归 [源码同步](PJ2026-010602-source-sync.md)。 +- YAML 配置、SecretRef sourceRef/targetKey、fingerprint 和受控下发归 [YAML运维](PJ2026-010603-yaml-first-ops.md)。 +- 具体服务的业务执行事实归对应业务规格；AgentRun run、command、event、runner job 和 terminal status 归 [AgentRun核心](PJ2026-010201-agentrun-core.md)，AgentRun `v0.1` 专项发布 lane 归 [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)。 +- RuntimeAssembly、AipodSpec、gitbundle 和 Secret projection 归 [Runtime装配](PJ2026-010202-runtime-assembly.md)。 +- Backend adapter、provider profile 和真实 provider turn 语义归 [后端Profile](PJ2026-010204-backend-profile.md)。 +- 一次性排障、长日志、PR 过程、证据堆叠和文档治理规则不进入本规格正文。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| 发布流水 | 从 source commit 到目标 runtime 的受控构建、promotion、GitOps sync、rollout 和发布状态查询链路。 | +| 版本 lane | 按版本隔离的 source branch、runtime namespace、GitOps branch、CI pipeline 和发布验收集合。 | +| PipelineRun | Tekton 中执行构建、镜像发布或 GitOps promotion 的一次流水线运行。 | +| GitOps desired state | GitOps branch 中声明的目标运行面资源状态。 | +| runtime live state | 目标 namespace 中实际运行的 workload、image、config、health 和 readiness 状态。 | +| env image reuse | 基础执行环境镜像按 env identity 复用，普通业务源码变更只改变 boot commit。 | +| 综合联调 | 在真实目标运行面、真实 SecretRef、真实 backend/provider 或服务入口上完成的发布候选验证。 | + +## 4. 系统边界和接口 + +本规格把发布流水作为平台运维内的服务交付系统看待；本章只描述输入、输出和责任边界。 + +| 边界项 | 内容 | +| --- | --- | +| 外部使用者 | 平台管理员、发布操作人员、服务维护者、CI/CD 自动化任务和需要发布状态的业务模块。 | +| 外部输入 | source commit、deploy 配置、lane 选择、镜像构建请求、GitOps promotion 请求、rollout 请求、SecretRef presence 和验证请求。 | +| 受控资源 | Tekton PipelineRun、Argo Application、runtime namespace、workload、image、release status、health/readiness 和发布判定结果。 | +| 外部输出 | PipelineRun 状态、image digest、promotion revision、Argo sync 状态、runtime readiness、发布候选结论和 redacted 失败信息。 | +| 用户接口 | UniDesk CI/CD CLI、服务自有 CLI 发布/验证相关入口、服务 health/readiness、Tekton/Argo 受控状态查询入口。 | +| 系统边界 | 发布流水负责让变更以可追踪、可恢复、可判定的方式进入运行面；不替代业务功能实现，不绕过受控 CLI，不把 mock 或 source-only 结果当作发布通过。 | + +## 5. 内部分工与规格索引 + +本规格前四个 L3 只承载服务无关的通用发布规则。AgentRun 固定 branch、namespace、Pipeline、GitOps path、真实 provider turn 等内容只在 AgentRun 专项 L3 中展开，通用发布条款只保留可复用的发布边界。 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| PJ2026-01060101 | Lane发布 | 本规格 6.1 | source/GitOps/runtime namespace、CI pipeline 和 rollout 入口 | 源码同步、YAML运维 | 全部 runtime 服务 | +| PJ2026-01060102 | 镜像Promotion | 本规格 6.2 | env image reuse、digest-pinned image、artifact promotion 和 image readiness | Source commit、Containerfile、registry | 需要运行镜像的服务 | +| PJ2026-01060103 | 发布判定 | 本规格 6.3 | source/GitOps/runtime 一致性、health/readiness 和 migration/SecretRef presence | CI/CD、GitOps、YAML运维 | 平台管理员、业务模块 | +| PJ2026-01060104 | 验证分层 | 本规格 6.4 | 自测试、综合联调、CLI/API 交互和真实运行面通过口径 | 目标 runtime、业务模块测试需求 | 发布决策 | +| PJ2026-01060105 | AgentRun发布 | [PJ2026-01060105 AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) | AgentRun `v0.1` 的发布 lane、Pipeline、runtime namespace 和真实联调细则 | 源码同步、YAML运维、Agent编排 | AgentRun runtime | + +## 6. 原子需求 + +### 6.1 OPS-RELEASE-REQ-001 版本 Lane 发布 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-RELEASE-REQ-001 | Lane发布 | PJ2026-01060101 Lane发布 | [源码同步](PJ2026-010602-source-sync.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) | + +发布流水应为 HWLAB 平台服务提供版本 lane 发布能力，使 source branch、runtime namespace、GitOps branch、CI pipeline 和 rollout 入口相互隔离。 + +具体服务的 lane 固定值、历史口径废弃项和运行面名称应写入对应服务专项规格；通用发布流水只定义隔离、受控入口、可追溯和不可绕过原则。 + +### 6.2 OPS-RELEASE-REQ-002 镜像与 Promotion + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-RELEASE-REQ-002 | 镜像Promotion | PJ2026-01060102 镜像Promotion | [源码同步](PJ2026-010602-source-sync.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) | + +发布流水应提供镜像构建、env image reuse、digest-pinned image 和 GitOps promotion 能力，使运行面使用的镜像能够追溯到 source commit、Containerfile、env identity 和 artifact 摘要。 + +需要 work-ready env image 的服务应在自身专项规格中声明工具和依赖要求；通用发布流水只保证镜像来源、digest、promotion 和运行面引用可追溯，不替业务模块定义运行时功能。 + +### 6.3 OPS-RELEASE-REQ-003 发布一致性判定 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-RELEASE-REQ-003 | 发布判定 | PJ2026-01060103 发布判定 | [源码同步](PJ2026-010602-source-sync.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) | + +发布流水应以 source revision、GitOps desired state、runtime live state、image digest、workload readiness、Postgres migration、SecretRef presence 和 service health/readiness 的一致性判断发布候选。 + +PipelineRun 成功、Argo Synced、health 可访问或 source check 通过都不能单独替代业务运行面通过。发布判定只能输出 redacted 状态和摘要，不得包含 provider credential、Postgres DSN password、token、URL credential 或 Secret value。 + +### 6.4 OPS-RELEASE-REQ-004 两层验证口径 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-RELEASE-REQ-004 | 验证分层 | PJ2026-01060104 验证分层 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md)、[HarnessRL](PJ2026-0103-harness-rl.md) | + +发布流水应区分组件自测试和综合联调：自测试允许 mock，用于快速反馈；综合联调必须在真实目标运行面、真实依赖、真实配置和服务原入口上完成。 + +mock、fake dependency、source-only、dry-run、缺关键配置时的 skip、只读 health 成功或没有真实业务终态的运行面状态，都不能作为综合联调或发布通过证据。具体服务需要哪些真实依赖和终态，由对应服务专项规格定义。 diff --git a/project-management/PJ2026-01/specs/PJ2026-01060105-agentrun-v01-release-lane.md b/project-management/PJ2026-01/specs/PJ2026-01060105-agentrun-v01-release-lane.md new file mode 100644 index 00000000..cfd31062 --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-01060105-agentrun-v01-release-lane.md @@ -0,0 +1,119 @@ +# PJ2026-01060105 AgentRun发布Lane + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | + +当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 + +## 正文 + +## PJ2026-01060105 AgentRun发布Lane需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PJ2026-01060105 | +| 短名 | AgentRun发布 | +| 层级 | L3 子课题 | +| 状态 | 已生效 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | +| 上级规格 | [PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md) | +| 规格治理索引 | [规格治理](spec-governance.md) | + +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 AgentRun `v0.1` 作为发布流水具体消费对象的 lane、CI/CD、运行面和真实联调要求。 + +## 2. 目的和范围 + +### 2.1 目的 + +AgentRun发布Lane负责定义 AgentRun `v0.1` 在 G14 上的专用发布 lane，使 `v0.1` source、GitOps、runtime、CI/CD、镜像和验证入口不与旧 dev/prod 口径或其他版本 lane 混用。 + +### 2.2 范围内 + +- AgentRun `v0.1` runtime namespace、GitOps branch、Tekton namespace、Pipeline、ServiceAccount、PipelineRun 命名和 runtime path。 +- Env image reuse、digest-pinned image、artifact promotion 和 runner/backend work-ready image 要求。 +- AgentRun manager、runner、Postgres、SecretRef、provider profile、Queue/Session 和 backend real turn 在综合联调中的发布判定。 +- AgentRun CLI 在发布验收中的正式操作入口，包括 runs、commands、runner jobs、queue、sessions、provider profiles、backends、secrets 和 server lifecycle 命令。 + +### 2.3 范围外 + +- 通用发布流水、镜像 promotion 和验证分层规则归 [发布流水](PJ2026-010601-controlled-release.md)。 +- AgentRun source branch、fixed worktree、Git mirror、GitOps branch 和 artifact catalog source truth 归 [AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md)。 +- AgentRun run、command、runner job、event 和 terminal status 归 [AgentRun核心](PJ2026-010201-agentrun-core.md)。 +- RuntimeAssembly、AipodSpec、gitbundle 和 Secret projection 归 [Runtime装配](PJ2026-010202-runtime-assembly.md)。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| AgentRun v0.1 lane | AgentRun `v0.1` 的 runtime namespace、GitOps branch、CI pipeline、image registry 和发布验收集合。 | +| AgentRun CI | G14 上用于 AgentRun `v0.1` 构建、promotion 和 GitOps 更新的 Tekton pipeline。 | +| env image | AgentRun runner/backend 的 work-ready 基础执行环境镜像。 | +| real provider turn | 通过真实 Codex app-server stdio backend 和真实 provider SecretRef 完成的一次 Code Agent turn。 | + +## 4. 系统边界和接口 + +本规格把 AgentRun发布Lane作为发布流水下的 AgentRun 专项发布切片看待；本章只描述输入、输出和责任边界。 + +| 边界项 | 内容 | +| --- | --- | +| 外部使用者 | AgentRun 维护者、平台运维、HWLAB Agent 维护者和 CI/CD 自动化任务。 | +| 外部输入 | AgentRun source commit、deploy/deploy.json、lane 配置、SecretRef presence、Tekton trigger、GitOps sync 和验证请求。 | +| 受控资源 | `agentrun-v01` runtime namespace、AgentRun Tekton Pipeline、Argo Application、runtime image、manager/runner workload 和 provider profile SecretRef。 | +| 外部输出 | PipelineRun 状态、image digest、promotion revision、runtime readiness、AgentRun CLI JSON、真实 turn 结果和 redacted failureKind。 | +| 用户接口 | UniDesk AgentRun CI/CD CLI、`./scripts/agentrun ...`、AgentRun REST API 和 service health/readiness。 | +| 系统边界 | AgentRun发布Lane只定义 AgentRun `v0.1` 的发布和验证细则；不替代 AgentRun 功能规格，也不把 mock、dry-run 或 source-only 结果当作发布通过。 | + +## 5. 内部分工与规格索引 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| PJ2026-0106010501 | RuntimeLane | 本规格 6.1 | namespace、GitOps path、Pipeline、ServiceAccount 和 rollout 目标 | AgentRun源码真相、YAML运维 | AgentRun runtime | +| PJ2026-0106010502 | EnvImage | 本规格 6.2 | env image identity、digest-pinned image、work-ready 工具和 promotion | Source commit、registry、Containerfile | Runtime装配、runner job | +| PJ2026-0106010503 | CLI验收 | 本规格 6.3 | AgentRun CLI JSON、短返回、redaction 和正式命令入口 | AgentRun REST API | HWLAB 接入、队列会话 | +| PJ2026-0106010504 | 真实联调 | 本规格 6.4 | real provider turn、Postgres durable facts、SecretRef 和 terminal status | AgentRun核心、后端Profile | 发布判定 | + +## 6. 原子需求 + +### 6.1 AR-RELEASE-REQ-001 v0.1 Runtime Lane + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-RELEASE-REQ-001 | RuntimeLane | PJ2026-0106010501 RuntimeLane | [AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md) | + +AgentRun `v0.1` 应使用独立 runtime lane，固定部署到 `agentrun-v01` namespace，并通过 AgentRun 专用 Tekton Pipeline、GitOps path 和 Argo Application 进入运行面。 + +`v0.1` 不复用旧 `dev/prod` 管理口径，不使用临时 clone、本地镜像、手工 Pod patch、自研 poller 或直接运行副本作为发布真相。后续 `v0.2`、`v0.3` 应使用各自独立 namespace、GitOps path 和 lane 配置。 + +### 6.2 AR-RELEASE-REQ-002 Env Image 与 Work-ready Runtime + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-RELEASE-REQ-002 | EnvImage | PJ2026-0106010502 EnvImage | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[源码同步](PJ2026-010602-source-sync.md) | + +AgentRun `v0.1` 的 runner/backend image 应按 env image reuse 模型构建和 promotion，最终运行面只使用 digest-pinned image。 + +AgentRun env image 必须包含 runner/backend 执行所需基础工具和生产依赖，使普通 Queue task、Session send 或 HWLAB canary 不在任务运行时默认安装基础环境。RuntimeAssembly 的 BackendImageRef 应能追溯 source commit、Dockerfile path、env identity、reuse/build 状态和 digest 摘要。 + +### 6.3 AR-RELEASE-REQ-003 AgentRun CLI 发布验收入口 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-RELEASE-REQ-003 | CLI验收 | PJ2026-0106010503 CLI验收 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[队列会话](PJ2026-010203-queue-session.md)、[后端Profile](PJ2026-010204-backend-profile.md) | + +AgentRun `v0.1` 发布验收应使用 `./scripts/agentrun` 作为正式 CLI 入口，覆盖 runs、commands、runner jobs、queue、sessions、provider profiles、backends、secrets 和 server lifecycle。 + +CLI 默认输出 JSON，stdout 不得为空伪成功，长时间模型 turn 必须短返回后通过 status/events 观察。发布验收不得用 debug/mock 路径、数据库直连或临时 kubectl 操作替代正式 CLI/API。 + +### 6.4 AR-RELEASE-REQ-004 AgentRun 真实综合联调 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-RELEASE-REQ-004 | 真实联调 | PJ2026-0106010504 真实联调 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[后端Profile](PJ2026-010204-backend-profile.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) | + +AgentRun `v0.1` 综合联调必须在真实 `agentrun-v01` 运行面完成，使用真实 Postgres、真实 Kubernetes SecretRef、真实 manager/runner/backend、真实 RuntimeAssembly 和至少一个真实 Code Agent provider turn。 + +mock backend、fake provider、source-only、dry-run、缺 provider credential 时的 skip、只读 health 成功或没有真实 command terminal status 的运行面状态，都不能作为 AgentRun 发布通过证据。涉及 profile 的变更还必须覆盖相关 backendProfile 的真实切换与隔离。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010602-source-sync.md b/project-management/PJ2026-01/specs/PJ2026-010602-source-sync.md new file mode 100644 index 00000000..ee3972a7 --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-010602-source-sync.md @@ -0,0 +1,127 @@ +# PJ2026-010602 源码同步 + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | + +当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 + +## 正文 + +## PJ2026-010602 源码同步需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PJ2026-010602 | +| 短名 | 源码同步 | +| 层级 | L2 课题 | +| 状态 | 已生效 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | +| 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) | +| 规格治理索引 | [规格治理](spec-governance.md) | + +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 Git mirror、source commit authority、GitOps 分支、artifact catalog、bundle/mirror URL 和运行面源码真相的通用稳定使命、范围、术语、系统边界、内部分工和原子需求。 + +## 2. 目的和范围 + +### 2.1 目的 + +源码同步负责让 HWLAB 平台服务运行面、CI/CD、RuntimeAssembly 和 gitbundle 资源装配都能引用明确、可验证、可追溯的 Git 来源，避免临时 clone、落后 worktree、运行面副本或不可复验 artifact 成为 source truth。具体服务的固定 branch、worktree、GitOps branch 和 artifact path 写入对应服务专项规格。 + +### 2.2 范围内 + +- G14、D601 和平台运行面使用的 Git mirror read/write URL、mirror cache、source branch 和固定 worktree 规则。 +- HWLAB 各服务的 source branch、source worktree、GitOps branch、artifact catalog 和 runtime path 的通用 source truth 关系。 +- RuntimeAssembly `ResourceBundleRef.kind="gitbundle"` 所需的 repo URL、ref、actual commit、bundle 摘要和 mirror 改写边界。 +- GitOps desired state 与 source branch 分离，promotion 只写 artifact catalog 和 rendered manifests，不把运行副本变成源码真相。 +- 运行面、CLI 和发布输出中的 source revision、artifact catalog、bundle/mirror URL 和 commit 摘要可见性。 + +### 2.3 范围外 + +- CI/CD 执行、镜像 promotion、rollout 和发布候选判定归 [发布流水](PJ2026-010601-controlled-release.md)。 +- YAML target/lane/node/service 配置、SecretRef 下发和敏感输出约束归 [YAML运维](PJ2026-010603-yaml-first-ops.md)。 +- 具体服务执行生命周期归对应业务规格；AgentRun run/command/runner job 执行生命周期归 [AgentRun核心](PJ2026-010201-agentrun-core.md)，AgentRun `v0.1` 专项 source truth 归 [AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md)。 +- Agent workspace 中业务代码如何被模型修改、测试或提交归对应业务任务，不属于源码同步定义。 +- GitHub issue/PR 过程记录、一次性迁移报告和长证据不进入本规格正文。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| source truth | 某服务或资源装配的权威 Git 来源，包括 repo URL、branch/ref、commit 和必要的 GitOps artifact。 | +| Git mirror | 为目标运行面提供 Git read/write 缓存和 source sync 的平台基础设施。 | +| source worktree | 固定在目标节点上的 source branch 工作区，只作为预检、同步和直接轻量文档交付入口。 | +| GitOps branch | 与 source branch 分离的 desired state 分支，只保存渲染后运行面资源和 artifact catalog。 | +| artifact catalog | 记录 image、env identity、source commit、runtime path 和 manifest 摘要的发布产物索引。 | +| gitbundle | RuntimeAssembly 中通过 Git repo/ref/bundles 物化工具、skills、prompt 和 workspace 文件的资源包。 | +| actual commit | gitbundle 或 source checkout 实际解析并物化到运行面的 commit。 | + +## 4. 系统边界和接口 + +本规格把源码同步作为平台运维内的 source truth 和 Git 资源同步系统看待；本章只描述输入、输出和责任边界。 + +| 边界项 | 内容 | +| --- | --- | +| 外部使用者 | 发布流水、Runtime装配、agent runner、服务维护者、平台运维 CLI 和业务模块。 | +| 外部输入 | Git remote、source branch、requested ref、commitId、GitOps branch、bundle paths、mirror target、promotion 请求和 source status 查询。 | +| 受控资源 | Git mirror、source worktree、GitOps branch、artifact catalog、gitbundle checkout、actual commit 摘要和 bundle/mirror URL。 | +| 外部输出 | source revision、mirror URL、actual commit、tree/bundle 摘要、artifact catalog path、GitOps revision 和 source sync 状态。 | +| 用户接口 | UniDesk CLI、服务自有 CLI source/status 输出、发布流水状态、RuntimeAssembly result/event 摘要。 | +| 系统边界 | 源码同步负责 Git 来源和 artifact 来源可追溯；不执行模型任务，不决定发布是否通过，不把运行面副本或临时目录提升为 source truth。 | + +## 5. 内部分工与规格索引 + +本规格前四个 L3 只承载服务无关的通用源码规则。AgentRun 固定 source branch、fixed worktree、GitOps branch、artifact catalog 和 mirror 细则只在 AgentRun 专项 L3 中展开，通用源码同步条款只保留可复用的 source truth 边界。 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| PJ2026-01060201 | Mirror同步 | 本规格 6.1 | Git mirror read/write URL、mirror cache 和 source branch 同步 | Git remote、平台网络 | 发布流水、Runtime装配 | +| PJ2026-01060202 | SourceTruth | 本规格 6.2 | fixed worktree、source branch、remote、clean/ff-only 状态 | Git mirror、项目仓库 | 服务 source 预检 | +| PJ2026-01060203 | GitOps目录 | 本规格 6.3 | GitOps branch、artifact catalog、runtime path 和 desired state | 发布流水 promotion | Argo sync、runtime 发布 | +| PJ2026-01060204 | GitBundle来源 | 本规格 6.4 | repoUrl/ref/actual commit/bundles 摘要和 mirror 改写 | Runtime装配、Git mirror | Agent runner、skills/tools | +| PJ2026-01060205 | AgentRun源码 | [PJ2026-01060205 AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md) | AgentRun `v0.1` source branch、fixed worktree、GitOps branch、artifact catalog 和 mirror 细则 | Git mirror、发布流水 | AgentRun runtime、Runtime装配 | + +## 6. 原子需求 + +### 6.1 OPS-SOURCE-REQ-001 Git Mirror 同步 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-SOURCE-REQ-001 | Mirror同步 | PJ2026-01060201 Mirror同步 | [发布流水](PJ2026-010601-controlled-release.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) | + +源码同步应提供 Git mirror read/write 能力，使 CI/CD、RuntimeAssembly 和目标运行面优先通过平台 mirror 获取 GitHub 资源，避免把外网直连失败或临时 clone 作为源码阻塞。 + +mirror 输出应能说明 owner/repo、read URL、write URL、cache 状态和同步来源，但不得输出 Git credential、SSH private key 或可复制 token。 + +### 6.2 OPS-SOURCE-REQ-002 Source Truth 预检 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-SOURCE-REQ-002 | SourceTruth | PJ2026-01060202 SourceTruth | [发布流水](PJ2026-010601-controlled-release.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) | + +源码同步应维护每条运行 lane 的 source truth，使固定 worktree、source branch、remote、clean 状态和 ff-only 同步结果可被发布流水和维护者确认。 + +具体服务的固定 source worktree、branch、remote 和历史废弃路径写入对应服务专项规格。开始开发、文档落库、发布或 render 前必须确认 source truth；临时 clone、运行副本、旧 worktree 或 master server 缓存不能替代它。 + +### 6.3 OPS-SOURCE-REQ-003 GitOps 与 Artifact Catalog + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-SOURCE-REQ-003 | GitOps目录 | PJ2026-01060203 GitOps目录 | [发布流水](PJ2026-010601-controlled-release.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md) | + +源码同步应将 source branch 与 GitOps branch 分离，使 Tekton promotion 只把 artifact catalog 和 rendered manifests 写入 GitOps desired state，而不把运行面生成物回写到 source branch。 + +GitOps 输出应能追溯 source commit、runtime path、image digest、manifest revision 和 artifact catalog path。source branch 不应包含 CI 自动构造物、runtime dump、Secret data 或临时报告。 + +### 6.4 OPS-SOURCE-REQ-004 GitBundle Source Authority + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| OPS-SOURCE-REQ-004 | GitBundle来源 | PJ2026-01060204 GitBundle来源 | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) | + +源码同步应为 gitbundle 装配提供 source authority，使 `ResourceBundleRef.repoUrl`、requested ref、actual commit、tree、bundles、promptRefs、tools 和 skills 的来源可验证。 + +runner materialization 可以按平台规则把 GitHub URL 改写到 G14 git mirror，但不得让 prompt、payload、host path、Secret volume、用户上传目录或运行时临时文件成为 gitbundle 的权威来源。event/result 只输出路径、hash、bytes、commit 和 bundle 摘要，不输出文件全文或凭据。 diff --git a/project-management/PJ2026-01/specs/PJ2026-01060205-agentrun-v01-source-truth.md b/project-management/PJ2026-01/specs/PJ2026-01060205-agentrun-v01-source-truth.md new file mode 100644 index 00000000..46454eaf --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-01060205-agentrun-v01-source-truth.md @@ -0,0 +1,110 @@ +# PJ2026-01060205 AgentRun源码真相 + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | + +当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 + +## 正文 + +## PJ2026-01060205 AgentRun源码真相需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PJ2026-01060205 | +| 短名 | AgentRun源码 | +| 层级 | L3 子课题 | +| 状态 | 已生效 | +| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | +| 上级规格 | [PJ2026-010602 源码同步](PJ2026-010602-source-sync.md) | +| 规格治理索引 | [规格治理](spec-governance.md) | + +本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 AgentRun `v0.1` 的 source branch、fixed worktree、Git mirror、GitOps branch、artifact catalog 和 gitbundle source authority。 + +## 2. 目的和范围 + +### 2.1 目的 + +AgentRun源码真相负责定义 AgentRun `v0.1` 的 Git source truth，使开发、规格落库、CI/CD、GitOps promotion、RuntimeAssembly 和 runner materialization 都引用同一 source branch、fixed worktree、mirror 和 artifact catalog。 + +### 2.2 范围内 + +- AgentRun `v0.1` source repo、source branch、G14 fixed source worktree、worktree root 和 remote。 +- Git mirror read/write URL、mirror cache 和 promotion 时的 source/GitOps 分离。 +- `v0.1-gitops` branch、artifact catalog、runtime path 和 source revision 可追溯关系。 +- AgentRun gitbundle materialization 中 GitHub URL 到 G14 git mirror 的改写和 actual commit 摘要。 +- 固定 source truth 预检、ff-only 同步、clean 状态和禁止临时 clone/运行副本成为 source truth。 + +### 2.3 范围外 + +- 通用源码同步、Git mirror 和 artifact catalog 规则归 [源码同步](PJ2026-010602-source-sync.md)。 +- AgentRun 发布、Pipeline、runtime namespace 和真实联调归 [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)。 +- AgentRun run、command、event 和 terminal status 归 [AgentRun核心](PJ2026-010201-agentrun-core.md)。 +- RuntimeAssembly 对 gitbundle 的字段语义归 [Runtime装配](PJ2026-010202-runtime-assembly.md)。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| fixed source worktree | AgentRun `v0.1` 在 G14 上的固定 source truth 工作区。 | +| v0.1-gitops | AgentRun `v0.1` 的 GitOps desired state 分支。 | +| artifact catalog | AgentRun CI promotion 生成的 artifact 索引文件，记录 image、source commit 和 runtime manifest 摘要。 | +| runtime path | GitOps branch 中 AgentRun `v0.1` runtime manifests 的路径。 | +| mirror read URL | CI/CD 或 runner materialization 拉取 AgentRun/相关 repo 时优先使用的 Git mirror 地址。 | + +## 4. 系统边界和接口 + +本规格把 AgentRun源码真相作为源码同步下的 AgentRun 专项 source truth 看待；本章只描述输入、输出和责任边界。 + +| 边界项 | 内容 | +| --- | --- | +| 外部使用者 | AgentRun 维护者、发布流水、Runtime装配、runner materialization 和平台运维。 | +| 外部输入 | AgentRun source branch、requested ref、GitOps promotion 请求、mirror sync 请求、gitbundle repo/ref 和 source status 查询。 | +| 受控资源 | G14 fixed source worktree、Git mirror、GitOps branch、artifact catalog、runtime path 和 actual commit 摘要。 | +| 外部输出 | source commit、remote、branch、clean/ff-only 状态、mirror URL、GitOps revision、artifact catalog path 和 gitbundle actual commit。 | +| 用户接口 | UniDesk trans/CLI 预检入口、AgentRun CI/CD CLI、RuntimeAssembly event/result source 摘要。 | +| 系统边界 | AgentRun源码真相只定义 AgentRun `v0.1` Git 来源和 artifact 来源；不执行发布、不判断功能通过、不把运行面副本或临时目录变成 source truth。 | + +## 5. 内部分工与规格索引 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| PJ2026-0106020501 | SourceWorktree | 本规格 6.1 | source repo、branch、G14 fixed worktree、remote 和 clean/ff-only 预检 | Git remote、Git mirror | 发布流水、规格落库 | +| PJ2026-0106020502 | GitOpsArtifact | 本规格 6.2 | GitOps branch、artifact catalog、runtime path 和 source revision | 发布流水 promotion | Argo runtime | +| PJ2026-0106020503 | MirrorMaterialize | 本规格 6.3 | mirror URL、gitbundle actual commit、bundle 摘要和 source event | Runtime装配、Git mirror | runner materialization | + +## 6. 原子需求 + +### 6.1 AR-SOURCE-REQ-001 AgentRun Fixed Source Worktree + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-SOURCE-REQ-001 | SourceWorktree | PJ2026-0106020501 SourceWorktree | [发布流水](PJ2026-010601-controlled-release.md)、[AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) | + +AgentRun `v0.1` source truth 应固定为 `git@github.com:pikasTech/agentrun.git` 的 `v0.1` branch，并在 G14 fixed source worktree 中保持可预检、可 ff-only 同步和可确认 clean 状态。 + +固定 source worktree 只作为 source truth、规格直接落库和轻量文档交付入口。普通源码/配置开发应按 AgentRun 仓库规则进入独立 worktree；临时 clone、旧 dev/prod worktree、运行面副本、master server 缓存或一次性目录不得替代 AgentRun `v0.1` source truth。 + +### 6.2 AR-SOURCE-REQ-002 AgentRun GitOps 与 Artifact Catalog + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-SOURCE-REQ-002 | GitOpsArtifact | PJ2026-0106020502 GitOpsArtifact | [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md) | + +AgentRun `v0.1` 应使用独立 GitOps branch 和 runtime path 保存 rendered desired state，并用 artifact catalog 记录 source commit、image digest、env identity 和 manifest 摘要。 + +source branch 与 GitOps branch 必须分离。Tekton promotion 只能把 artifact catalog 和 rendered manifests 写入 GitOps branch；不得把 live DB dump、runtime pod 状态、Secret data、CI 临时输出或执行报告回写到 source branch。 + +### 6.3 AR-SOURCE-REQ-003 AgentRun GitBundle Source + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| AR-SOURCE-REQ-003 | MirrorMaterialize | PJ2026-0106020503 MirrorMaterialize | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md) | + +AgentRun gitbundle materialization 应优先使用 G14 Git mirror 拉取 GitHub repo，并在 event/result 中记录 requested ref、actual commit、tree、bundle path、hash、bytes 和 mirror 摘要。 + +Git mirror 改写只能发生在 materialization 阶段，不能改变 AipodSpec 或 run payload 中的 source authority。非 GitHub URL 不应被强行改写；缺少 mirror cache 是基础设施缺口，不能通过 prompt、host path、Secret volume 或用户上传目录绕过。 diff --git a/project-management/PJ2026-01/specs/spec-governance.md b/project-management/PJ2026-01/specs/spec-governance.md index 9dba0900..97da4d54 100644 --- a/project-management/PJ2026-01/specs/spec-governance.md +++ b/project-management/PJ2026-01/specs/spec-governance.md @@ -96,3 +96,11 @@ L1 方向必须是直接服务 L0 使命的一等产品/系统边界，并能定 - L2/L3/L4 执行 issue 必须写明编号、短名、上级总项目、主责方向、关联方向、目标 lane/branch、验收入口和完成后回写对象。 - 稳定规则和长期规格最终应沉淀到 `project-management/PJ2026-01`；issue 保留执行状态、讨论、证据和交叉引用。 - agent 处理 HWLAB OA/总规格/项目漂移/issue 树任务时，应先加载 `$unidesk-oa`，并以 [L0 总规格](PJ2026-01-HWLAB.md) 和对应 L0 issue 锚点为准。 + +## AgentRun 跨仓规格归位 + +- AgentRun 是 HWLAB [Agent编排](PJ2026-0102-agent-orchestration.md) 的执行基础设施，不单独创建新的 OA L0 项目。 +- AgentRun 仓库内 `docs/reference/spec-v01-*.md` 只保留到 UniDesk OA 规格的交叉引用 stub；规格正文归 `project-management/PJ2026-01/specs/` 管理，避免双份规格漂移。 +- AgentRun 功能规格按职责落到 [AgentRun核心](PJ2026-010201-agentrun-core.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md)、[队列会话](PJ2026-010203-queue-session.md)、[后端Profile](PJ2026-010204-backend-profile.md) 和 [HWLAB接入](PJ2026-010205-hwlab-dispatch.md)。 +- 通用发布、源码同步和 YAML/Secret 运维仍归平台运维；只有能抽象到多服务共用的规则才放通用 L2。AgentRun 固定 lane、source truth 和真实联调等专项事实只作为 [发布流水](PJ2026-010601-controlled-release.md) 与 [源码同步](PJ2026-010602-source-sync.md) 下的 AgentRun L3 管理。 +- 迁移仓库内大量 SPEC 时，先合并为少量稳定 L2，再把服务、lane、source truth、验证切片拆到 L3；不要按原始文件一比一制造 L2。