孙雪健的数字花园

原-AI母体-设计

8分钟阅读

「原」最小种子 Agent — 设计文档

日期: 2026-06-06 阶段: 设计阶段（② 设计） 状态: 待用户确认

1. 设计决策（ADR）

ADR-001: 架构模式选择

决策：从零构建核心循环，不依赖 LangGraph/CrewAI 等框架

Why：

  • 最小种子需要纯粹的理解和完全掌控
  • 避免框架学习曲线，专注核心机制
  • 为后续扩展预留空间（可迁移到框架）

What：

  • 手写 ReAct 循环（Thought → Action → Observation）
  • 依赖注入的组件设计（LLM、工具、记忆）
  • 简单的状态机

How：

┌─────────────────────────────────────┐
│  ReAct Loop Controller              │
│  (手动实现，不依赖框架)               │
└─────────────────────────────────────┘
         │
         ├─► Planner（规划器）
         ├─► Executor（执行器）
         ├─► Memory（记忆）
         └─► Tools（工具）

ADR-002: 记忆系统规模

决策：仅实现短期记忆 + 可选向量记忆（不写代码，仅设计接口）

Why：

  • 记忆模块开发成本高，初期非核心
  • 短期记忆（对话缓冲）已满足 ReAct 循环需求
  • 向量记忆延后到验证阶段

What：

  • 短期记忆：线程作用域的对话缓冲
  • 向量记忆：空接口 + 理论设计，不实现

How：

class Memory:
    def add_short_term(self, message: dict):
        """添加到对话缓冲"""
        pass
 
    def retrieve_short_term(self, query: str) -> list:
        """从对话缓冲检索上下文"""
        pass
 
    def add_semantic(self, key: str, value: str, embedding: list):
        """语义记忆占位接口"""
        pass
 
    def retrieve_semantic(self, query: str, top_k: int = 5) -> list:
        """语义记忆检索占位接口"""
        pass

ADR-003: 工具集范围

决策：限定为内部操作工具，不实现外部 API 工具

Why：

  • 外部工具需要 API Key、沙箱、权限管理等复杂度
  • 最小种子应聚焦核心循环的正确性
  • 工具可后续扩展（文件读写、代码执行等）

What：

  • 内部工具：
    • list_files: 列出目录文件
    • read_file: 读取文件内容
    • write_file: 写入文件
    • execute_command: 执行系统命令（沙箱）

How：

class ToolRegistry:
    def register(self, name: str, func: Callable, schema: dict):
        """注册工具"""
 
    def call(self, name: str, args: dict) -> dict:
        """调用工具，带错误处理"""
        pass

ADR-004: 错误处理策略

决策：实现最大迭代限制 + 断路器 + 检查点恢复

Why：

  • 无限循环是 Agent 开发最常见的 bug
  • 检查点恢复是调试和用户体验的基础

What：

  • 最大迭代次数（默认 10）
  • 断路器（连续失败 X 次后停止）
  • 简单检查点（保存状态到临时文件）

How：

class CircuitBreaker:
    def __init__(self, failure_threshold: int = 3):
        self.failures = 0
 
    def record_failure(self):
        self.failures += 1
        if self.failures >= self.failure_threshold:
            raise RuntimeError("Circuit breaker tripped")
 
    def record_success(self):
        self.failures = 0

2. 最小种子需求（MVP）

2.1 核心能力

能力实现状态说明
感知（Perception）✅ 完成短期记忆提供上下文感知
推理（Reasoning）✅ 完成ReAct 循环实现推理链
行动（Action）✅ 完成工具调用机制

2.2 限定范围

范围决策原因
框架依赖无从零构建核心循环
记忆系统仅短期记忆降低开发成本
工具集内部工具避免外部复杂性
多 Agent单 Agent最小种子聚焦核心
自我进化不实现延后到后续版本
向量记忆接口设计延后实现

2.3 非功能需求

需求要求说明
可观测性日志 + 指标记录每个 Thought/Action/Observation
错误处理断路器 + 最大迭代防止无限循环
可测试性依赖注入每个组件可独立测试
可扩展性模块化设计未来易于添加新功能

3. 系统架构

3.1 层次结构

┌─────────────────────────────────────────────────────┐
│  App Layer (CLI/Streamlit)                          │
│  - 用户交互入口                                      │
│  - 流式输出                                          │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│  Orchestrator Layer (Agent Loop)                    │
│  - ReAct 循环控制器                                  │
│  - 状态机管理                                        │
│  - 错误处理                                          │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│  Component Layer (核心模块)                         │
│  - Planner（规划器）                                 │
│  - Executor（执行器）                                │
│  - Memory（记忆）                                    │
│  - Tools（工具）                                    │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│  Infrastructure Layer                               │
│  - LLM Adapter（LLM 适配器）                         │
│  - Logging（日志）                                   │
│  - Config（配置）                                    │
└─────────────────────────────────────────────────────┘

3.2 数据流

User Input
    │
    ▼
┌──────────────────┐
│ Orchestrator     │
│ - 初始化状态      │
│ - 调用 Planner   │
└──────────────────┘
    │
    ▼
┌──────────────────┐
│ Planner          │
│ - 生成 Thought   │
│ - 调用 Executor  │
└──────────────────┘
    │
    ▼
┌──────────────────┐
│ Executor         │
│ - 选择工具        │
│ - 调用 Tool      │
│ - 获取 Observation│
└──────────────────┘
    │
    ▼
┌──────────────────┐
│ Memory           │
│ - 存储对话缓冲    │
│ - 检索上下文      │
└──────────────────┘
    │
    ▼
循环 → 直到最终答案或超限

4. 技术栈

层级技术选择说明
语言Python 3.10+成熟的 AI 生态
LLMClaude / Gemini / Kimi可插拔适配器
CLIargparse简单命令行入口
日志logging 模块标准库，足够
测试pytest行业标准
部署单脚本 + requirements.txt最小化依赖

5. 开发计划

5.1 阶段划分

阶段任务产出
Phase 1核心模块实现agent_loop.py, planner.py, executor.py
Phase 2工具集实现tools.py, 内部工具实现
Phase 3记忆系统（短期）memory.py, 对话缓冲
Phase 4可观测性日志、指标
Phase 5集成与测试完整循环测试

5.2 验收标准

  • ✅ ReAct 循环完整跑通（Thought → Action → Observation）
  • ✅ 最大迭代限制生效
  • ✅ 工具调用正确执行
  • ✅ 日志完整记录
  • ✅ 单元测试覆盖核心逻辑

6. 风险与缓解

风险影响缓解措施
无限循环高最大迭代限制 + 断路器
幻觉问题中严格工具调用 + 错误处理
记忆泄漏中定期清理短期记忆
性能问题低轻量级设计，延迟不是首要

7. 下一步

待用户确认：

  1. ✅ 架构模式选择（ADR-001）是否同意？
  2. ✅ 记忆系统规模（ADR-002）是否同意？
  3. ✅ 工具集范围（ADR-003）是否同意？
  4. ✅ 错误处理策略（ADR-004）是否同意？

确认后进入构建阶段：

  • 创建模块文件
  • 实现 ReAct 循环
  • 实现 Planner/Executor
  • 实现工具集
  • 编写测试

关系图谱