ArchView

给一个仓库画一张「模块之间怎么依赖」的架构图 —— 拓扑全部来自 tree-sitter 静态分析，LLM 只负责给每个节点写一句人话摘要。同一份图通过 MCP 暴露给你 IDE 里的 agent。

单机、本地、只绑 127.0.0.1。默认中文界面。

🚀 让 AI 帮你装（最快）

没有发布到 npm，所以没有 npx archview 这条路 —— 只能从源码取。好消息是这件事可以整个丢给 AI。

把下面这段整段复制，粘给任何能读网页、能跑命令的 AI 助手（Kiro / Cursor / Claude Code / Codex …）， 把 <我的项目路径> 换成你要分析的仓库：

帮我装 ArchView 并把我的项目接进去。

仓库：https://github.com/LZZLHY/archview
安装剧本（先读这个，它是给你写的）：https://raw.githubusercontent.com/LZZLHY/archview/main/SETUP-FOR-AI.md

我的项目在：<我的项目路径>

照剧本走：环境体检 → clone → pnpm install + pnpm build → archview init 我的项目 → archview build → 起服务。
剧本里标了「决策点」的地方问我一下再决定（尤其是装到哪、要不要改我的 AI 宿主配置、要不要现在开始写摘要）。
最后把带 token 的面板 URL 给我。

剧本（SETUP-FOR-AI.md）里每个阶段都有「怎么知道这一步成了」，还有一节 「常见失败与对策」。它设计成 AI 在 clone 之前就能通过 raw URL 读到。

自己动手：跳到 第 5 节，五步命令能复制粘贴跑通； 或者一条命令搞定前两步：

# Windows PowerShell（先 clone，再跑仓库里的脚本）
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1

# macOS / Linux
bash scripts/setup.sh

想先判断值不值得看：第 3 节（它凭什么存在）与第 10 节（已知限制 / 谁不该用它）。

Related MCP server: SGraph MCP Server

1. 它解决什么问题

假设你一个人在写一个 9 个 ohpm 模块的 HarmonyOS 应用（这就是本项目的起因）。你想要两样东西：

1. 给自己看：一张能点开、能下钻、能看到「entry 依赖了哪几个 HAR、commons 被谁用」的图；

2. 给 agent 看：Cursor / Kiro / Claude Code 里的助手能准确知道项目结构，别再靠 grep 猜。

现成的东西各缺一半：

ArchView 把两头接起来：CodeGraph 出事实，UA 的面板出界面，LLM 只补语义。

2. 它是两个 MIT 项目的融合体，这里不避讳

两者皆 MIT。署名与逐文件出处在 NOTICE，本项目自己的许可在 LICENSE。

3. 为什么值得单独存在：LLM 永远不写拓扑

这是本项目唯一的技术根据，也是唯一一条不许妥协的规则：

节点和边只能由 CodeGraph 的 tree-sitter 输出派生。LLM/agent 只能提供 summary 与 tags，永远不写节点、不写边、不写模块划分。

区别很具体。拓扑由 LLM 生成的项目，必须再写一堆修补脚本擦屁股：规范化对不上的 ID、丢掉指向不存在节点的悬空边、翻转方向搞反的边。这些脚本本身就是「结构不可信」的证据。ArchView 不需要它们 —— 一条边存在，是因为 tree-sitter 在源码里真的解析到了那个引用。

配套的三条规则（覆盖率、layer 覆盖、文件级边上卷）与全部实现约束在 CONTRACT.md。MCP 的工具面里不存在任何写图的工具。

4. 需要什么

不需要全局安装 CodeGraph：它是 packages/core 的普通 npm 依赖，archview init 会从 node_modules 解析它的 bin 并代你调用（一律带 DO_NOT_TRACK=1 与 CODEGRAPH_NO_UPDATE_CHECK=1）。

发布状态：没有发布到 npm

所以没有 npx archview、没有 npm i -g archview，@archview/* 这些包名在 npm 上取不到。 唯一的安装方式是取源码 + 一次构建（第 5 节）。具体意味着三件事：

• 宿主机器必须有 Node ≥ 22.5 与 pnpm，没法只靠一个 npx 蒙过去；

• 首次要等一次 pnpm install + pnpm build（本机实测：全新克隆 install 5.0s、build 17.1s， 全流程 25.6s；pnpm store 冷的机器上 install 会久得多，几分钟正常）；

• 更新走 git pull + 重新 build（dist/ 是 gitignore 的，pull 只换源码不换产物）。

skill 安装器写 MCP 配置时也遵守这条现实：它优先指向本机已构建的 packages/mcp/dist/bin/mcp.js，而不是 npx -y @archview/mcp（那个包还没发布，照它写出来的配置 agent 一跑就是 404）。

平台现状（别指望我们全平台都测过）

• Windows —— 主要开发与验证平台。本 README 里的命令与输出都来自 Windows 11（build 26200）+ PowerShell + Node 22.20.0 + pnpm 10.28.2 上的实跑。skill 安装用 junction，不需要管理员权限。查端口占用：netstat -ano | findstr :7420。

• macOS / Linux —— 代码里所有平台相关分支都写了（打开浏览器用 open/xdg-open，skill 安装退化成 symlink），但我们没有在这两个平台上系统性跑过验收。遇到问题请开 issue，别当成「官方支持」。

• 运行时会看到一行 ExperimentalWarning: SQLite is an experimental feature。这是 Node 对 node:sqlite 的常规提示，不是错误。

5. 上手：从取代码到看见图

五步。每一步都写清楚在哪跑、跑完发生什么、怎么知道成功了。

不想自己走这五步？把 第 0 节那段提示词 粘给你的 AI 助手， 它会照 SETUP-FOR-AI.md 做完前三步。

第 1 步：取代码

它不在 npm 上（见第 4 节），所以第一步是把仓库弄到本机。四条路，挑一条：

A. git clone（首选） —— 以后 git pull 就能更新。

# Windows PowerShell
git clone --branch main --single-branch https://github.com/LZZLHY/archview.git "$env:USERPROFILE\archview"
cd "$env:USERPROFILE\archview"

# macOS / Linux
git clone --branch main --single-branch https://github.com/LZZLHY/archview.git "$HOME/archview"
cd "$HOME/archview"

B. 下载 zip（没有 git 时） —— 代价：以后更新只能重新下载覆盖。

# Windows PowerShell
Invoke-WebRequest https://github.com/LZZLHY/archview/archive/refs/heads/main.zip -OutFile "$env:TEMP\archview.zip"
Expand-Archive "$env:TEMP\archview.zip" -DestinationPath "$env:TEMP\av" -Force
Move-Item "$env:TEMP\av\archview-main" "$env:USERPROFILE\archview"

# macOS / Linux
curl -L https://github.com/LZZLHY/archview/archive/refs/heads/main.zip -o /tmp/archview.zip
unzip -q /tmp/archview.zip -d /tmp/av && mv /tmp/av/archview-main "$HOME/archview"

解压出来的目录名是 archview-main，记得改名（上面两条已经代你改了）。

C. gh repo clone（装了 GitHub CLI 时）

gh repo clone LZZLHY/archview "$HOME/archview"

D. 一键脚本（把第 1、2 步一起做完） —— 取代码 + pnpm install + pnpm build + 自检。 先用 A/B/C 拿到代码，然后：

# Windows PowerShell。-ExecutionPolicy Bypass 只影响这一次调用，不改系统策略
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1 -Dir D:\tools\archview -Ref main

# macOS / Linux
bash scripts/setup.sh
bash scripts/setup.sh --dir /opt/archview --ref main

还没 clone、想直接从云端拿脚本的话，先下载看一眼再跑，别无脑管道执行远程脚本：

irm https://raw.githubusercontent.com/LZZLHY/archview/main/scripts/setup.ps1 -OutFile "$env:TEMP\av-setup.ps1"
Get-Content "$env:TEMP\av-setup.ps1" -TotalCount 60     # 看一眼
powershell -ExecutionPolicy Bypass -File "$env:TEMP\av-setup.ps1"

curl -fsSL https://raw.githubusercontent.com/LZZLHY/archview/main/scripts/setup.sh -o /tmp/av-setup.sh
less /tmp/av-setup.sh                                   # 看一眼
bash /tmp/av-setup.sh

脚本参数：-Dir/--dir <路径>（默认 ~/archview）、-Ref/--ref <分支或 tag>、 -SkipBuild/--skip-build、-Help/--help。三条行为保证：目录已存在且是 archview 仓库 → git pull + 重新 build，不重复 clone；已存在但不是 archview 仓库 → 报错退出、那个目录一个字节都不动； 前置检查失败 → 给可执行的下一步而不是裸 exit 1。它刻意不做 archview init 与起服务 —— 那涉及你自己的仓库和常驻进程，得你或你的 AI 显式决定。

怎么知道成功了：安装目录下 package.json 存在且它的 name 是 archview。 用 git 取的还能 git rev-parse --short HEAD 看到一个 sha。

路径尽量别带空格 —— 能用，但之后每条命令的路径参数都得记着加引号。

第 2 步：装依赖 + 构建

在仓库根（也就是第 1 步落地的那个目录，比如 ~/archview）：

pnpm install
pnpm build

跑完会发生什么：六个包各自编译。五个 node 包 tsc 出 dist/，packages/web 用 Vite 出 packages/web/dist/（面板前端产物，服务靠它才有页面）。

怎么知道成功了：packages/cli/dist/bin/archview.js 与 packages/web/dist/index.html 都存在，且下面这条能打出帮助：

pnpm archview --help

pnpm install 首次会刷一串 WARN Failed to create bin at ... ENOENT。 四个包的 bin 都指向 dist/，而首次 install 时 dist/ 还不存在，所以 pnpm 建不出 node_modules/.bin/ 里的链接（最近一次从 GitHub 全新克隆实测 13 条；此前另一次运行是 12 条 —— 条数随 pnpm 版本与 store 布局微变，别把条数当判据，看到这类 WARN 就当正常）。它是无害的：下面所有命令走的是仓库根的 npm script pnpm archview（等价于 node packages/cli/dist/bin/archview.js），不依赖 bin 链接。 想拿到真正的 archview / archview-skill 命令：pnpm build 之后再跑一次 pnpm install，这次链接会建好，之后 pnpm exec archview --version 也能用。 我们刻意没加 prepare 脚本自动编译 —— 只想装依赖（CI 缓存、只改文档）的场合不该被迫等一次 Vite 全量构建。

⚠️ typecheck 必须在 build 之后跑

pnpm -r run build       # 先这个
pnpm -r run typecheck   # 再这个

反过来一定失败，报一串 TS2307: Cannot find module '@archview/core'（或它的 subpath，例如 '@archview/core/themes'）or its corresponding type declarations。原因是跨包类型走的是各包 package.json 的 exports → dist/*.d.ts，而 dist/ 是 gitignore 的：没 build 就没有 .d.ts。仓库里没有 TS project references，也没有把类型指回 src 的 path 别名，所以这不是配置疏漏，而是既有性质 —— 陌生人一定会踩，记住顺序就行。

同一条机制在日常开发里也会咬人：只要有人在某个包的 src/ 里新增了一个导出 subpath，其它包在那个包重新 build 之前都 typecheck 不过。看到 TS2307 先想「是不是该先 build」。

第 3 步：接入第一个要分析的仓库

还在 ArchView 仓库根。把路径换成你自己的仓库：

pnpm archview init d:/code/my-repo

跑完会发生什么（五步，每步都幂等，重复跑只是把现状告诉你）：

1. 环境检查（Node 版本、目录存在、是不是 git 仓库）

2. 在你那个仓库里建 CodeGraph 索引 .codegraph/codegraph.db（已有就跳过）

3. 写 .archview/config.json（已有就不覆盖；--force-config 才重写），并按 oh-package.json5 / pnpm-workspace.yaml / Cargo.toml / go.mod 自动预填模块骨架

4. 幂等地往你那个仓库的 .gitignore 追加一个带标记的块（详见第 7 节）

5. 把它登进 archview/workspaces.json（工作区注册表）

怎么知道成功了：最后打印工作区 id 与下一步命令。实跑输出（本次用的是 ArchView 自己的源码副本作为被分析仓库）：

[2/5] CodeGraph 索引（结构事实的唯一来源，铁律 1）
  → codegraph init "…/selfcopy"（大仓可能要几分钟，超时 1800s）
      *  Indexed 160 files
      •  2,142 nodes, 6,797 edges in 1.4s
  ✓ 索引建好了（exit 0，2.5s）-> …/selfcopy/.codegraph
[3/5] .archview/config.json
  ✓ 已写入：…/selfcopy/.archview/config.json
      模块识别：npmWorkspaces —— 自动识别命中 pnpm-workspace.yaml / package.json workspaces，6 个模块
[5/5] 登记进 workspaces.json
  ✓ 已登记：selfcopy -> …/selfcopy

接入完成。下一步：
  archview build selfcopy           # 建面板数据（codegraph sync + 建图 + 简报）
  archview serve --open             # 起服务（127.0.0.1:7420），打开列表页
  archview status selfcopy          # 随时看索引/图/摘要覆盖率/漂移

常用选项：--id <id>（进 URL，只允许 [a-z0-9][a-z0-9_-]*）、--name "显示名"、--skip-index、--telemetry-off。完整清单：pnpm archview init --help。

第 4 步：建面板数据

pnpm archview build            # 只登记了一个工作区时可以不带 id
pnpm archview build my-repo    # 多个工作区时说清是哪个

跑完会发生什么：codegraph sync（让索引跟上磁盘）→ 建图 → 写 .archview/graph.json 与 meta.json → 生成 .archview/briefs/*.json（给 LLM 的结构简报）→ 再确认一次 .gitignore 块。

怎么知道成功了：每一步前面是 ✓，末尾给出节点/边/模块与摘要覆盖率。本次实跑：

  ✓ codegraph sync             319 ms  exit 0
  ✓ buildGraph                  72 ms  981 节点 / 3851 边 / 7 layer
  ✓ writeGraph                   6 ms
  ✓ writeMeta                    1 ms
  ✓ buildAllBriefs               3 ms  7 份简报
  ✓ ensureGitignoreBlock         0 ms  unchanged

  节点 981  边 3851（文件级 734）  文件节点 158  模块 7
  摘要 已应用 0  覆盖率 0.0%（分母＝文件节点＋框架组件）

覆盖率 0% 是正常的第一次结果 —— 语义摘要要靠 agent 写，见第 6 节。

有告警时（比如摘要被误放进子目录导致一条都没读到）build 会把它们单独拎出来重打一遍并给出修法。告警不是失败，图确实建出来了，但那些东西没生效。

随时复查实况：

pnpm archview status           # 不带 id 就把注册表里所有工作区各打一段
pnpm archview status my-repo --json

status 的数字与列表页、MCP 的 archview_status 来自同一个函数 —— 不会出现两个不同的覆盖率。

第 5 步：起服务看图

pnpm archview serve --open

跑完会发生什么：一个进程、一个端口服务所有已登记的工作区。默认 127.0.0.1:7420；被占用时自动往上找（最多 20 个），显式给了 --port 就不换、占用即失败。启动打印一次性 session token，所有 api/* 都校验它。

怎么知道成功了：横幅长这样（本次实跑，token 已截断）：

  ArchView 服务已启动    127.0.0.1:7420（只绑本机）
  注册表                 …\workspaces.json
  工作区                 selfcopy
  面板产物               …\packages\web\dist
  🔑  http://127.0.0.1:7420/?token=be5fea76…27d1
  所有 api/* 都要带这个 token（?token= 或 x-archview-token 头）。进程重启换新 token。
  Ctrl-C 停止。（进程重启会换 token。）

「面板产物」那一行必须指到一个真实存在的 packages/web/dist —— 没构建前端时列表页会显式提示 面板前端未构建，这时跑 pnpm --filter @archview/web build。

列表页上每个工作区一张卡片，四个按钮：打开面板 / 重建数据 / 复制 agent 提示词 / 漂移详情。

本次对服务的实测（全部带 token）：

三种调用方式，随便挑

上面所有命令都写成 pnpm archview …（仓库根的 npm script），因为它在首次 install 之后立刻可用， 不依赖 bin 链接。另外两种等价写法：

# ① 直接跑 node，连 pnpm 都不要（脚本化、给 AI 用最省事）
node packages/cli/dist/bin/archview.js --help        # 总览
node packages/cli/dist/bin/archview.js init --help   # 每个子命令都有 --help
node packages/server/dist/bin/serve.js --port 7500   # 只起服务，跟 archview serve 是同一个 startServer
                                                    # 注意它没有 --help：给任何参数都直接起服务并常驻

# ② 真正的 archview 命令 —— 需要 bin 链接，也就是 build 之后再 install 一次
pnpm install                    # 这次不会再刷 ENOENT WARN，链接会建好
pnpm exec archview --version

注意 ② 只在这个仓库内有效（bin 链接在仓库的 node_modules/.bin/）。没有全局安装这条路 —— 包没发布到 npm（第 4 节）。

6. 让 agent 补上语义

图建好之后节点是有了，但每个节点的 summary 还只是确定性兜底句（docstring / 由签名合成 / <名字> —— <路径> 中的 <kind>）。把它们换成人话是 agent 的活。

零安装路径（先用这个）

1. 列表页点 复制 agent 提示词（等价于 GET /w/<id>/api/prompt）。

2. 把提示词粘给正在编辑那个仓库的 AI。提示词很短，主要作用是指向工作区里的 <workspace>/.archview/AGENT-GUIDE.md —— 一个本地文件，任何工具都能读。

3. AGENT-GUIDE.md 需要生成一次（build 不会自动生成它）：

   pnpm archview skill guide --workspace d:/code/my-repo --write

   本次实跑写出 22 KB（22185 字节），十节内容：铁律、这个工作区现在的样子、具体缺哪些摘要（逐个 nodeId 列出）、过期的摘要、你的输入（结构简报路径）、按检测到的语言挑好的指导、输出格式与提交方式、触发重建 + 只读地确认现状的端点、交付前自检清单、报告格式。提示词里也带了这条命令，agent 自己会跑。

   生成一次之后就不用再管它：往后每次重建（面板按钮 / archview build / POST api/rebuild / MCP archview_rebuild）都会把它整份重写（契约第 2 节要求如此，所以它在 gitignore 里）。重建的 steps 里能看到 writeAgentGuide 这一步跑了没跑。反过来说，文件不存在时重建不会替你创建 —— 我们不往你的工作区塞你没要过的文件。

4. agent 照指南往 .archview/summaries/<分片>.json 写摘要。分片名 = 模块 key 里的 / 换成 _（模块 packages/core → packages_core.json）。这个目录是平的，写进子目录的摘要一条都不会被读（会告警，但那一轮活白干了）。

5. 重建：pnpm archview build，或列表页点「重建数据」，或 agent 自己 POST /w/<id>/api/rebuild?token=…。

6. 面板上出现语义，status 的覆盖率往上走。

摘要提交有服务端护栏（默认值在 packages/core/src/limits.ts）：每条 30–140 字、标签 ≤6 个且每个 ≤16 字、单批 ≤200 条（超了整批拒绝，一条都不写盘，不截断），再加一份「空话词表」拦截「负责处理相关逻辑」这类废话。阈值与词表的真身只有一份，在 @archview/core：MCP 用它执法、skill 用同一份写指南 —— 免得说明书和执法者不一致（历史上就出过这个 bug）。

⚠️ 护栏只在 MCP 提交这条路上自动执法。 上面第 4 步那样直接写摘要分片时没有任何东西检查它们（写砸了不报错，静默进面板）。所以直接写文件之后跑一次自检，判据与 MCP 完全同一份代码（@archview/core 的 checkSummaryItem）：

pnpm exec archview-skill check-summaries --workspace d:/code/my-repo

逐条报告孤儿 nodeId、长度越界、tags 数量/长度/与确定性标签撞车、空话命中、hash 是否等于当前 content_hash，外加 summaries/ 下有没有子目录、分片 JSON 是否合法；有不合规项时退出码非 0。AGENT-GUIDE 的方式 A 段落与自检清单里都指向它。

进阶路径：装 skill + MCP

更省 token（不必通读源码，读结构简报即可），提交时有结构化校验。

pnpm archview skill hosts                    # 支持哪些宿主与各自的路径依据
pnpm archview skill install kiro --dry-run   # 先看它要动哪些文件（什么都不写）
pnpm archview skill install kiro             # 真装
pnpm archview skill verify                   # 语言/框架指导自检

实测：skill hosts 列出 7 个已确认宿主（kiro、claude、cursor、codex、opencode、gemini、copilot CLI）与一批明确不支持的（路径随平台/版本变、没法复现验证的，我们不猜，用 /skill/download 手动放）。skill verify 实测「语言指导 38 份，框架指导 10 份，全部存在、非占位符、都有上游标注与 ArchView 改造段落」。

Kiro 优先：skill 装到 ~/.kiro/skills/archview，agent 定义 ~/.kiro/agents/archview.json，MCP 写 ~/.kiro/settings/mcp.json。安装器合并不覆盖（只动 mcpServers.archview 一个键），改写已有文件前留 .bak-<时间戳>，Windows 用 junction 不用 symlink。--dry-run 会把要写的内容原样打出来（实测确认它一个字节都不写），--home <dir> 可以把 HOME 指到别处试。

MCP 配置也可以不装 skill 自己抄：AGENT-GUIDE.md 与 api/prompt 的 meta.mcp.snippet 里就带着可直接粘的片段，指向同仓已构建的 packages/mcp/dist/bin/mcp.js。

六个 MCP 工具，只读 + 提交摘要，没有任何写图的工具：

任何宿主都能直接下载 skill 包：GET /skill/download（tar.gz），或 GET /skill/* 明文浏览单个文件（比如 /skill/SKILL.md）。

7. 数据放哪 / 什么该提交进 git

这一节决定了你换机器之后摘要还在不在。 数据全落在被分析的那个仓库里，不在 ArchView 仓库里：

<你的仓库>/
  .codegraph/            CodeGraph 索引（SQLite，外部工具的，我们只读）   → 不提交
  codegraph.json         CodeGraph 的排除清单，可选、手写                 → 写了就提交（团队共享口径）
  .archview/
    config.json          语言、模块策略与标签、边阈值、输出语言           → **提交**
    summaries/*.json     LLM 摘要，按模块分片                             → **提交**（这是资产）
    graph.json           派生图，面板的数据源                             → 不提交
    meta.json            content_hash 快照（漂移检测的依据）              → 不提交
    briefs/*.json        给 LLM 的结构简报                                → 不提交
    AGENT-GUIDE.md       给 agent 的操作说明（每次生成整份重写，含时间戳）→ 不提交

判断标准只有一条：人和 LLM 攒出来的东西提交，工具能重新算出来的东西不提交。

• summaries/ 是几百条人工/LLM 写的中文摘要，重新生成要花掉真金白银的 token。它跟着代码走 —— 换机器、换人、换 agent 都还在。

• config.json 是团队对「模块怎么分、边阈值多少、输出什么语言」的共识。

• 其余都是 archview build 十秒内能重算的。AGENT-GUIDE.md 尤其不该提交：它每次重建整份重写并带时间戳，提交它只会制造冲突。

archview init 与每次 rebuild 都会幂等地往你那个仓库的 .gitignore 追加这个块（靠标记识别，重复运行不重复追加，也不动你原有的行）：

# >>> archview >>>
.codegraph/
.archview/graph.json
.archview/meta.json
.archview/briefs/
.archview/AGENT-GUIDE.md
# .archview/summaries/ 与 .archview/config.json 故意不忽略——它们要提交
# <<< archview <<<

ArchView 仓库自己的 .gitignore

本仓库的 .gitignore 排除 node_modules/、dist/（五个包的 tsc 产物与 packages/web 的 Vite 产物同名，一条覆盖）、dist-pack/、*.tsbuildinfo、.tmp/、.codegraph/ 与 *.db*、*.log、.env*、编辑器目录，以及 workspaces.json。

workspaces.json 是工作区注册表，内容是本机绝对路径（d:/code/my-repo），因机器而异 —— 所以新克隆的仓库里这张表一定是空的，这是设计而不是缺失。用 archview init 自己造。

8. 验收脚本

五个脚本加一组单元测试，合起来一百五十多项断言。大部分是「起服务 → 测 → 停」，不留常驻进程，对被检查工作区的写入可逆。

共同前置：pnpm build，并且至少有一个已经 archview build 过的真实工作区。它们刻意不用桩数据 —— 这些检查的价值全在真实数字上（历史上就是在真实数据上才暴露出 2253 条 auto-corrected 警告）。没有工作区时它们会打印怎么办然后 exit 1，不抛栈。

下面「实测」一列是在一个 TypeScript 工作区（ArchView 自己的源码副本，见第 9 节 A）上跑出来的；ArkTS 专项断言在这种工作区上会明确标成「跳过 / 不适用」，不算失败。

跑之前先清环境变量残留

# PowerShell
Remove-Item Env:ARCHVIEW_ACCEPT_WS,Env:ARCHVIEW_WORKSPACES,Env:ARCHVIEW_MCP_WS,Env:ARCHVIEW_CHECK_WS -ErrorAction SilentlyContinue

# bash / zsh
unset ARCHVIEW_ACCEPT_WS ARCHVIEW_WORKSPACES ARCHVIEW_MCP_WS ARCHVIEW_CHECK_WS

ARCHVIEW_WORKSPACES 换掉的是读哪张注册表，ARCHVIEW_ACCEPT_WS / ARCHVIEW_MCP_WS / ARCHVIEW_CHECK_WS 换掉的是测哪个工作区。它们在 shell 里残留一次，就会出现「明明没改代码，验收数字却变了」这种最费时间的假象 —— 因为你测的已经是另一个仓库了。同一个道理也适用于命令行：archview init|build|status --workspaces <file> 可以显式指定注册表，多注册表并行时建议每条命令都写上，别靠环境变量记状态。

三个坑，踩过才知道：

• selfcheck.mjs 结束时会把整个 archview/.tmp/ 删掉（除非给 --keep），不只是它自己那个子目录。别把想留的东西放在 .tmp/ 下。

• packages/mcp/scripts/acceptance.mjs 只读仓库根的 workspaces.json，不认 ARCHVIEW_WORKSPACES 环境变量（其余入口都认）。想让它跑别的注册表，得直接改那张表。

• MCP 验收里「写入现有分片时先合并再写」这条断言，要求被挑中的那个分片里除了缺口之外还有别的条目。 脚本按文件名排序取第一个含 file 节点的分片来造缺口，如果那个分片恰好只有一条摘要（比如只有一个文件的 _other 模块），缺口造完分片就空了，这条断言就无从成立，会报一条 36/37。这是工作区形状问题，不是代码问题：把摘要写全一点，或让第一个分片对应一个多文件模块即可。

9. 实测数字（附出处）

数字随仓库内容变化，所以每一条都标明是哪个仓库、什么时候、什么口径。

A. ArchView 分析自己（本次为写这份 README 重跑；被分析的是 ArchView 源码的一份副本，排除了 node_modules/、dist/、.tmp/；Windows 11 / Node 22.20.0 / pnpm 10.28.2）：

数字会随源码变动漂移：同一套口径在此前一个更早的源码版本上跑出来是 899 节点 / 6 模块 / 618 文件级边 / 6 对模块之间 148 条聚合边。差异全部来自源码本身长大了，不是口径变了 —— 所以别把这些数当基准值去断言，要断言就跑验收脚本。

B. AMCL（作者机器上的一个 HarmonyOS / ArkTS 应用，10 个 ohpm 模块） —— 这些数字来自作者机器上此前的运行，本次没有重跑（那个工作区不在本仓库里，也不该被本 README 的验证过程改动）：4277 节点 / 16124 边 / 10 模块 / 摘要覆盖 304 of 304 / 文件级边 2115 / 模块总览 24 对模块之间 1246 条聚合边。packages/core/src/limits.ts 里的摘要长度区间（40–80 字）也是从这批人工摘要量出来的：min 36 / p50 57 / p95 78 / max 108 字。

10. 已知限制 / 谁不该用它

诚实清单。不吹。

• 单机工具，没有多用户模型。 只绑 127.0.0.1，鉴权只有一个进程级一次性 session token。没有账号、没有角色、没有审计。不要暴露到外网，也不要当团队服务部署。

• 跨进程并发 rebuild 没有锁。 同时从面板、命令行、MCP 触发同一个工作区的重建，最后写盘的赢。单人用没问题，别写脚本并发调。

• graph.json / meta.json / 摘要分片都是直接覆盖写，不是原子写（没有「写临时文件再 rename」那一步）。正常退出没事，写盘中途断电或强杀进程可能留下半截文件 —— 删掉重跑 archview build 即可，它们都是派生物。唯一做了原子写的是 workspaces.json（注册表）。

• /skill/download 与 /skill/* 不校验 token。 它们吐的是随包发布的 skill 文档，本来就要给任何 agent 宿主直接下载，所以刻意没上门禁。会读你代码的那些端点（api/graph.json、api/file、api/rebuild …）全部校验。因为只绑 127.0.0.1，能访问它的就是本机进程 —— 这个取舍的前提是「别把它暴露出去」。

• 摘要质量完全取决于你的 agent 和你给它的预算。 ArchView 只保证「拓扑是真的」和「不许写空话」，不保证摘要写得好。护栏能拦住空话词表里的废话，拦不住一句正确但没用的话。

• HarmonyOS / ArkTS 是唯一验证充分的场景。 ohpm 模块识别、ArkUI 组件树两跳折叠、.ets 高亮都是在真实 ArkTS 工程上打磨的。其它语言只做了结构层验证（能索引、能建图、模块能识别、面板能渲染），没有针对性的框架推导，语言指导也只做了文档层自检。

• 只在 Windows 上系统性跑过验收。 macOS / Linux 的平台分支写了但没测。

• 不是「一键理解任意仓库」。 第一次 init 大仓可能要几分钟（CodeGraph 索引），摘要要 agent 跑好几轮。它适合你打算长期维护的项目，不适合十分钟浏览一个陌生仓库。

• 模块总览的 layer 间边是无向的。 vendored 的 aggregateLayerEdges 把 A→B 与 B→A 合并了。方向信息在下钻视图里还在。

• 走「包根 barrel」的跨包 import 解析不出来，所以模块总览上会少边。 CodeGraph 能解析深路径的跨包引用（import … from '../../server/src/rebuild.js' 这种），但 import { startServer } from '@archview/server' —— 即指向包入口、由 package.json 的 exports 再转发到实现文件的那种 —— 解析不到目标符号，于是这条依赖不进图。本仓库自己就是例子：packages/cli/src/commands/serve.ts 走 barrel，简报的 importsFrom 里没有 server；build.ts 走深路径，解析出来了。看到模块总览上少一条你确信存在的边，先怀疑这个原因（去简报里看那个文件的 importsFrom：为空或缺目标，就是它）。这是上游 CodeGraph 的解析能力边界，不是可配置项；我们刻意不在 builder 里按包名猜补这条边 —— 猜出来的拓扑就是 LLM 写拓扑的另一种形式，违反铁律 1。真要在图上看到它，把那处 import 改成深路径（或等 CodeGraph 支持）。

• 边按 confidence / resolvedBy 过滤（默认阈值 0.7，丢弃 heuristic）。不过滤会出现纯靠名字撞出来的假模块依赖（实测存在 confidence: 0.3 的 fuzzy 边）。反过来说，被过滤掉的真依赖也就看不见了。

• CodeGraph 遥测默认开启，但我们代你调它时一律带 DO_NOT_TRACK=1 与 CODEGRAPH_NO_UPDATE_CHECK=1（写在 runCodegraph 里，不是可选项）。想把它的全局开关也关掉：pnpm archview init … --telemetry-off。

• 源码浏览端点有硬限制：/w/<id>/api/file 只允许图里出现过的 filePath（白名单）、拒绝 .. 与绝对路径、上限 1 MB、拒绝二进制。

11. 架构与包结构

archview/
  package.json            pnpm workspace 根（scripts: build / typecheck / selfcheck / archview）
  LICENSE  NOTICE  README.md  CONTRACT.md
  AGENTS.md               仓库根路牌（多个 agent 工具会自动读它）：装 → SETUP-FOR-AI，改代码 → CONTRACT
  SETUP-FOR-AI.md         给 AI 的一次性安装剧本（阶段 + 成功判据 + 决策点 + 失败对策）
  scripts/setup.ps1       一键准备（Windows）：取代码 + install + build + 自检。幂等，不碰你的仓库
  scripts/setup.sh        同上（macOS / Linux；只做过 bash -n 语法检查，未在真实 Unix 上跑过）
  workspaces.json         工作区注册表（本机绝对路径，不提交）
  final-check.mjs         整体验收（起→测→停）
  packages/
    core/     图模型与校验（vendored UA schema）、CodeGraph 读取、builder(CG→图)、
              模块策略、框架 deriver、结构简报、.archview/ 布局与选择性 gitignore、
              提交护栏阈值与空话词表（唯一真身）
    web/      vendored 改造的 dashboard。按 /w/<id>/api/* 取数，中文默认开
    server/   单端口服务：工作区列表页 + 每工作区的面板与只读 API + rebuild
              bin: packages/server/dist/bin/serve.js   (archview-serve)
    mcp/      MCP server（stdio）。六个工具，只读 + 提交摘要
              bin: packages/mcp/dist/bin/mcp.js        (archview-mcp)
    skill/    SKILL.md 顶层提示词、38 份语言指导 + 10 份框架指导、
              AGENT-GUIDE.md 生成器、多宿主安装器
              bin: packages/skill/dist/bin/skill.js    (archview-skill)
    cli/      统一入口：init | build | serve | status | skill
              bin: packages/cli/dist/bin/archview.js   (archview)

cli 不重实现任何逻辑：build 调 server 的 rebuildOnce，status 调 inspectWorkspace，serve 调 startServer，skill 原样转发给 archview-skill。理由是面板、MCP、命令行对同一件事必须给同一个数 —— 覆盖率这种指标一旦有两个来源，两个数一定会分叉。

数据流一句话：

你的源码 ──tree-sitter──▶ .codegraph/codegraph.db ──builder──▶ .archview/graph.json ──▶ 面板 / MCP
                                                        ▲
                            .archview/summaries/*.json ──┘  （只贡献 summary 与 tags）
                                     ▲
                        你的 LLM agent ┘（读 .archview/briefs/*.json，不读源码）

12. 许可与致谢

ArchView 自己是 MIT（LICENSE）。它站在两个同样是 MIT 的项目上：

• Understand-Anything — MIT, © Yuxiang Lin and Infinite Universe, Inc. 面板、图 schema、校验器、skill 与语言/框架指导都来自它。我们全量 vendor 并改造，每个 vendored 文件头部都写着上游路径与改了什么。

• CodeGraph — MIT, © Colby McHenry. 全部结构事实的来源。没有 vendor：我们依赖发布的 npm 包，只读它的 SQLite 索引，调它的 bin。

逐文件出处与两者的完整署名在 NOTICE。如果这个项目对你有用，请先去给上面两个仓库点星 —— ArchView 只是把它们接了起来。

13. 想改点什么

先读 CONTRACT.md（AGENTS.md 是给 agent 的一页速览，指向同一处）。 它是硬约束地基，不是风格指南 —— 四条铁律（LLM 不写拓扑 / summary 非空 / layer 覆盖全部文件节点 / 文件级边必须上卷）、冻结的节点 ID 方案、图 schema、模块策略、服务端点表、MCP 工具面，全在里面，每一条都写了「为什么」和「违反了会发生什么」。违反其中任何一条是设计错误。

尤其注意两处：

• 节点 ID 方案是冻结的。 摘要文件用节点 ID 做 key，改 ID 等于作废所有人已有的摘要资产。

• 图 schema 与 vendored 的 UA schema 完全一致，不加不减。 面板是照搬的，schema 一动就要改面板。私有信息走节点的 passthrough 字段（边不是 passthrough，额外字段会被静默 strip，别依赖）。

改完至少跑：

pnpm -r run build                      # 一定在 typecheck 之前
pnpm -r run typecheck
pnpm --filter @archview/server run test
node packages/core/scripts/selfcheck.mjs --workspace <你的工作区目录>
node packages/server/scripts/acceptance.mjs
node packages/mcp/scripts/acceptance.mjs
node final-check.mjs

跑之前先清掉 ARCHVIEW_* 环境变量残留（第 8 节给了两个 shell 的命令），否则你测的可能是另一个仓库。