feat(agent-workspace): add mastery misconceptions capability lane

Jacobinwwey · Jacobinwwey · commit 451de658ffad · 2026-04-14T09:17:54.000-05:00
diff --git a/docs/brainstorms/2026-04-14-mainline-reality-reconciliation-and-next-direction-requirements.md b/docs/brainstorms/2026-04-14-mainline-reality-reconciliation-and-next-direction-requirements.md
@@ -219,6 +219,18 @@ npm run verify:agent-workspace:tauri
   - frontend payload-builder read query passthrough assertion,
   - runtime endpoint/payload/message assertions for memory read execution.
 
+#### M6.8 Progress Note (2026-04-14)
+
+- [Done] typed conversation capability surface expanded with `inspect_mastery_misconceptions` action, `query_mastery_misconceptions` operation, and `mastery_misconceptions_card` presentation.
+- [Done] conversation capability emission now includes scoped mastery misconception inspection execution through `/api/knowledge/mastery/misconceptions` with bounded `topK`.
+- [Done] contract/runtime planners preserve scoped misconception payload shaping:
+  - bounded `topK`,
+  - optional atom-scoped `atomIds` passthrough.
+- [Done] regression coverage expanded for:
+  - misconception capability wiring in conversation output,
+  - frontend payload-builder misconception endpoint/body assertions,
+  - runtime endpoint/payload/message assertions for misconception inspection execution.
+
 ### M7 (Future): Foundation Lane Re-entry (Evidence-First)
 
 Entry criteria:
diff --git a/docs/diataxis/en/explanation/development-progress-dashboard.md b/docs/diataxis/en/explanation/development-progress-dashboard.md
@@ -188,6 +188,21 @@ Execution anchor:
   - frontend payload-builder read query passthrough,
   - runtime endpoint/payload/message assertions for memory read execution.
 
+## Latest Mainline Increment (2026-04-14 M6.8 Mastery Misconceptions Capability Lane)
+
+- Added `inspect_mastery_misconceptions` to the typed conversation action union on mainline.
+- Extended capability operation/result unions with:
+  - `query_mastery_misconceptions`,
+  - `mastery_misconceptions_card`.
+- Extended `runAgentConversation(...)` capability emission to include scoped misconception inspection through `/api/knowledge/mastery/misconceptions`.
+- Kept contract/runtime planner behavior aligned for misconception payload shaping:
+  - bounded `topK`,
+  - optional atom-scoped `atomIds`.
+- Expanded regression coverage for:
+  - misconception capability wiring in conversation output,
+  - frontend misconception payload-builder endpoint/body assertions,
+  - runtime endpoint/payload/message assertions for misconception execution and rendering.
+
 ## Mainline vs Working-Branch Snapshot (2026-04-14)
 
 | Capability Slice | Working Branch (`feat/learning-multi-tutor-adapter`) | Mainline (`origin/main`) | Integration Status |
diff --git a/docs/diataxis/zh/explanation/development-progress-dashboard.md b/docs/diataxis/zh/explanation/development-progress-dashboard.md
@@ -188,6 +188,21 @@
   - 前端 payload-builder 的 read query 透传断言，
   - runtime read 路径 endpoint/payload/消息断言。
 
+## 主线最新增量（2026-04-14 M6.8 误解洞察能力链路）
+
+- 主线 typed conversation action union 新增 `inspect_mastery_misconceptions`。
+- capability operation/result union 同步扩展：
+  - `query_mastery_misconceptions`，
+  - `mastery_misconceptions_card`。
+- `runAgentConversation(...)` capability 输出新增误解洞察动作，执行路径对接 `/api/knowledge/mastery/misconceptions`。
+- contract/runtime payload 规划保持对齐：
+  - `topK` 有界收敛，
+  - 可选 `atomIds` 范围透传。
+- 回归覆盖同步扩展：
+  - conversation 输出中的 misconception capability 连线断言，
+  - 前端 misconception payload-builder 的 endpoint/body 断言，
+  - runtime misconception 路径 endpoint/payload/消息断言。
+
 ## 主线 vs 工作分支快照（2026-04-14）
 
 | 能力切片 | 工作分支（`feat/learning-multi-tutor-adapter`） | 主线（`origin/main`） | 集成状态 |
diff --git a/src/agent_workspace.contract.parity.test.ts b/src/agent_workspace.contract.parity.test.ts
@@ -14,6 +14,7 @@ describe('agent_workspace contract parity', () => {
             'execute_tutor_action',
             'build_study_session',
             'query_session_history',
+            'query_mastery_misconceptions',
             'capture_learning_quality_snapshot',
             'apply_memory_policy',
         ];
@@ -29,6 +30,7 @@ describe('agent_workspace contract parity', () => {
             'tutor_action_card',
             'study_session_card',
             'session_history_card',
+            'mastery_misconceptions_card',
             'learning_quality_snapshot_card',
             'memory_policy_card',
         ];
diff --git a/src/agent_workspace.frontend.test.ts b/src/agent_workspace.frontend.test.ts
@@ -210,6 +210,31 @@ describe('agent_workspace frontend operation contract', () => {
         });
     });
 
+    test('query_mastery_misconceptions builds scoped misconceptions payload', () => {
+        const requestPlan = buildKnowledgeOperationRequestPayload({
+            request: {
+                userId: 'learner-a',
+                atomId: 'atom-2',
+                topK: 6,
+            },
+            execution: {
+                operationId: 'query_mastery_misconceptions',
+            },
+        });
+
+        expect(requestPlan).toEqual({
+            operationId: 'query_mastery_misconceptions',
+            endpoint: '/api/knowledge/mastery/misconceptions',
+            method: 'POST',
+            resultPresentation: 'mastery_misconceptions_card',
+            body: {
+                userId: 'learner-a',
+                topK: 6,
+                atomIds: ['atom-2'],
+            },
+        });
+    });
+
     test('capture_learning_quality_snapshot builds snapshot payload', () => {
         const requestPlan = buildKnowledgeOperationRequestPayload({
             request: {
@@ -345,6 +370,7 @@ describe('agent_workspace frontend operation contract', () => {
             execute_tutor_action: 'assistant_message',
             build_study_session: 'study_session_card',
             query_session_history: 'session_history_card',
+            query_mastery_misconceptions: 'mastery_misconceptions_card',
             capture_learning_quality_snapshot: 'learning_quality_snapshot_card',
             apply_memory_policy: 'memory_policy_card',
         });
@@ -357,6 +383,9 @@ describe('agent_workspace frontend operation contract', () => {
         expect(diagnostics.operationAllowedResultPresentations.query_session_history).toEqual(
             expect.arrayContaining(['session_history_card'])
         );
+        expect(diagnostics.operationAllowedResultPresentations.query_mastery_misconceptions).toEqual(
+            expect.arrayContaining(['mastery_misconceptions_card'])
+        );
         expect(diagnostics.operationAllowedResultPresentations.capture_learning_quality_snapshot).toEqual(
             expect.arrayContaining(['learning_quality_snapshot_card'])
         );
diff --git a/src/agent_workspace.runtime.behavior.test.ts b/src/agent_workspace.runtime.behavior.test.ts
@@ -84,6 +84,8 @@ describe('agent workspace runtime behavior', () => {
                         ? '/api/knowledge/session/plan'
                         : operationId === 'query_session_history'
                             ? '/api/knowledge/session/history'
+                            : operationId === 'query_mastery_misconceptions'
+                                ? '/api/knowledge/mastery/misconceptions'
                             : operationId === 'capture_learning_quality_snapshot'
                                 ? '/api/knowledge/quality/snapshot'
                                 : operationId === 'apply_memory_policy'
@@ -109,6 +111,21 @@ describe('agent workspace runtime behavior', () => {
                         },
                     };
                 }
+                if (operationId === 'query_mastery_misconceptions') {
+                    return {
+                        operationId,
+                        endpoint,
+                        method: 'POST',
+                        resultPresentation: capability.execution.resultPresentation,
+                        body: {
+                            userId: request.userId,
+                            topK: Number.isFinite(Number(request.topK)) ? Number(request.topK) : 5,
+                            ...(typeof request.atomId === 'string' && request.atomId.trim().length > 0
+                                ? { atomIds: [request.atomId.trim()] }
+                                : {}),
+                        },
+                    };
+                }
                 return {
                     operationId,
                     endpoint,
@@ -356,6 +373,94 @@ describe('agent workspace runtime behavior', () => {
         expect(messages.textContent || '').toContain('Study session built');
     });
 
+    test('executes mastery misconceptions capability and renders summary message', async () => {
+        const fetchMock = jest
+            .fn()
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        userId: 'agent_user_default',
+                        message: 'Found 1 local knowledge point(s).',
+                        knowledgePoints: [
+                            {
+                                atomId: 'atom-misconception-1',
+                                title: 'Misconception Candidate',
+                                snippet: 'Inspect misconception concentration.',
+                                score: 0.72,
+                                capabilities: [
+                                    {
+                                        actionId: 'inspect_mastery_misconceptions',
+                                        label: 'Mastery Misconceptions',
+                                        request: {
+                                            userId: 'agent_user_default',
+                                            atomId: 'atom-misconception-1',
+                                            topK: 6,
+                                        },
+                                        execution: {
+                                            kind: 'knowledge_operation',
+                                            operationId: 'query_mastery_misconceptions',
+                                            resultPresentation: 'mastery_misconceptions_card',
+                                        },
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                }),
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        summary: {
+                            trackedTags: 2,
+                            totalObservations: 7,
+                        },
+                        items: [
+                            {
+                                errorTag: 'overgeneralization',
+                            },
+                        ],
+                    },
+                }),
+            });
+        (global as unknown as Record<string, unknown>).fetch = fetchMock;
+
+        const runtime = runtimeModule.createAgentWorkspaceRuntime({ defaultUserId: 'agent_user_default' });
+        runtime.init();
+
+        const input = document.getElementById('agent-workspace-input') as HTMLTextAreaElement;
+        const form = document.getElementById('agent-workspace-form') as HTMLFormElement;
+        input.value = 'inspect misconceptions';
+        form.dispatchEvent(new dom!.window.Event('submit', { bubbles: true, cancelable: true }));
+        await flushAsync();
+
+        const actionButton = document.querySelector('.agent-workspace-action-button') as HTMLButtonElement;
+        expect(actionButton).not.toBeNull();
+        actionButton.click();
+        await flushAsync();
+
+        expect(fetchMock).toHaveBeenNthCalledWith(
+            2,
+            '/api/knowledge/mastery/misconceptions',
+            expect.objectContaining({ method: 'POST' })
+        );
+        const payload = JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body || '{}')) as {
+            topK?: number;
+            atomIds?: string[];
+        };
+        expect(payload.topK).toBe(6);
+        expect(payload.atomIds).toEqual(['atom-misconception-1']);
+
+        const messages = document.getElementById('agent-workspace-messages') as HTMLElement;
+        expect(messages.textContent || '').toContain('Mastery misconceptions loaded');
+    });
+
     test('executes follow-up tutor capability and renders assistant message', async () => {
         const fetchMock = jest
             .fn()
diff --git a/src/agent_workspace.runtime.integration.test.ts b/src/agent_workspace.runtime.integration.test.ts
@@ -26,6 +26,7 @@ describe('agent workspace runtime integration baseline', () => {
         expect(runtimeSource).toContain('/api/knowledge/conversation');
         expect(runtimeSource).toContain('/api/knowledge/session/plan');
         expect(runtimeSource).toContain('/api/knowledge/session/history');
+        expect(runtimeSource).toContain('/api/knowledge/mastery/misconceptions');
         expect(runtimeSource).toContain('/api/knowledge/quality/snapshot');
         expect(runtimeSource).toContain('/api/knowledge/memory/policy');
         expect(runtimeSource).toContain('focusOnNode');
diff --git a/src/frontend/agent_workspace.js b/src/frontend/agent_workspace.js
@@ -38,6 +38,12 @@
                 defaultResultPresentation: 'session_history_card',
                 allowedResultPresentations: Object.freeze(['session_history_card']),
             }),
+            query_mastery_misconceptions: Object.freeze({
+                endpoint: '/api/knowledge/mastery/misconceptions',
+                method: 'POST',
+                defaultResultPresentation: 'mastery_misconceptions_card',
+                allowedResultPresentations: Object.freeze(['mastery_misconceptions_card']),
+            }),
             capture_learning_quality_snapshot: Object.freeze({
                 endpoint: '/api/knowledge/quality/snapshot',
                 method: 'POST',
@@ -122,6 +128,13 @@
             return Math.max(1, Math.min(100, Math.floor(base)));
         }
 
+        function resolveMisconceptionTopK(rawTopK, fallback) {
+            const numericTopK = Number(rawTopK);
+            const numericFallback = Number(fallback);
+            const base = Number.isFinite(numericTopK) ? numericTopK : (Number.isFinite(numericFallback) ? numericFallback : 5);
+            return Math.max(1, Math.min(20, Math.floor(base)));
+        }
+
         function createAgentConversationPayload(options) {
             const source = options || {};
             const userId = typeof source.userId === 'string' ? source.userId.trim() : '';
@@ -263,6 +276,25 @@
                 };
             }
 
+            if (operationId === 'query_mastery_misconceptions') {
+                const userId = String(request.userId || '').trim();
+                if (!userId) {
+                    throw new Error('query_mastery_misconceptions requires request.userId.');
+                }
+                const atomId = String(request.atomId || '').trim();
+                return {
+                    operationId,
+                    endpoint: config.endpoint,
+                    method: config.method,
+                    resultPresentation,
+                    body: {
+                        userId,
+                        topK: resolveMisconceptionTopK(request.topK, 5),
+                        ...(atomId ? { atomIds: [atomId] } : {}),
+                    },
+                };
+            }
+
             if (operationId === 'capture_learning_quality_snapshot') {
                 const userId = String(request.userId || '').trim();
                 if (!userId) {
diff --git a/src/frontend/agent_workspace_runtime.js b/src/frontend/agent_workspace_runtime.js
@@ -80,6 +80,13 @@
             return Math.max(1, Math.min(100, Math.floor(base)));
         }
 
+        function resolveMisconceptionTopK(rawTopK, fallback) {
+            const numericTopK = Number(rawTopK);
+            const numericFallback = Number(fallback);
+            const base = Number.isFinite(numericTopK) ? numericTopK : (Number.isFinite(numericFallback) ? numericFallback : 5);
+            return Math.max(1, Math.min(20, Math.floor(base)));
+        }
+
         function getI18nText(key, fallback, params) {
             if (
                 globalScope
@@ -217,6 +224,20 @@
                     },
                 };
             }
+            if (operationId === 'query_mastery_misconceptions') {
+                const atomId = trimString(request.atomId);
+                return {
+                    operationId,
+                    endpoint: '/api/knowledge/mastery/misconceptions',
+                    method: 'POST',
+                    resultPresentation: trimString(execution.resultPresentation) || 'mastery_misconceptions_card',
+                    body: {
+                        userId: trimString(request.userId),
+                        topK: resolveMisconceptionTopK(request.topK, 5),
+                        ...(atomId ? { atomIds: [atomId] } : {}),
+                    },
+                };
+            }
             if (operationId === 'capture_learning_quality_snapshot') {
                 return {
                     operationId,
@@ -586,6 +607,31 @@
                     return;
                 }
 
+                if (presentation === 'mastery_misconceptions_card') {
+                    const summary = result && result.summary && typeof result.summary === 'object'
+                        ? result.summary
+                        : {};
+                    const trackedTags = Number(summary.trackedTags);
+                    const totalObservations = Number(summary.totalObservations);
+                    const topItem = Array.isArray(result && result.items) && result.items.length > 0
+                        ? result.items[0]
+                        : null;
+                    const topErrorTag = trimString(topItem && topItem.errorTag);
+                    appendMessage(
+                        'assistant',
+                        getI18nText(
+                            'agentWorkspace.messages.masteryMisconceptionsLoaded',
+                            `Mastery misconceptions loaded (${Number.isFinite(trackedTags) ? trackedTags : 0} tags, ${Number.isFinite(totalObservations) ? totalObservations : 0} observations, top "${topErrorTag || 'n/a'}").`,
+                            {
+                                trackedTags: Number.isFinite(trackedTags) ? trackedTags : 0,
+                                totalObservations: Number.isFinite(totalObservations) ? totalObservations : 0,
+                                topErrorTag: topErrorTag || 'n/a',
+                            }
+                        )
+                    );
+                    return;
+                }
+
                 if (presentation === 'learning_quality_snapshot_card') {
                     const snapshot = result && result.snapshot && typeof result.snapshot === 'object'
                         ? result.snapshot
diff --git a/src/frontend/locales/en.json b/src/frontend/locales/en.json
@@ -241,6 +241,7 @@
       "generateCounterexample": "Generate Counterexample",
       "buildStudySession": "Build Session",
       "inspectSessionHistory": "Session History",
+      "inspectMasteryMisconceptions": "Mastery Misconceptions",
       "inspectLearningQualitySnapshot": "Learning Quality",
       "inspectMemorySnapshot": "Memory Snapshot",
       "inspectMemoryRetrainPlan": "Memory Retrain Plan",
@@ -268,6 +269,8 @@
       "studySessionBuilt": "Study session built ({totalActions} actions, {totalEstimatedMinutes} min).",
       "sessionHistoryFailed": "Session history request failed.",
       "sessionHistoryLoaded": "Session history loaded ({totalRecords} sessions, {totalExecutedActions} actions).",
+      "masteryMisconceptionsFailed": "Mastery misconceptions request failed.",
+      "masteryMisconceptionsLoaded": "Mastery misconceptions loaded ({trackedTags} tags, {totalObservations} observations, top \"{topErrorTag}\").",
       "learningQualitySnapshotFailed": "Learning quality snapshot request failed.",
       "learningQualitySnapshotLoaded": "Learning quality snapshot loaded (retest {retestPassRatePct}%, recurrence {misconceptionRecurrenceRatePct}%).",
       "memoryPolicyFailed": "Memory snapshot request failed.",
diff --git a/src/frontend/locales/zh.json b/src/frontend/locales/zh.json
diff --git a/src/learning/KnowledgeLearningPlatform.test.ts b/src/learning/KnowledgeLearningPlatform.test.ts
diff --git a/src/learning/KnowledgeLearningPlatform.ts b/src/learning/KnowledgeLearningPlatform.ts
diff --git a/src/learning/types.ts b/src/learning/types.ts
