dsh-workplan 1.7.0 → 1.8.0

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.
Files changed (43) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.en.md +41 -2
  3. package/README.md +40 -2
  4. package/SECURITY.md +109 -0
  5. package/docs/SBOM.md +113 -0
  6. package/docs/cc/AVA-VULNERABILITY-ANALYSIS.md +97 -0
  7. package/docs/cc/CC-2026-ASSESSMENT.md +254 -0
  8. package/docs/cc/SECURITY-TARGET.md +239 -0
  9. package/docs/collaboration.md +440 -0
  10. package/docs/collapse-interaction-spec.md +272 -0
  11. package/docs/defect-report-count-inconsistency.md +370 -0
  12. package/docs/departments.md +194 -0
  13. package/docs/design-proposals/state-machine.reference.ts +836 -0
  14. package/docs/design-proposals/state-machine.test.reference.ts +655 -0
  15. package/docs/fix-report-derived-counts-1.4.3.md +199 -0
  16. package/docs/fix-report-phase-percent-1.5.2.md +284 -0
  17. package/docs/preview/progress-visual-1.5.0.html +683 -0
  18. package/docs/progress-visualization-clarify-20261028.md +211 -0
  19. package/docs/progress-visualization-design-20261028.md +607 -0
  20. package/docs/progress-visualization-locate-20261028.md +159 -0
  21. package/docs/progress-visualization-report-1.5.0.md +140 -0
  22. package/docs/release-notes-1.7.0.md +46 -0
  23. package/docs/release-notes-1.7.1.md +36 -0
  24. package/docs/release-record-1.5.1-20261028.md +258 -0
  25. package/docs/release-record-1.5.2-20261029.md +101 -0
  26. package/docs/release-record-1.7.0-20261030.md +58 -0
  27. package/docs/release-record-1.7.1-20261030.md +56 -0
  28. package/docs/repro-count-inconsistency.md +310 -0
  29. package/docs/review-collaboration-20261030.md +246 -0
  30. package/docs/root-cause-phase-percent.md +866 -0
  31. package/docs/state-progress-matrix.md +517 -0
  32. package/docs/status-grouping-ia.md +789 -0
  33. package/docs/stuck-review-1.3.0.md +646 -0
  34. package/docs/t4-contrast-measurement.json +496 -0
  35. package/docs/t4-contrast-measurement.md +177 -0
  36. package/docs/t8-fix-prioritization.md +105 -0
  37. package/docs/version-upgrade-rollback-1.5.0-20261028.md +654 -0
  38. package/docs/visual-refinement-spec.md +164 -0
  39. package/lib/host.js +5 -16
  40. package/lib/runtime.js +37 -1
  41. package/package.json +4 -2
  42. package/src/host.ts +6 -15
  43. package/src/runtime.ts +39 -1
@@ -0,0 +1,211 @@
1
+ # T2 澄清问题清单 — dsh-workplan「画圈进度区」改造(2026-10-28)
2
+
3
+ 状态:**只出问题,未改动任何源码。** 插件版本仍为 `1.4.3`(`package.json:3`、`src/host.ts:328`)。
4
+ 上游依据:T1 定位报告 [progress-visualization-locate-20261028.md](./progress-visualization-locate-20261028.md)。
5
+
6
+ **本文件的任务:用 3 个必答问题 + 3 个默认题,把「怎么画」定死,然后才允许开工。**
7
+
8
+ ---
9
+
10
+ ## 0. 一句话结论(给决策者)
11
+
12
+ 既有的「图表下移」决策(`CHANGELOG.md:96`:*已按用户选择 B 修完*,落地在 `src/client.ts:1962-1966` 的注释里)
13
+ 正是今天「画圈部分不醒目」的**直接原因之一**。因此本次不是单纯"把字放大",
14
+ 而是要在**不再次毁掉首屏任务卡**的前提下,让折叠卡片自己就带图形进度。
15
+ **这里需要用户在 Q3 拍板,因为两个目标在物理上互相挤占首屏高度。**
16
+
17
+ ---
18
+
19
+ ## 1. 已经确认、不需要再问的事实(避免重复提问)
20
+
21
+ | 事实 | 证据位置 | 由此排除的问题 |
22
+ |---|---|---|
23
+ | 三处画圈 = 折叠态卡片 meta 行 + 组头摘要 + 空态,**不是** Chart.js 图表 | `src/client.ts:1356-1361`、`1671-1673`、`1698`、`1732` | 不需要问"用户到底圈的是哪个图" |
24
+ | 0% 时迷你条**完全不可见**:轨道与折叠按钮同为 `--dsw-alias-bg-layer-2` | 轨道 `src/client.ts:626`;按钮 `src/client.ts:759` | 不需要问"是不是屏幕太暗/手机问题" |
25
+ | 迷你条 54×5px,百分比只写在 `title` 属性(触屏无 hover) | `src/client.ts:623-624`、`1358` | 不需要问"为什么数字看不到" |
26
+ | 顶部 5 格统计条是纯数字,无完成率、无图形 | `src/client.ts:1947-1952` | 见 Q6 边界确认 |
27
+ | Chart.js 4.6.1 **已是依赖**,不是新增 | `package.json` dependencies | **"是否允许引入新依赖"这个问题不成立** |
28
+ | 项目规范已写死「不加新依赖」 | `docs/visual-refinement-spec.md` §1 第 3 条 | 同上,只剩"选哪种画法",见 Q4 |
29
+ | 空组文案「完成率暂无数据」由 `total=0` 触发 | 字符串 `src/client.ts:31`(中文)/`:191`(英文);分支 `1671-1673` | 不需要问"为什么已完成是 0/0" |
30
+
31
+ ---
32
+
33
+ ## 2. 阻塞问题(这 3 题答完才能开工)
34
+
35
+ ### Q1【阻塞·确认性】圈选对象确认
36
+
37
+ 请确认三处红圈指的是下面这三处(截图为 440 CSS px 宽移动端视口,DPR 3):
38
+
39
+ | 圈 | 复述内容 | 源码 |
40
+ |---|---|---|
41
+ | ① | 计划卡「dsh 插件多通道版本发布一致性方案…」折叠行里的 **「本计划 0/8 做好了」+「0 卡住了」** | `src/client.ts:1356-1361` |
42
+ | ② | 计划卡「核查 1.1.9 是否已进入 CDN 插件索引」折叠行里的 **「本计划 0/4 做好了」+「0 卡住了」** | 同上 |
43
+ | ③ | 「已完成」组头的 **「未完成 0 / 已完成 0(完成率暂无数据)」** + 空态 **「还没有完成的任务」** | `src/client.ts:1671-1673`、`1698`、`1732` |
44
+
45
+ - **候选答案**:`Q1 = 是` / `Q1 = 不是,实际圈的是 ____`(请描述或重发截图)
46
+ - **影响**:答「不是」则全部落点需重新定位,T1/T2 结论作废。
47
+ - **备注(T1 §8.1 遗留)**:该截图未随任务消息下发,按时间 + 内容匹配判定归属。这是本问题存在的唯一理由。
48
+
49
+ ### Q2【阻塞】"一眼看到"到底要看到什么?(本题决定图形语义)
50
+
51
+ **关键发现**:截图中两个计划的完成数都是 **0**(0/8、0/4),而顶部显示「2 正在做」。
52
+ **在这种情况下,把百分比放大到 24px 仍然是「0%」「0%」——照样不醒目。**
53
+ 所以必须先定"醒目"指的是哪一种信息:
54
+
55
+ | 候选 | 用户一眼看到的 | 数据来源 | 代价 |
56
+ |---|---|---|---|
57
+ | **2A 只看比例** | 大号百分比 + 环 + 加宽的可见条 | `session.stats`,`percent = round(done/total*100)`(`src/client.ts:1347`) | 最省事;但 0% 场景下一屏仍是「0%」,**大概率仍会被判定为不醒目** |
58
+ | **2B 只看"现在在做什么"** | 进行中的子任务标题 / 部门 / 第几步(如「正在做:核对类型 · 工程部 · 第 2/3 步」) | `session.statuses[]` 里 `status==='inProgress'` 的 `title / department / progress`(类型见 `src/plan.ts:1111`、`1128`) | 信息量大、0% 时也**必有内容**可看;但需新增一行文字,卡片折叠行会变高 |
59
+ | **2C 两者都要:比例为主 + 当前步骤为辅(推荐)** | 环 + 大号百分比 + 一行「正在做:…」;无进行中项时降级为「尚未开始」 | 两者都读 | 实现量最大,但**唯一能同时满足"比例感"与"0% 也不空白"的方案** |
60
+
61
+ - **影响**:选 2A 只能改样式;选 2B/2C 必须动渲染逻辑并新增文案键(`src/client.ts` 的 `LOCALE.zh`/`en`,如 `:31`、`:191` 所在对象)。
62
+ - 补充事实:`stats.progress` 是**加权**进度,`done/total` 是**计数**,两者不等价(T1 §4)。请确认比例以 `done/total` 为准(现状即如此),不要改成 `stats.progress`——否则会出现"进度条 70% 但 0 个做好"(1.4.3 修的正是这类缺陷)。
63
+
64
+ ### Q3【阻塞】图形放在哪里?(与既有决策 B 正面冲突,必须拍板)
65
+
66
+ **冲突事实**:`CHANGELOG.md:96` 记录「首屏看不到任务卡(已按用户选择 B 修完)」,
67
+ `src/client.ts:1962-1966` 的注释写明总览块与两张图表**都被下移到两组之后**,
68
+ 目的是让打开面板第一屏直接是「进行中」任务卡。现在要求"画圈区醒目",等于要求图表回到首屏。
69
+
70
+ | 候选 | 做法 | 首屏取舍 | 推翻决策 B? |
71
+ |---|---|---|---|
72
+ | **3A 只升级折叠头(推荐)** | 卡片折叠行里的 54×5px 迷你条 → 可见轨道 + 大号百分比(必要时加内联小环);图表仍留在两组之后 | 首屏仍是任务卡,但**每张卡自带图形进度**,不需要滚动就能看到比例 | 否 |
73
+ | **3B 只把总览块上移** | `Donut` + `TaskBars`(`src/client.ts:1963-1965`)移回统计条下方(`1947-1952` 之后) | 与 1.4.2 修掉的问题**原样复发**:首屏被总览挤占,任务卡掉到第二屏 | 是 |
74
+ | **3C 两者都做** | 折叠头升级 + 统计条下方加一条细的全局总进度条(约 40–56px 高) | 首屏多占一条细条,仍能看到任务卡;全局与单卡两级比例都可见 | 部分(只增加一条细条) |
75
+
76
+ - **候选答案**:`Q3 = 3A` / `3B` / `3C`
77
+ - **影响**:3A 改动集中在 `src/client.ts:621-630`(样式)+ `1356-1361`(结构);3C 还需新增一个组件并调整 `1947-1952` 与 `1957-1969` 的渲染顺序。
78
+ - **几何约束(已实测源码)**:折叠按钮 `min-height: 44px; gap: 10px; padding: 7px 10px`(`src/client.ts:749-760`),
79
+ 行内已放 chevron + 标题 + meta + badge。**32px 以内的内联环不撑高行高**;超过 32px 会挤压标题(440px 窄屏尤甚)。
80
+
81
+ ---
82
+
83
+ ## 3. 非阻塞问题(不答就按"推荐"执行,不耽误开工)
84
+
85
+ ### Q4【非阻塞】图形用哪种画法(不是"能否引入依赖")
86
+
87
+ - **4A 内联 SVG(推荐)**:复用已有零依赖图形资产——`GroupRing`(`src/client.ts:1609-1644` 双圆环)、`Donut`(`1736`)、`TaskBars`(`1800`)。
88
+ 优点:首屏不加载 vendor、无 CLS、SSR 安全、主题变量自动生效。缺点:复杂图表能力有限(本次不需要)。
89
+ - **4B Chart.js canvas**:`GroupCharts` 动态加载 `/dsh-workplan/vendor/chart.umd.js`(`src/client.ts:1425` 起),已有 fallback 策略。
90
+ 优点:动画与图例现成。缺点:多张卡 = 多个 canvas,440px 窄屏下性能与首屏 CLS 风险更高。
91
+ - **默认**:`Q4 = 4A`。若要 4B,请说明理由(`docs/visual-refinement-spec.md` §11.1 记录过"零依赖 vs Chart.js"的分歧)。
92
+
93
+ ### Q5【非阻塞】圈③ 空态怎么处理
94
+
95
+ 现状:`total=0` 时组头仍渲染「未完成 0 / 已完成 0(完成率暂无数据)」,没有信息量。
96
+
97
+ - **5A(推荐)**:`total=0` 时**不渲染摘要句**,只保留组标题 + 右侧环「—」+ 空态「还没有完成的任务」。
98
+ - **5B**:改成极简「暂无计划」,保留一行但去掉 0/0 与"暂无数据"。
99
+ - **5C**:完全不动(只改①②)。
100
+ - **默认**:`Q5 = 5A`。
101
+ - **确定的影响(已查测试)**:`tests/group-summary.test.ts:189` 硬断言 `未完成 0 / 已完成 0(完成率暂无数据)`,
102
+ 以及 `:190` 的 `data-percent="none"`、`:191` 的 `dsh-wp-group-ring-label">—<`。选 5A/5B **必须同步改该测试**,否则 `npm test` 必红。
103
+
104
+ ### Q6【非阻塞】范围边界 + 版本号
105
+
106
+ - **6A 版本号(推荐 `1.5.0`)**:本次新增可视化组件/新图形语义,按语义是 feature。
107
+ 若您认为只是视觉修复,则 `1.4.4`。**无论哪个都必须递增**(当前 1.4.3:`package.json:3` + `src/host.ts:328`,两处都要改)。
108
+ - **6B 顶部 5 格统计条**(`src/client.ts:1947-1952`):**默认不动**(未被圈选,避免扩大范围)。若要让它显示总完成率,请说"改统计条"。
109
+ - **6C 已知越界色**:`docs/visual-refinement-spec.md` §11.3 记录 `.dsh-wp-stat--done/active` 的 18px 数字仍用 `#0ea5e9`/`#f97316`(2.77/2.80:1,低于 4.5:1),且 `tests/status-colors.test.ts` 锁定了这些值。**默认不动,单独立项**。
110
+ - **6D 其他被测试锁定的点(改到时要同步)**:`tests/status-colors.test.ts:14` 断言 `.dsh-wp-mini-fill--done` 使用 `var(--dsh-wp-done)`——若折叠头重做并改类名,此测试需同步。
111
+
112
+ ---
113
+
114
+ ## 4. 最小回复模板(用户只需回一行)
115
+
116
+ ```
117
+ Q1=是;Q2=2C;Q3=3A;其余按推荐
118
+ ```
119
+ 或直接:**「全部按推荐」**(= Q1 是、Q2 2C、Q3 3A、Q4 4A、Q5 5A、Q6 1.5.0 且不动统计条)。
120
+ 收到这行即可开工,无需再等。
121
+
122
+ ---
123
+
124
+ ## 5. 若"全部按推荐",施工范围预览(仅供预览,未实施)
125
+
126
+ 1. `src/client.ts:621-630`:迷你条改可见轨道(对比度 ≥3:1)+ 加高至 8px;新增 32px 内联环样式。
127
+ 2. `src/client.ts:1356-1361`:meta 由「文本 + 迷你条」改为「内联环 + 大号百分比 + 极简计数」,百分比**脱离 `title` 属性变成可见文字**。
128
+ 3. 依 Q2=2C:新增一行「正在做:{title} · {department}」;无进行中项时降级为「尚未开始」,取值自 `statuses[].status === 'inProgress'`。
129
+ 4. `src/client.ts:1671-1673` + `:1698`:组头 `total=0` 时不渲染摘要句(Q5=5A)。
130
+ 5. 文案键:中文 `src/client.ts:31` 区、英文 `:191` 区,各新增(不删旧键,避免其他引用断链)。
131
+ 6. 测试:同步 `tests/group-summary.test.ts`、`tests/status-colors.test.ts`;新增「0% 时轨道可见」「百分比为可见文本」断言。
132
+ 7. `package.json:3` + `src/host.ts:328` → `1.5.0`;`CHANGELOG.md` 顶部加 1.5.0 段。
133
+ 8. 备份:插件目录**无 `.git`**,改前先用 `.backups/` 全量打包(现存 6 个文件,其中 4 个 `.tar.gz` 快照,最新为 `v1.4.2-pre-derived-counts-20261028-123136.tar.gz`)。
134
+
135
+ ---
136
+
137
+ ## 6. 需要主 Agent 执行、本子任务无权做的步骤
138
+
139
+ 1. 向用户提出 Q1–Q3(阻塞)并收集回答;Q4–Q6 可只给默认。
140
+ 2. 收到回答后派发施工子任务(含改测试与构建 `npm run build`)。
141
+ 3. 构建后**重启 DSH Web / 刷新页面**使 `client.js` 生效(插件以 `link:` 挂载,见 T1 §1)。
142
+ 4. 目视验收截图(本会话无法截图、无法重启)。
143
+
144
+ ---
145
+
146
+ ## 7. 复核命令
147
+
148
+ 带注释版:
149
+
150
+ ```bash
151
+ cd <repo>
152
+
153
+ # 1) 三处画圈对应的源码
154
+ sed -n '1356,1361p' src/client.ts # ①② 卡片 meta
155
+ sed -n '1671,1673p;1698p;1732p' src/client.ts # ③ 组摘要 + 空态
156
+
157
+ # 2) 0% 不可见的根因:轨道与按钮同为 bg-layer-2
158
+ sed -n '621,630p;749,762p' src/client.ts
159
+
160
+ # 3) 与既有决策 B 的冲突点
161
+ sed -n '1957,1972p' src/client.ts
162
+ grep -n "选择 B" CHANGELOG.md
163
+
164
+ # 4) 测试锁定的文案与类名
165
+ grep -n "完成率暂无数据\|data-percent" tests/group-summary.test.ts
166
+ grep -n "dsh-wp-mini-fill--done" tests/status-colors.test.ts
167
+
168
+ # 5) 版本号位置(改版本时两处都要动)
169
+ node -e "console.log(require('./package.json').version)"
170
+ grep -n "version: '1.4.3'" src/host.ts
171
+
172
+ # 6) 类型检查(不改产物)
173
+ npm run check
174
+ ```
175
+
176
+ 无注释、可直接复制版:
177
+
178
+ ```bash
179
+ cd <repo>
180
+ sed -n '1356,1361p' src/client.ts
181
+ sed -n '1671,1673p;1698p;1732p' src/client.ts
182
+ sed -n '621,630p;749,762p' src/client.ts
183
+ sed -n '1957,1972p' src/client.ts
184
+ grep -n "选择 B" CHANGELOG.md
185
+ grep -n "完成率暂无数据\|data-percent" tests/group-summary.test.ts
186
+ grep -n "dsh-wp-mini-fill--done" tests/status-colors.test.ts
187
+ node -e "console.log(require('./package.json').version)"
188
+ grep -n "version: '1.4.3'" src/host.ts
189
+ npm run check
190
+ ```
191
+
192
+ ---
193
+
194
+ ## 8. 未验证 / 本子任务边界
195
+
196
+ 1. **未目视验证**:本会话不能重启 `dsh web`、不能截图,无法证明截图对应的运行实例与 `1.4.3` 源码逐字节一致(承 T1 §8.4)。
197
+ 2. **未执行构建/测试**:`npm test` 未在本子任务运行(需 `npm run build` 写产物,超出"只澄清"的范围)。测试断言结论均来自**直接阅读测试源码**。
198
+ 3. **未改动任何文件**:除本澄清文档与 T1 报告外,源码零改动;版本仍 1.4.3。
199
+
200
+ ---
201
+
202
+ ## 9. 本子任务验收记录(2026-10-28)
203
+
204
+ | 验收项 | 命令 | 结果 |
205
+ |---|---|---|
206
+ | 类型检查不因本次工作失败 | `npm run check`(`tsc -p tsconfig.json --noEmit`) | **EXIT=0**,无任何 tsc 报错 |
207
+ | 源码零改动(哈希与 T1 记录一致) | `shasum -a 256` | `package.json`=8f865285 ✓、`src/client.ts`=62aa22fe ✓、`client.js`=0c3ffd34 ✓、`lib/host.js`=f87b9eab ✓(`src/host.ts`=8c1bc4e9,T1 未记录,本次为基线) |
208
+ | 版本未变 | `node -e "console.log(require('./package.json').version)"` | `1.4.3` |
209
+ | 新增文件 | — | 仅本文件 `docs/progress-visualization-clarify-20261028.md`(198 行) |
210
+
211
+ > 结论:本子任务**只产出澄清问题,未施工**。等主 Agent 收集 Q1–Q3 答案后,方可派发施工。