Xylem 是做什麼的?
您將把一個儲存庫轉換成一個以原始碼為根據的地圖。它包含四個檢視,位於一個靜態的雙檔案網站(index.html 和 deep-view.json)中:
| 檢視 | 顯示內容 |
|---|---|
| 瀏覽 | 元件(系統的組成部分)以及它們之間的連線,按層次分組 |
| 客戶歷程 | 使用者可以採取的每個歷程,在架構上以動畫呈現:請求、回覆及帶標籤的交接 |
| 狀態圖 | 對應範圍內每個已宣告的狀態維度、其狀態,以及歷程實際採用的轉換 |
| 程式碼 | 每個已對應的函式以磁磚形式顯示在其區域內,包含其決策、呼叫與呼叫者,以及在函式層級追蹤的歷程路徑 |
方法比頁面更重要。每一項宣告都必須附有 file:line。每一條連線都是真實的。當程式碼無法確定某件事時,地圖會如實說明,而不是猜測。
基本規則(在各階段均適用)
- 有證據,否則不成立。 每個元件、單元、決策、邊、狀態和動作都應引用
file:line。如果您無法引用,請將其標記為UNVERIFIED或直接省略。這是作者/審查者的義務:自動化關卡會強制要求架構證據和深層原始碼位置,但不強制要求每個狀態/動作引用或說明的精確含義。 - 指定 ID;絕不憑空創造實體或連線。 使用框架產生的檔案位置 ID;手動撰寫的 ID 也必須是唯一且穩定的。跨區域的邊必須依賴已宣告的架構連線。如果缺少某條連線,請記錄一個
diagram_gap,並在程式碼中驗證後再添加,且需附上證據。 - 誠實的缺口勝過不可能的路徑。 如果無法從原始碼中明確追蹤某個歷程的結果,請寫
{"unavailable": "<具體原因>"}。切勿將成功路徑複製到失敗結果中。切勿鏈結不可能同時為真的分支。 - 如實說明。 追蹤結果是靜態原始碼路徑,而非真實執行的記錄。請在頁面中標明。
- 唯讀。 絕不編輯目標儲存庫。所有內容都寫入
.xylem/(或使用者命名的資料夾)。 - 隱私。 除非使用者要求,否則不要將儲存庫內容發送給任何外部服務。該網站僅對其資料和可選影片發出同源請求。它不會發出任何外部請求;請在迴環(loopback)位址上提供服務以供離線使用。
輸出佈局
.xylem/
census.json # 在程式碼中找到的每個定義(scripts/census.py)
architecture.json # 階段 1
journeys.json # 階段 2
deep.json # 階段 3(函式層級地圖)
validation.json # scripts/validate.py 的輸出
reviews/ # 交叉審查報告(階段 6)
site/ # index.html + deep-view.json (+ videos/) (scripts/build_site.py)
每個檔案的格式定義在 references/schemas.md 中。在撰寫任何 JSON 之前,請先閱讀該文件。
階段與關卡
請依序執行各個階段。每個階段都以一個關卡(gate)結束。除非關卡通過,或者使用者接受有記錄的缺口,否則不要繼續。在明確授權的試驗中,保留失敗的工件和日誌不變,僅在該試驗範圍內繼續;將後續輸出標記為暫定。結構性通過並不代表完整的語意涵蓋範圍。
階段 0:普查(確定性)
python scripts/census.py <repo> --out .xylem/census.json [--exclude dir ...]
此腳本使用 Python AST、標準函式庫的 JS/TS Token 走訪器,以及針對其他支援語言的近似正規表達式,來盤點具名定義。scannedFiles 包含零定義的原始碼檔案。JS/TS 涵蓋通用箭頭函式、具體的多行/計算方法、重載簽名、詞法函式/類別擁有者、正規表達式字面量和模板插值;匿名回呼不算普查單元。這是一個測量性的盤點,並非所有語言語法的證明。在使用獨立的解析器或原始碼樣本驗證其完整性之前,請先進行限定。後續的百分比僅描述此盤點範圍。
關卡: 普查計數看起來與儲存庫規模相符。排除的路徑需有正當理由,例如產生的程式碼或 node_modules。
階段 1:架構
閱讀進入點、建置檔案、主要模組和程序邊界。然後撰寫 architecture.json:
- 層次: 例如 shell、UI、伺服器、領域、儲存、工作者、外部;
- 元件: 每個都包含
id、layer、files[]、簡潔的職責描述,以及processType; - 連線: 每個
{from, to, label, kind},其中kind為 spawn、ipc、http、file、data 或 uses; - 流程: 主要的端到端流程,以有序的元件步驟呈現。
關卡: python scripts/validate.py .xylem --only architecture 通過。每個 scannedFiles 條目都屬於某個元件,或者在 architecture.meta.fileExclusions 中有合理的說明。證據路徑和行號必須存在於證據根目錄下。
階段 2:歷程與狀態
撰寫 journeys.json。根據 UI、路由、CLI 指令、作業和錯誤路徑來擬定這些內容:
- stateDimensions: 每個獨立的狀態機;
- screens: 每個畫面;
- actions: 每個使用者動作和系統轉換,包含其結果、使用者看到的確切文字,以及復原方式;
- journeys: 起始狀態加上步驟。
每個動作都帶有一個有序的架構追蹤(交錯的元件和連線)。回程使用 {"connection": [a, b], "direction": "reply"}。當下一步不是從上一步結束的地方開始時,該步驟會攜帶 transition.handoff,並包含類型和標籤:user、timer、queue、continuation、lifecycle 或 download。涵蓋快樂路徑、不快樂路徑、復原路徑和邊界路徑。
關卡: validate.py --only journeys 通過:
- 每個歷程都能透過有效的結果重播;
- 零靜默跳躍(每次亮起都是經由一條連線、一個回覆或一個帶標籤的交接到達);
- 沒有孤立狀態。
階段 3:函式層級地圖(最終解析)
- 從普查產生草稿地圖:
python scripts/scaffold_deep.py .xylem
它會寫出 deep.json。草稿包含已分配的普查單元、來自 AST 的 Python 決策,以及啟發式 JS/TS if、while、for、switch 和括號括起的 catch 點。JS/TS 不聲稱完整盤點三元運算式、計算或短路決策。註解、字面量內容和子宣告會從每個主體中排除。通用呼叫保留不同的呼叫位置。呼叫邊使用 source: heuristic 和 confidence: name-resolved;未解析的名稱不會被當作發明的連結。根據原始碼進行 refinement;名稱解析不是型別解析。
2. 透過閱讀程式碼來 refinement 草稿:
- 每個單元一個業務可讀的
summary,根據主體而非名稱撰寫; - 對於每個決策,一個
plain問題(「這個檔案是否大於 16 MiB?」)加上確切的程式碼test、一個kind(branch、calculation、loop 或 unconditional)以及正確的後繼者。return或raise會終止路徑。try 區塊的正常和錯誤延續是分開的,待決的例外會執行finally然後傳播。當您不確定時,請將後繼者標記為unresolved;絕不標記為verified; - 僅在直接實現已知缺陷的決策上加上
risk標籤。
- 撰寫
actionTraces:對於每個歷程動作和結果,有序的執行事件{component, unit, event, decision?, line, note?, callsite?, returnTo?, precondition?, boundary?}。event是 call、return、branch、async、spawn、ipc、http、file、render、unknown、throw、finally 或 resume 之一。請參閱 schema 以了解啟用框架、終端事件和支援的重播限制。- 從真正的啟動者開始,例如 UI 處理常式、路由或作業。
- 跟隨呼叫、返回和程序邊界。拒絕必須遵循真實的錯誤路徑回到使用者。它絕不能繼續到「已儲存」或「成功」。
- 當路徑無法得知時,發出
{"event": "unknown", "note": "..."},或將整個結果標記為 unavailable。
大型儲存庫:將階段 3 按程式碼區域拆分給多個代理,每個代理撰寫相同格式的 deep-<part>.json,然後使用 scripts/merge_deep.py 合併它們。透過檔案和定義行號來調和 ID,絕不依賴名稱相似性。
關卡: validate.py 通過完整集合:
- 每個普查定義都已發出,或已明確排除且有原因;已發出的覆蓋率和排除的計數是分開的計數器;
- 每條邊的端點都能解析;
- 每條跨區域邊都依賴一條連線;
- 決策的後繼者能解析;
- 追蹤引用是有效的;
- 選擇器一致性: 對於未改變的值,沒有啟用框架會做出互斥的選擇。原始碼寫入可以改變一個值;迭代標籤本身不能重置約束。支援的語法和限制在 schema 中。例如,先有
x==='a'為真,然後x==='b'為真,或者某個值被排除後又被includes()要求。修正追蹤,或將其撤回至unavailable,並指出衝突。
階段 4:建置頁面
python scripts/build_site.py .xylem
這會寫出 site/index.html 和 site/deep-view.json。影片是可選的:先將 videos/<journeyId>.mp4 加上 videos/manifest.json 放入 .xylem/(請參閱 schema)。透過 HTTP 提供 site/ 服務以檢視它,例如 python -m http.server -d .xylem/site。file:// 頁面無法載入程式碼檢視的資料。
關卡: 開啟頁面並檢查每種模式一次:
- 無主控台錯誤;
- 手機寬度(420 px)無水平捲動;
- 鍵盤和深色模式正常運作。
階段 5:可選的真實畫面錄製
如果應用程式有您可以在本地端執行的 UI,請使用 Playwright 錄製歷程。起手腳本是 scripts/record_journey.example.mjs。錄製規則:
- 驅動真實 UI,不 mock 任何回應;
- 為每個步驟添加說明文字;
- 加快空閒等待速度,並在說明文字中標註加速;
- 在
manifest.json中記錄每個步驟的atSec; - 將部分錄製標記為部分。
檢視器會將影片與地圖同步,因此影片就成為了時鐘。
階段 6:交叉審查委員會
在可能的情況下使用兩位獨立的審查者:兩個不同的模型或代理,或至少一個全新的上下文,無法存取作者的推理過程。遵循 references/protocol.md:
- 作者絕不評分自己的工作;
- 審查者接收檔案和程式碼,而非作者的結論;
- 審查者執行獨立檢查器,並從原始碼中抽樣檢查宣告:使用 protocol.md 中的單一抽樣規則(低於其最小值時檢查所有可用項目);
- 發現結果寫入
reviews/<reviewer>-<round>.md,包含嚴重性、證據和具體的修正方案; - 接受關卡: 對於 architecture、journeys、deep、page/data 和最終凍結的套件,必須有明確的 ACCEPT、REJECT 或 BLOCKED。只有實質性的缺陷才構成 REJECT 的理由:錯誤的結論、不可能的路徑或阻礙核心任務。已宣告的限制、誠實的
unavailable標記以及追蹤的靜態特性不構成拒絕的理由; - 使用有限的審查預算;如果未解決,則以 REJECT/BLOCKED 停止並保留證據。重新審查確切的建置工件,而非其描述。
關卡: 所有凍結套件的工件都通過獨立審查。切勿為了達到抽樣配額而偽造路徑。
階段 7:發布與報告
告訴使用者頁面中有什麼內容,附上實際的計數:
- 函式、決策、歷程和追蹤的結果數量;
- 有多少結果是 unavailable,以及原因;
- 哪些內容經過了交叉審查。
如實報告限制。
腳本
| 腳本 | 目的 |
|---|---|
census.py | 多語言定義普查(覆蓋率分母) |
scaffold_deep.py | 從普查和架構產生函式層級地圖草稿 |
merge_deep.py | 合併部分地圖;根據檔案和行號調和 ID |
validate.py | 每個關卡:schema、引用、覆蓋率、靜默跳躍、後繼者、選擇器一致性 |
build_site.py | 匯出緊湊的程式碼檢視資料並建置單頁網站 |
record_journey.example.mjs | 用於真實畫面歷程影片的 Playwright 起手腳本 |
Python 腳本需要 Python 3.9+ 且僅使用標準函式庫。可選的 .mjs 瀏覽器/錄製輔助工具需要單獨可用的 Playwright。該頁面不使用任何框架或外部請求。