sage-architecture - SKILL.md Agent Skill

name: sage-architecture description: Sage 项目整体架构设计指南，基于 Claude Code、Crush 最佳实践的融合方案 when_to_use: 当涉及 Sage 项目架构设计、模块规划、重构决策时使用 allowed_tools: - Read - Grep - Glob - Edit - Write - Bash user_invocable: true priority: 100

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-cli
sage-tools 依赖 sage-sdk
循环依赖

新模块检查清单

创建新模块前确认：

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

文件结构模板

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

mod submodule1;
mod submodule2;

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

// 私有实现（如果有）