diff --git a/.agents/skills/unidesk-tasktree/SKILL.md b/.agents/skills/unidesk-tasktree/SKILL.md index a1057c90..6cad228b 100644 --- a/.agents/skills/unidesk-tasktree/SKILL.md +++ b/.agents/skills/unidesk-tasktree/SKILL.md @@ -5,6 +5,8 @@ description: HWLAB v0.3 TaskTree 开发与运维技能,覆盖 native PostgreSQ # UniDesk TaskTree +本技能遵循 Skill(cli-spec)。 + ## 核心合同 - TaskTree 源码位于 HWLAB v0.3: @@ -12,7 +14,8 @@ description: HWLAB v0.3 TaskTree 开发与运维技能,覆盖 native PostgreSQ - `cmd/hwlab-tasktree-worker/main.ts` 与 `cmd/hwlab-tasktree-api/main.ts` 是独立入口; - `tools/src/tasktree-cli.ts` 只选择 transport,不复制业务逻辑; - `web/hwlab-cloud-web/src/views/projects/TaskTreeView.vue` 提供甘特图。 -- TaskGroup、Task、Subtask 分别对应 MDTODO FILE、ITEM、SUBITEM。 +- TaskGroup 对应 MDTODO FILE。 +- Task、Subtask、Subsubtask 对应 MDTODO 的三级任务层级。 - Milestone 表达时间节点,ExecutionReport 归属 Task 或 Subtask。 - PostgreSQL 唯一真相来自 UniDesk `config/platform-db/postgres-nc01.yaml`。 - TaskTree 运行配置来自 UniDesk `config/hwlab-tasktree.yaml`。 @@ -34,6 +37,10 @@ description: HWLAB v0.3 TaskTree 开发与运维技能,覆盖 native PostgreSQ ## Native-first 开发 +- 开发等级遵循 `$unidesk-devlevel`: + - 解析器、导入和 dispatcher 领域逻辑使用 L0; + - HTTP、Temporal worker、PostgreSQL 和 HMR Web 联调使用 L1; + - L1 收口前不得用 L2/L3 CI/CD 滚动代替本地反馈循环。 1. 确认共享 Temporal 与 native PostgreSQL 已 ready,并动态解析 Temporal 地址。 2. 只启动 worker: @@ -66,8 +73,15 @@ HWLAB_TASKTREE_API_URL=http://127.0.0.1:6673 \ ``` - `--overapi` 只能切换 transport;命令、参数、DTO、输出 envelope 和错误语义必须保持一致。 -7. API 合同通过后,独立启动 HWLAB Cloud Web 的 Vite HMR 开发服务: - - 前端代理指向 native API; +7. API 合同通过后,启动 TaskTree standalone Vite HMR 开发服务: + - 只挂载 `TaskTreeView`、最小 Router 和 Pinia; + - 只把 `/v1/tasktree` 代理到 native API; + - TaskTree API 模块必须通过 `@/api/client` 导入 `fetchJson`: + - standalone Vite 将该入口替换为轻量 adapter; + - 禁止使用绕过 alias 的相对 `./client`,否则会加载全量 RUM 并产生非 TaskTree 请求; + - standalone API adapter 禁止触发 `/v1/web-performance` 等非 TaskTree 请求; + - 禁止加载 Cloud Web `App.vue`、完整 router、认证 guard、Workbench 和其他 HWLAB 服务入口; + - 浏览器出现 HWLAB 登录页、全量导航或非 TaskTree API 请求时,判定微服务 native 前端启动不合格; - 使用 `$unidesk-webdev` 的 custom/local `web-probe` 入口完成多视口和交互验收; - 修改前端时复用现有 HMR 与 API 进程,不触发镜像构建或 Kubernetes rollout。 8. Native worker、CLI、API 和 HMR 前端全部收口后,才进入自动 CI/CD。 @@ -79,7 +93,7 @@ HWLAB_TASKTREE_API_URL=http://127.0.0.1:6673 \ ```text tasktree health -tasktree group list|get|create|delete +tasktree group list|overview|get|create|delete tasktree task create|update|delete tasktree milestone create tasktree report create @@ -88,15 +102,27 @@ tasktree timeline tasktree workflow start ``` -- 子任务通过 `task create --parent ` 建立。 +- 子任务通过 `task create --parent ` 建立: + - Task 的子级是 Subtask; + - Subtask 的子级是 Subsubtask; + - Subsubtask 禁止继续创建下级。 - 报告正文优先使用 `--body-file`,避免把多行内容放入 shell 参数。 - MDTODO 导入规则: - MDTODO FILE 映射为 TaskGroup; - 顶层 R 项映射为 Task; - - 更深 R 项映射为对应顶层 Task 的 Subtask,并保留完整 R 编号; - - 三级及更深层级因 TaskTree 两级合同而压平,结果必须返回 `nested_task_flattened` warning; + - `R2.9` 映射为 `R2` 的 Subtask; + - `R2.9.1` 映射为 `R2.9` 的 Subsubtask; + - 第四级及更深层级压平到受支持的第三级,并返回 `nested_task_flattened` warning; + - 标题内容不得按冒号截断: + - Markdown 链接中的 `https:` 必须完整保留; + - URL 后面的标题正文也必须完整保留; - 正文中的本地 `任务报告` / `Task_Report` Markdown 链接自动读取并导入 ExecutionReport; - 报告文件缺失时保留任务并返回 `report_file_missing` warning; + - CLI 在调用端读取 MDTODO 与报告文件的最后修改时间,并通过同一 import DTO 传给本地 dispatcher 或 API; + - 缺少显式任务时间时,以 MDTODO 文件最后修改时间作为截止时间,开始时间为其前一天; + - 任务存在报告时,以最新报告文件的最后修改时间替代 MDTODO 文件时间; + - 父任务最终取自身与全部子任务时间区间的并集,必须覆盖最早子任务开始和最晚子任务截止; + - 导入报告的 `createdAt` 使用报告文件最后修改时间; - 导入前先使用 `--dry-run` 核对 task、subtask、report、missing 和 flattened 计数; - 实际导入必须在单个 PostgreSQL 事务内完成。 - `--overapi` 导入时: @@ -147,9 +173,36 @@ bun scripts/cli.ts web-probe console-verify \ - group 深链刷新恢复; - 详情弹框边界; - execution report 使用安全 Markdown Viewer,并支持长报告内部滚动; - - 未设置时间的任务不得伪造甘特条; + - 普通任务未设置时间时不得伪造甘特条,MDTODO 导入任务按上述文件时间规则回填; - 大型 MDTODO 导入后的长标题、深层压平、折叠和纵向滚动; - - 无 `pageerror`。 + - `/projects/tasktree` 默认显示全局 TaskGroup 甘特视图; + - 全局概览由 PostgreSQL 单次聚合 API 提供,禁止前端逐组请求 timeline; + - TaskGroup 使用比任务更粗的时间条,点击标题或时间条进入 `/projects/tasktree/:groupId`; + - 详情页支持 Task、Subtask、Subsubtask 三级缩进和逐级折叠; + - 单个父任务的可见后代超过 8 行时: + - 左侧标题与右侧时间条分别使用同步的组内滚动视窗; + - 初次加载和重新展开默认滚动到底部; + - 视窗使用下沉阴影、滚动边缘提示和细窄滚动条; + - 左侧任务栏桌面默认按视口比例计算,并继续支持拖拽调整; + - 标题必须先占满可用单行宽度,再使用省略号; + - 标题中的 Markdown 链接使用成熟 Markdown 渲染器显示为链接,不显示裸语法; + - 时间刻度和画布宽度至少填满右侧可用区域,放大后才横向滚动; + - 任务说明和执行报告共用一个 Markdown 阅读面板: + - 工具栏保持紧凑单行; + - 超长正文只能在阅读面板内部滚动; + - 前后任务导航、时间和状态共用底部窄状态栏; + - 任务详情使用可切换的双模式: + - 弹窗模式高度约占视口 90%,底部保留窄状态栏; + - 吸附模式形成左侧任务大纲、中间甘特图、右侧任务详情的 bounded 三栏布局; + - 两种模式都提供上一个、下一个任务和父节点、当前节点、子节点导航; + - 弹窗提供“吸附右侧”按钮,吸附栏提供“切换到弹窗”和关闭按钮; + - 详情深链使用 `task=` 恢复选中任务: + - `detail=docked` 恢复右侧吸附模式; + - 刷新后必须保持任务和详情模式; + - 关闭详情时清理两个 query 字段; + - 三栏模式必须保持 workspace 与详情栏等高、各栏内部滚动且 document 无横向或纵向溢出; + - 窄详情栏中的 Markdown 链接、行内代码和长单词必须在阅读面板内换行; + - console 不得出现错误,`pageerror`、失败请求和失败响应必须为零。 - 临时 ID 只作为 smoke 证据,不得写入 owning YAML 或长期 skill。 ## 配合技能