旧项目版本兼容改造需四步：先确认真实运行环境（node/ts/jdk版本），再用codex分析登录鉴权最小影响面，接着生成带契约约束的改造任务（如v1/v2 token共存），最后通过多维度验证确保运行时契约不被破坏。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
给运行多年的旧项目做版本兼容改造，不是简单改几行代码就能上线，Codex必须先理解老项目的契约边界、调用链路和隐性依赖，才能生成可落地的改造任务。
第一步：定位并确认旧项目真实运行环境
打开终端，进入项目根目录，执行cat package.json | grep -E "(engines|browserslist)"或grep -r "target:" tsconfig.json webpack.config.js 2>/dev/null，提取出实际生效的 Node.js 版本、TypeScript 编译目标、浏览器最低支持范围。这一步不能只看文档或 README，很多老项目里 package.json 的 engines 字段早已过期，真正起作用的是 CI 脚本中硬编码的 nvm use 14.18.3 或 Dockerfile 里的 FROM node:14-slim。
如果项目含 Java 模块，运行mvn help:evaluate -Dexpression=project.build.sourceEncoding -q -DforceStdout 2>/dev/null，再检查 pom.xml 中 maven-compiler-plugin 的 source 和 target 设置。跳过这步直接让 Codex 开始改代码，它会按你写的“升级到 JDK 17”去重构，而忽略掉那些被 【JDK 8 字节码校验器强制拦截的 Lambda 序列化逻辑】。
第二步：用 Codex 读取并输出最小影响面分析
在 Codex App 中打开该项目文件夹 → 确认左下角状态栏显示 Local 模式 → 输入指令：
先不要修改任何代码。请扫描 src/ 和 core/ 目录下所有与用户登录、权限校验、token 解析相关的文件（包括 .ts、.java、.xml），梳理出：① 入口 Controller/Servlet 名称；② token 解析所用的类名与方法签名；③ 所有显式 throw 的自定义异常类型；④ 前端调用该接口时携带的固定 header key（如 X-Auth-Token）。最后输出一份「最小兼容改造路径」，明确哪些文件必须动、哪些字段必须保留、哪些异常 message 字符串不能变更。
这一步操作起来很简单，直接把文件拖进去就行。但如果你跳过“先读再改”阶段，Codex 可能会把 JwtTokenUtil.java 里原本返回 null 的 getUserName() 方法强行改成 Optional.ofNullable(...)，导致旧版 Android 客户端解析 JSON 时因 null 字段缺失直接 crash。
第三步：生成带契约保护的改造任务清单
方法一：基于 TaoToken 通道发起结构化请求
在 Codex CLI 中执行：codex exec --task "add-jwt-v2-compat" --context auth.json --model tao-llm-pro，其中 auth.json 已提前替换为 TaoToken 提供的 Base URL 与 sk-xxx Key。该命令会触发 Codex 调用 TaoToken 接口，自动注入「向后兼容」约束模板。
通过本地 Codex 或 OpenClaw OAuth 凭证直接调用 ChatGPT/Codex Responses 的 image_generation 工具来生成或编辑光栅图像，然后保存
方法二：手动注入四要素提示词
目标：为 /api/v1/auth/login 接口新增 JWT v2 token 签发能力，同时保留 v1 token 解析逻辑；范围：只修改 AuthService.java 和 TokenManager.java，不碰 web.xml 与 Spring Security 配置类；约束：v1 token 字段 userName 必须继续存在且非空，v2 token 新增字段 display_name 与 expires_at_ms；验收：curl -H "X-Auth-Version: v1" 能正常登录并返回 userName，curl -H "X-Auth-Version: v2" 返回 display_name 且旧客户端无报错日志。
注意：若未在约束中明确定义「userName 必须非空」，Codex 可能默认沿用新模型的语义习惯，将字段设为可空，从而触发旧客户端的 undefined.toUpperCase() 异常。
第四步：验证改造结果是否满足运行时契约
1. 启动本地服务，用 Postman 分别发送两个请求：
→ 请求头带 X-Auth-Version: v1，检查响应 body 是否含 userName 字段且值不为空字符串；
→ 请求头带 X-Auth-Version: v2，检查响应 body 是否同时含 userName 和 display_name，且 display_name 值等于 userName 全小写加前缀；
2. 查看控制台日志，确认没有出现「Failed to parse token」或「Missing required field: userName」类错误；
3. 在浏览器开发者工具 Network 面板中，过滤 /api/v1/auth/login，确认响应 headers 中 Content-Type 仍为 application/json；【若意外变成 application/json;charset=UTF-8，说明 Codex 修改了 ResponseEntity 构造方式，需回退该行】。
