docs: record mdtodo launch and otel target lessons

2026-06-30 14:30:27 +00:00
parent 6f73690eb5
commit abbda09aa1
4 changed files with 8 additions and 0 deletions
@@ -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 的健康样本替代用户入口证据。