feat(conversation): expose intra-result graph relations

Jacobinwwey · Jacobinwwey · commit e4e156f2bc03 · 2026-06-12T00:53:49.000+08:00
diff --git a/docs/diataxis/en/explanation/development-progress-dashboard.md b/docs/diataxis/en/explanation/development-progress-dashboard.md
@@ -20,6 +20,7 @@ The key result is that the current code has moved further than the old plan word
 - that `graphContext` now survives through conversation trace, snapshot persistence, and workspace export,
 - the grounding inspector now renders that persisted `graphContext` as structured graph evidence,
 - relation aggregation now spans the whole grouped knowledge-point set instead of only the leading anchor's local hint set,
+- direct grouped-knowledge-point relations are now preserved as first-class graph-context data instead of only implicit edge membership,
 - temporal-validity aggregation now preserves temporal edge kinds/details in addition to warning text,
 - supersession details now also influence explanation and next-action text instead of staying limited to warning-only evidence,
 - and grounding inspectability is now normalized per turn so later turns without grounding payload do not keep stale evidence-pane state alive.
@@ -41,7 +42,7 @@ Code-vs-plan reconciliation for this slice:
 | Answer area contraction to a single targeted answer | `agent_workspace.js` now keeps the full conversation result in runtime state while only rendering user-facing answer blocks (`structured_answer`, `main_markdown`, `html_artifact`) in the main chat surface. | Implemented current slice |
 | Hide developer-heavy evidence from the primary hit list | `workspace_panes.js` no longer renders inline knowledge previews or visible typed capability buttons in the left-side hit list; those flows now route into graph focus or the dedicated evidence pane. | Implemented current slice |
 | Durable evidence/claim inspector | `workspace_panes.js` now exposes a dedicated evidence pane for grounding metadata, `knowledge_run`, `knowledge_run_history`, `knowledge_run_compare`, and `flashcard_batch`; `agent_workspace.js` wires the API status strip into grounding inspection and normalizes per-turn inspectability so stale grounding is cleared on later turns without evidence payloads. | Implemented broader current slice |
-| DAG-native answer planning | `AgentConversationKnowledgePoint` now carries grouped `relationPath`, `relationKinds`, `relationPathAtomIds`, and `temporalValidity`; `conversationComposer.ts` now materializes an explicit `graphContext`; `KnowledgeLearningPlatform.ts` and `WorkspaceExportBundle.ts` now preserve it through trace, persistence, and export surfaces; `workspace_panes.js` now renders that persisted `graphContext` in the evidence pane as a structured graph explanation surface; relation and temporal aggregation now span the whole grouped knowledge-point set and preserve source-atom plus temporal-edge detail; supersession details now also flow into explanation and next-action text. | Implemented broader partial slice |
+| DAG-native answer planning | `AgentConversationKnowledgePoint` now carries grouped `relationPath`, `relationKinds`, `relationPathAtomIds`, and `temporalValidity`; `conversationComposer.ts` now materializes an explicit `graphContext`; `KnowledgeLearningPlatform.ts` and `WorkspaceExportBundle.ts` now preserve it through trace, persistence, and export surfaces; `workspace_panes.js` now renders that persisted `graphContext` in the evidence pane as a structured graph explanation surface; relation and temporal aggregation now span the whole grouped knowledge-point set and preserve source-atom plus temporal-edge detail; direct grouped-knowledge-point relations are now preserved and surfaced; supersession details now also flow into explanation and next-action text. | Implemented broader partial slice |
 
 Immediate next direction from this point:
 
diff --git a/docs/diataxis/zh/explanation/development-progress-dashboard.md b/docs/diataxis/zh/explanation/development-progress-dashboard.md
@@ -22,6 +22,7 @@
 - 该 `graphContext` 现在也会沿着 conversation trace、snapshot persistence 与 workspace export 一起传播；
 - grounding inspector 现在会把持久化的 `graphContext` 渲染为结构化图解释面；
 - 关系聚合现在已覆盖整批 grouped knowledge points，而不再只看首个 anchor 的局部提示；
+- grouped knowledge points 之间的直接关系现在也会作为一等 `graphContext` 数据被保留，而不再只是隐式 edge 归属；
 - 时序有效性聚合现在除 warning text 外，还会保留 temporal edge kind/detail；
 - supersession 细节现在也会影响 explanation / next-action 文本，而不再只停留在 warning-only evidence；
 - grounding 检查入口现在按当前回合标准化判断，因此后续无 grounding payload 的回合不会继续保留陈旧的 evidence pane 状态。
@@ -43,7 +44,7 @@
 | 主回答区收缩为单一 targeted answer | `agent_workspace.js` 现在会保留完整 conversation result 到 runtime state，但主聊天面仅渲染用户面的回答块（`structured_answer`、`main_markdown`、`html_artifact`）。 | 当前切片已实现 |
 | 主命中列表不暴露开发者导向 evidence / action | `workspace_panes.js` 已不再在左侧命中列表中渲染 inline preview 或可见 typed capability button；这些流程现在会路由到 graph focus 或专门的 evidence pane。 | 当前切片已实现 |
 | durable evidence / claim inspector | `workspace_panes.js` 现已提供专门的 evidence pane，用于承接 grounding metadata、`knowledge_run`、`knowledge_run_history`、`knowledge_run_compare` 与 `flashcard_batch`；`agent_workspace.js` 也已把 API 状态条接成 grounding inspection 入口，并按当前回合规范清理陈旧 grounding 状态。 | 当前切片已更完整实现 |
-| DAG-native answer planning | `AgentConversationKnowledgePoint` 现已保留 grouped `relationPath`、`relationKinds`、`relationPathAtomIds` 与 `temporalValidity`；`conversationComposer.ts` 现已显式构建 `graphContext`；`KnowledgeLearningPlatform.ts` 与 `WorkspaceExportBundle.ts` 也已在 trace / persistence / export 中保留它；`workspace_panes.js` 现在会在 evidence pane 中把该 `graphContext` 渲染成结构化图解释面；关系与时序聚合也已扩展到整批 grouped knowledge points，并保留 source-atom 与 temporal-edge 细节；supersession 细节现在也会进入 explanation / next-action 文本。 | 当前切片已更宽的部分实现 |
+| DAG-native answer planning | `AgentConversationKnowledgePoint` 现已保留 grouped `relationPath`、`relationKinds`、`relationPathAtomIds` 与 `temporalValidity`；`conversationComposer.ts` 现已显式构建 `graphContext`；`KnowledgeLearningPlatform.ts` 与 `WorkspaceExportBundle.ts` 也已在 trace / persistence / export 中保留它；`workspace_panes.js` 现在会在 evidence pane 中把该 `graphContext` 渲染成结构化图解释面；关系与时序聚合也已扩展到整批 grouped knowledge points，并保留 source-atom 与 temporal-edge 细节；grouped knowledge points 之间的直接关系现在也会被保留并展示；supersession 细节现在也会进入 explanation / next-action 文本。 | 当前切片已更宽的部分实现 |
 
 从这里出发的即时推进方向：
 
diff --git a/docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md b/docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md
@@ -189,10 +189,12 @@ What the current slice now adds:
 - `buildAgentConversationGraphContext()` is no longer limited to the leading grouped knowledge point's local relation hints:
   - it now aggregates `relationPath` signals across the whole grouped knowledge-point set,
   - relation summaries now preserve `sourceAtomIds` as well as `targetAtomIds`,
+  - direct relations between grouped knowledge points are now materialized as first-class `knowledgePointRelations`,
   - supporting atom ids are assembled from the whole grouped set instead of the leading anchor only.
 - `workspace_panes.js` now projects that persisted `graphContext` into the evidence pane as a structured graph explanation surface:
   - anchor identity
   - relation kinds and relation summaries
+  - direct grouped-knowledge-point relations
   - relation source atoms
   - supporting titles and atom ids
   - temporal-validity status and warning reasons
@@ -315,6 +317,7 @@ Shipped characteristics:
 - the resulting `graphContext` now survives through conversation trace, snapshot persistence, and workspace export.
 - the evidence pane now renders that `graphContext` directly for user inspection,
 - relation aggregation now spans the whole grouped knowledge-point set and preserves relation source atoms,
+- direct grouped-knowledge-point relations are now preserved and surfaced through the same `graphContext`,
 - temporal-validity aggregation now preserves temporal edge kinds/details in addition to warning text,
 - grounding-pane state now clears cleanly when a later turn has no grounding payload.
 
diff --git a/src/agent_workspace.frontend.test.ts b/src/agent_workspace.frontend.test.ts
@@ -73,6 +73,7 @@ function createI18nStub() {
             'agentWorkspace.evidence.graphSupportingTitlesLabel': 'Supporting titles',
             'agentWorkspace.evidence.graphSupportingAtomsLabel': 'Supporting atoms',
             'agentWorkspace.evidence.graphRelationSummariesLabel': 'Relation summaries',
+            'agentWorkspace.evidence.graphKnowledgePointRelationsLabel': 'Knowledge-point relations',
             'agentWorkspace.evidence.graphRelationTargetsLabel': 'Targets: {count}',
             'agentWorkspace.evidence.graphRelationSourcesLabel': 'Sources: {sources}',
             'agentWorkspace.evidence.graphRelationConfidenceLabel': 'Avg confidence: {confidence}',
@@ -803,6 +804,7 @@ function createI18nStub() {
             'agentWorkspace.evidence.graphSupportingTitlesLabel': '支撑标题',
             'agentWorkspace.evidence.graphSupportingAtomsLabel': '支撑原子',
             'agentWorkspace.evidence.graphRelationSummariesLabel': '关系摘要',
+            'agentWorkspace.evidence.graphKnowledgePointRelationsLabel': '知识点关系',
             'agentWorkspace.evidence.graphRelationTargetsLabel': '目标数：{count}',
             'agentWorkspace.evidence.graphRelationSourcesLabel': '来源：{sources}',
             'agentWorkspace.evidence.graphRelationConfidenceLabel': '平均置信度：{confidence}',
diff --git a/src/export/WorkspaceExportBundle.test.ts b/src/export/WorkspaceExportBundle.test.ts
@@ -254,6 +254,17 @@ describe('WorkspaceExportBundle', () => {
                                         averageConfidence: 0.8,
                                     },
                                 ],
+                                knowledgePointRelations: [
+                                    {
+                                        edgeId: 'edge_reflection_reference',
+                                        relationKind: 'reference',
+                                        sourceAtomId: 'atom_reflection',
+                                        sourceTitle: 'Reflection',
+                                        targetAtomId: 'atom_transmission',
+                                        targetTitle: 'Transmission',
+                                        confidence: 0.8,
+                                    },
+                                ],
                                 temporalValidity: {
                                     checkedAt: '2026-05-26T00:00:00.000Z',
                                     allPointsValid: true,
@@ -294,6 +305,13 @@ describe('WorkspaceExportBundle', () => {
                         sourceAtomIds: ['atom_reflection'],
                     }),
                 ]),
+                knowledgePointRelations: expect.arrayContaining([
+                    expect.objectContaining({
+                        relationKind: 'reference',
+                        sourceTitle: 'Reflection',
+                        targetTitle: 'Transmission',
+                    }),
+                ]),
                 temporalValidity: expect.objectContaining({
                     edgeKinds: ['supersedes'],
                     details: expect.arrayContaining([
diff --git a/src/export/WorkspaceExportBundle.ts b/src/export/WorkspaceExportBundle.ts
@@ -256,6 +256,11 @@ function sortAndCloneConversationTurns(records: AgentConversationTurnRecord[]):
                                     targetAtomIds: Array.isArray(summary.targetAtomIds) ? [...summary.targetAtomIds] : [],
                                 }))
                                 : [],
+                            knowledgePointRelations: Array.isArray((record.response.trace as any).graphContext.knowledgePointRelations)
+                                ? (record.response.trace as any).graphContext.knowledgePointRelations.map((relation: any) => ({
+                                    ...relation,
+                                }))
+                                : [],
                             temporalValidity: (record.response.trace as any).graphContext.temporalValidity
                                 ? {
                                     ...(record.response.trace as any).graphContext.temporalValidity,
diff --git a/src/frontend/locales/en.json b/src/frontend/locales/en.json
@@ -446,6 +446,7 @@
       "graphSupportingTitlesLabel": "Supporting titles",
       "graphSupportingAtomsLabel": "Supporting atoms",
       "graphRelationSummariesLabel": "Relation summaries",
+      "graphKnowledgePointRelationsLabel": "Knowledge-point relations",
       "graphRelationTargetsLabel": "Targets: {count}",
       "graphRelationSourcesLabel": "Sources: {sources}",
       "graphRelationConfidenceLabel": "Avg confidence: {confidence}",
diff --git a/src/frontend/locales/zh.json b/src/frontend/locales/zh.json
@@ -446,6 +446,7 @@
       "graphSupportingTitlesLabel": "支撑标题",
       "graphSupportingAtomsLabel": "支撑原子",
       "graphRelationSummariesLabel": "关系摘要",
+      "graphKnowledgePointRelationsLabel": "知识点关系",
       "graphRelationTargetsLabel": "目标数：{count}",
       "graphRelationSourcesLabel": "来源：{sources}",
       "graphRelationConfidenceLabel": "平均置信度：{confidence}",
diff --git a/src/frontend/workspace_panes.js b/src/frontend/workspace_panes.js
@@ -590,6 +590,11 @@
                 .map((item) => item && typeof item === 'object' ? item : null)
                 .filter(Boolean)
             : [];
+        const knowledgePointRelations = Array.isArray(graphContext.knowledgePointRelations)
+            ? graphContext.knowledgePointRelations
+                .map((item) => item && typeof item === 'object' ? item : null)
+                .filter(Boolean)
+            : [];
         const temporalValidity = graphContext.temporalValidity && typeof graphContext.temporalValidity === 'object'
             ? graphContext.temporalValidity
             : null;
@@ -659,6 +664,21 @@
                 `;
             }).join('')
             : `<li class="agent-pane-list-empty">${escapeHtml(noneLabel)}</li>`;
+        const knowledgePointRelationHtml = knowledgePointRelations.length > 0
+            ? knowledgePointRelations.map((relation) => {
+                const relationLabel = `${String(relation.sourceTitle || noneLabel)} -> ${humanizeEvidenceRelationKind(relation.relationKind)} -> ${String(relation.targetTitle || noneLabel)}`;
+                const relationAtoms = `${String(relation.sourceAtomId || noneLabel)} -> ${String(relation.targetAtomId || noneLabel)}`;
+                return `
+                    <li class="agent-pane-list-item">
+                        <div>
+                            <div class="agent-pane-list-label">${escapeHtml(relationLabel)}</div>
+                            <div class="agent-pane-summary">${escapeHtml(relationAtoms)}</div>
+                        </div>
+                        <span class="agent-pane-meta">${escapeHtml(formatEvidenceConfidence(relation.confidence))}</span>
+                    </li>
+                `;
+            }).join('')
+            : '';
 
         const temporalEdgeKinds = temporalValidity && Array.isArray(temporalValidity.edgeKinds)
             ? temporalValidity.edgeKinds
@@ -719,6 +739,7 @@
             <ul class="agent-pane-list">${buildEvidenceMetricListHtml(contextMetrics)}</ul>
             <div class="agent-pane-section-title">${escapeHtml(translate('agentWorkspace.evidence.graphRelationSummariesLabel', 'Relation summaries'))}</div>
             <ul class="agent-pane-list">${relationSummaryHtml}</ul>
+            ${knowledgePointRelationHtml ? `<div class="agent-pane-section-title">${escapeHtml(translate('agentWorkspace.evidence.graphKnowledgePointRelationsLabel', 'Knowledge-point relations'))}</div><ul class="agent-pane-list">${knowledgePointRelationHtml}</ul>` : ''}
             ${temporalMetrics.length > 0 ? `<div class="agent-pane-section-title">${escapeHtml(translate('agentWorkspace.evidence.graphTemporalLabel', 'Temporal validity'))}</div><ul class="agent-pane-list">${buildEvidenceMetricListHtml(temporalMetrics)}</ul>` : ''}
             ${temporalDetailHtml ? `<div class="agent-pane-section-title">${escapeHtml(translate('agentWorkspace.evidence.graphTemporalDetailsLabel', 'Temporal edge details'))}</div><ul class="agent-pane-list">${temporalDetailHtml}</ul>` : ''}
         `;
diff --git a/src/learning/KnowledgeLearningPlatform.test.ts b/src/learning/KnowledgeLearningPlatform.test.ts
@@ -1820,6 +1820,23 @@ describe('KnowledgeLearningPlatform', () => {
                 relationKind: 'reference',
             }),
         ]));
+        expect((response.trace.graphContext as any).knowledgePointRelations).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                relationKind: 'reference',
+                sourceTitle: 'Reflection',
+                targetTitle: 'Transmission',
+            }),
+        ]));
+        expect(
+            structuredBlock && 'explanationMarkdown' in structuredBlock
+                ? String(structuredBlock.explanationMarkdown || '')
+                : ''
+        ).toContain('Reflection -> reference -> Transmission');
+        expect(
+            structuredBlock && 'nextActionsMarkdown' in structuredBlock
+                ? String(structuredBlock.nextActionsMarkdown || '')
+                : ''
+        ).toContain('Follow the direct graph path between Reflection and Transmission');
         expect((response.knowledgePoints[0] as any).relationKinds).toContain('reference');
     });
 
diff --git a/src/learning/KnowledgeLearningPlatform.ts b/src/learning/KnowledgeLearningPlatform.ts
@@ -3491,6 +3491,17 @@ export class KnowledgeLearningPlatform implements KnowledgeLearningPlatformAPI {
                     averageConfidence: Number.isFinite(Number(summary.averageConfidence)) ? Number(summary.averageConfidence) : 0,
                 }))
                 : [],
+            knowledgePointRelations: Array.isArray(value.knowledgePointRelations)
+                ? value.knowledgePointRelations.map((relation) => ({
+                    edgeId: String(relation.edgeId || '').trim(),
+                    relationKind: relation.relationKind,
+                    sourceAtomId: String(relation.sourceAtomId || '').trim(),
+                    sourceTitle: String(relation.sourceTitle || '').trim(),
+                    targetAtomId: String(relation.targetAtomId || '').trim(),
+                    targetTitle: String(relation.targetTitle || '').trim(),
+                    confidence: Number.isFinite(Number(relation.confidence)) ? Number(relation.confidence) : 0,
+                }))
+                : [],
             temporalValidity: value.temporalValidity && typeof value.temporalValidity === 'object'
                 ? {
                     checkedAt: String(value.temporalValidity.checkedAt || '').trim(),
diff --git a/src/learning/conversationComposer.test.ts b/src/learning/conversationComposer.test.ts
diff --git a/src/learning/conversationComposer.ts b/src/learning/conversationComposer.ts
diff --git a/src/learning/types.ts b/src/learning/types.ts
