前言¶

在 DSH 裏讓智能體畫硬件架構圖，常見問題是「圖看起來專業，卻和源碼對不上」：模塊名拼錯、連線不存在、行號對不上，肉眼很難逐條覈對。手工從 Verilog/SystemVerilog 整理層級關係又費時，且文檔一旦脫離源碼就容易過期。

ArchiLens（npm 包名 hw-topo-dsh，核心技能 hw-topo）把思路從「憑記憶畫」改成「從源碼機械轉錄」：掃描 RTL 生成拓撲，圖中節點與連線強制攜帶 file:line 證據；交付前對源碼樹重新掃描逐項複覈，幻覺率非零則機器拒交（退出碼 1）。默認對接 RTLens 的 rtlens.evidence/1 證據後端，無 npm 運行時依賴，scan / verify / deliver 可完全離線。維護者爲 Kylanfang，分類爲工作流；社區目錄見 SkillHub ArchiLens 頁，源碼在 GitHub Kylanfang/ArchiLens（當前公開星標爲 0）。

這是什麼¶

ArchiLens 是面向 DeepSeek Harness（DSH）的硬件拓撲圖插件：面向 Verilog/SystemVerilog，產出帶源碼證據的模塊拓撲 SVG，並配套交互 HTML、wiki 索引與機器可讀回執。項目基於 @tt-a1i/archify-dsh@0.1.0 的 DSH 打包形態改造，將通用圖表能力替換爲「證據優先 + 自檢門禁」流水線；與 RTLens 分工見下文——RTLens 管事實與信號級分析，本插件管拓撲交付物與 verify 門禁。

核心功能¶

證據掃描與規格派生¶

• scan：默認後端 auto——可用 RTLens（peer 依賴 rtlens-dsh ≥ 6.2.0，可選）時走 rtlens.evidence/1；不可用時降級內置容錯正則掃描器，並在回執、HTML 橫幅、wiki 頁眉標註 degraded。
• derive：從證據包機械轉錄拓撲規格（模塊、例化、連線）；支持 --focus <頂層模塊> 只畫子樹，--no-groups 關閉按目錄分組。

反幻覺門禁與四件套交付¶

• verify：不信任舊證據包，對 RTL 樹重新掃描，逐元素判定 backed / disclosed / unbacked / broken，計算 hallucinationRisk；分子爲 unbacked + broken，非零則 exit 1。
• deliver：產出 <前綴>.html（交互查看器）、<前綴>.svg、<前綴>.wiki.md（帶 file:line 的代碼庫索引）、<前綴>.receipt.json（回執與工件 SHA-256）。

可選能力¶

• GitHub 直達成圖：search 與 gh 子命令通過 tarball 取源碼（記錄 commit SHA，帶路徑穿越防護），SVG 節點可鏈到 GitHub blob 永久鏈接；僅這兩類命令需要網絡。
• 雙引擎交叉覈對：--cross-check 用另一引擎見證、只比行號；--cross-check-strict 下座標衝突可導致 verify 失敗。
• DSH 集成：cordis.patch.yml 註冊 filesystem Skill provider，npm install 時 prepare 暫存技能到 skills/。

當前版本（資料中的 package.json）：0.3.0，許可證 MIT，需 Node ≥ 18。

安裝與啓用¶

插件以當前 dsh 進程權限運行；安裝前應自行查看倉庫源碼與 LICENSE，確認符合團隊合規要求。下列命令摘自項目 README，勿自行改寫倉庫路徑佔位符。

方式一：Git 倉庫

# <owner> 換成實際用戶/組織名（維護者倉庫爲 Kylanfang/ArchiLens 時按 README 佔位說明替換）
dsh plugin add github:<owner>/archify-dsh --profile <profile 名>

方式二：npm pack 產物

npm pack
dsh plugin add ./hw-topo-dsh-<版本>.tgz --profile <profile 名>

方式三：本地目錄（README 含 clone 與 install 步驟，此處略述路徑裝法）

在倉庫根目錄執行 npm install（觸發 prepare，無運行時依賴）後：

dsh plugin add <archify-dsh 路徑> --profile <profile 名>

裝完可做約 30 秒自檢（技能 CLI 位於 profile 的 node_modules）：

node <profile>/node_modules/hw-topo-dsh/skills/hw-topo/bin/hw-topo.mjs doctor --json
# 期望 {"ok": true ...}

典型用法¶

CLI 流水線¶

在倉庫內可直接調用 hw-topo/bin/hw-topo.mjs（安裝後路徑見上節）：

node hw-topo/bin/hw-topo.mjs demo <輸出目錄>
node hw-topo/bin/hw-topo.mjs scan  <RTL根目錄> --out topo.bundle.json --json
node hw-topo/bin/hw-topo.mjs derive topo.bundle.json --out topo.topology.json --title "<題>" --project <名> --json
node hw-topo/bin/hw-topo.mjs verify topo.topology.json --json
node hw-topo/bin/hw-topo.mjs deliver topo.topology.json --json
node hw-topo/bin/hw-topo.mjs validate topo.topology.json --json

scan 常用選項：--backend auto|rtlens|builtin（默認 auto）、--evidence <rtlens證據.json>、可重複的 -D NAME（+define+ 語義）、-I <目錄>（`include 搜索路徑）。完整參數以 node hw-topo/bin/hw-topo.mjs 無參 usage 爲準。

DSH 會話中調用技能¶

Use the hw-topo skill to map <RTL根目錄> 的模塊拓撲,生成可溯源的 SVG 與 wiki 索引。

從 GitHub 倉庫出圖（需網絡）¶

node hw-topo/bin/hw-topo.mjs search "riscv cpu" --limit 5 --json
node hw-topo/bin/hw-topo.mjs gh <owner/repo> --ref <分支|tag|sha> --focus <頂層> --json

未認證 GitHub API 限 60 次/小時；可設 GITHUB_TOKEN。無 RTL 的倉庫會 no-rtl 退出，不生成空圖。

工作流順序可記爲：scan → derive →（可選 curate）→ verify → deliver；verify 不過不得當作成功交付。

適用場景與注意¶

適合誰：需要在文檔或評審裏交付「與源碼綁死」的 RTL 模塊層級圖、又希望 agent 在 DSH 裏按技能走固定流水線的硬件/FPGA 團隊；已與或計劃安裝 RTLens 時，證據質量最佳。

與鄰接技能：例化關係、端口、信號驅動、影響面分析應交給 RTLens；RTL 拓撲 HTML/SVG/wiki/回執交給 ArchiLens；非 RTL 的通用架構圖、時序圖等仍屬上游 archify 範疇，本插件 description 顯式排除。

後端與行號：對外座標爲 1-based、根相對 POSIX；RTLens 適配在 evidence-adapter.mjs 一處換算。顯式 --backend rtlens 時不靜默降級。換後端會在回執打 backendOverride。

生態說明：DSH 主張「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

ArchiLens 的價值在於把拓撲圖變成可複覈的轉錄產物：每個元素可追溯至 file:line，交付前機器門禁攔截未背書內容。若你要在 profile 裏裝工作流類 RTL 拓撲插件，可從目錄頁與倉庫 README 對照安裝方式與 hw-topo 技能名。

• 目錄頁：https://www.skillhub.cn/plugins/Kylanfang/ArchiLens
• GitHub：https://github.com/Kylanfang/ArchiLens