OpenCode 踩坑注意事项：上下文压缩、MCP 机制与 Skill

上下文压缩机制：避免关键信息丢失

当对话上下文过大时OpenCode 会自动触发压缩机制。理解这一机制是防止 SKILL.md 等关键配置“意外消失”的关键。

压缩的工作原理

压缩并非简单的截断，而是通过一次额外的 LLM 调用完成的智能处理：

• 早期对话被压缩为结构化摘要。
• 最近交互保留完整内容。
• 后续对话基于“摘要 + 最近轮次”继续进行。

SKILL.md 的丢失风险

如果 SKILL.md 在对话早期被读入，它可能会经历以下两种命运：

配置与 Prune机制

可以通过配置文件控制压缩行为。其中 "prune" 字段负责修剪旧的工具输出，而不是删除工具本身。

Prune 对 Skill 的特殊保护

读取的 SKILL.md 不会被 Prune 删除. 源码逻辑简化示例如下：

// tool/skill.ts 简化逻辑示意
function prune {
for {
// 第322行：遇到 skill 工具时跳过
if continue;// 第298行：标记其他工具输出为清除
markForRemoval;}
}

MCP 工具加载机制：警惕 Token 消耗

A common misconception is that MCP tool definitions live inside system prompt. In reality。y are injected into each request dynamically:

// 每次 LLM 请求前
SessionTools.resolve // 收集所有可用工具
→ registry.tools // 内置 + 插件
→ mcp.tools // 已连接 MCP 服务器返回的工具描述
→ 合并后的 tools 参数随本次请求发送给模型 API

性能警告 

The tool description consumes part of token budget for every round. Therefore,keep number of MCP tools moderate. Over‑loading request with dozens of tool schemas leads to:


Token 爆炸，导致模型截断关键对话。不过，

工具选择噪声增加。模型误选或根本不选，

整体响应延迟升高。


程序提示词里都有什么 

The system prompt defines agent’s persona and boundary conditions. It is assembled in /llm/request.ts:

System Prompt = .join

各层详解 

)。


层级
代码位置/来源
说明




 模型提示模板 
/system.ts:- + prompt/*.txt 


 环境信息 
/system.ts:-> sys.environment


 指令文件 
/instruction.ts:-> 搜索项目根目录和全局 


 技能列表 
/system.ts:-> sys.skills


 使用者 System `prompt.ts` 中每条使用者消息可附带自定义 `system` 字段。