tomyangod/architecture_viewer

**AI 写完代码后，查看结构变化与风险提示，由工程师确认后提交。**
> **本地版交付边界：** 本轮结构变更报告、可定位源码的结构总览，以及人工核实的风险提示。六视图降为兼容功能，不再是默认交付或卖点。绿灯不保证没有漏报；分析不完整不是通过。支持范围、离线模式与已知局限见随包交付的 首发交付范围。AI 精修、扩展、多仓和 SaaS 不在首发质量承诺内。
> **当前试点版：0.12.2-rc.7（npm 标签 next；latest 仍为 0.12.1）。** 接入请钉 arch-viewer@0.12.2-rc.7 或 @next，不要与工作区源码或 latest 混用。发布记录与源提交见 docs/commercial/npm-publish.md。这是有明确边界的本地试点候选，不是稳定商用版。
装一次 → 说话改代码 → 对话看灯 → git commit。
CLI / MCP / 网页 / PR 评论四端可用。免费开源（Apache-2.0），零配置、秒级出图，不依赖 LLM。
> **定位：AI 改码后的增量架构验收门，不是全量架构治理平台。**
能力边界（先说清楚不做什么）
- **不判断业务逻辑正确性**——不替代测试、类型检查、安全审查或人工 Code Review。
- **不做全量架构治理**——需要组织级架构看板、Git 历史热点、多仓聚合时看 Sonargraph / CodeScene。
- **不做 AI 泛审查**——不审查代码风格、性能、安全漏洞；只做可复核的结构事实：本轮改了哪些实体、有没有跨层违规、波及谁。
与其他工具的关系
| 工具 | 它做什么 | 和 AV 的关系 |
|------|---------|-------------|
| dependency-cruiser（开源） | JS/TS 架构规则、违规基线、--affected 影响范围 | **免费替代，部分重叠**——depcruise 已覆盖"本轮影响谁"的核心需求；AV 的差异在多语言、会话内 verdict、影响面 BFS |
| Import Linter（开源） | Python import 契约、CI 硬阻断 | **免费替代，部分重叠**——AV builtin 已吸收其契约评估能力 |
| Zügel（商业） | 面向 AI Agent 的 MCP 架构约束检查 | **直接竞品**——经 MCP 检查架构约束、识别依赖环 |
| CodeScene MCP（开源） | 本地代码健康分析、提交前检查、基线对比 | **直接竞品**——"本地 + MCP + 增量验收"组合并非 AV 独有 |
| CodeRabbit（商业） | AI PR 审查、Agent 工作流、MCP | **预算竞争**——争夺同一笔工具预算（~$24/开发者/月） |
| Sonargraph / CodeScene（商业） | 企业级全量架构治理、热点、质量门 | **重型替代/迁移目标**——团队长大、需要正式治理流程时迁移过去 |
> **差异化假设（待验证）**：①接入成本低于竞品组合；②只报本轮相关、噪音低；③每条结论附路径/依赖链/规则，可人工复核；④原生在 Agent 会话内出结论，不是又一个看板。
落地页（定价 / 60 秒成片 / 安装）：本地 npm run web → http://127.0.0.1:3847/ ；部署见 docs/commercial/landing-deploy.md。成片：docs/demos/demo.mp4。文档总索引：docs/README.md。
> **English**: README.en.md
> **新手入门**：不太懂术语？先看 小白图文攻略。
> 接到任意新项目：装一次、说话、看灯、commit → Quickstart。
>
> **实战文**：用 AI 自动生成架构图，还能在 PR 里抓漂移 · 60 秒 Demo 分镜
>
> 痛点：AI 编码会话一次改动几十个文件，**合入前没人说得清架构到底变了什么**——
> 删了哪个被广泛依赖的类型？有没有跨层调用？新引入了哪些第三方包？谁会被波及？
> Architecture Viewer 在会话结束时给出 Before/After 架构对比和风险分级，关键结论需对照源码核实。
---
四种用法
1. 一键接入 AI 工具（推荐 · Cursor / Claude / DeepSeek）
自动检测已安装的 AI 编程工具（Cursor、Claude、DeepSeek Harness），写入 MCP。
之后对 AI 说「改完用架构门检查一下」即可。Agent 应调用 av_guard；对话里回最多 3 行 verdict。
有 git 时对照 **HEAD**，**commit 即接受**当前结构。不必先拍照、不必默认打开 HTML。
升级：先 uninstall（需要时 --npm），再装新版本后 setup / setup . --project。
2. CLI 结构门（脚本 / CI / 无 MCP）
日常不必 session start。无 git 的仓，av_guard / session guard 会自动补快照。
完整 Before/After HTML（.av/session-report.html）是可选深挖。
高风险时退出码为 1。session report / check / diff 共用：0 通过 · 1 架构门未通过 · 2 参数配置错 · 3 扫描解析失败 · 4 基线不存在或失效。详见 Quickstart §6.3。
拍照仪式（session start → 开 HTML → 再 session start）见 Quickstart 附录。
3. PR 自动评论（GitHub Actions）
每个 PR 自动贴一条架构影响面评论；同一 PR 重复 push 只更新原评论，不刷屏：
评论内容：变更计数表、新增/移除第三方依赖清单、🔴🟠 风险发现、影响面 Top N（反向依赖）。
本仓 dogfood 工作流见 .github/workflows/architecture-diff.yml。
---
Install
要求 Node.js ≥ 18。支持语言：JavaScript / TypeScript（含 Vue、Svelte）、Python、Go、Java
（tree-sitter 解析，内置六平台 prebuild，安装无需编译）。
Quick Start（30 秒）
**最省事的方式（推荐）**——装一次，之后只说话：
然后对 AI 说：「改完用架构门检查一下」。把对话里的 **verdict**（最多 3 行）当验收：
绿灯 → git commit（即接受）；红灯 → 先修或解释，可用 av_explain_finding。
**无 MCP 时用 CLI：**
> **不懂技术术语？** 基线 = 对照物（有 git 就是 HEAD）。verdict = 对话里那几行灯。红灯 = 可能改坏了，绿灯 = 结构上没问题。详见 Quickstart 术语速查。
其他常用命令：