一、為什么前端聯(lián)調(diào)適合先接入 Codex

前端聯(lián)調(diào)的問題經(jīng)常很碎：字段名變了、枚舉值不一致、分頁參數(shù)沒對齊、錯(cuò)誤碼沒有說明、測試環(huán)境數(shù)據(jù)不完整、接口文檔和真實(shí)響應(yīng)不一致。單個(gè)問題不難，但它們會不斷打斷開發(fā)節(jié)奏。Codex 的價(jià)值不只是幫你寫代碼，而是把這些碎片化信息整理成可復(fù)核的判斷。

相比讓模型直接重構(gòu)頁面，前端聯(lián)調(diào)場景更適合作為團(tuán)隊(duì)第一批落地任務(wù)。它可以讀取接口文檔、類型定義、請求封裝、Mock 文件和報(bào)錯(cuò)日志，輸出字段差異、缺失用例、可能原因和下一步檢查動作。輸出仍由開發(fā)者確認(rèn)，但前期定位成本會明顯降低。

通過靈能API接入統(tǒng)一入口后，團(tuán)隊(duì)可以讓每位前端成員使用同一套 Codex 配置，避免每個(gè)人用不同模型、不同地址、不同提示詞，導(dǎo)致聯(lián)調(diào)建議不一致。

• 接口字段對比適合 Codex 做初步整理。
• 錯(cuò)誤復(fù)現(xiàn)流程適合 Codex 幫忙拆步驟。
• Mock 數(shù)據(jù)和真實(shí)響應(yīng)差異適合沉淀成文檔。
• 業(yè)務(wù)展示規(guī)則仍需要前端和產(chǎn)品共同確認(rèn)。

二、先統(tǒng)一接入入口：聯(lián)調(diào)前不要各配各的

前端團(tuán)隊(duì)經(jīng)常同時(shí)維護(hù)多個(gè)項(xiàng)目、多個(gè)環(huán)境和多個(gè)**配置。如果 Codex 的接入入口也各不相同，聯(lián)調(diào)問題會更難排查。第一步應(yīng)該先統(tǒng)一入口和變量名稱，再討論具體頁面怎么調(diào)。

建議通過 https://www.lnsns.com/ 進(jìn)入靈能API控制臺，確認(rèn)當(dāng)前接口說明、模型狀態(tài)和賬號資源。團(tuán)隊(duì)文檔里只寫入口、變量名和負(fù)責(zé)人，不寫完整密鑰。這樣新人可以快速配置，也不會把敏感憑證復(fù)制到前端項(xiàng)目里。

統(tǒng)一入口之后，前端成員只需要關(guān)心三件事：當(dāng)前任務(wù)讀取哪些文件、輸出什么格式、結(jié)果由誰確認(rèn)。接入本身不要散落在每個(gè)頁面目錄里，否則后續(xù)換環(huán)境、換模型或換成員時(shí)會很難維護(hù)。

• 入口統(tǒng)一后，問題定位才有共同基線。
• 完整密鑰不進(jìn)入前端倉庫和截圖。
• 聯(lián)調(diào)任務(wù)只引用變量名，不直接暴露敏感配置。

三、準(zhǔn)備文件范圍：讓 Codex 看該看的上下文

前端聯(lián)調(diào)任務(wù)不能只給一句“這個(gè)接口有問題”。Codex 需要看到足夠上下文，才能判斷字段差異和錯(cuò)誤來源。通常至少要給它四類材料：接口文檔、請求封裝、類型定義、當(dāng)前頁面的調(diào)用代碼。若有 Mock 文件和錯(cuò)誤日志，也應(yīng)一并提供。

但上下文也不能無限擴(kuò)大。不要讓 Codex 讀取整個(gè)前端倉庫，也不要把無關(guān)頁面、構(gòu)建產(chǎn)物、依賴緩存都塞進(jìn)去。范圍越干凈，輸出越接近可執(zhí)行排查建議。

前端聯(lián)調(diào)輸入范圍示例

讀取：src/api/order.ts
讀取：src/types/order.ts
讀取：src/pages/order-detail/index.tsx
讀取：mock/order-detail.json
讀取：do**/api/order.md

目標(biāo)：對比接口文檔、類型定義、頁面使用和 Mock 數(shù)據(jù)是否一致
限制：不修改文件，不推測文檔中不存在的業(yè)務(wù)規(guī)則

如果頁面較復(fù)雜，可以先只分析一個(gè)接口。等字段、錯(cuò)誤碼和展示邏輯確認(rèn)后，再擴(kuò)展到同頁面的多個(gè)接口。一次只解決一個(gè)清晰問題，比讓 Codex 同時(shí)分析整頁所有數(shù)據(jù)流更穩(wěn)。

• 輸入范圍包括文檔、類型、請求封裝、頁面調(diào)用。
• Mock 文件和真實(shí)響應(yīng)要分開標(biāo)記。
• 復(fù)雜頁面先按接口拆分，不要一次分析全部數(shù)據(jù)流。

?? 四、用 CC Switch 固定前端聯(lián)調(diào)配置

前端聯(lián)調(diào)需要較穩(wěn)定的輸出結(jié)構(gòu)，因此建議在 CC Switch 中單獨(dú)建立配置卡。它和代碼**、測試生成、文檔自動化不是同一類任務(wù)，不要全部混用一張默認(rèn)配置。

配置卡可以命名為 Lingneng-Codex-Frontend-De*ug 或 Lingneng-Codex-Mock-Review。備注中寫明：用于接口字段對比、Mock 數(shù)據(jù)**、錯(cuò)誤復(fù)現(xiàn)和聯(lián)調(diào)文檔草稿；默認(rèn)只讀，不自動覆蓋頁面代碼；如需生成修改建議，只輸出代碼片段。

配置卡備注建議

用途：前端接口聯(lián)調(diào)和 Mock **
權(quán)限：只讀接口文檔、類型定義、頁面調(diào)用和 Mock 文件
輸出：字段差異、錯(cuò)誤路徑、Mock 修正建議、聯(lián)調(diào)記錄
限制：不自動覆蓋頁面代碼，不輸出真實(shí)密鑰
復(fù)核：由前端負(fù)責(zé)人確認(rèn)后再改代碼

• 聯(lián)調(diào)配置卡要獨(dú)立于日常問答配置。
• 備注要寫清楚讀取范圍和寫入限制。
• 配置變更后，先用固定樣本頁面驗(yàn)證。

五、第一類任務(wù)：接口字段和類型定義對齊

字段不一致是前端聯(lián)調(diào)里最常見的問題。后端返回 user_id，前端類型寫 userId；文檔說 status 是 num*er，真實(shí)響應(yīng)是 string；Mock 數(shù)據(jù)缺少 nulla*le 情況；頁面里把可選字段當(dāng)必填字段使用。Codex 可以先把這些差異列出來。

字段對齊任務(wù)的輸出最好使用結(jié)構(gòu)化清單，包含字段名、文檔定義、類型定義、頁面使用、Mock 示例和建議處理。這樣前端、后端、測試都能各自確認(rèn)自己的部分，而不是在一段長解釋里找問題。

字段對齊提示詞

請對比接口文檔、TypeScript 類型、頁面調(diào)用和 Mock 數(shù)據(jù)。
輸出：
1. 字段完全一致的部分
2. 字段名不一致
3. 類型不一致
4. 可選/必填不一致
5. Mock 數(shù)據(jù)缺失情況
6. 需要后端確認(rèn)的問題

限制：不要修改文件，不要把猜測寫成結(jié)論。

• 字段名、類型、可選性要分別檢查。
• Mock 數(shù)據(jù)必須覆蓋空值和異常值。
• 無法從代碼確認(rèn)的字段進(jìn)入待確認(rèn)。

六、第二類任務(wù)：生成 Mock 數(shù)據(jù)和邊界樣例

Mock 數(shù)據(jù)如果只覆蓋理想狀態(tài)，聯(lián)調(diào)時(shí)會給人一種頁面已經(jīng)穩(wěn)定的錯(cuò)覺。真實(shí)環(huán)境里常見的問題是列表為空、字段缺失、狀態(tài)異常、金額為零、時(shí)間為空、權(quán)限不足、后端返回延遲。Codex 可以根據(jù)接口字段生成更完整的 Mock 樣例。

生成 Mock 時(shí)要明確場景，不要只要求“給我一份 **ON”。建議至少準(zhǔn)備正常數(shù)據(jù)、空狀態(tài)、部分字段為空、錯(cuò)誤狀態(tài)、權(quán)限不足、分頁邊界六類樣例。每類樣例都要說明它用于驗(yàn)證哪個(gè)頁面表現(xiàn)。

{
  "scenario": "empty_order_list",
  "purpose": "驗(yàn)證訂單為空時(shí)的頁面占位、按鈕狀態(tài)和提示文案",
  "response": {
    "list": [],
    "total": 0,
    "page": 1,
    "pageSize": 20
  },
  "expected_ui": [
    "顯示空狀態(tài)提示",
    "隱藏批量操作按鈕",
    "分頁組件不可點(diǎn)擊"
  ]
}

生成后的 Mock 不要直接覆蓋現(xiàn)有文件。先讓開發(fā)者確認(rèn)字段和場景，再放入 mock 目錄或 story 文件。這樣可以避免模型把不存在的字段寫進(jìn)去，也能讓 Mock 數(shù)據(jù)真正服務(wù)頁面驗(yàn)證。

• Mock 場景要覆蓋正常、空、異常和權(quán)限邊界。
• 每個(gè) Mock 都要說明驗(yàn)證目的。
• Mock 入庫前必須確認(rèn)字段來自真實(shí)接口或文檔。

七、第三類任務(wù)：復(fù)現(xiàn)接口錯(cuò)誤路徑

前端錯(cuò)誤復(fù)現(xiàn)經(jīng)常靠口頭描述：點(diǎn)擊某個(gè)按鈕后偶爾報(bào)錯(cuò)，刷新后又好了。Codex 可以幫助把復(fù)現(xiàn)過程拆成步驟，尤其是在你提供請求參數(shù)、響應(yīng)片段、頁面狀態(tài)和最近改動后，它能整理出更清晰的排查路徑。

錯(cuò)誤復(fù)現(xiàn)輸出不應(yīng)該只包含原因猜測，而應(yīng)包含復(fù)現(xiàn)前置條件、操作步驟、預(yù)期結(jié)果、實(shí)際結(jié)果、可能原因、下一步抓取信息。這樣測試和后端也能參與確認(rèn)，而不是只讓前端自己猜。

錯(cuò)誤復(fù)現(xiàn)模板

前置條件：用戶已登錄，訂單處于待支付狀態(tài)
操作步驟：進(jìn)入訂單詳情，點(diǎn)擊繼續(xù)支付，等待接口返回
預(yù)期結(jié)果：進(jìn)入支付確認(rèn)頁
實(shí)際結(jié)果：頁面提示系統(tǒng)異常
關(guān)聯(lián)接口：POST /api/order/pay
已知響應(yīng)：code=403，message=permission denied
下一步：確認(rèn)用戶角色、訂單歸屬、支付權(quán)限和接口鑒權(quán)規(guī)則

• 復(fù)現(xiàn)步驟要能被測試同學(xué)照著執(zhí)行。
• 實(shí)際響應(yīng)要和頁面表現(xiàn)一起記錄。
• 原因猜測要和**證動作綁定。

八、**類任務(wù)：從報(bào)錯(cuò)日志反推頁面狀態(tài)

有些前端問題不是接口直接失敗，而是頁面狀態(tài)處理不完整。比如接口返回空數(shù)組，但組件仍然讀取 list[0].name；字段為 null，但頁面調(diào)用了字符串方法；請求取消后狀態(tài)仍然更新，導(dǎo)致頁面閃爍。Codex 可以根據(jù)報(bào)錯(cuò)堆棧和組件代碼，幫助反推可能的頁面狀態(tài)。

這類任務(wù)要給足三類信息：錯(cuò)誤堆棧、組件相關(guān)代碼、觸發(fā)時(shí)的接口響應(yīng)。如果只給錯(cuò)誤堆棧，Codex 可能只能猜測；如果只給組件代碼，又很難還原真實(shí)數(shù)據(jù)。三者結(jié)合，輸出才更接近實(shí)際問題。

頁面狀態(tài)排查提示詞

請讀取錯(cuò)誤堆棧、組件代碼和接口響應(yīng)片段。
輸出：
1. 報(bào)錯(cuò)位置
2. 觸發(fā)該報(bào)錯(cuò)需要什么頁面狀態(tài)
3. 哪個(gè)接口字段可能為空或類型不符
4. 建議增加的保護(hù)邏輯
5. 建議補(bǔ)充的 Mock 場景
6. 仍需人工確認(rèn)的問題

• 報(bào)錯(cuò)堆棧、組件代碼、接口響應(yīng)要一起看。
• 空值和異步狀態(tài)是前端聯(lián)調(diào)高頻問題。
• 建議要能轉(zhuǎn)成保護(hù)邏輯或測試場景。

九、第五類任務(wù)：生成聯(lián)調(diào)記錄和問題交接文檔

前端聯(lián)調(diào)過程中，很多有價(jià)值的信息只停留在聊天記錄里。今天確認(rèn)了字段，明天又有人問；這次知道某個(gè)錯(cuò)誤碼代表權(quán)限不足，下次又從頭排查。Codex 可以把聯(lián)調(diào)過程整理成簡短文檔，減少重復(fù)溝通。

聯(lián)調(diào)記錄不需要寫成長篇報(bào)告，但要包含接口、問題、當(dāng)前結(jié)論、待確認(rèn)人、下一步動作和更新時(shí)間。這樣前端、后端、測試、產(chǎn)品都能知道當(dāng)前卡點(diǎn)在哪里。

聯(lián)調(diào)記錄模板

接口：GET /api/order/detail
頁面：訂單詳情頁
當(dāng)前問題：返回字段 payStatus 與前端枚舉不一致
影響范圍：支付按鈕展示和訂單狀態(tài)文案
當(dāng)前結(jié)論：前端類型需要同步，后端需確認(rèn)歷史狀態(tài)值
負(fù)責(zé)人：前端 A / 后端 *
下一步：確認(rèn)枚舉表并補(bǔ)充 Mock
更新時(shí)間：2026-09-04

• 聯(lián)調(diào)記錄要短，但必須可追蹤。
• 待確認(rèn)事項(xiàng)要有負(fù)責(zé)人。
• 解決后的結(jié)論要同步到正式文檔。

十、控制成本：聯(lián)調(diào)任務(wù)不要每次都跑長上下文

前端聯(lián)調(diào)任務(wù)如果沒有限制，很容易變成長上下文消耗。一個(gè)頁面可能有多個(gè)接口、多個(gè)組件、多個(gè)狀態(tài)文件和多份 Mock，如果每次都讓 Codex 全量讀取，成本和等待時(shí)間都會上升。

更穩(wěn)的策略是按問題類型分級：字段對比可以走標(biāo)準(zhǔn)任務(wù)；短錯(cuò)誤解釋可以走輕量任務(wù)；跨頁面狀態(tài)流分析再走深度任務(wù)；完整聯(lián)調(diào)復(fù)盤只在階段結(jié)束時(shí)手動觸發(fā)。

聯(lián)調(diào)任務(wù)分級

輕量任務(wù)：解釋錯(cuò)誤碼、整理短日志、生成小段 Mock
標(biāo)準(zhǔn)任務(wù)：字段對比、類型對齊、單接口聯(lián)調(diào)記錄
深度任務(wù)：跨頁面狀態(tài)流、復(fù)雜權(quán)限路徑、階段復(fù)盤
手動觸發(fā)：完整聯(lián)調(diào)報(bào)告、跨模塊影響分析

• 字段問題不要跑全頁面深度分析。
• 短日志解釋應(yīng)限制輸出長度。
• 完整復(fù)盤適合階段結(jié)束后手動觸發(fā)。

十一、提示詞模板：讓聯(lián)調(diào)輸出直接可用

前端聯(lián)調(diào)提示詞要明確角色和輸出格式。不要寫“幫我看看接口為什么不對”，而要寫清楚讀取范圍、對比目標(biāo)、輸出結(jié)構(gòu)和限制。越具體，輸出越容易進(jìn)入實(shí)際排查流程。

你是前端接口聯(lián)調(diào)助手。

目標(biāo)：對比接口文檔、類型定義、頁面調(diào)用和 Mock 數(shù)據(jù)。
輸入：讀取指定文件，不擴(kuò)展到其他目錄。
輸出：字段差異、類型差異、錯(cuò)誤路徑、Mock 修正建議、待確認(rèn)事項(xiàng)。
限制：不修改文件，不輸出真實(shí)密鑰，不推測文檔中不存在的業(yè)務(wù)規(guī)則。
復(fù)核：所有待確認(rèn)問題單獨(dú)列出負(fù)責(zé)人建議。

這個(gè)模板可以作為團(tuán)隊(duì)默認(rèn)入口。每次只替換文件路徑和接口名稱，不要每個(gè)成員都重新發(fā)明提示詞。提示詞統(tǒng)一后，聯(lián)調(diào)記錄也會更統(tǒng)一，后續(xù)沉淀到知識庫時(shí)不用反復(fù)整理格式。

• 提示詞先限定范圍，再要求分析。
• 輸出要面向排查動作，不是泛泛解釋。
• 待確認(rèn)問題必須獨(dú)立列出。

十二、形成閉環(huán)：從問題發(fā)現(xiàn)到文檔更新

聯(lián)調(diào)結(jié)束后，如果結(jié)論沒有進(jìn)入文檔，下次還會重復(fù)。建議把 Codex 輸出分成三類處理：字段差異進(jìn)入接口文檔，Mock 場景進(jìn)入測試或 story，錯(cuò)誤復(fù)現(xiàn)進(jìn)入排查手冊。不要讓有價(jià)值的結(jié)論只留在一次對話里。

閉環(huán)的關(guān)鍵是責(zé)任清楚。前端確認(rèn)頁面表現(xiàn)，后端確認(rèn)接口字段，測試確認(rèn)復(fù)現(xiàn)場景，產(chǎn)品確認(rèn)文案和業(yè)務(wù)規(guī)則。Codex 負(fù)責(zé)整理和提醒，團(tuán)隊(duì)成員負(fù)責(zé)最終判斷。

聯(lián)調(diào)閉環(huán)清單

[ ] 字段差異已確認(rèn)
[ ] 類型定義已同步
[ ] Mock 場景已補(bǔ)充
[ ] 錯(cuò)誤復(fù)現(xiàn)步驟可執(zhí)行
[ ] 接口文檔已更新
[ ] 排查手冊已補(bǔ)充
[ ] 待確認(rèn)事項(xiàng)已關(guān)閉

• 發(fā)現(xiàn)問題只是開始，沉淀結(jié)論才是閉環(huán)。
• 字段、Mock、錯(cuò)誤復(fù)現(xiàn)要進(jìn)入不同文檔位置。
• 未關(guān)閉的待確認(rèn)事項(xiàng)不能當(dāng)作已完成。

? 十三、收尾：把前端聯(lián)調(diào)變成可復(fù)用流程

Codex 接入 Claude中轉(zhuǎn)站 后，前端聯(lián)調(diào)是一個(gè)很適合長期使用的場景。它不會替團(tuán)隊(duì)決定業(yè)務(wù)規(guī)則，卻能把字段差異、Mock 缺口、錯(cuò)誤復(fù)現(xiàn)和聯(lián)調(diào)記錄提前整理出來，讓溝通更清楚。

落地順序建議是：先通過靈能API統(tǒng)一接入入口，再用 CC Switch 固化前端聯(lián)調(diào)配置卡，然后從單接口字段對比開始，逐步擴(kuò)展到 Mock 生成、錯(cuò)誤復(fù)現(xiàn)、頁面狀態(tài)分析和聯(lián)調(diào)文檔沉淀。

當(dāng)這套流程穩(wěn)定后，前端團(tuán)隊(duì)會少很多“這個(gè)字段到底是什么”的來回確認(rèn)，也能把每次聯(lián)調(diào)經(jīng)驗(yàn)留給下一次項(xiàng)目。Codex 的價(jià)值不只是回答問題，而是讓問題被更快定位、被更好記錄、被更少重復(fù)。

• 先對齊字段，再生成 Mock。
• 先復(fù)現(xiàn)錯(cuò)誤，再判斷原因。
• 先沉淀聯(lián)調(diào)記錄，再擴(kuò)展自動化范圍。