ArchView

「あるリポジトリについて、モジュール同士がどう依存し合っているかのアーキテクチャ図」を描く。トポロジはすべて tree-sitter による静的解析から得て、LLM は各ノードに1文の人間が読める要約を書くだけ。同じ図を MCP 経由で IDE 内の agent に公開する。

シングルマシン・ローカル・127.0.0.1 にのみバインド。デフォルトのUIは中国語です。

🚀 AI にインストールしてもらう（最速）

npm には公開されていないため、npx archview という方法はありません —— ソースコードから取得するしかありません。良い知らせは、その作業を丸ごと AI に任せられることです。

次のブロックを丸ごとコピーして、Web ページを読めてコマンドを実行できる 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 節 に進めば、5 ステップのコマンドをコピー＆ペーストだけで通せます。あるいは次の 1 コマンドで最初の 2 ステップを済ませられます：

# 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. それが解決する問題

あなたが1人で、9 個の ohpm モジュールからなる HarmonyOS アプリを書いているとします（それがこのプロジェクトの発端です）。欲しいものは2つです：

1. 自分用に：クリックしてドリルダウンでき、「entry がどの HAR に依存しているか」「commons は誰に使われているか」が見える図。

2. agent 用に：Cursor / Kiro / Claude Code 内のアシスタントがプロジェクト構造を正確に把握でき、grep で推測する必要がなくなる。

既存のものはどれも半分ずつ欠けています：

ArchView はその端と端をつなぎます：CodeGraph が事実、UA のパネルが UI、LLM は文意だけを補う。

2. これは2つの MIT プロジェクトの融合体であることを隠さない

どちらも MIT です。クレジットとファイル単位の出自は NOTICE にあります。このプロジェクト自身のライセンスは LICENSE になります。

3. なぜ単独で存在する価値があるのか：LLM は決してトポロジを書かない

これはこのプロジェクト唯一の技術的な根拠であり、唯一の一線挙げてはならない制約です：

ノードとエッジは必ず CodeGraph の tree-sitter 出力から導出する。LLM/agent は summary と tags だけを渡せばよく、ノードやエッジ、モジュール分割を書くことは決してない。

違いは具体的です。トポロジを LLM が生成するプロジェクトは、ID の正規化、存在しないノードを指すダングリングエッジの除去、辺の向きの正直化などの後始末スクリプトを何本も書かなければなりません。それらはまったくできない構造処理です。ArchView にはそれが必要ありません。エッジが存在するのは、tree-sitter がソース中に存在するリファレンスを実際にパースできたからです。

これに付随する3つ目のルール（カバレッジ、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 節）。これには3つのことを意味します：

• ホストマシンには Node >= 22.5 と pnpm が必要で、npx を 1 本実行するだけでは済みません。

• 初回は pnpm install + pnpm build の待ち時間があります（本機での実測：クリーンクローンから install が 5.0秒、build が 17.1秒、全体が 25.6秒。pnpm store が冷たいマシンでは install が数十秒かの?、何分でも正常です）。

• 更新は git pull + 再ビルド（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.2 で 0 + pnpm 10.28.2 で実動したものです。skill の導入はジャンクションを使い、管理者権限は不要。ポートの確認：netstat -解剖ano | findstr :7420。

• macOS / Linux —— コードにはプラットフォーム向けブランチは全部書いてあります（ブラウザを開くのは open / xdg-open、skill の設置は symlink に fall back）が、それらで体系的な検収はしていません。問題があれば issue を送ってください。「公式サポート」とは扱いないでください。

• 実行時に ExperimentalWarning: SQLite is an experimental feature が一行出ます。これは Node の node:sqlite に対する通常のメッセージで、エラーではありません。

5. 入門：ソースコードから図を表示するまで

5つのステップです。どこで実行するか、実行後に何が起こるか、成功したかどうかをすべて書いています。

この5ステップを自分で歩きたくない？ 第0節のプロンプト を AI アシスタントに渡せば、SETUP-FOR-AI.md に従って最初の 2 つまで済ませてくれます。

ステップ 1：コードを取得する

npm に無いので（第4節参照）、まずリポジトリをローカルに持ってきます。方法は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 ですが、上のコマンドは既に archview に名前を変えてくれます。

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 <ブランチ or tag>、-SkipBuild/--skip-build、-Help/--help。動作保証の3つ：ディレクトリが既存かつ archview リポジトリである場合は git pull + 再ビルドし、同じ clone はしない。既存だが** archview ではない**場合はエラー終了し、そのディレクトリは1バイトも変更しない。前提チェック失敗時は、^C 1だけではなく実行可能な次の手順を知らせる。意図的に archview init とサーバー起動は行いません。それは対象のリポジトリと常駐プロセスに関わるため、あなたかあなたの AI が明示的に決めることです。

成功の見分け方：インストール先の package.json が存在し、その name が archview になっていること。 git を使った場合は git rev-parse --short HEAD で sha を確認できます。

パスに空白を入れないようにご注意。動きますが、以後のすべてのコマンドのパス引数に引用符が必要になります。

ステップ 2：依存関係を導入してビルド

リポジトリのルート（つまりステップ1で取得したディレクトリ、~/archview など）で：

pnpm install
pnpm build

実行後の動き：6つのパッケージがそれぞれコンパイルされます。5つの node パッケージは dist/ に tsc で出力し、packages/web は Vite で packages/web/dist/ を作ります（UI のフロントエンドで、サーバーはこれを使ってページを表示します）。

成功の見分け方：packages/cli/dist/bin/archview.js と packages/web/dist/index.html が両方存在し、次がヘルプを表示することを確認：

pnpm archview --help

pnpm install の初回は WARN Failed to create bin at ... ENOENT が一連出ることがあります。 4つのパッケージの bin が dist/ を向いており、初回 install 時は dist/ がまだ存在しないため、pnpm は node_modules/.bin/ 内のリンクを作れないのです（直近の GitHub の完全クローンでは 13 件を達成。他の実行では12件でした。件数は pnpm バージョンとストアレイアウトで多少変動するので、件数を判断の材料にしないでください。この 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'（またはそのサブパスの '@archview/core/themes'）or its corresponding type declarations というエラーが出ます。理由は、パッケージ間の型が各パッケージの package.json の exports → dist/*.d.ts を通じており、dist/ は gitignore されているため：build しなければ .d.ts が存在しません。このリポジトリには TS project references も、src を指す path alias もありません。これは設定漏れではなく仕様です。初めて触れる人は必ず引っかかるので、順番を覚えておいてください。

同じ仕掛けは日常開発でも応答します。あるパッケージの src/ に新しい導出サブパスを追加した場合、そのパックージを再ビルドするまで他パッケージは typecheck を通過できません。TS2307 を見たらまず「ビルド不足を思い出」と考えることです。

ステップ 3：最初の解析対象リポジトリを登録する

ArchView リポジトリのルートから、パスを自分のリポジトリに置き換えます：

pnpm archview init d:/code/my-repo

実行後に起こること（5ステップ。各ステップは冪等で、再実行しても現在の状態が戻るだけ）：

1. 環境チェック（Node バージョン、ディレクトリ存在、git リポジトリか）

2. 自分のそのリポジトリに CodeGraph インデックス .codegraph/codegraph.db を作成（既にあれば skip）

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 節を参照してください。

警告が出た場合（例えば要約がサブディレクトリに散らばって1つも読まれなかった場合）、build はそれを抽出して表示し、対策をくれる。警告は失敗ではありません。たしかにグラフは作られましたが、その項目だけが適用されていません。

どこでも再確認できます：

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

status の数字と一覧ページ、MCP の archview_status は同じ関数を呼んでいるため、2つの異なるカバレッジ値が現れることはありません。

ステップ 5：サーバーを起動して図を見る

pnpm archview serve --open

実行後に起こること：1つのプロセス、1つのポートが登録済み全ワークスペースを提供します。デフォルトは 127.0.0.1:7420。他が使用中のときは自動的に上を探します（最大20 まで）。ただし --port を明示的に設定した場合は移りません。ビジーだったら失敗で終了です。起動時に一度だけセッショントークンを出力し、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 を実行してください。

リストページには「ワークごとに関カードと4つのボタンがあります：パネルを開く / データを再構築 / agent プロンプトをコピー / ドリフト詳細。

今回のサーバーに対する実測（すべてトークン付き）：

三つの呼び出し方法、どれでもどうぞ

上記のコマンドはすべて 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 はまだ、決定的フォーバック文（docから / シグネチャなどからの合成 / <名字> —— <路径> 中の <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_CONNECT_WS 换掉的是测哪个工作区。它们在 shell 里残留一次，就会出现「明明没改代码，验收数字却变了」这种最费时间的假象 —— 因为你测的其实是另一个仓库。同一个道理也适用于命令行：archview init|build|status --workspaces <file> 可以显式指定注册表，多注册表并行时建议每条命令都带上，别靠环境变量记状态。

三个坑，踩过才知道：

• selfcheck.mjs 结束时会把整个 selfcheck 的一个 .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 和你给它的预算。 我能保证「拓扑是真的」和「不许写空话」，不保证摘要写得好。护栏能拦住空话词表里的废话，拦不住一句正确但没用的话。

• 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][LICENSE]）。它站在两个同样是 MIT 的项目上：

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

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

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

13. 想改点什么

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

尤其注意两 cf：

• 变更 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 里的命令），否则你测的可能是另一个仓库。