Maka Agent 技能目录预算机制完整解析：2% 上下文窗口如何实现懒加载
Maka Agent 技能目录预算机制完整解析：2% 上下文窗口如何实现懒加载
【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/maka
Maka 是一个本地优先（local-first）的 AI Agent 工作区，它把模型消息、工具调用、权限决策等全部记录为追加式日志。当你安装了大量技能（Skills）后，Maka 并不会把它们全部塞进系统提示词，而是用一套"2% 上下文窗口预算 + 懒加载"机制来管理技能目录，让 Agent 在任意规模模型下都能稳定运行。本文带你从零理解这套预算机制的工作原理。
为什么技能目录需要预算？
很多人把技能理解为"给 Agent 装插件"。但技能不只是配置——每个技能的完整说明书（instructions）可能长达数千 Token，如果全部写入系统提示词，会直接吃掉模型宝贵的上下文窗口：
- 上下文窗口被浪费：技能说明在大多数对话里根本用不到，却每轮都计费。
- 规模失控：技能装得越多，提示词越长，推理成本越高。
- 大模型陷阱：200K 窗口的模型反而可能让提示词无限膨胀。
Maka 的答案是：提示词里只放"目录"，不放"正文"。就像图书馆只在书架上贴书名标签，读者看中哪本才去取书。
2% 预算公式：从上下文窗口到字符预算
预算的计算在 packages/runtime/src/skills-context.ts 中定义，核心规则如下：
- 基础比例：预算 = 所选模型上下文窗口 ×2%（
SKILLS_PROMPT_CONTEXT_RATIO = 0.02）。 - 上下限钳制：结果被限制在4,000 ~ 8,000 Token之间。下限保证小窗口模型也有可用目录，上限防止大窗口模型把目录变成无界成本。
- 字符换算：按 4 个字符 ≈ 1 Token 换算成字符预算。
- 兜底值：如果模型窗口未知，回退到向后兼容的固定 18,000 字符（
MAX_SKILLS_PROMPT_CHARS）。
| 模型上下文窗口 | 2% 计算值 | 钳制后预算（Token） |
|---|---|---|
| 8K | 160 | 4,000（取下限） |
| 128K | 2,560 | 4,000（取下限） |
| 320K | 6,400 | 6,400 |
| 200K | 4,000 | 4,000 |
| 1M | 20,000 | 8,000（取上限） |
💡 注意：上下文窗口是显式的提示词输入，而不是技能扫描器在内部偷偷查模型。这样切换模型时，选中的目录是确定性的、可预测的。
懒加载核心：Skill 与 SkillSearch 两个工具
被预算裁掉的技能并没有消失，Maka 用两个只读工具兜底：
Skill工具（取书）：当任务匹配某个技能时，模型按 ref、id 或名称精确加载完整说明书。即使该技能没进提示词目录，也照样能加载。SkillSearch工具（找书）：目录放不下时，提示词里会带一句固定大小的提示（只告知"还有 N 个技能被省略"，而不是列出一串 id），模型可用简短任务描述搜索，最多返回 8 条匹配结果。
这套"目录 → 搜索 → 精确加载"的三层结构，让技能数量从 5 个到 500 个，系统提示词的长度都基本恒定。
确定性选目录：从全量清单到提示词的 5 步
技能目录的挑选完全确定，顺序固定，见 docs/skill-catalog-policy.md：
- 发现：按"项目级 → 工作区兼容路径 → 用户级"的优先级扫描技能目录，重名技能先到先得；
- 过滤禁用：去掉用户禁用的技能；
- 宿主能力门控：技能声明的
required-tools或required-capabilities在宿主不可用时直接隐藏（allowed-tools仅作参考，不授予权限）； - 排序：用户置顶（pinned）的技能排最前，其次保持来源优先级与显示名排序；
- 装入预算：按序累加字符数直到触顶，超出者进入"省略"名单。
每一步都会产生一份决策报告（SkillSelectionReport），为每个技能记录明确结论：advertised（已展示）、budget（被预算裁掉）、disabled、invalid、host_incompatible、shadowed（被更高优先级同名技能遮蔽）。
如何查看预算决策：Context Inspector
桌面端会缓存最近一次提示词构建的报告，在Skills Context Inspector中展示：预算用了多少字符、哪些技能被展示、哪些因预算被省略、被谁遮蔽……一切透明可查。提示词尚未构建时，它还会展示一份确定性的预览。这对排查"为什么我的技能没被 Agent 看到"非常有用。
实用建议：让技能进入目录的技巧
- 🔖置顶关键技能：pinned 技能永远排在最前，最不容易被预算挤掉；
- 📝写短描述：目录条目按 id、名称、描述、声明工具逐项计字符，描述越精炼，同预算能装下越多技能；
- 🗂就近放置：项目级技能优先级高于用户级，把高频技能放进项目目录；
- ⚙️按需声明依赖：
required-tools声明的宿主能力缺失时技能会被整体隐藏； - 🔍别忘了 SkillSearch：被省略的技能仍然可被发现和精确加载，省略只影响"主动展示"，不影响可用性。
总结
Maka 的技能目录预算机制用一条简单公式（窗口 × 2%，钳制在 4K–8K Token）解决了"技能越多、提示词越贵"的经典难题；再配合Skill精确加载与SkillSearch搜索这两个懒加载工具，实现了"提示词成本恒定、技能规模无上限"的优雅平衡。完整策略细节可参考 docs/skill-catalog-policy.md，核心实现在 packages/runtime/src/skills-context.ts。
【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/maka
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考