按钮文案错了别全站搜改：先让 Codex 圈出最小修复边界

教程定位

这篇教程解决什么问题

线上小 bug 最容易被低估。一个按钮文案错了、一个状态标签展示不对、一个空状态提示漏了标点，看起来都像三分钟能改完的事。真正麻烦的是：同类组件很多，文案来源不止一处，状态枚举被多个页面复用，设计系统里还有通用按钮和业务按钮两套封装。你如果让 Codex 直接“把这个按钮改成已提交”，它可能搜到一堆相似文案，然后顺手改掉共享组件、翻译文件、测试快照和无关页面。bug 修好了，但范围变大了，评审反而更难。

这篇教程讲的是一个很窄但很实用的动作：在修小 bug 之前，先让 Codex 圈定最小修改边界。你要它先回答“该改哪里、为什么只改这里、哪些相似文件不能碰、改完如何验证”，而不是立刻写代码。最终产物不是一份泛泛的修复建议，而是一张小 bug 修复卡：最小修改点、相关复用组件、影响路径、不改清单、验证命令和人工复核项。

本文的例子是一个安全虚构的后台订单页：订单详情页在付款成功后，底部按钮仍显示“继续支付”，正确文案应该是“查看付款记录”。项目里有多个订单按钮、支付按钮和状态标签，`ContinuePaymentButton` 这个名字也被列表页、详情页和移动端壳层引用。开发者手上有 bug 描述、截图文字、复现路径和一段文件搜索结果。我们会让 Codex 先圈范围，再给出修复提示词。

这个方法适合处理线上小问题，尤其适合你不确定相似组件之间关系的时候。它不会替你做最终判断，也不鼓励把所有小 bug 都流程化到很重。它的价值在于：把“我以为只改一行”变成“我知道为什么只改这一行”，让小修复既快又可审查。

使用场景

什么情况下最适合用这一套

你是一个正在处理线上小问题的开发者。客服同事发来截图：订单已经付款成功，但详情页底部按钮还写着“继续支付”。用户点进去不会重复扣款，因为后端接口会拦截，但这个文案会让人误会订单还没完成。产品希望今天修掉。

你打开代码库，第一反应可能是搜“继续支付”。结果并不轻松。你搜到 `orders/detail` 里的按钮文案，也搜到 `orders/list` 里的快捷操作，还搜到 `payment/components` 里的通用支付按钮、移动端 WebView 的按钮映射、国际化文案、旧版页面和测试快照。它们看起来都可能相关。

这类 bug 的风险不在修复本身有多难，而在边界不清。比如：

如果你让 Codex 直接改，它可能会做出一个看似勤快的修复：把所有“继续支付”替换成“查看付款记录”。这会制造新 bug。未付款订单本来就应该显示“继续支付”；列表页也许需要保留快速支付入口；移动端旧壳层可能还在使用另一套交互。小 bug 最怕“搜到了就改”，尤其当同类组件很多时。

更稳的做法是让 Codex 先做边界确认。你把 bug 描述、截图文字、复现路径和搜索结果交给它，要求它只输出范围判断，不改代码。它要把候选文件分成三类：

等这张边界卡确认后，再让 Codex 只改必改位置。这样一个小修复可以保持很小：一个状态映射、一条条件判断、一个局部文案 key，外加一两个针对性测试。评审者能一眼看出你没有顺手动共享组件，也没有扩大到无关页面。

1. 详情页状态错了，但列表页文案是正确的，不能一起改。
2. 按钮组件是复用组件，直接改默认文案会影响订阅支付、押金支付和补款流程。
3. 截图里看到的是中文文案，但真实来源可能是状态到 action 的映射，不是纯文案文件。
4. 测试快照里有旧文案，不能为了让测试过而批量更新快照。
5. “付款成功”状态还有部分支付、待对账、退款中等相邻状态，不能把它们都改成同一个按钮。

• 必改：能直接解释截图问题的最小代码位置。
• 需确认：可能相关，但证据还不足，改之前要再读调用方或状态来源。
• 不应触碰：相似但服务其他页面、其他状态或其他平台的文件。

材料准备

开始前先把材料和边界备齐

开始前准备四类材料，不需要很多，但要足够具体。

第一类是 bug 描述。不要只写“按钮文案错了”，要写清楚正确与错误的对照：在哪个页面、什么状态下、当前显示什么、应该显示什么、为什么这个显示会误导用户。比如：“订单详情页，订单状态为 paid，底部主按钮显示继续支付，应该显示查看付款记录；用户看到继续支付会以为付款未完成。”

第二类是截图或截图文字。即使 Codex 能看图，也建议你把关键界面信息转成文字：页面标题、状态标签、按钮文案、订单状态、当前用户角色、是否有灰度开关。截图里的真实订单号、手机号、姓名、地址、支付流水号要脱敏。可以写成 `订单号：ORDER_DEMO_001`、`用户：demo_user`。

第三类是复现路径。小 bug 的最小范围往往藏在路径里。你要告诉 Codex 从哪里进入页面，使用什么角色，订单处于什么状态，刷新后是否仍然存在，列表页是否也有问题。比如：“运营账号进入订单列表，打开已付款订单详情；刷新详情页后仍显示继续支付；订单列表中的同一订单显示已付款，未看到继续支付按钮。”

第四类是相关文件搜索结果。这里最好不是把全仓库都丢给 Codex，而是先给一份粗搜索结果。可以包括文件路径、命中行附近的函数名或组件名、命中文案或状态值。不要只给路径，也不要只给几十行无上下文代码。边界判断需要知道每个候选文件为什么命中。

你还要明确本轮目标：

这一步很重要。Codex 看到“同类组件很多”时，很容易建议抽象或统一。可线上小 bug 的第一目标通常不是整理组件体系，而是在不扩大影响面的前提下修掉当前错误。边界卡写清楚后，后续修复才不容易跑偏。

• 只圈定修复范围，不写代码。
• 找最小修改点，不做批量替换。
• 标出复用组件和共享文案。
• 输出不改清单，并说明不改原因。
• 如果证据不足，列出下一步要读的文件，不要猜。
• 不新增重构，不统一命名，不顺手清理旧代码。

实操流程

按这套步骤把工作跑起来

第一步，先让 Codex 复述 bug 的触发条件。不是复述一句“按钮错了”，而是写成一条可判断条件：`订单详情页 + paid 状态 + 底部主按钮 + 当前文案继续支付 + 期望文案查看付款记录`。如果它不能把条件说清楚，说明输入材料还不够。

第二步，让 Codex 把候选文件按证据强弱分组。强证据通常包括：文件路径正好在复现页面下、组件名对应截图区域、状态判断里出现 `paid`、文案 key 对应截图文案、测试名描述同一页面。弱证据包括：只是命中文案、只是名称相似、只是通用组件被引用。你要它不要把“搜到了”当成“该改”。

第三步，要求它寻找“文案来源”。按钮上显示的字可能来自三种地方：组件内写死、状态到 action 的映射、国际化文案 key。最小修复点也会因此不同。如果只是详情页 `paid` 状态映射错了，就应该改映射；如果文案 key 名字对但内容错了，才改文案文件；如果通用按钮默认值错了，才考虑改组件默认文案。这个判断必须先做。

第四步，要求它识别复用组件。候选文件里凡是名字像 `PaymentButton`、`PrimaryActionButton`、`OrderActionBar`、`StatusActionMap` 的，都可能被多个页面引用。让 Codex 列出调用方和状态使用范围，至少区分订单详情、订单列表、支付页、移动端壳层、历史旧页。复用组件不是不能改，但改它需要更强证据和更宽验证。

第五步，建立“不改清单”。这是本文的核心。每个不改项都要写清楚理由，而不是只列文件。例如：`web/orders/list/OrderRowActions.tsx` 不改，因为复现路径是详情页，列表页截图和现有行为都正确；`components/payment/PaymentButton.tsx` 不改，因为它服务未付款订单的继续支付入口，错误只出现在 paid 状态动作映射；`locales/zh-CN/payment.json` 暂不改，因为同一文案 key 在未付款状态仍然需要使用。

第六步，让 Codex 提出最小修复方案。方案必须具体到“改哪一个文件里的哪类判断”，但这一步仍不写代码。比如：“优先检查 `web/orders/detail/orderActionMap.ts` 中 `paid` 状态对应的 primary action；若当前仍指向 `continuePayment`，将该状态映射到 `viewPaymentRecord`，并补充 paid 状态的组件测试。”这比“修改按钮文案”安全得多。

第七步，让 Codex 写验证计划。小 bug 的验证计划不需要宏大，但要覆盖相邻状态。至少包括：复现状态已修复、未付款状态仍显示继续支付、列表页不受影响、无权限或只读角色不出现错误动作、相关测试能证明范围没有扩大。对于文案类修复，截图复核也很重要。

第八步，人工确认后再进入修复。下一轮提示词要把边界带进去，例如：“只改边界卡中的必改文件，不碰不改清单；如果发现必须触碰共享组件，先停下说明原因。”这句话能明显降低 AI 顺手扩范围的概率。

第九步，修完后把差异和不改清单一起发给评审。小 bug 的评审重点不是展示你改了多少，而是证明你没有改多。PR 描述里可以写：“本次只修订单详情页 paid 状态的主按钮动作映射；未修改订单列表、通用支付按钮、移动端壳层和国际化文案。”评审者会更容易放心。

输入示例

可以直接参考的输入材料

下面是一份可以直接交给 Codex 的材料包。例子是虚构的，不包含真实订单、真实用户或真实支付信息。

这份输入故意保留了相似命中项。真实工作里，搜索结果越像，越需要先做边界判断。你不是让 Codex 猜哪个文件最顺眼，而是让它按复现路径和证据强弱排除无关文件。

bug 描述：
订单详情页在订单已付款后，底部主按钮仍显示“继续支付”。正确文案应该是“查看付款记录”。这个错误会让用户以为订单还没有付款成功。

截图文字：
- 页面：订单详情
- 订单号：ORDER_DEMO_001
- 顶部状态标签：已付款
- 底部主按钮：继续支付
- 用户角色：运营账号
- 备注：订单列表里同一订单显示“已付款”，没有看到“继续支付”按钮

复现路径：
1. 用运营账号进入后台。
2. 打开订单列表。
3. 找到状态为 paid 的订单。
4. 点击进入订单详情页。
5. 页面底部主按钮显示“继续支付”。
6. 刷新详情页后仍然显示错误文案。

期望结果：
paid 状态的订单详情页底部主按钮显示“查看付款记录”。
unpaid 状态仍应显示“继续支付”。
订单列表暂未发现错误，不希望本次改列表页。

相关搜索结果：
- web/orders/detail/OrderDetailActionBar.tsx
  命中：primaryAction.label，组件名与详情页底部按钮接近。
- web/orders/detail/orderActionMap.ts
  命中：paid: "continuePayment"，unpaid: "continuePayment"。
- web/orders/list/OrderRowActions.tsx
  命中："继续支付"，但复现路径不是列表页。
- components/payment/PaymentButton.tsx
  命中：默认 label = "继续支付"，被多个支付流程引用。
- locales/zh-CN/order.json
  命中：continuePayment: "继续支付"，viewPaymentRecord: "查看付款记录"。
- mobile/webview/orderActionBridge.ts
  命中：continuePayment，移动端桥接文件，本次截图来自桌面后台。

本轮目标：
请先不要写代码。请帮我圈定最小修复范围，列出必改文件、需确认文件、不应触碰文件、理由、验证计划。

提示词

可复制使用的提示词

你可以把下面这段提示词复制给 Codex。适合在修小 bug 前使用。

如果你已经准备让 Codex 进入代码修改阶段，可以在第二轮加上这句：“只允许修改边界卡中的必改文件；如需触碰需确认或不应触碰文件，先停止并说明原因。”这句很硬，但对小 bug 很有用。

你现在只做“小 bug 修复范围确认”，不要写代码。

bug 材料：
[粘贴 bug 描述、截图文字、复现路径、期望结果]

相关搜索结果：
[粘贴候选文件路径、命中内容、你已知的页面或组件信息]

请输出一份“最小修复边界卡”，要求：
1. 先把 bug 触发条件复述成可判断条件。
2. 把候选文件分成三类：必改、需确认、不应触碰。
3. 对每个文件说明分类理由，不能只因为命中文案就列为必改。
4. 找出按钮文案的来源：组件写死、状态映射、国际化 key，或仍需确认。
5. 标出复用组件和共享文案，说明改它们可能影响哪些页面或状态。
6. 给出最小修复方案，但不要写代码。
7. 输出“不改清单”，包括文件、原因、误改后可能造成的问题。
8. 给出验证计划，至少覆盖当前 bug、相邻状态、同类组件和回归测试。
9. 如果证据不足，请列出需要继续读取的文件，不要猜。

输出格式：
- bug 条件
- 证据分组
- 最小修复点
- 不改清单
- 需继续确认的问题
- 验证计划
- 后续实施提示词

输出样例

AI 应该输出到什么程度

下面是使用上面材料后，一份较理想的输出样例。它没有直接写代码，而是先把范围收住。

这份输出的关键不在它判断得多复杂，而在它把“不改”说清楚了。小 bug 修复卡里，“不改清单”有时比“改哪里”更重要，因为它防止相似命中项被顺手带进来。

bug 条件：
桌面后台订单详情页中，当订单状态为 paid 时，底部主按钮仍展示 continuePayment 对应文案“继续支付”。期望 paid 状态展示 viewPaymentRecord 对应文案“查看付款记录”。unpaid 状态仍应保留“继续支付”。

证据分组：

必改：
1. web/orders/detail/orderActionMap.ts
   理由：搜索结果显示 paid 和 unpaid 都映射到 continuePayment。复现状态是 paid，错误表现是详情页底部主按钮文案，因此这里最像状态到按钮动作的来源。

2. web/orders/detail/OrderDetailActionBar.tsx 的相关测试或同目录测试
   理由：需要证明 paid 状态展示 viewPaymentRecord，unpaid 状态仍展示 continuePayment。若已有测试文件，应优先补充最小用例。

需确认：
1. web/orders/detail/OrderDetailActionBar.tsx
   理由：组件承载详情页底部按钮，但当前证据显示错误可能来自 action map。需要确认它是否只是消费映射，不一定需要改组件实现。

2. locales/zh-CN/order.json
   理由：已有 continuePayment 和 viewPaymentRecord 两个 key，当前问题更像 paid 状态选错 key，而不是文案内容错误。除非发现 viewPaymentRecord 文案本身不正确，否则不改。

不应触碰：
1. web/orders/list/OrderRowActions.tsx
   理由：复现路径不是列表页，截图说明列表页未发现错误。误改可能影响未付款订单在列表里的快捷支付入口。

2. components/payment/PaymentButton.tsx
   理由：这是通用支付按钮，默认“继续支付”对 unpaid、补款、订阅续费等流程可能是正确的。当前错误仅出现在 paid 状态动作映射，直接改默认文案会扩大影响。

3. mobile/webview/orderActionBridge.ts
   理由：截图来自桌面后台，移动端桥接属于另一条入口。没有移动端复现证据，本次不碰。

最小修复点：
优先检查 web/orders/detail/orderActionMap.ts，将 paid 状态的 primary action 从 continuePayment 调整为 viewPaymentRecord。保留 unpaid 状态为 continuePayment。若 OrderDetailActionBar 只是读取该映射，则不改组件主体。

需继续确认的问题：
1. paid 是否还有子状态，例如 paid_pending_reconcile、partially_paid、refund_pending。
2. viewPaymentRecord 动作是否已经有对应点击行为；如果没有，需要确认按钮点击后应进入付款记录页还是打开抽屉。
3. 现有测试位置是组件测试还是状态映射单元测试。

验证计划：
1. paid 订单详情页显示“查看付款记录”。
2. unpaid 订单详情页仍显示“继续支付”。
3. 订单列表未发生文案变化。
4. 通用 PaymentButton 的默认文案不变。
5. 如果有测试，新增或更新 paid/unpaid 两个状态用例，而不是批量更新快照。

后续实施提示词：
请只修改 web/orders/detail/orderActionMap.ts 以及对应的最小测试。不要修改订单列表、通用 PaymentButton、mobile webview 桥接文件或 locale 文案。若发现必须修改这些文件，请先停止并说明原因。

人工验收

人要怎么检查和改到可用

拿到 Codex 的边界卡后，人工要做四轮复核。

第一轮，复核复现条件。确认 Codex 没把列表页、移动端、旧版页面混进当前问题。尤其看它有没有把“截图来自详情页”变成“全站订单按钮都要改”。如果它扩大了页面范围，要退回重新收窄。

第二轮，复核文案来源。打开必改文件，看按钮文案到底来自状态映射、组件默认值还是国际化 key。不要因为 AI 说“最像”就直接改。最小修复点必须能解释 bug 的触发条件：为什么只有 paid 详情页错，为什么 unpaid 不能变。

第三轮，复核不改清单。逐项看“不改”的理由是否成立。比如列表页如果其实也有同样错误，那它就不能留在不改清单；通用按钮如果只被详情页使用，那它也未必是高风险共享组件。边界卡不是为了死守范围，而是为了让范围变化有证据。

第四轮，复核验证计划。最少要覆盖当前状态和相邻状态。本文例子里，paid 修好只是第一项；unpaid 保持继续支付同样重要。小 bug 修复最常见的回归，就是把错误状态修对了，却把原本正确的状态改错。

人工修改时建议保留三条原则：

适用边界也要说清楚。这个方法适合按钮文案、状态标签、空状态提示、轻量样式展示、错误提示、局部权限展示等小范围问题。它不适合安全漏洞、支付扣款错误、数据损坏、跨系统状态不一致这类高风险事故；那些问题需要升级为事故处理、日志追踪和负责人确认。它也不适合已经确认要做组件体系重构的场景，因为那时目标本来就不是最小修复。

• 只在能解释 bug 的最小位置动手。
• 测试只覆盖本次边界，不用借机重写大块快照。
• 如果发现必须触碰共享组件，先重新做一次边界确认。

失败反例

这些失败反例要提前避开

**反例 1：看到同一句文案就全局替换。**

开发者让 Codex 把所有“继续支付”替换成“查看付款记录”。结果未付款订单、补款流程、订阅续费页都失去了正确入口。这个错误的根源是把“文案相同”当成“业务含义相同”。修复时应该先判断状态和页面，而不是先替换字符串。

**反例 2：为了修详情页，改了通用按钮默认值。**

Codex 找到 `PaymentButton` 的默认 label 是“继续支付”，于是把默认值改成“查看付款记录”。详情页看起来好了，但所有调用这个按钮且没有传 label 的支付流程都变了。通用组件可以改，但必须有全量调用方证据。对单页状态错误，优先查状态映射或调用处传参。

**反例 3：只修 paid，不检查 unpaid。**

修复者把 `paid` 的动作改对了，却没有验证 `unpaid`。后来发现条件判断写成了“非 cancelled 都显示查看付款记录”，未付款订单无法继续支付。小 bug 的验证不能只看错误截图，还要看相邻状态是否保持原行为。

**反例 4：用批量更新快照掩盖范围扩大。**

组件测试失败后，Codex 建议更新所有快照。快照是过了，但没人看出订单列表、移动端壳层和旧版页面也被改了。小修复里，快照变化要越少越好；如果快照很多，先停下来解释每个变化，而不是一次性接受。

**反例 5：不写不改清单，评审只能靠猜。**

PR 只写“修复订单按钮文案”，但 diff 里出现多个相似文件。评审者不知道哪些是必要修改，哪些是顺手改动，只能逐个追问。提前写不改清单，可以让 PR 说明变成：“本次没有修改列表页、通用支付按钮和移动端桥接，因为复现证据只指向桌面详情页 paid 状态映射。”

主题边界

它和相邻主题的区别

这篇文章和“把一句话需求问成验收标准”不同。那篇处理的是需求本身不清楚，比如老板只说“列表更好用”，重点是问出用户、场景和验收。本文默认 bug 已经明确：哪个页面、哪个状态、当前错在哪里、期望是什么。这里的难点不是问需求，而是控制代码修改边界。

它也不同于“从代码里挖业务规则”。业务规则调查要找隐藏规则、调用链和影响模块，通常用于计费、权限、审核、状态机等较深逻辑。本文只处理小 bug 的修复前范围确认，重点是避免同类组件很多时误改共享代码。

它还不同于“大功能拆成小改动”。大功能拆解关注合并顺序、发布节奏、回滚策略和多层依赖。本文的产物更轻：一张最小修复边界卡，服务于一次小修复。它不要求规划多轮 PR，也不鼓励借小 bug 做系统性重构。

本文的差异化重点是“小 bug 的不改清单”。当问题看起来只是一句文案或一个状态展示时，Codex 最应该先帮你证明哪些地方不用动。能把范围圈小，才是真的快。