ArchView

Нарисуйте для репозитория архитектурную схему «как модули зависят друг от друга» — вся топология берётся из статического анализа tree-sitter, а LLM отвечает только за однострочное человеческое резюме для каждого узла. Тот же граф через MCP доступен агенту в вашей IDE.

Однопользовательский, локальный, привязан только к 127.0.0.1. Интерфейс по умолчанию на китайском.

📦 Прямая загрузка (Windows, не нужен Node, не нужно клонировать)

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

После установки двойной клик — и у вас отдельное окно, внутри та же панель, что и в веб-версии. Встроены Node и CodeGraph, устанавливается в %LOCALAPPDATA%\ArchView, права администратора не нужны.

Использование: скопируйте абзац своему ИИ и ответьте на несколько вопросов.

При открытии программы панель пуста, сверху есть копируемый промпт (с реальным портом и токеном этого запуска). Вставьте его ИИ, который редактирует ваш проект — Kiro / Claude Code / Cursor / Codex / opencode / Gemini CLI / Copilot CLI — он сам поймёт, кто он. Затем он:

1. Подключится к уже запущенному окну (не будет клонировать или ставить ещё одну копию)

2. Определит, какой он хост, и настроит MCP (перед изменением ваших конфигов спросит разрешения)

3. В вашем рабочем пространстве рекурсивно найдёт кандидатов в проекты — когда в папке несколько репозиториев/подпроектов, это норма, он покажет вам список и спросит, какой подключить (или все)

4. Зарегистрирует + построит индекс + построит граф (если индекса нет, он создаст его сам; для больших репозиториев — несколько минут)

5. Затем спросит, писать ли сейчас семантические резюме (этот шаг жжёт токены, поэтому спрашивать обязательно)

Вам остаётся ответить на несколько вопросов и дождаться появления графа в окне. Как это сделать — в CONNECT-FOR-AI.md (на него и указывает промпт в программе), живая версия с реальным портом и токеном — в /onboarding.md во время работы.

Не хотите, чтобы ИИ вмешивался? Форма под панелью, куда вводится абсолютный путь, тоже подойдёт — после регистрации нажмите «Перестроить данные», индекс создастся сам.

⚠️ Код не подписан, при первом запуске SmartScreen один раз предупредит («Подробнее» → «Всё равно выполнить»).

Related MCP server: rpg-encoder

Или установите CLI-версию

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, клонирование, сборка; единственное жёсткое требование — Node ≥ 22.5 (node:sqlite). При первом npm i дополнительно скачается платформенный подпакет CodeGraph (для Windows x64 — 248.7 МБ, со встроенным node.exe и нативными модулями) — это ожидаемо, мы намеренно не кладём его в пакет (иначе каждый пользователь каждой платформы скачивал бы все шесть вариантов).

Как выбрать из трёх путей:

Все три используют один и тот же реестр рабочих пространств (~/.archview/workspaces.json), так что можно свободно смешивать — все видят один и тот же набор проектов. Подробности о десктопной версии — в Windows-версии с отдельным окном.

🚀 Пусть ИИ поможет установить из исходников

Хотите CLI-версию (CI, скрипты, подключение MCP) или менять код — это можно целиком поручить ИИ.

Скопируйте целиком следующий абзац и вставьте любому ИИ-ассистенту, который умеет читать веб и выполнять команды (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) на каждом этапе есть «как понять, что шаг удался», а также раздел «частые ошибки и что делать». Он спроектирован так, чтобы ИИ мог прочитать его по raw URL ещё до клонирования.

Своими руками: перейдите к разделу 5, пять команд можно скопировать и выполнить; или одной командой закрыть первые два шага:

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

# macOS / Linux
bash scripts/setup.sh

Хотите сначала понять, стоит ли смотреть: раздел 3 (зачем он существует) и раздел 10 (известные ограничения / кому он не подходит).

1. Какую проблему решает

Представьте, что вы в одиночку пишете HarmonyOS-приложение из 9 модулей ohpm (это и есть причина появления проекта). Вам нужно две вещи:

1. Для себя: граф, который можно открывать, углубляться, видеть «от каких HAR зависит entry, кто использует commons»;

2. Для агента: помощник в Cursor / Kiro / Claude Code точно знает структуру проекта, а не гадает через grep.

У готовых решений каждой не хватает половины:

ArchView соединяет оба конца: CodeGraph даёт факты, панель UA даёт интерфейс, LLM дополняет только семантику.

⚠️ Сначала прочтите: сколько модулей у вас получится, зависит от формы репозитория

Граф «как модули зависят друг от друга» предполагает наличие нескольких модулей. Модули не угадываются, а выводятся из фактов в вашем репозитории (железное правило 1), поэтому для репозиториев разной формы результат разный:

archview build при каждом запуске печатает строку о том, откуда взялись модули, например:

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

archview status и список на панели дают ту же фразу. Если не понимаете, почему модули разделились именно так, сначала смотрите её.

⚠️ Контринтуитивный момент: modules.labels может только переименовать и описать уже распознанные модули, он не определяет модули. Запись туда несуществующего ключа не создаст модуль (build на это выдаст предупреждение). Чтобы изменить «как делятся модули», меняйте modules.strategy / modules.pathDepth.

⚠️ Если в репозитории есть большие каталоги (артефакты сборки, предкомпилированные бинарники, контексты контейнеров), сначала напишите codegraph.json

Это два разных переключателя, действуют в разных местах, и новички почти всегда наступают на это:

codegraph.json — это конфиг CodeGraph, не наш — ArchView никогда его не создаёт и не изменяет, так что никто за вас его не напишет, и мы его не перезапишем. Форма простая:

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

После написания удалите .codegraph/ и перестройте заново (чтобы exclude вступил в силу, индекс нужно пересоздать).

Практические замеры этого раунда получены именно так — один и тот же репозиторий HarmonyOS (281 файл .ets), единственное отличие — наличие этого файла:

Последняя ячейка не преувеличение: graph.json пишется через JSON.stringify, а у V8 предел строки около 512 МиБ, при превышении выбрасывается Invalid string length. Поэтому сейчас два барьера, оба указывают на codegraph.json: если число файлов индекса велико, перед построением графа выдаётся предупреждение (чтобы вы не ждали четыре минуты зря), а если граф действительно превышает лимит — явный отказ записи с приведённым выше JSON.

2. Это слияние двух MIT-проектов, здесь не скрываем

Оба — MIT. Атрибуция и пофайловые источники — в NOTICE, лицензия самого проекта — в LICENSE.

3. Почему стоит существовать отдельно: LLM никогда не пишет топологию

Это единственное техническое обоснование проекта и единственное правило, которое нельзя нарушать:

Узлы и рёбра могут быть получены только из вывода tree-sitter от CodeGraph. LLM/агент может давать только summary и tags, но никогда не пишет узлы, рёбра и деление на модули.

Разница конкретна. В проектах, где топологию генерирует LLM, приходится писать кучу патч-скриптов, чтобы подчищать: нормализовать несовпадающие ID, выбрасывать висячие рёбра к несуществующим узлам, разворачивать перепутанные направления. Само наличие этих скриптов — доказательство «структуре нельзя доверять». ArchView в них не нуждается — ребро существует, потому что tree-sitter действительно распарсил эту ссылку в исходном коде.

Сопутствующие три правила (покрытие, покрытие слоёв, подъём рёбер уровня файлов) и все ограничения реализации — в CONTRACT.md. В наборе инструментов MCP нет ни одного инструмента для записи графа.

4. Что нужно

Глобально устанавливать CodeGraph не нужно: это обычная npm-зависимость packages/core, archview init найдёт его bin в node_modules и вызовет от вашего имени (всегда с DO_NOT_TRACK=1 и CODEGRAPH_NO_UPDATE_CHECK=1).

Статус релиза: обе формы уже доступны

npm-версия была по-настоящему установлена и запущена в полностью чистой временной папке (тянулась из registry, не локальный tarball): npm i archview 8,8 с → archview init реально вызывает CodeGraph и строит индекс → archview build строит граф (однопакетная раскладка автоматически углубляется до 2 модулей) → archview-serve поднимает сервис, эндпоинты графа и подключения все 200, prompt рендерится из @archview/skill, а не встроенным запасным вариантом, изоляция алиасов двух zod работает (mcp 3.25.76 / core 3.24.1).

Имена вида @archview/core никогда не появятся в npm: это внутренние имена workspace-пакетов (в package.json всех шести пакетов стоит private: true), публикуется только один пакет archview. Поэтому в конфиге MCP не пишите npx -y @archview/mcp (такого пакета нет), пишите npx -y -p archview archview-mcp, или просто используйте установленный bin archview-mcp — лучше всего указывать абсолютный путь к реально существующему mcp.js (его дают панель и GET /api/onboarding).

Тем, кто хочет выпустить новую версию (нужен npm login, или в ~/.npmrc токен с правами на публикацию; 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, в его шапке написано «почему один пакет», «почему без бандлера» и четыре стража (нет 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-пакет и production-зависимости в bundle.resources; сбой на любом шаге прерывает сборку — так что «установочника с недостающими частями» не получится.)

Это не отдельная сущность от браузерной версии: в окне стоит тот самый SPA из packages/web/dist, оболочка только порождает тот же packages/server и убивает его при выходе, на стороне Rust нет ни строчки сервисной логики (раздел 9 CONTRACT.md закрепляет это как жёсткое ограничение). Поэтому панель, 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. Старт: от получения кода до графа на экране

Пять шагов. Для каждого написано, где выполнять, что произойдёт после и как понять, что получилось.

Не хочешь проходить пять шагов сам? Вставь тот промпт из начала своему ИИ-ассистенту — он сделает первые три шага по SETUP-FOR-AI.md.

Шаг 1: получить код

На npm его пока нет (см. раздел 4: пакет собран, но не опубликован), так что первый шаг — завести репозиторий на машину. После публикации весь этот раздел можно пропускать — 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

Если ещё не клонировал и хочешь взять скрипт прямо из облака — сначала скачай и посмотри, потом запускай, не гоняй удалённые скрипты вслепую через конвейер:

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 <ветка или тег>, -SkipBuild/--skip-build, -Help/--help. Три гарантированных поведения: каталог уже существует и это репозиторий archview → git pull + повторный build, без повторного clone; существует, но не репозиторий archview → выход с ошибкой, в каталоге не тронут ни один байт; провал предварительной проверки → даётся выполнимое следующее действие, а не голый exit 1. Он намеренно не делает archview init и не поднимает сервис — это касается твоего репозитория и постоянных процессов, решать должен ты или твой ИИ явно.

Как понять, что получилось: в каталоге установки есть 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-скрипт корня репозитория 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 с автокомпиляцией — в случаях, когда нужен только install зависимостей (кэш 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. Причина: межпакетные типы идут через exports в package.json каждого пакета → dist/*.d.ts, а dist/ в gitignore: нет build — нет .d.ts. В репозитории нет TS project references и нет path-алиасов, указывающих типам на src, так что это не недоработка конфигурации, а свойство как есть — новичок обязательно споткнётся, просто запомни порядок.

Тот же механизм кусается и в повседневной разработке: как только кто-то добавил новый экспортируемый subpath в src/ какого-то пакета, остальные пакеты не пройдут typecheck, пока этот пакет не пересобран. Увидел TS2307 — сначала подумай «не пора ли пересобрать».

Шаг 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% — нормальный первый результат: семантические сводки пишет агент, см. раздел 6.

При предупреждениях (сводки случайно попали в подкаталог и не прочиталась ни одна, config.json не прошёл валидацию и весь откатился, ключи в modules.labels не соответствуют ни одному модулю) build выводит их отдельным блоком с вариантами исправления. Предупреждение — не ошибка: граф действительно построен, просто эти вещи не сработали.

Для разбора результата в скрипте/агенте используй --json (гораздо полезнее --quiet: он отдаёт полный RebuildResult — steps / log / warnings / before / after / files / moduleStrategy / summaries / agentGuide, тот же объект, что у POST api/rebuild панели и archview_rebuild у MCP):

pnpm archview build my-repo --json

В любой момент можно перепроверить фактическое состояние:

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

Числа в status, на странице списка и в archview_status у MCP приходят из одной функции — двух разных покрытий не бывает.

Шаг 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.

На странице списка у каждой рабочей области карточка с четырьмя кнопками: открыть панель / пересобрать данные / скопировать промпт для агента / детали расхождения.

Реальные замеры сервиса в этот раз (все с token):

Три способа вызова — выбирай любой

Все команды выше записаны как pnpm archview … (npm-скрипт корня репозитория), потому что он доступен сразу после первого 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), а он пока не опубликован — см. раздел 4.

6. Пусть агент допишет семантику

После построения графа узлы есть, но summary каждого узла — пока лишь детерминированная заглушка (docstring / синтез из сигнатуры / <имя> — <kind> в <путь>). Заменить их на человеческий язык — работа агента.

Путь без установки (начни с него)

1. На странице списка нажми скопировать промпт для агента (эквивалент GET /w/<id>/api/prompt).

2. Вставь промпт ИИ, который редактирует этот репозиторий. Промпт короткий, его главная роль — указать на <workspace>/.archview/AGENT-GUIDE.md в рабочей области — локальный файл, его прочитает любой инструмент.

3. AGENT-GUIDE.md нужно сгенерировать один раз (build его автоматически не создаёт):

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

   В этот раз записалось 22 KB (22185 байт), десять разделов: железные правила, как эта рабочая область выглядит сейчас, каких именно сводок не хватает (по nodeId поштучно), просроченные сводки, твой вход (пути к структурным брифам), подходящие инструкции по обнаруженному языку, формат вывода и способ коммита, триггер пересборки + эндпоинты для read-only проверки состояния, чек-лист самопроверки перед сдачей, формат отчёта. Промпт тоже несёт эту команду — агент сам её выполнит.

   Сгенерировал один раз — больше о нём не думаешь: при каждой следующей пересборке (кнопка в панели / archview build / POST api/rebuild / MCP archview_rebuild) он переписывается целиком (так требует раздел 2 контракта, поэтому он в gitignore). В steps пересборки видно, отработал ли шаг writeAgentGuide. И наоборот: если файла нет, пересборка его не создаст — мы не подкладываем в твою рабочую область файлы, которые ты не просил.

4. Агент по инструкции пишет сводки в .archview/summaries/<шард>.json. Имя шарда = ключ модуля, где / заменён на _ (модуль packages/core → packages_core.json). Каталог плоский: сводки, записанные в подкаталог, не прочитается ни одна (будет предупреждение, но этот раунд — впустую).

5. Пересборка: pnpm archview build, или кнопка «пересобрать данные» на странице списка, или сам агент через POST /w/<id>/api/rebuild?token=….

6. На панели появляется семантика, покрытие в status растёт.

У отправки сводок есть серверные ограждения (значения по умолчанию в packages/core/src/limits.ts): каждая запись 30–140 символов, тегов ≤6 и каждый ≤16 символов, одна партия ≤200 записей (превышение — отказ всей партии, на диск не пишется ни одна, без усечения), плюс «словарь пустословия», отсекающий «отвечает за обработку соответствующей логики» и подобную ерунду. Пороги и словарь существуют в единственном экземпляре, в @archview/core: MCP ими исполняет закон, skill той же копией пишет инструкцию — чтобы инструкция и исполнитель не разошлись (исторически такой баг был).

⚠️ Ограждения автоматически исполняются только на пути отправки через MCP. При прямой записи шардов сводок, как на шаге 4 выше, их никто не проверяет (написал криво — без ошибки, тихо попадает в панель). Поэтому после прямой записи файлов прогони самопроверку, критерии — ровно тот же код, что у MCP (checkSummaryItem из @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   # 不依赖链接

Построчно сообщает про осиротевшие nodeId, выход за границы длины, количество/длину тегов и коллизии с детерминированными метками, попадания в пустословие, равен ли hash текущему content_hash, плюс есть ли подкаталоги в summaries/ и валиден ли JSON шардов; при наличии несоответствий код выхода ненулевой. На это указывают и абзац «способ A» в AGENT-GUIDE, и чек-лист самопроверки.

Продвинутый путь: поставить 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, определение агента — ~/.kiro/agents/archview.json, MCP пишется в ~/.kiro/settings/mcp.json. Установщик сливает, не перезаписывает (трогает только один ключ mcpServers.archview), перед перезаписью существующих файлов оставляет .bak-<временная метка>, на Windows использует junction, не symlink. --dry-run печатает содержимое, которое будет записано, как есть (замер подтвердил: ни одного байта не пишет), --home <каталог> позволяет указать HOME в другое место для пробы.

MCP-конфиг можно и не ставить через skill, а списать самому: в AGENT-GUIDE.md и в meta.mcp.snippet из api/prompt лежат готовые к вставке фрагменты, указывающие на уже собранный 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 <<<

Собственный .gitignore репозитория ArchView

.gitignore этого репозитория исключает node_modules/, dist/ (результаты tsc пяти пакетов и артефакты Vite из packages/web называются одинаково — одна запись покрывает оба), dist-pack/, *.tsbuildinfo, .tmp/, .codegraph/ и *.db*, *.log, .env*, каталоги редакторов, а также workspaces.json.

workspaces.json — это реестр рабочих областей; содержимое — абсолютные пути на текущей машине (d:/code/my-repo), они различаются от машины к машине — поэтому в свежем клоне репозитория эта таблица гарантированно пуста. Это задумано, а не недостаток. Создай её сам через archview init.

8. Приёмочные скрипты

Пять скриптов плюс набор юнит-тестов — в сумме более полутора сотен проверок. Большинство работает по схеме «поднять сервис → проверить → остановить», не оставляя фоновых процессов, а запись в проверяемую рабочую область обратима.

Общая предпосылка одна: pnpm build. Три скрипта протокольного уровня (packages/server/scripts/acceptance.mjs, packages/mcp/scripts/acceptance.mjs, final-check.mjs) без --workspace сами создают одноразовую fixture-рабочую область — тебе не нужно готовить никакую рабочую область: в незнакомом клоне можно сразу запустить node final-check.mjs. Только packages/core/scripts/selfcheck.mjs по-прежнему требует реальный каталог рабочей области.

В колонке «Проверено на практике» ниже два набора цифр: режим fixture (по умолчанию, см. ниже) и --workspace <id> против реальной рабочей области. Специфичные для ArkTS проверки на fixture и на любой не-ArkTS рабочей области явно помечаются как «пропущено / неприменимо» — это не считается ошибкой.

Граница между «пропущено» и «ошибка»: пропуск только тогда, когда предпосылка конкретной проверки на этой рабочей области не выполняется (в графе нет узлов .ets → проверять подсветку ArkTS не с чего; только 1 слой → межмодульные связи не могут существовать). На многомодульной рабочей области отсутствие межмодульных связей — это настоящий баг, и он по-прежнему помечается как ошибка (сначала посмотри, не нулевое ли «Железное правило 4: рёбра на уровне файлов» — без подъёма не будет и связей в обзоре модулей).

Путь по умолчанию не трогает пользовательские данные ни на байт

У приёмочных проверок протокольного уровня два режима, граница — наличие --workspace:

• Без --workspace (по умолчанию): скрипт сам создаёт в os.tmpdir() одноразовый fixture-репозиторий (scripts/lib/fixture-workspace.mjs: pnpm-workspace.yaml + 4 пакета, реальные межмодульные import'ы по глубоким путям между пакетами, с десяток .ts с class/function/interface, git init + один commit, аннотации по правилам из ограждений — не менее 2 на каждый фрагмент), прогоняет индексацию CodeGraph, строит граф дважды, регистрирует в своём собственном временном реестре и удаляет после завершения. Твой репозиторий, твои аннотации и workspaces.json в корне репозитория не будут задеты ни на байт. Хочешь оставить fixture посмотреть: --keep-fixture.

• С --workspace <id>: выполняется на той реальной рабочей области; перед стартом в рамке заметно сообщается, что именно будет записано. Скрипт mcp будет писать в .archview/ этой рабочей области (переместит одну аннотацию, чтобы создать пробел, изменит graph.json, реально запустит rebuild) — резервная копия / построчная проверка sha256 / сначала копия, потом rename / сверка в конце, ни одно ограждение не пропущено.

Почему по умолчанию перешли на fixture. Аргумент «намеренно не используем заглушки, ценность только у реальных цифр» справедлив только для packages/core/scripts/selfcheck.mjs — он проверяет семантику builder'а на реальном коде (2253 предупреждения auto-corrected вскрылись именно на реальных данных). А приёмка server / mcp проверяет поведение эндпоинтов и протокол инструментов — для этого самодельного маленького репозитория вполне достаточно. Цена при этом реальная: эти скрипты удаляют записи аннотаций, меняют graph.json и реально запускают rebuild. Два предыдущих раунда исправлений (починка логики восстановления, отмена отката «по первой записи реестра» по умолчанию, добавление проверки резервных копий) не затрагивали корень проблемы — пока целью по умолчанию остаётся реальный репозиторий пользователя, безопасность держится только на том, что «в каждом месте код резервного копирования написан без ошибок», а инцидент (один 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 → восстановление → сверка в конце: эти два корневых файла идут тем же путём, что и .archview/. (Раньше список разрешался относительно .archview/, и одна приёмочная проверка с --workspace переписала пользовательский .gitignore, а ограждения ничего не заметили — они смотрели только на .archview/.) Скрипт server в режиме --workspace тоже добавил для этих двух файлов резервное копирование / восстановление / побайтовую сверку.

Единственное, что пишется вне списка, — это .codegraph/codegraph.db (его меняет codegraph sync): намеренно не восстанавливается — перезаписываемый индекс размером от десятков до сотен МБ, затраты на копирование в резервную копию намного больше выгоды.

Строки внутри управляемого блока больше не удаляются молча. Семантика блока — замена целиком, поэтому пользовательские правила, записанные между # >>> archview >>> и # <<< archview <<<, раньше исчезали при следующем rebuild. Теперь ensureGitignoreBlock, обнаружив внутри блока строки, которые сгенерировал не он, отказывается писать (refused), сообщает номера строк и исходный текст в лог rebuild, archview status, на страницу списка и в warnings у archview_status, не трогая ни байта. Свои правила пиши вне блока.

Перед запуском — очисти остатки переменных окружения

# 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 подменяют какая рабочая область тестируется. Если они остались в shell, возникает самая дорогая по времени иллюзия — «код не менял, а цифры приёмки изменились»: ты уже тестируешь другой репозиторий. То же самое касается командной строки: archview init|build|status --workspaces <file> позволяет явно указать реестр; при параллельной работе с несколькими реестрами рекомендуется указывать его в каждой команде, а не полагаться на переменные окружения.

Три грабли, о которых узнаёшь только споткнувшись:

• selfcheck.mjs по завершении удаляет весь archview/.tmp/ (если не задан --keep), а не только свой подкаталог. Не клади в .tmp/ то, что хочешь сохранить.

• Голый запуск трёх скриптов протокольного уровня теперь сам создаёт fixture, а не завершается с exit 1. В прошлой версии было «без --workspace — печать справки и выход», теперь — «без аргумента — одноразовый fixture». Поэтому node packages/mcp/scripts/acceptance.mjs запускается напрямую — он работает с репозиторием, который сам создал в os.tmpdir(), а не с твоим.

• Проверка «при записи в существующий фрагмент сначала слияние, потом запись» в приёмке MCP требует, чтобы в выбранном фрагменте, помимо пробела, были и другие записи. Скрипт берёт первый фрагмент с file-узлом, отсортировав по имени файла, и создаёт в нём пробел; если в этом фрагменте ровно одна аннотация (например, модуль _other с одним файлом), после создания пробела фрагмент пустеет, и проверка не может состояться — будет 36/37. Поэтому fixture намеренно даёт каждому file-узлу аннотацию (не менее 2 на фрагмент, за этим следит жёсткая проверка в генераторе). Если на реальной рабочей области такая ошибка — это форма рабочей области, а не код: допиши аннотации полностью или сделай так, чтобы первый фрагмент соответствовал модулю с несколькими файлами.

• В режиме --workspace проверка «идемпотентный rebuild» требует, чтобы graph.json рабочей области был синхронизирован с её исходниками. Сравнивается число узлов до и после rebuild; если после последнего archview build исходники менялись, rebuild естественно даст другое число узлов (на практике: в одной рабочей области 8972 → 8969, потому что из исходников исчез один файл) — будет 36/37. Это проблема состояния рабочей области: сначала один раз archview build, потом приёмка. В режиме 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 аннотации — вся разница от того, что само приложение выросло. Диапазон длины аннотаций (40–80 знаков) в packages/core/src/limits.ts измерен именно по этой партии рукописных аннотаций: 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 + один commit). От создания каталога до готового графа около 2.0s.

10. Известные ограничения / кому это не подходит

Честный список. Без прикрас.

• Однопользовательский инструмент, без многопользовательской модели. Привязка только к 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 / реестр. Отключение питания или принудительное убийство процесса не оставит половинчатых файлов. У фрагментов сводок есть две дополнительные защиты: отказ перезаписывать, если старое содержимое не читается; количество записей может только увеличиваться или оставаться прежним (подробнее в разделе 5 CONTRACT.md).

• /skill/download и /skill/* не проверяют token, но то, что они могут прочитать, находится в белом списке. Они отдают документацию skill, поставляемую с пакетом (SKILL.md, languages/*.md, frameworks/*.md), которая и так предназначена для прямого использования любым агентом-хостом, поэтому намеренно без ограничений. Просматриваемая коллекция == коллекция, поставляемая с пакетом — обе используют один и тот же обход директорий, который исключает 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 КБ исходного кода — это уже не «компромисс без token», а произвольное чтение файлов без аутентификации. Все конечные точки, которые читают ваш код (api/graph.json, api/file, api/rebuild …), проверяют token.

• Качество сводок полностью зависит от вашего агента и выделенного ему бюджета. ArchView гарантирует только «топология правдива» и «запрещена пустая болтовня», но не гарантирует, что сводки хорошие. Защита отсекает бессмысленные слова из списка, но не может отсечь правильную, но бесполезную фразу.

• HarmonyOS / ArkTS — единственный полностью проверенный сценарий. Распознавание модулей ohpm, двухшаговое сворачивание дерева компонентов ArkUI, подсветка .ets — всё отточено на реальных проектах ArkTS. Для остальных языков выполнена только структурная проверка (индексация, построение графа, распознавание модулей, рендеринг панели), без специфичного для фреймворка вывода, а языковые руководства прошли только самопроверку на уровне документации.

• Приёмка систематически проводилась только на Windows. Ветки платформ macOS / Linux написаны, но не протестированы.

• Это не «понимание любого репозитория в один клик». Первый init большого репозитория может занять несколько минут (индексация CodeGraph), сводки требуют нескольких раундов работы агента. Он подходит для проектов, которые вы планируете поддерживать долго, а не для десятиминутного просмотра незнакомого репозитория.

• Рёбра между слоями в обзоре модулей неориентированные. В vendored aggregateLayerEdges рёбра A→B и B→A объединяются. Информация о направлении сохраняется в представлении детализации.

• Межпакетные импорты через «barrel» пакета не разрешаются, поэтому в обзоре модулей может не хватать рёбер. CodeGraph может разрешать межпакетные ссылки по глубоким путям (например, import … from '../../server/src/rebuild.js'), но import { startServer } from '@archview/server' — то есть ссылку на точку входа пакета, которая через exports в package.json перенаправляется на файл реализации — не может разрешить до целевого символа, поэтому эта зависимость не попадает в граф. Сам этот репозиторий — пример: packages/cli/src/commands/serve.ts использует barrel, в сводке importsFrom нет server; build.ts использует глубокий путь, и он разрешается. Если вы видите, что в обзоре модулей не хватает ребра, в существовании которого вы уверены, сначала подозревайте эту причину (посмотрите в сводке importsFrom этого файла: если пусто или нет цели — это оно). Это граница возможностей разрешения вышестоящего CodeGraph, а не настраиваемый параметр; мы намеренно не добавляем это ребро в builder, угадывая по имени пакета — угаданная топология — это другая форма топологии, написанной LLM, что нарушает железное правило 1. Если действительно нужно увидеть его на графе, измените этот импорт на глубокий путь (или дождитесь поддержки CodeGraph).

• Рёбра фильтруются по confidence / resolvedBy (порог по умолчанию 0.7, heuristic отбрасывается). Без фильтрации появятся ложные зависимости модулей, созданные только по совпадению имён (на практике есть fuzzy-ребро с confidence: 0.3). С другой стороны, отфильтрованные настоящие зависимости тоже становятся невидимыми.

• Телеметрия CodeGraph включена по умолчанию, но когда мы вызываем его от вашего имени, всегда передаются DO_NOT_TRACK=1 и CODEGRAPH_NO_UPDATE_CHECK=1 (записано в runCodegraph, не является опцией). Чтобы отключить и глобальный переключатель: pnpm archview init … --telemetry-off.

• У конечной точки просмотра исходников есть жёсткие ограничения: /w/<id>/api/file разрешает только filePath, встречавшиеся в графе (белый список), отклоняет .. и абсолютные пути, лимит 1 МБ, отклоняет бинарные файлы.

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)

«Шесть пакетов» и Scope: all 7 workspace projects из pnpm install — это одно и то же. В packages/ действительно шесть пакетов; седьмой — сам корень репозитория (archview, pnpm считает корень workspace проектом, потому что у него есть свой package.json и scripts). Этот корневой проект не создаёт dist/ и не публикуется — он только содержит scripts pnpm build / pnpm typecheck / pnpm archview. Увидев 7, не думайте, что установлено что-то лишнее.

cli не перереализует никакой логики: build вызывает rebuildOnce из server, 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. Панель, схема графа, валидатор, skill и руководства по языкам/фреймворкам — всё из него. Мы полностью вендорим и модифицируем, в каждом вендоренном файле вверху указан путь к исходнику и что изменено.

• CodeGraph — MIT, © Colby McHenry. Источник всех структурных фактов. Не вендорим: мы зависим от опубликованного npm-пакета, только читаем его SQLite-индекс и вызываем его bin.

Пофайловое происхождение и полные атрибуции обоих — в NOTICE. Если этот проект вам полезен, сначала поставьте звёзды двум репозиториям выше — ArchView лишь соединил их.

13. Если хотите что-то изменить

Сначала прочитайте CONTRACT.md (AGENTS.md — одностраничный обзор для агента, указывающий на то же место). Это фундамент жёстких ограничений, а не руководство по стилю — четыре железных правила (LLM не пишет топологию / summary непустые / layer покрывает все файловые узлы / файловые рёбра должны сворачиваться), замороженная схема ID узлов, схема графа, стратегия модулей, таблица сервисных конечных точек, поверхность MCP-инструментов — всё там, и для каждого пункта написано «почему» и «что произойдёт при нарушении». Нарушение любого из них — ошибка проектирования.

Особенно обратите внимание на два места:

• Схема ID узлов заморожена. Файлы сводок используют ID узла как ключ; изменение ID обесценивает все существующие сводные активы.

• Схема графа полностью совпадает с вендоренной схемой UA, без добавлений и удалений. Панель скопирована как есть; изменение схемы потребует изменения панели. Приватная информация идёт через passthrough-поля узлов (рёбра не passthrough, дополнительные поля молча отбрасываются, не полагайтесь на них).

После изменений как минимум запустите:

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 даны команды для двух оболочек), иначе вы можете тестировать другой репозиторий.