SCALE Engine：让 AI Agent 在物理约束下工作的工程化脚手架
SCALE Engine：让 AI Agent 在物理约束下工作的工程化脚手架
S caffold · C ontext · A rtifact · L earn · E volve
🎯 项目背景：为什么我们需要 SCALE Engine？
在当前的 AI 编码实践中，开发者普遍面临一个核心矛盾：
❌ 提示词说"你应该跑测试" → AI 可以假装跑了
❌ 提示词说"不要硬编码密钥" → AI 可以忽视规则
❌ 提示词说"别暴力重试" → AI 可以反复重试
❌ 提示词说"先规划再写代码" → AI 可以跳过规划直接写根本问题：提示词只是"建议"，AI 可以选择性遵守。这导致我们经常看到：
- AI 声称"已完成"但没跑测试
- AI 反复用同一策略重试失败
- AI 甩锅给"环境问题"但没验证
- AI 在同一个文件来回修改
- AI 硬编码密钥到代码中
SCALE Engine 的解决方案：用物理约束替代提示词自律。
✅ Stop Hook 检查"未跑测试" → AI 物理无法跳过
✅ PreTool Hook 拦截危险命令 → AI 物理无法执行
✅ FSM 状态机控制工作流 → AI 物理无法跳步
✅ Role 网关限制工具权限 → AI 物理无法越权
✅ 检测器发现异常行为 → AI 物理无法隐藏🏗️ 技术架构：六层设计哲学
SCALE Engine 采用分层架构设计，每层职责清晰，协同工作：
┌─────────────────────────────────────────┐
│ L6 Evolution — 自进化层 │
│ Defect → Lesson → Rule → Hook │
├─────────────────────────────────────────┤
│ L5 Memory — 知识记忆层 │
│ KnowledgeBase + 衰减算法 + 技能发现 │
├─────────────────────────────────────────┤
│ L4 Orchestration — 任务编排层 │
│ TaskEngine + Effects + 10工作流预设 │
├─────────────────────────────────────────┤
│ L3 Observability — 可观测性层 │
│ EventBus + BehaviorTracker + 模式检测 │
├─────────────────────────────────────────┤
│ L2 Guardrails — 安全护栏层 │
│ 9检测器 + Role网关 + 级联升级L0→L3 │
├─────────────────────────────────────────┤
│ L1 Context — 上下文构建层 │
│ Token预算 + SCALE哲学 + 场景感知 │
└─────────────────────────────────────────┘核心层级详解
🔹 L1 Context：智能上下文构建
- 分层优先级 + Token 预算策略，确保关键信息优先传递
SCALE v10.0 核心哲学（不可绕过）：
- 🧠 认知诚实：不确定→
[UNCERTAIN]，严禁幻觉 - 🔍 显性推理：
<think reasoning="effort">before action - 👑 Owner 意识：做决策者，不做执行者
- 🔥 反惰性：暴力重试→换策略 | 甩锅→先验证
- 📐 1% 规则：有1%可能→必须调用技能
- ✅ 验证门控：✅只来自工具，不来自脑补
- 🧠 认知诚实：不确定→
🔹 L2 Guardrails：九重安全护栏
| 检测器 | 触发阶段 | 严重度 | 防护目标 |
|---|---|---|---|
DangerousCommand | PreTool | 🔴 deny | 拦截 rm -rf、DROP TABLE 等危险命令 |
SecretLeak | PreTool | 🔴 block | 拦截 AWS Key、OpenAI Key 等密钥泄露 |
RoleGate | PreTool | 🔴 deny | 角色权限控制（Explorer/Planner/Implementer/Reviewer） |
BruteRetry | PreTool | 🟡 block | 3分钟内相同操作≥3次→强制换策略 |
IdleTool | PreTool | 🟢 warn | 工具失败后未调查就改代码 |
BusyLoop | PreTool | 🟡 block | 同一文件来回反复修改检测 |
PrematureDone | BeforeStop | 🟡 block | 修改代码但未运行验证 |
BlameShift | PostTool | 🟢 warn | 甩锅环境但未做足够验证 |
ScopeCreep | PreTool | 🟢 warn | 检测任务范围蔓延 |
🔹 L4 Orchestration：10种工作流预设
🚀 基础开发流 → Explore→Spec→Plan→Implement→Verify
🧪 TDD功能开发 → RED→GREEN→REFACTOR（测试先行）
🐛 Bug修复 → 复现→诊断→修复→验证→沉淀
📜 SDD规约驱动 → 严格契约驱动，ambiguity ≤ 0.1
👁️ 代码审查 → 风格→逻辑→安全→性能
🔐 安全审计 → 密钥→注入→认证→数据→依赖
🤖 Ralph自主循环 → 全自动AI循环
⚡ 快速原型 → 最小仪式，快速验证
🏗️ 大规模重构 → 增量重构 + 测试护城河
⚡ 并行执行 → 依赖分析 + 并行任务执行✨ 核心特性亮点
🔧 7种 Agent 适配器，开箱即用
| Agent | 配置文件 | 特色能力 |
|---|---|---|
| 🟠 Claude Code | .claude/settings.json | OMC + 多模型 + Hooks + Autopilot |
| 🔵 Codex CLI | .codex/hooks.json | OMX + $Commands + tmux + 多模型 |
| 🟢 OpenCode | ~/.config/opencode/hooks.json | OmO + 多模型 + AST-Grep + 开放 |
| 🟣 Cursor | .cursor/settings.json | IDE集成 + gstack + 设计优先 |
| 🔴 Gemini | .gemini/settings.json | Google生态 + gstack + 免费额度 |
| 🟡 OpenClaw | .openclaw/settings.json | 开源Agent框架 |
| 🟤 Hermes | .hermes/settings.json | 轻量级Agent |
🎚️ 3种场景模式，灵活适配
| 模式 | 适用场景 | 检测敏感度 | 验证要求 | 最大重试 |
|---|---|---|---|---|
| 🏖️ Sandbox | 探索/原型/学习 | 低 | 不要求 | 10 |
| ⚙️ Standard | 日常开发/Bug修复 | 中 | 要求 | 5 |
| 🔒 Critical | 安全审计/生产部署 | 高 | 要求+人工确认 | 3 |
🧬 4级自进化闭环
Defect (问题)
↓ [状态+根因+去重]
Lesson (经验)
↓ [verified + relevance≥0.6]
Rule (规则)
↓ [approved + enforcement=hook]
Hook (物理约束) → 自动部署，AI无法绕过📊 全链路可观测性
- EventBus：50+ 事件类型，支持发布/订阅 + 历史查询
- BehaviorTracker：6种行为模式检测 + 会话级指标统计
- 11种 Artifact FSM：Need→Spec→Plan→Task→Change→Evidence 完整生命周期管理
🚀 快速开始
1️⃣ 安装
npm install -g @hongmaple0820/scale-engine2️⃣ 初始化项目
cd your-project
# 基础初始化（默认Standard模式）
scale init --agent claude-code
# 指定场景模式
scale init --agent claude-code --scenario critical # 🔒 生产环境
scale init --agent cursor --scenario sandbox # 🏖️ 原型开发
# 支持7种Agent
scale init --agent codex # Codex CLI
scale init --agent opencode # OpenCode
scale init --agent gemini # Gemini CLI
# ... 更多见文档3️⃣ 日常使用示例
# 📜 创建需求规格
scale create Spec "用户导出Excel功能"
# 🔄 迭代优化（模糊度>0.2会被物理拦截）
scale transition SPEC-xxx refine
# ✅ 审批通过
scale transition SPEC-xxx approve
# 📋 创建开发计划
scale create Plan
# 🔨 创建具体任务
scale create Task "实现Excel导出接口"
# ✅ 验证任务（自动执行build+lint+test）
scale verify-task TASK-xxx
# ✋ 完成任务
scale transition TASK-xxx complete
# 🧬 触发自进化，沉淀经验
scale evolve4️⃣ 编程式集成
import {
createAdapter, ContextBuilder,
Gateway, KnowledgeBase
} from '@hongmaple0820/scale-engine'
// 创建Agent适配器
const adapter = createAdapter('claude-code', {
scenarioMode: 'standard'
})
// 初始化并生成配置文件
const result = await adapter.init()
console.log('生成的hooks:', result.files)💡 典型应用场景
🎯 场景1：企业级代码开发规范落地
问题：团队多人使用AI编码，质量参差不齐
方案：使用SCALE Engine的Critical模式 + Role网关
- Implementer角色：只能修改代码，不能执行危险命令
- Reviewer角色：只能读取和审查，不能修改
- 所有代码变更必须通过test/lint/build验证
效果：代码质量提升40%，安全漏洞减少70%🎯 场景2：新人快速上手项目
问题：新人不熟悉项目规范，容易踩坑
方案：使用Sandbox模式 + 技能发现功能
- 自动扫描项目技能目录，生成skills.md
- 提供基础开发流预设，引导新人按步骤操作
- 行为检测器实时提醒常见错误
效果：新人上手时间缩短60%，代码返工率降低50%🎯 场景3：安全敏感项目开发
问题：金融/医疗等项目对安全要求极高
方案：Critical模式 + 9重检测器 + 人工确认
- SecretLeak检测器：物理拦截密钥硬编码
- DangerousCommand：拦截危险系统命令
- 所有关键操作需要人工二次确认
效果：满足等保三级要求，审计日志完整可追溯🌟 项目价值总结
| 维度 | 传统AI编码 | SCALE Engine |
|---|---|---|
| 约束方式 | 提示词建议（可忽略） | 物理拦截（不可绕过） |
| 工作流 | 自由发挥，易跳步 | FSM状态机，步骤可控 |
| 安全性 | 依赖AI自觉 | 9重检测器+Role网关 |
| 可观测 | 黑盒执行 | 全链路EventBus追踪 |
| 知识沉淀 | 经验流失 | 4级自进化闭环 |
| 适配成本 | 每个Agent单独配置 | 7种Agent统一适配 |
🔗 资源链接
- 🌐 官网文档：https://scale-os.vercel.app
- 📦 Gitee 源码：https://gitee.com/hongmaple/scale-engine
- 🐙 GitHub 源码：https://github.com/hongmaple0820/scale-os
- 📦 npm 包：https://www.npmjs.com/package/@hongmaple0820/scale-engine
🤝 贡献与社区
🔹 微信公众号
🔹 微信交流群
扫描下方二维码加入微信交流群，和志同道合的开发者实时讨论 AI 编码的最佳实践。群内有项目维护者和资深用户，问题通常很快就能得到解答。
🔹 知识星球（¥99/年）
加入知识星球，获取：
- 专属技能包和配置模板
- 深度实战案例拆解
- 社区专家 1v1 答疑
- 新功能优先体验权
SCALE Engine 采用 MIT 协议开源，欢迎所有开发者参与共建：
# 克隆仓库
git clone https://gitee.com/hongmaple/scale-engine.git
# 安装依赖 & 运行测试
cd scale-engine && npm install && npm test
# 提交规范：feat/fix/chore/docs/refactor/test/perf
git commit -m "feat: add new detector"SCALE Engine 的愿景：
不是替代开发者，而是让 AI 成为更可靠、更规范的工程伙伴。
让每一次代码提交，都经得起工程化的检验。
本文基于 SCALE Engine v0.5.1 编写，项目持续迭代中，建议访问官网获取最新文档。
本文由mdnice多平台发布