tracer-evolve

一个以证据、事件和受控进化为核心的 TypeScript Agent Runtime，用于构建可恢复、可审计、可验证并能够安全自我改进的 Ambient Agent。

tracer-evolve 不是又一个把 ReAct Loop 包装成聊天接口的 Agent 框架。它把一次 Agent 执行建模为由持久事实驱动的状态机，把动态工作流建模为可版本化的 WorkflowIR，把完成判定交给独立 Verifier，再把经过验证的 Trial 送入受治理的 Self-Harness Evolution Loop。

项目要复现的不是“让模型随意修改自己的代码”，而是 Self-Harness 中真正可工程化的部分：

在不允许候选方案重定义成功、篡改证据、降低权限或绕过发布门禁的前提下，持续改进 Agent 完成工作的方式。

项目定位
为什么做这个项目
设计原则与核心亮点
总体逻辑架构
Runtime Goal Loop
Dynamic Workflow
Evidence、Evaluation 与能力自我模型
Self-Harness Evolution Loop
Ambient Agent 控制面
核心领域对象
Monorepo 模块边界
信任边界与安全不变量
持久化、恢复与部署模型
确定性端到端示例
Quickstart、CLI 与验证矩阵
当前边界与后续扩展

项目定位

tracer-evolve 面向三类问题：

Agent Runtime：一次目标执行如何拥有明确事件流、状态 reducer、会话树、预算、权限、等待、恢复与重放语义；
Dynamic Workflow：工作流如何按目标动态选择、生成和修复，同时仍然保持结构化、可校验、可调度和可追踪；
Self-Improvement：系统如何从经过验证的失败中提取弱点，提出有限 Harness 变更，并通过 held-in、held-out 和可信发布门禁决定是否接受。

这里的核心不是某个 Prompt，也不是某个模型供应商，而是一组稳定协议：

事实事件 -> Reducer -> 状态 -> 决策 -> 幂等命令 -> Effect -> 新事实

模型、工具、子 Agent、人工审批和 evaluator 都只能通过命令与事件参与系统。状态由事实归约得到，不能由某次模型调用私下改写。

为什么做这个项目

普通 Agent 的四个结构性问题

状态隐藏在上下文窗口中。 模型看到的是经过裁剪的消息，系统却常把这段消息误当作真实运行状态。进程崩溃、上下文压缩或并发执行后，很难回答“究竟发生了什么”。

模型同时执行任务和宣布成功。 “我已经完成”只是行为输出，不是正确性证明。没有独立 verifier，运行轨迹再完整也只能说明 Agent 做过什么，不能说明结果满足目标。

工作流只有 Prompt，没有运行时语义。 如果计划、依赖、重试、等待、并行和补偿都藏在自然语言里，系统就无法稳定调度、恢复或审计。

自我改进没有可信边界。 如果候选 Harness 能修改 evaluator、测试集、权限或发布规则，它最容易学到的不是提升能力，而是降低成功标准。

tracer-evolve 的回答

问题	系统机制
状态不可恢复	Append-only Event Journal + Reducer + Projection
Effect 重复执行	`EffectCommand`、幂等键、租约和生命周期 outbox
模型自述成功	`VerifierResult` 与 `GoalState` 成功不变量
工作流不可控	版本化 `WorkflowIR`、`WorkflowRouter`、Scheduler、`NodeResult`
Trace 被误当成知识	`Trial -> CausalEpisode -> CapabilityProfile` 分层证据链
自我改进失控	可编辑面白名单、held-out、`AcceptRejectGate`、不可变 Registry
Ambient 事件丢失或重复	认证入口、delivery 去重、durable wake intent 与 lease

设计原则与核心亮点

1. 事实优先，而不是 Transcript 优先

Event Journal 是操作事实源。GoalState、Workflow 执行状态和各种查询投影都由事件重建；日志和聊天记录只用于观察，不承担状态权威。

2. Decision 与 Effect 分离

LeadAgent 只产生结构化决策，Effect Worker 才执行模型、工具、文件系统、Shell 或子 Agent 调用。每个 Effect 都经过命令登记、权限检查、租约、重试分类和结果事件化。

3. Goal 完成由独立证据决定

成功的 GoalState 和 Trial 必须包含独立且通过的 VerifierResult。模型不能仅通过输出 complete 绕过 verifier；决策还要经过 DecisionValidator。

4. Dynamic Workflow 是受约束的 IR

动态不是“执行任意生成代码”。WorkflowIR 有明确节点类型、依赖边、重试策略、能力声明、不变量和完成策略。新版本经过校验和发布后才能运行。

5. Replay 不制造新事实

默认 Replay 读取已记录事件和 Artifact，重建当时状态，不再次调用模型或工具。需要重新执行时，必须创建新的 Run 或分支，避免把重放和新实验混为一谈。

6. Trace 不是证明

Trace 描述行为过程；Artifact 保存内容；Verifier 给出独立判定；Trial 固化实验条件；只有经过因果归因与条件化聚合后，信息才进入 CapabilityProfile。

7. Harness 可以进化，可信计算基不能

候选只能改动声明过的 Prompt、上下文策略、工作流策略/模板、Skill 和结构化 Memory。Event Journal、原始证据、verifier、评估 split、权限根、预算上限、Sandbox、模型身份、门禁和 Registry 审计都在进化边界之外。

8. 发布是治理动作，不是模型动作

候选通过验证不等于自动上线。AcceptRejectGate 依据配对评估、安全约束、成本上限和审批策略给出决定；HarnessRegistry 负责不可变快照、channel 指针、审计与 CAS rollback。

9. Ambient 输入先持久化，再唤醒

外部 Webhook 或定时事件先经过认证、内容寻址和 delivery 去重，再与 durable wake intent 一起提交。入口不能绕过控制面直接调用模型。

10. TypeScript 端到端协议

协议、runtime、evaluator、evolution、storage、CLI 和 control plane 使用同一套 TypeScript/Zod 类型，减少跨语言序列化漂移。Evaluator Worker 并不要求 Python；只有需要 Python 专用评测生态时才应通过进程或服务适配。

总体逻辑架构

flowchart TB
    Source["Ambient Source / Operator"] --> CP["Control Plane<br/>认证、去重、授权"]
    CP --> Wake["Durable Wake Intent"]
    Wake --> Runtime

    subgraph Runtime["Agent Runtime 内环"]
        Journal["Event Journal"] --> Reducer["Reducer / Projection"]
        Reducer --> Goal["GoalState"]
        Goal --> Lead["LeadAgent"]
        Lead --> Router["WorkflowRouter"]
        Router --> WIR["Versioned WorkflowIR"]
        WIR --> WR["WorkflowRuntime / Scheduler"]
        WR --> Command["Idempotent EffectCommand"]
        Command --> Worker["Model / Tool / Skill / Subagent / Human"]
        Worker --> Result["NodeResult + ArtifactRef"]
        Result --> Journal
    end

    Result --> Trace["Trace / DecisionRecord"]
    Trace --> Trial["Trial"]
    Trial --> Verifier["Trusted Verifier"]
    Verifier --> VR["VerifierResult"]
    VR --> Goal
    VR --> Episode["Verified CausalEpisode"]
    Episode --> Profile["CapabilityProfile"]

    subgraph Evolution["Self-Harness 外环"]
        Profile --> Miner["WeaknessMiner"]
        Miner --> Proposer["HarnessProposer"]
        Proposer --> Candidate["HarnessCandidate"]
        Candidate --> Validator["CandidateValidator"]
        Validator --> Gate["AcceptRejectGate"]
        Gate --> Registry["HarnessRegistry"]
    end

    Registry --> Snapshot["Immutable HarnessSnapshot"]
    Snapshot --> Goal

系统由五条主链路组成：

Runtime：外部唤醒驱动 GoalState 前进；
Workflow：WorkflowIR 把目标决策落实为节点调度；
Evidence：节点、Effect、状态变化与 Artifact 形成可追溯证据；
Evaluation：可信 verifier 判定结果并构建能力画像；
Evolution：基于验证证据提出、评估和发布 Harness 候选。

Runtime Goal Loop

一次 Wake 是一个有界决策事务

GoalRuntime.wake(goalId, wakeEventId) 不运行无限 while-loop。它执行一次乐观并发控制下的有界周期：

从 goal:<goalId> 读取事件历史；
用 GoalReducer 重建最新 GoalState；
通过 DecisionContextProjector 组合 Run、Workflow、verifier、能力画像、等待条件和运行时 guard；
若目标已经 terminal，直接跳过；
若仍在等待人工、时间或外部条件，恢复必要命令后保持 waiting；
在预算、权限、审批等 guard 通过后调用 LeadAgent.decide()；
用 DecisionValidator 校验结构化决策；
以 expected stream version 原子追加事件；
分发由决策产生的幂等 EffectCommand。

flowchart LR
    Wake["Wake Event"] --> Read["读取 Event Journal"]
    Read --> Reduce["GoalReducer"]
    Reduce --> State["GoalState"]
    State --> Guard{"Terminal / Waiting /<br/>Budget / Permission?"}
    Guard -->|terminal| Stop["跳过，不产生新 Effect"]
    Guard -->|waiting| Wait["保持等待 / 恢复人工命令"]
    Guard -->|allowed| Context["DecisionContextProjector"]
    Context --> Lead["LeadAgent.decide"]
    Lead --> Validate["DecisionValidator"]
    Validate --> Append["按 expectedVersion 追加事件"]
    Append --> Dispatch["分发 EffectCommand"]
    Dispatch --> Effect["EffectRunner"]
    Effect --> Lifecycle["requested / started /<br/>succeeded / failed"]
    Lifecycle --> Read

LeadAgent 的职责边界

LeadAgent 是目标级决策器，不是拥有无限权限的总控脚本。它接收 LeadDecisionContext，输出以下结构化动作之一：

执行或继续某个 Run；
采用、修复或切换 Workflow；
请求人工输入或审批；
在证据满足时申请完成；
在无法继续时失败、取消或耗尽。

Runtime guard 可以在不调用模型的情况下产生受控决策，例如预算耗尽、等待未满足或权限不足。这样，“能否继续”由系统规则判断，“下一步做什么”才交给 Agent。

Effect 生命周期与幂等性

所有外部副作用通过 EffectCommand 执行。EffectRunner 与 CommandStore 提供：

命令登记和重复提交去重；
worker lease 与过期回收；
requested、running、retryable、succeeded、failed、cancelled 状态；
retryable/terminal 错误分类；
生命周期事件 outbox；
Artifact 化的输入、输出与错误证据。

幂等性不意味着外部系统天然 exactly-once。Worker 仍必须把 command id 传给下游作为 idempotency key，并只在持有有效 lease 时完成命令。

Session Tree 与 Subagent

SessionTree 明确父子 Session 关系。子 Agent 通过 SubagentRuntime 和 SubagentEffect 创建，拥有独立预算、上下文投影、能力范围与结果 Artifact；父 Agent 接收的是结构化结果引用，而不是把所有子 Agent 私有上下文拼回主窗口。

Dynamic Workflow

WorkflowIR

WorkflowIR 是运行时可校验的工作流定义：

interface WorkflowIR {
  workflowId: WorkflowId;
  goalId: GoalId;
  version: number;
  nodes: WorkflowNode[];
  edges: WorkflowEdge[];
  invariants: string[];
  completionPolicy: CompletionPolicy;
  createdAt: string;
}

当前协议支持 model、tool、skill、subagent、human、evaluation、condition、parallel、join、wait、checkpoint 和 compensation 节点类型。每个节点可声明重试策略与所需 capability。

Router、Revision 与 Publication

WorkflowRouter 根据目标、能力画像和现有 Workflow 做三类决定：

Route：从已发布版本中选择适合当前条件的 Workflow；
Synthesize：没有合适版本时生成新的 WorkflowIR；
Repair：根据失败节点和证据提出新 revision。

RevisionValidator 校验节点、边、版本关系、完成策略和不变量。Publication Store 保存不可变版本及父版本关系。运行中的 Run 固定 workflowId + version，不会被后续发布静默替换。

Scheduler 与 WorkflowRuntime

Scheduler 根据依赖边和当前节点状态计算 ready/running/blocked/terminal 集合。WorkflowRuntime.tick() 每次只推进一个确定性调度周期：

从 Workflow 事件流重建 WorkflowExecutionState；
选择可执行节点；
为节点生成命令并记录事件；
接收 Effect 结果并归约为节点状态；
形成 NodeResult；
在失败、等待、重试、取消和补偿之间按显式语义流转。

NodeResult 分离四类引用：

observationRefs：执行观察；
artifactRefs：产出物；
stateChangeRefs：环境或业务状态变化；
evidenceRefs：可供 verifier 使用的证据。

工作流完成不等于目标成功

Workflow 的终端节点全部成功，只说明调度计划执行完毕。目标是否成功仍由 CompletionPolicy 指定的独立 verifier 决定。系统支持全部终端节点成功、verifier 阈值和人工完成策略，但三者都必须声明 requiredVerifierIds 且要求独立 verifier。

Evidence、Evaluation 与能力自我模型

为什么不用 Traits 作为唯一自我认知

“擅长规划”“工具使用较弱”这类 trait 容易理解，但它们通常缺少任务条件、样本量、置信区间和可反驳证据。tracer-evolve 把 trait 降级为可选解释层，核心自我模型使用条件化的 CapabilityProfile：

在什么任务类别、环境、模型、Harness 和 Workflow 条件下，
以多大概率、成本和可靠性完成目标，
常见失败机制是什么，
证据和不确定性分别是什么。

这比固定 personality trait 更适合路由、预算、进化和回归判断。

证据分层

对象	回答的问题	不能证明什么
`Trace`	Agent、模型、工具和节点做了什么	结果是否正确
`ArtifactRef`	哪段不可变内容被输入、产生或观察	内容是否满足目标
`DecisionRecord`	当时基于什么上下文做了什么决定	决策是否最优
`VerifierResult`	某个固定版本 verifier 如何判定结果	跨任务的普遍能力
`Trial`	在固定 Run 条件下发生了什么并得到何种判定	失败机制是否具有因果性
`VerifiedCausalEpisode`	行为、终局原因和可复用机制之间的证据强度	未观察条件下必然成立
`CapabilityProfile`	条件化成功率、置信区间、成本、可靠性与失败机制	永久不变的 Agent 本质

Trial 是评估和进化的最小实验单元

一次 Trial 固定：

goalId 与 runId；
Workflow id/version；
Harness snapshot；
模型版本；
环境版本；
trace、state change 和 artifact 引用；
verifier 定义与结果；
最终 outcome。

只有这些条件固定，baseline 与 candidate 的比较才有意义。成功 Trial 必须至少有一个与其 goalId、runId、trialId 一致的独立通过结果。

从失败到能力画像

CausalEpisodeBuilder 和 mechanism miner 不会把单次相关性直接写成稳定知识。Episode 记录：

terminal verifier cause；
Agent behavior；
supporting 与 contradicting evidence；
unknown、correlated、attributed、intervention_validated 因果状态；
observed 到 replicated 的验证等级；
置信度和可复用机制。

CapabilityProjector 再按任务类别、split、模型、环境、Workflow、Harness 和成本条件聚合 Episode，产出带样本量、置信区间和 freshness 的版本化画像。

Self-Harness Evolution Loop

Self-Harness 外环消费完成且经过验证的 Trial，不读取模型自述作为成功事实。

flowchart LR
    Trials["Verified Trials"] --> Episodes["Causal Episodes"]
    Episodes --> Profiles["CapabilityProfile"]
    Profiles --> Miner["WeaknessMiner"]
    Miner --> Weakness["Bounded Weakness"]
    Weakness --> Proposer["HarnessProposer"]
    Proposer --> Candidate["HarnessCandidate"]
    Candidate --> Workspace["Isolated CandidateWorkspace"]
    Workspace --> Static["Static / Safety Validation"]
    Static --> HeldIn["Held-in Trials"]
    HeldIn --> HeldOut["Hidden Held-out Trials"]
    HeldOut --> Gate{"AcceptRejectGate"}
    Gate -->|reject| Archive["保留候选与拒绝证据"]
    Gate -->|accept| Snapshot["Immutable HarnessSnapshot"]
    Snapshot --> Registry["HarnessRegistry"]
    Registry --> Channel["Channel Promotion"]
    Channel --> Runs["New Runs"]
    Runs --> Trials

1. WeaknessMiner

WeaknessMiner 从失败 Trial、因果 Episode 和 Capability Profile 中选择边界明确、证据充分、可通过允许表面修复的问题。弱点不是泛化人格标签，而是带条件和证据引用的失败机制。

2. HarnessProposer

HarnessProposer 生成 HarnessCandidate，必须声明：

parent snapshot；
targeted weaknesses；
changed surfaces；
content-addressed patch；
predicted effect；
regression risks；
validation plan；
产生提案所依据的证据。

3. CandidateWorkspace

候选在隔离 workspace 中展开，不能直接改写当前发布快照或仓库可信代码。Patch 的实际变更表面必须与候选声明完全一致。

4. CandidateValidator

Validator 先做 manifest、checksum、兼容性、可编辑面和安全静态检查，再在固定预算下执行配对评估。held-out membership 不对 proposer 和 candidate code 开放。

5. AcceptRejectGate

门禁综合判断：

held-in 是否改善；
held-out 是否保持或改善；
安全与策略 verifier 是否全部通过；
成本、延迟和 token 是否在上限内；
是否存在要求的人工审批；
比较是否使用相同模型、环境、Workflow/verifier 条件。

候选不能修改门禁本身，也不能决定自己是否被接受。

6. HarnessRegistry

接受后的 Harness 以不可变快照保存。Registry 记录 parent、组件 digest、可信控制引用、验证证据和审计信息。发布只是移动 channel 指针；rollback 使用 compare-and-swap，避免并发操作覆盖更新。历史快照、失败候选和 Trial 不会被重写。

可进化表面

prompts
context_policies
workflow_policies
workflow_templates
skills
structured_memory

受保护表面

Event Journal 与原始 evidence；
verifier bundle 与 evaluation splits；
permission roots、sandbox enforcement 与 budget caps；
model identity；
candidate validator 与 accept/reject gate；
data retention 与 redaction policy；
registry audit 和生产 channel 权限。

工具实现、中间件代码、权限和子 Agent 拓扑即使可以被某种 Patch 表达，也必须经过显式人工审批。

Ambient Agent 控制面

Ambient Agent 的关键不是“后台一直运行”，而是能够可靠接收长期、异步、重复和乱序的外部事件。

Ingress 路径

apps/control-plane 提供 Fastify 边界：

RequestAuthenticator 验证调用方；
principal 的 allowedSources 限制可提交的 source；
payload 先进入 PayloadStore，控制面只在事件中保存 ArtifactRef；
AmbientIngress.accept() 按 source + deliveryId 去重；
delivery 事实与 wake intent 持久化；
dispatcher 通过 lease claim wake；
GoalRuntime.wake() 执行一个有界周期；
dispatcher 按成功、重试或终止结果 settle lease。

同一个 delivery id 携带不同目标或 payload 会被视为冲突，而不是静默覆盖。

Operator 路径

控制面和 CLI 暴露显式 operator seam，用于：

检查 Goal；
回答人工问题；
取消 Goal；
授予审批；
验证候选；
Promote 或 Rollback Harness。

这些动作必须经过认证、授权和事件记录。Ambient adapter 不得直接访问模型或 Registry 写接口。

核心领域对象

对象	责任与关键不变量
`GoalState`	目标、成功标准、约束、预算、Workflow/Harness 固定引用、进度证据与 blocker；成功必须有独立 verifier 证据
`Run`	固定一次执行的模型、环境、Workflow、verifier definitions 和 validated Harness release
`WorkflowIR`	版本化节点图、不变量、能力声明和完成策略
`NodeResult`	节点状态以及 observation/artifact/state-change/evidence 引用
`EffectCommand`	外部副作用的幂等执行意图与生命周期
`ArtifactRef`	内容寻址的不可变字节引用，不承载正确性结论
`VerifierResult`	固定版本、独立 evaluator 对特定 Trial 的判定
`Trial`	固定实验条件、完整证据与 outcome 的最小评估单元
`VerifiedCausalEpisode`	失败原因、行为机制、正反证据与因果验证等级
`CapabilityProfile`	条件化能力概率、置信区间、失败机制、成本与 freshness
`HarnessCandidate`	面向明确弱点、只修改声明表面的候选 Patch
`HarnessSnapshot`	README 中对不可变 Harness 发布物的统称；源码由 `HarnessManifest`/bundle 和 Registry snapshot 记录表示

Monorepo 模块边界

路径	责任
`packages/protocol`	Zod schema、branded id，以及 Goal、Run、Workflow、Evidence、Harness 和 Event 协议
`packages/event-runtime`	Event Journal、Reducer、Projection 与 Session Tree 原语
`packages/agent-runtime`	Goal Loop、LeadAgent、Dynamic Workflow、Effect、工具、Skill、权限、上下文和 Subagent
`packages/evidence`	Content-addressed Artifact Store、Tracer、DecisionRecord 与 Trial assembly
`packages/evaluation`	Verifier Registry、确定性/Artifact/Process verifier、Causal Episode 与 Capability Profile
`packages/evolution`	Weakness mining、Harness proposal、Candidate workspace/validation、Release Gate、Registry 和 Rollback
`packages/storage`	PostgreSQL Journal、Command/Projection/Domain repository、Ambient inbox/wake 以及本地文件 CAS
`apps/control-plane`	认证 Ambient ingress 与 operator API 的 Fastify 边界
`apps/agent-cli`	CLI parser、确定性本地 composition、持久化演示状态、Replay 和 operator seam
`examples/coding-agent`	覆盖失败、进化、发布、成功与重放的确定性 coding fixture

依赖方向以 protocol 为底层契约。Runtime 不直接依赖具体模型 SDK；模型、工具和 evaluator 通过接口注入。Storage 提供持久化 adapter，不反向决定领域规则。

信任边界与安全不变量

成功判定

模型输出不能直接把 Goal 设为 succeeded；
通过结果必须来自独立 verifier；
通过的 VerifierResult 必须绑定相同 Goal、Run 和 Trial；
candidate 不能修改 verifier definition 或 evaluation split。

权限与执行

capability 默认不授予；
文件系统按 root 和 operation 限制；
Shell 通过 supervisor、超时和 capability policy 执行；
Subagent 只能继承显式授予的范围；
Effect 输入输出通过 Artifact 引用，不把 secret 放入事件 metadata 或 Prompt。

进化治理

Patch 只能修改 allowlist 中的表面；
trusted control refs 进入 Harness manifest；
held-out 对 proposer 隐藏；
Validator 与 Gate 位于候选 Sandbox 之外；
发布、审批与 rollback 使用受信 operator 身份；
accepted、rejected 和 published 历史都保留审计证据。

可信计算基

系统真正信任的是：协议校验、Event Journal、原始 Artifact、Reducer、权限/Sandbox、预算、verifier bundle、split 定义、candidate validator、release gate 和 Registry audit。模型输出、候选 Patch、Trace 文本和自我解释全部是不可信输入。

持久化、恢复与部署模型

当前实现

测试和本地 composition 可使用：

InMemoryEventJournal；
in-memory command、projection、workflow 和 harness repository；
InMemoryArtifactStore；
LocalArtifactStore；
CLI 的 .tracer-evolve/<workspace>/state.json 演示状态。

生产 adapter 已包含：

PostgreSQL append-only Event Journal；
Effect command store、lease 与 lifecycle outbox；
Projection checkpoint、CAS 与 deduplication；
Workflow publication 与 Harness snapshot repository；
Ambient delivery dedupe 与 durable wake intent；
本地文件系统 content-addressed Artifact Store。

初始化 PostgreSQL 16+：

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 \
  -f packages/storage/src/migrations/001_initial.sql

恢复语义

进程崩溃后，Orchestrator 从 Journal 与 Projection checkpoint 恢复；Effect 和 ambient wake 的过期 lease 可被其他 worker 重新 claim。不能通过伪造 success event 清理积压。

Replay 默认读取记录结果：

Recorded events + immutable artifacts -> Reducers -> reconstructed state

它不会再次调用模型、工具或 verifier。需要验证新模型、新环境或新 Harness 时，应创建新 Run，并显式关联 parent/对照 Trial。

Artifact Storage 边界

仓库提供的 LocalArtifactStore 使用 staging、fsync、原子 rename 和 digest 校验，适合单一持久主机或正确配置的共享 POSIX 文件系统。多机部署需要实现等价的对象存储 adapter；本仓库没有内置 S3 adapter。

数据库与 Artifact Store 必须成对备份。只有数据库会丢失被引用内容，只有 Artifact 会丢失谱系和所有权。

详细运维要求见：

确定性端到端示例

examples/coding-agent 是完整但刻意确定性的 fixture：

baseline Harness 执行 coding task；
第一次 Run 因 verifier-backed 条件不满足而失败；
系统组装 Trial、提取 Episode 并更新 Capability Profile；
WeaknessMiner 定位受限失败机制；
proposer 只修改允许的 Harness 表面；
candidate 在 held-in 和隐藏 held-out split 上验证；
Gate 接受后发布不可变 snapshot；
第二次 Run 固定新 snapshot 并成功；
Replay 重建成功 Run，比较已记录事件序列与 digest。

该示例证明的是：

Event/Reducer 行为；
Goal 与 Workflow 状态推进；
verifier-backed completion；
Evidence 与 Trial 组装；
candidate 治理、发布和 rollback 语义；
跨 CLI 进程的演示状态与确定性 Replay。

它不是真实模型 benchmark，也不证明某个 live provider 的智能水平、泛化能力或线上可靠性。

Quickstart、CLI 与验证矩阵

环境要求

Node.js >=22.12
Corepack
pnpm 10.30.1，由 packageManager 固定
PostgreSQL 仅在运行 integration test 或生产 adapter 时需要

安装与基础验证

corepack enable
pnpm install
pnpm test
pnpm typecheck

跑通 Self-Harness 序列

# 1. baseline Run，记录输出中的 runId
pnpm agent run --fixture examples/coding-agent/task.json

# 2. 从失败证据提出、验证并发布候选
pnpm agent evolve --goal-family coding-fixture

# 3. 使用新的不可变 Harness snapshot 再次执行
pnpm agent run --fixture examples/coding-agent/task.json

# 4. 使用实际成功 runId 重建事件序列
pnpm agent replay <run-id>

pnpm dev 等价于运行一次默认 fixture：

pnpm dev

本地状态默认写入 .tracer-evolve/<workspace>/。可通过 TRACER_EVOLVE_STATE_DIR 指定其他目录。

CLI 命令

命令	用途
`pnpm agent run --fixture <path>`	执行 fixture 并持久化 Run/Trial 演示状态
`pnpm agent replay <run-id>`	从记录事件确定性重建 Run
`pnpm agent evolve --goal-family <family>`	对指定 Goal family 执行一次进化轮次
`pnpm agent goal inspect --goal <id>`	检查 Goal
`pnpm agent goal answer --goal <id> --answer-ref <sha256:...>`	回答等待中的人工问题；本地 fixture 仅保留 composition seam
`pnpm agent goal cancel --goal <id> --reason-ref <sha256:...>`	取消 Goal；本地 fixture 仅保留 composition seam
`pnpm agent approval grant --subject <id>`	授予受控审批；本地 fixture 不要求审批
`pnpm agent candidate validate --candidate <id>`	显式验证候选；本地 fixture 仅保留 composition seam
`pnpm agent harness promote --channel <name> --candidate <id>`	将接受候选发布到 channel；本地 fixture 仅保留 composition seam
`pnpm agent harness rollback --channel <name> --target <sha256:...> --expected <sha256:...>`	CAS rollback 到已知快照；本地 fixture 仅保留 composition seam

完整验证矩阵

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm test:integration
pnpm test:e2e
pnpm build
git diff --check

层次	主要覆盖
Unit	Schema、不变量、Reducer、Router、Effect、Verifier、Gate
Storage	Migration、Journal、Command、Projection、Ambient 去重与 lease
Integration	PostgreSQL append/concurrency/recovery 行为
E2E	baseline failure -> evolve -> publish -> success -> replay
Static	TypeScript 类型、workspace build 与 whitespace

当前边界与后续扩展

仓库已经实现

事件驱动 Goal Loop 与 reducer；
结构化 LeadAgent 决策和 runtime guard；
版本化 Dynamic Workflow 与节点调度；
幂等 Effect command、lease、重试和生命周期事件；
文件、Shell、模型、工具、Skill 与 Subagent 扩展接口；
Artifact、Trace、Trial、Verifier、Episode 与 Capability Profile；
受限 Harness candidate、held-in/held-out validation、Gate、Registry 与 rollback；
认证 Ambient ingress、operator seam 和 durable wake；
PostgreSQL 与本地 CAS adapter；
完整确定性 Self-Harness E2E fixture。

生产接入时仍需提供

真实模型 provider client 与用量/成本回传；
面向具体产品的 Tool、Skill、Prompt 和 Workflow 模板；
强隔离容器或 microVM Sandbox；
Secret Manager、KMS、OIDC/RBAC 实现；
对象存储 Artifact adapter；
外部队列或 CDC/outbox dispatcher；
metrics、distributed tracing 和日志 exporter；
面向真实任务的 verifier suite 与受控 benchmark 数据；
多租户配额、数据保留和合规策略；
Kubernetes/Terraform 等完整部署封装。

研究方向

在相同可信边界下加入 evolutionary search、population/archive 与多候选资源分配；
用干预实验提升 Causal Episode 的验证等级，而不是只扩大 Trace 文本；
基于 Capability Profile 做风险感知的 Workflow/模型/子 Agent 路由；
研究 Harness 变更的长期回归、能力遗忘与跨环境迁移；
将代码式 Dynamic Workflow 作为受控节点执行器接入，而不允许它绕过事件、权限和 verifier；
建立真实任务族上的 paired evaluation、污染防护与统计发布策略。

设计与研究文档

tracer-evolve 的最终目标不是制造一个会宣称自己变强的 Agent，而是建立一套能够回答以下问题的系统：

它改了什么？为什么改？依据是什么？在什么条件下变好？是否伤害 held-out 能力？谁允许它发布？失败后能否恢复与回滚？

只有这些问题都有可追溯答案，自我改进才从 Prompt 技巧变成可验证的工程系统。

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.github/workflows		.github/workflows
apps		apps
docs		docs
examples/coding-agent		examples/coding-agent
packages		packages
test/e2e		test/e2e
.gitignore		.gitignore
CONTEXT.md		CONTEXT.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
vitest.workspace.ts		vitest.workspace.ts

角色	职责
Control Plane	认证 ingress、operator API、审批与 durable wake acceptance
Orchestrator	Reducer、Goal Loop、Workflow routing 与 scheduling
Effect Worker	模型、工具、Skill、文件、Shell 和 Subagent Effect
Evaluation Worker	Verifier、Trial assembly、Episode 与 Capability Profile
Evolution Worker	Weakness、Candidate build/validation 与 release-decision inputs

Uh oh!

Folders and files

Latest commit

History

Repository files navigation