feat(walkthrough): guided AI walkthrough for diffs, branches, and PRs (#2572)
A diff is ordered by file path, which is almost never the order in which a change makes sense. This adds a Walkthrough surface that reorders it: the model groups related hunks into stops, explains what each group changes about behavior, and orders the stops so each builds on the last. It explains and orders; judging code stays with the existing Review action. Reviews uncommitted work (all, staged, unstaged), a branch against its base, or a pull request. Generation is always user-initiated — nothing runs on a timer, on a file change, or as a side effect of opening a panel. Invariants worth preserving: - Hunk identity is derived on the server and only there. Ids are content hashes, so an anchor that no longer resolves is proof the code it described changed, and staleness needs no heuristics. The client matches ids to ids and never recomputes them; two implementations would have to agree forever. - The digest is never truncated. A diff that does not fit the model's context is refused with an actionable reason, because a walkthrough written against half a diff reads as confident and is wrong. - Nothing disappears. Lockfiles and other generated output are excluded from the model's input by name — never by size — and everything no stop covers is listed at the end, so "have I seen all of it" stays answerable. - Cost is explicit. Results are content-addressed, so returning the working tree to an earlier state costs nothing; generation outlives its request, so a refresh detaches the client rather than discarding paid-for work, and only an explicit cancel stops it. Supporting changes to shared modules: - git: expose the existing getRangeDiff as GET /api/git listUntrackedPaths and getUntrackedDiffs. The latter resolve the repository once for a batch instead of per file, taking a panel ~340ms on an 80-file working tree. - small-model: structured output across four wire forma and abort signal, and an onOverflow policy so an oversized prompt fails loudly instead of being silently clipped. A provider remembered so the prompt-side fallback goes first next time. - models.dev metadata: surface structured_output as tri false blocks a model, a missing field does not, because the catalog omits it for roughly half of all models. Desktop and tablet only: VS Code serves Git through its these routes, and the mobile shell does not consume the surface registry. Docs: packages/docs walkthrough page in English and all eight locales.
This commit is contained in:
committed by
GitHub
parent
b1ec34162e
commit
34d0ff7383
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Recorrido por los cambios
|
||||
description: Lee un diff en el orden que tiene sentido, no en orden alfabético.
|
||||
---
|
||||
|
||||
# Recorrido por los cambios
|
||||
|
||||
Un diff está ordenado por ruta de archivo, que casi nunca es el orden en el que el cambio cobra sentido. El recorrido lo reordena: las ediciones relacionadas se agrupan en **paradas**, cada parada explica qué hace ahora el código de forma distinta, y las paradas se ordenan para que cada una se apoye en la anterior.
|
||||
|
||||
Explica y ordena. No juzga tu código ni emite veredictos — para eso está [Review](/git/).
|
||||
|
||||
Ábrelo con el icono **Recorrido** en la barra derecha, o con el botón **Recorrido con IA** en los paneles de cambios y de pull request. Ambos solo abren el panel; no se genera nada hasta que pulsas **Generar recorrido**.
|
||||
|
||||
## Qué puede recorrer
|
||||
|
||||
| Ámbito | Qué incluye |
|
||||
| --- | --- |
|
||||
| Todo sin confirmar | Todo lo que aún no está en un commit: preparado, sin preparar y archivos nuevos |
|
||||
| Preparados | Solo lo que iría a un commit ahora mismo |
|
||||
| Sin preparar | Árbol de trabajo y archivos nuevos |
|
||||
| Esta rama | Todos los commits de la rama que no están en su base |
|
||||
| Pull request | El cambio tal como existe en GitHub |
|
||||
|
||||
**Esta rama** no significa "commits sin subir": es todo lo que la rama añade a su base, se haya subido o no. Por eso, tras hacer commit pero antes de subirlo, esta y el pull request difieren a propósito: una muestra lo que hiciste, el otro lo que ven ahora quienes revisan.
|
||||
|
||||
Cada ámbito se guarda por separado, así que cambiar entre ellos nunca pierde nada.
|
||||
|
||||
## Elegir el modelo
|
||||
|
||||
Los recorridos usan tu modelo pequeño por defecto. Elige otro en **Ajustes → Sesiones → Modelo del recorrido de cambios**, o solo para una revisión desde la cabecera del panel — útil cuando un cambio es lo bastante delicado como para merecer un modelo más potente.
|
||||
|
||||
El selector solo ofrece modelos capaces de devolver salida estructurada, porque sin ella el recorrido no se puede montar. Si un modelo se queda corto para el diff, la generación se rechaza con una explicación en vez de recortar la entrada en silencio: un recorrido escrito sobre medio diff suena seguro y se equivoca.
|
||||
|
||||
Al reabrir el panel verás el modelo que produjo lo que tienes delante, así que **Regenerar** repite con el mismo salvo que lo cambies.
|
||||
|
||||
## Coste y caché
|
||||
|
||||
Nada se genera por su cuenta. La generación solo empieza cuando la pides, y regenerar también es manual.
|
||||
|
||||
Los resultados se guardan en caché según el contenido exacto del diff. Devuelve el árbol de trabajo a un estado anterior y el recorrido anterior vuelve gratis, sin llamar al modelo. Cambia de modelo y vuelve: el recorrido de cada uno sigue ahí.
|
||||
|
||||
La generación se ejecuta en el servidor de OpenChamber, no en la pestaña del navegador. Recarga la página o cierra el panel y continúa; al volver, el resultado te espera. Solo **Cancelar** la detiene.
|
||||
|
||||
## Ser honesto sobre lo desactualizado
|
||||
|
||||
Cada parada está anclada al contenido exacto del código que describe, así que el panel puede avisarte cuando ese código ha cambiado:
|
||||
|
||||
- **Pasos desactualizados** — el código que describía una parada cambió o desapareció. El recorrido se sigue mostrando, marcado, para que decidas si regenerar.
|
||||
- **Sin cubrir** — cambios del diff actual que ninguna parada describe. Ahí entran las ediciones hechas después de generar, los cambios que el recorrido consideró rutinarios y los archivos de bloqueo u otra salida generada, que se dejan fuera del modelo a propósito. Todo aparece al final para que nada desaparezca en silencio.
|
||||
|
||||
Regenerar no parchea, reescribe: el recorrido anterior va al modelo como contexto, así que lo que sigue siendo cierto se conserva, y todo se reancla al código actual.
|
||||
|
||||
## Notas
|
||||
|
||||
- Puedes comentar cualquier línea igual que en la vista de diff; los comentarios se adjuntan al campo del chat.
|
||||
- Disponible en escritorio y anchos de tableta. No se ofrece en la extensión de VS Code ni en la app móvil.
|
||||
- Recorrer un pull request requiere una cuenta de GitHub conectada — consulta [Issues y PR de GitHub](/github/).
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Git y GitHub](/git/) — el panel de cambios del que lee, y la acción Review que sí juzga el código
|
||||
- [Issues y PR de GitHub](/github/) — conecta GitHub para recorrer pull requests
|
||||
- [Proveedores, modelos y agentes](/providers/) — de dónde sale el modelo pequeño
|
||||
Reference in New Issue
Block a user