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.
- package/CHANGELOG.md +68 -0
- package/README.en.md +41 -2
- package/README.md +40 -2
- package/SECURITY.md +109 -0
- package/docs/SBOM.md +113 -0
- package/docs/cc/AVA-VULNERABILITY-ANALYSIS.md +97 -0
- package/docs/cc/CC-2026-ASSESSMENT.md +254 -0
- package/docs/cc/SECURITY-TARGET.md +239 -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-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 +5 -16
- package/lib/runtime.js +37 -1
- package/package.json +4 -2
- package/src/host.ts +6 -15
- package/src/runtime.ts +39 -1
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
# dsh-workplan 1.4.3 修复报告:「正在做」数字与真实状态不一致
|
|
2
|
+
|
|
3
|
+
> 结论先行:用户报告的现象是**真实缺陷**,且不是一处,而是同一根因下的 **4 处**逻辑分裂
|
|
4
|
+
> (D1 计数缓存冻结、D2 同一报文自相矛盾、D3 重置绕过状态机、D4 同一失败两种进度语义)。
|
|
5
|
+
> 根因是**同一个计划存在两套真相源**:实时状态列表 `record.statuses` 与缓存在记录上的
|
|
6
|
+
> `record.stats`。1.4.3 把计数改为**纯派生**(`derivePlanSnapshot`),结构上让「同一报文内
|
|
7
|
+
> 两套数字」无法再被表示出来,并加了不变量测试与真实会话回放作为护栏。
|
|
8
|
+
|
|
9
|
+
- 插件:`<repo>`
|
|
10
|
+
- 版本:1.4.2 → **1.4.3**(补丁级:仅缺陷修复 + 内部重构,对外载荷字段未变)
|
|
11
|
+
- 报告日期:2026-10-28
|
|
12
|
+
- 证据文件:本文 + `docs/repro-count-inconsistency.md` + `docs/defect-report-count-inconsistency.md`
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 一、用户报告与截图对应
|
|
17
|
+
|
|
18
|
+
| 截图 | 显示 | 真实状态 | 判定 |
|
|
19
|
+
|---|---|---|---|
|
|
20
|
+
| 图 1 顶部汇总 | 2 个任务 / 29 件工作 / 18 做好 / **0 正在做** | 同一时刻至少 1 个子任务处于 `in_progress` | 缺陷(D1) |
|
|
21
|
+
| 图 1 计划卡 | 该计划 3/14 做好(21%),组头仍归入「进行中」 | 一致(21% = 3/14) | 正常 |
|
|
22
|
+
| 图 2 第 3 步 | 0/3 做好,徽标 **正在做** | 阶段内确有子任务在跑 | 正常(阶段徽标读状态列表) |
|
|
23
|
+
| 图 3 具体工作 1 | **正在做 · 进度 10%** | 子 Agent 刚绑定,`progress: 10` 是启动即写入的真实值 | **正常行为,不是缺陷**(此前曾被误判,特此纠正) |
|
|
24
|
+
|
|
25
|
+
真正互相矛盾的是:**顶部/卡片数字读缓存**,**阶段与子任务徽标读实时状态列表**。缓存只在
|
|
26
|
+
「整批子任务跑完」后刷新,所以一批任务运行期间,看板会在同一屏同时显示「0 正在做」与「正在做」。
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 二、证据链(全部可复现)
|
|
31
|
+
|
|
32
|
+
### 2.1 真实会话回放(用户报告的原始会话)
|
|
33
|
+
|
|
34
|
+
`scripts/replay-reported-session.ts` 直接读取
|
|
35
|
+
`~/.dsh/sessions/--Users-open-Documents-Stocks--/session-91ec3273-3277-49ff-87b3-7ce4722f29e0/session.v4.jsonl.zstd`,
|
|
36
|
+
把其中**每一条** workplan 结果报文解析出来,用修复后的算法重算同一份 `statuses`,与 1.4.2 当时写下的数字对照:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
workplan 结果报文: 7 条;其中 1.4.2 发出时与状态列表不一致: 6 条
|
|
40
|
+
其中「待做却带着旧进度/旧子 Agent」的报文(D3 残留): 6 条
|
|
41
|
+
|
|
42
|
+
seq done inProgress pending progress(1.4.2→1.4.3) 不一致字段
|
|
43
|
+
195 5 0 9 43→36 progress
|
|
44
|
+
247 6 0 6 58→50 progress
|
|
45
|
+
263 7 0 5 67→58 progress
|
|
46
|
+
292 8 0 4 75→67 progress
|
|
47
|
+
308 9 0 3 83→75 progress
|
|
48
|
+
325 11 0 1 100→92 progress
|
|
49
|
+
392 12 0 0 100→100 —
|
|
50
|
+
|
|
51
|
+
D3 证据(1.4.2 把预算暂停项重置为 pending 却留着旧字段):
|
|
52
|
+
seq=195: T6(progress=100, childId) seq=247: T7(progress=100, childId)
|
|
53
|
+
seq=263: T8(progress=100, childId) seq=292: T9(progress=100, childId)
|
|
54
|
+
seq=308: T10(progress=100, childId) seq=325: T12(progress=100, childId)
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
注意 seq=325 那条:`done=11 / pending=1`,进度却写 **100%**。这正是截图图 1 计划卡
|
|
58
|
+
「未完成 11 / 已完成 3」与「21%」并存的同源问题:**进度与完成数来自不同口径**。
|
|
59
|
+
|
|
60
|
+
### 2.2 现象级复现(并发波中途读取看板载荷 + 真实 `client.js` 渲染)
|
|
61
|
+
|
|
62
|
+
`scripts/repro-inconsistent-counts.ts` 构造三组真实运行时状态:
|
|
63
|
+
|
|
64
|
+
- 场景 A(并发波进行中):真实状态 `done 2 / 正在做 1 / 待做 0`;1.4.2 载荷写出
|
|
65
|
+
`done 1 / 正在做 0 / 待做 2`、进度 33%,而真实进度 70%。同一载荷里
|
|
66
|
+
`stats.inProgress = 0` 与 `departments.design.inProgress = 1` 同时存在(D2)。
|
|
67
|
+
- 场景 B(预算用尽重置):`status = pending` 却带 `progress = 100`、`childId`、`startedAt`(D3)。
|
|
68
|
+
- 场景 C(blocked 计划 resume 后):`stats.blocked = 2`,而实际 `blocked = 0`(D1 的另一面)。
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## 三、根因(代码级)
|
|
73
|
+
|
|
74
|
+
| 编号 | 位置 | 缺陷 |
|
|
75
|
+
|---|---|---|
|
|
76
|
+
| **D1** | `src/runtime.ts:361-366` `writeSubtaskStatus()` | 只写 `record.statuses`,**不写** `record.stats` |
|
|
77
|
+
| **D1** | `src/runtime.ts:760`(1.4.2 行号) | `record.stats = computeStats(...)` 只在**整批子任务全部结束之后**执行,批次运行期间缓存冻结 |
|
|
78
|
+
| **D1** | `src/runtime.ts:838`(1.4.2) | `const stats = record.stats ?? computeStats(statuses)`:`stats` 恒已初始化,回退分支**永不触发**,恒发旧值 |
|
|
79
|
+
| **D2** | `src/runtime.ts:843-857`(1.4.2) | 同一函数内 `stats` 取自缓存、`departments` 由 `statuses` 现场聚合 → 一个响应两套口径 |
|
|
80
|
+
| **D3** | `src/runtime.ts:779-790`(1.4.2) | 预算用尽重置用裸对象展开 `{...item, status:'pending', progress: item.progress ?? 0}`,绕过 `applyStatus()` 的伴随字段清理 |
|
|
81
|
+
| **D4** | `src/runtime.ts:807-818`(1.4.2) | 异常收敛写 `progress: item.progress ?? 0`,而其余 4 处 blocked 写入点写 `progress: 100` |
|
|
82
|
+
|
|
83
|
+
连带的数据口径错误:1.4.2 的 `computeStats()` 直接对每条 `item.progress` 求平均,**不看 status**,
|
|
84
|
+
所以被重置为 pending 却残留 100 的条目会把总进度抬到 100%(12 项里 11 项完成也报 100%)。
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 四、其它同类模式的全面审查结论
|
|
89
|
+
|
|
90
|
+
用户问「是否还有多处逻辑混乱」。答案是:**数字层面已全部收敛,另有一处「状态缓存」经审查不是缺陷**。
|
|
91
|
+
逐项如下(每项都读过代码,不是推测):
|
|
92
|
+
|
|
93
|
+
| 数字/状态出现的位置 | 数据来源(1.4.2) | 1.4.3 结论 |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| 顶部汇总四格(任务数/工作量/完成/正在做) | 各计划 `stats` 求和(`src/client.ts:1950-1952`) | 单一来源 ✅ |
|
|
96
|
+
| 计划卡数字(总数、已完成、正在做、进度环) | `session.stats`(`src/client.ts:1339-1377`) | 单一来源 ✅ |
|
|
97
|
+
| 阶段徽标「N/M 做好」 | 该阶段 `items` 的状态计数(`src/client.ts:1250-1267`) | 与 `stats` 同源(同一 `statuses` 数组派生)✅ |
|
|
98
|
+
| 子任务进度条 | 子任务自身 `progress`(`src/client.ts:1231`) | 同源 ✅ |
|
|
99
|
+
| 部门分布(design/engineering/qa…) | 1.4.2 现场聚合,与缓存 `stats` 不同源 | 现由同一次遍历产出 ✅ |
|
|
100
|
+
| 甜甜圈/条形图/统计条 | `totals` ← 各计划 `stats` | 单一来源 ✅ |
|
|
101
|
+
| 工具返回 JSON(`dispatch`/`update`/`cancel`) | 1.4.2 部分读 `record.stats`,部分读状态 | 全部改为同一次派生 ✅ |
|
|
102
|
+
| 结果消息摘要「完成 x/y」 | `result.stats` | 派生 ✅ |
|
|
103
|
+
| 结果消息载荷 `stats` | 1.4.2 `record.stats` | 派生 ✅(并新增端到端守卫测试) |
|
|
104
|
+
| `record.phase`(计划阶段) | 缓存,但有补偿:批次结束/异常/暂停/取消各出口都会重算 `planPhase`;回放时用随载荷下发的 `phase` 还原 | **非计数**,未发现可观测矛盾;保留为设计注意点(见 §8) |
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 五、修复内容
|
|
109
|
+
|
|
110
|
+
### 5.1 单一派生源(核心)
|
|
111
|
+
|
|
112
|
+
`src/plan.ts` 新增(全部 TypeScript):
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
SubtaskStatus / StatusEntry / Stats / DepartmentSummary / PlanSnapshot
|
|
116
|
+
isSubtaskStatus / clampProgress / normaliseStatusEntry / normaliseStatuses
|
|
117
|
+
deriveAggregates / derivePlanSnapshot / computeStats(别名, @deprecated) / aggregateInvariantViolations
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
规则固定在一处:未知状态降级 `pending`;`pending` 强制 `progress=0` 且清空
|
|
121
|
+
`childId/startedAt/finishedAt`;`done` 强制 100;进度加权 done=100、blocked/in_progress=自身
|
|
122
|
+
(clamp 0–100)、pending=0;无 `subtaskId` 的条目丢弃;部门在同一次遍历内聚合。
|
|
123
|
+
|
|
124
|
+
`src/runtime.ts`:
|
|
125
|
+
|
|
126
|
+
- 删除**全部** `record.stats` 写入/读取(16 处),`grep 'record.stats'` 只剩一条注释;
|
|
127
|
+
- `serialisePlan` / `buildRoundResult` / `dispatchTool` / `updateStatus` / `cancelPlan`
|
|
128
|
+
统一「先派生一次,再用同一快照填 `statuses`、`stats`、`departments`、`phase`」;
|
|
129
|
+
- 预算用尽重置改为逐项 `applyStatus(..., { status: 'pending', error: ... })`;
|
|
130
|
+
- 异常收敛分支 blocked 统一 `progress: 100`。
|
|
131
|
+
|
|
132
|
+
### 5.2 状态机收口
|
|
133
|
+
|
|
134
|
+
`applyStatus()` 的 `pending` 分支清空 `progress/startedAt/finishedAt/childId`(同一 patch 里显式传入的值优先,
|
|
135
|
+
所以「预算用尽」的原因仍能保留在 `error` 里)。
|
|
136
|
+
|
|
137
|
+
### 5.3 构建卫生(本次实际踩到并修掉的 error)
|
|
138
|
+
|
|
139
|
+
`npm test` 曾因旧编译物残留报
|
|
140
|
+
`ERR_MODULE_NOT_FOUND ... dist-tests/src/state.js`(exit 2)。已修:
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
"clean": "rm -rf dist dist-tests",
|
|
144
|
+
"build": "rm -rf dist && tsc -p tsconfig.json && cp ... && cp dist/client.js client.js",
|
|
145
|
+
"test": "npm run build && rm -rf dist-tests && tsc -p tsconfig.test.json && node --test dist-tests/tests/*.test.js"
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### 5.4 移出失控产物(防止再造双真相源)
|
|
149
|
+
|
|
150
|
+
- 子 Agent 遗留、未被任何生产代码引用的 `src/state.ts`、`tests/state-machine.test.ts`
|
|
151
|
+
→ `docs/design-proposals/`(它与 `applyStatus` 重复实现同一语义,接入即再造两套状态机);
|
|
152
|
+
- `docs/design-derived-counts.reference.ts`(设计稿副本)在设计落地后**删除**,
|
|
153
|
+
`scripts/prove-derived-counts.ts` 改为直接导入 `src/plan.ts`,杜绝「设计与实现各算一套」。
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## 六、验证证据
|
|
158
|
+
|
|
159
|
+
| 验证 | 命令 | 结果 |
|
|
160
|
+
|---|---|---|
|
|
161
|
+
| 类型检查 | `npm run check` | exit 0 |
|
|
162
|
+
| 单元/回归测试 | `npm test` | **90 / 90 通过**(79 原有 + 11 新增) |
|
|
163
|
+
| 修复前行为复现 | `node --experimental-strip-types scripts/repro-inconsistent-counts.ts` | 12 条 check 失败 —— **符合预期**,脚本默认断言缺陷存在 |
|
|
164
|
+
| 修复后不变量 | 同脚本 `--expect-fixed` | **exit 0,全部 PASS**(顶部 2/1、卡片 70%/正在做 1/待做 0、甜甜圈 67;暂停项 progress=0、childId=null;resume 后 blocked=0) |
|
|
165
|
+
| 设计证明 | `node --experimental-strip-types scripts/prove-derived-counts.ts` | **13 条断言 PASS**,含 500 组随机状态序列的不变量与幂等检查 |
|
|
166
|
+
| 真实会话回放 | `node --experimental-strip-types scripts/replay-reported-session.ts <会话日志> --expect-fixed` | **exit 0**:7 条历史报文派生后全部满足不变量;并证明其中 6 条 1.4.2 的显示值确实与状态列表不符 |
|
|
167
|
+
|
|
168
|
+
新增测试 `tests/derived-counts.test.ts` 的关键设计:**变异测试**——手工把
|
|
169
|
+
`stats.done + 1`、`total + 1`、`pending - 1`、`progress = 101`、部门 `done/total` 改坏,
|
|
170
|
+
不变量检查器必须报错;否则测试只描述现状、挡不住回归。另有结构性守卫
|
|
171
|
+
`assert.equal('stats' in record, false)`,有人把缓存字段加回记录就会立刻失败。
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## 七、版本与回滚
|
|
176
|
+
|
|
177
|
+
- `package.json`、`src/host.ts`、重建后的 `lib/host.js` / `dist/host.js` 均为 **1.4.3**(四处交叉核对一致)。
|
|
178
|
+
- 对外载荷字段不变:`statuses` / `stats` / `departments` 同名同义,工具 JSON Schema 未改。
|
|
179
|
+
- 历史结果消息仍可回放读取(1.4.2 写下的数字保持原样,不被改写)。
|
|
180
|
+
- 回滚:`.backups/v1.4.2-pre-derived-counts-20261028-123136.tar.gz`(改动前完整快照),
|
|
181
|
+
`tar -xzf` 后 `npm test` 即回到 1.4.2 的 79 项通过。
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## 八、防复发机制与遗留说明
|
|
186
|
+
|
|
187
|
+
1. **结构上不可表示**:`stats`/`departments`/`statuses` 只能由 `derivePlanSnapshot` 一次产出,
|
|
188
|
+
报文里再想手工拼一个数进去,端到端守卫测试会失败。
|
|
189
|
+
2. **不变量 I1–I7**:四状态之和 = total、进度 0–100、pending 不携带进度/子 Agent、
|
|
190
|
+
done 恒 100、subtaskId 唯一非空、部门合计 = 总量。
|
|
191
|
+
3. **历史数据可自证**:回放脚本让任意一条历史报文都能被判「当时是否自相矛盾」。
|
|
192
|
+
4. **遗留说明(不作夸大)**:`record.phase` 仍是缓存字段。它在批次结束、异常、预算暂停、
|
|
193
|
+
取消四个出口都会重算,回放时又随载荷下发 `phase` 还原,因此本次**未**观察到可复现矛盾;
|
|
194
|
+
它不参与任何计数。若将来要给 phase 也做同样处理,可作为下一轮的独立改进项。
|
|
195
|
+
|
|
196
|
+
## 九、生效方式
|
|
197
|
+
|
|
198
|
+
已安装的运行实例在启动时加载 `lib/*.js`,**需要重启 DSH(或重新加载 `web` profile)才会使用 1.4.3**。
|
|
199
|
+
未重启时,页面仍由旧代码提供服务,旧缺陷会继续存在——这是「改完还没生效」,不是修复失败。
|
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
# 修复报告:计划卡「100% + 正在收尾」并存(1.5.2,2026-10-29)
|
|
2
|
+
|
|
3
|
+
> 一句话:**进度**和**状态**原本不是同一个事实源 —— 进度只数「做完了几项」,
|
|
4
|
+
> 状态却额外要求「结果消息已落盘」这个副作用。用 `dsh_workplan_update` 补完最后
|
|
5
|
+
> 一项时,没有任何代码会写结果消息,于是计划永久停在「正在收尾」,而进度已经是 100%。
|
|
6
|
+
> 1.5.2 让终态只由子任务计数决定,并把同根因的 8 类矛盾一并修掉。
|
|
7
|
+
|
|
8
|
+
- 事故会话:`session-c3852c31-f6cd-4fc5-8cff-d8a3932e9feb`
|
|
9
|
+
- 计划:`wp-dc44c4a2-3fce-4e78-a2df-1cf6da76eeb2`「159667工业母机ETF走势预判·证据驱动的分期推演计划」
|
|
10
|
+
- 截图现象:`14/14`、环形 `100%`、「都做完了」、胶囊「正在收尾」、卡片仍在「进行中」组
|
|
11
|
+
- 受影响版本:`1.5.1` 及更早
|
|
12
|
+
- 修复版本:`1.5.2`
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. 证据链(每一步都可复核)
|
|
17
|
+
|
|
18
|
+
### 1.1 用户截图那一轮到底发生了什么
|
|
19
|
+
|
|
20
|
+
直接解压会话日志(多帧 zstd,需用系统 `zstd -dc`;Node 的 `zstdDecompressSync`
|
|
21
|
+
只解第一帧,会得到一份被截断的日志):
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
zstd -dc ~/.dsh/sessions/--Users-open-Documents-Stocks--/session-c3852c31-f6cd-4fc5-8cff-d8a3932e9feb/session.v4.jsonl.zstd \
|
|
25
|
+
| nl -ba | sed -n '186,196p;260,276p'
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
事实(与截图逐项对得上):
|
|
29
|
+
|
|
30
|
+
| 位置 | 事件 | 内容 |
|
|
31
|
+
| --- | --- | --- |
|
|
32
|
+
| `seq 189`(文件第 191 行) | 最后一条 `workplan-result` | `stats.total=14, done=12, pending=2, progress=86`,`phase: "paused"`,`errors`:本轮预算(20 分钟)已到,已完成 12/14 |
|
|
33
|
+
| `seq 263` / `seq 269` | 主 Agent 直接调 `dsh_workplan_update` | 把 `T13`、`T14` 标为 `done`(后一条带 `note`:「由主 Agent 承接完成排版与自检(未再派发设计部门 Agent)」) |
|
|
34
|
+
| `seq 276` | `turn/end`(2026-10-28T15:12:28Z) | 会话结束,**此后再没有新的 `workplan-result` 事件** |
|
|
35
|
+
|
|
36
|
+
于是 `statuses` 变成 14/14 全 `done`,`stats.progress` 由计数派生为 100;
|
|
37
|
+
但 `phase` 走的是另一条路:
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
updateStatus() → record.phase = planPhase(record.statuses) // 不带 resultSeen
|
|
41
|
+
planPhase() → all done ? (resultSeen ? 'done' : 'integrating') // 于是 'integrating'
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
而 `resultSeen` 只可能由「派发轮次末尾写入的结果消息」置真 —— 这一轮根本没有派发,
|
|
45
|
+
所以它永远不会变成 `done`。**与截图完全一致。**
|
|
46
|
+
|
|
47
|
+
### 1.2 同一个会话「刷新前后翻转」
|
|
48
|
+
|
|
49
|
+
同一份事件,`reconstructFromSession()` 能找到 `seq 189` 的结果消息,于是
|
|
50
|
+
`resultSeen = true`,回放得到 `done`。也就是说:
|
|
51
|
+
|
|
52
|
+
- 实时缓存:`integrating`(正在收尾)
|
|
53
|
+
- 刷新页面后:`done`(已完成)
|
|
54
|
+
|
|
55
|
+
这不是观感问题,而是两条链路对「完成」的定义不同。
|
|
56
|
+
|
|
57
|
+
### 1.3 代码位置(修复前)
|
|
58
|
+
|
|
59
|
+
| 位置 | 代码 | 含义 |
|
|
60
|
+
| --- | --- | --- |
|
|
61
|
+
| `src/plan.ts:1377` | `if (statuses.every(done)) return resultSeen ? 'done' : 'integrating'` | 完成被绑在「结果消息」这个副作用上 |
|
|
62
|
+
| `src/runtime.ts:1209`(`updateStatus`) | `record.phase = planPhase(record.statuses)` | 丢掉了 `resultSeen`,把 done 打回 integrating |
|
|
63
|
+
| `src/runtime.ts:868`(`serialisePlan`) | `let phase = record.phase ?? planPhase(statuses)` | 内存 phase 优先于计数派生值 |
|
|
64
|
+
| `src/runtime.ts:1415`(派发尾部) | `if (record.resultWritten && allDone) record.phase='done'` | 终态只由「结果写入成功」触发;写入抛错就永远停在 integrating |
|
|
65
|
+
| `src/client.ts:1475` | `percent = Math.round(done / total * 100)` | 环只看计数 |
|
|
66
|
+
| `src/client.ts:1557` | `counts.done === counts.total → 「都做完了」` | 再一套完成判断 |
|
|
67
|
+
| `src/client.ts:1667` | `state = percent >= 100 ? 'done'` | 第三套完成判断 |
|
|
68
|
+
| `src/client.ts:2286` | `phase === 'done' ? finished : live` | 分组看 phase,于是 100% 的卡留在「进行中」 |
|
|
69
|
+
|
|
70
|
+
### 1.4 不是四舍五入造成的假 100%
|
|
71
|
+
|
|
72
|
+
计划最多 15 个子任务(`MAX_SUBTASKS = 15`),13/14 显示 93%、14/15 显示 93%,
|
|
73
|
+
不存在「没做完却四舍五入成 100%」。另有一个**真实的**同类缺陷是**加权口径**:
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
11 done + 1 blocked@95 → 环形进度 92%(done/total),总体进度 100%(progress 加权)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
这属于同一族问题(同一张卡两个百分比各说各话),一并修复。
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 2. 修复决策
|
|
84
|
+
|
|
85
|
+
**只保留一根轴:终态由子任务计数决定。** 理由:
|
|
86
|
+
|
|
87
|
+
1. 「结果消息是否落盘」是副作用,不是事实。用它决定计划是否完成,任何不走派发轮次的
|
|
88
|
+
完成路径(`update` 工具、人工交接、结果消息写入失败)都会漏掉;
|
|
89
|
+
2. 反过来「封顶 99%」的方案会制造新矛盾:`14/14` 却显示 99%,仍与「都做完了」冲突;
|
|
90
|
+
3. 计划追踪器的语义是「计划内的工作是否做完」。合成本身不属于被追踪的子任务,
|
|
91
|
+
进入合成就说明子任务已经清空 —— 此时对读者而言计划已完成。
|
|
92
|
+
|
|
93
|
+
因此新增 `reconcilePhase(phase, statuses)`,作为**唯一**的 phase 对账入口:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
const derived = planPhase(statuses) // 计数派生:全 done → 'done'
|
|
97
|
+
if (derived === 'done') return 'done' // 终态优先
|
|
98
|
+
if (phase === 'done' || phase === 'integrating') return derived // 旧派生值一律重算
|
|
99
|
+
if (phase === 'pending' || phase === 'planning' || phase === 'executing') {
|
|
100
|
+
return derived === 'pending' ? phase : derived
|
|
101
|
+
}
|
|
102
|
+
return phase ?? derived // paused/cancelled/blocked/degraded 有独立事实来源
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## 3. 改动清单
|
|
108
|
+
|
|
109
|
+
### 3.1 `src/plan.ts`
|
|
110
|
+
|
|
111
|
+
- `planPhase(statuses, _resultSeen)`:全部 `done` 时**恒返回 `done`**;参数保留只为兼容。
|
|
112
|
+
- 新增 `reconcilePhase()`(见上)。
|
|
113
|
+
- `deriveAggregates()`:未全部完成时总进度封顶 99(`Math.min(99, raw)`)。
|
|
114
|
+
- `applyStatus()`:`in_progress` 的进度夹紧到 99(「正在做」不允许自称 100%)。
|
|
115
|
+
- `aggregateInvariantViolations(snapshot, phase?)` 新增:
|
|
116
|
+
- **I8**:`done === total` ⟺ `phase === 'done'`(双向);
|
|
117
|
+
- **I9**:全部完成 ⟺ `progress === 100`;
|
|
118
|
+
- **I10**:`in_progress` 的子任务不得 `progress >= 100`。
|
|
119
|
+
|
|
120
|
+
### 3.2 `src/runtime.ts`
|
|
121
|
+
|
|
122
|
+
- `serialisePlan()`:phase 走 `reconcilePhase`;存在不变量违背时载荷附带 `violations`。
|
|
123
|
+
- `updateStatus()`:走 `reconcilePhase`(截图矛盾的直接入口)。
|
|
124
|
+
- 派发尾部:终态晋升不再依赖 `record.resultWritten` 这个副作用。
|
|
125
|
+
- `reconstructFromSession()`:回放与实时同源(刷新前后不再翻转)。
|
|
126
|
+
- `cancelPlan()`:计划已全部完成时改为 no-op(`alreadyDone: true`),消除「100% + 已取消」。
|
|
127
|
+
- 预算到点分支:此刻若已全部完成则记 `done`(防御性,正常循环下不可达)。
|
|
128
|
+
|
|
129
|
+
### 3.3 `src/client.ts`
|
|
130
|
+
|
|
131
|
+
自包含 bundle,不能 `import` `plan.ts`,因此在客户端复刻同一语义,并统一为三个函数:
|
|
132
|
+
|
|
133
|
+
- `planPercent(done, total)` —— 唯一的百分比算式;
|
|
134
|
+
- `planPhaseOf(rawPhase, counts)` —— 唯一的胶囊/分组判定;
|
|
135
|
+
- `planWeightedPercent(stats, counts)` —— 唯一的加权进度算式。
|
|
136
|
+
|
|
137
|
+
卡片环、徽章、分组、分组环、阶段条、会话内联卡、`rank`、`liveBars`、`TaskBars`
|
|
138
|
+
全部改走它们。新增文案:`helpWaitActive`、`helpNoPlan`、`nowRemaining`。
|
|
139
|
+
|
|
140
|
+
### 3.4 测试
|
|
141
|
+
|
|
142
|
+
| 文件 | 变化 |
|
|
143
|
+
| --- | --- |
|
|
144
|
+
| `tests/phase-percent-invariant.test.ts` | 新增 13 例:终态语义、计数封顶、I8/I9 双向、update 补完最后一项、空更新不回退、取消已完成计划、客户端渲染旧载荷 |
|
|
145
|
+
| `tests/completion-semantics.test.ts` | 新增 8 例:`in_progress@100` 夹紧、I10、单任务执行中不再宣布完成、部分完成「还剩 N 项」、0/0 降级不说完成、阶段条只按 done 计宽、阶段卡与「现在」同口径、0% 未开始不再标 active |
|
|
146
|
+
| `tests/plan.test.ts` | 原先断言「全 done → integrating」改为 `done`,并补 `reconcilePhase` 断言 |
|
|
147
|
+
| `tests/workplan-budget-pause.test.ts` | 三处「全部完成后仍 integrating」的期望值改为 `done` |
|
|
148
|
+
| `tests/derived-counts.test.ts` | blocked 用例的总进度期望由 100 改为 99(与封顶规则一致) |
|
|
149
|
+
|
|
150
|
+
> 说明:1.5.1 及更早的测试把**矛盾本身**写成了期望值
|
|
151
|
+
> (`tests/plan.test.ts:297`、`tests/workplan-budget-pause.test.ts:159`),
|
|
152
|
+
> 所以修复必须同时改测试 —— 这不是「为了让测试变绿而改测试」,
|
|
153
|
+
> 而是把设计契约从「完成需要副作用」改成「完成只看计数」,并附上新的反面用例。
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## 4. 同类问题(来自 `docs/state-progress-matrix.md`)
|
|
158
|
+
|
|
159
|
+
状态矩阵枚举了 12 类结构组合 × 5 类事件相位,共 14 项冲突。本次处理:
|
|
160
|
+
|
|
161
|
+
| 编号 | 现象 | 处理 |
|
|
162
|
+
| --- | --- | --- |
|
|
163
|
+
| C1 | 100% + 「正在收尾」+ 留在「进行中」 | 已修(本报告主线) |
|
|
164
|
+
| C2 | 执行中却写「没有下一步,这件事已完成」 | 已修:`nextText` 不再兜底「已完成」 |
|
|
165
|
+
| C4 | 预算到点且已全 done 仍写 `paused` | 已修(防御性分支) |
|
|
166
|
+
| C5 | 部分完成却写「还没开始」 | 已修:`done > 0` → 「还剩 N 项」 |
|
|
167
|
+
| C6 | 环 `done/total` 与加权 `progress` 双口径 | 已修:未完成时两边都封顶 99,完成时都为 100 |
|
|
168
|
+
| C7 | 阶段条把 `blocked` 算作已触达(环 50%、条 100%) | 已修:`reach = done / total` |
|
|
169
|
+
| C8 | 允许 `in_progress + 100%` | 已修:夹紧 99 + I10 |
|
|
170
|
+
| C9 | 阶段行说「正在做」、阶段卡说「还没开始」 | 已修:两处同口径 |
|
|
171
|
+
| C11 | 0/0 降级计划也说「这件事已完成」 | 已修:`helpNoPlan` |
|
|
172
|
+
| C12 | 同屏两个互斥的「现在」 | 已修:`workerText` 与 `planNow` 同序(blocked → active → …) |
|
|
173
|
+
| C13 | 0% 未开始的卡标 `data-state="active"` | 已修:`idle` |
|
|
174
|
+
| C3 | 已取消的卡在前端被过滤,用户看不到 | **未改**:既有设计,`tests/client-render.test.ts` 明确断言「cancelled plan cards should not be rendered」。与 `dsh_workplan_cancel` 的工具描述文案不一致,记录为待统一 |
|
|
175
|
+
| C10 | stale pending 被序列化成 `cancelled`,回放返回 `pending + stale:true` | 未改:两种语义都有消费方,单独变更风险高,记录为下一步 |
|
|
176
|
+
| C14 | `planning` 是死枚举 | 未改:清理项 |
|
|
177
|
+
|
|
178
|
+
---
|
|
179
|
+
|
|
180
|
+
## 5. 验证(可复制的命令与实测输出)
|
|
181
|
+
|
|
182
|
+
### 5.1 构建、类型检查、测试
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
cd /Users/open/Documents/Stocks/plugins/dsh-workplan
|
|
186
|
+
npm run build # exit 0
|
|
187
|
+
npm run check # tsc --noEmit,exit 0
|
|
188
|
+
npm test # 120 tests / 120 pass / 0 fail(原 99 + 新增 13 + 8)
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### 5.2 复现脚本(修复前会失败,修复后通过)
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
node scripts/repro-phase-percent-integrating.mjs --expect-fixed
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
实测输出(节选):
|
|
198
|
+
|
|
199
|
+
```
|
|
200
|
+
payload phase = done
|
|
201
|
+
stats = { total: 2, done: 2, progress: 100 }
|
|
202
|
+
badge = 已完成 · hasIntegrating = false
|
|
203
|
+
data-state = done
|
|
204
|
+
live = done · replay = done · violations = null
|
|
205
|
+
[PASS] ×7 RESULT: PASS
|
|
206
|
+
稳定性:3/3 次指纹一致(8623b993cc8a686c…)
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
同一脚本**不带参数**运行现在会报 3 条 FAIL —— 这正是「旧 bug 已不存在」的证据
|
|
210
|
+
(脚本头部注释已写明两种模式各自的期望)。
|
|
211
|
+
|
|
212
|
+
### 5.3 直接回放用户报告的那次事故会话
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
node scripts/replay-real-session.mjs \
|
|
216
|
+
~/.dsh/sessions/--Users-open-Documents-Stocks--/session-c3852c31-f6cd-4fc5-8cff-d8a3932e9feb/session.v4.jsonl.zstd
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
实测输出:
|
|
220
|
+
|
|
221
|
+
```
|
|
222
|
+
计划: wp-dc44c4a2-3fce-4e78-a2df-1cf6da76eeb2 · 159667工业母机ETF走势预判·证据驱动的分期推演计划
|
|
223
|
+
阶段: done
|
|
224
|
+
统计: total=14 done=14 blocked=0 inProgress=0 pending=0 progress=100
|
|
225
|
+
子任务: 14
|
|
226
|
+
不变量告警: 无
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
即:同一份历史事件,修复后不再出现「100% + 正在收尾」。
|
|
230
|
+
|
|
231
|
+
### 5.4 版本一致性(7 处)
|
|
232
|
+
|
|
233
|
+
```
|
|
234
|
+
package.json: 1.5.2 package-lock.json(root): 1.5.2
|
|
235
|
+
package-lock.json(packages[""]): 1.5.2
|
|
236
|
+
src/host.ts meta.version: 1.5.2
|
|
237
|
+
lib/host.js: 1.5.2 dist/host.js: 1.5.2
|
|
238
|
+
CHANGELOG.md 顶部: 1.5.2
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## 6. 生效方式(重要)
|
|
244
|
+
|
|
245
|
+
- **客户端**(`client.js`):刷新页面即生效(客户端 bundle 热重载)。
|
|
246
|
+
- **宿主侧**(`lib/*.js`):DSH 进程在**启动时** import,必须**重启 DSH** 才会加载 1.5.2。
|
|
247
|
+
- 已安装副本 `/Users/open/.dsh/profiles/web/node_modules/dsh-workplan` 是指向
|
|
248
|
+
`/Users/open/Documents/Stocks/plugins/dsh-workplan` 的**符号链接**,无需重新安装。
|
|
249
|
+
- 因此:**当前正在运行的 DSH 实例仍是 1.5.1 的代码**。若在重启前把本会话的计划
|
|
250
|
+
标成全完成,这张卡仍会显示「正在收尾」—— 那是旧代码的行为,不是修复失效;
|
|
251
|
+
重启后同一份数据会显示「已完成」。这也是本次诊断最直观的验证方式。
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## 7. 未做的事
|
|
256
|
+
|
|
257
|
+
- `git tag v1.5.2`、`npm publish`:属对外发布,**未执行**,需用户明确授权。
|
|
258
|
+
- C3 / C10 / C14:见第 4 节,记录为后续项。
|
|
259
|
+
- 运行中的 DSH 进程未重启(见第 6 节)。
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## 8. 回滚
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
cd /Users/open/Documents/Stocks/plugins/dsh-workplan
|
|
267
|
+
cp .backups/pre-1.5.2-20261029-125724/package.json .
|
|
268
|
+
cp .backups/pre-1.5.2-20261029-125724/package-lock.json .
|
|
269
|
+
cp .backups/pre-1.5.2-20261029-125724/CHANGELOG.md .
|
|
270
|
+
cp .backups/pre-1.5.2-20261029-125724/host.ts src/host.ts
|
|
271
|
+
npm run build
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
运行中的 DSH 进程不会自动重载 `lib/host.js`,回滚后同样需要重启。
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## 附:相关文档
|
|
279
|
+
|
|
280
|
+
- `docs/root-cause-phase-percent.md` —— 根因推导与 H1–H7 假设逐条证伪
|
|
281
|
+
- `docs/state-progress-matrix.md` —— 12 类结构 × 5 类相位的状态矩阵与 14 项冲突
|
|
282
|
+
- `scripts/repro-phase-percent-integrating.mjs` —— 合成场景复现/回归
|
|
283
|
+
- `scripts/scan-state-matrix.mjs` —— 三层证据扫描器
|
|
284
|
+
- `scripts/replay-real-session.mjs` —— 真实会话回放
|