From aead55489734b8dccc02056904a1df3606521048 Mon Sep 17 00:00:00 2001 From: Lyon <88232613+pikasTech@users.noreply.github.com> Date: Thu, 25 Jun 2026 21:22:26 +0800 Subject: [PATCH] docs: extend mdtodo web project management spec (#892) Co-authored-by: Codex --- .../PJ2026-01/specs/PJ2026-0104-client.md | 11 +- .../specs/PJ2026-010403-api-contract.md | 26 +++-- .../specs/PJ2026-010404-project-management.md | 100 ++++++++++++++++-- 3 files changed, 117 insertions(+), 20 deletions(-) diff --git a/project-management/PJ2026-01/specs/PJ2026-0104-client.md b/project-management/PJ2026-01/specs/PJ2026-0104-client.md index c8d71f98..7873b15f 100644 --- a/project-management/PJ2026-01/specs/PJ2026-0104-client.md +++ b/project-management/PJ2026-01/specs/PJ2026-0104-client.md @@ -22,7 +22,7 @@ | 短名 | 客户端 | | 层级 | L1 方向 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-project-management-mdtodo | +| 实现引用版本 | draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-project-management-mdtodo; draft-2026-06-25-p0-mdtodo-web-active-editing-hwpod-source | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -42,7 +42,7 @@ - Cloud Web 工作台、登录后工作流、任务创建、会话入口、trace/result 展示和用户可见资源入口。 - Cloud Web 通过 `/auth/session` 消费 canonical identity，并以业务 API 返回的 capability/blocker 展示授权状态。 - Cloud Web 的 CaseRun 用户入口、run 状态卡、trace/aggregate/HWPOD 证据阅读入口和可操作 blocker 展示。 -- Cloud Web 的项目管理根导航、MDTODO 页面、项目任务 DTO、Workbench launch context 和任务到 Workbench session 的公共 ID 链接。 +- Cloud Web 的项目管理根导航、MDTODO 页面、HWPOD-bound Source 配置、Rxx 任务树、主动编辑控件、项目任务 DTO、Workbench launch context 和任务到 Workbench session 的公共 ID 链接。 - HWLAB CLI 的运行端点解析、API key 鉴权入口、同源 API 调用、短连接命令、结构化输出、错误语义和脚本可用性。 - 通过 HWLAB CLI 覆盖账号/额度、工作台、显式 Agent session、Agent 任务、trace/result、HWPOD/CaseRun 组合入口和必要管理入口的非视觉全流程复验。 - web-probe 作为 Cloud Web 同源非视觉验收路径运行 CaseRun；它不拥有新的业务事实或后门接口。 @@ -66,6 +66,7 @@ | 同源 CLI | 与 Cloud Web 使用同一 Web origin、同一相对 API path 和同一用户身份语义的 HWLAB CLI 调用方式。 | | Web CaseRun 入口 | Cloud Web 中提交、观察和阅读 CaseRun 的用户界面，与同源 CaseRun API 和 HarnessRL run/read model 绑定。 | | 项目管理入口 | Cloud Web 登录后的 `/projects` 和 `/projects/mdtodo` 用户入口，用于查看项目 source、MDTODO 任务树和 Workbench link。 | +| MDTODO Web 主动编辑 | `/projects/mdtodo` 中通过 Project Management API 修改 Markdown source-of-truth 的用户操作，包括 Source 配置、Rxx task mutation、reindex 和 Workbench launch。 | | Workbench launch context | 项目管理等外部页面传给公共 Workbench Launch API 的脱敏启动上下文，只包含 `projectId`、`taskRef`、sourceKind、title 摘要和 prompt template 等元数据。 | | selected Web origin | 由 node/lane YAML 声明并由客户端工具解析的 Web origin；默认是 public origin，本次 D601/v03 验收可选择 internal IP origin。 | | web-probe CaseRun | 通过真实浏览器和 selected Web origin 执行的 CaseRun 验收路径；只模拟用户入口和同源 API，不直接访问未声明的内部服务。 | @@ -152,11 +153,15 @@ Cloud Web、HWLAB CLI 和 web-probe 必须使用 YAML 选中的同一 Web origin 客户端应提供登录后的项目管理入口，使用户能从 `/projects` 和 `/projects/mdtodo` 查看项目、source、MDTODO 文件摘要、任务树、任务状态、Workbench link 和结构化 blocker。 +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。 + 项目管理必须通过独立 `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 或测试后门补造成成功。 + MDTODO 页面启动 Workbench 时，只能调用公共 Workbench Launch API 并传递脱敏 `launchContext`、`projectId` 和 `taskRef`。Workbench 只消费这些元数据并按自身 session authority hydrate；项目管理页面不嵌入 Workbench、不 import Workbench store、不读取 Workbench 私有 reducer，Workbench 也不解析 Markdown 或 import MDTODO 页面。 -项目管理原入口验收优先使用 web-probe observe/analyze，采样 `/projects`、`/projects/mdtodo` 和自然同源 `/v1/project-management/*` 请求；`script` 只能作为短 API matrix、截图或 observe command 缺口的补充证据。 +项目管理原入口验收优先使用 web-probe observe/analyze，采样 `/projects`、`/projects/mdtodo` 和自然同源 `/v1/project-management/*` 请求；`script` 只能作为短 API matrix、截图或 observe command 缺口的补充证据。MDTODO Web closeout 必须至少有一次交互式 CLI 验收，使用同一个 observer 的 `observe command` 覆盖 Source 配置、HWPOD probe、文件选择、Rxx 树操作、编辑写回、reindex 和 Workbench launch，并用 `collect --view project-mdtodo-summary` 与 `observe analyze` 收口。 ## 7. 过程控制 diff --git a/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md b/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md index 008d93a0..e5541f9b 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md +++ b/project-management/PJ2026-01/specs/PJ2026-010403-api-contract.md @@ -19,7 +19,7 @@ | 短名 | API契约 | | 层级 | L2 课题 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-20-p0-workbench-pure-read-api; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-22-p1-workbench-redis-derived-cache; draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-project-management-mdtodo; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-24-p0-aggregate-event-stream; draft-2026-06-25-p0-serve-session-aggregate-authority; PJ2026-01050105 Web鉴权 draft-2026-06-18-p0-auth | +| 实现引用版本 | draft-2026-06-20-p0-workbench-pure-read-api; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-22-p1-workbench-redis-derived-cache; draft-2026-06-25-p0-web-caserun-e2e; draft-2026-06-25-p0-project-management-mdtodo; draft-2026-06-25-p0-mdtodo-web-active-editing-hwpod-source; PJ2026-0104010803 唯一投影 draft-2026-06-20-p0-durable-facts-model; draft-2026-06-20-p1-zero-split-durable-realtime; draft-2026-06-20-p2-terminal-outbox-recovery; draft-2026-06-24-p0-aggregate-event-stream; draft-2026-06-25-p0-serve-session-aggregate-authority; PJ2026-01050105 Web鉴权 draft-2026-06-18-p0-auth | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | | 关联规格 | [PJ2026-0104010803 Workbench唯一投影](PJ2026-0104010803-workbench-unique-projection.md)、[PJ2026-01060505 Workbench性能](PJ2026-01060505-workbench-performance.md) | @@ -41,7 +41,7 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE - Web session、API key、AuthPrincipal、actor 摘要和权限错误在客户端入口中的表达。 - Agent session、chat、steer、cancel、result、trace 和 inspect 的用户可见 API 形态。 - CaseRun case list、run admission、run status、events、aggregate、artifact manifest、cancel 和 HWPOD/AgentRun 引用的用户可见 API 形态。 -- 项目管理 navigation/projects/MDTODO source/file/task/workbench-link REST 资源、ProjectTask DTO、Workbench launch intent DTO 和独立项目管理服务代理边界。 +- 项目管理 navigation/projects/MDTODO source/file/task/workbench-link REST 资源、HWPOD-bound Source 配置、file content、task mutation、ProjectTask DTO、Workbench launch intent DTO 和独立项目管理服务代理边界。 - Workbench workspace、Admin Access、provider profile、HWPOD node-ops、gateway 和性能摘要等入口的字段稳定性。 - JSON 成功/失败响应、HTTP 状态、错误分类、脱敏、默认摘要和完整展开边界。 - Workbench pure-read API 的缓存诊断字段，包括 `cacheStatus`、`cacheAgeMs`、projection revision/seq、dbQueryAvoided 和 Redis unavailable/stale 的低基数表达。 @@ -67,7 +67,9 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE | 业务标识 | sessionId、turnId、traceId、runId、commandId、caseId 等用户可继续查询的稳定标识；projectId、workspaceId 和 conversationId 只能作为筛选、metadata 或兼容映射字段，不作为前端鉴权 authority。 | | CaseRun resource | Cloud Web origin 下表达 CaseRun case、run、stage、event、aggregate 和 artifact manifest 的 RESTful 资源集合。 | | Project Management resource | Cloud Web origin 下表达项目、source、MDTODO 文件、任务、Workbench link 和项目能力的 RESTful 资源集合。 | +| HWPOD-bound Source DTO | 项目管理 API 中表达 `sourceKind=hwpod-workspace`、`hwpodId`、`nodeId`、workspace 相对根、capability、probe status 和脱敏 blocker 的 Source 配置对象。 | | ProjectTask | 项目管理 API 返回的任务 DTO，包含 `taskRef`、`projectId`、`sourceId`、title、status、父子关系、linkCount 和脱敏 metadata。 | +| ProjectTask mutation | 对 MDTODO 任务 title/body/status/add/delete/reindex 的显式写入资源；必须带 expected revision 或 fingerprint，并由项目管理服务写入 Markdown source-of-truth。 | | `taskRef` | 项目管理 opaque 任务引用；API 可以转发和保存，Workbench、Cloud Web 和 CLI 不得解析其内部结构。 | | WorkbenchLaunchIntent | `POST /v1/workbench/launches` 的请求 DTO，用于把项目任务上下文传给 Workbench session admission。 | | ProjectWorkbenchLink | 项目管理 API 返回的任务到 Workbench session/trace 的链接摘要，只表达 ID 指针和脱敏状态。 | @@ -398,20 +400,32 @@ API契约应定义 YAML-selected Cloud Web origin 下的项目管理 RESTful 资 | --- | --- | --- | --- | --- | --- | | Navigation | `GET /v1/project-management/navigation` | 可选 `projectId` | 导航可见性、capability、默认 project/source 摘要、blocker | 200/401/403 | 只表达项目入口能力，不返回 raw Markdown | | Project list | `GET /v1/project-management/projects` | cursor、limit、可选筛选 | `projectId`、title、source 摘要、visibility、updatedAt | 200/401/403 | 当前 actor 可见项目列表 | -| MDTODO sources | `GET /v1/project-management/mdtodo/sources` | 可选 projectId | `sourceId`、displayName、root 摘要、read/write capability、parse/index status | 200/401/403 | 不暴露 host path、Secret 或完整 Git remote | +| MDTODO sources | `GET /v1/project-management/mdtodo/sources` | 可选 projectId | `sourceId`、displayName、sourceKind、root 摘要、read/write capability、parse/index status | 200/401/403 | 不暴露 host path、Secret 或完整 Git remote | +| MDTODO source create | `POST /v1/project-management/mdtodo/sources` | `sourceKind=hwpod-workspace`、`hwpodId`、`nodeId`、`mdtodoRootRef`、capability | Source DTO、source revision、probe status 可空 | 201/400/401/403/409/422 | 只创建受控 Source 配置，不直接暴露 HWPOD 文件系统 | +| MDTODO source update | `PATCH /v1/project-management/mdtodo/sources/{sourceId}` | displayName、root/capability patch、expected revision | updated Source DTO | 200/400/401/403/404/409/422 | 更新 ProjectSource registry，不改写任务文件 | +| MDTODO source delete | `DELETE /v1/project-management/mdtodo/sources/{sourceId}` | expected source revision、confirm impact | deleted sourceId、affected file/task/link counts、audit id | 200/400/401/403/404/409/422 | 禁用或删除 Source 配置，不删除 HWPOD workspace 文件 | +| MDTODO source probe | `POST /v1/project-management/mdtodo/sources/{sourceId}/probe` | 可选 probe options | HWPOD workspace op 摘要、capability、blocker、timing | 200/202/400/401/403/404/409/422 | 只探测连接和权限，不写任务事实 | +| 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 task mutation | `PATCH /v1/project-management/mdtodo/tasks/{taskRef}` | title/status/metadata patch、expected revision | updated ProjectTask、document revision、audit id | 200/400/401/403/404/409/422 | 写入必须经 MDTODO adapter 文件锁和原子写入 | +| 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，必须有影响范围摘要 | | Workbench launch | `POST /v1/workbench/launches` | `WorkbenchLaunchIntent`，含 `sourceKind=project-management`、`projectId`、`taskRef`、prompt template | `202 Accepted` 或 200、sessionId、workbenchUrl、linkId、traceId 可空 | 200/202/400/401/403/404/409/422 | Workbench 公共 mutation，不属于 MDTODO 私有 helper | | Workbench links | `GET /v1/project-management/workbench-links` | `taskRef`、可选 projectId/sourceId、cursor | linkId、sessionId、traceId、createdBy 摘要、createdAt、role、status | 200/401/403/404 | 只返回 ID 指针和脱敏摘要 | -`ProjectTask` DTO 至少应包含 `taskRef`、`projectId`、`sourceId`、`kind`、title、status、parentTaskRef、depth、linkCount、updatedAt 和 `valuesRedacted=true`。fileRef、lineNumber、source fingerprint、Markdown preview 和 parse diagnostic 只能作为脱敏 metadata 输出；默认响应不得包含 host path、raw Markdown、Secret、token、DB DSN、provider payload、完整 prompt 或可复用凭据。 +`ProjectSource` DTO 对 HWPOD-bound source 至少应包含 `sourceId`、`projectId`、`sourceKind="hwpod-workspace"`、displayName、`hwpodId`、`nodeId`、`mdtodoRootRef`、read/write capability、probe status、source revision、index status、blocker 可空和 `valuesRedacted=true`。`mdtodoRootRef` 只能是 workspace 相对根，例如 `docs/MDTODO/`；响应不得返回 host absolute path、Secret、session token、完整 file system listing 或未脱敏 node payload。 + +`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 或可复用凭据。 + +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。 项目管理 GET path 必须纯读。投影滞后、source 不可用、Markdown parse error、adapter unavailable、link 投影未收敛或 Workbench launch 尚未写回 link 时，GET 应返回 projecting、degraded、blocked 或结构化 failure；不得在 GET 中同步修复文件、触发 Workbench session 创建、调用 AgentRun dispatch、写 DB link、读取运行面 Secret 或访问未声明内部服务。 -项目管理 API 的错误必须使用 `HwlabErrorEnvelope` 或等价结构，并携带 route、status、code/blocker、resource id 摘要、OTel trace id、request id、serviceId 和 `valuesRedacted=true`。`mdtodo-raw-markdown-leak`、`mdtodo-hostpath-leak`、`mdtodo-taskref-missing`、`workbench-link-projection-missing` 等应作为可分析 code/blocker，而不是只返回裸字符串。 +项目管理 API 的错误必须使用 `HwlabErrorEnvelope` 或等价结构，并携带 route、status、code/blocker、resource id 摘要、OTel trace id、request id、serviceId 和 `valuesRedacted=true`。`mdtodo-raw-markdown-leak`、`mdtodo-hostpath-leak`、`mdtodo-taskref-missing`、`mdtodo-source-probe-failed`、`mdtodo-path-out-of-scope`、`mdtodo-document-revision-conflict`、`mdtodo-rxx-parse-error`、`mdtodo-hwpod-node-unavailable`、`workbench-link-projection-missing` 等应作为可分析 code/blocker，而不是只返回裸字符串。 web-probe observe/analyze 使用项目管理 API 时必须保持同源用户路径。它可以通过页面控件或同源正式 mutation 触发 Workbench launch，并通过自然请求、Resource Timing、DOM 摘要和 link API 观察结果；不得调用私有 service URL、Kubernetes、Postgres、D601 SSH、localStorage 后门或测试 fixture 来补齐通过证据。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md b/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md index 24ab488b..acab495f 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md +++ b/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md @@ -19,12 +19,11 @@ | 短名 | 项目管理 | | 层级 | L2 课题 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-25-p0-project-management-mdtodo | +| 实现引用版本 | draft-2026-06-25-p0-project-management-mdtodo; draft-2026-06-25-p0-mdtodo-web-active-editing-hwpod-source | | 需求规格模板 | [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) | | 规格治理索引 | [规格治理](spec-governance.md) | -| 架构治理 issue | [#2123](https://github.com/pikasTech/HWLAB/issues/2123)、P0 跟踪 [#2133](https://github.com/pikasTech/HWLAB/issues/2133) | 本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留项目管理的稳定使命、范围、术语、系统边界、内部分工和原子需求。 @@ -36,14 +35,18 @@ 本课题的目标状态是：Cloud Web 提供 `/projects` 根导航和 `/projects/mdtodo` 页面；MDTODO 任务能一键启动 Workbench；两者通过公共 API、`projectId`、`taskRef`、`sessionId`、`traceId` 和 `launchContext` 关联，不通过组件嵌套、store import、iframe、私有服务 URL 或 Markdown 结构解析互相依赖。 +`/projects/mdtodo` 的目标交互不只是只读投影。页面应支持 Web 配置 MDTODO Source、绑定 HWPOD workspace、按 Rxx 标准展示任务树、执行任务编辑 mutation，并通过受控 web-probe command 做交互式验收。Source/File 选择应收敛为顶部状态栏下拉，统计/诊断信息应进入 info/diagnostic 弹窗，主版面优先分配给任务树和编辑区。 + 项目管理从 P0 起必须作为独立 `hwlab-project-management` 微服务交付。它不作为 `hwlab-cloud-api` 内部模块起步，也不并入既有 UniDesk `mdtodo`、UniDesk `project-manager`、HWLAB Workbench runtime、Cloud Web 或 user-billing 服务。 ### 2.2 范围内 - Cloud Web `/projects` 根导航、项目列表、source 状态、能力摘要、blocker 和最近 Workbench link 展示。 - Cloud Web `/projects/mdtodo` 页面，展示 MDTODO source、Markdown 文件摘要、任务树、任务详情、状态、稳定 `taskRef`、链接摘要和 Workbench 启动入口。 +- `/projects/mdtodo` 的 Source 配置弹窗、HWPOD source binding、Source/File 顶部下拉、metric info/diagnostic 弹窗、Rxx 任务树和主动编辑控件。 - 独立 `hwlab-project-management` 微服务，包括 Project Management API、ProjectSource registry、MDTODO adapter 调度、DB read model、Workbench link 表、audit/outbox 和未来外部 PM adapter 扩展点。 -- MDTODO adapter 对 Markdown TODO 文件的解析、文件锁、原子写入、重建投影和 parse error 表达。 +- MDTODO adapter 对 Markdown TODO 文件的 Rxx heading 解析、文件锁、原子写入、重建投影、revision/fingerprint 并发保护和 parse error 表达。 +- HWPOD-bound MDTODO source 对 `d601-f103-v2` 这类 HWPOD workspace 的 `docs/MDTODO/` 受控读写。 - `projectId`、`sourceId`、`taskRef`、`linkId`、`sessionId` 和 `traceId` 的稳定关联模型。 - Workbench launch intent，即项目管理页面通过公共 Workbench Launch API 创建或选择 session，并记录项目任务与 Workbench session 的关联。 - 项目管理页面的 web-probe observe/analyze 采样、分析、DOM 脱敏、自然同源 API 分组、Workbench launch 控制动作和 YAML-first 阈值。 @@ -68,7 +71,10 @@ | ProjectSource | 项目任务来源，初始支持 `mdtodo`，后续可扩展到 `plane`、`vikunja`、`openproject` 等 adapter。 | | ProjectRecord | HWLAB 项目摘要，包含 `projectId`、标题、默认 source、可见性和更新时间。 | | MDTODO source | 指向一个受控 Markdown TODO 根目录或仓库视图的 ProjectSource。 | +| HWPOD-bound MDTODO source | `sourceKind=hwpod-workspace` 的 ProjectSource，绑定 `hwpodId`、`nodeId` 和 workspace 相对根，例如 `docs/MDTODO/`。 | +| Rxx 任务树 | MDTODO 标准的 heading 任务树，使用 `R1`、`R1.1`、`R1.1.1` 等 id 表达父子关系，层级来自 Rxx id 前缀而不是 checkbox 缩进或 Markdown heading 数量。 | | Markdown source-of-truth | MDTODO 的权威任务内容仍保存在 `.md` 文件中；DB 只保存可重建投影、link、audit/outbox。 | +| Document revision | 项目管理服务对单个 Markdown 文件内容、mtime、fingerprint 和 projection revision 的并发控制摘要。 | | `taskRef` | 项目管理 API 返回的 opaque 任务引用，例如 `mdtodo::#`；只有项目管理服务和 adapter 能反解。 | | ProjectTask | 从 source 投影出的任务 DTO，包含 `taskRef`、`projectId`、`sourceId`、title、status、父子关系、depth、linkCount 和更新时间。 | | WorkbenchLaunchContext | 项目管理页面发给公共 Workbench Launch API 的脱敏上下文，包含 `sourceKind=project-management`、`projectId`、`taskRef`、title 摘要和 prompt template 标识。 | @@ -76,6 +82,7 @@ | PM DB 投影 | 项目管理服务维护的 `project_sources`、`mdtodo_documents`、`mdtodo_task_projection`、`project_workbench_links`、`project_audit_events` 等可重建表。 | | Cloud API route/auth bridge | Cloud API 中只负责同源路由、AuthPrincipal、错误 envelope 和转发的桥接层；不拥有项目管理持久化或 Markdown 解析。 | | 项目管理 web-probe | 针对 `/projects`、`/projects/mdtodo` 和 `/v1/project-management/*` 的 observe/analyze 采样与分析能力，只观察公共页面和同源 API，不提供私有后门。 | +| `project-mdtodo-summary` | web-probe observe collect 的项目管理阅读视图，只从采样 artifact 渲染 Source/File/Task/Revision/Workbench link 摘要，不访问业务 API 或驱动浏览器。 | ## 4. 系统边界和接口 @@ -84,8 +91,8 @@ | 边界项 | 内容 | | --- | --- | | 外部使用者 | 硬件研发用户、平台管理员、需要从任务上下文启动 Workbench 的用户和自动化验收。 | -| 外部输入 | 浏览器导航、source/file/task 选择、任务状态修改请求、Workbench launch 请求、AuthPrincipal、项目可见性、Markdown source 和外部 PM adapter 事件。 | -| 受控资源 | `/projects`、`/projects/mdtodo`、`/v1/project-management/*`、`POST /v1/workbench/launches` 的项目上下文、MDTODO adapter、PM DB 投影、Workbench link、audit/outbox 和 web-probe artifact。 | +| 外部输入 | 浏览器导航、source/file/task 选择、任务状态修改请求、Workbench launch 请求、AuthPrincipal、项目可见性、Markdown source、HWPOD workspace source 配置和外部 PM adapter 事件。 | +| 受控资源 | `/projects`、`/projects/mdtodo`、`/v1/project-management/*`、`POST /v1/workbench/launches` 的项目上下文、MDTODO adapter、HWPOD node-ops workspace op、PM DB 投影、Workbench link、audit/outbox 和 web-probe artifact。 | | 外部输出 | 项目列表、source 摘要、文件摘要、任务树、任务详情、taskRef、Workbench link 摘要、capability/blocker、错误诊断、observe/analyze 报告和部署健康。 | | 用户接口 | Cloud Web 项目页面、同源 Project Management API、公共 Workbench Launch API、HWLAB CLI 同源 request 和 web-probe observe/analyze。 | | 系统边界 | 项目管理负责项目/任务入口、source 投影和 Workbench link；不执行 Agent、不拥有 Workbench session lifecycle、不替代用户权限、不把 `.md` 转为 DB 权威，也不承担平台发布运维。 | @@ -122,11 +129,16 @@ flowchart LR Links[(ProjectWorkbenchLink)] Audit[(audit/outbox)] Adapter[MDTODO Adapter] + HwpodAdapter[HWPOD Source Adapter] end subgraph Store[Task sources] Markdown[(.md source-of-truth)] + HwpodWs[(d601-f103-v2 workspace docs/MDTODO)] External[Future PM adapters] end + subgraph HWPOD[HWPOD node] + Ops[workspace.ls/cat/apply-patch/write] + end subgraph WB[Workbench] Session[(Session/read model)] Trace[(Trace/result projection)] @@ -139,7 +151,11 @@ flowchart LR Api --> Links Api --> Audit Api --> Adapter + Source --> HwpodAdapter Adapter --> Markdown + Adapter --> HwpodAdapter + HwpodAdapter --> Ops + Ops --> HwpodWs Api -.future adapter.-> External Mdtodo --> Launch Launch --> Session @@ -152,8 +168,9 @@ flowchart LR ```mermaid flowchart TD MD[Markdown TODO file] --> Parse[MDTODO adapter parse] - Parse --> Rev[MdtodoDocumentRevision] - Parse --> Task[MdtodoTaskProjection] + Parse --> Rxx[Rxx task tree R1/R1.1/R1.1.1] + Rxx --> Rev[MdtodoDocumentRevision] + Rxx --> Task[MdtodoTaskProjection] Task --> Api[GET /v1/project-management/mdtodo/tasks] Api --> UI[/projects/mdtodo task tree] UI --> Intent[WorkbenchLaunchContext] @@ -208,6 +225,54 @@ flowchart LR 项目管理验收优先使用 `observe start`、`observe command` 和 `observe analyze`。`web-probe script` 只作为短 API matrix、截图补证或 observe command 尚未覆盖时的过渡手段，不能作为原入口 closeout 的唯一证据。 +### 5.5 HWPOD Source 配置与编辑写回时序 + +```mermaid +sequenceDiagram + participant U as 用户 + participant P as /projects/mdtodo + participant PM as hwlab-project-management + participant H as HWPOD Source Adapter + participant N as hwpod-node node-ops + participant F as docs/MDTODO/*.md + U->>P: 打开 Source 配置弹窗 + P->>PM: POST /v1/project-management/mdtodo/sources {hwpodId,nodeId,root} + PM->>H: normalize + allowlist docs/MDTODO/ + H->>N: workspace.ls / workspace.cat probe + N->>F: 受控 workspace op + F-->>N: 文件摘要 + N-->>H: redacted result + H-->>PM: source probe status + PM-->>P: sourceId + capability + blocker 可空 + U->>P: 编辑 R1.1 title/status/body + P->>PM: PATCH taskRef with expected revision + PM->>H: lock document + mutate Rxx block + H->>N: workspace.apply-patch/write + N->>F: 原子写回 + H->>PM: new fingerprint + PM->>PM: rebuild projection + audit/outbox + PM-->>P: updated task + document revision +``` + +HWPOD-bound source 只能访问配置过的 workspace 相对根，例如 `docs/MDTODO/`。路径归一化必须拒绝 `..`、绝对路径、Secret 文件、未声明扩展名和非 allowlist 根；Web 不得展示任意文件浏览器，也不得直接调用 HWPOD node 私有接口。 + +### 5.6 web-probe 交互式 command 控制流 + +```mermaid +flowchart TD + Start[observe start /projects/mdtodo] --> Goto[command gotoProjectMdtodo] + Goto --> Config[command configureMdtodoHwpodSource] + Config --> Probe[command probeMdtodoSource] + Probe --> File[command selectMdtodoFile] + File --> Tree[command expand/select Rxx task] + Tree --> Mutate[command edit/toggle/add/reindex] + Mutate --> Launch[command launchWorkbenchFromMdtodo] + Launch --> Collect[collect --view project-mdtodo-summary] + Collect --> Analyze[observe analyze] +``` + +上述 command 必须通过页面 UI 或正式同源 API 表达用户动作，进入 `control.jsonl`。同类动作出现第二次时必须沉淀为 repo-owned command；一次性 `script` 只能作为探索、短 smoke、截图或 API matrix 补证。 + ## 6. 原子需求 ### 6.1 CLIENT-PM-REQ-001 项目根导航 @@ -230,7 +295,11 @@ flowchart LR 页面必须通过同源 `/v1/project-management/*` API 获取 DTO，不得直接访问 UniDesk microservice proxy、hostPath、SSH、Kubernetes、数据库、未声明内部 service URL 或 Markdown 文件系统。页面默认不得展示 host path、Secret、token、完整 raw Markdown、provider payload、DB DSN 或大段 stdout/stderr。 -MDTODO 页面可以提供任务状态写入入口，但写入必须进入项目管理服务，再由 MDTODO adapter 使用文件锁和原子写入修改 `.md`，随后重建投影。前端不得直接上传或覆盖 raw Markdown。 +页面布局应把 Source 和 File 选择压缩到顶部状态栏的两个下拉菜单；Source 配置由弹窗承载；Source/Files/Tasks/Links 等 metric 摘要进入 info/diagnostic 弹窗，不作为常驻大卡片占用主版面。任务树和详情/编辑区是主工作面，窄屏下也必须保持下拉、任务树、编辑控件和主要 action 可达且不重叠。 + +MDTODO 页面必须按 Rxx heading 标准组织任务树，至少支持 `R1`、`R1.1`、`R1.1.1` 的父子关系、展开/折叠、搜索、跳转、状态筛选和选中高亮。树 authority 来自项目管理 projection 中的 Rxx id 和 parentTaskRef，不得从 checkbox 缩进、DOM 缩进或标题级别临时推断。 + +MDTODO 页面可以提供任务状态和内容写入入口，但写入必须进入项目管理服务，再由 MDTODO adapter 使用文件锁和原子写入修改 `.md`，随后重建投影。前端不得直接上传或覆盖 raw Markdown。主动操作范围至少包括标题/正文或 raw block 编辑、`open/in_progress/completed` 状态切换、添加根任务、添加子任务、延续 sibling、删除任务、保存文本块、刷新文件、reindex 和 Workbench launch。 ### 6.3 CLIENT-PM-REQ-003 独立项目管理微服务 @@ -242,7 +311,7 @@ MDTODO 页面可以提供任务状态写入入口，但写入必须进入项目 Cloud API 只保留同源 route/proxy/auth bridge：负责 AuthPrincipal、route policy、错误 envelope、trace context 和转发，不拥有项目/任务持久化、Markdown 解析、外部 PM sync、Workbench link 表或 adapter 状态。即使 P0 只有只读 MDTODO 和 launch Workbench，也不得把实现先落到 `hwlab-cloud-api` 内部模块后再迁移。 -新增或重构的项目管理源码文件头部必须标注 `SPEC: PJ2026-010404 项目管理 draft-2026-06-25-p0-project-management-mdtodo`，并简述文件职责。 +新增或重构的项目管理源码文件头部必须标注 `SPEC: PJ2026-010404 项目管理 draft-2026-06-25-p0-mdtodo-web-active-editing-hwpod-source`，并简述文件职责；若文件只实现旧只读投影，也应同时引用 `draft-2026-06-25-p0-project-management-mdtodo`。 ### 6.4 CLIENT-PM-REQ-004 MDTODO adapter 与存储策略 @@ -252,7 +321,11 @@ Cloud API 只保留同源 route/proxy/auth bridge：负责 AuthPrincipal、route MDTODO 的权威存储应保持为 `.md` 文件。项目管理 DB 只保存可重建投影、Workbench link、audit/outbox 和 source sync 状态，不成为 Markdown 任务正文的唯一真实来源。 -PM DB 至少应能表达 `project_sources`、`mdtodo_documents`、`mdtodo_task_projection`、`project_workbench_links`、`project_audit_events` 或等价结构。`mdtodo_documents` 记录文件 fingerprint、mtime、lastIndexedAt、parseError 和 revision；`mdtodo_task_projection` 记录 `taskRef`、title、status、parentTaskRef、depth、linkCount、updatedAt 和 source fingerprint；link 表记录 `projectId/taskRef/sessionId/traceId`。 +MDTODO adapter 应兼容 VSCode 插件的 Rxx heading 语义：任务标题以 `## R1`、`### R1.1`、`#### R1.1.1` 或等价 heading 起始；状态 marker 至少支持 `[completed]`、`[in_progress]` 和历史 `[Processing]`、`[Finished]` 的读侧兼容；parentTaskRef 来自 Rxx id 前缀。checkbox list parser 只能作为显式 legacy mode，不能和 Rxx 标准任务树混成同一个 authority。 + +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`。 + +所有写操作必须携带 expected document revision 或 fingerprint。revision 不匹配时返回 409/conflict 和脱敏诊断，不覆盖远端修改。删除任务必须明确影响范围，写入 audit，并在响应中返回新的 document revision 和 projection status。 只有当多人实时协同编辑成为主需求、任务查询和权限规则复杂到 Markdown 投影无法支撑、外部 PM adapter 已经成为主写入源，并且具备可靠 Markdown export/import、审计、冲突解决和离线恢复方案时，才重新评估 DB 作为权威存储。 @@ -290,7 +363,9 @@ Workbench 可以保存和展示脱敏 `launchContext` 元数据，但 session、 项目管理页面应提供稳定 `data-testid` 或 ARIA 语义，覆盖项目导航、source 列表、file 列表、任务树、任务详情、selected task、Workbench launch 按钮、link 摘要、capability/blocker、empty/error/loading 状态。采样结果只保存 count、status、opaque id、hash/preview 和脱敏摘要，不保存 raw Markdown、host path、Secret、完整 prompt 或 provider payload。 -`observe command` 后续应支持 `selectProjectSource`、`selectMdtodoFile`、`selectMdtodoTask`、`launchWorkbenchFromTask` 等受控动作。动作必须通过页面 UI 或正式公共 API 触发，进入 `control.jsonl`，并在 `observe analyze` 中关联动作前后的 DOM/API/link 投影变化；不得调用私有 service URL、localStorage、Kubernetes、数据库或测试后门。 +`observe command` 应支持 MDTODO 交互式验收动作，包括 `gotoProjectMdtodo`、`openMdtodoSourceConfig`、`configureMdtodoHwpodSource`、`probeMdtodoSource`、`selectMdtodoSource`、`selectMdtodoFile`、`expandMdtodoTask`、`selectMdtodoTask`、`editMdtodoTaskTitle`、`editMdtodoTaskBody`、`toggleMdtodoTaskStatus`、`addMdtodoRootTask`、`addMdtodoSubTask`、`continueMdtodoTask`、`deleteMdtodoTask`、`reindexMdtodoSource`、`launchWorkbenchFromMdtodo`、`screenshot` 和 `mark`。动作必须通过页面 UI 或正式公共 API 触发，进入 `control.jsonl`，并在 `observe analyze` 中关联动作前后的 DOM/API/link 投影变化；不得调用私有 service URL、localStorage、Kubernetes、数据库或测试后门。 + +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 应输出 `project-management-*`、`mdtodo-*` 和 `workbench-launch-*` 前缀 findings，避免在非 Workbench 页面误报 Workbench session/trace 专属 finding。 @@ -304,6 +379,8 @@ Workbench 可以保存和展示脱敏 `launchContext` 元数据，但 session、 项目管理 web-probe target、readiness selector、自然请求 path group、DOM redaction allowlist、project command allowlist、loading/API 阈值和 slow path budget 也必须由受控 YAML 配置进入运行面，不得写在 probe 脚本、Cloud Web、项目管理服务或一次性 shell 中作为隐藏默认。 +D601/v03 的 HWPOD-bound MDTODO 验收应允许把 Source 配置到 `hwpodId=d601-f103-v2`、`nodeId=node-d601-f103-v2`、`mdtodoRootRef=docs/MDTODO/`。示例文件 `docs/MDTODO/hwlab-v03-mdtodo-web-sample.md` 应覆盖 `R1`、`R1.1`、`R1.1.1`、`R2`、`[in_progress]`、`[completed]` 和普通 text block，用于原入口 observe command 验收。 + Secret、DB DSN、provider token、session token、API key、host path 和 raw Markdown 内容不得出现在默认 CLI 输出、probe 报告、日志或错误 envelope 中。输出只披露对象名、key 名、sourceRef、presence、fingerprint、hash、字节数和 `valuesRedacted=true` 摘要。 ## 7. 过程控制 @@ -318,5 +395,6 @@ Secret、DB DSN、provider token、session token、API key、host path 和 raw M | P3 Workbench Launch 与 Link 投影 | [#2136](https://github.com/pikasTech/HWLAB/issues/2136) | 任务一键启动 Workbench，`projectId/taskRef/sessionId/traceId` link 可双向读取且模块解耦。 | | P4 web-probe observe/analyze 项目管理支持 | [#2137](https://github.com/pikasTech/HWLAB/issues/2137) | observe/analyze 输出项目管理 page-kind evidence，script 仅为补证。 | | P5 D601 YAML-first 部署与原入口验收 | [#2138](https://github.com/pikasTech/HWLAB/issues/2138) | D601/v03 selected origin 原入口通过 observe/analyze 完成 `/projects/mdtodo` 到 Workbench launch 验收。 | +| #2155 P0 增量 SPEC | [#2156](https://github.com/pikasTech/HWLAB/issues/2156) | HWPOD Source 配置、Rxx 主动编辑、web-probe command 验收和 D601 `docs/MDTODO/` 样例要求合并到 UniDesk master。 | P0 SPEC 完成前不得进入项目管理代码实现。每个阶段独立 PR 跟踪；PR 合并后必须把 PR、commit、observe/analyze 报告或原入口证据回写到对应阶段 issue 和 [#2123](https://github.com/pikasTech/HWLAB/issues/2123)。