架构

Navi Agent 保持以运行时为中心的小型架构。协议适配器和离线进化与核心执行循环分离。

flowchart LR
    CLI[CLI / 微信] --> APP[应用服务]
    APP --> RUNTIME[Agent 运行时]
    RUNTIME --> MODEL[模型传输层]
    RUNTIME --> TOOLS[工具 Registry]
    RUNTIME --> EVENTS[运行时事件]
    RUNTIME --> SESSIONS[会话存储]
    RUNTIME --> MEMORY[记忆]
    EVENTS --> STORE[事件存储]
    EVENTS --> TRACE[Trace 构建]
    EVENTS --> HEALTH[健康指标]
    EVENTS --> UI[UI 事件]
    STORE --> EVOLUTION[离线进化]

职责

网关

负责协议轮询、消息标准化、访问策略和出站发送。当前网关实现仅支持微信。

应用服务

组装运行时依赖，并向 CLI 和网关暴露用例级操作，不泄漏存储细节。

运行时

负责会话加载、上下文构建、模型调用、工具分发、Steering、取消、压缩和最终响应。

每个运行时都通过不可变的 EnvironmentBinding 完成组装。它让 Workspace 与执行边界在会话记录、事件、工具调用和默认子 Agent 之间共享稳定身份。当前 Binding 明确声明为宿主机执行；Workspace 路径校验不能被解释为操作系统级 Sandbox。

每次 Agent 模型调用前，运行时都会持久化不可变的 StepSnapshot。它把唯一的 Step 身份与所选模型、Environment、精确上下文与工具 Schema 投影的哈希、可见能力名称以及 Prompt 来源身份绑定起来。该轮的模型请求、工具上下文和运行时事件共享同一个 step_id。

每次工具调用也会形成持久化的 OperationRecord。它通过稳定的 operation_id，把来源 Step、Environment、能力名称以及参数/结果哈希绑定起来。其受限生命周期为 planned → running → succeeded|failed|awaiting_input；用户解决交互后，等待中的操作可以重新进入 running。已经完成的操作会按照 (run_id, tool_call_id) 复用结果，而不会再次执行相同副作用。

工具

通过明确的 Schema 和结果暴露能力。工具校验自身输入，审批和执行策略仍由运行时负责。

运行时事件

RuntimeEvent 是执行事实流。Subscriber 负责持久化事件，或派生 Trace、健康数据和面向用户的进度，避免这些视图与运行时循环耦合。

step.snapshot 事件提供诊断所需的非敏感投影元数据。离线回放会将其中记录的上下文和工具 Schema 哈希与回放请求对比，并显式报告投影漂移，而不是静默接受不同的请求。

本地 Trace Viewer 是只读的 Telemetry 投影视图。它读取 Event Store 与 Trace Store，展示 Session、真实事件顺序和 Skill 加载情况，不参与 Runtime 执行，也不修改记录状态。

记忆与会话

会话存储是对话历史的权威来源。记忆提供跨会话 Recall，并按用户隔离。

两种 Session Store 实现也会随 Run 保存 Step Snapshot，因此即使不依赖 Event Store 投影，也可以检查当时的请求边界。

Operation Record 复用现有的工具执行存储边界。两种 Session Store 都可以查询终态和未完成操作，让中断后遗留的 planned 或 running 工作保持可见，而不把恢复策略耦合进具体工具。

进化

消费已存储的证据，提出并治理 Prompt 或 Skill 候选项。它不会直接修改在线运行时链路。

Skill 生产与 Skill 评测属于两个独立职责。Agent 自主生成、人工编写和外部提供的 Skill 都进入同一个未激活的草稿区。准入只检查包结构与来源；A/B 评测随后在隔离的临时 Skill Store 中，以当前已激活集合为 Baseline、已准入草稿为 Variant。激活是最后一个显式操作，并且必须已有记录的 skill_ab 结果。

REVIEW.html 是静态评审产物。评审者可以对比输出、选择 Baseline/Variant/Tie、标注问题归因并下载 feedback.json。反馈只用于后续归因或修改 Skill，不会激活草稿，也不会修改在线运行时。