那天我做完一轮上游同步，第一感觉是“这次变化很大”。目录里多了很多内容，整理出了33个脚本、14份参考文档，还有几个新的入口。快照也重新核过，依赖装过，渲染流程跑过。单看文件变化，这很像一次内容和能力都大幅增加的升级。
但用户真正会问的，通常不是“这次改了多少文件”，而是“我现在到底能多做什么”。这个问题一问出来，前面的兴奋就需要暂停。因为文件变多、说明变长、入口变清楚，和产品能力增加，并不是同一件事。
我后来把这次升级重新拆开，才得到一个不那么热闹、但更准确的结论：真正新增能力是0，主要成果是把上游已经存在的能力登记清楚，同时修了4个真实问题。这个结论看起来不像升级说明，却比“新增了很多能力”更接近事实。
文件变多，不等于用户多了一种做法
最开始的判断很容易顺着目录走。脚本数量增加了，参考文档补齐了，入口也更完整，于是我自然会觉得“支持范围扩大了”。这种判断并非完全没有根据，文档确实会让很多能力从不可见变得可用。但“可被发现”与“刚刚被创造出来”，仍然要分开。
这次复核时，我把每一项变化都改写成用户问题：以前能不能完成？现在是不是多了新的输入或新的结果？有没有新的代码路径真正承担这件事？如果只是把上游已有脚本、素材目录和检查流程补进能力地图，它改善的是认知和入口，不是底层能力本身。
升级说明真正应该回答的，是用户现在多了一种什么做法，而不是仓库里多了多少文件。
如果不处理这个区别，会导致升级报告把“登记完成”说成“功能上线”。用户按报告去寻找新能力，最后发现它早就存在，或者只是换了一个更容易找到的入口，就会对后续的更新说明失去信任。更糟的是，真正重要的修复反而被大量文件变化盖住了。
所以我没有直接按提交数量写成果，也没有把新增文档的数量当成能力清单。它们可以作为变更证据，但不能直接当作用户价值。
我把变化分成4种，而不是只看新增
为了不再凭印象判断，我给每一项变化放进4个格子里：上游已有能力、文档化、真实修复、真正新增功能。这个分法的价值在于，它允许一次升级同时有多种结果，而不是非得把所有变化都包装成“新增”。
上游已有能力，是指功能已经存在，只是这次被重新核对、归类或接入说明。文档化，是把原本藏在上游说明里的内容写成更清楚的使用路径。真实修复，是原来的行为确实有问题，现在经过代码修改和运行验证后变好了。真正新增功能，则必须能指出过去做不到、现在通过新增代码或新链路做到的事情。
这4类不能混成一类。比如，一个检查工具以前就能运行，这次只是加入路线图，属于文档化；一个参数虽然能从命令行传入，但组件根本不消费它，不能算支持；一个无参数运行会抛出裸 traceback，改成可理解的用法提示，则属于真实修复，但仍不等于新增功能。
我判断一项变化是否算新增，先问“过去是否做不到”，再问“现在是否真的跑通”。
这两个问题缺一不可。只看过去，会把旧能力重复计算；只看现在，会把一段没有被调用的代码误判成可用能力。能力必须同时具备历史差异和运行证据，才能进入“新增”这一栏。
死开关暴露了“看起来支持”的风险
这次最能说明问题的，是两个看起来已经支持的命令行参数。它们能被脚本传入，也能在文档里找到名字。乍看之下，似乎只是以前没有写进说明，现在补齐了。但继续追到组件类型定义后，我发现组件只声明了7个属性，根本没有消费这两个参数。
也就是说，参数在入口处存在，往下却没有产生任何行为。它们是死开关。此前如果只检查脚本是否接受参数，就会得到一个错误结论：命令可以用，能力已经支持。真正沿着调用方和组件继续追，才发现传参只是动作，不是结果。
我选择把这两个参数从脚本里删掉，是因为留下它们比缺少它们更危险。缺少一个不支持的参数，用户会很快知道；保留一个看似有效、实际上没有效果的参数，用户可能把错误结果归因于自己的操作。
这里也有一个更普遍的判断：接口存在，不代表行为存在。按钮能点、参数能传、字段能写入，都只能证明入口没有立刻报错。它们最终有没有改变画面、产物或流程，必须回到真正消费它们的地方验证。
4个修复，比一长串新增更值得说清
复核以后，真正留下的代码修复有4项。第一，文档把产物写在一个过浅的目录里，实际产物在更深的工程目录。这个错误会让人找不到已经生成的文件。第二，删除没有被组件消费的两个死开关，避免形成虚假能力。
第三，修复了一个断链入口。原先某类预览目录并没有随版本记录，上游失效后，文档里的入口就可能指向不存在的内容。第四，无参数运行时原本会抛出裸 traceback，后来改成可理解的用法提示，让错误变成下一步行动的指引。
这4项都不是“用户突然获得了一个全新的创作能力”，但它们会改变使用体验：找得到产物，知道哪些参数有效，入口不容易断，出错时知道怎么改。它们的价值不在于让宣传页多一个亮点，而在于减少误用、返工和排查时间。
我还做了真实运行验证，而不是停在语法检查。改完参数校验后实际跑了一镜，确认渲染结果为1920×1080、30帧，时长约10.45秒，黑帧检测没有命中。这个结果不能证明所有场景都没有问题，但至少证明这次修复没有破坏主流程。
修复的价值不必伪装成新增；让原本会误导用户的流程变可靠，本身就是可以交付的进步。
用能力核验表替代升级兴奋感
后来我形成了一张很简单的能力核验表。第一列写用户能做什么，避免从文件名出发；第二列写这件事过去是否已有，防止把上游能力重复计算；第三列写这次究竟改了什么，是文档、修复还是新代码；第四列写实际运行证据，包括调用方、被消费的属性和最终产物。
这张表的重点不是形式，而是要求每一行都能完成一次追问。只要“用户能做什么”写不清，说明它还没有转成用户价值；只要“过去是否已有”没有证据，说明它可能只是新包装；只要“实际运行证据”为空，就只能写成待核验，不能写成已支持。
在具体执行时，我会先从用户动作开始，再追到入口、调用方和实际消费点，最后跑一个最小验证。遇到文档描述与产物位置不一致，就以实际产物为准；遇到参数能传但没有消费，就以组件行为为准；遇到脚本只在无参数时崩溃，就把错误提示也纳入验收。
如果不这样做，升级工作很容易变成“把所有东西登记一遍”。登记当然有价值，但它不能替代核验。一个流程成熟的标志，不是它能列出更多能力，而是它能诚实地区分已有、可用、修复和新增。
这件事让我重新意识到，升级最难的部分不是把变化写得热闹，而是允许结论不热闹。说“新增能力为0”，并不代表这次工作没有价值；它意味着我终于把价值放在了正确的位置：文档让能力可发现，修复让流程更可靠，验证让判断有证据。
下次我会怎么做
下次遇到一次看起来声势很大的同步，我会先不写“新增了什么”，而是先做一轮能力盘点。先按用户动作列出候选项，再逐项核对上游是否已有；然后把变化归入文档化、真实修复或真正新增；最后追到调用方和实际运行结果。
我会特别检查3个容易骗人的地方：脚本能不能传入但下游有没有消费，文档写的产物位置和真实产物是否一致，无参数或错误输入时用户能不能得到下一步提示。这3处往往比“新增了多少入口”更能说明升级质量。
最终报告里，我会把“新增能力为0”也作为有效结论写出来，并把真正修复的事项单独讲清楚。因为用户需要的不是一份让人兴奋的变更清单，而是一张能帮助他做决定的地图：什么以前就有，什么现在更稳，什么仍然没有支持，什么经过实跑已经确认。
真正可靠的升级报告，不是把变化说大，而是让每个变化都对应一个用户可以验证的结果。