feat(agent-workspace): expose scope and focus hit evidence

Author: Jacobinwwey

docs/diataxis/en/explanation/development-progress-dashboard.md

@@ -3,6 +3,32 @@
 This page is the implementation-facing dashboard for the Knowledge Mastery evolution plan.
 It tracks what is already implemented, where the hard gaps remain, and how to verify progress from code and runtime behavior.
 
+## 2026-06-06 Knowledge Workspace Scope Switcher and Evidence-Focused Hit UI
+
+This slice closes the frontend usability gap that made the active RAG scope hard to see from inside the Knowledge Workspace itself.
+The prior implementation depended on the global folder selector and request payload state, so users could ask a scoped question without a local, task-adjacent confirmation of the actual retrieval boundary.
+It also rendered summaries, citations, matched sections, and actions in every hit card, which pushed the question/reply area out of view after results returned and increased first-level choice density.
+
+Code-vs-plan reconciliation for this slice:
+
+| Requirement | Current implementation evidence | Progress call |
+|---|---|---|
+| Show and switch the Knowledge Workspace scope in the workspace window | `src/frontend/index.html` now includes an in-pane `agent-workspace-scope-select`; `src/frontend/agent_workspace.js` mirrors the global `folder-select`, publishes the same active-target event, updates `localStorage.nc_last_target`, and sends `activeTarget` plus `scope` with conversation requests. | Implemented |
+| Keep the question/reply area visible after hits return | `src/frontend/styles.css` gives chat messages a stable flex floor and caps the knowledge-hit list height, so the conversation stream and input remain part of the active workspace instead of being displaced by result cards. | Implemented |
+| Show only interactive knowledge-point filenames at the first level | `src/frontend/workspace_panes.js` now renders each knowledge point as a file button resolved from `sourcePath`, `citation.sourcePath`, or `matchedSpans[0].sourcePath`; summaries, scores, citations, and matched section snippets are no longer first-level card content. | Implemented |
+| Move secondary actions behind a long-press/context menu | Typed capability buttons remain backward-compatible, but are hidden in `agent-knowledge-actions-menu` until long-press, context menu, or keyboard context-menu activation opens them. | Implemented |
+| Highlight matched passages in the right pane | Clicking the filename opens the graph-focus pane with the knowledge point title and `matchedSpans`, rendering each matched passage as highlighted evidence. | Implemented |
+| Bilingual locale and contract compatibility | `agentWorkspace.scope.*` and new knowledge action labels are present in both frontend locale bundles, and the locale contract test verifies key coverage and placeholder parity. | Preserved |
+
+Verification for this slice:
+
+- `npm.cmd exec -- jest src/agent_workspace.frontend.test.ts -t "scope selector|knowledge hits as file entries" --runInBand`
+- `npm.cmd exec -- jest src/agent_workspace.frontend.test.ts --runInBand`
+- `npm.cmd exec -- jest src/agent_workspace.locale.contract.test.ts --runInBand`
+- `node --check src/frontend/agent_workspace.js`
+- `node --check src/frontend/workspace_panes.js`
+- `npm.cmd run build`
+
 ## 2026-06-06 Active-Scope Miss Recovery and Document-Augmented RAG Patch
 
 This patch resolves the live "what is water glass?" failure that reproduced while the WebView was already running on `npm run tauri:dev:mini:gpu`.

docs/diataxis/zh/explanation/development-progress-dashboard.md

@@ -3,6 +3,31 @@
 本页是“知识彻底掌握演进方案”的实现侧进度看板。
 它用于回答三件事：哪些能力已落地、哪些关键缺口仍在、如何用代码与运行时证据验证推进结果。
 
+## 2026-06-06 知识工作区 scope 切换器与证据聚焦命中 UI
+
+本切片关闭的是知识工作区前端可用性缺口：旧实现依赖全局文件夹选择器和请求载荷状态，用户在知识工作区内提问时，无法在同一任务窗口中直接确认当前 RAG 检索边界。
+同时，旧命中卡片会把摘要、引用、命中 section 与动作按钮全部铺在首层，导致结果返回后提问 / 回复区域容易被挤出视野，也让用户在第一层面对过多选择。
+
+本切片的代码 / 方案对齐结果：
+
+| 要求 | 当前实现证据 | 进度判断 |
+|---|---|---|
+| 在知识工作区窗口内默认显示并可切换 scope | `src/frontend/index.html` 现在在工作区内加入 `agent-workspace-scope-select`；`src/frontend/agent_workspace.js` 会镜像全局 `folder-select`，发布同一 active-target 事件，更新 `localStorage.nc_last_target`，并在 conversation 请求中发送 `activeTarget` 与 `scope`。 | 已实现 |
+| 命中返回后仍保持提问 / 回复区域可见 | `src/frontend/styles.css` 为聊天消息区设置稳定 flex 下限，并限制知识命中列表最大高度，使对话流和输入框不会被结果卡片挤出当前工作区。 | 已实现 |
+| 首层命中内容只显示可交互的知识点文件名 | `src/frontend/workspace_panes.js` 现在将每个知识点渲染为文件按钮，文件名来自 `sourcePath`、`citation.sourcePath` 或 `matchedSpans[0].sourcePath`；摘要、得分、引用与命中片段不再作为首层卡片内容。 | 已实现 |
+| 其他动作进入长按 / 右键菜单 | typed capability 按钮继续保持向前兼容，但默认隐藏在 `agent-knowledge-actions-menu` 中，只在长按、右键或键盘 context-menu 操作时展开。 | 已实现 |
+| 点击知识点后在右侧高亮命中段落 | 点击文件名会打开 graph-focus 面板，展示知识点标题与 `matchedSpans`，每个命中段落作为高亮证据渲染。 | 已实现 |
+| 双语文案与契约兼容 | `agentWorkspace.scope.*` 与新增知识点操作文案已经同步到中英 locale bundle，并由 locale contract 测试校验 key 覆盖与占位符一致性。 | 已保留 |
+
+本切片验证：
+
+- `npm.cmd exec -- jest src/agent_workspace.frontend.test.ts -t "scope selector|knowledge hits as file entries" --runInBand`
+- `npm.cmd exec -- jest src/agent_workspace.frontend.test.ts --runInBand`
+- `npm.cmd exec -- jest src/agent_workspace.locale.contract.test.ts --runInBand`
+- `node --check src/frontend/agent_workspace.js`
+- `node --check src/frontend/workspace_panes.js`
+- `npm.cmd run build`
+
 ## 2026-06-06 active scope miss recovery 与 document-augmented RAG 修复
 
 本次补丁修复了 WebView 已在 `npm run tauri:dev:mini:gpu` 中运行时复现的 “what is water glass?” 失败。

src/agent_workspace.frontend.test.ts

@@ -700,10 +700,20 @@ function createWorkspaceHtml() {
         <!doctype html>
         <html>
           <body>
+            <select id="folder-select">
+              <option value="ALL_FOLDERS">All folders</option>
+              <option value="financial">financial</option>
+              <option value="waterglass">waterglass</option>
+            </select>
             <div id="graph-wrapper">
               <div id="agent-workspace-shell">
                 <section id="agent-chat-pane">
                   <input id="agent-workspace-user-id" value="path_user_default" />
+                  <div class="agent-scope-control">
+                    <label for="agent-workspace-scope-select">Scope</label>
+                    <select id="agent-workspace-scope-select"></select>
+                    <div id="agent-workspace-scope-summary"></div>
+                  </div>
                   <div id="agent-workspace-chat-messages"></div>
                   <textarea id="agent-workspace-chat-input"></textarea>
                   <button id="btn-agent-workspace-send"></button>
@@ -2331,8 +2341,8 @@ describe('workspace panes controller', () => {
         expect(buttonsAfter).toEqual(['聚焦', '学习路径']);
     });
 
-    test('renders grouped knowledge-point hit spans inside a single card', () => {
-        const { controller, document } = loadWorkspacePanesHarness();
+    test('renders knowledge hits as file entries and opens matched spans in the focus pane', () => {
+        const { controller, document, window } = loadWorkspacePanesHarness();
         controller.init();
 
         controller.renderKnowledgePoints([
@@ -2361,21 +2371,57 @@ describe('workspace panes controller', () => {
                         score: 0.81,
                     },
                 ],
-                capabilities: [],
+                capabilities: [
+                    {
+                        actionId: 'open_focus_mode',
+                        label: 'Focus',
+                    },
+                    {
+                        actionId: 'open_learning_path',
+                        label: 'Guided Learning',
+                    },
+                ],
             },
         ], {
             onCapability: jest.fn(),
         });
 
         const cards = Array.from(document.querySelectorAll('.agent-knowledge-card'));
         expect(cards).toHaveLength(1);
-        const cardText = String(cards[0]?.textContent || '');
-        expect(cardText).toContain('Matched evidence');
-        expect(cardText).toContain('Definition');
-        expect(cardText).toContain('Thermal exchange');
-        expect(cardText).toContain('Knowledge_Base/waterglass/water glass.md:1');
-        expect(cardText).toContain('Knowledge_Base/waterglass/water glass.md:6');
-        expect(cards[0]?.querySelectorAll('.agent-knowledge-hit')).toHaveLength(2);
+        const fileButton = cards[0]?.querySelector('.agent-knowledge-file-button') as HTMLButtonElement;
+        expect(fileButton).not.toBeNull();
+        expect(String(fileButton?.textContent || '')).toBe('water glass.md');
+        expect(cards[0]?.querySelector('.agent-knowledge-summary')).toBeNull();
+        expect(cards[0]?.querySelectorAll('.agent-knowledge-hit')).toHaveLength(0);
+
+        const actionMenu = cards[0]?.querySelector('.agent-knowledge-actions-menu') as HTMLElement;
+        expect(actionMenu).not.toBeNull();
+        expect(actionMenu.hidden).toBe(true);
+        expect(actionMenu.querySelectorAll('button')).toHaveLength(2);
+
+        fileButton.dispatchEvent(new window.MouseEvent('contextmenu', {
+            bubbles: true,
+            cancelable: true,
+        }));
+        expect(actionMenu.hidden).toBe(false);
+        expect(fileButton.getAttribute('aria-expanded')).toBe('true');
+        fileButton.dispatchEvent(new window.KeyboardEvent('keydown', {
+            key: 'Escape',
+            bubbles: true,
+        }));
+        expect(actionMenu.hidden).toBe(true);
+
+        fileButton.click();
+
+        const graphPane = document.getElementById('agent-graph-focus-pane');
+        const graphBody = document.getElementById('agent-graph-focus-body');
+        expect(graphPane?.getAttribute('data-open')).toBe('true');
+        const focusText = String(graphBody?.textContent || '');
+        expect(focusText).toContain('Water Glass');
+        expect(focusText).toContain('Definition');
+        expect(focusText).toContain('A water glass is a physical system');
+        expect(focusText).toContain('Thermal exchange');
+        expect(focusText).toContain('The water glass exchanges heat');
     });
 
     test('keeps conversation card append kinds aligned with rerender registry', () => {
@@ -2656,6 +2702,68 @@ describe('agent workspace learning-path integration', () => {
         expect(diagnostics.legacyActionFallbacks).toEqual([]);
     });
 
+    test('shows a workspace scope selector and uses it for conversation requests', async () => {
+        const {
+            document,
+            window,
+            fetchMock,
+        } = loadAgentWorkspaceHarness();
+        if (!fetchMock) {
+            throw new Error('expected fetch mock');
+        }
+
+        fetchMock.mockImplementationOnce(async () => createSseResponse([
+            {
+                event: 'turn_completed',
+                payload: {
+                    type: 'turn_completed',
+                    turnId: 'turn_scope_selector',
+                    emittedAt: '2026-04-13T00:00:00.100Z',
+                    result: {
+                        assistantMessage: 'scoped selector response',
+                        citations: [],
+                        recalledMemories: [],
+                        memoryActions: [],
+                        knowledgePoints: [],
+                        summary: {
+                            generatedAt: '2026-04-13T00:00:00.100Z',
+                            topK: 6,
+                            returnedKnowledgePoints: 0,
+                            returnedCitations: 0,
+                            recalledMemoryCount: 0,
+                            queryEvidenceCoverageRatioPct: 0,
+                        },
+                    },
+                },
+            },
+        ]));
+
+        const scopeSelect = document.getElementById('agent-workspace-scope-select') as HTMLSelectElement;
+        expect(scopeSelect).not.toBeNull();
+        expect(Array.from(scopeSelect.options).map((option) => option.value)).toEqual([
+            'ALL_FOLDERS',
+            'financial',
+            'waterglass',
+        ]);
+        scopeSelect.value = 'waterglass';
+        scopeSelect.dispatchEvent(new window.Event('change', { bubbles: true }));
+
+        const scopeSummary = document.getElementById('agent-workspace-scope-summary');
+        expect(String(scopeSummary?.textContent || '')).toContain('waterglass');
+
+        const input = document.getElementById('agent-workspace-chat-input') as HTMLTextAreaElement;
+        input.value = 'what is water glass?';
+        await (window as any).NoteConnectionAgentWorkspace.sendConversation();
+
+        const requestBody = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body || '{}'));
+        expect(requestBody.activeTarget).toBe('waterglass');
+        expect(requestBody.scope).toEqual({
+            workspaceId: 'waterglass',
+            corpusId: 'waterglass',
+            sourcePathPrefixes: ['Knowledge_Base/waterglass'],
+        });
+    });
+
     test('prefers SSE turn streaming for conversation and renders the completed turn payload', async () => {
         const {
             document,
@@ -2798,9 +2906,10 @@ describe('agent workspace learning-path integration', () => {
         ).toBe(true);
         const knowledgeCards = Array.from(document.querySelectorAll('.agent-knowledge-card'));
         expect(knowledgeCards.length).toBeGreaterThan(0);
-        expect(String(knowledgeCards[0]?.textContent || '')).toContain('Stream Node');
-        expect(String(knowledgeCards[0]?.textContent || '')).toContain('Citation');
-        expect(String(knowledgeCards[0]?.textContent || '')).toContain('Knowledge_Base/optics/stream.md:12');
+        const fileButton = knowledgeCards[0]?.querySelector('.agent-knowledge-file-button') as HTMLButtonElement;
+        expect(String(fileButton?.textContent || '')).toBe('stream.md');
+        expect(knowledgeCards[0]?.querySelector('.agent-knowledge-summary')).toBeNull();
+        expect(knowledgeCards[0]?.querySelectorAll('.agent-knowledge-hit')).toHaveLength(0);
     });
 
     test('renders structured assistant blocks without breaking scoped conversation flow', async () => {