企业官网建设流程全解析

little-coder安全机制全解：权限白名单与Write保护如何防止小模型"删库跑路"

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

little-coder是一个专为小参数量本地模型优化的编程智能体（coding agent），而它最容易被低估的部分，正是那套安全机制：Shell权限白名单与Write 保护。小模型不像大模型那样"听话"——它可能会换个姿势绕过限制、整文件覆盖代码、甚至顺手执行一条危险命令。little-coder 用不到 30 个轻量扩展把风险关进笼子。这篇文章带你完整拆解这套防"删库跑路"体系的设计思路，无需读源码也能理解。

为什么小模型需要专属安全机制 🛡️

大模型通常能"理解"指令边界，而小模型更倾向于用各种变通方式达到目的。项目维护者就抓到过几个真实案例：

• Write 工具拒绝写已有文件后，小模型转头用cat > main.py << 'EOF'把整个文件从 Shell 重新灌了一遍，一次会话里上演 5 次；
• 白名单只检查命令第一个词，于是ls && rm -rf /因为"以 ls 开头"差点溜过去；
• 拒绝提示太含糊时，模型会依次尝试python3 -c、node -e、sh -c……花三轮把限制"研究"穿。

这些问题的共同点：光靠提示词约束小模型是不可靠的，必须把规则硬编码进执行层。little-coder 的做法是让每个安全机制都做成独立的 pi 扩展，在工具真正执行前的tool_call事件上拦截。

权限白名单：Shell 命令的三道铁律

Shell 命令是智能体最大的风险面。little-coder 的 permission-gate 扩展 在命令交给 pi 的确认流程之前，先过一遍内置的安全前缀白名单：

• 只读类：ls、cat、head、tail、grep、find、rg
• Git 只读子命令：git log、git status、git diff、git show
• 常规脚手架：cp、mv、mkdir、touch
• 常见解释器与包管理查询：python、node、pip show、npm list

完整清单见 BUILTIN_SAFE_PREFIXES 定义。注意rm和sudo刻意不在名单里——确实需要时才通过环境变量放行。

白名单之上还有两条硬规则，都来自真实事故的复盘（issue #70）：

规则一：链式命令逐个审查，不只看第一个词

ls && rm -rf /这种"开头安全、后面致命"的命令，会被按&&、||、;、|和换行拆成独立片段逐一判定，任何一段不合规整条命令直接拒绝。拆分逻辑在 splitCommandChain 中实现，且会正确处理引号——grep "a > b" file里的>不会误报。

规则二：通过 Shell 写文件的命令一律拒绝

cat虽然白名单在册，但cat > main.py << 'EOF'本质上就是一次写文件。little-coder 会扫描命令中的重定向（>、>>）、tee、dd of=等一切"写通道"，只要检测到写目标就拒绝，并明确告知模型：新建文件请用Write，改已有文件请用Edit。

检测器 detectWriteTargets 相当讲究：heredoc 正文先剥离再分析、2>&1这类文件描述符复制不算写、/dev/null这类无破坏性目标直接豁免。

规则三：拒绝时告诉模型"下一步该做什么"

小模型面对一句干巴巴的 "not allowed" 只会反复重试。little-coder 的拒绝文案会指名补救措施：这条命令被拒、别再用解释器变相重跑、要改文件就用 edit/write、用户可以用LITTLE_CODER_BASH_ALLOW放行。一段写得好拒绝提示，本身就是安全机制的一部分，见 拒绝理由生成逻辑。

Write 保护：不让小模型"整文件重写" 📝

这是 little-coder 白皮书里最重要的实验性机制之一。小模型有个致命习惯：改一行代码时把整个文件从记忆里重新吐一遍——上下文一长，重写内容就开始丢东西、改乱缩进，等于静默破坏你的代码库。

write-guard 扩展 把规则定死为运行时不变量：

1. Write只允许创建新文件。目标文件已存在时直接拒绝，并返回一份"照着抄就能用"的Edit调用模板，把模型引向精确的oldText/newText替换。这个拦截在约 57% 的基准题上触发过，直接支撑了 Aider Polyglot 的高分。
2. 路径归一化防"写错地方"。小模型被要求填绝对路径时，有时会写出/foo.md这种"根目录+裸文件名"，几乎总是笔误。write-guard 会把它重写到当前工作目录下，避免往文件系统根目录乱写；相对路径也统一锚定到 cwd，见 normalizeWritePath。
3. 拒绝 Windows 保留设备名。往nul、com1、con这类名字写文件，在 Windows 上会留下无法删除的垃圾文件。write-guard 跨平台拦截这些名字（比如小模型把nul当/dev/null用的经典错误），见 writeVerdict 判定逻辑。

Shell 重定向被同样拦截

如果只守Write工具，小模型会立刻学会走 Shell 后门——这正是 issue #70 的教训。所以 write-guard 挂了两个钩子：一个拦write工具，一个拦所有 Shell 系工具（bash、Bash、ShellSession、ShellStart）中的重定向写。两份守卫共享同一个工具清单 SHELL_TOOLS，从代码结构上杜绝"两个安全组件对工具清单认知不一致"的漏洞。追加写（>>）不覆盖内容，只保留设备名检查。

纵深防御：先读后改 + 修改前快照 🧩

白名单和 Write 保护之外，还有两道补充防线：

• 先读后改（read-guard-edit）：本会话没read过的文件，Edit一律拒绝。小模型经常"凭想象"填写oldText，要么匹配失败浪费轮次，要么匹配错位置造成意外修改。这条不变量强制模型先看清现状再动手。
• 修改前快照（checkpoint）：每次Write/Edit之前，文件的原始内容会被备份到~/.little-coder/checkpoints/<session>/。就算模型改坏了，你也能从快照里找回改动前的版本——这是最后一道兜底。

系统提示词 AGENTS.md 中还有一条软约束配合硬机制：被拒绝的命令就是答案，不是障碍——不要试图用别的解释器重跑同一操作。

三种权限模式：如何按部署环境切换安全等级

通过环境变量即可调节松紧度（详见 README 的 Permissions 章节）：

两个容易忽略的细节：

• 前缀末尾的空格有意义："make "只放行make test这类带参数的命令，"make"连makefoo也放行。
• 即便accept-all跳过了白名单，Write 保护仍然生效——Shell 重定向覆盖已有文件的命令照样被拒。这条"小模型不整文件重写"的保证在无人值守的基准运行中同样成立。

工具用法卡片 skills/tools/bash.md 与 skills/tools/write.md 也把这些规则讲给模型听，属于"硬机制 + 软引导"的组合拳。

安全机制拖慢任务了吗？📊

不会。这套机制在小模型 + 消费级笔记本（8 GB 显存）上跑出了四项基准的成绩：Aider Polyglot 78.67%、Terminal-Bench-Core 40.0%、Terminal-Bench 2.0 登上官方榜单（24.6%）、GAIA 验证集 40.0%。安全拦截本身反而帮模型省了轮次——拒绝提示直接给出正确做法，省掉了模型"撞墙—绕行—再撞墙"的消耗。

一图速览：little-coder 的安全防线 🎯

写在最后

little-coder 安全机制的核心哲学可以概括为一句话：对小模型，提示词是建议，扩展层才是法律。白名单管住"能执行什么"，Write 保护管住"能写什么"，先读后改管住"改得对不对"，快照管住"错了怎么办"——四层防线层层递进，让小模型在 8 GB 显存的笔记本上也能安全自主地干活。想动手看看每一层怎么实现，从 README 的 Architecture 章节 顺着扩展目录逛一圈就懂了。

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