From 3deaff174671c12ff01a1067f1fba76ba030738f Mon Sep 17 00:00:00 2001 From: pikastech Date: Sat, 18 Jul 2026 07:23:28 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20Workbench=20Kafka-?= =?UTF-8?q?only=20=E4=B8=8E=20L1=20=E7=AB=AF=E5=8F=A3=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/unidesk-devlevel/SKILL.md | 8 +++- .agents/skills/unidesk-kafka/SKILL.md | 25 +++++++++++++ .agents/skills/unidesk-webdev/SKILL.md | 7 +++- .../R4.5_Task_Report.md | 37 +++++++++++++++++++ .../MDTODO/observability-trace-reliability.md | 3 ++ 5 files changed, 76 insertions(+), 4 deletions(-) create mode 100644 docs/MDTODO/details/observability-trace-reliability/R4.5_Task_Report.md diff --git a/.agents/skills/unidesk-devlevel/SKILL.md b/.agents/skills/unidesk-devlevel/SKILL.md index d79e87e3..035c0266 100644 --- a/.agents/skills/unidesk-devlevel/SKILL.md +++ b/.agents/skills/unidesk-devlevel/SKILL.md @@ -43,8 +43,11 @@ description: >- ## L1 Native - 在 native 环境独立启动当前功能需要的 API、Worker、基础依赖和 HMR Web。 -- 每个 L1 服务必须使用 owning YAML 或项目规格声明的固定本地端口；启动前只识别同一服务的旧 L1 进程，若该固定端口已被它占用，先停止旧进程，再在同一端口启动新进程。 -- 不得因为端口冲突改用临时端口，也不得停止其他 L1、其他 worktree 或无关服务；无法确认端口占用者属于当前服务时先报告冲突。 +- 每个 L1 服务必须使用 owning YAML 或项目规格声明的端口： + - 同一服务的旧 L1 进程占用时，通过项目 CLI 停止或重启，再使用 YAML 当前端口； + - 其他服务占用时，禁止停止、接管或复用其他服务； + - 确认空闲端口后修改本服务 owning YAML，再由 parser/CLI 读取新端口继续； + - 禁止用命令行覆盖、临时环境变量或隐藏 fallback 形成第二端口真相。 - 固定端口、bind/probe/public host、状态目录和服务组成必须由 YAML-first 配置解析；代码和命令行不得补隐式端口默认值。 - L1 API、Worker、Temporal 开发依赖和 Web 的启动、停止、重启、状态、日志必须由项目 CLI 管理；`npm run`、`bun run`、`vite` 或裸脚本只允许作为 CLI 的内部实现，不是用户操作入口。 - CLI 显式使用项目 native `--over-api` transport，经 native API 调用 Worker。 @@ -57,6 +60,7 @@ description: >- - bind/probe 地址不得作为 L1 用户入口返回； - 公网 IP、API port 和 Web port 缺失时必须明确失败，不得回退到 localhost 或代码默认值。 - L1 验收命令必须实际从该公网 IP 打开页面和 API；本机 `127.0.0.1`/`localhost` 只可作为进程健康 probe，不构成 L1 证据。 +- HWLAB 的端口退让与公网验收细则以 `docs/reference/hwlab.md#workbench-浏览器回归专项` 为唯一权威，并由 `$unidesk-webdev` 执行。 - 适合前后端联调、异步作业、Workflow、网络接口和页面交互的快速开发。 ## L2 Development diff --git a/.agents/skills/unidesk-kafka/SKILL.md b/.agents/skills/unidesk-kafka/SKILL.md index bd951472..6aa76311 100644 --- a/.agents/skills/unidesk-kafka/SKILL.md +++ b/.agents/skills/unidesk-kafka/SKILL.md @@ -25,6 +25,31 @@ description: UniDesk Kafka 调试与事件链校对技能，覆盖 platform-infr - Kafka→SSE/reducer/read model 丢失或滞后。 - 版本、commit、schema/provenance 漂移只能作为 `warning`，不得阻塞用户业务或覆盖 durable terminal authority。 +## Kafka-only 第二权威审计 + +- 声明产品链路为 Kafka-only 前，必须同时审计事件入口、终态来源和配置来源；SSE 已连接或收到一个 topic event 不能单独证明通过。 +- 使用一次有界源码检索覆盖应用、renderer 和 owning YAML，再对命中做语义分类： + + ```bash + rg -n -S \ + '(/events|/result|waitForTerminal|projectTerminal|runnerTrace|snapshot|terminalAuthority|POLL_INTERVAL|TERMINAL_TIMEOUT)' \ + + ``` + +- 允许的路径： + - 提交接纳与 cancel 使用有界 `POST`，只返回 session/trace/run/command identity 和接纳状态； + - 非 UI 诊断读取 result/snapshot 时，必须与产品 reducer 隔离，不能写回消息、Trace 或 terminal 状态。 +- 禁止的第二权威： + - 轮询 AgentRun `/events` 或 `/result` 后补 UI event； + - 从 `runnerTrace.events`、session/turn snapshot、read model 或 terminal result 合成 assistant、tool、terminal、final； + - 把 `agentrun-command-result`、HTTP result、snapshot 或 projection read 声明为 Kafka-only UI terminal authority； + - 在 owning YAML、renderer 或进程环境保留仅服务于 result/events polling 的 timeout、interval 或开关。 +- 通过判定必须同时满足： + - UI assistant、tool、terminal、final 只由产品 Kafka envelope 经 SSE 和同一 reducer 产生； + - 正式 CLI 只从产品 SSE 路由观察业务 event； + - 运行配置不存在 polling 参数，进程环境不存在对应 polling 变量； + - AgentRun 或 CI/CD 不可用时明确报告 source blocker，不得启用 REST、snapshot、read-model 或 terminal-result fallback。 + ## 调查顺序 1. 固定 identity：记录 node/lane、business trace、OTel trace、session、run、command 和时间窗口。 diff --git a/.agents/skills/unidesk-webdev/SKILL.md b/.agents/skills/unidesk-webdev/SKILL.md index 7be8938c..1277fbd6 100644 --- a/.agents/skills/unidesk-webdev/SKILL.md +++ b/.agents/skills/unidesk-webdev/SKILL.md @@ -80,8 +80,11 @@ description: UniDesk Web 开发与受控浏览器验证技能。用户提到 Web - YAML 声明的 L1 端口被占用时： - 同一服务的旧 L1 进程只通过项目 CLI 停止或重启； - 其他服务不得停止、复用或接管； - - 必须等待旧进程退出，再在 YAML 声明的同一端口启动； - - 禁止改用临时端口、命令行覆盖或隐藏 fallback； + - 先用有界监听状态确认一个空闲端口； + - 再修改本 L1 服务的 owning YAML 端口并通过 parser/CLI 读取新值； + - 禁止用命令行覆盖、临时环境变量或隐藏 fallback 绕过 YAML； + - 端口退让后继续启动，并从 YAML 新端口执行 `web-probe native-readiness`； + - HWLAB 的唯一权威细则见 `docs/reference/hwlab.md#workbench-浏览器回归专项`； - L1 进程的启动、停止、重启、状态和日志必须通过项目 CLI，禁止把裸 `npm run`、`bun run`、`vite` 或临时脚本作为用户入口； - Vite 必须绑定可访问的 native 端口并保持 HMR，浏览器端 HMR 地址不得写成 `0.0.0.0`。 - HWLAB 工具页面默认使用受限工作区： diff --git a/docs/MDTODO/details/observability-trace-reliability/R4.5_Task_Report.md b/docs/MDTODO/details/observability-trace-reliability/R4.5_Task_Report.md new file mode 100644 index 00000000..39cf172a --- /dev/null +++ b/docs/MDTODO/details/observability-trace-reliability/R4.5_Task_Report.md @@ -0,0 +1,37 @@ +# R4.5 任务报告 + +## 结论 + +完成 [UniDesk #2502](https://github.com/pikasTech/unidesk/issues/2502) 的规则回归修复。后续 Workbench L1 调试以 owning YAML 为唯一端口真相，并在声明 Kafka-only 前一次审计事件入口、终态来源和配置来源，禁止 REST、snapshot 或 read-model 成为 UI 第二权威。 + +## 根因 + +- `d0ef4d2e` 已正确规定其他服务占用 L1 端口时，本服务修改 owning YAML 退让到空闲端口。 +- `31106a2e` 合并并行工作区语义时重新引入等待原端口的旧规则，导致 devlevel、WebDev 与 `docs/reference/hwlab.md` 冲突。 +- 既有 Kafka 验收偏重 EventSource 和 topic 连通性，未同时排除 AgentRun `/events`、`/result` polling、snapshot/read-model 补事件和 polling 配置，因此不能证明 UI 只有一个 terminal authority。 + +## 修改 + +- `$unidesk-devlevel`： + - 同服务旧进程只通过项目 CLI 停止或重启； + - 其他服务占用时修改本服务 owning YAML 退让； + - 禁止命令行、临时环境变量和隐藏 fallback 形成第二端口真相。 +- `$unidesk-webdev`： + - 恢复端口退让流程； + - 退让后从 YAML 新端口执行 `web-probe native-readiness`； + - 交叉引用 `docs/reference/hwlab.md#workbench-浏览器回归专项`，不复制第二份 HWLAB 规则。 +- `$unidesk-kafka`： + - 新增一次有界的 Kafka-only 第二权威审计； + - 同时覆盖 `/events`、`/result`、terminal projection、snapshot、authority 和 polling YAML/env； + - 明确 submit/cancel POST 只可返回 identity，AgentRun 或 CI/CD 故障时不得启用 fallback。 + +## 验证 + +- 三个 skill 均通过 `quick_validate.py`，结果均为 `Skill is valid!`。 +- 单次有界检索确认 L1 application/dispatcher 只保留 `terminalAuthority: "hwlab.event.v1"` 和会话读取声明，不存在 `/result`、`waitForTerminal`、`projectTerminal` 或 polling 环境变量。 +- owning YAML 中的 `/v1/agent/chat/result/` 与 `/snapshot` 命中属于 `forbiddenRequestPaths` 验收规则，不是实现 fallback；其他 snapshot 命中属于 source artifact 或内存 guard 等无关领域。 +- `git diff --check` 通过。 + +## 边界 + +本任务只修改 skill、MDTODO 和报告，没有修改 HWLAB、AgentRun、CI/CD 或任何运行面，不新增 runtime guard、合同测试、测试矩阵、第二 authority 或门禁。`rollout=not-applicable`。 diff --git a/docs/MDTODO/observability-trace-reliability.md b/docs/MDTODO/observability-trace-reliability.md index 61ce974c..fc1c5769 100644 --- a/docs/MDTODO/observability-trace-reliability.md +++ b/docs/MDTODO/observability-trace-reliability.md @@ -111,6 +111,9 @@ 执行 [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)。 +### R4.5 [completed] + +完成 [UniDesk #2502](https://github.com/pikasTech/unidesk/issues/2502)：恢复 L1 端口被其他服务占用时修改 owning YAML 退让到空闲端口的唯一规则，并在 Kafka skill 固化一次排除 AgentRun `/events`、`/result` polling、snapshot/read-model 补事件、terminal authority 与 polling YAML/env 的第二权威审计；不新增运行时 guard、第二 authority、测试矩阵或 CI/CD 门禁，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R4.5_Task_Report.md)。 ## R5 [completed] 实现 [UniDesk #2322](https://github.com/pikasTech/unidesk/issues/2322)：新增 YAML/参数驱动的 `platform-infra observability closeout` 只读聚合入口，在一次 CLI 调用中有界汇总 status、validate 及可选 PromQL/OTel trace 证据；保持 `mutation=false`、non-blocking，不修改公共运行面，完成任务后将详细报告写入[任务报告](./details/observability-trace-reliability/R5_Task_Report.md)。