oss-watch · 开源组件升级监测与执行技能

一句话用法：对本仓库的 AI Coding Agent 说「升级开源组件」，即自动走完全流程：扫描 → 出计划 → 你圈范围 → 逐项升级 → 门禁 → 发布。 纪律：扫描可以自动；升级走独立 PR——「更新计划组批 → 门禁测试 → 按协议 §1/§9.5 合并」；破坏性/大版本升级按 §3 人审放行，人保留叫停与回滚权。禁止裸 pnpm update 直接提交。 可选提醒：本机制为可选能力——开发者不主动发起时，仓库不做任何强制性的组件检查/升级拦截；想知道有没有可更新项，随时 pnpm oss:plan 看一眼即可。

〇、本仓身份

本仓库属于 WorkLoom 织元开源底座家族（Agent IM 通用底座及行业发行版）。本技能只管当前这一个仓库的组件健康——你不需要、也无权限关心其他仓库。

一、机制四件套（仓库内）

pnpm oss:watch    # 一键触发：扫描到期组件 → 生成/刷新《开源组件更新计划》
pnpm oss:plan     # 只看当前计划（不扫描）

二、组件仓库地址的登记纪律（回答「不列地址有没有影响」）

有影响，且分通道影响不同——清单中每个组件都必须填 repo 字段：

多命名空间 tag 的仓库（如 tauri 的 tauri-v2.x 与 v1.x 并存）须加 tag_prefix 字段（清单内 tauri 已配 tauri-v），否则 semver 排序会选错命名空间。

三、周期策略（cadence）

未到期组件自动跳过——组件量大也不扰动开发节奏。

四、标准流程（Agent 执行剧本）

0. 环境预检（执行升级前必跑，沉淀自 2026-08-26 实战）

# ① Node 版本：项目 engines 要求 >=24（dsh rc.2 起硬性依赖 node:zlib 的 zstd API）
node -v   # 必须 ≥24；不足则：NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node nvm install 24 && corepack enable
# ② corepack/pnpm 代理（直连 npmjs 不通时必须）：
export COREPACK_NPM_REGISTRY=https://registry.npmmirror.com COREPACK_INTEGRITY_KEYS=0
# ③ 数据库：docker start workloom-im-pg
#    注意容器映射 5432 而 .env 用 5433——缺转发时：socat TCP-LISTEN:5433,fork,reuseaddr TCP:127.0.0.1:5432 &
# ④ 测试/套件前清残留服务（防端口串台）：
pkill -f "[t]sx.*src/index"; pkill -f "[v]ite"
#    ⚠ pkill 模式必须带 [t] 字符类——裸写 pkill -f "tsx.*" 会匹配 pkill 自己的命令行导致自杀
# ⑤ 套件（suite）必须在净库单跑：脏库重置 = drop/create 数据库 → pnpm db:migrate → pnpm db:seed → 单次跑完

1. 扫描：pnpm oss:watch → 宣读计划（组件/现版/最新/跨度/建议）→ 用户圈定范围

2. 逐项升级（一批一 commit，dsh 永远单独一批）

3. 门禁矩阵（升级后必过，组件升级时全部执行，不可只跑 smoke）

任一失败 → 立即回滚该批，计划中标「⛔ 阻塞+原因」，禁止带伤发布。

4. 发布

• 全绿 → commit（chore(oss): <pkg> a→b（门禁明细））→ push → 在 docs/oss-update-plan.md 标「✅ 已发布(hash)」
• 发布前建议对仓库做一次完整快照（git bundle/镜像仓），事故可整体回切

五、新能力评估（每次升级计划必填 · 人工裁决）

底层组件升级常带来新能力而不仅是修复。计划的「新能力评估」模块列出线索，是否产品化由人判断。2026-08 批次示例：

六、历史踩坑（每次升级前重读）

1. Node 版本是硬门禁：dsh rc.2 起必须 Node ≥24（createZstdDecompress），低版本报 node:zlib does not provide export——先对齐 engines 再升级。
2. set -euo pipefail 下的 find 静默中止：PTY=$(find 不存在目录 ...) 返回非零直接杀脚本——兜底 || true（dsh-gate.sh 已修）。
3. fixture 门控互踩：「空表才灌」遇上「扩充运行态先占表」→ 新装环境 e2e 七连挂（D36）。幂等 fixture 不得用空表门控（已修）。
4. 残留服务打错库：套件打到别的服务进程（并发上限误报、simulated/real 串台）——测试前必 pkill -f "[t]sx.*src/index"。
5. 套件状态残留：模式切换类用例要求净库单跑；失败先想「库干不干净」，再想代码。
6. corepack 双坑：默认 registry 拉不到 pnpm + 镜像签名校验失败——固定 COREPACK_NPM_REGISTRY + COREPACK_INTEGRITY_KEYS=0。
7. pnpm --filter 包名匹配不稳：私有 workspace 包用 pnpm -C <dir> 直操作。
8. tag 命名空间：tauri 双轨 tag（tauri-v2/v1.x）——清单配 tag_prefix。
9. 转发随沙箱休眠中断：5433 突然 ECONNREFUSED 先查 socat 进程，别怀疑代码。
10. 中断残留误判：上次中断的套件留下的测试行会污染后续断言——净库是最高优先级排障动作。

七、登记纪律

• 新装运行时依赖必须同步登记进 oss-components.json（含 repo 地址）；AGPL 仅独立进程并注明。
• 归档/停更上游每季度复核活性；供应链/CVE 事件走 event 通道即时查。
• 本机制随仓库开源分发：你在自己 fork/clone 里改清单、调周期、跑升级，都只需要管这一仓。