WorkBuddy 连接器 CLI 修复
连接器（飞书 / 知识星球…）在桌面端表现为「连接异常」，但底层往往是一条 CLI 入口断裂：
npm 在自动升级时 postinstall 失败 → 回滚把入口包目录删空 → 所有命令报 Cannot find module。
先取证，再动手。 不要一上来就重装连接器——重装走的是同一条坏路（npm + curl），大概率再坏一次。
§1 · 触发信号
| 用户表述 | 真相 |
|---|---|
| 飞书/连接器「连接异常」 | 连接器状态通常仍显示 bound/enabled，实际是 CLI 调用失败 |
| 「连接器安装失败，退出码 1」 | npm postinstall 失败 → 已回滚并删空入口包 |
Cannot find module '...\@larksuite\cli\scripts\run.js' |
入口包被清空，这就是根因确认 |
| 昨天还能用，今天突然不行 | 多为后台自动升级触发 |
§2 · 判断规则（按顺序排除）
- 先分清是网络问题还是安装问题。 直连目标域名 + 用 Python
urllib请求 registry，
全通则网络无罪。别在网络上浪费时间。 - 看 npm 调试日志（
cli-connector-cache/_logs/*-debug-0.log）里的 postinstall 报错行。
出现curl: (N) ...→ 是下载器的问题，不是包源的问题。 - 看入口包是否被删空：
node_modules/<scope>/<pkg>/是空目录 = npm 回滚现场。 - 找 npm 留下的备份目录：同 scope 下的
.<pkg缩写>-<8位hash>（如.cli-30EeUkZZ）是
升级前被改名暂存的完好旧版，内含可用的二进制与入口脚本。
→ 有它 = 可以零下载回滚；没它 = 必须重新下载（见 §3）。 - curl 是否可用要实测：本机 curl 可能因进程上下文（线程/job 限制）报
(6) getaddrinfo() thread failed to start，去代理也一样报。
→ curl 不可用时，凡「npm postinstall + curl 下载二进制」的连接器安装都会失败。用 Python 下载绕开。
§3 · 修复流程
取证 → 判断 → 选路 → 安装 → 验证
- 取证：跑
scripts/repair_connector_cli.py --check（只读，不写盘）。 - 选路：
- 备份目录在 → 就地恢复（最快，零下载），版本停在旧版。
- 备份目录不在，或要对齐最新版 → Python 下载重装（推荐，一次对齐 registry 的
latest）。 - 安装：
--apply会自动备份旧载荷、清空目录、装新包、带上运行时依赖。全程不调用 curl / npm。 - 验证：必须走连接器自己的入口（不是直调 exe）跑一条真实业务接口，返回
ok: true才算修好。
§4 · 输出契约
给用户的结论必须包含：
- 一句话根因（不是网络问题 / 是升级回滚删了入口包）。
- 证据：npm 日志原始报错行 + 入口目录现状（空 / 有）。
- 改了哪些文件：给出路径与版本（旧 → 新）。
- 备份在哪（回滚路径必须明确告知）。
- 验证结果：入口版本号 + 一条真实接口的返回。
- 残留风险与后续（例：下次再有新版本，同一条坏路会复现；修复脚本在哪）。
§5 · 自检清单
- [ ]
--check已跑过，确认入口包状态（不猜） - [ ] 下载物的 checksum 已校验（tarball integrity + 二进制 sha256），不通过就中止
- [ ] 旧版本已完整备份到
node_modules之外（别留在 scope 目录里，npm 会再清） - [ ] 新包
scripts/run.js+bin/<exe>都在位 - [ ] 运行时依赖（
@clack/prompts等嵌套 node_modules）已带上 - [ ] 验证走的是连接器入口（shim），不是直调 exe
- [ ] 验证接口返回
ok: true（不是只看--version）
§6 · 配套资源
| 文件 | 内容 |
|---|---|
references/methodology.md |
为什么 npm 会删空入口包、curl 为何起不来、代理端口假死、npm staging 目录命名规律、验证闭环 |
references/sop.md |
全部路径、命令、校验值来源、分步操作与避坑清单（含本机实测记录） |
scripts/repair_connector_cli.py |
参数化体检 + 修复脚本（--check 只读 / --apply 执行），不依赖 curl 与 npm |
§7 · 下游路由
- 修好后要操作飞书文档/表格 → 技能
lark-sheets/lark-doc/lark-shared（连接器自带）。 - 修好后要配置飞书权限范围（scope）→
lark-shared；缺 scope 报错不是连接故障，别混为一谈。 - 其他 WorkBuddy 环境类故障（登录态、自动化调度）→ 见用户长期记忆中的「环境事实」小节。
