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:
Bohdan Triapitsyn
2026-08-02 16:22:55 +03:00
committed by GitHub
parent b1ec34162e
commit 34d0ff7383
99 changed files with 7316 additions and 53 deletions
@@ -0,0 +1,63 @@
---
title: 変更のウォークスルー
description: 差分をアルファベット順ではなく、意味の通る順序で読みます。
---
# 変更のウォークスルー
差分はファイルパス順に並びますが、それは変更の意味が通る順序であることはほとんどありません。ウォークスルーはこれを並べ替えます。関連する編集を**ステップ**にまとめ、各ステップはコードが今までと何が違う動きをするのかを説明し、前のステップの上に次が積み上がる順序で並びます。
説明し、順序を与えるものです。コードを評価したり判定を下したりはしません。それは [Review](/git/) の役割です。
右側のレールの**ウォークスルー**アイコン、または変更パネルとプルリクエストパネルの **AI ウォークスルー**ボタンから開きます。どちらもパネルを開くだけで、**ウォークスルーを生成**を押すまで何も生成されません。
## 対象にできる範囲
| 範囲 | 含まれるもの |
| --- | --- |
| 未コミットすべて | まだコミットされていないもの全部: ステージ済み、未ステージ、新規ファイル |
| ステージ済み | 今コミットすれば入るものだけ |
| 未ステージ | 作業ツリーと新規ファイル |
| このブランチ | ベースに無い、このブランチのすべてのコミット |
| プルリクエスト | GitHub 上に存在する形の変更 |
**このブランチ**は「未プッシュのコミット」ではなく、プッシュの有無に関わらずブランチがベースに追加したすべてです。そのためコミット後・プッシュ前には、これとプルリクエストは意図的に食い違います。前者はあなたが何をしたかを、後者はレビュアーが今何を見ているかを示します。
範囲ごとに別々に保存されるため、切り替えても失われるものはありません。
## モデルの選択
ウォークスルーは既定でスモールモデルを使います。**設定 → セッション → 変更ウォークスルーのモデル**で別のモデルを選べます。一度だけならパネルのヘッダーからも選べます。リスクの高い変更を、より強いモデルに任せたいときに便利です。
選択肢に出るのは構造化出力を返せるモデルだけです。それが無ければウォークスルーは組み立てられません。差分に対してモデルが小さすぎる場合は、入力を黙って切り詰めるのではなく、理由を示して生成を拒否します。差分の半分だけを見て書かれたウォークスルーは、自信ありげに間違えるからです。
パネルを開き直すと、目の前の内容を生成したモデルが表示されます。したがって**再生成**は、変更しない限り同じモデルで繰り返します。
## コストとキャッシュ
勝手に生成されることはありません。生成はあなたが求めたときだけ始まり、再生成も手動です。
結果は差分の正確な内容に対してキャッシュされます。作業ツリーを以前の状態に戻せば、そのときのウォークスルーがモデル呼び出し無しで戻ります。モデルを切り替えて戻しても、それぞれのウォークスルーは残っています。
生成はブラウザのタブではなく OpenChamber サーバー上で動きます。ページを再読み込みしてもパネルを閉じても処理は続き、戻れば結果が待っています。止められるのは**キャンセル**だけです。
## 古くなったことを正直に示す
各ステップは説明対象のコードの正確な内容に紐づいているため、そのコードが動いたことをパネルが伝えられます。
- **古くなったステップ** — ステップが説明していたコードが変わった、あるいは無くなった。ウォークスルーは印を付けたまま表示され、再生成するかはあなたが決めます。
- **未対応** — 現在の差分のうち、どのステップも説明していない変更。生成後に加えた編集、ウォークスルーが定型的と判断した変更、そして意図的にモデルへ渡していないロックファイルなどの生成物が含まれます。すべて末尾に一覧されるので、黙って消えるものはありません。
再生成は継ぎ当てではなく書き直しです。前回のウォークスルーが文脈としてモデルに渡るため、まだ正しい部分は残り、すべてが現在のコードに紐づけ直されます。
## 補足
- 差分ビューと同じように任意の行にコメントできます。コメントはチャットの入力欄に添付されます。
- デスクトップとタブレット幅で利用できます。VS Code 拡張とモバイルアプリでは提供されません。
- プルリクエストのウォークスルーには GitHub アカウントの接続が必要です。[GitHub の Issue と PR](/github/) を参照してください。
## 関連
- [Git と GitHub](/git/) — 読み取り元となる変更パネルと、実際にコードを評価する Review アクション
- [GitHub の Issue と PR](/github/) — プルリクエストを扱うために GitHub を接続する
- [プロバイダー・モデル・エージェント](/providers/) — スモールモデルの出どころ