ArchView

リポジトリの「モジュール間の依存関係」を図にする —— トポロジはすべて tree-sitter の静的解析から取得し、LLM は各ノードに一言の要約を書くだけ。同じ図を MCP 経由で IDE のエージェントに公開する。

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

📦 直接ダウンロード（Windows、Node のインストール不要、clone 不要）

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

インストール後、ダブルクリックすると独立したウィンドウが開き、中身は Web 版と同じパネル。Node と CodeGraph が同梱されており、 %LOCALAPPDATA%\ArchView にインストールされる。管理者権限は不要。

使い方：AI に文章をコピーして渡し、いくつかの質問に答える。

ソフトを開くとパネルは空で、上部にコピー可能なプロンプト（実際のポートとトークン付き）がある。 それを、プロジェクトを編集中の AI に貼り付ける —— Kiro / Claude Code / Cursor / Codex / opencode / Gemini CLI / Copilot CLI のどれでもよい。AI は自分がどのホストかを認識する。その後、AI は：

1. すでに起動しているこのウィンドウに接続する（clone や再インストールはしない）

2. 自分がどのホストかを認識し、MCP を設定する（設定を変更する前に必ず確認を取る）

3. ワークスペース内で再帰的に候補プロジェクトを探す —— 1 つのフォルダに複数のリポジトリ/サブプロジェクトがあるのは普通。候補リストを表示し、どれに接続するか（または全部）を尋ねる

4. 登録 + インデックス作成 + グラフ作成（インデックスが存在しない場合は自動で作成、大規模リポジトリは数分かかる）

5. セマンティック要約を今すぐ書くかどうかを尋ねる（そのステップはトークンを消費するため、必ず確認が必要）

あなたはいくつかの質問に答えるだけで、あとはウィンドウに図が表示されるのを待つ。手順は CONNECT-FOR-AI.md（ソフト内のプロンプトはこれを指している）に記載。 実際のポートとトークンを含むライブ版は、実行時の /onboarding.md にある。

AI に介入させたくない？パネル下部のフォームに絶対パスを入力するだけでも同じ —— 登録後に「データ再構築」をクリックすれば、 インデックスは自動で作成される。

⚠️ コード署名はないため、初回実行時に SmartScreen に一度ブロックされる（「詳細情報」→「実行」）。

Related MCP server: rpg-encoder

またはコマンドライン版をインストール

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 .               # 不装，试一次就走

npm に公開済み：archview。pnpm 不要、clone 不要、build 不要。 唯一のハードルは Node ≥ 22.5（node:sqlite）。初回の npm i で CodeGraph のプラットフォーム別サブパッケージもダウンロードされる（Windows x64 版は 248.7 MB、node.exe とネイティブモジュール同梱）—— これは想定どおり。 意図的にパッケージに含めていない（含めると全プラットフォームのユーザーが 6 つ全部をダウンロードすることになるため）。

3 つの選択肢：

3 つは同じワークスペース登録ファイル（~/.archview/workspaces.json）を共有するので、混在して使っても 同じプロジェクト群が見える。デスクトップ版の詳細は Windows 独立ウィンドウ版 を参照。

🚀 AI にソースからのインストールを任せる

コマンドライン版（CI、スクリプト、MCP 接続）が欲しい場合、またはコードを変更したい場合 —— これはすべて 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 つのコマンドをコピペで実行できる。 または、最初の 2 ステップを 1 コマンドで：

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

# macOS / Linux
bash scripts/setup.sh

価値があるか先に判断したい場合：第 3 節（存在理由）と第 10 節（既知の制限 / 使うべきでない人）。

1. 解決する問題

1 人で 9 つの ohpm モジュールからなる HarmonyOS アプリを書いているとしよう（これが本プロジェクトのきっかけ）。欲しいものは 2 つ：

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

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

既存のツールはそれぞれ半分ずつ欠けている：

ArchView は両者をつなぐ：CodeGraph が事実を出し、UA のパネルが UI を出し、LLM はセマンティクスを補完するだけ。

⚠️ 最初にこれを見て：モジュール数はリポジトリの形状によって決まる

「モジュール間の依存関係」の図の前提は複数モジュール。モジュールは推測ではなく、リポジトリ内の 事実から派生する（鉄則 1）。したがって、リポジトリの形状によって結果が異なる：

archview build は毎回、モジュールの由来を 1 行で表示する。例：

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

archview status とパネルの一覧ページは同じ文言。モジュールがなぜこのように分割されているかわからないときは、まずこれを見る。

⚠️ 直感に反する点：modules.labels はすでに認識されているモジュールの表示名と説明を変更するだけで、 モジュールを定義することはできない。存在しないキーを書いてもモジュールは作られない（build はその際に警告を出す）。 「モジュールの分割方法」を変えたい場合は、modules.strategy / modules.pathDepth を変更する。

⚠️ リポジトリに大きなディレクトリ（ビルド成果物、プリコンパイル済みバイナリ、コンテナコンテキスト）がある場合、先に codegraph.json を書く

これは 2 つの異なるスイッチで、作用点が異なる。初めて使う人はほぼ必ず踏む：

codegraph.json は CodeGraph の設定ファイルであり、私たちのものではない —— ArchView はこれを生成も変更もしない。 したがって、誰かが代わりに書くことはなく、上書きされることもない。形状はこれだけ：

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

書き終えたら .codegraph/ を削除して再構築する（exclude を有効にするにはインデックスを再作成する必要がある）。

今回の実測値はこのようにして得られた —— 同じ HarmonyOS リポジトリ（281 個の .ets）、 唯一の違いはこのファイルの有無：

最後のセルは誇張ではない：graph.json は JSON.stringify で書き出すが、V8 の文字列上限は約 512 MiB。 超えると Invalid string length がスローされる。そのため現在は 2 つの防御があり、どちらも codegraph.json を指名する： インデックスファイル数が大きい場合はグラフ作成前に警告を出す（4 分待たせない）、グラフが本当に上限を超えた場合は書き込みを明確に拒否し、 上記の JSON を提示する。

2. 2 つの MIT プロジェクトの融合体（ここでは隠さない）

両者とも MIT。帰属とファイルごとの出典は NOTICE、本プロジェクト自身のライセンスは LICENSE。

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

これが本プロジェクトの唯一の技術的根拠であり、唯一妥協を許さないルール：

ノードとエッジは必ず CodeGraph の tree-sitter 出力から派生する。LLM/エージェントは summary と tags のみ提供でき、ノード、エッジ、モジュール分割を書くことは決してない。

違いは具体的。トポロジを LLM が生成するプロジェクトは、後始末のパッチスクリプトを大量に書く必要がある：ID の正規化、存在しないノードを指すダングリングエッジの破棄、方向が逆のエッジの反転。これらのスクリプト自体が「構造が信頼できない」ことの証拠。ArchView には不要 —— エッジが存在するのは、tree-sitter がソースコード内でその参照を実際に解析したから。

付随する 3 つのルール（カバレッジ、レイヤーカバレッジ、ファイルレベルエッジの集約）とすべての実装制約は CONTRACT.md に記載。MCP のツール面にはグラフを書くツールは存在しない。

4. 必要なもの

CodeGraph のグローバルインストールは不要：packages/core の通常の npm 依存であり、archview init が node_modules から bin を解決して代わりに呼び出す（常に DO_NOT_TRACK=1 と CODEGRAPH_NO_UPDATE_CHECK=1 を付ける）。

リリース状況：2 つの形態がともに公開済み

npm 版は完全にクリーンな一時ディレクトリで実際にインストール・実行された（ローカル tarball ではなく registry から取得）： npm i archview 8.8 秒 → archview init が実際に CodeGraph を呼び出してインデックス作成 → archview build でグラフ作成 （単一パッケージ構成は自動で 2 モジュールにドリルダウン）→ archview-serve でサービス起動、グラフエンドポイントと接続エンドポイントがすべて 200、 prompt は @archview/skill がレンダリング（組み込みのフォールバックではない）、2 つの zod のエイリアス分離が有効（mcp 3.25.76 / core 3.24.1）。

@archview/core などの名前は決して npm には公開されない：これらはリポジトリ内部の workspace パッケージ名 （6 つのパッケージの package.json はすべて private: true）。公開されるのは archview の 1 パッケージのみ。 したがって、MCP 設定に npx -y @archview/mcp と書いてはいけない（そのパッケージ名は存在しない）。npx -y -p archview archview-mcp と書くか、 インストールされた archview-mcp という bin を直接使う —— 最も良いのは、ローカルに実在する mcp.js の絶対パスを指すこと （パネルと GET /api/onboarding がそれを返す）。

新バージョンをリリースする人（npm login が必要、または ~/.npmrc に publish 権限のあるトークンが必要。 npm は現在デフォルトで 2FA を要求するため、対話的なリリースでは --otp=<6 桁コード> を付ける）：

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

何が公開されるかだけ見たい場合：

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

アセンブラは scripts/build-npm-package.mjs。ファイルヘッダに 「なぜ単一パッケージか」「なぜ bundler を使わないか」、および 4 つのガード（dist 欠落 / dist が src より古い / バージョン番号が不統一 / 成果物の自己チェック不合格 → すべてパッケージングを拒否、空パッケージや古いコードを公開しない）が明記されている。

仍然可以从源码装（第 5 节）：想改代码、想跑验收脚本、想用 pnpm --filter 单独构建某个包， 都走源码路。那条路需要 Node ≥ 22.5 与 pnpm，首次要等一次 pnpm install + pnpm build （本机实测：全新克隆 install 5.0s、build 17.1s，全流程 25.6s；pnpm store 冷的机器上几分钟正常）， 更新走 git pull + 重新 build（dist/ 是 gitignore 的，pull 只换源码不换产物）。

skill 安装器写 MCP 配置时按「本机真实存在的文件优先」：npm 装的形态下它指向 node_modules/archview/packages/mcp/dist/bin/mcp.js，源码形态下指向 packages/mcp/dist/bin/mcp.js，两边都拿不到才退回 npx -y -p archview archview-mcp 并在文案里说明那条要求包已发布。command 用的是当前进程的 node 绝对路径而不是裸 "node"：桌面版自带运行时、不要求用户装 Node，而裸 "node" 依赖宿主的 PATH （可能没有、可能是 18、可能被 nvm 切走）。

Windows 独立窗口版（安装包）

除了命令行，还有一个有自己窗口的 Windows 软件 —— desktop/，Tauri 2 的壳。 已发布，直接下载：

⬇ ArchView_0.1.0_x64-setup.exe （35 MB，Windows 10/11 x64，%LOCALAPPDATA% 安装免 UAC）

也可以自己打：

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

（需要 Rust 工具链：rustup + MSVC。npm run build 会自己先跑 scripts/stage-resources.mjs 把 npm 单包与生产依赖摆进 bundle.resources， 那一步任何环节失败都会中止构建 —— 所以打不出「缺东西的安装包」。）

它跟浏览器版不是两个东西：窗口里装的就是 packages/web/dist 那个 SPA， 壳只负责 spawn 同一份 packages/server 并在退出时收掉它，Rust 侧一行服务逻辑都没有 （CONTRACT.md 第 9 节把这条钉成了硬约束）。所以面板、CLI、MCP、 桌面版对同一件事给同一个数。

装出来的软件自带 Node 与 CodeGraph，用户机器上什么都不用先装：

装完的用法就是「开窗 → 在列表页填一个仓库的绝对路径 → 点重建 → 看图」，全程不碰终端。 没有索引时重建会自己代跑 codegraph init（契约第 6 节）—— 老实现在这里回一条 「先跑 archview init」，而那是一条只有窗口的用户没法执行的命令。

还没做的两件事，说清楚：没有代码签名（第一次运行会被 SmartScreen 拦一次， 「更多信息 → 仍要运行」）、只有 Windows x64（打包脚本按当前平台取 CodeGraph 的 平台子包，跨平台要在目标平台上各打一次）。细节见 desktop/README.md。

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

• 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. 上手：从取代码到看见图

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

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

第 1 步：取代码

npm 上现在还没有它（见第 4 节：包已经打好、还没 publish），所以第一步是把仓库弄到本机。 发布之后这一节整节都可以跳过 —— npm i -g archview 之后直接从第 3 步（archview init）开始。 四条路，挑一条：

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 + 再 pnpm install 一次（补 bin 链接）+ 自检。 先用 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 与 pnpm exec archview-skill … 都能用。 走一键脚本（scripts/setup.ps1 / setup.sh）的话这一步已经代你做了（它在 build 之后又 install 了一次，并当场验证 archview-skill 的链接在不在）—— 少了它，文档里所有 pnpm exec archview-skill … 的命令都会报 not recognized / Command "archview-skill" not found。 我们刻意没加 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、--json（机器可读：工作区 id、配置/gitignore 动作、模块识别结论、下一步命令；五步进度进 log 字段）。完整清单：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 节。

有告警时（摘要被误放进子目录导致一条都没读到、config.json 校验失败整份回退、modules.labels 里的 key 对不上任何模块）build 会把它们单独拎出来重打一遍并给出修法。告警不是失败，图确实建出来了，但那些东西没生效。

要在脚本/agent 里解析结果就用 --json（比 --quiet 有用得多：它给的是完整的 RebuildResult —— steps / log / warnings / before / after / files / moduleStrategy / summaries / agentGuide，与面板的 POST api/rebuild、MCP 的 archview_rebuild 是同一个对象）：

pnpm archview build my-repo --json

随时复查实况：

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

给了 --token <你定的串> 时最后两行改成「token 由 --token 指定，重启不变」并提醒别提交它 —— 文案按「有没有显式给 --token」分岔，免得固定了 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
pnpm exec archview-skill --help

注意 ② 只在这个仓库内有效（bin 链接在仓库的 node_modules/.bin/）。想让这四个命令进全局 PATH 就得走 npm 那条路（npm i -g archview），而它现在还没 publish —— 见第 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

# 报 "archview-skill not found" 就是 bin 链接还没建（build 之后没再 install 过）。
# 两条出路，任选一条：
pnpm install                                     # 补上链接，之后上面那条就能用
node packages/skill/dist/bin/skill.js 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 が書いた中国語の要約で、再生成には実費のトークンがかかる。コードと一緒に移動する——マシンを変えても、人を変えても、エージェントを変えても残る。

• 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/（5 つのパッケージの tsc 成果物と packages/web の Vite 成果物が同名なので 1 行でカバー）、dist-pack/、*.tsbuildinfo、.tmp/、.codegraph/ と *.db*、*.log、.env*、エディタのディレクトリ、そして workspaces.json を除外する。

workspaces.json はワークスペースレジストリで、内容は本機の絶対パス（d:/code/my-repo）であり、マシンごとに異なる——だから新しくクローンしたリポジトリではこのテーブルは必ず空になっている。これは設計であって欠落ではない。archview init で自分で作る。

8. 受け入れスクリプト

5 つのスクリプトと一組のユニットテストで、合わせて 150 以上のアサーションがある。ほとんどは「サービス起動 → テスト → 停止」で、常駐プロセスは残さず、検査対象ワークスペースへの書き込みは可逆的だ。

共通の前提条件は 1 つだけ：pnpm build。プロトコル層の 3 つのスクリプト（packages/server/scripts/acceptance.mjs、packages/mcp/scripts/acceptance.mjs、final-check.mjs）は --workspace を指定しなければ使い捨ての fixture ワークスペースを自前で作るので、ワークスペースを用意する必要はない——初めてクローンした状態でそのまま node final-check.mjs を実行できる。packages/core/scripts/selfcheck.mjs だけは、依然として実在のワークスペースディレクトリを渡す必要がある。

下の「実測」列には 2 組の数字を示す：fixture モード（デフォルト、下記参照）と --workspace <id> で実ワークスペースを対象にした場合。ArkTS 専用のアサーションは、fixture と ArkTS 以外のワークスペースでは明確に「スキップ / 該当なし」と表示され、失敗にはならない。

「スキップ」と「失敗」の境界線：ある検査の前提がこのワークスペースで成立しない場合にのみスキップする（図に .ets ノードがない → ArkTS ハイライトは検査しようがない；layer が 1 つだけ → モジュール間の接続線は成立しようがない）。マルチモジュールワークスペースでモジュール間の接続線がないのは本当のバグで、やはり失敗として報告される（まず「鉄律 4 ファイルレベル辺」が 0 でないか確認——ロールアップしなければモジュール概要の接続線は出ない）。

デフォルトのパスはユーザーデータに 1 バイトも触れない

プロトコル層の受け入れには 2 つのモードがあり、境界線は --workspace があるかどうかだ：

• --workspace を指定しない（デフォルト）：スクリプトが os.tmpdir() 内に使い捨ての fixture リポジトリを作る（scripts/lib/fixture-workspace.mjs：pnpm-workspace.yaml + 4 つのパッケージ、パッケージ間は深いパスを通る実際のクロスモジュール import、class/function/interface を含む十数個の .ts、git init + 1 回の commit、ガードレールに従って書かれた要約が各チャンクに ≥ 2 件）、CodeGraph インデックスを実行し、グラフを 2 回構築し、それ自身の一時レジストリに登録し、実行後に削除する。あなたのリポジトリも、あなたの要約も、リポジトリルートの workspaces.json も、1 バイトも触れない。 fixture を残して確認したい場合：--keep-fixture。

• --workspace <id> を指定：その実ワークスペースで実行し、開始前に枠で囲んで今回何を書き込むかを明示する。mcp のものはそのワークスペースの .archview/ に書き込む（要約を 1 件移動して欠落を作り、graph.json を変更し、実際に rebuild を 1 回実行する）。バックアップ / ファイルごとの sha256 検証 / 先にコピーしてから rename / 終了時の比較、ガードレールは 1 つも欠かさない。

なぜデフォルトを fixture に変えたのか。 「意図的にスタブデータを使わず、実データでこそ価値がある」という理由は、packages/core/scripts/selfcheck.mjs にのみ当てはまる——これは builder が実コード上でどう振る舞うかの意味論を検証するものだからだ（2253 件の auto-corrected 警告は実データで初めて顕在化した）。一方、server / mcp の受け入れが検証するのはエンドポイントの挙動とツールプロトコルであり、自前で小さなリポジトリを作れば十分だ。しかしコストは現実にあった：これらのスクリプトは要約エントリを削除し、graph.json を変更し、実際に rebuild を実行する。これまでの 2 回の修正（復元ロジックの修正、「レジストリの先頭エントリ」へのデフォルトフォールバックの廃止、バックアップ検証の追加）はどれも根本原因に手を付けていなかった——デフォルトの標的がユーザーの実リポジトリである限り、安全性は常に「すべてのバックアップコードが正しく書かれていること」だけに依存し、事故（ある restore() がワークスペース内の 308 件の再生成不能な人間の要約を黙って削除し、スクリプトは PASS 已恢复原样 と報告した）がこの前提が成り立たないことを証明した。

rebuild の書き込み面は .archview/ より一回り広く、バックアップ対象リストもそれに合わせて変わる。 ensureGitignoreBlock が触れるのはワークスペースルートの .gitignore（書き換え前の原文は .gitignore.archview-bak に残る）なので、mcp 受け入れのバックアップ対象リストは現在ワークスペースルート基準で解決される：.archview/graph.json、.archview/meta.json、.archview/briefs、.archview/summaries、.archview/AGENT-GUIDE.md、.gitignore、.gitignore.archview-bak。バックアップ → ファイルごとの sha256 検証 → 復元 → 終了時の比較、この 2 つのルートファイルも .archview/ と同じ経路を通る。（以前はリストが .archview/ 基準で解決されていたため、ある --workspace 受け入れがユーザーの .gitignore を書き換えたのにガードレールは何も知らなかった——.archview/ しか見ていなかったからだ。）server のスクリプトも --workspace モードではこの 2 つのファイルにバックアップ / 復元 / バイト単位の比較を追加している。

リスト外で唯一書き込まれるものは .codegraph/codegraph.db（codegraph sync がこれを変更する）：意図的に復元しない——数十〜数百 MB の再生成可能なインデックスで、バックアップにコピーするコストが利益をはるかに上回る。

管理ブロック内の行は黙って消されない。 ブロックの意味論はブロック全体の置換なので、# >>> archview >>> と # <<< archview <<< の間に書かれたユーザールールは、以前は次の rebuild で消えていた。現在は ensureGitignoreBlock がブロック内に自分が生成した行以外の行を発見すると書き込みを拒否し（refused）、行番号と原文を rebuild ログ、archview status、リストページと archview_status の warnings に報告し、1 バイトも変更しない。自分のルールはブロックの外に書く。

実行前に環境変数の残りをクリアする

# 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 が変えるのはどのワークスペースをテストするか。これらがシェルに 1 回残ると、「コードを変えていないのに受け入れの数字が変わった」という最も時間を食う錯覚が起きる——なぜならテストしているのがすでに別のリポジトリだからだ。同じ理屈はコマンドラインにも当てはまる：archview init|build|status --workspaces <file> でレジストリを明示的に指定でき、マルチレジストリを並行して使う場合は各コマンドに必ず書くことを推奨する。環境変数で状態を覚えるのはやめよう。

3 つの落とし穴、踏んで初めてわかる：

• selfcheck.mjs は終了時に archview/.tmp/ 全体を削除する（--keep を付けない限り）、自分自身のサブディレクトリだけではない。残したいものを .tmp/ の下に置かないこと。

• 3 つのプロトコル層スクリプトを裸で実行すると、今は fixture を自前で作るようになり、exit 1 しなくなった。 前の版は「--workspace を指定しなければ使用方法を表示して終了」だったが、今は「指定しなければ使い捨て fixture を使う」。だから node packages/mcp/scripts/acceptance.mjs はそのまま実行できる——対象は os.tmpdir() 内に自分で作ったリポジトリであって、あなたのものではない。

• MCP 受け入れの「既存チャンクへの書き込みはマージしてから書き込む」というアサーションは、選ばれたチャンクに欠落以外のエントリが他にもあることを要求する。 スクリプトはファイル名順で最初の file ノードを含むチャンクを選んで欠落を作るが、そのチャンクにたまたま要約が 1 件しかない場合（例えばファイルが 1 つだけの _other モジュール）、欠落を作るとチャンクが空になり、このアサーションは成立せず 36/37 と報告される。fixture はそのため意図的に各 file ノードに要約を書いている（各チャンク ≥ 2 件、生成器にハードアサーションで保証）。実ワークスペースでこの失敗に当たった場合はワークスペースの形状の問題であり、コードの問題ではない：要約をもう少し充実させるか、最初のチャンクがマルチファイルモジュールに対応するようにすればよい。

• --workspace モードの「冪等再構築」アサーションは、ワークスペースの graph.json がそのソースコードと同期していることを要求する。 アサーションは再構築前後のノード数を比較する；そのリポジトリが前回の archview build 以降にソースコードを変更していれば、再構築は当然異なるノード数になる（実測：あるワークスペースで 8972 → 8969、ソースコードからファイルが 1 つ減ったため）、36/37 と報告される。これはワークスペースの状態の問題：先に archview build を 1 回実行してから受け入れを実行する。fixture モードにはこの問題はない（グラフは作ったばかりだから）。

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 アプリ、ohpm マルチモジュール） —— これらの数字は読み取り専用で観測したもの（既に構築済みの graph.json を読んだだけで、再構築はしていない）：8972 ノード / 27864 辺 / 11 モジュール / ファイルレベル辺 3216 / 要約 308 件（カバレッジ 308 / 682、うちフレームワークコンポーネント 71）、モジュール戦略 ohpm。より前のバージョンで同じ口径は 4277 ノード / 16124 辺 / 10 モジュール / 要約 304——差異はすべてそのアプリ自体が大きくなったことによる。packages/core/src/limits.ts の要約長の区間（40–80 字）はこの人間の要約群から計測したもの：min 36 / p50 57 / p95 78 / max 108 字。

C. 受け入れ用の使い捨て fixture リポジトリ（scripts/lib/fixture-workspace.mjs がその場で作って削除するので、これらの数字は毎回同じで、基準値として使える）：4 つの pnpm パッケージ / 13 個の .ts / 20 ファイル → CodeGraph インデックス 0.8s → 49 ノード / 150 辺 / 4 モジュール / ファイルレベル辺 43 / 要約 13 件（カバレッジ 13/13）、モジュール戦略 npmWorkspaces、モジュール概要は 6 組のモジュール間で 26 本の集約辺、gitCommitHash は本物（git init + 1 回の commit）。ディレクトリ作成からグラフ準備完了まで約 2.0s。

10. 既知の制限 / 誰が使うべきでないか

正直なリスト。誇張はしない。

• スタンドアロンツールであり、マルチユーザーモデルはない。 127.0.0.1 にのみバインドし、認証はプロセスレベルの使い捨て session token のみ。アカウントもロールも監査もない。外部ネットワークに公開しないこと。チームサービスとしてデプロイもしないこと。

• 並行リビルドは排他だが、ロックを取得できない場合は待ち行列に入らず直接失敗する。 3つの入口（パネル / archview build / MCP の archview_rebuild）は同じファイルロック .archview/.rebuild.lock を使う。2番目のリクエストは即座に「別のプロセスがリビルド中（pid X、Y から開始）」を受け取り、HTTP 層では 409 を返す。意図的に待ち行列にしない：待ち行列にするとブラウザが延々と回り続けるし、2回の全量 codegraph sync を並べてもあなたに価値がない。デッドロックの自己回復は2つ —— 同一マシンでロックを保持するプロセスが既に存在しない場合、または30分を超えた場合。ロックはリビルドのみを保護する：「リビルド中に誰かが手で summaries/ を変更する」ケースは管轄外で、その場合は最後に書き込んだものが優先される。

• ディスクへの書き込みはアトミック（同一ディレクトリの一時ファイル + rename）で、graph.json / meta.json / briefs/ / サマリーシャード / config.json / レジストリを上書きする。停電や強制 kill でも中途半端なファイルは残らない。サマリーシャードにはさらに2つのガードレールがある：古い内容を読み取れなければ上書きを拒否、エントリ数は増加か横並びのみ許可（詳細は CONTRACT.md 第5節）。

• /skill/download と /skill/* はトークンを検証しないが、読み取れるものはホワイトリスト化されている。 これらが返すのはパッケージに同梱される skill ドキュメント（SKILL.md、languages/*.md、frameworks/*.md）で、そもそも任意の agent ホストが直接取得できるようにしているため、意図的にゲートを設けていない。閲覧可能なコレクション == 同梱公開コレクションで、両者は同じディレクトリ走査を共有し、その走査は node_modules / dist / .git を除外し、実ファイルのみを受け付ける —— つまりシンボリックリンクは一切コレクションに含まれない。これは後から補足された点：旧実装は「.. 禁止 + プレフィックス検査」のみで、従来型のトラバーサルは防げたが、pnpm が packages/skill/node_modules/@archview/core に置く packages/core を指すリンク（リンクのテキストパスは skill ディレクトリのサブパスなので、プレフィックス検査は素通り）は防げず、実測で GET /skill/node_modules/@archview/core/src/builder.ts が 200 と 25 KB のソースコードを返した —— それはもはや「トークンなしのトレードオフ」ではなく、認証なしの任意ファイル読み取りだ。あなたのコードを読むエンドポイント（api/graph.json、api/file、api/rebuild …）はすべてトークンを検証する。

• サマリーの品質は完全にあなたのエージェントと、それに与える予算次第。 ArchView が保証するのは「トポロジーが本物であること」と「空話を書かないこと」だけで、サマリーが上手く書けることは保証しない。ガードレールは空話ワードリストの無駄話は防げるが、正しくても役に立たない一文は防げない。

• HarmonyOS / ArkTS は唯一検証が十分なシナリオ。 ohpm モジュール認識、ArkUI コンポーネントツリーの2ホップ折りたたみ、.ets ハイライトはすべて実物の ArkTS プロジェクトで磨き上げた。他の言語は構造層の検証のみ（インデックス可能、グラフ構築可能、モジュール認識可能、パネル描画可能）で、対象特化のフレームワーク推論はなく、言語ガイドもドキュメント層の自己チェックのみ。

• Windows でのみ体系的に受け入れテストを実施。 macOS / Linux のプラットフォーム分岐は書いたが未テスト。

• 「ワンクリックで任意のリポジトリを理解する」ものではない。 初回 init で大規模リポジトリは数分かかる可能性があり（CodeGraph インデックス）、サマリーはエージェントが数ラウンド実行する必要がある。長期メンテナンスするプロジェクト向けであり、10分で知らないリポジトリを眺める用途には向かない。

• モジュール概要の 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 は深いパス経由で、解決されている。モジュール概要で確実に存在するはずのエッジが1本欠けているのを見たら、まずこの原因を疑う（ブリーフでそのファイルの 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 + 补 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)

「6つのパッケージ」と pnpm install が打つ Scope: all 7 workspace projects は同じことを言っている。 packages/ の下は確かに6つのパッケージ；7つ目はリポジトリルート自身（archview、pnpm はワークスペースルートも 1つの project と数える。独自の package.json と scripts を持つため）。ルートの project は dist/ を生成せず、公開もしない —— それは pnpm build / pnpm typecheck / pnpm archview といった script を担うだけ。7 を見ても余計なものが入っていると思わないこと。

cli はロジックを一切再実装しない：build は server の rebuildOnce を呼び、status は inspectWorkspace を呼び、serve は startServer を呼び、skill はそのまま archview-skill に転送する。理由はパネル、MCP、コマンドラインが同じ事柄に対して同じ数値を返さなければならないから —— カバレッジのような指標に2つのソースがあると、2つの数値は必ず分岐する。

データフローを一言で：

你的源码 ──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 の2つのプロジェクトの上に立っている：

• Understand-Anything — MIT, © Yuxiang Lin and Infinite Universe, Inc. パネル、グラフスキーマ、バリデータ、skill、言語/フレームワークガイドはすべてこれに由来する。全量 vendor して改造しており、vendored ファイルの各ヘッダーには上流パスと変更内容が書かれている。

• CodeGraph — MIT, © Colby McHenry. すべての構造的事実のソース。vendor していない：公開 npm パッケージに依存し、その SQLite インデックスを読むだけで、その bin を呼ぶ。

ファイルごとの出所と両者の完全なクレジットは NOTICE。このプロジェクトが役に立つなら、まず上記2つのリポジトリにスターを付けてほしい —— ArchView はそれらを繋いだだけだ。

13. 何かを変更したい場合

まず CONTRACT.md を読む（AGENTS.md はエージェント向けの1ページ速覧で、同じ場所を指している）。 これはハード制約の基盤であり、スタイルガイドではない —— 4つの鉄律（LLM はトポロジーを書かない / summary は非空 / layer は全ファイルノードをカバー / ファイルレベルエッジは必ずロールアップ）、凍結されたノード ID スキーム、グラフスキーマ、モジュール戦略、サービスエンドポイント表、MCP ツール面、すべてが含まれ、それぞれに「なぜ」と「違反すると何が起きるか」が書かれている。そのいずれかに違反することは設計ミスだ。

特に2箇所に注意：

• ノード ID スキームは凍結されている。 サマリーファイルはノード ID をキーに使うため、ID を変えることは全員の既存サマリー資産を無効化することに等しい。

• グラフスキーマは vendored の UA スキーマと完全に一致しており、増減なし。 パネルはそのまま流用しているため、スキーマを動かすとパネルも変更が必要になる。プライベート情報はノードの 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                    # 不给 --workspace = 自建一次性 fixture
node packages/mcp/scripts/acceptance.mjs                       # 同上；给了 --workspace 它才会写那个工作区
node final-check.mjs                                           # 同上；只读

実行前に ARCHVIEW_* 環境変数の残りをクリアする（第8節に2つのシェルのコマンドがある）。そうしないと別のリポジトリをテストしている可能性がある。