多項目接入最容易混淆的三個邊界

每個項目至少有三個邊界：項目目錄、項目運行環(huán)境和 Codex 接入配置。目錄決定讀取哪些文件，運行環(huán)境決定使用哪些命令和變量，配置卡決定請求發(fā)往哪條線路。三者混在同一個終端里，就很難判斷問題來自哪里。

接入前先寫清邊界，再建立對應(yīng)卡片；不要把所有項目都指向一張名為‘默認’的配置。

• 目錄邊界：當前工作區(qū)和允許讀取的文件。
• 運行邊界：Node、Python、包管理器和 .env。
• 線路邊界：*ase **L、模型、Key 和權(quán)限。

第一步：給每個項目建立線路登記表

打開靈能API服務(wù)入口，先確認項目需要的模型、接口地址和權(quán)限，再為每個項目登記一行信息。登記表只保存用途和配置元數(shù)據(jù)，不保存完整 API Key。

項目：do**-tool
環(huán)境：local
用途：代碼閱讀與文檔生成
*ase **L：<當前接口地址>
Model ID：<當前模型標識>
Key：<本機安全存儲>

靈能API入口：https://www.lnsns.com/。項目登記表的作用是讓你知道‘哪張卡給哪個項目使用’，而不是替代安全的令牌存儲。

? 第二步：在 CC Switch 中按項目命名配置卡

建議使用‘項目-環(huán)境-用途’的命名順序，例如‘do**-tool-local-development’。如果同一項目有測試和生產(chǎn)線路，環(huán)境必須寫進卡片名稱，避免切換時依賴顏色或位置記憶。

卡片名稱清楚之后，切換線路的動作就可以被檢查和復(fù)述，團隊成員也不必猜測當前狀態(tài)。

• 每個項目保留一張已驗證的基線卡。
• 測試卡和日常開**分開。
• 停用卡片標明日期和原因，不直接刪除歷史記錄。

第三步：每次啟動前確認工作目錄

Codex 的上下文與當前工作目錄密切相關(guān)。啟動前先確認 PowerShell 位置，再檢查項目根目錄是否包含預(yù)期的 package.json、pyproject.toml 或其他入口文件。不要從另一個項目的終端窗口直接繼續(xù)。

Get-Location
Get-ChildItem -Force | Select-O*ject Name
git status

• 目錄名稱與配置卡中的項目名稱對應(yīng)。
• Git 狀態(tài)屬于當前項目，而不是另一個工作區(qū)。
• 啟動命令從項目根目錄執(zhí)行。

**步：讓項目變量與線路配置各自負責

項目的 .env 文件用于應(yīng)用運行時，CC Switch 配置用于 Codex 客戶端線路。兩者可能都出現(xiàn)模型或地址字段，但來源不同。最穩(wěn)妥的方式是明確誰是最終來源，避免系統(tǒng)變量、項目變量和客戶端配置互相覆蓋。

# .env.example
APP_ENV=development
APP_MODEL=<項目運行時模型>
APP_API_KEY=<本機填寫，不提交倉庫>

• 模板保留占位符，真實值只在本機或安全存儲中出現(xiàn)。
• 檢查 .gitignore 是否忽略真實 .env。
• 不要用項目變量無意覆蓋 Codex 的線路配置。

第五步：用固定流程切換項目

切換項目時，建議固定為‘停止舊進程、確認目錄、啟用卡片、重新啟動、最小測試’五步。少做其中一步，就可能出現(xiàn)界面顯示新卡片、實際進程仍使用舊配置的情況。

1. 關(guān)閉舊 Codex 進程
2. 進入目標項目根目錄
3. 啟用目標配置卡
4. 重新啟動 Codex
5. 先執(zhí)行只讀測試

不要在多個項目之間快速點擊切換并同時保留多個終端。先完成一個項目的狀態(tài)確認，再開始下一個項目。

第六步：用只讀任務(wù)確認沒有串項目

進入新項目后，第一條指令不要直接要求修改文件。可以讓 Codex 列出當前目錄、解釋指定配置文件或概括一個模塊，并明確告訴它不要寫入。回答中如果出現(xiàn)另一個項目的文件名或約束，立即停止并檢查上下文。

請確認當前工作目錄和項目名稱。
只讀取 README.md 和 package.json。
不要修改任何文件。
說明當前項目的啟動命令。

只讀驗證通過后，再讓 Codex 執(zhí)行安裝、測試或局部修改。這樣即使線路切錯，也能在沒有寫入變更前發(fā)現(xiàn)。

?? 第七步：為每個項目保留可回滾點

項目切換和線路調(diào)整都應(yīng)該有回滾點。最簡單的做法是保留上一張已驗證卡片，并在項目變更前記錄當前配置卡名稱、工作目錄和 Git 狀態(tài)。發(fā)生異常時先回到這組已知狀態(tài)，再逐項排查。

不要為了證明某個配置可用而刪除項目現(xiàn)有修改。回滾動作必須明確范圍，并保留當前狀態(tài)記錄。

• 配置回滾：切回上一張已驗證卡。
• 代碼回滾：只處理本次變更，不覆蓋用戶已有修改。
• 環(huán)境回滾：恢復(fù)項目所需的運行時和變量。

多項目場景常見錯誤

遇到問題時，先恢復(fù)到‘正確目錄 已知穩(wěn)定卡 只讀任務(wù)’這個最小狀態(tài)，再決定下一步。

• 卡片切換了但進程沒重啟：舊配置仍在內(nèi)存中。
• 同名卡片太多：無法確認當前啟用的是哪張。
• 從錯誤目錄啟動：Codex 讀取了另一個項目。
• 環(huán)境變量覆蓋客戶端字段：界面值和實際請求不一致。
• 共享完整 .env：項目秘密擴散到不必要的設(shè)備。
• 測試直接寫文件：還沒確認線路就產(chǎn)生了項目變更。

? 多項目接入驗收清單

靈能API與 CC Switch 適合被納入項目工作流，但穩(wěn)定的關(guān)鍵仍是清晰的目錄邊界、配置邊界和驗證順序。

• 每個項目都有清晰的配置卡名稱。
• 配置卡記錄用途和環(huán)境，不記錄完整令牌。
• 啟動前能確認當前工作目錄。
• 項目變量和 Codex 線路變量沒有無意覆蓋。
• 切換流程包含關(guān)閉舊進程和重新啟動。
• 每次切換先執(zhí)行只讀驗證。
• 每個項目都有可用的卡片和環(huán)境回滾點。