docs: rename readonly analysis to offline investigation
This commit is contained in:
Codex
@@ -51,6 +51,7 @@ bun scripts/cli.ts web-probe observe analyze <observerId>
|
||||
|
||||
## Triage Shape
|
||||
|
||||
0. 用户要求“离线调查”时，只读已有 sentinel run/report、runner API/index、OTel 既有 trace、observe artifact 和源码；不得新开 web-probe、触发 dashboard/manual quick verify 或改运行面。若 report/analyze 无法给出有界 root-cause 证据，先改进 report/analyzer/CLI 可见性，再继续结论。
|
||||
1. Separate shell/API/render: check public HTML/CSS/JS, `/api/overview`, `/api/runs`, then browser console/DOM render evidence.
|
||||
2. Separate runner and web: runner Pod/PVC/API/report health is not the same as monitor-web rendering health.
|
||||
3. Separate service rollout and target validation: Argo/runtime green only proves哨兵自身可用；HWLAB business recovery must come from observe/analyze report.
|
||||
|
||||
@@ -20,6 +20,7 @@ bun scripts/cli.ts platform-infra observability search --service <service> --lim
|
||||
## P0 边界
|
||||
|
||||
- 可见性问题优先修复；状态、耗时、失败原因、trace、命令结果或关键证据不可见时，先补 CLI/日志/状态输出。
|
||||
- 离线调查中的 OTel 只能分析既有 trace 和已有业务记录；如果 trace/search/diagnose 摘要不好用、缺少业务映射或无法区分 observability gap 与业务失败，先改进 OTel CLI/analyze/instrumentation 可见性，再继续业务结论。
|
||||
- OTel 查询默认低噪声摘要；完整 span/context 显式 `--full`/`--raw`。
|
||||
- OTel 查询的 `--target` 必须匹配 trace 所属运行面 node/lane；JD01 运行面产生的 trace 用 `--target JD01` 查询，不能拿其他节点查询失败当作 trace 缺失结论。
|
||||
- 不把 trace 缺口误判成业务成功；缺少 span 或窗口不完整时，先说明观测边界。
|
||||
|
||||
@@ -31,6 +31,7 @@ description: UniDesk Web 开发与浏览器验证技能。用户处理 UniDesk/H
|
||||
|
||||
## web-probe 证据规则
|
||||
|
||||
- 用户要求“离线调查”时，web-probe 只读取已有 observer/sentinel artifact、`observe collect` 和 `observe analyze` 报告；不得新开 `run/script/observe` 或触发新的 dashboard 验证。若 collect/analyze 难以定位 run、trace、sample、root-cause signal 或输出不可界定，先改进 analyzer/CLI 证据面，再继续业务结论。
|
||||
- 用户要求“用 web-probe 做 smoke”时，`web-probe` 是取证工具，smoke 目标以用户/issue 指定的业务入口为准；例如目标是 Workbench 时，必须用 `web-probe run` 或 `web-probe observe start` + `observe command --type sendPrompt` 验证 Workbench 页面、会话、消息终态和 `observe analyze` 结果，不能改成只验证 web-probe 工具自身。只有用户明确说“验证 web-probe 自身/基础设施”时，才把 screenshot/script/observe 作为工具自检 smoke。
|
||||
- web-probe 发现 Workbench 请求风暴、浏览器卡死、内存上涨、submit/command 失败或投影缺失时，修复目标默认是 Workbench runtime/projection/read model 或业务代码；不得为了通过 smoke 去降低 Playwright/Chromium 能力、减少采样、自动刷新页面、关闭 freeze/memory 检测或把 blocker 降级。探针侧只能补证据、root cause 可见性和 YAML policy 接入。
|
||||
- 交互式线上验收优先使用 `web-probe observe start`、`observe command`、`observe collect` 和 `observe analyze`；`web-probe script` 只作为一次性探测逃生口。重复出现的高频动作（折叠侧栏、关闭报告、切换全屏、导出低码率截图、采集布局指标）必须沉淀为 observe command 或 analyzer 能力。
|
||||
|
||||
@@ -47,7 +47,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台。本文
|
||||
- P0: GitHub issue/PR 正式写入必须走 `$unidesk-gh` / `bun scripts/cli.ts gh ...`，禁止原生 `gh` 或手写 GitHub API 绕过；正文、评论和 closeout 默认中文。
|
||||
- P0: 远端文本修改优先走 `$unidesk-trans` 的 `trans <route> apply-patch`；route 定位和容器 cwd 规则见 `docs/reference/cli.md`。
|
||||
- P0: Web、Workbench、Playwright/web-probe、前端状态投影和线上 Web bug 复测使用 `$unidesk-webdev`；OTel/Tempo/trace 追踪使用 `$unidesk-otel`。
|
||||
- P0: 用户要求“只读分析路径”时，直接按 `$unidesk-otel` + `$unidesk-webdev` + `$unidesk-gh` 执行：只读 OTel、静态源码、离线 web-probe analyze 和 `../opencode` 对比，最后新建分析 issue；禁止新开 web-probe 或改运行面。
|
||||
- P0: 用户要求“离线调查”时，按 `$unidesk-otel` + `$unidesk-webdev` + `$unidesk-gh` 执行：OTel 离线 analyze、已有 web-probe artifact/analyze、代码静态分析和 `../opencode` 对比；不得新开 web-probe 或改运行面；工具不好用先改工具。
|
||||
- P0: Web 哨兵、`web-probe sentinel`、`monitor.pikapython.com`、定期/周期巡检和新建巡检使用 `$unidesk-monitor`，涉及页面复现或截图时同时使用 `$unidesk-webdev`。
|
||||
|
||||
## P0: HWLAB、AgentRun 与节点边界
|
||||
|
||||
@@ -10,6 +10,14 @@ UniDesk 的可观测性优先级高于静默成功。CLI、服务日志、Docker
|
||||
|
||||
因此，CLI、Web、trace 和 issue 评论中的状态字段必须避免把“已观测到缺口”“已显示失败原因”“已提供诊断入口”表达成“问题已解决”。如果当前阶段只能增加可见性，输出应明确标记为诊断进展或阻塞定位；不得关闭对应功能 issue，不得把观测增强当作验收通过。
|
||||
|
||||
## Offline Investigation
|
||||
|
||||
用户要求“离线调查”时，统一使用这个术语，不再写成“只读流程”“只读调查”或“只读分析路径”。离线调查的边界是用既有证据定位问题：OTel/Tempo 中已经采集的 trace、`platform-infra observability ...` 的离线 analyze/diagnose 输出、已有 `web-probe observe` / `web-probe sentinel` artifact 与 `observe analyze` 报告、代码静态分析、配置/YAML 静态读取，以及必要的 `../opencode` 静态对比。
|
||||
|
||||
离线调查不得新开 `web-probe observe/run/script`、不得触发 dashboard/manual quick verify、不得部署、rollout、重启、写数据库、改 Secret 或改变业务运行面。可以读取已有运行记录、状态表、报告索引、source checkout、OTel trace 和离线 artifact；需要 GitHub 写入时只允许在结论阶段通过 `$unidesk-gh` 新建或评论分析 issue，并标明目标合并分支或运行 lane。
|
||||
|
||||
离线调查遇到 OTel 或 analyze 不好用时，先改进工具再继续业务结论。典型触发包括：OTel 查询缺少目标运行面、service path、business trace 映射、error span 摘要或 `--grep`/`--limit` drill-down；`diagnose-code-agent` 不能区分 observability gap 与业务失败；`observe collect/analyze` 解析失败、输出不可界定、不能按 run/observer/trace/sample 定位、只给 dump 或缺少 root-cause signal；sentinel report 不能把 runner API、SQLite index 和 artifact findings 对齐。工具改进应优先落在 CLI/analyzer/summary/parser 或 instrumentation 的可见性层，并用既有 trace/artifact 做回归验证；若工具改进需要实际部署或新采样，必须先把离线调查结论停在“工具缺口”，再取得明确授权后进入对应运行面流程。
|
||||
|
||||
## Zero Implicit Fallback
|
||||
|
||||
运行时异常、投影写入异常、序列化异常、ReferenceError/TypeError、不可达上游、provider 不可用、trace 同步失败和状态机非法转移不得被隐式 fallback 吞掉。任何 catch 后继续返回旧值、空值、默认值、legacy 查询、二次来源仲裁或“看起来成功”的行为，都必须改成以下两类之一：
|
||||
|
||||
Reference in New Issue
Block a user