xu-jin-cs/dsh-skills

ArchMap 架構測繪 Agent

終端原生 Agent，無 Web 介面。零參呼叫自動分流 full/lite，另支援增量需求影響面分析、sync 同步、diff 影響面等顯式模式。

安裝與依賴

首次使用前在本技能根目錄執行 pip3 install -r requirements.txt（詳見 README.md）。其中 sentence-transformers 為可選依賴，缺失時向量識別自動回退本地哈希向量化，功能可用、精度略降。

觸發方式

/archmap <專案路徑>                        # 零參自動分流（推薦）
/archmap <專案路徑> full | lite [備註]      # 強制模式兜底
/archmap <專案路徑> <需求文字>
/archmap <專案路徑> sync
/archmap <專案路徑> diff [修改內容備註]

範例：

/archmap /Users/xujin/projects/my-app
/archmap /Users/xujin/projects/my-app 新增用戶積分系統，涉及登入介面和角色表
/archmap /Users/xujin/projects/my-app sync

模式路由（零參自動分流，2026-08-12 新增）

零參呼叫 /archmap <專案路徑> 按基線存在與否全自動分流，無人工切換開關：

• 無基線（archmap/full_index.json 不存在）→ 自動執行 full 完整初始化
• 有基線 → 自動執行 lite 極簡增量（日常疊代預設，見模式 G）
• 特殊場景手動兜底：full / lite 顯式詞強制指定（大重構後 full 重新生成完整圖譜，無需刪基線目錄）

模式清單

模式 A：全量分析（只輸入專案路徑）

路徑是專案根目錄時：

1. 執行全量原始碼掃描
2. 按業務目錄拆分模組，多執行緒 Worker 解析
3. 母體聚合資產、標記共享 API/儲存、生成向量快取
4. 生成 Mermaid 文字圖表與 01~09 號 Markdown 報告
5. 結果原子寫入 <專案路徑>/archmap/
6. 輸出產物路徑和摘要

產物路徑：

<專案路徑>/archmap/
├── full_index.json          # 完整架構基線
├── vector_cache.json        # 模組向量快取
├── 01_執行摘要.md
├── 02_架構圖.md              # Mermaid 文字
├── 03_資料鏈路圖.md
├── 04_時序圖.md
├── 05_模組資產清單.md
├── 06_API資產清單.md
├── 07_儲存資產清單.md
├── 08_依賴矩陣.md
└── 09_粒度校驗報告.md

模式 B：增量影響面分析（專案路徑 + 需求文字）

輸入已有基線對應的專案路徑，並附加需求文字。本模式會在匹配需求前先同步原始碼中的實際變更，因此呼叫 /archmap <路徑> <需求> 即觸發復盤整合：

1. 讀取 <專案路徑>/archmap/ 下的 vector_cache.json、full_index.json、module_hashes.json
2. 對比當前原始碼與上次同步時的模組內容指紋（SHA256），識別已變更/新增的模組
3. 僅重新解析變更模組並合併回基線，未變更模組直接複用基線資料
4. 將需求文字向量化，與最新模組向量做餘弦相似度匹配
5. 區分高信賴/低信賴疑似模組，遞迴遍歷上下游依賴
6. 僅對需求命中的新增/修改模組啟動 Worker 解析，存量依賴模組直接複用基線資料，不呼叫 LLM
7. 對命中的模組做模組內精準定位：識別涉及檔案、函數/類別名、介面路由、路由→檔案映射，並按需求關鍵詞相關度排序
8. 召回補強（recall_engine）：向量命中基礎上，用兩類確定性訊號擴展受影響集合，不受向量閾值約束——① 路由供需閉包（受影響模組引用的路由→定義方模組，及其定義路由的引用方模組）② 需求路由關鍵詞硬匹配（需求詞含 CN→EN 擴展，直接命中模組 defined 路由）。輸出 match_sources 標註每個模組的命中來源（vector/keyword/route_closure/route_keyword）
9. 合併更新基線，生成 precise_analysis.json 影響面檔案 + precise_meta.json 預測元資料（需求文字、命中來源、基線哈希指紋）
10. 輸出受影響的模組、API、儲存、涉及檔案清單，指導精準開發

說明：復盤同步只在「已有基線 + 新需求」時觸發；首次全量分析新專案不會執行同步。

產物：基線資料夾內更新 full_index.json、vector_cache.json，並新增 precise_analysis.json：

[
  {
    "module_id": "src_users",
    "module_path": "src/users/",
    "files": [
      {
        "file_path": "api.py",
        "functions": ["list_users", "get_user"],
        "classes": [],
        "routes": ["/api/users", "/api/users/<id>"],
        "relevance": 0.6
      }
    ],
    "route_to_files": {
      "/api/users": ["api.py"],
      "/api/users/<id>": ["api.py"]
    },
    "keyword_matches": ["api.py"]
  }
]

模式 C：同步更新（專案路徑 + sync）

在專案已完成全量分析並進入持續開發後，新增程式碼需要被合併回既有基線，而不是重新執行全量分析。

觸發：

/archmap <專案路徑> sync
/archmap <專案路徑> 同步

執行流程：

1. 讀取 <專案路徑>/archmap/ 下的 full_index.json、vector_cache.json、module_hashes.json
2. 對比當前原始碼與上次同步時的模組內容指紋（SHA256）
3. 僅重新解析新增/修改的模組，已解析過的未變更模組直接複用基線資料，不呼叫 LLM
4. 從基線中移除已刪除的模組及其向量
5. 重新生成 Mermaid 圖表與 01~09 號 Markdown 報告
6. 原子更新 full_index.json、vector_cache.json、module_hashes.json 與報告檔案
7. 召回驗證（recall_engine）：若基線內存在上次影響面分析的預測檔案（precise_analysis.json + precise_meta.json），自動比對預測模組與本次實際變更模組：
   • 有變更 → 產出 recall_report.json（命中率、漏報模組及歸因：route_keyword_miss / closure_miss / vector_miss），追加 recall_history.jsonl，隨後消費預測檔案
   • 無變更 → 保留預測，待開發完成後下次同步再驗證
   • 基線哈希指紋不一致（預測屬於已結束的舊開發週期）→ 丟棄陳舊預測，不驗證

產物：基線資料夾內容全量重新整理，結構與模式 A 一致，但只消耗變更模組的解析成本。存在待驗證預測時新增 recall_report.json 與 recall_history.jsonl。

<專案路徑>/archmap/
├── full_index.json          # 已合併新增/修改模組
├── vector_cache.json        # 僅變更模組向量重新計算
├── module_hashes.json       # 最新模組內容指紋
├── 01_執行摘要.md
├── 02_架構圖.md
├── 03_資料鏈路圖.md
├── 04_時序圖.md
├── 05_模組資產清單.md
├── 06_API資產清單.md
├── 07_儲存資產清單.md
├── 08_依賴矩陣.md
└── 09_粒度校驗報告.md

典型使用節奏：

1. 首次：/archmap /path/to/project
2. 開發新功能並修改原始碼
3. 復盤同步：/archmap /path/to/project sync
4. 定位影響：/archmap /path/to/project 新增積分功能

模式 D：ETL 底層規則探查（自動觸發）

對含 ETL 特徵目錄的專案（tongue_diagnosis/etl / etl_config / etl/core 任一存在），全量分析與同步更新時自動生成 7 項 ETL 變更維護服務產出，寫入 <專案路徑>/archmap/etl_rules/：

#	產出	內容
①	ETL規則索引總目錄.md	7 分層目錄樹（預處理清洗→Chunk分片→向量化寫入→一致性對帳→隔離儲存→異常重試→ETL編排）+ 規則唯一編碼（ETL-CHUNK-01 等）+ 關鍵詞標籤 + 檢索快捷索引 + 7 步使用流程
②	details/ETL-{編碼}.md（每規則 1 份）	統一 7 章節：規則基礎識別 / 完整底層執行邏輯 / 原始碼精準定位 / 輸入輸出約束 / 關聯依賴規則 / 歷史改動記錄 / 測試校驗標準
③	etl_rule_mapping.json	ETL規則-程式碼-配置映射對照表（機器可讀）
④	ETL規則依賴鏈路圖.md	Mermaid 依賴圖 + 文字影響清單 + 影響分級（高/中/低）
⑤	ETL全域參數基線表.md	全部規則參數基線值 + 配置檔案來源
⑥	ETL規則變更風險評估清單.md	全部規則風險等級/描述/迴歸測試 + 變更前置動作
⑦	etl_rule_search_index.json	機器檢索索引（規則條目 + 關鍵詞快捷索引 keyword → 規則編碼）
⑧	ETL配置契約對齊報告.md + config_contract_report.json	配置-程式碼契約漂移檢測（定期對齊）：yaml 鍵實存 + read/use 特徵串 grep → aligned（已接線）/ unused（死配置）/ stale（程式碼殘留）/ missing_from_yaml（契約不一致）+ 處置建議

要點：

• 定期對齊（配置契約漂移）：改配置/改程式碼消費點後跑 /archmap <專案路徑> sync，⑧報告自動重新整理每欄位狀態（欄位存在 ≠ 生效：unused/stale 需按處置建議接線或清理）；已有基線漂移範例：RRF 權重未生效（rag_engine._rrf_fuse weights 寫死 1.0）、max_ctx_tokens 配置未接線、reconcile.enabled/batch_size 死配置、embedding.yaml batch_size 未消費
• 原始碼定位行號執行時按函數名/特徵串 grep 解析，改程式碼後 /archmap <專案路徑> sync 即重新整理全部行號與產出
• P0/P1/P2 解析深度分級（2026-08-12 二期）：risk_level 高→P0 深度解析（行號+配置+契約）、中→P1 標準解析（行號）、低→P2 輕量解析（僅檔案存在性校驗，行號跳解析且不計入 unresolved 口徑）；詳情文件頭部/索引總目錄/mapping JSON/search_index JSON 均攜帶 priority 識別，summary 含 priority_counts 與 parse_depth 統計；單條規則可在 etl_rule_registry.py 顯式寫 priority 欄位覆蓋推導
• 回填約定（修改 ETL 規則/步驟/配置後必須執行）：/archmap <專案路徑> sync 自動回填三方面——① 行號（grep 即時解析）；② 參數基線（etl.yaml/embedding.yaml/chunking.yaml 執行時讀取，③⑤⑦ 中對應規則參數自動重新整理為配置檔案當前值）；③ 語義級變更（規則改名/行為變更/風險等級調整）在 etl_rule_registry.py 追加 history 記錄後重跑 sync 重新生成。不執行 sync 則文件與程式碼/配置漂移
• 檢索入口：讀 etl_rules/etl_rule_search_index.json（機器）或索引總目錄關鍵詞表（人工）
• 詳情文件含測試校驗標準章節，改完規則按對應用例迴歸
• 自訂 ETL 規則註冊表覆蓋機制見 README.md「專案級配置」一節

模式 E：測試設計輸入資產（Test Design Input Assets）

ArchMap 全量分析產出的架構圖、資料鏈路圖、時序圖、資產清單、依賴矩陣，可直接作為 test-case-designer 的輸入，驅動「節點 + 分支 + 方法」三要素測試設計。

可被測試設計消費的產物

產物檔案	測試設計用途	提取內容
02_架構圖.md	識別系統分層與模組邊界	分層節點（Trigger/Definition/Persistence/Engine/Validation）
03_資料鏈路圖.md	識別端到端資料流	資料流節點、輸入輸出、持久化落點
04_時序圖.md	識別呼叫順序與並發/等待關係	呼叫時序、同步/非同步邊界、異常返回點
05_模組資產清單.md	識別功能模組與職責	模組名、核心函數、職責描述
06_API資產清單.md	識別介面測試節點	路由、方法、參數、返回結構、錯誤碼
07_儲存資產清單.md	識別資料持久化測試點	儲存類型、欄位、約束、生命週期
08_依賴矩陣.md	識別變更影響面與迴歸範圍	模組間呼叫關係、共享 API/儲存
precise_analysis.json	增量需求時精準定位測試範圍	變更模組、涉及檔案、函數/路由、相關度

測試設計輸入標準格式

test-case-designer 讀取上述產物後，必須將資訊歸約為以下標準結構（作為設計中間產物隨 execution-list.json 一併提交審核，不作為 archmap 產物檔案落地——archmap 引擎產物僅 01~09）：

## 測試節點清單（Node Inventory）

| 節點編號 | 節點名稱 | 所在模組 | 功能/作用 | 輸入 | 輸出 | 持久化 |
|----------|----------|----------|-----------|------|------|--------|
| N-001 | create_workflow_endpoint | webui.py | 透過 Web UI 建立新工作流 | {name, mode} | flow.yml / SKILL.md / 目錄 | 新建目錄樹 |
| N-002 | validate_flow_structure | workflow.py | 校驗 flow.yml 結構合法性 | flow_data | 錯誤列表或空列表 | 無 |
| N-003 | gate_a_check | engine.py | 執行前准入校驗 | agent, state | passed/errors/log | engine_state.json |

## 分支閉環清單（Branch Closure）

| 源節點 | 分支條件 | 真分支 | 假分支 | 非法輸入 | 狀態不一致 |
|--------|----------|--------|--------|----------|------------|
| N-001 | name 是否為空 | 繼續建立 | 返回 400 | 超長/特殊字元 | 父目錄未設定 |
| N-003 | upstream 是否全部完成 | 進入 Gate B | blocked | 未知節點 | 交付物哈希被篡改 |

## 測試方法映射（Method Mapping）

| 節點 | 邊界值(BV) | 等價類(EC) | 需求邏輯(DL) | 場景(SC) | 異常(EX) | 相容(CP) | 介面安全(IS) |
|------|------------|------------|--------------|----------|----------|----------|--------------|
| N-001 | 名稱長度邊界 | 有效/無效名稱 | 建立→生成→返回 | 正常建立流程 | 父目錄缺失 | — | 路徑穿越/特殊字元 |
| N-003 | max_retry 邊界 | 上游完成/未完成 | Gate A→執行→Gate B | 正常推進 | 哈希不匹配 | 有/無 jsonschema | — |

增量場景下的消費方式

當 PM 給出新增需求時：

1. 呼叫 /archmap <專案路徑> "需求文字" 生成/更新 precise_analysis.json。
2. test-case-designer 優先讀取 precise_analysis.json 中的變更模組與涉及檔案。
3. 僅對變更模組及其直接依賴模組提取測試節點，避免全量重設計。
4. 在 execution-list.json 中標記 baseline_affected: true 的用例，用於精準迴歸。

與 test-case-designer 的對接契約

test-case-designer 具備自主分析能力，啟動後按以下邏輯處理：

1. 自主發現現有分析結果： 檢查 <專案路徑>/archmap/ 是否存在且包含有效的 02_架構圖.md 與 03_資料鏈路圖.md。
   • 若存在： 直接讀取 02~08 號產物 + precise_analysis.json（增量場景），作為測試設計輸入，避免重複分析。
   • 若不存在或已過期： 自行呼叫 /archmap <專案路徑>（全量）或 /archmap <專案路徑> "需求文字"（增量）生成分析結果，再讀取使用。PM 無需在測試前單獨呼叫 archmap。
2. 讀取 02_架構圖.md + 03_資料鏈路圖.md + 04_時序圖.md，識別系統級測試節點。
3. 讀取 05_模組資產清單.md + 06_API資產清單.md + 07_儲存資產清單.md，識別模組級測試節點。
4. 讀取 08_依賴矩陣.md，識別節點間依賴與影響面。
5. 輸出歸約後的節點/分支/方法清單作為設計中間產物（即規則 32 Step 1.8《測試節點與分支清單》），隨 execution-list.json 一併提交審核。

模式 F：diff 影響面分析（專案路徑 + diff，2026-08-12 新增）

版本更新後的差異化影響面分析，為白盒增量測試等下游提供權威 diff 輸入。git 無關（無倉庫專案可用），零 LLM 呼叫，秒級完成。

執行時機（固定卡點）：功能新增/修改完成後、復盤階段前必須執行一次。 本次變更（時間+修改內容+行區間+影響閉包）自動記入變更歷史，作為復盤的輸入材料；驗收通過後再用 sync 重新整理基線並回補 01~09 分析文件——diff 記錄、變更歷史、分析文件三者構成一個整體。

觸發：

/archmap <專案路徑> diff
/archmap <專案路徑> diff 本次給視訊加速功能增加非法參數校驗

執行流程：

1. 讀取基線目錄行級快照 file_line_hashes.json（full/sync 時自動寫入；首次 diff 無快照則初始化並提示下輪起可比對）
2. 逐檔案 difflib 比對當前行哈希與快照 → 輸出變更檔案的精確變更行區間（1-based，合併相鄰區間）。未變更檔案僅做哈希比對，不做任何重新分析
3. 依賴圖（含根目錄檔案，不依賴模組掃描粒度）三類邊：Python import（AST）、JS/TS/Vue import/require（正則+別名解析）、跨語言路由供需邊（路由定義×字面量引用，雙向）；快取走 file_imports.json + file_routes.json，僅變更/快取缺失檔案重新解析；新增或刪除檔案屬結構性變更，全量重解析一次防邊缺失。v2 起快照覆蓋 .py/.ts/.tsx/.js/.jsx/.vue/.sql/.yaml/.yml，v1 快照自動遷移
4. 從變更業務檔案出發沿反向導入邊 BFS → 影響閉包（變更檔案 + 全部傳遞依賴方）；測試檔案僅作匯點不傳播
5. 測試選擇：選中 = 閉包內測試檔案 ∪ 自身變更的測試檔案；標記 untested_changes（閉包內無任何測試的變更業務檔案）
6. 若專案根存在 coverage-tiers.json，按最長前綴匹配為每個變更檔案標註 tier
7. 產出 <專案路徑>/archmap/diff_impact.json；行級快照不在 diff 模式更新（保證同一工作期重複比對結果穩定），隨下次 full/sync 重新整理
8. 有變更時自動留痕：追加 diff_history.jsonl（機器可讀，含備註）並重渲染 10_變更歷史.md（時間+修改內容+變更檔案區間+閉包+測試選擇）；零變更執行不記錄

產物結構：

{
  "changed_files": [{"path": "ui/main_window.py", "change_type": "modified", "tier": "P2", "changed_ranges": [[169, 182]]}],
  "deleted_files": [],
  "affected_closure": {"files": ["..."], "changed": ["..."], "propagated": ["..."]},
  "test_selection": {"selected": ["tests/test_main_window.py"], "skipped": ["..."], "untested_changes": []},
  "stats": {"changed_files": 1, "changed_ranges": 1, "closure_files": 3, "tests_selected": 1, "tests_skipped": 7},
  "history_path": "<專案路徑>/archmap/diff_history.jsonl",
  "history_doc": "<專案路徑>/archmap/10_變更歷史.md"
}

下游消費：whitebox-coverage 增量模式以 diff_impact.json 為唯一範圍依據（選擇性執行 + --diff-scope 缺口過濾 + diff_gate 門禁）；復盤流程以 10_變更歷史.md 為變更台帳輸入。

模式 G：lite 極簡增量（零參呼叫且有基線時自動進入，或顯式 lite，2026-08-12 新增）

日常開發疊代的預設模式。與 sync 的差異：不重新生成 01~09 全量報告與架構大圖，只做變更閉環，秒級完成：

1. 行級快照比對檢測變更（與模式 F 同一引擎，git 無關）
2. 僅重解析變更模組並合併回基線（full_index / vector_cache / module_hashes / 行級快照 / 導入圖快取全部重新整理）
3. 有變更自動留痕：追加 diff_history.jsonl + 重渲染 10_變更歷史.md（可帶修改內容備註）
4. ETL 專案自動重新整理 etl_rules/ 產物；存在未驗證預測時照常做召回驗證
5. 產出/重新整理 diff_impact.json（含 direct_dependents 一級依賴摘要 + 全量傳遞閉包，機器讀全閉包不佔 Agent 上下文）

零變更時直接返回「無變更，無需更新」。01~09 報告需要反映最新程式碼時跑 sync 或 full。

底層呼叫

包裝腳本位置：

/Users/xujin/.agents/skills/archmap/archmap <專案路徑> [需求文字]

等價於：

# 全量
python3 /Users/xujin/.agents/skills/archmap/archmap /path/to/project

# 增量
python3 /Users/xujin/.agents/skills/archmap/archmap /path/to/project "新增用戶積分系統"

引擎套件 archmap_agent 已隨技能自包含分發（與包裝腳本同目錄），無需另外安裝引擎。

約束

• 不啟動任何 Web 服務。
• 不讀寫 SQLite 任務表。
• 所有狀態保存在專案路徑下的 archmap/ 資料夾內。
• 不修改使用者原始業務程式碼，僅做靜態原始碼分析。
• 全量模式只掃描業務目錄，自動過濾 test、node_modules、dist、build 等目錄。
• 增量模式複用存量基線資產，不重複解析未變更模組，顯著降低 Token 消耗。
• 輸出均為 JSON/YAML/Markdown/Mermaid 純文字，不生成圖片。