change v1

AGENT_IMPLEMENTATION_SPEC.md

@@ -0,0 +1,167 @@
+# AGENT Implementation Spec
+
+## Goal
+重构 Agent 的主循环逻辑：将意图识别、快照管理、字段提取完全交给 LLM 驱动。建立“任务栈”管理机制，确保跨 Skill、中途换话题、回填参数等复杂场景下的状态一致性，并由 DAG 自动化完成执行逻辑。
+
+## 1. Core Principles
+
+### 1.1 必须遵守
+- 大脑前置：每一轮用户输入必须先经过意图识别，禁止规则层先于模型层截断复合语义。
+- 快照优先：LLM 必须感知当前及历史快照（Snapshot/Reference），优先判断输入是否属于对已有任务的续接。
+- DAG 驱动执行：Skill Handler 仅负责原子操作，复杂的逻辑依赖、顺序、确认由 LLM 生成的 DAG 任务包驱动执行。
+
+### 1.2 明确禁止
+- 禁止静默失败：参数越界或逻辑冲突时，必须通过 LLM 反馈给用户原因，禁止直接丢弃输入。
+- 禁止单向路由：禁止在单次意图识别中只认一个 Action，必须支持多 Action 列表化输出。
+
+## 2. Intent Handling
+
+### 2.1 总入口
+所有用户输入都必须先经过统一意图识别：
+- [x] 是
+
+统一意图识别需要判断以下结果：
+- [x] `continue`
+说明：续接当前快照。
+- [x] `switch`
+说明：开启新快照或切换到历史快照。
+- [x] `cancel`
+说明：明确取消当前任务。
+- [x] `instant_reply`
+说明：直接回答，无需进入快照流转。
+
+### 2.2 由谁判断
+意图识别主要由以下方式负责：
+- [x] 大模型
+
+### 2.3 当前 Flow 中的输入
+`continue`：
+- 用户提供了缺失字段。
+- 用户对配置表示确认，例如“OK”“建吧”。
+- 用户对已有配置进行微调。
+
+`switch`：
+- 用户输入了与当前快照领域无关的新需求。
+- 例如正在调策略时突然要查余额。
+- 例如正在配置一个模型时突然要求配置另一个模型。
+
+`cancel`：
+- 用户表达了明确的负面意图。
+- 例如“算了”“不要了”“重来”。
+
+## 3. Slot Extraction / Field Extraction
+
+### 3.1 抽取方式
+字段抽取主要由以下方式负责：
+- [x] 大模型
+
+如果由大模型负责，抽取时必须输入以下上下文：
+- [x] 当前 `skill/action`
+- [x] 当前 `draft/session`
+- [x] 当前缺失字段（来自 DAG 定义）
+- [x] 历史对话（近 3 轮）
+- [x] 快照 / 当前引用
+
+### 3.2 输出格式
+期望大模型返回如下结构化 JSON：
+
+```json
+{
+  "intent": "continue | switch | cancel",
+  "target_snapshot_id": "uuid-xxxx",
+  "tasks": [
+    {
+      "skill": "strategy",
+      "action": "create",
+      "fields": {
+        "leverage": 20,
+        "name": "my_strat"
+      }
+    }
+  ],
+  "reason": "用户提供了杠杆倍数，继续策略创建流程"
+}
+```
+
+### 3.3 合并策略
+- 补全模式：新抽取的字段 merge 到原快照中。
+- 覆盖模式：若用户明确修改已存在的值，以最新输入为准，但必须经过 Validator 重新校验。
+
+## 4. Flow / State Machine
+
+### 4.1 统一状态机
+所有 flow 必须统一走同一个 orchestrator：
+- [x] 是
+
+Flow 状态至少包含：
+- [x] `collecting`
+说明：字段收集中。
+- [x] `waiting_confirmation`
+说明：待用户确认。
+- [x] `ready`
+说明：校验通过。
+- [x] `executing`
+说明：DAG 执行中。
+- [x] `suspended`
+说明：被新任务压栈挂起。
+
+### 4.2 Switch / Suspend / Resume
+用户切换话题时，当前任务应该：
+- [x] 压栈
+说明：放入 History Snapshots 栈，支持后续唤回。
+
+## 5. Skill Scope
+
+### 5.1 适用范围
+这套方法模式适用于：
+- [x] 全部
+说明：实现全架构的语义编排。
+
+### 5.2 不允许单独补丁
+是否禁止只针对单个 skill / 单句子打补丁：
+- [x] 是
+
+补充说明：
+- 必须保证所有 Skill 共享同一套 Router 和快照机制。
+
+## 6. Risk Control / Validation
+
+### 6.1 校验层
+字段抽取后必须统一进入 validator：
+- [x] 是
+
+validator 需要覆盖：
+- [x] `strategy` 数值限制（Clamp）
+- [x] `model` 配置合法性
+- [x] `exchange` 凭证合法性
+- [x] `trader` 绑定关系合法性
+
+### 6.2 错误提示
+- 提示原则：LLM 解析校验失败结果，用自然语言告知用户安全范围。
+- 示例：`杠杆最高 20 倍，已为您设为 20，是否接受？`
+
+## 7. Performance
+
+### 7.1 调用策略
+- 流式响应：意图识别确定后，第一时间返回“正在处理[某意图]...”，减少用户感知延迟。
+- LLM Cache：对高频重复意图进行缓存。
+
+### 7.2 快路径
+允许不用大模型直接返回的场景：
+- 简单打招呼，例如 `Hi`、`Hello`
+- 完全匹配的单词退出指令，例如 `exit`、`quit`
+
+## 8. Testing / Acceptance
+
+### 8.1 必测场景
+- 意图切换：正在创建策略时，询问“比特币价格”，查完后回答“继续创建刚才的策略吗”并成功恢复快照。
+- 多动作合并：一句话同时完成“创建策略 A”和“配置交易所 B”。
+- 纠错重填：用户输入了错误的杠杆倍数，系统提示纠正后，用户补填正确数值，系统能正确合并到原快照。
+
+### 8.2 验收标准
+- 无静默吞咽：任何有效信息必须体现在快照更新或回复中。
+- 快照一致性：`CurrentReferences` 必须能精准映射到用户口中的“它”或“那个策略”。
+
+## 9. Notes
+- 快照快照还是快照：代码底层必须实现一个 `SnapshotManager`，支持 `Save/Load/List` 动作，供 LLM 通过特定的内部 Tool 进行调用。
+- DAG 是约束而非死板流程：DAG 告诉 LLM 缺什么，但 LLM 决定如何通过对话向用户要到这些。