前言¶

在 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