Deep Dive

Data Structure Map

This document is not available in the current locale. Showing fallback: zh

When This Page Helps

Every important record in one place. Use when you lose track of where state lives.

Best Read Alongside

s03 · TodoWrite s06 · Context Compact s09 · Memory System s12 · Task System s13 · Background Tasks s18 · Worktree Isolation

学习 agent，最容易迷路的地方不是功能太多，而是不知道“状态到底放在哪”。这份文档把主线章节和桥接章节里反复出现的关键数据结构集中列出来，方便你把整套系统看成一张图。

先记住两个总原则

原则 1：区分“内容状态”和“流程状态”

messages、tool_result、memory 正文，属于内容状态。
turn_count、transition、pending_classifier_check，属于流程状态。

很多初学者会把这两类状态混在一起。
一混，后面就很难看懂为什么一个结构完整的系统会需要控制平面。

原则 2：区分“持久状态”和“运行时状态”

task、memory、schedule 这类状态，通常会落盘，跨会话存在。
runtime task、当前 permission decision、当前 MCP connection 这类状态，通常只在系统运行时活着。

1. 查询与对话控制状态

Message

作用：保存当前对话和工具往返历史。

最小形状：

message = {
    "role": "user" | "assistant",
    "content": "...",
}

支持工具调用后，content 常常不再只是字符串，而会变成块列表，其中可能包含：

text block
tool_use
tool_result

相关章节：

s01
s02
s06
s10

NormalizedMessage

作用：把不同来源的消息整理成统一、稳定、可送给模型 API 的消息格式。

最小形状：

message = {
    "role": "user" | "assistant",
    "content": [
        {"type": "text", "text": "..."},
    ],
}

它和普通 Message 的区别是：

Message 偏“系统内部记录”
NormalizedMessage 偏“准备发给模型之前的统一输入”

相关章节：

s10
s10a-message-prompt-pipeline.md

CompactSummary

作用：上下文太长时，用摘要替代旧消息原文。

最小形状：

summary = {
    "task_overview": "...",
    "current_state": "...",
    "key_decisions": ["..."],
    "next_steps": ["..."],
}

相关章节：

s06
s11

SystemPromptBlock

作用：把 system prompt 从一整段大字符串，拆成若干可管理片段。

最小形状：

block = {
    "text": "...",
    "cache_scope": None,
}

你可以把它理解成：

text：这一段提示词正文
cache_scope：这一段是否可以复用缓存

相关章节：

s10
s10a-message-prompt-pipeline.md

PromptParts

作用：在真正拼成 system prompt 之前，先把各部分拆开管理。

最小形状：

parts = {
    "core": "...",
    "tools": "...",
    "skills": "...",
    "memory": "...",
    "claude_md": "...",
    "dynamic": "...",
}

相关章节：

s10

QueryParams

作用：进入查询主循环时，外部一次性传进来的输入集合。

最小形状：

params = {
    "messages": [...],
    "system_prompt": "...",
    "user_context": {...},
    "system_context": {...},
    "tool_use_context": {...},
    "fallback_model": None,
    "max_output_tokens_override": None,
    "max_turns": None,
}

它的重要点在于：

这是“本次 query 的入口输入”
它和循环内部不断变化的状态，不是同一层

相关章节：

s00a-query-control-plane.md

QueryState

作用：保存一条 query 在多轮循环之间不断变化的流程状态。

最小形状：

state = {
    "messages": [...],
    "tool_use_context": {...},
    "turn_count": 1,
    "max_output_tokens_recovery_count": 0,
    "has_attempted_reactive_compact": False,
    "max_output_tokens_override": None,
    "pending_tool_use_summary": None,
    "stop_hook_active": False,
    "transition": None,
}

这类字段的共同特点是：

它们不是对话内容
它们是“这一轮该怎么继续”的控制状态

相关章节：

s00a-query-control-plane.md
s11

TransitionReason

作用：记录“上一轮为什么继续了，而不是结束”。

最小形状：

transition = {
    "reason": "next_turn",
}

在更完整的 query 状态里，这个 reason 常见会有这些类型：

next_turn
reactive_compact_retry
token_budget_continuation
max_output_tokens_recovery
stop_hook_continuation

它的价值不是炫技，而是让：

日志更清楚
测试更清楚
恢复链路更清楚

相关章节：

s00a-query-control-plane.md
s11

2. 工具、权限与 hook 执行状态

ToolSpec

作用：告诉模型“有哪些工具、每个工具要什么输入”。

最小形状：

tool = {
    "name": "read_file",
    "description": "Read file contents.",
    "input_schema": {...},
}

相关章节：

s02
s19

ToolDispatchMap

作用：把工具名映射到真实执行函数。

最小形状：

handlers = {
    "read_file": run_read,
    "write_file": run_write,
    "bash": run_bash,
}

相关章节：

s02

ToolUseContext

作用：把工具运行时需要的共享环境打成一个总线。

最小形状：

tool_use_context = {
    "tools": handlers,
    "permission_context": {...},
    "mcp_clients": [],
    "messages": [...],
    "app_state": {...},
    "cwd": "...",
    "read_file_state": {...},
    "notifications": [],
}

这层很关键。
因为在更完整的工具执行环境里，工具拿到的不只是 tool_input，还包括：

当前权限环境
当前消息
当前 app state
当前 MCP client
当前文件读取缓存

相关章节：

PermissionRule

作用：描述某类工具调用命中后该怎么处理。

最小形状：

rule = {
    "tool_name": "bash",
    "rule_content": "rm -rf *",
    "behavior": "deny",
}

相关章节：

s07

PermissionRuleSource

作用：标记一条权限规则是从哪里来的。

最小形状：

source = (
    "userSettings"
    | "projectSettings"
    | "localSettings"
    | "flagSettings"
    | "policySettings"
    | "cliArg"
    | "command"
    | "session"
)

这个结构的意义是：

你不只知道“有什么规则”
还知道“这条规则是谁加进来的”

相关章节：

s07

PermissionDecision

作用：表示一次工具调用当前该允许、拒绝还是提问。

最小形状：

decision = {
    "behavior": "allow" | "deny" | "ask",
    "reason": "matched deny rule",
}

在更完整的权限流里，ask 结果还可能带：

修改后的输入
建议写回哪些规则更新
一个后台自动分类检查

相关章节：

s07

PermissionUpdate

作用：描述“这次权限确认之后，要把什么改回配置里”。

最小形状：

update = {
    "type": "addRules" | "removeRules" | "setMode" | "addDirectories",
    "destination": "userSettings" | "projectSettings" | "localSettings" | "session",
    "rules": [],
}

它解决的是一个很容易被漏掉的问题：

用户这次点了“允许”，到底只是这一次放行，还是要写回会话、项目，甚至用户级配置。

相关章节：

s07

HookContext

作用：把某个 hook 事件发生时的上下文打包给外部脚本。

最小形状：

context = {
    "event": "PreToolUse",
    "tool_name": "bash",
    "tool_input": {...},
    "tool_result": "...",
}

相关章节：

s08

RecoveryState

作用：记录恢复流程已经尝试到哪里。

最小形状：

state = {
    "continuation_attempts": 0,
    "compact_attempts": 0,
    "transport_attempts": 0,
}

相关章节：

s11

3. 持久化工作状态

TodoItem

作用：当前会话里的轻量计划项。

最小形状：

todo = {
    "content": "Read parser.py",
    "status": "pending" | "completed",
}

相关章节：

s03

MemoryEntry

作用：保存跨会话仍然有价值的信息。

最小形状：

memory = {
    "name": "prefer_tabs",
    "description": "User prefers tabs for indentation",
    "type": "user" | "feedback" | "project" | "reference",
    "scope": "private" | "team",
    "body": "...",
}

这里最重要的不是字段多，而是边界清楚：

只存不容易从当前项目状态重新推出来的东西
记忆可能会过时，要验证

相关章节：

s09

TaskRecord

作用：磁盘上的工作图任务节点。

最小形状：

task = {
    "id": 12,
    "subject": "Implement auth module",
    "description": "",
    "status": "pending",
    "blockedBy": [],
    "blocks": [],
    "owner": "",
    "worktree": "",
}

重点字段：

blockedBy：谁挡着我
blocks：我挡着谁
owner：谁认领了
worktree：在哪个隔离目录里做

相关章节：

s12
s17
s18
s13a-runtime-task-model.md

ScheduleRecord

作用：记录未来要触发的调度任务。

最小形状：

schedule = {
    "id": "job_001",
    "cron": "0 9 * * 1",
    "prompt": "Generate weekly report",
    "recurring": True,
    "durable": True,
    "created_at": 1710000000.0,
    "last_fired_at": None,
}

相关章节：

s14

4. 运行时执行状态

RuntimeTaskState

作用：表示系统里一个“正在运行的执行单元”。

最小形状：

runtime_task = {
    "id": "b8k2m1qz",
    "type": "local_bash",
    "status": "running",
    "description": "Run pytest",
    "start_time": 1710000000.0,
    "end_time": None,
    "output_file": ".task_outputs/b8k2m1qz.txt",
    "notified": False,
}

这和 TaskRecord 不是一回事：

TaskRecord 管工作目标
RuntimeTaskState 管当前执行槽位

相关章节：

s13
s13a-runtime-task-model.md

TeamMember

作用：记录一个持久队友是谁、在做什么。

最小形状：

member = {
    "name": "alice",
    "role": "coder",
    "status": "idle",
}

相关章节：

s15
s17

MessageEnvelope

作用：队友之间传递结构化消息。

最小形状：

message = {
    "type": "message" | "shutdown_request" | "plan_approval",
    "from": "lead",
    "to": "alice",
    "request_id": "req_001",
    "content": "...",
    "payload": {},
    "timestamp": 1710000000.0,
}

相关章节：

s15
s16

RequestRecord

作用：追踪一个协议请求当前走到哪里。

最小形状：

request = {
    "request_id": "req_001",
    "kind": "shutdown" | "plan_review",
    "status": "pending" | "approved" | "rejected" | "expired",
    "from": "lead",
    "to": "alice",
}

相关章节：

s16

WorktreeRecord

作用：记录一个任务绑定的隔离工作目录。

最小形状：

worktree = {
    "name": "auth-refactor",
    "path": ".worktrees/auth-refactor",
    "branch": "wt/auth-refactor",
    "task_id": 12,
    "status": "active",
}

相关章节：

s18

WorktreeEvent

作用：记录 worktree 生命周期事件，便于恢复和排查。

最小形状：

event = {
    "event": "worktree.create.after",
    "task_id": 12,
    "worktree": "auth-refactor",
    "ts": 1710000000.0,
}

相关章节：

s18

5. 外部平台与 MCP 状态

ScopedMcpServerConfig

作用：描述一个 MCP server 应该如何连接，以及它的配置来自哪个作用域。

最小形状：

config = {
    "name": "postgres",
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "..."],
    "scope": "project",
}

这个 scope 很重要，因为 server 配置可能来自：

本地
用户
项目
动态注入
插件或托管来源

相关章节：

MCPServerConnectionState

作用：表示一个 MCP server 当前连到了哪一步。

最小形状：

server_state = {
    "name": "postgres",
    "type": "connected",   # pending / failed / needs-auth / disabled
    "config": {...},
}

这层特别重要，因为“有没有接上”不是布尔值，而是多种状态：

connected
pending
failed
needs-auth
disabled

相关章节：

s19
s19a-mcp-capability-layers.md

MCPToolSpec

作用：把外部 MCP 工具转换成 agent 内部统一工具定义。

最小形状：

mcp_tool = {
    "name": "mcp__postgres__query",
    "description": "Run a SQL query",
    "input_schema": {...},
}

相关章节：

s19

ElicitationRequest

作用：表示 MCP server 反过来向用户请求额外输入。

最小形状：

request = {
    "server_name": "some-server",
    "message": "Please provide additional input",
    "requested_schema": {...},
}

它提醒你一件事：

MCP 不只是“模型主动调工具”
外部 server 也可能反过来请求补充输入

相关章节：

s19a-mcp-capability-layers.md

最后用一句话把它们串起来

如果你只想记一条总线索，可以记这个：

messages / prompt / query state
  管本轮输入和继续理由

tools / permissions / hooks
  管动作怎么安全执行

memory / task / schedule
  管跨轮、跨会话的持久工作

runtime task / team / worktree
  管当前执行车道

mcp
  管系统怎样向外接能力

这份总表最好配合 s00-architecture-overview.md 和 entity-map.md 一起看。

教学边界

这份总表只负责做两件事：

帮你确认一个状态到底属于哪一层
帮你确认这个状态大概长什么样

它不负责穷举真实系统里的每一个字段、每一条兼容分支、每一种产品化补丁。

如果你已经知道某个状态归谁管、什么时候创建、什么时候销毁，再回到对应章节看执行路径，理解会顺很多。

推荐联读

先记住两个总原则

原则 1：区分“内容状态”和“流程状态”

原则 2：区分“持久状态”和“运行时状态”

1. 查询与对话控制状态

Message

NormalizedMessage

CompactSummary

SystemPromptBlock

PromptParts

QueryParams

QueryState

TransitionReason

2. 工具、权限与 hook 执行状态

ToolSpec

ToolDispatchMap

ToolUseContext

PermissionRule

PermissionRuleSource

PermissionDecision

PermissionUpdate

HookContext

RecoveryState

3. 持久化工作状态

TodoItem

MemoryEntry

TaskRecord

ScheduleRecord

4. 运行时执行状态

RuntimeTaskState

TeamMember

MessageEnvelope

RequestRecord

WorktreeRecord

WorktreeEvent

5. 外部平台与 MCP 状态

ScopedMcpServerConfig

MCPServerConnectionState

MCPToolSpec

ElicitationRequest

最后用一句话把它们串起来

教学边界