一、为什么前端联调适合先接入 Codex
前端联调的问题经常很碎：字段名变了、枚举值不一致、分页参数没对齐、错误码没有说明、测试环境数据不完整、接口文档和真实响应不一致。单个问题不难，但它们会不断打断开发节奏。Codex 的价值不只是帮你写代码，而是把这些碎片化信息整理成可复核的判断。
相比让模型直接重构页面，前端联调场景更适合作为团队第一批落地任务。它可以读取接口文档、类型定义、请求封装、Mock 文件和报错日志，输出字段差异、缺失用例、可能原因和下一步检查动作。输出仍由开发者确认，但前期定位成本会明显降低。
通过灵能API接入统一入口后，团队可以让每位前端成员使用同一套 Codex 配置，避免每个人用不同模型、不同地址、不同提示词，导致联调建议不一致。
- 接口字段对比适合 Codex 做初步整理。
- 错误复现流程适合 Codex 帮忙拆步骤。
- Mock 数据和真实响应差异适合沉淀成文档。
- 业务展示规则仍需要前端和产品共同确认。
二、先统一接入入口：联调前不要各配各的
前端团队经常同时维护多个项目、多个环境和多个**配置。如果 Codex 的接入入口也各不相同，联调问题会更难排查。第一步应该先统一入口和变量名称，再讨论具体页面怎么调。
建议通过 https://www.lnsns.com/ 进入灵能API控制台，确认当前接口说明、模型状态和账号资源。团队文档里只写入口、变量名和负责人，不写完整密钥。这样新人可以快速配置，也不会把敏感凭证复制到前端项目里。
统一入口之后，前端成员只需要关心三件事：当前任务读取哪些文件、输出什么格式、结果由谁确认。接入本身不要散落在每个页面目录里，否则后续换环境、换模型或换成员时会很难维护。
- 入口统一后，问题定位才有共同基线。
- 完整密钥不进入前端仓库和截图。
- 联调任务只引用变量名，不直接暴露敏感配置。
三、准备文件范围：让 Codex 看该看的上下文
前端联调任务不能只给一句“这个接口有问题”。Codex 需要看到足够上下文，才能判断字段差异和错误来源。通常至少要给它四类材料：接口文档、请求封装、类型定义、当前页面的调用代码。若有 Mock 文件和错误日志，也应一并提供。
但上下文也不能无限扩大。不要让 Codex 读取整个前端仓库，也不要把无关页面、构建产物、依赖缓存都塞进去。范围越干净，输出越接近可执行排查建议。
前端联调输入范围示例
读取：src/api/order.ts
读取：src/types/order.ts
读取：src/pages/order-detail/index.tsx
读取：mock/order-detail.json
读取：do**/api/order.md
目标：对比接口文档、类型定义、页面使用和 Mock 数据是否一致
限制：不修改文件，不推测文档中不存在的业务规则如果页面较复杂，可以先只分析一个接口。等字段、错误码和展示逻辑确认后，再扩展到同页面的多个接口。一次只解决一个清晰问题，比让 Codex 同时分析整页所有数据流更稳。
- 输入范围包括文档、类型、请求封装、页面调用。
- Mock 文件和真实响应要分开标记。
- 复杂页面先按接口拆分，不要一次分析全部数据流。
⚙️ 四、用 CC Switch 固定前端联调配置
前端联调需要较稳定的输出结构，因此建议在 CC Switch 中单独建立配置卡。它和代码**、测试生成、文档自动化不是同一类任务，不要全部混用一张默认配置。
配置卡可以命名为 Lingneng-Codex-Frontend-De*ug 或 Lingneng-Codex-Mock-Review。备注中写明：用于接口字段对比、Mock 数据**、错误复现和联调文档草稿；默认只读，不自动覆盖页面代码；如需生成修改建议，只输出代码片段。
配置卡备注建议
用途：前端接口联调和 Mock **
权限：只读接口文档、类型定义、页面调用和 Mock 文件
输出：字段差异、错误路径、Mock 修正建议、联调记录
限制：不自动覆盖页面代码，不输出真实密钥
复核：由前端负责人确认后再改代码- 联调配置卡要独立于日常问答配置。
- 备注要写清楚读取范围和写入限制。
- 配置变更后，先用固定样本页面验证。
五、第一类任务：接口字段和类型定义对齐
字段不一致是前端联调里最常见的问题。后端返回 user_id，前端类型写 userId；文档说 status 是 num*er，真实响应是 string；Mock 数据缺少 nulla*le 情况；页面里把可选字段当必填字段使用。Codex 可以先把这些差异列出来。
字段对齐任务的输出最好使用结构化清单，包含字段名、文档定义、类型定义、页面使用、Mock 示例和建议处理。这样前端、后端、测试都能各自确认自己的部分，而不是在一段长解释里找问题。
字段对齐提示词
请对比接口文档、TypeScript 类型、页面调用和 Mock 数据。
输出：
1. 字段完全一致的部分
2. 字段名不一致
3. 类型不一致
4. 可选/必填不一致
5. Mock 数据缺失情况
6. 需要后端确认的问题
限制：不要修改文件，不要把猜测写成结论。- 字段名、类型、可选性要分别检查。
- Mock 数据必须覆盖空值和异常值。
- 无法从代码确认的字段进入待确认。
六、第二类任务：生成 Mock 数据和边界样例
Mock 数据如果只覆盖理想状态，联调时会给人一种页面已经稳定的错觉。真实环境里常见的问题是列表为空、字段缺失、状态异常、金额为零、时间为空、权限不足、后端返回延迟。Codex 可以根据接口字段生成更完整的 Mock 样例。
生成 Mock 时要明确场景，不要只要求“给我一份 **ON”。建议至少准备正常数据、空状态、部分字段为空、错误状态、权限不足、分页边界六类样例。每类样例都要说明它用于验证哪个页面表现。
{
"scenario": "empty_order_list",
"purpose": "验证订单为空时的页面占位、按钮状态和提示文案",
"response": {
"list": [],
"total": 0,
"page": 1,
"pageSize": 20
},
"expected_ui": [
"显示空状态提示",
"隐藏批量操作按钮",
"分页组件不可点击"
]
}生成后的 Mock 不要直接覆盖现有文件。先让开发者确认字段和场景，再放入 mock 目录或 story 文件。这样可以避免模型把不存在的字段写进去，也能让 Mock 数据真正服务页面验证。
- Mock 场景要覆盖正常、空、异常和权限边界。
- 每个 Mock 都要说明验证目的。
- Mock 入库前必须确认字段来自真实接口或文档。
七、第三类任务：复现接口错误路径
前端错误复现经常靠口头描述：点击某个按钮后偶尔报错，刷新后又好了。Codex 可以帮助把复现过程拆成步骤，尤其是在你提供请求参数、响应片段、页面状态和最近改动后，它能整理出更清晰的排查路径。
错误复现输出不应该只包含原因猜测，而应包含复现前置条件、操作步骤、预期结果、实际结果、可能原因、下一步抓取信息。这样测试和后端也能参与确认，而不是只让前端自己猜。
错误复现模板
前置条件：用户已登录，订单处于待支付状态
操作步骤：进入订单详情，点击继续支付，等待接口返回
预期结果：进入支付确认页
实际结果：页面提示系统异常
关联接口：POST /api/order/pay
已知响应：code=403，message=permission denied
下一步：确认用户角色、订单归属、支付权限和接口鉴权规则- 复现步骤要能被测试同学照着执行。
- 实际响应要和页面表现一起记录。
- 原因猜测要和**证动作绑定。
八、**类任务：从报错日志反推页面状态
有些前端问题不是接口直接失败，而是页面状态处理不完整。比如接口返回空数组，但组件仍然读取 list[0].name；字段为 null，但页面调用了字符串方法；请求取消后状态仍然更新，导致页面闪烁。Codex 可以根据报错堆栈和组件代码，帮助反推可能的页面状态。
这类任务要给足三类信息：错误堆栈、组件相关代码、触发时的接口响应。如果只给错误堆栈，Codex 可能只能猜测；如果只给组件代码，又很难还原真实数据。三者结合，输出才更接近实际问题。
页面状态排查提示词
请读取错误堆栈、组件代码和接口响应片段。
输出：
1. 报错位置
2. 触发该报错需要什么页面状态
3. 哪个接口字段可能为空或类型不符
4. 建议增加的保护逻辑
5. 建议补充的 Mock 场景
6. 仍需人工确认的问题- 报错堆栈、组件代码、接口响应要一起看。
- 空值和异步状态是前端联调高频问题。
- 建议要能转成保护逻辑或测试场景。
九、第五类任务：生成联调记录和问题交接文档
前端联调过程中，很多有价值的信息只停留在聊天记录里。今天确认了字段，明天又有人问；这次知道某个错误码代表权限不足，下次又从头排查。Codex 可以把联调过程整理成简短文档，减少重复沟通。
联调记录不需要写成长篇报告，但要包含接口、问题、当前结论、待确认人、下一步动作和更新时间。这样前端、后端、测试、产品都能知道当前卡点在哪里。
联调记录模板
接口：GET /api/order/detail
页面：订单详情页
当前问题：返回字段 payStatus 与前端枚举不一致
影响范围：支付按钮展示和订单状态文案
当前结论：前端类型需要同步，后端需确认历史状态值
负责人：前端 A / 后端 *
下一步：确认枚举表并补充 Mock
更新时间：2026-09-04- 联调记录要短，但必须可追踪。
- 待确认事项要有负责人。
- 解决后的结论要同步到正式文档。
十、控制成本：联调任务不要每次都跑长上下文
前端联调任务如果没有限制，很容易变成长上下文消耗。一个页面可能有多个接口、多个组件、多个状态文件和多份 Mock，如果每次都让 Codex 全量读取，成本和等待时间都会上升。
更稳的策略是按问题类型分级：字段对比可以走标准任务；短错误解释可以走轻量任务；跨页面状态流分析再走深度任务；完整联调复盘只在阶段结束时手动触发。
联调任务分级
轻量任务：解释错误码、整理短日志、生成小段 Mock
标准任务：字段对比、类型对齐、单接口联调记录
深度任务：跨页面状态流、复杂权限路径、阶段复盘
手动触发：完整联调报告、跨模块影响分析- 字段问题不要跑全页面深度分析。
- 短日志解释应限制输出长度。
- 完整复盘适合阶段结束后手动触发。
十一、提示词模板：让联调输出直接可用
前端联调提示词要明确角色和输出格式。不要写“帮我看看接口为什么不对”，而要写清楚读取范围、对比目标、输出结构和限制。越具体，输出越容易进入实际排查流程。
你是前端接口联调助手。
目标：对比接口文档、类型定义、页面调用和 Mock 数据。
输入：读取指定文件，不扩展到其他目录。
输出：字段差异、类型差异、错误路径、Mock 修正建议、待确认事项。
限制：不修改文件，不输出真实密钥，不推测文档中不存在的业务规则。
复核：所有待确认问题单独列出负责人建议。这个模板可以作为团队默认入口。每次只替换文件路径和接口名称，不要每个成员都重新发明提示词。提示词统一后，联调记录也会更统一，后续沉淀到知识库时不用反复整理格式。
- 提示词先限定范围，再要求分析。
- 输出要面向排查动作，不是泛泛解释。
- 待确认问题必须独立列出。
十二、形成闭环：从问题发现到文档更新
联调结束后，如果结论没有进入文档，下次还会重复。建议把 Codex 输出分成三类处理：字段差异进入接口文档，Mock 场景进入测试或 story，错误复现进入排查手册。不要让有价值的结论只留在一次对话里。
闭环的关键是责任清楚。前端确认页面表现，后端确认接口字段，测试确认复现场景，产品确认文案和业务规则。Codex 负责整理和提醒，团队成员负责最终判断。
联调闭环清单
[ ] 字段差异已确认
[ ] 类型定义已同步
[ ] Mock 场景已补充
[ ] 错误复现步骤可执行
[ ] 接口文档已更新
[ ] 排查手册已补充
[ ] 待确认事项已关闭- 发现问题只是开始，沉淀结论才是闭环。
- 字段、Mock、错误复现要进入不同文档位置。
- 未关闭的待确认事项不能当作已完成。
✅ 十三、收尾：把前端联调变成可复用流程
Codex 接入 Claude中转站 后，前端联调是一个很适合长期使用的场景。它不会替团队决定业务规则，却能把字段差异、Mock 缺口、错误复现和联调记录提前整理出来，让沟通更清楚。
落地顺序建议是：先通过灵能API统一接入入口，再用 CC Switch 固化前端联调配置卡，然后从单接口字段对比开始，逐步扩展到 Mock 生成、错误复现、页面状态分析和联调文档沉淀。
当这套流程稳定后，前端团队会少很多“这个字段到底是什么”的来回确认，也能把每次联调经验留给下一次项目。Codex 的价值不只是回答问题，而是让问题被更快定位、被更好记录、被更少重复。
- 先对齐字段，再生成 Mock。
- 先复现错误，再判断原因。
- 先沉淀联调记录，再扩展自动化范围。
