Grafo de código y base de conocimientos

El grafo de código es experimental. Su interfaz, su formato de datos y su comportamiento de indexación pueden cambiar en versiones posteriores.

El grafo de código usa CodeGraph para analizar los símbolos de un proyecto y las relaciones entre ellos. La Base de conocimientos de sesiones almacena decisiones de diseño, restricciones y lecciones aprendidas. Las referencias al código conectan ambos, de modo que puede ver tanto la estructura actual del código como los motivos que la explican.

Páginas

El grafo de código se abre como un cuadro de diálogo con las pestañas «Vista general», «Símbolos», «Explorar código» y «Archivos». Su botón «Base de conocimientos» abre la base de conocimientos.

Vista general: el número de archivos, símbolos y relaciones, la distribución de lenguajes y de tipos de símbolo, y el estado de sincronización («Sincronización automática activa» o «Sincronizar antes de consultar»). Haga clic en un elemento de la distribución para ver los resultados correspondientes.
Símbolos: búsqueda por nombre o ruta de archivo («Buscar símbolos o rutas de archivo…»). La página de un símbolo muestra su código fuente con resaltado de sintaxis y sus «Relaciones entrantes» y «Relaciones salientes», agrupadas por tipo de relación y por archivo. Las relaciones deducidas por el análisis se marcan como «Relación inferida», y los números de línea llevan al lugar de la llamada.
Explorar código: describa una funcionalidad o un flujo, o indique un archivo o símbolo, y vea el código fuente y las relaciones pertinentes. Esta consulta se ejecuta localmente y no usa ningún modelo de IA.
Archivos: examine los archivos indexados; haga clic en un archivo para ver la lista de sus símbolos.
Símbolos que llaman y Símbolos llamados: en la página de un símbolo, muestran varios niveles de llamadas. La «Profundidad de recorrido» es 3 de forma predeterminada y 6 como máximo. Se muestran hasta 500 resultados; cuando hay más, se indican el total y un aviso.
Análisis de impacto: en la página de un símbolo, muestra los símbolos y archivos a los que podría afectar un cambio, hasta la profundidad elegida (3 de forma predeterminada, 6 como máximo). Se muestran hasta 500 símbolos y 2000 relaciones, con el total y un aviso cuando el resultado se recorta.
Ruta de llamadas: en la página de un símbolo, busque un símbolo de destino («Buscar un símbolo de destino…») para ver la ruta más corta a lo largo de las relaciones de llamada. «No se encontró una ruta de llamadas dirigida en el índice» solo significa que el índice no contiene esa ruta.

Cambie el directorio de trabajo desde el menú de directorios, que también muestra la ruta completa. La página, la pregunta de Explorar código, el símbolo, la profundidad, el destino y la línea de código fuente forman parte de la URL, de modo que puede actualizar la página, abrirla en una pestaña nueva o usar los botones Atrás y Adelante del navegador. Un enlace funciona en el mismo servidor con un inicio de sesión válido.

Activación del índice de un proyecto

Haga clic con el botón derecho en un proyecto o una colección de la barra lateral y elija «Experimental» → «Grafo de código».
La primera vez, haga clic en «Descargar CodeGraph». El servidor al que está conectado descarga de GitHub la versión fija 1.6.0 de CodeGraph y la verifica con una suma de comprobación SHA-256 integrada («La suma de comprobación de la descarga no coincide. No se ha instalado el entorno de ejecución» significa que la verificación ha fallado). No es necesario instalar Node.js por separado.
Elija el «Directorio de trabajo» y haga clic en «Activar indexación». El directorio del proyecto y los demás directorios de trabajo que usan sus sesiones y grupos se enumeran por separado; cada worktree de Git tiene su propio índice. Una colección necesita al menos una sesión con un directorio de trabajo válido.
Espere a que el estado sea «Listo» y, a continuación, busque símbolos o rutas de archivo. La indexación se ejecuta en segundo plano («Hay una tarea de indexación en curso. Puede cerrar esta página o desactivar la indexación para detenerla»), y cerrar la página no la cancela.

«Sincronizar» actualiza el índice manualmente o lo vuelve a intentar tras un error. Antes de cada consulta de código, VelaTerm también pone al día el índice. Para un mismo servidor y directorio de trabajo se reutiliza un único proceso de consultas que, mientras está en ejecución, incorpora los cambios de los archivos a medida que se producen. El proceso termina tras cinco minutos sin consultas; la siguiente consulta vuelve a abrir el índice y lo pone al día. La Vista general actualiza su estado de sincronización cada 30 segundos; cuando la sincronización automática no está disponible, VelaTerm sigue sincronizando antes de cada consulta y nunca presenta un resultado obsoleto como actual.

«Desactivar indexación» detiene una tarea de indexación en curso y conserva los archivos del índice y los vínculos con los artículos de conocimiento, de modo que puede volver a activarla más adelante. Cuando una tarea se interrumpe, en unos dos minutos su estado pasa a ser un error que se puede reintentar («La tarea anterior se interrumpió. Sincronice para volver a intentarlo»). Una tarea de indexación puede durar como máximo 30 minutos.

Los índices se almacenan en una carpeta .codegraph/ de cada directorio de trabajo y los gestiona CodeGraph. VelaTerm ejecuta la indexación por sí mismo; no ejecuta el instalador de agentes de CodeGraph ni instala hooks de Git. Si el directorio del proyecto es una subcarpeta de un repositorio, solo se indexa esa carpeta.

Consulta de las relaciones del código

Los resultados de búsqueda muestran el nombre, el tipo y la ubicación de cada símbolo. La página de un símbolo muestra su código fuente, sus relaciones entrantes y salientes y los artículos de conocimiento vinculados; haga clic en un símbolo vecino para continuar.

Las relaciones proceden de un análisis estático y pueden ser incompletas o inciertas («Las relaciones proceden de un análisis estático y pueden ser incompletas o inciertas»); no sustituyen a la ejecución del código. La página de un símbolo muestra como máximo 200 relaciones en cada dirección y 600 líneas de código fuente, con un aviso cuando hay más. Los archivos de código fuente de más de 4 MiB no se muestran. Si un archivo cambia mientras lo consulta, VelaTerm le pide que vuelva a sincronizar antes de fiarse de sus números de línea.

Vinculación y revisión de artículos

En la página de un símbolo, elija «Vincular artículo de conocimiento», seleccione un artículo existente, compare su texto con el código y guarde. En la página del artículo, «Referencias al código» lleva de vuelta al código, y los enlaces a artículos del grafo de código abren el artículo completo.

Un vínculo almacena el proyecto, el directorio de trabajo, la ruta del archivo, la identidad del símbolo y el resumen SHA-256 del archivo tal como estaba al revisarlo. Cuando el archivo cambia, el vínculo muestra «Requiere revisión»; cuando el archivo ya no se puede leer o se ha eliminado, muestra «No disponible»; en los demás casos, muestra «Sin cambios». La comprobación se hace por archivo, de modo que cualquier cambio en el mismo archivo obliga a revisar el vínculo. Una página de artículo abierta comprueba sus referencias periódicamente.

Elija «Revisar código y artículo» para ver el código actual y «Confirmar revisión» si el artículo sigue siendo válido. El servidor vuelve a comprobar que ni el archivo ni el artículo han cambiado entretanto y, si han cambiado, le pide que vuelva a cargarlos. La confirmación solo actualiza la referencia al código; no modifica el texto del artículo. Para cambiar la conclusión, edite el artículo como de costumbre.

Cuando un símbolo se elimina o se renombra, el vínculo no pasa a otro símbolo con el mismo nombre. Use «Eliminar vínculo» y vincule el símbolo correcto. Al eliminar un artículo se eliminan sus vínculos; al eliminar un proyecto se eliminan sus registros de índice y sus vínculos, pero no otros artículos ni los archivos de índice de los directorios de trabajo.

Consultas desde una sesión

Todas las sesiones de terminal y de agente que inicia VelaTerm disponen del comando vkb. Otros agentes capaces de ejecutar comandos de terminal también pueden usarlo. Si una sesión existente no encuentra vkb después de una actualización, reinicie la sesión.

Con «Vela Skills» instalado (Ajustes ▸ General), Claude puede usar /vkb y Codex, $vkb. La habilidad solo se ejecuta cuando usted la solicita explícitamente; los agentes no la invocan por su cuenta durante otros trabajos. Si un agente no muestra la habilidad después de una actualización, haga clic en «Reinstall» y reinicie la sesión de ese agente.

vkb status
vkb explore "how a session is created and its working directory chosen"
vkb search "greet"
vkb node "<symbol ID from a search result>"
vkb callers "<symbol ID>" 2
vkb callees "<symbol ID>" 2
vkb impact "<symbol ID>" 3
vkb path "<start symbol ID>" "<end symbol ID>"
vkb files "src/session"
vkb memories "design decision"
vkb memory "<entry ID from a search result>"
vkb notes "reading notes"
vkb note <knowledge-base-ID> "folder/note.md"

explore devuelve el mismo resultado que Explorar código.
callers, callees e impact aceptan una profundidad opcional; sus resultados incluyen relations, total, depth y truncated.
path recibe dos ID de símbolo exactos procedentes de los resultados de búsqueda, y files puede filtrar por ruta.
search devuelve por separado los resultados de código (ordenados por relevancia, con hasMore cuando hay más), los artículos de conocimiento y las notas locales.
node devuelve el código fuente de un símbolo, sus relaciones y los artículos vinculados.
memories y memory buscan y leen artículos de la base de conocimientos de sesiones, incluidas sus fuentes, revisiones y referencias al código.
notes y note buscan y leen las bases de conocimientos locales (consulte Bases de conocimientos locales).

Las consultas de código usan el índice del directorio en el que se ejecuta el comando. Una subcarpeta usa el índice de su proyecto, y un worktree independiente anidado nunca toma prestado el índice de la copia de trabajo principal. Cuando no hay ningún índice activado o una consulta falla, el resultado indica que el código no está disponible, y las consultas de conocimiento siguen funcionando. Estos comandos no instalan nada, no activan la indexación y no modifican artículos.

Ubicación de los datos

El entorno de ejecución de CodeGraph se instala en codegraph/1.6.0/, dentro del directorio de datos de la aplicación. Las tareas de indexación y los vínculos con artículos se almacenan en la base de datos de la aplicación (tablas knowledge_*). La indexación se ejecuta en el servidor donde reside el código; los clientes de navegador y las conexiones SSH leen los resultados a través de su conexión existente, por lo que no se abre ningún puerto adicional. Cada servidor mantiene su propia configuración de índices y su propia base de conocimientos.

La telemetría, la búsqueda de actualizaciones y el servicio independiente en segundo plano de CodeGraph están desactivados. VelaTerm gestiona el proceso de consultas y se comunica con él a través de un canal privado de entrada y salida estándar, sin escuchar en ningún puerto. La indexación en sí no usa IA. El código o los artículos que un agente lee con vkb pueden enviarse al servicio de modelos configurado para ese agente, igual que cuando el agente lee archivos de código fuente.

Los eventos del grafo de código se escriben en logs/runtime-*.log, en el directorio de datos de la aplicación. Cuando VLX_LOG_DIR no está definida, VLX_KNOWLEDGE_LOG_DIR establece su directorio. VLX_KNOWLEDGE_LOG_LEVEL los filtra (por ejemplo, error u off). El registro no contiene código fuente, texto de consultas, texto de artículos ni credenciales.

CodeGraph se desarrolla en github.com/colbymchenry/codegraph y se publica con la licencia MIT.