Merge remote-tracking branch 'origin/master' into feat/selfmedia-cicd-timing

# Conflicts: # docs/MDTODO/pr-merge-driven-automatic-delivery.md
2026-07-14 11:05:48 +02:00
parent 7e8b83962e 1f57332190
commit ca092389d1
12 changed files with 328 additions and 10 deletions
@@ -14,6 +14,10 @@ description: UniDesk 主代理调度子代理的必读技能。用户提到子
  - 既有权限、Secret 脱敏、不可逆操作和损害预防边界继续生效，本规则不授权绕过既有安全底线；
  - 发现衍生问题时，只能创建独立 issue 或记录待办，不得扩大当前 prompt、PR、合并范围或验收前置；
  - 现有机制阻碍原始目标时，先寻找既有架构内的最小实现路径；确需架构扩展时，必须向用户说明与原始目标的关系并取得明确授权。
+  - bug fix 不得擅自改变 event authority、transport、persistence、replay 或 source of truth；发现现有架构可能是根因时，也必须先完成证据和规格裁决。
+  - 涉及事件、投影、实时、回放或持久化的派单，主代理必须在子 issue 中先写出 current data flow 和 desired data flow；两者存在架构变化时，先更新长期 SPEC 并取得用户明确授权，再允许实施。
+  - 新增测试只能验证已经授权的合同，不能用测试通过把未经授权的架构变化、迁移依赖或新 authority 合法化。
+  - 主代理审核顺序固定为：先比较用户最新目标、适用 SPEC 和 current/desired data flow，再审核代码内部一致性、测试和实现质量；后者通过不能覆盖前者偏离。
 - 执行型和调研型委派默认优先使用 AgentRun `Artificer`：
  - Artificer 的 `create task`、`apply` 和 `dispatch` 必须以下文“子 issue + MDTODO”登记为 fail-closed 前置；禁止先创建 task 或派单再补登记；
  - 原生子代理和 Artificer 每次派单前都必须已有对应 MDTODO ITEM 或 SUBITEM；派单 prompt 与最终报告必须写明同一个 MDTODO ID；
@@ -38,8 +42,9 @@ description: UniDesk 主代理调度子代理的必读技能。用户提到子
  - Artificer 禁止递归修复自身：
    - 影响派单、AipodSpec、provider/model、credential 投影、session/workspace、Runner、AgentRun runtime 或其 CI/CD 可用性的故障，调查与实现必须交给原生子代理；
    - Artificer 只能在修复自动上线后作为被测对象，执行最短 canary、原 session 续跑或业务验收；
-  - Artificer 可用时，新任务和可安全接续的剩余任务必须优先交给 Artificer，原生子代理只用于管理性主代理职责以外、且 Artificer 本身修复或恢复所必需的工作；
-  - Artificer 已被证明确实不可用时，先创建独立 issue 和泛化问题域 MDTODO，再派一个原生子代理修复 Artificer；紧急且边界独立的业务任务可以暂时派原生子代理，但不得把临时 fallback 固化为长期调度入口；
+  - Artificer 是所有执行型子代理任务的强制默认执行面：用户只说“子代理”“并行代理”或“派代理”时，必须使用 Artificer；只有用户明确指定“原生子代理”，或 Artificer 经有界 readiness、最短真实派单或 typed failure 证明确实不可用时，才允许使用原生子代理；
+  - 主代理不得因为方便、速度、空闲并发槽、已有原生 worktree、历史习惯或预计任务较短而自行降级到原生子代理；管理性、决策性工作由主代理直接完成，不构成原生子代理例外；
+  - Artificer 已被证明确实不可用时，先创建独立 issue 和泛化问题域 MDTODO，再派一个原生子代理修复 Artificer；只有与故障修复解耦且用户明确要求继续的紧急业务任务，才允许临时使用原生子代理，并必须在 Artificer 恢复后交接；不得把临时 fallback 固化为长期调度入口；
  - Artificer 恢复后，原生子代理必须在 clean commit、PR 或只读报告 checkpoint 停止继续扩展；主代理通过原 issue、MDTODO 和 session 传递接续上下文，再由 Artificer 接替尚未完成的工作；禁止两个执行面共享可写 worktree、重复提交或并发修改同一任务；
  - 管理性、决策性文档仍由主代理负责，不为了满足 Artificer 优先规则而外包治理决策。
 - 子代理并发必须从用户原始任务的依赖图出发主动扩展：
@@ -4,6 +4,8 @@

 ## 调度原则

+- 执行型任务默认且必须交给 Artificer。用户泛称“子代理”“并行代理”或“派代理”不等于授权原生子代理；只有用户明确指定原生子代理，或 Artificer 经有界 readiness、最短真实派单或 typed failure 证明不可用时，才允许原生执行面。
+- 主代理不能以方便、速度、空闲槽、已有 worktree、任务较短或历史习惯作为原生降级理由。Artificer 故障修复可由原生子代理承担；管理性与决策性工作仍由主代理直接完成。
 - 主代理先明确总目标、目标 repo/branch/lane、架构方向和不可倒退边界，再拆任务。不能把“决定架构是否倒退”“是否关闭用户问题”“是否合并 PR”整体外包给子代理。
 - 主代理直接审核子代理产出的 diff、验证证据和 PR。允许子代理实施、要求并行或多轮审查都不授权审核子代理；只有用户明确要求子代理审核时，才建立独立审核任务。
 - 只有低耦合任务才并行：不同 worktree、不同模块或不同 issue，产物可以独立 review，失败不会阻塞其他任务继续产出证据。
@@ -121,3 +121,7 @@
 ## R6 [completed]

 将“先恢复运行面再工程化”固化为 unidesk-subagent 的泛化主线规则：运行面恢复关键路径由主代理控制，低耦合工程化任务及时并行，恢复后继续完成工程化交付；将单 PR 收口、复用 guarded merge 内建 preflight、避免仅补 merge SHA 的重复 PR 和减少碎片化 GitHub 查询固化到 unidesk-gh 及相关 reference，并让 merge 默认摘要直接披露 merge commit 与 mergedAt，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R6_Task_Report.md)。
+
+## R7 [completed]
+
+将 Artificer 固化为所有执行型子代理任务的强制默认执行面：用户只说“子代理”时必须使用 Artificer；只有用户明确指定原生子代理，或 Artificer 经有界 readiness/真实派单证据确认故障不可用时，才允许原生子代理执行；禁止主代理因方便、速度、空闲槽或历史习惯自行降级，并要求 Artificer 恢复后立即停止原生扩展并交接，完成任务后将详细报告写入[任务报告](./details/agentrun-runtime-reliability/R7_Task_Report.md)。
@@ -0,0 +1,7 @@
+# R7 任务报告
+
+已将 Artificer 固化为执行型子代理任务的强制默认执行面。用户泛称子代理、并行代理或派代理时必须使用 Artificer；只有用户明确指定原生子代理，或 Artificer 经有界 readiness、最短真实派单或 typed failure 证明确实不可用时，才允许原生执行面。
+
+规则明确禁止主代理因方便、速度、空闲并发槽、已有 worktree、任务较短或历史习惯自行降级。Artificer 故障修复仍可交给原生子代理；管理性和决策性工作由主代理直接完成。临时原生 fallback 必须在 Artificer 恢复后停止扩展并交接。
+
+验证：unidesk-subagent skill quick_validate 通过；git diff --check 通过。
@@ -109,4 +109,4 @@

 ##### R4.4.2.10 [in_progress]

-执行 [HWLAB #2538](https://github.com/pikasTech/HWLAB/issues/2538)：删除六个架构 capability env 及 direct/live/refresh 分支，把 agentrun.event.v1→transactional projector→PostgreSQL facts/outbox→hwlab.event.v1→实时/回放 SSE 固定为代码不变量；新增 config/feature-config.schema.json 只描述 Trace、原始事件、调试重放和视图等产品功能，一个功能只用一个规范变量；保持 canonical duration、同 cursor/reducer 和纯 Kafka，禁止 HTTP 补链、页面轮询、双 authority、额外锁租约状态库，schema warning 不关闭功能、不改配置且不阻塞滚动上线，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.10_Task_Report.md)。
+执行 [HWLAB #2538](https://github.com/pikasTech/HWLAB/issues/2538) P0 架构纠偏：确认 PR #2540 把已工作的 agentrun.event.v1→hwlab.event.v1→实时 SSE/Kafka retention 回放错误替换为强制 PostgreSQL transactional projector，构成重大架构偏移；从最新 v0.3 分析偏移提交并创建新的精确纠偏提交，恢复 direct publish、live Kafka SSE、Kafka refresh replay 及其单一 Kafka authority，删除强制 v8 schema 启动门禁和数据库迁移依赖，保留 canonical duration 修复、feature-config schema、HTTP fallback 禁令及其他无关改动；通过新 PR 和自动 PaC/GitOps/Argo 上线后校对实时、回放、terminal/final 与 canonical duration，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.4.2.10_Task_Report.md)。
@@ -87,6 +87,20 @@

 执行 [UniDesk #1981](https://github.com/pikasTech/unidesk/issues/1981)：固定仓库产品功能 schema 路径为 config/feature-config.schema.json，CI/CD 只读校验 schema 语法、值匹配和功能到唯一配置变量的一对一关系；缺失、非法、不匹配或重复仅输出 typed warning 并投影到 OTel/status/history/debug-step，必须继续 artifact、GitOps/Argo 和滚动上线，禁止写回、默认值、变量删除、功能关闭、架构切换及其他补救操作，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R6_Task_Report.md)。

+<<<<<<< HEAD
 ## R7 [completed]

 依据 [UniDesk #2005](https://github.com/pikasTech/unidesk/issues/2005) 实现 SELFMEDIA CI/CD 单次只读查询：从 owning YAML 解析 selfmedia-nc01，在一次受控 CLI 调用内关联 pikainc/selfmedia GitHub mergedAt、PaC PipelineRun/TaskRun、Argo/runtime health，直接披露 trigger wait、pipeline duration、end-to-end duration 与证据缺口；同步 unidesk-cicd skill 的唯一推荐入口，禁止新增第二状态源或交付 mutation，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R7_Task_Report.md)。
+=======
+## R7 [in_progress]
+
+执行 [UniDesk #2008](https://github.com/pikasTech/unidesk/issues/2008)：按 PJ2026-01060106 建立 HWLAB 开发/生产双环境发布；v0.3 固定为 NC01 development，release 固定为 production，两个环境在 source、Pipeline、GitOps、Argo、namespace、public origin、PostgreSQL database/role/Secret/migration ledger 和 Kafka consumer group 上隔离，所有值由 owning YAML 控制，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R7_Task_Report.md)。
+
+### R7.1 [in_progress]
+
+迁移 [UniDesk #2009](https://github.com/pikasTech/unidesk/issues/2009)：保持 v0.3 开发 branch/namespace/DB consumer，删除其对 hwlab.pikapython.com 的所有权，选择并 YAML 固化 NC01 公网 IP 的空闲 HTTP 端口和同源 API/health/probe，通过新 PR 和自动链完成原入口验证，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R7.1_Task_Report.md)。
+
+### R7.2 [in_progress]
+
+建立 [UniDesk #2010](https://github.com/pikasTech/unidesk/issues/2010)：跟随 release branch 的独立 production PaC/Tekton/GitOps/Argo、namespace、host PostgreSQL database/role/Secret/migration ledger、Kafka consumer group 与 https://hwlab.pikapython.com YAML publicExposure；release 只从完成 P0 Kafka 纠偏并验证的 v0.3 commit 初始化，完成任务后将详细报告写入[任务报告](./details/pr-merge-driven-automatic-delivery/R7.2_Task_Report.md)。
+>>>>>>> origin/master
@@ -15,3 +15,11 @@
 ### R1.3 [completed]

 重新分发用户更新后的 SelfMedia 管理员凭据，并将 owning YAML、Secret sync/status、自动交付与公网鉴权验收最短路径沉淀到 `unidesk-selfmedia` skill；不得读取或输出凭据值，不得影响其他仓库 token 选择，完成任务后将详细报告写入[任务报告](./details/selfmedia-production-delivery/R1.3_Task_Report.md)。
+
+## R2 [in_progress]
+
+依据 [UniDesk #2006](https://github.com/pikasTech/unidesk/issues/2006) 优化 selfmedia-nc01 PaC 流水线的 env reuse 与依赖缓存：由 owning YAML、lockfile 和 source artifact 生成环境身份，依赖不变时复用并披露 hit/miss 与阶段耗时，依赖变化时正确失效；通过正常 SELFMEDIA PR merge 自动交付验收，保持 commit-pinned artifact、GitOps/Argo、runtime health 和单一 source authority，完成任务后将详细报告写入[任务报告](./details/selfmedia-production-delivery/R2_Task_Report.md)。
+
+## R3 [in_progress]
+
+依据 [UniDesk #2007](https://github.com/pikasTech/unidesk/issues/2007) 为 pikainc/selfmedia release 分支建立独立生产 PaC/GitOps 流水线：master 保持开发 consumer，release 精确驱动独立生产 namespace、Pipeline、GitOps branch/Application、runtime/PVC/Secret 与 YAML-first 公网端口；禁止 branch follower、手工同步和共享可写状态，以正常 release PR merge 验收生产公网入口、登录、digest 与 health，完成任务后将详细报告写入[任务报告](./details/selfmedia-production-delivery/R3_Task_Report.md)。
@@ -0,0 +1,84 @@
+# PJ2026-010401080313 纯Kafka权威架构偏离复盘
+
+## 1. 事件摘要
+
+| 字段 | 内容 |
+| --- | --- |
+| 严重度 | P0 开发事故 |
+| 日期 | 2026-07-14 |
+| 影响规格 | [PJ2026-010401080313 Workbench实时权威](../specs/PJ2026-010401080313-workbench-realtime-authority.md) |
+| 关联执行 | pikasTech/HWLAB#2538、PR #2540 |
+| 事故类型 | 未经授权改变 event authority、persistence 和 replay 架构，并引入数据库 schema 启动硬前置 |
+| 当前状态 | 已停止继续扩展，正在通过新 PR 精确纠偏；禁止粗暴 reset 或覆盖无关修改 |
+
+事故边界如下：
+
+- 原始目标是修复 Workbench timing/duration 与一次 17 分钟投影异常。
+- 原始架构要求坚持 `agentrun.event.v1 -> hwlab.event.v1 -> 实时 SSE / Kafka retention 回放 SSE`。
+- 实际实现把链路替换为 PostgreSQL transactional projector、facts/outbox 和数据库 replay。
+- 实际实现删除 direct publish、live Kafka SSE 与 Kafka refresh replay，构成对用户目标和实时权威的根本偏离。
+
+## 2. 时间线
+
+| 阶段 | 事实 |
+| --- | --- |
+| 事故前 | 运行配置启用 direct publish、live Kafka SSE、Kafka refresh replay；transactional projector 与 projection outbox relay 关闭。 |
+| 任务定义 | #2538 和 MDTODO 被错误写成“删除 direct/live/refresh，固定 transactional projector”，没有先证明 duration 故障需要改变 authority。 |
+| 实现 | `3e03e94e` 固定 transactional 投影并修改 timing；`fc87a7e5` 删除 direct/live/refresh；`bef23280` 删除 HTTP 自动补链；`2603b00c` 继续清理旧投影残余。 |
+| 合并 | PR #2540 通过 merge commit `6ae0d1b5a48118b6a65a521919de0bc5801e969d` 进入 `v0.3`。 |
+| 部署 | PipelineRun/GitOps 成功，但新 Cloud API Pod 因 `workbench_transactional_realtime_schema_blocked` CrashLoop；Argo 为 `Synced/Degraded`，旧 Pod 继续服务。 |
+| 判定 | 数据库迁移被误认为新架构的必要条件，随后确认它不是原纯 Kafka实时/回放能力的依赖。 |
+| 止损 | 主代理纠正 #2538 与 MDTODO，要求从最新 `v0.3` 建新分支和新 PR，逐文件恢复纯 Kafka路径并保留无关修复。 |
+
+## 3. 影响
+
+- 新 Cloud API Pod 无法启动，滚动发布退化；旧 Pod 暂时维持服务，因此未发生完整业务中断。
+- CI/CD 显示成功而运行面 `Degraded`，扩大了“流水线成功等于发布成功”的可见性误差。
+- 原本无需数据库迁移的实时/回放链被增加 v8 schema 前置，导致修复路径被错误引向数据库迁移。
+- direct publish、live/replay Kafka 代码被删除，回退成本从配置切换扩大为代码纠偏。
+- 子代理和主代理的多轮 review 围绕新架构内部一致性优化，消耗时间并偏离原始 Web 增强主线。
+
+## 4. 直接原因
+
+1. 任务合同直接把未经用户授权的 PostgreSQL transactional projector 写成目标架构。
+2. PR 删除原 authority 路径，并用启动断言强制新 schema 就绪。
+3. review 把“Kafka 仍在链路中”误判为“纯 Kafka”，没有检查 Kafka 是否仍是实时和回放 authority。
+4. canonical duration 修复与 authority 替换被耦合在同一 PR，未保持问题与架构变更的因果边界。
+
+## 5. 系统性原因
+
+- 派单前没有写出 current data flow、desired data flow 和两者差异，也没有要求用户授权 authority/persistence/replay 变化。
+- 主代理以测试和内部一致性替代对用户目标、最新 SPEC、线上运行配置和数据流的优先审查。
+- 较旧“Workbench唯一投影”规格包含数据库 outbox 设计，较新的纯 Kafka要求尚未形成明确优先级裁决；冲突未先解决就进入实现。
+- 新测试验证了 transactional 架构，却没有证明该架构是被授权目标；测试把偏移固化成了代码门禁。
+- rollout 验证只看到 PipelineRun/GitOps 成功，没有把新 Pod readiness、Argo health 和启动 blocker 作为同一发布判定。
+
+## 6. 主代理责任
+
+主代理对事故负最终责任：主代理创建和接受了错误任务合同，未在派单前完成架构裁决；review 时继续要求删除旧路径；在看到 schema blocker 后仍一度沿数据库迁移方向调查。子代理按错误合同实现不能替代主代理的架构审查责任。
+
+## 7. 检测与恢复
+
+本次事故由新 Pod CrashLoop、Argo `Synced/Degraded` 和 `workbench_transactional_realtime_schema_blocked` 暴露。恢复不执行数据库迁移来承认新架构，而是从最新 `v0.3` 创建精确纠偏提交：
+
+- 恢复 direct publish、live Kafka SSE 和 Kafka retention replay。
+- 删除 v8 schema 作为 Cloud API 启动前置。
+- 保留 canonical duration、feature config schema、HTTP fallback 禁令和无关修复。
+- 通过新的 PR、自动 PaC/GitOps/Argo 上线，并在原入口校对 live/replay SSE、terminal/final 和 canonical duration。
+
+禁止 reset、force push、整提交粗暴反转或人工 runtime patch，以免覆盖 PR #2540 中与架构偏移无关的正确修改。
+
+## 8. 纠正与防复发措施
+
+| 措施 | Owner | 完成判定 |
+| --- | --- | --- |
+| 更新实时权威 SPEC | 主代理 | 明确纯 Kafka data flow、数据库非阻塞边界和新旧规格优先级。 |
+| 精确纠偏 PR #2540 | HWLAB 实施代理 | 新 PR 恢复 live/replay 路径，Cloud API 不再依赖 v8 schema 启动。 |
+| 原入口验证 | 主代理审核 | 自动上线后以同一 session/trace 校对实时、刷新回放、terminal/final 与 duration。 |
+| 固化派单规则 | 主代理 | `unidesk-subagent` 要求 current/desired data flow 和架构变化授权。 |
+| 固化 review 顺序 | 主代理 | 先比较用户目标、SPEC、运行 data flow，再看代码内部一致性和测试。 |
+| CI/CD 可见性 | 独立任务 | PipelineRun 成功但 Argo/Pod degraded 时明确报告发布未完成，不以 schema warning 阻塞滚动。 |
+
+## 9. 长期判定
+
+修复 timing、duration、丢事件或 UI 收敛问题时，不得默认改变 event authority、transport、persistence、replay 或 source of truth。若证据表明确需架构变化，必须先更新长期 SPEC，写清 current/desired data flow、迁移与回退方案，并取得用户明确授权；新增测试只能验证已授权架构，不能反向把未经授权的实现合法化。
@@ -7,6 +7,8 @@

 当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。

+> 裁决优先级：本规格中以 PostgreSQL aggregate event stream、transactional projector、durable outbox 或 `/v1/workbench/sync` 作为实时/回放 authority 的条款，已被 2026-07-14 的 [PJ2026-010401080313 Workbench实时权威](PJ2026-010401080313-workbench-realtime-authority.md) `draft-2026-07-14-p0-pure-kafka-authority` 取代。当前权威链固定为 `agentrun.event.v1 -> mapper -> hwlab.event.v1 -> 实时 SSE / Kafka retention 回放 SSE`；PostgreSQL 只可作为非阻塞派生读模型，不能成为 Cloud API 启动、Kafka 实时或回放的前置。未完成正文重整前，冲突条款一律以最新专项裁决为准。
+
 ## 正文

 ## PJ2026-0104010803 Workbench唯一投影需求规格
@@ -19,7 +19,7 @@
 | 短名 | Workbench实时权威 |
 | 层级 | L4 专项规格切片 |
 | 状态 | 草稿 |
-| 实现引用版本 | draft-2026-07-08-p0-workbench-realtime-authority-v2; draft-2026-07-09-p1-single-step-debug |
+| 实现引用版本 | draft-2026-07-08-p0-workbench-realtime-authority-v2; draft-2026-07-09-p1-single-step-debug; draft-2026-07-14-p0-pure-kafka-authority |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
 | 上级规格 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) |
 | 关联规格 | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[PJ2026-0106050514 Workbench实时运行面](PJ2026-0106050514-workbench-realtime-runtime.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-01060508 Web哨兵](PJ2026-01060508-web-probe-sentinel.md) |
@@ -31,14 +31,21 @@

 ### 2.1 目的

-Workbench实时权威负责把 Workbench 主 timeline、session rail、turn card、Final Response、Trace detail 和 transport diagnostic 的实时输入收敛到同一 durable projection 语义。当前目标不是“永远不用 REST”，而是禁止前端多端点补洞成为 correctness path：SSE typed event 是 live 主路径，`/v1/workbench/sync` 只能作为与 SSE 同语义的统一 replay/delta，initial snapshot 只负责页面初始水位，detail/history 只服务用户显式查看。
+Workbench实时权威负责把 Workbench 主 timeline、session rail、turn card、Final Response、Trace detail 和 transport diagnostic 收敛到纯 Kafka 事件权威：
+
+- 固定数据流为 `agentrun.event.v1 -> mapper -> hwlab.event.v1 -> 实时 SSE / Kafka retention 回放 SSE`。
+- 浏览器只消费同一 SSE 合同。
+- 断线、刷新和 cursor 缺口由服务端按 Kafka retention 回放后继续 live tail。
+- `/v1/workbench/sync` 或业务 REST 补链不得成为 correctness path。
+
+PostgreSQL 可以保存查询优化所需的派生读模型，但不是 `agentrun.event.v1` 与 `hwlab.event.v1` 之间的 inline authority，也不是实时或回放 SSE 的启动前置。读模型 schema 缺失、迁移未执行或投影器退化必须形成 warning/diagnostic，不能关闭 direct publish、live SSE、Kafka replay，不能阻塞 Cloud API 启动或滚动上线。

 本规格同时定义单步调试工作台。调试工作台必须能在不接触真实运行面、不触发 automatic recovery 和不污染生产 Workbench store 的前提下，用 fake SSE 数据逐条驱动同一 reducer，暴露每一步的 authority decision、entity version、state diff、DOM triad 和禁止请求。

 ### 2.2 范围内

 - `/v1/workbench/events` typed event 的 authority metadata、cursor、entity family/id/version、projectionRevision 和 terminal seal 语义。
- `/v1/workbench/sync` replay/delta 的语义边界：它是 SSE replay 等价物，不是第二套 REST repair 事实源。
+- Kafka retention 回放 SSE 的 cursor、去重、顺序和回放到 live tail 的切换语义。
 - initial snapshot、explicit detail/history、trace-detail-only payload、session list/detail/messages read model 和主状态投影之间的合并边界。
 - 前端 reducer/adapter 的 authority gate、sealed guard、detail-only rejection、late stale rejection 和 diagnostic 输出。
 - 自动恢复、SSE error、cursor gap、cross-tab projection signal 和 refresh/reconnect 的允许动作与禁止动作。
@@ -56,9 +63,9 @@ Workbench实时权威负责把 Workbench 主 timeline、session rail、turn card

 | 术语 | 定义 |
 | --- | --- |
-| Realtime Authority v2 | Workbench 主状态只能由 initial snapshot、SSE typed event、统一 `/v1/workbench/sync` replay/delta 和显式 detail/history 中各自被授权的 projection 输入更新的规则集合。 |
+| Realtime Authority v2 | Workbench 主状态只能由 initial snapshot、`hwlab.event.v1` 的 live/replay SSE typed event 和显式 detail/history 中各自被授权的输入更新的规则集合。 |
 | 高纯度 SSE | Workbench live correctness 优先由 SSE typed event 驱动；断线、重复、乱序和缺口通过同一 durable cursor/replay 语义处理，不回退到多个业务 REST endpoint 自行补事实。 |
-| sync replay | `/v1/workbench/sync` 或等价入口按 session/trace scope 与 cursor 返回的 typed delta。它必须能被转换为与 SSE 相同的 reducer event，并携带同一 authority metadata。 |
+| Kafka replay SSE | SSE 服务按客户端 cursor 从 `hwlab.event.v1` retention 回放 typed event，追上水位后在同一连接继续 live tail；replay 与 live 使用同一事件 schema 和 reducer。 |
 | 多源补洞 | 前端在 automatic recovery 中同时或顺序调用 `/turns`、`/sessions/:id/messages`、`/traces/:id/events`、旧 `/v1/agent/*` 等端点来推断 terminal/final/message/session 主状态。该模式禁止。 |
 | detail-only | 只服务 Trace detail、历史页、诊断和审计的 payload。它可以展示过程，不能覆盖主 message/finalResponse/turn/session authority。 |
 | terminal seal | 同一 durable projection revision 内写入的 message/part terminal status、turn terminal、Final Response、timing、session running=false 和 cursor checkpoint。 |
@@ -71,7 +78,7 @@ Workbench 主状态只接受以下输入：

 - `initial snapshot`：页面初始加载或 explicit user refresh 的水位输入，只能写入其声明的 session/message/turn/trace bucket。
 - `SSE typed event`：live delivery 主路径，必须携带 `contractVersion`、`realtimeAuthority`、`entity.family/id/version`、cursor 和 `projectionRevision`。
- `sync replay/delta`：与 SSE 同语义的 replay 输入，必须先转换为 typed event 或同等 reducer action，再进入主 reducer。
+- `Kafka replay SSE`：服务端按 cursor 从 `hwlab.event.v1` retention 回放，与 live event 使用同一 schema、authority metadata 和 reducer action。
 - `explicit detail/history`：用户显式打开的 trace detail、历史分页或详情读取，只能写 detail bucket 或 diagnostic bucket；声明 `detailProjection=true` 或 `authority=trace-detail-only` 时必须拒绝写主状态。
 - `optimistic local echo`：submit admission 前后的本地临时投影，必须有 stable id，对账后由 durable event/sync 覆盖；不得成为跨页面或刷新后的事实源。

@@ -81,6 +88,7 @@ Workbench 主状态只接受以下输入：
 - 用 trace tail、trace detail 末行、message text、session list preview、elapsed timeout、localStorage、DOM active card 或 analyzer fallback 推断 `running`、terminal、Final Response 或 session active。
 - 让 late session list/detail/messages、detail-only trace payload、transport diagnostic、requestfailed 或 stale running snapshot 覆盖 sealed entity version。
 - 用 reload、切换 session、自动 repair helper、测试后门或 probe analyzer suppress 把已经分裂的页面补成通过。
+- 用 `/v1/workbench/sync`、数据库 outbox replay、HTTP polling 或读模型查询替代 Kafka retention replay，或在 Kafka replay 可用前要求 PostgreSQL schema 就绪。

 ## 5. 单步调试工作台

@@ -123,7 +131,7 @@ fake 数据优先来自真实受控样本脱敏后的 fixture。合成 fixture

 静态验收：

- 自动恢复路径只允许 `SSE typed event`、`/v1/workbench/sync` replay 或 diagnostic；不得出现旧 `/turns`、`/sessions/:id/messages`、`/traces/:id/events` automatic fan-out 写主状态。
+- 自动恢复路径只允许 live/replay `SSE typed event` 或 diagnostic；不得出现 `/v1/workbench/sync`、旧 `/turns`、`/sessions/:id/messages`、`/traces/:id/events` automatic fan-out 写主状态。
 - `traceHydration*` 命名和运行时口径必须收敛为 `traceDetail*` 或显式 detail read；旧配置字段如保留，只能作为 deprecated alias。
 - `detailProjection=true`、`authority=trace-detail-only` 和缺 authority metadata 的输入必须被 reducer gate 拒绝写主状态，并产生可见 diagnostic。

@@ -133,6 +141,7 @@ fake 数据优先来自真实受控样本脱敏后的 fixture。合成 fixture
 - refresh/reconnect/cross-tab signal 后，control/observer/fresh page 不出现 persistent `cross-page-projection-divergence`。
 - `workbench-automatic-recovery-fanout-authority`、旧 agent read-through 和旧 Workbench detail fan-out 不回归。
 - fake SSE 单步调试可以在无真实 API、无 `/sync`、无补洞的模式下完成 terminal seal、late stale rejection、detail-only rejection 和两页收敛测试。
+- Cloud API 在 Workbench 数据库 schema 缺失或读模型迁移未完成时仍能启动，并继续 direct publish、live SSE 与 Kafka retention replay；退化项只形成可见 warning/diagnostic。

 ## 7. 过程控制

@@ -84,6 +84,7 @@
 | 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 |
+| PJ2026-01060106 | HWLAB双环境 | [PJ2026-01060106 HWLAB双环境](PJ2026-01060106-hwlab-dev-production-lanes.md) | HWLAB `v0.3` development 与 `release` production 的分支、流水线、公开入口和数据隔离 | 源码同步、YAML运维、Workbench实时权威 | HWLAB runtime |

 ## 6. 原子需求

@@ -0,0 +1,182 @@
+# PJ2026-01060106 HWLAB双环境
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-01060106 HWLAB双环境需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-01060106 |
+| 短名 | HWLAB双环境 |
+| 层级 | L3 子课题 |
+| 状态 | 草稿 |
+| 实现引用版本 | draft-2026-07-14-p0-hwlab-dev-production-lanes |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-010601 发布流水](PJ2026-010601-controlled-release.md) |
+| 关联规格 | [PJ2026-010602 源码同步](PJ2026-010602-source-sync.md)、[PJ2026-010603 YAML运维](PJ2026-010603-yaml-first-ops.md)、[PJ2026-010401080313 Workbench实时权威](PJ2026-010401080313-workbench-realtime-authority.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文定义 HWLAB 在 NC01 上的 development/production 双环境。所有可调事实由 owning YAML 控制，自动发布只由目标 source branch 的 PR merge/branch update 驱动，禁止人工补跑 PipelineRun、手工 Argo sync、运行时 patch 或从集群反解配置。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+把当前 `v0.3` 固定为开发环境，并建立跟随 `release` 分支的生产环境。两套环境在发布身份、运行资源、公开入口、数据库数据域和 Kafka consumer identity 上隔离，使开发变更可以持续滚动，同时只有经过开发原入口验证的 commit 才能晋升为生产基线。
+
+### 2.2 范围内
+
+- `v0.3` development 与 `release` production 的 source、PaC consumer、Tekton Pipeline、GitOps branch/path、Argo Application、namespace 和 artifact provenance。
+- development 的 NC01 公网 IP HTTP 入口与 production 的 `https://hwlab.pikapython.com` 入口。
+- 共用 NC01 host PostgreSQL 服务时，两套独立 database、role、Secret consumer 和 migration ledger。
+- 两套独立 Kafka consumer group identity，以及纯 Kafka实时/回放权威不被数据库迁移阻塞的边界。
+- `v0.3` 到 `release` 的受控晋升、自动部署和原入口验证。
+
+### 2.3 范围外
+
+- Web 页面能力和组件重写归客户端规格。
+- AgentRun 自身的发布 lane 和数据库归 AgentRun 专项规格。
+- DNS、Caddy、FRP 和证书服务的通用实现归 YAML运维与公开入口平台；本规格只定义 HWLAB 两个 consumer 的所有权。
+- 从 development 向 production 复制业务数据、Secret value 或用户会话不在本任务范围内。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| development lane | source 为 `v0.3`、保留当前开发 namespace、通过 NC01 公网 IP 空闲 HTTP 端口访问的 HWLAB 环境。 |
+| production lane | source 为 `release`、使用独立 production namespace、通过 `https://hwlab.pikapython.com` 访问的 HWLAB 环境。 |
+| 晋升 | 把已在 development 完成原入口验证的精确 commit 纳入 `release`，随后由 production 自动链发布。 |
+| 数据域隔离 | 两个环境不共享 PostgreSQL database、role、Secret consumer 或 migration ledger，任何 schema/data mutation 只作用于选中 lane。 |
+| 入口所有权 | owning YAML 中唯一声明某 public origin 的 consumer；同一 host/origin 不得同时归 development 和 production。 |
+
+## 4. 架构与数据流
+
+### 4.1 系统架构
+
+```mermaid
+flowchart LR
+  V03[HWLAB v0.3] --> DEVPA[development PaC/Pipeline]
+  DEVPA --> DEVGIT[development GitOps]
+  DEVGIT --> DEVNS[development namespace]
+  DEVNS --> DEVHTTP[152.53.229.148:YAML端口]
+  DEVNS --> DEVDB[(host PostgreSQL: development database)]
+
+  REL[HWLAB release] --> PRODPA[production PaC/Pipeline]
+  PRODPA --> PRODGIT[production GitOps]
+  PRODGIT --> PRODNS[production namespace]
+  PRODNS --> PRODHTTPS[https://hwlab.pikapython.com]
+  PRODNS --> PRODDB[(host PostgreSQL: production database)]
+
+  KAFKA[(Kafka)] -->|development consumer group| DEVNS
+  KAFKA -->|production consumer group| PRODNS
+```
+
+### 4.2 运行数据流
+
+```mermaid
+flowchart LR
+  AR[agentrun.event.v1] --> MAP[HWLAB mapper]
+  MAP --> HE[hwlab.event.v1]
+  HE -->|development group| DEVSSE[development live/replay SSE]
+  HE -->|production group| PRODSSE[production live/replay SSE]
+  DEVSSE --> DEVWEB[development Web]
+  PRODSSE --> PRODWEB[production Web]
+  DEVWEB -.显式查询.-> DEVDB[(development read model)]
+  PRODWEB -.显式查询.-> PRODDB[(production read model)]
+```
+
+Kafka event 是实时与回放 authority。数据库只保存各 lane 的业务数据和派生读模型；任一数据库 schema 缺失不得改变 Kafka direct publish/live/replay 路径，也不得成为 Cloud API 启动或自动滚动前置。
+
+### 4.3 晋升与自动发布时序
+
+```mermaid
+sequenceDiagram
+  participant D as v0.3
+  participant DC as development CI/CD
+  participant DV as development 原入口验证
+  participant R as release
+  participant PC as production CI/CD
+  participant PV as production 原入口验证
+  D->>DC: merge/update commit C
+  DC->>DV: 自动构建、GitOps、rollout
+  DV-->>D: C 验证通过
+  D->>R: 受控晋升精确 commit C
+  R->>PC: branch update 自动触发
+  PC->>PV: 自动构建、GitOps、rollout
+  PV-->>R: digest/source/runtime/入口证据
+```
+
+初始 `release` 分支只能从完成 P0 纯 Kafka纠偏并在 development 原入口验证通过的 `v0.3` commit 创建。不得从已知强制 PostgreSQL transactional projector 的事故 commit 创建，也不得把 production 自动链的缺失用人工 PipelineRun 或 runtime patch 填补。
+
+## 5. 配置与隔离
+
+### 5.1 YAML-first 配置
+
+owning YAML 至少声明：
+
+- lane id、source repository/branch、PaC consumer、Pipeline、GitOps branch/path、Argo Application 和 namespace。
+- public exposure 的 scheme、host、port、target service、health path、Caddy/FRP managed block 引用。
+- PostgreSQL host service reference、database、role、Secret sourceRef/targetKey、migration ledger identity。
+- Kafka bootstrap SecretRef、topic contract、consumer group identity 和 replay retention/cursor 配置。
+- artifact repository、image name、digest provenance 和 source commit label。
+
+代码只校验和渲染 YAML，不内置 development/production 特例，不从现有 Deployment、Secret、Ingress、Caddy 或数据库反解事实。Secret 输出只允许 presence、object/key、fingerprint 和脱敏摘要。
+
+### 5.2 公开入口
+
+- development 正式入口是 `http://152.53.229.148:<development.publicExposure.port>`；实施任务应探测空闲端口并把最终值固化到 owning YAML。
+- production 正式入口固定为 `https://hwlab.pikapython.com`，由 production publicExposure 独占。
+- development 必须删除 `hwlab.pikapython.com` 的 route、probe、CORS/origin 和 managed block 所有权；Web/API/health 使用同源 development 入口。
+- production 证书、Caddy/FRP route 和 health probe 由 YAML 渲染，禁止手改共享配置文件。
+
+### 5.3 PostgreSQL 与 Kafka 隔离
+
+- 两个 lane 可以复用同一 NC01 host PostgreSQL 服务进程，但必须使用不同 database、role、Secret consumer 和 migration ledger。
+- migration 命令必须显式选中 lane，只能迁移其 database；禁止用共享 DSN、共享 schema 或默认 database 回退。
+- production 初始化不复制 development 会话、用户业务数据或 migration history；需要数据导入时必须另立受控任务。
+- development 与 production 使用不同 Kafka consumer group identity。运行状态和 lag 必须带 lane 标签，禁止同名 group 导致 offset 互相推进。
+- 数据库、Kafka 或 schema warning 不得触发功能关闭、authority 切换、HTTP fallback 或阻塞其他 lane 滚动上线。
+
+## 6. 原子需求
+
+### 6.1 HWLAB-LANE-REQ-001 Development迁移
+
+`v0.3` 自动链必须继续部署到 development namespace，并迁移到 YAML 声明的 NC01 公网 IP HTTP 入口。迁移完成后 `https://hwlab.pikapython.com` 只指向 production，不再路由到 development。
+
+### 6.2 HWLAB-LANE-REQ-002 Production自动链
+
+`release` 必须拥有独立 PaC consumer、Tekton Pipeline/ServiceAccount、GitOps branch/path、Argo Application、namespace、image provenance 和 release status。`release` update 自动触发完整链，不依赖主代理或值班人员人工补跑。
+
+### 6.3 HWLAB-LANE-REQ-003 Source与制品对齐
+
+每个 lane 的 PipelineRun、GitOps desired state、runtime image digest 和 workload label 必须能关联同一 source commit。缺失或不一致必须可见，但微服务契约、版本或 schema 检查只输出 warning，不得阻塞业务和滚动上线。
+
+### 6.4 HWLAB-LANE-REQ-004 数据边界
+
+任一 lane 的应用、migration、Secret 和管理命令不得连接另一 lane 的 database/role。验收必须证明两个环境写入的 canary 数据、migration ledger 和 consumer group offset 互不出现于对方数据域。
+
+### 6.5 HWLAB-LANE-REQ-005 原入口验收
+
+原入口验收要求如下：
+
+- development 从新的公网 IP HTTP 入口完成 Web、API、health 和至少一次实时/回放 SSE 验收。
+- production 从 `https://hwlab.pikapython.com` 完成同样验收。
+- production 同时核对 source commit、image digest、namespace、database identity 和 Kafka consumer group。
+- 源码测试、PipelineRun 成功或 Argo Synced 不能单独替代原入口通过。
+
+## 7. 过程控制
+
+- 父任务由 pikasTech/unidesk#2008 跟踪。
+- development 入口迁移由 pikasTech/unidesk#2009 和 MDTODO `R7.1` 跟踪。
+- production release lane 由 pikasTech/unidesk#2010 和 MDTODO `R7.2` 跟踪。
+- 两个实施任务可以在独立 worktree 并行；共享 YAML/publicExposure 基线的合并和上线顺序由主代理审核。
+- production 实现可以先准备，但 `release` 分支创建、生产部署和公网切换必须等待 P0 纯 Kafka纠偏在 development 验证完成。