一、為什么接入后還要做請(qǐng)求追蹤

只要是團(tuán)隊(duì)使用 Codex，就一定會(huì)遇到“我剛才這次請(qǐng)求為什么不對(duì)”的問(wèn)題。可能是模型名填錯(cuò)，可能是上下文太長(zhǎng)，可能是 Key 權(quán)限變化，也可能是提示詞里混入了過(guò)期需求。如果沒(méi)有追蹤記錄，每次排查都只能靠回憶。

請(qǐng)求追蹤的目標(biāo)不是把所有內(nèi)容都記錄下來(lái)，而是保留足夠判斷鏈路問(wèn)題的信息。靈能API負(fù)責(zé)統(tǒng)一 API 中轉(zhuǎn)站入口，CC Switch負(fù)責(zé)配置切換，追蹤日志則負(fù)責(zé)記錄這次調(diào)用屬于哪個(gè)項(xiàng)目、哪類(lèi)任務(wù)、哪張配置卡、結(jié)果是否成功。

二、追蹤日志不要等出問(wèn)題才補(bǔ)

很多團(tuán)隊(duì)在鏈路穩(wěn)定時(shí)不記錄，等異常出現(xiàn)才發(fā)現(xiàn)沒(méi)有任何依據(jù)。請(qǐng)求追蹤最好從第一次接入就開(kāi)始設(shè)計(jì)，哪怕字段很少，也要保證每次調(diào)用都能回到同一套記錄口徑。

字段不需要復(fù)雜，但必須穩(wěn)定。今天記模型名，明天記項(xiàng)目名，后天只寫(xiě)一句“失敗了”，這種記錄無(wú)法形成排查價(jià)值。

• 誰(shuí)發(fā)起：成員、腳本或自動(dòng)化任務(wù)。
• 用什么：CC Switch 配置卡、模型名稱(chēng)、任務(wù)類(lèi)型。
• 做什么：代碼生成、審閱、排障、文檔整理或測(cè)試補(bǔ)齊。
• 結(jié)果如何：成功、失敗、超時(shí)、格式不符或需要人工復(fù)查。

三、先確認(rèn)靈能API入口和基礎(chǔ)狀態(tài)

開(kāi)始設(shè)計(jì)追蹤流程前，先進(jìn)入靈能API https://www.lnsns.com/，確認(rèn) API *ase、可用模型、賬號(hào)狀態(tài)和當(dāng)前項(xiàng)目使用規(guī)則。所有追蹤字段都要圍繞真實(shí)接入信息建立，不能用舊截圖或歷史配置湊數(shù)。

團(tuán)隊(duì)文檔里可以把靈能API設(shè)置成可點(diǎn)擊入口，方便成員核對(duì)信息。需要注意的是，請(qǐng)求追蹤不等于記錄完整請(qǐng)求；完整 Key、真實(shí)用戶(hù)數(shù)據(jù)和內(nèi)部賬號(hào)都不應(yīng)該進(jìn)入日志。

四、CC Switch 配置卡要參與日志命名

如果團(tuán)隊(duì)使用多張 CC Switch 配置卡，日志里必須記錄配置卡名稱(chēng)。否則排查時(shí)只知道“Codex 輸出不對(duì)”，卻不知道它當(dāng)時(shí)用的是輕量配置、審閱配置還是文檔配置。

日志里記錄配置卡，比只記錄模型名更有用。因?yàn)榕渲?*常包含任務(wù)意圖、輸入邊界和使用場(chǎng)景，能幫助團(tuán)隊(duì)更快判斷是否誤用了配置。

• codex-dev：日常開(kāi)發(fā)與局部修改。
• codex-review：diff 審閱與風(fēng)險(xiǎn)檢查。
• codex-de*ug：錯(cuò)誤日志分析和復(fù)現(xiàn)步驟整理。
• codex-do**：文檔、說(shuō)明和復(fù)盤(pán)整理。

五、建議的追蹤字段

第一版追蹤日志可以用表格或 **ON Lines 保存。重點(diǎn)是字段可讀、可篩選、可復(fù)盤(pán)，而不是一開(kāi)始就做復(fù)雜平臺(tái)。

{
  "trace_id": "codex-20260903-001",
  "project": "project-a",
  "task_type": "de*ug",
  "config_card": "codex-de*ug",
  "model": "team-selected-model",
  "input_size": "short|medium|large",
  "result": "success|failed|timeout|needs_review",
  "error_category": "none|auth|model|network|for**t|context",
  "created_at": "2026-09-03T10:30:00 08:00"
}

trace_id 很關(guān)鍵。它可以把一次請(qǐng)求、一次截圖、一次復(fù)現(xiàn)包和一次工單備注串起來(lái)。后續(xù)有人問(wèn)“當(dāng)時(shí)那次失敗是哪次”，直接用 trace_id 就能定位。

六、日志脫敏要寫(xiě)成規(guī)則

請(qǐng)求追蹤最容易踩的坑，是為了方便排查而把敏感信息寫(xiě)進(jìn)日志。正確做法是記錄元信息，不記錄敏感原文；必要時(shí)保存脫敏摘要，而不是完整請(qǐng)求。

靈能API https://www.lnsns.com/ 作為統(tǒng)一入口時(shí)，日志只需要記錄它對(duì)應(yīng)的配置名稱(chēng)和調(diào)用結(jié)果，不需要把**敏感頁(yè)面復(fù)制進(jìn)排查材料。

• Key：不記錄完整值，只記錄配置來(lái)源或變量名。
• 用戶(hù)信息：手機(jī)號(hào)、郵箱、訂單號(hào)、賬號(hào) ID 做替換。
• 業(yè)務(wù)內(nèi)容：只保留模塊、錯(cuò)誤類(lèi)型、影響范圍，不保留隱私數(shù)據(jù)。
• 截圖材料：上傳前檢查是否包含賬號(hào)、余額、密鑰或內(nèi)部域名。

七、錯(cuò)誤分類(lèi)比原始報(bào)錯(cuò)更有價(jià)值

很多日志只記錄一長(zhǎng)串異常文本，讀起來(lái)費(fèi)勁，也不利于統(tǒng)計(jì)。建議把錯(cuò)誤先歸類(lèi)，再保留簡(jiǎn)短摘要。這樣一周后復(fù)盤(pán)時(shí)，能看出主要問(wèn)題集中在哪一類(lèi)。

有了分類(lèi)，***就能更快判斷該修接入、修配置、修提示詞還是修知識(shí)包。不要每次都從原始報(bào)錯(cuò)重新讀起，那樣太耗時(shí)間。

• auth：Key 無(wú)效、權(quán)限不足、賬號(hào)狀態(tài)異常。
• model：模型名錯(cuò)誤、模型不可用、配置卡未同步。
• network：網(wǎng)絡(luò)超時(shí)、連接失敗、**或 DNS 問(wèn)題。
• for**t：輸出格式不符合要求，需要調(diào)整提示詞。
• context：輸入材料不足、上下文過(guò)長(zhǎng)、資料互相沖突。

八、本地最小復(fù)現(xiàn)包怎么準(zhǔn)備

當(dāng)某次 Codex 調(diào)用效果異常時(shí)，最好不要直接把完整對(duì)話轉(zhuǎn)發(fā)給別人。更規(guī)范的方式是準(zhǔn)備一個(gè)最小復(fù)現(xiàn)包：只保留能復(fù)現(xiàn)問(wèn)題的輸入、配置說(shuō)明和預(yù)期輸出。

replay-pack/
  README.md              問(wèn)題說(shuō)明、trace_id、復(fù)現(xiàn)步驟
  input-re**cted.md      脫敏后的輸入材料
  expected-output.md     期望輸出結(jié)構(gòu)
  actual-output.md       實(shí)際輸出摘要
  config-note.md         CC Switch 配置卡名稱(chēng)、模型名、任務(wù)類(lèi)型
  check-result.md        人工復(fù)查結(jié)論

復(fù)現(xiàn)包越小，定位越快。它不追求還原全部上下文，而是保留足夠證明問(wèn)題的材料：同樣輸入、同樣配置、同樣預(yù)期，是否還能得到類(lèi)似偏差。

九、用 Codex 生成復(fù)現(xiàn)包摘要

你也可以讓 Codex 幫忙整理復(fù)現(xiàn)包摘要，但要先脫敏。輸入給它的不是完整賬號(hào)和真實(shí)數(shù)據(jù)，而是處理后的問(wèn)題材料。

請(qǐng)根據(jù)以下脫敏材料生成問(wèn)題復(fù)現(xiàn)摘要。
必須包含：trace_id、任務(wù)類(lèi)型、使用配置卡、輸入摘要、預(yù)期輸出、實(shí)際偏差、需要人工確認(rèn)的問(wèn)題。
不要補(bǔ)充不存在的賬號(hào)信息，不要還原被脫敏的數(shù)據(jù)。

這類(lèi)摘要適合寫(xiě)回工單或排查文檔。別人接手時(shí)，不需要重新讀完整對(duì)話，只看復(fù)現(xiàn)包就能理解問(wèn)題范圍。

十、如何判斷是配置問(wèn)題還是提示詞問(wèn)題

請(qǐng)求失敗不一定是接入問(wèn)題，輸出不理想也不一定是模型問(wèn)題。排查時(shí)可以先按順序判斷：鏈路是否通、配置是否正確、輸入是否充分、輸出格式是否被明確要求。

這個(gè)判斷順序能減少無(wú)效排查。先確認(rèn)鏈路，再確認(rèn)配置，最后討論提示詞和模型表現(xiàn)，思路會(huì)清楚很多。

• 最小請(qǐng)求失?。簝?yōu)先看 API *ase、Key、模型名和網(wǎng)絡(luò)。
• 最小請(qǐng)求成功，真實(shí)任務(wù)失敗：看上下文長(zhǎng)度、材料沖突和任務(wù)范圍。
• 內(nèi)容正確但格式混亂：看提示詞是否給了明確輸出結(jié)構(gòu)。
• 偶發(fā)好壞不一：看樣本是否穩(wěn)定，配置是否被多人臨時(shí)修改。

十一、每周看一次追蹤統(tǒng)計(jì)

追蹤日志如果只在故障時(shí)看，價(jià)值會(huì)少一半。建議每周***輕量統(tǒng)計(jì)，看看哪些錯(cuò)誤最常見(jiàn)、哪些配置卡最容易出問(wèn)題、哪些任務(wù)最容易需要人工返工。

周復(fù)盤(pán)指標(biāo)：
總請(qǐng)求次數(shù)：
失敗次數(shù)：
超時(shí)次數(shù)：
格式不符次數(shù)：
上下文不足次數(shù)：
最常出問(wèn)題的配置卡：
需要更新的提示詞模板：
需要補(bǔ)充的知識(shí)包內(nèi)容：

如果連續(xù)幾周都出現(xiàn) context 類(lèi)錯(cuò)誤，說(shuō)明團(tuán)隊(duì)的知識(shí)包或工單輸入需要加強(qiáng)；如果 for**t 類(lèi)錯(cuò)誤很多，說(shuō)明提示詞模板還不夠清楚。追蹤的意義，就是把感覺(jué)變成證據(jù)。

? 十二、自動(dòng)化腳本要帶 trace_id

如果團(tuán)隊(duì)把 Codex 調(diào)用放進(jìn)腳本，例如自動(dòng)生成摘要、整理日志、輔助審閱，就更應(yīng)該帶 trace_id。自動(dòng)化任務(wù)一旦失敗，沒(méi)有 trace_id 會(huì)很難定位是哪一輪輸入出了問(wèn)題。

自動(dòng)化越多，追蹤越重要。靈能API與 CC Switch 解決的是接入和切換，trace_id 解決的是后續(xù)誰(shuí)來(lái)排查、怎么排查、根據(jù)什么排查。

• 腳本啟動(dòng)時(shí)生成 trace_id，并寫(xiě)入本地日志。
• 輸出文件名帶 trace_id，方便和日志對(duì)應(yīng)。
• 錯(cuò)誤摘要帶分類(lèi)，不直接保存敏感原文。
• 復(fù)現(xiàn)包只保存脫敏輸入和必要配置說(shuō)明。

十三、完整落地順序

• 第一步：進(jìn)入靈能API https://www.lnsns.com/，確認(rèn) API *ase、模型范圍和賬號(hào)狀態(tài)。
• 第二步：在 CC Switch 中按任務(wù)類(lèi)型建立配置卡，并統(tǒng)一命名。
• 第三步：為每次 Codex 調(diào)用生成 trace_id，記錄項(xiàng)目、配置卡、模型和結(jié)果。
• **步：制定日志脫敏規(guī)則，不記錄完整 Key 和真實(shí)用戶(hù)數(shù)據(jù)。
• 第五步：把錯(cuò)誤分成鑒權(quán)、模型、網(wǎng)絡(luò)、格式、上下文幾類(lèi)。
• 第六步：出現(xiàn)異常時(shí)準(zhǔn)備最小復(fù)現(xiàn)包，而不是轉(zhuǎn)發(fā)完整對(duì)話。
• 第七步：每周復(fù)盤(pán)追蹤統(tǒng)計(jì)，更新提示詞模板和知識(shí)包。

? 十四、結(jié)語(yǔ)：能復(fù)現(xiàn)的問(wèn)題，才真正好解決

Codex API 中轉(zhuǎn)站接入完成后，請(qǐng)求追蹤會(huì)變成團(tuán)隊(duì)穩(wěn)定使用的關(guān)鍵能力。靈能API提供統(tǒng)一入口，CC Switch管理配置卡，trace_id、脫敏日志和復(fù)現(xiàn)包則把一次次調(diào)用變成可排查記錄。

當(dāng)問(wèn)題出現(xiàn)時(shí)，團(tuán)隊(duì)不必靠猜測(cè)判斷原因，而是能根據(jù)配置、輸入、結(jié)果和錯(cuò)誤分類(lèi)逐步定位。接入鏈路越常用，越需要這種可觀察、可復(fù)現(xiàn)、可復(fù)盤(pán)的工作流。