Skip to content

ask behavior doc sync_ja

Jump to bottom
Kazushi Kamegawa edited this page Sep 19, 2026 · 1 revision

READMEとパネルのウェルカム文言を/askのグラウンディング挙動に合わせる

日付: 2026-09-19 追跡: Issue #249

English

概要

PR #233 と PR #237 で、チャットのグラウンディング挙動が次のように変わった。

  • スラッシュコマンドなしの平文チャットでも、ピン留めスニペットと添付ファイルが自動的にグラウンディングコンテキストとして付与され、そのターンでは contextualResources.webContext.isWebEnabled = false が設定される。
  • /ask は「コンテキストを付与するコマンド」から、「ピン留めスニペットも添付ファイルも無ければ送信を拒否する」任意のガードに変わった。

本計画は、この変更がドキュメントに反映されているかの調査から始まる。大部分は反映済みだった。README の「Chatting and Searching」と /ask の節、コマンド表、docs/plan.md §4.1/§4.3、docs/adr.md、docs/tasks.md、docs/test_plan.md（T-CHAT-05、T-CHAT-09）、docs/e2e_checklist.md（E2E-33）、src/router/commandRouter.ts の /ask ヘルプ文は、いずれも現行挙動を説明している。

一方、次の4か所は変更前のままだった。うち2か所はユーザーが目にするパネル内の文言である。

  1. README.md 冒頭 — 「Plain text starts a Microsoft 365 Copilot chat without automatically attaching ContextRelay search context」とあり、ピン留めスニペットと添付ファイルが付与される点に触れていない。
  2. README.md の Features「Plain Copilot chat」 — 自動グラウンディングにも /ask のガード役割にも触れていない。
  3. src/webview/chatRenderer.ts — clear() が再構築するウェルカム文が「Pin snippets and run /ask to process pinned snippets or #file mentions with Microsoft 365 Copilot」のままで、ChatViewProvider.getHtmlForWebview() の初期 HTML と矛盾していた。/clear を実行すると、正しい説明が古い説明に置き換わる。
  4. src/webview/slashMenu.ts — /ask の説明が「Ask Microsoft 365 Copilot using pinned snippets in the panel」で、ガードである点が伝わらない。

また、本リポジトリは MIT ライセンスで他のドキュメントには日本語版があるにもかかわらず、README_ja.md が存在しなかった。

設計判断

  • ウェルカム文言は2か所を同期させるのではなく、定義を1つにする。 ウェルカム段落は、拡張ホストが生成する静的 HTML と、webview が生成する DOM ノードという独立した2実装として存在していた。#233/#237 の更新が片側にしか入らなかった原因はこれである。文言は vscode を import しないモジュール src/chatWelcomeText.ts に移し、両者がそこから描画する。src/sourcePresentation.ts が、src/ 直下の vscode 非依存モジュールを拡張ホストと webview バンドルの双方から import できるという先例をすでに作っている。
  • 単一文字列ではなくセグメント配列にする。 双方ともインラインの <code> を必要とするが、一方は HTML を、他方は DOM ノードを生成する。共有テキストは { text, code? } のセグメント配列とし、ホスト側はエスケープして囲み、webview 側はテキストノードと <code> 要素を生成する。いずれもこの文言に innerHTML を使わない。
  • 拡張ホスト側の文言を正とし、1点だけ取り込む。 2つのうちホスト側が現行挙動を説明しており、ユーザーが最初に目にするものでもあるため、これを共有テキストとする。webview 側にしかなかった「combine source commands like /mail /onedrive」のヒントは事実（ルーターは複数のソースコマンドを受け付ける）なので残し、情報の欠落を防ぐ。
  • README_ja.md は要約ではなく全訳にする。 見出し構成・表・コードブロックを README.md と一致させ、両者を並べてレビューできるようにする。README.md を正とする。SECURITY.md と LICENSE は翻訳しない。
  • 挙動は変更しない。 文言とドキュメントのみの変更であり、設定、リクエストペイロード、制御フローには触れない。

実装

  • src/chatWelcomeText.ts（新規）: WelcomeTextSegment、CHAT_WELCOME_HEADING、CHAT_WELCOME_INTRO、CHAT_WELCOME_COMMANDS_HINT、CHAT_WELCOME_GROUNDING_HINT、CHAT_WELCOME_HINT_FONT_SIZE を定義する。
  • src/panel/chatViewProvider.ts: モジュールレベルの escapeHtml() と renderWelcomeParagraph() を追加し、getHtmlForWebview() のウェルカムブロックを共有セグメントから組み立てる。
  • src/webview/chatRenderer.ts: clear() が、新設の private メソッド buildWelcomeParagraph() を通じて同じセグメントからブロックを構築する。
  • src/webview/slashMenu.ts: /ask の説明を「Ask Microsoft 365 Copilot, but only when pinned snippets or attached files are present」に変更し、commandRouter.ts のヘルプ文と揃える。
  • README.md: 冒頭と「Plain Copilot chat」の項目を現行挙動に合わせ、README_ja.md へのリンクを追加する。
  • README_ja.md（新規）: 全訳を作成し、README.md と相互リンクする。
  • docs/adr.md: ウェルカム文言の単一定義化と日本語 README 追加について、2026-09-19 のエントリを追記する。
  • docs/plan.md: ドキュメント一式と、パネル自身のユーザー向け文言の所在を説明する Appendix C を追加する。
  • docs/tasks.md: 作業記録を追記する。

検証

npm run lint
npm run compile
npm test
npm run security:check

src/test/suite/chatRenderer.test.ts に、getHtmlForWebview() から本番のパネル HTML を読み込む既存の domTestUtils 基盤を使って、次の2ケースを追加する。

  • clear() が再構築したブロックが、実際に配布されるパネル HTML のブロック（見出し、段落テキスト、フォントサイズ、インラインコード）と一致すること。これが今回混入したリグレッションそのものである。
  • ウェルカム文言が、ピン留めコンテキストは自動的に付与されると述べていること。

あわせて、getHtmlForWebview() が生成するウェルカム HTML をダンプして直接確認した。結果は 389 passing、0 failing、脆弱性 0 件。

Clone this wiki locally