Sage 项目架构指南

核心设计原则

1. 模块边界原则

每个模块 < 200 行，超过则拆分为子模块。

正确 ✓
src/tools/
├── mod.rs           # 公开接口 (~50行)
├── registry.rs      # 注册表 (~150行)
├── executor.rs      # 执行器 (~180行)
└── permission/      # 子模块
    ├── mod.rs
    ├── rules.rs
    └── handlers.rs

错误 ✗
src/tools/
├── mod.rs           # 800行的巨型文件

2. 层级职责分离

┌─────────────────────────────────────────────────────────────┐
│                      sage-cli (用户界面)                      │
├─────────────────────────────────────────────────────────────┤
│                      sage-sdk (高级 API)                      │
├─────────────────────────────────────────────────────────────┤
│                     sage-core (核心引擎)                       │
│  ┌─────────┬─────────┬─────────┬─────────┬─────────┐       │
│  │  agent  │   llm   │  tools  │ skills  │ context │       │
│  ├─────────┼─────────┼─────────┼─────────┼─────────┤       │
│  │recovery │learning │checkpoint│  mcp   │ storage │       │
│  └─────────┴─────────┴─────────┴─────────┴─────────┘       │
├─────────────────────────────────────────────────────────────┤
│                    sage-tools (工具实现)                      │
└─────────────────────────────────────────────────────────────┘

3. Sage 独有优势（必须保持）

绝不删除这些模块，它们是 Sage 的核心竞争力。

4. 学习 Crush 的简洁模式

Prompt 模板化（而非硬编码）：

prompts/
├── templates/
│   ├── coder.md.tpl      # 主 system prompt
│   ├── task.md.tpl       # 任务 prompt
│   └── initialize.md.tpl # 初始化 prompt
├── renderer.rs           # 模板渲染器
└── variables.rs          # 变量定义

工具描述文件（TOOL.md）：

tools/builtin/
├── bash/
│   ├── mod.rs      # 实现
│   └── TOOL.md     # 描述（注入 system prompt）
├── edit/
│   ├── mod.rs
│   └── TOOL.md

模块重组方案

需要合并的模块

需要拆分的模块

命名规范

类型命名（RFC 430）

// 正确 ✓ - 缩写词当作普通单词
LlmClient, SseDecoder, McpServer, HttpRequest

// 错误 ✗ - 全大写缩写
LLMClient, SSEDecoder, MCPServer, HTTPRequest

模块命名

// 正确 ✓ - 小写下划线
pub mod rate_limiter;
pub mod circuit_breaker;

// 错误 ✗ - 驼峰或连字符
pub mod rateLimiter;
pub mod circuit-breaker;

依赖关系规则

sage-cli → sage-sdk → sage-core → sage-tools
                ↓
           外部 crates (tokio, serde, etc.)

禁止：

• sage-core 依赖 sage-cli
• sage-tools 依赖 sage-sdk
• 循环依赖

新模块检查清单

创建新模块前确认：

• 是否真的需要新模块？能否放入现有模块？
• 模块职责单一吗？
• 预计代码量 < 200 行吗？
• 与现有模块的边界清晰吗？
• 命名符合 RFC 430 吗？
• 有对应的测试模块吗？

文件结构模板

//! 模块简短描述
//!
//! 详细说明（可选）

mod submodule1;
mod submodule2;

pub use submodule1::PublicType;
pub use submodule2::public_function;

// 私有实现（如果有）