@stephen1620/dsh-tomato-board 0.3.2 → 0.3.4

package/README.md

@@ -1,6 +1,15 @@
 # DSH 番茄工作台
 
-为 DeepSeek Harness Web 提供 Gitee Team（番茄）工作台和原生对话联动。
+页签顺序：事项看板、任务日历、PR 助手、团队管理。PR 助手已内置，原独立插件不再需要，功能和配置见 [PR 助手说明](./PR_ASSISTANT.md)。
+
+为 DeepSeek Harness Web 和 DSH Desktop 提供 Gitee Team（番茄）工作台与原生对话联动。
+
+| 页签 | 主要功能 |
+| --- | --- |
+| 事项看板 | 按负责人查看事项，搜索标题、编号或类型，关联 Harness 对话 |
+| 任务日历 | 本地需求排期，查询 Task / 跟踪任务，分配工时、改期、关联 Bug 和一键报工 |
+| PR 助手 | 仓库与 PR 查看、代码评审及相关操作，详见独立说明 |
+| 团队管理 | 按迭代查看需求故事点与 Task 计划投入，管理本地团队和成员 |
 
 ## 快速安装（推荐）
 
@@ -26,6 +35,24 @@ npx @deepseek-ai/dsh plugin --profile desktop add .
 
 安装前请先确认必备的 Gitee CLI 已配置完成，具体要求见下方“必备环境”。
 
+## 0.3.4 更新
+
+- PR 助手合并为第三个页签，原「迭代投入」调整为「团队管理」。访问过的任务日历、PR 助手和团队管理在切换页签时保留界面状态。
+- 日历与一键报工同时支持 Task 和跟踪任务。事项看板与日历共用类型配色：Story 青绿色、Task 紫色、跟踪任务玫紫色，图例与拖拽高亮同步区分。
+- 需求排期直接读取本地文件，不等待番茄接口；打开分配弹窗时只核对当前需求的 Task，保存与创建时再次核对。旧创建日志不作为服务器 Task 或剩余容量的依据。
+- 支持搜索其他负责人名下的需求；新 Task 始终归当前登录用户，父需求负责人不变。
+- 新 Task 自动填写计划起止日期、预估人天，并动态继承父需求当时的迭代；迭代按 ID 字符串数组写入，创建后回读校验。
+- 同一需求可以有多个时间段，连续或重叠的时间段自动合并。扩长排期后可按剩余容量继续分配，最小单位为 0.5 人天。
+- 需求以单个时间段为单位拖动或调整左右边缘，不联动 Task；删除时间段仅移除本地排期。Task 改期和删除同步到番茄，删除进入回收站。
+- 新增每周一键报工：按每天容量建议人天，写入实际工时并遵循实时工作流流转；全部成功后自动关闭弹窗。
+- Task 详情支持番茄原生 Bug 关联，优先展示父需求实现层级下的缺陷；日历卡片以红色数字显示已关联 Bug 数量。
+- 日历按周独立纵向滚动，拖拽高亮整个日期范围并支持跨周。弹窗关闭仅关闭当前弹窗，保留工作台。
+
+## 0.3.3 更新
+
+- 团队管理中，展开团队的成员始终参与加载，切换迭代后不再停留在“读取中”。
+- 首次进入先确认有效迭代，切换迭代或刷新时重新读取成员数据，避免复用上一迭代的结果。
+
 ## 0.3.2 更新
 
 - 使用 Harness `main` 主内容区展示工作台，保留左侧栏，关闭后返回原对话。
@@ -33,30 +60,83 @@ npx @deepseek-ai/dsh plugin --profile desktop add .
 
 ## 界面兼容性
 
-工作台注册到 Harness 的 `main` 主内容区，打开时替换对话页并保留左侧会话栏，关闭后返回原对话。需要支持 `main` keyed slot 和 `ctx.layout.selectPanel` 的 Harness 版本；已在 DSH Desktop 2.0.13 验证。构建时也需要对应版本的 Harness 源码与类型声明。
+工作台注册到 Harness 的 `main` 主内容区，打开时替换对话页并保留左侧会话栏，关闭后返回原对话。点击侧栏对话（含当前对话和搜索结果）或切换、新建对话时自动返回对话页；点击侧栏空白、展开项目和打开菜单时保留工作台。需要支持 `main` keyed slot 和 `ctx.layout.selectPanel` 的 Harness 版本；已在 DSH Desktop 2.0.13 验证。构建时也需要对应版本的 Harness 源码与类型声明。
+
+客户端仅以类型导入 `SessionId`，不依赖浏览器提供 `@deepseek-ai/dsh-session/types` 运行时模块，避免构建工具将其外置后导致插件加载失败。
 
 ## 功能
 
 ### 事项看板
 
 - 在 Harness 侧栏或对话顶部栏打开番茄工作台，按状态展示事项。
-- 支持标题、编号、创建人搜索，以及负责人、空间、类型和状态筛选。
+- 支持标题、编号、类型和创建人搜索，以及负责人、空间、类型和状态筛选；输入「跟踪任务」可筛出该类型。查询不限定事项类型，仍受当前负责人、配置的 IQL 和状态过滤影响。
 - 支持拖动状态列调整顺序、手动置灰卡片；偏好保存在当前浏览器。
+- 每条泳道内的卡片按创建时间倒序排列，最新创建的卡片显示在最上方。
 - 点击卡片优先打开已关联对话；未关联时选择 Harness 项目并创建对话。
 - 卡片上的独立外链按钮可直接打开番茄事项。
 - 对话顶部栏支持查询状态和执行流转；“待测试”因必填字段失败时，可交给当前 AI 对话继续处理。
 
-### 迭代投入
+事项看板按负责人将最近一次成功读取的列表缓存在当前浏览器 localStorage。刷新页面或重新打开时优先展示缓存，并后台读取最新数据；读取失败保留已有卡片并显示错误。成功返回空列表也会覆盖旧缓存。切换负责人会切换对应缓存并取消旧请求，避免不同负责人的返回结果串用。第一次使用或缓存不可用时仍需完成一次服务器读取。
+
+### 任务日历（工时管理）
+
+工作台的「任务日历」页签显示以本周为中心、前后各两周的日历，周六、周日作为每周的前两列。点击某一天，或按住鼠标划选连续几天，松开指针后立刻弹出「选择需求」下拉框，选定后直接进入该需求的工时分配；不需要先选需求，也不再提供左侧需求池和拖拽。一个连续日期范围保存为一个时间段，同一需求可以有多个时间段。
+
+工时分配按需求聚合：同一需求的所有时间段合并为一个计划，点击任意时间段的卡片打开的都是同一个弹窗，人天合计按全部日期去重计算，且不能超过总天数（可以少于，剩余时间保持未分配）。阶段按需求与项目理解、方案设计、功能开发、联调与验证、Bug 修复填写人天，每个阶段至少 0.5 人天并按 0.5 递增；留空或填 0 的阶段视为不分配，直接跳过。番茄需求不提供删除操作；本地时间段可删除；未被 Task 锁定的时间段可以改期或新增，已创建 Task 覆盖的时间段锁定；新增时间段仍可分批创建。每个已分配阶段创建一个直属 Task。标题由需求主题和阶段动作生成，可在确认前修改；阶段输入仅在弹窗中保留，保存时间段不会保存阶段草稿。所属项目和迭代从需求实时读取，迭代为空则不填；新 Task 负责人为当前登录用户，团队和工时成本归属参考需求或同项目近期任务的一致取值，缺失时必须手动选择；API 不假设网页的字段联动会执行。分类仅允许软件开发和修复 BUG 对应的当前选项。
+
+创建 Task 时统一填写计划日期与预估工作量，并同时将实际工作量、实际开始与完成日期填写为与计划一致；服务器按实时字段约束校验，计划字段及必填字段超范围时拒绝提交；可选的实际工时字段超范围时整组跳过，并展示跳过记录。阶段按该需求全部日期的先后顺序安排，每天容量为 1 人天，0.5 人天的阶段可以与其他阶段共享同一天。周末仅作视觉区分，不自动排除。
+
+历史安排和每个 Task 的创建结果保存到 `$DSH_HOME/tomato-worktime/<配置范围摘要>.json`（未设置 DSH_HOME 时使用 `~/.dsh`）。可在插件配置中设置 `worktimeDataFile` 更换路径。文件按 profile、番茄域名和租户隔离，原子替换并串行写入；刷新、翻周和重启均不清除。显示区间内所选负责人的番茄 Task 和跟踪任务独立读取，包含已完成事项，不继承看板状态过滤；再回读详情核实当前负责人和日期，避免搜索索引旧数据影响日历。需求排期直接读本地，不等待这些请求。
+
+创建前保存操作记录，逐个创建并回读核对父故事、标题、项目、迭代、负责人、分类、人天和日期。失败时停止并保留已成功、未开始、结果待核对的记录；未知结果不自动重试；下次明确创建时重新查询番茄，旧提交日志独立保留且不再作为创建拦截条件。新增分配仅扣除接口确认仍存在且由当前用户负责的直属 Task 的计划人天；远端删除或转交的 Task 不再占用本人的剩余容量，支持 0.5 人天续分配。进程异常退出遗留的 `.lock` 文件需先核对创建结果并确认无其他工作台写入，再人工解除；本版本不自动恢复未知写入。
+
+插件的服务端路由在 DSH 进程启动时注册，前端 bundle 则随页面刷新：重新构建后必须完全退出并重新打开 DSH（仅刷新页面只更新界面），否则创建 Task 会提示“工时服务仍是旧版本”。
+
+桌面进程 PATH 缺少用户目录时，插件会查找 `~/.local/bin/gitee`、`~/go/bin/gitee` 和常用安装目录；也可在配置 `executable` 中指定绝对路径。无法定位时返回具体配置提示。
+
+#### Task / 跟踪任务删除与拖拽改期
+
+以下日期同步、删除和 Bug 关联操作均适用于 Task 与跟踪任务；工时分配新建的事项仍为 Task。
+
+时间段列表提供“删除”，保存后仅移除本地排期，不调用番茄需求或 Task 的删除接口，最后一个时间段也可移除。带有 Task 的时间段转存为本地历史，保留创建与待核对记录；原 Task 仍按番茄计划日期显示，后续改期或回收也会同步更新历史记录。点击 Task 打开详情，可修改计划起止日期或确认移入番茄回收站；删除 Task 可能连同其后代一起回收，确认界面会明确提示。需求安排和其他 Task 保留。
+
+当前登录用户可将 Task 时间条拖到目标日期，按拖动天数平移计划起止日期并保留时长；拖住跨周 Task 的中间日期时以实际抓取日期为基准。Task 可以移到需求原时间段之外，日历仍会展示。需求时间条也可以拖动：以当前时间段为单位，仅移动该段；同需求的其他时间段及所有 Task 保持原位。需求和 Task 的左右边缘均提供拖拽手柄，可调整开始、结束日期；需求边缘只调整需求时间段，Task 日期保持不变。改期仅更新计划日期，实际日期与人天保持不变。其他负责人的日历只读。
 
-- 顶部栏对齐 Harness 对话页样式；顶部 Tab 切换「事项看板 / 迭代投入」，迭代选择器支持切换迭代并记住上次选择。
-- 左侧切换负责人，展示故事点总数、环形分布图和需求列表。
-- 需求卡片与事项看板共用对话关联逻辑，点击打开已有对话或选择项目创建新对话；独立的 ↗ 按钮跳转番茄。
-- 右侧团队以折叠卡片管理：创建、改名、删除团队，添加或移除成员，成员行以背景比例条展示故事点。
-- 点击排行榜成员可切换左侧负责人；第一个团队默认展开并加载，其他团队按展开需要加载。
-- 点击团队成员行可切换左侧负责人；第一个团队默认展开并加载，其他团队按展开需要加载。
-- 团队、成员及负责人选择保存在当前浏览器，不同步到番茄或其他设备。
+拖动或调整需求时间段后，同一需求连续或重叠的时间段自动合并，跨周同样生效。合并保留所有 Task 的日期、创建结果与待核对记录，不更新番茄 Task。
 
-统计读取卡片的 `StoryPoint` 字段，仅包含所选迭代中的 `Story`、`EnablerStory` 和 `Task`，包含全部状态。未填写故事点的需求保留在列表，不参与总数和饼图；0 点保留为已估点记录，不占饼图面积。多负责人需求分别计入各负责人。需要调整故事点时，使用外链按钮进入番茄修改，然后刷新统计。
+Task 弹窗提供计划日期、删除和关联 Bug。关联区域显示 Bug 的最新状态，优先从父需求的实现层级（后代缺陷）提供候选，并支持按标题或编号搜索其他缺陷。选择后通过番茄原生 `Relations` 字段关联，先显示结果，再后台提交；失败时撤回预显示并提示核对。当前 osc/xly-poc 使用其原生 Relates 类型；其他租户通过 `bugLinkTypeId` 和 `bugLinkNames`（该类型的 inward/outward 文案）配置关联类型。关系不在本地另存。
+
+日历 Task 右侧用红色数字显示已关联 Bug 的数量（包括已关闭的 Bug，未关联时不显示）。数量独立后台读取，每批最多并行查询 3 个 Task，使用 30 秒内存缓存；只统计实际关联，不计父需求候选。弹窗关联与回退会立即同步红标，旧的后台结果不会覆盖新数量；其他负责人的 Task 同样支持查看。
+
+服务端写入前校验事项类型、当前负责人和原日期；改期后回读验证。同步结果未知时保留操作日志并拒绝重复写入，需要先在番茄核对。重建前端后刷新加载，新增 Task 同步、Bug 关联接口需要重启 DSH。
+
+日历最大宽度 1280px、高度 640px，使用 `margin: auto` 居中，工具栏与日历等宽对齐，小窗口自动缩小。拖动、调整边缘和删除会先更新日历显示，再后台同步；同步期间保留日历内容，旧读取结果不会覆盖预显示。失败时撤回预显示并提示原因。需求拖动仅保存当前时间段的本地日期，不调用番茄 Task 更新接口。
+
+拖动时间条或其边缘时，会高亮整个预览日期范围，并在日历上方显示起止日期；范围可跨周，仅高亮本次拖动的时间段。整周内所有日期格子（包括时间条覆盖的位置）都能接收拖放，松开时按实际预览日期保存。左右手柄使用 14px 触发区，起止边界不会互相越过。
+
+每周是独立的纵向滚动区域：卡片按泳道撑开周内容，超出周高度时可滚动查看全部卡片，日期数字保持在该周顶部。周标题和日期列预留相同滚动条空间，拖放按周内容区域识别日期，跨周高亮继续保留。
+
+已分配的时间段扩长后可以再次分配。弹窗展示剩余可分配人天，提交时保留旧 Task 并追加新 Task；日期按剩余的半天位置安排，不会重复占用旧 Task 的日期。新记录保存半天占用日期，旧记录在修改排期前补齐，以保留跨周和多时间段之间的空档。
+
+### 添加其他负责人的需求
+
+在任务日历选择日期后，弹窗默认保留“我的需求”，也可按完整需求编号或标题关键词搜索当前账号有权限访问的 Story / EnablerStory，不限制需求负责人。搜索结果展示编号、状态和负责人，最多显示前 20 条。选中后可照常安排时间段、分配工时；新 Task 归当前登录用户，父需求负责人保持不变，项目和其他业务字段仍沿用需求。
+
+### 一键报工
+
+任务日历右上角可打开每周报工，默认当前周（周一到周日），展示计划日期与该周相交的、当前登录用户负责的 Task 和跟踪任务，以及计划人天和已报实际人天。每天一个已选 Task 建议 1 人天，两个各 0.5 人天，跨天累加；超过两个会提示调整选择或排期，最小单位为 0.5 人天。可修改实际日期和工时，提交会覆盖该 Task 的整项实际工时，跨周 Task 需明确勾选并核对总数。
+
+报工由固定程序调用番茄接口执行，不使用 LLM。提交后按每个 Task 当前可用工作流推进到「进行中」，再到「工时核对中」或可用的「已完成」分支，停在核对阶段，不自动执行核对完成。每一步回读状态，已核对中/已完成的 Task 跳过；负责人、日期或工时发生变化时要求刷新。全部成功或跳过时自动关闭弹窗并提示；部分失败时保留逐项结果，未知写入结果不自动重试。实际完成日期遵守番茄字段的允许范围。
+
+### 团队管理
+
+- 选择迭代和负责人，分别查看需求故事点（SP）与 Task 计划人天，可切换分布图和成员排名的指标，两种单位不相加。
+- 需求统计 `Story` / `EnablerStory` 的 `StoryPoint`：有有效计划日期时按迭代日期窗口相交纳入；无计划日期时按迭代归属纳入。未估点的需求仍显示，0 点视为已估点。
+- Task 统计 `planStoryPoint`，按计划日期是否与迭代窗口相交纳入，不要求绑定迭代；跨迭代 Task 按重叠日历天数比例折算。此处目前统计 Task，不包含跟踪任务。
+- 统计包含全部状态，不继承事项看板的状态过滤。多负责人事项分别计入各负责人。
+- 右侧可创建、改名、删除本地团队，添加或移除成员；展开团队后加载成员统计，点击成员切换左侧负责人。
+- 点击事项可打开关联对话或创建对话；独立外链按钮跳转番茄。修改故事点请在番茄中操作，然后刷新。
+- 团队、成员和选择偏好保存在当前浏览器，不同步到番茄或其他设备。成功读取的统计支持浏览器缓存，切换页签保留已有内容。
 
 ## 0.3.1 更新
 
@@ -68,7 +148,7 @@ npx @deepseek-ai/dsh plugin --profile desktop add .
 
 ## 0.2.0 更新
 
-新增「迭代投入」页面、多个团队管理和个人故事点分布；需求卡片支持打开 Harness 对话及独立跳转番茄；完善顶部栏、看板筛选与状态列排序。
+新增「团队管理」页面、多个团队管理和个人故事点分布；需求卡片支持打开 Harness 对话及独立跳转番茄；完善顶部栏、看板筛选与状态列排序。
 
 ## 必备环境
 
@@ -96,11 +176,13 @@ command -v gitee
 
 ## 安装
 
-当前版本：`0.3.2`。已安装用户在对应 profile 目录升级：
+仓库当前版本：`0.3.4`。GitHub 代码与 npm 发布独立；如需使用本 README 描述的最新仓库实现，请优先从 GitHub 或本地目录安装。
+
+通过 npm 安装的用户，可在对应 profile 目录升级到 npm 已发布的最新版本：
 
 ```bash
 cd ~/.dsh/profiles/desktop # Web 用户改为 web
-pnpm add @stephen1620/dsh-tomato-board@0.3.2
+pnpm add @stephen1620/dsh-tomato-board@latest
 ```
 
 保留已有 `dsh.profile.bundles` 注册项，升级后完全退出并重新打开 Harness。
@@ -154,7 +236,7 @@ npx @deepseek-ai/dsh plugin --profile web remove @stephen1620/dsh-tomato-board
 | --- | --- | --- |
 | `executable` | `gitee` | Gitee CLI 可执行文件名或绝对路径 |
 | `profile` | `osc` | Gitee CLI profile |
-| `iql` | 空字符串 | 看板附加查询条件，负责人由界面选择；不影响迭代投入统计 |
+| `iql` | 空字符串 | 看板附加查询条件，负责人由界面选择；不影响团队管理统计 |
 | `tomatoOrigin` | `https://osc.gitee.work` | 番茄站点地址 |
 | `tomatoTenant` | `xly-poc` | 番茄租户 |
 | `cacheTtlMs` | `15000` | 事项查询缓存时间（毫秒，最大 300000） |
@@ -170,25 +252,19 @@ npx @deepseek-ai/dsh --profile web --dump-config
 
 ## 开发与构建
 
-该插件依赖 Harness 尚未独立发布的 workspace 包，因此源码构建需要放在 Harness monorepo 中进行。不要使用目录软链；Harness 的插件发现不会遍历该软链。
+在本仓库直接构建，源码与 `lib/` 产物均留在 `plugins/tomato-board`，无需复制到 Harness：
+
+```bash
+npm run build:tomato-board
+```
+
+构建工具仍使用已安装依赖的 Harness checkout，默认查找本仓库同级的 `deepseek-harness`。其他位置可显式指定：
 
 ```bash
-git clone https://github.com/deepseek-ai/deepseek-harness.git
-cd deepseek-harness
-pnpm install
-
-rsync -a --delete \
-  --exclude .git \
-  --exclude node_modules \
-  --exclude lib \
-  /absolute/path/to/dsh-plugins/plugins/tomato-board/ \
-  packages/client/tomato-board/
-
-pnpm exec tsc -b packages/client/tomato-board
-pnpm --dir packages/client/tomato-board bundle
+DSH_HARNESS_ROOT=/absolute/path/to/deepseek-harness npm run build:tomato-board
 ```
 
-构建完成后，把 `packages/client/tomato-board/lib/` 同步回本仓库。`lib` 会提交到 Git，确保 GitHub 安装不依赖用户本地具备 Harness 源码构建环境。
+本机 desktop、web profile 的 `node_modules/@stephen1620/dsh-tomato-board` 软链直接指向本仓库 `plugins/tomato-board`。前端构建后刷新页面加载；服务端改动需要重启 DSH。构建期间应用可能读到正在更新的产物，构建成功后再刷新。`lib` 提交到 Git，安装已发布的包不需要本地构建环境。
 
 ## 发布