From abbda09aa12e23f16b2af2f9c58625ec1f8aa8c7 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 30 Jun 2026 14:30:27 +0000 Subject: [PATCH] docs: record mdtodo launch and otel target lessons --- .agents/skills/unidesk-otel/SKILL.md | 1 + .agents/skills/unidesk-otel/references/full.md | 2 ++ .agents/skills/unidesk-webdev/SKILL.md | 1 + .agents/skills/unidesk-webdev/references/full.md | 4 ++++ 4 files changed, 8 insertions(+) diff --git a/.agents/skills/unidesk-otel/SKILL.md b/.agents/skills/unidesk-otel/SKILL.md index 02a928bb..2edb528a 100644 --- a/.agents/skills/unidesk-otel/SKILL.md +++ b/.agents/skills/unidesk-otel/SKILL.md @@ -21,6 +21,7 @@ bun scripts/cli.ts platform-infra observability search --service --lim - 可见性问题优先修复；状态、耗时、失败原因、trace、命令结果或关键证据不可见时，先补 CLI/日志/状态输出。 - OTel 查询默认低噪声摘要；完整 span/context 显式 `--full`/`--raw`。 +- OTel 查询的 `--target` 必须匹配 trace 所属运行面 node/lane；JD01 运行面产生的 trace 用 `--target JD01` 查询，不能拿其他节点查询失败当作 trace 缺失结论。 - 不把 trace 缺口误判成业务成功；缺少 span 或窗口不完整时，先说明观测边界。 - `diagnose-code-agent` 的 `observabilityGap` / `Service trace coverage` 是跨服务追穿完整性证据：如果 business trace 只有 `hwlab-cloud-api`，但缺少 `agentrun-manager` 或 `agentrun-runner`，应按观测缺口记录并继续用 runId/commandId/sessionId drill-down，不要把缺失 span 当作服务未参与的业务结论。 - `platform-infra observability status` 默认应保持短表；需要完整 Kubernetes/Tempo payload 时才显式使用 `--full` 或 `--raw`。 diff --git a/.agents/skills/unidesk-otel/references/full.md b/.agents/skills/unidesk-otel/references/full.md index 4970e181..6d1407aa 100644 --- a/.agents/skills/unidesk-otel/references/full.md +++ b/.agents/skills/unidesk-otel/references/full.md @@ -42,6 +42,8 @@ bun scripts/cli.ts platform-infra observability trace \ 默认输出不得展开完整 Tempo JSON；需要原始响应时才用 `--raw`。 +`--target` 必须和产生 trace 的运行面一致。按 HWLAB node/lane 复测得到的 `x-hwlab-otel-trace-id` 应优先使用同一 node 查询，例如 JD01/v0.3 的 Workbench launch 或 `/v1/agent/chat` 响应头用 `--target JD01`。如果拿其他 target 查询返回 `traceFound=-`、`parseOk=false` 或平台状态超时，只能说明 target/运行面不匹配或该 target observability 不可用，不能据此判断原 trace 不存在。 + 当只有错误文案而没有 OTel trace id 时，先用 `search` 从 Tempo 最近 trace 中反查候选，再进入 `trace`： ```bash diff --git a/.agents/skills/unidesk-webdev/SKILL.md b/.agents/skills/unidesk-webdev/SKILL.md index 6d89532e..9260d5b9 100644 --- a/.agents/skills/unidesk-webdev/SKILL.md +++ b/.agents/skills/unidesk-webdev/SKILL.md @@ -35,6 +35,7 @@ description: UniDesk Web 开发与浏览器验证技能。用户处理 UniDesk/H - Issue closeout 引用 observer id、command id、stateDir/report SHA、screenshot SHA 和关键字段摘要；不要粘贴截图二进制、完整 JSON、Secret、cookie 或无界日志。 - 取证 drill-down 先用 `observe collect` / `observe analyze` 的 bounded view；需要截图路径、SHA、traceId 或 command detail 时优先查 `control.jsonl`、analysis 摘要或专用 artifact view，避免直接 `rg samples.jsonl`，因为页面快照是超长单行 JSON，容易触发输出截断和噪声。 - Project Management/MDTODO closeout 必须区分 `control` 页和被动 `observer` 页：显式 `observe command` 的 command result、control URL 和对应截图是用户动作证据；observer 周期刷新或 stop 后根路由空态只能作为对照信号，不能覆盖 command result。涉及报告的验收要同时记录 `reportPreviewVisible`、`reportFullscreenVisible`、报告 deep link 和截图 SHA。 +- MDTODO → Workbench launch 验收必须引用 `launchWorkbenchFromMdtodo` 的 command result，确认文件/任务选择、Workbench session、launch/chat 状态和 OTel trace header；不要只凭页面最终停在 Workbench URL 判断通过。 - `observe analyze` 的 archive/history findings 可能包含旧样本或旧规则误判；关闭用户入口问题前同时核对最新 sample 字段、DOM 几何和截图。若 top-level findings、latest sample 和 archive red 冲突，说明冲突并补工具反馈 issue，不要只凭 archive red 或单张截图下结论。 ## 高频工作流 diff --git a/.agents/skills/unidesk-webdev/references/full.md b/.agents/skills/unidesk-webdev/references/full.md index efad2936..d3b0aab8 100644 --- a/.agents/skills/unidesk-webdev/references/full.md +++ b/.agents/skills/unidesk-webdev/references/full.md @@ -139,6 +139,10 @@ bun scripts/cli.ts web-probe observe collect webobs-xxxx --view project-mdtodo-s bun scripts/cli.ts web-probe observe analyze webobs-xxxx ``` +`launchWorkbenchFromMdtodo` 是 Project Management 到 Workbench 的正式用户动作复现入口。传入 `--filename` / `--file-ref` 和 `--task` / `--task-ref` 时，runner 必须通过公开 source/file/task 控件完成选择；若 control 页停在 `/projects/mdtodo` 根路由，应先选择默认 source，再选择文件和任务。`source` 是 observe command provenance 字段，不能当成 MDTODO source id；需要指定 source 时只能使用显式 `--source-id`。显式文件或任务目标选不中时，命令必须失败并输出结构化 before/after project snapshot、目标摘要和选项样本，禁止静默选第一项或退回任意任务。 + +MDTODO → Workbench launch closeout 必须引用 command result 中的 `launchStatus`、`sessionId`、`workbenchUrl`、`chatStatus`、业务 trace、`otelTraceId` / `chatOtelTraceId`、文件/任务选择摘要和 control URL。`project-mdtodo-summary` 的 `LAUNCH ok/fail` 与 `OTEL` 计数是第一层汇总；若 analyzer 的 archive red 与当前 command result 冲突，以当前 command result、control 页面截图和最新 project summary 为准，并说明 archive red 来自旧样本或旧规则。 + MDTODO 或 Project Management 的 Web 重写/布局 closeout 不能只引用组件 diff、PipelineRun 成功或一张默认截图。最小证据应按 SPEC 覆盖：默认深链任务正文可见、Source/File 下拉显示 direct MDTODO 文件名、Rxx 任务树为 outline 辅助视图、右侧报告栏可打开且不挤爆主工作区、报告全屏可读并可关闭。涉及报告渲染时，先用有 `reportLinkCount > 0` 的任务执行 `openMdtodoReportPreview`，再执行 `toggleMdtodoReportFullscreen`，并在 closeout 中记录 command id、`reportPreviewVisible`、`reportFullscreenVisible`、报告 deep link、截图 SHA 和 analyze report SHA。 `observe` 的 Project Management 采样可能同时包含 control 页和 observer 页。control 页是显式用户动作所在页面；observer 页用于被动对照和周期刷新。若 `project-mdtodo-summary` 或 `observe analyze` 的最新汇总被 observer 周期刷新、stop 命令或根路由样本带成 `SRC=0/FILES=0/TASKS=0`，不得直接推翻已完成 command result 和 control 页面截图；必须按 `pageRole`、command JSON、control URL、screenshot path/SHA 和相邻 samples 解释。反过来，若 control command 失败、command backlog 未清空或截图 URL 不在目标 source/file/task/report 深链上，也不能用 observer 的健康样本替代用户入口证据。