ArchView

Eine Austauschzeichnung eines Repos – und wie die Module voneinander abhängen. Die Topologie stammt vollständig aus der tree-sitter-Statikanalyse, das LLM schreibt nur für jeden Knoten einen einzeiligen Klartext-Summary. Dasselbe Diagramm wird über MCP dem Agenten in deiner IDE bereitgestellt.

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

Wenn du es sofort ausprobieren willst: Spring zu Abschnitt 5, einviert...? Nein – nicht Einviertel. Vier Befehle, einfach kopieren und ausführen. Wenn du zuerst prüfen willst, ob es sich lohnt: Abschnitt 3 (warum es einen eigenständigen Daseinsgrund hat) und Abschnitt 10 (bekannte Einschränkungen / für wen es nicht gedacht ist).

1. Welches Problem es löst

Angenommen, du entwickstest allein eine HarmonyOS-Anwendung aus neun ohpm-Modulen – genau dafür gibt es das Projekt. Du willst zwei Dinge:

1. Für dich selbst: Ein Diagramm, das du anklicken und vertiefwindows kannst. „An welche HAR hängt entry, wer verwendet commons?“

2. Für den Agenten: Assistenten in Cursor / Kiro / Claude Code kennen die Projektstruktur genau; sie sollen nicht mit grep raten müssen.

Fertige Lösungen fehlt jeweils die andere Hälfte:

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

Related MCP server: SGraph MCP Server

2. Es ist die Fusion zweier MIT-Projekte, das verschweigen wir nicht

Beide Lizenzen sind MIT. Die Namensnennung und der Datei-Für-Quelle-Nachweis stehe in NOTICE; die Lizenz dieses Projekts liegt in SOURCE.

3. Warum es Daseinsberechtigt braucht: Das LLM schreibt nie die Topologie

Das ist die einzige technische Grundlage dieses Projekts und die einzige Regel, über die es nichts zu verhandeln gibt:

Knoten und Kanten können nur aus dem tree-sitter-Output von „CodeGraph“ abgeleitet werden. LLM/Agent [LLM/A**] liefert nur summary und tags, nicht Knoten, keine Kanten, nicht die Modulaufteilung.

Der Unterschied ist konkret. Projekte, deren Topologie von LLM erzeugt wird, benötigen ein weiteres Bündel von Flickskripts, um die Andocken zu könnte: IDs normalisieren, schwebende Kanten zu nicht existierenden Knoten entfernen, Kanten mit falscher Richtung drehen. Diese Skripts selbst sind der Beweis, dass die Struktur nicht vertrauenswürdig ist. ArchView braucht sie nicht – eine Kante existiert, weil tree-sitter diesen Referenz im Quelltext wirklich gefunden hat.

Die dazugehörigen Regeln (Abdeckung, Layer-Abdeckung, das Hochrollen von Datei-Ebenen in die Modul-Kant) und die Implementierbarkeitsbindungenstehen in CONTRACT.md. Im MCP-Werkzeugraum gibt es keine Werkzeuge, die ein Diagram schreiben.

4. Voraussetzungen

Eine globale Installation von CodeGraph ist nicht nötig: Es ist eine gewöhnliche npm-Abhängigkeit von packages/core; archview init löst sein bin aus node_modules auf und ruft es für dich auf (und übergibt immer DO_NOT_TRACK=1 und CODEGRAPH_NO_UPDATE_CHECK=1).

Plattform-Realität (erwarte nicht, dass wir alles getestet haben)

• Windows – Hauptentwicklungs- und Validierungsplattform. Alle Befehle und Ausgaben in diesem README stammen aus einer echten Ausführung unter Windows 11 (Build 26200) + PowerShell + Node 22.20.0 + pnpm 10.28.2. Die Skill-Installation nutzt "junction" und keine Administrator-Rechte. Belegte Ports: netstat -ano | findstr :7420.

• macOS / Linux – Im Code sind alle plattformbezogenen Zweige vorhanden (Browseröffnen via open/xdg-open, Skill-Installation fällt auf Symlinks zurück), aber wir haben auf diesen Plattformen nicht systematisch akzeptiert. Bei Problemen bitte Issue öffnen, nicht als „offiziell unterstützt“ ansehen.

• Beim Lauf erscheint eine Zeile ExperimentalWarning: SQLite is an experimental feature. Das ist nur eine normale Node-Hinweis auf `node:sqlite identify thecause. Hinweis – kein Fehler.

5. Erste Schritte: vom Klonen bis zum sichtbaren Diagramm

Vier Schritte. Zu jedem ist festgehalten, wo es ausgeführt wird, was nachher passiert, wie sicher man den Erfolg wiedererkennt.

Schritt 1: Abhängigkeiten installieren + bauen

Im Repository-Root (also in archview/):

pnpm install
pnpm build

Was dann passiert: Sechs Pakete werden kompiliert. Fünf Node-Pakete erzeugen dist/ per tsc, und packages/web erzeeren packages/web/dist/ (die Frontend-Leistung des Panels, ohne die es keine Seite gibt).

Wie du den Erfolg erkennst: Es existieren packages/cli/dist/bin/archview.js und packages/web/dist/index.html, und die folgende Zeile gibt die Hilfe aus:

pnpm archview --help

pnpm install spuckt bei der ersten Ausführung eine Reihe von WARN Failed to create bin at ... ENOENT aus. Die bin-Einträge der vier Pakete zeigen auf dist/. Beim ersten Install existiert dist/ noch nicht, also kann pnpm im node_modules/.bin/ keine Links erstellen (Autor hat für eine saubere Clonewup auf 12 Notices getestet). Das ist eher unnötig: Alle Befehle unten nutzen die Installationsender pnpm archview im Root (entspricht node packages/cli/dist/bin/archview.js), die von den bin-Links nicht abhängt. Für die echten archview / archview-skill-Kommandos: Nach pnpm build anderenmal pnpm install ausführen; dieses Mal werden die Links erstellt, und dann kan man auch pnpm exec archview --version nutzen. Wir haben bewusst kein prepare-Skript eingebaut, das automatisch kompiliert – jemand, der nur Abhängigkeiten installieren möchte (z. B. CI-Cache oder Review), soll nicht gezwungen sein, einen kompletten Vite-Build zu halten.

Achtung:

⚠️ typecheck muss nach build laufen

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

In umgekehrter Reihenfolge schlägt er mit einer Reihe von TS2307: Cannot find module units immer fehl (oder der Unterpfad, z.B. '@archview/core/themes') or its corresponding type declarations. Ursache: Typen sind in der Paketgrenze mit exports in package.json auf dist/*.d.ts verweisen, und dist/ ist in .gitignore: Ohne Build gibt es kein .d.ts. Das Repo hat weder TypeScript-Projekt-References noch Pfad-Aliase, die die Typen nach src lenken. Es ist also keine Konfigurationslücke, sondern ein bewusster Zustand – jede neue Person wird hängenbleiben; man lernt die Reihenfolge vor wie seine Westentasche.

Denselben Mechanismus spürt man auch im Alltag: Sobald jemand in den src eines Paketes einen Exportounterpfad neu aufnimmt, sind die anderen Pakete über uselbem Typencheck blockiert, bis jenes Paket wieder gebaut wurde. Beim Blick auf TS2307 überlege zuerst: „Muss ich das da stattdessen erst bauen?“

Schritt 2: Das erste zu analysierende Repo anschließen

Immer noch in archview/. Ersetze den Pfad mit deinem eigenen Repo:

pnpm archview init d:/code/my-repo

Fünfsatürlich: (fünf Schritte, alle idempotistik – wieder laufen lässt und nur den Ist-Zustand erzählt)

1. Laufzeituntersuchung (Node-Version, Verzeichnis existiert, ist es ein git-Repo?)

2. Lege in deinem Repo den CodeGraph-Index .codegraph/codegraph.db an (überspringen, wird erneut bereits)

3. Schreibt .archview/config.json (vorhandene Datei wird nicht überschreiben; --force-config erzwingt sie) und füllt automatisch ein Modulskelett basierend auf oh-packagejson5 / pnpm-workspace.yaml / Cargo.toml / go.mod

4. Fügt in deinem Repo in .gitignore einen markierten Block idempotent an (Details siehe Abschnitt 7)

5. Trägt es in To:…? NE struct. workspace.json / in workspaces.json – die Works-endliche Registry

Wie kommt zu den zurück: Am Ende werden „workspace id“ und der nächste Befehl ausgegeben. Tatsächlicher Lauf (als Ziel wird diesmal die eigene Quellkopie von der ArchView 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äufig genutzte Optionen: --id <id> (geht in die URL, erlaubt [a-z0-9][a-z0-9_-]*), --name "Anzeigename", --skip-index, --telemetry-off. Volle Liste: pnpm archived init --help.

Schritt 3: Bildschirm-Daten erzeugen

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

Nach dem Durchlauf: codegraph sync (Index pos auf dem Datenstand) → Diagramm erstellen → .archview/graph.json und meta.json schreiben → .archview/briefs/*.json generieren (Struktur-Bries für das LLM) → noch einmal den .gitignore-Block prüfen.

So erkennt man den Erfolg: Jeder Schritt erscheint mit „✓“ davor; am Ende werden Node/Edge/Modul und Summary-Abdeckung gezeigt. Aktueller 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%（分母＝文件节点＋框架组件）

0% Abdeckung ist beim ersten Aufruf normal – die Zusammenfassung liefert der Agent (siehe Abschnitt 6).

Wenn Warnungen auftreten (etwa die Summary-Ergebnisse in einem Unterordner, sodass keine gelesen wird), listet build sie extra und nennt die Abhilfe. Eine Warnung ist kein Fehler – das Diagramm ist trotzdem gebaut, nur bestimmte Teile haben keine.

Aktuellen Zustand kann jedezeit abgerufen werden:

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

Die Werte von status und die Liste ang_weisungen archview_status stammen aus derselben Funktion – es gibt nicht zwei verschiedenne Abdeckungswerte.

Schritt 4: Server starten und das Diagramm sehen

pnpm archview serve --open

Großer Effekt: Ein Prozess, ein Portdurchläuft alle registrierten Workspaces. Standard is 127.0.0.1:7420; wenn der Port schon belegt ist, wird automatisch nach oben gezählt (maximal 20A: Z19). Mit einem explizitiol --port wechselt er nicht – dann schlägt fehl, wenn der Port schon belegt. Der Start gibt ein einmaliges Sessiontgets aus; alle api/* prüfen es.

So kommt man und du heraus. Das Banner ist so (tatsächlicher aktueller Lauf, Token ausgeschnitten):

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

Die Zeile „Panelausgabe“ muss auf ein erreichbares packages/web/dist zeigen können: Wenn das Panel-Viren nicht gebaut ist, zeigt die Systemliste eine Spezielle Hinweis „Panelformat“ nicht gebaut und man benutzt pnpm --filter @archview/web build.

Auf der Webübersicht hat das Schaufenster pro Workspace eine Karte: vier Schaltsenförderer, Diagramm, Heuchen der ctw?? Hmm. „Aufschaltung / Daten neu bauen / Agent-Prompt kopieren / Driftdetails.”

Fertigstellung nach Squeeze (teilbar mit vorgehaltenem Token):

Falls du nicht über den pnpm-Script-Mechanismus gehst:

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

6. Den Agenten die Semantik nachliefern

Wenn du das Diagram gebaut hast, sind die Knoten vorhanden. Aber summary jener Knoten ist nur noch die deterministische Fallback-Zusammenfassung (enten der DOC-String / gebaut aus Signatur / <名字> —— <路径> 中的 <kind>). Das zu ersetzen durch einen verständlicher Satz ist Aufgabe des Agents.

Weg ohne Installation (iziemeist damit beginnen)

1. In der Listenansicht klick „Agent-Prompt kopieren“ (entspricht GET /w/<id>/api/prompt).

2. Den Prompt in das KI-System einfügen, das jene Repo bearbeitet. Der Prompt ist sehr kurz und führt dich im Wesentlichen auf die Datei <workspace>/.archview/AGENT-Guide.md hier - ein lokale Datei, die deshalb jedes Instrument lesen kann.

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

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

   Der tatsächliche Ablauf schrieb 22 KB (22185 Bytes), mit zehn Abschnitten: Grundsatzregel, das Zustandsbild dieses Wdepots jetzt, welchen Summaries genau fehlen (je nodeId aus aufgezählt), die verlinksverseienen Summary; deine Eingabe (Pfad der Strukturdaten); passende Anleitung je nach erkannt identifizierter Sprach; Format und Weg beim Committen; Trigger für Rebuild und die read-out-Status, die /API/-Endpunkte; Checkerliste vor der Auslieferung; ein Berichtsformat. Dieser Prompt hat den Befehl enthalten, den der Agent selbst ausführen.

   Nach der Einmalgenerierung braucht du ihn dir nie wieder anders. Jede weitere Rekonstruktion (Panel-Button / archview build / POST api/rebuild / MCP archview_re-build) schreibt sie komplett neu (das ist Umsetzung von Abschnitt 2 des Vertrags – der Notification writeAgentGuide in den steps zeigt, ob es lief. Karin: Wenn die Datei nicht existiert, wird sie beim Rebuild auch nicht angelegt, wir befüllen deine Workspace nicht mit Dateien, die du nicht wollt hast.

4. Der Agent trägt gemäß Anleitung Summ-ary in .archview/summaries/<shard>.json ein. Der Teilname = entspricht aktuellen Modulschluss mit / → _ ersetzt (modul packages/core → packages_core.json). Die Widerruf ist flach“; Summary im Unterordner werden nie gelesen (es gibt eine Warnung, aber die Runde ist verloren).

5. Rebuild: pnpm archview build, oder in der Liste auf „We willen“, oder Schnitt des Moduls der Agent performt POST /w/<id>/api/rebuild?token=….

6. Danach erscheinen die Semantik in der Paneloberfläche und status-Abdeckung ischt.

Die Einreichung der Summaries unterliegt serverseitigen Checks (Die packages/core/src/limits.ts ist Standards) pro Zeile 30–140 Zeichen, Tags ≤6, jede ≤16 Punkte, pro Charge ≤200 Stellen; wenn ihrere Charge (einzelner das ganzeabgelehnt), nichts wird diskret gespeichert, nicht abgeschnitten; daneben eine Liste bekannter Vulgarism Begriffe du norserver mit catch-und Abfrage weißtete die „verantwortlich für die Verarbeitung relevanter Logik“. Die heiß Schwellenwerte und die Vokabelliste existieren aus einem einzigen, in @archiver/core: MCP und en vigilt, der Skill verwendet die a dieser Liste zum Schreiben des Guides – so kann die Spezifikation nicht einmal mit dem (Code-of) ergänzen, was es wirklich tut. Das gab es im Historichen Fall als Bug.

⚠️ Der Sicherheits-Check wird nur bei der MCP-Eingabe automatisch angewendet. Bei den direkten Summary-Dateien (also Abschnitt 6-4) prüft oder nichts; wenn es nicht unordentlich ist, meldungslos in das Panelfeld. Deshalb: Nach dem direkten Dateischreibens wird man einmal ein Selbstprüfung durch, mit derselben regel-?? CSPM and checkSummaryItem @archview/core:

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

Daraus ergibt sich, bei deiner genauen Berichtssatz: orphan nodeId, Länge die über Grenze, Anzahl/ Länge von tags/ collision mit dem deterministisch TagrID, Treffer? (aus der leeren-Wort-Liste), ob hash dem Ist current_chuck ist, plus ob es unter summaries/ Unterverzeichnis gibt und ob die Shard-JSON-Datei gültig ist; sind ungültige Elemente, ist der Exit-Code non-null. Beide Methoden von AGENT-Guide (Abschnitt A) und die kompletistische, die endChecklist in der Anleitung weisen darauf hin.

Erweiterter Weg: installierte Skill + MCP

Der Weg liefet Folge von token-Kosten (du musst nicht den ganzen Originalcode lesungen, du nur den Struktur-Brief benötigst) und hat bei Einreichung strukturellem Prüfungen.

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

Realer Test: skill hosts detektierte 7 bestätigte Anschläge (KIRO, claude, cursor, codex, opencode, gemine, copilot CLI) and eine Berggruppe ausdrücklich nichtunterstützt (Pfad ab/s von Platform/and versionn ab und lässt sich nicht reprodu once maps – wir verschätzen uns nicht, neutrons in Manuelles Vorkommen via /skill/download). skill verify hat mit „Sprachanabführungsn 38 & frameworks“ Steuerung, von den wir actual exactly: Z “10 pieces”, je Par austen, den gendered (Harker two placeholder bzw. upstreamzeichenen) and the den upstream-Existenz von “ob sie durch archView a-Aufhänger” bestaat und .archview/skill.

Kiro hat Vorrang: Skill bereits beim Skill zusammen eingesetzn nach ~/.kiro/skills/archview, statt der Agenten „ClaudeDefinition‘ unter ~/.kiro/agents/archview.json. MCP schreibet unter ~/.kiro/settings/mcp.json. UI mittan / merged, nicht ueberschreibet (in mcpServers.archview no trigger field), hat er über Datei-Hintergrund beishand existierenden Dateizurückweis. .bak-<timestamp> Erstellung, auf Windows ist mit Junktion. --dry-run gibt die ins die Ziel Versand bleiben Waren (der Act wurde in der Realwert geprüfen: Wrote keine Bytes), --home <dir>, um HOME hinunter zuaching und test.

Die Smd starter MCP-Konfiguration: symbol man crafti verta, - er nimmt all die Standpunkt: /AGENT-GUIDE.md und im api/prompt meta.mcp.snippet steht eine Schon ein bezugsfertiges Fragmentschreiben – es zeigt auf die bereits im selben Repo gebauten packages/mcp/dist/bin/mcp.js.

Six -MCP-werkzeuge, nur lesen/rein main zer Summary, es hat kein Essay ueber Graf dessen:

Jeder Host kann das Skill-Paket direkt herunterladen: GET /skill/download (tar.gz), oder über GET /skill/* einzelne Dateien im Klartext ansehen (z. B. /skill/SKILL.md).

7. Wohin die Daten gehören / Was per git committet werden soll

Dieser Abschnitt entscheidet, ob deine Zusammenfassungen einen Maschinenwechsel überleben. Die Daten liegen vollständig in dem analysierten Repository, nicht im ArchView-Repository:

<你的仓库>/
  .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 genau ein Kriterium: Das, was Menschen und LLM erarbeitet haben, wird committet; das, was das Werkzeug neu berechnen kann, wird nicht committet.

• summaries/ enthält hunderte von Menschen/LLM verfasste chinesische Zusammenfassungen – sie neu zu erzeugen würde echtes Token-Geld kosten. Sie ziehen mit dem Code mit – egal ob Maschine, Person oder Agent wechselt, sie bleiben erhalten.

• config.json ist der Konsens des Teams darüber, „wie die Module zerteilt sind, welche Kantenschwelle gilt und welche Ausgabesprache".

Wennst der Rest lässt sich von archview build in zehn Sekunden neu berechnen. Insbesondere AGENT-GUIDE.md solltest du nicht committen: Bei jedem Rebuild wird das komplette Dokument neu geschrieben und mit einem Zeitstempel versehen, es zu committen erzeugt nur Merge-Konflikten.

archview init und jeder rebuild hängen idempotent ein block additionally an die .gitignore deines Repos (Erkennung über eine Markierung, sodass wiederholtes Ausführen nicht doppelt hängt und deine vorhandenen Zeilen nicht angefasst werden):

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

Die .gitignore dieses Repos schließt node_modules/, dist/ (die tsc-Ausgabe der fünf Pakete und die Vite-Ausgabe 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-Registry, sie enthä absolute lokale Pfade (d:/code/my-repo) und ist damit maschinenabhängig – in einem frisch geklonten Repository ist diese Tabelle also zwangsläufig leer, das ist Design und kein Makel. Er statt „13“ aus erzeugt sie sich über archview init.

8. Abnahmeskripte

Fünf Skripte plus ein Satz Unit-Tests, zusammen über hundertsiebzig Asserungen. Zumeist gilt „Dienst starten → testen → stoppen“, es bleiben keine Dauerprozesse zurück, und die Schreibzugriffe auf die geprüfte Workspace sind umkehrbar.

GemeinsameVoraussetzung: pnpm build, additionally mindestens ein realer Workspace, der bereits mit archview buildgelaufen ist. Sie verzichten bewusst auf Mocks – der Wert dieser Prüfungen liegt ausschließlich in echten Zahlen (historisch wurden genau darauf die 2253 auto-corrected-Warnungen entdeckt). Ohne Workspace den Print das Vorgehen und melden exit 1, kein unStack.

Die Spalte können installierten weiter unten wurde auf einem TypeScript-Workspace (einer Kopie des ArchView-Quellcodes, siehe Abschnitt 9 A) gemessen; ArkTS-spezifische Assertions in diesem Workspace werden sichtbaras mitsprüngend „übersprungen / nicht anwendbar" markiert und zählen nicht als Fehler.

Reinige Umgebungsvariablen-Reste, bevor du startest

# 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 Registry gelesen wird; ARCHVIEW_ACCEPT_WS / ARCHVIEW_MCP_WS / ARCHVIEW_CHECK_WS tauschen aus, welcher Workspace getestet wird. Wenn davon zurückbleibt, entsteht der Trugschluss „nichts am Code geändert, und nicht die Abnahmezahlen stimmen nicht mehr" – ein äußerst aufwändiger Fehler, denn du misst dann bereits ein anderes Repository. Das gilt für die Kommandozeile: archview init|build|status --workspaces <file> verlangt die Registry explizit, und wenn mehrere Registries parallel im Spiel sind, empfehlt sich, bei jedem Command dafür schreiben, Mittag von Umgebungsvariablen zur beobachten.

Drei Punkte, die man erst nach einem Mal kennt:

1. selfcheck.mjs mitsamt archview/.tmp/ löscht am Ende alles, was in .tmp/ liegt, nicht nur den eigenen Untermeister. Leg in .tmp/ nichts ab, was du behalten willst.

2. packages/mcp/scripts/acceptance.mjs liest nur die workspaces.json im Repo-Root, nicht die Umgebungsvariable ARCHVIEW_WORKSPACES (alle anderen Einstiegs Schalter erkennen sie). Um eine andere Registry zu durchlauf, muss diese Tabelle direkt anpasst werden.

3. Die Assertion „Bei früherem Schreiben in einen bestehenden Schaard wird erst zusammengeführt und dann geschrieben" in der MCP-Abnahme verlangt, dass der gewählte Schard außerhalb der Nachholspalten noch weitere Einträge enthält. Das Skript sortiert nach Dateinamen und nimmt den ersten Schard mit einem file-Knoten, um dort eine Lücke zu verursachen. Hat der Schard zufällig nur einer einzigen Foto (etwa ein _other-Modul mit nur einer Datei), ist der schard nach dem Bilden der Lücke leer, die Assertion greift nicht durch das Ergebnis ist 36/37. Das ist eine Geometrie des Workspace, kein Code-Problem: Schreibt die Summaries, bzw. sorgt dafür, dass der erste Schard zu einem Mehr-Datei-Modul gehört.

9. Echte Messwerte (mit Quelle)

Zahlen ändern sich mit dem Inhalt des Repos, also führt jede Zeile die Quelle, den Zeitpunkt und die Definition an.

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

Die Zahlen driftieren mit dem Quellcode: Mit derselben Definition liefert ein früherer Stand des Quellcodes 899 Knoten / 6 Module / 618 file-level Kanten / 6 Modulpaare mit 148 Aggregation-Kanten. Die Unterschiede gelten einzig und völlig der Quelle, dass die Quelle selbst größer geworden ist, nicht die Definition – Halte diese Zahlen also nicht für Basismarker für Assertions; du willst testen, bring die ZulassungsTests.

B. AMCL (eine HarmonyOS-/ArkTS-Anwendung auf dem Rechner des Autors, 10 ohpm modules) – diese Zahlen stammen aus dem Rechner des Autors; es besteht in dieser Ausfertigung nicht neu erneuert (dieses Workspace befindet sich nicht in diesem Repository und wie das vom technischen Prozess von README nicht teköhnert ): 4277 Knoten / 16124 Kantenern / 10 Module / Summary-Abdeckung 304 of 304 / Datei-Ebenen-Kanten 2115 / Modul-Überblick 24 Modulen koppelt, 1246 aggregate Kanten. Die Zusammenfassungslängen-Spanne in packages/core/src/limits.ts für die Zusammenfassung wiederum (min 36 / p50 57 / p95 78 / max 108 Zeichen) stammte aus eben dieser manuellen Kurve: 108–108, Range min 36 / p50 57 / p95 78 / max 108.

10. Bekannte Grenzen / Für wen es nicht gedacht ist

Ehrliche Aufräumen. Keine überhöhte Zusagen.

• Einzelgerät-Werkzeug, ohne Multi-User-Modell. Bind nur an 127.0.0.1, Auth nur ein einmaliger Session-Token. Keine Konten, keine Rollen, kein Audit. Nicht zum Exponieren nach außenund nicht als Team-Service aufgesetzt werden.

• Bei paralleler Prozessübergreifender Neuaufstellung gibt es keinen Lock. Wenn das UI, CLI und MCP zugleich denselben Workspace neu anstoßen, gewinnt der letzte der die Dateien schreibt. Für eine einzelne Person kein Problem, aber schreibt keine synchronen Aufrufe in Skripten.

• graph.json / meta.json / Summenzierte Dateien sind pur überschrieben, nicht atomar geschrieben (kein Schritt „temporäre Datei schreiben, dann rename”). Regulierende Exit OK; bei Stromausfall oder hartem Abkündigen während des Schreiboperationen können halbierte Dateien überbleiben – fällt dir, und einfach erneut mit archview build ausführen, denn es handelt sie sich um abgeleitete Daten entstehen. Hier das einzig atomar schreibende ist workspaces.json (die Registry).

• /skill/download und /skill/* prüfen keinen Token: ist keine Gating; veröffentlichte Skill-Dokumentation gehört jedem Agent-Host, also nimmt Kern keine Token-Abfrage. Die Endpunkte, die deinen Code ausliefern (api/graph.json, etc.) machen das bereits. Beim Binden an 127.0.0.1 bleiben es nur lokale Prozesse – darauf beruht das Vorzeichen: „nicht nach außen öffnen”.

• Qualität der Zusammenfassungen hängt vollständig von Agent und zugewieseten Budget ab. ArchView steht sonst für die „Topologie ist echt” und für „keine Silben­”; es steht nicht dafür, dass eine Summaryotional Spannend ist. Der Zaun ist groß genug, um bloße Floskeln aus der Füllliste abzuhalten, aber nicht einen nichtssagend, aber korrekten Satz.

• HarmonyOS / ArkTS ist der einzige gesättigt getestete Fall. Die Erkennung der ohpm Module, die Zwei-Hop-Faltung von ArkUI-Zellkomponenten, und die Hervorhebung von .ets sind auf einem realen ArkTS-Projekt mitgedacht. Andere Sprachen sind nur auf struktureller Ebene wiederholt getestet (Indizierung, Graph, Modulbildungs, Panel-Rendering) funktionieren), aber eine spezifische Framework-Deduktion ist nicht erfolgt; die Sprachräder sind nur auf Dokumentebene gültig geprüft.

• Die Umlaufabläufe wurden nur unter Windows systematisch durchgeführt. Die macOS/Linux-Varianten wurden geschrieben, aber nicht getestet.

• Werkzeug für „mit einem Klick irgendein Repository verstehen”. Für „erste init auf eine große Repo“ reicht: in der Minuten des CodeGraph-Index, Zusammenfassungen dauern mehr Agents-Runden. Es passt zu Projekten, die man dauerhaft beibehält, nicht um in zehn Sekunden ein fremdes Repo erkundenden.

• Kanten zwischen Layers in der Modul-Klappdarstellung sind ungelenkt. Das vendor ingekauftes aggregateLayerEdges verdichtet A→B und B→A in eine Kante. Im Drilldown bleiben die Richtungsinformationen erhalten.

• Beim import through Paket Root-Barrel wird nicht gelöst, sodass in der Modul-Übersicht Kanten fehls. CodeGraph kann ein („import … from '../../server/src/rebuild.js') sehr wohl; die für einen Pfad über der Public-API – also („import { startServer } from '@archview/owner/server'), die über den exports-Eintrag im package.jsonauf die implementation weiterleitet – ist nicht auflösbar, diese Abhängigkeit wird also gar nicht Graph. Dieses Repo ist selber ein Beispiel:packages/cli/src/commands/serve.tsverwendet einen Barrel, und das ReportimportsFromenthält keinserver; build.tsdagegen nutzt tiefe Pfade und wird so gelöst. Wenn du eine Kante, von der du überzeugt bist, auf dem Seitenübersicht siehst du, diese Ursache als Hypothesen des ersten (im RapportimportsFrom` der Datei überprüfen: wenn diese leer ist oder das Ziel fehlt, ist es sie). Das ist eine Grenze des resolvers aller Upstreamengeschichte, kein Konfigurationsmerkmal; absichtlich haben wir im Builder nicht aufgrund von Paketraten zu erraten weggelassen. So geschätztes Topologie ist genauso ein Fall von "LLM schreibt Topologie" und widerspricht Regel 1. Falls man sie im Graphen braucht, sollte der Import in der echten Pfad verwendet werden (oder auf Upstream nächstes Version warten).

• Kanten werden through confidence / resolvedBy gefiltert (Default-Schwelle 0.7, hwrcon aussortiert). Ohne den Filter kannst du dich eine echte Abhängigkeiten fake ergeben, die aus rein symbolischen Found zusammengesetzt sind (eine fuzzy-Kante mit confidence: 0.3 existiert nachweis). Echte Kanten, die jetzt weggefiltert werden, sind also auch nicht dahinter zusehen.

• CodeGraph-Telekometrie ist standard-aktiviert, aber wenn wir ihn für dich fern, tun wir es immer mit DO_NOT_TRACK=1 und CODEGRAPH_NO_UPDATE_CHECK=1 (in runCodegraph, ein optionales). Um den Schalter global zu deaktivieren: pnpm archview init … --telemetry-off.

• Die Endpunkte der Quellkontext-Inspektion haben eine hart Grenze: /w/<id>/api/file erlaubt nur filePath, die im Graphen vorkommen gehen (White-List), lehnt .. sowie absolute Pfade, reagiert auf 1 MB, und verworfen Binärdateien.

11. Architektur und Paketstruktur

archview/
  package.json            pnpm workspace 根（scripts: build / typecheck / selfcheck / archview）
  LICENSE  NOTICE  README.md  CONTRACT.md
  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 nimmt keine Logik second-hand neu ein: build fragt den Server rebuildOnce an, status spricht inspectWorkspace, serve die Serveru-startServer; „Skill" takes single verbatim from archview-skill um. Grund: Dashboardbar kein? Moderator, MCP und CLI müssen die derselben Sache dieselbe Zahl liefern – ein Indikator wie Abdeckung, wenn sie zwei Quellen hat, zwei Zahl driftet.

Der Datenfluss in einem Satz:

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

12. Lizenz und Dankbarkeit

ArchView selbst ist MIT (LICENSE). Es bestehend auf zwei Projekte, die ebenfalls MIT sind:

• **[Understand-Anything] (https://github.com/Egonex-AI/Understand-Anything)**— MIT, © Yuxiang Lin and Infinite Universe, Inc. Das GUI, das Graph-Schema, der Validator, die Fähigkeiten und die Sprach-/Framework-Anleitung stammt von ihm. Wir haben den vendor sie in voller Länge modifiziert, jede mitgeführte Datei trägt oben den Upstream-Pfad und was genau abgewandert ist.

• CodeGraph — MIT, © Colby McHenry. Quelle all strukturexer Tatsachen. Nicht mitgekäuft: wir hängen vom veröffentlichten npm-Paket ab, lesen sein SQLite-Index nur, und rufen die bin auf.

Die Quellenreferenzen **die Datei zu jeder Datei und die vollständige Danksagung beider findestens in 3 im [NOTICE](. `. Wenn du das Projekt hilfreich findest, stelle in diesen beiden oben erwähnten Repositories einen Stern geben werden – ArchView hat sie nur (its1 verbunden).

13. Etwas ändern wollen

Erste gefügen Sie der [CONTRACT.md] readreate(CONTRACT.md** Diese ist die harte Basis der Verpflichtungen, keine Stülleitfaden** – die vier stahlharten Regeln (LLM läuft nicht Topologie vor / summary muss nicht leer / der Layer über alle Dateiknoten / Datei≤Ebenen-Connectors), die eingefrorene Node-ID-Schemata, das Diff des Graph-Schemas, Modulstrategien, Dienstrate (endpoints and MCP-Tool-Oberfläche) sind mit der "Why" Water. Jede Regel in Wortschatzt hat bestenfalls einen Designentwurf in eine verletzte als design fehlt.

Zwei Stellen besonders:

• Die Node-ID-Tabellenmethode ist eingefroren. Das Datenverzeichnis für die Zusammenfassungen die Node-ID als Schlüssel; eine Idempotent heißt es, alle bisherigen Zusammenfassungsdaten für alle zu verlieren.

• Das Graph-Schema ist exakt die Schema-Ergänzung von der UA-Form, ohne Abweichung. Das GUI-Chef ist relocated; wenn das Schema ändert, muss das GUI mits. Private Info fließt durch das Passthrough-Feld in den Nodes (Edgedges haben kein Passthrough; die Zusatzwerte werden uneingeschränkt gestrippt, sich aber nicht abhängen).

Danach mindestens:

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

Durchlaufen Sie vor dem Lauf erneut die Umgebungsvariable ARCHVIEW_* nach (Section Abschnitt 8 gibt zwei Hun Shell-Kommandos), sonst kann man ein anderes Repository testen.