本文档汇总当前项目中所有会出现的 metadata 约定，供前端图谱解析、运行态展示和调试使用。
来源：
core/policy.pyagents/<swarm>/graph.py
图节点的 metadata 是一个自由字典，但当前已有的语义字段主要有：
- 类型：
string - 典型值：
"all""first"
- 语义：
"all"表示从当前节点分叉后，所有后继节点都应执行"first"或缺省表示按默认顺序执行第一个后继
- 类型：
int - 语义：
- 表示并行分支执行后的汇合节点
- 当前 demo 中常用于从分叉源节点回到审查/汇总节点
节点 metadata 仍然允许继续扩展，前端应保留未知字段并原样展示。
- 类型：
bool - 语义：
- 表示该节点是运行时临时节点
- 允许 runtime 在临时 agent 已删除、但对应节点尚未移除时，把它视为可接受的过渡态
- 这是兼容字段；新实现更推荐使用
node_lifecycle
- 类型：
string - 典型值：
"transient""persistent"
- 语义：
transient表示临时节点，用完即弃persistent表示持久节点，直到被显式删除、禁用、替换或回滚
- 类型：
string - 典型值：
"run""session""swarm""manual"
- 语义：
- 描述节点的生命周期边界
run通常对应一次性节点manual通常对应长期保留节点
- 类型：
object - 语义：
- 结构化生命周期字段
- 当前推荐包含：
runtime_transientpersistencelifetime_policy
- 前端和调试工具应优先展示该对象，而不是只看单个布尔值
来源：
core/results.pycore/executor.py
运行状态里的 metadata 会随着执行过程变化。当前已知字段包括：
- 类型：
int - 语义：
- 当前分支编号
- 用于在并行执行时区分不同分支
- 类型：
int - 语义：
- 分支来源节点 id
- 表示该分支从哪个节点 fork 出来
- 工具可继续写入新的执行上下文信息
- 前端应把未知字段展示为原始 JSON
- 类型：
array[string]或string - 语义：
- 指示执行器从
state.metadata删除哪些旧控制键 - 适合 cleanup 场景清理
next_node_id、spawned_agent_*等残留值
- 指示执行器从
来源：
core/agent.py
每个 agent 维护独立上下文，metadata 当前已知字段：
- 类型：
int - 语义：
- 最近一次 round 调用的轮次编号
- 类型：
int - 语义：
- 该 agent 当前上下文中所有消息的条数
- 包括 active window 中的消息，以及所有 compressed blocks 中归档的原始消息
- 计算公式：
len(active_messages) + sum(len(b.archived_messages) for b in compressed_blocks)
- 类型：运行时内部结构，不直接暴露在 metadata 中
- 语义：
ManagedAgentContext维护的压缩块列表- 每条压缩块包含
summary、keywords、participants和归档的完整messages - 通过
recall_context工具可按查询召回归档内容
- 来源：
node.completed事件的data.llm_input - 语义：
- 仅对
AgentNode存在 - 记录该节点实际发送给 LLM 的完整输入：
systemprompt、usermessage、prev_messages、绑定的tools - 是调试和审计 agent 行为的核心证据
- 详见 事件流协议
- 仅对
- 可继续扩展记忆摘要、内部状态、临时标记等
- 不同 agent 之间不共享
来源：
core/toodefl.pycore/executor.py
工具接收到的 metadata 是当前执行状态的一个拷贝，工具可读取并在执行逻辑中据此决定行为。
- 代表工具执行时的上下文
- 通常来自
ExecutionState.metadata - 可用于图编辑、状态写入、调试记录
来源：
core/skills.py
skill asset 会把 contract 结构扁平化到 metadata 中。当前字段包括：
- 类型：
string - 语义：
- skill contract 版本号
- 类型：
string - 语义：
- 该 skill 的能力名称或职责标签
- 类型：
string - 语义：
- skill 的文字说明
- 类型：
object - 语义：
- 该 skill 可接受的输入结构
- 类型：
object - 语义：
- 该 skill 期望输出的结构
- 类型：
array[string] - 语义：
- 执行该 skill 时所需工具
- 类型：
array[string] - 语义：
- 执行该 skill 时所依赖的其他 skill
- 类型：
array[string] - 语义：
- 该 skill 的前置条件
- 类型：
array[string] - 语义：
- 该 skill 的后置条件
- 类型：
string - 典型值：
"retry"- 其他自定义策略
- 语义：
- skill 失败时的处理策略
- 类型：
bool - 语义：
- 该 skill 是否允许并行执行
前端在解析图谱时应遵守以下原则：
- 保留所有原始 metadata
- 不要丢弃未知字段
route_policy和join_node_id应作为图语义增强项branch_index和branch_source_node_id应作为运行态分组信息- skill metadata 应显示在节点详情或能力详情面板
- 结构连接以
edges为准，语义提示以metadata为准
- 基础信息：
node_id、node_name、node_type - 语义标签：
entry、exit、branch_source、join_target - 元信息：
metadata折叠显示
- 当前
run_id - 当前
current_node_id branch_indexbranch_source_node_idrounds- 实时事件流
capabilitydescriptioninput_schemaoutput_schemarequires_toolsrequires_skillsfailure_policyparallelizable