القائمة
Sage 项目整体架构设计指南，基于 Claude Code、Crush 最佳实践的融合方案
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
跨语言代码库健康治理与自动优化系统。基于学术研究和实战经验，系统性检测 LLM 生成代码的结构性缺陷。完整流程：SCAN → DIAGNOSE → FIX → HARDEN。适用于任何语言的项目。
Sage 到 Tink UI 框架的完全重构指南，包含迁移步骤、文件清单、架构设计
Sage 版本管理规范，包含语义化版本、CHANGELOG、发布流程
Sage CLI UI 设计规范，参考 Claude Code 的终端显示模式，包含对齐、颜色、图标等设计标准
Sage Agent 执行引擎开发指南，涵盖 UnifiedExecutor、Subagent、Lifecycle 管理
Sage 独有的检查点系统设计，包含状态快照、文件追踪、回滚恢复机制
| 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 |
每个模块 < 200 行，超过则拆分为子模块。
正确 ✓
src/tools/
├── mod.rs # 公开接口 (~50行)
├── registry.rs # 注册表 (~150行)
├── executor.rs # 执行器 (~180行)
└── permission/ # 子模块
├── mod.rs
├── rules.rs
└── handlers.rs
错误 ✗
src/tools/
├── mod.rs # 800行的巨型文件
┌─────────────────────────────────────────────────────────────┐
│ sage-cli (用户界面) │
├─────────────────────────────────────────────────────────────┤
│ sage-sdk (高级 API) │
├─────────────────────────────────────────────────────────────┤
│ sage-core (核心引擎) │
│ ┌─────────┬─────────┬─────────┬─────────┬─────────┐ │
│ │ agent │ llm │ tools │ skills │ context │ │
│ ├─────────┼─────────┼─────────┼─────────┼─────────┤ │
│ │recovery │learning │checkpoint│ mcp │ storage │ │
│ └─────────┴─────────┴─────────┴─────────┴─────────┘ │
├─────────────────────────────────────────────────────────────┤
│ sage-tools (工具实现) │
└─────────────────────────────────────────────────────────────┘
| 模块 | 功能 | 竞品对比 |
|---|---|---|
recovery/ | 熔断器、限流器、supervisor | OpenClaude/Crush 无 |
learning/ | 模式学习、用户偏好 | OpenClaude/Crush 无 |
checkpoints/ | 状态快照、回滚恢复 | OpenClaude/Crush 无 |
storage/ | 多后端(SQLite/Postgres) | Crush 仅 SQLite |
sandbox/ | 安全沙箱执行 | OpenClaude/Crush 无 |
绝不删除这些模块，它们是 Sage 的核心竞争力。
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}/ | 职责过多 |
// 正确 ✓ - 缩写词当作普通单词
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创建新模块前确认：
//! 模块简短描述
//!
//! 详细说明（可选）
mod submodule1;
mod submodule2;
pub use submodule1::PublicType;
pub use submodule2::public_function;
// 私有实现（如果有）