docs: bound mdtodo task windows
This commit is contained in:
Codex
@@ -155,6 +155,8 @@ Cloud Web、HWLAB CLI 和 web-probe 必须使用 YAML 选中的同一 Web origin
|
||||
|
||||
MDTODO 页面应提供高密度工作区：Source/File 以顶部状态栏下拉呈现，metric 摘要进入 info/diagnostic 弹窗，主版面优先展示 Rxx 任务树和详情/编辑区。页面应支持 Web 配置 HWPOD-bound Source，选择 `d601-f103-v2` 这类 HWPOD 的 `docs/MDTODO/` workspace 根，并通过同源 Project Management API 读写 Markdown source-of-truth。
|
||||
|
||||
MDTODO 页面必须对大 source 做有界读取：首屏不依赖 source 级全量任务响应，任务树按 selected file、parentTaskRef、搜索/状态过滤和 cursor/limit 窗口加载。`71-FREQ` 这类包含数百个 Rxx 任务的 HWPOD source 应能先完成 source/file 识别，再按用户选择加载任务窗口；不能因为一次全量 task payload 过大导致页面或 web-probe 进入 status=0/超时。
|
||||
|
||||
项目管理必须通过独立 `hwlab-project-management` 微服务和同源 Project Management API 暴露。客户端不得把项目管理实现并入 Workbench、Cloud Web 私有状态、Cloud API 内部模块、UniDesk `mdtodo` 或 UniDesk `project-manager` 服务。
|
||||
|
||||
MDTODO 主动编辑只能调用公开 Project Management API。标题/正文编辑、状态切换、添加、子任务、延续、删除和 reindex 必须带 revision/fingerprint 并发保护；冲突、parse error、HWPOD 不可用和 path 越界都应展示结构化 blocker，不能由前端本地状态、localStorage 或测试后门补造成成功。
|
||||
|
||||
@@ -410,7 +410,7 @@ Cloud API 的 Project Management proxy 必须按同源鉴权和脱敏 envelope
|
||||
| MDTODO source reindex | `POST /v1/project-management/mdtodo/sources/{sourceId}/reindex` | expected source revision 可选 | projection status、indexed files/tasks、diagnostics | 200/202/400/401/403/404/409/422 | 从 Markdown 重建 projection，不把 DB 反写为权威 |
|
||||
| MDTODO files | `GET /v1/project-management/mdtodo/files` | `sourceId`、cursor、limit | fileRef、displayName、taskCount、status、fingerprint hash、parseError 摘要 | 200/401/403/404 | 文件摘要，不返回完整 Markdown |
|
||||
| MDTODO file content | `GET /v1/project-management/mdtodo/files/{fileRef}/content` | `sourceId`、可选 redaction mode | 脱敏 Markdown preview 或 rawContent capability、revision、sha256、parser diagnostics | 200/401/403/404/409/422 | 默认不返回完整 raw Markdown；完整内容必须显式 capability |
|
||||
| MDTODO tasks | `GET /v1/project-management/mdtodo/tasks` | `sourceId`、fileRef、可选 status/filter | `ProjectTask[]`、taskRef、父子关系、linkCount、projection revision | 200/401/403/404/409 | 任务投影来自项目管理 read model |
|
||||
| MDTODO tasks | `GET /v1/project-management/mdtodo/tasks` | `sourceId`、可选 fileRef、parentTaskRef、status/filter、cursor/offset、limit | bounded `ProjectTask[]`、taskRef、父子关系、linkCount、projection revision、page/limit/total/hasMore | 200/401/403/404/409/422 | 任务投影来自项目管理 read model；不得默认返回 source 全量任务 |
|
||||
| MDTODO task mutation | `PATCH /v1/project-management/mdtodo/tasks/{taskRef}` | title/body/raw block/status/metadata patch、expected revision | updated ProjectTask、document revision、audit id | 200/400/401/403/404/409/422 | 写入必须经 MDTODO adapter 文件锁和原子写入 |
|
||||
| MDTODO task create | `POST /v1/project-management/mdtodo/tasks` | sourceId、fileRef、mode=root/subtask/continue、parent taskRef 可选、title/body、expected revision | created ProjectTask、document revision、audit id | 201/400/401/403/404/409/422 | 生成 Rxx id 并写入 Markdown source-of-truth |
|
||||
| MDTODO task delete | `DELETE /v1/project-management/mdtodo/tasks/{taskRef}` | expected revision、confirm impact | deleted taskRef、affected refs、document revision、audit id | 200/400/401/403/404/409/422 | 删除 Markdown task block，必须有影响范围摘要 |
|
||||
@@ -421,6 +421,8 @@ Cloud API 的 Project Management proxy 必须按同源鉴权和脱敏 envelope
|
||||
|
||||
`ProjectTask` DTO 至少应包含 `taskRef`、`projectId`、`sourceId`、`fileRef`、`kind`、`rxxId`、title、status、parentTaskRef、depth、linkCount、document revision、updatedAt 和 `valuesRedacted=true`。Rxx 树的 parentTaskRef 来自 `rxxId` 前缀；fileRef、lineNumber、source fingerprint、Markdown preview 和 parse diagnostic 只能作为脱敏 metadata 输出；默认响应不得包含 host path、raw Markdown、Secret、token、DB DSN、provider payload、完整 prompt 或可复用凭据。
|
||||
|
||||
`GET /v1/project-management/mdtodo/tasks` 必须是有界读取。未指定 `limit` 时服务端应使用受控默认窗口，指定 `limit` 时必须套用服务端最大值；响应应返回 `total`、`hasMore`、`limit` 和 cursor/offset 摘要。页面首屏应优先读取 source/files 摘要和 selected file 或 selected subtree 的任务窗口；对 `71-FREQ` 这类包含数百个任务的大 source，不得通过一次 source 级全量任务响应支撑默认渲染或 web-probe 验收。
|
||||
|
||||
MDTODO mutation 请求必须携带 expected document revision、fingerprint 或等价并发条件。服务端发现 revision 不匹配时返回 409，并输出 current revision、conflict code 和下一步建议；不得用读侧修复、last write wins 或前端重试覆盖远端 Markdown 修改。
|
||||
|
||||
`WorkbenchLaunchIntent` 至少应包含 `sourceKind="project-management"`、`projectId`、`taskRef`、title 摘要、promptTemplateId、optional initial prompt metadata 和 `valuesRedacted=true`。Workbench 可以保存这些字段为 session metadata，但不得反解 taskRef、读取 Markdown、调用 Project Management adapter 或把项目管理 DB 当作 Workbench authority。
|
||||
|
||||
@@ -299,6 +299,8 @@ flowchart TD
|
||||
|
||||
MDTODO 页面必须按 Rxx heading 标准组织任务树，至少支持 `R1`、`R1.1`、`R1.1.1` 的父子关系、展开/折叠、搜索、跳转、状态筛选和选中高亮。树 authority 来自项目管理 projection 中的 Rxx id 和 parentTaskRef，不得从 checkbox 缩进、DOM 缩进或标题级别临时推断。
|
||||
|
||||
MDTODO 页面不得把 source 级全量任务列表作为首屏依赖。首屏应读取 source 摘要、file 摘要和默认 selected file 或 selected subtree 的有界任务窗口；文件切换、展开 Rxx 分支、搜索和状态过滤再按 cursor/offset 或 parentTaskRef 请求后续窗口。对于 `constart-71freq-mdtodo` 这类大 source，`/projects/mdtodo` 必须能在不下载全部任务投影的情况下识别 source、列出文件并进入可交互状态。
|
||||
|
||||
MDTODO 页面可以提供任务状态和内容写入入口，但写入必须进入项目管理服务，再由 MDTODO adapter 使用文件锁和原子写入修改 `.md`，随后重建投影。前端不得直接上传或覆盖 raw Markdown。主动操作范围至少包括标题/正文或 raw block 编辑、`open/in_progress/completed` 状态切换、添加根任务、添加子任务、延续 sibling、删除任务、保存文本块、刷新文件、reindex 和 Workbench launch。
|
||||
|
||||
### 6.3 CLIENT-PM-REQ-003 独立项目管理微服务
|
||||
@@ -327,6 +329,8 @@ MDTODO adapter 应兼容 VSCode 插件的 Rxx heading 语义：任务标题以 `
|
||||
|
||||
PM DB 至少应能表达 `project_sources`、`mdtodo_documents`、`mdtodo_task_projection`、`project_workbench_links`、`project_audit_events` 或等价结构。`project_sources` 对 HWPOD source 保存 `sourceKind`、`hwpodId`、`nodeId`、workspace 相对根、能力开关和配置 revision；`mdtodo_documents` 记录 fileRef、fingerprint、mtime、lastIndexedAt、parseError 和 revision；`mdtodo_task_projection` 记录 `taskRef`、rxxId、title、status、parentTaskRef、depth、linkCount、updatedAt 和 source fingerprint；link 表记录 `projectId/taskRef/sessionId/traceId`。
|
||||
|
||||
任务投影读取 API 必须支持 fileRef、parentTaskRef、status/search 和 cursor/offset+limit 的受控窗口。服务端应对缺省 limit 使用 YAML 或代码常量声明的保守默认值，并对客户端传入 limit 套用最大上限；source 级全量导出只能作为显式管理/调试能力，不能作为普通 Web 页面、web-probe collect/analyze 或默认 CLI 输出的依赖。
|
||||
|
||||
所有写操作必须携带 expected document revision 或 fingerprint。revision 不匹配时返回 409/conflict 和脱敏诊断，不覆盖远端修改。删除任务必须明确影响范围，写入 audit，并在响应中返回新的 document revision 和 projection status。
|
||||
|
||||
只有当多人实时协同编辑成为主需求、任务查询和权限规则复杂到 Markdown 投影无法支撑、外部 PM adapter 已经成为主写入源，并且具备可靠 Markdown export/import、审计、冲突解决和离线恢复方案时，才重新评估 DB 作为权威存储。
|
||||
@@ -369,6 +373,8 @@ Workbench 可以保存和展示脱敏 `launchContext` 元数据，但 session、
|
||||
|
||||
web-probe 必须提供 `observe collect --view project-mdtodo-summary` 或等价第一层阅读视图。该视图只读取 `samples.jsonl`、`control.jsonl`、network/resource timing 和已有 analysis，输出 sourceId、fileRef、taskRef、revision before/after、mutation 结果、Workbench link/session/trace 摘要和慢路径 findings，不访问业务 API，不驱动浏览器，不构成第二事实源。
|
||||
|
||||
项目管理 analyzer 必须把 source 级全量 task 拉取、超过受控 limit 的响应、`/v1/project-management/mdtodo/tasks` 慢路径和 `status=0`/requestfailed 单独归类为 `mdtodo-task-window-*` 或等价 finding。修复方向应是 API/window/UI 的职责收敛，而不是把 web-probe script 超时时间调大、在脚本中直连 service、或用 Kubernetes/DB/SSH 补齐统计。
|
||||
|
||||
项目管理 analyzer 应输出 `project-management-*`、`mdtodo-*` 和 `workbench-launch-*` 前缀 findings，避免在非 Workbench 页面误报 Workbench session/trace 专属 finding。
|
||||
|
||||
### 6.8 CLIENT-PM-REQ-008 YAML-first 运行配置
|
||||
|
||||
Reference in New Issue
Block a user