完善文档

docs/agent/README.md

@@ -0,0 +1,3 @@
+# Agent
+
+Agent Runtime 与认知架构文档目录。

docs/agent/execution.md

@@ -0,0 +1,24 @@
+# Agent Execution
+
+## 执行阶段
+
+1. 创建 Run
+2. 构建上下文
+3. 召回记忆
+4. 生成计划
+5. 执行步骤
+6. 获取观察
+7. 验证结果
+8. 重规划或完成
+9. 记录经验
+
+## 长任务
+
+长任务必须：
+
+- 持久化状态
+- 可查询
+- 可恢复
+- 可取消
+- 可超时
+- 可审计

docs/agent/memory.md

@@ -0,0 +1,67 @@
+# Agent Memory Architecture
+
+## 六层记忆
+
+### Working Memory
+
+当前上下文、任务状态、临时变量。
+
+### Episodic Memory
+
+历史事件、对话、任务经历、重要决策。
+
+### Semantic Memory
+
+事实、概念、实体、知识。
+
+### Procedural Memory
+
+技能、策略、流程和经验方法。
+
+### Social Memory
+
+用户、关系、偏好、交互模式。
+
+### Identity Memory
+
+Agent 身份、长期经历、目标、自我认知。
+
+## Memory Manager
+
+统一负责：
+
+`write -> classify -> store -> retrieve -> consolidate -> update -> forget`
+
+## 存储
+
+```mermaid
+flowchart LR
+    MemoryManager --> Redis["Working / Runtime State"]
+    MemoryManager --> PostgreSQL["Structured Long-term Memory"]
+    MemoryManager --> VectorStore["Semantic Retrieval"]
+    MemoryManager --> GraphStore["Relationship Memory"]
+```
+
+## 重要性
+
+不是所有对话都进入长期记忆。应结合重要性、稳定性、重复度、未来价值和用户明确意图进行判断。
+
+## 记忆生命周期
+
+```mermaid
+flowchart LR
+    Experience --> Candidate
+    Candidate --> Evaluate
+    Evaluate --> Consolidate
+    Consolidate --> LongTerm
+    LongTerm --> Retrieve
+    Retrieve --> Update
+    Update --> Forget
+```
+
+## 原则
+
+- 事实和推断分离。
+- 推断必须标记来源和置信度。
+- 重要记忆应保留来源和时间。
+- 记忆更新必须可追踪。

docs/agent/model-system.md

@@ -0,0 +1,22 @@
+# Model System
+
+## 目标
+
+统一管理：
+
+- LLM
+- Embedding
+- Reranker
+- Vision
+- Speech-to-Text
+- Text-to-Speech
+
+## Model Gateway
+
+Agent Runtime 不直接绑定单一模型供应商。
+
+统一抽象：
+
+`Provider -> Model -> Capability -> Request -> Response`
+
+支持 OpenAI SDK、LiteLLM 及本地模型。

docs/agent/overview.md

@@ -0,0 +1,32 @@
+# Agent 认知架构
+
+## 核心闭环
+
+```mermaid
+flowchart LR
+    Perception["感知"] --> Context["上下文"]
+    Context --> Memory["记忆"]
+    Memory --> Understanding["理解"]
+    Understanding --> Planning["规划"]
+    Planning --> Decision["决策"]
+    Decision --> Action["行动"]
+    Action --> Observation["反馈"]
+    Observation --> Reflection["反思"]
+    Reflection --> Learning["学习"]
+    Learning --> Memory
+```
+
+## 主要能力
+
+- Runtime
+- Memory
+- Planning
+- Reasoning
+- Reflection
+- Tool Use
+- Model Use
+- Learning
+- Self Model
+- World Model
+
+当前阶段重点实现 Runtime、Memory、Planning、Tool、RAG；World Model 与 Self Model 保持可扩展接口。

docs/agent/planning.md

@@ -0,0 +1,51 @@
+# Planning
+
+## 目标
+
+将用户目标转换为可执行、可验证、可恢复的任务计划。
+
+## 模式
+
+### Plan-and-Execute
+
+适合目标明确、步骤较稳定的复杂任务。
+
+### ReAct
+
+适合需要根据环境反馈动态决定下一步的任务。
+
+### Dynamic Replanning
+
+当计划假设失效、工具失败或新信息出现时重新规划。
+
+## 闭环
+
+```mermaid
+flowchart TD
+    Goal --> Understand
+    Understand --> Decompose
+    Decompose --> Plan
+    Plan --> Execute
+    Execute --> Observe
+    Observe --> Evaluate
+    Evaluate -->|success| Finish
+    Evaluate -->|failure| Reflect
+    Reflect --> Replan
+    Replan --> Execute
+```
+
+## 计划对象
+
+计划至少应包含：
+
+- goal
+- steps
+- dependencies
+- expected_output
+- constraints
+- status
+- retry_policy
+
+## 原则
+
+计划不是不可变脚本；执行过程中的观察可以触发局部或全局重规划。

docs/agent/reasoning.md

@@ -0,0 +1,29 @@
+# Reasoning
+
+## 推理职责
+
+- 任务理解
+- 假设生成
+- 证据分析
+- 工具选择
+- 结果验证
+- 错误诊断
+
+## ReAct
+
+`Thought/Reasoning -> Action -> Observation`
+
+实际系统不要求暴露模型内部思维链。对外只输出必要的状态、依据和工具事件。
+
+## Reflection
+
+反思不是无条件重复推理，应在以下情况触发：
+
+- 工具失败
+- 结果与目标不一致
+- 关键约束未满足
+- 新信息推翻原假设
+
+## 验证
+
+最终结果应尽可能进行结构化验证，而不是只依赖 LLM 自评。

docs/agent/reflection.md

@@ -0,0 +1,24 @@
+# Reflection
+
+## 目标
+
+通过执行结果发现错误、总结经验并修正后续行为。
+
+## 类型
+
+- Step Reflection：单步骤反思
+- Run Reflection：一次任务结束后的反思
+- Experience Consolidation：把经验沉淀为长期记忆
+- Strategy Reflection：更新策略
+
+## 原则
+
+反思必须产生可执行结果，例如：
+
+- 修改计划
+- 更换工具
+- 调整参数
+- 增加验证
+- 写入经验
+
+避免“反思但不改变行为”。

docs/agent/runtime.md

@@ -0,0 +1,22 @@
+# Agent Runtime
+
+## 职责
+
+- Agent 生命周期
+- Session / Run 管理
+- 上下文组装
+- 模型调用
+- Tool 调度
+- 状态机
+- 事件发布
+- 错误恢复
+- 运行追踪
+
+## 不负责
+
+- 具体数据库实现
+- 具体向量数据库
+- 前端 UI
+- 外部服务业务逻辑
+
+Runtime 应通过接口调用这些能力。

docs/agent/tool-system.md

@@ -0,0 +1,28 @@
+# Tool System
+
+## 架构
+
+```mermaid
+flowchart LR
+    Registry["Tool Registry"] --> Discovery["Discovery"]
+    Discovery --> Permission["Permission"]
+    Permission --> Validation["Schema Validation"]
+    Validation --> Runtime["Execution"]
+    Runtime --> Normalize["Result Normalize"]
+    Normalize --> Audit["Audit"]
+```
+
+## Tool 必须具备
+
+- name
+- description
+- input schema
+- output schema
+- permission
+- timeout
+- retry policy
+- version
+
+## 统一原则
+
+Agent 不直接执行任意外部能力。所有工具调用必须经过 Tool Runtime。