Doc Reader
1次資料を読んでいて詰まった箇所にだけ、事前に生成しておいた解説をホバーで出す VS Code 拡張。
考え方
要約を読むと「他人の言葉」で理解することになる。だから二次資料は作らない。
主役はあくまで原文で、解説は読む速度を落としている箇所（知らない語・意味の掴めないブロック）
にだけ脇から出す。AIの出力を読ませないための、AIの使い方。
学術的には ScholarPhi (CHI 2021, Head et al.) が論文向けに実証した方向性で、
IDE のホバー機能をコード以外の資料にも一般化するもの。
責務の分離
この拡張は「中身を知らないレンダラ」である。
| 担当 |
中身 |
| 拡張機能（このリポジトリ） |
JSON を読む → 該当範囲に印をつける → ホバーで出す |
| 説明データ (JSON) |
別環境で生成する。業務知識はすべてこちら側 |
| 生成スクリプト |
拡張には同梱しない。完全に別プロセス |
拡張側に業務知識・ドメイン固有のロジックを一切入れないため、拡張は公開しても
業務情報が漏れない。またJSONスキーマが変わっても拡張を作り直さずに済む。
ホバー時にAIへ問い合わせることはしない。 事前生成した JSON を引くだけ。
表示方針
既定では下線を出さない。原文の見た目を完全に保つ。
Doc Reader: 下線の表示を切り替える（docReader.toggleUnderlines）を実行した間だけ、
解説のある箇所すべてに下線が浮かび上がる。
使い方
- ワークスペースに
.docreader/ を作り、docs/schema.md の形式で JSON を置く
（pool / anchors / notes の3種類。notes が最後に上書きする）
- コードを開くと、解説のある語にポインタを乗せたときだけホバーが出る
- PDF は右クリック →「エディターを選択」→
Doc Reader: PDF で開く。
既定のビューアは奪わないので、明示的に選ばないと従来どおりに開く
コマンド
| コマンド |
すること |
Doc Reader: 状態を表示 |
読み込んだ件数・見つからない document・salience 別と layer 別の件数・開いている文書のカバー率（識別子のうち解説のある語の割合と、無い語の一覧）を出力チャンネルに出す |
Doc Reader: 説明データを読み直す |
JSON を読み直す（ファイル変更時は自動でも走る） |
Doc Reader: 下線の表示を切り替える |
解説のある箇所の下線を出す／消す |
Doc Reader: ここにメモを書く |
選んだ語（何も選んでいなければその行）に、自分の言葉でメモを書く。右クリックからも呼べる |
Doc Reader: AI への指示書をコピー |
説明データを作る側の AI に渡す指示書（prompt/generate.md）をクリップボードに入れる。検証 CLI の実際のパスが埋まった状態で入る |
解説パネル
アクティビティバーの Doc Reader アイコンで開く。カーソルの位置に追随して、
そこに当たっている解説を出す。ホバーと違って中の語にもう一度ポインタを乗せられ、
参照（[[id]]）を押すと潜って、戻る・進むで往復できる。ピン留めすると追随を止める。
参照と自動リンク
値の中の [[id]] はその解説へのリンクになる（[[id|呼び名]] で表示名を変えられる）。
それに加えて、解説のある語（textQuote の exact）が本文に素のまま出てきたら、
[[id]] を書いていなくてもリンクになる（docReader.autoLink、既定 on）。
繋ぐのは 3 文字以上の識別子だけ。同じ語が複数の解説に付いていれば繋がない。
コードブロック・インラインコード・URL・パス:行 の中は触らない。
本文の途中に パス:行（cimfwstr.hpp:48 のような形。拡張子が要る）が出てきたら、
どのキーに書いてあっても押せる。値まるごとが パス:行 の場合と同じく、その場所が開く。
メモ
書いたメモは ExtensionContext.storageUri の下の memo.json に入る。
VS Code がワークスペースごとに用意する領域で、リポジトリの外にあるので git には入らない。
実際のパスは「状態を表示」に出る
（Windows なら %APPDATA%\Code\User\workspaceStorage\<hash>\kennel.doc-reader\memo.json）。
保存したメモは行末の1行（✎ 印）だけになる。吹き出しは保存した瞬間に消え、本文の縦幅を取らない。
行末の印か原文の語にポインタを乗せると全文が読め、「書き直す」「消す」が押せる。
「書き直す」を押したときだけ吹き出しが開き、確定かやめるで閉じる。
設定
| キー |
既定 |
すること |
docReader.dataPaths |
[".docreader"] |
説明データを探す場所。後に書いたものほど優先 |
docReader.displayFields |
[] |
ホバーに出す fields のキーと順序。空なら書かれているキーを書かれた順に全部出す |
docReader.requireSource |
true |
source が空のエントリを出さない |
docReader.overlapOrder |
"narrowFirst" |
重なったときの並び順 |
docReader.maxHoverEntries |
5 |
1つのホバーに並べる最大件数 |
docReader.visibleLayers |
[] |
表示する layer。空なら制限なし |
docReader.minSalience |
1 |
この値未満の salience を隠す（無指定は 3 として扱う） |
docReader.displayMode |
"respectEntry" |
hoverOnly で icon/always を全部ホバーだけに、off で装飾を一切出さない |
docReader.quoteField |
"quote" |
このキーの値を「原文の逐語引用」としてホバーの先頭に出す |
docReader.titleField |
"title" |
このキーの値を参照（[[id]]）の見出しに使う |
docReader.autoLink |
true |
解説のある語が本文に出てきたら [[id]] 無しでもリンクにする |
拡張は layer や fields のキーの意味を知らない。
JSON 側で使った名前をそのまま書く。fields のキーは日本語でよく、
書いたキー名がそのまま画面の見出しになる。
検証 CLI（check.js）
書いた説明データが原文に当たったかを、VS Code なしで確かめる。
拡張の dist/check.js に入っている（パスは「AI への指示書をコピー」の中に埋まる）。
node <拡張のフォルダ>/dist/check.js [対象のフォルダ] [--data フォルダ]... [--scope パス]... [--verbose]
--data を省くと .vscode/settings.json の docReader.dataPaths を読み、
それも無ければ .docreader。拡張が見るのと同じ場所を見る--scope で pool の照合に使う原文をその下だけに絞る（巨大なツリーで遅いとき）。
anchors の document は scope の外でも読む- 出るもの: 当たらなかった解説（単語境界を外せば当たる／大文字小文字が違う、の助言付き）・
当たりすぎ（
prefix/suffix で絞ったのに複数の場所に付く）・行き先の無い参照・
source が空／根拠になっていない・[[id]] 無しで出ている解説のある語（数だけ。画面では自動で繋がる）など
開発
npm install
npm run compile # 1回ビルド
npm run watch # 監視ビルド
npm run typecheck # 型チェックのみ
npm test # 単体テスト + VS Code 統合テスト
VS Code でこのフォルダを開いて F5 を押すと、拡張が読み込まれた2つ目のウィンドウ
(Extension Development Host) が起動する。Marketplace への公開はテストには不要。
テスト用のワークスペースは sample/。
sample/docs/sample.pdf は node scripts/make-sample-pdf.mjs で作り直せる。
Webview（PDF側）の中身は外から触れないので、確かめたいことを Webview に計算させて
返させている（probe / hoverProbe）。本物の Electron・本物の CSP の上で測っている。
進捗
docs/plan.md が正。ここはその要約。
- [x] Phase 0 — 拡張の雛形。F5 で起動する
- [x] Phase 1 — データ層 + コード側ホバー
- [x] Phase 2 — 範囲・入れ子・下線の制御
- [x] Phase 3 — PDF ビューア。テキストレイヤーの文字座標検証
- [x] Phase 4 — PDF 側の自前ホバー
- [x] Phase 6 — 配布（Marketplace
kennel.doc-reader）
- [x] Phase 7〜10 — 行末の印・要約・Markdown・解説パネル・入れ子
- [x] Phase 11 — メモ・AI への指示書・検証 CLI
- [x] 実 UAT のフィードバック 13 件（
docs/feedback-siview.md）— 0.0.2
ライセンス
MIT。取り込んだ OSS のライセンスは third-party-licenses/ を参照。
