那天我想确认一件很具体的事：以后不管是哪个 Agent 在本地装项目，遇到 FFmpeg、Python、Node，或者大模型权重时，能不能先知道它们已经存在，直接复用，而不是每次重新安装？
表面上，这是在找一个安装工具。一个项目缺什么，就让它补什么，听起来也很自然。但当我把问题继续往下拆，才发现真正麻烦的不是“有没有安装命令”，而是同一台电脑里可能有多个 Python、多个虚拟环境、多个缓存根目录，还有不同 Agent 各自认识的一套入口。命令能运行，不代表它用的是我以为的那份资源。
一次安装，为什么会变成多份环境
这次讨论的范围一开始就不小。系统级依赖包括 FFmpeg 这一类工具，语言环境包括 Python、npm 和 Node，另外还要考虑大模型缓存。后来范围又扩展到代码和模型生态：GitHub 之外，还包括 Gitee、GitCode、GitLab、Hugging Face、ModelScope 等平台。
我一开始以为，只要做一个统一的安装入口，再给它加上“已存在则跳过”的判断，问题就解决了。后来发现，这个判断太粗了。一个叫 python3 的命令确实存在，但它可能来自另一套版本；一个虚拟环境确实有目录，但它的基础解释器可能已经被应用升级删除；一个模型文件确实找得到，但当前进程使用的缓存根目录可能不是那一处。
本地资源管理的难点，不是把东西装上，而是确认当前调用的到底是哪一份东西。
如果不处理这些差异，后面会出现一种很隐蔽的失败：项目在我的终端里能跑，换到另一个 Agent 启动就找不到包；模型明明下载过，非登录进程却又下载一遍；应用升级以后，原来依赖应用私有解释器的虚拟环境突然失效。每一次看起来都像“再装一次”就能解决，实际上是在继续制造分叉。
只看命令存在，是错误捷径
这次盘点给了我一个很具体的提醒。当前环境里能看到多份 Python，既有系统和包管理器提供的版本，也有 uv、WorkBuddy、桌面应用各自维护的版本。还有一些项目的虚拟环境依赖应用私有目录，其中一部分私有目录已经消失，虚拟环境只剩下一个看似完整、实际无法启动的壳。
Node 也不是只看 node 能不能执行就够了。命令可能经过转发脚本，实际落到另一份安装；包管理器也可能因为 PATH 顺序不同，优先使用旧版本。模型缓存更容易造成错觉：大模型本体可能已经通过软链共享，但 Hugging Face 缓存却存在多个根目录，环境变量只写在登录 shell 的配置里，后台进程并不一定能继承。
这里最容易误判的是“文件在”和“系统能稳定使用”之间的差别。文件在磁盘上，只能说明曾经下载或创建过；要判断能否复用，还要知道它的来源、版本、依赖者、路径是否有效，以及当前进程是否能看见它。
我没有直接让每个项目缺什么就现场安装，是因为这种做法会把一次性的方便，换成长期的不可见维护成本。安装动作越多，重复包、失效环境和缓存漂移就越难区分。以后排查问题时，大家只会记得“以前装过”，却没人说得清装在哪里、被谁使用。
先把资源分成几层
我更愿意先建立一张资源登记表，再决定安装还是复用。第一层是系统工具，比如 FFmpeg，它们通常由系统包管理器提供，重点是记录可执行文件位置、版本和调用来源。第二层是语言运行时，包括 Python、Node 和包管理器，重点是区分系统、包管理器、应用私有运行时和项目自带运行时。
第三层是项目虚拟环境。它不能只登记环境目录，还要登记 base 解释器从哪里来、当前是否有效、有哪些项目引用它。一个环境如果绑定了应用私有解释器，就应该被标成高风险，而不是因为目录还在就算作可复用资源。
第四层是模型权重和缓存。这里要把模型本体、下载缓存、转换后的权重和软链关系分开记录。第五层是代码和模型平台，用来回答“去哪里找现成能力”，而不是直接把平台当成安装来源。找项目、判断项目是否真实可用、安装本地依赖，是三个不同动作，不能混成一次搜索。
统一入口首先要做资源探测和登记，其次才是安装；没有登记的安装，往往只是把未知继续藏起来。
探测阶段应该只读完成几件事：解析命令的真实路径，读取版本，检查软链目标，确认虚拟环境的基础解释器，扫描缓存根目录，并把重复项、断链和失效引用标出来。这个阶段不删除、不移动、不升级，也不因为发现重复就急着清理。先把事实留下，后面才有安全的取舍。
复用、隔离和安装要有顺序
登记之后，统一入口才开始做决策。能稳定复用的公共资源直接复用，比如已经存在且来源明确的系统工具、与当前 Python 版本匹配的包缓存、已经登记过的模型权重。不能直接共享的资源要隔离，比如某些老项目必须使用旧版 Python 或固定版本的深度学习包，不能为了“统一”强行迁移。
只有确认本地没有合适资源，或者现有资源与目标不兼容时，才进入安装。安装前要记录目标版本、来源和预计写入的缓存根目录；安装后再做一次探测，确认入口、版本和依赖关系确实发生了预期变化。这比单纯检查命令退出码严格，因为命令成功可能只代表某一步执行结束，并不代表 Agent 下次仍会走到同一份环境。
我判断统一入口应当由 WorkBuddy 和其他 Agent 共同调用，是因为资源的所有权应该集中，而不是随着调用方复制。每个 Agent 可以负责提出需求，但不应该各自决定缓存放哪里、Python 从哪里来、同一个模型要不要再下载一遍。入口越统一，后续才越容易修正 PATH 优先级和非登录进程的环境变量。
环境变量也要进入管理范围
这次模型缓存的问题尤其说明，环境变量不是用户配置里的附属品，而是资源管理的一部分。如果 Hugging Face 的缓存位置只写在登录 shell 配置中，终端里看起来一切正常，后台任务、桌面应用或 Agent 启动的非登录进程仍可能使用默认目录，最后留下另一份残片。
所以统一入口不能只返回“模型已存在”。它还要给调用方注入明确的缓存根目录，并在启动前打印实际生效的路径。对于 Python 和 Node，也要把解释器路径、包管理器路径、项目环境路径作为同一组上下文传进去。这样排查时看到的不是模糊的“找不到”，而是可以继续追问的事实：这次任务使用了哪个解释器，写入了哪个缓存，复用了哪个已登记资源。
一个跨 Agent 入口的价值，不只是少输几条命令，而是让不同调用方共享同一套资源事实。
这里还有一个边界：统一不等于全部合并。应用私有运行时由应用自己管理，系统自带解释器不应该为了整齐而删除，必须保留的旧版本也不应该强行升级。统一入口要负责识别这些边界，并把它们标注为“隔离保留”，而不是把所有东西都塞进一个目录。
把方法变成可重复的流程
这件事让我重新意识到，依赖管理其实是在管理记忆。每次现场安装，都是把一次判断留在人的临场记忆里；统一登记，则是把“为什么复用、为什么隔离、为什么不能动”留给下一次调用。
以后遇到新项目，我会按这个顺序走：先探测系统工具、运行时、虚拟环境和模型缓存；再登记版本、来源、真实路径和引用关系；然后扫描重复、断链、失效环境与缓存漂移；接着判断复用、隔离还是安装；最后把统一入口实际使用的解释器、缓存根目录和平台来源记录下来。
这套方法也适用于代码平台的搜索。先在多个平台寻找已有项目，再判断项目的真实性、维护状态、运行条件和依赖关系，最后才决定是否接入。搜索平台的范围可以扩展，但判断标准不能因为平台变多而消失。真正可复用的不是某个网站上的一条命令，而是从发现到验证再到接入的完整链条。
下次我会怎么做
下次再遇到“这个依赖是不是已经装过”的问题，我不会先回答“有”或“没有”。我会先问它来自哪里、当前谁在使用、调用方能否稳定看到，以及它和目标项目的版本是否匹配。
如果只是目录存在，我会把它视为待验证；如果解释器、软链和缓存根目录都能对应上，才把它列为可复用。对于应用升级可能破坏的私有环境，我会提前标记迁移风险；对于非登录进程可能看不到的缓存位置，我会把环境注入作为入口职责，而不是交给每个 Agent 自己补。
一个流程成熟的标志，不是它能把安装动作跑通一次，而是下次面对同样的需求时，不需要重新猜测资源在哪里。我真正想统一的不是文件夹，而是判断：什么可以共享，什么必须隔离，什么还没有被证明安全。