diff --git a/project-management/PJ2026-01/specs/PJ2026-0104-client.md b/project-management/PJ2026-01/specs/PJ2026-0104-client.md index e180e07e..c8d71f98 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-web-caserun-e2e; draft-2026-06-25-p0-project-management-mdtodo | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -42,6 +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 链接。 - HWLAB CLI 的运行端点解析、API key 鉴权入口、同源 API 调用、短连接命令、结构化输出、错误语义和脚本可用性。 - 通过 HWLAB CLI 覆盖账号/额度、工作台、显式 Agent session、Agent 任务、trace/result、HWPOD/CaseRun 组合入口和必要管理入口的非视觉全流程复验。 - web-probe 作为 Cloud Web 同源非视觉验收路径运行 CaseRun；它不拥有新的业务事实或后门接口。 @@ -53,6 +54,7 @@ - Agent run、session、workspace 和 result 指针事实归 [Agent编排](PJ2026-0102-agent-orchestration.md)。 - HWPOD 资源、硬件事实和 probe 能力归 [硬件池](PJ2026-0101-hardware-pool.md)。 - CaseRun 评价、aggregate、replay 和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。 +- 项目管理的 source、任务投影、MDTODO adapter、Workbench link 和外部 PM adapter 归 [项目管理](PJ2026-010404-project-management.md)；Workbench 只消费公共 launch context 元数据。 - FRP、Caddy、TLS、CI/CD、Secret 和发布健康归 [平台运维](PJ2026-0106-platform-ops.md)。 ## 3. 术语表 @@ -63,6 +65,8 @@ | HWLAB CLI | HWLAB 命令行入口，用于脚本化访问 Web 同源 API、Agent、CaseRun、HWPOD、用户和管理能力。 | | 同源 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。 | +| 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，不直接访问未声明的内部服务。 | | API 契约 | HTTP API 和错误语义的稳定调用约定。 | @@ -90,6 +94,7 @@ | PJ2026-010401 | Web工作台 | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md) | Cloud Web 用户工作流、会话输入、诊断反馈和响应式布局 | 用户管理、Agent编排、硬件池、HarnessRL、平台运维 | 用户和管理员 | | PJ2026-010402 | HWLAB CLI | [PJ2026-010402 HWLAB CLI](PJ2026-010402-hwlab-cli.md) | 短连接命令、同源 API 调用、结构化输出、错误语义和非视觉全流程复验 | 全部业务 L1 | 用户脚本、自动化脚本、内测复现 | | PJ2026-010403 | API契约 | [PJ2026-010403 API契约](PJ2026-010403-api-contract.md) | 同源 API path、schema、鉴权主体、错误码和兼容性 | 用户管理、Agent编排、硬件池、HarnessRL、平台运维 | Web、HWLAB CLI | +| PJ2026-010404 | 项目管理 | [PJ2026-010404 项目管理](PJ2026-010404-project-management.md) | 项目根导航、MDTODO 页面、独立项目管理微服务、任务投影、Workbench link 和项目管理 observe/analyze 验收 | 用户管理、Agent编排、平台运维、API契约 | Web、HWLAB CLI、web-probe | ## 6. 原子需求 @@ -139,6 +144,20 @@ Cloud Web、HWLAB CLI 和 web-probe 必须使用 YAML 选中的同一 Web origin 客户端只拥有入口、展示、命令形态和错误呈现。CaseRun stage、aggregate、评价和回放归 HarnessRL；Agent run/command/trace 归 Agent编排；HWPOD 资源、租约、节点路由和 operation result 归硬件池。客户端发现能力缺失时应展示缺失能力和下一步诊断，不得用前端文案或脚本后处理合成通过状态。 +### 6.5 CLIENT-L1-REQ-005 项目管理入口 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-L1-REQ-005 | 项目管理 | [PJ2026-010404 项目管理](PJ2026-010404-project-management.md) | [PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) | + +客户端应提供登录后的项目管理入口，使用户能从 `/projects` 和 `/projects/mdtodo` 查看项目、source、MDTODO 文件摘要、任务树、任务状态、Workbench link 和结构化 blocker。 + +项目管理必须通过独立 `hwlab-project-management` 微服务和同源 Project Management API 暴露。客户端不得把项目管理实现并入 Workbench、Cloud Web 私有状态、Cloud API 内部模块、UniDesk `mdtodo` 或 UniDesk `project-manager` 服务。 + +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 缺口的补充证据。 + ## 7. 过程控制 本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。客户端方向的阶段活动材料应引用本规格和各 L2 规格，不在本规格正文中展开执行流水。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md index e5494747..d64c2723 100644 --- a/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md +++ b/project-management/PJ2026-01/specs/PJ2026-010401-web-workbench.md @@ -19,7 +19,7 @@ | 短名 | Web工作台 | | 层级 | L2 课题 | | 状态 | 已生效 | -| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p0-passive-web-probe-observer; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-24-p0-no-ui-timing-fabrication; draft-2026-06-25-p0-web-caserun-e2e; 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 | +| 实现引用版本 | draft-2026-06-20-p0-long-running-workbench; draft-2026-06-20-p0-error-diagnostics; draft-2026-06-20-p0-passive-web-probe-observer; draft-2026-06-20-p1-view-local-timing-ticker; draft-2026-06-24-p0-no-ui-timing-fabrication; 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 | | 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) | | 上级规格 | [PJ2026-0104 客户端](PJ2026-0104-client.md) | | 规格治理索引 | [规格治理](spec-governance.md) | @@ -45,6 +45,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 - 基本工作台 Agent 调用，包括最小任务输入、发送、短返回执行标识、状态查询入口和失败原因展示。 - 工作台诊断入口、运行状态摘要、probe/build/HWPOD/Agent 状态的低噪声展示方式。 - CaseRun 用户入口，包括 HWPOD 资源选择、case 列表、run 提交、run stage、Trace、HWPOD evidence、artifact manifest、aggregate 和 blocker 展示。 +- Workbench 公共 launch context 消费，包括从项目管理等外部登录后页面创建或选择 session，并把脱敏 `projectId/taskRef` 元数据写入 session projection。 - 桌面多栏布局、侧栏折叠、移动端工作台布局和输入区可达性。 - Web 与 HWLAB CLI 共用的 Code Agent composer policy、trace renderer 和同源 API 行为。 - Web 入口对用户管理、Agent编排、硬件池、HarnessRL 和平台运维输出事实的展示契约。 @@ -58,6 +59,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 - CaseRun 评价、回放和训练反馈语义归 [HarnessRL](PJ2026-0103-harness-rl.md)。 - 公开入口、CI/CD、GitOps、Secret、FRP、Caddy 和 runtime 健康归 [平台运维](PJ2026-0106-platform-ops.md)。 - CLI 参数、CLI 输出和 HTTP API 契约仍归 [PJ2026-0104 客户端](PJ2026-0104-client.md) 中对应 L2 课题。 +- 项目管理根导航、MDTODO source、Markdown 解析、任务投影、ProjectWorkbenchLink 和外部 PM adapter 归 [PJ2026-010404 项目管理](PJ2026-010404-project-management.md)。 ## 3. 术语表 @@ -72,6 +74,8 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | 同源业务入口 | Cloud Web 与 HWLAB CLI 通过同一 Web origin、相对 REST/JSON API path 和业务标识访问 HWLAB 能力的入口。 | | Web CaseRun 视图 | Web 工作台或其相邻登录后页面中用于提交、观察和阅读 CaseRun 的用户界面。 | | CaseRun run 卡 | 展示一次 CaseRun 的 runId、caseId、hwpodId、stage、Trace、HWPOD evidence、artifact manifest、aggregate 和 blocker 的紧凑工作态组件。 | +| WorkbenchLaunchContext | 项目管理等外部页面传给公共 Workbench Launch API 的脱敏启动上下文，Workbench 只把它作为 session metadata 保存和展示，不反解外部任务来源。 | +| ProjectTaskRef | 项目管理 API 返回的 opaque `taskRef`；Workbench 可保存和显示其摘要，但不得解析 Markdown、文件路径或 adapter 内部结构。 | | selected Web origin | Web 工作台、CLI 和 web-probe 共同使用的 YAML-selected origin；默认 public，D601/v03 端到端验收可由 YAML 切换到 internal IP。 | | 浏览器登录态 | Cloud Web 随同源请求携带的 `hwlab_session` Web session transport；前端只负责传递，不解释权限、project 归属或资源可见性。 | | canonical identity | Web 工作台从 `/auth/session` 读取的最小身份结果，包含 actor、`authMethod`、`identityAuthority`、`sessionKind` 和 capability 摘要；它是 Web shell、导航和业务页面的唯一身份输入。 | @@ -133,6 +137,7 @@ Web工作台负责 HWLAB 登录后的浏览器主入口，使用户能够在同 | PJ2026-01040110 | 浏览器回归 | 本规格 6.10 | Playwright 独立测试、真实采集 fixture、mock server、截图 artifact 和状态投影断言 | API契约、平台运维 | Workbench 功能回归、防止刷新和会话切换退化 | | PJ2026-01040111 | 长程观测 | 本规格 6.11 | 纯客户端 web-probe observer、命令文件控制、无副作用采样、JSONL artifact 和后处理分析 | 平台运维、公开入口 | Workbench 长程稳定性、瞬态竞态复现 | | PJ2026-01040112 | CaseRun入口 | 本规格 6.12 | Web CaseRun 视图、run 卡、证据阅读、blocker 展示和 web-probe 同路径验收 | HarnessRL、API契约、硬件池、Agent编排 | 用户端到端硬件验证 | +| PJ2026-01040113 | 项目启动 | 本规格 6.13 | 公共 Workbench launch context 消费、session metadata 投影和项目任务解耦边界 | 项目管理、API契约、Agent编排 | `/projects/mdtodo` 一键启动 Workbench | ### 5.1 目标数据流程图 @@ -494,6 +499,20 @@ Web 工作台只调用 YAML-selected origin 下的同源 CaseRun API 和既有 T 线上 web-probe 对 CaseRun 的验收必须从同一 selected Web origin 进入。默认使用正式 public origin；本次 D601/v03 可以由 YAML 切换到 internal IP origin。web-probe 可以点击页面控件或调用页面同源正式 mutation，但不得绕过 Web session、不得使用未被 YAML 选中的内部 service URL、不得直接写 D601 文件系统、不得用 SSH 或手工 CLI 操作补齐硬件证据。web-probe 报告至少应记录 originMode、YAML source path、final URL、截图 SHA、caseId、runId、hwpodId、nodeId、traceId、HWPOD operation result 引用、aggregate 或 artifact manifest hash，以及是否存在用户可见 blocker。 +### 6.13 CLIENT-WB-REQ-013 项目启动 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-WB-REQ-013 | 项目启动 | PJ2026-01040113 项目启动 | [PJ2026-010404 项目管理](PJ2026-010404-project-management.md)、[PJ2026-010403 API契约](PJ2026-010403-api-contract.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) | + +Web 工作台应提供公共 launch context 消费能力，使项目管理等登录后页面可以通过 `POST /v1/workbench/launches` 创建或选择 Workbench session，并把脱敏 `projectId`、`taskRef`、`sourceKind`、title 摘要和 prompt template 标识保存为 session metadata。 + +Workbench 对 launch context 的使用必须保持只读和脱敏。它可以在 session header、message detail 或诊断入口展示项目来源摘要，也可以把 metadata 传给 Agent turn admission；但不得反解 `taskRef`、读取 Markdown、调用 Project Management 私有 adapter、访问 PM DB、import MDTODO 页面组件或把项目管理状态写入 Workbench reducer。 + +项目管理页面跳转到 `/workbench/sessions/{sessionId}` 后，Workbench 必须按既有 session detail、message page、turn snapshot 和 trace event page authority hydrate。`projectId/taskRef` 只作为 metadata 和后续查询 link 的 ID，不得替代 sessionId、turnId、traceId 或 messageId 成为 Workbench authority。 + +Workbench 模块不得为了项目管理联动新增 iframe、嵌套 Workbench 容器、localStorage 协议、私有 service URL、跨模块 store import 或 Markdown parser 依赖。需要回到项目任务时，只能使用公共 project link URL 或公共 Project Management API 暴露的 link 摘要。 + ## 7. 过程控制 本规格不单独索引过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `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 6234e816..008d93a0 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; 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; 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,6 +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 和独立项目管理服务代理边界。 - 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 的低基数表达。 @@ -51,6 +52,7 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE - AgentRun run、command、runner job、session continuation 和 provider runtime 归 [Agent编排](PJ2026-0102-agent-orchestration.md)。 - HWPOD 资源身份、硬件操作、node 路由和原始硬件事实归 [硬件池](PJ2026-0101-hardware-pool.md)。 - CaseRun、评价、aggregate、回放和训练反馈归 [HarnessRL](PJ2026-0103-harness-rl.md)。 +- ProjectSource、MDTODO adapter、Markdown 任务投影、ProjectWorkbenchLink 和外部 PM adapter 归 [项目管理](PJ2026-010404-project-management.md)。 - 运行端点、FRP/Caddy、Secret、rollout 和 Prometheus 监控归 [平台运维](PJ2026-0106-platform-ops.md)。 - Redis workload、镜像、资源、NetworkPolicy、TTL 数值、metrics scrape 和运行面发布归 [平台运维](PJ2026-0106-platform-ops.md) 与 [Workbench性能](PJ2026-01060505-workbench-performance.md)；API契约只定义客户端可见字段和诊断边界。 @@ -64,6 +66,11 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE | CanonicalPrincipal | `/auth/session` 和受保护业务 route 共享的最小身份结果，包含 `authMethod`、`identityAuthority`、`sessionKind`、actor 摘要和后端 capability 摘要；它是业务 route 的唯一身份输入。 | | 业务标识 | 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 资源集合。 | +| ProjectTask | 项目管理 API 返回的任务 DTO，包含 `taskRef`、`projectId`、`sourceId`、title、status、父子关系、linkCount 和脱敏 metadata。 | +| `taskRef` | 项目管理 opaque 任务引用；API 可以转发和保存，Workbench、Cloud Web 和 CLI 不得解析其内部结构。 | +| WorkbenchLaunchIntent | `POST /v1/workbench/launches` 的请求 DTO，用于把项目任务上下文传给 Workbench session admission。 | +| ProjectWorkbenchLink | 项目管理 API 返回的任务到 Workbench session/trace 的链接摘要，只表达 ID 指针和脱敏状态。 | | Run admission | 接收 CaseRun 提交并返回 `202 Accepted`、runId、statusUrl 和下一步查询入口的短返回 mutation。 | | selected origin mode | 客户端入口从 YAML 解析出的 origin 模式，至少区分 `public` 和 `internal`；API 只看到同源请求，不反推或硬编码入口地址。 | | 错误语义 | HTTP status、错误码、blocker、failureKind、route 和下一步提示组成的可定位失败表达。 | @@ -114,6 +121,7 @@ API契约负责定义 Cloud Web、HWLAB CLI 和自动化脚本共同使用的 RE | PJ2026-01040305 | 错误输出 | 本规格 6.5 | JSON 成功/失败响应、错误码、route/status、脱敏和渐进披露 | 全部业务 L1 | 用户、脚本、排障 | | PJ2026-01040306 | 缓存诊断 | 本规格 6.6 | Workbench pure-read cache diagnostic 字段、脱敏边界和禁止状态仲裁 | Workbench唯一投影、Workbench性能 | Web、CLI、Performance 页 | | PJ2026-01040307 | CaseRun接口 | 本规格 6.7 | CaseRun case/run/status/events/aggregate/cancel REST 资源、短返回和错误语义 | HarnessRL、硬件池、Agent编排 | Web CaseRun、CLI、web-probe | +| PJ2026-01040308 | 项目管理接口 | 本规格 6.8 | 项目管理 REST 资源、MDTODO DTO、Workbench launch intent、link 查询和独立微服务代理边界 | 项目管理、Web工作台、用户管理 | `/projects`、`/projects/mdtodo`、CLI、web-probe | 目标后端模块应至少拆分为 route/handler、schema/contract、read model、persistence/projection、AgentRun adapter、trace event pager、SSE/event publisher 和 compat wrapper。route 文件只负责 HTTP 入口、鉴权桥接和错误映射；schema/contract 只负责类型和字段；read model 只组装查询模型；adapter 只转换外部执行事实；projection 只写 durable facts；compat wrapper 只提供旧 path 到新资源的兼容映射，不拥有第二套业务事实。 @@ -376,6 +384,37 @@ CaseRun API 必须把事实来源分仓输出。AgentRun refs 至少应能指向 web-probe 使用 CaseRun API 时必须保持 YAML-selected origin 下的同源用户路径。它可以通过页面控件或同源正式 mutation 提交 run，并通过同一 status/events/aggregate 资源观察终态；当 YAML 选择 internal origin 时可以使用内部 IP，但仍不得调用未声明的内部 service URL、Kubernetes、Postgres、D601 SSH、本地 gateway 端口、旧 v0.2 runner 或测试 fixture 来补齐 CaseRun 成功证据。 +### 6.8 CLIENT-API-REQ-008 项目管理用户接口 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-API-REQ-008 | 项目管理接口 | PJ2026-01040308 项目管理接口 | [PJ2026-010404 项目管理](PJ2026-010404-project-management.md)、[PJ2026-010401 Web工作台](PJ2026-010401-web-workbench.md)、[用户管理](PJ2026-0105-user-management.md) | + +API契约应定义 YAML-selected Cloud Web origin 下的项目管理 RESTful 资源，使 Cloud Web、HWLAB CLI 和 web-probe 能用同一用户身份、同一相对 path、同一错误 envelope 和同一脱敏边界访问项目、source、MDTODO 文件、任务、Workbench link 和 Workbench launch intent。 + +目标项目管理 API 资源设计如下。Cloud API 可以作为同源 route/auth bridge 转发到独立 `hwlab-project-management` 微服务，但不得拥有项目管理持久化、Markdown 解析、外部 PM sync、Workbench link 表或 adapter 状态。 + +| 资源 | Method / path | 请求字段 | 响应主体 | 状态码 | 权威边界 | +| --- | --- | --- | --- | --- | --- | +| 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 files | `GET /v1/project-management/mdtodo/files` | `sourceId`、cursor、limit | fileRef、displayName、taskCount、status、fingerprint hash、parseError 摘要 | 200/401/403/404 | 文件摘要，不返回完整 Markdown | +| 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 文件锁和原子写入 | +| 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 或可复用凭据。 + +`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，而不是只返回裸字符串。 + +web-probe observe/analyze 使用项目管理 API 时必须保持同源用户路径。它可以通过页面控件或同源正式 mutation 触发 Workbench launch，并通过自然请求、Resource Timing、DOM 摘要和 link API 观察结果；不得调用私有 service URL、Kubernetes、Postgres、D601 SSH、localStorage 后门或测试 fixture 来补齐通过证据。 + ## 7. 过程控制 本规格不单独索引一般过程 issue；跨 L1 的内测、灰度和阶段活动索引统一保留在 [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) 的 `7. 过程控制`。Workbench Redis 派生读缓存架构执行 issue 为 [#1870](https://github.com/pikasTech/HWLAB/issues/1870)，P0 SPEC-first 子 issue 为 [#1871](https://github.com/pikasTech/HWLAB/issues/1871)，后续实现必须引用 `draft-2026-06-22-p1-workbench-redis-derived-cache`。 diff --git a/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md b/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md new file mode 100644 index 00000000..24ab488b --- /dev/null +++ b/project-management/PJ2026-01/specs/PJ2026-010404-project-management.md @@ -0,0 +1,322 @@ +# PJ2026-010404 项目管理 + +## 修改历史 + +| 版本 | 对应 commit id | 更新日期 | 变更说明 | +| --- | --- | --- | --- | + +当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。 + +## 正文 + +## PJ2026-010404 项目管理需求规格 + +## 1. 文档控制 + +| 字段 | 内容 | +| --- | --- | +| 编号 | PJ2026-010404 | +| 短名 | 项目管理 | +| 层级 | L2 课题 | +| 状态 | 已生效 | +| 实现引用版本 | draft-2026-06-25-p0-project-management-mdtodo | +| 需求规格模板 | [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 需求规格模板的项目裁剪版：正文只保留项目管理的稳定使命、范围、术语、系统边界、内部分工和原子需求。 + +## 2. 目的和范围 + +### 2.1 目的 + +项目管理负责 HWLAB 登录后的项目入口、项目 source、MDTODO 任务树、任务与 Workbench session 的公共 ID 关联，以及后续外部项目管理系统 adapter 的统一入口。 + +本课题的目标状态是：Cloud Web 提供 `/projects` 根导航和 `/projects/mdtodo` 页面；MDTODO 任务能一键启动 Workbench；两者通过公共 API、`projectId`、`taskRef`、`sessionId`、`traceId` 和 `launchContext` 关联，不通过组件嵌套、store import、iframe、私有服务 URL 或 Markdown 结构解析互相依赖。 + +项目管理从 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 启动入口。 +- 独立 `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 表达。 +- `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 阈值。 +- D601/v03 YAML-first 独立微服务部署所需的 serviceId、namespace、Secret sourceRef、DB migration、OTel `service.name`、public route/proxy 和 health/readiness 声明。 + +### 2.3 范围外 + +- Workbench session、turn、run、command、trace/result 执行事实归 [Agent编排](PJ2026-0102-agent-orchestration.md) 和 Workbench 相关规格。 +- 用户身份、role、capability、tenant/project visibility、API key 和额度归 [用户管理](PJ2026-0105-user-management.md)。 +- Cloud API 的同源 path、错误 envelope、鉴权主体和 DTO 稳定性归 [API契约](PJ2026-010403-api-contract.md)。 +- Cloud Web Workbench 的 session hydrate、timeline、trace renderer、composer 和状态投影归 [Web工作台](PJ2026-010401-web-workbench.md)。 +- CI/CD、GitOps、FRP/Caddy、Secret 下发、public URL、OTel/Prometheus 和 rollout 归 [平台运维](PJ2026-0106-platform-ops.md)。 +- P0 不直接部署 OpenProject、Plane、Vikunja、Redmine、Taiga、Huly、Leantime 或其他完整 PM 套件。 +- P0 不把 Markdown TODO 权威数据迁移到数据库，不让 Workbench 解析 Markdown，也不让项目管理页面嵌入 Workbench。 + +## 3. 术语表 + +| 术语 | 定义 | +| --- | --- | +| 项目管理 | HWLAB 登录后的项目、source、任务和 Workbench link 入口。 | +| `hwlab-project-management` | 独立项目管理微服务，拥有项目管理 API、source registry、MDTODO adapter 编排、DB 投影、Workbench link、audit/outbox 和外部 PM adapter 扩展点。 | +| ProjectSource | 项目任务来源，初始支持 `mdtodo`，后续可扩展到 `plane`、`vikunja`、`openproject` 等 adapter。 | +| ProjectRecord | HWLAB 项目摘要，包含 `projectId`、标题、默认 source、可见性和更新时间。 | +| MDTODO source | 指向一个受控 Markdown TODO 根目录或仓库视图的 ProjectSource。 | +| Markdown source-of-truth | MDTODO 的权威任务内容仍保存在 `.md` 文件中；DB 只保存可重建投影、link、audit/outbox。 | +| `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 标识。 | +| ProjectWorkbenchLink | `projectId/taskRef/sessionId/traceId` 的稳定关联记录，用于从任务回到 Workbench session 或从 Workbench 元数据看到来源。 | +| 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，不提供私有后门。 | + +## 4. 系统边界和接口 + +本规格把项目管理作为客户端方向下的独立项目入口课题看待；本章只描述输入、输出和责任边界。 + +| 边界项 | 内容 | +| --- | --- | +| 外部使用者 | 硬件研发用户、平台管理员、需要从任务上下文启动 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 摘要、文件摘要、任务树、任务详情、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 权威，也不承担平台发布运维。 | + +## 5. 内部分工与规格索引 + +| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 | +| --- | --- | --- | --- | --- | --- | +| PJ2026-01040401 | 项目根导航 | 本规格 6.1 | `/projects` 一级入口、项目列表、source 状态、capability/blocker | 用户管理、Project Management API、平台入口 | 登录后项目入口、MDTODO 页面 | +| PJ2026-01040402 | MDTODO 页面 | 本规格 6.2 | `/projects/mdtodo` source/file/task/taskRef/link/launch 展示 | Project Management API、MDTODO adapter、API契约 | 用户任务阅读和 Workbench 启动 | +| PJ2026-01040403 | 独立微服务 | 本规格 6.3 | `hwlab-project-management` API、source registry、DB 投影、audit/outbox、adapter 编排 | 用户管理、平台运维、API契约 | Cloud Web、CLI、web-probe | +| PJ2026-01040404 | MDTODO adapter 与存储 | 本规格 6.4 | Markdown source-of-truth、解析、文件锁、原子写入、投影重建 | MDTODO `.md` source、mdtodo parser/CLI/service | ProjectTask DTO、DB 投影 | +| PJ2026-01040405 | Workbench Link | 本规格 6.5 | 公共 launch context、link 表、ID 关联和解耦边界 | Workbench Launch API、Agent编排 | 项目任务到 Workbench session | +| 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 | + +### 5.1 目标架构图 + +```mermaid +flowchart LR + subgraph Browser[Cloud Web] + Root[/projects/] + Mdtodo[/projects/mdtodo/] + end + subgraph Edge[Cloud API same-origin] + Bridge[route/auth bridge + HwlabErrorEnvelope] + Launch[POST /v1/workbench/launches] + end + subgraph PM[hwlab-project-management] + Api[Project Management API] + Source[ProjectSource Registry] + Projection[(PM DB read model)] + Links[(ProjectWorkbenchLink)] + Audit[(audit/outbox)] + Adapter[MDTODO Adapter] + end + subgraph Store[Task sources] + Markdown[(.md source-of-truth)] + External[Future PM adapters] + end + subgraph WB[Workbench] + Session[(Session/read model)] + Trace[(Trace/result projection)] + end + Root --> Bridge + Mdtodo --> Bridge + Bridge --> Api + Api --> Source + Api --> Projection + Api --> Links + Api --> Audit + Api --> Adapter + Adapter --> Markdown + Api -.future adapter.-> External + Mdtodo --> Launch + Launch --> Session + Launch --> Links + Session --> Trace +``` + +### 5.2 数据流图 + +```mermaid +flowchart TD + MD[Markdown TODO file] --> Parse[MDTODO adapter parse] + Parse --> Rev[MdtodoDocumentRevision] + Parse --> Task[MdtodoTaskProjection] + Task --> Api[GET /v1/project-management/mdtodo/tasks] + Api --> UI[/projects/mdtodo task tree] + UI --> Intent[WorkbenchLaunchContext] + Intent --> Launch[POST /v1/workbench/launches] + Launch --> Sess[Workbench sessionId] + Sess --> Link[ProjectWorkbenchLink] + Link --> LinkApi[GET /v1/project-management/workbench-links] + LinkApi --> UI +``` + +MDTODO `.md` 文件是任务正文的 source-of-truth。PM DB 投影只用于导航、检索、权限投影、Workbench link 和审计，可从 source 重建。写入路径必须是 Web mutation 到项目管理服务，再到 adapter 文件锁和原子写入，最后重建投影；前端不得直接 PUT raw Markdown，DB 投影不得绕过 adapter 反写文件。 + +### 5.3 Workbench 启动时序 + +```mermaid +sequenceDiagram + participant U as 用户 + participant P as /projects/mdtodo + participant PM as Project Management API + participant W as Workbench Launch API + participant R as Workbench Read Model + U->>P: 选择 source/file/task + P->>PM: GET /v1/project-management/mdtodo/tasks + PM-->>P: ProjectTask DTO with taskRef + U->>P: 点击在 Workbench 执行 + P->>W: POST /v1/workbench/launches {projectId, taskRef, launchContext} + W->>R: create/select session with project metadata + W->>PM: record ProjectWorkbenchLink + W-->>P: sessionId, workbenchUrl, linkId + P->>PM: GET workbench-links by taskRef + P->>U: router.push(workbenchUrl) + U->>R: /workbench/sessions/{sessionId} + R-->>U: session/messages/trace projection +``` + +Workbench 接收 `launchContext` 元数据，但不反解 `taskRef`、不读取 Markdown、不 import MDTODO 页面或 adapter。项目管理页面只拿到 `sessionId` 和 `workbenchUrl`，随后让 Workbench 自己按 session authority hydrate。 + +### 5.4 web-probe observe/analyze 流程 + +```mermaid +flowchart LR + Start[observe start --target-path /projects/mdtodo] --> Page[Project Management page] + Page --> Dom[DOM/testId/ARIA passive samples] + Page --> Net[Natural same-origin network] + Cmd[observe command select/launch/screenshot/mark] --> Page + Dom --> Art[(JSONL artifacts)] + Net --> Art + Cmd --> Art + Art --> Analyze[observe analyze page-kind project-management-mdtodo] + Analyze --> Report[analysis/report.md + report.json] +``` + +项目管理验收优先使用 `observe start`、`observe command` 和 `observe analyze`。`web-probe script` 只作为短 API matrix、截图补证或 observe command 尚未覆盖时的过渡手段，不能作为原入口 closeout 的唯一证据。 + +## 6. 原子需求 + +### 6.1 CLIENT-PM-REQ-001 项目根导航 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-PM-REQ-001 | 项目根导航 | PJ2026-01040401 项目根导航 | [Web工作台](PJ2026-010401-web-workbench.md)、[用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) | + +项目管理应提供 Cloud Web 登录后一级“项目”导航和 `/projects` 根页面，使用户可以看到可见项目、source 状态、最近任务、最近 Workbench session link、capability 和 blocker。 + +项目根导航不得嵌入 Workbench，也不得以 Workbench session、workspace snapshot 或 localStorage 作为项目可见性 authority。项目列表和 source 状态只能来自同源 Project Management API 和当前 AuthPrincipal；未登录、无权限、source 不可用和 adapter parse 失败必须显示结构化 blocker。 + +### 6.2 CLIENT-PM-REQ-002 MDTODO 页面 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-PM-REQ-002 | MDTODO页面 | PJ2026-01040402 MDTODO 页面 | [API契约](PJ2026-010403-api-contract.md)、[用户管理](PJ2026-0105-user-management.md) | + +项目管理应提供 `/projects/mdtodo` 页面，使用户可以选择 MDTODO source、Markdown 文件摘要和任务树，查看任务 title、status、父子关系、link 摘要、capability/blocker 和稳定 `taskRef`。 + +页面必须通过同源 `/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。 + +### 6.3 CLIENT-PM-REQ-003 独立项目管理微服务 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-PM-REQ-003 | 独立微服务 | PJ2026-01040403 独立微服务 | [API契约](PJ2026-010403-api-contract.md)、[用户管理](PJ2026-0105-user-management.md)、[平台运维](PJ2026-0106-platform-ops.md) | + +项目管理后端必须作为独立 `hwlab-project-management` 微服务交付。该服务拥有 Project Management API、ProjectSource registry、MDTODO adapter 编排、PM DB read model、ProjectWorkbenchLink、audit/outbox、health/readiness、OTel `service.name` 和未来外部 PM adapter 扩展点。 + +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`，并简述文件职责。 + +### 6.4 CLIENT-PM-REQ-004 MDTODO adapter 与存储策略 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-PM-REQ-004 | MDTODO存储 | PJ2026-01040404 MDTODO adapter 与存储 | 项目管理独立微服务、平台运维 | + +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`。 + +只有当多人实时协同编辑成为主需求、任务查询和权限规则复杂到 Markdown 投影无法支撑、外部 PM adapter 已经成为主写入源，并且具备可靠 Markdown export/import、审计、冲突解决和离线恢复方案时，才重新评估 DB 作为权威存储。 + +### 6.5 CLIENT-PM-REQ-005 Workbench Link 与解耦 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-PM-REQ-005 | Workbench联动 | PJ2026-01040405 Workbench Link | [Web工作台](PJ2026-010401-web-workbench.md)、[API契约](PJ2026-010403-api-contract.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) | + +项目管理页面应通过公共 Workbench Launch API 启动 Workbench。请求只能携带 `projectId`、`taskRef`、`launchContext`、prompt template 或等价脱敏元数据；响应返回 `sessionId`、`workbenchUrl`、可选 `traceId/linkId` 和错误诊断。 + +Workbench 与项目管理必须互相解耦。项目管理页面不得 import `useWorkbenchStore`、`CodeWorkbenchView`、Workbench reducer、Trace renderer 私有模块或 session 内部状态；Workbench 模块不得 import MDTODO 页面、MDTODO adapter、Markdown parser 或 Project Management DB。两者不得通过 iframe、嵌套容器、localStorage、私有 service URL、数据库 join 或解析对方 ID 内部结构关联。 + +Workbench 可以保存和展示脱敏 `launchContext` 元数据，但 session、turn、message、trace 和 final response 的 authority 仍来自 Workbench durable projection。项目管理页面返回后通过 `GET /v1/project-management/workbench-links?taskRef=...` 读取 link 摘要，不从 Workbench 私有 store 反查。 + +### 6.6 CLIENT-PM-REQ-006 外部 PM adapter 边界 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-PM-REQ-006 | 外部PM适配 | PJ2026-01040406 外部 PM adapter | 项目管理独立微服务、用户管理 | + +项目管理应预留外部 PM adapter 边界，但 P0 不直接引入完整外部套件。Plane 可作为未来 work item 平台优先候选，Vikunja 可作为任务/todo 后端优先候选，OpenProject/Redmine/Taiga/Huly/Leantime 仅作为后续 adapter 评估对象。 + +外部 PM adapter 必须通过 ProjectSource 和 ProjectTask DTO 进入项目管理服务，不得替换 HWLAB 项目管理 API，也不得让 Cloud Web 直接调用外部系统 UI/API 成为第二入口。外部服务的授权、同步、冲突、审计和脱敏策略必须先落入项目管理服务边界，再暴露给 Web 和 CLI。 + +### 6.7 CLIENT-PM-REQ-007 web-probe observe/analyze + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-PM-REQ-007 | 观测验收 | PJ2026-01040407 观测与验收 | [Web工作台](PJ2026-010401-web-workbench.md)、[平台运维](PJ2026-0106-platform-ops.md) | + +项目管理页面必须支持 web-probe observe/analyze 原入口验收。`web-probe observe start --target-path /projects/mdtodo` 应能在 selected Web origin 采样项目管理页面，并通过 `observe analyze` 输出 issue-ready evidence：observer id、stateDir、report SHA、screenshot SHA、page-kind 摘要、DOM 摘要、自然同源 API timing 和 findings。 + +采样器应优先观察自然页面行为：`/auth/session`、`/v1/project-management/navigation`、`/v1/project-management/projects`、`/v1/project-management/mdtodo/sources`、`/v1/project-management/mdtodo/files`、`/v1/project-management/mdtodo/tasks`、`/v1/project-management/workbench-links` 和 `POST /v1/workbench/launches`。`script` 只允许作为短 API matrix、截图或 observe command 缺口补证；阶段 closeout 不得仅凭 script 通过。 + +项目管理页面应提供稳定 `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、数据库或测试后门。 + +项目管理 analyzer 应输出 `project-management-*`、`mdtodo-*` 和 `workbench-launch-*` 前缀 findings，避免在非 Workbench 页面误报 Workbench session/trace 专属 finding。 + +### 6.8 CLIENT-PM-REQ-008 YAML-first 运行配置 + +| 编号 | 短名 | 主责模块 | 关联模块 | +| --- | --- | --- | --- | +| CLIENT-PM-REQ-008 | YAML运行配置 | PJ2026-01040408 YAML-first 运行配置 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[平台运维](PJ2026-0106-platform-ops.md) | + +`hwlab-project-management` 的运行面配置必须走 YAML-first。D601/v03 部署应在 node/lane YAML 中声明 serviceId、namespace、image/source truth、Service/Deployment、DB migration/read model、Secret sourceRef、targetKey、OTel `service.name`、health/readiness、NetworkPolicy、Cloud API route/proxy 和 public exposure 关联。 + +项目管理 web-probe target、readiness selector、自然请求 path group、DOM redaction allowlist、project command allowlist、loading/API 阈值和 slow path budget 也必须由受控 YAML 配置进入运行面，不得写在 probe 脚本、Cloud Web、项目管理服务或一次性 shell 中作为隐藏默认。 + +Secret、DB DSN、provider token、session token、API key、host path 和 raw Markdown 内容不得出现在默认 CLI 输出、probe 报告、日志或错误 envelope 中。输出只披露对象名、key 名、sourceRef、presence、fingerprint、hash、字节数和 `valuesRedacted=true` 摘要。 + +## 7. 过程控制 + +本规格的阶段活动由架构治理 issue [#2123](https://github.com/pikasTech/HWLAB/issues/2123) 拆分跟踪： + +| 阶段 | 跟踪 issue | 完成口径 | +| --- | --- | --- | +| P0 SPEC 先行 | [#2133](https://github.com/pikasTech/HWLAB/issues/2133) | 本规格与客户端/Web/API 交叉引用合并到 UniDesk master。 | +| P1 独立项目管理微服务 | [#2134](https://github.com/pikasTech/HWLAB/issues/2134) | D601/v03 有独立 `hwlab-project-management` 服务、API、DB 投影和 health/readiness。 | +| P2 项目根导航与 MDTODO 页面 | [#2135](https://github.com/pikasTech/HWLAB/issues/2135) | `/projects` 与 `/projects/mdtodo` 可通过同源 API 展示项目、source、file、task 和 blocker。 | +| 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 验收。 | + +P0 SPEC 完成前不得进入项目管理代码实现。每个阶段独立 PR 跟踪；PR 合并后必须把 PR、commit、observe/analyze 报告或原入口证据回写到对应阶段 issue 和 [#2123](https://github.com/pikasTech/HWLAB/issues/2123)。