ArchView

Zeichne für ein Repository ein Architekturdiagramm „wie hängen die Module voneinander ab" – die Topologie stammt vollständig aus der tree-sitter-Statikanalyse, die LLM schreibt nur für jeden Knoten eine Zusammenfassung in einem Satz. Dieselbe Grafik wird über MCP an den Agenten in deiner IDE exponiert.

Standalone, lokal, nur an 127.0.0.1 gebunden. Standardmäßig chinesische Oberfläche.

📦 Direkter Download (Windows, ohne Node-Installation, ohne Clone)

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

Nach der Installation hast du per Doppelklick ein eigenständiges Fenster, in dem sich genau das Panel der Webversion befindet. Node und CodeGraph sind enthalten, Installation nach %LOCALAPPDATA%\ArchView, keine Administratorrechte nötig.

Verwendung: Kopiere einen Absatz an deine KI und beantworte dann ein paar Fragen.

Beim Öffnen der Software ist das Panel leer, oben steht ein kopierbarer Prompt (mit dem echten Port und Token dieser Ausführung). Füge ihn der KI ein, die gerade an deinem Projekt arbeitet – Kiro / Claude Code / Cursor / Codex / opencode / Gemini CLI / Copilot CLI, egal welche, sie erkennt selbst, welche sie ist. Dann wird sie:

1. Sich mit diesem bereits laufenden Fenster verbinden (nicht klonen oder eine weitere Instanz installieren)

2. Erkennen, welcher Host sie ist, und das MCP konfigurieren (bevor sie deine Konfiguration anfasst, fragt sie dich)

3. In deinem Workspace rekursiv Kandidatenprojekte finden – mehrere Repositories/Unterprojekte in einem Ordner sind normal, sie zeigt dir die Liste und fragt, welche du anbinden willst (oder alle)

4. Registrieren + Index erstellen + Grafik erstellen (wenn der Index nicht existiert, erstellt sie ihn selbst, bei großen Repositories dauert das ein paar Minuten)

5. Dann fragt sie, ob du jetzt die semantischen Zusammenfassungen schreiben willst (dieser Schritt verbrennt Tokens, also muss gefragt werden)

Du musst nur ein paar Fragen beantworten und dann warten, bis die Grafik im Fenster erscheint. Die Vorgehensweise steht in CONNECT-FOR-AI.md (darauf verweist der Prompt in der Software), die Live-Version mit echtem Port und Token liegt zur Laufzeit unter /onboarding.md.

Keine Lust, dass die KI mitmischt? Das Formular unter dem Panel mit dem absoluten Pfad ausfüllen geht genauso – nach der Registrierung auf „Daten neu aufbauen" klicken, der Index wird von selbst erstellt.

⚠️ Keine Codesignatur, beim ersten Start wird SmartScreen einmal blockieren („Weitere Informationen" → „Trotzdem ausführen").

Related MCP server: rpg-encoder

Oder die Kommandozeilenversion installieren

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

Veröffentlicht auf npm: archview. Kein pnpm, kein Clone, kein Build nötig, die einzige harte Hürde ist Node ≥ 22.5 (node:sqlite). Beim ersten npm i wird zusätzlich das CodeGraph-Plattform-Subpaket heruntergeladen (das Windows-x64-Paket hat 248,7 MB und enthält eine eigene node.exe und native Module) – das ist beabsichtigt, wir packen es bewusst nicht in das Paket (es einzupacken hieße, dass Nutzer jeder Plattform alle sechs Varianten herunterladen).

Wie man die drei Wege wählt:

Alle drei teilen sich dieselbe Workspace-Registrierung (~/.archview/workspaces.json), du kannst sie also beliebig mischen und siehst alle dieselben Projekte. Details zur Desktop-Version unter Windows eigenständiges Fenster.

🚀 Lass die KI dir helfen, aus dem Quellcode zu installieren

Du willst die Kommandozeilenversion (CI, Skripte, MCP anbinden) oder den Code ändern – das kannst du komplett an die KI abgeben.

Kopiere den folgenden gesamten Absatz und füge ihn in einen beliebigen KI-Assistenten ein, der Webseiten lesen und Befehle ausführen kann (Kiro / Cursor / Claude Code / Codex …), ersetze <mein Projektpfad> durch das Repository, das du analysieren willst:

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

Im Drehbuch (SETUP-FOR-AI.md) gibt es für jede Phase ein „woran du erkennst, dass dieser Schritt geklappt hat", plus einen Abschnitt „häufige Fehler und Gegenmaßnahmen". Es ist so gestaltet, dass die KI es über die Raw-URL lesen kann, bevor sie klont.

Selbst machen: Spring zu Abschnitt 5, fünf Befehle zum Kopieren und Ausführen; oder die ersten beiden Schritte mit einem einzigen Befehl:

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

# macOS / Linux
bash scripts/setup.sh

Erst prüfen, ob es sich lohnt: Abschnitt 3 (warum es existiert) und Abschnitt 10 (bekannte Einschränkungen / für wen es nicht gedacht ist).

1. Welches Problem es löst

Angenommen, du schreibst allein eine HarmonyOS-App mit 9 ohpm-Modulen (das ist der Ursprung dieses Projekts). Du willst zwei Dinge:

1. Für dich selbst: eine Grafik, die du anklicken, in die du hineinzoomen kannst und auf der du siehst, „welche HARs entry abhängt, wer commons verwendet";

2. Für den Agenten: Assistenten in Cursor / Kiro / Claude Code sollen die Projektstruktur genau kennen, statt per grep zu raten.

Was es fertig gibt, fehlt jeweils die Hälfte:

ArchView verbindet beide Enden: CodeGraph liefert die Fakten, das UA-Panel liefert die Oberfläche, die LLM ergänzt nur die Semantik.

⚠️ Erst das lesen: Wie viele Module du bekommst, hängt von der Form deines Repositories ab

Die Grafik „wie hängen die Module voneinander ab" setzt mehrere Module voraus. Module sind nicht von uns geraten, sondern werden aus den Fakten in deinem Repository abgeleitet (eiserne Regel 1), also sehen die Ergebnisse je nach Repository-Form anders aus:

archview build gibt bei jedem Lauf eine Zeile aus, die erklärt, woher die Module kommen, z. B.:

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

archview status und die Listen-Seite des Panels zeigen denselben Satz. Wenn du nicht verstehst, warum deine Module so aufgeteilt sind, schau zuerst hierhin.

⚠️ Ein kontraintuitiver Punkt: modules.labels kann nur den bereits erkannten Modulen einen Anzeigenamen und eine Beschreibung geben, es kann keine Module definieren. Einen nicht existierenden Key hineinzuschreiben erzeugt kein Modul (build meldet dafür eine Warnung). Um zu ändern, „wie Module aufgeteilt werden", änderst du modules.strategy / modules.pathDepth.

⚠️ Wenn dein Repository große Verzeichnisse hat (Build-Artefakte, vorkompilierte Binaries, Container-Kontexte), schreib zuerst eine codegraph.json

Das sind zwei verschiedene Schalter, die an unterschiedlichen Stellen wirken – fast jeder stolpert beim ersten Mal darüber:

codegraph.json ist CodeGraphs Konfigurationsdatei, nicht unsere – ArchView erzeugt sie nie und ändert sie nie, also schreibt sie dir niemand, und sie wird auch nicht von uns überschrieben. So einfach ist die Form:

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

Nach dem Schreiben .codegraph/ löschen und neu aufbauen (der Index muss neu erstellt werden, damit exclude wirkt).

Die diesmal gemessenen Zahlen stammen genau daher – dasselbe HarmonyOS-Repository (281 .ets), der einzige Unterschied ist, ob diese Datei existiert:

Die letzte Zelle ist keine Übertreibung: graph.json wird per JSON.stringify auf die Platte geschrieben, und das V8-String-Limit liegt bei etwa 512 MiB, darüber wirft es ein Invalid string length. Es gibt also jetzt zwei Barrieren, die beide codegraph.json namentlich nennen: Wenn die Index-Dateianzahl zu groß wird, gibt es vor dem Grafikbau eine Warnung (damit du nicht vier Minuten umsonst wartest), und wenn die Grafik wirklich das Limit überschreitet, wird das Schreiben klar verweigert und das obige JSON als Lösung angegeben.

2. Eine Fusion zweier MIT-Projekte, hier wird nichts beschönigt

Beide sind MIT. Namensnennung und Datei-für-Datei-Herkunft in NOTICE, die eigene Lizenz dieses Projekts in LICENSE.

3. Warum es sich lohnt, allein zu existieren: Die LLM schreibt niemals Topologie

Das ist die einzige technische Grundlage dieses Projekts und die einzige Regel, die nicht verhandelbar ist:

Knoten und Kanten dürfen nur aus CodeGraphs tree-sitter-Ausgabe abgeleitet werden. Die LLM/der Agent darf nur summary und tags liefern, niemals Knoten, niemals Kanten, niemals die Modulaufteilung schreiben.

Der Unterschied ist konkret. Projekte, deren Topologie von der LLM erzeugt wird, müssen eine Reihe von Flick-Skripten schreiben, um nachzuputzen: IDs normalisieren, die nicht zusammenpassen, hängende Kanten verwerfen, die auf nicht existierende Knoten zeigen, Kanten mit falscher Richtung umdrehen. Diese Skripte selbst sind der Beweis, dass „die Struktur nicht vertrauenswürdig ist". ArchView braucht sie nicht – eine Kante existiert, weil tree-sitter diese Referenz im Quellcode wirklich geparst hat.

Die drei begleitenden Regeln (Abdeckung, Layer-Abdeckung, Hochrollen von Datei-Ebenen-Kanten) und alle Implementierungsbeschränkungen stehen in CONTRACT.md. In der MCP-Werkzeugfläche gibt es kein Werkzeug zum Schreiben von Grafiken.

4. Was du brauchst

CodeGraph muss nicht global installiert sein: Es ist eine normale npm-Abhängigkeit von packages/core, archview init löst sein bin aus node_modules auf und ruft es für dich auf (immer mit DO_NOT_TRACK=1 und CODEGRAPH_NO_UPDATE_CHECK=1).

Veröffentlichungsstatus: Beide Formen sind live

Die npm-Version wurde in einem komplett sauberen temporären Verzeichnis wirklich installiert und ausgeführt (aus dem Registry gezogen, nicht als lokales Tarball): npm i archview 8,8 Sekunden → archview init ruft wirklich CodeGraph auf und baut den Index → archview build baut die Grafik (Einzelpaket-Layout bohrt sich automatisch zu 2 Modulen nach unten) → archview-serve startet den Dienst, Grafik-Endpunkt und Anbindungs-Endpunkt liefern alle 200, prompt wird von @archview/skill gerendert statt vom eingebauten Fallback, die Alias-Isolation der beiden zod ist aktiv (mcp 3.25.76 / core 3.24.1).

Namen wie @archview/core werden nie auf npm erscheinen: Das sind interne Workspace-Paketnamen (die package.json aller sechs Pakete hat private: true), veröffentlicht wird nur das eine Paket archview. MCP-Konfigurationen sollten also nicht npx -y @archview/mcp schreiben (dieser Paketname existiert nicht), sondern npx -y -p archview archview-mcp, oder direkt das installierte bin archview-mcp verwenden – am besten ist es, auf den absoluten Pfad der real existierenden mcp.js auf dem Rechner zu zeigen (das Panel und GET /api/onboarding liefern genau diesen).

Wer eine neue Version veröffentlichen will (braucht npm login, oder ein Token mit publish-Berechtigung in ~/.npmrc; npm verlangt standardmäßig 2FA, beim interaktiven Veröffentlichen muss --otp=<6-stelliger Code> dazu):

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

Nur sehen wollen, was rausgeht:

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

Der Assembler ist scripts/build-npm-package.mjs, sein Dateikopf erklärt „warum Einzelpaket", „warum kein Bundler" und die vier Wächter (dist fehlt / dist älter als src / Versionsnummern uneinheitlich / Produkt-Selbsttest nicht bestanden → Paketbau wird verweigert, es wird kein leeres Paket oder alter Code verschickt).

Weiterhin aus dem Quellcode installierbar (Abschnitt 5): Wer Code ändern, Abnahmeskripte ausführen oder mit pnpm --filter ein einzelnes Paket bauen will, geht den Quellcode-Weg. Dieser Weg benötigt Node ≥ 22.5 und pnpm, beim ersten Mal muss man ein pnpm install + pnpm build abwarten (lokal gemessen: frisches Klonen install 5,0 s, build 17,1 s, Gesamtdauer 25,6 s; auf Maschinen mit kaltem pnpm-Store sind ein paar Minuten normal), Updates laufen über git pull + erneutes build (dist/ ist gitignored, pull tauscht nur den Quellcode, nicht die Build-Artefakte).

Der Skill-Installer schreibt die MCP-Konfiguration nach dem Prinzip „lokal tatsächlich vorhandene Datei zuerst": Bei der npm-Installationsform zeigt er auf node_modules/archview/packages/mcp/dist/bin/mcp.js, bei der Quellcode-Form auf packages/mcp/dist/bin/mcp.js, und nur wenn beides nicht verfügbar ist, fällt er auf npx -y -p archview archview-mcp zurück und erklärt im Text, dass dieser Weg eine veröffentlichte Paketversion voraussetzt. Als command wird der absolute Node-Pfad des aktuellen Prozesses verwendet statt eines nackten "node": Die Desktop-Version bringt ihre eigene Laufzeit mit und verlangt nicht, dass der Nutzer Node installiert, während ein nacktes "node" vom PATH des Hosts abhängt (der fehlen, Version 18 sein oder von nvm umgeschaltet worden sein kann).

Windows-Eigenfenster-Version (Installationspaket)

Neben der Kommandozeile gibt es noch eine Windows-Software mit eigenem Fenster – desktop/, ein Tauri-2-Shell. Veröffentlicht, direkt herunterladen:

⬇ ArchView_0.1.0_x64-setup.exe (35 MB, Windows 10/11 x64, Installation in %LOCALAPPDATA% ohne UAC)

Man kann es auch selbst bauen:

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

(benötigt Rust-Toolchain: rustup + MSVC. npm run build führt zuerst selbst scripts/stage-resources.mjs aus, das das npm-Einzelpaket und die Produktionsabhängigkeiten in bundle.resources ablegt; schlägt irgendein Schritt fehl, bricht der Build ab – es lässt sich also kein „unvollständiges Installationspaket" erzeugen.)

Es ist nicht etwas anderes als die Browser-Version: Im Fenster läuft genau das SPA aus packages/web/dist, der Shell spawnet nur dieselbe packages/server und räumt sie beim Beenden ab, die Rust-Seite enthält keine einzige Zeile Servicelogik (CONTRACT.md Abschnitt 9 hat das als harte Einschränkung festgenagelt). Panel, CLI, MCP und Desktop-Version liefern also für dieselbe Sache dieselbe Zahl.

Die installierte Software bringt Node und CodeGraph selbst mit, auf dem Rechner des Nutzers muss vorher nichts installiert sein:

Die Nutzung nach der Installation ist „Fenster öffnen → im Listenbereich den absoluten Pfad eines Repos eintragen → Neuaufbau klicken → Grafik ansehen", ganz ohne Terminal. Ohne Index führt der Neuaufbau selbst codegraph init aus (Vertrag Abschnitt 6) – ehrlich gesagt wäre es hier besser, „zuerst archview init ausführen" zu antworten, aber das ist ein Befehl, den nur ein Nutzer ohne Fenster ausführen kann.

Zwei Dinge, die noch nicht erledigt sind, klar gesagt: keine Codesignatur (beim ersten Start blockiert SmartScreen einmal, „Weitere Informationen → Trotzdem ausführen"), nur Windows x64 (das Paketskript holt das Plattform-Subpaket von CodeGraph je nach aktueller Plattform; für andere Plattformen muss man jeweils auf der Zielplattform bauen). Details siehe desktop/README.md.

Plattform-Status (nicht erwarten, dass wir alles auf allen Plattformen getestet haben)

• Windows – Hauptentwicklungs- und -verifikationsplattform. Alle Befehle und Ausgaben in dieser README stammen von echten Läufen auf Windows 11 (Build 26200) + PowerShell + Node 22.20.0 + pnpm 10.28.2. Die Skill-Installation nutzt Junctions, keine Administratorrechte nötig. Portbelegung prüfen: netstat -ano | findstr :7420.

• macOS / Linux – Alle plattformabhängigen Zweige im Code sind geschrieben (Browser öffnen mit open/xdg-open, Skill-Installation fällt auf Symlinks zurück), aber wir haben die Abnahme auf diesen beiden Plattformen nicht systematisch durchgeführt. Bei Problemen bitte ein Issue eröffnen, nicht als „offiziell unterstützt" behandeln.

• Zur Laufzeit erscheint eine Zeile ExperimentalWarning: SQLite is an experimental feature. Das ist der übliche Node-Hinweis zu node:sqlite, kein Fehler.

5. Erste Schritte: vom Holen des Codes bis zum Sehen der Grafik

Fünf Schritte. Bei jedem steht klar, wo man ihn ausführt, was danach passiert und woran man den Erfolg erkennt.

Die fünf Schritte nicht selbst gehen wollen? Den Eingangs-Prompt an deinen KI-Assistenten kleben, der erledigt die ersten drei Schritte gemäß SETUP-FOR-AI.md.

Schritt 1: Code holen

Auf npm gibt es das Paket noch nicht (siehe Abschnitt 4: Das Paket ist gebaut, aber noch nicht publiziert), also ist der erste Schritt, das Repo auf die Maschine zu holen. Nach der Veröffentlichung kann dieser ganze Abschnitt übersprungen werden – nach npm i -g archview geht es direkt mit Schritt 3 (archview init) los. Vier Wege, einen aussuchen:

A. git clone (bevorzugt) – danach kann man mit git pull aktualisieren.

# 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 herunterladen (ohne git) – Nachteil: Updates später nur durch erneutes Herunterladen und Überschreiben.

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

Das entpackte Verzeichnis heißt archview-main, unbedingt umbenennen (die beiden obigen Befehle haben das schon für dich erledigt).

C. gh repo clone (wenn GitHub CLI installiert ist)

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

D. Ein-Klick-Skript (macht Schritt 1 und 2 zusammen) – Code holen + pnpm install + pnpm build + nochmal pnpm install (um die bin-Links zu ergänzen) + Selbstprüfung. Zuerst mit A/B/C den Code holen, dann:

# 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

Noch nicht geklont und das Skript direkt aus der Cloud holen wollen? Erst herunterladen und ansehen, dann ausführen, nicht blind ein Remote-Skript durch eine Pipe ausführen:

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

Skriptparameter: -Dir/--dir <Pfad> (Standard ~/archview), -Ref/--ref <Branch oder Tag>, -SkipBuild/--skip-build, -Help/--help. Drei garantierte Verhaltensweisen: Verzeichnis existiert bereits und ist ein archview-Repo → git pull + erneutes build, kein doppeltes Klonen; existiert bereits, ist aber kein archview-Repo → Fehlermeldung und Beenden, das Verzeichnis wird kein einziges Byte angefasst; Vorprüfung fehlgeschlagen → ausführbarer nächster Schritt statt nacktem exit 1. Es macht bewusst kein archview init und startet keinen Dienst – das betrifft deine eigenen Repos und langlebige Prozesse, das musst du oder dein KI explizit entscheiden.

Woran man den Erfolg erkennt: Im Installationsverzeichnis existiert package.json und sein name ist archview. Bei git-basiertem Bezug kann man mit git rev-parse --short HEAD auch einen sha sehen.

Pfade möglichst ohne Leerzeichen – funktioniert zwar, aber danach muss man bei jedem Befehl die Pfadargumente in Anführungszeichen setzen.

Schritt 2: Abhängigkeiten installieren + bauen

Im Repo-Root (also dem Verzeichnis aus Schritt 1, z. B. ~/archview):

pnpm install
pnpm build

Was danach passiert: Die sechs Pakete kompilieren jeweils. Die fünf Node-Pakete erzeugen mit tsc ein dist/, packages/web erzeugt mit Vite packages/web/dist/ (das Panel-Frontend, der Dienst braucht es, um eine Seite zu haben).

Woran man den Erfolg erkennt: packages/cli/dist/bin/archview.js und packages/web/dist/index.html existieren beide, und der folgende Befehl gibt die Hilfe aus:

pnpm archview --help

Beim ersten pnpm install erscheint eine Reihe WARN Failed to create bin at ... ENOENT. Die bin der vier Pakete zeigen auf dist/, und beim ersten Install existiert dist/ noch nicht, also kann pnpm die Links in node_modules/.bin/ nicht anlegen (beim letzten frischen Klonen von GitHub gemessen: 13 Stück; bei einem früheren Lauf waren es 12 – die Anzahl variiert leicht mit pnpm-Version und Store-Layout, die Anzahl nicht als Kriterium nehmen, solche WARNs als normal ansehen). Es ist harmlos: Alle folgenden Befehle laufen über das npm-Skript pnpm archview im Repo-Root (äquivalent zu node packages/cli/dist/bin/archview.js) und hängen nicht an bin-Links. Echte archview / archview-skill-Befehle bekommen: nach pnpm build noch einmal pnpm install ausführen, diesmal werden die Links angelegt, danach funktionieren pnpm exec archview --version und pnpm exec archview-skill …. Beim Ein-Klick-Skript (scripts/setup.ps1 / setup.sh) ist dieser Schritt schon erledigt (es installiert nach dem build noch einmal und prüft sofort, ob der archview-skill-Link existiert) – ohne ihn melden alle pnpm exec archview-skill …-Befehle in der Doku not recognized / Command "archview-skill" not found. Wir haben bewusst kein prepare-Skript für die automatische Kompilierung eingebaut – wer nur Abhängigkeiten installieren will (CI-Cache, nur Doku-Änderungen), soll nicht gezwungen sein, auf einen vollständigen Vite-Build zu warten.

⚠️ typecheck muss nach build laufen

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

Umgekehrt schlägt es sicher fehl, mit einer Reihe TS2307: Cannot find module '@archview/core' (oder dessen Subpath, z. B. '@archview/core/themes') or its corresponding type declarations. Der Grund: Die paketübergreifenden Typen laufen über die exports der jeweiligen package.json → dist/*.d.ts, und dist/ ist gitignored: ohne build gibt es kein .d.ts. Das Repo hat keine TS-Project-References und keine Path-Aliase, die Typen auf src zurückzeigen lassen – das ist also keine Konfigurationslücke, sondern eine inhärente Eigenschaft. Fremde werden garantiert darüber stolpern, sich die Reihenfolge merken.

Derselbe Mechanismus beißt auch im Alltag: Sobald jemand in den src/ eines Pakets einen neuen Export-Subpath hinzufügt, typechecken die anderen Pakete nicht, bevor dieses Paket neu gebaut wurde. Bei TS2307 zuerst denken: „Sollte ich erst bauen?"

Schritt 3: Das erste zu analysierende Repo anbinden

Noch im ArchView-Repo-Root. Den Pfad durch dein eigenes Repo ersetzen:

pnpm archview init d:/code/my-repo

Was danach passiert (fünf Schritte, jeder idempotent, erneutes Ausführen sagt dir nur den Ist-Zustand):

1. Umgebungsprüfung (Node-Version, Verzeichnis existiert, ist es ein git-Repo)

2. Im deinem Repo einen CodeGraph-Index .codegraph/codegraph.db anlegen (überspringen, wenn vorhanden)

3. .archview/config.json schreiben (vorhandene nicht überschreiben; nur --force-config schreibt neu), und gemäß oh-package.json5 / pnpm-workspace.yaml / Cargo.toml / go.mod automatisch ein Modulgerüst vorbelegen

4. Idempotent einen markierten Block an die .gitignore deines Repos anhängen (Details in Abschnitt 7)

5. Es in archview/workspaces.json eintragen (Workspace-Registry)

Woran man den Erfolg erkennt: Am Ende werden Workspace-ID und nächster Befehl ausgegeben. Echter Lauf (diesmal wurde eine eigene Quellcode-Kopie von ArchView als analysiertes Repo verwendet):

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

Häufige Optionen: --id <id> (kommt in die URL, nur [a-z0-9][a-z0-9_-]* erlaubt), --name "Anzeigename", --skip-index, --telemetry-off, --json (maschinenlesbar: Workspace-ID, Konfig-/gitignore-Aktionen, Modulerkennungsergebnis, nächster Befehl; der Fortschritt der fünf Schritte steht im Feld log). Vollständige Liste: pnpm archview init --help.

Schritt 4: Paneldaten erzeugen

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

Was danach passiert: codegraph sync (Index auf den Stand der Platte bringen) → Grafik erzeugen → .archview/graph.json und meta.json schreiben → .archview/briefs/*.json generieren (strukturierte Briefings für LLMs) → den .gitignore-Block noch einmal bestätigen.

Woran man den Erfolg erkennt: Vor jedem Schritt steht ✓, am Ende werden Knoten/Kanten/Module und die Zusammenfassungs-Abdeckung ausgegeben. Dieser echte Lauf:

  ✓ 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%（分母＝文件节点＋框架组件）

Eine Abdeckung von 0 % ist ein normales Erstergebnis – semantische Zusammenfassungen muss der Agent schreiben, siehe Abschnitt 6.

Bei Warnungen (Zusammenfassungen versehentlich in Unterverzeichnisse gelegt, sodass keine einzige gelesen wurde; config.json-Validierung fehlgeschlagen und komplett zurückgefallen; Keys in modules.labels passen auf kein Modul) druckt build sie separat noch einmal aus und nennt die Lösung. Warnungen sind kein Fehler, die Grafik ist tatsächlich erzeugt, aber diese Dinge haben nicht gewirkt.

Zum Parsen des Ergebnisses in Skripten/Agenten --json verwenden (viel nützlicher als --quiet: Es liefert das vollständige RebuildResult – steps / log / warnings / before / after / files / moduleStrategy / summaries / agentGuide, dasselbe Objekt wie POST api/rebuild im Panel und archview_rebuild im MCP):

pnpm archview build my-repo --json

Jederzeit den Ist-Zustand nachprüfen:

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

Die Zahlen von status stammen aus derselben Funktion wie die Listenansicht und archview_status im MCP – es kann nicht zwei verschiedene Abdeckungswerte geben.

Schritt 5: Dienst starten und Grafik ansehen

pnpm archview serve --open

Was danach passiert: Ein Prozess, ein Port bedient alle registrierten Workspaces. Standard 127.0.0.1:7420; bei Belegung automatisch nach oben suchen (maximal 20), bei explizitem --port wird nicht gewechselt, bei Belegung Fehler. Beim Start wird ein einmaliges Session-Token ausgegeben, alle api/* prüfen es.

Woran man den Erfolg erkennt: Das Banner sieht so aus (dieser echte Lauf, Token gekürzt):

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

Bei --token <selbst gewählte Zeichenkette> ändern sich die letzten beiden Zeilen zu „Token per --token festgelegt, bleibt über Neustarts hinweg gleich" mit dem Hinweis, es nicht einzuchecken – der Text verzweigt nach „explizit --token angegeben oder nicht", damit jemand mit festem Token nicht denkt, es hätte nicht gegriffen.

Die Zeile „Panel-Artefakte" muss auf ein tatsächlich existierendes packages/web/dist zeigen – ohne gebautes Frontend zeigt die Listenansicht explizit Panel-Frontend nicht gebaut an, dann pnpm --filter @archview/web build ausführen.

Auf der Listenansicht hat jeder Workspace eine Karte mit vier Buttons: Panel öffnen / Daten neu aufbauen / Agent-Prompt kopieren / Drift-Details.

Dieser echte Test des Dienstes (alle mit Token):

Drei Aufrufarten, beliebig wählen

Alle obigen Befehle sind als pnpm archview … geschrieben (npm-Skript im Repo-Root), weil es direkt nach dem ersten Install verfügbar ist und nicht an bin-Links hängt. Zwei weitere äquivalente Schreibweisen:

# ① 直接跑 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

Achtung: ② funktioniert nur innerhalb dieses Repos (die bin-Links liegen in node_modules/.bin/ des Repos). Diese vier Befehle global in den PATH zu bekommen, geht nur über den npm-Weg (npm i -g archview), und der ist noch nicht publiziert – siehe Abschnitt 4.

6. Den Agenten die Semantik ergänzen lassen

Nach dem Erzeugen der Grafik sind die Knoten da, aber die summary jedes Knotens ist noch ein deterministischer Fallback-Satz (Docstring / aus der Signatur synthetisiert / <Name> – <kind> in <Pfad>). Sie in verständliche Sprache zu bringen, ist die Aufgabe des Agenten.

Null-Installations-Pfad (zuerst diesen verwenden)

1. Auf der Listenseite Agent-Prompt kopieren klicken (äquivalent zu GET /w/<id>/api/prompt).

2. Den Prompt an die KI kleben, die gerade das Repo bearbeitet. Der Prompt ist kurz, seine Hauptfunktion ist der Verweis auf <workspace>/.archview/AGENT-GUIDE.md im Workspace – eine lokale Datei, die jedes Werkzeug lesen kann.

3. AGENT-GUIDE.md muss einmal erzeugt werden (build erzeugt es nicht automatisch):

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

   Dieser echte Lauf schrieb 22 KB (22185 Bytes), zehn Abschnitte: eiserne Regeln, wie dieser Workspace gerade aussieht, welche Zusammenfassungen konkret fehlen (einzeln nach nodeId aufgelistet), abgelaufene Zusammenfassungen, deine Eingaben (Pfade zu den Struktur-Briefings), nach erkannter Sprache ausgewählte Anleitungen, Ausgabeformat und Einreichungsweg, Neuaufbau auslösen + Ist-Zustand schreibgeschützt bestätigen (Endpunkte), Selbstprüf-Checkliste vor der Abgabe, Berichtsformat. Der Prompt enthält diesen Befehl ebenfalls, der Agent führt ihn selbst aus.

   Nach der einmaligen Erzeugung muss man sich nicht mehr darum kümmern: Bei jedem späteren Neuaufbau (Panel-Button / archview build / POST api/rebuild / MCP archview_rebuild) wird es komplett neu geschrieben (Vertrag Abschnitt 2 verlangt das, deshalb steht es in der gitignore). In den steps des Neuaufbaus sieht man, ob der Schritt writeAgentGuide gelaufen ist. Umgekehrt: Wenn die Datei nicht existiert, erzeugt der Neuaufbau sie nicht für dich – wir legen keine Dateien in deinen Workspace, die du nicht angefordert hast.

4. Der Agent schreibt gemäß der Anleitung Zusammenfassungen nach .archview/summaries/<Shard>.json. Shard-Name = / im Modul-Key durch _ ersetzt (Modul packages/core → packages_core.json). Dieses Verzeichnis ist flach, Zusammenfassungen in Unterverzeichnissen werden keine einzige gelesen (es gibt eine Warnung, aber diese Runde war umsonst).

5. Neuaufbau: pnpm archview build, oder auf der Listenseite „Daten neu aufbauen" klicken, oder der Agent selbst POST /w/<id>/api/rebuild?token=….

6. Im Panel erscheint die Semantik, die Abdeckung von status steigt.

Die Einreichung von Zusammenfassungen hat serverseitige Schutzmechanismen (Standardwerte in packages/core/src/limits.ts): 30–140 Zeichen pro Eintrag, Tags ≤6 und jeweils ≤16 Zeichen, pro Batch ≤200 Einträge (bei Überschreitung wird der ganze Batch abgelehnt, kein einziger Eintrag wird geschrieben, nichts wird abgeschnitten), dazu eine „Phrasen-Liste" gegen Floskeln wie „zuständig für die Verarbeitung der zugehörigen Logik". Schwellenwerte und Wortliste existieren nur einmal, in @archview/core: Das MCP setzt sie durch, der Skill verwendet dieselbe für die Anleitung – damit Anleitung und Durchsetzer nicht auseinanderlaufen (diesen Bug gab es historisch).

⚠️ Die Schutzmechanismen greifen nur automatisch auf dem MCP-Einreichungsweg. Beim direkten Schreiben von Zusammenfassungs-Shards wie in Schritt 4 oben prüft nichts sie (wenn man es vermasselt, gibt es keinen Fehler, es landet still im Panel). Also nach dem direkten Dateischreiben eine Selbstprüfung laufen lassen, mit exakt derselben Codebasis wie das MCP (checkSummaryItem aus @archview/core):

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   # 不依赖链接

Meldet einzeln verwaiste nodeIds, Längenüberschreitungen, tags-Anzahl/-Länge/Kollision mit deterministischen Labels, Phrasen-Treffer, ob hash dem aktuellen content_hash entspricht, außerdem ob es Unterverzeichnisse unter summaries/ gibt und ob die Shard-JSONs gültig sind; bei nicht konformen Einträgen ist der Exit-Code ungleich 0. Abschnitt A der AGENT-GUIDE und die Selbstprüf-Checkliste verweisen beide darauf.

Fortgeschrittener Pfad: Skill + MCP installieren

Spart Tokens (man muss nicht den Quellcode durchlesen, die Struktur-Briefings reichen), und bei der Einreichung gibt es strukturierte Validierung.

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

Gemessen: skill hosts listet 7 bestätigte Hosts (kiro, claude, cursor, codex, opencode, gemini, copilot CLI) und eine Reihe explizit nicht unterstützter (Pfade variieren je nach Plattform/Version, nicht reproduzierbar verifizierbar, wir raten nicht, manuell über /skill/download ablegen). skill verify gemessen: „38 Sprach-Anleitungen, 10 Framework-Anleitungen, alle vorhanden, keine Platzhalter, alle mit Upstream-Angabe und ArchView-Anpassungsabschnitt".

Kiro zuerst: Skill wird nach ~/.kiro/skills/archview installiert, Agent-Definition ~/.kiro/agents/archview.json, MCP nach ~/.kiro/settings/mcp.json geschrieben. Der Installer führt zusammen, überschreibt nicht (fasst nur den einen Key mcpServers.archview an), legt vor dem Umschreiben vorhandener Dateien .bak-<Zeitstempel> an, unter Windows Junctions statt Symlinks. --dry-run gibt den zu schreibenden Inhalt unverändert aus (gemessen: es schreibt kein einziges Byte), --home <dir> kann HOME woanders hinlegen zum Testen.

Die MCP-Konfiguration kann man auch ohne Skill-Installation selbst abschreiben: In AGENT-GUIDE.md und im meta.mcp.snippet von api/prompt stehen direkt einfügbare Snippets, die auf das bereits gebaute packages/mcp/dist/bin/mcp.js im selben Repo zeigen.

Sechs MCP-Tools, schreibgeschützt + Zusammenfassungen einreichen, kein einziges Tool schreibt die Grafik:

Jeder Host kann das Skill-Paket direkt herunterladen: GET /skill/download (tar.gz), oder GET /skill/* zum Klartext-Lesen einzelner Dateien (z. B. /skill/SKILL.md).

7. Wo die Daten liegen / was in git eingecheckt werden sollte

Dieser Abschnitt entscheidet, ob deine Zusammenfassungen nach einem Maschinenwechsel noch da sind. Alle Daten liegen im analysierten Repo, nicht im 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 的操作说明（每次生成整份重写，含时间戳）→ 不提交

Es gibt nur ein Kriterium: Was Menschen und LLMs erarbeitet haben, wird eingecheckt; was Werkzeuge neu berechnen können, wird nicht eingecheckt.

• summaries/ enthält mehrere hundert von Menschen/LLMs verfasste chinesische Zusammenfassungen; eine Neugenerierung kostet echtes Geld an Tokens. Es folgt dem Code – egal ob Maschine, Person oder Agent gewechselt wird, es bleibt erhalten.

• config.json ist der Konsens des Teams darüber, „wie Module aufgeteilt werden, wie hoch der Kanten-Schwellenwert ist, in welcher Sprache ausgegeben wird".

• Der Rest lässt sich in zehn Sekunden mit archview build neu berechnen. Insbesondere AGENT-GUIDE.md sollte nicht eingecheckt werden: Es wird bei jedem Rebuild komplett neu geschrieben und mit Zeitstempel versehen; das Einchecken erzeugt nur Konflikte.

archview init und jeder rebuild hängen idempotent diesen Block an die .gitignore deines Repos an (Erkennung über Marker, bei wiederholter Ausführung kein doppeltes Anhängen, deine vorhandenen Zeilen bleiben unangetastet):

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

Die eigene .gitignore des ArchView-Repos

Die .gitignore dieses Repos schließt node_modules/, dist/ (die tsc-Artefakte der fünf Pakete und die Vite-Artefakte von packages/web heißen gleich, ein Eintrag deckt beide ab), dist-pack/, *.tsbuildinfo, .tmp/, .codegraph/ sowie *.db*, *.log, .env*, Editor-Verzeichnisse und workspaces.json aus.

workspaces.json ist die Workspace-Registrierung; der Inhalt sind lokale absolute Pfade (d:/code/my-repo), die je nach Maschine variieren – daher ist diese Tabelle in einem frisch geklonten Repo garantiert leer. Das ist Design, kein Fehler. Erzeuge sie selbst mit archview init.

8. Abnahmeskripte

Fünf Skripte plus eine Reihe von Unit-Tests, zusammen über hundertfünfzig Assertions. Die meisten folgen dem Muster „Dienst starten → testen → stoppen", hinterlassen keine dauerhaften Prozesse und die Schreibvorgänge in den geprüften Workspaces sind reversibel.

Die einzige gemeinsame Voraussetzung ist pnpm build. Die drei Skripte der Protokollebene (packages/server/scripts/acceptance.mjs, packages/mcp/scripts/acceptance.mjs, final-check.mjs) erstellen ohne --workspace selbst ein Einmal-Fixture-Workspace – du musst keinen Workspace vorbereiten; ein fremder Klon kann direkt node final-check.mjs ausführen. Nur packages/core/scripts/selfcheck.mjs benötigt weiterhin zwingend ein echtes Workspace-Verzeichnis.

Die Spalte „Praktisch getestet" unten enthält zwei Zahlensätze: Fixture-Modus (Standard, siehe unten) und --workspace <id> gegen ein echtes Workspace. ArkTS-spezifische Assertions werden im Fixture und auf jedem Nicht-ArkTS-Workspace explizit als „übersprungen / nicht zutreffend" markiert, das zählt nicht als Fehlschlag.

Die Grenze zwischen „übersprungen" und „fehlgeschlagen": Übersprungen wird nur, wenn die Voraussetzung einer Prüfung in diesem Workspace nicht gegeben ist (keine .ets-Knoten im Graphen → die ArkTS-Hervorhebung kann nicht geprüft werden; nur 1 Layer → Verbindungen zwischen Modulen können nicht entstehen). Fehlende Verbindungen zwischen Modulen in einem Multi-Modul-Workspace sind ein echter Bug und werden als Fehlschlag gemeldet (prüfe zuerst, ob „Eiserne Regel 4 Datei-Ebene-Kanten" 0 ist – ohne Hochrollen gibt es keine Modul-Übersichts-Verbindungen).

Der Standardpfad fasst kein einziges Byte der Benutzerdaten an

Die Abnahme der Protokollebene hat zwei Modi; die Grenze ist das Vorhandensein von --workspace:

• Ohne --workspace (Standard): Das Skript erstellt selbst in os.tmpdir() ein Einmal-Fixture-Repo (scripts/lib/fixture-workspace.mjs: pnpm-workspace.yaml + 4 Pakete, echte Cross-Modul-Imports über tiefe Pfade zwischen den Paketen, ein Dutzend .ts-Dateien mit class/function/interface, git init + ein Commit, nach den Leitplanken geschriebene Zusammenfassungen mit ≥ 2 Einträgen pro Fragment), führt die CodeGraph-Indizierung aus, baut den Graphen zweimal, registriert ihn in seiner eigenen temporären Registrierung und löscht ihn nach dem Lauf. Dein Repo, deine Zusammenfassungen, die workspaces.json im Repo-Root – kein einziges Byte wird angefasst. Wenn du das Fixture behalten möchtest: --keep-fixture.

• Mit --workspace <id>: Läuft gegen dieses echte Workspace; vor dem Start wird dir in einem Rahmen deutlich angezeigt, was diesmal geschrieben wird. Das mcp-Skript schreibt in das .archview/ dieses Workspace (verschiebt eine Zusammenfassung, um eine Lücke zu erzeugen, ändert graph.json, führt wirklich einen Rebuild aus), mit Backup / sha256-Prüfung pro Datei / erst Kopieren dann Rename / Vergleich am Ende – keine Leitplanke fehlt.

Warum standardmäßig das Fixture. Die Begründung „bewusst keine Dummy-Daten, nur echte Zahlen haben Wert" gilt nur für packages/core/scripts/selfcheck.mjs – es prüft die Semantik des Builders an echtem Code (die 2253 auto-corrected-Warnungen traten nur an echten Daten zutage). Die Abnahme von server/mcp prüft dagegen Endpunkt-Verhalten und Tool-Protokoll; ein selbst erstelltes kleines Repo reicht völlig aus. Der Preis ist real: Diese Skripte löschen Zusammenfassungseinträge, ändern graph.json und führen wirklich einen Rebuild aus. Die beiden früheren Reparaturrunden (Wiederherstellungslogik korrigiert, „erster Eintrag der Registrierung" als Standard-Fallback entfernt, Backup-Prüfung hinzugefügt) haben die Ursache nicht behoben – solange das Standardziel das echte Benutzer-Repo ist, hängt die Sicherheit ewig nur daran, dass „jede Zeile Backup-Code fehlerfrei geschrieben ist", und der Vorfall (ein restore() löschte stillschweigend 308 nicht regenerierbare manuelle Zusammenfassungen in einem Workspace, und das Skript meldete trotzdem PASS Wiederhergestellt) hat bewiesen, dass diese Annahme nicht trägt.

Die Schreibfläche von rebuild ist größer als .archview/; die Backup-Liste zieht mit. ensureGitignoreBlock fasst die .gitignore im Workspace-Root an (der Originaltext vor dem Umschreiben landet in .gitignore.archview-bak), daher wird die Backup-Liste der mcp-Abnahme jetzt relativ zum Workspace-Root aufgelöst: .archview/graph.json, .archview/meta.json, .archview/briefs, .archview/summaries, .archview/AGENT-GUIDE.md, .gitignore, .gitignore.archview-bak. Backup → sha256-Prüfung pro Datei → Wiederherstellung → Vergleich am Ende; diese beiden Root-Dateien laufen über denselben Pfad wie .archview/. (Zuvor wurde die Liste relativ zu .archview/ aufgelöst, sodass eine --workspace-Abnahme die .gitignore des Benutzers umschrieb, ohne dass die Leitplanke etwas davon wusste – sie sah nur .archview/.) Das server-Skript fügt im --workspace-Modus für diese beiden Dateien ebenfalls Backup / Wiederherstellung / Byte-für-Byte-Vergleich hinzu.

Das Einzige außerhalb der Liste, das geschrieben wird, ist .codegraph/codegraph.db (codegraph sync ändert es): bewusst nicht wiederhergestellt – ein regenerierbarer Index von einigen Dutzend bis einigen hundert MB; die Kosten des Kopierens ins Backup überwiegen den Nutzen bei weitem.

Zeilen innerhalb des verwalteten Blocks werden nicht mehr stillschweigend entfernt. Die Semantik des Blocks ist vollständiger Ersatz, daher verschwanden zuvor Benutzerregeln, die zwischen # >>> archview >>> und # <<< archview <<< geschrieben wurden, beim nächsten Rebuild. Jetzt verweigert ensureGitignoreBlock das Schreiben (refused), wenn es Zeilen im Block findet, die nicht von ihm selbst stammen, meldet Zeilennummer und Originaltext in die Rebuild-Logs, archview status, die Listenseite und die Warnings von archview_status – und fasst kein einziges Byte an. Eigene Regeln gehören außerhalb des Blocks.

Vor dem Lauf: Umgebungsvariablen-Reste bereinigen

# 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 tauscht aus, welche Registrierung gelesen wird; ARCHVIEW_ACCEPT_WS / ARCHVIEW_MCP_WS / ARCHVIEW_CHECK_WS tauschen aus, welches Workspace getestet wird. Wenn sie einmal in der Shell zurückbleiben, entsteht die zeitfressendste Täuschung: „Ich habe den Code nicht geändert, aber die Abnahme-Zahlen haben sich geändert" – weil du bereits ein anderes Repo testest. Dasselbe Prinzip gilt für die Kommandozeile: archview init|build|status --workspaces <file> kann die Registrierung explizit angeben; bei parallelen Multi-Registrierungen empfiehlt es sich, bei jedem Befehl anzugeben, statt den Zustand über Umgebungsvariablen zu merken.

Drei Fallstricke, die man erst kennt, wenn man hineingetreten ist:

• selfcheck.mjs löscht am Ende das gesamte archview/.tmp/ (außer mit --keep), nicht nur sein eigenes Unterverzeichnis. Lege nichts, das du behalten willst, unter .tmp/ ab.

• Die drei Protokollebenen-Skripte erstellen jetzt selbst ein Fixture, statt mit exit 1 zu enden. Die alte Version gab ohne --workspace die Nutzung aus und beendete sich; jetzt gilt „ohne Argument = Einmal-Fixture". node packages/mcp/scripts/acceptance.mjs läuft also direkt durch – es trifft das selbst erstellte Repo in os.tmpdir(), nicht deines.

• Die Assertion „beim Schreiben in ein vorhandenes Fragment erst zusammenführen, dann schreiben" in der MCP-Abnahme verlangt, dass das ausgewählte Fragment außer der Lücke noch weitere Einträge enthält. Das Skript sortiert nach Dateiname und nimmt das erste Fragment mit file-Knoten, um die Lücke zu erzeugen. Wenn dieses Fragment zufällig nur eine Zusammenfassung hat (z. B. ein _other-Modul mit nur einer Datei), ist das Fragment nach dem Erzeugen der Lücke leer, und diese Assertion kann nicht greifen – es wird ein 36/37 gemeldet. Das Fixture schreibt daher bewusst für jeden file-Knoten eine Zusammenfassung (jedes Fragment ≥ 2 Einträge, im Generator durch harte Assertions abgesichert). Wenn dieser Fehlschlag gegen ein echtes Workspace auftritt, ist es ein Formproblem des Workspace, kein Codeproblem: Schreibe die Zusammenfassungen vollständiger oder lass das erste Fragment einem Multi-Datei-Modul entsprechen.

• Im --workspace-Modus verlangt die Assertion „idempotenter Rebuild", dass die graph.json des Workspace mit seinem Quellcode synchron ist. Die Assertion vergleicht die Knotenzahl vor und nach dem Rebuild; wenn das Repo nach dem letzten archview build Quellcode geändert hat, ergibt der Rebuild natürlich eine andere Knotenzahl (praktisch: ein Workspace 8972 → 8969, weil eine Quelldatei fehlte), es wird ein 36/37 gemeldet. Das ist ein Workspace-Zustandsproblem: Führe einmal archview build aus, dann die Abnahme. Der Fixture-Modus hat dieses Problem nicht (der Graph ist frisch gebaut).

9. Praktisch gemessene Zahlen (mit Quellenangabe)

Die Zahlen variieren mit dem Repo-Inhalt, daher ist bei jedem Eintrag angegeben, welches Repo, wann, mit welcher Messweise.

A. ArchView analysiert sich selbst (für dieses README neu ausgeführt; analysiert wurde eine Kopie des ArchView-Quellcodes, ohne node_modules/, dist/, .tmp/; Windows 11 / Node 22.20.0 / pnpm 10.28.2):

Die Zahlen driften mit Quellcode-Änderungen: Dieselbe Messweise ergab auf einer früheren Quellcode-Version 899 Knoten / 6 Module / 618 Datei-Ebene-Kanten / 6 Modulpaare mit 148 aggregierten Kanten. Die Unterschiede stammen vollständig aus dem gewachsenen Quellcode, nicht aus einer geänderten Messweise – behandle diese Zahlen also nicht als Basiswerte für Assertions; für Assertions führe die Abnahmeskripte aus.

B. AMCL (eine HarmonyOS-/ArkTS-App auf der Maschine des Autors, ohpm-Multi-Modul) – diese Zahlen wurden nur lesend beobachtet (die bereits gebaute graph.json gelesen, nie neu aufgebaut): 8972 Knoten / 27864 Kanten / 11 Module / Datei-Ebene-Kanten 3216 / Zusammenfassungen 308 (Abdeckung 308 / 682, davon Framework-Komponenten 71), Modulstrategie ohpm. Auf einer früheren Version ergab dieselbe Messweise 4277 Knoten / 16124 Kanten / 10 Module / Zusammenfassungen 304 – die Unterschiede stammen vollständig aus dem gewachsenen Quellcode der App. Das Zusammenfassungslängen-Intervall (40–80 Zeichen) in packages/core/src/limits.ts wurde aus genau dieser Charge manueller Zusammenfassungen gemessen: min 36 / p50 57 / p95 78 / max 108 Zeichen.

C. Das Einmal-Fixture-Repo für die Abnahme (scripts/lib/fixture-workspace.mjs erstellt und löscht es bei jedem Lauf, daher sind diese Zahlen jedes Mal identisch und können als Basiswerte dienen): 4 pnpm-Pakete / 13 .ts-Dateien / 20 Dateien → CodeGraph-Index 0,8s → 49 Knoten / 150 Kanten / 4 Module / Datei-Ebene-Kanten 43 / Zusammenfassungen 13 (Abdeckung 13/13), Modulstrategie npmWorkspaces, Modul-Übersicht 6 Modulpaare mit 26 aggregierten Kanten, gitCommitHash ist echt (git init + ein Commit). Vom Erstellen des Verzeichnisses bis zum fertigen Graphen ca. 2,0s.

10. Bekannte Einschränkungen / Für wen es nicht gedacht ist

Eine ehrliche Liste. Keine Angeberei.

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

• 并发重建是互斥的，但拿不到锁会直接失败而不是排队。 三个入口（面板 / archview build / MCP 的 archview_rebuild）走同一把文件锁 .archview/.rebuild.lock。第二个请求会立刻收到「另一个进程正在重建（pid X，从 Y 开始）」，HTTP 那层回 409。刻意不排队：排队会让浏览器一直转圈，而两次全量 codegraph sync 排在一起对你没有价值。死锁自愈两条 —— 同机持锁进程已经不在，或超过 30 分钟。锁只保护重建：它不管「一边重建、一边有人手改 summaries/」，那种情况以最后写盘的为准。

• 写盘是原子的（同目录临时文件 + rename），覆盖 graph.json / meta.json / briefs/ / 摘要分片 / config.json / 注册表。断电或强杀进程不会留下半截文件。摘要分片另有两道护栏：读不懂旧内容就拒绝覆盖、条目数只允许增加或持平（详见 CONTRACT.md 第 5 节）。

• /skill/download 与 /skill/* 不校验 token，但能读到的东西是白名单化的。 它们吐的是随包发布的 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 源码 —— 那已经不是「无 token 的取舍」，是无鉴权的任意文件读。会读你代码的端点（api/graph.json、api/file、api/rebuild …）全部校验 token。

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

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

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

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

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

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

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

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

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

11. 架构与包结构

archview/
  package.json            pnpm workspace 根（scripts: build / typecheck / selfcheck / archview）
  LICENSE  NOTICE  README.md  CONTRACT.md
  AGENTS.md               仓库根路牌（多个 agent 工具会自动读它）：装 → SETUP-FOR-AI，改代码 → CONTRACT
  SETUP-FOR-AI.md         给 AI 的一次性安装剧本（阶段 + 成功判据 + 决策点 + 失败对策）
  scripts/setup.ps1       一键准备（Windows）：取代码 + install + build + 补 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)

「六个包」与 pnpm install 打的 Scope: all 7 workspace projects 说的是同一件事。 packages/ 下确实是六个包；第七个是仓库根自己（archview，pnpm 把 workspace 根也算一个 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、命令行对同一件事必须给同一个数 —— 覆盖率这种指标一旦有两个来源，两个数一定会分叉。

数据流一句话：

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

12. 许可与致谢

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

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

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

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

13. 想改点什么

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

尤其注意两处：

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

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

改完至少跑：

pnpm -r run build                      # 一定在 typecheck 之前
pnpm -r run typecheck
pnpm --filter @archview/server run test
node packages/core/scripts/selfcheck.mjs --workspace <你的工作区目录>   # 只有这个必须给真实工作区
node packages/server/scripts/acceptance.mjs                    # 不给 --workspace = 自建一次性 fixture
node packages/mcp/scripts/acceptance.mjs                       # 同上；给了 --workspace 它才会写那个工作区
node final-check.mjs                                           # 同上；只读

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