这次想做的事情，听起来很像一个批量命令：把所有依赖的上游拉下来，看看哪些有更新，有优势的就跟上，再把面板和知识库一起刷新。真正开始盘点以后，数字先把这个想象打破了：182 个能力关联到 164 个上游仓库，其中 162 个已经在本地有克隆。
如果把这件事理解成“批量执行拉取”，后面的每一步都会被压成同一种动作。可这些仓库在系统里承担的责任并不一样。有的只提供阅读材料，有的会被实际运行，有的已经有本地定制，还有的早已形成分叉。它们都叫仓库，却不能接受同一套更新待遇。
我一开始以为难点是规模，后来发现真正难的是判断：这次变化到底会不会碰到运行环境，会不会覆盖本地决策，会不会把“拉到了新提交”误报成“系统已经更新成功”。上游更新不是把远端状态搬到本地，而是让变化经过与它的角色相匹配的验收。
先把“更新”这件事拆开
在正式执行前，我先建立了依赖清单。清单不只记录某个能力对应哪个仓库，还要补上它在系统里的使用方式：它是知识源，还是会被调用的运行仓库，是否存在本地修改，是否已经偏离上游形成分叉。只有这样，后面才有可能决定一条仓库该走哪条车道。
这一步看起来不像更新，反而像整理资料，但它决定了风险边界。只当知识源的项目，主要任务是获取新的代码和文档供检索，通常可以采用快进式更新；真正运行的项目，代码变了还不够，依赖、环境和健康检查也必须重新通过；本地有定制或分叉的项目，最重要的不是自动覆盖，而是把差异报告出来，留给人工合并。
如果不先做这层区分，批量动作就会把知识变化和运行变化混在一起。一个只供阅读的仓库可能因为依赖没装而被错误回滚；一个正在运行的项目也可能只完成了拉取，却没有经过启动验证。最后面板上的“已更新”，只代表某个命令返回过成功，不代表系统真的变好了。
同一个上游提交，对知识源是新资料，对运行仓库是一次变更，对本地分叉则可能是一项合并工作。
3 条车道对应 3 种责任
第一条是知识源车道。它不参与当前运行链路，更新的价值在于补足阅读和检索材料。这里我更关心远端分支是否前进、工作区是否保持干净，不把不存在的运行环境强行装出来。这样可以避免为了“统一流程”给大量资料库增加无意义的安装成本。
第二条是运行态车道。它的顺序不能只是拉取、结束，而应该是更新、识别项目使用的依赖方式、重装依赖、运行健康检查，失败就回到更新前的提交。这里的依赖管理也不能凭习惯统一执行。有的项目使用 Python 环境，有的使用 npm，有的使用 pnpm 或 bun；包管理器和锁文件本身就是项目的一部分。
第三条是本地定制和分叉车道。只要工作区有真实改动、提交历史已经与上游分开，或者存在未跟踪文件阻断合并，就不能把它当成普通快进。它可以继续获取上游信息，但自动合并不是默认选项。报告清楚“为什么不能自动更新”，比为了增加成功数量而覆盖本地内容更有价值。
我选择分车道，是因为这 3 类项目的失败后果不同。知识源更新失败，通常影响资料新鲜度；运行态更新失败，可能影响功能可用性；本地分叉处理错误，则可能直接丢掉已经验证过的本地能力。风险既然不同，验收标准就不应该相同。
运行态必须把依赖和健康检查接上
这次执行中，某些仓库快进本身是成功的，但后面的依赖安装或健康检查失败，于是自动回滚到了旧提交。这个结果很重要，因为它说明“拉取成功”和“更新成功”不是一回事。一次变更只有在代码、依赖和基本行为都能接上时，才值得留在系统里。
其中有个项目安装依赖时长时间没有进展，后来确认是包索引和网络路径不合适。换用更合适的国内镜像后，几秒就完成了安装，并通过了关键包导入和依赖冲突检查。这里没有去改系统网络配置，只针对这一条安装命令调整来源，因为问题属于依赖下载，不值得扩大成全局环境变更。
另一个边界是项目没有现成的健康检查入口。此时不能因为缺少固定命令就把验证跳过去，而要退回到最小冒烟检查，比如在它自己的环境里导入本次更新涉及的关键包，确认基本依赖能被加载。验证可以因项目而异，但不能因项目不同而消失。
运行态更新的最小闭环是“新提交、依赖可用、基本行为通过、失败可恢复”，少一环都只能算处理中。
这也解释了为什么失败自动回滚很重要。更新前要记住旧的 HEAD，快进后再做依赖和健康检查；任一关键步骤失败，就恢复旧提交并确认工作区干净。这样失败的代价是一次可追踪的重试，而不是让半更新状态继续污染后面的任务。
最容易误判的是成功口径
首轮统计有 24 个上游真正前进。补跑以后，当天最终统计变成 85 个上游前进，164 个里有 127 个已经是最新。数字变大并不自动代表执行器变可靠，反而迫使我重新检查统计口径：到底什么才叫“前进”？
之前有一种情况，仓库因为未跟踪文件只能拉取，不能完成合并，但执行器仍然把它报成“已更新”。这会制造一种危险的确定感：总数很好看，真正的提交却没有变化。后来把成功判断改成检查 HEAD 是否前进，并把这个字段写进结果，才把“做过动作”和“产生了更新”分开。
这里最容易走的错误捷径，就是所有项目统一执行拉取、统一安装依赖、统一看命令返回值，再用总数掩盖少数失败。它省掉了判断，却把错误藏进统计里。如果不修正，下一次自动任务会把这些误报当成历史成功，继续在错误状态上叠加更新，直到有人需要人工追查整条链路。
包管理器缺失也暴露了同一个问题。一次批量任务不能因为某个项目没有安装指定工具就整轮崩溃，正确处理应该是记录该项目失败，继续处理其他项目；在允许的情况下，用项目声明的替代入口完成安装。失败要可定位，批量过程也要有隔离性。
我更愿意把验收记录成几项事实：HEAD 是否前进，工作区是否干净，依赖是否安装成功，健康检查或冒烟验证是否通过，失败时是否回到旧提交。面板上的“今日已更新 85”只有在这些事实可追溯时，才有管理意义。
知识库和面板要放在最后刷新
上游处理还牵涉知识库和面板。它们不是更新动作的附属装饰，而是结果的两个出口：知识库负责让后续查询能看见新内容，面板负责让人知道哪些成功、哪些落后、哪些需要人工介入。但这两个出口不能过早刷新，否则会把中间状态包装成最终状态。
这次联邦知识库重建后，从 5.3GB 降到 878MB；两字中文检索增加了兜底，查询耗时约 20-800ms。这个结果说明，刷新知识库不只是把文件重新生成一遍，还要同时验收体积、短词检索和查询速度。索引如果变小了，却搜不到常用词，仍然不能算完成。
面板也要展示过程中的差异，而不是只展示一个总数。最终当天显示已更新 85 个，仍落后 16 个，并能打开对应报告。那些需要人工合并、安全门拦截、依赖装不上后回滚、只拉不合的项目，应该保留原因和恢复状态。一个成熟的更新面板，不是把失败藏起来，而是让人一眼知道下一步该处理哪一种失败。
所以我把刷新顺序放在所有车道完成、结果对账之后。先完成更新和回滚，再重建知识库，最后更新面板。顺序本身就是一种保护：前面的事实稳定了，后面的展示才不会替它们做未经验证的结论。
下次我会怎么做
下次遇到类似的批量上游更新，我会先建立一张最小清单，至少包含依赖关系、仓库角色、当前 HEAD、工作区状态和本地分叉标记。没有这张清单，就不开始批量动作，因为我还不知道每个项目的成功条件是什么。
然后按 3 条车道处理：知识源只做安全的分支更新；运行态执行“更新—依赖—健康检查—失败回滚”；本地定制和分叉只获取信息并生成待人工处理报告。每条车道都记录可验证结果，不用一个总数替代细节。
最后才刷新知识库和面板，并做一次对账：HEAD 前进的数量是否与报告一致，已是最新的数量是否排除了抓取失败，失败项目是否真的回到干净状态，面板链接是否能打开。数字格式上可以很简洁，但判断链不能省略。
这件事让我重新意识到，批量的价值不是把很多命令同时发出去，而是让很多不同的对象各自接受正确的处理。一个流程成熟的标志，不是它能在顺利时一次跑完，而是它遇到卡死、缺工具、未跟踪文件和本地分叉时，仍然知道该停在哪里、退回哪里、把什么交给人。真正值得沉淀的，也不是某次更新了多少仓库，而是下一次面对同样规模时，不必再从“所有东西都一样”这个误判开始。