#Trace Index 设计原则

Trace Index 是什么 已经确定了产品的基本分工。Trace Index 位于 Agent 生产 Trace 和再次消费 Trace 之间，负责组织和索引事实。Agent 根据当前问题检索事实、形成解释并采取行动。

设计原则要解决的是下一层问题。当事实覆盖、解释准确性、查询成本、实现复杂度和使用便利发生冲突时，Trace Index 应该怎样选择？

这些原则不是当前实现特征的总结。它们约束领域模型和总体架构，也为未来新增 Runtime、事实类型和查询能力提供裁决依据。

#Agent 是第一使用者

Agent 既是 Trace 的生产者，也是 Trace 的最佳消费者。Trace Index 因而不是一个先为人设计、再补充机器调用入口的工具。它从事实模型到使用界面，都把 Agent 能否自主完成调查作为首要使用者约束。

“第一使用者”不等于“唯一使用者”。人类协作者仍然需要阅读、检查和纠正 Trace Index 的结果，但面向人的呈现与面向 Agent 的接口应当建立在同一套事实和字段定义之上。核心能力不能依赖只有人才能理解的界面位置、隐含约定或未公开背景。

Agent Friendly 也不只是让调用更短。Agent 应当能够发现系统提供什么，理解字段、边界和副作用，组合多次读取，识别失败与不完整，沿稳定身份继续任务，并在需要时验证来源。这些能力共同决定 Agent 能否独立、可靠地使用 Trace Index。

Agent 的阅读、检索和比较速度远高于人工翻阅，但单次任务的上下文仍然有限。因此，Trace Index 提供可发现、可组合、可逐步收窄的事实空间。Agent 可以先发现范围，再定位候选，读取结构和有界事实，展开必要上下文，最后在需要时沿溯源路径验证原始 Trace。

当人类操作习惯、实现便利和 Agent 自主使用发生冲突时，Trace Index 优先保证 Agent 能够发现能力、理解边界、组合事实、判断不完整并继续行动。

#索引事实，而不是预写结论

Trace 中的信息之所以具有长期价值，正是因为未来会提出什么问题无法预知。同一条用户修正、工具失败或废弃路径，在一次任务中可能只是背景，在另一次任务中却可能成为恢复决定、诊断问题或比较系统的关键证据。

Trace Index 在索引时主要回答两类问题：这里记录了什么事实，以及这些事实之间存在什么可以由来源确定的关系。它不在写入时替未来的 Agent 决定哪些内容重要，也不把针对当前问题形成的摘要固化成所有问题共同依赖的历史底座。

摘要、记忆、经验和知识都可以从 Trace 事实中形成，但它们处于事实层之上。Agent 根据当前目标选择材料，完成相关性判断、总结、归纳和演绎。问题变化后，也可以从同一批事实重新形成不同的解释。

当“提前压缩成一个方便答案”与“保留未来重新解释的可能性”冲突时，Trace Index 选择索引事实。

#原始 Trace 拥有来源事实，索引可以重建

原始 Trace 对“Runtime 实际持久化了什么”拥有最终的证据地位。Trace Index 是从这些记录建立的派生事实层，不是另一份需要与来源独立维护的真相。

索引可以保存来源身份、物理位置、内容哈希、已经组织的程序事实和派生关系，使普通任务不必反复扫描原始文件。与此同时，每项需要验证的事实都保留溯源路径，可以回到 Runtime 实际持久化的记录核对。

组织规则、领域模型或存储方式发生变化时，索引应当能够从来源重新建立。索引内部的局部身份不能替代来源身份和物理证据。来源没有记录的事实保持缺失，不能通过猜测补全。

当“维持现有派生结果”与“按照新规则得到一致事实”冲突时，Trace Index 选择从原始 Trace 重建。

#统一共同结构，同时保留 Runtime 差异

跨会话、跨项目、跨 Runtime 是 Trace Index 释放 Trace 价值的核心能力。Agent 需要用一致方式发现和组合事实，否则每次调查都要重新理解不同 Runtime 的文件、记录类型、边界信号和关联方式。

统一发生在能够被多个 Runtime 共同支持的程序结构层，例如来源范围、Runtime 赋予的上下文身份、一次完整运行的生命周期、有序活动及其关系。统一后的结构降低查询成本，但不会把不同 Runtime 的行为或证据宣称为等价。

不同 Runtime 对运行边界、作者身份、完成状态或工具关联可能提供不同强度的证据。Trace Index 保留 Runtime、原生身份、分类依据和观察覆盖，让 Agent 在共享结构上查询时仍能判断比较是否成立。

因此，相同的查询形状不等于相同的证据强度。某个 Runtime 上的空结果也可能来自未记录、未覆盖或确实没有发生。模型应当让这些情况可以继续调查。

当“得到更整齐的统一结果”与“准确表达 Runtime 差异”冲突时，Trace Index 选择保留差异。

#确定性的组织前移，开放性的解释后置

每个 Agent 都会重复完成、并且可以由来源或结构稳定决定的工作，应当在索引时完成一次。只有这样，Agent 才能从已经组织好的事实开始，而不是在每个任务中重新解析 Runtime。

适合前移的工作包括发现物理输入、识别原生记录、恢复 Runtime 赋予的身份和可观察运行边界、关联前后活动、保留分类依据，以及计算能够从事实重建的结构统计。这些边界来自 Runtime 程序结构，不来自对自然语言内容的理解。

Task、意图、话题、相关性、稳定偏好、失败根因、最佳实践、经验总结和知识判断依赖自然语义、当前问题、比较范围与推理过程，适合由 Agent 在读取事实后形成。Trace Index 不应因为 Agent 能够理解这些含义，就在索引时替 Agent 持久化一套未经 Runtime 证明的边界。

可以用一个简单问题判断边界：面对相同来源，不同 Agent、不同任务是否都应该得到同一个结果？如果答案是肯定的，它更接近可索引的确定性事实。如果答案取决于当前目标和解释，它更接近查询时的智能工作。

当“减少查询时工作”与“避免把一次解释固化成公共事实”冲突时，Trace Index 只前移确定性的组织。

#让有限上下文观察持续增长的历史

Agent 的阅读速度很快，Trace 的增长速度更快，而单次任务的上下文始终有限。Trace Index 不能以“可查询”为由把全部历史一次性送入 Agent，也不能返回一个看似完整的局部结果而隐藏已经触发的限制。

观察应当逐层展开：先确定会话、项目、Runtime 或时间等范围，再定位候选事实，随后读取必要上下文，只有在需要核对时才沿溯源路径访问原始记录。每一层都可以缩小后续成本。

时间、结果数量、单项大小和总体输出等边界都应当可预测。发生截断、超限或只观察到部分范围时，这些状态本身也是事实，必须随结果一起交给 Agent。Agent 据此决定继续收窄、分组、展开还是停止。

当“返回更多内容”与“保护任务的时间、内存和上下文”冲突时，Trace Index 选择有界观察，并显式说明不完整。

#写入、失败与覆盖必须显式

Agent 需要知道一次操作会不会改变索引，也需要知道一个结果究竟表示“没有发现”，还是“没有完整观察”。副作用和缺口只有显式可见，自动化调用才能据此作出可靠决定。

索引变化由明确的同步动作触发，普通发现、查询和溯源读取不会顺带修改观察对象。一次来源处理失败时，已经完整提交的其他来源仍然可用。失败来源保持可识别，不能被一个看似成功的总结果掩盖。

未识别的文件、仍在写入的不完整记录、已经识别但处理失败的 Trace，以及当前格式解释规则尚未覆盖的来源形态，是不同事实。它们应当以不同状态呈现，而不是被折叠成同一种“没有数据”。

当“让流程继续”与“暴露真实失败”发生张力时，Trace Index 同时保留局部可用性和失败可见性。

#接口和抽象由真实问题推动

Trace Index 的核心需要足够稳定，使 Agent 可以长期依赖。它也需要足够小，避免把一次任务的便利变成所有 Runtime 和所有未来问题都要承担的永久复杂度。

新增命令、实体、关系或扩展机制，应当至少由一种真实需求支撑：它建立了新的能力边界，建立了新的安全或副作用边界，多个任务反复需要同一种确定性工作，或者可复现的测量证明现有方式已经造成不可接受的成本与错误。

代码较长、概念看起来对称或某次查询可以更短，都不足以单独证明一个抽象应该进入核心。反过来，已经在真实任务中反复出现的结构性问题，也不应因为当前实现还能绕过就长期留给每个 Agent 重复解决。

当“形式上的完整”与“已经得到证明的必要性”冲突时，Trace Index 选择较小、可解释、可以继续演化的核心。

#原则如何共同裁决

“Agent 是第一使用者”规定的是有效方案之间的使用者优先级。它不是允许系统为了 Agent 的使用便利改写事实的通行证。来源支持、事实与解释分层、Runtime 差异可见，是任何方案进入比较之前都必须满足的有效性前提。

#先通过事实有效性

1. 结果是否仍然由原始 Trace 支持，并且可以溯源？
2. 事实与解释是否仍然分层，缺失和推断有没有被伪装成来源事实？
3. 跨 Runtime 的共同结构是否真实存在，差异和证据强度是否仍然可见？

任一前提不成立，方案就不能进入下一层比较。不能为了更快、更方便或更适合 Agent 而制造错误事实。

#再以 Agent 自主使用为优先

通过有效性检查后，再按下面的顺序选择：

1. Agent 是否能够在有限上下文中发现、理解、组合和逐步展开事实，并在中断后继续任务？
2. 写入、副作用、失败、覆盖和不完整是否明确，使 Agent 能够判断下一步？
3. 新接口或抽象是否有真实任务或测量依据，没有把实现复杂度转嫁给所有调用者？

在这些有效方案之间，当 Agent 自主使用与人类操作习惯或实现便利冲突时，Trace Index 选择前者。一个被发现的来源缺口、分类错误或覆盖不足，则应当作为事实进入设计，而不是为了维持表面上的 Agent Friendly 而被隐藏。

#继续阅读

设计原则确定了 Trace Index 应当承认什么、保留什么以及在冲突中如何选择。下一步需要把这些判断落实为一组具有明确身份、关系和生命周期的对象。

Trace Index 领域模型 回答这个问题。Trace Index 设计索引 提供完整阅读路径和事实来源。