Architecture Map

主执行链

Renderer / user action
        ↓
Coordinator
  └─ provider routing / local transcript / MCP bridge
        ↓
Host Runner
  ├─ create Turn-owned context
  ├─ assemble model-visible context
  ├─ stream model/tool execution
  ├─ record observations
  └─ settle + persist
        ↓
Storage / Memory / Trace / Workspace

层	文件	Symbol	读源码时关注什么
Turn scope	source/host/runner/turn-run-shell.ts	createTurnAgentRunContext()	provider session、privacy、tool session、scope、cleanup owner 在何时固定
Context	source/host/runner/system-prompt-assembly.ts	createSystemPromptAssembly() / getSystemPrompt()	Runtime facts 如何变成 model-visible sections
Observation	source/host/runner/turn-observation.ts	createTurnObservation()	tool / await / background / TTFT 如何变成结构化事实
Settlement	source/host/runner/turn-settle.ts	persistCheckpoint() / settleCompletedTurn()	checkpoint 与 transcript 的提交顺序、Turn 后处理
Approval	source/host/runner/auto-review-gate.ts	assertNoPendingApproval() / shellApprovalState()	side effect 为什么必须经过 Runtime Gate
Memory	source/host/runner/turn-memory.ts	runTurnMemory() / runMemoryExtraction()	maintenance path 与 user-visible turn 如何隔离
Routing	source/node-agent-coordinator/inference-router.ts	createCoordinatorInferenceRouter() / execute() / dispatch()	provider 差异、per-agent queue、direct tools vs MCP bridge
MCP	source/node-agent-coordinator/routed-mcp-bridge.ts	createRoutedMcpBridge() / mcpResult()	protocol request 如何投影到 internal tool

最值得先追的一条调用链

createTurnAgentRunContext()
  ↓
getSystemPrompt()
  ↓
model / tool stream
  ↓
toolStarted() / toolCompleted()
  ↓
persistStepCheckpoint()
  ↓
settleCompletedTurn()
  ↓
persistFinalState()
  ↓
runTurnMemory()   // maintenance path

这条链足以把 Context、Tool、Observation、Checkpoint、Memory 五个抽象放到同一个 Runtime 生命周期里理解。

固定源码

• turn-run-shell.ts
• system-prompt-assembly.ts
• turn-observation.ts
• turn-settle.ts