Architecture Viewer

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 泛审查——不审查代码风格、性能、安全漏洞；只做可复核的结构事实：本轮改了哪些实体、有没有跨层违规、波及谁。

与其他工具的关系

差异化假设（待验证）：①接入成本低于竞品组合；②只报本轮相关、噪音低；③每条结论附路径/依赖链/规则，可人工复核；④原生在 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）

npx arch-viewer setup              # 用户级 MCP
npx arch-viewer setup . --project  # 本仓 hooks + 跨宿主规则（停手时自动跑结构门）
npx arch-viewer uninstall .        # 对称卸载本仓接入（其它 MCP 不动）
# 连全局包一起卸：npx arch-viewer uninstall . --npm
# 再清会话报告/快照（仍保留 .av/layers.json）：加 --purge

自动检测已安装的 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）

npx arch-viewer session report     # 对照 git HEAD（无 git 时用快照基线）
npx arch-viewer session guard --adapter generic   # hooks / CI 通用结构门

日常不必 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 只更新原评论，不刷屏：

# .github/workflows/architecture-diff.yml
name: Architecture Diff
on:
  pull_request:
    types: [opened, synchronize, reopened]
permissions:
  contents: read
  pull-requests: write
jobs:
  impact-comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Checkout PR base
        run: git worktree add --detach /tmp/av-base "${{ github.event.pull_request.base.sha }}"
      - name: Post architecture impact comment
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx --yes arch-viewer@latest pr-comment /tmp/av-base . --post

评论内容：变更计数表、新增/移除第三方依赖清单、🔴🟠 风险发现、影响面 Top N（反向依赖）。 本仓 dogfood 工作流见 .github/workflows/architecture-diff.yml。

---

Install

npm i -g arch-viewer        # CLI 全局安装
# 或免安装直接用：npx arch-viewer <command>

要求 Node.js ≥ 18。支持语言：JavaScript / TypeScript（含 Vue、Svelte）、Python、Go、Java （tree-sitter 解析，内置六平台 prebuild，安装无需编译）。

Quick Start（30 秒）

最省事的方式（推荐）——装一次，之后只说话：

npx arch-viewer setup
# 本仓要强制停手检查：npx arch-viewer setup . --project

然后对 AI 说：「改完用架构门检查一下」。把对话里的 verdict（最多 3 行）当验收： 绿灯 → git commit（即接受）；红灯 → 先修或解释，可用 av_explain_finding。

无 MCP 时用 CLI：

npx arch-viewer session report .       # 对照 HEAD；加 --open 才打开对比图

不懂技术术语？ 基线 = 对照物（有 git 就是 HEAD）。verdict = 对话里那几行灯。红灯 = 可能改坏了，绿灯 = 结构上没问题。详见 Quickstart 术语速查。

其他常用命令：

arch-viewer extract <repo> --out graph.json      # 导出代码结构图谱
arch-viewer diff <base-dir> <head-dir> --json    # 结构 diff（JSON）
arch-viewer impact <base-dir> <head-dir>         # 影响面文本报告
arch-viewer pr-comment <base-dir> <head-dir>     # PR 评论 Markdown（--post 直接发）
arch-viewer workspace ...                         # 多仓基线管理
arch-viewer auth login [email]                    # 邮箱验证码登录（Pro 账号）
arch-viewer auth whoami                           # 查看当前登录邮箱与 Pro 状态

---

风险分级与影响面怎么算

• 风险发现（lib/risk-rules.js）：跨层依赖违规、层级穿透（controller 直连 storage）、 类型删除（按下游数量升降级）、新增外部依赖、高扇出变更、孤儿新实体。
• 影响面（lib/impact.js）：从被改实体出发，沿 import/extends/implements/calls 等 wiring 边反向 BFS（base 与 head 反向边取并集，穿透被改实体集群）， 报告集群边界之外的直接/间接受害者。归属关系边（declared-in）不参与。

分层识别：零配置，也可锁定

跨层违规检测依赖「每个文件属于哪一层」。0.9 起分层由四个信号交叉推断， 不需要手写配置：

1. .av/layers.json 用户配置（最高优先）——{ "目录名": "分层名" }；
2. import 框架语义——import 了 sqlalchemy/gorm/JpaRepository → storage， flask/express/gin/@RestController → controller，@Entity → domain 等；
3. 目录名/文件名约定——services/、*Controller.java、data_collection/ 等；
4. 结构位置兜底——被很多模块依赖且自己不依赖别人 → domain，只出不进 → controller。

每次 session report / extract 后，推断结果会写入 .av/layers.suggested.json （按目录聚合，含置信度和判定依据；import 信号与目录名冲突的文件会单列）。 审阅没问题就不用管；想锁定或纠正，复制为 .av/layers.json 即可——它永远优先、 不会被覆盖。实测 246 文件的 Python 爬虫仓分层覆盖率从 57% 提升到 92%。

经典能力：PR 漂移红灯

新模块 / 服务 / 入口没画进六视图时 CI 失败，坏图进不了主干。 （粒度是目录与部署单元，不是每一个新文件；文件级变化看 session report。）

npx arch-viewer init .
npx arch-viewer generate .
npx arch-viewer check architecture_viewer --filled --drift --repo .   # 漂移即 exit ≠ 0
npx arch-viewer check . --rules architecture-rules.example.yaml       # 团队制图规范（命名 / 跨层 / Rel 白名单）

CI 模板：

• 漂移红灯：.github/workflows/architecture-check.yml
• 漂移 + 规范 + PR 评论：.github/workflows/architecture-drift.yml（Gitee 等价见 .gitee/workflows/）

规则写法见 architecture-rules.example.yaml：复制为仓库根或套件目录的 architecture-rules.yaml 即可；check 未传 --rules 时会自动读取该文件。

网页版（分享 / 评审）

npm run web    # http://127.0.0.1:3847 — 粘贴仓库 URL 生成六视图，/p/<id> 内联分享

新叙事落地页：docs/demos/landing-new.html（浏览器直接打开）。 新手跟做：小白图文攻略 · Quickstart §10（npm run demo:beginner）。

---

目录

├── lib/                              # 扫描 / diff / 影响面 / 风险规则 / 报告 / 遥测（CLI · MCP · Web 共用）
│   └── pro/                          # Pro 核心：账号 / 权益 / 存储 / CLI auth client
├── src/extension*.js                 # VS Code 扩展：会话命令 + 状态栏 + Webview（暂缓）
├── scripts/build-vsix.js             # 扩展打包 vsce（暂缓）
├── scripts/pr-comment.js             # CI 评论入口（架构 diff）
├── scripts/ci-drift-action.mjs       # CI：漂移 / 规范检查 + PR 评论
├── architecture-rules.example.yaml   # 团队制图规范示例
├── web/                              # 落地页 + API + /p/<id> 分享页 + Pro 路由
├── .github/workflows/                # check 红灯 + diff 评论 + drift 规范评论
├── .gitee/workflows/                 # Gitee 等价 drift pipeline
├── templates/                        # 可复制的套件与 CI 模板
├── docs/                             # 文档（见 docs/README.md：guides / demos / commercial / plans …）
└── eval/                             # 多语言解析夹具与评测

Pro 账号

arch-viewer auth login you@example.com    # 输入邮箱，收到 6 位验证码，输入后登录
arch-viewer auth whoami                  # 查看当前登录邮箱与 Pro 状态
arch-viewer auth logout                  # 退出登录
arch-viewer pro refine                   # 云端精修（需登录；未登录会提示升级 + 定价页）
arch-viewer pro sync                     # 增量同步占位（同上）

首次登录自动建档为 7 天 Pro 试用。token 存于 ~/.config/arch-viewer/auth.json（权限 0600）， 重启终端仍登录。generate / check / session / --refine（自带 Key）属 Community，永不要求登录。详见 lib/pro/README.md、COMMERCIAL.md。

隐私与遥测

CLI 遥测默认关闭，企业友好。开启方式：

export ARCH_TELEMETRY=1    # 开启
# 或设 DO_NOT_TRACK=1 永久关闭（优先级最高）

开启后仅记录：事件名（CLI 命令名）、耗时（毫秒）、退出码、CLI 版本、操作系统类型。 不记录：文件路径、代码内容、仓库名/URL、用户邮箱。数据落本地 ~/.config/arch-viewer/telemetry.log（JSONL），可随时查看或删除。

定价摘要（验证期定价）

以下数字均为验证期定价，未经付费数据支撑。详见 COMMERCIAL.md。