先看清楚：多項目工作區(qū)不是一個項目

單項目接入 Codex API 中轉(zhuǎn)站時，只要根目錄里的配置能生效，基本就能繼續(xù)往下走。但多項目工作區(qū)不一樣，根目錄可能只負(fù)責(zé)依賴管理，真正調(diào)用模型的是 apps/api、apps/we*、packages/agent、tools/scripts 這些子目錄。你在根目錄驗證成功，不代表每個子項目都在使用同一套配置。

所以多項目接入的第一原則，是把“倉庫可用”和“服務(wù)可用”拆開。靈能API負(fù)責(zé)統(tǒng)一中轉(zhuǎn)入口，CC Switch負(fù)責(zé)保存不同用途的配置卡，而每個子項目都要做自己的最小驗證。這樣才能避免前端走新配置、后端走舊配置、腳本走默認(rèn)地址的混亂情況。

• 根目錄驗證：確認(rèn)當(dāng)前終端和基礎(chǔ)中轉(zhuǎn)鏈路可用。
• 子項目驗證：確認(rèn)某個服務(wù)真實讀取了對應(yīng)配置。
• 腳本驗證：確認(rèn)批處理、生成器或測試工具沒有寫死舊參數(shù)。
• 回滾驗證：確認(rèn)出問題時能切回穩(wěn)定配置。

第一步：先統(tǒng)一確認(rèn)靈能API服務(wù)側(cè)信息

多項目工作區(qū)里不要讓每個子項目各自找一套 API 信息。先打開靈能API官網(wǎng) https://www.lnsns.com/，由負(fù)責(zé)人統(tǒng)一確認(rèn)當(dāng)前賬號、模型列表、額度和 Key 分組策略。這樣后續(xù)每個子項目只需要引用同一份可信來源，不用從舊文檔和舊截圖里猜。

建議把非敏感字段寫成一份工作區(qū)接入說明：服務(wù)名稱、官網(wǎng)入口、*ase **L、模型選擇原則、負(fù)責(zé)人、回滾策略。完整 API Key 不寫進(jìn)說明文檔。

• 確認(rèn)賬號狀態(tài)正常，避免把服務(wù)側(cè)問題帶入項目排查。
• 確認(rèn)當(dāng)前模型列表，避免子項目使用過期 Model ID。
• 確認(rèn)額度足夠支持多個子項目分別測試。
• 確認(rèn) Key 分組方式，避免所有服務(wù)共用一條 Key。

第二步：按服務(wù)拆分 Key，而不是按倉庫共用

多項目倉庫最容易偷懶的做法，是整個倉庫共用一條 Key。短期確實省事，但只要某個子項目請求量異常，你就很難知道是前端調(diào)試、后端接口、文檔生成還是測試腳本造成的。更穩(wěn)的方式是按服務(wù)或用途拆分 Key。

Key 分組示例：
we*-codex-dev：前端項目日常開發(fā)
api-codex-dev：后端項目日常開發(fā)
do**-codex-*uild：文檔生成和摘要
scripts-codex-check：工具腳本驗證
monorepo-codex-de*ug：全倉庫排查專用
monorepo-codex-roll*ack：回滾對照專用

靈能API的 Key 分組越細(xì)，后續(xù)成本追蹤越容易。尤其是多服務(wù)倉庫，一條異常消耗能快速定位到具體子項目，而不是讓整個團(tuán)隊一起猜。

• 前端、后端、文檔、腳本分別使用不同用途 Key。
• 排查 Key 不參與日常任務(wù)，只用于定位問題。
• 回滾 Key 保持穩(wěn)定，不頻繁調(diào)整模型和參數(shù)。

第三步：在 CC Switch 建立多項目配置卡規(guī)則

CC Switch 的配置卡在多項目場景里非常適合做分組管理。不要只建一張“默認(rèn)卡”，而是按服務(wù)和用途建立清晰命名的卡片。這樣切換到哪個子項目，就能對應(yīng)啟用哪張卡。

配置卡命名建議：
靈能API-Codex-Monorepo-We*-Dev
靈能API-Codex-Monorepo-API-Dev
靈能API-Codex-Monorepo-Do**-*uild
靈能API-Codex-Monorepo-Scripts-Check
靈能API-Codex-Monorepo-De*ug
靈能API-Codex-Monorepo-Roll*ack

命名清晰以后，截圖溝通也更快。別人看到卡片名，就能知道當(dāng)前是不是在測正確的服務(wù)。

• 服務(wù)名用于區(qū)分子項目。
• 環(huán)境名用于區(qū)分本地、測試、遠(yuǎn)程或容器。
• 用途名用于區(qū)分開發(fā)、構(gòu)建、排查和回滾。

? **步：每張卡都核對 *ase **L、Model ID、API Key

多項目工作區(qū)配置多，越要堅持字段來源一致。*ase **L 統(tǒng)一來自靈能API入口，Model ID 從當(dāng)前模型列表復(fù)制，API Key 使用對應(yīng)服務(wù)分組。不要讓某個子項目卡片沿用舊模型，另一個子項目卡片使用新模型，排查時會很麻煩。

字段模板：
*ase **L：https://www.lnsns.com/v1
Model ID：從靈能API當(dāng)前模型列表復(fù)制
API Key：對應(yīng)服務(wù)或用途的專用 Key
備注：服務(wù)名、環(huán)境、負(fù)責(zé)人、創(chuàng)建日期
禁止：完整 Key 出現(xiàn)在截圖、README 或提交記錄里

如果某張卡要使用不同模型，備注里要寫清原因，比如“長上下文分析”“低成本驗證”“文檔摘要”。否則后續(xù)會以為是誤配置。

• *ase **L 不要在不同卡片里寫成不同入口。
• Model ID 更新時，按卡片逐張驗證，不批量盲改。
• API Key 只寫入**配置或安全工具，不寫進(jìn)倉庫。

第五步：先畫出工作區(qū)目錄和配置來源

進(jìn)入真實倉庫前，先讓 Codex 只讀分析目錄結(jié)構(gòu)，找出每個子項目可能讀取 API 配置的位置。不要讓它直接修改文件，也不要讀取 .env 明文。目標(biāo)是先畫出配置來源圖。

請只讀分析當(dāng)前工作區(qū)，不要修改文件。
請輸出：
1. 子項目目錄清單
2. 每個子項目可能的 SDK 初始化位置
3. 可能讀取 *ase **L、API Key、Model ID 的配置文件
4. 需要避開的敏感文件
5. 推薦的逐服務(wù)驗證順序

多項目工作區(qū)常見的配置文件包括根目錄 .env.example、子項目 .env、config 模塊、SDK client 文件、package script、Docker compose、CI 配置等。先知道入口在哪里，再談接入。

• 先找配置入口，不讀取敏感值。
• 先確認(rèn)哪些子項目真的會調(diào)用模型。
• 先記錄每個服務(wù)的啟動方式和測試入口。

第六步：根目錄只做基礎(chǔ)短請求，不代表全部通過

根目錄驗證的意義，是確認(rèn)當(dāng)前終端、CC Switch 和靈能API基礎(chǔ)鏈路可用。它是第一道門檻，但不是最終結(jié)論。根目錄通過以后，還要進(jìn)入每個子項目做獨(dú)立驗證。

New-Item -ItemType Directory codex-monorepo-root-check
Set-Location codex-monorepo-root-check
codex

請只回復(fù)：多項目工作區(qū)根目錄中轉(zhuǎn)站配置已生效。

這個驗證最好保留下來，作為以后回歸測試的第一步。只要根目錄短請求失敗，子項目驗證就先暫停。

• 根目錄成功：繼續(xù)進(jìn)入子項目逐個驗證。
• 根目錄 401：優(yōu)先檢查 Key 和舊環(huán)境變量。
• 根目錄 404：優(yōu)先檢查 *ase **L 和 Model ID。
• 根目錄 timeout：先排查網(wǎng)絡(luò)、**和 DNS。

第七步：為每個子項目建立最小驗證命令

多項目工作區(qū)真正穩(wěn)定的關(guān)鍵，是每個子項目都有自己的最小驗證命令。前端可以驗證環(huán)境變量讀取，后端可以驗證 SDK client 創(chuàng)建，腳本項目可以驗證一次短請求，文檔項目可以驗證摘要生成。

逐服務(wù)驗證清單：
apps/we*：確認(rèn)前端構(gòu)建不會暴露服務(wù)端 Key
apps/api：確認(rèn)后端 SDK 使用靈能API *ase **L
packages/agent：確認(rèn)模型名從統(tǒng)一配置讀取
tools/scripts：確認(rèn)腳本不寫死舊接口地址
do**：確認(rèn)文檔生成任務(wù)使用低成本模型卡

逐服務(wù)驗證會讓問題邊界更小。比如 apps/api 失敗，不代表 do** 失敗；tools/scripts 讀錯變量，也不代表靈能API服務(wù)側(cè)不可用。

• 每個子項目只測一件事，先不跑全量任務(wù)。
• 每個子項目記錄當(dāng)前配置卡和模型。
• 每個子項目失敗時，先留在本目錄排查，不影響其他服務(wù)。

第八步：防止 .env、腳本和默認(rèn)值互相打架

多項目倉庫里，最容易制造混亂的是多套配置同時存在：根目錄一份 .env，子項目一份 .env.local，腳本里又寫了默認(rèn) *ase **L，CI 里還有變量。接入時要讓配置讀取路徑盡量單一。

建議配置優(yōu)先級：
1. 安全環(huán)境變量或**密鑰管理
2. 子項目** .env，本地不提交
3. 根目錄 .env.example，只寫變量名和示例
4. 代碼默認(rèn)值只允許用于非敏感字段
5. 禁止在業(yè)務(wù)代碼里寫死 API Key

如果項目已經(jīng)很亂，先讓 Codex 輸出配置來源清單，再逐個收斂。不要直接全局替換，尤其不要讓它讀取或打印敏感文件內(nèi)容。

• 不要把真實 Key 寫進(jìn) .env.example。
• 不要讓不同子項目使用不同變量名表達(dá)同一件事。
• 不要在 SDK 初始化處偷偷寫死舊 *ase **L。

第九步：用表格記錄每個服務(wù)的接入狀態(tài)

多項目接入一定要有狀態(tài)記錄。口頭說“倉庫已經(jīng)接好了”沒有意義，因為可能只有根目錄成功。建議記錄每個子項目的配置卡、模型、Key 用途、驗證命令和結(jié)果。

服務(wù)驗證記錄：
服務(wù)：apps/api
配置卡：靈能API-Codex-Monorepo-API-Dev
模型：當(dāng)前 Model ID
Key 用途：api-codex-dev
驗證命令：最小 SDK 請求
結(jié)果：成功 / 失敗
錯誤碼：401 / 404 / timeout / model_not_found
備注：不記錄完整 Key

這張表會讓多項目接入從“模糊成功”變成“逐項確認(rèn)”。項目越大，越值得這樣做。

• 狀態(tài)記錄要能看出哪個子項目已通過。
• 失敗項要記錄錯誤碼和下一步動作。
• 模型或配置卡變更后，要重新更新記錄。

第十步：模型切換要先在單個子項目灰度

當(dāng)你準(zhǔn)備給多項目工作區(qū)切換模型時，不要一次性把所有卡片都改掉。先選一個低風(fēng)險子項目灰度，比如 do** 或 scripts，用靈能API的新模型跑幾輪短任務(wù)，確認(rèn)穩(wěn)定后再推廣到 api 或 agent 這類核心服務(wù)。

模型切換最怕“全倉庫同步失敗”。灰度方式慢一點(diǎn)，但問題只會影響一個子項目，回滾也更簡單。

• 先復(fù)制配置卡，不直接覆蓋原卡。
• 先在低風(fēng)險子項目驗證新模型。
• 記錄新模型的響應(yīng)速度、成本和錯誤碼。
• 保留回滾卡，核心服務(wù)不和試驗卡綁定。

第十一步：真實開發(fā)任務(wù)從小范圍開始

多項目工作區(qū)接入完成后，第一次真實任務(wù)不要直接要求 Codex 重構(gòu)多個服務(wù)。建議從單個子項目、單個文件、單個測試入口開始，讓它先展示理解和修改邊界。

推薦第一輪真實任務(wù)：
請只處理 apps/api/src/config 目錄。
目標(biāo)：檢查 SDK 初始化是否統(tǒng)一讀取環(huán)境變量。
限制：不要讀取 .env、secrets、私鑰和生產(chǎn)配置。
輸出：發(fā)現(xiàn)的問題、建議修改、需要確認(rèn)的風(fēng)險。
在我確認(rèn)前不要修改文件。

這樣能把靈能API中轉(zhuǎn)站能力放進(jìn)真實項目，同時避免第一次就把多個服務(wù)的配置全部攪在一起。

• 先讓 Codex 提出范圍，再批準(zhǔn)修改。
• 先做配置入口修復(fù)，再做業(yè)務(wù)調(diào)用改造。
• 先跑局部測試，再考慮全倉庫任務(wù)。

? 最后一份多項目工作區(qū)檢查清單

多項目工作區(qū)接入 Codex API 中轉(zhuǎn)站，真正要做的是把復(fù)雜倉庫拆成**證的小單元。靈能API提供統(tǒng)一中轉(zhuǎn)入口，CC Switch管理不同服務(wù)的配置卡，逐服務(wù)驗證負(fù)責(zé)確認(rèn)每一段鏈路真實生效。把這套流程跑順后，多目錄、多模型、多團(tuán)隊協(xié)作都會更穩(wěn)。

• 已從靈能API確認(rèn)賬號、模型、額度和 Key 分組策略。
• 已按服務(wù)或用途拆分 API Key，不讓全倉庫共用一條 Key。
• 已在 CC Switch 建立多項目配置卡命名規(guī)范。
• 每張卡的 *ase **L、Model ID、API Key 來源一致。
• 已只讀梳理工作區(qū)目錄和配置入口。
• 根目錄短請求通過，但沒有把它當(dāng)成全倉庫通過。
• 每個子項目都有自己的最小驗證命令。
• 已整理 .env、腳本默認(rèn)值和 CI 變量的優(yōu)先級。
• 模型切換先灰度，保留回滾配置卡。