# Architecture Viewer

**AI 写完代码后，查看结构变化与风险提示，由工程师确认后提交。**

> **本地版交付边界：** 本轮结构变更报告、可定位源码的结构总览，以及人工核实的风险提示。六视图降为兼容功能，不再是默认交付或卖点。绿灯不保证没有漏报；分析不完整不是通过。支持范围、离线模式与已知局限见随包交付的 [首发交付范围](docs/delivery-scope.md)。AI 精修、扩展、多仓和 SaaS 不在首发质量承诺内。

> **当前试点版：`0.12.2-rc.3`（npm 标签 `next`；`latest` 仍为 `0.12.1`）。** 接入请钉 `arch-viewer@0.12.2-rc.3` 或 `@next`，不要与工作区源码或 `latest` 混用。源提交 `81e6c43`；发布记录见 [docs/commercial/npm-publish.md](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 会话内出结论，不是又一个看板。

![demo](docs/demos/demo.gif)

落地页（定价 / 60 秒成片 / 安装）：本地 `npm run web` → http://127.0.0.1:3847/ ；部署见 [docs/commercial/landing-deploy.md](docs/commercial/landing-deploy.md)。成片：[docs/demos/demo.mp4](docs/demos/demo.mp4)。文档总索引：[docs/README.md](docs/README.md)。

> **English**: [README.en.md](README.en.md)

> **新手入门**：不太懂术语？先看 [小白图文攻略](docs/guides/beginner-guide/index.html)。
> 接到任意新项目：装一次、说话、看灯、commit → [Quickstart](docs/guides/quickstart.md)。
>
> **实战文**：[用 AI 自动生成架构图，还能在 PR 里抓漂移](docs/demos/blog/2026-09-ai-architecture-drift.md) · [60 秒 Demo 分镜](docs/demos/demo-script.md)
>
> 痛点：AI 编码会话一次改动几十个文件，**合入前没人说得清架构到底变了什么**——
> 删了哪个被广泛依赖的类型？有没有跨层调用？新引入了哪些第三方包？谁会被波及？
> Architecture Viewer 在会话结束时给出 Before/After 架构对比和风险分级，关键结论需对照源码核实。

---

## 四种用法

### 1. 一键接入 AI 工具（推荐 · Cursor / Claude / DeepSeek）

```bash
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）

```bash
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](docs/guides/quickstart.md)。

拍照仪式（`session start` → 开 HTML → 再 `session start`）见 [Quickstart 附录](docs/guides/quickstart.md#附录a-拍照仪式高级)。

### 3. PR 自动评论（GitHub Actions）

每个 PR 自动贴一条架构影响面评论；同一 PR 重复 push 只更新原评论，不刷屏：

```yaml
# .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](.github/workflows/architecture-diff.yml)。

---

## Install

```bash
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 秒）

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

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

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

**无 MCP 时用 CLI：**

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

> **不懂技术术语？** 基线 = 对照物（有 git 就是 HEAD）。verdict = 对话里那几行灯。红灯 = 可能改坏了，绿灯 = 结构上没问题。详见 [Quickstart 术语速查](docs/guides/quickstart.md#术语速查)。

其他常用命令：

```bash
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`。）

```bash
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](.github/workflows/architecture-check.yml)
- 漂移 + 规范 + PR 评论：[.github/workflows/architecture-drift.yml](.github/workflows/architecture-drift.yml)（Gitee 等价见 `.gitee/workflows/`）

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

## 网页版（分享 / 评审）

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

新叙事落地页：[docs/demos/landing-new.html](docs/demos/landing-new.html)（浏览器直接打开）。
新手跟做：[小白图文攻略](docs/guides/beginner-guide/index.html) · [Quickstart §10](docs/guides/quickstart.md#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 账号

```bash
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](lib/pro/README.md)、[COMMERCIAL.md](docs/commercial/COMMERCIAL.md)。

## 隐私与遥测

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

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

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

## 定价摘要（验证期定价）

| 档位 | 价格 | 要点 |
|------|------|------|
| Community | ¥0 | CLI 会话门 + 自托管 Actions（漂移红灯 + PR 评论） |
| Pro | ¥29/月 | 托管 PR 评论 + 本机文件夹检查 + 邮箱账号 |
| Team | ¥99/人/月 | 早期采用者计划，不主推——组织规范 + 门禁托管 |

> 以下数字均为验证期定价，未经付费数据支撑。详见 [COMMERCIAL.md](docs/commercial/COMMERCIAL.md)。