# NOFXi Agent 当前设计说明

## 目的

本文描述当前 NOFXi Agent 的实际设计，而不是早期版本的理想设计。重点回答这些问题：

- 用户消息从哪里进入
- 什么请求会进入 planner
- 当前有哪些记忆层
- planner 如何生成与执行 plan
- tool 现在是怎么设计的
- 动态快照和当前引用分别解决什么问题
- 为什么某些问题会出现“看起来有历史，但模型还是会追问”

本文对应的主要实现文件：

- `agent/agent.go`
- `agent/web.go`
- `api/agent_routes.go`
- `agent/planner_runtime.go`
- `agent/execution_state.go`
- `agent/memory.go`
- `agent/history.go`
- `agent/tools.go`

## 一句话总览

当前 Agent 的运行模型可以概括为：

1. 前端把消息发到 `/api/agent/chat/stream`
2. 后端把登录用户身份放进 context
3. Agent 除 `/clear` 和 `/status` 外，其他消息全部进入 planner
4. planner 结合多层记忆、动态快照和 tool schema 生成 plan
5. 执行 plan 中的 `tool / reason / ask_user / respond`
6. 在执行过程中持续更新执行态、短期原话、长期摘要和当前对象引用

## 请求入口

### 前端入口

前端 Agent 页面在：

- `web/src/pages/AgentChatPage.tsx`

当前聊天使用：

- `POST /api/agent/chat/stream`

请求体里会传：

- `message`
- `lang`
- `user_key`

### 后端路由入口

路由注册在：

- `api/agent_routes.go`

这里会：

1. 经过 `authMiddleware`
2. 从登录态里取出 `user_id`
3. 通过 `agent.WithStoreUserID(...)` 写入 request context

### Agent Web Handler

真正的 HTTP handler 在：

- `agent/web.go`

主要入口：

- `HandleChat(...)`
- `HandleChatStream(...)`

再往下进入：

- `HandleMessageForStoreUser(...)`
- `HandleMessageStreamForStoreUser(...)`

## 最外层分流

当前外层分流已经被收口。

在 `agent/agent.go` 中，除了这两个命令之外，其他输入全部交给 planner：

- `/clear`
- `/status`

也就是说，现在这些都不再在外层直接处理：

- setup flow
- trade confirmation
- direct trade regex
- 自然语言配置流程
- 自然语言策略创建

这些都统一进入 planner。

这是当前设计里一个很重要的原则：

- 外层分流越少，行为边界越清晰
- 自然语言理解尽量统一交给 planner + tool

## 当前的 5 层记忆

当前不是 3 层，也不是 4 层，而是 5 层：

1. `chatHistory`
2. `TaskState`
3. `ExecutionState`
4. `CurrentReferences`
5. `Persistent Preferences`

### 1. chatHistory

定义位置：

- `agent/history.go`

作用：

- 保存最近几轮用户 / assistant 原始消息
- 给模型保留最近原话上下文
- 为后续摘要成 `TaskState` 提供原始素材

特点：

- 只保留短期原话
- 内存态
- `/clear` 时清空

适合存：

- 最近几轮对话原文
- 用户的最新措辞
- 刚刚的自然语言上下文

不适合存：

- 长期真相
- 当前外部系统状态
- 当前流程精确执行位置

### 2. TaskState

定义位置：

- `agent/memory.go`

作用：

- 保存跨轮次仍然有意义的高层摘要
- 注入 planner / reasoning / final response

持久化 key：

- `agent_task_state_<userID>`

字段：

- `CurrentGoal`
- `ActiveFlow`
- `OpenLoops`
- `ImportantFacts`
- `LastDecision`
- `UpdatedAt`

适合存：

- 当前高层目标
- 跨轮次仍然成立的未闭环事项
- 关键事实
- 最近一次重要决策及其原因

不适合存：

- step 级待办
- “下一步调用哪个 tool”
- 动态余额、持仓、配置存在性
- 任何可以通过 tool 重新读取的实时状态

### 3. ExecutionState

定义位置：

- `agent/execution_state.go`

作用：

- 保存当前 plan 的执行态
- 支持 `ask_user` 之后继续执行
- 保存 plan、当前步骤、执行日志、等待状态等

持久化 key：

- `agent_execution_state_<userID>`

当前关键字段：

- `SessionID`
- `Goal`
- `Status`
- `PlanID`
- `Steps`
- `CurrentStepID`
- `DynamicSnapshots`
- `ExecutionLog`
- `SummaryNotes`
- `Waiting`
- `CurrentReferences`
- `FinalAnswer`
- `LastError`

### 4. CurrentReferences

定义位置：

- `agent/execution_state.go`

作用：

- 记录当前对话里“这个 / 那个 / 刚才那个”到底指的是谁

当前支持的引用对象：

- `strategy`
- `trader`
- `model`
- `exchange`

这是为了解决一种常见问题：

- 用户明明前一轮刚说过“激进策略”
- 下一轮说“改一下这个策略”
- 如果没有结构化引用，模型虽然有聊天历史，也容易重新追问

`CurrentReferences` 不是系统状态快照，而是：

- 当前对话焦点对象
- 当前代词绑定对象

### 5. Persistent Preferences

对应工具：

- `get_preferences`
- `manage_preferences`

作用：

- 保存用户长期偏好

适合存：

- 默认中文回复
- 偏好激进风格
- 更关注 BTC / ETH
- 不喜欢高频
- 每天固定时间简报

它和 `TaskState` 的区别是：

- `TaskState` 偏向当前任务摘要
- `Persistent Preferences` 偏向长期用户画像

## DynamicSnapshots 是什么

`DynamicSnapshots` 是当前真实系统状态的快照。

它不是历史，也不是长期记忆，而是 planner 在规划前或执行中插入的“当前事实”。

当前会进入快照的典型信息包括：

- 当前模型配置列表
- 当前交易所配置列表
- 当前策略列表
- 当前 trader 列表
- 当前余额
- 当前持仓
- 最近交易历史

作用：

- 防止 planner 盲信旧结论
- 避免“之前没配置，现在其实已经配好了却还说没有”
- 避免“之前余额是 A，现在拿旧 observation 继续回答”

一句话：

- `DynamicSnapshots` = 当前世界里真实有什么

## CurrentReferences 和 DynamicSnapshots 的区别

这两个容易混淆，但职责完全不同。

`DynamicSnapshots`：

- 当前系统状态快照
- 是候选集合 / 当前事实
- 例如当前有两个策略：`激进`、`新策略`

`CurrentReferences`：

- 当前对话焦点对象
- 是“这个”到底指谁
- 例如用户现在说的“这个策略”就是 `激进`

可以这样理解：

- `DynamicSnapshots` 是地图
- `CurrentReferences` 是你手指现在指着地图上的哪个点

## Planner 的输入

planner 主逻辑在：

- `agent/planner_runtime.go`

生成计划时，当前会把这些东西一起送给模型：

- 当前用户请求
- tool schema
- `Persistent Preferences`
- `TaskState`
- `ExecutionState`
- `Resume context`
- `Structured waiting state`
- `Observation context`

其中 observation context 不是旧版单数组，而是分层后的：

- `dynamic_snapshots`
- `execution_log`
- `summary_notes`

## Plan 的结构

当前 planner 只允许这 4 类 step：

- `tool`
- `reason`
- `ask_user`
- `respond`

这意味着现在的 Agent 不是一个“自由发挥的回复器”，而是：

- 先规划
- 再执行步骤
- 必要时重规划

## 步骤执行流程

`executePlan(...)` 的核心逻辑是：

1. 找下一个 pending step
2. 标记 step 为 running
3. 执行对应类型
4. 写回 `ExecutionState`
5. 必要时触发 replanning

不同 step 类型行为如下：

### tool

- 调内部 tool
- 把结果写入 `ExecutionLog`
- 根据结果更新 `CurrentReferences`
- 必要时触发 replanner

### reason

- 发起一次短 reasoning 调用
- 生成一段简短中间推理
- 写入 `ExecutionLog`

### ask_user

- 进入 `waiting_user`
- 保存 `WaitingState`
- 把问题直接回给用户

### respond

- 生成最终回答
- 标记当前执行完成

## WaitingState 是什么

`WaitingState` 用来解决：

- 用户回复 `是`
- 用户回复 `继续`
- 用户回复 `那个就行`

这类短回复如果没有结构化等待状态，很容易丢上下文。

当前字段包括：

- `Question`
- `Intent`
- `PendingFields`
- `ConfirmationTarget`
- `CreatedAt`

它的作用是：

- 告诉 planner 上一轮到底在等什么
- 让这轮短回复更容易被理解成“对上一问的回答”

## CurrentReferences 如何更新

当前是双路径更新：

### 1. 用户消息命中对象名时更新

如果用户说：

- `修改激进策略`
- `停止 lky`
- `用 DeepSeek`

系统会去当前用户的策略 / trader / model / exchange 列表里尝试匹配名称或 ID。

匹配成功后，更新 `CurrentReferences`。

### 2. tool 成功返回对象时更新

比如：

- `manage_strategy(create/update/activate)`
- `manage_trader(create/update)`
- `manage_model_config(update)`
- `manage_exchange_config(update)`

只要 tool 返回了具体对象，系统就会把对应 ID / name 写回当前引用。

## Tool 设计

当前 tool 是“资源型 tool”设计，不是“页面动作型 tool”。

### 当前主要工具

配置资源：

- `get_exchange_configs`
- `manage_exchange_config`
- `get_model_configs`
- `manage_model_config`

策略资源：

- `get_strategies`
- `manage_strategy`

trader 资源：

- `manage_trader`

交易 / 查询资源：

- `search_stock`
- `execute_trade`
- `get_positions`
- `get_balance`
- `get_market_price`
- `get_trade_history`

### 为什么这么设计

优点：

- tool schema 稳定
- 行为边界清晰
- planner 更容易学会
- 资源增删改查统一

当前 `manage_strategy` 支持：

- `list`
- `get_default_config`
- `create`
- `update`
- `delete`
- `activate`
- `duplicate`

当前 `manage_trader` 支持：

- `list`
- `create`
- `update`
- `delete`
- `start`
- `stop`

## 为什么“创建策略”不该默认依赖交易所和模型

当前设计里，策略模板应该是独立资源：

- `strategy`

而运行态对象是：

- `trader`

更合理的边界是：

- 创建策略模板：用 `manage_strategy`
- 把策略跑起来：用 `manage_trader`

也就是说：

- 策略不默认依赖交易所和模型
- 只有当用户要求“运行 / 部署 / 创建 trader”时，才需要进一步关联 exchange / model / trader

## 当前一个完整例子

用户输入：

`帮我创建一个新的激进策略模板，名字就叫激进。创建完后，再把这个策略绑定到 trader lky。`

当前大致流程：

1. 前端请求 `/api/agent/chat/stream`
2. 后端注入 `store_user_id`
3. Agent 进入 planner
4. planner 刷新动态快照：
   - 当前策略
   - 当前 trader
5. 生成 plan，例如：
   - `get_strategies`
   - `manage_strategy(create)`
   - `manage_trader(update)`
   - `respond`
6. 执行 `manage_strategy(create)` 后：
   - 写入 `ExecutionLog`
   - 更新 `CurrentReferences.strategy`
7. 执行 `manage_trader(update)` 时：
   - 直接使用刚创建策略的 ID
8. 输出最终回复

如果此后用户继续说：

`把这个策略的 prompt 改激进一点`

系统会优先从 `CurrentReferences.strategy` 理解“这个策略”。

## 为什么看起来“有历史”，模型还是会追问

因为“有聊天历史”不等于“有结构化对象绑定”。

如果没有 `CurrentReferences`：

- 模型只能依赖原话文本推断“这个策略”是谁
- 一旦中间插入多条消息，或者有多个候选策略
- 就容易重新追问

所以当前设计里，`CurrentReferences` 是补齐这一块的关键。

## 当前已知限制

### 1. 外层虽然已经大幅收口，但仍然不是纯 graph runtime

现在比之前更统一，但整体仍然是：

- Agent 主入口
- Planner
- Tool 执行

而不是完整 node-graph 引擎。

### 2. ExecutionState 仍然是按 userID 单槽位

这意味着：

- 同一用户的多个并行任务仍然可能相互影响

更彻底的方向应该是：

- 按 thread / session 多实例存储

### 3. CurrentReferences 目前还是轻量实现

当前只覆盖：

- strategy
- trader
- model
- exchange

后面如果要更强，需要考虑：

- 多候选冲突消解
- 昵称映射
- 跨更长会话的稳定实体绑定

## 当前设计的核心思想

一句话总结：

- `chatHistory` 记原话
- `Persistent Preferences` 记长期偏好
- `TaskState` 记高层摘要
- `ExecutionState` 记当前流程
- `DynamicSnapshots` 记当前事实
- `CurrentReferences` 记当前指代对象
- `planner` 决定步骤
- `tools` 执行落地动作

这就是当前 NOFXi Agent 的实际运行设计。