gwj001/arch-lens

Arch Lens · 架构学习台

EN：Arch Lens 是一个 DeepSeek Harness（DSH）扩展插件，它能把任何代码
仓库变成一个可学习的对象：在 8 个标签页中研究图示，将基于证据的问题
路由到你现有的聊天会话中——而会话历史就是
你的笔记本（问答、图示、追问，全都包含在内）。MIT 许可。中文文档如下。

一个把“读代码”变成“上课”的 DSH 插件：扫描 → 制图 → 讲解 → 会话即笔记 闭环。

Arch Lens 学习台总览

| 更多学习单元界面 | 更多学习单元界面 |
| :-: | :-: |
| 学习单元示例 | 学习单元示例 |

📖 使用者层

1. 你能得到什么

- 8 个学习 Tab：⚡ 动态总览 · 概念树 · 主流程时序 · 调用关系 · 流程图 · 交互 · 依赖 · ER · 目录。
- 每图带出处徽章：doc 仓库文档原文（权威）/ code 真实调用关系（权威）/ flow AI 归纳 /
curated 规则回退——哪句是抄的、哪句是猜的，一眼分清。
- 文档优先，不白花 token：仓库自带架构文档时，概念/流程/时序直接逐字提取原文，冷启动 0 次 LLM。
- 讲解不换窗口：点「🗣 AI 讲解」，Arch Lens 把带事实依据（职责、核心文件、真实调用边、图源）
的问题发进你当前会话；回答就留在会话历史里——会话记录就是笔记，问答与生成的图全都记得住
（原 ARCH-NOTES.md 笔记面板、📊 学习进度已下线，见 usage）。
- 一键出文档：📄 按钮按 7 章（目录/概念/依赖/时序/流程/ER/交互，认知主干顺序）逐章串行生成，每章只依据
代码事实写正文，先过“幻觉门禁”再落地 docs/architecture-.generated.md；已生成的章节
缓存复用，重复点击只补缺、重试失败章。
- 随问随画：hover 任意调用边/子图可下钻细节图；🎨 动态出图按你的问题现画一张（含讲解概要），
可保存锁定——保存的图是你的资产，重扫不丢。
- 不多花一分钱：结果全部缓存；重新扫描只更新受影响的部分，没变的图秒回、不重复计费。
- 用量透明：⚡ LLM 面板显示本工作区累计与最近明细（字符/估算/模型实际 token），重启不丢。
- 代码不出机器：扫描与解析全程本地离线，除你已配置的模型调用外无任何网络请求。

2. 安装启用（三步）

1. 克隆本仓库并按 开发者层 › 构建 打出全部包产物；
2. 在仓库根执行 scripts\link-arch-lens.ps1（Windows）或
pwsh scripts/link-arch-lens.ps1（macOS / Linux），把 arch-lens-backend、
client-arch-lens、code-index-tree-sitter 以 link: 依赖挂载进 DSH web
profile 的 node_modules（幂等，可重复执行；详见
scripts/scripts.md link-arch-lens 一节）；
3. 执行 scripts\toggle-arch-lens.ps1 -Mode on 写入启用行，再重启 DSH 主服务 +
浏览器硬刷新（Ctrl+F5），在 Web GUI 侧边栏唤出悬浮机器人 → 学习台。

随时停用 / 恢复

脚本只对 DSH profile 的 cordis.patch.yml 做追加 / 变更：缺 arch-lens 行才补、
已有则只翻转 disabled，文件里其它任何配置（mcp-browser 等）原样保留。

脚本命令与参数说明见 scripts/scripts.md（toggle-arch-lens 一节），

3. 界面速查

全局按钮（面板顶部）

| 按钮 | 含义 | LLM 消耗 |
|---|---|---|
| 提示词 | 编辑讲解/生成用的提示词套装（保存在工作区，跟随仓库） | 0 |
| ↻ 重新扫描 | 只重建事实：重扫代码图与索引，按变动包精确失效受影响的图缓存；不生成任何图 | 0 |
| ⚡ 变动更新 | 一条链 = 重新扫描 + 智能增量重绘：只补画失效/缺失的图；改完代码后的一键维护 | 仅失效的图 |
| 🔁 全量重建 | 不重扫，对全部图逐一校验缓存：失效/缺失的重绘、有效的跳过（“全量”指清点范围，不是无条件重绘） | 仅失效/缺失的图 |
| ⏹ 停止 | 立即中断所有进行中的 AI 生成 | — |
| 📄 一键生成文档 | 7 章串行生成（见上）；每章独立失败、独立重试，重复点击只补缺 | 缺失/失效的章 |

三颗扫描/重建按钮的完整用法（费用语义、中断、常见坑）见
usage.md「三个扫描 / 重建按钮」一节。

📊 学习进度按钮已下线（2026-09）：其数据源是已退役的笔记文件；会话记录本身就是
更完整的笔记。详见 usage.md。

图内交互

| 操作 | 含义 |
|---|---|
| 🤖 AI 生成（各 Tab） | 对当前图不满意？把重画请求发进会话，AI 读码后重画这张图，画完自动回填 |
| 🗣 AI 讲解 | 概念树节点、追问对话框、动态出图行都有——把“讲明白这个”发进会话，答案进笔记；讲解过的组件计入进度 |
| 🔬 方法级 | 时序/交互/流程图切到方法粒度：按真实方法与调用边重新归纳（独立生成，不影响实体级图） |
| hover 调用边 / 子图标题 | 浮出 🤖 动态画图——只对这一条边/这一块画细节图 |
| 右键节点/边/子图 | 把该元素的标签送进 🎨 出图输入框，改一改再问 |
| 💾 保存当前图 | 动态出的图连标题、讲解概要一起保存，图号锁定，重扫不失效 |
| ✏️ 追问重画 | 在对话框里对已生成的图追加要求（“把 XX 展开”“换成时序”），原图位置更新 |
每个 Tab 与交互的完整走读见 docs/usage.md。

🛠 开发者层

4. 构建与开发命令

环境要求：DeepSeek Harness（DSH）运行环境、
Node.js ^22.19 || >=24、pnpm 11（见 package.json 的 engines / packageManager）。

pnpm install

类型检查 + 全量测试
pnpm exec tsc -b tsconfig.json
pnpm exec vitest run --pool=threads

两面构建（产物 lib/ 随仓库提交，即部署载荷）
pnpm exec tsdown --config tsdown.config.ts                             # host 面
pnpm exec tsdown --config tsdown.config.ts --env.DSH_BUILD_FACE client # client 面

改动的生效方式：后端 = 重启 DSH 主服务（启动时快照加载）；前端 = 浏览器 Ctrl+F5。

依赖与版本对齐

- 编译期 @deepseek-ai/ 依赖来自 npm，统一锁定 0.1.2-rc.1 线（devDependencies /
peerDependencies 精确版本，升级 DSH 宿主时若上游有更新版本线需同步调整）；
- 运行时由宿主 DSH 提供：后端 bundle 把所有 @deepseek-ai/ external 化，npm 副本只
用于编译期类型；浏览器端 bundle 自包含内联；
- vendored dsh-typert-protocol 跟随宿主源码并保持版本号与 npm 线对齐（0.1.2-rc.1）：
升级宿主版本时需同步更新 vendored 的 src 与版本号，否则 pnpm 会为上游包的 peer 自动
拉一份 npm 副本（同一包名两套实现并存）；
- 全部 @deepseek-ai/* 均已 npm 化，无机器耦合路径（tsconfig.base.json 仅剩本地
workspace 包与 vendored 的映射）；typertPlugin 生成器来自 npm 包
@deepseek-ai/dsh-typert-generator/tsdown。

5. 仓库结构

| 包 | 位置 | 职责 |
|---|---|---|
| packages/arch-lens-backend | 宿主 | 扫描、图注册表与缓存、生成链、会话图生成、文档章节管线（含幻觉门禁） |
| packages/client-arch-lens | 浏览器 | 悬浮机器人、8 Tab 学习台、Mermaid/SVG 渲染 |
| packages/code-index-tree-sitter | 宿主 | tree-sitter 离线解析（TS / Python / Java） |
| packages/code-index | 宿主 | 代码索引能力缝契约 |
| packages/typert-protocol | 共享 | Typert Remote 协议（vendored，见许可致谢） |

6. 深入机制

| 文档 | 内容 |
|---|---|
| docs/arch-lens-overview.md | 包分工与关键机制（缓存 / 失效 / 写路径 / 组装） |
| docs/arch-lens-diagrams.md | 绘图机制全图解（逐节点标代码出处） |
| docs/architecture.generated.md | 旧组装链给本仓库生成的架构文档（历史产物示例；V1 章节管线产出 architecture-.generated.md） |

7. 贡献

Issues 与 Pull Requests 欢迎。请先阅读 CONTRIBUTING.md
与 CODE_OF_CONDUCT.md；变更记录见 CHANGELOG.md。

⚖️ 许可层

- 本项目以 MIT License 开源。
- packages/typert-protocol 为 deepseek-harness packages/typert/protocol 的 vendor 拷贝，
著作权归 deepseek-harness 项目所有，以同源 MIT 条款分发。
- 依赖 mermaid、tree-sitter 语法包等第三方 MIT 开源组件；安全漏洞报告见 SECURITY.md。