dsh-workplan 2.1.3 → 2.2.6

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 (38) hide show
  1. package/CHANGELOG.md +380 -1
  2. package/README.en.md +5 -2
  3. package/README.md +5 -2
  4. package/README.zh.md +5 -2
  5. package/client.js +143 -3
  6. package/docs/dsh-workplan_T4_runtime.patch +508 -0
  7. package/docs/release-records/_release_notes_2.1.2_20261106.md +44 -0
  8. package/docs/release-records/_t2_version_determination_20261106.md +39 -0
  9. package/docs/release-records/_t5_external_reverify_20261106.md +18 -0
  10. package/docs/release-records/release-dryrun-report-20261106.md +74 -0
  11. package/docs/release-records/release-notes-2.2.6-T3.md +128 -0
  12. package/docs/release-records/release-record-2.1.3-20261106.md +82 -0
  13. package/docs/release-records/release-steps-20261106.md +129 -0
  14. package/docs/release-records/version-freeze-20261109-T2.md +37 -0
  15. package/lib/client.js +143 -3
  16. package/lib/comm-format.js +17 -0
  17. package/lib/departments.js +19 -0
  18. package/lib/host.js +95 -17
  19. package/lib/notice-channel.js +290 -0
  20. package/lib/plan.js +541 -32
  21. package/lib/replan.js +4 -0
  22. package/lib/runtime.js +1481 -85
  23. package/lib/supersede.js +2 -2
  24. package/lib/understanding.js +8 -2
  25. package/lib/watchdog.js +52 -1
  26. package/package.json +3 -2
  27. package/scripts/repair-malformed-user-messages.mjs +312 -0
  28. package/src/client.ts +150 -2
  29. package/src/comm-format.ts +17 -0
  30. package/src/departments.ts +22 -0
  31. package/src/host.ts +90 -12
  32. package/src/notice-channel.ts +328 -0
  33. package/src/plan.ts +575 -24
  34. package/src/replan.ts +4 -0
  35. package/src/runtime.ts +1500 -86
  36. package/src/supersede.ts +2 -1
  37. package/src/understanding.ts +10 -2
  38. package/src/watchdog.ts +80 -1
@@ -0,0 +1,74 @@
1
+ # dsh-workplan release.sh 干跑测试报告(T3 · 质量验证)
2
+
3
+ - 日期:2026-11-06
4
+ - 测试对象:`plugins/dsh-workplan/release.sh`(408 行)
5
+ - 环境:macOS arm64,GNU bash 3.2.57(1)-release
6
+ - 仓库基线(测试前记录):HEAD `7c054e9702376a19950978e2967810ad0d36261f`,分支 `main`,工作区仅未跟踪 `?? release.sh`,tag `v2.1.4` 不存在
7
+ - 输入:T2 产物 `release.sh` + T1 清单 `RELEASE_STEPS_T1.md`
8
+
9
+ ## A1 · 语法检查
10
+
11
+ ```
12
+ $ bash -n release.sh
13
+ (exit 0)
14
+ ```
15
+
16
+ 结论:**通过**。macOS 系统 bash 3.2(最严苛的常见 bash 版本)下语法解析零错误。
17
+
18
+ ## A2 · 命令顺序比对(干跑输出 vs T1 清单)
19
+
20
+ 干跑命令:`bash release.sh --version 2.1.4 --summary "T3 干跑验证" --dry-run` → **exit 0**,30 条「将执行」按序打印。
21
+
22
+ | T1 步骤(RELEASE_STEPS_T1.md) | 干跑输出(实际顺序) | 一致 |
23
+ |---|---|---|
24
+ | 步骤0 版本四处声明点 | ② npm version(package.json+lock)→ sed src/host.ts → CHANGELOG 顶部插入 | ✓ |
25
+ | 步骤1 git status --short | ① 工作区检查(porcelain + --short) | ✓ |
26
+ | 步骤1 npm run check | ③ 第 1 条 `npm run check` | ✓ |
27
+ | 步骤1 npm test | ③ 第 2 条 `npm test` | ✓ |
28
+ | 步骤1 npm run build && git diff --exit-code | ③ 第 3、4 条 `npm run build` → `git diff --exit-code -- lib client.js` | ✓ |
29
+ | 步骤2 git add -A / commit / tag -a | ④ add → commit → tag(三条按序) | ✓ |
30
+ | 步骤2 git push origin main / vX | ④ push main → push v2.1.4 | ✓ |
31
+ | 步骤3 clone --depth 1 --branch vX | ⑤ git clone(mktemp 临时目录,比 T1 的 /tmp 固定路径更安全) | ✓ |
32
+ | 步骤3 npm ci && build && npm pack | ⑤ 按序打印 | ✓ |
33
+ | 步骤3 sha256sum | ⑤ 记录制品 sha256 | ✓ |
34
+ | 步骤3 gh release create(带 tgz) | ⑥ 带 tgz + --notes-file | ✓ |
35
+ | 步骤3 curl -sIL 验证制品 | ⑥ 末尾 curl 校验 HTTP 200(在 npm 发布之前,与 T1 步骤3→4 顺序一致) | ✓ |
36
+ | 步骤4 npm whoami / npm publish | ⑦ 按序打印 | ✓ |
37
+ | 步骤4 npm view X / npm view latest | ⑦ 两条 view 验证 | ✓ |
38
+ | 步骤5/6 索引源 PR / 发布记录 | 不代做,结尾 warn 列为人工收尾(T1 明确标注「非本仓库权限」) | ✓ |
39
+ | 步骤7 回滚 | --rollback 分支:gh release delete(tag 保留)、npm unpublish 仅打印、索引源仅提示 | ✓ |
40
+
41
+ **顺序结论**:检查 → 版本四处同步 → check/test/build/diff → add/commit/tag/push → clone/ci/build/pack/sha256 → gh release create → curl 验证 → npm whoami/publish → npm view ×2——与 T1「顺序铁律」逐环节一致。
42
+
43
+ 合理差异说明(均不改变顺序判定):
44
+ 1. 脚本新增前置检查(工具存在、分支、tag 不存在、版本确为新)——落实 T1 前置条件,不是重排。
45
+ 2. 版本同步扩展到三语 README + tests/fixtures/tool-surface.json——依据 `tests/version-sync.test.ts:45`(断言 README.md/README.en.md 必须含 `dsh-workplan@<新版本>`),防止重蹈 2.1.2 CI #399/#400 红叉。
46
+ 3. T1 清单 #4 `npm run verify` 是 CI 聚合命令;脚本按 RELEASING.md §1 细分为 check→test→build→diff,顺序等价。
47
+
48
+ ## 安全检查(无越权操作)
49
+
50
+ - `sudo|launchctl|systemctl|kill|pkill|reboot|shutdown|chmod|chown|curl -X`:**0 命中**。
51
+ - `npm unpublish` 4 处命中全部是注释/警告文本(release.sh:25,51,93,368),**无一处执行**。
52
+ - `rm -rf` 仅 1 处(release.sh:328),目标是 `mktemp -d` 生成的临时目录。
53
+ - 不重启任何服务、不写 `~/.dsh`、不安装依赖(与脚本头部声明边界一致)。
54
+ - 干跑全程**零网络请求、零文件改动**:干跑后 `git status --short` 仍为 `?? release.sh`、HEAD 仍 `7c054e9`。
55
+
56
+ ## 边界测试
57
+
58
+ | 用例 | 结果 |
59
+ |---|---|
60
+ | `--help` | exit 0 ✓ |
61
+ | 缺 `--version` | 报错 exit 1,无副作用 ✓ |
62
+ | `--rollback --dry-run` | exit 0,`gh release delete` 仅打印、tag 保留 ✓ |
63
+ | 文件可执行位 | `-rwx--x--x`,用法文档的 `./release.sh` 可直接运行 ✓ |
64
+
65
+ ## 缺陷清单
66
+
67
+ - **D-01(非阻塞,文档性瑕疵)**:头部注释 `release.sh:45-46` 把「⑧ curl 验证」列在「⑦ npm 发布」之后;实际代码在 `do_gh_release` 内先 curl 验证(release.sh:341-343)再 npm 发布,且该顺序与 T1 一致。仅注释编号与代码不符,不影响执行顺序与 A2 判定。建议后续顺手修正注释。
68
+
69
+ ## 结论
70
+
71
+ - **A1 语法检查:通过**(bash -n exit 0)。
72
+ - **A2 模拟输出命令顺序与 T1 清单一致:通过**(17 行映射表逐条一致,合理差异 3 项均已注明依据)。
73
+ - **安全检查:通过**(无越权操作、零副作用)。
74
+ - 遗留:D-01 注释瑕疵(不阻塞交付)。
@@ -0,0 +1,128 @@
1
+ # dsh-workplan v2.2.6 对外发布说明(T3 · 2026-11-09)
2
+
3
+ - 版本冻结依据:`docs/release-records/version-freeze-20261109-T2.md`(冻结版本 = **2.2.6**;已发布基准 2.1.5 / tag v2.1.5 / commit 6ed12d3)
4
+ - 本文所有数字与事实均回指既有归档证据,未新造任何数字;引用清单见文末「证据回指表」。
5
+ - 用途:§一 供 GitHub Release 页面正文直接粘贴;§二 供索引源(awesome-dsh-plugin)PR 与 tarball 更新;§三 为自检记录。
6
+ - 本文件只描述「准备就绪的发布内容」,不表述发布动作是否已发生;发布执行与状态由 T4/T5/T6/T7 产出。
7
+
8
+ ---
9
+
10
+ ## 一、GitHub Release 正文(tag:v2.2.6)
11
+
12
+ # dsh-workplan v2.2.6 — 三项修复:回放闭环、需求序列化、分解进度可见
13
+
14
+ **本版包含三项修复**,全部改动以锚点标记可追溯(`[2.2.6]` 标记 src 12 处 ↔ lib 12 处一一对应),并完成合并态统一回归(**666/666** 通过)。
15
+
16
+ ## 1. D-1:重启回放丢弃人工改判的 closure 字段(起源 1.7.0,非 2.2.5 引入)
17
+
18
+ durable 的 `workplan-update` 自 1.11.0 起携带 closure,但 `reconstructFromSession` 的回放 patch 一直没把它传给 `applyStatus`:行停在 escalated 时,`status=done` 的改判被「非法闭环迁移 escalated→done」拒绝,整条 update 被裸 catch 吞掉,重启后「待指示」行永久卡死。本版补上 `closure: update.closure`,并把裸 catch 改为 `console.warn` 留痕(fail-closed 而非 fail-silent)。
19
+
20
+ 红-绿验证:摘掉修复跑全量 → 651 项中恰好 1 失败(失败点=改判链 escalated→instructed→done→reported 必须完整回放);恢复修复 → 651/651 通过。
21
+
22
+ ## 2. 跨部门需求落盘变 `[object Object]`(handoff 序列化)
23
+
24
+ - **现象**:子 Agent 以对象形提出的跨部门需求,入库时被隐式 `String(对象)` 整体转成字面量 `[object Object]`,部门信息一并丢失(实证:主计划 wp-db6de2f0 的 T1–T4 四条需求均为 `request="[object Object]"、department:null`)。
25
+ - **病根**:4 个写坏点(`src/plan.ts` `readEvidenceNeeds` / `mergeHandoffsFromNeeds` / `readEvidenceOptions`,`src/runtime.ts` escalate)。
26
+ - **修复**:全部改为对象感知的受控序列化——对象需求落盘为「部门:需求(用途)」可读文本 + 合法部门键;嵌套/循环引用兜底为循环引用安全、undefined 安全的受控 JSON;字符串路径逐字不变;历史损坏记录加载不抛错、存量逐字段不改写。
27
+ - **验证**:专项回归 **10/10**(对象原文一致 / 嵌套受控 JSON / 循环引用不抛错 / 历史记录不改写 / 幂等 / 全链路);坏模式 `String(item ?? '')` 在 src 与 lib 中 **0 命中**。
28
+
29
+ ## 3. 任务自动分解期间界面零提示(进度可见性)
30
+
31
+ - **现象**:发任务后自动分解的几十秒到几分钟里界面毫无反应,分不清「在干活」「在重试」还是「卡死」。取证判定:分解全程插件零 `session.append`、零 `records.set`——侧栏 4 秒轮询与「正在安排」词汇早已存在,只是从未收到数据(断点层=未发出,插件层)。
32
+ - **修复**(零新组件、零新路由、零推送机制):
33
+ 1. **进行中**:进入分解先写占位进度卡,侧栏 4 秒轮询内出现「正在安排」+「正在生成任务分解…」;
34
+ 2. **重试中**:每次可重试失败,卡片追加「第 N 次尝试失败(原因码):真因;正在重试(约 X 秒后),第 (N+1)/3 次」,聊天通知每轮**至多 2 条**(第 3 次失败直接进降级文案);
35
+ 3. **失败带真因**:3 次全败走降级横幅,逐次真因链截断 ≤120 字符、错误码(如 `ECONNREFUSED`)原样保留;
36
+ 4. **等信息中**:澄清场景徽标不再回显原始键名 `clarify`(zh「等信息中」/ en "Waiting for info");
37
+ 5. **用户中止**:全静默、不残留假「进行中」、不丢上一份终态进度。
38
+ - **验证**:专项回归 **5/5**(抖动重试文案 / 通知频率硬规则 / aborted 静默 / 真因截断 / 词汇键);重试语义零变化(`onProgress` 只读观察点)。
39
+
40
+ ## 合并态统一回归(总判定 GO,产品级失败项 = 0)
41
+
42
+ - 产物一致性:构建前后双检哈希 15/15 + 根 client.js 一致;`npm run check` exit 0;
43
+ - 全量套件 **666/666**(= 661 + 5,计数精确吻合);
44
+ - 既有守卫与双向回归不回退:守卫 6/6、抖动正例 8/8 断言、AUTH 反例 4/4、cause 链 3/3、取消传播 3/3、真故障反例 7/7(1564–1678ms,与基线 1.454s 同量级带内)。
45
+
46
+ ## 边界与已知事项(如实登记,不包装)
47
+
48
+ - 两项双缺陷修复的**生环境复验**待用户重启后执行(四态:进行中 / 重试中 / 失败带真因 / 等信息中);聊天通知能否在分解等待期间即时上屏属宿主运行态行为(H-1),侧栏卡片(4 秒轮询)为保底通道。
49
+ - wp-db6de2f0 四条历史损坏记录原文已从子会话日志提取留档,**可恢复**;存量数据一字不改。
50
+ - **D-3 未在本版修复**(轮次中途完成只存内存、重启丢当前计划状态):属轮次生命周期改造,建议下版专项处理;缓解:重要节点后不要立刻重启。
51
+ - 宿主侧三项深度改进(cause 透传、maxRetries 可配、直连流重试覆盖)随宿主发版落实;插件侧已前向兼容、不依赖。
52
+ - 2.1.5 → 2.2.6 之间各版的完整变更见 [CHANGELOG.md](CHANGELOG.md)。
53
+
54
+ ## 安装
55
+
56
+ ```bash
57
+ npm install dsh-workplan@2.2.6
58
+ ```
59
+
60
+ ---
61
+
62
+ ## 二、索引源登记内容
63
+
64
+ 索引源机制(沿用既有结论):上游索引仓库 `awesome-dsh-plugin`,文件 `data/plugins/abbaababa__dsh-workplan.yml`,仅含 7 个键、无 version/sha256 字段,版本由 `tarball` URL 隐含;上游 catalog 的 npm 包由上游 CI 定时从该仓库生成,提交 PR 不等于 npm 包立即更新。
65
+
66
+ ### 2.1 tarball 行更新(本次只改 1 行)
67
+
68
+ 旧值:
69
+
70
+ ```yaml
71
+ tarball: https://github.com/abbaababa/dsh-workplan/releases/download/v2.1.5/dsh-workplan-2.1.5.tgz
72
+ ```
73
+
74
+ 新值(版本号与冻结值一致):
75
+
76
+ ```yaml
77
+ tarball: https://github.com/abbaababa/dsh-workplan/releases/download/v2.2.6/dsh-workplan-2.2.6.tgz
78
+ ```
79
+
80
+ ### 2.2 PR 标题与正文模板
81
+
82
+ 标题:
83
+
84
+ ```text
85
+ Update abbaababa__dsh-workplan to v2.2.6
86
+ ```
87
+
88
+ 正文:
89
+
90
+ ```markdown
91
+ Bump dsh-workplan tarball from v2.1.5 to v2.2.6.
92
+
93
+ Release: https://github.com/abbaababa/dsh-workplan/releases/tag/v2.2.6
94
+ Highlights: replay keeps manual-adjudication closure across restart; cross-department handoff needs serialize as readable text instead of "[object Object]" (department key preserved); progress visibility during automatic task planning (planning card via 4s sidebar poll, retry notices with real cause chain, capped at 2 per round, "Waiting for info" badge).
95
+ No breaking changes.
96
+ Tests: 666/666 passing (`npm test`).
97
+ ```
98
+
99
+ ### 2.3 版本短描述(zh / en,供目录与展示用)
100
+
101
+ - zh:修复三项:重启后人工改判不再丢失(closure 回放);跨部门需求落盘不再变 `[object Object]`(可读文本+部门键,历史记录不改写);任务自动分解期间界面有进度(4 秒内侧栏进度卡、重试带真因且每轮至多 2 条通知、澄清徽标显示「等信息中」)。合并态回归 666/666。
102
+ - en: Three fixes: manual-adjudication closure survives restart replay; handoff needs serialize as readable "department: need (purpose)" text with the department key preserved instead of "[object Object]" (legacy broken records load untouched); progress visibility during automatic task planning (planning card via 4s sidebar poll, retry notices with real cause chain capped at 2 per round, "Waiting for info" badge). Merged-state suite 666/666.
103
+
104
+ ---
105
+
106
+ ## 三、自检记录(A1–A3)
107
+
108
+ - **A1 版本号一致**:本文所有版本号均为 **2.2.6**(tag v2.2.6 / npm install dsh-workplan@2.2.6 / tarball URL v2.2.6),与 T2 冻结值一致;对比基准 2.1.5 亦与 T2 三处对照记录一致。自检命令:`grep -n "2\.2\.6\|2\.1\.5" docs/release-records/release-notes-2.2.6-T3.md`(结果见 T3 汇报)。
109
+ - **A2 数字可回指、未新造**:651(D-1 红绿)、10/10(序列化专项)、5/5(可见性专项)、666/666、15/15、6/6、8/8、4/4、3/3、7/7、1564–1678ms、1.454s、≤120 字符、至多 2 条、4 秒轮询、300s 窗口、12 处标记、四条历史记录——逐项出处见下表。
110
+ - **A3 无未经验证的收尾表述**:全文不含任何收尾性定论用语(如宣称发布动作已完成、宣称成品定稿);发布动作状态显式移交 T4–T7;生环境复验明确写为「待用户执行」。
111
+
112
+ ### 证据回指表
113
+
114
+ | 文中数字/事实 | 出处 |
115
+ |---|---|
116
+ | 2.2.6 冻结 / 2.1.5 已发布基准 / 6ed12d3 / 12 处标记 / 666 待发布范围 | `docs/release-records/version-freeze-20261109-T2.md` §1–§4 |
117
+ | D-1 651 红绿 / closure 补丁 / console.warn | CHANGELOG.md 2.2.6 条目(既有,本版沿用);tests/runtime-replay.test.ts |
118
+ | `[object Object]` 现象 / W1–W4 点位 / wp-db6de2f0 四条 / 可恢复结论 | `_t1_dualdefect_rootcause_20261108/root-cause-and-boundary-report.md` §2.2/§2.3/§2.5 |
119
+ | 序列化修复点位与改法 / 10/10 / `String(item ?? '')` 0 命中 / `[2.2.6][T4]` 锚点 | `_t4_need_serialization_fix/fix-report.md` §二/§四 |
120
+ | 可见性四态文案 / 频率 ≤2 条 / ≤120 截断 / P-9 clarify / 零新组件 / 4 秒轮询 / 300s 窗口 / 重试语义零变化 | `_t5_visibility_impl_20261108/implementation-notes.md` §一/§二/§三 |
121
+ | 666/666 / 15/15 哈希 / 守卫 6/6 / 抖动 8/8 / AUTH 4/4 / cause 3/3 / 取消 3/3 / 真故障 7/7 / 1564–1678ms / 基线 1.454s / 偏差披露 | `_t6_dualfix_regression_20261108/T6_双修复回归测试报告.md` §一/§四/§五/§六 |
122
+ | 生环境复验四态 / H-1 / 通道 A 保底 / 宿主三项 H2 | `_t7_closure_20261108/结案说明与移交清单.md` §四/§二 |
123
+ | 索引源机制(awesome-dsh-plugin / 7 键 YAML / tarball 隐含版本 / CI 定时) | `_t11_release_20261102/index_entry_v1.11.0.md`(既有机制结论,机制未变) |
124
+
125
+ ### 遗留提示(移交,不阻塞文案冻结)
126
+
127
+ - CHANGELOG.md 三处历史条目含本机用户目录绝对路径(T2 敏感初筛发现项::138/:180/:2233 附近),属既有条目,是否随发布提交改写由主 Agent/T4 决定;本 T3 新增文案未引入任何本机绝对路径。
128
+ - GitHub Release 资产名 `dsh-workplan-2.2.6.tgz` 为按既有 tarball 命名惯例(v1.11.0 同构)推导的约定值,实际资产名以 T4 发布脚本/T5 上传为准。
@@ -0,0 +1,82 @@
1
+ # Release record — dsh-workplan 2.1.3 (2026-11-06)
2
+
3
+ 本文件是可复现的发布记录,供后续排查与追溯使用。每一项都可用文中给出的命令重新验证。
4
+
5
+ ---
6
+
7
+ ## 一、这一版要解决什么
8
+
9
+ | 版本 | 改了什么 | 够不够 |
10
+ |---|---|---|
11
+ | 2.1.1 | 把规划器超时从 120s 提到 300s | ❌ 只是推迟了超时 |
12
+ | 2.1.2 | 明确区分「真超时」与「偶发中断」,不再误报 | ⚠️ 报错变清楚了,但超时照样复发 |
13
+ | **2.1.3** | **把单次规划器调用的墙钟上限改成可配置项** | ✅ 治本 |
14
+
15
+ **根因(2.1.3 之前一直没解决的)**:规划器是**单次 LLM 调用**,用写死的常量做墙钟超时。
16
+ 任务越复杂(长上下文 + 多子任务结构化 JSON),单次调用耗时越长,到点必被杀。
17
+ 2.1.1 只把 120s 改成 300s,等于把「必然发生」推迟到 5 分钟后,仍然必然发生。
18
+
19
+ **2.1.3 的解法**:`plannerTimeoutMs` 变成可配置项,链路打通
20
+ `host.ts`(配置 / 环境变量)→ `runtime.ts`(`WorkplanRuntimeOptions`)→ `runPlanner`(`setTimeout`)。
21
+
22
+ ---
23
+
24
+ ## 二、改动清单
25
+
26
+ | 文件 | 改动 |
27
+ |---|---|
28
+ | `src/host.ts` | `WorkplanConfig` 新增 `plannerTimeoutMs?: number`;`apply()` 里 `plannerTimeoutMs: numericSetting(config.plannerTimeoutMs, 'DSH_WORKPLAN_PLANNER_TIMEOUT_MS')` |
29
+ | `src/runtime.ts` | `WorkplanRuntimeOptions` 新增 `plannerTimeoutMs?: number`;`runPlanner` 改为 `const plannerTimeoutMs = Number(options.plannerTimeoutMs ?? PLANNER_TIMEOUT_MS)`,`setTimeout` 用它;调用点传入 `options?.limits?.plannerTimeoutMs` |
30
+ | `lib/runtime.js` / `lib/host.js` | 由 `npm run build` 生成(与 src 同步) |
31
+ | `package.json` / `package-lock.json` / `src/host.ts`(meta.version) / `README.md` / `README.en.md` / `README.zh.md` / `tests/fixtures/tool-surface.json` | 版本号 7 处同步至 `2.1.3` |
32
+ | `CHANGELOG.md` | 新增 `## 2.1.3 — 2026-11-06` 条目 |
33
+
34
+ ---
35
+
36
+ ## 三、怎么用(新增能力)
37
+
38
+ ```bash
39
+ # 复杂任务(长上下文 / 多子任务)放宽规划器时限,毫秒
40
+ export DSH_WORKPLAN_PLANNER_TIMEOUT_MS=900000 # 15 分钟
41
+ ```
42
+
43
+ 未设置时回落到默认 `300000`(5 分钟)。也可用配置文件 `plannerTimeoutMs`。
44
+
45
+ ---
46
+
47
+ ## 四、发布与回验证据
48
+
49
+ | 渠道 | 结果 | 复验命令 |
50
+ |---|---|---|
51
+ | npm | 已发布 `2.1.3`,`dist-tags.latest = 2.1.3` | `npm view dsh-workplan dist-tags.latest` |
52
+ | npm tarball 内容 | 含修复 | `curl -sL $(npm view dsh-workplan@2.1.3 dist.tarball) \| tar -xzO package/lib/runtime.js \| grep plannerTimeoutMs` |
53
+ | GitHub Release | 已建,含安装包 `dsh-workplan-2.1.3.tgz` | `gh release view v2.1.3 --repo abbaababa/dsh-workplan` |
54
+ | git tag | `v2.1.3` 已推送(指向 `cc3562e`) | `git ls-remote --tags origin \| grep v2.1.3` |
55
+ | GitHub Actions | `verify` 全绿 | https://github.com/abbaababa/dsh-workplan/actions/runs/42192179962 |
56
+ | 本地测试 | 580/580 通过 | `npm run verify` |
57
+ | build 幂等 | 通过(CI 第 6 步 `git diff --exit-code -- lib client.js` 必为 0) | `npm run build && git diff --exit-code -- lib client.js` |
58
+
59
+ ---
60
+
61
+ ## 五、2.1.2 的 CI 红叉(已修复,供参考)
62
+
63
+ 2.1.2 首次推送时 CI `verify` 红叉(run `42172640105`),580 项中 2 项失败:
64
+
65
+ - `#399 package.json, package-lock.json and meta.version stay in sync` → `'2.1.2' !== '2.1.1'`
66
+ - `#400 CHANGELOG and README mention the version being shipped` → `README.md must install dsh-workplan@2.1.2`
67
+
68
+ **根因**:2.1.2 发布时只 bump 了 `package.json`,漏改 `package-lock.json`(两处)、
69
+ `src/host.ts` 的 meta.version、三语 README 的徽章与安装命令、`tests/fixtures/tool-surface.json`。
70
+ 仓库自带的 `tests/version-sync.test.ts` 当场抓到(这正是该测试存在的意义)。
71
+
72
+ **修复**:commit `c2ec7b2` 补齐 7 处,红叉转绿(run `42188255718`)。
73
+
74
+ **注意**:npm 上已发布的 `2.1.2` 包内文档仍是旧版本号(npm 不允许覆盖已发布版本),
75
+ 不影响插件功能;2.1.3 起包内外一致。
76
+
77
+ ---
78
+
79
+ ## 六、回滚方式
80
+
81
+ - 代码:`git revert cc3562e && git push origin main`;撤销 tag:`git tag -d v2.1.3 && git push origin :refs/tags/v2.1.3`
82
+ - npm:发布 72 小时内可 `npm unpublish dsh-workplan@2.1.3`;超时则 `npm deprecate dsh-workplan@2.1.3 "请升级到修复版本"` 并另发修复版。
@@ -0,0 +1,129 @@
1
+ # dsh-workplan 发布流程梳理(T1 交付物)
2
+
3
+ > 仓库根:`plugins/dsh-workplan`(相对工作区根;自身含 `.git`,工作区根不是 git 仓库)
4
+ > 当前版本:`2.1.3`(`package.json:3`、`package-lock.json:3,9`、`src/host.ts` 的 `meta.version`、CHANGELOG 顶部 `## 2.1.3 — 2026-11-06`)
5
+ > 本文所有命令均标注来源:RELEASING.md 章节、package.json scripts、.github/workflows/verify.yml,或前期对话(m00001)实测事实。
6
+
7
+ ---
8
+
9
+ ## 一、发布步骤(有序列表)
10
+
11
+ ### 步骤 0 · 版本号规则与四处声明点
12
+ - 版本号只有四个声明点,由 `tests/version-sync.test.ts` 断言一致(`RELEASING.md:12-19`):
13
+ 1. `package.json` 的 `version`
14
+ 2. `package-lock.json` 的 `version` 与 `packages[""].version`
15
+ 3. `src/host.ts` 的 `meta.version`
16
+ 4. `CHANGELOG.md` 的 `## <version> — <date>`
17
+ - 改版本时必须四处同步改,否则 CI `npm test` 中的 version-sync 断言会失败。
18
+ - 来源:RELEASING.md §0(行 6-19)
19
+
20
+ ### 步骤 1 · 发布前检查(全部通过才继续)
21
+ ```bash
22
+ git status --short # 工作区干净,无未提交改动 [RELEASING.md §1:25]
23
+ npm run check # = tsc --noEmit [package.json scripts:69]
24
+ npm test # = build + 全部用例 [package.json scripts:70]
25
+ npm run build && git diff --exit-code -- lib client.js # 重新构建后 lib/client.js 无差异 [RELEASING.md §1:32]
26
+ ```
27
+ - `npm test` 会先 `npm run build` 再跑全部用例;任一失败不打 tag。
28
+ - (可选/历史探针,不并入 npm test)headless W5 跨版本 A/B 探针:`node scripts/w5-cross-version-check.mjs ...`,需 tag `v1.8.19` 与夹具,判据 `RESULT: PASS` 且 EXIT=0(`RELEASING.md §1.4:41-70`)。该步当前有已知偏差,未确认前只记未通过。
29
+ - 来源:RELEASING.md §1(行 21-35、41-90)
30
+
31
+ ### 步骤 2 · 提交与打标签
32
+ ```bash
33
+ git add -A
34
+ git commit -m "Release 2.1.3: <一句话说明>"
35
+ git tag -a v2.1.3 -m "v2.1.3 <说明>"
36
+ git push origin main
37
+ git push origin v2.1.3
38
+ ```
39
+ - 来源:RELEASING.md §2(行 92-100);实际 tag `v2.1.2`、`v2.1.3` 已存在于仓库(`git tag` 实测)
40
+
41
+ ### 步骤 3 · GitHub Release + 制品(必须带 tgz)
42
+ ```bash
43
+ # 干净检出打包,避免把本地未跟踪文件打进制品
44
+ rm -rf /tmp/dsh-workplan-pack && git clone --depth 1 --branch v2.1.3 \
45
+ git@github.com:abbaababa/dsh-workplan.git /tmp/dsh-workplan-pack
46
+ cd /tmp/dsh-workplan-pack && npm ci && npm run build && npm pack
47
+ sha256sum dsh-workplan-2.1.3.tgz # macOS: shasum -a 256
48
+
49
+ # 建 Release 并上传制品
50
+ gh release create v2.1.3 /tmp/dsh-workplan-pack/dsh-workplan-2.1.3.tgz \
51
+ --repo abbaababa/dsh-workplan \
52
+ --title "v2.1.3 — <说明>" \
53
+ --notes-file docs/release-notes-2.1.3.md
54
+
55
+ # 验证制品可下载(HTTP 200,大小一致)
56
+ curl -sIL -o /dev/null -w '%{http_code} %{size_download}\n' \
57
+ https://github.com/abbaababa/dsh-workplan/releases/download/v2.1.3/dsh-workplan-2.1.3.tgz
58
+ ```
59
+ - 历史教训(1.6.0):Release 必须带 `assets`,否则索引源 `tarball:` 指向 GitHub Release 会 404。
60
+ - 来源:RELEASING.md §3(行 102-126)
61
+ - 实测事实(前期对话 m00001 + `gh release view v2.1.3`):`v2.1.3` Release 已建,含 `dsh-workplan-2.1.3.tgz`,URL `https://github.com/abbaababa/dsh-workplan/releases/tag/v2.1.3`
62
+
63
+ ### 步骤 4 · npm 发布
64
+ ```bash
65
+ npm whoami # 必须是拥有该包发布权的账号
66
+ npm publish # 已登录直接发;CI 用 NPM_TOKEN + --provenance
67
+ npm view dsh-workplan@2.1.3 version dist.tarball # 验证已发布
68
+ npm view dsh-workplan@latest version # 必须等于新版本
69
+ ```
70
+ - 来源:RELEASING.md §4(行 128-135)
71
+ - 实测事实(前期对话 m00001):`npm view` → `version=2.1.3 latest=2.1.3`,tarball `https://registry.npmjs.org/dsh-workplan/-/dsh-workplan-2.1.3.tgz`
72
+ - 注意:本地 `npm view` 在本次环境因沙箱 EPERM 缓存权限被拒,但以 RELEASING.md §4 文档命令 + 前期对话实测输出为准。
73
+
74
+ ### 步骤 5 · 索引源(dsh-plugin-catalog,上游 CI,非本仓库权限)
75
+ - 链路:awesome-dsh-plugin 条目 → CI 探测 npm `dist-tags.latest` → 构建 `docs/index.json` → 发布 npm 包 `dsh-plugin-catalog` → jsDelivr → DSH 插件市场。
76
+ - 本仓库只完成「条目 PR」(改 `data/plugins/abbaababa__dsh-workplan.yml` 的 `tarball:` 指向刚发布的 Release),catalog 的 npm 发版由上游 CI 触发。
77
+ - 来源:RELEASING.md §5(行 137-155)
78
+
79
+ ### 步骤 6 · 发布后记录
80
+ - 在 `docs/release-record-<version>-<date>.md` 写可复核证据:tag、commit、npm `shasum`、Release 制品 URL 与 sha256、catalog 版本、复验命令输出。
81
+ - 来源:RELEASING.md §6(行 157-161);实测 `git log` 顶条 `7c054e9 docs: add reproducible release record for 2.1.3`
82
+
83
+ ### 步骤 7 · 回滚
84
+ - npm:`npm unpublish dsh-workplan@<version>`(24h 内)或发 `-fix` 补丁。
85
+ - GitHub:`gh release delete v<version>`,tag 保留。
86
+ - 索引源:改回上一可用 `tarball` 并提 PR。
87
+ - 来源:RELEASING.md §7(行 163-167)
88
+
89
+ ---
90
+
91
+ ## 二、CI(自动验证,非手动步骤)
92
+
93
+ `.github/workflows/verify.yml` 在 `push: main` 与 `pull_request` 触发(`verify.yml:3-6`):
94
+ 1. `actions/checkout@v4`(`verify.yml:15-16`)
95
+ 2. `actions/setup-node@v4`,node 22,cache npm(`verify.yml:18-22`)
96
+ 3. `npm ci`(`verify.yml:24-25`)
97
+ 4. `npm run verify`(`verify.yml:27-28` = `npm run check && npm test`)
98
+ 5. `git diff --exit-code -- lib client.js` 失败当提交产物过期(`verify.yml:30-31`)
99
+
100
+ - 实测事实(前期对话 m00001):2.1.2 与 2.1.3 的 CI run 均 success(run `42188255718`、`42192179962`)。
101
+
102
+ ---
103
+
104
+ ## 三、关键命令清单(一键脚本可直接复用)
105
+
106
+ | 序 | 命令 | 作用 | 来源 |
107
+ |---|---|---|---|
108
+ | 1 | `npm run build` | 构建:`rm -rf dist && tsc -p tsconfig.json && cp dist/*.js lib/ && cp dist/client.js client.js` | package.json:68 |
109
+ | 2 | `npm run check` | 类型检查 `tsc --noEmit` | package.json:69 |
110
+ | 3 | `npm test` | build + 全量用例 | package.json:70 |
111
+ | 4 | `npm run verify` | `check && test` | package.json:71 |
112
+ | 5 | `git status --short` | 发布前工作区干净检查 | RELEASING.md:25 |
113
+ | 6 | `git diff --exit-code -- lib client.js` | 构建产物无差异 | RELEASING.md:32 |
114
+ | 7 | `git add -A && git commit -m "..." && git tag -a vX -m "..."` | 提交并打注释 tag | RELEASING.md:95-97 |
115
+ | 8 | `git push origin main && git push origin vX` | 推送分支与 tag | RELEASING.md:98-99 |
116
+ | 9 | `git clone --depth 1 --branch vX ... && npm ci && npm run build && npm pack` | 干净打包生成 tgz | RELEASING.md:109-111 |
117
+ | 10 | `gh release create vX <tgz> --repo abbaababa/dsh-workplan --title "..." --notes-file ...` | 建 Release 并上传制品 | RELEASING.md:115-118 |
118
+ | 11 | `curl -sIL -o /dev/null -w '%{http_code} %{size_download}\n' <release-url>` | 验证制品可下载 | RELEASING.md:124-125 |
119
+ | 12 | `npm whoami` / `npm publish` | 登录校验 + 发布 | RELEASING.md:131-132 |
120
+ | 13 | `npm view dsh-workplan@X version dist.tarball` / `npm view dsh-workplan@latest version` | 验证已发布且 latest 正确 | RELEASING.md:133-134 |
121
+ | 14 | CI:checkout → setup-node22 → `npm ci` → `npm run verify` → `git diff --exit-code -- lib client.js` | 推送即自动验证 | verify.yml:15-31 |
122
+
123
+ ---
124
+
125
+ ## 四、给 T2(脚本工程)的要点提示
126
+ - 顺序铁律:检查 → 改版本四处 → 构建 → 测试 → 提交打 tag → 推 tag → GitHub Release(带 tgz) → npm publish → 验证。
127
+ - 两处「非本仓库权限」:索引源 catalog 由上游 CI 触发(步骤 5)、服务重启/加载新代码由运行环境负责(不在脚本内,前期对话中用户手动重启 PID 9137)。
128
+ - `npm publish` 需 `NPM_TOKEN` 或已登录账号;`gh release` 需 `gh` 已登录且对 `abbaababa/dsh-workplan` 有写权限。
129
+ - 回滚命令(步骤 7)建议也纳入脚本的 `--rollback` 分支。
@@ -0,0 +1,37 @@
1
+ # 版本与变更基准冻结清单(T2 · 2026-11-09)
2
+
3
+ 采集时刻:2026-11-09T13:08+08:00;仓库:`/Users/open/Documents/Stocks/plugins/dsh-workplan`(`git rev-parse --show-toplevel` 确认为仓库根)。
4
+
5
+ ## 1. 版本号三处对照(A1)
6
+
7
+ | 口径 | 结果 | 证据 |
8
+ |---|---|---|
9
+ | package.json `version` | **2.2.6** | `node -e require('./package.json')` → `dsh-workplan@2.2.6` |
10
+ | 构建产物/源码标记 | **2.2.6** | `src/host.ts:1574` `version: '2.2.6'`;`[2.2.6]` 标记 src 12 处(plan.ts 8 / runtime.ts 3 / understanding.ts 1),lib 对应 plan.js 8 / runtime.js 3 / understanding.js 1,一一对应 |
11
+ | 索引源 & npm 已发布版本 | **2.1.5** | 插件目录索引 `dsh-plugin-catalog/index.json`(unpkg 拉取,目录版本 2026.1109.17642)中 dsh-workplan 仅登记 versions=[2.1.5];npm registry dist-tags.latest=2.1.5 |
12
+ | CHANGELOG 顶部条目 | 2.2.6 — 2026-11-08 | `head CHANGELOG.md` |
13
+
14
+ **冻结结论:本次发布的「最新版本」= 2.2.6**。已发布基准为 2.1.5(tag v2.1.5,commit 6ed12d3),2.1.5 之后全部 2.2.x 内容目前只存在于**未提交的工作区**。
15
+
16
+ ## 2. Git 基线与未提交变更(A2)
17
+
18
+ - 分支 `main`,HEAD `6ed12d32af03d22d5024eb1d9fbb1c20a7546781`(= tag v2.1.5 = 已发布基准)。
19
+ - 未提交变更:**30 个已跟踪文件修改 + 23 个未跟踪新文件**,含全部 2.2.x 源码(src/ 与 lib/ 10 组)、CHANGELOG.md、package.json/package-lock.json、13 个新测试、`release.sh`、`docs/release-records/*`、`src/notice-channel.ts` 等。
20
+ - **判定:包含**。版本号 2.2.6 只存在于未提交变更中,不提交则「发布 2.2.6」无从谈起——发布前必须先把这些变更作为 2.2.6 提交(该提交由发布脚本/T4-T5 执行,本清单已将其显式纳入范围,无静默纳入)。
21
+ - 构建产物新鲜度:T2 已执行 `npm run build`,build 后 lib/ 与当前 src 同源(编译成功、产物含 2.2.6 标记);发布脚本构建步骤再次构建即可保持同源。
22
+ - 遗留杂物:未跟踪 `dist-tests-t4/`、`handoff-need-serialization.test.ts`(根目录散件,tests/ 下已有同名)建议发布提交时不纳入或清理,由主 Agent 决定。
23
+
24
+ ## 3. 敏感信息初筛(A3)
25
+
26
+ - 密钥类模式(sk-/ghp_/AKIA/api_key/password/token 硬编码)扫描变更范围内文件:**0 命中 → 通过**。
27
+ - 本地绝对路径 `/Users/open`:4 处命中——`CHANGELOG.md:138/180/2233`、`RELEASING.md:61`、`docs/release-records/release-steps-20261106.md:3`、`release.sh:271`(含 W5_ROOT_LOG 默认值)。均为机器路径/日志路径,**非凭证**,泄露面为「暴露本机用户目录结构」,风险低。结论:**通过,附发现项**——建议 T3/T4 在发布文案与脚本中把 `/Users/open/...` 改写为相对路径或 `$(pwd)` 占位;若不处理亦可接受(公开仓库历史中已有同类)。
28
+ - 远端:`origin = git@github.com:abbaababa/dsh-workplan.git`(SSH),与索引源登记的 `github.com/abbaababa/dsh-workplan` 一致。
29
+
30
+ ## 4. 待发布内容清单(冻结范围)
31
+
32
+ 以「发布提交 = 当前工作区全部变更(30 修改 + 22 有效新文件,剔除 §2 杂物 2 项)」为冻结范围,版本号 2.2.6,构建产物 lib/ + client.js 由发布脚本构建步骤生成。凭证与推送执行属 T1/T4/T5 结论,本清单不预设。
33
+
34
+ ## 5. 待确认项(移交)
35
+
36
+ - 索引源提交协议(catalog 是第三方聚合索引,登记机制/是否需 PR 或自动同步 npm)→ T1/T6 结论。
37
+ - GitHub 凭证可用性(SSH key / gh CLI / token)→ T1 核查。