feat: organize tauri agent replies into structured blocks

Author: Jacobinwwey

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

@@ -67,6 +67,12 @@ Tauri-first reply rendering baseline delivered:
 - `src/frontend/workspace_panes.js` now mounts assistant replies through typed blocks instead of only plain text when structured payloads are present,
 - `src/frontend/agent_workspace.js` keeps legacy fallback behavior intact, so older `assistantMessage`-only flows still render.
 
+The next real improvement beyond that baseline is now also in code:
+
+- `src/learning/KnowledgeLearningPlatform.ts` no longer treats `assistantBlocks` as a thin transport wrapper around the same old answer string,
+- the scoped conversation reply is now organized into explicit overview / explanation / evidence summary / memory notice / action guidance sections before citations and knowledge-action affordances are appended,
+- which means the Tauri agent surface can now look materially different even when the underlying knowledge result set is unchanged.
+
 The next gap is narrower now:
 
 - broaden block coverage where future endpoints emit richer assistant payloads,

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

@@ -67,6 +67,12 @@ Tauri-first reply rendering 基线已交付：
 - `src/frontend/workspace_panes.js` 现已在结构化载荷存在时通过 typed blocks 挂载 assistant reply，而不再只走纯文本，
 - `src/frontend/agent_workspace.js` 继续保留 legacy fallback，因此旧的 `assistantMessage`-only 路径仍然可显示。
 
+在这条基线之上，当前代码又前进了一步：
+
+- `src/learning/KnowledgeLearningPlatform.ts` 不再把 `assistantBlocks` 当成“同一段旧 answer 的运输包装层”，
+- scoped conversation reply 现在会先组织成明确的 overview / explanation / evidence summary / memory notice / action guidance，再追加 citations 与 knowledge-action affordance，
+- 这意味着即便底层知识命中集合没变，Tauri 中的 agent 输出也已经可以在结构上明显不同。
+
 当前剩余缺口已经收窄为：
 
 - 当更多端点开始返回 richer assistant payload 时，继续扩充 block 覆盖面，

docs/en/implementation_plan.md

@@ -35,7 +35,9 @@ Bring the implementation plan back in line with `main` reality at three levels:
 3. **P2: release-grade ANN calibration**
    - keep the `external_http` connector green under workload proof, then close recall/latency threshold calibration.
 4. **P3: Tauri-first reply/render surface expansion**
-   - keep the shared Reader-derived runtime as the Tauri baseline and continue widening typed block usage without breaking compatibility.
+   - keep the shared Reader-derived runtime as the Tauri baseline,
+   - move `assistantBlocks` from a thin wrapper around the legacy answer string into a real reply-organization layer,
+   - continue widening typed block usage without breaking compatibility.
 5. **P4: tutor routing and orchestration hardening**
    - move from active local-first routing toward a production-proven multi-provider policy.
 6. **P5: architecture pressure reduction**
@@ -66,6 +68,7 @@ Align the active implementation plan with current code reality:
   - a typed reply-rendering model in the Tauri agent workspace,
   - shared reuse of Reader-derived markdown/math/mermaid rendering inside the agent reply surface,
   - artifact-style handling for large HTML assistant outputs through sandboxed preview.
+  - structured reply composition now splits the assistant output into overview / explanation / evidence summary / memory notice / action guidance blocks instead of emitting only one wrapped markdown answer.
 
 #### Next execution order
 

docs/en/task.md

@@ -9,6 +9,7 @@
 - [x] Reader-side markdown/KaTeX/Mermaid hardening and Tauri debug capture tooling are now real on the current branch.
 - [x] The Tauri agent workspace now has a typed rich-reply baseline instead of `assistantMessage`-only text mounting.
 - [x] The Tauri-first plan to evolve toward shared Reader-aligned rich reply rendering is now implemented as the current baseline while preserving knowledge-point/capability compatibility.
+- [x] The backend reply composer now uses `assistantBlocks` as a real organization layer in Tauri: overview, explanation, evidence summary, memory notice, and next-action guidance are emitted as distinct blocks instead of only wrapping the old answer text.
 - [x] FR-010 is now governed by the current workflow reality instead of the removed transition-era assumption: repo-owned workflows pin `actions/setup-node@v4` to Node 24 and no longer rely on `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24`.
 - [~] Remote CI closure remains a live release bar rather than a static claim: `Fixrisk Operational Readiness` must stay green on `main`, while residual Node 20 deprecation annotations from marketplace actions remain documented as non-blocking external debt.
 

docs/zh/implementation_plan.md

@@ -36,7 +36,9 @@
 3. **P2：release-grade ANN 校准**
    - 保持 `external_http` connector 在 workload proof 下稳定，再收口 recall/latency 阈值校准。
 4. **P3：Tauri-first reply/render surface 扩展**
-   - 继续以共享的 Reader-derived runtime 作为 Tauri 基线，在不破坏兼容性的前提下扩展 typed block 使用面。
+   - 继续以共享的 Reader-derived runtime 作为 Tauri 基线，
+   - 把 `assistantBlocks` 从“legacy answer 的薄包装层”推进为真正的回复组织层，
+   - 在不破坏兼容性的前提下继续扩展 typed block 使用面。
 5. **P4：tutor routing 与 orchestration 加固**
    - 从已激活的 local-first 路由推进到生产级多 provider 策略。
 6. **P5：架构压力缩减**
@@ -67,6 +69,7 @@
   - Tauri agent workspace 中的 typed reply-rendering model，
   - Reader render substrate 在 agent reply surface 中的共享复用，
   - 面向大型 HTML assistant output 的 artifact-style 隔离路径（sandboxed preview）。
+  - assistant 输出现在按 overview / explanation / evidence summary / memory notice / action guidance 分块组织，而不再只是单个 markdown answer 的包装。
 
 #### 下一步执行顺序
 

docs/zh/task.md

@@ -5,6 +5,7 @@
 - [x] Reader 侧 markdown / KaTeX / Mermaid 加固与 Tauri 调试抓取工具链已在当前分支真实落地。
 - [x] Tauri agent workspace 已具备 typed rich-reply baseline，不再只是 `assistantMessage` 纯文本挂载。
 - [x] 这条 Tauri-first 路线已作为当前基线落地：在保持现有 knowledge-point / capability 兼容的前提下，引入了共享 Reader-aligned rich reply rendering。
+- [x] 后端回复组织层现在已经把 `assistantBlocks` 用成真正的 Tauri 输出结构：overview、explanation、evidence summary、memory notice、next-action guidance 已分块输出，而不再只是旧 answer 文本的包装。
 - [x] FR-010 现已按当前工作流现实治理，而不是继续沿用已删除的过渡期假设：仓库自有工作流固定为 `actions/setup-node@v4` + Node 24，且不再依赖 `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24`。
 - [~] remote CI 是否闭环仍以 `main` 上的实时 `Fixrisk Operational Readiness` 结果为准；其余 marketplace action 带来的 Node 20 弃用注解继续作为非阻塞外部债务记录。
 

src/agent_workspace.frontend.test.ts

@@ -2770,11 +2770,25 @@ describe('agent workspace learning-path integration', () => {
             svg: '<svg><text>Rendered Mermaid</text></svg>',
         }));
         (window as any).marked = {
-            parse: jest.fn(() => (
-                '<h2>Scoped Answer</h2>'
-                + '<p>Inline math $E=mc^2$ and a diagram:</p>'
-                + '<pre><code class="language-mermaid">graph TD;A-->B;</code></pre>'
-            )),
+            parse: jest.fn((markdown: string) => {
+                if (markdown.includes('## Scoped Answer')) {
+                    return (
+                        '<h2>Scoped Answer</h2>'
+                        + '<ul><li>Relevant knowledge points: <strong>1</strong></li></ul>'
+                    );
+                }
+                if (markdown.includes('## Evidence Summary')) {
+                    return (
+                        '<h2>Evidence Summary</h2>'
+                        + '<p>Blocks Citation</p>'
+                    );
+                }
+                return (
+                    '<h2>Explanation</h2>'
+                    + '<p>Inline math $E=mc^2$ and a diagram:</p>'
+                    + '<pre><code class="language-mermaid">graph TD;A-->B;</code></pre>'
+                );
+            }),
         };
         (window as any).renderMathInElement = renderMathInElement;
         (window as any).mermaid = {
@@ -2795,10 +2809,25 @@ describe('agent workspace learning-path integration', () => {
                         assistantMessage: 'Scoped Answer',
                         answer: 'Scoped Answer',
                         assistantBlocks: [
+                            {
+                                blockId: 'block_overview_1',
+                                type: 'main_markdown',
+                                markdown: '## Scoped Answer\n\n- Relevant knowledge points: **1**\n- Citations returned: **1**\n- Scoped memories recalled: **0**',
+                            },
                             {
                                 blockId: 'block_main_1',
                                 type: 'main_markdown',
-                                markdown: '## Scoped Answer\n\nInline math $E=mc^2$ and a diagram:\n\n```mermaid\ngraph TD;A-->B;\n```',
+                                markdown: '## Explanation\n\nInline math $E=mc^2$ and a diagram:\n\n```mermaid\ngraph TD;A-->B;\n```',
+                            },
+                            {
+                                blockId: 'block_evidence_1',
+                                type: 'main_markdown',
+                                markdown: '## Evidence Summary\n\n1. **Blocks Citation** (Knowledge_Base/optics/blocks.md:18)\n   - Scoped snippet',
+                            },
+                            {
+                                blockId: 'block_notice_1',
+                                type: 'system_notice',
+                                text: 'No scoped memory note was recalled for this turn.',
                             },
                             {
                                 blockId: 'block_citations_1',
@@ -2884,6 +2913,9 @@ describe('agent workspace learning-path integration', () => {
         const assistantNode = document.querySelector('.agent-chat-message-rendered.agent-chat-message-assistant');
         expect(assistantNode).not.toBeNull();
         expect(assistantNode?.querySelector('h2')?.textContent).toBe('Scoped Answer');
+        expect(String(assistantNode?.textContent || '')).toContain('Relevant knowledge points');
+        expect(String(assistantNode?.textContent || '')).toContain('No scoped memory note was recalled for this turn.');
+        expect(String(assistantNode?.textContent || '')).toContain('Evidence Summary');
         expect(renderMathInElement).toHaveBeenCalled();
         expect((window as any).mermaid.initialize).toHaveBeenCalled();
         expect(mermaidRender).toHaveBeenCalled();

src/learning/KnowledgeLearningPlatform.test.ts

@@ -1458,6 +1458,21 @@ describe('KnowledgeLearningPlatform', () => {
 
         expect(response.answer).toContain('吸收');
         expect(response.citations.length).toBeGreaterThan(0);
+        expect(Array.isArray(response.assistantBlocks)).toBe(true);
+        expect(response.assistantBlocks?.map((block) => block.type)).toEqual(
+            expect.arrayContaining(['main_markdown', 'system_notice', 'citations', 'knowledge_actions'])
+        );
+        const markdownBlocks = (response.assistantBlocks || []).filter((block) => block.type === 'main_markdown');
+        expect(markdownBlocks.length).toBeGreaterThanOrEqual(3);
+        expect(
+            markdownBlocks.some((block) => String((block as { markdown?: string }).markdown || '').includes('## Scoped Answer'))
+        ).toBe(true);
+        expect(
+            markdownBlocks.some((block) => String((block as { markdown?: string }).markdown || '').includes('## Explanation'))
+        ).toBe(true);
+        expect(
+            markdownBlocks.some((block) => String((block as { markdown?: string }).markdown || '').includes('## Evidence Summary'))
+        ).toBe(true);
         expect(response.trace.usedScope.corpusId).toBe('optics');
         expect(response.summary.appliedMemoryCount).toBeGreaterThan(0);
 

src/learning/KnowledgeLearningPlatform.ts

@@ -7624,18 +7624,112 @@ export class KnowledgeLearningPlatform implements KnowledgeLearningPlatformAPI {
         return `${memoryPrefix}The strongest scoped match is ${leadingPoint.title}. I found ${params.knowledgePoints.length} relevant knowledge point(s) and ${params.citations.length} citation(s).\n\nKey evidence:\n${evidenceLines.join('\n')}`;
     }
 
+    private buildScopedConversationOverviewMarkdown(params: {
+        knowledgePoints: AgentConversationKnowledgePoint[];
+        citations: KnowledgeCitation[];
+        recalledMemories: AgentConversationMemoryRecord[];
+    }): string {
+        const strongestPoint = params.knowledgePoints[0];
+        const lines = [
+            '## Scoped Answer',
+            '',
+        ];
+        if (strongestPoint) {
+            lines.push(`The strongest scoped match is **${strongestPoint.title}**.`, '');
+        } else {
+            lines.push('No scoped knowledge point produced a strong match for the current request.', '');
+        }
+        lines.push(
+            `- Relevant knowledge points: **${params.knowledgePoints.length}**`,
+            `- Citations returned: **${params.citations.length}**`,
+            `- Scoped memories recalled: **${params.recalledMemories.length}**`
+        );
+        return lines.join('\n');
+    }
+
+    private buildScopedConversationEvidenceMarkdown(params: {
+        citations: KnowledgeCitation[];
+    }): string {
+        const evidenceLines = params.citations.slice(0, 3).map((citation, index) => (
+            `${index + 1}. **${citation.title}** (${citation.sourcePath}${citation.startLine ? `:${citation.startLine}` : ''})\n   - ${citation.snippet}`
+        ));
+        if (evidenceLines.length <= 0) {
+            return '## Evidence Summary\n\nNo scoped citations were returned.';
+        }
+        return [
+            '## Evidence Summary',
+            '',
+            ...evidenceLines,
+        ].join('\n');
+    }
+
+    private buildScopedConversationMemoryNotice(params: {
+        recalledMemories: AgentConversationMemoryRecord[];
+    }): string {
+        if (params.recalledMemories.length <= 0) {
+            return 'No scoped memory note was recalled for this turn.';
+        }
+        if (params.recalledMemories.length === 1) {
+            return '1 scoped memory note was recalled and merged into the answer context.';
+        }
+        return `${params.recalledMemories.length} scoped memory notes were recalled and merged into the answer context.`;
+    }
+
+    private buildScopedConversationActionGuideMarkdown(params: {
+        knowledgePoints: AgentConversationKnowledgePoint[];
+    }): string {
+        if (params.knowledgePoints.length <= 0) {
+            return '## Next Actions\n\nNo actionable scoped knowledge card is available for this turn.';
+        }
+        return [
+            '## Next Actions',
+            '',
+            'Use the scoped knowledge cards below to continue with focus mode or guided learning for the highest-signal nodes:',
+            ...params.knowledgePoints.slice(0, 3).map((point) => `- ${point.title}`),
+        ].join('\n');
+    }
+
     private buildScopedConversationAssistantBlocks(params: {
         answer: string;
         citations: KnowledgeCitation[];
         knowledgePoints: AgentConversationKnowledgePoint[];
+        recalledMemories: AgentConversationMemoryRecord[];
     }): AgentConversationAssistantBlock[] {
-        const blocks: AgentConversationAssistantBlock[] = [
-            {
+        const blocks: AgentConversationAssistantBlock[] = [];
+        const overviewMarkdown = this.buildScopedConversationOverviewMarkdown(params);
+        const normalizedAnswer = String(params.answer || '').trim();
+        const evidenceMarkdown = this.buildScopedConversationEvidenceMarkdown(params);
+        const memoryNotice = this.buildScopedConversationMemoryNotice(params);
+        const actionGuideMarkdown = this.buildScopedConversationActionGuideMarkdown(params);
+
+        if (overviewMarkdown) {
+            blocks.push({
                 blockId: this.nextId('assistant_block'),
                 type: 'main_markdown',
-                markdown: String(params.answer || ''),
-            },
-        ];
+                markdown: overviewMarkdown,
+            });
+        }
+        if (normalizedAnswer) {
+            blocks.push({
+                blockId: this.nextId('assistant_block'),
+                type: 'main_markdown',
+                markdown: `## Explanation\n\n${normalizedAnswer}`,
+            });
+        }
+        if (evidenceMarkdown) {
+            blocks.push({
+                blockId: this.nextId('assistant_block'),
+                type: 'main_markdown',
+                markdown: evidenceMarkdown,
+            });
+        }
+        if (memoryNotice) {
+            blocks.push({
+                blockId: this.nextId('assistant_block'),
+                type: 'system_notice',
+                text: memoryNotice,
+            });
+        }
         if (params.citations.length > 0) {
             blocks.push({
                 blockId: this.nextId('assistant_block'),
@@ -7645,6 +7739,11 @@ export class KnowledgeLearningPlatform implements KnowledgeLearningPlatformAPI {
             });
         }
         if (params.knowledgePoints.length > 0) {
+            blocks.push({
+                blockId: this.nextId('assistant_block'),
+                type: 'main_markdown',
+                markdown: actionGuideMarkdown,
+            });
             blocks.push({
                 blockId: this.nextId('assistant_block'),
                 type: 'knowledge_actions',
@@ -8061,6 +8160,7 @@ export class KnowledgeLearningPlatform implements KnowledgeLearningPlatformAPI {
             answer,
             citations,
             knowledgePoints,
+            recalledMemories,
         });
         const response: AgentConversationResponse = {
             userId,