docs(平台线): 版本管理与包更新机制拍板落地（C案→B案 · 执行棒登记）

用户拍板（2026-09-26 06:36 原话）：「C 方案，然后B，这次就用版本更新机制去更新网络上各节点，子节点和设备」口径（唯一执行单 = 交付物/版本管理与包更新机制-现状与方案-20260926.md） - 用户说的 C 案 = 层 A（止血）+ 层 B-1~B-4（版本目录化 / channel 灰度 / 定向钉版 / 设备纳入） - 随后做的 B 案 = 层 B-5（全局版本矩阵视图） - 层 C 跨区拓扑本次不做（属覆盖网络线），但实现须兼容其口径 - 收尾必须真跑一次分发到 47 本机 worker + 106 子节点 + 设备 - 执行棒第一件事 = 取证设备（桌面端）侧载体（承缺陷 D6）本棒产出 - 交接单 §5 改为「已拍板」+ 新增 §8 执行棒细化（S1 止血 → S2 完整版本管理 → S3 全局矩阵视图 → S4 真跑分发） - 入口 §0 落 06:36 拍板行 + §2 落续作二/续作三注 - 05-交接单/README.md §一第 44 行追加拍板（该目录 gitignore → 不入库，按既有口径） - 执行棒 automation da73ab87-fb2f-47f0-a8d8-8ea3ad35eb19（一次性 · 2026-09-26T06:52）事故与判据（已自愈 · 无损） - tmp/p36/patch-c3.py 复合式 open(P,"wb").write(join(...)) —— Python 先求值 open() 即截断， join() 再抛 TypeError ⇒ 入口被清成 0 字节；已 git checkout -- 复原（341,330 B / 968 行， sha 1d44073b… 与 HEAD 逐字节一致），随后改用 Edit 精确片段替换补写 - 新增铁律：改共享文件只准 Edit 片段替换，或「先算全量 bytes 再一次性写」；禁用 open(...,"wb").write(表达式) 复合式边界 - 未改 D:/github/dsh_shenxian/src/** 一行（只读取证） - 未 ssh 真机做任何变更；未碰他线在途改动（CODEBUDDY.md / state.py / MEMORY.md 等）
2026-09-26 06:45:59 +08:00
1 parent a38d8b674d
commit 2a1226ca13
@@ -116,3 +116,49 @@
 ### 🔴 未登记下一棒
 §5 有 **1 项待拍板**（修到什么程度：只修超时 A ／ A＋全局视图 C ／ A＋完整版本管理 B）⇒ 依「要用户拍板的，等拍了再新建接续会话」**⛔ 未登记 automation**。我的倾向：**A 先落、C 紧随**。
 ## IM 反向通道定案棒（06:3x）
 - **用户拍板**：「都需要实现完整，才能让插件接入，否则两边都要返工」⇒ 反向通道（平台 → 插件）**必须补、做完整**。
 - **本棒只定案不实现**（会话预算 18 万＋，硬约束）⇒ 产出施工规格 `接续包_IM反向通道实现_20260926.md`（含设计已定项/文件清单/验收/回滚/开工命令）+ 登记执行棒 automation `cce748b8`。
 - **设计要点（已定项）**：实例侧 SDK **长轮询拉取**（保持"拨出式"，⛔ 平台不打进实例、⛔ 不需实例可寻址、⛔ 不新增凭据）；
  `speak.check` 同步（带 deadline）· `event.deliver` 异步（不阻塞消息流）；
  超时缺省**放行**（与同进程 `binding.ts` 口径逐字一致，⛔ 不新增"不可达即冻结房间"）+ 具名计数；契约可声明 `onTimeout:'deny'`（回合制必须声明）；每实例有界队列，满则丢最旧并计数。
 - **口径同步 3 处**：09 §10.4/§10.5/§12.5 · `交付物/IM插件跨进程桥-20260925.md §5/§6` · `交付物/插件对接答复件-20260926.md §0`。
 - 🔴 **实测发现**：`p36c-platform-versioning` 会话持 `src/web`、`aliyun-dsh-server/交付物`、`.workbuddy`、`05-交接单` 域
  ⇒ 执行棒必须先 `preflight-lock.sh`；`src/web` 未释放时**先做不冲突部分**（新文件/文档），`routes/im.ts` 放最后。
 - **教训（沿用）**：跨进程能力的**单测替代不了真 HTTP 验收**（本线 09-26 已实证一次）。
 ## 插件投放与分库线 · 第 36 棒续作三 · 拍板落地棒（2026-09-26 06:36）· 会话 `p36d-platform-versioning`
 ### 拍板原话（用户本人 · 06:36）
 「**C 方案，然后B，这次就用版本更新机制去更新网络上各节点，子节点和设备**」
 ### 口径（⛔ 别被方案里的层名混淆）
 - 用户说的 **C 案** = 层 A（止血 20 s↔300 s／按大小动态／重试退避／失败留痕）＋ 层 B-1~B-4（版本目录化／channel 灰度／定向钉版／**设备纳入**）。
 - **随后做** 的 **B 案** = 层 B-5（全局版本矩阵视图）。
 - **层 C 跨区拓扑本次不做**（属覆盖网络线架构层），但实现须**兼容**其口径：每区 Manager 各持内容源、节点只向本区拉、同版本号须字节一致。
 - **收尾必须真跑一次分发**：`[email protected]`（含以后版本）→ **47 本机 worker ＋ 106 子节点 ＋ 设备（桌面端）**，读数验证（`w-106` 对账快照 `stale`/`failed` 清空）。
 - 🔴 **执行棒第一件事 = 取证设备（桌面端）侧载体**（承缺陷 D6「设备不在分发链上」）：桌面端有无「包/插件目录 ＋ 拉取入口」、凭据走哪条。**有 ⇒ 按同一对账协议接入；没有 ⇒ 具名报告缺口 ＋ 给最小接入方案，⛔ 不硬造。**
 ### 产出（本棒只做记录落地，⛔ 未改 `src/**`）
 - 唯一执行单 `交付物/版本管理与包更新机制-现状与方案-20260926.md`：§5 改为「🔴 已拍板」＋ **§8 执行棒细化**（§8.1 S1→S4 顺序表／§8.2 未知项三条／§8.3 既有纪律）⇒ 14,893 B。
 - 入口 `接续入口_插件投放与分库线_20260922.md`：§0 落 06:36 拍板行（最新一行 = 执行依据）＋ §2 落「续作二／续作三」注 ⇒ 343,592 → **已含两节**，977 → 986 行。
 - `$DOC/05-交接单/README.md §一` 第 44 行（04 单状态行）追加 06:36 拍板 ＋ §8 细化 ＋ 执行棒登记。
 - ✅ **执行棒 automation = `da73ab87-fb2f-47f0-a8d8-8ea3ad35eb19`**（一次性 · `2026-09-26T06:52`）；本线入口 automation `35e1bfbc-…` 保持 `PAUSED`。
 ### 🔴 本棒事故（已自愈 · 值得进技能）
 `tmp/p36/patch-c3.py` 步 1 成功（交付件 §5/§8 落盘），步 2 报 `TypeError: sequence item 11: expected a bytes-like object, str found`（`NEW0` 漏 `.encode("utf-8")`）。**真正的伤害不在那行 TypeError** —— 复合式 `open(P,"wb").write(b"\n".join(parts))` 的求值顺序是 **先 `open()`（立即截断！）→ 再求值 `join()`**，join 抛错 ⇒ **入口被清成 0 字节**。
 - **发现方式**：事后 `wc -c` 得 `0`（若只看脚本 traceback 只会以为"没写进去"）。
 - **复原**：`git checkout -- <入口>`；HEAD 版 = **341,330 B / 968 行**、含 06:29 规划棒行、且远端对账 `0 0` ⇒ **无损**；复原后 `git hash-object` == `git rev-parse HEAD:<file>` = `1d44073b…`。
 - **判据（新增铁律）**：改共享文件**只准** Edit 精确片段替换，或「**先算全量 bytes 再一次性写**」；⛔ **禁用 `open(...,"wb").write(表达式)` 复合式**（表达式求值前文件已被清空）。同源风险：**任何"写前先 open 再算内容"的写法**都有此坑。
 - ✅ **补救**：改用 Edit 工具做三处插入（入口 §0／§2、README §一），不再走整文件覆盖。
 ### 边界
 ⛔ 未改 `D:/github/dsh_shenxian/src/**` 一行（只读取证）；⛔ 未 ssh 真机做任何变更（本棒纯记录落地 ＋ 收口）；⛔ 未碰他线 `src/web`·`routes/im.ts`。
@@ -102,7 +102,16 @@
 ## 5 决策点（**待拍板 = 1 项**）
-**要用户定的是**：106 拉包超时要修到什么程度 —— 只把超时调大让它能拉完，还是顺手把"版本管理"补成可灰度可回滚的机制？
+**🔴 已拍板（2026-09-26 06:36 · 用户本人原话）**：「**C 方案，然后B，这次就用版本更新机制去更新网络上各节点，子节点和设备**」。
 **口径对齐（⛔ 执行棒务必按本行理解，勿被 §2 的层名混淆）**：
 - 用户说的 **C 案** = 本文 **层 A（止血）＋ 层 B-1~B-4**（版本目录化／channel 灰度／定向钉版／**设备纳入**）——「完整版本管理」。
 - 用户说的 **B 案（随后做）** = 本文 **层 B-5**（全局版本矩阵视图）。
 - **层 C（跨区拓扑）本次 ⛔ 不实施**（属覆盖网络线架构层）；但实现须与其口径兼容：每区 Manager 各持内容源、节点只向本区拉、同版本号须字节一致。
 - **收尾必须用这套机制真跑一次分发**：`[email protected]`（含以后版本）→ **47 本机 worker ＋ 106 子节点 ＋ 设备（桌面端）**，并读数验证。
 - ✅ **执行棒已登记** = automation `da73ab87-fb2f-47f0-a8d8-8ea3ad35eb19`（一次性 · 2026-09-26T06:52）。
 **原三选项（存档）**：
 - **A 案（只修超时，层 A）**：优点 = 改动小（两处常量 ＋ 一个重试）、当天可验、106 立刻能拿到修复；缺点 = 版本管理仍是"最新一份"，下次要灰度/回滚还得再做一轮。
 - **B 案（层 A ＋ 层 B）**：优点 = 一次把"节点与设备的版本管理与更新机制"补齐（含全局矩阵视图）；缺点 = 要动 manifest 结构与装配口径，回归面更大，且要新增概念（channel），周期长。
@@ -123,3 +132,30 @@
 ## 7 本轮已改文件（⛔ 仅本工作区产物，未碰 `src/**`）
 - 本文件（新建）｜入口 §0／§2 ＋ `$DOC/05-交接单/README.md §一` ＋ 当日日志（收口行）
 ---
 ## 8 执行棒细化（拍板后新增 · 2026-09-26 06:36）
 ### 8.1 子阶段顺序（⛔ 不许跳、不许换序）
 | 子阶段 | 内容 | 完成判据 |
 |---|---|---|
 | **S1 · 止血** | 层 A-1~A-4（拆超时 20 s↔300 s／按大小动态／重试退避 2s·8s／失败留痕） | 106 对账快照 `stale` 不含 `dsh-plugin-mcn-suite`、`failed` 为空 |
 | **S2 · 完整版本管理** | 层 B-1 版本目录化 ＋ B-2 channel（stable/canary）＋ B-3 定向钉版 ＋ **B-4 设备纳入** | 能"只让某节点/设备升到指定版本"、可回滚到任意历史版；**设备侧真跑通一次拉取** |
 | **S3 · 全局矩阵视图** | 层 B-5 `GET /api/plugins/shared/status` | 一屏返回「每 flat × 每 host/设备」的版本、指纹、漂移、最近成功时间 |
 | **S4 · 真跑分发**（收尾必做） | 用 S1–S3 落成的机制把 `0.5.1` 分发到 **w-47 ＋ w-106 ＋ 设备** | 三处读数一致；`w-106` 快照 `stale/failed` 清空 |
 ### 8.2 未知项与处置（⛔ 不许"假装知道"）
 1. **设备（桌面端）侧载体未取证**（承 D6）⇒ **开工第一件事就是取证**：桌面端有没有「包/插件目录 ＋ 拉取入口」、凭据走哪条（序46/47 的设备 grant？）。**有 ⇒ 按同一对账协议接入；没有 ⇒ 具名报告缺口 ＋ 给最小接入方案，⛔ 不硬造。**
 2. **`manifest` 是共享层旁的旁挂状态文件** ⇒ 改其结构须**向后兼容**（老节点读新 manifest 不能崩）。
 3. **`src/worker` 属机制层** ⇒ 域锁必须**独占**（开工前确认无其他会话在跑）。
 ### 8.3 必须遵守的既有纪律
 - 新增能力 ⇒ **纯插入**；修 bug ⇒ 可改既有逻辑但**须回归用例 ＋ 新行为可观测 ＋ 阈值可注入**（超时/重试次数一律走 env，⛔ 不写死）。
 - 测试跑 `lib/` ⇒ **改完必 `build`**（否则新旧产物混跑，症状像"注入无效"）。
 - ⛔ 不改 `07-scripts/`；⛔ 不动 `config`/`crypto`/`isolation`/`index` 等机制层其他文件（只碰必需者且先报告）。
 - 生产变更（`restart dshs-worker` / 47）可直接做，**动手前一句话说明**；不可逆操作先报清单。
@@ -9,6 +9,15 @@
 ## §0 状态（**最新一行 = 执行依据**）
 - 🔴 **2026-09-26 06:36｜用户拍板 ⇒ 执行棒已登记（`p36d-platform-versioning`）—— 本线最新一行，🔴 **执行依据以本行为准** ——**
  **用户原话**：「**C 方案，然后B，这次就用版本更新机制去更新网络上各节点，子节点和设备**」。
  **口径（⛔ 别被方案里的层名混淆）**：用户说的 **C 案** = **层 A（止血）＋ 层 B-1~B-4**（版本目录化／channel 灰度／定向钉版／**设备纳入**）；**随后做**的 **B 案** = **层 B-5**（全局版本矩阵视图）；**层 C 跨区拓扑本次不做**（属覆盖网络线架构层），但实现须与其口径**兼容**（每区 Manager 各持内容源、节点只向本区拉、同版本号须字节一致）。
  **收尾必做**：**用这套机制真跑一次分发** —— `[email protected]`（含以后版本）→ **47 本机 worker ＋ 106 子节点 ＋ 设备（桌面端）**，并**读数验证**（判据：`w-106` 对账快照 `stale`/`failed` 清空）。
  🔴 **执行棒第一件事 = 取证设备（桌面端）侧载体**（承缺陷 D6「设备不在分发链上」）：桌面端有没有「包/插件目录 ＋ 拉取入口」、凭据走哪条。**有 ⇒ 按同一对账协议接入；没有 ⇒ 具名报告缺口 ＋ 给最小接入方案，⛔ 不硬造。**
  📂 **唯一执行单** = `交付物/版本管理与包更新机制-现状与方案-20260926.md`（§6 八段交接要素 ＋ **§8 执行棒细化** S1→S4）。⛔ 过程档案 `04-调整方案/` 不作依据。
  ✅ **执行棒 automation = `da73ab87-fb2f-47f0-a8d8-8ea3ad35eb19`**（一次性 · 2026-09-26T06:52）；⛔ 本线入口 automation `35e1bfbc-…`（第 36 棒）保持 `PAUSED` 不动。
  ⚠️ **本轮事故留档**：`tmp/p36/patch-c3.py` 用 `open(P,"wb").write(join(...))` ⇒ Python 先求值 `open()`（**立即截断**）再求值 `join()`，join 抛 `TypeError` ⇒ **入口被清成 0 字节**；已 `git checkout --` 复原（341,330 B / 968 行，sha `1d44073b…` 与 HEAD 逐字节一致，**无损**）。⇒ **判据：改共享文件只准 Edit 精确片段替换或「先算全量 bytes 再一次性写」，⛔ 禁用 `open(...,"wb").write(表达式)` 复合式**。
 - 🔴 **2026-09-26 06:29–06:5x｜用户授权「你就是平台线」⇒ 第 36 棒续作二 · 规划棒（`p36c-platform-versioning`）—— 只读取证 ＋ 出方案，⛔ 未改 `src/**` 一行；⛔ 未登记下一棒（撞 1 项待拍板）** ——
  **用户原话**：「**你就是平台线，看看如何修复（还有 worker 如何更新包，是不是应该有个机制，现在的网络结构各种节点和设备，如何进行版本管理和包更新机制）**」⇒ **本轮按「规划与执行分离」只产出方案**。
  **成果** ⇒ `交付物/版本管理与包更新机制-现状与方案-20260926.md`（**同时是下一棒的「唯一执行单」**，含 8 段交接要素）。要点：
@@ -469,6 +478,8 @@
 ### 🗃️ 本轮动作（**第 36 棒 · 执行棒 · ✅ 已收官 23:5x** —— 仅供追溯，⛔ 不要按它开工；**下一棒未登记（等拍板）**）
 > 🟢 **第 36 棒续作（2026-09-26 00:17 用户两条拍板）**：**① A 案 ⇒ A2 实例进程内面达成**（实例一直 running@20001；`/mcn/api/accounts` `200` · `total:5`；上一棒所据 PG 台账 `stopped` 是滞后失真）；**② 「worker 用插件更新机制」⇒ 机制已落地且在跑**（worker `POST /shared-layer/pull` ＋ 定时拉），真机对账快照 `w-106` **`stale:[mcn-suite]` ＋ `failed:[timeout]`** ⇒ **自主拉取成立、该件拉取超时失败** ⇒ A8 改判。⛔ 平台侧问题（拉取超时／台账滞后）**只报告不改码**。详解 ⇒ 交付件 **§9**。
 > 🔴 **第 36 棒续作二（2026-09-26 06:29 用户授权「你就是平台线」）**：本会话**转为平台线**，只读取证 ＋ 出方案 ⇒ 产出 `交付物/版本管理与包更新机制-现状与方案-20260926.md`（**骨架齐全 ⇒ ⛔ 不是"没有机制"**；**根因 D1** = `src/worker/agent.ts:376` 那个 **20 s 超时常量被对账面 `:426` 与下载面 `:508` 共用** ⇒ 2.0 MB 包跨云拉不完；另 7 条 D2–D8）。⚠️ **该轮只读取证，⛔ 未改 `src/**` 一行**。
 > 🔴 **第 36 棒续作三（2026-09-26 06:36 用户拍板）＝ 本线当前执行依据**：**「C 方案，然后B，这次就用版本更新机制去更新网络上各节点，子节点和设备」** ⇒ 层 A ＋ 层 B-1~B-4（= C 案）先做 → 层 B-5（= B 案）随后 → **层 C 跨区拓扑本次不做**（属覆盖网络线）；**收尾必须真跑一次分发到 47 本机 worker ＋ 106 ＋ 设备**；**执行棒第一件事 = 取证设备侧载体**（D6）。🔴 **执行棒 automation = `da73ab87-fb2f-47f0-a8d8-8ea3ad35eb19`**（一次性 · `2026-09-26T06:52`）⇒ **唯一执行单 = 上述交付件**（§6 八段 ＋ **§8 细化 S1→S4**）。⛔ **不要按本节下方「第 36 棒」旧范围开工**。
 > 📦 **第 36 棒已收官**（`p36-exec-plugin-dataline`）：**①–④ 全达成**（修 `canonicalJsonText()` 键序敏感＋单测 67/67 → 出包 `0.5.1`＋上池＋发布共享层 → 删本地 5 条冗余行 39→34 → 影子读**三表全 match、内容 34/34 差异 0**）；**⑤ 仅「47 侧切档」达成**（**7 表 `platform`**，A5 达成；A2 切档后读路径全 OK）。
 > ⛔ **未达成 2 项**：A2「真实例进程内」面（实例 `stopped`，未启动 —— 直调 worker `/launch` 会绕过控制面台账，主动不做）｜**106 同步＋合并重启**（ssh `Permission denied (publickey)`，无通道）⇒ **A8 如实记「两机不一致」**。