Codespaces -- 信念映射架構探索

Codespaces -- 信念映射架構探索 是做什麼的？

在讀取原始碼檔案之前，先查詢 .belief_map.sexp 以探索模組、邊界與相依性。切勿盲目閱讀程式碼——先查詢圖形。

腳本

此技能內含 Python 腳本。請從技能的基礎目錄執行它們：

• scripts/belief_search.py -- 查詢信念映射圖形
• scripts/build_belief_map.py -- 從原始碼產生信念映射
• scripts/build_infra_topology.py -- 提取 Kustomize、Helm 與 Terraform 拓撲事實
• scripts/git_descendants.py -- 尋找從 HEAD（或指定參考點）開始的所有後續提交

切勿使用專案本地的腳本副本——它們可能已過時，且會輸出 JSON 而非 S-expression。

前置條件

找到信念映射檔案。若不存在，則建立它：

ls .belief_map.sexp belief_map.sexp 2>/dev/null
# 建立：pip3 install tree-sitter tree-sitter-typescript tree-sitter-python
python3 scripts/build_belief_map.py          # 增量建置 ~5 秒
python3 scripts/build_belief_map.py --full   # 完整重建 ~30 秒

強制工作流程：先查詢，再讀程式碼

對於非瑣碎的程式碼工作，請在執行 rg、find、sed、cat、nl、開啟目錄或讀取原始碼檔案之前，先執行信念映射查詢。此技能只有在作為第一個範圍界定步驟而不是在原始碼已檢查完後作為確認時才有幫助。

任務有關鍵字時的快速第一遍：

python3 scripts/belief_search.py quick "keyword"

quick 會搜尋第一個匹配的模組並立即執行 analyze。用它來一步獲取邊界檔案、相依性、反向相依性、層級與違規。如果 quick 返回錯誤的模組或找不到匹配項，請使用下面明確的 search -> analyze 流程。

步驟 1 -- 尋找模組 ID：

python3 scripts/belief_search.py search "keyword"
python3 scripts/belief_search.py entity EntityName

使用 search 或 entity 來定位模組 ID。模組 ID 是完整的相對路徑，例如 pki-service/src/modules/ca/ca.service，而不是像 ps34 這樣的簡短代碼。信念映射內部可能包含短的 path-map ID，但它們會自動解析——始終傳遞人類可讀的類路徑字串。請勿猜測或發明模組 ID —— 務必先用 search 確認。

步驟 2 -- 分析模組（立即且必須執行，而非可選）：

python3 scripts/belief_search.py analyze <module-id>

analyze 是主要命令。它返回完整的上下文：邊界檔案、相依性、反向相依性、架構層級與違規。在讀取任何原始碼之前，務必先執行它。

步驟 3 -- 只讀取 analyze 輸出中列出的邊界檔案。

步驟 4 -- 請勿讀取整個目錄。 如果邊界顯示 2-3 個相關檔案，只讀取那些檔案。忽略目錄中所有其他內容。

命令參考

命令	目的	範例
search "<pattern>"	圖形上的正則表達式搜尋（尋找模組 ID）	search "operative.*service"
analyze <id>	完整模組分析（主要命令）	analyze drive/modules/drive/drive_schema
quick <keyword>	搜尋 + 分析第一個匹配項（快捷鍵）	quick operatives
boundary <id>	變更需要讀取的檔案	boundary operatives.service
boundary <id> --files-only	僅檔案路徑（簡潔）	boundary operatives.service --files-only
entity <Name>	尋找定義 + 參考	entity DrivePath
deps <id> [depth]	外向相依性樹	deps operatives.service 3
rdeps <id> [depth]	影響範圍（誰依賴於此）	rdeps drive_schema 2
flow <id> <fn>	追蹤呼叫/資料流	flow drive_api fetchFiles
module <id>	帶邊界的單一模組	module operatives.controller
`boundaries [id	all]`	檢查架構違規
`invariants [id	all]`	檢查命名慣例違規
layers	按層級顯示所有模組	layers
find_function <name>	尋找函數/方法定義	find_function createOrder
find_type <name>	尋找型別/類別/介面/列舉定義	find_type DriveDbCommitResponse
find_callchain <src> <tgt> [depth]	追蹤函數間的呼叫路徑	find_callchain createOrder processPayment
find_callers <fn> [depth]	誰呼叫此函數	find_callers handleRequest 3
find_calls <fn> [depth]	此函數呼叫了什麼	find_calls createOrder 2
grep_functions <pattern>	在原始碼中搜尋函數主體	grep_functions "validate.*input"
diff_functions [ref]	git diff 中變更的函數	diff_functions HEAD~3
query '<sexp>'	可組合的 Scheme 查詢	query '(count (boundary "X"))'
repl	互動式 Scheme REPL	repl

快速參考：rg 查詢

當你需要快速、有針對性的查詢而不需呼叫 Python 腳本時，可直接用 rg 查詢信念映射。配套的建置器會寫入 .belief_map.sexp；如果儲存庫仍使用舊的 belief_map.sexp，請在下列命令中替換該檔名：

# 關於模組的所有事實
rg 'drive/modules/drive_db/api ' .belief_map.sexp

# 誰匯入了某模組
rg 'imports .* drive/modules/commons/result' .belief_map.sexp

# 模組匯入了什麼
rg 'imports drive/modules/drive_db/api' .belief_map.sexp

# 對實體的所有參考
rg 'DriveDbCommitResponse' .belief_map.sexp

# 儲存庫中的所有類別
rg '^\(cls drive/' .belief_map.sexp

# 資料流邊緣
rg 'data-flow' .belief_map.sexp

這些單行指令對於快速檢查很有用。若要獲得結構化輸出和完整分析，請使用 Python 腳本命令。

輸出表示法

所有輸出均為 S-expression 事實，每行一個。完整的格式請參閱 references/sexp-notation.md。

關鍵模式：

(boundary <mod> :lang py :file <path> :purpose "<desc>")
(boundary-dep <mod> <dep> :lang ts :file <path> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <path> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <Name> <line> :lang py :file <path>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<reason>")
(result <module-or-path>)
(result-count 42)

:lang 值：py = Python（蛇形命名法），ts = TypeScript（駝峰命名法），tsx = TSX（帕斯卡命名法）。

Scheme 查詢語言

為複雜分析編寫可組合的查詢。完整參考請參閱 references/scheme-queries.md。

基本：

(boundary "id")                ; 目標 + 相依性 + 反向相依性（變更邊界）
(entity "Name")                ; 定義此實體的模組
(deps "id" depth)              ; 外向相依性
(rdeps "id" depth)             ; 反向相依性
(find-function "name")         ; 具有匹配函數定義的模組
(find-type "name")             ; 具有匹配型別定義的模組
(find-callers "fn" depth)      ; 呼叫某函數的模組
(find-calls "fn" depth)        ; 某函數呼叫的模組
(intersect A B)                ; 集合交集
(filter SET "pattern")         ; 正則表達式過濾
(files SET)                    ; 解析為檔案路徑
(count SET)                    ; 計算成員數
(violations)                   ; 有邊界違規的模組
(layer "id")                   ; 模組的架構層級

分析計劃模式

在修改程式碼之前，從查詢組合出一個計劃：

; 1. 範圍界定
(boundary "operatives.service")
(count (boundary "operatives.service"))

; 2. 架構約束
(violations "operatives.service")
(layer "operatives.service")

; 3. 跨語言邊界
(filter (refs-to "DrivePath") "app-service")

; 4. 縮小到可操作的檔案
(filter (boundary "operatives.service") "dto")
(intersect (deps "controller" 2) (deps "service" 2))

; 5. 變更後：驗證
(violations "operatives.service")

觸發範例

在讀取原始碼之前，針對以下情況使用此技能：

• 提及服務、API、任務、事件、UI 流程或失敗行為的根本原因調查。
• 跨服務或跨模組的問題，包括「X 如何呼叫 Y？」以及「這個儲存在哪裡？」
• 當答案依賴於程式碼行為時的 Redmine 澄清。
• 架構審查、影響評估、公共合約變更或影響範圍檢查。
• 審查非瑣碎的暫存變更，特別是在依賴方向或模組歸屬很重要時。

不要強迫它用於僅提交任務、git-log 摘要、手動示範/伺服器執行、純瀏覽器測試或會話日誌分析。

錯誤恢復

如果某命令返回 (error no-match ...)：

1. 請勿使用相同的 ID 重試或猜測另一個 ID
2. 用更廣泛的關鍵字執行 search 以找到正確的模組 ID
3. 使用存在的 :suggestions 欄位——它會列出相似的模組 ID

# 錯誤：猜測 ID
python3 scripts/belief_search.py analyze ps34        # 失敗：ps34 是簡短的 path-map ID
python3 scripts/belief_search.py analyze ca.service  # 失敗：路徑不完整

# 正確：先搜尋，然後使用結果中的完整路徑
python3 scripts/belief_search.py search "ca.*service"
# 輸出顯示：pki-service/src/modules/ca/ca.service
python3 scripts/belief_search.py analyze pki-service/src/modules/ca/ca.service

反模式

• 猜測模組 ID。 模組 ID 是完整的相對路徑（例如 pki-service/src/modules/ca/ca.service）。像 ps34 這樣的簡短代碼是內部的 path-map ID，不得直接使用。務必先 search。
• 建置但不查詢。 建立信念映射後從未執行 search、analyze 或 boundary，這完全沒有價值。
• 讀取原始碼後才查詢。 第一次讀取原始碼應來自 analyze 輸出中的 boundary-file 行。
• 將 .belief_map.sexp 作為完整檔案讀取。 使用 search、analyze 或 rg 來查詢特定事實。
• 跳過跨模組任務的信念映射。 在讀取原始碼檔案前，務必先查詢圖形以了解邊界。
• 讀取目錄中的所有檔案。 當邊界顯示 2-3 個檔案時，只讀取那些。
• 使用專案本地腳本。 始終使用此技能內建的腳本。專案副本可能會輸出 JSON 而非 S-expression。

重建圖形

python3 scripts/build_belief_map.py          # 增量建置 (~5 秒)
python3 scripts/build_belief_map.py --full   # 完整重建 (~30 秒)
python3 scripts/build_belief_map.py ./drive  # 單一子儲存庫
python3 scripts/build_belief_map.py --lsp    # 含 LSP 呼叫層級 (~1-5 分鐘)

在結構性變更（新增/刪除檔案、變更匯入、新增類別）後重建。

基礎設施拓撲

從 Kustomize、Helm 與 Terraform 檔案中提取服務拓撲。此腳本需要 PyYAML（pip3 install pyyaml）。

python3 scripts/build_infra_topology.py                    # 自動偵測所有 IaC
python3 scripts/build_infra_topology.py --kustomize .      # 僅 kustomize
python3 scripts/build_infra_topology.py --helm ./charts    # 僅 helm charts
python3 scripts/build_infra_topology.py --terraform ./infra # 僅 terraform
python3 scripts/build_infra_topology.py --append .belief_map.sexp  # 合併到圖形

產生 infra-node、k8s-depends、k8s-service、helm-depends、tf-depends 與 infra-maps 邊緣。使用以下方式查詢：

rg 'infra-node' .belief_map.sexp                  # 所有服務
rg 'k8s-depends' .belief_map.sexp                 # 服務相依性
rg 'infra-node.*:component database' .belief_map.sexp  # 所有資料庫
rg 'infra-maps.*app-service' .belief_map.sexp     # 基礎設施 -> 原始碼對應