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 中定义，核心规则如下：

1. 基础比例：预算 = 所选模型上下文窗口 ×2%（SKILLS_PROMPT_CONTEXT_RATIO = 0.02）。
2. 上下限钳制：结果被限制在4,000 ~ 8,000 Token之间。下限保证小窗口模型也有可用目录，上限防止大窗口模型把目录变成无界成本。
3. 字符换算：按 4 个字符 ≈ 1 Token 换算成字符预算。
4. 兜底值：如果模型窗口未知，回退到向后兼容的固定 18,000 字符（MAX_SKILLS_PROMPT_CHARS）。

💡 注意：上下文窗口是显式的提示词输入，而不是技能扫描器在内部偷偷查模型。这样切换模型时，选中的目录是确定性的、可预测的。

懒加载核心：Skill 与 SkillSearch 两个工具

被预算裁掉的技能并没有消失，Maka 用两个只读工具兜底：

• Skill工具（取书）：当任务匹配某个技能时，模型按 ref、id 或名称精确加载完整说明书。即使该技能没进提示词目录，也照样能加载。
• SkillSearch工具（找书）：目录放不下时，提示词里会带一句固定大小的提示（只告知"还有 N 个技能被省略"，而不是列出一串 id），模型可用简短任务描述搜索，最多返回 8 条匹配结果。

这套"目录 → 搜索 → 精确加载"的三层结构，让技能数量从 5 个到 500 个，系统提示词的长度都基本恒定。

确定性选目录：从全量清单到提示词的 5 步

技能目录的挑选完全确定，顺序固定，见 docs/skill-catalog-policy.md：

1. 发现：按"项目级 → 工作区兼容路径 → 用户级"的优先级扫描技能目录，重名技能先到先得；
2. 过滤禁用：去掉用户禁用的技能；
3. 宿主能力门控：技能声明的required-tools或required-capabilities在宿主不可用时直接隐藏（allowed-tools仅作参考，不授予权限）；
4. 排序：用户置顶（pinned）的技能排最前，其次保持来源优先级与显示名排序；
5. 装入预算：按序累加字符数直到触顶，超出者进入"省略"名单。

每一步都会产生一份决策报告（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