Tekton — 共享架構意圖基底

Tekton — 透過一個共享模型共同設計架構

它是什麼

一個用於人類↔AI 代理架構夥伴關係的基底。設計存在於一個我們雙方都能編輯的 YAML 模型中；git 是來回傳遞的媒介。你看到它（HTML 檢視器）；我讀取和寫入相同的模型。我們在同一個脈絡下思考。

它修復的失敗：手寫的 HTML/SVG 文件是一個末端渲染 — 你無法向後追溯、查詢或編輯它，而且它的圖表不帶有任何意義。Tekton 將即時模型置於渲染結果的上游。

引擎

scripts/tekton.py（Python 3，pyyaml）。本體論在 references/ontology.md。

python3 scripts/tekton.py validate <model.arch.yaml>       # 完整性檢查
python3 scripts/tekton.py lint     <model.arch.yaml>       # v0.2 — 適應性函數；違反時 exit 1
python3 scripts/tekton.py stats    <model.arch.yaml>       # 節點/邊緣/狀態/規則計數
python3 scripts/tekton.py views                            # 列出 6 個視圖
python3 scripts/tekton.py mermaid  <model.arch.yaml> <view># 原始 mermaid（嵌入/供代理閱讀）
python3 scripts/tekton.py render   <model.arch.yaml> [-o out.html]  # 品牌化 HTML 檢視器
python3 scripts/tekton.py query    <model.arch.yaml> <from> <to>    # 跨層路徑

v0.2 本體論升級（來自架構審查）

• 包含關係 — 任何節點上的 parent: 加上 boundary 類型；檢視器渲染嵌套群組，雙擊可折疊/展開（C4 風格鑽取）。
• 生命週期 — 節點上的 status:（current|target|deprecated；target 渲染為虛線 = 在一個模型中同時呈現現狀與目標狀態）以及決策上的完整 Nygard ADR 欄位（context、consequences、status、supersedes）。
• 品質 — qualities: 區塊；NFRs constrains 元素；在詳細資訊面板 + 專用視圖中呈現。
• 適應性函數 — rules: 區塊（forbid-dep、no-cycle、layer-order）；tekton lint 是 CI 可關卡化的（exit 1）。設計循環的獨立驗證器。

AI 代理在設計工作階段中如何使用它

1. 定位/建立 模型：<project>/docs/design/<name>.arch.yaml（或使用 examples/ 進行草稿）。
2. 隨著我們思考而變異 — 隨著對話揭示元件、流程、資料、基礎設施和 ADR，直接在 YAML 中新增/調整節點、邊緣和決策。
3. 每次實質性編輯後執行 validate + lint（懸空引用、錯誤類型、適應性規則）。
4. render，然後 — 在認定檢視器正確之前 — 執行幾何審計：bash tests/visual-audit.sh <model.arch.yaml>。它會以無頭模式渲染每個視圖，並在節點重疊或空白擷取時失敗。未經此步驟就宣稱「圖表是正確的」正是第一次內部測試所發現的確切失敗（群組內邊緣斷開、節點重複 — DOM 計數探針無法發現，只有幾何審計能抓到）。在 URL 中使用 #<view> 進行深層連結。
5. query 來回答可追溯性問題（「這會觸及什麼？」）而非猜測。
6. 引導 → 重複。 人類編輯 YAML 或檢視器意圖；git diff 是交接點。

已知的外觀殘留問題（非審計失敗）：旅程迴圈邊緣會迫使 ELK 在任意步驟處中斷循環（迴圈必須在某處中斷）；相鄰平行邊緣的標籤在密集群組中可能靠得很近。

慣例

• 模型檔案：*.arch.yaml。渲染後的檢視器：*.view.html（可加入 gitignore 或提交 — 由你決定）。
• 每個有界系統一個模型；使用 external 節點加上 uses 邊緣來連結系統。
• 決策（ADRs）是一等公民節點 — 將它們固定到它們所管轄的對象。
• 類別 C 的 HTML 報告成為模型的下游匯出，而非真相來源。

渲染 — 為何不是 Mermaid

主要檢視器是一個自訂渲染器，不是 Mermaid。Mermaid 的主題天花板無法表達 Broomva 設計系統（OKLCH 藍色軸、霧面卡片、有代價的玻璃效果、彗星光暈），而且其 dagre 佈局在密集圖表上會退化。取而代之的是：elkjs 在瀏覽器中計算佈局（純 JS → 輸出保持為一個獨立的 HTML 檔案），節點繪製為 Broomva 霧面卡片（玻璃效果保留給浮動詳細資訊面板，遵循設計系統中「玻璃效果是有代價的」規則）。設計記號從 Broomva 設計系統內嵌。tekton mermaid 僅保留作為一次性的嵌入/可供 AI 代理閱讀的目標。

路線圖（v0 → v2）

• v0.2（現在）： YAML 模型 · validate + lint（適應性函數）· 6 個視圖 · 品牌化 elkjs 檢視器（包含關係折疊/展開、現狀/目標狀態、點擊追蹤、玻璃效果詳細資訊面板）· 跨層查詢 · Mermaid 備援嵌入。
• v1： 雙向來回（在檢視器中拖曳/編輯 → 序列化回 YAML）；MCP 伺服器（驗證過的變異，使 AI 代理無法輸出無效模型）；為 React-Flow 互動式畫布取得完整 Broomva 設計系統。
• v2： CRDT（loro）即時人類↔AI 代理共同編輯；即時同步到 Prosopon 作為一個表面。

狀態

v0 內部測試 — 內部設計工具。一旦設計循環在 ≥3 個真實系統上使用過（三法則），將進行技能化（已測試 + 已註冊）。