我最近遇到一个看起来很直接、实际一点也不简单的任务：把一套已经在旧电脑上跑起来的视频自动化能力，搬到一台全新的 Mac 上。最初的想法很自然，既然用户希望 Agent 能自己读取，那就把现有目录压缩起来，再附上一份安装说明。压缩文件并不难，难的是打开压缩包以后，里面的每一行代码都不能继续假设“这就是原来那台电脑”。
这次盘点之后，我才发现真正需要搬运的不是一个文件夹，而是一组彼此牵连的假设：应用已经安装并登录，外部存储一定存在，字幕模板一定在某个位置，Python 环境里已经有对应的包，辅助工具也会从原来的目录出现。一个工具能在作者电脑上跑通，不等于它已经具备被别人安装的能力。
压缩包只是最后一层
这次需求一开始是“做一个压缩包和一键安装指引”。我没有马上打包，而是先盘点运行链路。因为如果不先盘点，压缩包越完整，越容易给人一种已经可移植的错觉。新电脑解压以后，可能第一步就找不到应用，第二步找不到模板，第三步又因为虚拟环境记录了旧电脑的绝对位置而停住。
我把问题拆成几类来看。第一类是宿主应用：它不是普通的 Python 依赖，必须在新电脑上安装，而且还要完成登录。第二类是系统工具和运行库，例如视频处理工具、系统命令行组件以及若干 Python 包。第三类是内容资产，尤其是默认字幕模板。第四类是旁路能力：主程序会调用一些辅助工具，但这些工具原本并不在主目录里。
这样的拆分很重要。应用登录不能靠压缩包解决，系统组件也不一定适合直接塞进包里；但模板和一部分确实必要的辅助文件，可以随包带走。可移植性不是把所有东西都装进去，而是把必须随包走的资产、必须在新机完成的动作和无法替代的人工授权分开。
最先暴露的是路径问题
盘点最先发现的是路径。十几个脚本直接指向旧电脑上的外部存储位置，工作目录、素材库和字幕模板都依赖那些位置。旧电脑上它们像常量一样可靠，换到新 Mac 后却根本不存在。默认模板还在外部存储里，新机即使已经装好应用，也会在真正开始处理前停住。
这里最容易误判的是：把几个路径改成新电脑的路径，就算完成迁移。实际上，路径散落在许多脚本里时，今天改对了，明天加一个脚本又会写回旧假设。并发改造还曾经暴露出另一个问题：代码已经换成调用统一的路径模块，却漏掉了多个文件的导入；有一个导入甚至落到了文件中间。表面上看是导入错误，根子上却是改造没有形成完整的检查闭环。
我的判断是，路径不能继续由每个脚本自己猜。我选择建立一个单一解析层，是因为它能把环境差异集中在一个地方处理：先看环境变量，再看设置文件，再看本机可用的外部目录，最后落到用户目录下的稳定位置。这样旧电脑可以继续使用原来的目录，新电脑没有外部存储时也有明确的本地落点。
这并不意味着所有路径问题都自动消失。调用方仍然必须真正导入并使用这个解析层，所以改完以后要逐个检查：凡是使用统一路径的文件，都必须能导入；凡是涉及路径的命令，都要在假用户目录里运行一次。路径单一来源的价值，不是少写几行字符串，而是让环境变化只需要被解释一次。
依赖要分成带走和现场完成
接下来我处理依赖。有人会自然地问，视频处理工具和 Python 环境能不能都放进安装包，到了新电脑直接编译就好。我没有把这个问题简单回答成“都带上”或“都现场装”，而是按依赖的性质拆开。
必要的 Python 包可以由安装器按清单创建独立环境并安装，必要的模板可以直接放在包内，少量稳定的辅助文件也可以复制进包里。宿主应用则必须由新电脑完成安装并登录，因为它涉及系统安装状态和用户授权。某些系统工具可以下载或调用已有安装方式，但安装器应该检查结果，而不是假设下载成功就等于可用。
如果不处理这种边界，后果会很具体：安装器显示“完成”，用户一运行主命令才发现模板缺失；或者虚拟环境创建成功，但里面仍然残留旧电脑的绝对位置；又或者一个辅助功能缺失，程序直接在深层调用里崩溃，用户不知道该补什么。
因此我把安装顺序设计成几个可观察的阶段：先确认宿主应用和登录状态，再检查系统工具，然后创建 Python 环境，接着放置模板和必要辅助文件，最后运行自检。缺少的项目要显示成清楚的诊断，而不是等到业务命令里才抛出模糊异常。对不属于主线的可选能力，也应该明确告诉用户“哪项缺失会影响什么”，而不是把所有缺失都伪装成安装失败。
错误捷径是把旧电脑整包复制
最容易走的错误捷径，就是把当前电脑的整个目录直接压缩，到了新电脑再靠报错逐个补路径和依赖。它看上去省事，实际上把旧电脑最隐蔽的状态一起打包了：绝对路径、虚拟环境记录、缓存、外部资源假设，甚至可能还有不应该外发的授权信息。
这种做法还有一个更难发现的缺点：每次报错只暴露当前遇到的第一个缺口。补完模板，才发现 Python 包缺失；补完 Python 包，才发现辅助工具不在；再补一个路径，才发现应用没有登录。用户不是在安装工具，而是在替作者做一次没有地图的环境考古。
我没有采用这个捷径，是因为迁移的目标不是让某一台新电脑“碰巧能跑”，而是让安装过程本身可以重复。安装器要能再次执行，已经完成的项目不应被破坏；只检查不改动的 dry-run 也要能提前告诉用户缺什么。这样失败会停在可理解的位置，修好一个条件后可以从同一入口继续，而不是依赖记忆手工重来。
自检要模拟一个陌生用户
为了验证这个判断，我没有只在旧电脑上运行成功的命令，而是用假用户目录演练安装。这个目录故意没有旧电脑的外部路径，也没有旧电脑的缓存和授权状态。安装器在这种环境里应当能走完检查流程，同时把未登录、缺系统组件、缺依赖、模板未准备好等问题逐项指出。
这里还有两道容易被忽略的门。第一道是代码门：全量检查使用路径模块的脚本是否真的导入它，并逐个验证模块能够加载。此前并发改造漏导入的事故说明，不能只看改动差异，也不能因为主命令暂时能跑就跳过逐文件检查。第二道是包门：解压后的内容要重新扫描，确认没有旧电脑绝对路径，也没有登录凭据或其他敏感信息。
最终的验收结果是，压缩包解压后复扫没有命中本机路径、外部存储标识和授权信息；假用户目录下的 dry-run 能报告缺项，路径命令也都落在假目录内。真实新机仍有几件事必须由人完成，比如安装并登录宿主应用、处理系统授权，以及根据系统状态选择后台或可见运行模式。这些不是安装器失败，而是边界被诚实地保留下来。
一个流程成熟的标志，不是它能在顺利环境里跑通一次，而是它能在陌生环境里把缺什么说清楚。
这件事真正迁移的是判断
回头看，这次工作表面上是在制作安装包，其实是在把一台电脑里的隐性知识显性化。旧电脑之所以“什么都能用”，并不是因为工具没有依赖，而是因为依赖已经被环境默默提供了。换一台电脑，所有默契都会变成问题。
这件事让我重新意识到，工具的可移植性和代码量没有直接关系。路径集中、依赖分层、缺项诊断、可重复安装、模拟陌生环境，这几件事看起来都不如新增功能显眼，却决定了工具能不能离开作者继续工作。真正难的不是把文件搬过去，而是把“我知道这里应该有什么”改成程序和说明都能表达的规则。
以后我会把迁移任务当成一次小型产品化，而不只是一次打包。先列出运行所需的应用、系统工具、语言依赖、内容资产和人工授权，再决定哪些随包、哪些现场安装、哪些必须提示用户。每个依赖都要有检查入口，每个失败都要有下一步，每次安装都要能在同一台电脑上安全重跑。
下次我会怎么做
下次遇到类似需求，我会先做环境盘点，不直接压缩旧目录。第一步找出所有硬编码路径和默认资产，确认它们分别属于代码、配置还是外部资源；第二步把路径集中到一个解析层，并用静态检查和导入检查守住改造质量；第三步整理依赖清单，明确哪些可以随包带走，哪些必须在新机完成；第四步写安装器，让它按顺序检查、安装、诊断，并提供只检查不改动的入口。
然后我会准备一个假用户目录，模拟没有外部存储、没有缓存、没有登录状态的电脑。安装器先在这里演练，再到真实新机验证。最后对压缩包做解压复扫，查旧路径、敏感信息和不该进入交付物的文件。
我希望最终交付的不只是一个压缩文件，而是一条别人可以照着走的路：知道先做什么，缺什么会停在哪里，补好以后怎样继续，以及什么事情必须由人完成。这样工具才算真正从作者的电脑里走出来。