majiayu000 Sage-core 模块指南
模块总览（36 个模块）
sage-core/src/
├── agent/ # 核心执行引擎
├── builder/ # 构建器模式
├── cache/ # 缓存系统
├── checkpoints/ # 状态快照 ⭐ 独有
├── commands/ # 斜杠命令
├── concurrency/ # 并发管理
├── config/ # 配置加载
├── context/ # 上下文管理
├── cost/ # 成本追踪
├── error/ # 错误定义
├── events/ # 事件总线
├── hooks/ # 钩子系统
├── input/ # 输入处理
├── interrupt/ # 中断管理
├── learning/ # 学习系统 ⭐ 独有
├── llm/ # LLM 抽象
├── mcp/ # MCP 协议
├── memory/ # 长期记忆
├── modes/ # 模式管理
├── output/ # 输出格式化
├── plugins/ # 插件系统
├── prompts/ # Prompt 模板
├── recovery/ # 恢复系统 ⭐ 独有
├── sandbox/ # 沙箱执行 ⭐ 独有
├── session/ # 会话管理
├── settings/ # 运行时设置
├── skills/ # 技能系统
├── storage/ # 持久化
├── telemetry/ # 遥测统计
├── tools/ # 工具系统
├── trajectory/ # 轨迹记录
├── types/ # 公共类型
├── ui/ # 终端 UI
├── utils/ # 工具函数
├── validation/ # 验证系统
└── workspace/ # 工作区分析
核心模块详解
agent/ - 执行引擎
职责：Agent 生命周期管理、执行循环、状态转换
agent/
├── mod.rs # 公开接口
├── unified/ # 统一执行器（主要）
│ ├── executor.rs # 执行循环
│ ├── llm_orchestrator.rs # LLM 调度
│ └── step_processor.rs # 步骤处理
├── lifecycle/ # 生命周期
│ ├── manager.rs # 管理器
│ ├── hooks/ # 生命周期钩子
│ └── phase.rs # 阶段定义
├── state.rs # Agent 状态
├── step.rs # 执行步骤
└── completion.rs # 完成检测
关键类型：
pub struct UnifiedExecutor { ... }
pub struct AgentExecution { ... }
pub enum AgentState { Idle, Running, Waiting, Completed, Failed }
pub struct AgentStep { ... }
扩展点：
- 实现
LifecycleHook添加生命周期钩子 - 扩展
ExecutionMode添加执行模式
llm/ - LLM 抽象层
职责：多提供者支持、流式处理、降级策略
llm/
├── mod.rs
├── client.rs # 客户端 trait
├── providers/ # 提供者实现
│ ├── anthropic.rs
│ ├── openai.rs
│ ├── google.rs
│ ├── glm.rs
│ └── ...
├── fallback/ # 降级策略
├── parsers/ # 响应解析
├── converters/ # 格式转换
└── rate_limiter/ # 限流
关键类型：
#[async_trait]
pub trait LlmClient {
async fn chat(&self, request: ChatRequest) -> Result<LlmResponse>;
async fn chat_stream(&self, request: ChatRequest) -> Result<impl Stream<Item = StreamEvent>>;
}
pub enum LlmProvider { Anthropic, OpenAI, Google, Glm, ... }
扩展点：
- 实现
LlmClient添加新提供者 - 在
fallback/中配置降级链
tools/ - 工具系统
职责：工具注册、执行、权限管理、结果缓存
tools/
├── mod.rs
├── base/ # 基础定义
│ ├── tool.rs # Tool trait
│ ├── schema.rs # JSON Schema
│ └── result.rs # 执行结果
├── executor/ # 执行器
├── permission/ # 权限系统
│ ├── rules.rs
│ └── handlers.rs
├── parallel_executor/ # 并行执行
├── tool_cache/ # 结果缓存
└── registry.rs # 工具注册表
关键类型：
#[async_trait]
pub trait Tool: Send + Sync {
fn name(&self) -> &str;
fn description(&self) -> &str;
fn schema(&self) -> ToolSchema;
async fn execute(&self, call: &ToolCall) -> Result<ToolResult, ToolError>;
}
pub struct ToolExecutor { ... }
pub struct ToolRegistry { ... }
扩展点：
- 实现
Tooltrait 添加新工具 - 在
permission/rules.rs添加权限规则
recovery/ - 恢复系统 ⭐ Sage 独有
职责：熔断器、限流器、重试策略、任务监督
recovery/
├── mod.rs
├── circuit_breaker/ # 熔断器
│ ├── breaker.rs
│ ├── config.rs
│ └── registry.rs
├── rate_limiter/ # 限流器
│ ├── sliding_window.rs
│ └── token_bucket.rs
└── supervisor/ # 任务监督
├── policy.rs
└── supervisor.rs
关键类型：
pub struct CircuitBreaker { ... }
pub enum CircuitState { Closed, Open, HalfOpen }
pub struct SlidingWindowRateLimiter { ... }
pub struct TokenBucketRateLimiter { ... }
pub struct TaskSupervisor { ... }
pub enum SupervisionPolicy { Restart, Resume, Stop }
使用示例：
// 熔断器
let breaker = CircuitBreaker::new(CircuitBreakerConfig {
failure_threshold: 5,
recovery_timeout: Duration::from_secs(30),
..Default::default()
});
breaker.call(|| async {
llm_client.chat(request).await
}).await?;
// 限流器
let limiter = SlidingWindowRateLimiter::new(100, Duration::from_secs(60));
limiter.acquire().await?;
learning/ - 学习系统 ⭐ Sage 独有
职责：模式识别、用户偏好学习、纠正记录
learning/
├── mod.rs
├── engine/ # 学习引擎
│ ├── engine.rs
│ └── config.rs
├── patterns/ # 模式检测
│ ├── detector.rs
│ └── types.rs
└── types/ # 类型定义
├── correction.rs
├── pattern.rs
└── preference.rs
关键类型：
pub struct LearningEngine { ... }
pub struct Pattern {
pub id: PatternId,
pub pattern_type: PatternType,
pub confidence: f32,
pub occurrences: usize,
}
pub struct CorrectionRecord {
pub original: String,
pub corrected: String,
pub reason: Option<String>,
}
checkpoints/ - 检查点系统 ⭐ Sage 独有
职责：状态快照、文件变更追踪、回滚恢复
checkpoints/
├── mod.rs
├── manager.rs # 检查点管理器
├── storage.rs # 存储接口
│ ├── file.rs # 文件存储
│ └── memory.rs # 内存存储
├── snapshot.rs # 快照类型
├── diff.rs # 差异计算
└── restore.rs # 恢复逻辑
关键类型：
pub struct CheckpointManager { ... }
pub struct Checkpoint {
pub id: CheckpointId,
pub created_at: DateTime<Utc>,
pub file_states: Vec<FileSnapshot>,
pub conversation: ConversationSnapshot,
}
pub struct RestoreOptions {
pub restore_files: bool,
pub restore_conversation: bool,
}
skills/ - 技能系统
职责：Skill 发现、加载、匹配、激活
skills/
├── mod.rs
├── registry.rs # 技能注册表
├── types.rs # 类型定义
├── loader.rs # SKILL.md 加载器
└── watcher.rs # 热重载监视器
关键类型：
pub struct SkillRegistry { ... }
pub struct Skill {
pub metadata: SkillMetadata,
pub prompt: String,
pub triggers: Vec<SkillTrigger>,
pub when_to_use: Option<String>,
pub available_tools: ToolAccess,
}
pub struct SkillContext { ... }
pub struct SkillActivation { ... }
模块依赖关系
┌─────────────────┐
│ agent │
└────────┬────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ llm │ │ tools │ │ skills │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ sandbox │ │
│ └──────────┘ │
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│recovery │ │ prompts │
└─────────┘ └─────────┘
│
▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ context │ ←── │ session │ ←── │ memory │
└─────────┘ └─────────┘ └─────────┘
│
▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ storage │ ←── │ config │ ←── │settings │
└─────────┘ └─────────┘ └─────────┘
扩展指南
添加新 LLM 提供者
- 在
llm/providers/创建new_provider.rs - 实现
LlmClienttrait - 在
LlmProviderenum 添加变体 - 在配置中添加支持
添加新工具
参见 /sage-tool-development skill
添加新模式
- 在
modes/创建模式定义 - 实现
AgentModetrait - 在
ModeManager注册
添加新钩子类型
- 在
hooks/types.rs定义事件类型 - 在
HookRegistry添加注册方法 - 在相应位置触发钩子
代码规范速查
// 模块命名
pub mod rate_limiter; // 正确
pub mod rateLimiter; // 错误
// 类型命名 (RFC 430)
struct LlmClient; // 正确
struct LLMClient; // 错误
// 错误处理
fn do_something() -> Result<T, Error>; // 正确
fn do_something() -> T { x.unwrap() } // 错误
// 异步代码
async fn fetch() -> Result<Data>; // 正确
fn fetch() -> Data { block_on() } // 错误