企业官网建设流程全解析

little-coder架构拆解：27个pi扩展如何把冷启动上下文压缩到7k tokens

【免费下载链接】little-coderA harness optimized to smaller LLMs项目地址: https://gitcode.com/gh_mirrors/li/little-coder

little-coder 是一个面向本地小语言模型的 AI 编程 Agent 框架，构建在 pi 运行时之上。它通过 27 个 pi 扩展 + 30 份技能文件，把 Agent 的冷启动上下文从 20k+ tokens 压缩到约 7k tokens——省下来的每一分上下文，都变成了 8GB 显存小模型上真实可用的推理空间。本文带你逐层拆解这套架构的设计思路。

为什么小模型的上下文"花不起"

对云端大模型来说，上下文窗口动辄 20 万 tokens，多塞点工具说明无所谓。但 little-coder 的目标场景是：一台消费级笔记本，一块 8GB 显存的显卡，跑一个 9.7B~35B 的本地模型。此时上下文有三个致命约束：

1. 窗口小：本地服务通常只开 16K 上下文，冷启动就吃掉 20k 的 Agent 直接溢出；
2. KV cache 昂贵：本地推理缓存命中失败意味着整段历史重新计算，一次全量重处理可能要等几十秒；
3. 注意力稀释：小模型对上下文尾部的权重更高，冗长的系统提示会稀释它真正该看的指令。

所以 little-coder 的第一设计原则就是：第一个 prompt 之前花掉的 token，是永远拿不回来的钱。官方扩展文档 docs/extensions.md 开篇就把这句话写进了设计哲学。

整体架构：pi 是地基，扩展是全部

little-coder 不 fork pi，也不改它的 CLI——pi 是package.json里的一个普通依赖，提供 Agent 循环、多供应商 API、TUI 和会话树，只带 4 个内置工具（read/write/edit/bash）和约 1000 token 的系统提示。所有小模型适配机制全部做成pi 扩展，住在.pi/extensions/目录下，每个扩展是一个独立小目录，开头都有注释解释"为什么它存在"。

启动器 bin/little-coder.mjs 做了一件关键的事：以--no-extensions启动 pi（关闭自动发现），再把自己打包的扩展集合逐一显式挂进去。加载的就是发布的那一套，多一个不多、少一个不少。这就是冷启动稳定在 7k tokens 的根本原因——工作目录里的任何文件都无法在任务中途改变 Agent 行为。

27个扩展各司其职：一张分类表

扩展之间互不依赖，按需挂在 pi 的生命周期事件上（before_agent_start、tool_call、tool_result、turn_end等）。按职责可以分成四组：

完整清单和版本演进见 CHANGELOG.md 与 docs/architecture.md（后者还保留了 Python 时代的历史架构）。

三个最反直觉的压缩手法

手法一：指导内容绝不进系统提示，而是"贴"在对话尾部

这是项目最有含金量的一次重构。早期版本把工具技能卡片、算法速查表追加到系统提示末尾——直觉上"最新的内容放最后"很合理，但系统提示位于每个请求的最前面，它一变，整个缓存前缀就失效，llama.cpp 被迫重算全部历史。社区用户用cache-hunter抓到了"120k token 历史无故重处理"的铁证（问题 #73。

修复方案很优雅：借助 pi 的before_agent_start钩子，把这些内容作为一条消息追加到对话末尾。前面所有字节一字不动，缓存前缀原样复用，只处理新增的少量 token。而小模型恰好最重视上下文尾部——"最后"的要求不但没变弱，反而更强了。实现就藏在 .pi/extensions/_shared/inject.ts 这个共享模块里，配一个去重器：与上一回合完全相同的卡片不再重复注入，因为上一条还留在对话里。

手法二：按需注入，三优先级选择算法

30 份技能文件从不全量加载。.pi/extensions/skill-inject/ 每个回合按三个优先级挑 1~2 张工具卡片：错误恢复（上一步哪个工具失败了就推哪个的补救卡）>近期性（最近两回合用过什么）>意图预测（用户消息里的关键词，如 "find" 命中 glob/grep 卡片）。算法知识则用关键词打分：单词命中记 1.0 分、双词命中记 2.0 分，得分 ≥2.0 且预算内才入选。没有命中就是零注入——不为"可能有用的知识"预付 token。

手法三：把"大"挡在上下文外面

• 读文件熔断：.pi/extensions/read-guard/ 发现某次 Read 会把上下文撑爆时，直接只留文件前 30 行，并附一句"用 grep 定位你要的部分"的指令；
• 隔离子 Agent：dispatch工具派生的 sub-coder 在独立会话里读代码、查资料，只有简短报告进入主对话，完整记录留在 UI 面板里；
• 压缩看门狗：.pi/extensions/context-watchdog/ 在每个回合边界检查上下文占用，越过窗口 80% 就主动触发 pi 的自动压缩——专治"几十个连续工具调用直接把窗口打穿"的场景；
• 压缩不丢证据：evidence-compact 在自动压缩后提醒模型"你的证据还在，用 EvidenceList 取"，保住研究链。

如何验证压缩是否生效：看状态行的 CH 字段

little-coder 的终端底部状态行是这套架构的"仪表盘"：

↑26k ↓5.4k R447k CH99.8% 9.3%/262k (auto) qwen3.6-35b-a3b • medium

其中CH 是最近一次响应的 KV cache 命中率。跑长对话时如果 CH 掉下来，说明服务器在重算本该复用的历史，值得排查；配合右侧的9.3%/262k（当前上下文占窗口比例）和(auto)（自动压缩已启用），新手也能一眼判断上下文预算健康与否。

省下来的上下文，换回了什么成绩

压缩不是目的，成绩才是。全部数据来自一台 8GB 显存的消费级笔记本，零云端推理：

想加自己的扩展？三条官方路径

默认封闭的扩展集并非不可扩展，docs/extensions.md 给了三层渐进方案：

1. 放文件：把自己的扩展丢进~/.config/little-coder/extensions/，每次启动自动加载在捆绑集之后，可覆盖内置行为；
2. 指路径：LITTLE_CODER_EXTRA_EXTENSIONS环境变量指向任意位置的扩展文件；
3. 全开放：加--with-pi-extensions让 pi 按原生方式发现生态扩展（会提示你"冷启动上下文不再固定"）。

在 TUI 里跑/extensions可以随时查看实际加载了什么、来自哪里——这正是"透明可验证"设计哲学的体现。

写在最后

little-coder 给出的启示超越了工具本身：脚手架与模型的匹配度，往往比模型大小更能决定实际表现。当你能把一个 9.7B 模型的上下文每一分都花在刀刃上时，它就能做出让 45% 解决率变成现实的事。如果你手头正好有一块 8GB 显卡和一个 Qwen 模型，这大概就是目前最值得研究的本地编程 Agent 方案了。

【免费下载链接】little-coderA harness optimized to smaller LLMs项目地址: https://gitcode.com/gh_mirrors/li/little-coder