第十一章:设计决策与迭代历程
本章完整记录
my-opencode-deepseek-config从 v1 到 v20 共 83+ 次提交中的每一个关键设计决策——为什么选择 DeepSeek、为什么借鉴这些项目却又不照搬、每一个权衡背后的代价与收益,以及 20 个版本迭代中逐步打磨出来的设计哲学。
11.1 设计决策总览
在开始之前,先回答三个根本问题:为什么是 DeepSeek?为什么是 OpenCode?以及为什么选择纯配置驱动的方案?
11.1.1 为什么选择 DeepSeek 而非其他模型
这个决策是三方面因素的叠加结果:成本、能力、可控性。
成本维度:DeepSeek V4 的定价在同类模型中极具竞争力。Pro 模型(deepseek-v4-pro)输入约 ¥1/百万 tokens,输出约 ¥4/百万 tokens;Flash 模型(deepseek-v4-flash)成本更低。对于一个重度 AI 编码用户而言,日均消耗 50K–80K tokens 是常态——如果使用 Claude 或 GPT-4 系列,日均成本可能在 $2–$5,而 DeepSeek 在相同任务量下成本仅为前者的 1/3 到 1/5。这不仅是”省钱”的问题,更意味着可以更激进地使用多 Agent 架构——因为每个 Agent 的 token 开销不再是瓶颈。
能力维度:DeepSeek V4 Pro 在代码理解和生成任务上表现出了与 Claude 4 和 GPT-5 系列可比的能力水平。特别是其推理(reasoning/thinking)模式在复杂调试、根因分析和多文件重构场景中表现突出。而 Flash 模型在搜索、简单编辑等轻量任务上速度极快,能很好地承担”快件”角色。
可控性维度:相比 Anthropic 和 OpenAI 的频繁 API 变更和定价调整,DeepSeek 的 API 更为稳定,文档清晰,且对中国大陆用户网络友好(无需额外代理即可直连)。此外,DeepSeek 的 provider 从 OpenCode v1.14.24 起被内置支持,无需安装任何额外插件或驱动。
单一 Provider 的锁定的收益与风险:我们通过 enabled_providers: ["deepseek"] 和 disabled_providers 双重配置锁定了唯一 Provider。这个决策的收益是:
- 模型行为一致,Agent 提示词的调优可以精确针对 DeepSeek 的特性
- 成本可预测,不会因为 Provider 切换导致意外开销
- 配置简单,不需要为多 Provider 的兼容性做额外处理
风险是:当 DeepSeek API 出现故障时(这种情况极少发生,但并非不可能),整个系统不可用。对此,我们不是关闭 Provider 锁,而是在 Agent 架构上做了”无状态”设计——所有配置是纯文本文件,切换到其他 Provider 只需修改 opencode.jsonc 中的几行 JSON,不涉及 Agent 提示词和 Skill 的调整。
11.1.2 为什么选择 OpenCode 而非其他 Agent 框架
在 2025-2026 年的 AI 编码工具生态中,有几个主要方向:IDE 插件(Cursor、Copilot)、独立 CLI Agent(Claude Code、gemini-cli)、以及多 Agent 编排框架(OpenCode、Hermes Agent)。我们的选择基于以下分析:
vs IDE 插件的劣势:Cursor 和 Copilot 的核心优势是”开箱即用”——安装后即可使用,学习成本低。但它们的软肋是:
- 多 Agent 能力有限或隐式,无法显式控制 Agent 的职责边界和路由策略
- 配置是 GUI 中的黑盒,无法通过 Git 版本管理,团队共享困难
- 模型选择受限,通常绑定特定 Provider
- Token 消耗策略对用户不可见
vs 独立 CLI Agent 的劣势:Claude Code 等单 Agent 工具虽然强大,但缺乏结构化的多 Agent 协作机制——一个 Agent 要同时扮演探索者、分析者、实施者和审查者,角色冲突导致每个环节都做不深。
选择 OpenCode 的核心理由:
-
原生多 Agent 支持:OpenCode 从架构层面支持多 Agent 协作,包括 Agent 嵌套(
subagent_depth)、自动路由、会话复用和上下文隔离。这不是”把多个对话串起来”的 trick,而是框架级别的能力。 -
纯文本配置体系:OpenCode 的全部配置(
opencode.jsonc、agents/*.md、skills/*/SKILL.md、AGENTS.md)都是纯文本文件,完全可审计、可通过 Git 管理、可直接 Fork 到团队仓库。这是实现”配置即代码”的基础。 -
技能按需加载:OpenCode 的 Skill 机制通过原生
skill工具实现按需加载——Skill 文件存放在磁盘上,Agent 只在需要时才通过skill工具注入上下文。这是本方案 Token 效率策略的基石。 -
Provider 模型解耦:OpenCode 的模型绑定与 Agent 定义解耦,切换模型不影响 Agent 逻辑。这使得我们可以将 Provider 锁定在 DeepSeek,同时保留未来的扩展性。
-
活跃的开发生态:OpenCode 是 GitHub 上活跃的开源项目(由 anomalyco 维护),迭代速度快,社区贡献积极(oh-my-openagent、oh-my-opencode-slim 等衍生配置仓库的出现证明了这一点)。
11.1.3 纯配置驱动的设计选择
“纯配置驱动”不是一句口号——它是一个主动的设计约束。我们用四种纯文本文件类型(JSONC、Markdown)完成了以下全部能力:
| 文件类型 | 实现的能力 |
|---|---|
opencode.jsonc |
模型绑定、Provider 锁定、Agent 定义与权限、命令别名映射、实验功能开关、权限基线策略 |
agents/*.md |
10 个 Agent 的职责定义、行为约束、模型绑定、禁止行为声明 |
skills/*/SKILL.md |
18 个可复用技能的工作流、检查清单、输出格式规范 |
AGENTS.md |
全局规则、核心原则、反模式清单、质量基准、证据纪律、Task Rejection Contract |
为什么不做成代码项目:如果引入 TypeScript 或 Python 脚本,虽然能实现更复杂的逻辑(如动态路由算法、自适应压缩策略),但会带来:
- 依赖管理负担(npm/pip 依赖、版本冲突)
- 调试和测试成本
- 团队协作的学习门槛
- 与 OpenCode 框架的耦合风险
纯配置方案虽然在上限上受限于 OpenCode 的能力边界,但在可靠性、可维护性和可审计性上远超代码方案。这是一个”约束带来自由”的选择——放弃了一些灵活性,换来了极低的维护成本和极高的可复现性。
11.2 借鉴来源与设计吸收
本配置方案的几乎每一个核心设计都受到了业界优秀项目的启发,但关键区别在于:借鉴其核心理念,轻量化吸收,而非照搬其实现。以下是 7 个主要借鉴来源及其在本方案中的具体体现。
11.2.1 oh-my-openagent(by code-yeongyu)
借鉴的理念:意图门控(Intent Gating)、只读隔离、反模式清单。
oh-my-openagent 是 OpenCode 生态中最有影响力的配置仓库之一。它首次提出了在 OpenCode 配置中使用”意图门控”来区分不同类型的用户请求,并建立了只读 Agent(reviewer、oracle)和执行 Agent 的分离。
如何轻量化吸收:
-
意图门控:oh-my-openagent 的意图分类使用了较重的流水线(多次路由判断),本方案简化为 Orchestrator 中的 6 类任务分类 + 模型感知路由,一步完成分类和调度,减少了一次额外的意图分析消耗。
-
只读隔离:保留 oracle、reviewer、explore、librarian 四个 Agent 的只读约束,并增加了”禁止研究/委托”约束给执行 Agent(deep-worker、light-orchestrator),形成双向隔离。
-
反模式清单:oh-my-openagent 在各自 Agent 提示词中分散定义反模式,本方案统一收敛到 AGENTS.md 的全局反模式清单中(Anti-Patterns 章节),所有 Agent 共享,消除了重复声明。
-
去掉的部分:oh-my-openagent 中较重的流水线(多阶段预检、中间态检查点)被去掉。这些机制在复杂项目中确实有价值,但在本方案的 Token 效率优先原则下,它们带来的额外上下文成本超过了收益——flash agent 的快速执行 + 后备链的自动升级已经覆盖了大部分异常场景。
11.2.2 oh-my-opencode-slim(by alvinunreal)
借鉴的理念:调度器优先(Orchestrator-first)、后备链(Fallback Chain)、拒绝契约(Task Rejection Contract)。
oh-my-opencode-slim 是一个极简主义的 OpenCode 配置方案。它的核心思想是:不要把过多能力塞进配置,用一个精简的调度逻辑覆盖 90% 的场景。
具体体现:
-
调度器优先:oh-my-opencode-slim 引入了一个中心化的调度 Agent。本方案继承这一理念,将 Orchestrator 设为
default_agent,所有自然语言请求首先经过它的意图分析和路由判断。与 slim 不同的是,本方案在 Orchestrator 中增加了模型感知路由——根据任务复杂度决定 Pro 还是 Flash 模型,而非均一使用 Pro。 -
后备链:oh-my-opencode-slim 提出了 Agent 失败时的升级链路(简单 Agent → 复杂 Agent)。本方案在此基础上增加了”上下文传递”机制——当一个 Flash Agent(如 light-orchestrator)无法完成任务时,升级到 Pro Agent(deep-worker)时不仅切换模型,还传递完整的失败上下文,避免重复探索。
-
拒绝契约:oh-my-opencode-slim 首次提出了 Agent 必须拒绝越权任务的概念。本方案将这一理念扩展为 AGENTS.md 中完整的 Task Rejection Contract 章节,定义了三种必须拒绝的场景(角色越界、信息不足、能力不足),并要求 Agent 给出明确的拒绝理由和正确的下一步建议。
-
与 slim 的不同:slim 是轻量起点,本方案是生产级完整方案。slim 只有少数几个 Agent 和 Skill,本方案有 10 个 Agent、18 个 Skill、23+ 命令别名和完整的上下文管理策略(DCP + 路径引用 + 去重)。如果用户的场景简单,用 slim 就够了;如果需要覆盖代码审查、安全审查、规约驱动开发、Git Release 等完整工作流,本方案更合适。
11.2.3 anomalyco/opencode(官方仓库)
借鉴的理念:配置 Schema、技能目录体系。
OpenCode 官方仓库的文档和配置示例是本方案的技术基础。主要体现在:
-
配置 Schema:
opencode.jsonc的$schema字段引用https://opencode.ai/config.json,使编辑器(VS Code 等)能提供自动补全和类型检查。本方案严格遵循官方 Schema,没有使用任何非标字段。 -
技能目录体系:OpenCode 官方推荐
skills/<name>/SKILL.md的目录结构,Agent 通过skill工具按名称加载。本方案完全遵循此约定,18 个 Skill 都按此结构组织。同时,在 AGENTS.md 中增加了”使用 Skill 前先检查是否有现成 Skill 覆盖”的指引,避免 Agent 重新发明轮子。 -
权限模型:参考官方的
permission配置结构,定义了read/bash/skill/external_directory四层权限基线,对破坏性 bash 命令(rm -rf、git push --force等)配置ask,对敏感文件(.env、.env.*)配置deny。
与官方默认配置的区别:官方默认配置是一个”裸机”——1 个默认 Agent + 基础权限。本方案在此基础上增加了:9 个额外 Agent、18 个 Skill、完整的 AGENTS.md 全局规则、DCP 智能压缩、命令别名映射。本方案可以理解为一个”预装操作系统”——基础来自官方,但功能由配置层的有机组合而来。
11.2.4 cli/cli(GitHub 官方)
借鉴的理念:gh 完整命令集的 Skill 化封装。
GitHub 官方 CLI 工具 gh 是目前最完整的 GitHub API 命令行客户端。本方案的 gh-cli Skill 不是简单列举常用命令,而是:
-
全面覆盖 v2.96+:覆盖了
gh的所有核心子命令(pr、issue、release、repo、gist、actions、workflow、search、api 等),包括 v2.96+ 新增的 Issues 2.0(支持子 issue、issue type)、discussions、projects、rulesets、agent skills(gh skill)、AI commands(gh copilot、gh agent-task)、repo read-file/read-dir 等。 -
结构化输出与分页:详细说明了
gh的--json+--jq结构化输出模式,以及--paginate分页策略,让 Agent 能够精确提取需要的数据而不需要后续解析。 -
模式区分:明确区分
searchvslist的使用场景——gh search是全 GitHub 搜索(需要--分隔符),gh list是当前仓库/组织的过滤列表。这是实践中容易混淆的点。 -
回退到
gh api:当gh封装命令无法满足需求时(如/review-pr需要逐行评论),Skill 中提供了gh api的直接 API 调用模式。
为什么需要这样一个 Skill:很多 Agent 在需要 GitHub 操作时会”即兴发挥”,写出不存在的 gh 命令或使用错误的参数格式。gh-cli Skill 的定位是”参考手册”——Agent 在需要 GitHub 操作时加载这个 Skill,按图索骥,而不是凭记忆猜测。
11.2.5 OpenSpec(by Fission-AI)
借鉴的理念:Delta Specs(增量规约)、变更提案的完整生命周期(propose → apply → update → archive)。
OpenSpec 是一个规约驱动的软件开发方法论,核心理念是:每一次变更有对应的 spec 文档记录 WHY 和 WHAT,代码变更只是 spec 的实现。本方案的 spec-workflow Skill 吸收了其核心流程:
-
Explore 阶段:在写提案之前先探索代码、勾勒选项和权衡、发现待澄清的问题。这是一个”不承诺任何方案”的思考阶段,类似于 OpenSpec 的 pre-proposal research。
-
Propose 阶段:创建
openspec/changes/<change-id>/,包含proposal.md(WHY 和 WHAT)、tasks.md(可勾选的实现清单)、delta specs(描述规格变更,以 ADDED/MODIFIED/REMOVED/RENAMED 标注),以及可选的design.md(HOW)。 -
Apply 阶段:按
tasks.md逐项勾选执行,如果设计出现问题则更新 delta specs,而非悄悄偏离 spec。 -
Update 阶段:对于已存在但尚未完成的变更提案,允许原地修订(而非重新创建)。这条路径在 OpenSpec 原始流程中不够明确,本方案将其独立为一个阶段。
-
Archive 阶段:将 delta specs 归档合并到
openspec/specs/中的源 spec 文件,变更目录移入archive/并追加日期前缀。 -
差异化设计:OpenSpec 的原始流程中缺少”实现前规划验证”环节,本方案在 v18 迭代中增加了
/verify-plan命令(加载verification-planningSkill),在 Propose 和 Apply 之间插入一个验证规划步骤。同时,spec-workflow 的每个命令都做了精确的 Agent + Skill 绑定:
| 命令 | Agent | 模型 | 说明 |
|---|---|---|---|
/explore |
explore | Flash | 探索阶段只需搜索和概览,不需要深度推理 |
/propose |
planner | Pro | 提案需要架构思维和技术判断 |
/apply |
deep-worker | Pro | 多文件实现是重型任务 |
/update |
planner | Pro | 修订提案需要重新评估设计 |
/archive |
light-orchestrator | Flash | 归档是机械性操作,不需要推理 |
11.2.6 mattpocock/skills
借鉴的理念:交接文档(Handoff)、结构化调试(Structured Debugging)。
Matt Pocock 是 TypeScript 社区的知名教育者,他的 skills 仓库中提出了两个在实际开发中非常有价值的模式:
- 交接文档:当 AI Agent 的会话过长需要中断或切换时,不把所有原始上下文复制到下一个会话,而是生成一个压缩的”交接文档”——包含当前任务状态、关键发现、待办事项和后续建议。本方案的
handoffSkill 继承这一理念,并做了增强:- 输出到系统临时目录(而非项目目录,避免污染 Git 仓库)
- 引用已有制品(specs、plans、diffs)的路径而非复制内容
- 包含
suggested-skills章节,建议下一个会话应加载哪些 Skill - 自动脱敏敏感信息
- 结构化调试:Matt Pocock 提出了分阶段的调试方法论。本方案将其发展为
diagnoseSkill,采用 6 阶段结构化调试流程:复现(Reproduce)→ 最小化(Minimize)→ 假设(Hypothesize)→ 打点(Instrument)→ 修复(Fix)→ 回归(Regression-test)。每个阶段有明确的输入输出和 Go/No-Go 条件,避免”试错式调试”。
11.2.7 deepreview(by mechanai)
借鉴的理念:熵扫描(Entropy Scanning)、收敛检查(Convergence Check)。
deepreview 是一个实验性的代码审查工具,提出了一些在传统代码审查中不常见的维度:
-
熵扫描(Entropy Scanning):检查代码中是否存在”意义漂移”——同一概念被多个不同的变量名指代、同一变量名在不同上下文中指代不同概念、复杂度过高的函数中存在多个半相关的子逻辑。这个概念在 code-review Skill 中被吸收为审查维度的”命名一致性”和”关注点分离”检查。
-
收敛检查(Convergence Check):检查连续的代码变更是否存在”重复模式”——比如连续 3 个 commit 都在修改同一个函数的同一段逻辑,说明之前的修改没有”一刀切干净”。这个概念被化为 code-review Skill 中的”反复修正检测”——如果发现一个 PR 在同一个位置的多次修改,标记为可能存在的设计问题或理解不足。
本方案的落地:熵扫描和收敛检查不是作为独立的检查工具存在,而是集成到 code-review Skill 的审查维度中,与 security、performance、maintainability 等维度并列。审查时,reviewer Agent 会根据 diff 的特征自动判断是否需要激活这些维度——小型 diff(单文件少量修改)通常不触发熵扫描,大型 diff(多文件、多函数修改)则几乎必然触发。
11.3 关键设计权衡
每一个设计决策都面临两难。本节逐一拆解本方案中五个最关键的设计权衡,分析每个选择背后的代价和收益。
11.3.1 执行与探索分离
决策:deep-worker 和 light-orchestrator 的系统提示中明确写入”禁止研究、禁止委托”——它们必须基于 Orchestrator 提供的上下文执行,不得自行探索代码库或委托给其他 Agent。反过来,explore、librarian 和 oracle 虽然可以探索,但被设为只读,不能修改文件。
为什么这样设计:
在早期的实践(v1-v3)中,我们尝试过”全功能 Agent”——每个 Agent 既可以探索又可以执行。结果出现了两类典型问题:
第一类是上下文雪崩:Agent A 在执行过程中发现信息不足,自行搜索代码库。搜索结果占用了大量上下文,Agent A 基于搜索结果又发现了新的问题,继续搜索……当 Agent A 的上下文超过 50K tokens 时,它开始”遗忘”最初的执行目标,转而处理探索过程中发现的新问题。最终,原始任务没完成,上下文已经膨胀到了 80K+ tokens。
第二类是角色漂移:一个被分配去”修复登录 Bug”的 Agent,在探索过程中发现了 3 个”看上去需要改进”的代码片段,顺手修改了它们。这些”额外修改”未经审查、未经测试、与原始任务无关,却引入了新的 Bug。
解决方案的代价:
- 灵活性降低:在某些场景下,执行 Agent 确实需要”看一下某个文件确认信息”,但被硬约束禁止了。这意味着 Orchestrator 必须在调度时提供比”刚好够”更多的上下文,增加了 Orchestrator 的负担。
- 对 Orchestrator 的要求更高:调度方需要准确预判执行 Agent 需要哪些上下文。如果预判不足,Agent 会返回”需要更多上下文”的拒绝,导致一轮额外的调度往返。
收益:
- Token 消耗可控:执行 Agent 的上下文大小保持在一个稳定的范围内(通常 10K–25K tokens),不会出现”雪崩式增长”。
- 可审计性:修改的代码和探索的报告来自不同的 Agent,可以独立审查。如果一段代码改了,你知道是哪个 Agent 改的、基于谁的探索结果改的。
- 防止”顺手修”:执行 Agent 必须严格按计划行事,不能”顺手优化”不相关的代码。
11.3.2 只读 Agent 的隔离
决策:oracle、reviewer、explore、librarian 四个 Agent 被设为只读——它们可以读取文件、搜索代码、分析逻辑,但不能修改任何文件。这一约束通过 Agent 的系统提示声明,并在 opencode.jsonc 的权限配置中做了双重保障。
为什么这样设计:
只读隔离不是”限制 Agent 的能力”,而是”保护 Agent 的判断”。
-
防止越权修改:reviewer 被发现”代码有问题”时,如果它有写权限,它可能直接修改代码。但这混淆了两个不同的角色——审查和实现。审查者的职责是”发现问题并报告”,实现者的职责是”在理解问题的基础上修改代码”。两者合一会导致:审查不够客观(审查者会倾向于”自己改就行”而不是”系统性地审查”),修改不够慎重(修改者没有做独立的方案评估)。
-
确保分析客观:oracle 在进行根因分析时,如果它可以修改代码,它可能会”推理出一个原因,然后自己去验证”。但根因分析需要的是”穷举所有可能的原因并逐一排除”,而非”找到一个合理的原因就停下来”。只读约束让 oracle 只能报告分析结果,不能替自己”证明”。
代价:
- 需要额外的写 Agent 接力:审查报告出来后,需要一个写 Agent(deep-worker 或 light-orchestrator)来落实修复。这意味着一次典型的”审查→修复”流程需要两轮调度(reviewer → deep-worker),增加了 Orchestrator 的中转开销。
- 分析结果的传递可能有损耗:oracle 的分析报告是一个文本,deep-worker 基于这个文本来执行修复。如果报告不够精确,deep-worker 可能需要返回去”再确认”。
收益:
- 安全性:只读 Agent 的操作可以被完全审计——它们读取了什么文件、分析了什么逻辑,都有记录。如果分析有误,可以回溯到具体的”读取”和”推理”步骤。
- 质量保证:审查者和修复者不是同一个”人”,修复的结果需要经过再次审查(这恰好是
/review-loop命令的设计目标)。
11.3.3 模型隔离(仅 DeepSeek)
决策:通过 enabled_providers: ["deepseek"] 和 disabled_providers: ["openai", "anthropic", "google", "openrouter"] 双重配置,将本配置方案的模型选择锁定在 DeepSeek V4 双模型。AGENTS.md 进一步增加了”不允许引入新模型”的硬约束。
为什么这样设计:
-
团队统一:在团队使用场景下,如果每个开发者使用不同的 Provider,产生的代码风格、质量特性、甚至对同一问题的回答都会有差异。统一模型 = 统一行为。
-
成本可控:DeepSeek 的定价结构清晰且稳定。如果开放多 Provider,开发者可能会在不知情的情况下切换到更贵的模型,导致 API 账单超出预期。
-
提示词调优精准:不同的模型对提示词的响应特征不同——有些模型对”不要做 X”的指令更敏感,有些则对”请做 Y”的正向引导更敏感。锁定单一模型意味着 Agent 提示词可以针对 DeepSeek V4 的特点做精确调优,不需要”兼容多个模型”。
代价:
- 无法利用其他模型的优势:Claude 在某些场景(如长篇文档生成)中有独特优势,GPT-5 在特定代码模式识别上可能表现更好。锁定 DeepSeek 意味着这些优势无法被利用。
- 单点依赖:DeepSeek API 的可用性决定了整个系统的可用性。
缓解措施:
- 配置解耦:所有 Agent 系统提示和 Skill 中不包含 Provider 相关的硬编码。切换模型只需修改
opencode.jsonc中的 Provider 配置,不需要改 Agent 提示词。 - AGENTS.md 的”No new models”约束是”配置层面的约束”而非”框架层面的限制”——如果团队决策改变,修改这一条即可。
11.3.4 Flash 优先的路由策略
决策:Orchestrator 在路由时遵循”Flash 优先”原则——搜索、查找、简单编辑等明确定义的任务优先路由到 Flash Agent(explore、librarian、light-orchestrator)。只有当任务明确需要深度推理(规划、分析、审查)或任务超出 Flash 能力时才使用 Pro。在路由边界模糊时,优先选择 Flash。
为什么这样设计:
最直观的原因是成本。DeepSeek V4 Pro 的输出价格约为 Flash 的 2 倍。一个典型开发任务中,80% 的步骤不需要强推理——搜索文件位置(”这个接口定义在哪里?”)、查询文档(”React 19 的 use() 怎么用?”)、简单语法修改(”把这里改成 const”)、生成提交信息——这些用 Flash 完全足够。如果所有任务都用 Pro,每天多花费近 50% 的 Token 却没有带来实质性的质量提升。
但成本只是表层原因。更深层的原因是响应速度:Flash 模型的推理速度显著快于 Pro。在交互式开发中,用户等待 3 秒和等待 8 秒的体验差异很大。Flash 优先的策略让 80% 的”快问快答”场景保持低延迟。
实际节省效果:
以一次典型的”排查 Bug 并修复”会话为例:
| 步骤 | Flash 路由方案 | 全 Pro 方案 |
|---|---|---|
| 搜索相关文件 | explore (Flash): ~3K tokens | Pro Agent: ~5K tokens |
| 分析根因 | oracle (Pro): ~12K tokens | oracle (Pro): ~12K tokens |
| 查阅 API 文档 | librarian (Flash): ~2K tokens | Pro Agent: ~4K tokens |
| 修改代码 | deep-worker (Pro): ~15K tokens | deep-worker (Pro): ~15K tokens |
| 生成提交信息 | light-orchestrator (Flash): ~2K tokens | Pro Agent: ~3K tokens |
| 总计 | ~34K tokens | ~39K tokens |
在更大的项目中,这种差异会更加显著——当探索步骤涉及 10+ 个文件时,Flash 和 Pro 的差异可能达到每次探索节省 5K–8K tokens。
后备链的价值:
Flash 优先路由有一个配套机制:后备链。当一个 Flash Agent 无法完成任务时(例如 light-orchestrator 遇到了超出预期的复杂逻辑),它不会”硬做”,而是将任务升级到 Pro Agent(如 deep-worker),并传递完整的任务上下文。这意味着”Flash 优先”不是”只用 Flash”——当 Flash 不够时,系统会自动升级。
11.3.5 技能按需加载
决策:18 个 Skill 通过 OpenCode 原生的 skill 工具按需加载——Agent 的初始上下文中不包含任何 Skill 的完整内容。只有当 Agent 在运行时显式调用 skill 工具时,对应 Skill 的内容才会被注入上下文。
为什么不把技能内容直接嵌入 Agent prompt:
如果把 18 个 Skill 的全部内容直接嵌入到 Agent 系统提示中,每次对话启动时都会注入这些内容。粗略估算,18 个 Skill 的累计体积约为 50K–80K tokens。这意味着:
- 一个”帮我看看这个变量定义在哪里”的简单查询,要额外携带 50K+ tokens 的 Skill 指令
- 用户支付的 Token 中,可能只有 5% 花在实际任务上,95% 花在了”可能有用但实际没用”的技能指令上
- 过大的系统提示会压缩可用的上下文窗口,降低长对话的质量
按需加载 vs 预加载的 Token 消耗对比:
以一个 5 轮对话的代码审查任务为例:
| 策略 | 每轮注入 | 实际使用 | 浪费比例 |
|---|---|---|---|
| 全量预加载 | 80K(18 个 Skill) | 10K(code-review Skill) | 87.5% |
| 按需加载 | 0(初始)→ 10K(仅 code-review) | 10K(code-review Skill) | 0% |
累积体积分析:18 个 Skill 中,体积较大的(code-review、spec-workflow、gh-cli)各约 8K–12K tokens,较小的(conventional-commits、git-release)各约 2K–4K tokens。如果在每次对话中全量注入,日均消耗会增加 30K–50K tokens。以每月 20 个工作日计算,每月额外消耗 600K–1M tokens,折合额外成本约 ¥6–¥10/月——看似不多,但对于重度用户而言,再加上其他 Token 效率优化的叠加效应,总体节省可达 30%–50%。
代价:
- Agent 需要”知道 Skill 的存在”才能加载:如果 Agent 没有被告知某个 Skill 存在,它不会自行加载。这意味着 Orchestrator 的提示词中需要包含 Skill 列表的简要描述(不是完整内容,只是名称+一句话说明),这消耗约 1K–2K tokens。这是必要的”目录”成本。
- 加载 Skill 是一个额外的工具调用:Agent 需要先调用
skill工具,等待 Skill 内容注入,然后再开始执行任务。这比”内置”多了一个步骤,但延迟通常可以忽略(Skill 内容在本地磁盘,注入耗时 < 1 秒)。
11.4 迭代里程碑详细记录
以下是本配置方案从 v1 到 v20 的完整迭代记录。每个版本都标注了关键变更、变更动机和遇到的问题。这不是一个”成果展示”,而是一个”决策日志”——后续版本的设计决策几乎都可以追溯到早期版本的实践反馈。
v1-v7:奠基阶段
v1:双模型绑定
最初版本只做了一件事:在 opencode.jsonc 中绑定 DeepSeek V4 Pro 为主模型、Flash 为小模型。这是整个方案的起点——证明了双模型配置在 OpenCode 中是可以工作的。当时还没有任何 Agent 定义,只是让 OpenCode 的默认 Agent 使用 DeepSeek。
决策记录:为什么选 Pro 而非 Flash 作为主模型?——因为主模型是默认 Agent 使用的模型,默认 Agent 承担了”理解用户意图”和”执行任务”的双重职责,这需要推理能力。如果主模型用 Flash,会导致复杂任务处理质量下降。而小模型用 Flash,让系统 Agent(compaction、summary、title)享受低成本。
v2:Agent 角色体系建立
在 agents/ 目录下创建了第一批 Agent 定义文件:orchestrator、planner、deep-worker、oracle、reviewer。每个 Agent 有了独立的职责描述和能力边界。但这一版中,Agent 之间还没有清晰的路由机制——用户需要手动指定要使用哪个 Agent。
遇到问题:手动指定 Agent 的使用门槛太高。新用户不知道什么时候该用 planner、什么时候该用 oracle。需要一种”自动路由”机制。
v3:意图门控与分类路由
在 Orchestrator 的系统提示中增加了完整的意图门控表——6 类任务分类(探索、规划、实现、审查、咨询、维护),每类有预设的 Agent → 模型映射。用户只需用自然语言描述需求,Orchestrator 自动判断意图并路由。
决策记录:为什么是 6 类?——最初设计了 8 类,但在实践中发现”维护”和”优化”总是合并出现、”部署”类任务通常被归入”实现”。经过 2 周的实地使用反馈,合并为 6 类。这不是”设计出来的”,而是”清理出来的”。
v4:AGENTS.md 全局规则
创建了 AGENTS.md 文件,将之前散落在各 Agent 提示词中的公共规则(代码风格、命名约定、反模式)集中管理。这是”去重”思维的第一次实践——当同一个规则在 3+ 个 Agent 提示词中重复出现时,就应该上移到全局规则。
决策记录:AGENTS.md 和 Agent 提示词的重叠部分怎么处理?——遵循”AGENTS.md 优先”原则。Agent 提示词只写本 Agent 独有的职责和约束,不重复 AGENTS.md 中已有的内容。如果 AGENTS.md 中已有”禁止创建 utils.ts”,Agent 提示词中不再重复。
v5:Skills 目录与命令别名
建立了 skills/ 目录结构,创建了第一批 Skill 文件(code-review、gh-cli、conventional-commits、security-review)。同时在 opencode.jsonc 中定义了第一批命令别名(/deep、/quick、/review、/plan、/search 等)。
决策记录:命令别名的命名遵循”短、直观、符合直觉”原则。/deep 而非 /heavy-implementation,/quick 而非 /light-task。因为在终端输入时,每个字符都是成本——/deep(5 个字符)vs /heavy-implementation(21 个字符)。
v6:权限基线配置
在 opencode.jsonc 中增加了完整的权限配置:对 .env 类敏感文件设为 deny,对破坏性 bash 命令(rm -rf、git push --force、git reset --hard 等)设为 ask,对外部目录访问设为 ask。
决策记录:为什么 .env.example 要 allow?——因为 .env.example 是公开的模板文件,不含密钥,而且 Agent 在初始化项目时经常需要读取它来了解需要的环境变量。如果把它也 deny 了,很多初始化任务会卡住。
v7:第一次大规模测试和优化
这是奠基阶段的收尾。对 v1-v6 的功能进行了为期一周的全面测试,发现了 30+ 个问题:路由错误(oracle 被调去执行编辑操作)、Skill 加载失败(路径错误)、命令别名冲突等。修复后形成了稳定的 v7 基线。
v8-v12:审查 + 规约增强
v8:增强 code-review
最初的 code-review Skill 比较简单——只是几个检查维度。v8 进行了全面增强:
- 多维度审查:security、performance、maintainability、naming、error-handling、testing 共 6 个维度
- 严重度分级:引入 critical / high / medium / low / info 五级严重度,并给每级明确的定义标准
- 上下文校准(Context Calibration):要求审查开始前先评估项目类型(库 vs 应用、前端 vs 后端),据此调整各维度的权重——一个 React 组件库的 accessibility 权重应该高于一个 CLI 工具
- 拒绝准则:定义了”不审查”的场景——diff 过大(>1000 行)、缺少测试、没有明确的 base branch
决策记录:严重度分级不是”主观判断”,而是基于函数签名——critical = 安全漏洞/数据丢失;high = 功能错误/性能退化;medium = 可维护性问题;low = 风格不一致;info = 建议性质的改进。
v9:建立 spec-workflow
引入了 OpenSpec 启发的规约驱动工作流。创建了 spec-workflow Skill,定义了 Explore → Propose → Apply → Archive 四个阶段的完整流程和输出格式。这是本方案”工程纪律”理念的核心体现。
决策记录:Archive 阶段为什么重要?——因为 delta specs(ADDED/MODIFIED/REMOVED)如果在 Apply 后不归档,随着变更累积,spec 文件会变成”无法阅读”的增量日志。Archive 阶段将 delta specs 合并到源 spec 中,保持 specs 文件的可读性和权威性。
v10:新增 deepwork 技能
创建了 deepwork Skill——一个审查门控的分阶段执行流程:Plan(写计划制品)→ Review Gate(人工审批)→ Implement(按计划执行)→ Verify(验证结果)→ Report(生成完成报告)。适用于 3 文件以上的复杂改动。
决策记录:deepwork 的”门控”机制是对抗 AI Agent “过度自信”的关键。Agent 倾向于”直接开始写代码”而不是”先想清楚再写”。Review Gate 强制 Agent 在动手之前等待人类确认计划——这是一个”减速带”,但保证了复杂任务的质量。
v11:新增 reflect 和 verification-planning
reflect Skill 建立了持续改进闭环:回顾近期工作 → 发现摩擦点 → 提出最小配置优化。verification-planning Skill 在实现前规划最窄的验证路径。
决策记录:为什么 reflect 要由 oracle 执行而非 planner?——因为 reflect 需要”深度分析工作模式”,这是 oracle 的专长。planner 擅长”向前看”(规划未来),oracle 擅长”向后看”(分析过去)。
v12:gh-cli 对齐 v2.96+
将 gh-cli Skill 更新为对齐 GitHub CLI v2.96+ 的最新功能,包括 Issues 2.0(子 issue、issue type)、discussions、projects、rulesets 等新增子命令。
v13-v15:契约 + 精简
v13:AGENTS.md 新增 Evidence Discipline
在 AGENTS.md 中新增了完整的 Evidence Discipline 章节。定义了一个硬约束:没有可验证的证据,不能声称任务完成。Agent 必须在报告完成前提供至少一条可验证的证据(测试通过、构建成功、lint 检查干净、端到端验证)。
决策记录:这个章节的触发原因是一次真实事故——一个 Agent 声称”修复了 Bug”,但实际上只改了代码却没有运行测试。测试实际上是失败的。因为 Agent 说”已完成”,用户就合并了代码,结果 CI 失败。Evidence Discipline 是说”不要相信我,证明给我看”。
v14:新增 Task Rejection Contract
在 AGENTS.md 中新增了 Task Rejection Contract 章节。定义了 Agent 必须拒绝执行的三类任务:角色越界(只读 Agent 被要求编辑)、信息不足(不知道哪个文件/什么错误)、能力不足(需要更强的 Agent)。每次拒绝必须在 1-2 句话内说明原因和正确的下一步。
决策记录:拒绝契约是 oh-my-opencode-slim 的理念的具体化。我们增加了”拒绝的格式要求”——必须是纯文本、1-2 句话、说明原因和建议的下一步。这是为了让 Orchestrator 能解析拒绝信息并采取正确的后备链操作。
v15:全量去重 agent prompt 与全局规则
这是第一次全面去重。遍历了所有 Agent 系统提示词,将 AGENTS.md 中已覆盖的规则从 Agent 提示词中移除。结果是平均每个 Agent 提示词减少了 20% 的 Token 消耗。
v15 补充:补齐后台子 agent 错误核查
发现了 OpenCode 后台子 Agent(build、plan、compaction 等系统 Agent)在异常场景下的错误处理不完整。比如 compaction Agent 在压缩失败时没有降级方案。v15 在 opencode.jsonc 的 Agent 配置中为这些系统 Agent 补充了 fallback 配置——当 Flash 模型的 compaction 失败时,回退到 Pro 模型。
v16-v18:高效执行
v16:移除神话名称、合并路由表
这是 AGENTS.md 和 Orchestrator 提示词的一次”清理”优化。移除了之前版本中一些过度修饰的命名(如”神圣的 Orchestrator”、”终极审查者”等),回归到简洁的功能性描述。同时将 Orchestrator 中原本分散在多个章节的路由规则合并为一个集中的路由表,减少 Agent 在解析路由逻辑时需要的上下文量。
决策记录:神话名称的引入最初是为了”给 Agent 更强的身份认同”,但实践中发现:Agent 对”身份”不敏感,对”职责边界”敏感。一个叫”代码守护者”的 Agent 和叫”reviewer”的 Agent 在审查质量上没有差异,但前者的提示词比后者多了 200+ tokens 的”身份描述”。移除这些没有实际价值的修辞,每次对话净省 ~2K tokens。
v17:gh-cli 扩至 Issues 2.0
将 gh-cli Skill 从基础版本扩展到覆盖 Issues 2.0 的完整功能集:子 issue 的创建和关联、issue type(Bug/Feature/Task)的 --type 参数、issue 的层级关系管理。
v18:spec-workflow 增加 verify + 决策框架
在 spec-workflow 的 Propose 和 Apply 之间嵌入了 verify 步骤(通过 /verify-plan 命令触发)。同时增加了决策框架——在 Propose 阶段引入了”权衡分析”模板,要求提案中明确列出每个方案的 pros/cons 和推荐理由。
决策记录:verify 步骤的增加源于实践中的一个典型问题——Propose 阶段的 proposal.md 写得很好,但实现时发现”测试不了”(依赖外部服务)或”无法验证”(需要特定的环境)。verify 阶段在动手实现之前就识别出这些”验证盲区”,避免了”实现完了才发现无法验证”的尴尬。
v19:对齐上游
v19.1:复核 6 个上游仓库
由于 OpenCode 和相关生态项目迭代迅速,进行了全面的上游对齐:复核了 anomalyco/opencode 的最新配置 Schema 变更、oh-my-openagent 的最新路由策略、oh-my-opencode-slim 的最新拒绝契约措辞、cli/cli(gh)的 v2.96+ 新功能、OpenSpec 的最新归档流程、以及 mattpocock/skills 的新技能模式。
发现的主要变更:
- OpenCode 新增了
experimental.batch_tool选项(已在本方䅁中启用) - cli/cli 的 Issues 2.0 有一些 API 调整(已在 v17 中更新)
- OpenSpec 的归档流程增加了一些 meta 文件(已在 spec-workflow 中适配)
v19.2:修正 /review-pr 逐行评论 Bug
/review-pr 命令之前使用 gh pr review 来提交审查结果。但 gh pr review 不支持逐行评论(per-line comments)——它只能提交一个整体的 review body。这意味着代码审查发现的”第 42 行有安全隐患”无法精确标注位置,只能写在 body 中靠文字描述。
修复方案:改为使用 gh api repos/{owner}/{repo}/pulls/<n>/reviews 直接调用 GitHub API,通过 event=COMMENT 和 comments[] 数组提交带行号标注的评论。
v19.3:code-review 路由从裸行数改为有效逻辑体量
之前的 code-review Skill 中,审查深度根据 diff 的行数来决定。实践中发现”行数”是一个误导性的指标——一个 200 行的配置文件(如 package.json)和一个 200 行的核心业务逻辑函数,需要的审查深度完全不同。
v19 将审查深度判断从”裸行数”改为”有效逻辑体量”——排除纯配置变更、排除注释行、排除空白行、排除 import/export 语句,只计算包含业务逻辑的实际代码行数。这是一个”更精准的复杂度判断”,避免了在简单文件上浪费审查深度,也避免了在复杂文件上审查不足。
v20:重构优化
v20 是目前最大的一次”瘦身和强化”并行迭代。与之前的迭代(要么加功能、要么减体积)不同,v20 同时做了两者——通过去掉冗余换出空间,再在省出的空间中新增强功能。
v20.1:agent/ → agents/ 目录对齐
OpenCode 官方推荐的 Agent 定义目录是 agents/(复数形式)。本方案早期使用了 agent/(单数形式)。v20 将目录名对齐为 agents/,确保与官方约定一致,避免未来 OpenCode 对目录名做严格校验时出现问题。
v20.2:AGENTS.md 精简 22%(292 → 229 行)
这是第二次全面去重,也是力度最大的一次。目标是:AGENTS.md 中的每一条规则必须是”真正全局的”——如果一条规则只和某类 Agent 相关(如”只读 Agent 不能修改文件”),它应该只在相关 Agent 的提示词中出现,不应该占用所有 Agent 的上下文。
精简手段包括:
- 移除与 Agent 提示词重复的规则(已定义的职责描述)
- 合并相似规则(”代码风格”和”质量基准”中有重叠的条目)
- 删除对 Agent 行为无实质影响的”说明性文字”
- 用更少的词表达相同的约束
结果:229 行,减少 22%,但规则覆盖率不变——被移除的 63 行要么是重复的,要么是冗余的说明。
v20.3:新增 diagnose(6 阶段调试)+ handoff(会话交接)技能
diagnose Skill 吸收了 mattpocock 的结构化调试理念,扩展为 6 阶段流程:
- Reproduce:用最少步骤复现问题。如果无法复现,后续阶段无意义——Go/No-Go 门槛。
- Minimize:将问题缩小到最小可复现范围(最小代码片段、最简操作序列)。
- Hypothesize:列出所有可能的原因,按概率排序。不跳过”不太可能但可能”的原因。
- Instrument:打点/日志/断点,收集证据来验证或排除每个假设。
- Fix:基于确认的根因进行修复——只修复根因,不远距离关联修复。
- Regression:验证修复确实解决了原问题,且没有引入新问题。
handoff Skill 将长会话压缩为交接文档,包含任务状态、关键发现、待办事项、建议加载的 Skill 和上下文压缩的引用路径。输出到系统临时目录,不污染项目 Git 仓库。
v20.4:spec-workflow 增加 /update 命令
在 spec-workflow 中新增了 /update 命令——允许对已存在但尚未完成的变更提案进行原地修订。之前的流程中,如果需要修订提案,必须重新走 /propose 流程,但提案中的部分内容(如 proposal.md 中的 WHY)不应该被重新创建。/update 解决了这个”修订一个未完成的提案”的空白地带。
v20.5:code-review 增加熵扫描 + 收敛检查
将 deepreview 项目中的熵扫描和收敛检查概念落地到 code-review Skill 中。具体实现是增加了两个审查子维度:
- Naming Cohesion(命名一致性):检查 diff 中是否有人为不同的事物用了相同的名字,或为相同的事物用了不同的名字。
- Iteration Convergence(迭代收敛检查):检查 diff 中是否有”修改了 3 次同一行代码”的模式,这可能意味着设计层面的问题,而非单纯的技术错误。
v20.6:agent prompt 去重 20%
与 v15 的第一次去重不同,v20 的去重是在 Agent 提示词之间进行的。方法是:提取出 2 个以上 Agent 共同使用的能力描述(如”如何读取文件”、”如何理解用户意图”),并将它们上移到 AGENTS.md 或 Orchestrator 提示词中。最终每个 Agent 提示词平均减少 20% 的篇幅,节省的 Token 用于承载 v20 新增的功能描述。
11.5 设计哲学总结
经过 20 个迭代阶段和 83+ 次提交,本方案形成了四条清晰的设计原则。它们不是”预设的信念”,而是”贯穿始终的实践法则”。
原则一:精简优先于新增
信条:每次迭代以净减 Token 为目标。如果要新增一个功能,先看看能否通过精简已有内容来腾出空间。
这不是”反对增加功能”,而是”对每个新增功能要求更严格的论证”。v20 是这一原则的最佳示范——同时做了四个增强(diagnose、handoff、/update、熵扫描+收敛检查)和两个瘦身(AGENTS.md 精简 22%、agent prompt 去重 20%),净效果是功能更强但 Token 总消耗反而降低。
具体度量:在每次发版前,统计所有 Agent 提示词 + 所有 Skill + AGENTS.md 的总 Token 数。如果在新增功能后总 Token 数增长超过 5%,需要明确的论证来解释为什么这 5% 的增长是必要的。
原则二:借鉴而非照搬
信条:外部项目的优良设计,只汲取其核心理念并做轻量化吸收,不照搬实现。
这不是”看不起别人的代码”,而是”承认每个项目有自己的上下文和约束”。oh-my-openagent 的重流水线在其上下文中有价值,但在本方案中以 Token 效率的视角看就是过度设计。OpenSpec 的规约流程在独立工具中可以很重,但在 Skill 中必须精简为核心步骤。
具体体现:
- 从 oh-my-openagent 汲取了意图门控,但去掉了多阶段预检
- 从 OpenSpec 汲取了 delta specs,但将流程打包为 5 个独立命令(而非一个厚重的工具)
- 从 deepreview 汲取了熵扫描,但作为 code-review 的一个子维度而非独立检查工具
原则三:冗余由现有能力覆盖
信条:在不新增重复功能的前提下,优先利用现有 Agent 和 Skill 的组合来覆盖新需求。
“冗余”的定义:如果一个新的 Skill 的内容有 50% 以上与已有 Skill 重叠,或者一个新的 Agent 的职责与已有 Agent 有 60% 以上的交集,那就是冗余。
实例分析:在 v18 讨论是否要新增加一个”性能分析”Skill 时,分析发现 code-review 的 performance 维度已经覆盖了静态性能分析,oracle 的根因分析能力可以覆盖动态性能问题。新增一个 Skill 只会造成 token 浪费和 Agent 选择困惑。最终决定不增加。
原则四:持续演进而非一次到位
信条:设计决策在初始时只做”足够好”的判断,然后通过 reflect 机制持续发现摩擦并驱动改进。
v1 的配置和 v20 的配置看起来差异巨大,但这不是因为”v1 的设计错了”,而是因为”通过 20 个迭代逐步发现并修复了 v1 中不够好的部分”。如果一开始就试图设计一个”完美的 v1”,大概率会过度设计——很多”想象中的需求”在实践中并不存在,而很多”实践中才暴露的问题”在设计时完全无法预见。
11.6 未来演进方向
本配置方案是”活的”——它随 OpenCode 框架的演进、DeepSeek 模型的迭代、以及社区实践的积累而持续进化。以下是当前识别的几个未来演进方向,按优先级排序。
方向一:更多 DeepSeek 模型支持
现状:当前只使用 DeepSeek V4 的 Pro 和 Flash 两个模型。
演进路径:如果 DeepSeek 发布新模型(如 V5、推理专用模型、长上下文模型等),在不违反”模型隔离”原则的前提下,可以考虑在 Agent 层面做更细粒度的模型分配。例如:
- 超长上下文任务(如全仓库级重构分析)使用专用长上下文模型
- 特定领域的高难度推理任务使用推理专用模型
- 保持 Flash 模型作为”轻量兜底”
约束:引入新模型的前提是不增加 Agent 的”模型选择困惑”——每个 Agent 应该仍然绑定单一模型,路由逻辑由 Orchestrator 负责。
方向二:技能体系的持续丰富
现状:18 个 Skill 覆盖了代码审查、安全审查、规约驱动开发、Git 操作、调试和交接等核心场景。
演进路径:以下是当前识别的高价值技能扩展方向:
-
多语言/多框架专项:虽然现有 Skill 是语言无关的,但某些场景下”知道 React 特有的陷阱”比”通用的代码审查”更有价值。考虑增加框架专项的子 Skill,但通过”条件加载”而非”全量注入”来保持 Token 效率。
-
团队协作增强:增加技能来管理”团队编码规范”的版本化和同步——当前
AGENTS.md是团队共用的,但缺乏”团队成员发现新反模式→提议加入 AGENTS.md”的流程化机制。 -
CI/CD 集成:增加技能让 Agent 能理解和操作 CI/CD 流程——读取 CI 日志、分析失败原因、提出修复方案。
方向三:更多自动化工作流
现状:/review-loop(审查→修复循环)和 spec-workflow 的 /explore → /propose → /apply → /archive 链已经实现了自动化工作流。
演进路径:
-
端到端的 PR 自动化:从”创建分支 → 开发 → 审查 → 修复 → 合并 → 归档 → 发布”的完整自动化链路。当前每个环节都有独立的命令,但还没有一条”端到端”的命令。
-
定时任务触发:利用 OpenCode 的会话复用能力,设计”定时审查”工作流——每天定时触发一次对当天所有修改的自动审查。
-
跨仓库协调:当一次变更涉及多个仓库时(monorepo 场景),自动化跨仓库的 spec 同步和版本协调。
方向四:社区贡献方向
现状:本仓库在 GitHub 上以 MIT 许可证开源,目前有 36 Star 和 9 Fork。
演进路径:
-
完善教程体系:当前正在编写 12 章的完整教程(你正在阅读的文档即是其中一部分),目标是将”如何设计一套 OpenCode 配置”的知识显性化和可传播。
-
模块化配置拆分:当前的配置是”一个大而全的仓库”。未来可能拆分为”核心配置 + 可选模块”的架构,让用户可以根据需要选择加载哪些模块(如”只需代码审查,不需要 spec-workflow”)。
-
中文社区推广:OpenCode 的多 Agent 配置目前在中文开发社区的认知度较低。通过教程、示例和实战分享,降低中文开发者的入门门槛。
-
贡献上游:将本方案中发现的 OpenCode 框架可以改进的点(如 Skill 按需加载的缓存优化、Agent 权限模型的更细粒度控制)以 Issue 或 PR 的形式贡献回 OpenCode 官方仓库。
本章小结
回到开头的三个问题,现在有了完整的答案:
为什么选择 DeepSeek? —— 成本、能力和可控性的三重优势。DeepSeek V4 双模型在编码任务上表现出色,成本仅为同类方案的 1/3 到 1/5,且 API 稳定、文档清晰、对中国大陆用户网络友好。
为什么选择 OpenCode? —— 原生多 Agent 支持、纯文本配置体系、技能按需加载和 Provider 模型解耦,这四个特性让 OpenCode 成为实现”纯配置驱动的多 Agent 协作方案”的最佳基础。
为什么借鉴这些项目却又不照搬? —— 每个被借鉴的项目都有自己独特的上下文和约束。本方案从它们汲取核心理念(意图门控、只读隔离、delta specs、熵扫描等),但通过轻量化吸收,将重功能转化为适配本方案 Token 效率原则的轻量机制。
20 个版本、83+ 次提交,每一次迭代都不是”为了迭代而迭代”,而是”遇到了问题 → 分析根因 → 最小化修复 → 验证效果 → 沉淀为配置”。这套配置仍在演进——它不是一个完成品,而是一个”有生命力的工程实践”。
| ← 上一章:典型工作流实战 | 返回目录 | 下一章:最佳实践与定制指南 → |