OpenCode 完全手册：路由协作、记忆嫁接与 DeepSeek 刀法

这套组合为什么划算

成本收益来自路由，而不是来自「所有任务都换成便宜模型」。

主控模型只在需要判断的地方出现，纯文本执行交给子 Agent，媒体能力按需触发。任务越清晰，这个分工越省成本；任务越模糊，越应该先让 Luna 收敛目标，再派发执行。

三个角色，各自守住一条边界

有一个容易被误解的点：DeepSeek 是纯文本模型，不等于它只能写调用方案。它可以直接调用当前会话已经暴露、并且权限和认证都通过的 OpenCode 原生工具与 MCP。它不能接收媒体字节，但可以把路径、URL、Prompt 或 task_id 作为工具参数传出去，再处理工具返回的文本结果。

真正防止「失忆」的不是上下文，而是委派契约

子 Agent 不应该依赖主控上一轮说过什么。每次通过原生 task 委派时，都重复注入下面这段固定声明：

DeepSeek V4 Flash 是纯文本执行 Agent，不接收图片、剪贴板附件或未转换的多媒体，只处理主控提供的结构化文字，并返回非空结果、修改文件、验证命令、验证结果和剩余风险。

同一个任务里还要补上正向能力声明：

DeepSeek 可以直接调用当前会话已注册且权限/认证通过的 OpenCode 原生工具和 MCP；多媒体只能通过工具参数处理，不能作为原始模型输入。工具不可见或调用失败时，必须返回非空阻塞结果，不得猜测或伪造媒体结果。

这两段话缺一不可。只有限制没有授权，DeepSeek 会把自己误判成「只能分析文本、不能碰工具」；只有授权没有限制，它可能把图片附件当作模型输入，或者把无法验证的媒体结果说成已完成。

固定契约至少要覆盖五件事：

1. 任务范围：只做当前子任务，不擅自扩大。
2. 输入边界：原始媒体不进模型，结构化参数可以交给工具。
3. 工具权限：只能使用当前会话实际暴露且获准的工具。
4. 失败行为：工具不可见、未连接、认证失败或调用失败时，返回非空阻塞结果。
5. 验收证据：返回工具结果、文件路径或任务状态，以及验证命令、验证结果和剩余风险。

媒体任务的标准接力

图片理解时，image_source 是传给视觉工具的路径或 URL，不是把图片字节交给 DeepSeek。标准流程是：

1. Luna 或 DeepSeek 根据任务范围准备 image_source 和分析 Prompt。
2. minimax-coding_understand_image 处理图片，返回 OCR、对象、颜色、布局或其他结构化文字。
3. DeepSeek 消费这段结构化文字，继续做判断、改写、代码修改或下一步编排。
4. Luna 检查返回内容是否非空，检查路径、状态、文件变更和需求覆盖。

生成任务也遵循同样的接力方式。DeepSeek 可以直接调用媒体工具，但要先识别副作用：生图和生音频会产生文件和额度消耗，视频可能是异步任务，播放会产生本地设备副作用，网页搜索会产生外部网络请求。

视频任务尤其不能把「已提交」当成「已完成」：MiniMax_generate_video 返回 task_id 后，必须继续使用 MiniMax_query_video_generation 查询到终态，并以最终产物和 Review 结果为准。

当前工具面

当前 OpenCode 会话登记并暴露的能力族如下。具体参数以当次运行时工具签名为准，能力索引不替代工具定义。

这套工具面让产物不再只有文本和代码，还可以包括图片、音乐、语音、视频、OCR 结果和结构化媒体分析。DeepSeek 的职责不是拥有这些媒体模态，而是把结构化任务送到正确的工具，并继续处理返回结果。

已验证什么，不能越界推断什么

验证结论要分层写，不能把配置状态和业务成功混在一起。

「工具已注册」「MCP 已连接」「认证通过」「权益充足」「业务调用成功」是五个不同状态。任何一项都不能替代另外四项。

主控验收标准

Luna 收到 task_result 后，至少检查以下内容：

这套验收机制把模型的「记性」变成了可检查的契约。子 Agent 即使忘了上下文，也会在当前 Prompt 中重新获得能力边界和工具入口；它即使给出错误结论，Luna 仍然可以通过结果、权限和验证证据把错误拦下来。

最容易写错的几句话

维护这套体系的几条硬规则

1. opencode.json 是运行时配置来源，capability-index.md 是能力登记表，AGENTS.md 和 session-bootstrap.md 是协作规则和新会话同步层。
2. 修改 Agent、模型、MCP、Skill、Plugin 或权限后，同时更新能力索引，并重新做 JSON 解析和运行时检查。
3. 每次原生 task 委派都重复注入固定能力声明，不依赖历史上下文。
4. 运行时工具栏优先于旧文档。工具名、参数和可用性发生变化时，以当次实际暴露签名为准。
5. 修改配置后重启 OpenCode。配置不是热加载的，当前会话不会自动获得所有新规则。
6. 凭据只从认证存储或环境变量读取，不进入 Prompt、日志、能力索引或知识笔记。
7. 媒体工具按需触发。涉及生成、播放、外部网络或异步任务时，先标明副作用，再执行和验收。

适合迁移到其他项目的原则

• 按输入模态和任务复杂度分工，不按「谁都能做」分工。
• 把工具权限、失败处理和验收证据写进每次委派契约。
• 让低成本模型承担可验证的执行，让高能力模型承担路由和最终判断。
• 把多媒体当作工具参数和工具结果管理，不把媒体字节硬塞给纯文本模型。
• 将配置状态、运行时状态和业务结果分层记录。
• 用真实调用验证工具链，不用静态 enabled 字段替代运行时证据。
• 对异步产物坚持「状态到终态」的验收，而不是看到 task_id 就结束。
• 保留失败和未知项。未知不是失败，但把未知写成成功会让整套协作失去可信度。

这套方案的核心不是让某一个模型变得无所不能，而是让每个角色都知道自己能做什么、该把什么交给工具、什么时候必须停下来等主控验收。这样，成本、能力和产物多样性才会同时成立。

compaction 不是 AutoMemory

这两个概念很容易混在一起。

OpenCode 的 session persistence 和 context compaction，解决的是当前会话太长之后如何继续；Claude Code AutoMemory 解决的是哪些信息值得跨会话保留下来。一个负责压缩上下文，一个负责沉淀长期记忆，不是一回事。

OpenCode 核心目前没有 Claude Code 同款的自动记忆提取机制。想让它跨会话召回和写回，就需要插件或其他扩展层。

选兼容层，不另起炉灶

这次接入的是 opencode-claude-memory。它的定位不是新建一个记忆系统，而是把 OpenCode 接到 Claude Code 已有的本地 Markdown 目录上：

说白了，这不是复制记忆，而是接同一个文件入口。

实际接入只需要三步

先安装插件：

1
npm install -g opencode-claude-memory

再安装会话结束后的 wrapper：

1
opencode-memory install

最后在全局 opencode.json 里追加插件：

1
{
2
  "plugin": ["opencode-claude-memory"]
3
}

已有其他插件时只追加，不要覆盖整个配置。改完后要完全退出并重启 OpenCode，配置不会在当前进程里热加载。

Windows 下真正容易卡住的是路径

我的 blog 工作区有两个层级：

1
D:\OneDrive\Desktop\blog
2
└── Firefly    # 真正的 Git 仓库

Claude Code 旧记忆已经落在：

1
C:\Users\Lenovo\.claude\projects\D--OneDrive-Desktop-blog\memory\

而插件按照 Firefly 的 Git 根目录解析出了另一条路径：

1
C:\Users\Lenovo\.claude\projects\D--OneDrive-Desktop-blog-Firefly\memory\

如果不处理这个差异，插件虽然能加载，memory_list 也能调用，但看到的是一个空目录。这个状态最容易被误判成“插件没有记忆”。

解决方式是把空的目标目录改成 Windows junction，指向已有的 Claude memory：

1
D--OneDrive-Desktop-blog-Firefly\memory
2
        ↓ junction
3
D--OneDrive-Desktop-blog\memory

这样没有复制文件，也没有迁移真源；两个路径只是指向同一份内容。以后如果项目根目录或 Git worktree 变化，要重新检查插件解析出的路径。

验证不能只看配置文件

“配置写进去了”和“共享记忆真的能用”至少是三层证据：

1. opencode debug config 能识别 opencode-claude-memory。
2. 独立重启的 OpenCode 进程能调用 memory_list、memory_search、memory_read。
3. OpenCode 写入一条临时记忆后，Claude Code 在同一个项目里也能读到。

本次验证结果是：

最后一项很重要。测试写入时，插件会同步更新 MEMORY.md 索引；如果只删测试主题文件、不恢复索引，记忆库仍然会留下脏引用。验证脚本或工具如果没有帮你做回滚，必须再检查一次索引。

记忆、项目规则和文章素材各归其位

共享记忆很有用，但它不是整个知识系统：

把所有东西塞进 AutoMemory，最后只会得到一间很难找东西的杂物间。记忆应该保存“以后还会影响决策的事实”，文章素材则应该进入自己的写作流水线。

还有一个 Skill 入口误会

OpenCode 的 Skill 不等于斜杠命令。它由 Agent 的 skill 工具按需加载，所以在 /skills 菜单里看不到，不代表文件没有安装。

正确的触发方式是直接告诉 Agent：

1
用 knowledge-extract 提炼这次会话。

如果 Skill 已被当前 CLI 的 available skills 发现，Agent 就可以加载它。模型 variants 是 API 推理参数问题，Skill 则是 Agent 工具入口问题，这两件事不要混成一个“索引失败”。

最后留一条边界

共享方案解决的是存储一致性，不保证所有 shell 的 wrapper 行为都一样。Windows 下 Git Bash 更容易让 opencode-memory install 生效；PowerShell 仍能加载插件和 memory 工具，但会话结束后的自动提取是否触发，要按实际运行环境验证。

真正稳妥的判断顺序是：先看插件有没有被 OpenCode 解析，再看工具能不能读已有条目，最后做一次跨工具写读。三层都通过，才算真的把两套记忆接成了一套。🧠

那些吐槽，哪些属实

结论先摆桌上：有真实依据，但别被「问模型你是谁」带沟里。

8 月 4 日那边还有另一条硬新闻：Flash API 因「前所未有访问量」容量吃紧，OpenCode 自己也发过告警，官方随后说已恢复。负载是真的猛——OpenCode 还晒过 8 月 1 日单日约 8T tokens（免费 5T + Go 付费 3T）。人多了，卡顿和体感波动都正常。

自报身份不可靠。想判断版本，拿真实 coding / 多轮工具任务并排测，比盘问「你是谁」靠谱。

性价比到底离谱在哪

官方落地页（opencode.ai/go）那张「每 5 小时请求数」条形图，一眼就能看懂 Flash 站哪：

图上谁短谁长不用我多嘴：Grok / Kimi K3 / Qwen Max 一百出头，Flash 直接拉到六万级。便宜、额度进 $60 池、个人重度 coding agent 很难打满。同样体积用量去官方直连，口袋要掏满那$60；Go 这边月费十刀，还顺带一堆 GLM / Kimi / MiniMax / Qwen 等模型。

2× 是限时的（落地页 New 条写着 limited time），促销结束会回落基础档，别按峰值当永久真理。细则仍以 docs/go 与控制台为准。

额度是全模型共享的。你狂烧 GLM-5.2、Kimi K3 这类贵货，Flash 的「几乎无限」会被挤掉。想蹬 Flash，就别把贵模型当背景噪音开着。

我怎么把它接到 Claude Code 里蹬

别人材料里写了很多对比评测。我自己的用法就三步，够用：

人太多会抖，但还没打断我

Flash 现在是全球热点。OpenCode 一家就能晒出单日万亿级 token；官方 API 也出现过容量告警。人多了——印度那边也在猛蹬、各路羊毛党、agent 刷子一起上——上游抖动、偶发变慢甚至「感觉钝了」，都说得通，官方性能被挤差一截也不奇怪。

但这并不碍事。起码目前没有打断我这套工作流，我也没体验到那种「换了个假模型」的断崖差别。有体感落差时，优先查：China opt-in 开了没、是不是高峰挤兑、贵模型有没有在偷额度。

还在观望的，开一个月实测最准：看消耗曲线，也看复杂任务并排对比。对我来说，这五刀订下去，Flash 已经够当日用主力了。