dsh-group-status 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 ## 未发布
 
+- **feat** 多层聚合：父分组折叠时，徽标聚合所有后代分组的会话状态，不再只看直接成员。嵌套的 workspace 目录结构现在能正确反映整棵子树的活动。
+- **fix** 上面这条「多层聚合」交付时是坏的：折叠的父文件夹会**漏算处于展开状态的中间层文件夹**的会话。`directStatusesForGroups` 沿用了「展开即 `EMPTY_LIVE_STATUS`」的占位写法，而聚合器把这个值当输入消费，于是展开的中间层对祖先贡献 0。现在展开的分组同样被测量，「不画徽标」退回渲染层决定。实测：dsh-group-status 展开且 1 个运行中、dsh-gitea-dispatch 1、dsh-later 3 时，dsh-plugins 的折叠徽标由 `4` 修正为 `5`。
+- **fix** 折叠文件夹时完全没有淡出动画。`AnimatedRows` 的 `resetKey` 混入了 `sessionLimits`，而上游在折叠时会把该组的 limit 重置回默认值 → `resetKey` 变化 → 动画被整个跳过。属上游行为（vendor 基线 `d70ad82`），非本仓库引入。副作用：「展开其余 N 个会话」现在也会淡入而非瞬时呈现。
+- **test** 徽标管线的测试此前是**自欺**的：`groupOf()` 在测试里手工赋值 `group.liveStatus`，而那份手工副本编码的正是上面第一个错误语义——所以少算 bug 能一路绿灯合入。改为走真实管线 `deriveGroups → directStatusesForGroups → aggregateGroupStatuses`，并给聚合路径补上全折叠 / 全展开两侧的 perf 护栏。变异验证：把 bug 塞回去，红 6 个测试（此前 0 个）。
+- **refactor** 未经聚合的行现在在类型上不可表示：`StatusedGroupNode`（`liveStatus` 必填）+ `withAggregatedStatus` 生产者。上游的 `GroupNode.liveStatus?` 与 vendored 文件的签名均未改动。
+- **refactor** 删掉 `tree.ts` 里无人使用的 re-export（两个值只有测试在用，4 个跨插件 summary 类型零消费方）。`tree.ts` 相对上游基线的新增分歧 31 → 18 行。
+- **docs** 修正 README 的徽标数字公式：漏了「运行中的子智能体」一项，且「有徽标就带数字」与 `countThreshold` 默认值 2 自相矛盾。
+- **perf** 代价说明：为正确性放弃了「展开的分组跳过聚合计算」这一优化，展开分组现在也会被测量（折叠祖先需要它的数字）。该成本由新增的 perf 用例守住。
+- **feat** 设置项从 1 个扩展到 7 个：5 个按状态显隐（进行中 / 待审批 / 已完成 / 定时任务 / 等待评审）+ 悬停明细开关 + 数字显示阈值。设置卡片分 3 个 section，每个开关独立控制对应来源的点/图标是否出现在折叠徽标、悬停明细与计数中。
+- **feat** 数字显示阈值（`countThreshold`）：取代原来的布尔开关 `alwaysShowCount`。现在可以设置一个数字阈值，只有当聚合数量 >= 该阈值时才在徽标上显示数字。默认 2（即 count=1 时省略，因为状态点已表达"有东西"）；设为 1 则始终显示；设为 3 则 count=1 和 count=2 时都不显示。
+- **fix** 设置项 `showCompletedInBadge` 在 GUI 里根本没有入口：宿主只把 `Config` 投影成客户端表单，插件页要插件自己往 `plugins.bundle.config` 注册卡片才画得出来。现在侧栏 **插件** → dsh-group-status 的 bundle 详情页有这张卡片，保存后写进 profile patch 并即时生效。外观与交互不自造——用官方 `SettingsForm` / `SettingsFormModel` / `Switch`，与「插件 → 官方 → 子智能体」同一套框架与取值。README 此前描述的路径是文档超前于实现，文案与升级手册已同步。
+- **test** 新增字段规格（真实现）与卡片接线（官方组件契约等价桩）用例。
+
 ## 0.2.0-rc.2-fork1
 
 - **feat** 折叠分组聚合徽标：收起的文件夹行显示进行中（转圈）、待审批（黄点）、已完成（绿点）的聚合状态，带数字与悬停明细。

package/README.en.md

@@ -6,7 +6,7 @@
 
 [中文](./README.md) | **English**
 
-[![version](https://img.shields.io/badge/version-0.2.0--rc.2--fork1-0EA5E9)](https://github.com/WuJiaoJue/dsh-group-status)
+[![version](https://img.shields.io/badge/version-0.2.0-0EA5E9)](https://github.com/dsh-plugin-collection/dsh-group-status)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![DSH](https://img.shields.io/badge/DeepSeek%20Harness-0.2.0--rc.2-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
 
@@ -49,31 +49,37 @@ Fold any group that has live sessions; a badge appears after the folder name:
 Rules:
 
 - **Completed reaches the badge**: `done` (completed-unread) now shows a green dot while folded, reusing the same `StateDot` state as the session row; a group with nothing but completed sessions shows a badge just like any other.
-- **The count** = approvals + running + completed + sessions with scheduled tasks + sessions waiting for review. Whenever a badge renders it carries the count, including a single-session `1`.
+- **The count** = approvals + running (**including running subagents**) + completed + sessions with scheduled tasks + sessions waiting for review. Whether the number renders at all is gated by `countThreshold` (default 2 — a lone item shows dots only).
 - **Hover details**: the folder row's hover card appends lines in the order `approval · plan review · answer · running · subagents · waiting review · scheduled tasks · completed`, e.g. `1 Waiting for answer · 1 Running`.
 - **Expanding defers to the rows**: the aggregate badge only renders while collapsed; expanded groups keep their per-row statuses with no duplication.
 - **Accessible**: the badge is `role="img"` with a localized `aria-label` (e.g. `1 Waiting for answer · 1 Running`) and the same text as its `title`.
 
 ### Settings
 
-Settings → Plugins → **dsh-group-status** (the config form on the plugin's page):
+**Plugins** in the sidebar → **dsh-group-status** (the config form on the bundle's page, between its description and the component rows):
 
 | Field | Default | Meaning |
 |---|---|---|
+| `showRunningInBadge` | `true` | Whether the folded badge shows the "running" spinning dot |
+| `showPendingInBadge` | `true` | Whether the folded badge shows the "pending" yellow dot (approval / plan review / waiting for answer) |
 | `showCompletedInBadge` | `true` | Whether the folded badge shows a green "completed" dot |
+| `showScheduledInBadge` | `true` | Whether the folded badge shows the "scheduled" clock icon (data from dsh-later) |
+| `showWaitingReviewInBadge` | `true` | Whether the folded badge shows the "waiting for review" list-pen icon (data from dsh-gitea-dispatch) |
+| `showHoverDetails` | `true` | Whether the hover card shows the aggregated status detail lines |
+| `countThreshold` | `2` | The count is shown on the badge only when the total is >= this value (default 2, i.e. omits the count when it equals 1 — the dots already convey "something is happening"; set to 1 to always show) |
 
-Switching it off takes `done` out of the folded row's aggregate entirely — no green dot, no contribution to the badge count, and it no longer keeps the badge alive, so a group with nothing but completed sessions shows no badge again. **The green dot on a session row itself is unaffected**: that is row-level state, not a folder hint.
+Switching a source off takes it out of the folded row's aggregate entirely — no dot/icon, no contribution to the badge count, no hover detail line, and it no longer keeps the badge alive. **The state dot on a session row itself is unaffected**: that is row-level state, not a folder hint. With `showHoverDetails` off, the hover card shows only the title, path, and creation time.
 
-Changes apply live, with no refresh. When the settings face cannot be read (e.g. the Host serves no settings service), it falls back to the default "show", matching the schema default — failing to read a config is not the user turning it off.
+Saving applies it live, with no refresh; the Host writes it into the profile patch's `dsh-group-status` entry `config`, so it survives a page reload. When the settings face cannot be read (e.g. the Host serves no settings service), it falls back to the default "show", matching the schema default — failing to read a config is not the user turning it off.
 
 ---
 
 ## Feature overview
 
-- **Visible when folded**: the aggregate only exists while collapsed; an expanded sidebar is pixel-identical to stock.
+- **Visible when folded**: the aggregate only exists while collapsed; an expanded sidebar is pixel-identical to stock. Nested groups are supported too — when a parent group is folded, its badge aggregates sessions from all descendant groups.
 - **Same source of truth as rows**: priority, colors and wording all reuse the row derivation and `StateDot`; blank and archived sessions are skipped.
 - **Cross-plugin aggregation** (optional): scheduled tasks from dsh-later, waiting PR reviews from dsh-gitea-dispatch — works fine with neither installed.
-- **Usable with zero config**: sensible defaults out of the box; the one setting, `showCompletedInBadge`, can drop the green "completed" dot from the folded badge.
+- **Usable with zero config**: sensible defaults out of the box; 7 settings let you fine-tune which sources appear in the folded badge, hover details, and count display.
 - **No stock files touched**: not a single file of the published `dsh-client-ui-workspace` is modified; all changes live in this repo's source, and the profile patch is two lines (add this package, disable the stock row).
 - **Localized**: follows the DSH UI language (中文 / English) by reusing the stock locale keys; only `status.waitingReview` and `status.scheduled` are new.
 
@@ -87,7 +93,7 @@ When sessions inside a group have scheduled tasks or wait on a PR review, the ba
 
 | Publisher | Provides | Consumer entry point |
 |---|---|---|
-| [dsh-later](https://github.com/WuJiaoJue/dsh-later) | `useScheduleSummary()`: session id → `{ count, pausedCount, nextAt, state }` | `require('dsh-later/client')` |
+| [dsh-later](https://github.com/dsh-plugin-collection/dsh-later) | `useScheduleSummary()`: session id → `{ count, pausedCount, nextAt, state }` | `require('dsh-later/client')` |
 | dsh-gitea-dispatch | `useWaitingSummary()`: session id → `{ prNumber, state }` | `require('dsh-gitea-dispatch/client')` |
 
 - When either plugin is **absent or disabled, the integration degrades silently**: no icon, everything else keeps working, no errors and no idle polling.
@@ -107,17 +113,24 @@ The working shape is: copy the template into the provider → the provider calls
 
 ### Install into DSH
 
-This package is a **fork override**: it registers the same slots as the stock `dsh-client-ui-workspace` and disables the stock row (patch in `cordis.patch.yml`). Build artifacts are committed, so installing from GitHub needs no local build:
+**npm install (recommended, pre-built, no auth required):**
 
 ```bash
-dsh plugin --profile web add "github:WuJiaoJue/dsh-group-status"
+dsh plugin --profile web add dsh-group-status
 # Takes effect after restarting dsh web (the whole sidebar package is swapped)
 ```
 
+Or install from GitHub:
+
+```bash
+dsh plugin --profile web add "github:dsh-plugin-collection/dsh-group-status"
+# restart dsh web
+```
+
 For local development, link a checkout and rebuild as you edit `src/`:
 
 ```bash
-git clone https://github.com/WuJiaoJue/dsh-group-status.git
+git clone https://github.com/dsh-plugin-collection/dsh-group-status.git
 cd dsh-group-status
 pnpm install && pnpm build
 
@@ -176,7 +189,7 @@ Seven further upstream specs only run inside the DSH monorepo: they either need
 ## Known limitations
 
 - **Upstream bumps need a manual rebase**: the upstream source is vendored (`src/`, `tests/`) and this is not a stable public API; slot names, component signatures and context contracts may shift under it. Steps are in the [upgrade runbook](./docs/upgrading.md).
-- **One extra full traversal while collapsed**: aggregation shares the expanded derivation, so huge groups (hundreds of sessions) cost one extra traverse per status change — same order as expanded rendering, acceptable.
+- **One extra full measurement pass per status change**: aggregation shares the expanded derivation, and to make collapsed parents count correctly **expanded groups get measured too** — they draw no badge themselves, but a collapsed ancestor needs their numbers. Huge groups (hundreds of sessions) cost one extra traverse plus a fold up the tree per status change — same order as expanded rendering, acceptable. A perf spec guards this cost.
 - **It produces no status itself**: the cross-plugin icons depend entirely on the summary APIs published by dsh-later / dsh-gitea-dispatch. Without them you simply lose those two icons.
 - **The count is coarser than the details**: scheduled tasks are counted per *session*, not per task; the exact task count lives in dsh-later's own UI.
 - **Collapsed sidebar only**: this plugin only adds an aggregate display — it does not touch the session state machine or the per-row badge predicates.

package/README.md

@@ -6,7 +6,7 @@
 
 **中文** | [English](./README.en.md)
 
-[![version](https://img.shields.io/badge/version-0.2.0--rc.2--fork1-0EA5E9)](https://github.com/WuJiaoJue/dsh-group-status)
+[![version](https://img.shields.io/badge/version-0.2.0-0EA5E9)](https://github.com/dsh-plugin-collection/dsh-group-status)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![DSH](https://img.shields.io/badge/DeepSeek%20Harness-0.2.0--rc.2-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
 
@@ -49,31 +49,37 @@
 规则：
 
 - **已完成进徽标**：`done`（已完成未读）折叠时也显示绿点，和会话行的绿点同一个 `StateDot` 状态；一组只剩已完成时徽标照常出现。
-- **数字** = 待审批 + 进行中 + 已完成 + 有定时任务的会话 + 等待评审的会话；有徽标就带数字，只有一个会话时也会显示 `1`。
+- **数字** = 待审批 + 进行中（**含运行中的子智能体**）+ 已完成 + 有定时任务的会话 + 等待评审的会话；数字是否出现受 `countThreshold` 控制（默认 2，即只剩 1 项时只画点、不显数字）。
 - **悬停明细**：文件夹行 hover 卡在路径、创建时间下面，按 `等待审批 · 计划待审 · 等待回答 · 进行中 · 子智能体 · 等待评审 · 定时任务 · 已完成` 的顺序追加明细行，例如 `1 等待回答 · 1 进行中`。
 - **展开即让位**：聚合徽标只在折叠时出现；展开后子行自带状态，不重复显示。
 - **无障碍**：徽标是 `role="img"` + 本地化 `aria-label`（如 `1 等待回答 · 1 进行中`），悬停 `title` 同文案，读屏与鼠标都读得到。
 
 ### 设置项
 
-设置 → 插件 → **dsh-group-status**（插件详情页的配置表单）：
+侧栏 **插件** → **dsh-group-status**（bundle 详情页的配置表单，在描述与「包含的组件」之间）：
 
 | 字段 | 默认 | 说明 |
 |---|---|---|
+| `showRunningInBadge` | `true` | 折叠徽标是否显示「进行中」转圈 |
+| `showPendingInBadge` | `true` | 折叠徽标是否显示「待审批 / 待评审 / 待回答」黄点 |
 | `showCompletedInBadge` | `true` | 折叠徽标是否显示「已完成」绿点 |
+| `showScheduledInBadge` | `true` | 折叠徽标是否显示「定时任务」时钟图标（数据来自 dsh-later） |
+| `showWaitingReviewInBadge` | `true` | 折叠徽标是否显示「等待评审」列表笔图标（数据来自 dsh-gitea-dispatch） |
+| `showHoverDetails` | `true` | 悬停卡是否显示聚合状态明细行 |
+| `countThreshold` | `2` | 徽标数字显示阈值：数量 >= 此值时才显示数字（默认 2，即 count=1 时省略——点已表达"有东西在发生"；设为 1 则始终显示） |
 
-关闭后，`done` 完全退出折叠行的聚合提示——不画绿点、不计入徽标数字、不参与「是否显示徽标」的判断，等于回到「一组只剩已完成时不出现徽标」。**会话行自身的绿点不受影响**：那是行级状态，不是分组提示。
+按状态关掉后，对应的来源完全退出折叠行的聚合提示——不画点/图标、不计入徽标数字、不进悬停明细、不参与「是否显示徽标」的判断。**会话行自身的状态点不受影响**：那是行级状态，不是分组提示。`showHoverDetails` 关闭后，悬停卡只显示标题、路径与创建时间。
 
-改动即时生效，无需刷新。设置面读不到时（例如宿主未提供设置服务）回落为默认「显示」，与 schema 默认值同源——读不到配置不等于用户关掉了。
+点「保存」后即时生效，无需刷新；设置由宿主写进 profile patch 的 `dsh-group-status` 条目 `config`，刷新页面后仍在。设置面读不到时（例如宿主未提供设置服务）回落为默认「显示」，与 schema 默认值同源——读不到配置不等于用户关掉了。
 
 ---
 
 ## 特性一览
 
-- **收起可见**：聚合状态只在分组折叠时出现，展开后的侧栏与官方版本逐像素一致。
+- **收起可见**：聚合状态只在分组折叠时出现，展开后的侧栏与官方版本逐像素一致。嵌套分组也支持——父分组折叠时，徽标聚合所有后代分组的会话状态。
 - **与行内同源**：优先级、颜色、文案全部复用行内状态的派生逻辑与 `StateDot`，跳过空白会话与已归档会话。
 - **跨插件聚合**（可选）：dsh-later 的定时任务、dsh-gitea-dispatch 的等待评审，两个都没装也照常工作——见下。
-- **零配置可用**：默认开箱即用；唯一的设置项 `showCompletedInBadge` 可关掉折叠徽标上的「已完成」绿点。
+- **零配置可用**：默认开箱即用；7 个设置项可精细控制折叠徽标的来源显隐、悬停明细与数字样式。
 - **本体零改动**：官方 `dsh-client-ui-workspace` 包文件一个不动；改动全在本仓库源码里，profile 补丁只有两条（装本包、禁用官方行）。
 - **多语言**：跟随 DSH 界面语言（中文 / English），复用官方文案键，只新增了 `status.waitingReview` 与 `status.scheduled`。
 
@@ -87,7 +93,7 @@
 
 | 数据源 | 提供 | 消费方接入 |
 |---|---|---|
-| [dsh-later](https://github.com/WuJiaoJue/dsh-later) | `useScheduleSummary()`：会话 id → `{ count, pausedCount, nextAt, state }` | `require('dsh-later/client')` |
+| [dsh-later](https://github.com/dsh-plugin-collection/dsh-later) | `useScheduleSummary()`：会话 id → `{ count, pausedCount, nextAt, state }` | `require('dsh-later/client')` |
 | dsh-gitea-dispatch | `useWaitingSummary()`：会话 id → `{ prNumber, state }` | `require('dsh-gitea-dispatch/client')` |
 
 - 两个插件**未安装 / 未启用时静默降级**：图标不出现，其余徽标照常，不会报错也不会空转。
@@ -107,17 +113,24 @@
 
 ### 安装到 DSH
 
-本包是一个 **fork 覆盖包**：注册与官方 `dsh-client-ui-workspace` 相同的槽位，并把官方那一行 disable（补丁见 `cordis.patch.yml`）。构建产物随仓库提交，从 GitHub 直接装即可，不需要本地构建：
+**npm 安装（推荐，预构建产物，无需授权）：**
 
 ```bash
-dsh plugin --profile web add "github:WuJiaoJue/dsh-group-status"
+dsh plugin --profile web add dsh-group-status
 # 重启 dsh web 后生效（侧栏是整包替换，需重新生成浏览器模块）
 ```
 
+或者从 GitHub 安装：
+
+```bash
+dsh plugin --profile web add "github:dsh-plugin-collection/dsh-group-status"
+# 重启 dsh web 后生效
+```
+
 本机开发时用 link，改完 `src/` 重建即可生效：
 
 ```bash
-git clone https://github.com/WuJiaoJue/dsh-group-status.git
+git clone https://github.com/dsh-plugin-collection/dsh-group-status.git
 cd dsh-group-status
 pnpm install && pnpm build
 
@@ -176,7 +189,7 @@ pnpm test:spec    # 只跑上游 spec 套件
 ## 已知限制
 
 - **上游换代必须手工 rebase**：本包 vendored 了上游源码（`src/`、`tests/`），用的不是稳定公共 API；上游动槽位名、组件签名或上下文契约时要跟着改，步骤见[升级手册](./docs/upgrading.md)。
-- **折叠时多一次全量遍历**：聚合计数与展开态共用同一份派生，超大分组（数百会话）每次状态变更多一次 traverse，与展开渲染同量级，可接受。
+- **每次状态变更多一轮全量测量**：聚合计数与展开态共用同一份派生；为了让折叠的父级算得准，**展开的分组同样要被测量**（它自己不画徽标，但祖先要用它的数字）。超大分组（数百会话）每次状态变更多一轮 traverse + 一次沿树上卷，与展开渲染同量级，可接受；该成本由 `tests/group-status.client.spec.ts` 的 perf 用例守住。
 - **状态不自己产生**：跨插件图标完全依赖 dsh-later / dsh-gitea-dispatch 暴露的摘要 API，它们不装就只是没有那两个图标，不影响本体。
 - **数字比明细粗**：定时任务按「组内有定时任务的会话数」计，不按任务条数累计；具体条数在 dsh-later 自己的界面上看。
 - **只覆盖侧栏折叠态**：本插件只加聚合显示，不改会话状态机、不改行内 badge 的判据。