ArchView

Dibuja un diagrama de arquitectura de «cómo dependen los módulos entre sí» para un repositorio: la topología proviene íntegramente del análisis estático de tree-sitter, y el LLM solo se encarga de escribir un resumen en lenguaje natural para cada nodo. El mismo diagrama se expone a tu agente en el IDE a través de MCP.

Monousuario, local, solo vinculado a 127.0.0.1. Interfaz en chino por defecto.

📦 Descarga directa (Windows, sin instalar Node, sin clonar)

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

Tras instalarlo, haz doble clic y tendrás una ventana independiente con el mismo panel que la versión web. Incluye Node y CodeGraph integrados, se instala en %LOCALAPPDATA%\ArchView, sin necesidad de permisos de administrador.

Uso: copia un párrafo a tu IA y responde unas preguntas.

Al abrir el software, el panel está vacío y arriba hay un prompt copiable (con el puerto real y el token de esta ejecución). Pégalo a la IA que está editando tu proyecto — Kiro / Claude Code / Cursor / Codex / opencode / Gemini CLI / Copilot CLI, cualquiera vale; ella misma reconocerá cuál es. Luego hará:

1. Conectarse a esta ventana ya en ejecución (no clonará ni instalará otra copia)

2. Reconocer qué host es, configurar el MCP (te preguntará antes de tocar tu configuración)

3. Buscar recursivamente proyectos candidatos en tu espacio de trabajo — es normal que una carpeta contenga varios repos/subproyectos; te mostrará la lista y te preguntará a cuál conectar (o si conectarlos todos)

4. Registrar + crear índice + crear diagrama (si el índice no existe, lo creará él mismo; en repos grandes tarda unos minutos)

5. Preguntarte de nuevo si quieres escribir los resúmenes semánticos ahora (ese paso consume tokens, así que debe preguntar)

Solo tienes que responder unas preguntas y esperar a que aparezca el diagrama en la ventana. El procedimiento está en CONNECT-FOR-AI.md (el prompt del software apunta a él); la versión en vivo con el puerto y token reales está en /onboarding.md en tiempo de ejecución.

¿No quieres que la IA intervenga? Rellena el formulario de abajo del panel con la ruta absoluta igualmente — tras registrarlo, haz clic en «Reconstruir datos» y el índice se creará solo.

⚠️ No tiene firma de código; la primera ejecución será bloqueada por SmartScreen una vez («Más información» → «Ejecutar de todos modos»).

Related MCP server: rpg-encoder

O instala la versión de línea de comandos

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

Publicado en npm: archview. No necesita pnpm, ni clonar, ni build; el único requisito duro es Node ≥ 22.5 (node:sqlite). El primer npm i descargará además el subpaquete de plataforma de CodeGraph (el de Windows x64 pesa 248.7 MB, incluye su propio node.exe y módulos nativos) — esto es intencionado; deliberadamente no lo incluimos en el paquete (hacerlo obligaría a cada usuario de cada plataforma a descargar las seis variantes).

Cómo elegir entre las tres vías:

Los tres comparten el mismo registro de espacios de trabajo (~/.archview/workspaces.json), así que puedes mezclarlos libremente y todos verán los mismos proyectos. Los detalles de la versión de escritorio están en Versión de ventana independiente para Windows.

🚀 Deja que la IA te ayude a instalarlo desde el código fuente

Si quieres la versión de línea de comandos (CI, scripts, conectar MCP) o modificar el código — puedes delegar todo esto a la IA.

Copia todo el siguiente bloque y pégalo a cualquier asistente de IA que pueda leer páginas web y ejecutar comandos (Kiro / Cursor / Claude Code / Codex …), reemplazando <mi ruta de proyecto> por la ruta del repositorio que quieras analizar:

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

El guion (SETUP-FOR-AI.md) incluye en cada fase «cómo saber si este paso ha funcionado» y una sección de «fallos comunes y soluciones». Está diseñado para que la IA pueda leerlo a través de la URL raw antes de clonar.

Hazlo tú mismo: salta a la sección 5; hay cinco comandos que puedes copiar y pegar para que funcionen; o un solo comando para los dos primeros pasos:

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

# macOS / Linux
bash scripts/setup.sh

Si quieres decidir primero si merece la pena: la sección 3 (por qué existe) y la sección 10 (limitaciones conocidas / quién no debería usarlo).

1. Qué problema resuelve

Imagina que estás escribiendo solo una aplicación HarmonyOS con 9 módulos ohpm (este es el origen de este proyecto). Quieres dos cosas:

1. Para ti: un diagrama que se pueda hacer clic, profundizar, y ver «de qué HAR depende entry, quién usa commons»;

2. Para el agente: que el asistente en Cursor / Kiro / Claude Code conozca con precisión la estructura del proyecto, sin tener que adivinar con grep.

Las herramientas existentes carecen de la mitad cada una:

ArchView conecta ambos extremos: CodeGraph aporta los hechos, el panel de UA aporta la interfaz, y el LLM solo completa la semántica.

⚠️ Léelo primero: cuántos módulos obtendrás depende de la forma de tu repositorio

El diagrama de «cómo dependen los módulos entre sí» presupone que hay varios módulos. Los módulos no los adivinamos nosotros; se derivan de los hechos de tu repositorio (regla de hierro 1), así que repositorios con formas distintas dan resultados distintos:

archview build imprime cada vez una línea explicando de dónde salen los módulos, por ejemplo:

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

archview status y la página de lista del panel dan la misma frase. Si no entiendes por qué tus módulos están divididos así, mírala primero.

⚠️ Un punto contraintuitivo: modules.labels solo puede cambiar el nombre mostrado y la descripción de los módulos ya reconocidos; no puede definir módulos. Escribir una clave inexistente no crea un módulo (build emitirá una advertencia por ello). Para cambiar «cómo se dividen los módulos», cambia modules.strategy / modules.pathDepth.

⚠️ Si tu repositorio tiene directorios grandes (artefactos de build, binarios precompilados, contextos de contenedor), escribe primero un codegraph.json

Son dos interruptores distintos, actúan en puntos diferentes; casi todo el que lo usa por primera vez pisa esto:

codegraph.json es el archivo de configuración de CodeGraph, no nuestro — ArchView nunca lo genera ni lo modifica, así que nadie lo escribirá por ti, y no será sobrescrito por nosotros. La forma es así de simple:

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

Después de escribirlo, borra .codegraph/ y reconstruye (el índice debe rehacerse para que el exclude surta efecto).

Las cifras reales de esta ronda salen de aquí — el mismo repositorio HarmonyOS (281 .ets), con la única diferencia de si existe ese archivo:

La última celda no es exageración: graph.json se escribe con JSON.stringify, y el límite de cadena de V8 es de unos 512 MiB; superarlo lanza un Invalid string length. Así que ahora hay dos barreras, ambas mencionan codegraph.json: si el número de archivos del índice es grande, se da una advertencia antes de construir el diagrama (para que no esperes cuatro minutos en vano); si el diagrama realmente supera el límite, se rechaza explícitamente la escritura y se da el JSON de arriba.

2. Es la fusión de dos proyectos MIT, aquí no lo ocultamos

Ambos son MIT. La atribución y el origen archivo por archivo están en NOTICE; la licencia de este proyecto está en LICENSE.

3. Por qué merece la pena existir: el LLM nunca escribe la topología

Es el único fundamento técnico de este proyecto y la única regla que no admite compromiso:

Los nodos y las aristas solo pueden derivarse de la salida de tree-sitter de CodeGraph. El LLM/agente solo puede proporcionar summary y tags; nunca escribe nodos, ni aristas, ni la división de módulos.

La diferencia es concreta. Los proyectos cuya topología genera el LLM deben escribir además un montón de scripts de parcheo para limpiar: normalizar IDs que no coinciden, descartar aristas colgantes que apuntan a nodos inexistentes, invertir aristas con dirección equivocada. Esos scripts son en sí mismos la prueba de que «la estructura no es fiable». ArchView no los necesita — una arista existe porque tree-sitter realmente parseó esa referencia en el código fuente.

Las tres reglas complementarias (cobertura, cobertura de capas, subida de aristas a nivel de archivo) y todas las restricciones de implementación están en CONTRACT.md. En la superficie de herramientas de MCP no existe ninguna herramienta que escriba diagramas.

4. Qué se necesita

No hace falta instalar CodeGraph globalmente: es una dependencia npm normal de packages/core; archview init resuelve su bin desde node_modules y lo invoca en tu nombre (siempre con DO_NOT_TRACK=1 y CODEGRAPH_NO_UPDATE_CHECK=1).

Estado de publicación: ambas formas ya están en línea

La versión npm se instaló y ejecutó de verdad en un directorio temporal completamente limpio (descargado del registry, no un tarball local): npm i archview 8.8 s → archview init realmente llama a CodeGraph para crear el índice → archview build construye el diagrama (la disposición de paquete único baja automáticamente a 2 módulos) → archview-serve arranca el servicio, los endpoints del diagrama y de conexión responden todos 200, prompt lo renderiza @archview/skill en lugar del fallback integrado, y el aislamiento de alias de las dos zod funciona (mcp 3.25.76 / core 3.24.1).

Nombres como @archview/core nunca aparecerán en npm: son nombres de paquetes internos del workspace (los seis paquetes tienen private: true en su package.json); solo se publica el paquete archview. Por eso la configuración de MCP no debe escribir npx -y @archview/mcp (ese nombre de paquete no existe), sino npx -y -p archview archview-mcp, o usar directamente el bin archview-mcp que se instala — la mejor forma es apuntar a la ruta absoluta del mcp.js real de la máquina (el panel y GET /api/onboarding te la dan).

Para quien quiera publicar una nueva versión (necesita npm login, o un token con permisos de publicación en ~/.npmrc; npm ahora exige 2FA por defecto, así que la publicación interactiva requiere añadir --otp=<código de 6 dígitos>):

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

Si solo quieres ver qué se publicará:

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

El ensamblador es scripts/build-npm-package.mjs; su cabecera explica «por qué un solo paquete», «por qué no usar bundler» y las cuatro guardas (dist ausente / dist más antiguo que src / versiones no unificadas / autocomprobación del artefacto fallida → se rechaza el empaquetado; nunca se publica un paquete vacío o con código viejo).

Todavía se puede instalar desde el código fuente (sección 5): si quieres modificar el código, ejecutar los scripts de aceptación o usar pnpm --filter para compilar un paquete concreto, se va por la ruta del código fuente. Esa ruta requiere Node ≥ 22.5 y pnpm; la primera vez hay que esperar un pnpm install + pnpm build (medido en esta máquina: clonado limpio install 5,0 s, build 17,1 s, todo el proceso 25,6 s; en máquinas con el store de pnpm frío, unos minutos es normal), las actualizaciones van por git pull + volver a build (dist/ está en gitignore, el pull solo cambia el código fuente, no los artefactos).

El instalador de skills, al escribir la configuración de MCP, sigue la regla de «prioridad a los archivos que existen realmente en la máquina»: en la forma instalada por npm apunta a node_modules/archview/packages/mcp/dist/bin/mcp.js; en la forma de código fuente apunta a packages/mcp/dist/bin/mcp.js; si no se consigue ninguna de las dos, se cae a npx -y -p archview archview-mcp y en el texto se explica que esa vía requiere que el paquete esté publicado. El command usa la ruta absoluta del node del proceso actual, no un "node" pelado: la versión de escritorio trae su propio runtime y no exige que el usuario tenga Node instalado, mientras que un "node" pelado depende del PATH del host (puede no existir, puede ser la 18, puede que nvm lo haya cambiado).

Versión de ventana independiente para Windows (instalador)

Además de la línea de comandos, hay un software de Windows con ventana propia — desktop/, una carcasa de Tauri 2. Ya publicado, descarga directa:

⬇ ArchView_0.1.0_x64-setup.exe (35 MB, Windows 10/11 x64, instalación en %LOCALAPPDATA% sin UAC)

También puedes compilarlo tú mismo:

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

(Requiere la cadena de herramientas de Rust: rustup + MSVC. npm run build ejecuta primero scripts/stage-resources.mjs, que coloca el paquete npm único y las dependencias de producción en bundle.resources; si falla cualquier paso, se aborta la compilación — así que no se puede generar un «instalador al que le falten cosas».)

No son dos cosas distintas de la versión de navegador: lo que va en la ventana es el mismo SPA de packages/web/dist; la carcasa solo se encarga de lanzar el mismo packages/server y de cerrarlo al salir. En el lado de Rust no hay ni una línea de lógica de servicio (la sección 9 de CONTRACT.md lo fija como restricción dura). Así que el panel, la CLI, el MCP y la versión de escritorio dan el mismo número para la misma cosa.

El software instalado trae Node y CodeGraph incorporados; en la máquina del usuario no hay que instalar nada antes:

El uso tras instalar es «abrir la ventana → escribir la ruta absoluta de un repositorio en la página de lista → clic en reconstruir → ver el gráfico», sin tocar la terminal en todo el proceso. Si no hay índice, la reconstrucción ejecuta sola codegraph init (sección 6 del contrato) — sería un error responder aquí «primero ejecuta archview init», porque es una orden que un usuario que solo tiene la ventana no puede ejecutar.

Dos cosas que aún no están hechas, y se dicen claramente: no hay firma de código (la primera ejecución la bloqueará SmartScreen una vez, «Más información → Ejecutar de todos modos») y solo existe para Windows x64 (el script de empaquetado toma el subpaquete de plataforma de CodeGraph según la plataforma actual; para multiplataforma hay que empaquetar una vez en cada plataforma de destino). Detalles en desktop/README.md.

Estado actual de plataformas (no esperes que hayamos probado todas)

• Windows — plataforma principal de desarrollo y verificación. Los comandos y salidas de este README provienen de ejecuciones reales en Windows 11 (build 26200) + PowerShell + Node 22.20.0 + pnpm 10.28.2. La instalación de skills usa junction, sin permisos de administrador. Para ver qué ocupa un puerto: netstat -ano | findstr :7420.

• macOS / Linux — todas las ramas específicas de plataforma del código están escritas (abrir el navegador con open/xdg-open, la instalación de skills se degrada a symlink), pero no hemos ejecutado la aceptación sistemáticamente en estas dos plataformas. Si encuentras problemas, abre un issue; no lo trates como «soporte oficial».

• En tiempo de ejecución verás una línea ExperimentalWarning: SQLite is an experimental feature. Es el aviso habitual de Node sobre node:sqlite, no un error.

5. Primeros pasos: de obtener el código a ver el gráfico

Cinco pasos. En cada uno se indica claramente dónde se ejecuta, qué ocurre al ejecutarlo y cómo saber si ha funcionado.

¿No quieres recorrer estos cinco pasos tú mismo? Pega el prompt del principio a tu asistente de IA, y hará los tres primeros pasos siguiendo SETUP-FOR-AI.md.

Paso 1: Obtener el código

En npm todavía no existe (ver sección 4: el paquete ya está compilado, aún no publicado), así que el primer paso es traer el repositorio a tu máquina. Cuando se publique, toda esta sección se puede saltar — con npm i -g archview se empieza directamente en el paso 3 (archview init). Cuatro vías, elige una:

A. git clone (recomendado) — después, git pull sirve para actualizar.

# 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. Descargar el zip (si no tienes git) — coste: para actualizar solo se puede volver a descargar y sobrescribir.

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

El directorio que se descomprime se llama archview-main; recuerda renombrarlo (las dos órdenes de arriba ya lo hacen por ti).

C. gh repo clone (si tienes GitHub CLI instalado)

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

D. Script de un solo clic (hace los pasos 1 y 2 juntos) — obtener el código + pnpm install + pnpm build + otro pnpm install (para completar los enlaces de bin) + autocomprobación. Primero consigue el código con A/B/C, y luego:

# 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

Si aún no has clonado y quieres traer el script directamente desde la nube, descárgalo y míralo antes de ejecutarlo; no ejecutes a ciegas scripts remotos por tubería:

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

Parámetros del script: -Dir/--dir <ruta> (por defecto ~/archview), -Ref/--ref <rama o tag>, -SkipBuild/--skip-build, -Help/--help. Tres comportamientos garantizados: si el directorio ya existe y es un repositorio de archview → git pull + volver a build, sin clonar de nuevo; si ya existe pero no es un repositorio de archview → error y salida, sin tocar ni un byte de ese directorio; si falla una comprobación previa → se da el siguiente paso ejecutable en lugar de un exit 1 pelado. Deliberadamente no hace archview init ni arranca el servicio — eso involucra tu propio repositorio y procesos persistentes, y debe decidirlo explícitamente tú o tu IA.

Cómo saber que ha funcionado: en el directorio de instalación existe package.json y su name es archview. Si lo has traído con git, además puedes ver un sha con git rev-parse --short HEAD.

En la ruta, evita espacios en la medida de lo posible — funciona, pero luego en cada comando habrá que acordarse de poner comillas al parámetro de ruta.

Paso 2: Instalar dependencias + compilar

En la raíz del repositorio (es decir, el directorio donde aterrizó el paso 1, por ejemplo ~/archview):

pnpm install
pnpm build

Qué ocurre al ejecutarlo: los seis paquetes se compilan cada uno. Los cinco paquetes de node generan dist/ con tsc, y packages/web genera packages/web/dist/ con Vite (el frontend del panel; el servicio necesita eso para tener página).

Cómo saber que ha funcionado: packages/cli/dist/bin/archview.js y packages/web/dist/index.html existen, y lo siguiente imprime la ayuda:

pnpm archview --help

El primer pnpm install escupe una ristra de WARN Failed to create bin at ... ENOENT. Los bin de los cuatro paquetes apuntan a dist/, y en el primer install dist/ aún no existe, así que pnpm no puede crear los enlaces en node_modules/.bin/ (en la última medición con clonado limpio desde GitHub: 13 avisos; en otra ejecución anterior fueron 12 — el número varía ligeramente según la versión de pnpm y la disposición del store, no uses el número como criterio; si ves ese tipo de WARN, considéralo normal). Es inofensivo: todos los comandos de abajo usan el npm script de la raíz pnpm archview (equivalente a node packages/cli/dist/bin/archview.js), que no depende de los enlaces de bin. Para tener los comandos reales archview / archview-skill: después de pnpm build, ejecuta pnpm install otra vez; esta vez los enlaces se crearán, y a partir de ahí pnpm exec archview --version y pnpm exec archview-skill … funcionan. Si usas el script de un clic (scripts/setup.ps1 / setup.sh), este paso ya está hecho por ti (hace otro install después del build y verifica en el acto que el enlace de archview-skill existe) — sin eso, todos los comandos pnpm exec archview-skill … de la documentación darán not recognized / Command "archview-skill" not found. Deliberadamente no hemos añadido un script prepare que compile automáticamente — en los casos en que solo se quieren instalar dependencias (caché de CI, solo cambiar documentación) no se debería estar obligado a esperar una compilación completa de Vite.

⚠️ typecheck debe ejecutarse después de build

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

Al revés, falla seguro, con una ristra de TS2307: Cannot find module '@archview/core' (o su subpath, por ejemplo '@archview/core/themes') or its corresponding type declarations. La razón es que los tipos entre paquetes pasan por el exports del package.json de cada paquete → dist/*.d.ts, y dist/ está en gitignore: sin build no hay .d.ts. En el repositorio no hay TS project references ni alias de path que apunten los tipos de vuelta a src, así que esto no es un descuido de configuración, sino una propiedad existente — cualquier persona nueva se va a tropezar con ello; recuerda el orden.

El mismo mecanismo también muerde en el desarrollo diario: en cuanto alguien añade un subpath de export nuevo en el src/ de un paquete, los demás paquetes no pasan el typecheck hasta que ese paquete se vuelva a compilar. Si ves TS2307, piensa primero «¿no habrá que compilar antes?».

Paso 3: Conectar el primer repositorio a analizar

Sigue en la raíz del repositorio de ArchView. Cambia la ruta por la de tu propio repositorio:

pnpm archview init d:/code/my-repo

Qué ocurre al ejecutarlo (cinco pasos, todos idempotentes; repetirlos solo te cuenta el estado actual):

1. Comprobación del entorno (versión de Node, existencia del directorio, si es un repositorio git)

2. Crea el índice de CodeGraph .codegraph/codegraph.db en tu repositorio (si ya existe, lo salta)

3. Escribe .archview/config.json (si ya existe, no lo sobrescribe; solo con --force-config lo reescribe), y rellena automáticamente el esqueleto de módulos según oh-package.json5 / pnpm-workspace.yaml / Cargo.toml / go.mod

4. Añade de forma idempotente un bloque marcado al .gitignore de tu repositorio (ver sección 7)

5. Lo registra en archview/workspaces.json (el registro de workspaces)

Cómo saber que ha funcionado: al final imprime el id del workspace y el siguiente comando. Salida de una ejecución real (esta vez se usó una copia del propio código fuente de ArchView como repositorio analizado):

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

Opciones habituales: --id <id> (va en la URL; solo se permite [a-z0-9][a-z0-9_-]*), --name "nombre visible", --skip-index, --telemetry-off, --json (legible por máquina: id del workspace, acciones de configuración/gitignore, conclusión del reconocimiento de módulos, siguiente comando; el progreso de los cinco pasos va en el campo log). Lista completa: pnpm archview init --help.

Paso 4: Generar los datos del panel

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

Qué ocurre al ejecutarlo: codegraph sync (para que el índice siga al disco) → construir el gráfico → escribir .archview/graph.json y meta.json → generar .archview/briefs/*.json (resúmenes estructurados para el LLM) → volver a confirmar el bloque de .gitignore.

Cómo saber que ha funcionado: cada paso va precedido de ✓, y al final se dan nodos/aristas/módulos y cobertura de resúmenes. Ejecución real de esta vez:

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

Una cobertura del 0 % es un primer resultado normal — los resúmenes semánticos los tiene que escribir el agente, ver sección 6.

Cuando hay avisos (un resumen metido por error en un subdirectorio y por tanto ninguno se ha leído, config.json que falla la validación y revierte todo el archivo, una key de modules.labels que no coincide con ningún módulo), build los vuelve a imprimir aparte y da la solución. Un aviso no es un fallo: el gráfico sí se ha construido, pero esas cosas no han surtido efecto.

Para parsear el resultado en un script/agente, usa --json (mucho más útil que --quiet: da el RebuildResult completo — steps / log / warnings / before / after / files / moduleStrategy / summaries / agentGuide —, el mismo objeto que el POST api/rebuild del panel y el archview_rebuild del MCP):

pnpm archview build my-repo --json

Para revisar el estado real en cualquier momento:

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

Los números de status vienen de la misma función que la página de lista y el archview_status del MCP — no puede haber dos coberturas distintas.

Paso 5: Arrancar el servicio y ver el gráfico

pnpm archview serve --open

Qué ocurre al ejecutarlo: un proceso, un puerto, sirve todos los workspaces registrados. Por defecto 127.0.0.1:7420; si está ocupado, sube automáticamente (hasta 20); si se da --port explícitamente, no cambia — si está ocupado, falla. Al arrancar imprime un token de sesión de un solo uso, y todos los api/* lo verifican.

Cómo saber que ha funcionado: el banner tiene este aspecto (ejecución real de esta vez, token truncado):

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

Si se da --token <tu cadena>, las dos últimas líneas cambian a «token fijado por --token, no cambia al reiniciar» y recuerdan no commitearlo — el texto se bifurca según «¿se ha dado --token explícitamente?», para que quien fijó un token no crea que no ha surtido efecto.

La línea de «artefacto del panel» debe apuntar a un packages/web/dist que exista de verdad — si no se ha compilado el frontend, la página de lista mostrará explícitamente panel frontend sin compilar; entonces ejecuta pnpm --filter @archview/web build.

En la página de lista, cada workspace es una tarjeta con cuatro botones: Abrir panel / Reconstruir datos / Copiar prompt de agente / Detalles de deriva.

Pruebas reales del servicio de esta vez (todas con token):

Tres formas de invocación, elige la que quieras

Todos los comandos de arriba están escritos como pnpm archview … (npm script de la raíz del repositorio), porque está disponible inmediatamente después del primer install y no depende de los enlaces de bin. Las otras dos formas equivalentes:

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

Ojo: ② solo funciona dentro de este repositorio (los enlaces de bin están en node_modules/.bin/ del repositorio). Para meter esos cuatro comandos en el PATH global hay que ir por la vía de npm (npm i -g archview), y eso aún no está publicado — ver sección 4.

6. Que el agente complete la semántica

Una vez construido el gráfico, los nodos ya están, pero el summary de cada nodo sigue siendo una frase de respaldo determinista (docstring / sintetizada a partir de la firma / <nombre> — <kind> en <ruta>). Convertirlas en lenguaje natural es trabajo del agente.

Vía de instalación cero (usa esta primero)

1. En la página de lista, clic en copiar prompt de agente (equivalente a GET /w/<id>/api/prompt).

2. Pega el prompt a la IA que está editando ese repositorio. El prompt es muy corto; su función principal es apuntar a <workspace>/.archview/AGENT-GUIDE.md del workspace — un archivo local que cualquier herramienta puede leer.

3. AGENT-GUIDE.md hay que generarlo una vez (build no lo genera automáticamente):

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

   La ejecución real de esta vez escribió 22 KB (22185 bytes), con diez secciones: reglas de hierro, cómo está este workspace ahora, qué resúmenes faltan concretamente (nodeId por nodeId), resúmenes caducados, tus entradas (rutas de los resúmenes estructurados), guía elegida según el lenguaje detectado, formato de salida y forma de enviar, disparar la reconstrucción + endpoints de solo lectura para confirmar el estado, lista de autocomprobación antes de entregar, formato de informe. El prompt también lleva este comando; el propio agente lo ejecutará.

   Una vez generado, no hay que volver a ocuparse de él: en cada reconstrucción posterior (botón del panel / archview build / POST api/rebuild / MCP archview_rebuild) se reescribe entero (así lo exige la sección 2 del contrato, por eso está en gitignore). En los steps de la reconstrucción se puede ver si el paso writeAgentGuide se ha ejecutado o no. Dicho al revés: si el archivo no existe, la reconstrucción no lo crea por ti — no metemos en tu workspace archivos que no hayas pedido.

4. El agente escribe los resúmenes en .archview/summaries/<fragmento>.json siguiendo la guía. El nombre del fragmento = la key del módulo con / cambiado por _ (módulo packages/core → packages_core.json). Este directorio es plano; un resumen escrito en un subdirectorio no se lee ni uno (habrá un aviso, pero esa ronda de trabajo se ha perdido).

5. Reconstruir: pnpm archview build, o clic en «Reconstruir datos» en la página de lista, o el propio agente hace POST /w/<id>/api/rebuild?token=….

6. En el panel aparece la semántica y la cobertura de status sube.

El envío de resúmenes tiene protecciones en el servidor (valores por defecto en packages/core/src/limits.ts): cada uno de 30–140 caracteres, etiquetas ≤6 y cada una ≤16 caracteres, un lote ≤200 (si se supera, se rechaza el lote entero, no se escribe ni una, no se trunca), más una «lista de palabras vacías» que bloquea frases como «se encarga de la lógica relacionada». Los umbrales y la lista tienen una única copia real, en @archview/core: el MCP la usa para hacer cumplir, el skill usa la misma para escribir la guía — para que el manual y el que hace cumplir no se contradigan (históricamente ha habido ese bug).

⚠️ Las protecciones solo se aplican automáticamente en la vía de envío por MCP. Al escribir directamente los fragmentos de resúmenes como en el paso 4 de arriba, nada los comprueba (si se escribe mal, no da error; entra en silencio al panel). Así que, después de escribir archivos directamente, ejecuta una autocomprobación; el criterio es exactamente el mismo código que el MCP (el checkSummaryItem de @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   # 不依赖链接

Informa uno a uno de nodeIds huérfanos, longitudes fuera de rango, cantidad/longitud de tags y colisiones con etiquetas deterministas, coincidencias con palabras vacías, si hash es igual al content\_hash actual, además de si hay subdirectorios en summaries/ y si los JSON de los fragmentos son válidos; si hay elementos no conformes, el código de salida es distinto de 0. El párrafo de la vía A de AGENT-GUIDE y la lista de autocomprobación apuntan a ello.

Vía avanzada: instalar skill + MCP

Ahorra más tokens (no hace falta leer el código fuente entero; basta con leer los resúmenes estructurados) y al enviar hay validación estructurada.

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

Medido en la práctica: skill hosts lista 7 hosts confirmados (kiro, claude, cursor, codex, opencode, gemini, copilot CLI) y un montón de explícitamente no soportados (las rutas varían según plataforma/versión y no se pueden reproducir para verificar; no adivinamos, se colocan a mano con /skill/download). skill verify medido en la práctica: «38 guías de lenguaje, 10 guías de framework, todas presentes, no son placeholders, todas con atribución upstream y párrafo de adaptación de ArchView».

Kiro tiene prioridad: el skill se instala en ~/.kiro/skills/archview, la definición de agente en ~/.kiro/agents/archview.json, el MCP se escribe en ~/.kiro/settings/mcp.json. El instalador fusiona sin sobrescribir (solo toca la clave mcpServers.archview), antes de reescribir un archivo existente deja un .bak-<marca de tiempo>, en Windows usa junction, no symlink. --dry-run imprime tal cual lo que se va a escribir (medido: no escribe ni un byte), y --home <dir> permite apuntar HOME a otro sitio para probar.

La configuración del MCP también se puede copiar a mano sin instalar el skill: en AGENT-GUIDE.md y en el meta.mcp.snippet de api/prompt viene el fragmento listo para pegar, apuntando al packages/mcp/dist/bin/mcp.js ya compilado del mismo repositorio.

Seis herramientas MCP, de solo lectura + envío de resúmenes; no hay ninguna herramienta que escriba el gráfico:

Cualquier host puede descargar el paquete de skill directamente: GET /skill/download (tar.gz), o GET /skill/* para ver un archivo suelto en texto plano (por ejemplo /skill/SKILL.md).

7. Dónde van los datos / qué se debe commitear a git

Esta sección decide si los resúmenes siguen existiendo cuando cambias de máquina. Todos los datos caen en el repositorio analizado, no en el repositorio de 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 的操作说明（每次生成整份重写，含时间戳）→ 不提交

El único criterio es este: lo que acumulan las personas y el LLM se commitea; lo que las herramientas pueden recalcular no se commitea.

• summaries/ son varios cientos de resúmenes en chino escritos por humanos/LLM; regenerarlos cuesta tokens de verdad. Sigue al código: cambies de máquina, de persona o de agente, sigue ahí.

• config.json es el consenso del equipo sobre «cómo dividir los módulos, cuál es el umbral de aristas, en qué idioma se emite la salida».

• El resto se puede recalcular en diez segundos con archview build. AGENT-GUIDE.md en particular no debería commitearse: se reescribe entero en cada rebuild y lleva marca de tiempo; commitearlo solo genera conflictos.

archview init y cada rebuild añaden de forma idempotente este bloque al .gitignore de tu repositorio (se identifica por marcadores; ejecutarlo repetido no lo vuelve a añadir ni toca tus líneas existentes):

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

El .gitignore del propio repositorio de ArchView

El .gitignore de este repositorio excluye node_modules/, dist/ (los artefactos de tsc de los cinco paquetes y los de Vite de packages/web comparten nombre; una sola regla cubre ambos), dist-pack/, *.tsbuildinfo, .tmp/, .codegraph/ y *.db*, *.log, .env*, los directorios de editores y workspaces.json.

workspaces.json es el registro de workspaces; su contenido son rutas absolutas de la máquina local (d:/code/my-repo), que varían de una máquina a otra — por eso en un clon nuevo esa tabla siempre está vacía: es un diseño, no una carencia. Créala tú con archview init.

8. Scripts de aceptación

Cinco scripts más un conjunto de pruebas unitarias suman más de ciento cincuenta aserciones. La mayoría son «levantar servicio → probar → parar»; no dejan procesos residentes y las escrituras en el workspace inspeccionado son reversibles.

El único prerrequisito común es pnpm build. Los tres scripts de la capa de protocolo (packages/server/scripts/acceptance.mjs, packages/mcp/scripts/acceptance.mjs, final-check.mjs) crean ellos mismos un workspace fixture desechable si no se les pasa --workspace — no necesitas preparar ningún workspace: en un clon desconocido basta con node final-check.mjs para ejecutarlo. Solo packages/core/scripts/selfcheck.mjs sigue exigiendo un directorio de workspace real.

En la columna «Prueba real» de abajo se dan dos conjuntos de números: modo fixture (por defecto, ver más abajo) y con --workspace <id> contra un workspace real. Las aserciones específicas de ArkTS se marcan explícitamente como «omitido / no aplicable» tanto en el fixture como en cualquier workspace que no sea ArkTS; no cuentan como fallo.

La línea entre «omitido» y «fallo»: solo se omite cuando la premisa de esa comprobación no se cumple en ese workspace (no hay nodos .ets en el grafo → no hay nada que comprobar para el resaltado ArkTS; solo hay 1 layer → no puede haber aristas entre módulos). En un workspace multimódulo, la ausencia de aristas entre módulos sí es un bug real y se reporta como fallo (mira primero si «Regla de hierro 4: aristas a nivel de archivo» es 0 — sin roll-up no hay líneas en la vista general de módulos).

La ruta por defecto no toca ni un byte de los datos del usuario

La aceptación de la capa de protocolo tiene dos modos; la frontera es si hay --workspace o no:

• Sin --workspace (por defecto): el script crea él mismo un repositorio fixture desechable en os.tmpdir() (scripts/lib/fixture-workspace.mjs: pnpm-workspace.yaml + 4 paquetes, imports reales entre módulos por rutas profundas, una docena de .ts con class/function/interface, git init + un commit, resúmenes escritos según las salvaguardas con ≥ 2 por fragmento), ejecuta el índice de CodeGraph, construye el grafo dos veces, lo registra en su propio registro temporal y lo borra al terminar. Tu repositorio, tus resúmenes y el workspaces.json de la raíz del repo no se tocan ni un byte. Si quieres conservar el fixture para verlo: --keep-fixture.

• Con --workspace <id>: se ejecuta sobre ese workspace real y, antes de empezar, te avisa de forma bien visible con un recuadro qué va a escribir. El de mcp sí escribe en el .archview/ de ese workspace (mueve un resumen para crear un hueco, modifica graph.json y ejecuta un rebuild de verdad), con copia de seguridad / verificación sha256 archivo por archivo / copiar primero y luego rename / comparación al final: no falta ni una salvaguarda.

Por qué el modo por defecto pasó a ser fixture. La razón de «a propósito no usar datos simulados; solo los números reales tienen valor» solo se sostiene para packages/core/scripts/selfcheck.mjs — lo que valida es la semántica del builder sobre código real (las 2253 advertencias auto-corrected solo salieron a la luz con datos reales). En cambio, la aceptación de server / mcp valida el comportamiento de los endpoints y el protocolo de herramientas, y un repositorio pequeño autoconstruido es más que suficiente. El coste, en cambio, era real: esos scripts borran entradas de resúmenes, modifican graph.json y ejecutan rebuilds de verdad. Los dos parches anteriores (arreglar la lógica de restauración, quitar el fallback por defecto a «primera entrada del registro», añadir verificación de copias) no atacaron la causa raíz: mientras el objetivo por defecto sea el repositorio real del usuario, la seguridad depende siempre de que «cada fragmento de código de copia de seguridad esté bien escrito», y el incidente (un restore() que borró silenciosamente 308 resúmenes humanos irreproducibles de un workspace mientras el script reportaba PASS 已恢复原样) ya demostró que esa premisa no se sostiene.

La superficie de escritura de rebuild es más amplia que .archview/, y la lista de copias de seguridad la sigue. ensureGitignoreBlock toca el .gitignore de la raíz del workspace (el texto original antes de la reescritura queda en .gitignore.archview-bak), así que la lista de copias del mcp ahora se resuelve relativa a la raíz del workspace: .archview/graph.json, .archview/meta.json, .archview/briefs, .archview/summaries, .archview/AGENT-GUIDE.md, .gitignore, .gitignore.archview-bak. Copia → verificación sha256 archivo por archivo → restauración → comparación al final: esos dos archivos raíz siguen el mismo camino que .archview/. (Antes la lista se resolvía relativa a .archview/, así que una aceptación con --workspace reescribió el .gitignore del usuario sin que las salvaguardas se enteraran — solo miraban .archview/.) El script de server también añadió copia / restauración / comparación byte a byte para esos dos archivos en modo --workspace.

Lo único que se escribe fuera de la lista es .codegraph/codegraph.db (lo modifica codegraph sync): a propósito no se restaura — un índice regenerable de decenas a cientos de MB; el coste de copiarlo a la copia de seguridad supera con creces el beneficio.

Las líneas dentro del bloque gestionado ya no se eliminan en silencio. La semántica del bloque es reemplazo completo, así que las reglas de usuario escritas entre # >>> archview >>> y # <<< archview <<< antes desaparecían en el siguiente rebuild. Ahora ensureGitignoreBlock, al detectar líneas dentro del bloque que no ha generado él, se niega a escribir (refused), reporta el número de línea y el texto original en el log del rebuild, en archview status, en la página de listado y en los warnings de archview_status, y no toca ni un byte. Tus propias reglas van fuera del bloque.

Antes de ejecutar, limpia los restos de variables de entorno

# 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 cambia qué registro se lee; ARCHVIEW_ACCEPT_WS / ARCHVIEW_MCP_WS / ARCHVIEW_CHECK_WS cambian qué workspace se prueba. Si quedan una vez en el shell, aparece la ilusión más costosa en tiempo: «no he tocado el código y los números de aceptación han cambiado» — porque ya estás probando otro repositorio. Lo mismo aplica a la línea de comandos: archview init|build|status --workspaces <file> permite especificar el registro explícitamente; con varios registros en paralelo conviene escribirlo en cada comando, no fiarse de variables de entorno para recordar el estado.

Tres trampas que solo se aprenden pisándolas:

• selfcheck.mjs al terminar borra todo archview/.tmp/ (salvo que se pase --keep), no solo su propio subdirectorio. No pongas nada que quieras conservar bajo .tmp/.

• Ejecutar a secas los tres scripts de la capa de protocolo ahora crea su propio fixture, ya no hace exit 1. La versión anterior era «sin --workspace imprime el uso y sale»; ahora es «sin argumento usa un fixture desechable». Así que node packages/mcp/scripts/acceptance.mjs se ejecuta directamente — ataca al repositorio que él mismo crea en os.tmpdir(), no al tuyo.

• En la aceptación de MCP, la aserción «al escribir en un fragmento existente, primero se fusiona y luego se escribe» exige que el fragmento elegido tenga, además del hueco, otras entradas. El script ordena por nombre de archivo y toma el primer fragmento con nodos file para crear el hueco; si ese fragmento tiene exactamente una sola entrada de resumen (p. ej. un módulo _other con un solo archivo), al crear el hueco el fragmento queda vacío y esa aserción no puede cumplirse: reporta un 36/37. Por eso el fixture escribe a propósito un resumen para cada nodo file (cada fragmento ≥ 2 entradas, con una aserción dura en el generador que lo garantiza). Si contra un workspace real te falla esto, es un problema de forma del workspace, no del código: escribe resúmenes más completos, o haz que el primer fragmento corresponda a un módulo con varios archivos.

• En modo --workspace, la aserción «rebuild idempotente» exige que el graph.json del workspace esté sincronizado con su código fuente. La aserción compara el número de nodos antes y después del rebuild; si ese repositorio modificó el código fuente después del último archview build, el rebuild dará naturalmente un número de nodos distinto (prueba real: en un workspace 8972 → 8969, porque el código fuente perdió un archivo) y reportará un 36/37. Es un problema de estado del workspace: ejecuta archview build una vez antes de correr la aceptación. En modo fixture no existe este problema (el grafo acaba de construirse).

9. Números reales (con su origen)

Los números cambian con el contenido del repositorio, así que cada entrada indica de qué repositorio es, cuándo y con qué criterio.

A. ArchView analizándose a sí mismo (re-ejecutado para escribir este README; se analizó una copia del código fuente de ArchView, excluyendo node_modules/, dist/, .tmp/; Windows 11 / Node 22.20.0 / pnpm 10.28.2):

Los números derivan con los cambios del código fuente: con el mismo criterio, en una versión anterior del código fuente daba 899 nodos / 6 módulos / 618 aristas a nivel de archivo / 6 pares de módulos con 148 aristas agregadas. La diferencia viene toda de que el código fuente ha crecido, no de que haya cambiado el criterio — así que no uses estos números como valores de referencia para aserciones; para asertar, ejecuta los scripts de aceptación.

B. AMCL (una app HarmonyOS / ArkTS en la máquina del autor, multimódulo con ohpm) — estos números se observaron solo en lectura (se leyó su graph.json ya construido, sin reconstruirlo): 8972 nodos / 27864 aristas / 11 módulos / aristas a nivel de archivo 3216 / 308 resúmenes (cobertura 308 / 682, de los cuales 71 de componentes de framework), estrategia de módulos ohpm. En una versión anterior, con el mismo criterio: 4277 nodos / 16124 aristas / 10 módulos / 304 resúmenes — la diferencia viene toda de que la app ha crecido. El rango de longitud de resúmenes en packages/core/src/limits.ts (40–80 caracteres) se midió sobre ese lote de resúmenes humanos: min 36 / p50 57 / p95 78 / max 108 caracteres.

C. El repositorio fixture desechable de la aceptación (scripts/lib/fixture-workspace.mjs lo crea y lo borra al momento, así que estos números son siempre iguales y pueden usarse como referencia): 4 paquetes pnpm / 13 .ts / 20 archivos → índice de CodeGraph 0.8s → 49 nodos / 150 aristas / 4 módulos / aristas a nivel de archivo 43 / 13 resúmenes (cobertura 13/13), estrategia de módulos npmWorkspaces, vista general de módulos con 6 pares de módulos y 26 aristas agregadas, gitCommitHash real (git init + un commit). De crear el directorio a tener el grafo listo, unos 2.0s.

10. Limitaciones conocidas / para quién no es

Lista honesta. Sin humo.

• Herramienta de un solo equipo, sin modelo multiusuario. Solo se vincula a 127.0.0.1, y la autenticación es un único token de sesión de un solo proceso. No hay cuentas, ni roles, ni auditoría. No lo expongas a Internet ni lo despliegues como servicio de equipo.

• La reconstrucción concurrente es mutuamente excluyente, pero si no se obtiene el bloqueo, falla directamente en lugar de hacer cola. Las tres entradas (panel / archview build / archview_rebuild de MCP) usan el mismo bloqueo de archivo .archview/.rebuild.lock. La segunda solicitud recibe inmediatamente «otro proceso está reconstruyendo (pid X, desde Y)», y la capa HTTP responde con 409. Deliberadamente no se hace cola: hacer cola haría que el navegador girara sin fin, y poner dos codegraph sync completos en cola no te aporta nada. La auto-recuperación de bloqueos muertos tiene dos vías: el proceso que mantiene el bloqueo en la misma máquina ya no existe, o han pasado más de 30 minutos. El bloqueo solo protege la reconstrucción: no se ocupa de «mientras se reconstruye, alguien edita manualmente summaries/»; en ese caso, lo que se escriba al final es lo que prevalece.

• La escritura en disco es atómica (archivo temporal en el mismo directorio + rename), y cubre graph.json / meta.json / briefs/ / fragmentos de resumen / config.json / registro. Un corte de energía o un proceso eliminado a la fuerza no deja archivos a medias. Los fragmentos de resumen tienen además dos salvaguardas: si no se puede leer el contenido anterior, se rechaza la sobrescritura; y el número de entradas solo puede aumentar o mantenerse igual (ver sección 5 de CONTRACT.md).

• /skill/download y /skill/* no validan token, pero lo que se puede leer está en una lista blanca. Devuelven los documentos de skill que se distribuyen con el paquete (SKILL.md, languages/*.md, frameworks/*.md), que de todos modos están destinados a que cualquier host de agente los tome directamente, por lo que deliberadamente no se les puso control de acceso. El conjunto navegable == el conjunto distribuido con el paquete, ambos comparten el mismo recorrido de directorio, y ese recorrido excluye node_modules / dist / .git y solo acepta archivos reales — por lo que los enlaces simbólicos nunca están en el conjunto. Esto se añadió después: la implementación anterior solo hacía «no permitir .. + verificación de prefijo», que bloqueaba el traversal clásico, pero no podía bloquear el enlace que pnpm coloca en packages/skill/node_modules/@archview/core apuntando a packages/core (la ruta de texto del enlace es una subruta del directorio de skill, y la verificación de prefijo la dejaba pasar). En la práctica, GET /skill/node_modules/@archview/core/src/builder.ts devolvía 200 con 25 KB de código fuente — eso ya no era «una compensación sin token», sino una lectura arbitraria de archivos sin autenticación. Todos los endpoints que leen tu código (api/graph.json, api/file, api/rebuild …) validan token.

• La calidad del resumen depende completamente de tu agente y del presupuesto que le des. ArchView solo garantiza que «la topología es real» y que «no se escriben frases vacías», pero no garantiza que el resumen esté bien escrito. Las salvaguardas pueden bloquear las frases vacías de la lista de palabras vacías, pero no pueden bloquear una frase correcta pero inútil.

• HarmonyOS / ArkTS es el único escenario con validación completa. El reconocimiento de módulos ohpm, el plegado de dos saltos del árbol de componentes ArkUI y el resaltado de .ets se pulieron en proyectos reales de ArkTS. Los demás lenguajes solo tienen validación a nivel de estructura (pueden indexarse, construir el grafo, reconocer módulos y renderizar el panel), sin deducción de frameworks específica, y las guías de lenguaje solo pasaron una auto-revisión a nivel de documentación.

• Solo se ejecutó la aceptación sistemáticamente en Windows. Las ramas de plataforma para macOS / Linux están escritas pero no probadas.

• No es «entender cualquier repositorio con un clic». La primera init de un repositorio grande puede tardar varios minutos (índice de CodeGraph), y el resumen requiere que el agente ejecute varias rondas. Es adecuado para proyectos que planeas mantener a largo plazo, no para echar un vistazo a un repositorio desconocido en diez minutos.

• Las aristas entre capas en la vista general de módulos son no dirigidas. El aggregateLayerEdges vendored combina A→B y B→A. La información de dirección aún está presente en la vista de desglose.

• Las importaciones entre paquetes que pasan por el «barrel de la raíz del paquete» no se resuelven, por lo que faltan aristas en la vista general de módulos. CodeGraph puede resolver referencias entre paquetes con rutas profundas (como import … from '../../server/src/rebuild.js'), pero import { startServer } from '@archview/server' — es decir, las que apuntan a la entrada del paquete y se reenvían al archivo de implementación mediante exports de package.json — no puede resolver el símbolo de destino, por lo que esa dependencia no entra en el grafo. Este repositorio es un ejemplo: packages/cli/src/commands/serve.ts usa el barrel, y en el informe importsFrom no aparece server; build.ts usa ruta profunda y se resuelve. Si ves que falta una arista en la vista general de módulos que estás seguro que existe, sospecha primero de esta causa (mira el importsFrom de ese archivo en el informe: si está vacío o falta el destino, es eso). Es un límite de capacidad de resolución de CodeGraph, no una opción configurable; deliberadamente no completamos esa arista adivinando por nombre de paquete en el builder — una topología adivinada es otra forma de que el LLM escriba topología, violando la regla de hierro 1. Si realmente quieres verla en el grafo, cambia esa importación a una ruta profunda (o espera a que CodeGraph lo soporte).

• Las aristas se filtran por confidence / resolvedBy (umbral predeterminado 0.7, se descarta heuristic). Sin filtrar, aparecerían dependencias falsas entre módulos creadas solo por coincidencia de nombres (en la práctica existe una arista fuzzy con confidence: 0.3). Por otro lado, las dependencias reales que se filtran tampoco se ven.

• La telemetría de CodeGraph está activada por defecto, pero cuando lo invocamos en tu nombre, siempre llevamos DO_NOT_TRACK=1 y CODEGRAPH_NO_UPDATE_CHECK=1 (escrito en runCodegraph, no es opcional). Para desactivar también su interruptor global: pnpm archview init … --telemetry-off.

• El endpoint de navegación de código fuente tiene límites estrictos: /w/<id>/api/file solo permite filePath que hayan aparecido en el grafo (lista blanca), rechaza .. y rutas absolutas, tiene un límite de 1 MB y rechaza binarios.

11. Arquitectura y estructura de paquetes

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)

«Seis paquetes» y el Scope: all 7 workspace projects que imprime pnpm install se refieren a lo mismo. Bajo packages/ hay efectivamente seis paquetes; el séptimo es la raíz del repositorio misma (archview, pnpm cuenta la raíz del workspace como un project, porque tiene su propio package.json y scripts). Este project raíz no produce dist/ ni se publica — solo aloja los scripts pnpm build / pnpm typecheck / pnpm archview. Si ves 7, no pienses que hay algo extra instalado.

cli no reimplementa ninguna lógica: build llama a rebuildOnce del server, status llama a inspectWorkspace, serve llama a startServer, y skill reenvía tal cual a archview-skill. La razón es que el panel, MCP y la línea de comandos deben dar el mismo número para lo mismo — una métrica como la cobertura, si tiene dos fuentes, los dos números inevitablemente divergirán.

El flujo de datos en una frase:

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

12. Licencia y agradecimientos

ArchView en sí es MIT (LICENSE). Se apoya en dos proyectos que también son MIT:

• Understand-Anything — MIT, © Yuxiang Lin and Infinite Universe, Inc. El panel, el esquema del grafo, el validador, los skills y las guías de lenguaje/marcos provienen de allí. Lo hemos vendido por completo y modificado, y cada archivo vendido tiene en su cabecera la ruta del proyecto original y qué se cambió.

• CodeGraph — MIT, © Colby McHenry. La fuente de todos los hechos estructurales. No está vendido: dependemos del paquete npm publicado, solo leemos su índice SQLite y llamamos a su bin.

La atribución archivo por archivo y la atribución completa de ambos están en NOTICE. Si este proyecto te resulta útil, ve primero a darle una estrella a esos dos repositorios — ArchView solo los conecta.

13. Si quieres cambiar algo

Primero lee CONTRACT.md (AGENTS.md es una vista rápida de una página para agentes, que apunta a lo mismo). Es la base de restricciones duras, no una guía de estilo — las cuatro reglas de hierro (el LLM no escribe topología / los resúmenes no están vacíos / las capas cubren todos los nodos de archivos / las aristas a nivel de archivo deben agregarse hacia arriba), el esquema de ID de nodos congelado, el esquema del grafo, la estrategia de módulos, la tabla de endpoints del servicio y la superficie de herramientas de MCP, todo está ahí, y cada regla tiene su «por qué» y «qué pasa si se viola». Violar cualquiera de ellas es un error de diseño.

Presta especial atención a dos puntos:

• El esquema de ID de nodos está congelado. Los archivos de resumen usan el ID de nodo como clave; cambiar el ID equivale a invalidar todos los activos de resumen existentes de todos.

• El esquema del grafo es exactamente el mismo que el esquema de UA vendido, sin añadir ni quitar nada. El panel está copiado tal cual; si el esquema cambia, hay que modificar el panel. La información privada va en los campos passthrough de los nodos (las aristas no son passthrough; los campos adicionales se eliminan silenciosamente, no dependas de eso).

Después de cambiar, al menos ejecuta:

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                                           # 同上；只读

Antes de ejecutar, limpia los residuos de variables de entorno ARCHVIEW_* (la sección 8 da los comandos para los dos shells), de lo contrario podrías estar probando otro repositorio.