dsh-workplan 1.7.1 → 1.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +72 -0
- package/README.en.md +42 -1
- package/README.md +43 -1
- package/SECURITY.md +120 -0
- package/docs/SBOM.md +113 -0
- package/docs/cc/AVA-VULNERABILITY-ANALYSIS.md +97 -0
- package/docs/cc/CC-2026-ASSESSMENT.md +266 -0
- package/docs/cc/SECURITY-TARGET.md +244 -0
- package/docs/collaboration.md +440 -0
- package/docs/collapse-interaction-spec.md +272 -0
- package/docs/defect-report-count-inconsistency.md +370 -0
- package/docs/departments.md +194 -0
- package/docs/design-proposals/state-machine.reference.ts +836 -0
- package/docs/design-proposals/state-machine.test.reference.ts +655 -0
- package/docs/fix-report-derived-counts-1.4.3.md +199 -0
- package/docs/fix-report-phase-percent-1.5.2.md +284 -0
- package/docs/preview/progress-visual-1.5.0.html +683 -0
- package/docs/progress-visualization-clarify-20261028.md +211 -0
- package/docs/progress-visualization-design-20261028.md +607 -0
- package/docs/progress-visualization-locate-20261028.md +159 -0
- package/docs/progress-visualization-report-1.5.0.md +140 -0
- package/docs/release-notes-1.7.0.md +46 -0
- package/docs/release-notes-1.7.1.md +36 -0
- package/docs/release-notes-1.8.0.md +80 -0
- package/docs/release-notes-1.8.1.md +69 -0
- package/docs/release-record-1.5.1-20261028.md +258 -0
- package/docs/release-record-1.5.2-20261029.md +101 -0
- package/docs/release-record-1.7.0-20261030.md +58 -0
- package/docs/release-record-1.7.1-20261030.md +56 -0
- package/docs/repro-count-inconsistency.md +310 -0
- package/docs/review-collaboration-20261030.md +246 -0
- package/docs/root-cause-phase-percent.md +866 -0
- package/docs/state-progress-matrix.md +517 -0
- package/docs/status-grouping-ia.md +789 -0
- package/docs/stuck-review-1.3.0.md +646 -0
- package/docs/t4-contrast-measurement.json +496 -0
- package/docs/t4-contrast-measurement.md +177 -0
- package/docs/t8-fix-prioritization.md +105 -0
- package/docs/version-upgrade-rollback-1.5.0-20261028.md +654 -0
- package/docs/visual-refinement-spec.md +164 -0
- package/lib/host.js +20 -3
- package/lib/runtime.js +21 -0
- package/package.json +4 -2
- package/src/host.ts +20 -2
- package/src/runtime.ts +22 -0
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
# dsh-workplan 两级折叠交互规格(T2 · 交互设计)
|
|
2
|
+
|
|
3
|
+
> 状态:设计定稿(可直接作为 T3/T4 的验收依据)
|
|
4
|
+
> 适用代码快照:`plugins/dsh-workplan/src/client.ts` sha256 前 16 位 `5533bf7293ef57b2`,1384 行,2026-10-25 22:37 读取。
|
|
5
|
+
> 说明:T2 勘察期间该文件被并行工作流从 1367 行改到 1384 行,`SessionCard` 与 `StageCard` 的折叠接线是**勘察中落地的**;本规格按该目标形态定义,若后续行号变化,以组件名/类名定位,不以行号为准。
|
|
6
|
+
> 本规格只覆盖 Dashboard 的任务卡片与步骤卡片;不覆盖会话内 `TurnCard`、工具调用卡片。
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 0. 结论先行
|
|
11
|
+
|
|
12
|
+
1. **两级折叠**:第一级是「任务卡片」(`SessionCard`),第二级是「每一步」(`StageCard`,即“第 N 步:…”那一行)。两级的摘要行默认都折叠。
|
|
13
|
+
2. **不设第三级**:不给「分几步做」整段再加一层折叠,也不给单条「具体工作」(`SubtaskRow`)加折叠;后者保留现有「更多细节」的 `<details>`。理由见 §2.2。
|
|
14
|
+
3. **默认折叠**:首次打开页面时,每张任务卡只显示一行摘要;展开任务后,每一步也只显示一行摘要;再点该步才显示目标、检查点和具体工作正文。
|
|
15
|
+
4. **折叠是纯展示层**:只改 `hidden`、`aria-expanded`、箭头方向;**不重算任何数字、不重新判状态、不发请求、不写存储**。顶部统计条、任务摘要、步骤摘要三者各有唯一数据源,见 §5。
|
|
16
|
+
5. **不做跨刷新记忆**:刷新后回到全部折叠;但在页面存活期间,4 秒一次的自动刷新**不得**把用户已展开的卡片收起来。见 §8。
|
|
17
|
+
6. **可访问性**:摘要行是原生 `<button>`,带 `aria-expanded` / `aria-controls`,面板用原生 `hidden` 隐藏;键盘 Enter/Space 可切换,焦点环可见;触摸目标不小于 44px。
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## 1. 现状与设计依据
|
|
22
|
+
|
|
23
|
+
| 事实 | 证据(当前快照) |
|
|
24
|
+
|---|---|
|
|
25
|
+
| 已有一个可复用的折叠容器 `Collapse`,默认 `defaultOpen=false`,摘要含 `title`、`meta`、`badge`,面板为 `hidden` | `src/client.ts:802-873` |
|
|
26
|
+
| 折叠样式:整行按钮 `min-height: 44px`、`touch-action: manipulation`、焦点环、`[hidden]{display:none}`、箭头 160ms 且尊重 `prefers-reduced-motion` | `src/client.ts:494-540` |
|
|
27
|
+
| 任务卡片已接线:`article.dsh-wp-session` 内放 `Collapse.dsh-wp-session-collapse`,摘要用 `session.stats`,面板放其余内容 | `src/client.ts:1050-1111`(摘要 1061-1069,面板 1070-1109) |
|
|
28
|
+
| 步骤卡片已接线:`section.dsh-wp-stage` 内放 `Collapse.dsh-wp-stage-collapse`,摘要用本步 `statuses`,面板放目标/检查点/具体工作 | `src/client.ts:961-989`(摘要 977-983,面板 984-986) |
|
|
29
|
+
| 「分几步做」只是分组标题,不是第三层折叠 | `src/client.ts:1092-1100` |
|
|
30
|
+
| 顶部汇总的 `totals` 继续只遍历 `activeSessions` 的 `session.stats`,与折叠无关 | `src/client.ts:1113-1133`、统计条 1147 起 |
|
|
31
|
+
| `stats` 的唯一算法在服务端:`computeStats(statuses)`;`phase` 由 `planPhase` 单独判定(全完成但结果未写入是 `integrating`,不是 `done`) | `src/plan.ts:1052-1061`、`1064-1070` |
|
|
32
|
+
| `Collapse` 单元测试已覆盖默认折叠、点击开合、阻止冒泡、原生按钮键盘、受控/非受控、44px 与 `[hidden]` 样式 | `tests/collapse.test.ts`(359 行,本次勘察时) |
|
|
33
|
+
|
|
34
|
+
**尚未验证**:`http://127.0.0.1:3080` 需要登录态(T1 实测未登录返回 401),因此本规格未做线上像素/真机验证;所有结论来自源码与单元测试快照,不冒充已看过的视觉结果。
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## 2. 两级折叠的定义
|
|
39
|
+
|
|
40
|
+
### 2.1 层级与 DOM 关系
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
Dashboard(统计条 + 汇总说明,不参与折叠)
|
|
44
|
+
└─ div.dsh-wp-sessions
|
|
45
|
+
└─ article.dsh-wp-session(保留 tone 左边框/圆角/内边距)
|
|
46
|
+
└─ section.dsh-wp-collapse.dsh-wp-session-collapse ← 第一级
|
|
47
|
+
├─ button.dsh-wp-collapse-toggle(任务摘要行)
|
|
48
|
+
└─ div.dsh-wp-collapse-panel(hidden 时隐藏)
|
|
49
|
+
├─ 更新于 / Guide / 降级提示 / 进度条 / 负责团队
|
|
50
|
+
├─ div.dsh-wp-section
|
|
51
|
+
│ ├─ div.dsh-wp-section-title「分几步做」(静态标题,可折叠入口不是它)
|
|
52
|
+
│ └─ section.dsh-wp-stage
|
|
53
|
+
│ └─ section.dsh-wp-collapse.dsh-wp-stage-collapse ← 第二级
|
|
54
|
+
│ ├─ button.dsh-wp-collapse-toggle(步骤摘要行)
|
|
55
|
+
│ └─ div.dsh-wp-collapse-panel
|
|
56
|
+
│ ├─ 要做出什么 / 这一步做完先检查
|
|
57
|
+
│ └─ div.dsh-wp-subtask × N(正文,不再折叠)
|
|
58
|
+
├─ Analysis(原有 details,保持原样)
|
|
59
|
+
└─ 错误正文
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
- **第一级(任务层)**:一张任务卡 = 一个折叠单元。
|
|
63
|
+
- **第二级(步骤层)**:一步 = 一个折叠单元;步骤列表由多个独立折叠单元组成。
|
|
64
|
+
- 两级状态互相独立:收起任务不会重置它内部各步骤的展开状态;展开/收起某一步不影响同任务的其他步骤,也不影响任务本身的展开状态。
|
|
65
|
+
|
|
66
|
+
### 2.2 为什么不是三级(明确拒绝的方案)
|
|
67
|
+
|
|
68
|
+
| 被拒绝的方案 | 拒绝理由 |
|
|
69
|
+
|---|---|
|
|
70
|
+
| 在「分几步做」整段外面再套一层折叠 | 用户从“看任务”到“看某一步”需要点 3 次;且会隐藏步骤名,用户无法先扫一眼有几步、哪步卡住。属于规格过度设计。 |
|
|
71
|
+
| 每条「具体工作」再单独折叠 | 步骤展开后正是用户主动要看的内容;再折叠会把一次点击变成多次,且与已有的「更多细节」`<details>` 功能重复。 |
|
|
72
|
+
| 顶部增加“全部展开/全部收起” | 用户本次只要求默认折叠、按需展开;全局开关增加状态耦合与误操作面,本期不做。 |
|
|
73
|
+
| 为折叠加高度动画 | 需要测量高度、处理异步内容与 reduced-motion,收益低、回归风险高;本期只保留箭头旋转 160ms。 |
|
|
74
|
+
|
|
75
|
+
### 2.3 默认状态
|
|
76
|
+
|
|
77
|
+
| 场景 | 默认状态 | 说明 |
|
|
78
|
+
|---|---|---|
|
|
79
|
+
| 首次加载 / 刷新 | 全部任务卡折叠 | `defaultOpen=false` |
|
|
80
|
+
| 展开某任务后 | 该任务内的每一步仍各自折叠 | 只显示步骤摘要行 |
|
|
81
|
+
| 收起某任务再展开 | 该任务内各步骤保持收起前的状态 | 面板用 `hidden` 隐藏但保持挂载,组件 state 不丢 |
|
|
82
|
+
| 4 秒自动刷新(同一会话) | 已展开的保持展开,已收起的保持收起 | 卡片有稳定 `key`(`session.sessionId`、`stage.id`),未被卸载 |
|
|
83
|
+
| 刷新浏览器 / 重新进入页面 | 回到全部折叠 | 本期不做跨刷新记忆,见 §8 |
|
|
84
|
+
|
|
85
|
+
> 默认折叠是**首次渲染**语义,不是“每次数据刷新都强制收起”。这两件事必须分开,否则用户展开后 4 秒就被自动收起,会被当成故障。
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## 3. 点击与开合行为
|
|
90
|
+
|
|
91
|
+
| 行为 | 规格 |
|
|
92
|
+
|---|---|
|
|
93
|
+
| 点击任务摘要行任意位置 | 展开该任务;再点一次收起。整行都是按钮(`button.dsh-wp-collapse-toggle`),不是只有小箭头可点。 |
|
|
94
|
+
| 点击步骤摘要行任意位置 | 展开该步;再点一次收起。只影响本步。 |
|
|
95
|
+
| 点击已展开面板内的正文/链接/按钮 | 正常执行内容自身行为,**不得**触发折叠(内容在按钮之外;折叠容器的点击只绑定在摘要按钮上)。 |
|
|
96
|
+
| 点击箭头 | 等同于点击整行,不单独处理。 |
|
|
97
|
+
| 事件冒泡 | 摘要按钮的 click / Enter / Space 必须 `stopPropagation()`,防止以后给卡片外层加点击时双重触发。当前 `Collapse` 已实现。 |
|
|
98
|
+
| 收起时焦点位置 | 焦点停留在摘要按钮上(用户就是点它收起的);不把焦点丢进被隐藏区域。若未来出现“代码主动收起且焦点在面板内”的场景,必须把焦点移回摘要按钮;本期无此调用路径。 |
|
|
99
|
+
| 展开时焦点 | 不自动把焦点移入面板;用户按 Tab 自然进入面板第一个可聚焦元素。 |
|
|
100
|
+
| 切换时的网络/数据副作用 | 禁止:不发 fetch、不调用计划更新、不改 URL、不写 localStorage/sessionStorage、不重新排序会话、不改变 `activeSessions` 过滤。 |
|
|
101
|
+
| 切换时的视觉反馈 | 箭头旋转(160ms;`prefers-reduced-motion` 下无动画);面板即时显示/隐藏,无高度动画。 |
|
|
102
|
+
| 双击/连点 | 每次点击翻转一次,最终状态以最后一次为准;不得出现“点一次开、再点仍开”的状态错位(state 由 React 管理,截图/测试以 `aria-expanded` 为准)。 |
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 4. 摘要字段规格
|
|
107
|
+
|
|
108
|
+
摘要行必须做到:**不展开也能回答“这是什么任务/哪一步、做完多少、现在什么状态”**。
|
|
109
|
+
|
|
110
|
+
### 4.1 第一级:任务卡片摘要行
|
|
111
|
+
|
|
112
|
+
| 字段 | 必需 | 精确文案 / 来源 | 缺失时 |
|
|
113
|
+
|---|---|---|---|
|
|
114
|
+
| 任务名 | 是 | `session.title` | 回退 `t('panel')`(“任务进度”) |
|
|
115
|
+
| 完成数/总数 | 是 | `本计划 ${stats.done ?? 0}/${stats.total ?? 0} 做好了`,只读 `session.stats` | 缺失按 0 处理,不隐藏 |
|
|
116
|
+
| 状态 | 是 | `Pill(tone=phaseTone(session.phase), t('phase.' + session.phase))`,如“已完成 / 正在做 / 卡住了 / 正在收尾 / 已取消” | `phase` 缺省 `pending` |
|
|
117
|
+
| 卡住数 | 保留(现有信息,不倒退) | `${stats.blocked ?? 0} 卡住了` | 显示 `0` |
|
|
118
|
+
| 更新于 | 可选 | 当前实现放在展开后的面板首行(`dsh-wp-session-updated`),可以接受;不要求塞进摘要,避免窄屏拥挤 | 无时间则不渲染 |
|
|
119
|
+
| 不进入摘要的内容 | — | 进度百分比、进行中/未开始数量、负责团队、Guide 三句话、降级提示、错误正文、Analysis | 全部留在面板内 |
|
|
120
|
+
|
|
121
|
+
可访问名称示例(屏幕阅读器会把按钮内文字连起来):
|
|
122
|
+
`单句说明 1+1=2 本计划 1/1 做好了 0 卡住了 已完成`。
|
|
123
|
+
|
|
124
|
+
### 4.2 第二级:步骤卡片摘要行
|
|
125
|
+
|
|
126
|
+
| 字段 | 必需 | 精确文案 / 来源 | 缺失时 |
|
|
127
|
+
|---|---|---|---|
|
|
128
|
+
| 步骤名 | 是 | `第 N 步:${stage.name}`(现有 `stageLabel`) | 名称缺失显示“第 N 步” |
|
|
129
|
+
| 完成数/总数 | 是 | `${done}/${items.length} 做好了`,`done` 为本步内 `statuses` 中 `done` 的条数,`items` 为本步 `stage.subtasks` | `subtasks` 缺失按空数组,显示 `0/0` |
|
|
130
|
+
| 状态 | 是 | `Pill(tone, stateText)`;`stateText` 沿用折叠前既有规则:`blocked>0 → “${blocked} 卡住了”`;全部完成 → “都做完了”;有 `in_progress` → “正在做”;否则 → “还没开始” | 按“还没开始” |
|
|
131
|
+
| 步骤目标/检查点/具体工作 | 否(进面板) | `stage.goal`、`stage.checkpoint`、`SubtaskRow` 列表 | 不展示于摘要 |
|
|
132
|
+
| 不进入摘要的内容 | — | 负责人、方法、验收、交付、风险、单条具体工作的进度条 | 全部留在面板内 |
|
|
133
|
+
|
|
134
|
+
**口径声明(写进 UI 语义,防止误读)**:第二级的 `x/y` 是**本步**的完成数,不是整个任务;摘要必须保留“第 N 步”前缀,禁止把本步数字放到没有步骤语境的位置。任务级数字只认 `session.stats`(§5)。
|
|
135
|
+
|
|
136
|
+
### 4.3 数据来源铁律(摘要层)
|
|
137
|
+
|
|
138
|
+
1. 任务摘要的 `done/total/blocked` **只能**取 `session.stats`,与顶部统计条、页头“N 个任务,拆成 M 件具体工作”同源。
|
|
139
|
+
2. 步骤摘要的 `done/items.length` **只能**沿用折叠前 `StageCard` 的算法(本步 `subtasks` × `statuses`),不得改成读 `session.stats`,也不得把各步相加后回填任务摘要。
|
|
140
|
+
3. `phase` 一律透传服务端结果;禁止在客户端用 `done === total` 重新推导“已完成”,否则会把“正在收尾(integrating)”误判为“已完成”。
|
|
141
|
+
4. 折叠前后不得新增、隐藏、过滤或重排会话;`activeSessions` 仍只过滤 `phase === 'cancelled'`。
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## 5. 统计与状态不变式(硬性)
|
|
146
|
+
|
|
147
|
+
**定义**:折叠是纯展示层。允许变化的只有 `hidden`、`aria-expanded`、`data-open`、箭头方向、焦点环。除此之外任何数字、状态、顺序、请求都不得变化。
|
|
148
|
+
|
|
149
|
+
| 不变式 | 要求 | 反例(禁止) |
|
|
150
|
+
|---|---|---|
|
|
151
|
+
| 顶部统计条 | 折叠/展开任意组合前后,四个数字逐字不变 | 根据展开的卡片重新累加 |
|
|
152
|
+
| 页头汇总 | “当前各会话最新计划汇总:N 个任务,拆成 M 件具体工作”不变 | 把已折叠任务从汇总里排除 |
|
|
153
|
+
| 任务摘要 | 每张卡的 `本计划 x/y` 等于该会话 `session.stats`;所有有效卡之和等于统计条 | 用 `stages.length`、`statuses.length`、DOM 条数重算 |
|
|
154
|
+
| 步骤摘要 | 每步 `x/y` 等于本步既有算法结果;不改状态判断 | 把各步相加显示成任务总数 |
|
|
155
|
+
| 状态 | `phase` 与 `stateText` 完全沿用折叠前逻辑 | 用“全 done”覆盖 `integrating` |
|
|
156
|
+
| 数据请求 | 切换折叠不发请求、不重置轮询、不丢已加载数据 | 展开时懒加载计划 |
|
|
157
|
+
| 挂载 | 面板隐藏时内容仍挂载(`hidden`),不卸载 | 用条件渲染卸载面板,导致 `<details>` 状态丢失、统计重算 |
|
|
158
|
+
|
|
159
|
+
**验收口径**:以“同一份接口数据、同一时刻”为前提,记录折叠前/后的 `statbar` 文本与每张卡摘要文本,必须逐字相等;不是“看起来差不多”。
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## 6. 可访问性要求
|
|
164
|
+
|
|
165
|
+
| 项 | 要求 | 现状 |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| 控件语义 | 摘要行必须是原生 `<button type="button">`,不用 `div role=button`,不用 `<summary>` 模拟 | 已满足(`client.ts:846-864`) |
|
|
168
|
+
| 展开状态 | `aria-expanded="true/false"` 与视觉状态同步 | 已满足 |
|
|
169
|
+
| 关联面板 | `aria-controls` 指向面板 `id`;面板 id 在组件生命周期内稳定(`useState` 生成一次) | 已满足(`client.ts:816-818`) |
|
|
170
|
+
| 隐藏方式 | 面板用原生 `hidden` 属性;折叠时内容不可聚焦、不被读屏朗读 | 已满足(`client.ts:867-871`) |
|
|
171
|
+
| 按钮可访问名称 | 由标题 + 计数 + 状态文本组成;不额外加固定 `aria-label` 覆盖 | 由内容自然生成 |
|
|
172
|
+
| 键盘 | Tab 聚焦;Enter / Space 触发一次且仅一次(原生按钮行为;`onKeyDown` 只阻止冒泡,不 `preventDefault`) | 已满足,测试覆盖 |
|
|
173
|
+
| 焦点可见 | `:focus-visible` 显示 2px 品牌色描边、offset 2px | 已满足(CSS 516) |
|
|
174
|
+
| 折叠后 Tab 顺序 | 隐藏面板内的链接/按钮不进入 Tab 序列 | 由 `hidden` 保证 |
|
|
175
|
+
| 嵌套按钮 | 摘要按钮内不得再放按钮/链接;`Pill` 是 `span`,允许 | 已满足(`Pill` 见 `client.ts:727-729`) |
|
|
176
|
+
| 箭头 | 纯装饰,`aria-hidden="true"` | 已满足 |
|
|
177
|
+
| 读屏播报 | 聚焦时读“<任务名> … 已折叠/已展开 按钮”;不额外加 live region | 依赖 `aria-expanded` |
|
|
178
|
+
| 颜色 | 状态不能只靠颜色:`Pill` 内必须有状态文字;计数必须有数字 | 已满足 |
|
|
179
|
+
| 动态更新 | 4 秒轮询更新数字时,不打断用户焦点、不自动展开/收起、不移动焦点 | 需回归验证(见 AC9) |
|
|
180
|
+
| Escape | **不要求**用 Escape 收起(原生 disclosure 模式无此约定;加了反而与弹层习惯混淆) | 本期不做 |
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## 7. 移动端与触摸要求
|
|
185
|
+
|
|
186
|
+
| 项 | 要求 |
|
|
187
|
+
|---|---|
|
|
188
|
+
| 触摸目标 | 摘要按钮 `min-height ≥ 44px`,整行可点,宽度撑满卡片内容区;不要求点小箭头。 |
|
|
189
|
+
| 触摸延迟 | 按钮保留 `touch-action: manipulation`,避免双击缩放延迟。 |
|
|
190
|
+
| 悬停 | 不允许存在“只有 hover 才能发现可折叠”的设计;箭头和摘要行在静止态即可识别。 |
|
|
191
|
+
| 窄屏换行 | 320px / 375px 宽度下,任务名、计数、状态药丸允许换行;不得出现横向滚动、文字截断(不用 `text-overflow: ellipsis` 截掉关键计数/状态)。 |
|
|
192
|
+
| 两级间距 | 步骤折叠行之间、步骤行与任务面板边缘之间保持现有 ≥10px 间距,避免误触相邻行。 |
|
|
193
|
+
| 嵌套误触 | 点步骤摘要不得收起父任务;点任务摘要不得展开任何步骤。 |
|
|
194
|
+
| 长文本 | 标题与摘要 `overflow-wrap: anywhere`;放大到 200% 字号不裁切、不重叠。 |
|
|
195
|
+
| 动效 | `prefers-reduced-motion: reduce` 时关闭箭头 transition;不引入面板高度动画。 |
|
|
196
|
+
| 安全区 | 不改现有 `env(safe-area-inset-bottom)` 与滚动容器;折叠不改变页面总滚动方式。 |
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## 8. 折叠状态记忆(“待确认”项的结论)
|
|
201
|
+
|
|
202
|
+
**结论:本期不做跨刷新持久化;只保留页面内的组件状态。**
|
|
203
|
+
|
|
204
|
+
| 范围 | 行为 | 理由 |
|
|
205
|
+
|---|---|---|
|
|
206
|
+
| 同一次页面会话内 | 已展开/已收起状态保留,包括 4 秒轮询重渲染之后 | 组件 `key` 稳定、非受控 state 不丢;这是“不打断用户”的最低要求 |
|
|
207
|
+
| 浏览器刷新 / 重新进入 | 全部回到折叠 | 用户明确要求“默认折叠”;持久化会让“默认”失效,还会出现旧展开状态掩盖新任务 |
|
|
208
|
+
| 跨设备 / 跨标签页 | 不同步 | 无此需求 |
|
|
209
|
+
| 存储 | 不写 localStorage、sessionStorage、cookie、URL | 避免状态版本/清理/多会话串扰问题;减少回归面 |
|
|
210
|
+
|
|
211
|
+
如果将来产品确需“刷新后记住”,应单独立项,键建议 `dsh-workplan:collapsed:<sessionId>:<level>`,带版本号与过期清理;**不属于本次验收范围**。
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
215
|
+
## 9. 验收条件(可直接执行)
|
|
216
|
+
|
|
217
|
+
| 编号 | 场景 | 通过标准 |
|
|
218
|
+
|---|---|---|
|
|
219
|
+
| AC1 | 首次加载 | 所有任务卡默认折叠:每个 `.dsh-wp-collapse-panel` 都是 `hidden`;每个摘要按钮 `aria-expanded="false"`;页面只显示摘要行,不显示 Guide/进度条/团队/步骤正文。 |
|
|
220
|
+
| AC2 | 任务摘要字段 | 每张卡可见:任务名、`本计划 x/y 做好了`、`z 卡住了`、状态药丸;数字与同会话 `session.stats` 完全一致;状态文本与 `phase` 一致。 |
|
|
221
|
+
| AC3 | 任务开合 | 点摘要行 → `aria-expanded="true"`、面板 `hidden=false`、箭头朝上;再点 → 全部还原。点箭头与点整行效果相同。 |
|
|
222
|
+
| AC4 | 步骤层默认折叠 | 展开任务后,每一步只显示 `第 N 步:名称`、`x/y 做好了`、状态药丸;步骤面板默认 `hidden`。 |
|
|
223
|
+
| AC5 | 步骤独立开合 | 展开第 1 步不影响第 2 步;再点第 1 步收起;同任务其他步骤状态不变。 |
|
|
224
|
+
| AC6 | 嵌套不误触 | 点步骤摘要时任务不收起(`stopPropagation` 生效);点已展开面板正文不触发折叠。 |
|
|
225
|
+
| AC7 | 键盘 | 仅用 Tab、Enter、Space 可完成两级开合;焦点环可见;每次按键只翻转一次;折叠面板内的控件不可 Tab 到。 |
|
|
226
|
+
| AC8 | 读屏语义 | 摘要按钮的可访问名称包含任务名/步骤名、计数、状态;`aria-controls` 指向的面板真实存在;箭头不被朗读。 |
|
|
227
|
+
| AC9 | 统计不变 | 以“全部折叠”为基线,任意展开/收起组合后:统计条四数、页头汇总、每张卡摘要数字、每步摘要数字逐字不变;状态文本不变。 |
|
|
228
|
+
| AC10 | 自动刷新 | 展开若干卡后等待 ≥2 个轮询周期(约 8s),展开状态保持;数字仅随接口数据变化;焦点不被抢走。 |
|
|
229
|
+
| AC11 | 无副作用 | 切换折叠期间无网络请求、无 URL 变化、无存储写入;计划/状态接口数据不被修改。 |
|
|
230
|
+
| AC12 | 移动端 | 320px 与 375px 视口:摘要行高度 ≥44px、可整行点击、无横向滚动、计数与状态不截断、200% 字号不重叠;reduced-motion 下无箭头动画。 |
|
|
231
|
+
| AC13 | 刷新语义 | 刷新浏览器后回到 AC1 的全折叠状态(本期明确不记忆)。 |
|
|
232
|
+
|
|
233
|
+
**建议的测试实现**:
|
|
234
|
+
|
|
235
|
+
1. 组件级:沿用 `tests/collapse.test.ts` 的 hook-aware harness(支持惰性初始值与函数式 `setState`),挂载 `Dashboard` fixture,断言所有面板 `hidden === true`、摘要文本、点击后状态翻转、统计文本不变。
|
|
236
|
+
2. 交互级:用 `client-render.test.ts` 的整页渲染断言默认折叠文本仍在(面板 `hidden` 但内容挂载),但需注意其简易 `useState` stub 不执行惰性初始值/函数式更新(`tests/client-render.test.ts:83-89`),若要在该文件里测点击,必须升级 stub,否则 `Collapse` 生成的 id 会变成函数、点击也不会重渲染。
|
|
237
|
+
3. 手工级(需登录态):登录后在 `http://127.0.0.1:3080` 打开面板;DevTools 执行 `Array.from(document.querySelectorAll('.dsh-wp-collapse-panel')).every(p => p.hidden)` 应为 `true`;记录统计条文本,反复开合后再比对;切 320px 设备模拟;只用键盘走一遍;开 VoiceOver 抽查两个摘要按钮。
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## 10. 给实现方的接线要点(当前快照已按此实现)
|
|
242
|
+
|
|
243
|
+
- 任务层:`SessionCard`(`client.ts:1050`)外层保留 `article.dsh-wp-session`(tone 边框/圆角/内边距),内部用 `Collapse`,传 `className='dsh-wp-session-collapse'`、`panelClassName='dsh-wp-session-body'`、`title`、`meta=[本计划计数, 卡住数]`、`badge=状态药丸`、`defaultOpen=false`;其余内容作为 children。
|
|
244
|
+
- 步骤层:`StageCard`(`client.ts:961`)外层保留 `section.dsh-wp-stage`(tone 边框),内部 `Collapse`,传 `className='dsh-wp-stage-collapse'`、`panelClassName='dsh-wp-stage-body'`、`title=第 N 步:名称`、`meta=本步 x/y`、`badge=本步状态`、`defaultOpen=false`;`goal/checkpoint/SubtaskRow` 作为 children。
|
|
245
|
+
- 不动的部分:`SubtaskRow` 正文与其 `<details>`、`Analysis`、`TurnCard`、`Dashboard` 的 `activeSessions`/`totals`/统计条、`plan.ts` 的 `computeStats`/`planPhase`、`host.ts`/`runtime.ts`。
|
|
246
|
+
- 已发现的边界(**非折叠引入**,供决定是否单独修):`StageCard` 在 `stage.subtasks` 为空时,`done === items.length` 为 `0 === 0`,会显示 `0/0 做好了` + tone `done` + 状态“都做完了”。这是折叠前就有的逻辑;若要修,应另开缺陷,不要借折叠改动状态口径。
|
|
247
|
+
- 并行修改提醒:本次勘察 22:33→22:37 期间 `client.ts` 从 1367 行变为 1384 行,接线是并行落地的;实现/复核前先重新 `shasum` 与 `grep` 确认当前接线,不要只信本文行号。
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## 11. 不做项清单(防止过度设计)
|
|
252
|
+
|
|
253
|
+
- 不做跨刷新/跨标签页记忆。
|
|
254
|
+
- 不做“全部展开/全部收起”。
|
|
255
|
+
- 不做第三级折叠(步骤列表整体、单条具体工作)。
|
|
256
|
+
- 不做面板高度动画、不做滚动定位/吸顶。
|
|
257
|
+
- 不改统计口径、不改 `phase` 判定、不改接口、不加新依赖。
|
|
258
|
+
- 不新增 locale 文案(本规格复用现有键:`panel`、`scopeThis`、`stats.done`、`stats.blocked`、`phase.*`、`steps`、`stepPrefix/stepSuffix`、`updatedAt`、`helpDone`);如未来要显示“共 N 步”,需同时补中英文并处理英文单复数,本期不需要。
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## 12. 未验证与风险
|
|
263
|
+
|
|
264
|
+
| 项 | 状态 |
|
|
265
|
+
|---|---|
|
|
266
|
+
| 线上真实 DOM / 像素 / iPhone 真机 | **未验证**(面板需登录,T1 实测未登录 401) |
|
|
267
|
+
| 4 秒轮询下展开状态保持 | 代码推演为保持(稳定 key + 非受控 state),未在真实页面计时验证 |
|
|
268
|
+
| 读屏软件实际播报 | 未用 VoiceOver/NVDA 实测,仅按 ARIA 规范与组件结构检查 |
|
|
269
|
+
| 并行工作流继续改文件 | 可能存在;以最终 `shasum` 与测试结果为准 |
|
|
270
|
+
| 空步骤边界 | 已发现,属既有逻辑,未修改 |
|
|
271
|
+
|
|
272
|
+
**风险控制**:本规格的核心是把“折叠”与“统计/状态”解耦——摘要只读既有数据源,折叠只改可见性。只要实现遵守 §4.3 与 §5,就不会再出现此前“4 件 / 5 件 / 12 件”口径混用的回归。
|
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
# dsh-workplan 计数一致性缺陷诊断报告(T2 分级清单)
|
|
2
|
+
|
|
3
|
+
- 报告编号:T2-DEFECT-2026-10-28
|
|
4
|
+
- 被测版本:`dsh-workplan@1.4.2`
|
|
5
|
+
- 被测代码指纹:见第 8 节(源码与构建产物 sha256)
|
|
6
|
+
- 复现文档:[`docs/repro-count-inconsistency.md`](repro-count-inconsistency.md)
|
|
7
|
+
- 复现脚本:[`scripts/repro-inconsistent-counts.ts`](../scripts/repro-inconsistent-counts.ts)
|
|
8
|
+
- 结论:**存在 4 条已实测缺陷,全部可稳定复现;其中 2 条 P0、2 条 P1。它们不是 4 个互不相关的根因,而是“同一份计划状态被维护成两个真相源”在 4 个边界上的表现。**
|
|
9
|
+
- 原始会话证据:`session-91ec3273-3277-49ff-87b3-7ce4722f29e0` 内嵌的第 6 条 `workplan-result` 已直接出现 `done=11/12 + stats.progress=100 + 最后一项 pending/progress=100`。
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 1. 分级口径
|
|
14
|
+
|
|
15
|
+
| 级别 | 定义 | 用户影响 |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| P0 | 正常执行路径即可触发;同一屏出现互相矛盾的事实;会直接误导用户对“还有没有在干活”的判断 | 高,主界面常驻 |
|
|
18
|
+
| P1 | 特定但常规的路径触发(预算暂停、续跑);状态/进度语义被破坏,可能误导“是否完成” | 中高,暂停/续跑时可见 |
|
|
19
|
+
| P2 | 需要非常规路径;影响局部或仅内部契约 | 低 |
|
|
20
|
+
|
|
21
|
+
“复现概率”指在当前代码下由逻辑必然性决定,不是统计抽样;本轮脚本每次运行都得到同一组数值。
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 2. 缺陷总表
|
|
26
|
+
|
|
27
|
+
| ID | 级别 | 一句话 | 触发路径 | 主要观测面 | 复现概率 |
|
|
28
|
+
| --- | --- | --- | --- | --- | --- |
|
|
29
|
+
| D1 | P0 | 并发波内 `stats` 冻结在第一波波末,实时状态继续变化 | 任何多波计划 | 顶部统计条、卡片进度行、Donut | 确定性 100% |
|
|
30
|
+
| D2 | P0 | 同一份 payload 内 `stats` 与 `departments` 互相矛盾 | 同 D1 | HTTP/序列化契约、任何消费者 | 确定性 100% |
|
|
31
|
+
| D3 | P1 | 预算暂停把未完成项改成 `pending`,却保留 `progress=100`、`childId`、`startedAt` | 单轮预算耗尽 | 任务明细、卡片 100%、原始会话 | 确定性 100% |
|
|
32
|
+
| D4 | P1 | blocked 计划 resume 后 `stats.blocked` 仍为 2,实际已无 blocked | 续跑受阻计划 | 顶部“卡住了”、卡片“正在做/还没开始” | 确定性 100% |
|
|
33
|
+
|
|
34
|
+
D1 与 D2 是同一根因的两个观测面:前者是“时间上的旧”,后者是“同一时刻的自相矛盾”。D4 是同一根因在 resume 路径上的又一次出现。把它们分开列,是因为验收探针、用户影响和修复检查点不同,不是为了凑数。
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## 3. D1(P0):并发波内 `stats` 冻结
|
|
39
|
+
|
|
40
|
+
### 3.1 用户看到什么
|
|
41
|
+
|
|
42
|
+
一个三任务、两阶段的计划正在执行:
|
|
43
|
+
|
|
44
|
+
- 主 Agent 的实时状态:T1 done、T2 done、T3 正在做;
|
|
45
|
+
- 页面顶部:`1 做好了 · 0 正在做`;
|
|
46
|
+
- 卡片:`总体进度 33%`、`0 正在做 · 2 还没开始`;
|
|
47
|
+
- 但同一张卡片的第二阶段徽标写着「正在做」,T3 的子任务胶囊也写着「正在做」。
|
|
48
|
+
|
|
49
|
+
也就是说,**同一屏同时存在“0 个正在做”和“某个任务正在做”**。用户无法判断到底有没有在干活。
|
|
50
|
+
|
|
51
|
+
### 3.2 观察到的错误值 vs 期望值
|
|
52
|
+
|
|
53
|
+
场景 A 实测(`node scripts/repro-inconsistent-counts.ts`):
|
|
54
|
+
|
|
55
|
+
| 字段/界面 | 观察到的错误值 | 期望值(由同一份 statuses 派生) |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| `stats.total` | `3` | `3` |
|
|
58
|
+
| `stats.done` | `1` | `2` |
|
|
59
|
+
| `stats.inProgress` | `0` | `1` |
|
|
60
|
+
| `stats.pending` | `2` | `0` |
|
|
61
|
+
| `stats.progress` | `33` | `70` |
|
|
62
|
+
| 顶部统计条 | `1 做好了 / 0 正在做` | `2 做好了 / 1 正在做` |
|
|
63
|
+
| 卡片进度行 | `总体进度 33%`、`0 正在做 · 2 还没开始` | `总体进度 70%`、`1 正在做 · 0 还没开始` |
|
|
64
|
+
| 阶段徽标 | `第 2 步:第二波 … 正在做` | 同左;但它与上方统计条不能同时为真 |
|
|
65
|
+
| 子任务胶囊 | T2「做好了」、T3「正在做」 | 同左;与上方统计条不能同时为真 |
|
|
66
|
+
| Donut | `33%` | 至少不应与卡片 `33%` 一起被当成“实时” |
|
|
67
|
+
|
|
68
|
+
### 3.3 代码证据与机制
|
|
69
|
+
|
|
70
|
+
- 所有子任务状态写入都经过 `writeSubtaskStatus()`:`src/runtime.ts:361-366`。它只写 `record.statuses` 和 `updatedAt`,**不碰 `record.stats`**。
|
|
71
|
+
- `dispatchPlan` 只在每一轮并发波结束后重算:`src/runtime.ts:760`(`record.stats = computeStats(record.statuses)`),以及 `finally` 中再算一次:`src/runtime.ts:825`。
|
|
72
|
+
- 因此,从第一波波末到整个派发结束,`record.stats` 是**冻结快照**;而 `record.statuses` 在波内持续变化。窗口长度 = 后续所有波 + 子 Agent 运行时间,可能是分钟级。
|
|
73
|
+
- 序列化时直接取缓存:`src/runtime.ts:838`(`const stats = record.stats ?? computeStats(statuses)`)。
|
|
74
|
+
- UI 每 4000ms 轮询一次(`src/client.ts` 的 `usePlans`),所以错误画面是稳定可见的,不是瞬时闪烁。
|
|
75
|
+
|
|
76
|
+
### 3.4 复现概率与可见性
|
|
77
|
+
|
|
78
|
+
- 任何“第一波结束后还有状态变化”的计划:确定性 100%。
|
|
79
|
+
- 主界面常驻元素:顶部统计条、卡片进度行、Donut、组头汇总都读 `stats`;阶段徽标和子任务胶囊读 `statuses`。因此用户不需要点开详情就能看到矛盾。
|
|
80
|
+
- 原始会话 `session-91ec3273…` 有 6 个阶段、12 个子任务、6 轮预算续跑,天然处于多波结构;用户的截图投诉与此路径一致(截图原文件本轮未取得,故不引用其具体数字)。
|
|
81
|
+
|
|
82
|
+
### 3.5 根因
|
|
83
|
+
|
|
84
|
+
`statuses` 是唯一事实,`stats` 是派生缓存;但代码把缓存当成可独立维护的第二事实,且只在“波末”失效。跨波期间没有任何机制让两者对齐。
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 4. D2(P0):同一份 payload 内 `stats` 与 `departments` 自相矛盾
|
|
89
|
+
|
|
90
|
+
### 4.1 用户/消费者看到什么
|
|
91
|
+
|
|
92
|
+
不需要 UI,只看服务端下发的一份 JSON:
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
"stats": { "total": 3, "done": 1, "blocked": 0, "inProgress": 0, "pending": 2, "progress": 33 },
|
|
96
|
+
"departments": [
|
|
97
|
+
{ "id": "engineering", "total": 1, "done": 1, "blocked": 0, "inProgress": 0 },
|
|
98
|
+
{ "id": "qa", "total": 1, "done": 1, "blocked": 0, "inProgress": 0 },
|
|
99
|
+
{ "id": "design", "total": 1, "done": 0, "blocked": 0, "inProgress": 1 }
|
|
100
|
+
]
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`stats.done=1` 与 `qa.done=1` 不可能同时成立(qa 一个部门就完成了 1 项);`stats.inProgress=0` 与 `design.inProgress=1` 同样不可能同时成立。
|
|
104
|
+
|
|
105
|
+
### 4.2 观察到的错误值 vs 期望值
|
|
106
|
+
|
|
107
|
+
| 字段 | 观察到的错误值 | 期望值 |
|
|
108
|
+
| --- | --- | --- |
|
|
109
|
+
| `stats.done` | `1` | `2` |
|
|
110
|
+
| `stats.inProgress` | `0` | `1` |
|
|
111
|
+
| `stats.pending` | `2` | `0` |
|
|
112
|
+
| `departments[qa].done` | `1` | `1`(正确,实时聚合) |
|
|
113
|
+
| `departments[design].inProgress` | `1` | `1`(正确,实时聚合) |
|
|
114
|
+
| 同一响应的一致性 | 矛盾 | 所有聚合字段必须来自同一次 `computeStats(statuses)` |
|
|
115
|
+
|
|
116
|
+
### 4.3 代码证据与机制
|
|
117
|
+
|
|
118
|
+
- `serialisePlan()` 的 `stats` 走缓存:`src/runtime.ts:838`;
|
|
119
|
+
- 同一函数的 `departments` 却按 `statuses` 实时累加:`src/runtime.ts:843-857`(`if (item.status === 'done') current.done += 1` 等)。
|
|
120
|
+
- 这是**同一响应内的两套聚合逻辑**:一套读旧快照,一套读实时数组。即使把 D1 的冻结窗口缩到最短,这种“同报文矛盾”仍然会在每次序列化时出现,除非统一为一个派生结果。
|
|
121
|
+
|
|
122
|
+
### 4.4 复现概率与用户可见性
|
|
123
|
+
|
|
124
|
+
- 与 D1 同触发条件:确定性 100%。
|
|
125
|
+
- 普通用户看到的是 UI 矛盾;任何脚本、导出、第三方消费者读到的是 API 矛盾。它比 D1 更严重的地方在于:**即使不渲染 UI,数据本身已经坏了**。
|
|
126
|
+
- 修复验收必须直接比较 `stats` 与 `computeStats(payload.statuses)`,以及 `departments` 与按 statuses 聚合的结果。
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## 5. D3(P1):预算暂停产生 `pending + progress=100`
|
|
131
|
+
|
|
132
|
+
### 5.1 用户看到什么
|
|
133
|
+
|
|
134
|
+
本轮预算用尽,计划暂停:
|
|
135
|
+
|
|
136
|
+
- 卡片:`总体进度 100%`;
|
|
137
|
+
- 同一卡片:`0 正在做 · 1 还没开始`;
|
|
138
|
+
- Donut:`0%`(它按 `done/total` 算);
|
|
139
|
+
- 任务明细里最后一项:状态「还没开始」,进度却是 100%,还带着上一轮的 `childId` 和开始时间。
|
|
140
|
+
|
|
141
|
+
用户会以为“已经 100% 完成了”,但实际上还有一项没做。原始会话第 6 轮下发的就是这一组合;按 `client.js` 的渲染逻辑,卡片会显示 `总体进度 100%`,而同屏 Donut 为 `0%`。
|
|
142
|
+
|
|
143
|
+
### 5.2 观察到的错误值 vs 期望值
|
|
144
|
+
|
|
145
|
+
场景 B 实测:
|
|
146
|
+
|
|
147
|
+
| 字段/界面 | 观察到的错误值 | 期望值 |
|
|
148
|
+
| --- | --- | --- |
|
|
149
|
+
| `statuses[0].status` | `pending` | `pending` |
|
|
150
|
+
| `statuses[0].progress` | `100` | `0` |
|
|
151
|
+
| `statuses[0].childId` | `child-hang` | `null` |
|
|
152
|
+
| `statuses[0].startedAt` | 非空 | `null` |
|
|
153
|
+
| `statuses[0].finishedAt` | `null` | `null` |
|
|
154
|
+
| `statuses[0].error` | `本轮预算用尽,等待续跑` | 同左 |
|
|
155
|
+
| `stats` | `{"total":1,"done":0,"blocked":0,"inProgress":0,"pending":1,"progress":100}` | `progress: 0` |
|
|
156
|
+
| UI 卡片 | `总体进度 100%` + `0 正在做 · 1 还没开始` | `总体进度 0%` |
|
|
157
|
+
| UI Donut | `0%` | `0%`;但不应与卡片 100% 同屏 |
|
|
158
|
+
|
|
159
|
+
原始会话真实数据(`session-91ec3273…`,解压后 JSONL 第 327 行 / `seq=325`,2026-10-27 21:20:36 CST):
|
|
160
|
+
|
|
161
|
+
```json
|
|
162
|
+
"stats": {"total":12,"done":11,"blocked":0,"inProgress":0,"pending":1,"progress":100}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
```json
|
|
166
|
+
{
|
|
167
|
+
"subtaskId": "T12",
|
|
168
|
+
"status": "pending",
|
|
169
|
+
"progress": 100,
|
|
170
|
+
"childId": "41bcef5d-39b2-4726-9ba1-f67ac4908de1",
|
|
171
|
+
"startedAt": 1793106957096,
|
|
172
|
+
"finishedAt": null,
|
|
173
|
+
"summary": "",
|
|
174
|
+
"error": "本轮预算用尽,等待续跑"
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
同一条消息的头部写着「完成 11/12……剩余 1 项未完成」。**这是原始会话内的真实记录,不是构造。**
|
|
179
|
+
|
|
180
|
+
### 5.3 代码证据与机制
|
|
181
|
+
|
|
182
|
+
预算耗尽分支在 `src/runtime.ts:780-791`:
|
|
183
|
+
|
|
184
|
+
```ts
|
|
185
|
+
record.statuses = record.statuses.map((item: any) => item.status === 'done'
|
|
186
|
+
? item
|
|
187
|
+
: {
|
|
188
|
+
...item,
|
|
189
|
+
status: 'pending',
|
|
190
|
+
progress: item.progress ?? 0,
|
|
191
|
+
error: '本轮预算用尽,等待续跑',
|
|
192
|
+
summary: '',
|
|
193
|
+
finishedAt: null,
|
|
194
|
+
})
|
|
195
|
+
record.phase = 'paused'
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
它用对象展开**手工重写**状态,绕过了 `applyStatus()`;而 `applyStatus()` 在 `patch.status === 'pending'` 时会强制 `progress=0`、`startedAt=null`、`finishedAt=null`、`childId=null`(`src/plan.ts:1034-1074`)。两套“变成 pending”的规则不一致,于是产生了 `pending + 100` 这种非法组合。
|
|
199
|
+
|
|
200
|
+
随后 `finally` 里的 `computeStats(statuses)`(`src/runtime.ts:825`)如实把 `progress=100` 平均进 `stats.progress`,于是 100% 进入 UI。
|
|
201
|
+
|
|
202
|
+
### 5.4 复现概率与用户可见性
|
|
203
|
+
|
|
204
|
+
- 只要单轮预算在任一子任务执行中耗尽:确定性 100%。
|
|
205
|
+
- 默认单轮预算下限 60000ms;原始会话连续 6 轮都在预算边界暂停,说明这是常规路径。
|
|
206
|
+
- 用户可见性高:暂停画面正是用户会停下来检查“做到哪了”的时刻,此时给出 100% 最容易被误读为完成。
|
|
207
|
+
|
|
208
|
+
### 5.5 附带影响(不夸大)
|
|
209
|
+
|
|
210
|
+
残留的 `childId` / `startedAt` 与 `pending` 语义冲突,会让后续消费者无法区分“从未启动”与“启动过但被暂停”。本轮没有证据表明它会直接导致重复执行;这一点**未验证**,不写成已发生的后果。
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## 6. D4(P1):blocked 计划 resume 后 `stats.blocked` 残留
|
|
215
|
+
|
|
216
|
+
### 6.1 用户看到什么
|
|
217
|
+
|
|
218
|
+
一个 2 项都“卡住了”的计划被用户续跑,第一项已经重新开始执行:
|
|
219
|
+
|
|
220
|
+
- 顶部:`2 卡住了 · 0 正在做`;
|
|
221
|
+
- 卡片:`0 正在做 · 0 还没开始`;
|
|
222
|
+
- 子任务:T1「正在做」,T2「还没开始」。
|
|
223
|
+
|
|
224
|
+
三个地方三种说法。
|
|
225
|
+
|
|
226
|
+
### 6.2 观察到的错误值 vs 期望值
|
|
227
|
+
|
|
228
|
+
场景 C 实测:
|
|
229
|
+
|
|
230
|
+
| 字段/界面 | 观察到的错误值 | 期望值 |
|
|
231
|
+
| --- | --- | --- |
|
|
232
|
+
| `stats.blocked` | `2` | `0` |
|
|
233
|
+
| `stats.inProgress` | `0` | `1` |
|
|
234
|
+
| `stats.pending` | `0` | `1` |
|
|
235
|
+
| 实际计数 | `{done:0, blocked:0, inProgress:1, pending:1}` | 同左 |
|
|
236
|
+
| 顶部 | `2 卡住了 / 0 正在做` | `0 卡住了 / 1 正在做` |
|
|
237
|
+
| 卡片 | `0 正在做 · 0 还没开始` | `1 正在做 · 1 还没开始` |
|
|
238
|
+
| 子任务胶囊 | T1「正在做」 | 同左 |
|
|
239
|
+
|
|
240
|
+
### 6.3 代码证据与机制
|
|
241
|
+
|
|
242
|
+
- resume 分支:`src/runtime.ts:691`(`record.statuses = resetBlockedStatuses(record.statuses)`)之后,没有立即重算 `record.stats`。
|
|
243
|
+
- 紧接着 `src/runtime.ts:716` 把 `record.phase='executing'`,于是 UI 立即显示“执行中”,但统计仍停在 resume 前的 `blocked=2`。
|
|
244
|
+
- 直到第一波结束 `src/runtime.ts:760` 或 `finally` `src/runtime.ts:825` 才重算;如果第一个子任务运行较久,错误窗口同样是分钟级。
|
|
245
|
+
- `updateStatus()`(`src/runtime.ts:1169` 起)反而会同步重算 stats(`:1198`),说明代码里已经知道“写状态后要重算”,只是没有把这条规则落实到所有写入口。
|
|
246
|
+
|
|
247
|
+
### 6.4 复现概率与用户可见性
|
|
248
|
+
|
|
249
|
+
- 只要计划曾 blocked 且被 resume,并在第一波结束前读取:确定性 100%。
|
|
250
|
+
- 用户主动点“续跑”后最关心“是不是又跑起来了”,此时顶部仍说 2 个卡住,直接打击可信度。
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## 7. 根因归纳(单一真相源原则)
|
|
255
|
+
|
|
256
|
+
### 7.1 事实链
|
|
257
|
+
|
|
258
|
+
```text
|
|
259
|
+
canonical: statuses[] ──(writeSubtaskStatus, 波内实时写)──► 永远最新
|
|
260
|
+
│
|
|
261
|
+
│ 没有失效通知
|
|
262
|
+
▼
|
|
263
|
+
derived cache: stats ──(只在 760 波末 / 825 finally 重算)──► 跨波冻结
|
|
264
|
+
│
|
|
265
|
+
serialisePlan: stats 读缓存 ──────┘
|
|
266
|
+
departments 读 statuses(843-857)──► 同一响应两套事实
|
|
267
|
+
│
|
|
268
|
+
client: 顶部/卡片/Donut 读 stats;阶段徽标/胶囊读 statuses
|
|
269
|
+
└──► 用户屏幕上同时出现两种事实
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
### 7.2 两个主根因 + 一个放大器
|
|
273
|
+
|
|
274
|
+
| 编号 | 根因 | 表现 |
|
|
275
|
+
| --- | --- | --- |
|
|
276
|
+
| R1 | `stats` 被当作可独立维护的第二真相源:写 `statuses` 时不失效,只在波末重算 | D1、D4 |
|
|
277
|
+
| R2 | 预算暂停手工重写 statuses,绕过 `applyStatus()` 的 pending 归一化 | D3 |
|
|
278
|
+
| R3(放大器) | `serialisePlan` 内 `stats` 读缓存、`departments` 读实时;客户端又分别信任两种来源 | D2 及全部 UI 矛盾 |
|
|
279
|
+
|
|
280
|
+
### 7.3 为什么“只在批次结束时偶然对齐”
|
|
281
|
+
|
|
282
|
+
- 每轮 `dispatchPlan` 结束时执行 `finally` 的 `record.stats = computeStats(record.statuses)`(`:825`);
|
|
283
|
+
- 每个并发波结束时执行 `:760`;
|
|
284
|
+
- 因此只有在这些时刻,两个来源才短暂一致。其余时间 UI 轮询到的都是旧 `stats` + 新 `statuses`。
|
|
285
|
+
|
|
286
|
+
这与用户观察到的“截图里显示的数量和实际数量不一致”完全吻合,不是渲染库、缓存策略或浏览器问题。
|
|
287
|
+
|
|
288
|
+
### 7.4 设计文档早已规定单一来源
|
|
289
|
+
|
|
290
|
+
`docs/collapse-interaction-spec.md` 写明:
|
|
291
|
+
|
|
292
|
+
> `stats` 的唯一算法在服务端:`computeStats(statuses)`;`phase` 由 `planPhase` 单独判定。
|
|
293
|
+
|
|
294
|
+
`docs/status-grouping-ia.md` 也把 `stats.inProgress` 定义为 `status === 'in_progress'` 数。当前实现违反了自己文档里的不变量,属于实现缺陷,不是设计分歧。
|
|
295
|
+
|
|
296
|
+
---
|
|
297
|
+
|
|
298
|
+
## 8. 证据指纹
|
|
299
|
+
|
|
300
|
+
```text
|
|
301
|
+
plugin <repo>
|
|
302
|
+
version 1.4.2
|
|
303
|
+
node v26.9.0
|
|
304
|
+
src/runtime.ts f4dc6fd33b3e511ff0bfbc5886a1d1ef2404d17f495c142e93e5174cd385b367
|
|
305
|
+
src/plan.ts c3cfd5e760604c8cde3a2b9c57bc55b01b4755837257d09396d05bd269dd506e
|
|
306
|
+
lib/runtime.js 5f93ea0fa49b0cdc04819642d8626704b5918c8768e2982ebfa0603b355f9790
|
|
307
|
+
lib/plan.js 24455faea8791ba8e0ccec26c8d84cc98415ae0e6da881e9f60f5573b9418503
|
|
308
|
+
client.js 0c3ffd342a66da3a436633ba73b9d5b514200e9d91db3203f0a97bf7d5acd15d
|
|
309
|
+
package.json b542c81034a24eb31cea016a93ef2716fc850787994cf8dd93c9e42ce8f05fad
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
- ~~无 git 仓库:`git rev-parse` 返回 `fatal: not a git repository`,因此用文件哈希 + 版本号绑定证据。~~
|
|
313
|
+
**更正(2026-10-28 14:30 Lead 复核)**:该结论不成立——插件目录是独立 git 仓库(`git rev-parse --show-toplevel`
|
|
314
|
+
输出本目录,分支 `main`,tag `v1.4.3`)。本报告写作时的证据绑定方式(文件哈希 + 版本号)依然有效且无错,
|
|
315
|
+
但「没有 git 可用」这一理由有误;未来取证优先用 `git rev-parse HEAD` + 快照 SHA-256 双重绑定。
|
|
316
|
+
- 源码 mtime:`src/runtime.ts` 2026-10-26 21:24;构建产物 `lib/runtime.js`、`client.js` 2026-10-27 16:16。
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
## 9. 复现方式与验收探针
|
|
321
|
+
|
|
322
|
+
完整步骤见 [`docs/repro-count-inconsistency.md`](repro-count-inconsistency.md)。摘要:
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
cd <repo>
|
|
326
|
+
node scripts/repro-inconsistent-counts.ts # 当前构建:exit 0,14 条复现断言全 PASS
|
|
327
|
+
node scripts/repro-inconsistent-counts.ts --expect-fixed # 当前构建:exit 1,9 条不变量断言中 8 条 FAIL(departments 那条本就 PASS)
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
修复完成后,第二条命令必须变成 `exit 0`,且打印 `All single-source invariants hold.`。这应作为 T4 的硬验收门禁,而不是“看一眼 UI 差不多对了”。
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## 10. 对修复方向的约束(交给 T3,不在本任务实施)
|
|
335
|
+
|
|
336
|
+
以下是**约束**,不是已经写好的补丁;T3 必须自行设计并让回归测试证明:
|
|
337
|
+
|
|
338
|
+
1. **单一派生点**:`stats` 只能由 `computeStats(statuses)` 得到;序列化时现算,或使用带失效机制的派生缓存。禁止在 `statuses` 写入后继续向客户端发送旧 `stats`。
|
|
339
|
+
2. **同一响应同一次派生**:`departments` 与 `stats` 必须来自同一次状态快照;不能一个读缓存、一个读实时。
|
|
340
|
+
3. **所有状态迁移统一入口**:预算暂停、resume、取消、`updateStatus`、子 Agent 回调都必须经过同一套状态迁移规则(尤其是 `pending` 的归一化)。
|
|
341
|
+
4. **不变量断言**:序列化前断言
|
|
342
|
+
- `stats.total === statuses.length`;
|
|
343
|
+
- 四状态计数与 `statuses` 逐一相等;
|
|
344
|
+
- `pending` 项必须 `progress===0`、`childId===null`、`startedAt===null`;
|
|
345
|
+
- `done` 项必须 `progress===100`;
|
|
346
|
+
- `departments` 的聚合与 `statuses` 一致。
|
|
347
|
+
5. **回归测试**:把本脚本的三个场景移植为 `node:test`,并保留 `--expect-fixed` 作为独立探针;测试必须在修复前失败、修复后通过。
|
|
348
|
+
6. **客户端信任边界**:客户端继续只读服务端 `stats` 是可以的,但前提是服务端保证不变量;如果保留客户端二次聚合,必须与 `stats` 使用同一派生结果,不能各自维护。
|
|
349
|
+
7. **版本与变更记录**:按用户要求升级版本并写 CHANGELOG;本条属于 T3/T4 的交付,不在 T2 伪造。
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
## 11. 本轮未验证/未纳入分级的静态候选
|
|
354
|
+
|
|
355
|
+
以下两条是读代码时发现的可疑点,但**没有构造出运行态复现**,因此不计入 4 条缺陷,也不声称它们一定成立:
|
|
356
|
+
|
|
357
|
+
1. **运行中 `cancelPlan` 返回的 `stats` 可能是旧快照**:`src/runtime.ts:1249` 在 `record.dispatchPromise` 分支直接返回 `record.stats ?? computeStats(...)`。若取消时波内状态刚变、`finally` 尚未重算,返回值可能落后于 `statuses`。需要构造“取消瞬间”的时序才能验证。
|
|
358
|
+
2. **`planPhase` 把“有 done 但无 in_progress”判为 `executing`**:`src/plan.ts:1089-1095`。这可能是为了让主 Agent 收尾阶段仍显示“执行中”,但会让“全部子任务已 done、结果尚未写入”的计划显示为「正在做」;设计文档把该状态定义为 `integrating`,两者是否冲突需要产品口径确认。当前实现 `planPhase` 实际是先判全 done → `integrating`,因此只有“部分 done 且无 in_progress”才落 `executing`,属于边界语义问题,不是本轮主诉。
|
|
359
|
+
|
|
360
|
+
这两条建议 T3 在修复主问题时顺手加断言或测试确认;若确认成立,应另开缺陷编号并补“观察 vs 期望”,不要混入本报告的 4 条。
|
|
361
|
+
|
|
362
|
+
---
|
|
363
|
+
|
|
364
|
+
## 12. 结论
|
|
365
|
+
|
|
366
|
+
1. 用户的怀疑成立:插件确实存在多处逻辑不一致,且不是单点笔误。
|
|
367
|
+
2. 但根因高度集中:`stats` 作为派生缓存被当成第二真相源;预算暂停又绕过了统一的 pending 归一化。4 条缺陷是同一类错误在不同边界的表现。
|
|
368
|
+
3. 已用不依赖人工观察的脚本稳定复现 4 条缺陷,并在**原始会话的真实 payload** 中找到了 D3 的直接证据。
|
|
369
|
+
4. 当前版本 1.4.2 不应被视为“只是显示问题”;服务端下发的同一份 JSON 已经自相矛盾,修复必须从服务端单一派生点入手,不能只改前端文案。
|
|
370
|
+
5. 本报告不包含修复代码、不改版本号;修复、回归测试、版本升级与 CI 门禁属于后续任务。
|