半年时间，比想象中的短，但又比想象中的长。
毕竟在大模型真正到“可用”阶段之前，谁也不会想去重构一个2008年的 PHP 中型项目。
本文包含 Github copilot 和 codex 的创作。
0.这是什么？
“口袋社区 PokeTB”是我在初中时候(~2007)与几个互联网上的网友开办的一个宝可梦主题的论坛。2008年的中国互联网，只需要一张 ICP 证书即可开办论坛，当时甚至还有类似于“我的领地（5d6d.com）”这样的“论坛站群”，注册一个账号你就可以获得自己的分站点。
以现在的数据说话思路，它至少还有14000+的主题（其中有很多 Pokemon Rom 修改的资料和工具）、以及超过28万的回帖。
这些朋友现在有的已经投身游戏行业，甚至有的曾经在神游(iQue)工作，现在已经移职到香港任天堂。
还有一些朋友，在聊天室退场，论坛贴吧刚刚兴盛的时候，自学 php，给论坛做插件。
更有一些朋友，当初为论坛设计顶头 Logo 和界面风格，现在有不少朋友已经是知名公司的插画师、独立漫画作者了。
1. 为什么要迁移旧系统
1.1 旧系统维护起来越来越贵
2007年的互联网上机器流量没有这么大。而时至今日，旧系统真的没有办法扛住现在的互联网流量。
那个时候，互联网 B/S 架构软件对于 MVC 的实践远没有现在成熟。当然，也有一些问题是 Discuz 6 特有的，后面21世纪后10年的 Discuz X 系列也以经典 MVC 架构重构过。我们没有 Follow 版本升级的原因有很多，主要还是时间精力，以及插件迁移的成本问题。
从 Discuz! 6的业务现状来看，问题很多：
1、模板、查询和业务逻辑混在一起。 Discuz 的模版引擎include/template.func.php 里的 parse_template() 读取 .htm 文件，把变量和 {template}、{subtemplate} 语法转成 PHP，生成 forumdata/templates/*_*.tpl.php。这套机制有编译缓存，代价是模板最终会变成可执行 PHP。业务入口同时还直接查数据库、准备展示数据：faq.php 在一个入口里根据 $action 查 FAQ、拼搜索条件、选模板；medal.php 一个文件管权限、分页、查询和申请写入；campaign.php 还要读配置、反序列化设置、拼外部 iframe URL。
这些文件未必不能工作。问题是数据准备、业务规则、页面输出之间没有稳定边界，改一个页面就得同时理解入口脚本、全局变量、模板语法、缓存刷新和隐含权限。
2、服务分层模糊。 pm.php 处理未读私信检查、登录判断、收件人查询、交易消息拼接，还直接更新会员表。modcp/editpost.inc.php 在一个 action 分支里完成版主权限判断、帖子查询、表单展示、主题和帖子更新。logging.php 同时管登录页面、验证码和安全问题、UCenter 登录、会员查询、会话状态和跳转。这样的代码能按历史路径跑，但没法靠类型、依赖关系和边界检查去理解。
3、数据库访问靠全局对象和字符串拼接。 Legacy 用 $db、$tablepre、$discuz_uid 这些全局变量做查询，很多 SQL 直接在入口里拼。faq.php 用 $keyword 拼 LIKE '%$keyword%'，campaign.php、medal.php、invite.php、pm.php 也都在入口里拼查询和写入。旧代码通常会先过一遍 addslashes()、dhtmlspecialchars() 或 intval()，但这和参数化查询、明确的数据对象、可测试的 Repository 完全是两回事。
仓库里还留着几个 mysql_compat 兼容层，用全局 $mysql_link 把废弃的 mysql_\* API 映射到 mysqli。看得出当时的目标就是让旧应用继续跑，没打算动数据库访问模型。
4、安全和运行时机制背着历史包袱。 表单保护靠 FORMHASH、formhash()、Cookie 和入口级判断；common.inc.php 直接 error_reporting(0)，顺手关掉 display_errors。这些机制不等于"完全不安全"，但很多行为藏在全局初始化和约定里，排查问题时你说不清一个请求到底过了哪些保护。
5、源码里还有旧式动态执行和反序列化：UCenter 客户端用 eval() 动态实例化控制器；campaign.php 从设置里 unserialize() 配置；归档入口用 eval() 执行权限公式；模板里也有 {eval ...}，viewpro_inajax.htm 就会执行显示函数和自定义作者信息。这些不能一刀切全删，有些可能是历史协议或数据格式。正确做法是逐项确认输入来源、实际用法和替代边界。
6、限流和资源保护跟业务入口耦合在一起。 发帖和私信限制由 checkflood()、$floodctrl、$maxpostsperhour、$lastpost 这些全局状态共同决定，发帖限流还会查最近一小时的帖子数。WAP 私信和回复入口各自实现了一遍表单 hash、时间间隔和写入逻辑。机制本身能表达历史业务，但你没法统一观察哪个入口受限、限流会不会误伤、一次写入失败后状态有没有恢复。这些边界是 Modern 慢慢拆出来的：入口、权限、限流、事务、任务进程，各自可验证。
7、缓存责任不清，部署时经常"代码更新了，页面没更新"。 模板编译产物、数据库缓存文件、Cookie 状态、UCenter 数据、页面输出，各归各的机制管。迁移中间我还遇到过持久卷里的旧 Twig 编译文件继续输出旧页面。后来我把构建层缓存、Twig 编译缓存、OPcache/FPM 状态、Redis 业务投影分开定义，轮换和验证也写进了发布流程。
8、GBK 编码与现代基建格格不入：2008年的 vps 配置还是 1CPU+256MB 内存+10GB 硬盘，而且当时的个人电脑配置也普遍受限，加上 IE6 横行，对于 UTF8 的支持并不是很好，所以当时大量的网站采用 gbk 编码以节约 B、S 两方资源，但随着基建（php、mysql）的退役，GBK 的支持也逐渐变成了问题。
Legacy 不是一无是处。恰恰相反，旧系统里存着大量用户用了多年、但从来没被正式写成规格的业务规则。迁移要做的不是推倒重来，是把还重要的规则从隐式代码和运行时副作用里解放出来。
1.2 这个论坛不该封存在某个人硬盘里
另一个原因更简单：论坛里装的不是我一个人的东西。
十五年，很多人发过帖、回过帖、传过图。作者、时间、权限、附件、上下文，这些数据凑在一起是一段共同记忆。
如果它只能靠一台旧电脑、一个没人敢动的 PHP 版本、一个唯一掌握全部上下文的人活着，那它其实已经半封存了。数据还在，普通用户访问不稳，维护交接不了，将来也没法安全地继续跑。
所以这次迁移不是"把旧代码改漂亮"，更不是证明我能重写一个论坛。它更像数字遗产维护：把已经发生过的内容和行为尽量保住，同时把系统挪到一个别人能理解、能验证、能部署、能接着维护的地基上。这也是为什么项目坚持保留历史数据、已确认的业务语义和用户界面，不借迁移之名清理旧记录、改交互、重设计数据库。
2. “修旧如旧”：表面是升级 PHP，实际是保住一段业务历史
项目对象是一个跑了十九年的中文论坛，基础系统是 Discuz! 6.1F。目标不是重新设计一个论坛，而是在尽量保留历史数据、业务语义、权限关系和用户界面的前提下，把运行环境和代码结构带到 PHP 8.3。
重构后的系统是 PHP 8.3 的模块化单体：Composer、PSR-4/PSR-12、PDO、Router、Middleware、Twig。数据在 MySQL 8.4，Redis 管会话和部分缓存，附件走对象存储，应用和任务跑在 Docker 里。
听着像一次标准的老系统现代化。难的地方不在旧语法改新语法，在于旧系统里有大量没写进正式规格的规则：
- 有些字段的含义已经被历史数据固定了；
- 有些权限不只看当前角色，还看作者、版块、主题状态和已有操作；
- 积分、余额、库存、日志、通知必须在正确的事务边界里一起成功或一起回滚；
- 一个旧入口可能包含多个 action（modcp.php），不能因为入口名字相同就统一跳到同一个现代页面。
至于为什么不用更新、更酷的现代技术栈，比如 node 甚至 go，继续向下看。
3. 最初的教训：架构迁移的边界，和生成很多文件不等于完成迁移
今年一月的时候，我动了重构这个论坛的念头。一方面，yadex 和 yahoo 的假冒爬虫让机器频繁宕机，另一方面，discuz 的防 cc 是以 mysql 作为数据库的（会把 sid 落库），海量的异常请求把 mysql 都打垮了。加上去年（2025）一年， cursor 带给我的体验太神奇了：
那肯定是先用自己现在最熟的东西：来，让 claude code 重构成 nodejs 项目。很直接：按模块和周计划，让模型生成 Controller、Service、Repository、测试和完成报告。推进很快，新系统骨架很快就有了，然后灾难来了。
2月的模型是什么： Claude sonnet 4.6、GLM4.7（对，5都还没上），Openclaw 也还要半个月后。大家对于 Agent 工程也懵懵懂懂，自然就是一坨灾难。
Claude code 在把 plan 和 GLM Coding Plan 都烧完之后，告诉我搞定了。
结果可想而知。
这个结果给我的最重要的输入是，对模型能力的判断。也在那时，我确定了当前节点的目标：先别换语言了，让它的架构跟现代开发框架一致，“修旧如旧”。下一步再说怎么改。
很快我确立了三个黄金原则，直到现在也留在了这个阶段的项目里，帮了大忙。
1、零改表原则：一个 BS 架构的系统包含前端、后端、缓存和数据库，缓存随便扔，如果要动前后端，意味着数据结构可能要有变化，那如果数据库也一起修改了，就意味着无法做校验。虽然确保不动数据库可能会导致模型层产生垃圾兼容代码，但这是阵痛。
2、最终行为一致：虽然模版引擎从 discuz 的 template 迁移到了 Twig 这个现代引擎，但页面视觉、行为、交互应当严格保持一致。
3、TDD 原则：虽然这半年很多人已经进化到了 SDD 模式（即 Spec 驱动开发），但事实上，旧系统翻新这件事，有明确标的，采用 旧系统-写用例-改新系统-完善用例 这样 交替迭代系统侧和测试侧的方法更为有效。截止项目上线，目前维护了14000+ Unit Case、3000+行为 Case 和 300+前端 case。
虽然这些原则在大概3月就确定了，但是当时的模型确实能力不足，导致产生了一个让我很头疼的问题：文件按照规划的模块都生产了，然后 claude 报告已经完成，然而：
一是文件存在经常被当成能力存在。类、路由、单元测试都能写出来，但用户真走一遍"进页面、提交表单、发生写入、跳转、再读取"的链路，接线错误就露出来了。
二是现代设计习惯会悄悄改写旧业务。模型看到一个不好看的旧字段，就顺手推一个更"合理"的新字段；看到一个怪权限分支，就当成 bug；看到旧的 CSRF、编码或状态处理，可能直接换成一个看起来更现代的实现。
三是测试有时验证的是实现布局，不是用户行为。比如某个共享组件已经正确提供了路由，测试却要求某个特定字符串必须出现在页面源文件里。测试是失败了，但失败的对象是代码组织方式，跟业务结果没关系。
所以，我还是引入了行为（业务能力）迁移判断流程：从"按文件补齐"转成"按业务能力迁移"。能力的单位不再是某个 PHP 文件，而是一个用户或后台操作者能完成的动作，包括入口、角色、状态、读写、外部副作用和生命周期。
这个区别很关键。比如说，旧的 poll.php 不是一个能力。创建投票、投票、查看投票人、编辑、关闭、删除、个人列表，才是不同的能力。它们可能共享代码，但权限、状态和验收标准不一定共享。
4. 三种权威和目标的迭代：虽然已经可以自动化了，但前提是人依然很重要
迁移过程中，另一个浪费了很多时间的是，搞清楚"事实""目标"和"授权"。现在分三类：
实际是什么。 以可达源码、配置、数据结构和运行证据为准。历史文档可以帮你导航，但文档里的一句话不能压过代码和实际行为。
目标是什么。 以当前已确认的产品语义和领域契约为准。Legacy 是重要证据，但不是无条件的真理。旧系统的漏洞、已批准退役的入口、损坏数据的保全策略，分清楚什么是“原有设计”、“缺陷”，并能判断“是否保留”，仍需要大量的人工参与。
这次能做什么。 以当前任务的授权边界为准。普通实现和可逆修复可以继续；新的数据删除、结构变更、不可逆副作用、生产操作，要单独确认。
所以在6月、7月两个月，我基于这个方法明确了很多围栏，并且与模型专门进行了一轮历史功能确认，以明确功能边界。可以说，如果没有人工输入的判断，就没有下面完全脱手的实现。
在8月份，codex 的 /goal 稳定了，我也让 5.6-sol 在走查修复过程中使用了一个 15day+ 的 goal。不得不说，模型的进步速度实在是太快了，goal 让我真正享受一把“脱手”的感觉：
最后的这两个月提交量暴增（我从来没有在 github 上每天100+PR），而且模型已经可以稳定的自行闭环走查任务了。
5. 最难的不是分层，是守住旧行为的边界
/goal 解决了“脱手”的问题，但也让过程监控和结果是否漂移变得更难观测。
5.1 数据库"少改"不等于业务简单
项目有零改表原则，但它不是"永远不许改表"。真实含义是：新增结构之前，先核对 Legacy 的同功能表、字段和文件存储；确实要变，必须有明确的结构决定和兼容方案。
这么做的理由不是迷信旧表。历史数据本身就是系统的一部分，一个看着干净的新字段可能解释不了旧记录，一次批量清洗可能毁掉用户看不见但有意义的状态。
5.2 跨域写入必须有明确边界
论坛、积分、银行、附件、通知、ZPet 之间联动很多。ZPet 最后用的是进程内插件加唯一的同步事件总线，没有让核心业务直接调插件内部逻辑。
事件通道也不能混用：有的必须跟根事务一起提交或回滚；有的要求同步且只能有一个处理者；有的只做只读收集；有的用于跨事务投影。这个区分比"用了事件总线"重要得多。
5.3 模板迁移不是替换括号
Legacy 模板的路径是 .htm 经旧模板引擎生成可执行的 .tpl.php，运行时加载。迁到 Twig 后：
- 旧变量、条件、循环、子模板改成 Twig 的输出、控制结构和继承；
- 模板里混着的业务计算挪到控制器和服务；
- 全局变量变成明确的数据输入；
- 翻译、URL、资源路径、CSRF、BBCode、插件插槽全部重新接线；
- Legacy 的布局、类名、语言和样式语义尽量保留；
- 在线模板编辑和旧的可写执行产物退役，模板变更交给源码和发布流程。
6. 真实浏览器比"AI 说完成了"可靠
项目里最有效的验收方式之一：把用户动作真走一遍，同时看页面、数据库、对象存储和日志。
很多问题只有真实链路里才会出现：
- 控制器写好了，服务工厂接错类型；
/bbs挂载路径漏了，源站检查正常，公网路径不对；- 下载内容正确，原始文件名丢了；
- 表单按钮值跟 Legacy 不一样，服务端直接拒绝；
- 旧页面 CSRF token 过期后，失败回显把用户输入丢了；
- CSS 和头像这些公共资源也走完整应用初始化，页面本身没问题，但整个请求瀑布很慢；
- 测试库里的外围事务掩盖了真实请求中事件准备时序的错误。
不同证据回答不同问题：单元测试验证局部规则，集成测试验证组合，静态检查验证边界，浏览器验证真实装配和用户路径，发布后检查验证实际运行的版本。
7. 架构和发布：重点在边界连续
Modern 的架构可以概括成模块化单体：
- 前台、AdminCP、ModCP 用 Twig 组织页面；
- Front Controller、Router、Middleware 处理入口、身份、权限、CSRF 和输入边界；
- 业务服务管论坛、用户、私信、积分、银行、附件和管理能力；
- Repository/PDO、Redis、对象存储、邮件、任务是基础适配；
- ZPet 通过类型化契约和唯一的同步事件总线协作；
- Legacy 行为证据和可观察回归是系统的两根柱子。
生产部署不是把容器启动起来就完了。PHP 镜像和 Nginx 镜像分开构建，依赖层和业务源码层分开，基础镜像按摘要固定，OCI 层按 SHA 校验并复用。生产里 PHP-FPM、Nginx、常规定时任务、投影/邮件任务、附件隔离任务分开跑；数据库、Redis、备份各有独立的数据生命周期。
发布的流程：完整质量验收和静态验收先绑定最终 main 提交，本机 pre-push 登记证据；GitHub Actions 按 AMD64 构建，做依赖审计、SBOM、漏洞扫描和隔离 smoke；服务器核对 OIDC、源码 SHA、制品摘要和运行身份，然后才切换五个应用容器。失败就回退到上一份合规的 main 制品，重新轮换缓存、重载 FPM、验证入口。
这里得诚实：这是原地 Compose 更新，不是双集群、不是金丝雀、不是全业务零停机发布。两个入口的 HTTP 检查只能证明入口健康，代替不了完整业务验收。镜像回退撤不掉新版本已经写进数据库的数据，更不等于数据库回滚。
8. 性能教训：高配开发机会让错误的测量显得可靠
本机是 M5 Max、128GB 内存、2TB 硬盘。开发体验很好，盲区也明显：很多问题在开发机上不显形，部署到资源更有限、还跟 WordPress 和百科共享 CPU 的生产机后才暴露。
更根本的问题不是机器快，是早期测量的对象不完整。有过性能报告只测单条数据库读取，还把顺序循环叫成并发。这些数字能证明某个局部片段快，证明不了首页响应、FPM 队列、浏览器首屏、真实并发没问题。
上线后的分析显示，成本主要来自请求链里的重复工作：路由身份构造、插件和事件元数据检查、头像清单处理，还有 HTML、CSS、头像等资源各自启动一遍应用链路。一次优化把重复的路由身份构造从约 43,295 次降到 1,790 次；另一次把交替原型路由安装的 CPU 中位数从约 193ms 降到约 44ms；CSS 路径的 CPU 从约 333ms 降到约 93ms。
现在的经验是：从第一个纵向切片开始，就在接近生产的资源约束下测完整 HTTP 链路，分别记录启动、路由、查询、渲染、附属资源、FPM 排队、浏览器首屏。性能不能等全部功能迁完再安排。
9. 回头看：Claude Code、GLM、Copilot 和 Codex 分别改变了什么
这个项目先后用过 Claude Code 配 GLM 模型、Github Copilot 和 Codex。
工具换来换去，最大的启示是一条：工具可以换，共享事实不能依赖工具的记忆。
先是 Claude Code。早期模型也不行，工具也不完善，所以单体构建、单体测试，人工回归。但它至少给人了一个反馈：这事搞不好真的一个人能干。它更像快的代码生成器，帮忙搭骨架、补局部实现。项目复杂度上来之后，真正重要的工作变成了：从 Legacy 提炼行为证据；对照 Modern 的真实装配；找出"看起来合理"但不符合历史语义的实现；把一次线上或浏览器发现固化成回归；检查源码、测试、镜像和生产运行身份是否一致。
Github Copilot 很像 multica ：你给他一个 issue（pr、issue、comment），它自己有 workspace，可以构建检测，推送上线。但是它有跟 Codex /goal 类似的问题：过程不可监控，猛猛几个小时出来一个大PR，你根本不知道它在干什么。
Codex 是能成功上线的最终推手，不只是模型能力，也基于这半年超过所有人类认知的模型、Agent 工程的发展——它真的能用在真实项目里了。
10. 下一次迁移，我会提前做什么
再来一次的话，我不会照搬这个项目的全部文档，也不会默认照搬 PHP 分层、零改表、四类事件或现有 Docker 拓扑。方法复用，业务重新调查。
第一天先立五样东西：
- 项目适配配置：代码位置、运行命令、数据隔离、不能碰的资源、生产边界；
- 能力清单：按入口、角色、状态、动作列出真实迁移表面；
- 最小行为证据：源码、配置、样例输入输出、已批准差异；
- 纵向切片：从入口到存储、响应、再次读取，走通一条真实链路；
- 真实性能和缓存契约：第一个切片就定好测量范围、资源预算和失效方式。
然后让程序帮着判断哪些结论需要重看：Legacy 摘要变了，重看关联事实；Modern owner 变了，选受影响的回归；产品决定被替代了，更新预期；环境不匹配、测试没跑、源码漂移，撤销"当前通过"状态。
理想的最小技能包只要四个动作：discover 发现入口、能力、来源和未知项；characterize 把行为、边界和差异固定下来；migrate 实现一个有界且已授权的纵向切片；verify 以源码身份为起点，给出证据等级和真实缺口。
模型应该拿到的是任务包和证据索引，不是几百页互相覆盖的历史记忆。
结语
遗留系统迁移最危险的时刻往往不是代码报错，是代码看起来已经完成。单元测试过了，但没有真实入口；新表有了，但解释不了旧数据；页面能打开，但丢了一个用户依赖多年的边界行为；镜像能部署，但不是刚才验收过的那个版本。
这次项目让我接受了一个不怎么激动人心但更有用的结论：AI 的价值不是让迁移变成自动驾驶，而是让人有更多时间花在真正要紧的判断上——哪些行为必须保留，哪些应该改变，哪些差异已经被批准，什么证据足以说明这次改变没有越界。
这些判断写成能力、契约、回归和发布证据之后，Claude Code、Copilot、Codex，包括下一代完全不同的工具，都只是执行和检查这套方法的不同入口。
近期评论