ZCode Agent 核心运行时

ZCode CLI 的 Agent 核心位于 apps/zcode-cli/packages/core。它负责”一轮工作如何执行”，与负责”多轮产品状态如何接纳、持久化、投影与恢复”的 session-runtime 是两条独立边界。

AgentRuntime 装配

真正的 AgentRuntime 在 core/src/runtime/agent-runtime.ts:145（runtime.ts 只是 barrel）。构造函数冻结：

session ID、model config
tool registry / executor
event store / reducer
trace context
MCP、memory、subagent、workflow ports

随后通过 installAgentRuntimeMethods(AgentRuntime)（agent-runtime.ts:720）把大量方法动态装到 prototype 上（methods/index.ts:201）。

这是为控制单文件行数（架构策略 maxFileLines: 400）而做的拆分，但代价是 Runtime 的静态可读性与可测试性偏弱——是本仓库已知的维护风险点。

Turn 执行序列

Turn 入口是 executeTurn，先入 runtime command queue，再由 executeTurnCommand 执行：

冻结本轮 model selection / output style
创建 turnId / queryId / traceId
初始化 context
执行 SessionStart / UserPromptSubmit hooks
持久化 user message
发布 TurnStarted
进入 regular turn loop

见 core/src/runtime/methods/turn.ts:81。

Turn 状态机

core/src/agent/turn-state.ts:25 定义状态流转：

processing_input
  → awaiting_model_response
  → streaming
  → scheduling_tools
  → executing_tools / awaiting_permission
  → aggregating_results
  → completing

Turn Loop（每轮）

core/src/runtime/methods/turn-loop.ts:44 的每轮顺序：

取消检查
runtime command / steering drain
microcompact
auto compact
MCP 初始化与工具刷新
plan / TODO / output-style reminder 注入
provider message projection
调用 model step

Model Step

core/src/runtime/methods/turn-model-step.ts:139：

持久化 assistant / step-start
发布 ModelRequest
调用 runModelTextRequest
记录 reasoning / text / tool parts
发布 ModelComplete
处理 output-limit continuation、context overflow、stream recovery、model fallback 和 tool batch

core/src/runtime/methods/model.ts:35 的 runModelTextRequest 做媒体能力/预算投影、上下文 usage 统计与 provider invocation context，再选择 generateText 或 streamText；流事件统一转换为 start/text/reasoning/tool/finish/error 并进入 session event queue。

Streaming 工具协调

只有同时满足 readOnly && concurrentSafe && !destructive && !needsApproval && sideEffectScope=none 的工具才会边流边执行；其他工具等完整 model result 后进入 scheduler。见 core/src/runtime/methods/streaming-tool-coordinator.ts:360。工具契约见 tool-system。

上下文构建与压缩

ContextBuilder

core/src/context/builder.ts:83 把上下文拆成明确 section，映射到 system 或 meta-user attachment：

稳定身份、动态行为、memory、env、Git、skills、AGENTS.md、日期等

Compact 策略

core/src/compact/policy.ts:67：按 context window 扣 output reserve，再留 13K buffer 作为 compact 阈值依据。

会话恢复（Resume）

Resume 不是简单读 DB。core/src/runtime/methods/resume.ts:61 会：

修复路径、恢复 shell
重建 Context / MessageHistory / read-file state
选择 rewind branch
恢复 compact / checkpoint / goal / permission
发布 SessionResumed 和 SessionStart hooks

冷恢复事实源是 SQLite transcript/entries；live/replay 顺序事实源是 session event；面向客户端的可重建视图是 ProductProjection。详见 session-runtime。

与模型层的关系

Agent Core 通过 provider message projection 与 provider invocation context 调用模型层；模型选择的校验与 Model 创建由 Provider Registry + AiSdkModelAdapter 负责（见 model-provider）。Provider 事实在 Model 创建时冻结，请求期只允许动态刷新凭据/header。

维护风险与偏差

本 wiki 分析：上游 V2 架构文档声称 core 只依赖 contracts、不得直接 I/O；实际 core/package.json 依赖 shared / dynamic-workflow / zcode-cua，且 subagent runner、memory/dream、saved workflows、workflow drafts 等直接使用 node:fs（如 core/src/subagent/runner.ts:44）。现有 core/tests/io-boundary.test.ts 只抽查少数路径，不能证明全局纯 core。此外 AgentRuntime 大对象 + prototype 动态安装也是可读性风险。

Wiki AI

目录