50行声明编译出1400行生产运行时SmallCode的MarrowScript认知层工作原理【免费下载链接】smallcodeAI coding agent optimized for small LLMs. 87% benchmark with 4B-active model.项目地址: https://gitcode.com/gh_mirrors/sm/smallcodeSmallCode 是一款专为本地小模型8B–35B 参数优化的 AI 编程助手它的大脑并不靠手写胶水代码堆出来而是由 MarrowScript 声明式语言编译而成约 50 行.marrow声明就能生成 1400 行以上带缓存、重试、校验、追踪与预算控制的生产级 TypeScript 运行时。本文带你读懂这套认知层的设计原理。为什么小模型需要一个认知层大多数 AI 编程工具默认你用的是 128k 上下文的顶级模型JSON 输出稳定、长程记忆可靠。而本地 8B–14B 模型恰恰相反——上下文小、工具调用时好时坏、写到第 3 步就忘了第 1 步在干什么。SmallCode 的应对思路不是换更大的模型而是在模型外面包一层确定性的认知脚手架cognition layer哪些 LLM 调用该用什么超时、命中缓存怎么办、输出不合法怎么修复、花了多少 token 怎么记账——这些全部以声明方式写死编译进运行时。小模型负责思考脚手架负责不出事故。声明式写法把 LLM 调用写成接口契约认知层的全部行为定义在 marrow/smallcode_cognition.marrow 中一眼就能看懂它声明了什么prompt classify_task_type(user_message: string) { model: TinyClassifier timeout: 3s cache: { key: hash(user_message), ttl: 10m } retry: { max_attempts: 2, backoff: fixed, interval: 100ms } constraints: [output in [coding, editing, search, ...]] }整份声明只描述了 4 类东西声明块作用源码位置model定义 Tiny / Small / Medium 三档模型档位上下文窗口、温度、成本等级smallcode_cognition.marrow#L14-L45router按任务复杂度确定性分档trivial→小模型simple→中模型complex→强模型smallcode_cognition.marrow#L49-L57prompt每次 LLM 调用的完整契约超时、缓存、重试、输出约束smallcode_cognition.marrow#L78-L119policy限流 120 次/分钟、每小时 50 万 token 硬预算超限直接报TOKEN_LIMITsmallcode_cognition.marrow#L123-L134注意extension_point机制提示词的措辞放在 src/extensions.ts 等扩展点里编译产物只按名字引用。这样重新编译不会冲掉你手工调优过的 prompt。编译产物1400 行运行时从哪里来编译输出集中在 src/compiled/cognition/每个文件开头都标着Generated by MarrowScript compiler. DO NOT EDIT.prompts.ts —— 每条prompt声明变成一个带类型的异步函数执行固定的 8 步流水线输入校验 → 解析模型直连或走 router→ 加载模板 → 发请求 → 输出校验 → 按预算内重试/修复 → 写追踪 span → 返回结果见 prompts.ts#L2-L14 的注释说明cache.ts —— 提示词缓存内容哈希键 TTLtraces.ts —— 结构化追踪每次 LLM 调用都有 trace_id/span_idbudget.ts —— 按成本等级记账的 token 预算器router.ts —— 声明式复杂度路由的可执行实现validate.ts / repair.ts —— schema 校验与自动修复对外入口是 index.ts应用代码只调用callPrompt(name, input)一行应用层不需要关心缓存、重试、超时这些细节——它们在声明里说一次运行时里就有。编译器免费附赠的 5 项生产级能力1. 内容哈希缓存重复问题 0ms 响应缓存键由提示词名、模型 ID、模板哈希和规范化 JSON 输入共同推导见 cache.ts#L47-L60。模板一改旧缓存自动失效输入相同直接命中。默认内存模式也可切 Postgres 模式跨重启持久化。2. 全链路结构化追踪每次模型调用自动产出 span 日志。设置环境变量SMALLCODE_COGNITION_LOGstderr即可在终端看到每次认知调用的完整链路——调试小模型时这比什么都值钱。3. 复杂度分档路由省 token 也省延迟coding_router按复杂度分数分三档见 smallcode_cognition.marrow#L49-L57简单任务用输出上限 64 token 的 TinyClassifier复杂任务才动用 8192 输出的强模型置信度低于 0.6 自动升级档位。4. Token 预算与限流永不超支policy cognition_limits声明了每用户每小时 50 万 token 的硬顶和每分钟 120 次的限流超限时运行时直接抛出TOKEN_LIMIT错误而不是悄悄烧钱。5. 校验 自动修复输出按validate声明做 schema 检查on_invalid指定失败动作——retry固定/指数退避或retry_with_repair_prompt追加修复提示词重跑。小模型最常见的输出格式跑偏在这里被消化掉不会泄漏到主 agent 循环。其他 Marrow 声明文件认知层不止一份marrow/目录还有若干独立声明共同构成完整脚手架tool_router.marrow —— 确定性工具路由把消息按正则加权信号分到 read/write/search/run/plan/web/respond 七类零 token、零延迟、100% 可复现替代了原本要消耗一次 LLM 调用的路由分类器bounded_loops.marrow —— 生成→校验→修订的有界循环用于 write_file → 语法检查 → 修错 → 重试quality_monitor.marrow、read_guard.marrow、contract.marrow —— 质量监控、读前守卫与任务契约这套设计的容错哲学也很实用任何编译模块不可用时全部优雅降级为正则兜底或返回空值绝不让认知层反过来拖垮 agent 主循环。如何上手验证这套机制安装npm install -g smallcode在项目根目录建.env配置SMALLCODE_MODEL与SMALLCODE_BASE_URL指向 LM Studio / Ollama 等本地端点加一行SMALLCODE_COGNITION_LOGstderr启动后就能在终端观察每次认知调用的缓存命中、路由档位与重试情况想深入阅读从 marrow/smallcode_cognition.marrow 出发对照 src/compiled/cognition/ 的产物逐块印证小结SmallCode 的 MarrowScript 认知层本质上是把如何稳妥地调用 LLM这件事从代码升维成了声明50 行契约换来 1400 行运行时缓存、追踪、路由、预算、修复一次声明、处处生效。对于想在自己项目里驯服小模型的同学这套声明式认知脚手架的思路值得直接抄作业。【免费下载链接】smallcodeAI coding agent optimized for small LLMs. 87% benchmark with 4B-active model.项目地址: https://gitcode.com/gh_mirrors/sm/smallcode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考