docs: specify mdtodo web rewrite

2026-06-26 18:27:25 +00:00
parent f27e947dc0
commit 9a6bdfd128
2 changed files with 379 additions and 1 deletions
@@ -19,7 +19,7 @@
 | 短名 | 项目管理 |
 | 层级 | L2 课题 |
 | 状态 | 已生效 |
-| 实现引用版本 | draft-2026-06-25-p0-project-management-mdtodo; draft-2026-06-25-p0-mdtodo-web-active-editing-hwpod-source; draft-2026-06-26-p1-mdtodo-web-operable |
+| 实现引用版本 | draft-2026-06-25-p0-project-management-mdtodo; draft-2026-06-25-p0-mdtodo-web-active-editing-hwpod-source; draft-2026-06-26-p1-mdtodo-web-operable; draft-2026-06-26-p0-mdtodo-web-rewrite |
 | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
 | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) |
 | 关联规格 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md)、[PJ2026-0105 用户管理](PJ2026-0105-user-management.md)、[PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
@@ -114,6 +114,7 @@
 | PJ2026-01040406 | 外部 PM adapter | 本规格 6.6 | Plane/Vikunja/OpenProject 等未来 adapter 接口和隔离边界 | 外部 PM 服务、用户管理 | 后续完整 PM 能力 |
 | PJ2026-01040407 | 观测与验收 | 本规格 6.7 | web-probe observe/analyze、DOM 脱敏、YAML-first 阈值和 issue-ready evidence | 平台运维、公开入口、Cloud Web | D601/v03 原入口验收 |
 | PJ2026-01040408 | YAML-first 运行配置 | 本规格 6.8 | 独立服务部署、Secret sourceRef、DB/OTel/health/public route 配置 | YAML运维、平台发布 | D601/v03 rollout |
+| PJ2026-01040409 | MDTODO前端重写 | [PJ2026-01040409 MDTODO前端重写](PJ2026-01040409-mdtodo-web-rewrite.md) | 清除旧 MDTODO Web 前端并按有界三栏、Rxx 树、报告预览和主动编辑重新实现 | Project Management API、Web工作台、web-probe | D601/v03 MDTODO 原入口可用性 |

 ### 5.1 目标架构图

@@ -0,0 +1,377 @@
+# PJ2026-01040409 MDTODO前端重写
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-01040409 MDTODO前端重写需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-01040409 |
+| 短名 | MDTODO前端重写 |
+| 层级 | L3 专项规格切片 |
+| 状态 | 已生效 |
+| 实现引用版本 | draft-2026-06-26-p0-mdtodo-web-rewrite |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-010404 项目管理](PJ2026-010404-project-management.md) |
+| 关联规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[PJ2026-01060508 Web Probe Sentinel](PJ2026-01060508-web-probe-sentinel.md)、[PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 MDTODO Web 前端重写的稳定目标、边界、架构要求、交互要求和验收要求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+MDTODO Web 已经过多轮局部改造，但仍然存在布局不稳定、信息层级混乱、主工作区被元数据挤压、报告预览崩坏、任务树与 MDTODO Rxx 标准不一致、主动编辑能力弱、Workbench 启动不能形成真实工作上下文等问题。这些问题说明继续在旧页面上叠加 CSS 和局部组件修补不能收敛。
+
+本规格要求对 `/projects/mdtodo` 的前端实现进行一次受控清除和重写：保留已稳定的公共 API、ID 关联和可复用运行证据，清除旧页面中面向临时修补的布局、状态和渲染实现，重新建立有界三栏工作区、Rxx 任务树、任务正文编辑、报告预览、Source/File 配置和 Workbench launch 交互。
+
+重写目标不是制作新的静态展示页，而是把 MDTODO Web 做成可长期迭代的项目管理任务面。页面必须能在真实 HWPOD source 上读写 `docs/MDTODO/*.md` 直接文件，能通过公共 Project Management API 做任务 mutation，能通过公共 Workbench Launch API 创建带首轮任务上下文的 Workbench 工作流，并能通过 web-probe observe/analyze 完成可复验的视觉和交互验收。
+
+### 2.2 范围内
+
+- Cloud Web `/projects/mdtodo` 页面 shell、路由选择、状态栏、Source/File 下拉、Rxx 任务树、任务正文区域、报告预览区、弹窗和错误呈现。
+- MDTODO 前端组件、composable、API adapter、DTO 映射、router restore、DOM/testId/ARIA 验收契约和局部样式。
+- 旧 MDTODO 页面中不符合本规格的 `metric-card`、常驻详情元数据、常驻新建任务框、嵌套卡片、页面级长滚动、深色代码块、裸 JSON/Markdown 报告、临时 selector hack 和重复状态实现的清除。
+- 从 Workbench 抽象出的通用有界三栏工作区布局组件在 MDTODO 页面中的使用。Workbench 现有页面可保持不动，抽象组件先服务 MDTODO。
+- Source 配置弹窗、HWPOD-bound source 选择、`docs/MDTODO/` 直接文件发现、文件下拉显示、reindex 触发和 blocker 展示。
+- Rxx 任务树展示、折叠、搜索、状态过滤、inline/double-click 编辑、任务新增、子任务、状态修改、删除、继续执行和冲突回滚。
+- 任务内 Markdown link 的报告解析结果展示、右侧报告预览、全屏预览、长 JSON/RPC 日志渲染、代码块样式和报告关闭后的布局恢复。
+- Workbench launch 按 `projectId`、`sourceId`、`fileRef`、`taskRef`、任务正文和报告上下文生成真实首轮工作内容。
+- web-probe 对 MDTODO 页面多状态的 observe command、collect summary、analyze 规则、截图证据和 closeout 模板。
+
+### 2.3 范围外
+
+- `hwlab-project-management` 微服务的业务事实重构。若重写前端发现 API 缺口，应先补充项目管理规格和执行 issue，再做后端改动。
+- Workbench session、trace、terminal、composer 和 read model 内部实现。MDTODO 只能通过公共 Workbench Launch API 关联 Workbench。
+- HWPOD node、workspace adapter、DB schema、Secret、Auth、FRP/Caddy 和 GitOps 部署控制面。
+- 对 MDTODO v0.2 的兼容实现。页面只支持 v0.3 及后续模型。
+- 本地 `vue-tsc` 验证。前端类型和构建验证应走受控 CI/PipelineRun，开发本地最多做语法、lint 或针对性命令形态确认。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| 清除和重写 | 不在旧页面继续叠加修补；盘点旧实现后替换页面 shell、布局、状态和交互组件，删除不符合规格的旧 UI 代码。 |
+| 有界三栏工作区 | 页面外层高度受限，左侧任务树、中央任务正文、右侧报告预览分别内部滚动；页面本身不因长任务或报告无限变高。 |
+| 左侧任务树 | Rxx outline 区域，默认不超过可用宽度的 30%，可折叠、可调整宽度，只承担导航和摘要。 |
+| 主工作区 | 任务标题、状态、正文、inline edit、任务操作和 Workbench launch 的主要区域；无报告时应占据除左侧栏外的大部分宽度。 |
+| 右侧报告栏 | 任务内报告链接的预览区；可折叠、可关闭、可全屏，打开时默认与主工作区各占约一半。 |
+| 状态栏 | 页面顶部窄工具栏，承载 Source/File 下拉、任务搜索、状态过滤、info、settings、reindex 和 create action。 |
+| info 弹窗 | 收纳 Source、TaskRef、File、Updated、统计、诊断和 link metadata 的信息面板；这些元数据不常驻挤占主工作区。 |
+| Source 配置弹窗 | 配置 MDTODO source 的表单，可绑定 HWPOD 和 workspace 根。 |
+| Direct MDTODO file | `docs/MDTODO/` 下直接 `.md` 文件；子目录内报告、日志和任务报告不得作为 MDTODO 文件。 |
+| Rxx 任务树 | 以 `R1`、`R1.1`、`R1.1.1` 等任务 id 前缀组织层级，而不是按 Markdown heading 数量或 checkbox 缩进猜测。 |
+| Inline edit | 双击标题或正文后原位进入编辑状态，提供保存、取消、冲突提示和回滚，不使用独立标题/正文输入框常驻占位。 |
+| ReportPreview | 由 Project Management API 返回的报告预览 DTO，用于右侧栏和全屏展示。 |
+| Workbench launch | MDTODO 页面调用公共 Workbench Launch API，创建带任务上下文和首轮 prompt 的 Workbench session。 |
+| web-probe command | 可复用的 web-probe 交互命令，覆盖常见 MDTODO 操作；临时 script 只能作为过渡，不作为长期验收入口。 |
+
+## 4. 系统边界和接口
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 硬件研发用户、项目维护者、自动化验收和平台管理员。 |
+| 外部输入 | 浏览器 URL、Source/File/task/report 深链、用户点击和键盘输入、Project Management API DTO、Workbench Launch API 响应、web-probe command。 |
+| 受控资源 | `/projects/mdtodo` 页面、MDTODO 前端组件树、同源 `/v1/project-management/*` 读写请求、`POST /v1/workbench/launches`、web-probe artifact。 |
+| 外部输出 | 有界布局截图、Rxx task outline、任务正文、编辑结果、报告预览、Workbench session link、blocker、diagnostic 和 observe/analyze 报告。 |
+| 用户接口 | Cloud Web、公共 API、web-probe observe/analyze CLI。 |
+| 系统边界 | MDTODO 前端只做展示、交互、路由状态和公共 API 调用；不解析私有 Workbench store、不直连 HWPOD/DB/Kubernetes/SSH、不保存业务 authority 到 localStorage。 |
+
+## 5. 目标架构
+
+### 5.1 前端组件分层
+
+```mermaid
+flowchart TD
+  Route[Vue Router deep link] --> Page[MdtodoPageShell]
+  Page --> Layout[BoundedWorkspaceLayout]
+  Page --> Toolbar[MdtodoToolbar]
+  Page --> Dialogs[Source/Create/Info dialogs]
+  Layout --> Tree[MdtodoTaskTree]
+  Layout --> Main[MdtodoTaskPanel]
+  Layout --> Report[MdtodoReportPanel]
+  Toolbar --> Selection[useMdtodoRouteSelection]
+  Tree --> TaskData[useMdtodoTaskData]
+  Main --> Mutation[useMdtodoTaskMutation]
+  Report --> Reports[useMdtodoReportPreview]
+  Main --> Launch[useMdtodoWorkbenchLaunch]
+  Selection --> Api[MdtodoProjectApiClient]
+  TaskData --> Api
+  Mutation --> Api
+  Reports --> Api
+  Launch --> WorkbenchApi[Workbench Launch API]
+```
+
+`BoundedWorkspaceLayout` 只拥有布局、折叠、拖拽、滚动容器和可访问性状态。它不得包含 MDTODO 业务逻辑。MDTODO 页面通过 slot、props 和事件接入左侧、主区域和右侧内容。
+
+### 5.2 状态和数据流
+
+```mermaid
+flowchart LR
+  Url[URL sourceId/fileRef/taskId/linkId] --> Select[route selection composable]
+  Select --> Load[load source/file/task/report]
+  Load --> Store[local view state]
+  Store --> Render[tree/main/report render]
+  Render --> Edit[inline edit action]
+  Edit --> Api[Project Management mutation with revision]
+  Api --> Reconcile[refresh projection + rollback on conflict]
+  Render --> Launch[Workbench launch action]
+  Launch --> Wb[Workbench session with initial prompt]
+  Render --> Probe[web-probe observe sample]
+```
+
+URL 是可恢复选择状态的 authority。组件内部可以缓存折叠宽度、当前编辑草稿和加载状态，但不能把 source/file/task/report 的业务选择只保存在 store 或 localStorage。
+
+### 5.3 工作区布局
+
+```mermaid
+flowchart LR
+  subgraph App[bounded page height]
+    Header[Narrow page header]
+    Toolbar[Status toolbar]
+    subgraph Workspace[bounded workspace]
+      Left[Task tree <=30 percent collapsible]
+      Main[Task body/editor]
+      Right[Report preview collapsible/fullscreen]
+    end
+  end
+```
+
+桌面视口下，`Header` 和 `Toolbar` 必须保持窄。`Workspace` 使用剩余高度，内部各栏滚动。报告未打开时，`Main` 占除左侧栏之外的全部宽度；报告打开时，`Main` 与 `Right` 默认约 50/50，可拖拽调整。
+
+## 6. 原子需求
+
+### 6.1 MDTODO-WEB-REWRITE-REQ-001 清除旧前端实现
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-001 | 清除旧前端实现 | MDTODO Web | 项目管理、Web工作台 |
+
+实现前必须盘点当前 MDTODO 前端文件、组件、样式、composable 和 API client，并形成删除或保留清单。
+
+旧页面中只为局部问题叠加的布局和样式必须被清除或替换，包括但不限于常驻 `metric-card` 信息卡、常驻 `task-create-box`、常驻任务详情元数据块、嵌套卡片容器、页面级长滚动、报告区域裸 JSON 输出、深色代码块、固定 query selector 依赖、重复文件标题显示和不能恢复 URL 状态的本地 store。
+
+允许保留的代码必须满足以下条件之一：公共 API client/DTO 已与 Project Management API 对齐；通用工具没有 MDTODO 业务耦合；web-probe 使用的 data-testid/ARIA 契约仍符合新页面。不能为了降低改动量保留旧页面主 shell 或旧布局骨架。
+
+### 6.2 MDTODO-WEB-REWRITE-REQ-002 有界三栏布局
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-002 | 有界三栏布局 | `BoundedWorkspaceLayout` | Web工作台、web-probe |
+
+MDTODO 页面必须使用通用有界工作区布局。桌面视口下整体高度受限，页面 header、状态栏、任务树、主工作区和报告栏不得导致 document body 无限增长。
+
+左侧任务树默认占可用宽度的 30% 或更小，可折叠、可拖拽调整，折叠后的展开按钮必须始终可见且不被 header、toolbar、report 或 overflow 遮挡。
+
+右侧报告栏默认折叠。没有打开报告时，主工作区应占据除左侧任务树外的全部宽度。打开报告后，主工作区和报告栏默认各占约一半，用户可拖拽调整；关闭报告后主工作区恢复全宽。
+
+任务树、主工作区和报告栏必须分别拥有内部滚动容器。长任务正文、长报告、长 JSON/RPC 日志只能在对应 pane 内滚动，不得把整个页面撑成长页面。
+
+### 6.3 MDTODO-WEB-REWRITE-REQ-003 顶部状态栏和信息收敛
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-003 | 状态栏和信息收敛 | `MdtodoToolbar` | 项目管理 |
+
+页面 header 必须窄，只提供页面位置、主要状态和必要 action，不得占据任务阅读空间。
+
+Source 和 File 必须作为顶部状态栏的下拉菜单。File 下拉的主显示文本必须是 `docs/MDTODO/` 下的直接文件名或清晰相对路径，不得显示内部标题、hash、奇怪的投影标题或报告标题。
+
+Source、TaskRef、File、Updated、统计计数、link 摘要、诊断信息和 Workbench link metadata 必须收敛到 info/diagnostic 弹窗或菜单，不得常驻在主工作区挤占正文版面。
+
+新建任务入口必须是按钮加弹窗，不得以常驻表单占据默认布局。Source 配置也必须通过设置按钮打开弹窗，弹窗关闭后不改变主工作区布局。
+
+### 6.4 MDTODO-WEB-REWRITE-REQ-004 Source/File 选择和文件范围
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-004 | Source/File 选择 | `MdtodoToolbar`、`useMdtodoSource` | Project Management API |
+
+MDTODO source 应能在 Web 中配置，配置方式至少支持绑定到 HWPOD 和 workspace 根。HWPOD-bound source 默认只读取 `docs/MDTODO/` 目录。
+
+MDTODO 文件发现必须只包含 `docs/MDTODO/` 下直接 `.md` 文件。子目录中的 `details/**`、`*_Task_Report.md`、`*_log_*.md`、图片、artifact 和报告文件只作为链接 target，不得作为 MDTODO 文件出现在 File 下拉或任务树根中。
+
+文件选择必须驱动 URL、任务树、任务详情和报告预览刷新。source/file 不可用、文件过大、parse error、权限不足和 HWPOD 不在线必须显示结构化 blocker，不得通过空白页面或只读假成功掩盖。
+
+### 6.5 MDTODO-WEB-REWRITE-REQ-005 Rxx 任务树
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-005 | Rxx 任务树 | `MdtodoTaskTree` | MDTODO adapter |
+
+任务树必须按 MDTODO v0.3 的 Rxx id 组织。`R1` 是根任务，`R1.1` 是 `R1` 子任务，`R1.1.1` 是 `R1.1` 子任务。层级不得由 Markdown heading 数量、缩进或前端字符串猜测单独决定。
+
+任务树行应展示 Rxx id、标题摘要、状态、阻塞或报告提示。树只作为大纲存在，默认不展示完整正文和大块 metadata。
+
+任务树必须支持折叠、展开、键盘导航、搜索、状态过滤和当前任务高亮。折叠状态不应破坏 URL 选择；用户通过深链进入 `R1.1` 时，父节点应自动展开到可见。
+
+大文件场景下，任务树应按 selected file、搜索/状态过滤、父节点或窗口加载，不应依赖 source 级一次性全量响应才能进入可操作状态。
+
+### 6.6 MDTODO-WEB-REWRITE-REQ-006 任务正文和主动编辑
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-006 | 任务正文和主动编辑 | `MdtodoTaskPanel`、`useMdtodoTaskMutation` | Project Management API |
+
+任务正文是主工作区的核心内容，必须在只读状态下直接可见。标题、正文、状态、报告链接和主要 action 不得被元数据卡片、空表单或报告栏遮挡。
+
+标题和正文不得使用常驻独立输入框修改。用户双击标题或正文后，原位置进入可编辑状态；保存、取消、加载中、错误和冲突回滚状态必须明确可见。
+
+任务 mutation 必须通过 Project Management API 执行，并携带 revision/fingerprint 或等价并发保护。前端允许做乐观更新，但 API 失败、版本冲突、parse error、写回失败或 HWPOD 离线时必须回滚或给出可恢复状态。
+
+新增根任务、新增子任务、修改状态、删除、继续任务和 reindex 都应是公共 API 操作。前端不得直接编辑 Markdown 文件、不得直连 HWPOD workspace、不得把修改只保存在 localStorage。
+
+### 6.7 MDTODO-WEB-REWRITE-REQ-007 报告预览和 Markdown 渲染
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-007 | 报告预览 | `MdtodoReportPanel` | Project Management API、Web工作台 |
+
+任务正文中的 Markdown link，如 `[R1.1](./20260110_LOG/R1.1_log_implementation.md)`，必须能被 Project Management API 解析为报告链接，并在右侧报告栏打开预览。
+
+报告预览必须使用成熟 Markdown 渲染工具并启用安全清理。代码块、JSON、RPC 日志和长行应采用浅色、接近 Workbench 的代码块风格，支持横向滚动或合理换行，不得输出破碎的裸 JSON、未闭合代码块或深色大块区域。
+
+报告栏必须支持打开、关闭、折叠、拖拽调整宽度和全屏预览。全屏预览关闭后，应恢复原报告栏和主工作区状态。
+
+报告文件不得进入 MDTODO File 下拉或任务树。报告加载失败、文件过大、路径越界、权限不足和解析失败都应展示 report blocker，并保留任务正文可操作。
+
+### 6.8 MDTODO-WEB-REWRITE-REQ-008 RESTful 深链
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-008 | RESTful 深链 | Vue Router、`useMdtodoRouteSelection` | API契约 |
+
+MDTODO 页面必须支持可复制、可刷新、可回放的深链，至少包含 source、file、task 和 report 四层选择：
+
+```text
+/projects/mdtodo/sources/:sourceId/files/:fileRef/tasks/:taskId/reports/:linkId?
+```
+
+刷新页面、浏览器前进后退、web-probe 直接打开深链和用户复制链接分享时，页面都必须从公共 API 恢复相同的 source/file/task/report 选择。
+
+URL 不应暴露本地绝对路径、HWPOD 内部 host、DB 主键或 secret。`fileRef`、`taskId` 和 `linkId` 可以是 opaque id，但 UI 必须显示人类可读的文件名、Rxx id 和报告标题。
+
+### 6.9 MDTODO-WEB-REWRITE-REQ-009 Workbench launch 真工作流
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-009 | Workbench launch | `useMdtodoWorkbenchLaunch` | Web工作台、Agent编排 |
+
+点击“在 Workbench 执行”必须调用公共 Workbench Launch API，并提交 `projectId`、`sourceId`、`fileRef`、`taskRef`、任务标题、任务正文摘要、相关报告链接和 prompt template 标识。
+
+成功启动后，Workbench session 必须包含可工作的首轮用户消息或等价任务上下文，不能只是创建空 session。MDTODO 页面只能在 launch API 返回 sessionId、workbenchUrl 和 link 记录后跳转。
+
+失败时，用户应留在 MDTODO 页面并看到结构化错误、重试入口和诊断信息。前端不得把空 session、无首轮消息或未关联 `taskRef` 的 session 标记为成功。
+
+MDTODO 页面和 Workbench 只能通过公共 API 和 ID 关联。MDTODO 不 import Workbench store，不嵌入 Workbench 组件；Workbench 不解析 MDTODO Markdown，不 import MDTODO 组件。
+
+### 6.10 MDTODO-WEB-REWRITE-REQ-010 web-probe 交互验收
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-010 | web-probe 验收 | web-probe commands/analyze | 平台运维 |
+
+MDTODO 前端重写必须补齐可复用 web-probe command，覆盖 source 选择、file 选择、task 选择、任务树折叠展开、pane resize、报告打开关闭、报告全屏、标题/正文 inline edit、状态修改、创建任务弹窗、Source 配置弹窗、reindex 和 Workbench launch。
+
+验收应优先使用 `observe start`、`observe command`、`observe collect` 和 `observe analyze`。临时 `script` 只能作为短期补证，closeout 前高频动作必须沉淀为 command。
+
+closeout 至少需要以下截图和分析证据：
+
+| 视口 | 状态 | 必要证据 |
+| --- | --- | --- |
+| 960x600 | 默认深链进入任务 | header 窄、状态栏可用、任务正文可见、无页面级长滚动 |
+| 960x600 | 左侧任务树折叠 | 展开按钮可见且未被覆盖，主工作区扩展 |
+| 960x600 | 报告打开 | 主工作区和报告栏约 50/50，报告渲染正常 |
+| 960x600 | 报告全屏 | 全屏可读、可关闭、关闭后状态恢复 |
+| 1440x900 | 长 JSON/RPC 报告 | 浅色代码块、内部滚动、无裸 JSON 崩坏 |
+| 390x844 | 窄屏阅读 | Source/File 可选、正文可读、报告入口可访问 |
+| 960x600 | 创建任务弹窗 | 弹窗打开/关闭不破坏主布局 |
+| 960x600 | Workbench launch | 目标 session 存在首轮任务上下文，不是空 session |
+
+`observe analyze` 当前状态不得出现 `mdtodo-task-body-not-visible`、`mdtodo-report-fullscreen-missing`、左侧折叠按钮被遮挡、页面整体高度极端长、报告裸 JSON 崩坏或主工作区被详情 metadata 挤压等 top-level finding。若历史 artifact 仍有旧 finding，closeout 必须说明当前 artifact 和历史 artifact 的差异。
+
+### 6.11 MDTODO-WEB-REWRITE-REQ-011 可访问性和稳定选择器
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-011 | 可访问性和稳定选择器 | MDTODO Web | web-probe |
+
+所有关键交互控件必须有稳定 `data-testid` 或 ARIA label，供 web-probe command 和人工排障使用。不得依赖形如 `document.querySelector("#app > main > section > ... > button:nth-child(3)")` 的脆弱选择器作为长期验收入口。
+
+Source/File 下拉、info、settings、create task、tree collapse、report close、report fullscreen、inline edit save/cancel、Workbench launch 都必须能通过键盘到达，并有清晰 disabled/loading/error 状态。
+
+### 6.12 MDTODO-WEB-REWRITE-REQ-012 视觉密度和版面原则
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| MDTODO-WEB-REWRITE-REQ-012 | 视觉密度 | MDTODO Web | Web工作台 |
+
+MDTODO 是项目管理工作台，不是营销页。页面应采用高密度、低装饰、可扫描的工具布局，避免大 hero、装饰卡片、嵌套卡片、单色大面积背景和占用主空间的说明文案。
+
+正文和报告是主要内容。桌面默认状态下，主工作区可用面积应显著大于元数据和 chrome；没有报告时，正文区域应占除左侧任务树外的主要空间；有报告时，正文与报告应并列，而不是上下堆叠撑长页面。
+
+MDTODO UI 应对齐 VSCode 插件的任务大纲和主动编辑心智，但不能把 Web 做成插件的逐像素复制。Web 版应保留深链、Source 配置、报告预览、Workbench launch 和 web-probe 验收这些浏览器特性。
+
+## 7. 实施阶段
+
+| 阶段 | 目标 | 完成条件 |
+| --- | --- | --- |
+| P0 SPEC 和现状盘点 | 以本规格为 source of truth，盘点旧 MDTODO 前端实现和删除清单 | issue 引用本规格，列出保留/删除文件，确认不动 backend-core 和 Workbench 内部 |
+| P1 交互骨架和截图评审 | 用真实 API 或受控 fixture 做新布局骨架 | 960x600 默认、树折叠、报告打开、报告全屏截图通过人工评审 |
+| P2 清除旧页面并接入新 shell | 替换旧页面 shell、toolbar、layout 和 route restore | 旧常驻 metric/detail/create box 不再出现在默认页面 |
+| P3 任务树和主动编辑 | Rxx 树、正文展示、inline edit、mutation、conflict rollback 可用 | web-probe command 能完成选择、编辑、保存、取消和失败展示 |
+| P4 报告预览和 Markdown 渲染 | 右侧报告栏、全屏、浅色代码块、长 JSON/RPC 滚动可用 | 长报告深链截图无裸 JSON 崩坏，报告文件不进入 File 下拉 |
+| P5 Workbench launch | 任务能启动带首轮上下文的 Workbench session | web-probe 证明目标 session 不是空 session，ProjectWorkbenchLink 可查 |
+| P6 D601/v03 滚动上线和 closeout | 使用受控 CI/CD 发布并用 web-probe 复验 | issue closeout 包含 PipelineRun、URL、截图、analyze report 和剩余风险 |
+
+P1 截图评审是强制门槛。若用户或 reviewer 仍认为布局“不好”，不得进入 P2/P3 大量实现，应先调整规格或骨架。
+
+## 8. 验收标准
+
+| 编号 | 验收项 | 标准 |
+| --- | --- | --- |
+| AC-001 | 规格先行 | 执行 issue 明确引用本规格、上级规格、关联规格和实现引用版本。 |
+| AC-002 | 清除旧实现 | PR diff 显示旧 MDTODO 前端页面 shell 和临时布局被替换，旧常驻 metric/detail/create box 不再存在。 |
+| AC-003 | 布局有界 | 960x600 和 1440x900 下页面整体高度受限，任务树、主工作区、报告栏内部滚动。 |
+| AC-004 | 左侧任务树 | 默认宽度不超过 30%，可折叠可展开，展开按钮不被遮挡。 |
+| AC-005 | 主工作区 | 默认任务正文直接可见，元数据进入 info 弹窗，正文区域未被详情卡片挤压。 |
+| AC-006 | File 下拉 | 直接显示 `docs/MDTODO/` 下文件名，不显示内部标题或报告文件。 |
+| AC-007 | Direct file 范围 | `details/**`、报告和日志不会出现在 File 下拉或任务树根。 |
+| AC-008 | Rxx 树 | `R1/R1.1/R1.1.1` 按 id 层级组织，深链任务自动展开父节点。 |
+| AC-009 | Inline edit | 双击标题/正文可编辑，保存/取消/失败/冲突状态可见。 |
+| AC-010 | 报告预览 | 任务报告在右侧栏和全屏模式可读，Markdown/代码块/长 JSON 渲染稳定。 |
+| AC-011 | 深链 | source/file/task/report 深链刷新后恢复同一选择。 |
+| AC-012 | Workbench launch | 点击执行后生成带首轮任务上下文的 Workbench session，不接受空 session 成功。 |
+| AC-013 | 解耦边界 | MDTODO 前端只通过公共 Project Management API 和 Workbench Launch API 关联，不 import Workbench store 或直连 backend/HWPOD。 |
+| AC-014 | web-probe | observe command 覆盖主要交互，analyze 当前 artifact 无布局崩坏 top-level finding。 |
+| AC-015 | 发布验证 | D601/v03 通过受控 CI/CD rollout 和原入口 web-probe 验证；不在本地运行 `vue-tsc` 作为验收依据。 |
+
+## 9. 风险和约束
+
+- 若后端 API 仍缺少 task detail body、report preview、mutation revision 或 Workbench launch seed 字段，前端重写不得用本地拼接绕过，应先补规格和后端执行 issue。
+- 若通用有界布局组件不足以支持 MDTODO，需要扩展通用组件，而不是在 MDTODO 页面复制一套私有三栏 CSS。
+- 若历史 web-probe command 无法覆盖高频操作，应先补 command，再做 closeout；不得每次用临时脚本重放同一操作。
+- 若 D601/v03 运行面和本地开发 fixture 展示不一致，以 D601/v03 原入口证据为准。
+- 若用户在 P1 骨架评审中仍指出布局不满足需求，应暂停实现扩展，先修正布局规格和骨架。
+
+## 10. 过程控制
+
+本规格不直接记录执行日志。执行 issue 必须按阶段引用本规格，并在每个阶段关闭前回写：
+
+- 当前实现引用版本。
+- 关键 PR 和 rollout evidence。
+- web-probe observe/analyze artifact 路径或报告。
+- D601/v03 真实 URL 和截图摘要。
+- 未完成项和后续 issue。
+
+涉及 GitHub issue/PR 的正式写入必须使用 UniDesk 受控 GitHub CLI。涉及发布、PipelineRun、rollout 和 GitOps 的操作必须使用 UniDesk CI/CD 受控入口。涉及 web-probe 的验收必须优先使用 observe/analyze 和可复用 command。