ArchView

Draw an architecture diagram of "how modules depend on each other" for a repository — the topology all comes from tree-sitter static analysis, and the LLM is only responsible for writing a one-sentence human-readable summary for each node. The same diagram is exposed to the agent in your IDE via MCP.

Standalone, local, bound only to 127.0.0.1. Chinese interface by default.

📦 Direct Download (Windows, no Node install, no clone)

⬇ ArchView_0.1.0_x64-setup.exe · 35 MB · Windows 10/11 x64

After installing, double-click and you get a standalone window — inside it is the same panel as the web version. It bundles Node and CodeGraph, installed to %LOCALAPPDATA%\ArchView, no administrator rights needed.

Usage: copy a paragraph to your AI, then answer a few questions.

When you open the software the panel is empty, with a copyable prompt at the top (carrying the real port and token for this run). Paste it to the AI that's editing your project — Kiro / Claude Code / Cursor / Codex / opencode / Gemini CLI / Copilot CLI, any of them will do; it will recognize which one it is by itself. Then it will:

1. Connect to this already-running window (it won't clone or install another copy)

2. Recognize which host it is, configure MCP properly (it will ask you before touching your config)

3. Recursively find candidate projects in your workspace — a folder containing several repos/subprojects is the norm, it will show you the list and ask which one to connect (or all of them)

4. Register + build index + build graph (it will build the index itself if it doesn't exist; a large repo takes a few minutes)

5. Ask again whether to write semantic summaries now (that step burns tokens, so it must ask)

You only need to answer a few questions, then wait for the graph to appear in the window. The procedure is written in CONNECT-FOR-AI.md (the prompt in the software points to it), the live version with the real port and token is at /onboarding.md at runtime.

Don't want the AI involved? Filling in an absolute path in the form below the panel works the same — after registering, click "Rebuild Data", and the index will be built on its own.

⚠️ No code signing; the first run will be blocked once by SmartScreen ("More info" → "Run anyway").

Related MCP server: SGraph MCP Server

Or install the CLI version

npm i -g archview                 # 四个命令进 PATH：archview / archview-serve / archview-mcp / archview-skill
archview init d:/code/my-repo && archview build && archview serve --open

npx archview init .               # 不装，试一次就走

Published on npm: archview. No pnpm, no clone, no build needed; the only hard requirement is Node ≥ 22.5 (node:sqlite). The first npm i will also pull down CodeGraph's platform subpackage (the Windows x64 one is 248.7 MB, bundling its own node.exe and native modules) — this is expected; we deliberately don't bundle it into the package (doing so would mean every platform's users download all six copies).

How to choose among the three paths:

All three share the same workspace registry (~/.archview/workspaces.json), so you can mix and match freely and all see the same set of projects. Desktop version details in Windows standalone window version.

🚀 Let the AI install it from source for you

Want the CLI version (CI, scripts, MCP integration), or want to modify the code — this whole thing can be handed to an AI.

Copy the following entire block, paste it to any AI assistant that can read web pages and run commands (Kiro / Cursor / Claude Code / Codex …), and replace <我的项目路径> with the repository you want to analyze:

帮我装 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 给我。

Each stage of the script (SETUP-FOR-AI.md) has a "how to know this step succeeded" section, plus a "common failures and countermeasures" section. It's designed so the AI can read it via raw URL before cloning.

Do it yourself: jump to Section 5; the five-step commands can be copy-pasted and run through; or one command handles the first two steps:

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

# macOS / Linux
bash scripts/setup.sh

Want to first judge whether it's worth looking at: Section 3 (why it deserves to exist) and Section 10 (known limitations / who shouldn't use it).

1. What problem it solves

Say you're writing a HarmonyOS app with 9 ohpm modules by yourself (that's the origin of this project). You want two things:

1. For yourself: a graph you can click, drill into, and see "which HARs entry depends on, who uses commons";

2. For the agent: the assistant in Cursor / Kiro / Claude Code can accurately know the project structure, no more guessing via grep.

Existing tools each miss half:

ArchView connects the two ends: CodeGraph produces the facts, UA's panel produces the UI, and the LLM only fills in semantics.

⚠️ Read this first: how many modules you get depends on your repository's shape

The premise of the "how modules depend on each other" graph is having multiple modules. Modules aren't guessed by us; they're derived from facts in your repository (iron rule 1), so repositories of different shapes get different results:

archview build prints a line each time explaining where the modules came from, for example:

模块策略 pathDepth —— 未命中工程化模块声明（…），退化到路径深度切分；
  按路径首段只得到 1 个模块（src），已自动下钻到第 2 层，切出 4 个模块：src、src/api、src/core、src/utils

archview status and the panel's list page give the same sentence. If you don't understand why your modules are split this way, look at it first.

⚠️ One counterintuitive point: modules.labels can only change the display name and description of modules that have already been recognized; it cannot define modules. Writing a key that doesn't exist into it won't create a module (build will report a warning for this). To change "how modules are split", change modules.strategy / modules.pathDepth.

⚠️ If your repository has large directories (build artifacts, precompiled binaries, container contexts), write a codegraph.json first

These are two different switches with different points of effect; almost everyone trips on this the first time:

codegraph.json is CodeGraph's config file, not ours — ArchView never generates or modifies it, so no one will write it for you, and it won't be overwritten by us. The shape is that simple:

{ "exclude": ["prebuilt/", "docker/output/", ".tmp-build/", "third_party/"] }

After writing it, delete .codegraph/ and rebuild once (the index has to be rebuilt for the exclude to take effect).

The measured numbers for this round came from exactly this — the same HarmonyOS repository (281 .ets files), the only difference being whether this file exists:

That last cell isn't an exaggeration: graph.json is written to disk via JSON.stringify, and V8's string limit is about 512 MiB; beyond that it throws an Invalid string length. So now there are two barriers, both of which name codegraph.json: when the index file count is too large it gives a warning before building the graph (so you don't wait four minutes for nothing), and when the graph truly exceeds the limit it explicitly refuses to write and gives the JSON above.

2. It's a fusion of two MIT projects; no hiding it here

Both are MIT. Attribution and per-file provenance are in NOTICE; this project's own license is in LICENSE.

3. Why it deserves to exist on its own: the LLM never writes topology

This is the project's only technical basis, and the only rule that must never be compromised:

Nodes and edges can only be derived from CodeGraph's tree-sitter output. The LLM/agent can only provide summary and tags; it never writes nodes, never writes edges, never writes module divisions.

The difference is concrete. Projects whose topology is generated by an LLM have to write a pile of patch scripts to clean up after themselves: normalizing IDs that don't match, dropping dangling edges pointing at nonexistent nodes, flipping edges whose direction got reversed. Those scripts are themselves evidence that "the structure can't be trusted." ArchView doesn't need them — an edge exists because tree-sitter actually parsed that reference in the source code.

The three supporting rules (coverage, layer coverage, file-level edge rollup) and all implementation constraints are in CONTRACT.md. No graph-writing tool exists in the MCP tool surface.

4. What you need

No global CodeGraph install needed: it's an ordinary npm dependency of packages/core; archview init resolves its bin from node_modules and calls it on your behalf (always with DO_NOT_TRACK=1 and CODEGRAPH_NO_UPDATE_CHECK=1).

Release status: both forms are live

The npm package was genuinely installed and run in a completely clean temp directory (pulled from the registry, not a local tarball): npm i archview 8.8 seconds → archview init actually calls CodeGraph to build the index → archview build builds the graph (single-package layout auto-drills down to 2 modules) → archview-serve starts the service, graph endpoint and connection endpoint all return 200, prompt is rendered by @archview/skill rather than a built-in fallback, and the two zod alias isolations hold (mcp 3.25.76 / core 3.24.1).

Names like @archview/core will never appear on npm: they're internal workspace package names (all six packages' package.json mark private: true); only the single archview package is published. So don't write npx -y @archview/mcp in your MCP config (that package name doesn't exist); write npx -y -p archview archview-mcp, or just use the installed archview-mcp bin — the best form is pointing at the absolute path of the real mcp.js on your machine (the panel and GET /api/onboarding give you exactly that).

For people publishing a new version (needs npm login, or a token with publish permission in ~/.npmrc; npm now requires 2FA by default, so interactive publishing needs --otp=<6-digit code>):

pnpm run npm:publish     # = 先 build 六个包 → 组装 npm-package/ → npm publish

Just want to see what would be published:

pnpm run npm:pack                        # 产出 npm-package/archview-<版本>.tgz
npm publish ./npm-package --dry-run      # 逐条清单，不落地

The assembler is scripts/build-npm-package.mjs; its file header spells out "why a single package", "why no bundler", and the four guards (missing dist / dist older than src / version numbers not unified / artifact self-check fails → all refuse to package; no empty packages or stale code will be shipped).

You can still install from source (Section 5): if you want to modify code, run acceptance scripts, or use pnpm --filter to build a single package, go the source route. That route requires Node ≥ 22.5 and pnpm, and the first time you'll wait through one pnpm install + pnpm build (measured locally: fresh clone install 5.0s, build 17.1s, full flow 25.6s; on a machine with a cold pnpm store, a few minutes is normal). Updates go through git pull + rebuild (dist/ is gitignored, so pull only swaps source, not build artifacts).

When the skill installer writes MCP config, it prefers "files that actually exist on this machine": in the npm-installed form it points to node_modules/archview/packages/mcp/dist/bin/mcp.js, in the source form to packages/mcp/dist/bin/mcp.js, and only if neither is available does it fall back to npx -y -p archview archview-mcp, with copy explaining that this requires the package to be published. command uses the absolute path of the current process's node rather than a bare "node": the desktop build ships its own runtime and doesn't require the user to install Node, while a bare "node" depends on the host's PATH (which may be missing, may be 18, or may be switched away by nvm).

Windows standalone window build (installer)

Besides the CLI, there's also a Windows app with its own window — desktop/, a Tauri 2 shell. Published, download directly:

⬇ ArchView_0.1.0_x64-setup.exe (35 MB, Windows 10/11 x64, installs to %LOCALAPPDATA%, no UAC)

You can also build it yourself:

cd desktop
npm install              # 只装 @tauri-apps/cli 一个本机开发工具
npm run build            # 产出 ArchView_<版本>_x64-setup.exe（~35 MB）

(Requires the Rust toolchain: rustup + MSVC. npm run build will first run scripts/stage-resources.mjs itself to place the npm single package and production dependencies into bundle.resources; if any step in that process fails, the build aborts — so you can't produce an "installer with missing pieces".)

It is not a separate thing from the browser version: the window loads the same packages/web/dist SPA, and the shell only spawns the same packages/server and kills it on exit — there's not a line of service logic in the Rust side (CONTRACT.md section 9 pins this as a hard constraint). So the panel, CLI, MCP, and desktop version all give the same number for the same thing.

The installed software ships with Node and CodeGraph built in — nothing needs to be pre-installed on the user's machine:

After install, usage is "open the window → enter a repo's absolute path on the list page → click rebuild → look at the graph", no terminal involved. If there's no index, rebuild will run codegraph init itself (contract section 6) — honestly, right now it replies with "run archview init first", which is a command a window-only user can't execute.

Two things not done yet, stated clearly: no code signing (SmartScreen will block the first run once — "More info → Run anyway"), Windows x64 only (the packaging script picks the CodeGraph platform subpackage based on the current platform; cross-platform builds need to be run once on each target platform). Details in desktop/README.md.

Platform status (don't expect us to have tested every platform)

• Windows — the primary development and validation platform. All commands and output in this README come from real runs on Windows 11 (build 26200) + PowerShell + Node 22.20.0 + pnpm 10.28.2. Skill install uses junctions, no admin rights needed. Check port usage: netstat -ano | findstr :7420.

• macOS / Linux — all platform-specific branches in the code are written (opening the browser uses open/xdg-open, skill install degrades to symlink), but we have not systematically run acceptance on these two platforms. If you hit issues, please open an issue — don't treat this as "officially supported".

• At runtime you'll see a line ExperimentalWarning: SQLite is an experimental feature. This is Node's routine notice for node:sqlite, not an error.

5. Getting started: from fetching code to seeing the graph

Five steps. Each one spells out where to run it, what happens when it finishes, and how to know it worked.

Don't want to walk through these five steps yourself? Paste the opening prompt to your AI assistant, and it will follow SETUP-FOR-AI.md to do the first three steps.

Step 1: Fetch the code

It's not on npm yet (see Section 4: the package is built but not published), so step one is getting the repo onto your machine. After publication, this whole section can be skipped — npm i -g archview and then start directly at Step 3 (archview init). Four routes, pick one:

A. git clone (preferred) — future updates via 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. Download the zip (when you don't have git) — cost: future updates mean re-downloading and overwriting.

# 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"

The extracted directory is named archview-main; remember to rename it (the two commands above already did it for you).

C. gh repo clone (when you have GitHub CLI)

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

D. One-shot script (does Steps 1 and 2 together) — fetch code + pnpm install + pnpm build + another pnpm install (to fix bin links) + self-check. First get the code via A/B/C, then:

# 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

If you haven't cloned yet and want to grab the script directly from the cloud, download and read it first before running — don't blindly pipe remote scripts:

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

Script arguments: -Dir/--dir <path> (default ~/archview), -Ref/--ref <branch or tag>, -SkipBuild/--skip-build, -Help/--help. Three behaviors guaranteed: directory exists and is an archview repo → git pull + rebuild, no duplicate clone; exists but is not an archview repo → error exit, not a single byte of that directory touched; preflight check fails → gives an actionable next step instead of a bare exit 1. It deliberately does not run archview init or start the service — those involve your own repo and a long-running process, so they need an explicit decision from you or your AI.

How to know it worked: package.json exists in the install directory and its name is archview. If you used git, git rev-parse --short HEAD will also show a sha.

Try to avoid spaces in the path — it works, but every command's path argument from then on needs quotes.

Step 2: Install dependencies + build

In the repo root (the directory from Step 1, e.g. ~/archview):

pnpm install
pnpm build

What happens when it finishes: all six packages compile. Five node packages tsc out dist/, and packages/web uses Vite to produce packages/web/dist/ (the panel frontend artifact — the service needs it to have a page).

How to know it worked: packages/cli/dist/bin/archview.js and packages/web/dist/index.html both exist, and the following prints help:

pnpm archview --help

The first pnpm install will print a string of WARN Failed to create bin at ... ENOENT. The four packages' bin entries all point to dist/, and on first install dist/ doesn't exist yet, so pnpm can't create the links in node_modules/.bin/ (measured 13 on the most recent fresh GitHub clone; a previous run showed 12 — the count shifts slightly with pnpm version and store layout, so don't treat the count as a criterion; seeing these WARNs is normal). It's harmless: all commands below go through the repo-root npm script pnpm archview (equivalent to node packages/cli/dist/bin/archview.js), which doesn't depend on bin links. To get real archview / archview-skill commands: after pnpm build, run pnpm install once more — this time the links get created, and afterwards pnpm exec archview --version and pnpm exec archview-skill … both work. If you used the one-shot script (scripts/setup.ps1 / setup.sh), this step is already done for you (it installs again after build and verifies the archview-skill link on the spot) — without it, every pnpm exec archview-skill … command in the docs will report not recognized / Command "archview-skill" not found. We deliberately did not add a prepare script to auto-compile — cases that only want dependencies (CI cache, doc-only changes) shouldn't be forced to wait through a full Vite build.

⚠️ typecheck must run after build

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

The reverse always fails with a string of TS2307: Cannot find module '@archview/core' (or its subpath, e.g. '@archview/core/themes') or its corresponding type declarations. The reason: cross-package types go through each package's package.json exports → dist/*.d.ts, and dist/ is gitignored: no build, no .d.ts. The repo has no TS project references and no path aliases pointing types back to src, so this isn't a config oversight but an inherent property — strangers will always trip on it, just remember the order.

The same mechanism bites in daily development too: as soon as someone adds a new exported subpath in some package's src/, other packages won't typecheck until that package is rebuilt. When you see TS2307, first think "maybe I should build first".

Step 3: Connect the first repo to analyze

Still in the ArchView repo root. Replace the path with your own repo:

pnpm archview init d:/code/my-repo

What happens when it finishes (five steps, each idempotent — re-running just reports the current state):

1. Environment check (Node version, directory exists, is a git repo)

2. Creates a CodeGraph index .codegraph/codegraph.db in your repo (skipped if it exists)

3. Writes .archview/config.json (doesn't overwrite if it exists; only --force-config rewrites), and auto-prefills the module skeleton from oh-package.json5 / pnpm-workspace.yaml / Cargo.toml / go.mod

4. Idempotently appends a marked block to your repo's .gitignore (see Section 7)

5. Registers it in archview/workspaces.json (the workspace registry)

How to know it worked: it prints the workspace id and the next command at the end. Real run output (this time using ArchView's own source copy as the analyzed repo):

[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          # 随时看索引/图/摘要覆盖率/漂移

Common options: --id <id> (goes in the URL, only [a-z0-9][a-z0-9_-]* allowed), --name "display name", --skip-index, --telemetry-off, --json (machine-readable: workspace id, config/gitignore actions, module detection results, next command; the five steps' progress goes in the log field). Full list: pnpm archview init --help.

Step 4: Build panel data

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

What happens when it finishes: codegraph sync (brings the index up to date with disk) → build the graph → write .archview/graph.json and meta.json → generate .archview/briefs/*.json (structured briefs for LLMs) → confirm the .gitignore block once more.

How to know it worked: each step is prefixed with ✓, and the end gives node/edge/module counts and summary coverage. This real run:

  ✓ 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% coverage is a normal first result — semantic summaries are the agent's job, see Section 6.

When there are warnings (summaries accidentally placed in a subdirectory so none were read, config.json validation failure causing a full fallback, modules.labels keys that don't match any module), build pulls them out and reprints them with fixes. Warnings are not failures — the graph was indeed built, but those things didn't take effect.

To parse results in scripts/agents, use --json (far more useful than --quiet: it gives the full RebuildResult — steps / log / warnings / before / after / files / moduleStrategy / summaries / agentGuide — the same object as the panel's POST api/rebuild and MCP's archview_rebuild):

pnpm archview build my-repo --json

Re-check the live state anytime:

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

The status numbers come from the same function as the list page and MCP's archview_status — you won't see two different coverage numbers.

Step 5: Start the service and look at the graph

pnpm archview serve --open

What happens when it finishes: one process, one port serves all registered workspaces. Default 127.0.0.1:7420; if occupied, it walks upward automatically (up to 20); if --port is given explicitly, it won't change and fails on conflict. On startup it prints a one-time session token that all api/* endpoints validate.

How to know it worked: the banner looks like this (this real run, token truncated):

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

When --token <your string> is given, the last two lines change to "token set via --token, stable across restarts" plus a reminder not to commit it — the copy branches on "was --token explicitly given", so people who fixed a token don't think it didn't take effect.

The "panel artifacts" line must point to a real packages/web/dist — if the frontend wasn't built, the list page will explicitly show panel frontend not built, and you run pnpm --filter @archview/web build.

Each workspace on the list page is a card with four buttons: Open panel / Rebuild data / Copy agent prompt / Drift details.

This real run against the service (all with token):

Three ways to invoke, pick any

All commands above are written as pnpm archview … (the repo-root npm script), because it's available immediately after the first install and doesn't depend on bin links. Two other equivalent forms:

# ① 直接跑 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
pnpm exec archview-skill --help

Note ② only works inside this repo (the bin links live in the repo's node_modules/.bin/). To get these four commands into the global PATH you need the npm route (npm i -g archview), which isn't published yet — see Section 4.

6. Let the agent fill in the semantics

Once the graph is built, the nodes exist, but each node's summary is still just a deterministic fallback sentence (docstring / synthesized from the signature / <name> — <kind> in <path>). Turning them into human language is the agent's job.

Zero-install path (use this first)

1. On the list page click Copy agent prompt (equivalent to GET /w/<id>/api/prompt).

2. Paste the prompt into the AI that's editing that repo. The prompt is short; its main job is to point at <workspace>/.archview/AGENT-GUIDE.md in the workspace — a local file any tool can read.

3. AGENT-GUIDE.md needs to be generated once (build won't generate it automatically):

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

   This real run wrote 22 KB (22185 bytes), ten sections: iron rules, what this workspace looks like now, exactly which summaries are missing (listed nodeId by nodeId), stale summaries, your inputs (structured brief paths), guidance picked by detected language, output format and submission method, endpoints for triggering rebuild + read-only status confirmation, pre-delivery self-check list, report format. The prompt also carries this command, so the agent will run it itself.

   Once generated, you never have to touch it again: every subsequent rebuild (panel button / archview build / POST api/rebuild / MCP archview_rebuild) rewrites it in full (contract section 2 requires this, which is why it's in gitignore). The rebuild's steps show whether writeAgentGuide ran. Conversely, a rebuild won't create it for you if the file doesn't exist — we don't drop files into your workspace that you didn't ask for.

4. The agent writes summaries to .archview/summaries/<shard>.json per the guide. Shard name = module key with / replaced by _ (module packages/core → packages_core.json). This directory is flat; summaries written into subdirectories will never be read (you'll get a warning, but that round of work is wasted).

5. Rebuild: pnpm archview build, or click "Rebuild data" on the list page, or the agent itself does POST /w/<id>/api/rebuild?token=….

6. Semantics appear in the panel, and status coverage goes up.

Summary submission has server-side guardrails (defaults in packages/core/src/limits.ts): each item 30–140 characters, tags ≤6 and each ≤16 characters, single batch ≤200 items (over that, the entire batch is rejected — not a single item written to disk, no truncation), plus a "filler word list" that blocks nonsense like "responsible for handling related logic". The thresholds and word list have a single source of truth in @archview/core: MCP enforces with it, and the skill uses the same one to write the guide — so the manual and the enforcer can't disagree (this bug happened historically).

⚠️ The guardrails only auto-enforce on the MCP submission path. Writing summary shards directly as in step 4 above has nothing checking them (if you botch it, no error — it silently goes into the panel). So after writing files directly, run a self-check whose criteria come from exactly the same code as MCP (@archview/core's checkSummaryItem):

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

# 报 "archview-skill not found" 就是 bin 链接还没建（build 之后没再 install 过）。
# 两条出路，任选一条：
pnpm install                                     # 补上链接，之后上面那条就能用
node packages/skill/dist/bin/skill.js check-summaries --workspace d:/code/my-repo   # 不依赖链接

It reports orphan nodeIds, length violations, tags count/length/collisions with deterministic labels, filler-word hits, whether hash equals the current content_hash, plus whether summaries/ has subdirectories and whether the shard JSON is valid; exit code is non-zero when there are non-compliant items. Both the AGENT-GUIDE's method-A paragraph and the self-check checklist point to it.

Advanced path: install skill + MCP

Saves tokens (no need to read the full source; reading the structured briefs is enough), and submission gets structured validation.

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

Measured: skill hosts lists 7 confirmed hosts (kiro, claude, cursor, codex, opencode, gemini, copilot CLI) plus a batch of explicitly unsupported ones (paths vary by platform/version and can't be reproduced for verification — we don't guess, use /skill/download to place manually). skill verify measured "38 language guides, 10 framework guides, all present, non-placeholder, all with upstream attribution and an ArchView adaptation section".

Kiro first: skill installs to ~/.kiro/skills/archview, agent definition to ~/.kiro/agents/archview.json, MCP written to ~/.kiro/settings/mcp.json. The installer merges without overwriting (only touches the single mcpServers.archview key), leaves a .bak-<timestamp> before rewriting existing files, and uses junctions on Windows rather than symlinks. --dry-run prints exactly what would be written (measured: it writes not a single byte), and --home <dir> lets you point HOME elsewhere to test.

You can also copy the MCP config yourself without installing the skill: AGENT-GUIDE.md and api/prompt's meta.mcp.snippet both carry copy-paste-ready snippets pointing at the already-built packages/mcp/dist/bin/mcp.js in the same repo.

Six MCP tools, read-only + summary submission, no graph-writing tools at all:

Any host can download the skill package directly: GET /skill/download (tar.gz), or browse individual files in plaintext via GET /skill/* (e.g. /skill/SKILL.md).

7. Where data lives / what should be committed to git

This section decides whether your summaries survive a machine switch. All data lands in the analyzed repo, not the ArchView repo:

<你的仓库>/
  .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 的操作说明（每次生成整份重写，含时间戳）→ 不提交

There's only one criterion: commit what humans and LLMs accumulated; don't commit what tools can recompute.

• summaries/ holds a few hundred human/LLM-written Chinese summaries; regenerating them costs real tokens. It travels with the code — switching machines, people, or agents doesn't lose it.

• config.json is the team's consensus on "how modules are split, what the edge threshold is, what language to output."

• Everything else can be recomputed by archview build in under ten seconds. AGENT-GUIDE.md in particular should not be committed: it's fully rewritten on every rebuild and carries a timestamp, so committing it only creates conflicts.

archview init and every rebuild idempotently append this block to your repository's .gitignore (recognized by its markers; repeated runs don't append duplicates and don't touch your existing lines):

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

ArchView's own .gitignore

This repository's .gitignore excludes node_modules/, dist/ (the tsc output of the five packages and the Vite output of packages/web share the same name, so one entry covers both), dist-pack/, *.tsbuildinfo, .tmp/, .codegraph/ and *.db*, *.log, .env*, editor directories, and workspaces.json.

workspaces.json is the workspace registry; its contents are machine-local absolute paths (d:/code/my-repo) and therefore differ per machine — so in a freshly cloned repository this table is always empty. That's by design, not a gap. Create it yourself with archview init.

8. Acceptance scripts

Five scripts plus a set of unit tests, totaling over 150 assertions. Most follow the "start service → test → stop" pattern, leave no resident processes behind, and their writes to the checked workspace are reversible.

There is only one shared prerequisite: pnpm build. The three protocol-layer scripts (packages/server/scripts/acceptance.mjs, packages/mcp/scripts/acceptance.mjs, final-check.mjs) build a one-off fixture workspace themselves when no --workspace is given — you don't need to prepare any workspace; a stranger can clone the repo and run node final-check.mjs directly. Only packages/core/scripts/selfcheck.mjs still requires a real workspace directory.

In the "Measured" column below, two sets of numbers are given: fixture mode (default, see below) and --workspace <id> against a real workspace. ArkTS-specific assertions are explicitly marked "skipped / not applicable" on the fixture and on any non-ArkTS workspace; that doesn't count as a failure.

The line between "skipped" and "failed": skip only when a check's precondition doesn't hold on this workspace (no .ets nodes in the graph → ArkTS highlighting can't be checked; only 1 layer → inter-module edges can't exist). On a multi-module workspace, missing inter-module edges are a real bug and still reported as a failure (first check "Iron Rule 4 file-level edges" — if it's 0, there's no rollup, so no module-overview edges).

The default path doesn't touch a single byte of user data

The protocol-layer acceptance has two modes; the dividing line is whether --workspace is given:

• No --workspace (default): the script creates a one-off fixture repository in os.tmpdir() (scripts/lib/fixture-workspace.mjs: pnpm-workspace.yaml + 4 packages, real cross-module imports between packages via deep paths, a dozen or so .ts files containing class/function/interface, git init + one commit, summaries written per the guardrails with ≥ 2 entries per shard), runs the CodeGraph index, builds the graph twice, registers it in its own temporary registry, and deletes it when done. Your repository, your summaries, and the workspaces.json at the repo root are not touched, not even a single byte. Want to keep the fixture around to inspect it? Use --keep-fixture.

• --workspace <id> given: runs against that real workspace, and before starting, a boxed notice tells you explicitly what will be written this run. The mcp one will write to that workspace's .archview/ (moves one summary aside to create a gap, modifies graph.json, and actually runs a rebuild), with backup / per-file sha256 verification / copy-then-rename / end-of-run comparison — not a single guardrail is missing.

Why the default switched to fixture. The rationale "no stubbed data on purpose; only real numbers have value" holds only for packages/core/scripts/selfcheck.mjs — it validates the builder's semantics on real code (the 2253 auto-corrected warnings only surfaced on real data). But the server / mcp acceptance validates endpoint behavior and the tool protocol, and a small self-built repository is entirely sufficient for that. The cost, however, was real: these scripts delete summary entries, modify graph.json, and actually run a rebuild. The two previous rounds of patching (fixing the restore logic, removing the "first registry entry" default fallback, adding backup verification) never addressed the root cause — as long as the default target is the user's real repository, safety rests solely on "every line of backup code is correct," and an incident (a single restore() silently deleting 308 non-regenerable human summaries in a workspace while the script still reported PASS restored to original) already proved that assumption false.

rebuild's write surface is one step wider than .archview/, and the backup list follows. ensureGitignoreBlock touches the workspace root's .gitignore (the pre-rewrite original lands in .gitignore.archview-bak), so the mcp acceptance backup list now resolves relative to the workspace root: .archview/graph.json, .archview/meta.json, .archview/briefs, .archview/summaries, .archview/AGENT-GUIDE.md, .gitignore, .gitignore.archview-bak. Backup → per-file sha256 verification → restore → end-of-run comparison; these two root files travel the same path as .archview/. (Previously the list resolved relative to .archview/, so a --workspace acceptance run could rewrite the user's .gitignore while the guardrails knew nothing about it — they only looked at .archview/.) The server script also added backup / restore / byte-for-byte comparison for these two files in --workspace mode.

The only thing written outside the list is .codegraph/codegraph.db (codegraph sync modifies it): deliberately not restored — it's a regenerable index of tens to hundreds of MB, and the cost of copying it into backup far outweighs the benefit.

Lines inside the managed block are no longer silently removed. The block's semantics are whole-block replacement, so user rules written between # >>> archview >>> and # <<< archview <<< used to disappear on the next rebuild. Now ensureGitignoreBlock refuses to write (refused) when it finds lines inside the block that it didn't generate, reporting the line numbers and original text into the rebuild log, archview status, the list page, and archview_status warnings — without touching a single byte. Put your own rules outside the block.

Clear leftover environment variables before running

# 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 swaps which registry is read; ARCHVIEW_ACCEPT_WS / ARCHVIEW_MCP_WS / ARCHVIEW_CHECK_WS swap which workspace is tested. If one of them lingers in your shell, you get the most time-wasting illusion of all — "I didn't change any code, yet the acceptance numbers changed" — because you're already testing a different repository. The same logic applies to the command line: archview init|build|status --workspaces <file> can explicitly specify the registry; when running multiple registries in parallel, write it on every command rather than relying on environment variables to hold state.

Three pitfalls you only learn by stepping in them:

• selfcheck.mjs deletes the entire archview/.tmp/ directory on exit (unless --keep is given), not just its own subdirectory. Don't put anything you want to keep under .tmp/.

• Running the three protocol-layer scripts bare now builds a fixture instead of exit 1. The previous version printed usage and exited when no --workspace was given; now it uses a one-off fixture. So node packages/mcp/scripts/acceptance.mjs runs straight through — it targets a repository it built itself in os.tmpdir(), not yours.

• The MCP acceptance assertion "merge before writing into an existing shard" requires the chosen shard to contain other entries besides the gap. The script picks the first shard containing a file node (sorted by filename) to create the gap; if that shard happens to have only one summary (e.g. an _other module with a single file), the shard becomes empty after the gap is created, the assertion can't hold, and you get a 36/37. The fixture therefore deliberately writes summaries for every file node (≥ 2 per shard, enforced by a hard assertion in the generator). If you hit this failure on a real workspace, it's a workspace-shape problem, not a code problem: write summaries more completely, or make the first shard correspond to a multi-file module.

• In --workspace mode, the "idempotent rebuild" assertion requires the workspace's graph.json to be in sync with its source. The assertion compares node counts before and after the rebuild; if the repository's source changed since the last archview build, the rebuild naturally yields a different node count (measured: one workspace went 8972 → 8969 because a file was removed from the source), reporting a 36/37. This is a workspace-state problem: run archview build once before the acceptance. Fixture mode doesn't have this issue (the graph was just built).

9. Measured numbers (with provenance)

Numbers vary with repository content, so each entry states which repository, when, and under what criteria.

A. ArchView analyzing itself (re-run for this README; the analyzed target is a copy of the ArchView source, excluding node_modules/, dist/, .tmp/; Windows 11 / Node 22.20.0 / pnpm 10.28.2):

Numbers drift as the source changes: the same criteria on an earlier source version produced 899 nodes / 6 modules / 618 file-level edges / 6 module pairs with 148 aggregated edges. The differences all come from the source itself growing, not from the criteria changing — so don't treat these numbers as baselines to assert against; to assert, run the acceptance scripts.

B. AMCL (a HarmonyOS / ArkTS app on the author's machine, ohpm multi-module) — these numbers were observed read-only (read its already-built graph.json, never rebuilt it): 8972 nodes / 27864 edges / 11 modules / file-level edges 3216 / 308 summaries (covering 308 / 682, of which 71 framework components), module strategy ohpm. The same criteria on an earlier version gave 4277 nodes / 16124 edges / 10 modules / 304 summaries — the differences all come from the app itself growing. The summary length range in packages/core/src/limits.ts (40–80 characters) was measured from this batch of human summaries: min 36 / p50 57 / p95 78 / max 108 characters.

C. The one-off fixture repository used for acceptance (scripts/lib/fixture-workspace.mjs creates and deletes it on the fly, so these numbers are identical every run and can be used as a baseline): 4 pnpm packages / 13 .ts files / 20 files → CodeGraph index 0.8s → 49 nodes / 150 edges / 4 modules / file-level edges 43 / 13 summaries (covering 13/13), module strategy npmWorkspaces, module overview 6 module pairs with 26 aggregated edges, gitCommitHash is real (git init + one commit). From directory creation to graph ready: about 2.0s.

10. Known limitations / who shouldn't use it

An honest list. No hype.

• Single-machine tool, no multi-user model. It binds only to 127.0.0.1, and authentication is just a single process-level one-time session token. No accounts, no roles, no audit. Do not expose it to the public internet, and don't deploy it as a team service.

• Concurrent rebuilds are mutually exclusive, but failing to acquire the lock fails immediately rather than queueing. The three entry points (panel / archview build / MCP's archview_rebuild) share the same file lock .archview/.rebuild.lock. A second request immediately receives "another process is rebuilding (pid X, started at Y)", and the HTTP layer returns 409. Deliberately no queueing: queueing would make the browser spin forever, and two full codegraph sync runs queued back-to-back are of no value to you. Deadlock self-heals two ways — the lock-holding process on the same machine no longer exists, or more than 30 minutes have passed. The lock only protects rebuilds: it doesn't govern "someone hand-editing summaries/ while a rebuild is running" — in that case, the last write to disk wins.

• Writes to disk are atomic (temp file in the same directory + rename), covering graph.json / meta.json / briefs/ / summary shards / config.json / the registry. Power loss or a force-killed process won't leave half-written files. Summary shards have two additional guardrails: refuse to overwrite if the old content can't be parsed, and entry counts may only increase or stay flat (see CONTRACT.md section 5).

• /skill/download and /skill/* don't validate the token, but what they can read is whitelisted. They serve the skill docs shipped with the package (SKILL.md, languages/*.md, frameworks/*.md), which are meant to be picked up directly by any agent host, so the gate was deliberately left off. The browsable collection == the shipped collection; both share the same directory traversal, and that traversal excludes node_modules / dist / .git and only accepts real files — so symlinks are never in the collection. This was patched in: the old implementation only did "no .. + prefix check", which blocked classic traversal but not the symlink that pnpm places at packages/skill/node_modules/@archview/core pointing to packages/core (the link's textual path is a subpath of the skill directory, so the prefix check let it through all the way); in testing, GET /skill/node_modules/@archview/core/src/builder.ts returned 200 with 25 KB of source code — that was no longer "a trade-off of no token", it was unauthenticated arbitrary file read. Endpoints that read your code (api/graph.json, api/file, api/rebuild …) all validate the token.

• Summary quality depends entirely on your agent and the budget you give it. ArchView only guarantees "the topology is real" and "no empty platitudes"; it doesn't guarantee the summaries are well written. The guardrails can block nonsense from the empty-phrase vocabulary, but not a correct yet useless sentence.

• HarmonyOS / ArkTS is the only thoroughly validated scenario. ohpm module recognition, two-hop folding of the ArkUI component tree, and .ets highlighting were all polished on real ArkTS projects. Other languages only got structural-level validation (indexable, graph-buildable, modules recognizable, panel renderable), with no targeted framework inference, and the language guides only got documentation-level self-checks.

• Only systematically acceptance-tested on Windows. The macOS / Linux platform branches are written but untested.

• Not "one-click understanding of any repository". The first init on a large repo can take minutes (CodeGraph indexing), and summaries require the agent to run several rounds. It suits projects you plan to maintain long-term, not a ten-minute skim of an unfamiliar repo.

• Edges between layers in the module overview are undirected. The vendored aggregateLayerEdges merges A→B and B→A. Direction information still exists in the drill-down view.

• Cross-package imports that go through the "package-root barrel" can't be resolved, so the module overview will be missing edges. CodeGraph can resolve deep-path cross-package references (like import … from '../../server/src/rebuild.js'), but import { startServer } from '@archview/server' — i.e., one that points at the package entry and is forwarded by package.json's exports to the implementation file — can't resolve the target symbol, so that dependency doesn't enter the graph. This repo itself is the example: packages/cli/src/commands/serve.ts goes through the barrel, and importsFrom in its brief has no server; build.ts uses a deep path and resolves fine. If you see an edge missing from the module overview that you're certain exists, suspect this cause first (check that file's importsFrom in the brief: if it's empty or missing the target, this is it). This is an upstream CodeGraph resolution capability boundary, not a configurable option; we deliberately don't guess-patch this edge in the builder by package name — a guessed topology is just another form of LLM-written topology, violating iron rule 1. If you truly need to see it on the graph, change that import to a deep path (or wait for CodeGraph to support it).

• Edges are filtered by confidence / resolvedBy (default threshold 0.7, heuristic dropped). Without filtering, fake module dependencies purely matched by name would appear (a confidence: 0.3 fuzzy edge was observed in testing). Conversely, real dependencies that get filtered out are also invisible.

• CodeGraph telemetry is on by default, but whenever we invoke it on your behalf we always pass DO_NOT_TRACK=1 and CODEGRAPH_NO_UPDATE_CHECK=1 (written in runCodegraph, not optional). To also turn off its global switch: pnpm archview init … --telemetry-off.

• The source-browsing endpoint has hard limits: /w/<id>/api/file only allows filePath values that have appeared in the graph (whitelist), rejects .. and absolute paths, caps at 1 MB, and rejects binaries.

11. Architecture and Package Structure

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 + 补 bin 链接 + 自检。幂等，不碰你的仓库
  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)

"Six packages" and the Scope: all 7 workspace projects printed by pnpm install are the same thing. There are indeed six packages under packages/; the seventh is the repo root itself (archview — pnpm counts the workspace root as a project too, because it has its own package.json and scripts). This root project produces no dist/ and publishes nothing — it only carries scripts like pnpm build / pnpm typecheck / pnpm archview. Seeing 7 doesn't mean extra packages were installed.

cli doesn't reimplement any logic: build calls the server's rebuildOnce, status calls inspectWorkspace, serve calls startServer, and skill forwards verbatim to archview-skill. The reason is that the panel, MCP, and CLI must give the same number for the same thing — once a metric like coverage has two sources, the two numbers are guaranteed to diverge.

The data flow in one sentence:

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

12. License and Acknowledgments

ArchView itself is MIT (LICENSE). It stands on two projects that are also MIT:

• Understand-Anything — MIT, © Yuxiang Lin and Infinite Universe, Inc. The panel, graph schema, validators, skill, and language/framework guides all come from it. We fully vendored and modified it; every vendored file's header states the upstream path and what was changed.

• CodeGraph — MIT, © Colby McHenry. The source of all structural facts. Not vendored: we depend on the published npm package, only read its SQLite index, and invoke its bin.

Per-file provenance and the full attribution for both are in NOTICE. If this project is useful to you, please go star those two repositories first — ArchView just wires them together.

13. If You Want to Change Something

Start with CONTRACT.md (AGENTS.md is a one-page quick reference for agents, pointing to the same place). It's a hard-constraint foundation, not a style guide — the four iron rules (LLM doesn't write topology / summaries non-empty / layers cover all file nodes / file-level edges must roll up), the frozen node ID scheme, the graph schema, the module strategy, the service endpoint table, and the MCP tool surface are all in there, each with its "why" and "what happens if violated". Violating any of them is a design error.

Pay special attention to two things:

• The node ID scheme is frozen. Summary files use node IDs as keys; changing the IDs invalidates everyone's existing summary assets.

• The graph schema is exactly identical to the vendored UA schema, no additions, no removals. The panel is copied as-is; if the schema moves, the panel has to change. Private information goes through the node's passthrough fields (edges are not passthrough — extra fields get silently stripped, don't rely on them).

After changes, at minimum run:

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                    # 不给 --workspace = 自建一次性 fixture
node packages/mcp/scripts/acceptance.mjs                       # 同上；给了 --workspace 它才会写那个工作区
node final-check.mjs                                           # 同上；只读

Before running, clear any leftover ARCHVIEW_* environment variables (section 8 gives the commands for both shells), otherwise you might be testing a different repository.