2026 DeepSeek Harness AGENTS.md 不生效怎麼排查？

症狀：AGENTS.md 明明存在，但 DeepSeek Harness 仍忽略專案規範。
最快解法：先確認會話工作目錄與專案根，再核對候選指令檔、內容限制和本地覆蓋層；修改檔案後必須用新會話或明確刷新上下文驗證。

這篇適合三類人：已建立 AGENTS.md，但 Agent 仍沒有遵守規範的開發者；維護 monorepo、多層目錄或多個指令檔的技術負責人；以及把工作區搬到遠端 Mac 後，發現本地與遠端行為不一致的運維人員。

「檔案存在」不等於「規則已生效」

排查時要把「檔案在硬碟上」和「內容進入本次模型上下文」視為兩件事。前者只能證明路徑上有檔案，不能證明程序找到了正確的專案根，也不能證明內容通過讀取、格式和上下文預算檢查。

通常有至少四個隱性限制：

• 工作目錄可能錯位：終端機從父資料夾啟動，Web UI 選的是工作區名稱，但實際倉庫根可能是另一層。
• 多層規則可能改變：monorepo 根目錄和子專案都可能存在指令檔；進入子目錄後，Agent 看到的 workspace context 不一定與根目錄會話相同。
• 候選檔案可能互相覆蓋：AGENTS.md、CLAUDE.md、全域指令及本地覆蓋檔同時存在時，不能只按檔名猜測實際採用順序。
• 舊會話可能保留舊內容：修改檔案後，繼續原會話未必會重新建立專案上下文；這時看起來像檔案監聽失效，其實是會話歷史仍在發揮作用。
• 權限與編碼會造成靜默失敗：檔案可在 Finder 中看見，不表示啟動 DeepSeek Harness 的使用者能讀取它。macOS 的檔案存取仍受擁有者、群組及讀取權限控制，可參考Apple 的檔案權限說明。

公開操作指南可以確認 DeepSeek Harness 具備工作區、會話、檔案工具和本地設定等運作概念；但具體候選順序、檔案變更監聽和介面回饋，應以你當天使用的版本與原始碼為準，不要把其他 Agent 工具的規則直接套過來。參考 DeepSeek Harness 操作指南

先固定「這次會話到底在哪裡開始」

第一步：記錄啟動目錄與實際倉庫根

在建立會話前，先在同一個終端機記錄：

pwd
git rev-parse --show-toplevel
find .. -name AGENTS.md -o -name CLAUDE.md

pwd 用來保存程序啟動時的目前目錄；如果 DeepSeek Harness 由 Node 程式啟動，也可用 process.cwd() 檢查該程序的工作目錄。Node 官方文件對 process.cwd() 的定義，就是回傳目前 Node.js 程式的工作目錄。查看 Node.js process.cwd() 文件

git rev-parse --show-toplevel 則用來確認 Git 工作樹頂層路徑；如果這個結果與你在 Web UI 選取的工作區不一致，先修正工作區，不要先修改指令內容。查看 Git 根目錄命令說明

第二步：建立最小測試倉庫

不要直接拿有大量業務程式碼的倉庫測試。建立一個只包含下列內容的臨時目錄：

dsh-rule-test/
├── .git/
├── AGENTS.md
└── src/

在 AGENTS.md 寫入一條不會改動檔案、但容易觀察的規則，例如：

驗證規則：回答本倉庫狀態時，必須先指出「規則標記：海風」。
禁止執行任何寫入、刪除或安裝命令。

這條規則的價值在於可驗證，而不是內容本身。若 Agent 只回答「我看到了 AGENTS.md」，卻沒有回傳「規則標記：海風」，就不能視為規則已進入上下文。

注意：不要用「請遵守所有規則」作為測試。這種要求太寬泛，即使載入失敗，也很難從回答中判斷原因。

前半段先比較哪些載入條件？

這張表的重點不是建立一套未經版本確認的優先順序，而是把「哪個環節失敗」固定下來。若你需要先規劃遠端 Mac 的工作區與存取方式，可先看遠端開發環境的使用場景，再回到本文驗證指令檔。

子目錄會改變你看到的規則集合

在 monorepo 中，根目錄的 AGENTS.md 可能只描述整體工具鏈，而 apps/mobile/ 或 packages/api/ 下面又有更具體的規則。你需要用同一個測試標記，分別從根目錄和子目錄建立會話，並保存以下三項結果：

1. Agent 是否能指出目前工作路徑。
2. Agent 是否能回傳根目錄規則標記。
3. Agent 是否能回傳子目錄規則標記。

如果根目錄會話和子目錄會話的結果不同，不要立即判定其中一個「漏載入」。可能是層級規則只適用於目標目錄，也可能是相同段落被折疊，還可能是你進入了另一個 Git 工作樹。

CLAUDE.md 也應單獨測試。不要把它和 AGENTS.md 合併成一個想像中的規則集合：在兩個檔案放入不同的無害識別字，然後於新會話要求 Agent 列出它實際採用的規範。若結果不穩定，就把共用規則集中到一份來源，另一份只保留工具特定補充。其他編碼 Agent 對根目錄與最近指令檔的處理方式也不完全相同，相關差異可參考公開的自訂指令文件，但不要把其行為當成 DeepSeek Harness 的官方承諾。

檔案太長或格式異常時的驗證方法

任務書沒有提供一個可安全套用到所有版本的固定大小上限，因此不要把網路文章中的某個數字當成 DeepSeek Harness 的預設值。你應該做的是逐步縮減，而不是無限增大指令檔：

1. 先備份原始 AGENTS.md，記錄檔案大小、編碼和雜湊。
2. 保留禁止事項、驗證命令、目錄邊界及輸出格式等真正執行約束。
3. 把背景介紹、架構歷史、長篇範例移到獨立文件。
4. 在新會話中測試精簡版是否出現獨特規則標記。
5. 再逐段加回內容，找出導致載入失敗或回應不穩定的區段。

除了長度，也檢查 UTF-8 編碼、不可見字元、意外的二進位內容和檔案是否能由實際執行帳戶讀取。若遠端 Mac 上由不同帳戶啟動，Finder 顯示「可讀」並不能代替終端機的實際驗證。

• [ ] 在目前工作區執行 ls -l AGENTS.md CLAUDE.md，確認擁有者與讀取權限。
• [ ] 用執行 DeepSeek Harness 的同一帳戶執行 cat AGENTS.md >/dev/null。
• [ ] 檢查檔案是否為有效 UTF-8，並移除不可見控制字元。
• [ ] 記錄精簡前後的檔案雜湊，避免測試時讀到另一份副本。
• [ ] 將背景資料移出指令檔，只留下可驗收的規則。
• [ ] 用全新會話重做獨特標記測試。

修改檔案後的會話刷新判斷

把修改後的行為分成三組比較：

• 繼續舊會話：用來觀察舊上下文是否仍然存在。
• 建立新會話：用來確認檔案內容是否在初始化階段被重新讀取。
• 重啟執行程序後建立新會話：用來排除程序層級快取、設定載入或環境變數未更新。

每一組都使用完全相同的無風險測試任務，並保存修改前後的檔案雜湊、啟動路徑、會話識別資訊和 Agent 回應。DeepSeek Harness 公開操作文件明確區分新建與恢復會話，因此不能把 --resume 後的結果直接當成新上下文驗證。參考會話操作與恢復方式

如果新會話能看到新標記、舊會話看不到，根因大多是上下文生命週期，而不是檔案沒有保存。此時不要重複編輯提示詞；把團隊流程改成「修改規則後建立乾淨會話，再執行基準任務」。

遠端重啟後的端到端驗收流程

搬到遠端 Mac 後，至少要重新核對五個環節：

1. 工作區路徑：本地與遠端是否使用同一個倉庫根，而非相同名稱的不同目錄。
2. DSH_HOME：如果你的部署使用此環境變數，記錄它在本地和遠端的實際值，並確認沒有指向舊設定目錄。
3. 檔案交付：確認 AGENTS.md、CLAUDE.md 和任何本地覆蓋檔真的隨倉庫或部署流程送達。
4. 權限：用遠端啟動帳戶直接讀取檔案，不要只檢查管理員帳戶。
5. 基準任務：使用同一個最小測試倉庫、同一個規則標記和同一個新會話流程比較結果。

若本地成功、遠端失敗，先把問題歸類為路徑、環境或權限差異；若兩邊新會話都失敗，再回頭檢查候選檔案和內容預算。無法立即恢復時，回退到固定的專案根目錄，移除本地覆蓋檔，建立乾淨會話，再逐層加回規則。

你也可以把這套驗收流程納入常見問題與環境核對入口，讓團隊成員在交付遠端工作區前先完成路徑、權限和新會話測試。

遠端 Mac 方案適合用於可重現排查

如果問題只在本地出現，常見缺點包括：每位開發者的工作目錄不一致、權限與 shell 設定各自漂移，以及同一倉庫難以重現乾淨會話。繼續在這種環境反覆改寫 AGENTS.md，通常只會把路徑問題誤認成模型問題。

當你需要臨時建立一致的 DeepSeek Harness 測試環境、比較本地與遠端載入結果，或讓團隊共用一套可驗收的 Mac 工作區時，租用 KVMFLUX 的遠端 Mac 會比臨時購置硬體更容易控制交付條件；但若你要長期滿載運算、需要實體介面，或已有穩定自有設備，直接自購 Mac 仍可能更合適。你可先查看目前方案與 Mac 遠端使用方式，再依測試週期和權限需求決定，不必把所有指令失效問題都歸咎於提示詞。

延伸閱讀

• DeepSeek Harness 接入 GitHub Actions 的設定與排查指南
• AI Agent 外掛與跨平台標準：理解工具整合與執行流程

常見問題 FAQ