Communitygithub.com

truepath

產生一個自包含的 HTML 模擬,逐步解釋流程或錯誤路徑 — 一個點沿著真實路徑移動,資料面板顯示每一步的變化,並並排播放「之前/之後」情境,標記首次分歧點。

truepath 是什麼?

truepath 是一個 AI Agent 技能,可根據 `spec.json` 規範生成自包含的離線 HTML 模擬。它支援流程圖、情境比較和網格比較,用於視覺化流程、錯誤路徑或決策規則。該技能支援兩個平台:Oracle(從凍結的 Git 快照執行真實程式碼以獲取判決)和 JS Port(用於尚未編寫程式碼的規則)。它與 Claude Code、Cursor、Codex 等工具相容。核心工作流程是編寫描述節點、邊、情境和判決來源的 `spec.json`,然後執行 `build.py` 來計算判決、執行 13 項檢查並生成 HTML 檔案。其獨特功能包括:一個點沿著邊移動的動畫、帶有資料面板的詳細步驟、並排的「之前/之後」比較以及用於比較多個規則的網格。該工具強制要求情境不得與實際程式碼行為矛盾(C3、C4 檢查),防止發布不準確的模擬。它支援英文和法文,具有淺色/深色主題,且無需網路字型即可離線運作。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bastien-gallay/truepath/tree/HEAD/skills/truepath

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

truepath 是做什麼的?

一個 spec.json 敘述流程(節點、邊緣)、情境(路徑、訊息、標題、輸入)以及判決的來源。build.py 計算判決、佈局圖形、執行檢查,並產生一個離線的 .html 檔案 — 否則什麼都不產生。

spec.json ──┐
oracle/port ├─► build.py ──► checks C1–C13 ─► sim.html   (or nothing)
layout.py ──┘                                └► fixture.json (--export)

工作流程

  1. 將最接近的範例複製到主題筆記旁邊(請參閱檔案), 將 spec.json 重新命名為 <subject>.spec.json。

  2. 敘述節點和邊緣。每個匯集節點(結果)都有一個 kind; 這些 kind 是唯一的顏色,每個顏色都有一個圖例標籤。

  3. 選擇判決的來源(見下文):當規則存在於程式碼中時使用 oracle,否則使用 JS port。

  4. 編寫情境。每個情境宣告其 origin、其 inputs、預期的判決欄位 expect,以及沿著實際邊緣的 steps。

  5. 建置,然後開啟檔案:

    python3 <skill-dir>/scripts/build.py <subject>.spec.json
    
  6. 閱讀違規情況,修正規格 — 永遠不要修改檢查。

spec.json 建置 sim.html,<subject>.spec.json 建置 <subject>.sim.html;-o 可指定其他檔案名稱。

頁面開啟在第一個分頁,細節面板展開。折疊面板會切換到概覽:繪製完整路徑,一個點在其上循環移動。

判決的來源

來源規格鍵使用時機面板中的標記
Oracleoracle規則存在於儲存庫中✓ code
Portport: "decide.js"尚無程式碼、正在討論的規則、無程式碼的流程⚠ ported

Oracle 協議。 build.py 對 oracle.ref 執行 git archive(永遠不是即時工作目錄:正在開發的分支在建立過程中可能會移動),提取 oracle.paths,連結 oracle.link(通常是 node_modules)並將 oracle.files 複製到其中,然後在 oracle.cwd 中執行 oracle.cmd,同時設定:

  • TRUEPATH_ORACLE_IN:一個 JSON 陣列,包含每個情境的 inputs;
  • TRUEPATH_ORACLE_OUT:要寫入判決 JSON 陣列的位置,順序相同。

當 oracle.repo 是相對路徑時,會從規格所在的資料夾讀取。link 和 files 都以 {snapshot中的路徑: 來源} 的格式寫入:link 是儲存庫中的路徑,files 是規格旁邊的檔案。

判決是一個包含欄位的物件。outcome 是必要的:它指定路徑必須結束的節點,並將情境與邏輯連結起來。basis 選擇性地說明每個欄位是否由真實程式碼計算("code: …")、glue 複製了行為("port: …")或模擬定義了它(任何其他文字,顯示為 ◇ definition)。頁面會在每個面板值的旁邊顯示該標記,前提是其欄位有基礎值,將滑鼠懸停在其上時會顯示完整文字,而 --export 只斷言基礎值為 code 的欄位:在 oracle 下,沒有基礎值的欄位視為 code,在 port 下則視為 ported。一個 oracle 可以混合它們:仍在討論中的規則與程式碼已執行的規則並列。任何執行器都可以使用:專案自己框架的測試檔案、腳本、Java 的 JUnit 測試。頁尾會顯示產生判決的參考名稱和簡短 SHA。

測試檔案 oracle 可以兼作回歸測試套件:當設定 TRUEPATH_ORACLE_IN 時,它會寫入判決,否則它會讀取匯出的 fixture 並斷言它。這樣情境就只存在於規格中一次,並在 CI 中執行。examples/loyalty-tier/src/oracle.js 同時實現了這兩種功能。

規格參考

鍵形狀備註
title, subtitle, source字串source 會顯示在頁尾;與規格中的所有文字一樣,它們以文字形式顯示,絕不會作為 HTML 讀取
langen(預設)或 fr頁面自身文字的語言;規格的文字以該語言編寫
kinds{id: {label, color}}最多 4 個
nodes[{id, label, role?, kind?}]role: "decision" 標記一個分支點;路徑的起點會被找到並繪製成圓形;匯集節點需要 kind
edges[[from, to, label]]如果沒有標籤則使用 ""
panel[{label, value, at, labels?, digits?, compared?}]value 讀取 inputs.x 或 verdict.y;從步驟 at 開始顯示(0 是第一步);labels 將值對應到頁面顯示的內容(分別為 "true"、"false"、"null"、"[]");digits 將數值代碼零填充到該長度;compared: true 用於命名配對比較內容(修復、規則)的那一行,該行不參與首次分歧搜尋
scenarios[{id, tab, summary, origin, inputs, expect, steps, undecided?, caseName?}]origin: `{kind: real
pairs[{before, after, tab, summary}]兩個情境 ID,以 − 和 + 的形式並排播放;步驟數相同
grid`{baseline, questionsvariants, cases, steps, expect?, show?, hover, summary?}`
oracle{repo, ref, paths, link?, files?, cwd, cmd}見上文
port導出 decide(inputs) 的 CommonJS 檔案路徑當沒有 oracle 時使用
export{dir, fixture, assert}--export <worktree> 將 fixture 寫入那裡

比較多個規則:網格

當問題是「每個可能的答案對每個案例做了什麼」時,宣告一個 grid。相對於扁平規則列表,問題更受青睞:讀者一個問題一個問題地決定,因此頁面應該以此方式佈局。

  • baseline: {id, label, short?, inputs},當前的狀況;
  • questions: [{id, text, options: [{id, label, inputs}], cases, if?}]。 cases 列出該問題所決定的案例;if: {"Q1": "1A"} 表示僅在該答案之後才提出此問題。build.py 會為每個一致的答案集(1A+2A、1A+2B、1B)推導出一個變體,合併選項的 inputs;
  • cases: [{id, label, summary, origin, inputs, steps?}];label 用讀者知道的詞語命名行,而不是案例代碼;
  • steps: 所有儲存格共用,除非某個案例有自己的步驟;
  • expect: {case: {variant: {field: value}}},由 C3 檢查;
  • show: 矩陣儲存格顯示的單一面板行(預設為 hover 中的第一個);hover: 儲存格在懸停時顯示的行;
  • summary: 矩陣上方的一行文字。

一個扁平的 variants: [{id, label, short?, note?, inputs}] 搭配 baseline 作為 id 仍然有效:矩陣隨後只有一個區段,每個案例與每個變體比較。

頁面開啟在矩陣上:每個問題一個表格,其案例與當前狀況和每個答案進行比較,儲存格的行在與當前狀況不同時標記為 ≠。沒有每個案例的分頁:點擊儲存格會開啟它,顯示當前狀況與該答案的比較,並標記首次分歧。兩個按鈕行 − 和 +,用於在該區段的答案之間選擇任一側(1A 旁邊是 1B,而不僅僅是在當前狀況旁邊),每個按鈕以其問題名稱命名;← matrix 返回。在面板中,一個帶有 "value": "answer" 和 "compared": true 的行會命名所播放的答案。

步驟範本。 message、caption 和 hop 可以引用 {inputs.x} 或 {verdict.y}:它們在邏輯執行後被填充,格式與讀取相同路徑的面板行相同。跳轉到 {verdict.outcome} 可以讓一個步驟列表服務於每個規則。

檢查

ID拒絕情況
C1步驟的 hop 不是一條邊
C2路徑中斷、不是從源節點開始或沒有步驟
C3expect 欄位與邏輯矛盾
C4路徑結束在邏輯的 outcome 之外,或邏輯沒有給出 outcome
C5outcome 沒有 kind、kind 沒有圖例、超過 4 個 kind
C6標籤寬度超出其框(13px monospace)
C7情境沒有 origin 來說明是 real 還是 illustrative,以及來自何處
C8配對的情境無法一起進行,或未知
C9面板行讀取了情境缺少的欄位
C10矩陣儲存格命名的面板行不存在
C11顯示在問題下的案例,其儲存格仍依賴於另一個問題
C12案例不在任何矩陣區段中,或區段命名了未知案例
C13面板行設定在情境沒有的步驟出現

C3 和 C4 是重點:一個說程式碼不會做的事情的情境無法發布。C6 保護的是佈局而不是規格:框的大小是根據其標籤調整的,因此只有在 layout.py 停止這樣做時才會觸發。透過在 tests/ 中破壞一次其輸入來證明新檢查的有效性。每個檢查都是 build.py 中的一個函式,列在 CHECKS 下,使用此表格中的 ID。

建置無法讀取的規格(缺少鍵、邊連接到未知節點、port 拋出異常)會以相同方式拒絕,使用簡單明瞭的文字,在檢查執行之前。

設計規則

  • 每個圖表只有一個移動元素:一個單一的點,恆定速度,一次移動一個 hop。
  • 並排的兩個圖表同步移動。
  • 已走過的邊緣是實線,未走過的邊緣是虛線和灰色;路徑外的節點淡出。
  • 顏色僅編碼結果的 kind。在配對中,首次分歧(面板值不同的第一步)以琥珀色輪廓標記,並在兩側標記 ≠,面板顯示 − / + 列。
  • 僅在沒有實際案例達到該結果時使用說明性情境;說明實際案例的來源(工單、記錄、度量、日期)。
  • 網格每個儲存格顯示一個欄位;每個儲存格三個欄位使矩陣難以閱讀。
  • 預設為淺色主題,在 prefers-color-scheme 下為深色;無網路字型,因此檔案可以離線工作。

檔案

路徑角色
scripts/build.py讀取規格、獲取判決、執行檢查、寫入頁面和匯出
scripts/runtime.html頁面;build.py 將要顯示的內容(已格式化)提供給它,而不提供規格的任何其他內容
scripts/layout.py分層佈局:框的大小根據其標籤調整,正交邊緣
examples/refund-window/一個 JS port 和一個之前/之後配對
examples/free-shipping/一個網格:兩個開放性問題,每個問題根據其變更的案例進行決定
examples/loyalty-tier/一個資料夾自身 src/ 的 oracle、其 glue 以及 --export 寫入的 fixture

生成的檔案(.truepath/,其中存放 oracle 的快照,以及規格旁邊的 *.html)是建置輸出。port 範例保留其 sim.html,以便無需執行即可查看技能。loyalty-tier 不保留任何內容:其頁尾顯示產生判決的提交名稱,因此頁面會隨每次提交而變化,並且它只在包含它的 git 儲存庫內建置。

限制

  • 一種圖表類型:流程圖。未建置序列圖和架構圖。
  • C6 在 macOS(ui-monospace)上測量;較窄的 Windows 字型只會增加間距。
  • 步驟是宣告的,而不是從邏輯推導出來的:C3 和 C4 捕獲錯誤的結果,而不是錯誤的中間訊息。

相關技能