ArchView

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

Monousuario, local, y enlazado únicamente a 127.0.0.1. Interfaz en chino por defecto.

Si quieres ponerte con ello ya: salta a la sección 5: cuatro comandos que se pueden copiar, pegar y ejecutar. Si primero quieres decidir si vale la pena: la sección 3 (por qué existe) y la sección 10 (limitaciones conocidas / para quién no es).

1. Qué problema resuelve

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

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

2. Para el agente de tu IDE: que los asistentes de Cursor / Kiro / Claude Code conozcan con exactitud la estructura del proyecto, sin depender de adivinar con grep.

Lo que existe ya se queda a medias:

ArchView conecta las dos: CodeGraph aporta los hechos, UA aportsa el interfaz, y el LLM solo aporta la semántica.

Related MCP server: SGraph MCP Server

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

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

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

Este es el único fundamento técnico del proyecto y la única regla que no admite concesiones:

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

La diferencia es muy concreta. Los proyectos cuya topología está generada por LLM necesitan además una máquina de parches: normalizar los IDs que no encajan, descartar aristas escritas que apuntan a nodos que no existen, invertir aristas con la dirección equivocada. Esos scripts son ya la prueba de que « la estructura no es fiable ». Los ArchView no se utilizan: que una arista exista significa que tree-sitter ha recuperado de verdad esa referencia en el código fuente.

Las tres reglas que la acompañan (cobertura, cobertura de capas y subir las aristas a nivel de archivo) y todas las restricciones de implementación están en CONTRACT.md. No existe ninguna herramienta de escritura de grafos en la superficie de herramientas de MCP.

4. Qué se necesita

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

Estado de plataforma (no esperes que hayamos probado en todas)

• Windows: es la plataforma principal de desarrollo y validación. Los comandos y las salidas de este README provienen de una ejecución real en Windows 11 (build 26200) + PowerShell + Node 22.20.0 + pnpm 10.28.2. La instalación del skill usa junction, sin permisos de administrador. Para ver qué puerto está en uso: netstat -ano | findstr :7420.

• macOS / Linux: en el código están escritas todas las ramas específicas de la plataforma (abrir el navegador con open/xdg-open, la instalación del skill se degradó a symlink), pero no hemos ejecutado una validación sistemática en estos dos plataformas. Si encuentras un problema, abre un issue, no lo que lo esperemos como el violín.

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

5. Primeros pasos: del clon a ver el diagrama

Cuatro pasos. En cada paso escribimos claro dónde ejecutarlo, qué pasa al terminar y cómo saber si ha funcionado.

Paso 1: instalar dependencias + compilar

En la raíz del repositorio (es decir, en archview/):

pnpm install
pnpm build

Cuando termines, los seis paquetes se compilan. Cinco los compila el tsc a dist/; packages/web el Via a packages/web/dist/ (el producto del frontend del panel; el serviciode depende de él para tener páginas).

Cómo saber si ha funcionado: packages/cli/dist/bin/archview.js y packages/web/dist/index.html existen, y esta línea saca la ayuda:

pnpm archview --help

En el primer pnpm install saldrá una tanda de WARN Failed to create bin at … ENOENT. Los bin de los cuatro paquetes apuntan a dist/, y el primer dist/ aún no existe, así que pnpm no puede crear los enlaces de node_modules/.bin/ (el autor ha meditado 12 WARN en un clon limpio). Es inofensivo: todos los comandos que vienen después utilizan el script npm de la raíz pnpm archview (equivalente a node packages/cli/dist/bin/archview.js), que no depende de los acoplamientos bin. Si quieres tener los comandos reales archview / archview-skill: después de pnpm build vuelve a ejecutar pnpm install; esta vez los enlaces crearán, y luego pnpm exec archview --version servirá. Deliberadamente no añadimos un script prepare que compile solo: no se debe forzar a una compilación completa de Vite a quien solo quiere instalar dependencias (cache de CI, cambiar solo documentación).

⚠️ typecheck siempre necesita después de build

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

A la inversa, falla sí o sí: saldrá una tanda de TS2307: Cannot find module '@archview/core' '(o su subpath, por ejemplo '@archview/core/themes') o or its corresponding type declarations. La razón es que los tipos entre paquetes pasan por los exportsdelpackage.jsonde cada paquete →dist/*.d.ts, y dist/estágitignore: **si no has hecho build, no hay .d.ts**. No hay TS project references en el repositorio, ni alias de rutas que devuelvan los tipos a src`; por tanto no es un fallo de config, sino una propiedad estructural: cualquiera que llegue se va a dar de bruces con ella. Recuerda el orden.

Esa misma mecánica también te salta en el desarrollo normal: en cuanto alguien añade un subpath exportado en el src/ de un paquete, los demás no pasan el typecheck hasta que ese paquete no se reconstruya. Veas un núcleo TS2307 primero piensa: «¿habrá que compilar antes?».

Paso 2: conectar con el repositorio que quieres analizar

Sigues en archview/. Cambia la ruta a tu propio repositorio:

pnpm archview init d:/code/my-repo

Qué ocurre al terminar (cinco pasos, todas las setas; si lo repites solo te cuenta el estado):

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

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

3. Escribe el .archview/config.json (no lo sobrescribe si existe; solo --force-config lo rehace), y en función de oh-package.json5 / pnpm-workspace.yaml / Cargo.toml / go.mod prellen del muelle de módulos

4. Añade --de forma idempotente-- un bloque marcado al final del .gitignore de tu repositorio (detalle en la sección 7)

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

Cómo saber si ha funcionado: al final se muestra el id del workspace y el siguiente comando. Una salida real (en este caso se usó la copia del propio código 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> (para URL, solo acepta [a-z0-9][a-z0-9_-]*), --name 「nombre visible」, --skip-index, --telemetry-off. Lista completa: pnpm archview init --help.

Paso 3: crear los datos del panel

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

Qué pasa al terminar: codegraph sync (sin dejar atrás el disco) → construir grafo → escribir .archview/graph.json y meta.json → generar .archview/briefs/*.json (los briefs de complejidad para el LLM) → comprobar una vez más el bloque .gitignore.

Cómo saber si ha funcionado: cada paso va precedido de ✓, y al final se muestra el número de nodos / aristas / módulos y la cobertura de resumen. Esta ejecución real:

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

Que el coverage sea 0 % es el primer resultado normal: los resumos semánticos los escribe el agente, que termina en la sección 6.

Si hay advertencias (por ejemplo, porque los resúmenes los metieron de encima en un subdirectorio y ni uno se lee), build los close en un bloque aparte y te dice cómo arreglarlos. Una advertencia no es un fallo: el grafo se ha construido, pero esas cosas no han tenido effect.

Puedes revisar lo que sea en cualquier momento:

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

los números de status y los de la homepage del workspace vienen de la misma función que archview_status de MCP — no habrá nunca dos coberturas distintas.

Paso 4: arrancar el servicio para ver el grafo

pnpm archview serve --open

Qué pasa al terminar: un proceso y un puerto solo sirven a todos los todos los workspaces registrados. Por defecto, 127.0.0.1:7420; si está ocupado, se sube automáticamente (máximo 20); y si se le pasa --port explícito no busca otros, si el puerto está ocupado falla. El arranque muestra un token de sesión de un solo uso, y todos los api/* lo tienen en cuenta.

Cómo saber que ha funcionado: el banner se ve así (una ejecución real; token recortado):

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

La línea de «panel distribuido» debe apuntar a un packages/web/dist que de realidad: si no te compilado el frontend, la página de lista lo indica explícitamente con panel frontend no build, y entonces basta pnpm --filter @archview/web build.

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

Prueba real del propio servicio (todas con token):

Si no quieres pasar por pnpm:

node packages/cli/dist/bin/archview.js --help        # 总览
node packages/cli/dist/bin/archview.js init --help   # 每个子命令都有 --help
node packages/server/dist/bin/serve.js --port 7500   # 只起服务，跟 archview serve 是同一个 startServer

6. Que el agente complete la semántica

Cuando el grafo termina de crearse, los nodos que tenemos, pero el summary de cada nodo es todavía una frase determinista de Relleno (docstring / sintetizado por el nombre / < name> —— la kind en »). Que sean frases naturales es tarea del agente.

Ruta de instalación cero (prueba primero esta)

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

2. Pega el prompt a la IA que está editando ese mismo repositorio. El prompt es muy corto; lo principal de assenta al AGENT-GUIDE.md del <workspace>/.archview/, un archivo local que cualquier herramienta puede leer.

3. Need one of before AGENT-GUIDE.md (build no lo genera automáticamente):

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

   En esta ejecución real se han salvado 22 KB (22185 bytes), with ten: la regla de hierro, el estado actual de este workspace, qué resúmenes faltan (y un lista de nodeId), los resúmenes que ya no están vivos, tus entradas (las rutas de estructura/resumen), la guía elegida según el lenguaje detectado, el formato de salida y el método de entrada, los endpoints para dispar una reconstrucción + leer el estado, la lista de checkeo antes de la entrega, y el formato del informe. Este comando está también incluido en el prompt, así que el agente puede ejecutarlo por sí solo.

   Tas generarlo una vez no vuelves a pensar en él: de cada reconstrucción (botón del panel / archview build / POST api/rebuild / MCP archview_rebuild) lo sobreescribe entero (el contrato en su sección 2 lo pide, y por eso está en gitignore). En los steps de la reconstrucción se ve si writeAgente se ha ejecutado. Dicho a la inversa: si el fichero no existe, la reconstrucción no lo crea por ti por ti — nosotros no guardamos en tu workspace ningún fichero que no hayas pedido.

4. El agente sigue el guión para escribir los resúmenos en .archview/summaries/<分片>.json. Lespeciallyr archivo de fragmento = la clave de módulo con / convertido en _ (módulo packages/core → packages_core.json). ese directorio es plano; la guía que pongas do within a subdirectory no se le leen literalmente (habrá hueco, pero esa ronda habrá sido en vano).

5. Rebuild: pnpm archview build, o cmts en la pagina listado, o el agente mismo una POST /w/<id>/api/rebuild?token=….

6. En el panel aparece la semícantica, y la cobertura de status sube.

El envío de resúmeneses tiene una verja en ser: no. (los valores por defecto en packages/core/src/limits.ts): cada uno 30 a 140 caracteres, tags ≤6 y cada uno ≤16 caracteres, lote por ≤200 (si se pasa, se disgusta todo el lote, no se escribe ni uno, no se truncan) y además una «palabra vacía de lista» que video a «responsable de the related logic» like nonsense. El peso / umbral y la lista exacta solo tiene una fuente, en @archview/core: MCP lo use para aplicarlo, el skill para escribir con esa misma lista — lo que exige que esta enseñan a otra parte sino que cumple con el justo (éste un bug).

⚠️ El guarda la guarda solo en la ruta de MCP se aplica automátic. Si escribes las resúmenes (en el caso de la paso 4 de la arriba) no hay nada que los comprobar (si la escribes mal, no se verás: entra en silencio al panel). Por lo tanto, después de escribir directamente los archivos, ejecuta una autoexaminación con exactamente el mismo código que MCP (checkSummaryItem de @archview/core):

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

Esta report one by nodeId orphans, length limit exceeded, the tags quantity/limits/used with the etiquetas de determinismo, vac aggiunto (oos), si el hash es igual al actual content_hash, y si hay basura en summaries/, if a fragment JSON is valid; no hay tese manuel then exit code nonzero. the way A of AGENT-GUIDE and the auto-check-list both reference it.

Ruta avanzada: instalar skill + MCP

Más Economía de tokens (no tienes que leer su código completo, basta con leer los briefs) y el envío tiene una validación estructurada.

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

Ejecución real: skill hosts tiene 7 hosts confirmados (kiro, claude, cursor, codex, opencode, gemini, copilot CLI) y una lista de una hoja de no soportado (rutas que camian según plataforma/versión y no se pueden repetir para verificar; nosotros no adivim, y lo pones a mano con /skill/download). skill verify mide en la ejecución: «38 language guides, 10 framework guides, todos hogue, not placeholders, with upstream annotations and ArchView modification paragraph».

Prioridad de Kiro: el skill se instala en ~/.kiro/skills/archview, el agente en ~/.kiro/agents/archview.json y MCP en ~/.kiro/settings/mcp.json. El instalador merge no se sobreescribe (solo toca mcpServers.archview, una); antes de cambiar un archivo dejja antes um .bak-<timestamp>; Windows usa junction en lugar de symlink. --dry-run imprime el contenido que escribirá exactamente (en la realidad comprobamos que no escribe ni un byte), y --home <dir> permite apuntar a un HOME alternativo para probar.

También puedes no instalar el skill y copiar config de MCP: en AGENT-GUIDE.md y meta.mcp.snippet de api/prompt vienen el snippet que puedes pegar, apuntando al packages/mcp/dist/bin/mcp.js construido del mismo repo.

Herramientas de MCP de seis, solo de lectura + envío de resumen, no hay ninguna herramienta de escritura de grafo:

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

7. Dónde van los datos / qué debería subirse a git

Esta sección decide si tus resúmenes seguirán ahí cuando cambies de máquina. Todos los datos van a parar al repositorio que se está analizando, no al 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 criterio es uno solo: lo que humanos y LLM han ido acumulando se hace commit; lo que las herramientas pueden volver a calcular, no.

• summaries/ son cientos de resúmenes en chino escritos por humanos/LLM; regenerarlos cuesta tokens de verdad. Viajan con el código: seguirán ahí al cambiar de máquina, de persona o de agente.

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

• Todo lo demás se puede recalcular en menos de diez segundos con archview build. AGENT-GUIDE.md sobre todo no debería sometearse a commit: cada reconstrucción la reescribe entera con su marca de tiempo, y hacerle commit solo crea conflictos.

archview init y cada rebuild añadirán de forma idempotente ese bloque a tu .gitignore del repositorio (se detecta por una marca; repetir la ejecución no lo duplica ni toca las líneas que ya tenías):

# >>> 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 se llaman igual: una sola línea los cubre a todos), dist-pack/, *.tsbuildinfo, .tmp/, .codegraph/ y *.db*、*.log, .env*, los directorios de editores, y también workspaces.json.

workspaces.json es el registro de espacios de trabajo; su contenido son rutas absolutas de esta máquina (d:/code/my-repo), así que cambian de una máquina a otra. Por eso en un repositorio recién clonado esa tabla siempre está vacía; es diseño, no una carencia. Créatela tú con archview init.

8. Scripts de aceptación

Cinco scripts más una tanda de pruebas unitarias suman en conjunto más de ciento cincuenta aserciones. La mayoría son «arrancar el servicio → probar → pararlo», no dejan procesos residentes y las escrituras en el espacio de trabajo inspeccionado son reversibles.

Prerrequisito común: pnpm build y al menos un espacio de trabajo real que ya haya pasado por archview build. A propósito no usan datos ficticios — el valor de estas comprobaciones reside en los números reales (históricamente fue con datos reales como aparecieron las 2253 advertencias de auto-corrected). Si no hay ningún espacio de trabajo, imprimen qué se puede hacer y hacen exit 1, sin soltar ningún stack de excepciones.

La columna «medición» siguiente se ha obtenido ejecutándolo en un espacio de trabajo TypeScript (una copia del propio código fuente de ArchView, ver sección 9, punto A); las aserciones específicas de ArkTS se marcan explícitamente como «omitidas / no aplicables» en ese tipo de espacio de trabajo y no cuentan como fracapos.

Antes de pisar, 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 lo que cambia es qué registro se lee; ARCHVIEW_ACCEPT_WS / ARCHVIEW_MCP_WS / ARCHVIEW_CHECK_WS lo que cambian es qué espacio de trabajo analiza. Si se quedan una vez en el shell, aparece la ilusión más costosa de tiempo: «sin tocar el código, han cambiado los números de la aceptación» — porque en realidad ya se está haciendo la prueba contra otro repositorio. Lo mismo vale en CLI: archview init|build|status --workspaces <file> permite decir explícitamente el registro; si se trabaja con varios registros en paralelo, se recomienda poner el flag en cada comando y no fiarse del estado que guardan las variables.

Hay tres trampas que solo se ven al pisarlas:

• selfcheck.mjs al terminar borra todo el directorio archview/.tmp/ (a menos que se da --keep), no solo su propia subcarpeta. No dejes en .tmp/ nada que quieras conservar.

• packages/mcp/scripts/acceptance.mjs lee solo el workspaces.json de la raíz del repositorio, no reconoce ARCHVIEW_WORKSPACES (el resto de entradas sí). Para hacerlo actuar sobre otro registro, hay que editar ese archivo directamente.

• En la aceptación del MCP, la aserción «al escribir en un fragmento existente, primero se combina 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 un resumen (p. ej. un módulo _other con un solo archivo), cuando el hueco se crea queda el fragmento vacío y no hay lugar para esa aserción, así que de una línea 36/37. Es un problema de la forma del espacio de trabajo, no de code: escribe los resúmenes de forma más completa o haz que el primer fragmento correspondiente a un módulo con varios archivos.

9. Números medidos (conletamente

Los números cambian con el contenido del repositorio, así que cada uno lleva repositorio, momento y criterio.

A. ArchView se analiza a sí mismo (en esta ocasión se ha vuelto a ejecutar para escribir este README; se ha analizado una copia del código fuente de ArchView, excluyendo node_modules/, dist/, .tmp/; Windows 11 / Node 22.20.0 / pnpm 10.28.2):

Estos valores se mueven según cambie el fuente. Con exactamente el mismo criterio, una versión anterior del código fuente daba 899 nodos / 6 módulos / 618 aristas de archivo / 148 aristas agregadas. La diferencia viene toda de que el códigofuente ha crecido, no de que la práctica haya cambiado: por lo tanto no uses esos números como una línea base para afirmar nada; si necesitas afirmar, corre los scripts de aceptación.

B. AMCL (app HarmonyOS / ArkTS que hay en la máquina del autor, 10 módulos ohpm) — estos provienen de una ejecución anterior, no se vuelven a correr (el trabajo no está dentro de este repositorio, y no debe verse modificado por la validación de esta README): 4277 nodos / 16124 aristas / 10 módulos / cobertura de resúmenes 304 de 304 / aristas de archivo 2115 / vista general de 24 pares de módulos 1246 aristas. El intervalo de caracteres (40–80) del resumen en packages/core/companion genuinely (40-80) fue también medido sobre ese lote de resúmen hechos a mano: min 36 / p50 57 / p95 78 / max 108.

10. Limitaciones conocidas / quién no deberia usarla

Lista que se mira a uno mismo. Sin humo.

• herramienta de una sola máquina, sin modelo multiusuario. Solo se ata a 127.0.0.1, la única auth es un token de sesión de un solo uso, nivel de proceso. Sin cuentas, sin papeles, sin auditoría. No la expongas a internet ni la despliegues como un servicio para un equipo.

• **Se reconstruyó concurrentemente sin lock entre procesos. ** Es lanzado la misma zona tanto desde el panel, comando y MCP, gana quien escribe el disco el último. Con un solo uso no pasa nada; no escribas un script que llame a este en paralelo.

• graph.json / meta.json / los fragmentos de resumen se sobrescriben, no son atómico (no tiene el paso de «escribir un temporal y luego hacer el rename»). Si la salida es normal, no hay problema; una caía de corriente o que se corte el proceso mientras se escribe puede dejar archivos a medias — basta con eliminar y archivo build de nuevo, porque todo es derivado. El único que todavía hace escritura atómica es workspaces.json (del registro).

• /skill/download y /skill/* no comprueban el token. Estos endpoints devuelven de document del skill, its meant to be descargado por cualquier host de agent, por eso deliberadamente no se le ha puesto control de access delante. Todos los endpoints que leen tu código (api/graph.json, api/file, api/rebuild …) comparan y validan. Al estar ligado solo a 127.0.0.1, quien le entra es un proceso de la propia máquina; la base de ese tradeoff es “no exponer”.

• La calidad de los resúmenes depende totalmente de tu agente y del presupuesto que le pongas. ArchView garantiza únicamente «la topología es verdadera» y «no se pueden decir cosas vacías», no nos garantiza que el resumen esté bien escrito. La red de seguridad puede detener los que en esa «lista de vacías», pero no una frase que sea correcta pero inútil.

• HarmonyOS / ArkTS es el único escenario con validación completa. El reconocimiento de módulos ohpm, el de los canales de rizado del componente ArkUI y el resaltado .ets están pulidos sobre un proyecto ArkTS real. Para otros lenguajes solo se puede hacer capal estructura de validación (que indexa, que grafo, que reconoce módulos, que panel renderiza), sin la deducción orientada a un framework concreto, y las guías de lenguaje se han self-checked solo en el documento.

• La aceptación solo se ha ejecutado sistemáticamente en Windows. Las ramas para macOS / Linux están escritas pero no probada.

• No es « un botón para entender un repositorio que no conoces **». En el primer init un repo grande puede tardar unos minutos (Index de CodeGraph), y los resúmenes requieren al agente varias rondas. Se desempeña un proyecto que va a mantener a largo plazo, no para explorar con 10 minutos un repo ajeno.

• En la vista general, las aristas entre layers son no dirigidas. El método aggregateLayerEdges vendado junta A→B con B→A. La información de dirección sigue en la vista de seguimiento la funcionar las partes.

• Las importaciones interpackage que pasan por el barrel de raíz de paquete no se resuelven; así que en la vista general falta la arista. CodeGraph sí resuelve los cross-package desde rutas profundas (como import { startServer } from '../../server/src/rebuild.js', but the package entry and is re-exported later by package.json's "exports" hacia el propio implementation — no resuelve el símbolo destino, y esa dependencia no entra el grafo. Esto es un ejemplo del mismo repo: packages/cli/src/commands/serve.ts pasa por barrel, y en importsFrom no aparece server; build.ts goes por ruta quedando profundo, and that is resolved. Si ves que en la vista general falta una arista que Estas seguro de que existe, sospecha primero de esta causa (mira el importsFrom de un archivo: sin tarjeta de entrada no tendrás). Esto es el límite de la resolución de CodeGraph, no una opción configurable; hemos obrado de intento no agregar esa línea por adivinanza en el builder: adivinar topología es otra forma de que a la LLM escriba topología, acabando con la Regla de 1. Si de verdad quieres verla en el grafo, convierte la importación en símbolo profundo (o espera que CodeGraph apoyo).

• Las aristas se filtran por confidence / resolvedBy (límite por defecto 0.7, se desprecian las heuristic). Sin la se mira que el módulo debería coincidir, porque no hace nada (se han visto confidence: 0.3 fuzzy) edges. Por otra parte, las dependencias reales que se filtran no se ven.

• La telemetría de CodeGraph está activada de serie, pero cuando lo ejecutamos en tú nombre está siempre acompañado de DO_NOT_TRACK=1 y CODEGRAPH_NO_UPDATE_CHECK=1 (está en runCodegraph, no es opción). Decir si quieres apagar también el general: pnpm archview init … --telemetry-off.

• Los endpoints de navegación de origen tienen limitaciones duras: /w/<id>/api/file? “state” es lo que ya existe en el grafo filePath (allowlist), rechaza de ..` / absolute path, can up to 1 MB, rechaza binarios.

11. Arquitectura y estructura de paquetes

archview/
  package.json            pnpm workspace 根（scripts: build / typecheck / selfcheck / archview）
  LICENSE  NOTICE  README.md  CONTRACT.md
  workspaces.json         工作区注册表（本机绝对路径，不提交）
  final-check.mjs         整体验收（起→测→停）
  packages/
    core/     图模型与校验（vendored UA schema）、CodeGraph 读取、builder(CG→图)、
              模块策略、框架 deriver、结构简报、.archview/ 布局与选择性 gitignore、
              提交护栏阈值与空话词表（唯一真身）
    web/      vendored 改造的 dashboard。按 /w/<id>/api/* 取数，中文默认开
    server/   单端口服务：工作区列表页 + 每工作区的面板与只读 API + rebuild
              bin: packages/server/dist/bin/serve.js   (archview-serve)
    mcp/      MCP server（stdio）。六个工具，只读 + 提交摘要
              bin: packages/mcp/dist/bin/mcp.js        (archview-mcp)
    skill/    SKILL.md 顶层提示词、38 份语言指导 + 10 份框架指导、
              AGENT-GUIDE.md 生成器、多宿主安装器
              bin: packages/skill/dist/bin/skill.js    (archview-skill)
    cli/      统一入口：init | build | serve | status | skill
              bin: packages/cli/dist/bin/archview.js   (archview)

cli no reimplementa ninguna lógica: build llama a rebuild del servidor, status a inspect, serve a startServer, skill reenvia a la archview-skill. the reason is que ** panel, MCP y commando de línea tienen que devolver el mismo número para lo mismo**: si una métrica como el coverage tiene dos fuente, los dos números divergen acaban enseguida. El fluj de datos en unas pocas palabras:

你的源码 ──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 es MIT (LICENSE). Y además se apoya en dos proyectos MIT:

• Understand-Anything — MIT, © Yuxiang Lin and Infinite Universe, Inc. Panel, schema de grafo, validador, skill y guías de lenguaje/framework sonleed. De ellos hemos hecho full vendor y modificación, y cada archivo vendado cómo tiene su correspondencia upstream y qué ha sido los cambio.

• CodeGraph — MIT, © Colby McHenry. Es la fuente de toda la verdad estructural. No es vendor: dependemos del paquete npm publicado, solo leemos su índice SQLite, llamamos su binari.

Full mention to each file and both projects are they. If a project is useful to you, go first darle estrella the two emporios above: ArchView only does online, works.

13. Si puedes cambiar algo

Primero el CONTRACT.md. Es el fundamento sólido, no una guía de estilo: cuatro reglas de hierro (LLM no topología / summary no vacía / layer cubre todo archivo nodo / aristas a nivel de archivo deben subir), la de identificación de nodo congelada, el esquema de grafo, estrategia de gran ancla, la tabla de endpoints de servicio, la superficie tool de MCP — todo está ahí, y cada regla lleva ¿cómo y qué pasa si la violo? Violaciones de cualquiera es un error de diseño.

Sobre todo dos ideas:

• La identificación de bug de nodos es congelada. Los ficheros de resumen usan el nodo ID como key; cambiarla equivale a perder el dataset de resúmenes que todos tienen.

• El esquema del grafo es exactamente el mismo que el esquema de UA ha vendado, sin más ni menos. El panel es un duplicado; el esquema da movimiento cambiar también al menú. La información privada se mueve por el campo passthrough del nodo no (las aristas no son paspastías: los extra se desprenden silenciosamente, no te apoyes en ello).

Al final, vengan en al menos:

pnpm -r run build                      # 一定在 typecheck 之前
pnpm -r run typecheck
pnpm --filter @archview/server run test
node packages/core/scripts/selfcheck.mjs --workspace <你的工作区目录>
node packages/server/scripts/acceptance.mjs
node packages/mcp/scripts/acceptance.mjs
node final-check.mjs

Si te importa primero, limpia los restos de variables ARCHVIEW_* (sección 8 te da los dos comandos shell), porque si no es probable que elijas otro repositorio.