dsh-workplan 2.2.8 → 2.3.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 +12 -0
- package/README.en.md +2 -2
- package/README.md +2 -2
- package/README.zh.md +242 -0
- package/docs/handle-policy-fix-20261110-T2.md +50 -0
- package/docs/handle-policy-fix-20261110-T2.patch +1050 -0
- package/docs/release-notes-2.3.0.md +7 -0
- package/docs/release-record-2.2.8-20261110.md +66 -0
- package/docs/release-record-2.2.9-20261110.md +48 -0
- package/docs/rootcause-red-x-recurrence-20261110-T1.md +110 -0
- package/lib/host.js +13 -3
- package/lib/plan.js +22 -0
- package/lib/runtime.js +282 -13
- package/lib/watchdog.js +2 -1
- package/package.json +2 -2
- package/src/host.ts +13 -3
- package/src/plan.ts +21 -0
- package/src/runtime.ts +285 -13
- package/src/watchdog.ts +2 -1
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# 发布记录 v2.2.8(2026-11-10)
|
|
2
|
+
|
|
3
|
+
按 RELEASING.md §6 留档:所有证据可复跑。
|
|
4
|
+
|
|
5
|
+
## 1. 版本与提交
|
|
6
|
+
|
|
7
|
+
| 项 | 值 |
|
|
8
|
+
|---|---|
|
|
9
|
+
| 版本 | 2.2.8(四处一致:package.json / package-lock×2 / src/host.ts:1574 / CHANGELOG 首段) |
|
|
10
|
+
| 发布提交 | `70c89f2`(main 已推送) |
|
|
11
|
+
| 标签 | `v2.2.8`(已推送) |
|
|
12
|
+
| 上承 | v2.2.7(`dc39eeb`,同轮已发布;其 CI 红叉由本版本根因修复取代,见 §3) |
|
|
13
|
+
|
|
14
|
+
## 2. 渠道与制品
|
|
15
|
+
|
|
16
|
+
| 渠道 | 结果 | 证据 |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| GitHub Release | https://github.com/abbaababa/dsh-workplan/releases/tag/v2.2.8 | 资产 `dsh-workplan-2.2.8.tgz` |
|
|
19
|
+
| 制品 sha256 | `3f8c68055fa658f19b45c7e517db3324ea0e672fe1d0cec8b1b9a76457bbde53` | 本地 `shasum -a 256` 与 `gh api .../assets/<id> -H "Accept: application/octet-stream"` 下载流**逐字节一致** |
|
|
20
|
+
| npm | `+ dsh-workplan@2.2.8`(账号 open-dsh) | `npm publish /tmp/dsh-workplan-2.2.8.tgz`;`npm view dsh-workplan@latest` 传播期内为 2.2.7,复验命令见 §5 |
|
|
21
|
+
| 索引源 | PR https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/13802 | 条目 tarball 已改指 v2.2.8 资产;catalog npm 发版由上游 CI 触发(本仓库权限边界=PR) |
|
|
22
|
+
|
|
23
|
+
## 3. 本次修复(CI 红叉根因,用户截图圈红的「Release 2.2.6 ✗」)
|
|
24
|
+
|
|
25
|
+
- 现象:2.2.6(run 42568839758)与 2.2.7(run 42749749361)提交 CI `pass N / fail 0 / cancelled 3 → exit 1` 判红;本地 node 26 全绿(假绿)。
|
|
26
|
+
- 根因:`runSubtaskAttempt` 的 `arm()` 对上限计时器 `timer.unref?.()`——裸事件循环进程(node:test / CI node 22)等待竞态期间无存活句柄 → 进程排空 → 用例 `cancelledByParent` → node:test exit 1。
|
|
27
|
+
- 修复:`src/runtime.ts` 去除 unref(ref 句柄;收束路径 `finally` 照旧 `clearTimeout`,不悬挂进程)。
|
|
28
|
+
- 实证:`70c89f2` 的 CI run **completed success**(node 22 裸循环环境);本地 699/699、cancelled 0。
|
|
29
|
+
- 不可变历史声明:GitHub 提交状态是历史事实,**2.2.6/2.2.7 两个旧提交的红叉无法也不应被改写**;「修复」的语义=根因消除且其后继发布提交转绿。2.2.6 的失败重跑(run 42568839758 rerun)仍为 failure,与根因分析一致(旧提交代码仍含 unref)。
|
|
30
|
+
|
|
31
|
+
## 4. 发布前检查(RELEASING §1)
|
|
32
|
+
|
|
33
|
+
- `npm test`:699/699 pass、fail 0、cancelled 0、exit 0。
|
|
34
|
+
- W5 跨版本 A/B 探针(R-W5-01,打 tag 前):`RESULT: PASS`、EXIT=0(六断言全过;旧 lib 取 `git archive v1.8.19`,夹具 `W5_ROOT_LOG=/Users/open/Documents/Stocks/_baseline_work/root/root.jsonl`)。
|
|
35
|
+
- 构建可复现:提交后 `npm run build && git diff --exit-code -- lib client.js` = **REPRO_CLEAN**(v2.2.7 与 v2.2.8 两次提交均验)。
|
|
36
|
+
|
|
37
|
+
## 5. 复验命令
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm view dsh-workplan@latest version # 传播完成后应=2.2.8
|
|
41
|
+
gh run list --repo abbaababa/dsh-workplan --commit 70c89f2 # 应 completed success
|
|
42
|
+
gh api repos/abbaababa/dsh-workplan/releases/tags/v2.2.8 --jq '.assets[0].size' # 应=本地 tgz 字节数
|
|
43
|
+
curl -s https://cdn.jsdelivr.net/npm/dsh-plugin-catalog/index.json | grep -o '"id":"dsh-workplan"' # PR 合并+上游发版后命中
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## 6. 运行态指纹(§6.1,2026-11-10 12:45 补记完成)
|
|
47
|
+
|
|
48
|
+
- 用户已手工重启 DSH(pid 6112,启动 2026-11-10 12:08:55)。
|
|
49
|
+
- ① 运行态自报:`v2.2.8|build 6a8a74c16977996d`。
|
|
50
|
+
- ② 磁盘复刻(完整字节算法):`6a8a74c16977996d` —— **相同** ⇒ 运行态与磁盘逐字节同一产物,2.2.8 确已加载。
|
|
51
|
+
- 文档缺陷补记:RELEASING §6.1 原命令 `printf '%s' "$(cat …)"` 因命令替换剥尾换行,与实现(readFileSync 完整字节 sha256 前 16 位)不符,曾产出假不匹配值 `bdb1ab2712cc538a`(负样本留档);已纠正为 `cat … | shasum -a 256 | cut -c1-16`。
|
|
52
|
+
- 旁证:lib 四文件 mtime 11:54:23 早于进程启动 12:08:55。
|
|
53
|
+
|
|
54
|
+
## 7. PR #13802 闭环状态(2026-11-10 12:40 补记)
|
|
55
|
+
|
|
56
|
+
用户复核指出 PR 页面曾显示 2.2.7;实测残留仅在「门面层」,现已全清:
|
|
57
|
+
|
|
58
|
+
| 层 | 状态(gh 实测) |
|
|
59
|
+
|---|---|
|
|
60
|
+
| 标题 | `chore: bump abbaababa/dsh-workplan tarball to v2.2.8` ✔ |
|
|
61
|
+
| 正文 | npm 2.2.8 + v2.2.8 资产 URL + sha256 `3f8c6805…de53`(与 Release 资产下载流互证) ✔ |
|
|
62
|
+
| 提交 | 单一提交 `78a0b962`(消息含 v2.2.8;旧 2.2.7 提交经重建分支消除) ✔ |
|
|
63
|
+
| diff | 唯一改动行 `+tarball: …/v2.2.8/dsh-workplan-2.2.8.tgz`;`grep -c '2.2.7' = 0` ✔ |
|
|
64
|
+
| npm | registry `dist-tags.latest = 2.2.8` ✔ |
|
|
65
|
+
|
|
66
|
+
**唯一残留与平台机制声明**:头分支名 `bump-dsh-workplan-2.2.7` 仍含旧版本号。GitHub 不支持「保持 PR 编号更换头分支」——实测 rename 即触发跨仓 PR 自动 CLOSED(已 rename back + `gh pr reopen` 无损恢复,head sha 不变)。分支名是 git ref 名称、**非任何消费方读取的版本引用**(catalog CI 读合并后 yml 内容);上游合并后删除该分支即全链无任何 2.2.7 展示面。是否换干净分支名新开 PR(换编号)由用户裁决,见会话记录。
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# 发布记录 v2.2.9(2026-11-10)
|
|
2
|
+
|
|
3
|
+
按 RELEASING.md §6 留档:所有证据可复跑。
|
|
4
|
+
|
|
5
|
+
## 1. 版本与提交
|
|
6
|
+
|
|
7
|
+
| 项 | 值 |
|
|
8
|
+
|---|---|
|
|
9
|
+
| 版本 | 2.2.9(四处一致:package.json / package-lock×2 / src/host.ts / CHANGELOG 首段;version-sync 测试随全量绿) |
|
|
10
|
+
| 发布提交 | `b341db9`(main 已推送) |
|
|
11
|
+
| 标签 | `v2.2.9`(已推送) |
|
|
12
|
+
| 内容 | 红字复发族治本:收束类计时器分类去 unref(存活恰 3 处卫生类白名单)+ EVIDENCE_MISSING 有界回喂与盘上结算备份 + 防回归四件套(handle-policy 守卫/全局测试锚/run-tests cancelled===0 硬断言/CI node22+26 双矩阵) |
|
|
13
|
+
|
|
14
|
+
## 2. 发布前检查(RELEASING §1)
|
|
15
|
+
|
|
16
|
+
- `npm run check` exit 0;`npm test` 全量 exit 0(失败面仅 version-sync 两处版本声明,同步后绿)。
|
|
17
|
+
- W5 跨版本 A/B 探针(打 tag 前):`RESULT: PASS`。
|
|
18
|
+
- 构建可复现:提交后 `npm run build && git diff --exit-code -- lib client.js` = **REPRO_CLEAN**。
|
|
19
|
+
|
|
20
|
+
## 3. 渠道与制品
|
|
21
|
+
|
|
22
|
+
| 渠道 | 结果 | 证据(16:38 实测) |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| GitHub | `b341db9` + tag `v2.2.9` | CI verify(node 22+26 双矩阵)= **completed success**(双矩阵首次生产实证) |
|
|
25
|
+
| GitHub Release | https://github.com/abbaababa/dsh-workplan/releases/tag/v2.2.9 | 资产 `dsh-workplan-2.2.9.tgz`,sha256 `f46f6f5601ee889f5f53c5b248933443bc7bad3d12a1c54aefe6f86cb596840b`(本地打包即该值,打包源=干净克隆 v2.2.9) |
|
|
26
|
+
| npm | `+ dsh-workplan@2.2.9` | registry `dist-tags.latest = 2.2.9` 实测 |
|
|
27
|
+
| 索引源 | PR [awesome-dsh-plugin#13893](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/13893) OPEN,tarball 指 v2.2.9 | 前序 #13802 **已被上游合并**(mergedAt 2026-11-10T07:00:21Z,条目当时升至 v2.2.8);#13893 合并+上游 CI 发版后索引升至 2.2.9 |
|
|
28
|
+
|
|
29
|
+
## 4. 运行态指纹(§6.1)
|
|
30
|
+
|
|
31
|
+
- 运行态实测(16:39,`dsh_workplan_status`):**v2.2.8|build 54a0e5295d0aa712|pid 822|启动 16:19:41**。
|
|
32
|
+
- 磁盘复刻(完整字节算法):`cat lib/host.js lib/runtime.js lib/plan.js lib/watchdog.js | shasum -a 256 | cut -c1-16` = **`88cae5ee10476b8b`**(v2.2.9 lib,16:38 实测)。
|
|
33
|
+
- 判定:**运行态≠磁盘属预期时序**——用户进程 16:19:41 启动,当时磁盘版本声明仍是 2.2.8(bump 发生在 16:3x),加载的就是当时的正确字节;2.2.9 lib 于其启动之后重建。不存在"重启未生效"故障。
|
|
34
|
+
- **待用户再手工重启一次后**,比对运行态 build=`88cae5ee10476b8b`、v=`2.2.9` 即判「2.2.9 已加载」;相同前不得宣称修复在运行态生效。
|
|
35
|
+
|
|
36
|
+
## 5. 版本显示问答(用户 16:26 问题留档)
|
|
37
|
+
|
|
38
|
+
「已重启但插件版本还是显示 2.2.8,正常吗?」——正常:①上一轮修复提交未 bump 版本(发版待用户决定),磁盘=2.2.8,重启后运行态=磁盘=2.2.8,三者一致说明加载链路健康;②本轮 2.2.9 发布后,需再次重启才见新版本(进程不会热载磁盘新字节)。
|
|
39
|
+
|
|
40
|
+
## 6. 复验命令
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npm view dsh-workplan@latest version # = 2.2.9(已实测)
|
|
44
|
+
gh run list --repo abbaababa/dsh-workplan --commit b341db9 # completed success(双矩阵)
|
|
45
|
+
gh pr view 13893 --repo awesome-dsh-plugin/awesome-dsh-plugin --json state
|
|
46
|
+
curl -s https://cdn.jsdelivr.net/npm/dsh-plugin-catalog/index.json | grep -o '"id":"dsh-workplan"' # #13893 合并+上游发版后
|
|
47
|
+
cat lib/host.js lib/runtime.js lib/plan.js lib/watchdog.js | shasum -a 256 | cut -c1-16 # = 运行态回显即 2.2.9 已加载
|
|
48
|
+
```
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# 根因诊断报告:CI「红叉/cancelled 红字」为何多次复发(T1 · 2026-11-10)
|
|
2
|
+
|
|
3
|
+
> 仓库:`/Users/open/Documents/Stocks/plugins/dsh-workplan`(HEAD `3aed805`,v2.2.8)
|
|
4
|
+
> 基线锚定:`src/runtime.ts` sha256 `173944207a4fc35f…1f0a`(8492 行);本报告所有行号以此为准。
|
|
5
|
+
> 诊断人:T1(资深 SRE · Node.js 事件循环与 CI 诊断)
|
|
6
|
+
|
|
7
|
+
## 0. 执行摘要(一段话)
|
|
8
|
+
|
|
9
|
+
「红字/红叉」= CI(GitHub Actions,node 22)上 `node --test` 把等待中的用例判为 `cancelledByParent` → exit 1 → 提交状态红叉;本地 node 26 因 test runner 自带存活句柄而假绿。**它复发 4 次(1.5.0 起每次 push、2.1.2 版本漂移另一类、2.2.6、2.2.7)的根本原因不是某一行代码,而是三条结构性诱因叠加**:①生产代码把「必须触发才能收束的 deadline 计时器」与「卫生性计时器」一律 `unref()`,在裸事件循环下进程排空即死;②第一次修复(`9f0de34`)选择在**测试侧加锚**治标,未动生产模式,锚覆盖靠手工、新文件即漏;③本地 node 26 与 CI node 22 的 runner 句柄行为差异让问题只在 CI 显形,显形滞后于引入。2.2.8 只修了 1 处(attempt 上限计时器),**当前 src/ 仍有 9 处同类 unref,且 9 个触及这些路径的测试文件全部无锚**——同类竞态的复发面依然存在。
|
|
10
|
+
|
|
11
|
+
## 1. 「红字」的确切所指
|
|
12
|
+
|
|
13
|
+
- CI 日志红字:`# cancelled 3`(node:test 汇总行)+ exit code 1 → GitHub 提交状态红叉。
|
|
14
|
+
- 机理(`9f0de34` 提交信息原文,逐字):
|
|
15
|
+
> "Node 22 then cancels a pending test as soon as the loop drains with no ref'd handle left, which is why verify has been red on every push since 1.5.0 while the suite passed on Node 26."
|
|
16
|
+
- 同机理在 2.2.8 修复注释中再次确认(`src/runtime.ts:2727-2731`):unref 时裸事件循环进程(node:test / CI node22)在等待竞态期间排空退出,用例被 `cancelledByParent` → exit 1 → 红叉;本地 node26 因 runner 自带句柄"竞态获胜"而假绿。
|
|
17
|
+
|
|
18
|
+
## 2. 历史复发时间线(git 实证,`git log --all --date=short`)
|
|
19
|
+
|
|
20
|
+
| # | 时间 | 提交 | 事件 | 修复方式 | 是否治本 |
|
|
21
|
+
|---|---|---|---|---|---|
|
|
22
|
+
| 1 | 2026-10-28→29 | `98989d9`(1.4.3)→`9f0de34` | **自 1.5.0 起每次 push CI verify 全红**(node 22 cancelled),本地 node 26 全绿 | 测试侧加 `eventLoopAnchor`(ref'd setInterval + after 钩子清理),仅覆盖当时受影响的少数文件 | ❌ 治标:生产 unref 模式原样保留 |
|
|
23
|
+
| 2 | 2026-11-06 | `c2ec7b2` | 另一类红叉:2.1.2 漏同步 6 处版本号 → version-sync 门禁红 | 补齐 6 处版本号 | ✅(该类);说明「红叉」有独立第二成因类 |
|
|
24
|
+
| 3 | 2026-11-09→10 | 2.2.6(`f1e3f7b`)| CI 再现 cancelled 红叉(3 条用例 `cancelledByParent`,`pass 663/fail 0/cancelled 3`) | `dc39eeb`(2.2.7) 宣称"cancelled 之源消除(699/699, cancelled 0)"——**本地 node 26 验证** | ❌ 本地假绿再次骗过验证 |
|
|
25
|
+
| 4 | 2026-11-10 | `dc39eeb`(2.2.7) 提交本身在远端 CI 仍红 | attempt 上限计时器仍带 `unref` → 远端 node 22 复现同类排空 | `70c89f2`(2.2.8) 删除该行 unref + 注释禁令;远端 CI `completed success` | ⚠️ 单点治本;同类 9 处未动 |
|
|
26
|
+
|
|
27
|
+
**复发计数:事件循环排空类 3 次(#1、#3、#4),版本漂移类 1 次(#2)。**
|
|
28
|
+
|
|
29
|
+
## 3. 为什么多次发生:根因 + 触发条件矩阵(A1)
|
|
30
|
+
|
|
31
|
+
### 结构性根因(3 条)
|
|
32
|
+
|
|
33
|
+
- **RC-1 句柄策略二元冲突(主根因)**:插件运行在 DSH 宿主内,`unref()` 是刻意卫生设计(宿主关闭时不被插件计时器拖住,`9f0de34` 提交信息:"unref'd on purpose so a shutting down host is not held open")。但**收束语义计时器**(attempt 上限、round 总预算、ack deadline、auto-resume 延迟、watchdog)必须真实触发才能让子任务/轮次到达终态。在"进程内只有这些计时器在等"的裸事件循环窗口(node:test、headless、宿主排空瞬间),unref = 允许进程在收束前排空退出 → cancelled/静默死亡。**"不拖住宿主"与"保证收束"在同一句柄上互斥,代码未做分类,一律选了前者。**
|
|
34
|
+
- **RC-2 修复层次错位**:#1 的修复把锚加在**测试文件**(每文件手工一份),不是运行时或全局 setup。锚覆盖 = 手工枚举,任何新增/改动的触及计时器路径的测试文件默认无保护。实证:当前 12/97 个测试文件有锚,而 **9 个触及 unref 计时器路径的测试文件(§4.2)与 12 个有锚文件的交集为空**——最需要保护的文件恰好全部裸奔,目前靠"测试自身 await 的 promise 恰好持有句柄"侥幸不触发。
|
|
35
|
+
- **RC-3 验证环境与故障环境不一致**:故障只在 node 22(CI)显形;开发/验证在 node 26(本地,实测 `node -v` = v26.9.0)。node 26 的 test runner 自带存活句柄使排空竞态"获胜"→ 本地 699/699 全绿被当成修复证据(2.2.7 即如此误判),远端才暴露。**本地全绿对这类缺陷零检出能力。**
|
|
36
|
+
|
|
37
|
+
### 触发条件矩阵
|
|
38
|
+
|
|
39
|
+
| 条件 | 取值 | 说明 |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| 进程类型 | 裸事件循环(node:test / headless / 宿主排空瞬间) | 宿主常驻时 HTTP server 等 ref'd 句柄掩盖问题 |
|
|
42
|
+
| Node 版本 | 22(触发)vs 26(掩盖) | node:test 对 loop drain 的取消语义差异 |
|
|
43
|
+
| 等待窗口 | 所有存活句柄均 unref 的时刻 | 例:attempt 计时器被 clear 后仅剩 auto-resume 延迟计时器的窗口 |
|
|
44
|
+
| 计时器类别 | 收束类(必须触发)受致命影响;卫生类(notice/poll)仅丢通知 | 见 §4 分类 |
|
|
45
|
+
|
|
46
|
+
## 4. 当前代码全部风险点清单(A2/A3)
|
|
47
|
+
|
|
48
|
+
扫描命令:`grep -rn 'unref\|\.ref()' src/`、`grep -n 'setTimeout\|setInterval' src/*.ts`(全覆盖 `src/runtime.ts` 18 处、`src/client.ts` 3 处、`src/watchdog.ts` 2 处计时器点位,无遗漏)。
|
|
49
|
+
|
|
50
|
+
### 4.1 生产代码:9 处存活 unref(2.2.8 修复后仍在)
|
|
51
|
+
|
|
52
|
+
分类口径:**收束类** = 不触发则子任务/轮次无法到达终态(危险);**卫生类** = 不触发只丢一条通知/轮询(低危)。
|
|
53
|
+
|
|
54
|
+
| # | 位置 | 计时器 | 类别 | 触发条件 | 影响 | 优先级 |
|
|
55
|
+
|---|---|---|---|---|---|---|
|
|
56
|
+
| R1 | `src/runtime.ts:3115` | `totalTimer` 轮次总预算 → abort TOTAL_TIMEOUT | **收束** | 裸循环下整轮仅剩此计时器(与已修的 attempt 计时器同构!) | 轮次不收束为 TOTAL_TIMEOUT,进程排空 → cancelled/静默死 | **P0** |
|
|
57
|
+
| R2 | `src/runtime.ts:2173` | `deadlineTimer` 180s no-ack 判定 → blocked+abort | **收束** | 派发后子会话未启动、无其他 ref'd 句柄 | no-ack 永不判定,行悬死 | **P0** |
|
|
58
|
+
| R3 | `src/runtime.ts:5678` | auto-resume 延迟计时器 | **收束** | 轮次结束→续跑窗口内进程无其他句柄 | 自动续跑永不发生,计划静默停摆 | **P0** |
|
|
59
|
+
| R4 | `src/watchdog.ts:265` | watchdog 轮询 interval(idle/hard 超时判定) | **收束** | 子会话执行期间宿主句柄排空 | 超时看门狗失效,卡死子任务无人收束 | **P0** |
|
|
60
|
+
| R5 | `src/runtime.ts:6334` | 指示 ack deadline → blocked no-ack | **收束** | instruct 后窗口内裸循环 | 指示无回执永不判 blocked | P1 |
|
|
61
|
+
| R6 | `src/runtime.ts:1201` | dispose 超时 reject(Promise.race 臂) | **收束**(弱) | dispose 挂起且无其他句柄 | race 永不 settle,进程直接退出而非报错 | P1 |
|
|
62
|
+
| R7 | `src/runtime.ts:2140` | ack notice(ackOverdue 标记) | 卫生 | 同上 | 丢一次"已下发未响应"提示 | P2 |
|
|
63
|
+
| R8 | `src/runtime.ts:6301/6311` | 指示 poll interval + notice | 卫生 | 同上 | 丢确认轮询/提示(deadline R5 兜底) | P2 |
|
|
64
|
+
| R9 | `src/runtime.ts:6282` 关联 `6301` | (同 R8 poll) | 卫生 | 同上 | 同 R8 | P2 |
|
|
65
|
+
|
|
66
|
+
**ref'd(安全)点位备查**:`runtime.ts:729`(sleepAbortable)、`889/891`(runPlanner progress/hard,planner 收束依赖,现为 ref——正确)、`2726`(attempt 上限,2.2.8 已修,带禁令注释);`client.ts:1580/3077/3079` 为浏览器 UI 计时器,不在 node 事件循环风险面内。
|
|
67
|
+
|
|
68
|
+
### 4.2 测试代码:暴露面(RC-2 实证)
|
|
69
|
+
|
|
70
|
+
- 有 `eventLoopAnchor` 的文件:**12/97**(planner-*、time-*、workplan-auto-retry/budget-*/dispatch-modes/status-lock/stuck-recovery)。
|
|
71
|
+
- 触及 unref 计时器路径(grep `ackOverdue|no-ack|autoResume|TOTAL_TIMEOUT|instructionOverdue|startWatchdog|dispose timeout|ASSIGN_ACK`)的文件:`auto-resume-policy`、`interrupt-announce`、`workplan-closure-ack-escalation`、`workplan-closure-n1-n5`、`workplan-comm-format-e2e`、`workplan-followup-tool`、`workplan-monotonicity`、`workplan-retry-feedback`、`workplan-unparsable-retry` —— **9 个全部无锚(交集=∅)**。
|
|
72
|
+
- 风险:这些文件当前通过是因为测试自身 await 的 promise/桩件恰好持有句柄;任何桩件时序调整(如改用真计时器、加长等待)都会复现 #3/#4 型红叉。触发条件:node 22 + 等待窗口内句柄全 unref。建议:全局 setup 锚(见 §6 P-2)后此类风险整体消除。优先级 **P1**。
|
|
73
|
+
|
|
74
|
+
### 4.3 CI 环境因素(假红/假绿其他来源)
|
|
75
|
+
|
|
76
|
+
- `.github/workflows/verify.yml`:node-version **22** 固定单版本;`npm run verify` = check+test;另有 `git diff --exit-code -- lib client.js` 构建产物新鲜度门禁(漏 build 即红——第二类"非事件循环"红叉源,与 #2 版本漂移同类:门禁红 ≠ 逻辑错,需看红叉的具体 job/step 名分诊)。
|
|
77
|
+
- 本地 v26.9.0 与 CI 22 无矩阵交集 → RC-3 持续存在。建议 CI 增加 26 矩阵或本地验证强制 `node 22` 跑一遍(§6 P-4)。
|
|
78
|
+
|
|
79
|
+
## 5. 本地 vs CI 环境差异完整影响面(A1 支撑)
|
|
80
|
+
|
|
81
|
+
| 维度 | 本地(node 26.9.0) | CI(node 22) | 影响 |
|
|
82
|
+
|---|---|---|---|
|
|
83
|
+
| node:test loop-drain 语义 | runner 自带存活句柄,排空竞态获胜 | 排空即 cancel pending 用例,exit 1 | 同类缺陷本地 0 检出(#3 误判"cancelled 0"即此) |
|
|
84
|
+
| 验证结论效力 | 699/699 全绿 ≠ 修复 | 唯一真实判据 | 2.2.7 的"之源消除"宣称被远端证伪 |
|
|
85
|
+
| 构建门禁 | 手工 build 通常新鲜 | `git diff --exit-code` 强制 | 漏提交 lib/ 即红(历史 #2 类) |
|
|
86
|
+
|
|
87
|
+
## 6. 防回归建议(交 T2 实施,按优先级)
|
|
88
|
+
|
|
89
|
+
- **P-1(P0)收束计时器去 unref 分类改造**:R1–R6 六处收束类计时器删除 `unref()`(与 2.2.8 attempt 修法一致:ref 持有 + 收束路径 `finally clearTimeout`,不会悬挂宿主);R7–R9 卫生类保留 unref 并加注释声明类别。**验收:`grep -c 'unref' src/runtime.ts src/watchdog.ts` 只剩卫生类白名单点位。**
|
|
90
|
+
- **P-2(P0)测试全局锚取代手工锚**:新增单一 `tests/setup-event-loop-anchor.ts`(或 `node --test --import` 全局 setup),持一个 ref'd interval + 全局 after 清理;删除 12 份手工锚防漂移。任何新测试文件自动获得保护,消除 RC-2。
|
|
91
|
+
- **P-3(P1)静态守卫测试**:仿 `tests/version-sync.test.ts` 门禁模式,新增 `handle-policy.test.ts`:解析 src/ 全部 `setTimeout/setInterval` 点位,断言"收束类白名单内禁止出现 unref、白名单外必须 unref",把 §4.1 分类固化为可执行契约。任何未来新增计时器未分类即红。
|
|
92
|
+
- **P-4(P1)CI 断言与环境对齐**:test 脚本输出显式断言 `cancelled === 0`(当前 exit 1 间接体现,但汇总行断言可区分"fail"与"cancelled"两类红);CI 增加 node 26 矩阵或 RELEASING 增加"发布前 node 22 本地复跑"硬步骤,消除 RC-3。
|
|
93
|
+
- **P-5(P2)文档固化**:把"收束 vs 卫生"句柄分类写进 RELEASING/贡献指南,附本报告 §3 矩阵。
|
|
94
|
+
|
|
95
|
+
## 7. 证据索引(全部可复跑)
|
|
96
|
+
|
|
97
|
+
1. 时间线:`git log --all --format='%h %ad %s' --date=short -i --grep='unref' --grep='cancel' --grep='红叉' --grep='alive'`(§2 各行)。
|
|
98
|
+
2. 机理原文:`git show 9f0de34`(提交信息 + eventLoopAnchor diff);`sed -n '2715,2745p' src/runtime.ts`(2.2.8 禁令注释)。
|
|
99
|
+
3. unref 全量扫描:`grep -rn 'unref\|\.ref()' src/` → runtime.ts 1201/2140/2173/3115/5678/6301/6311/6334 + watchdog.ts:265(9 处)+ 2727 注释行。
|
|
100
|
+
4. 计时器全量点位:`grep -n 'setTimeout\|setInterval' src/runtime.ts src/client.ts src/watchdog.ts`(runtime 18、client 3、watchdog 2)。
|
|
101
|
+
5. 锚覆盖:`grep -ln 'eventLoopAnchor' tests/*.ts` = 12;`ls tests/*.ts | wc -l` = 97;路径触及 `grep -ln 'ackOverdue|no-ack|autoResume|TOTAL_TIMEOUT|instructionOverdue|startWatchdog|dispose timeout|ASSIGN_ACK' tests/*.ts` = 9(交集空)。
|
|
102
|
+
6. CI 配置:`.github/workflows/verify.yml`(node 22、verify、lib 新鲜度门禁);`package.json:71-72`(test/verify 脚本);本地 `node -v` = v26.9.0。
|
|
103
|
+
7. 第二类红叉:`git show c2ec7b2 --stat`(版本漂移 6 处);`tests/version-sync.test.ts` 存在。
|
|
104
|
+
8. 基线:`git rev-parse HEAD` = `3aed805…`;`shasum -a 256 src/runtime.ts` = `173944207a4f…`。
|
|
105
|
+
|
|
106
|
+
## 8. 边界与未验证项(如实声明)
|
|
107
|
+
|
|
108
|
+
- 本轮截图原件未直接读取(子任务输入注明"待确认");「红字=cancelledByParent 汇总行/提交红叉」的判定基于会话上下文中主 Agent 已实证的 2.2.6/2.2.7 红叉记录(`pass 663/fail 0/cancelled 3`)与用户追问脉络,与全部 git 证据自洽。若截图另指其他红字,§4.3 提供了分诊入口(看 job/step 名),报告主体结论不受影响。
|
|
109
|
+
- node 22 与 26 的 node:test 句柄差异细节引自本仓库两处一手记录(9f0de34 提交信息、runtime.ts:2727 注释)与远端 CI 实测结果,未另行查 Node 官方 changelog 逐版本比对(20 分钟全链时限内的取舍)。
|
|
110
|
+
- R4(watchdog)在宿主常驻场景实际由宿主句柄兜底,其 P0 定级针对裸循环/headless 场景;宿主是否在所有版本都持有 ref'd 句柄未逐一验证。
|
package/lib/host.js
CHANGED
|
@@ -109,6 +109,12 @@ const PROMPT_SECTION = [
|
|
|
109
109
|
* (上方 1.8.7/1.8.13 注释)全部保留,不删。
|
|
110
110
|
*/
|
|
111
111
|
'7. 子任务的时间是「协商上限」+「安全兜底」,不是固定交付期限:规模参考 15 分钟量级(仅供参考、非承诺,实际时长由执行专家开工预告协商决定),整轮预算(默认 20 分钟)同样只是安全兜底,不是交付期限。子 Agent 接近上限时应先把已完成内容落盘并在结论里列出路径。任何「达到协商上限」「本轮预算用尽」都不等于「什么都没做」:状态里的 error 会列出「声明产物已在盘上」,必须先用文件核对;若产物已覆盖验收标准,用 dsh_workplan_update 复核改判,只补缺失部分再续跑,禁止无视盘上产物把整步重跑。确认需要更多时间时,主 Agent 可用 dsh_workplan_update 的 extendMs 协商放宽(放宽永远有界:累计超过初始协商上限的一倍即拒绝,转新轮续跑或转 escalate 请主 Agent/用户裁决)。',
|
|
112
|
+
/*
|
|
113
|
+
* [2.3.0][T1] 专家执行时间机制三条款(用户 2026-11-10 要求 1/2 的主 Agent 侧义务):
|
|
114
|
+
* 预估上报后必须转告用户;第 1 次超时必须放宽并告知专家(插件自动投递最新时限
|
|
115
|
+
* 与质量效率要求);第 2 次超时由主 Agent 接手,已完成部分只读保护、禁止丢弃。
|
|
116
|
+
*/
|
|
117
|
+
'7a. [2.3.0] 专家时间机制:专家开工预告(timeNotice/【专家预估上报】通知)到达后,必须把该预估执行时间告知用户;专家第一次超时(【执行中断】通知与状态行 timeoutCount=1)时,必须用 extendMs 放宽——延期成功后插件自动把最新执行时限与「必须在保证工作质量的前提下高效率执行」告知专家,回执 childNotified=false 时用 dsh_workplan_followup 补发;同一子任务第二次超时(timeoutCount≥2,takeoverRequired=true)后不再重派专家,由主 Agent 直接接手:只继续 takeoverBrief.remainingOutputs 与未满足的验收,专家已完成产物已登记为只读保护(landedRefs 并入 artifacts,只增不减),禁止丢弃、禁止删除或覆盖、禁止整步重跑。',
|
|
112
118
|
'8. 出现「待指示」项(closure=escalated,左侧栏显示「待指示」并附问题摘录)时,必须在当轮处理:用 dsh_workplan_instruct 下发决定(投递到子会话并把该行恢复为执行中),或确认放弃后用 dsh_workplan_update 置 blocked。不要沉默略过,也不要把待指示当成普通失败——它是一条还没被回答的请示,会一直占着交付门禁。',
|
|
113
119
|
'9. 出现「已下发未响应」(ackOverdue)时,不要重复派发:先用 dsh_workplan_status 看该行 childId 与已等待时长,必要时用 dsh_workplan_followup 投递一次说明;超过硬超时仍未响应会记为 blocked(blockedKind=no-ack),可以再下发指示复活。',
|
|
114
120
|
/*
|
|
@@ -171,6 +177,8 @@ function createUpdateTool(runtime) {
|
|
|
171
177
|
+ '把子任务标成 done 时,必须同时给出真实的 verification 与 acceptance(每项 result="pass"),'
|
|
172
178
|
+ '否则计划不会变成可交付状态(deliveryReady=false,present 会被拒绝)。'
|
|
173
179
|
+ '运行中的子任务需要更多时间时,传 extendMs(毫秒)即可协商放宽,不需要 force;放宽永远有界(累计 ≤ 初始协商上限 × 1),超出转新轮续跑或转 escalate 请主 Agent 裁决。'
|
|
180
|
+
+ '[2.3.0] 延期成功后插件自动向执行中的专家投递最新执行时限与「保证质量、高效率执行」要求(回执 childNotified);'
|
|
181
|
+
+ '同一子任务第二次超时自动置 takeoverRequired,由主 Agent 接手未完成部分,已完成产物只读保护、禁止丢弃。'
|
|
174
182
|
+ '这些字段会写入会话日志,刷新/重启后仍然生效。',
|
|
175
183
|
parameters: {
|
|
176
184
|
type: 'object',
|
|
@@ -271,7 +279,8 @@ function createUpdateTool(runtime) {
|
|
|
271
279
|
type: 'integer',
|
|
272
280
|
description: '延期毫秒数(正整数,仅主 Agent 可用):只推移本子任务的协商截止并重置计时,'
|
|
273
281
|
+ '不改状态判定;运行中可用,不需要 force。除非另传 status,否则可省略 status。'
|
|
274
|
-
+ '放宽永远有界:累计延期 ≤ 初始协商上限的一倍,超出会被拒绝并提示转新轮续跑或转 escalate 请主 Agent 裁决。'
|
|
282
|
+
+ '放宽永远有界:累计延期 ≤ 初始协商上限的一倍,超出会被拒绝并提示转新轮续跑或转 escalate 请主 Agent 裁决。'
|
|
283
|
+
+ '[2.3.0] 延期成功后插件自动告知专家最新执行时限(含保证质量、高效率执行要求);每次超时计一行内 timeoutCount,第二次触发 takeoverRequired(主 Agent 接手,已完成部分只读保护)。',
|
|
275
284
|
},
|
|
276
285
|
/*
|
|
277
286
|
* [2.2.0][T5/O-4c] O-2a 专家开工预告:{declaredMinutes, reason}。与 extendMs
|
|
@@ -279,7 +288,8 @@ function createUpdateTool(runtime) {
|
|
|
279
288
|
*/
|
|
280
289
|
timeNotice: {
|
|
281
290
|
type: 'object',
|
|
282
|
-
description: '专家开工预告(O-2a):{ declaredMinutes, reason },只记入协商流水,不改状态与判定。'
|
|
291
|
+
description: '专家开工预告(O-2a):{ declaredMinutes, reason },只记入协商流水,不改状态与判定。'
|
|
292
|
+
+ '[2.3.0] 落档后插件立即向主会话推送【专家预估上报】通知,提醒主 Agent 把该预期执行时间告知用户。',
|
|
283
293
|
properties: {
|
|
284
294
|
declaredMinutes: { type: 'number', description: '预计完成本子任务的分钟数(仅供参考、非承诺)。' },
|
|
285
295
|
reason: { type: 'string', description: '预告理由(可选)。' },
|
|
@@ -1442,7 +1452,7 @@ export function apply(ctx, config = {}) {
|
|
|
1442
1452
|
}
|
|
1443
1453
|
export const meta = {
|
|
1444
1454
|
name,
|
|
1445
|
-
version: '2.
|
|
1455
|
+
version: '2.3.0',
|
|
1446
1456
|
promptOrder: PROMPT_ORDER,
|
|
1447
1457
|
routes: ['/dsh-workplan/plans', '/dsh-workplan/vendor/chart.umd.js'],
|
|
1448
1458
|
};
|
package/lib/plan.js
CHANGED
|
@@ -4566,6 +4566,17 @@ export function resetBlockedStatuses(statuses) {
|
|
|
4566
4566
|
*/
|
|
4567
4567
|
if (item?.closure === 'escalated' || item?.closure === 'instructed')
|
|
4568
4568
|
continue;
|
|
4569
|
+
/*
|
|
4570
|
+
* [2.3.0][T1] 二次超时 = 主 Agent 接手,不再把专家重派一遍。
|
|
4571
|
+
*
|
|
4572
|
+
* 用户要求 2:预估时间超时两次后由主 Agent 接手尚未完成的事,且禁止丢弃
|
|
4573
|
+
* 专家已完成部分。若续跑把这行重置为 pending 重派,等于让新专家从零重做、
|
|
4574
|
+
* 绕开 takeoverBrief 的只读保护——这里直接跳过:行保持 blocked,
|
|
4575
|
+
* takeoverRequired/takeoverBrief/artifacts 保护登记原样保留,由主 Agent
|
|
4576
|
+
* 用 dsh_workplan_update 复核改判(只补缺口)或人工裁决后离开该状态。
|
|
4577
|
+
*/
|
|
4578
|
+
if (item?.takeoverRequired === true)
|
|
4579
|
+
continue;
|
|
4569
4580
|
next = applyStatus(next, item.subtaskId, {
|
|
4570
4581
|
status: 'pending',
|
|
4571
4582
|
progress: 0,
|
|
@@ -4866,6 +4877,16 @@ leadAgentId = '', leadAgentIdSource = 'none', }) {
|
|
|
4866
4877
|
: []),
|
|
4867
4878
|
// [T3 扩展点·T6] 供 T6 在此行之后追加「完成即时通知」条款(O-1a 插件兜底通道语义);上方三条款为 O-1a①+O-2a+O-4a 合并协议段(矩阵 Z1),既有条款不得删改。
|
|
4868
4879
|
// [2.2.0][T6/O-1a] 完成即时通知条款(插件兜底通道):完成即报是第一通道(见上方「完成即回报」);插件另设兜底——子任务结算成功后立即向主会话推送一条含子任务 ID、摘要、验收计数与用时的即时通知,不等待整轮结束。兜底不替代主动回报。
|
|
4880
|
+
/*
|
|
4881
|
+
* [2.3.0][T1] 超时放宽告知与二次超时接手条款(用户 2026-11-10 要求 1/2):
|
|
4882
|
+
* 预告会由插件自动转告主 Agent「请把预期时间告知用户」;超时后主 Agent
|
|
4883
|
+
* 放宽时插件会把最新执行时限推送给你;连续两次超时改由主 Agent 接手,
|
|
4884
|
+
* 因此专家任何时候都要把已完成内容及时落盘并在回报中列路径——已完成部分
|
|
4885
|
+
* 会被登记为只读保护,禁止被丢弃。以下既有条款零删改。
|
|
4886
|
+
*/
|
|
4887
|
+
'- 预估上报会被插件即时转告主 Agent(含「请把此预期执行时间告知用户」提示),主 Agent 会把你报的预估时间告知用户,让双方都有准备。',
|
|
4888
|
+
'- 超时后主 Agent 放宽时,插件会向你的会话推送【延期告知】:内含最新执行时间与剩余余量,并要求你在保证工作质量的前提下高效率执行——收到通知继续当前工作,不要重新开始;已完成内容及时落盘。',
|
|
4889
|
+
'- 连续两次超时后本行转为「主 Agent 接手」(takeoverRequired):你已完成的产物会被登记为只读保护(禁止丢弃),主 Agent 只继续未完成部分;所以每个阶段都要及时落盘并在回报中列出已完成路径。',
|
|
4869
4890
|
'',
|
|
4870
4891
|
'遇阻上报(强制,先于继续动作):',
|
|
4871
4892
|
'- 出现以下任一情况,第一动作是上报,不是猜测、绕过或静默继续:缺少权限/输入/依赖产物;需求自相矛盾;无法验证;同一命令连续两次失败;需要主 Agent 决定方向。',
|
|
@@ -4878,6 +4899,7 @@ leadAgentId = '', leadAgentIdSource = 'none', }) {
|
|
|
4878
4899
|
EVIDENCE_MARKER_BEGIN,
|
|
4879
4900
|
'{"status":"done","blockedReason":"","phases":{"planning":{"problemAnalysis":["要解决的问题 1(含现状/约束/未知/主要矛盾)"],"constraints":["..."],"unknowns":["..."],"approach":["第 1 步:做什么 → 产出什么 → 如何证明"]},"execution":{"steps":["实际执行的步骤"],"deviations":[]},"verification":{"allPassed":true,"checks":[{"criterion":"A1","method":"怎么验证","evidence":"命令输出/文件/引用"}],"requirementCheck":"逐条核对用户原要求的结果","retrospective":{"problems":["本次遇到的问题(现象+根因)"],"detours":["走过的弯路/返工/无效尝试;确实没有就写 []"],"resolutions":["最终是如何解决的"],"prevention":["以后如何预防再犯:遇到…先…"]}}},"acceptance":[{"criterion":"A1 把上面的验收标准原文抄在这里","result":"pass","evidence":"用命令输出、文件路径或引用证明"}],"artifacts":[{"kind":"file","ref":"相对工作目录的路径"}],"needs":[],"question":"","options":[],"timeSpentMinutes":0,"finalEstimateMinutes":0}',
|
|
4880
4901
|
EVIDENCE_MARKER_END,
|
|
4902
|
+
'- [2.2.9] 盘上结算备份(必做):发送结果块之前,先把同一份 JSON 写入 reports/wp-settlement-<你的子任务 ID>.json(相对工作目录)。收尾消息因异常(error/截断/超时)丢失时,宿主会自动采纳该备份结算,避免「已完成的工作」被误判为「缺失回报」而受阻并级联冻结下游。',
|
|
4881
4903
|
'- status 只能是 done / blocked / partial;partial 会被当作受阻处理。',
|
|
4882
4904
|
'- acceptance 必须逐条覆盖上面的验收标准:criterion 以 A1、A2… 开头对号入座(编号不可省略);result 只能是 pass / fail / unverified。无法确认就写 unverified,不要写 pass。',
|
|
4883
4905
|
'- artifacts 写你实际产出或修改的文件(kind=file,ref 用相对路径)、链接(kind=url)或说明(kind=note)。',
|