majiayu000 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 独有优势（必须保持）
| 模块 | 功能 | 竞品对比 |
|---|---|---|
recovery/ |
熔断器、限流器、supervisor | OpenClaude/Crush 无 |
learning/ |
模式学习、用户偏好 | OpenClaude/Crush 无 |
checkpoints/ |
状态快照、回滚恢复 | OpenClaude/Crush 无 |
storage/ |
多后端(SQLite/Postgres) | Crush 仅 SQLite |
sandbox/ |
安全沙箱执行 | OpenClaude/Crush 无 |
绝不删除这些模块，它们是 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
模块重组方案
需要合并的模块
| 当前 | 合并到 | 原因 |
|---|---|---|
settings/ |
config/ |
功能重叠 |
session/ |
context/ |
会话是上下文的一部分 |
sandbox/ |
tools/sandbox/ |
沙箱服务于工具执行 |
modes/ |
agent/modes/ |
模式是 agent 的状态 |
cost/ |
telemetry/cost/ |
成本是遥测的一部分 |
需要拆分的模块
| 当前 | 拆分为 | 原因 |
|---|---|---|
llm/ 过大 |
llm/{client,providers,streaming,fallback}/ |
文件超 200 行 |
agent/unified/ |
agent/executor/{loop,step,completion}/ |
职责过多 |
命名规范
类型命名（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-clisage-tools依赖sage-sdk- 循环依赖
新模块检查清单
创建新模块前确认：
- 是否真的需要新模块？能否放入现有模块？
- 模块职责单一吗？
- 预计代码量 < 200 行吗？
- 与现有模块的边界清晰吗？
- 命名符合 RFC 430 吗？
- 有对应的测试模块吗？
文件结构模板
//! 模块简短描述
//!
//! 详细说明（可选）
mod submodule1;
mod submodule2;
pub use submodule1::PublicType;
pub use submodule2::public_function;
// 私有实现（如果有）