2026-06-20 v1.7.0 - Agent Knowledge Workspace Graph Preview and Review Closure¶

English Document¶

Objective¶

This note closes the latest Agent Knowledge Workspace alignment slice on main. It reconciles the user's latest UI expectations with the already-landed DAG answer contract and final-answer review work:

the public answer stays targeted to the user's question instead of dumping retrieval evidence,
matched files are explicitly discoverable as clickable source entries without adding permanent instructional text to the workspace,
source clicks open the right focus pane and highlight the matched basis,
Related Focus hosts an isolated Knowledge Focus pane through the main graph's getFocusModeProjection() contract without reparenting the main #graph-container; pane-local double-clicks switch anchors or open Markdown inside the pane, Focus semantic labels stay visible, dense gray background context nodes are hidden by default, the hosted pane intentionally omits the main toolbar frame and visible edge layer, and backend relation detail stays hidden unless Developer Mode is enabled,
Learning Path hosts the Godot Future Path contract in the Guided Learning pane by using the existing Graph / PathEngine diffusion/core and treeLayout flow for the resolved DAG node, inheriting matching live Path-mode expansion/collapse/completion state when available, then rendering it through a modular TreeRenderer-compatible godot_future_path_renderer.js surface; it keeps human graph labels visible and does not show the native Godot window by default,
the final public answer is reviewed before release by the local deterministic reviewer,
all added fields and UI surfaces remain optional, additive, and backward-compatible.

This is not a recommendation to introduce another RAG framework. The right owner is already inside this codebase: the existing DAG, the learning runtime, the answer composer/reviewer, the main graph Focus-mode semantics, and the Godot Future Path treeLayout contract.

2026-06-24 Incremental Alignment¶

This update closes the remaining hosted-interaction parity issues reported after the 2026-06-22 slice. It does not change the reuse boundary: the workspace still reuses contracts and renderer semantics, not the live Tauri main graph DOM and not the native Godot window.

What changed:

Hosted Related Focus now has a pane-local viewport for wheel zoom, pointer panning, icon reset, and icon focus history. The transform state is scoped to the right-side pane and never mutates the main graph runtime.
Hosted Focus history is bounded and uses the same hosted anchor switch path as double-click focus switching, so the pane can move between water glass and application without calling openFocusModeById() or the global reader.
Hosted Learning Path now treats Future Path node double-click as a pane-local reader request. It reuses the existing source-path resolution and Markdown preview/highlight pipeline already used by Knowledge Focus.
src/frontend/godot_tree_interactions.js remains backward-compatible: nodeReaderRequested is optional, and callers that omit it still get the previous double-click prerequisite expand/collapse fallback.
The strict browser verifier now owns this exact regression: it checks node_reader_requested, verifies Knowledge_Base/waterglass/water glass.md is read, verifies Markdown appears inside the learning-path pane, verifies global reader.open remains unused, and verifies Focus wheel zoom, reset, history open, and history switching back to water glass.

Best-practice boundary:

Do not add a second Focus renderer just to gain controls. Keep using getFocusModeProjection() plus the shared double-click decision contract.
Do not wire Future Path double-click to global reader.open. The reader owner is the pane that received the graph interaction.
Do not treat native Godot docking as a small UI change. It is a platform-window ownership problem and should remain a separate spike if product direction later requires it.

2026-07-03 Incremental Alignment¶

This update closes three concrete gaps that remained after the hosted-interaction parity pass:

a fallback Mermaid parse failure on malformed quoted node labels,
first-open Guided Learning latency caused by repeated hosted Future Path runtime reconstruction,
public answers that still collapsed to the first top-hit sentence even when bounded DAG context had already been assembled.

What changed:

src/notemd/MermaidProcessor.ts and src/reader_renderer.ts now normalize stray inner double quotes inside bracketed Mermaid node labels on a per-line basis before parsing/rendering. This closes the known Superior Overall failure class without moving syntax repair into PathBridge; the bridge remains a transport owner, not a Mermaid repair owner.
The Mermaid repair path was tightened rather than widened blindly:
per-line normalization prevents the quote-escape pass from crossing line boundaries,
existing dangling-bracket label repairs continue to work,
the same malformed pattern is now covered at both the NoteMD source-fix boundary and the local renderer fallback boundary.
src/frontend/workspace_panes.js now caches the hosted Future Path Graph / PathEngine runtime by source-graph signature. Reopening or rerendering the same Guided Learning projection no longer rebuilds the full hosted graph runtime on every render.
The hosted Future Path runtime cache is no longer just a top-level mutable variable inside workspace_panes.js. A dedicated src/frontend/hosted_future_path_runtime.js owner now holds signature-based reuse plus cold/hot-path diagnostics, and workspace_panes.js consumes that owner instead of open-coding cache behavior.
The pending-pane path introduced in src/frontend/agent_workspace.js stays intact: the Guided Learning pane still opens immediately while /api/knowledge/path resolves, and the runtime cache now removes the repeated graph-rebuild cost behind that UI.
Developer-mode Guided Learning now exposes runtime-cache diagnostics for the hosted Future Path surface, including cache state, hit/miss/build counters, source node/edge counts, and resolve/build timing. The same diagnostics are also published through getHostedFuturePathRuntimeDiagnostics() and window.__NC_LAST_AGENT_GODOT_FUTURE_PATH_RUNTIME_DIAGNOSTICS.
The pending Guided Learning pane no longer waits on /api/knowledge/path before showing structure. When the current workspace already has a usable graph target and snapshot, workspace_panes.js now renders the hosted Future Path projection immediately and keeps the pending status visible while the backend request is still in flight.
src/frontend/agent_workspace.js now dedupes identical in-flight /api/knowledge/path requests by normalized request payload, preventing repeated clicks on the same Learning Path target from spawning parallel duplicate path builds.
src/learning/graphContextAssembler.ts now produces an additive anchorGraphProfile carrying bounded in-degree / out-degree / centrality facts for the selected anchor, and predecessor/successor windows now also preserve optional degree metadata.
src/learning/conversationComposer.ts no longer treats the main public answer as only “first direct sentence or title: summary”. It now uses the existing bounded DAG context to add a strongest-path sentence plus a compact graph-profile sentence when that context materially improves the answer.
src/learning/answerReleaseReview.ts now preserves that richer bounded graph-aware answer shape during deterministic revise flows instead of collapsing revised answers back to a single top-hit snippet.
The local references under ref/enterprise_agent_platform and ref/codex now support the chosen owner split:
enterprise_agent_platform reinforces runtime/retrieval/memory/evidence separation,
codex reinforces bounded model-visible context and additive context fragments,
neither suggests moving DAG semantics or release review into an external framework runtime.

Current code-vs-plan reading:

Requirement	Current implementation evidence	Progress call	Remaining risk
Fallback Mermaid rendering should not crash on the known malformed bracketed-label pattern	`MermaidProcessor.ts` and `reader_renderer.ts` now normalize stray quotes per line; `src/notemd.core.test.ts` and `src/reader_renderer.test.ts` pin the regression.	Implemented	If future imports generate new malformed Mermaid shapes, push repair upstream into source/diagram generation instead of piling fallback heuristics into the bridge.
First Learning Path open should avoid repeated full hosted runtime rebuilds	`workspace_panes.js` caches the hosted Future Path runtime by source-graph signature, and `src/agent_workspace.frontend.test.ts` verifies node/edge construction is not repeated for the same graph snapshot.	Implemented	Large-graph latency still needs real-corpus measurement; cache invalidation may need strengthening if live graph data mutates in place without a signature change.
First Learning Path open should show useful graph guidance before the backend path request completes	`workspace_panes.js` now renders an immediate hosted Future Path projection in the pending pane when local graph state is sufficient; `src/agent_workspace.frontend.test.ts` now verifies the pending pane contains both pending status and the hosted path surface before the deferred `/api/knowledge/path` response resolves.	Implemented	The backend request still matters for mastery/divergence/recommended-action payloads, so the remaining work is latency measurement and backend-path tuning, not removing the request entirely.
Hosted runtime reuse should have a real owner and observable cold/hot-path evidence	`hosted_future_path_runtime.js` now owns runtime-cache reuse and diagnostics; `src/agent_workspace.frontend.test.ts` now verifies both hot reuse for the same snapshot and rebuild on signature change.	Implemented partial owner reduction	This is instrumentation and owner tightening, not the final latency study. Real corpus measurement is still the next required step.
Learning Path request chaining should avoid duplicate identical in-flight backend calls	`agent_workspace.js` now keys in-flight `/api/knowledge/path` requests by normalized payload; `src/agent_workspace.frontend.test.ts` verifies repeated opens of the same target reuse a single in-flight request while the pending pane remains open.	Implemented	This reduces duplicate work during waiting windows, but it is not a substitute for true cold-open latency measurement on large corpora.
Public answers should use bounded graph context instead of only the top-hit sentence	`graphContextAssembler.ts` now supplies `anchorGraphProfile`; `conversationComposer.ts` and `answerReleaseReview.ts` now use bounded path/degree context on the public-answer path.	Implemented	This is still intentionally budgeted, not a full graph dump. The remaining work is answer-organization calibration, not more answer volume by default.

Fresh verification captured on 2026-07-03:

npm.cmd exec -- tsc --noEmit
npm.cmd exec -- jest src/learning/KnowledgeLearningPlatform.test.ts src/learning/KnowledgeWorkspaceConversationRegression.test.ts src/learning/conversationComposer.test.ts src/agent_workspace.frontend.test.ts src/notemd.core.test.ts src/reader_renderer.test.ts --runInBand --no-cache
npm.cmd run build:mini
node scripts/verify-knowledge-workspace-runtime.js --case waterglass_explicit_scope_compact_zh

2026-07-03 Architecture Progress Audit¶

This re-audit compares the current code against the earlier plan chain instead of treating the 2026-07-03 slice as an isolated fix set:

docs/brainstorms/2026-05-25-multiplatform-lightweight-rag-agent-architecture-plan.md
docs/brainstorms/2026-05-26-deep-student-comparison-next-phase-plan.md
docs/solutions/architecture-progress-alignment-2026-06-06.md
docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md
docs/solutions/agent-knowledge-dag-answer-contract-plan-2026-06-17.md
docs/solutions/agent-final-reply-review-robustness-plan-2026-06-18.md

Current reconciliation:

Prior expectation	Current code evidence	Progress reading	Next direction
The runtime should close the full scoped path from scope -> retrieval -> graph context -> answer -> review -> pane-backed evidence	`KnowledgeLearningPlatform.ts` normalizes graph context including `anchorGraphProfile`; `graphContextAssembler.ts` assembles bounded graph context; `conversationComposer.ts` composes the bounded public answer; `answerReleaseReview.ts` remains the deterministic final gate; `workspace_panes.js` holds pane-backed evidence and graph projections.	Implemented baseline	Keep tightening owner boundaries, not by adding a framework, but by shrinking oversized local owners around real invariants.
DAG structure should affect answer planning rather than staying a shallow retrieval bonus	`graphContextAssembler.ts` now emits `connectionPaths`, `anchorGraphProfile`, `predecessorWindow`, `successorWindow`, and `evidenceSourceRefs`; `conversationComposer.ts` and `answerReleaseReview.ts` now use bounded path/degree context on the public-answer path.	Implemented stronger baseline	Calibrate answer organization on real corpora before adding more graph-derived sentences or weights.
RSE-style document augmentation should stay evidence-backed and bounded	The current `graphContext` remains additive and budgeted; `evidenceSourceRefs`, explicit path windows, and anchor degree/profile facts augment the answer path without turning the main response into a trace dump.	Implemented bounded baseline, not final closure	Expand only through measured retrieval/ranking gains and explicit weak-evidence behavior, not through larger prompt payloads.
Hosted Guided Learning should feel responsive without violating owner boundaries	`workspace_panes.js` reuses hosted `Graph` / `PathEngine` runtime by source-graph signature, while `agent_workspace.js` keeps the immediate pending-pane open behavior.	Implemented	Capture cold-open vs hot-reopen evidence on large corpora before changing cache invalidation semantics.
Hosted Guided Learning cache identity and telemetry should belong to a narrow owner instead of a workspace-global mutable variable	`hosted_future_path_runtime.js` now owns signature-based reuse, cache hit/miss/build counters, and resolve/build timing; `workspace_panes.js` consumes that owner and exposes the last diagnostics snapshot.	Implemented improvement	More owner reduction is still needed elsewhere; this only removes one local concentration point.
Guided Learning should avoid wasting request work while the same target is already opening	`agent_workspace.js` now dedupes identical in-flight `/api/knowledge/path` calls, and the pending pane can already show a local hosted projection before the backend reply arrives.	Implemented improvement	The end-state still requires measured large-corpus latency evidence before calling the first-open problem closed.
The system should learn from reference architectures without importing their runtime ownership wholesale	`ref/enterprise_agent_platform` reinforces evidence/retrieval/runtime/review separation and RAG failure ledgers; `ref/codex` reinforces bounded model-visible context, additive fragments, and hard context caps.	Integrated as design guidance	Keep using local TypeScript owners for DAG semantics, release review, and pane behavior instead of delegating them to external orchestration stacks.
Mainline architecture pressure should fall over time instead of concentrating into bigger files	Current line counts remain high: `src/server.ts` about `15850`, `src/learning/KnowledgeLearningPlatform.ts` about `11200`, `src/frontend/workspace_panes.js` about `9289`, `src/frontend/agent_workspace.js` about `4882`, and `src/learning/answerReleaseReview.ts` about `4261`; the newly introduced `src/learning/graphContextAssembler.ts` is about `792`, and the new `src/frontend/hosted_future_path_runtime.js` now holds the hosted Future Path cache/diagnostics invariant outside `workspace_panes.js`.	Improved, still behind	Continue preferring narrow extractions only when the new module owns a real invariant such as cache identity, telemetry, or answer-boundary policy.

Progress reading:

The main gap is no longer "whether the existing DAG reaches the answer path." That closure now exists in code.
The main gap is also no longer "whether Learning Path can reuse the hosted runtime." That closure now exists in code.
The remaining risk is still architectural concentration, but this slice now reduces it in two concrete ways: a real owner extraction for hosted Future Path cache identity/diagnostics, and narrower request ownership for identical in-flight Learning Path calls.
The right next move is therefore calibration plus ownership reduction, not another broad framework comparison pass.

Best-practice boundary:

Keep Mermaid repair in the source-fix and renderer-fallback owners; do not move syntax healing into PathBridge.
Keep hosted Future Path runtime reuse keyed to graph snapshot identity/signature; do not turn it into a global mutable singleton that can leak state across unrelated graphs.
Keep graph-aware public answers bounded. Rich graph telemetry still belongs in traces, panes, artifacts, and export surfaces.

Completion Boundary¶

Current implementation status is code-backed:

src/learning/graphContextAssembler.ts owns graph-conditioned context assembly before answer synthesis.
src/learning/conversationComposer.ts calls reviewAnswerRelease() and releases answerReleaseReview.publicAnswer.
src/learning/answerReleaseReview.ts owns deterministic public-answer gates, including graph-causal, graph-order, graph-comparison, temporal-validity, and query-intent gates.
src/frontend/workspace_panes.js owns the Knowledge Workspace source focus pane, help affordance, matched-file action controls, hosted Focus projection pane, pane-local Focus viewport controls, bounded Focus history, hosted Godot Future Path renderer surface, pane-local node readers, close controls, and provenance diagnostics.
src/frontend/focus_mode_interactions.js owns the shared Focus-mode double-click decision contract now consumed by both the main graph runtime and the hosted Knowledge Focus pane.
src/frontend/godot_tree_interactions.js owns the browser-to-Godot TreeRenderer signal adapter for hosted Future Path input: node click, optional pane-local reader requests on double-click, spine-only right-click/double-click prerequisite expansion fallback, middle-click collapse-all, and long-press navigation. Toggle eligibility follows the Godot TreeRenderer contract instead of widening to non-spine prerequisite nodes.
src/frontend/godot_future_path_renderer.js owns the modular TreeRenderer-compatible Future Path surface: 140x50 capsule nodes, Bezier skip-level edge filtering, active subtree hulls, spine expansion badges, hover subtree focus, word-preserving labels, and target-centered pane-local pan/zoom auto-fit hooks.
scripts/verify-agent-workspace-browser.js owns the strict browser regression for the latest UI defects, including the water glass.md display case, hosted Focus anchor/no-context-dot assertions for water glass, hosted Focus semantic-label assertions, absence of the hosted Focus toolbar/edge layer, Focus wheel zoom/reset/history behavior, pane-local Focus double-click switching and reader opening, refusal to dock the main #graph-container, live Path-mode expansion-state inheritance, TreeRenderer marker/hull/viewport assertions, Future Path double-click pane-local Markdown opening, Godot-style click/right-click/middle-click signal assertions, right-click collapse state for water glass, and refusal to show the native Godot window by default.
src/agent_workspace.frontend.test.ts pins help-popover behavior, stable ARIA/control IDs, source highlight behavior, hosted Focus projection behavior, pane-local Focus viewport/history controls, pane-local Focus double-click semantics, hosted Future Path pane-local node reader behavior, and Godot Future Path renderer/input semantics.

The remaining work is calibration and coverage expansion. It is not a blocker for this slice:

older payloads without source offsets still need conservative fallback,
the reviewer should keep expanding contradiction families only when false-positive boundaries are explicit,
the Focus pane reuses the Focus-mode behavior contract without taking ownership of the main graph DOM; it renders a pane-local Focus surface backed by existing graph snapshot/resolve APIs and a pane-local Markdown reader,
CI should keep the strict browser UI gate fresh if this surface continues changing.

First Principles¶

Term Definitions¶

Public answer: the final text displayed in the main answer area. It should answer the user's question directly and should not list citations, debug counters, graph traces, or planner state.
Secondary evidence surface: any pane, card, export, trace, or diagnostic area that helps developers or advanced users inspect why an answer was produced.
Existing DAG: this project's directed acyclic knowledge structure built from notes, atoms, relations, prerequisites, next-step edges, references, and temporal edges. It is not a generic graph database product.
Knowledge hit: a matched document, concept, atom, or grouped source returned by the agent workspace query path.
Source provenance: the path, line window, snippet, and optional source offsets that let the UI open the original Markdown and highlight the exact support fragment.
Graph context pack: the bounded graph-derived structure assembled for answer synthesis. It contains anchor identity, support nodes, relation/path windows, temporal warnings, evidence refs, and diagnostics. It must not be the whole graph.
Answer release review: the post-synthesis decision layer that can release, revise, or abstain before a draft becomes the public answer.
Hosted Focus pane: rendering an isolated Focus-mode surface from the existing graph snapshot and node-resolution APIs. It preserves Focus-mode semantics while keeping the main graph lifecycle untouched; pane-local double-clicks either switch the focus anchor or open Markdown inside the pane-local reader.
Hosted Godot Future Path projection: running the resolved DAG node through the existing frontend Graph / PathEngine diffusion/core path and projecting the resulting treeLayout into the Guided Learning pane. The pane deliberately does not mount browser #path-container, does not call bridge/Tauri showGodot=true, and does not require native window reparenting.
Resolved graph label: the human-facing node name selected for display. In the reported failure this must be water glass, not an internal atom ID such as atom_h.

Layer Connections¶

The runtime should be read as a chain of owners:

Markdown source layer
Owns durable source text, filenames, headings, and raw snippets.
Required invariant: a knowledge hit must be traceable back to a canonical source path or a controlled fallback path.
Graph build and DAG layer
Owns graph nodes, edges, topological structure, predecessor/successor semantics, and graph-view data.
Required invariant: edge direction must remain meaningful. A prerequisite edge cannot be rendered as a symmetric "related" edge when it is used for learning guidance.
Learning atom/relation layer
Owns KnowledgeAtom, RelationEdge, TemporalEdge, evidence spans, scoped store operations, and graph-path lookup.
Required invariant: answer-time graph structure should come from typed runtime data, not from display strings scraped in the frontend.
Graph context assembly layer
Owns bounded graph-context selection for the LLM/composer.
Required invariant: the graph pack is scoped, budgeted, and explainable. It should include enough high-quality DAG structure for the answer, not the entire corpus.
Answer synthesis layer
Owns draft answer creation from scoped retrieval plus graph context.
Required invariant: draft generation can use evidence and graph paths, but the public answer should stay narrow unless the user asks to inspect supporting material.
Answer release review layer
Owns final release policy.
Required invariant: unsupported, contradictory, temporally stale, or diagnostic-leaking drafts must be revised or abstained before they hit the main answer surface.
Frontend Knowledge Workspace layer
Owns discoverability, source reading, source highlighting, right-pane lifecycle, and graph previews.
Required invariant: the UI projects structured state. It should not invent graph semantics from arbitrary text labels.
Verification layer
Owns regression evidence.
Required invariant: the exact failure class should be executable. Screenshots alone are not enough once the failure is understood.

Current Code vs Prior Requirements¶

Requirement	Current implementation evidence	Progress call	Remaining risk
Public answer should be targeted, not a list of every retrieved item	`conversationComposer.ts` releases `answerReleaseReview.publicAnswer`; graph/evidence detail stays in blocks, traces, panes, artifacts, and exports.	Implemented	Future prompt or composer changes can accidentally re-inflate the main answer.
Developer-heavy evidence and previously purple-box-style content should not pollute the main area	The runtime keeps graph context, citations, `knowledgeRun`, and reviewer state in secondary surfaces.	Implemented	Useful evidence can become invisible if there is no clear affordance to inspect it.
Matched files need a clear affordance that left-click opens source and highlights support	`workspace_panes.js` now uses a compact question-mark help control instead of permanent instructional text.	Implemented	Tooltip text must stay keyboard-accessible and must not reappear as static clutter.
Left matched-file area must be scrollable and show long names such as `water glass.md`	The strict browser verifier checks visible `water glass.md`, no horizontal overflow, and interactive action targets.	Implemented	Very long filenames still need truncation plus tooltip discipline, not layout expansion.
Clicking a hit should open right-side source and highlight matched evidence	Source pane logic uses source-line provenance, line windows, snippets, and offset-backed inline highlight where available.	Implemented baseline	Old payloads without offsets can only fall back conservatively.
Right-side source window needs a close control	The strict browser verifier asserts three close buttons across the affected right-pane surfaces.	Implemented	Future pane additions must not bypass the shared close-control pattern.
`Related Focus` should match Tauri Focus mode semantics	`workspace_panes.js` hosts a pane-local Focus-mode surface from `NoteConnectionGraphView.getFocusModeProjection()`, keeps the main `#graph-container` in its original parent, renders active Focus nodes without dense gray context dots, preserves the Focus semantic labels, intentionally omits the hosted toolbar frame and visible edge layer, and consumes `focus_mode_interactions.js` so the main graph and hosted pane share the same double-click decision model: related-node double-click switches the pane-local anchor, anchor double-click opens Markdown inside the pane-local reader, and global `reader.open` remains untouched. Relation diagnostics are Developer Mode only.	Implemented	This is projection/behavior-contract reuse, not DOM reuse. Any future attempt to reuse the live graph instance must first solve reader ownership and main-graph lifecycle isolation.
`Learning Path` should match Godot/Path mode semantics and use the real node name	`workspace_panes.js` resolves the selected DAG node, uses existing frontend `Graph` / `PathEngine` `diffusion/core` plus `getTreeLayout(...)`, inherits matching live Path-mode expansion/collapse/completion state, renders the resulting tree through `godot_future_path_renderer.js`, and consumes `godot_tree_interactions.js` so browser input emits Godot TreeRenderer spine-only signals. The strict verifier checks `water glass` labels, live expansion-state inheritance, TreeRenderer marker/hull/viewport state, node-click selection, right-click expansion/collapse, middle-click collapse-all, and rejects browser `#path-container` docking plus bridge/Tauri `showGodot=true`.	Implemented	This does not embed the native Godot window. Native window reparenting remains a separate platform spike, not a pane feature.
Existing DAG should be visible to the LLM and reviewer	`graphContextAssembler.ts` assembles `connectionPaths`, predecessor/successor windows, temporal validity, evidence refs, and diagnostics; reviewer graph gates consume DAG context.	Implemented baseline	Ranking and reviewer calibration still need broader corpora.
Final public answer needs robust review and correction	`answerReleaseReview.ts` owns deterministic release gates and is called before response release.	Implemented	Gate expansion must remain conservative to avoid false positives.
Compatibility must be preserved	New fields are optional/additive; legacy `assistantMessage` and existing answer fields remain valid.	Implemented	Contract drift can reappear if new clients treat optional fields as mandatory.

Why the Earlier Framework Options Are Not the Runtime Answer¶

The reference projects under ref/ are useful, but they solve different layers:

Reference	Useful pattern	Why it should not own this slice
DSPy	Typed LM programs, evaluation harnesses, optimizer loops.	It can help offline prompt/reviewer evaluation, but it should not become the source of truth for local DAG invariants in a TypeScript/Tauri runtime.
Guidance	Constrained generation and structured output control.	It shapes generated text, but it does not guarantee source-pane provenance, graph-mode projection, or release-worthiness.
Semantic Kernel	Prompt function boundaries, orchestration, telemetry concepts.	Importing a broad orchestration framework would duplicate local owners and increase integration surface.
LangChain Core	Runnable composition, parser boundaries, observability patterns.	Useful as a design reference, but it should not replace this project's existing learning runtime and graph context pack.
LiteLLM	Provider routing and model-call normalization.	Provider routing is orthogonal to DAG correctness, source highlighting, and final public-answer review.

The better direction is local ownership with optional external evaluation:

keep graph semantics in TypeScript types and store operations,
keep release policy in the deterministic backend reviewer,
keep model frameworks outside the hot path unless there is a measured reason,
use reference libraries for evaluation, not as a substitute for invariants.

Implementation Phases and Current Progress¶

P0: Public Answer Surface Contraction¶

Status: completed.

The main answer area now receives the release-reviewed public answer. Citation lists, graph paths, temporal warnings, reviewer details, and developer traces stay in structured surfaces. This is the right boundary: the user asked a question, not for a dump of every retrieved artifact.

Pitfall to avoid: do not "fix" sparse answers by appending evidence blocks to the public answer. That recreates the original defect under a different shape.

P1: DAG Context Assembly¶

Status: completed baseline.

graphContextAssembler.ts is the correct owner because it sits between retrieval and synthesis. It can see scoped candidates and graph operations before the answer is drafted. This is where predecessor windows, successor windows, connection paths, temporal validity, and evidence refs belong.

Tradeoff: the pack is bounded. Sending the whole graph would increase latency and confusion faster than it improves answer quality.

P2: Final Answer Release Review¶

Status: completed baseline.

answerReleaseReview.ts now owns the final release decision. Its value is not that it catches every semantic error. Its value is that public-answer correctness is no longer an accidental property of a prompt string.

Tradeoff: deterministic gates are narrower than a model verifier, but they are testable, low-latency, and auditable. A model verifier can be added later as a shadow signal only after the local gate contract is stable.

P3: Source Focus and Highlight Provenance¶

Status: completed baseline.

The right pane resolves candidate source paths, renders Markdown, selects the best evidence block, and projects inline highlights. Offset-backed provenance is preferred when available; line/snippet fallback keeps legacy payloads working.

Pitfall to avoid: do not relax the evidence gate because old payloads lack offsets. Missing provenance should be observable, not silently treated as correct.

P4: Matched-File Discoverability and Workspace Hygiene¶

Status: completed.

The matched-file area now has an explicit compact help affordance. The instructional copy is not permanently printed into the workspace. This matches the product requirement: discoverability without visual pollution.

Best practice: the help control must work on hover and focus, must close on blur/outside interaction, and must keep stable ARIA relationships so rerenders do not orphan the tooltip.

P5: Focus Runtime and Godot Future Path Reuse¶

Status: completed.

Related Focus hosts the selected node inside a Knowledge Focus pane without moving the main graph DOM. The pane uses the main graph's pure getFocusModeProjection() contract, renders the resolved node name, keeps Focus semantic labels visible, hides the dense gray background context dots by default, and consumes the same focus_mode_interactions.js double-click decision model as the main graph runtime. The hosted surface deliberately does not render the main toolbar frame or visible edge layer. Related-node double-click switches only the pane-local anchor; anchor double-click opens Markdown in the pane-local reader; global reader.open is not called. Relation-edge lists, relation kinds, and backend diagnostics are available only when Developer Mode is enabled.

Learning Path does not show Tauri/browser Learning Path and does not mount browser path-container. It resolves the selected hit to a DAG node, then uses existing frontend Graph / PathEngine with diffusionLearning(target, 'core', completedSet, forcedExpansionSet) and getTreeLayout(..., collapsedSet, expansionOrder, stickyClaimEnabled, { verticalGap: 240 }). When the live Path-mode target is the same diffusion/core node, the hosted pane inherits completedIds, forcedExpansionIds, collapsedIds, expansionOrder, and stickyClaimEnabled before recomputing the pane-local layout. The resulting tree is rendered by godot_future_path_renderer.js, a modular TreeRenderer-compatible surface that keeps Godot's capsule nodes, Bezier edge filtering, active subtree hulls, spine-only expansion badges, hover subtree focus, word-preserving labels, and pane-local pan/zoom auto-fit. Input is routed through godot_tree_interactions.js, which maps browser events back to the Godot TreeRenderer signal contract instead of relying on ad hoc DOM handlers. Pane-local right-click collapse remains a state-machine guarantee: an explicit collapse of the current target survives the next render instead of being overwritten by the default target-expanded initialization path.

Tradeoff: a hosted Focus pane avoids stealing lifecycle ownership from the main Tauri graph, but it must explicitly preserve the interaction semantics without importing every visual context layer. A hosted Future Path projection avoids native window reparenting and now reuses the Godot-facing treeLayout contract, live Path-mode expansion state, and TreeRenderer semantics; pixel-perfect native Godot parity or true native window docking remains a dedicated renderer extraction or embedding project.

P6: Regression and Release Hygiene¶

Status: completed for this slice.

The current regression surface includes Jest contracts and a strict browser verifier that exercises the exact water glass.md UI failure. This matters because the most recent defects were not theoretical architecture issues; they were product-level mismatches in labels, scrollability, affordances, and pane lifecycle.

Testing and Verification Snapshot¶

Fresh validation evidence for the current mainline includes:

npm run build
npm test -- --runInBand
npm run test:agent-workspace:contracts
npm exec -- tsc --noEmit
npm run build:vite
node --check scripts/verify-agent-workspace-browser.js
strict browser verification through scripts/verify-agent-workspace-browser.js
frontend law audit evidence under output/agent-workspace-frontend-audit.*

The strict browser case specifically verifies:

water glass.md is visible as a matched file,
the help text is hidden behind the question-mark affordance until hover/focus,
Learning Path and Related Focus are interactive,
action targets meet minimum hit-area expectations,
there is no horizontal overflow,
hosted Focus uses projection data, Focus semantic labels, and a high-density background context-dot layer for target water glass,
hosted Focus does not render the toolbar/control frame or visible edge layer,
hosted Focus related-node double-click switches the pane-local anchor to application,
hosted Focus anchor double-click opens the pane-local Markdown reader and does not call global reader.open,
hosted Godot Future Path uses diffusion/core, treeLayout, live Path-mode expansion-state inheritance, and the modular TreeRenderer-compatible renderer for target water glass,
Future Path preserves water glass as a word-preserving node label and exposes TreeRenderer hulls, expansion badges, and viewport auto-fit state,
Future Path left-click emits node_clicked and selects water glass,
Future Path right-click emits a TreeRenderer prerequisite collapse signal for the initially expanded water glass target and leaves that target in the collapsed set after rerender,
Future Path middle-click on the viewport emits collapse_all_requested,
the browser path-container is not docked into the learning pane,
bridge/Tauri showGodot=true is not called by the pane action,
the real #graph-container stays in its original parent,
default Related Focus does not display relation diagnostics unless Developer Mode is enabled,
right-pane windows have close controls.

Tradeoffs¶

Reuse contracts, not ownership by accident: Focus reuses projection semantics without moving the main graph DOM and without rendering the dense gray background context layer in the hosted pane; Future Path reuses the Graph / PathEngine / Godot treeLayout contract plus Path-mode expansion-state and TreeRenderer-compatible rendering semantics instead of opening or embedding the native window by default.
Deterministic reviewer before model verifier: less broad semantic coverage, but stable, testable release policy.
Bounded DAG pack over whole-graph prompt: less complete context, but lower latency and lower hallucination risk.
Optional additive fields over mandatory schema break: slower cleanup of legacy branches, but preserves existing clients.
Tooltip affordance over static instruction copy: less always-visible guidance, but cleaner workspace and better scan density.

Pitfalls¶

Rendering internal atom IDs when a human graph label is available.
Treating a graph database or prompt framework as a substitute for the existing DAG contract.
Putting instructional copy directly in the workspace because the click affordance is weak.
Reintroducing a handcrafted Path preview, browser Path mount, or native-window show side effect after the requirement has been clarified as hosted Godot Future Path contract and TreeRenderer-semantics reuse.
Expanding reviewer gates faster than the false-positive corpus.
Hiding missing provenance by broadening highlight heuristics until the UI "looks right".
Adding a facade that only forwards calls and owns no invariant.

Next Direction¶

Broaden the answer-release contradiction corpus around real user failures: alias drift, cross-scope leakage, same-subject relation swaps, temporal drift, and graph-direction reversals.
Increase source-offset coverage for legacy payloads so repeated snippets can be disambiguated more often without heavier AST provenance.
Calibrate graph-aware ranking with real corpora before increasing relation-weight bonuses.
Extract frontend owners only when the new module owns a real invariant, for example graph-projection normalization or source-provenance selection.
Keep strict browser UI verification in CI for this surface if matched-file interactions continue evolving.
Add explicit hosted Future Path runtime-cache invalidation only if real graph-mutation paths prove that source-graph signature reuse is insufficient.
Measure first-open versus hot-reopen Guided Learning latency on representative large corpora before taking on deeper frontend performance work.
Keep the graph-aware public-answer path aligned with bounded RSE-style augmentation: use anchor, path, and degree context to strengthen the answer, but do not turn the main answer area into a graph-inspection surface.

Thought Model¶

Use three questions when changing this area:

What is the public answer allowed to say?
Owned by answer synthesis plus release review.
What evidence and graph structure produced that answer?
Owned by graph context assembly, traces, artifacts, panes, and exports.
How does the user inspect the supporting source or graph context?
Owned by source focus, matched-file controls, hosted Focus behavior, and hosted Godot Future Path projection.

Do not collapse these questions into one prompt or one frontend component. Each question has a different invariant and a different failure mode.

Real Applications¶

A user asks 什么是waterglass?: the public answer should define the concept directly; the matched file should show water glass.md; source click should open the Markdown and highlight the support.
A user wants to learn the selected node: Learning Path should host the Godot Future Path diffusion/core/treeLayout projection for the selected DAG node and keep visible node labels such as water glass.
A user wants relation context: Related Focus should provide the same Focus-mode interaction model in the Knowledge Focus pane without stealing the main graph DOM or opening Markdown in the global reader.
A developer audits a questionable answer: the reviewer result, graph context, citations, and provenance diagnostics should be available in secondary surfaces without polluting the public answer.

Common Misreads¶

"The UI shows graph buttons, so the LLM is graph-native."
Wrong. Graph-native answer planning requires graph context before synthesis and graph gates before release.
"The answer is concise, so it is correct."
Wrong. Concision and correctness are separate invariants.
"A prompt framework can solve final answer review."
Incomplete. It can shape drafts, but release policy still needs a local owner.
"Side-pane Path/Focus must embed the real Godot/Tauri windows."
Too broad. Focus must preserve Focus-mode behavior in the pane, but moving the main graph DOM breaks ownership. Future Path currently reuses the Godot data contract through treeLayout; DOM/native embedding needs separate renderer extraction or native window reparenting work.
"If the highlight is roughly near the right paragraph, provenance is good enough."
Not for repeated snippets. Offset or AST provenance is the durable fix.

Five-Point Summary¶

The correct architecture is local DAG -> bounded graph context -> answer synthesis -> deterministic release review -> secondary evidence surfaces.
The latest UI slice now reuses real contracts: matched files are discoverable and clickable, source highlights work, Focus is hosted with pane-local interactions and no dense gray context dots, Learning Path hosts the Godot Future Path treeLayout through the modular TreeRenderer-compatible renderer plus live Path-mode expansion state, labels stay human-readable, and right panes can close.
The earlier DSPy/Guidance/Semantic Kernel/LangChain/LiteLLM ideas remain useful references, but none should own DAG semantics, source provenance, or final release policy in this runtime.
The main remaining risk is calibration, not missing ownership: broader reviewer corpora, more offset coverage, and ranking evaluation are the next hard work.
Keep changes backward-compatible and invariant-owned; avoid pass-through layers, unbounded graph dumps, and UI-only correctness fixes.

2026-06-22 Interaction Contract Addendum¶

This follow-up closes the specific interaction gap behind the latest user rejection. The previous side-pane implementation was still too close to a visual approximation: it could prove that a Focus/Future Path-like surface existed, but it did not make the reused interaction contracts executable enough.

What changed:

Focus double-click behavior is now a shared contract in src/frontend/focus_mode_interactions.js, used by both src/frontend/app.js and the hosted Knowledge Focus pane.
Hosted Focus remains pane-local by design: related-node double-click switches the hosted anchor, anchor double-click opens the pane-local Markdown reader, and the main graph DOM plus global reader lifecycle are not mutated.
Godot Future Path input is now mediated by src/frontend/godot_tree_interactions.js, a TreeRenderer signal adapter rather than bespoke button handlers.
Hosted Future Path now records and verifies Godot-style signals: node_clicked, prerequisite expand/collapse, and collapse_all_requested; right-click collapse of the current target is now verified as state, not only as an emitted signal.
Hosted Focus now verifies the mainlike contract directly: no Layout toolbar frame, no visible edge layer, no dense gray context-dot layer, Focus semantic labels, and pane-local double-click behavior.
Hosted Future Path now inherits the matching live Path-mode state package (completedIds, forcedExpansionIds, collapsedIds, expansionOrder, stickyClaimEnabled) before recomputing the pane-local treeLayout; this is the piece that aligns main-spine subtree counts with the native Future Path flow.
Strict browser verification now fails if the water glass Focus/Future Path pane is merely visible but not interactable.

The deliberate limitation remains: this is contract and renderer-semantics reuse, not native Godot window embedding. Native window docking would require a separate platform-level owner for window parenting, input focus, teardown, and reader routing.

中文文档¶

目标¶

本文收口 main 上最新一轮 Agent Knowledge Workspace 对齐工作。它把用户最新 UI 期望与已经落地的 DAG 回答契约、最终回答审核机制对齐：

公开回答只针对用户问题，不把检索证据堆进主回答区；
命中文件必须有明确但克制的可点击提示；
单击命中文件后打开右侧聚焦 pane，并高亮命中依据；
关联聚焦 在右侧知识聚焦 pane 内托管隔离的 Focus-mode 行为，不重挂载主 #graph-container；pane 内双击关联节点切换锚点，双击中心节点在 pane 内打开 Markdown，保留 Focus 语义标签，但默认不渲染密集灰色背景 context 节点，并刻意不显示主界面工具框和可见边线；Developer Mode 关闭时隐藏后端 relation 细节；
学习路径 在引导式学习 pane 内托管 Godot Future Path 数据契约：复用现有 Graph / PathEngine 的 diffusion/core 与 treeLayout 流程解析目标 DAG 节点，并在 live Path mode 的 target/mode/strategy 匹配时继承 expansion/collapse/completion 状态包，保持人类可读图节点名可见，且默认不显示 Godot 原生窗口；
最终公开回答必须先经过本地确定性 reviewer 再发布；
新增字段与 UI surface 保持 optional、additive、向前兼容。

这不是引入另一套 RAG 框架的理由。正确 owner 已经在本项目内部：现有 DAG、learning runtime、answer composer/reviewer、主图 Focus-mode 语义，以及 Godot Future Path 的 treeLayout 契约。

2026-06-24 增量对齐¶

本次更新收口 2026-06-22 后继续暴露的托管交互 parity 问题。它不改变复用边界：工作区继续复用契约与 renderer 语义，而不是复用 Tauri 主图的 live DOM，也不是复用 Godot 原生窗口。

当前变化：

托管 关联聚焦 现在具备 pane-local viewport，支持滚轮缩放、指针拖拽平移、图标式 reset 与图标式 focus history。transform 状态只作用于右侧 pane，不会修改主图运行时。
托管 Focus history 有数量上限，并复用与双击切换相同的 hosted anchor switch 路径，因此 pane 可以在 water glass 与 application 之间移动，而不调用 openFocusModeById() 或全局 reader。
托管 学习路径 现在将 Future Path 节点双击视为 pane-local reader 请求。它复用知识聚焦已经使用的 source-path 解析与 Markdown preview/highlight 管线。
src/frontend/godot_tree_interactions.js 继续保持向前兼容：nodeReaderRequested 是可选 callback，未提供该 callback 的调用方仍保留旧的双击 prerequisite 展开 / 收起回退行为。
strict browser verifier 已经持有这条准确回归：检查 node_reader_requested、确认读取 Knowledge_Base/waterglass/water glass.md、确认 Markdown 出现在 learning-path pane 内、确认全局 reader.open 未被调用，并确认 Focus 可滚轮缩放、reset、打开 history、通过 history 回跳到 water glass。

最佳实践边界：

不要为了拿到控件而再写一套 Focus renderer。继续复用 getFocusModeProjection() 与共享双击决策契约。
不要把 Future Path 双击接到全局 reader.open。reader owner 应该是接收图交互的 pane。
不要把 Godot 原生 docking 当成小 UI 改动。它是平台窗口 owner 问题；如果后续产品方向需要，应作为独立 spike 处理。

2026-07-03 增量对齐¶

这次更新收口的是 hosted-interaction parity 之后仍然存在的三类具体缺口：

回退 Mermaid 渲染在畸形带引号节点标签上的解析失败，
Guided Learning 首次打开时因为重复重建托管 Future Path 运行时而产生的卡顿，
明明已经装配出有界 DAG context，但主公开回答仍只退化成首条 top-hit 句子的过短回答。

当前变化：

src/notemd/MermaidProcessor.ts 与 src/reader_renderer.ts 现在都会在解析/渲染前按“逐行”方式归一化 bracketed Mermaid node label 内部多余的双引号。这使已知的 Superior Overall 故障类在 NoteMD 源修复层与本地 renderer fallback 层都可被自愈，而不需要把语法修复错误地塞进 PathBridge；bridge 继续只做 transport owner。
Mermaid 修复路径这次是“收紧而不是放宽”：
逐行归一化避免新的 quote-escape 逻辑跨行污染其他 Mermaid 语句，
原有 dangling-bracket label repair 继续有效，
相同的 malformed 模式现在同时被 source-fix 边界与 local renderer fallback 边界覆盖。
src/frontend/workspace_panes.js 现在会按 source-graph signature 缓存托管 Future Path 的 Graph / PathEngine 运行时。对同一 Guided Learning 投影的再次打开或 rerender 不再每次都重建整套托管图运行时。
托管 Future Path runtime cache 现在也不再只是 workspace_panes.js 顶层的可变变量。新的 src/frontend/hosted_future_path_runtime.js 已经成为独立 owner，负责按签名复用运行时并记录冷/热路径诊断。
src/frontend/agent_workspace.js 里已有的 pending-pane 路径继续保留：/api/knowledge/path 尚未返回时，Guided Learning pane 仍立即打开；现在托管运行时缓存则进一步去掉了其后的重复图重建成本。
Developer Mode 下的 Guided Learning 现在会显示 hosted Future Path runtime-cache 诊断，包括 cache state、hit/miss/build 计数、source node/edge 数量，以及 resolve/build 时延；同一组诊断也会通过 getHostedFuturePathRuntimeDiagnostics() 与 window.__NC_LAST_AGENT_GODOT_FUTURE_PATH_RUNTIME_DIAGNOSTICS 暴露出来。
Pending 阶段的 Guided Learning 现在也不再空等 /api/knowledge/path 返回。如果当前工作区本地已经有可用 graph target 与 graph snapshot，workspace_panes.js 现在会先渲染 hosted Future Path 投影，同时保留 pending 状态提示，再等待后端结果补全 mastery/divergence/recommended-action 数据。
src/frontend/agent_workspace.js 现在会按归一化 request payload 对相同的 /api/knowledge/path 在途请求做 dedupe，避免对同一个 Learning Path 目标的重复点击生成并行重复 path build。
src/learning/graphContextAssembler.ts 现在会生成 additive 的 anchorGraphProfile，为当前 anchor 提供有界的 in-degree / out-degree / centrality 事实；predecessor/successor window 现在也会保留可选 degree metadata。
src/learning/conversationComposer.ts 不再把主公开回答固定成“第一条 direct sentence 或 title: summary”。现在只要有界 DAG context 确实能提升回答，它就会补一条 strongest-path 句子和一条紧凑 graph-profile 句子。
src/learning/answerReleaseReview.ts 现在也会在确定性 revise 路径中保留这种 richer 但仍受预算约束的 graph-aware 回答形态，而不再把 revised answer 折回成单个 top-hit snippet。
本地 ref/enterprise_agent_platform 与 ref/codex 现在进一步支撑当前 owner 切分：
enterprise_agent_platform 强化 runtime / retrieval / memory / evidence separation，
codex 强化 bounded model-visible context 与 additive context fragment，
两者都没有给出“把 DAG semantics 或 release review 挪进外部 framework runtime”的正当理由。

当前代码 / 先前方案对比结论：

要求	当前实现证据	进度判断	剩余风险
回退 Mermaid 渲染不应在已知畸形 bracketed-label 模式上崩溃	`MermaidProcessor.ts` 与 `reader_renderer.ts` 已按行归一化 stray quote；`src/notemd.core.test.ts` 与 `src/reader_renderer.test.ts` 固定回归。	已实现	如果未来导入链继续生成新的 malformed Mermaid 形态，应优先把修复前移到 source/diagram 生成层，而不是继续向 bridge 堆 heuristic。
首次打开 Learning Path 不应为同一图快照重复执行完整托管运行时重建	`workspace_panes.js` 现按 source-graph signature 缓存托管 Future Path runtime，`src/agent_workspace.frontend.test.ts` 验证同一图快照不会重复构造 nodes/edges。	已实现	大图下的真实首开时延仍需语料级量测；如果 live graph 数据会原地变异而不变更签名，缓存失效策略可能还需加强。
首次打开 Learning Path 时，应在后端路径请求完成前先展示有用的图结构引导	`workspace_panes.js` 现在会在 pending pane 中立即渲染 hosted Future Path 投影；`src/agent_workspace.frontend.test.ts` 现在验证 deferred `/api/knowledge/path` 响应尚未返回时，pending 状态与 hosted path surface 会同时出现。	已实现	后端请求仍然负责 mastery/divergence/recommended-action 数据，因此剩余工作是量测真实时延与继续调优后端路径，不是完全移除这条请求。
托管运行时复用应有真实 owner，并能给出冷/热路径证据	`hosted_future_path_runtime.js` 现在持有 runtime-cache 复用与诊断；`src/agent_workspace.frontend.test.ts` 现在同时验证同一快照热复用与签名变化后的重建。	已实现，属于局部 owner 缩减	这还只是仪表化和 owner 收紧，不等于已完成真实大语料时延研究。下一步仍需量测。
Learning Path 链路不应对相同在途请求重复打后端	`agent_workspace.js` 现在按归一化 payload 对 `/api/knowledge/path` 在途请求做 dedupe；`src/agent_workspace.frontend.test.ts` 现在验证相同目标重复打开时只会复用一条在途请求，且 pending pane 维持打开。	已实现	它减少了等待窗口内的重复工作，但不能替代大语料下的真实 cold-open 时延量测。
主公开回答应消费有界图上下文，而不是只释放 top-hit 首句	`graphContextAssembler.ts` 已提供 `anchorGraphProfile`，`conversationComposer.ts` 与 `answerReleaseReview.ts` 已在公开回答路径消费有界 path/degree context。	已实现	这仍然是“有界增强”，不是全图倾倒。剩余工作是回答组织校准，而不是默认增加回答体积。

2026-07-03 当日新鲜验证证据：

npm.cmd exec -- tsc --noEmit
npm.cmd exec -- jest src/learning/KnowledgeLearningPlatform.test.ts src/learning/KnowledgeWorkspaceConversationRegression.test.ts src/learning/conversationComposer.test.ts src/agent_workspace.frontend.test.ts src/notemd.core.test.ts src/reader_renderer.test.ts --runInBand --no-cache
npm.cmd run build:mini
node scripts/verify-knowledge-workspace-runtime.js --case waterglass_explicit_scope_compact_zh

2026-07-03 架构推进复审¶

这次复审不把 2026-07-03 切片当作孤立 bugfix，而是把它放回先前方案链中重新对比：

docs/brainstorms/2026-05-25-multiplatform-lightweight-rag-agent-architecture-plan.md
docs/brainstorms/2026-05-26-deep-student-comparison-next-phase-plan.md
docs/solutions/architecture-progress-alignment-2026-06-06.md
docs/solutions/knowledge-workspace-dag-alignment-2026-06-10.md
docs/solutions/agent-knowledge-dag-answer-contract-plan-2026-06-17.md
docs/solutions/agent-final-reply-review-robustness-plan-2026-06-18.md

当前对齐结论：

先前预期	当前代码证据	进度判断	后续方向
运行时应闭合 scope -> retrieval -> graph context -> answer -> review -> pane-backed evidence 全链路	`KnowledgeLearningPlatform.ts` 已归一化 `anchorGraphProfile` 等图上下文；`graphContextAssembler.ts` 装配有界 graph context；`conversationComposer.ts` 负责有界公开回答；`answerReleaseReview.ts` 继续作为确定性最终门禁；`workspace_panes.js` 持有 pane-backed evidence 与图投影。	基线已实现	后续继续收紧 owner 边界，但方式不是再引入一层框架，而是在本地大文件中围绕真实不变量缩 owner。
DAG 结构应参与回答规划，而不是只当浅层 retrieval bonus	`graphContextAssembler.ts` 现在会发射 `connectionPaths`、`anchorGraphProfile`、`predecessorWindow`、`successorWindow` 与 `evidenceSourceRefs`；`conversationComposer.ts` 与 `answerReleaseReview.ts` 已在公开回答路径消费有界 path/degree context。	更强基线已实现	先用真实语料校准回答组织，再决定是否增加更多图派生句子或权重。
RSE 风格 document augmentation 必须 evidence-backed 且保持有界	当前 `graphContext` 仍是 additive 且 budgeted；`evidenceSourceRefs`、显式路径窗口与 anchor 度数画像会增强回答路径，但不会把主回答面变成 trace dump。	有界基线已实现，尚非最终闭环	只在量化到真实检索/排序收益时再扩展，不通过增大 prompt 载荷来“堆增强”。
Hosted Guided Learning 应更流畅，但不能破坏 owner 边界	`workspace_panes.js` 现在按 source-graph signature 复用 hosted `Graph` / `PathEngine` runtime；`agent_workspace.js` 保留立即打开 pending pane 的交互。	已实现	先采集大语料下 cold-open / hot-reopen 证据，再决定是否修改缓存失效语义。
Hosted Guided Learning 的 cache identity 与 telemetry 不应继续作为 workspace-global mutable variable 漂浮在大文件里	`hosted_future_path_runtime.js` 现在持有 signature-based reuse、cache hit/miss/build counter 与 resolve/build timing；`workspace_panes.js` 通过该 owner 消费并暴露最后一次诊断快照。	已实现改进	其他大 owner 仍需类似原则推进；这只是先抽出一个真实不变量。
Guided Learning 在等待同一目标后端结果时不应浪费重复请求工作	`agent_workspace.js` 现在会对相同 `/api/knowledge/path` 在途调用做 dedupe，而且 pending pane 已能先显示本地 hosted projection。	已实现改进	最终闭环仍要求 representative large corpus 下的真实时延证据。
系统应吸收参考架构的分层经验，但不能把 runtime owner 外包给参考仓库	`ref/enterprise_agent_platform` 强化了 evidence / retrieval / runtime / review separation 与 RAG failure ledger；`ref/codex` 强化了 bounded model-visible context、additive fragment 与 hard context cap。	已吸收为设计输入	继续让本地 TypeScript owner 持有 DAG semantics、release review 与 pane 行为，不把它们委托给外部 orchestration stack。
主线架构压力应逐步下降，而不是继续堆大文件	当前行数压力仍高：`src/server.ts` 约 `15850`、`src/learning/KnowledgeLearningPlatform.ts` 约 `11200`、`src/frontend/workspace_panes.js` 约 `9289`、`src/frontend/agent_workspace.js` 约 `4882`、`src/learning/answerReleaseReview.ts` 约 `4261`；新引入的 `src/learning/graphContextAssembler.ts` 约 `792`，而新的 `src/frontend/hosted_future_path_runtime.js` 已开始承接 hosted Future Path cache/diagnostics 这一真实不变量。	有所改善，但仍落后	继续只在新模块能持有真实不变量时再做窄提取，例如 answer-boundary policy 或 provenance selection owner。

当前进展判断：

当前主缺口已经不再是“现有 DAG 有没有真正进入回答路径”，这一点现在已有代码闭环。
当前主缺口也不再是“Learning Path 能否复用 hosted runtime”，这一点现在已有代码闭环。
剩余主要风险仍是架构集中度过高，但本切片已开始用两类真实 owner 收紧来缓解它：一类是 hosted Future Path cache/diagnostics owner，另一类是 identical in-flight Learning Path request owner。
因此下一步正确动作是“校准 + 缩 owner”，而不是再做一轮宽泛 framework 对标。

最佳实践边界：

Mermaid 修复继续放在 source-fix 与 renderer-fallback owner 中，不要把语法自愈搬进 PathBridge。
托管 Future Path runtime 复用必须绑定到图快照身份 / 签名，不要升级成跨图共享的可变全局单例。
graph-aware public answer 继续保持有界；更丰富的图遥测仍属于 trace、pane、artifact 与 export surface。

完成边界¶

当前实现已经有代码证据：

src/learning/graphContextAssembler.ts 在回答合成前持有 graph-conditioned context assembly。
src/learning/conversationComposer.ts 调用 reviewAnswerRelease()，并发布 answerReleaseReview.publicAnswer。
src/learning/answerReleaseReview.ts 持有确定性公开回答门禁，包括 graph-causal、graph-order、graph-comparison、temporal-validity 与 query-intent 门禁。
src/frontend/workspace_panes.js 持有 Knowledge Workspace 的 source focus pane、帮助提示、命中文件 action、托管 Focus pane、pane-local Focus viewport 控件、有界 Focus history、托管 Godot Future Path 投影、pane-local node reader、关闭控件与 provenance 诊断。
src/frontend/godot_tree_interactions.js 持有托管 Future Path 的 TreeRenderer 风格输入信号适配：节点点击、可选 pane-local reader 请求、spine-only 右键 / 双击 prerequisite 展开收起回退、中键全部收起与长按导航；可展开判定重新对齐 Godot TreeRenderer，而不是扩展到非 spine prerequisite 节点。
scripts/verify-agent-workspace-browser.js 固定了最新 UI 缺陷的严格浏览器回归，包括 water glass.md 展示案例、托管 Focus anchor 必须为 water glass、Focus 语义标签、默认无密集 context 点、托管 Focus 不存在工具框 / 可见边线、Focus 滚轮缩放 / reset / history 行为、拒绝停靠主 #graph-container、live Path-mode expansion 状态继承、Future Path 双击在 pane 内打开 Markdown、water glass 右键后必须进入 collapsed 状态，以及默认拒绝显示 Godot 原生窗口。
src/agent_workspace.frontend.test.ts 固定 help popover、稳定 ARIA/control ID、source highlight、托管 Focus viewport/history 控件、pane-local Focus 双击语义、托管 Future Path pane-local node reader 行为与 path role 渲染。

剩余工作属于校准和覆盖扩展，不是本切片阻塞项：

旧 payload 缺少 source offset 时仍只能保守回退；
reviewer 只能在 false-positive 边界清晰时继续扩展矛盾族群；
Focus pane 复用 Focus-mode 行为契约，而不接管主图 DOM 生命周期；它通过现有 graph snapshot/resolve API 与 pane-local Markdown reader 渲染局部 Focus surface；
如果该 surface 后续持续变化，应继续把 strict browser UI gate 固化到 CI。

第一性原理¶

术语定义¶

公开回答：主回答区最终展示给用户的文本。它应直接回答问题，不应列出 citation、debug counter、graph trace 或 planner state。
次级证据 surface：pane、card、export、trace、diagnostic 等用于开发者或高级用户检查回答来源的区域。
现有 DAG：本项目由 note、atom、relation、prerequisite、next-step、reference、temporal edge 组成的有向无环知识结构。它不是泛化图数据库产品。
知识命中：agent workspace 查询返回的命中文档、概念、atom 或聚合 source。
源 provenance：让 UI 能打开原始 Markdown 并高亮支持片段的 path、line window、snippet 与可选 source offset。
Graph context pack：回答合成前装配出的有界图上下文，包含 anchor、support node、relation/path window、temporal warning、evidence ref 与 diagnostics。它不应该是整张图。
回答发布审核：draft answer 进入公开回答前的后置决策层，可以 release、revise 或 abstain。
托管 Focus pane：从现有 graph snapshot 与 node-resolution API 渲染隔离的 Focus-mode surface。它保留 Focus-mode 语义，同时不接管主图生命周期；pane 内双击要么切换 focus anchor，要么在 pane-local reader 中打开 Markdown。
托管 Godot Future Path 投影：将解析后的 DAG 节点送入现有前端 Graph / PathEngine 的 diffusion/core 路径，并把生成的 treeLayout 投影到引导式学习 pane。该 pane 刻意不挂载浏览器 #path-container，不调用 bridge/Tauri showGodot=true，也不要求 native window reparenting。
解析后的图标签：用于展示的人类可读节点名。报告中的失败点要求显示 water glass，而不是 atom_h 这类内部 atom ID。

各层连接¶

运行时应被理解为一串 owner：

Markdown source 层
持有持久源文本、文件名、标题与原始 snippet。
必要不变量：knowledge hit 必须能追溯到 canonical source path 或受控 fallback path。
Graph build 与 DAG 层
持有图节点、边、拓扑结构、predecessor/successor 语义与 graph-view 数据。
必要不变量：边方向必须有意义。用于学习引导的 prerequisite edge 不能被渲染成对称的 related edge。
Learning atom/relation 层
持有 KnowledgeAtom、RelationEdge、TemporalEdge、evidence span、scoped store operation 与 graph-path lookup。
必要不变量：answer-time graph structure 应来自 typed runtime data，而不是前端从展示字符串里反推。
Graph context assembly 层
持有给 LLM/composer 使用的有界图上下文选择。
必要不变量：graph pack 必须受 scope 约束、有预算、可解释。它应该提供高质量 DAG 结构，而不是整库倾倒。
Answer synthesis 层
持有基于 scoped retrieval 与 graph context 的 draft answer。
必要不变量：draft 可以使用 evidence 与 graph path，但公开回答只展示用户当前问题需要的内容。
Answer release review 层
持有最终发布策略。
必要不变量：unsupported、contradictory、temporally stale 或 diagnostic-leaking 的 draft 必须在进入主回答区前被改写或拒答。
前端 Knowledge Workspace 层
持有 discoverability、source reading、source highlighting、右侧 pane 生命周期与 graph preview。
必要不变量：UI 投影结构化状态，不从任意文本标签发明图语义。
验证层
持有回归证据。
必要不变量：理解后的失败类别必须可执行验证。单独截图不足以作为长期验收。

当前代码与先前要求对比¶

要求	当前实现证据	进度判断	剩余风险
公开回答应针对问题，不罗列所有命中项	`conversationComposer.ts` 发布 `answerReleaseReview.publicAnswer`；graph/evidence 细节留在 block、trace、pane、artifact 与 export 中。	已实现	后续 prompt 或 composer 变更可能重新撑大主回答。
开发者导向 evidence 与紫框类内容不应污染主区域	runtime 将 graph context、citation、`knowledgeRun`、reviewer state 放在次级 surface。	已实现	如果没有明确查看入口，有用证据可能变得不可发现。
命中文件需要明确提示左键可打开源文档并高亮依据	`workspace_panes.js` 使用紧凑问号帮助控件，而不是永久显示说明文字。	已实现	tooltip 必须保持键盘可访问，且不能回退成静态污染文案。
左侧命中文件区域要可滚动，并完整处理 `water glass.md` 这类长名称	strict browser verifier 检查 `water glass.md` 可见、无水平溢出、action target 可交互。	已实现	极长文件名仍要靠截断与 tooltip，而不是撑开布局。
单击命中项应打开右侧源文档并高亮命中依据	source pane 使用 source-line provenance、line window、snippet，并在可用时使用 offset-backed inline highlight。	已实现基线	旧 payload 没有 offset 时只能保守回退。
右侧打开窗口需要关闭按钮	strict browser verifier 检查相关右侧 pane surface 上有 3 个 close button。	已实现	后续新增 pane 不能绕开共享关闭控件模式。
`关联聚焦` 应对应 Tauri Focus mode 语义	`workspace_panes.js` 为解析后的节点托管 pane-local Focus-mode surface，保持主 `#graph-container` 留在原父节点，双击关联节点只切换 pane-local anchor，双击中心节点在 pane-local reader 内打开 Markdown；relation 诊断仅 Developer Mode 可见。	已实现	这是行为契约复用，不是 DOM 复用。未来如果要复用 live graph instance，必须先解决 reader 归属和主图生命周期隔离。
`学习路径` 应对应 Godot/Path mode 语义，并显示真实节点名称	`workspace_panes.js` 解析选中 DAG 节点后，复用现有前端 `Graph` / `PathEngine` 的 `diffusion/core` 与 `getTreeLayout(..., focusMode=true)` 托管 Godot Future Path 投影；strict verifier 检查 `water glass` label，并拒绝浏览器 `#path-container` 停靠和 bridge/Tauri `showGodot=true`。	已实现	这不嵌入 Godot 原生窗口。native window reparenting 是单独的平台 spike，不是 pane 功能。
现有 DAG 应进入 LLM 与 reviewer	`graphContextAssembler.ts` 装配 `connectionPaths`、predecessor/successor window、temporal validity、evidence ref 与 diagnostics；reviewer 图门禁消费 DAG context。	已实现基线	ranking 与 reviewer 校准仍需更广语料。
最终公开回答需要鲁棒审核与纠错	`answerReleaseReview.ts` 持有确定性 release gate，并在 response release 前执行。	已实现	gate 扩展必须保守，避免误报。
必须保持向前兼容	新字段 optional/additive；legacy `assistantMessage` 与既有 answer 字段继续有效。	已实现	如果新客户端把 optional 字段当 mandatory，contract drift 会复发。

为什么先前框架方案不是运行时答案¶

ref/ 下的参考项目有价值，但它们解决的是不同层：

参考	可借鉴模式	为什么不应持有本切片
DSPy	typed LM program、evaluation harness、optimizer loop。	可用于离线 prompt/reviewer 评估，但不应成为 TypeScript/Tauri runtime 中本地 DAG 不变量的事实源。
Guidance	constrained generation 与结构化输出控制。	它能约束生成文本，但不保证 source-pane provenance、graph-mode projection 或 release-worthiness。
Semantic Kernel	prompt function boundary、orchestration、telemetry 概念。	引入宽编排框架会复制本地 owner，并扩大集成面。
LangChain Core	runnable composition、parser boundary、observability 模式。	可作为设计参考，但不应替换本项目已有 learning runtime 与 graph context pack。
LiteLLM	provider routing 与 model-call normalization。	provider routing 与 DAG 正确性、source highlighting、最终回答审核是正交问题。

更好的方向是本地 owner 加可选外部评估：

图语义保留在 TypeScript 类型与 store operation 中；
release policy 保留在后端确定性 reviewer 中；
model framework 只有在有量化理由时才进入热路径；
参考库用于 evaluation，而不是替代不变量。

实施阶段与当前进度¶

P0：公开回答面收缩¶

状态：已完成。

主回答区现在接收经过 release review 的公开回答。citation list、graph path、temporal warning、reviewer detail 与 developer trace 保留在结构化 surface。这个边界是正确的：用户问的是问题，不是要看所有检索产物。

要避免的坑：不要用“把 evidence block 拼回公开回答”来修复答案稀疏。这会用另一种形状复现原始缺陷。

P1：DAG context assembly¶

状态：已完成基线。

graphContextAssembler.ts 是正确 owner，因为它位于 retrieval 与 synthesis 之间。它能在回答起草前看到 scoped candidates 与 graph operations。predecessor window、successor window、connection path、temporal validity 与 evidence ref 都应该在这里形成。

权衡：graph pack 是有界的。把整张图塞进 prompt 只会让延迟和混乱增长得比答案质量更快。

P2：最终回答发布审核¶

状态：已完成基线。

answerReleaseReview.ts 现在持有最终发布决策。它的价值不是“捕获所有语义错误”，而是公开回答正确性不再是 prompt 文本的偶然结果。

权衡：确定性 gate 比模型 verifier 窄，但可测试、低延迟、可审计。模型 verifier 未来可以作为 shadow signal，但前提是本地 gate contract 稳定。

P3：Source focus 与高亮 provenance¶

状态：已完成基线。

右侧 pane 会解析候选 source path、渲染 Markdown、选择最佳 evidence block，并投影 inline highlight。可用时优先使用 offset-backed provenance；line/snippet fallback 保持 legacy payload 可用。

要避免的坑：不要因为旧 payload 缺少 offset 就放宽 evidence gate。缺失 provenance 应可观测，而不是被静默当作正确。

P4：命中文件可发现性与工作区克制¶

状态：已完成。

命中文件区域现在有明确但紧凑的帮助入口。说明文案不会永久打印到 workspace 中。这符合产品要求：可发现，但不污染。

最佳实践：help control 必须支持 hover 与 focus，blur/outside interaction 后关闭，并保持稳定 ARIA 关系，避免 rerender 后 tooltip 变成孤儿节点。

P5：Focus runtime 与 Godot Future Path 复用¶

状态：已完成。

关联聚焦 在不移动主图 DOM 的前提下，将选中节点托管到 Knowledge Focus pane。该 pane 复用主图 getFocusModeProjection() 投影契约与 node-resolution 行为，渲染解析后的节点名，保留 Focus 语义标签，默认隐藏密集灰色背景 context 节点，并且不渲染主界面工具框和可见边线。它支持双击关联节点切换 anchor，并在双击中心节点时把 Markdown 打开到 pane-local reader。relation edge 列表、relation kind 与后端诊断只有 Developer Mode 开启时才显示。

学习路径 不显示 Tauri/browser Learning Path，也不挂载浏览器 path-container。它把选中命中解析为 DAG 节点后，复用现有前端 Graph / PathEngine，执行 diffusionLearning(target, 'core', completedSet, forcedExpansionSet) 与 getTreeLayout(..., collapsedSet, expansionOrder, stickyClaimEnabled, { verticalGap: 240 })，并在 live Path mode 的 target/mode/strategy 匹配时继承 completedIds、forcedExpansionIds、collapsedIds、expansionOrder 与 stickyClaimEnabled，让 pane 托管同一套 Godot Future Path 数据契约，而不是默认打开 Godot 原生窗口。最新右键修复落在状态机：用户显式收起当前 target 后，collapsed 状态必须跨过下一次 render，而不能被“target 默认展开”的初始化路径覆盖。

权衡：托管 Focus pane 避免右侧 pane 抢走 Tauri 主图生命周期，但必须显式保留用户期待的 Focus-mode 交互语义，同时不要把背景上下文层强塞进知识工作区。托管 Future Path 投影避免 native window reparenting，同时继续复用面向 Godot 的 treeLayout 契约与 Path-mode expansion 状态；如果后续要求像素级 Godot renderer 一致性，应独立做 renderer extraction 或 native embedding。

P6：回归与发布卫生¶

状态：本切片已完成。

当前回归面包括 Jest contract 与 strict browser verifier，后者覆盖了 water glass.md 的真实 UI 失败。这个点重要，因为最新问题不是抽象架构争论，而是 label、scrollability、affordance 与 pane lifecycle 的产品级错位。

测试与验证快照¶

当前主线已有新鲜验证证据：

npm run build
npm test -- --runInBand
npm run test:agent-workspace:contracts
npm exec -- tsc --noEmit
npm run build:vite
node --check scripts/verify-agent-workspace-browser.js
通过 scripts/verify-agent-workspace-browser.js 执行的 strict browser verification
output/agent-workspace-frontend-audit.* 下的 frontend law audit 证据

strict browser case 明确验证：

water glass.md 作为命中文件可见；
help text 隐藏在问号控件后，只有 hover/focus 时显示；
学习路径 与 关联聚焦 可交互；
action target 满足最小点击区域要求；
不存在水平溢出；
托管 Focus 对目标 water glass 使用主图投影数据与 Focus 语义标签，并默认不渲染密集灰色 context 点；
托管 Focus 不渲染工具框 / control frame，也不渲染可见边线；
托管 Godot Future Path 对目标 water glass 使用 diffusion/core、live Path-mode expansion 状态继承与 treeLayout；
Future Path 右键对初始展开的 water glass 发出 prerequisite collapse，并在 rerender 后保持该 target 位于 collapsed set；
浏览器 path-container 没有被停靠到 learning pane；
pane action 不调用 bridge/Tauri showGodot=true；
真实 #graph-container 保持在原父节点；
默认 关联聚焦 不展示 relation 诊断；只有 Developer Mode 才显示诊断；
右侧窗口具备关闭控件。

权衡¶

复用契约，而不是意外转移 ownership：Focus 复用 mode 行为但不移动主图 DOM，托管 pane 默认不渲染密集灰色背景 context 层；Future Path 复用 Graph / PathEngine / Godot treeLayout 契约和 Path-mode expansion 状态包，而不是默认打开或嵌入原生窗口。
先确定性 reviewer，后模型 verifier：语义覆盖更窄，但 release policy 稳定、可测试。
有界 DAG pack 优先于整图 prompt：上下文不完整，但延迟更低、幻觉面更小。
optional/additive 字段优先于强制 schema break：legacy 分支清理更慢，但保留现有客户端。
tooltip affordance 优先于静态说明文案：说明不是永远可见，但 workspace 更干净、信息密度更合理。

坑点¶

有人类可读图标签时仍渲染内部 atom ID。
把图数据库或 prompt framework 当作现有 DAG contract 的替代品。
因为 click affordance 弱，就把说明文案直接堆进 workspace。
在需求已明确为托管 Godot Future Path 契约复用后，又重新引入手写 Path preview、浏览器 Path 挂载或原生窗口显示副作用。
reviewer gate 扩展快于 false-positive 语料。
通过放宽高亮启发式来掩盖 provenance 缺失，让 UI 看起来正确。
新增只转发调用、不持有不变量的 facade。

后续推进方向¶

围绕真实用户失败扩展 answer-release contradiction corpus：alias drift、cross-scope leakage、same-subject relation swap、temporal drift 与 graph-direction reversal。
提高 legacy payload 的 source-offset 覆盖，让重复 snippet 更常能在不引入重 AST provenance 的情况下去歧义。
在提高 relation-weight bonus 前，用真实语料校准 graph-aware ranking。
只有当新模块持有真实不变量时才继续拆前端 owner，例如 graph-projection normalization 或 source-provenance selection。
如果 matched-file interaction 后续还会演进，应把 strict browser UI verification 持续保留在 CI。
只有当真实 graph mutation 路径证明 source-graph signature 复用不足时，才继续增加托管 Future Path runtime-cache invalidation 机制。
在进入更深的前端性能工作前，先量化 representative large corpus 下 Guided Learning 的 first-open 与 hot-reopen 时延。
继续把 graph-aware public-answer 路径保持为“有界 RSE 式增强”：使用 anchor、path 与 degree context 提升回答，但不要把主回答面改成 graph-inspection surface。

思维模型¶

改动这个区域时先问三个问题：

公开回答允许说什么？
由 answer synthesis 与 release review 持有。
哪些 evidence 与 graph structure 产生了这个回答？
由 graph context assembly、trace、artifact、pane 与 export 持有。
用户如何检查支撑源文档或图上下文？
由 source focus、matched-file control、托管 Focus 行为与托管 Godot Future Path 投影持有。

不要把这三个问题压进一个 prompt 或一个前端组件。它们的不变量不同，失败模式也不同。

真实应用¶

用户问 什么是waterglass?：公开回答应直接定义概念；命中文件应显示 water glass.md；单击后打开 Markdown 并高亮依据。
用户想学习选中节点：学习路径 应为选中 DAG 节点托管 Godot Future Path 的 diffusion/core/treeLayout 投影，并保持 water glass 这类可见节点 label。
用户想理解关系上下文：关联聚焦 应在 Knowledge Focus pane 内提供同一套 Focus-mode 交互模型，而不是抢走主图 DOM 或把 Markdown 打开到全局 reader。
开发者审计可疑回答：reviewer result、graph context、citation 与 provenance diagnostics 应在次级 surface 可见，而不污染公开回答。

常见误区¶

“UI 有图按钮，所以 LLM 已经 graph-native。”
错。graph-native answer planning 要求 synthesis 前有 graph context，release 前有 graph gate。
“回答简洁，所以回答正确。”
错。简洁与正确是两个不变量。
“prompt framework 能解决最终回答审核。”
不完整。它能改善 draft，但 release policy 仍需要本地 owner。
“右侧 Path/Focus 必须嵌入真实 Godot/Tauri 窗口。”
这个说法过宽。Focus 必须在 pane 内保留 Focus-mode 行为，但移动主图 DOM 会破坏 ownership。Future Path 当前通过 treeLayout 复用 Godot 数据契约；DOM/native 嵌入需要单独做 renderer extraction 或 native window reparenting。
“高亮大致落在正确段落附近就够了。”
对重复 snippet 不够。offset 或 AST provenance 才是耐久修复。

五点总结¶

正确架构是本地 DAG -> 有界 graph context -> answer synthesis -> 确定性 release review -> 次级 evidence surface。
最新 UI 切片已复用真实契约：命中文件可发现、可点击，source highlight 生效，Focus 以 pane-local 交互托管且无工具框 / 边线污染，Learning Path 托管 Godot Future Path treeLayout 投影并支持右键收起当前 target，标签保持人类可读，右侧 pane 可关闭。
先前 DSPy/Guidance/Semantic Kernel/LangChain/LiteLLM 方案仍有参考价值，但不应在本 runtime 中持有 DAG 语义、source provenance 或最终 release policy。
主要剩余风险是校准，不是 owner 缺失：更广 reviewer 语料、更多 offset 覆盖与 ranking evaluation 是下一步硬工作。
后续变更必须保持向前兼容，并由真实不变量驱动；避免 pass-through layer、无界图倾倒和 UI-only correctness fix。

2026-06-22 交互契约补充¶

本次补充收口的是最新反馈中的真实交互缺口。上一版右侧 pane 能证明 Focus/Future Path 风格 surface 存在，但仍不足以证明它复用了可执行的交互契约；这就是“看起来像，但左键、右键、双击不可用”的根因。

已落地的变化：

Focus 双击行为现在由 src/frontend/focus_mode_interactions.js 持有，并同时被 src/frontend/app.js 与托管 Knowledge Focus pane 使用。
托管 Focus 仍然保持 pane-local：双击关联节点只切换托管 anchor，双击中心节点只打开 pane 内 Markdown reader，不移动主图 DOM，也不调用全局 reader.open；托管视图同时验证无 Layout 工具框、无可见边线、默认无密集灰色 context 点，并保留 Focus 语义标签。
Godot Future Path 的输入现在由 src/frontend/godot_tree_interactions.js 适配为 TreeRenderer 信号，而不是继续散落在临时 DOM handler 中。
托管 Future Path 现在记录并验证 Godot 风格信号：node_clicked、前置节点展开 / 折叠、collapse_all_requested；water glass 右键收起现在验证 collapsed 状态，而不只验证信号被发出。
托管 Future Path 现在会在重新计算 pane-local treeLayout 前继承匹配 live Path mode 的状态包（completedIds、forcedExpansionIds、collapsedIds、expansionOrder、stickyClaimEnabled），这是主干节点子树数与原生 Future Path 流程对齐的关键。
strict browser verification 现在会在 water glass 的 Focus/Future Path pane 只是可见但不可交互时失败。

保留的边界也必须写清楚：当前复用的是契约与 renderer 语义，不是把 Godot 原生窗口嵌入 DOM。真正的 native window docking 需要单独的平台级 owner 处理窗口父子关系、输入焦点、销毁顺序与 reader 路由，不能混入当前 Knowledge Workspace pane 修复。