第一章：my-opencode-deepseek-config 项目概览与核心定位
阅读目标：用一章篇幅建立对
my-opencode-deepseek-config的整体认知——它是什么、解决什么问题、怎么做到的、和别的方案有什么不同、适合谁用。读完本章，你将理解这套配置的设计哲学，并能判断它是否适合你的开发场景。
1.1 一句话理解
my-opencode-deepseek-config = OpenCode × DeepSeek 的最优配置方案。
展开来说：这是一个纯配置驱动、零额外依赖的 OpenCode 多 Agent 配置仓库。它把 opencode.jsonc、agents/*.md、skills/*/SKILL.md、AGENTS.md 这四类纯文本文件组织成一个有机整体，将 DeepSeek V4 三模型（Pro + Flash + Flash-Vision-Exp）在 OpenCode 多 Agent 框架下的能力发挥到极致。
核心理念只有四个字：Token 效率优先——用最小的上下文成本达到最好的开发效果。这不是一个花哨的”AI 生产力工具”，而是一套经过 38+ 个迭代阶段（v1–v38+）打磨出来的务实方案：路径引用替代文件粘贴、技能按需加载而非全量注入、DCP 智能压缩替代简单截断、AGENTS.md 全局规则精简到 218 行——每一步都在追问”能不能少花一点 token”。
如果你用一个比喻来记住它：它是 OpenCode 生态里专门为 DeepSeek 用户打造的”操作系统”——帮你分配算力（Pro vs Flash）、调度进程（Agent 路由）、装载驱动（Skills）、定义权限和契约（AGENTS.md），而你只需要用自然语言下达指令。
1.2 项目解决什么问题
传统 AI 编码工具和配置方案存在五个系统性问题，my-opencode-deepseek-config 针对每一个都给出了回答。
问题一：厂商/模型锁定
大多数 AI 编码工具将用户绑定到特定模型（GPT-4、Claude、Gemini），切换成本极高。即使工具本身支持多 Provider，默认配置也往往偏向某一个生态。这导致：
- 无法利用不同模型的差异化优势（DeepSeek 的成本优势、推理能力）
- 定价策略变化时没有议价能力
- 想尝试新模型时需要大量手动配置
本方案的答案：通过 provider.deepseek 配置将模型矩阵锁定在 DeepSeek V4 家族（pro / flash / flash-vision-exp），并在 AGENTS.md 中明确”不引入新模型”的约束。同时保留扩展性——换模型只需修改 provider 配置，Agent 和 Skills 体系零耦合。
问题二：上下文成本不可控
大语言模型的 API 调用按 Token 计费，上下文越长成本越高。很多配置方案缺乏系统的 Token 管理策略，导致：
- 每次对话无差别地注入全部 Skill 和规则，80% 的 Token 花在”可能用得上”的内容上
- 代码审查报告把整个文件贴进提示词，而不是用路径引用
- 会话历史无限增长，没有压缩机制
本方案的答案：贯彻 Token 效率优先——Skill 通过原生 skill 工具按需加载（只在触发时才注入上下文）；DCP 插件按模型成本分层在 38K/77K Token 阈值主动压缩；AGENTS.md 明确要求”引用路径，不粘贴文件”；甚至在 Agent 系统提示的设计上也做了去重（v20 版本将 AGENTS.md 精简 22%）。
问题三：缺乏结构化的多 Agent 协作机制
单模型对话的局限性已经很明显：一个模型既要理解意图、又要探索代码、还要执行修改、还要自我审查——角色冲突导致每个环节都做不深。但多 Agent 方案如果缺少清晰的职责边界和路由规则，反而会造成上下文浪费和决策混乱。
本方案的答案：12 个 Agent 各司其职，通过 Orchestrator 的意图门控 + 任务分类 + 模型感知路由实现精准调度。关键设计包括：
- 执行与探索分离：deep-worker 和 light-orchestrator 禁止研究/委托，explore 和 librarian 禁止修改
- Pro vs Flash 模型分工：Pro 做推理和决策，Flash 做查询和轻量执行
- Task Rejection Contract：Agent 遇到越权任务必须拒绝，不能”勉强做”
问题四：配置无法沉淀、无法团队共享
很多开发者的 AI 编码配置是散落在环境变量、GUI 设置、记忆中的”隐性知识”。换台机器要重新搭一遍，团队成员之间无法复用。
本方案的答案：所有配置都是纯文本文件，存放在标准目录结构下，通过 Git 版本管理：
- 个人使用：
git clone到~/.config/opencode，即刻就绪 - 团队共享：Fork 仓库，按需调整 Agent 提示词和 Skill，PR 合并
- 持续改进：
/reflect命令机制化地发现摩擦并沉淀为配置优化
问题五：没有系统化的编码规范和反模式约束
AI 生成的代码质量参差不齐——空 catch 块、多余的 try/catch、死代码、冗余注释、utils.ts 等”万金油”文件。大多数配置方案只管”能不能生成代码”，不管”生成的代码好不好”。
本方案的答案：AGENTS.md 定义了一套完整的反模式清单（禁止创建 utils.ts、禁止空 catch 块、禁止 @ts-ignore 不加说明、禁止注释掉的代码等）和质量基准（尽早 return、用 const 而非 let、函数式数组方法优于 for 循环等）。这些规则不是建议，而是 Agent 在执行时必须遵守的契约。
1.3 核心特性
特性一：纯配置驱动，零额外依赖
整个项目的全部能力来自四类纯文本文件：
| 文件类型 | 作用 | 示例 |
|---|---|---|
opencode.jsonc |
核心配置：模型绑定、Agent 定义、权限基线、实验功能开关 | DeepSeek 三模型绑定、subagent_depth: 3、权限 deny/ask 策略 |
agents/*.md |
12 个 Agent 的系统提示词，定义角色、能力、约束 | orchestrator.md 包含意图门控逻辑和完整路由表 |
skills/*/SKILL.md |
25 个可复用技能的详细指令，按需加载 | code-review/SKILL.md 包含双轴并行审查维度、严重度分级、熵扫描和收敛检查 |
AGENTS.md |
全局规则，所有 Agent 共享 | 语言检测、反模式列表、证据纪律、Task Rejection Contract |
不需要安装任何额外的 npm 包、Python 库、或外部服务。OpenCode 自身作为运行时，配置文件就是”程序”。
特性二：DeepSeek V4 三模型极致利用
这是本方案最核心的优化策略——用最小的模型开销完成任务：
| 模型 | 角色 | 典型用途 |
|---|---|---|
deepseek/deepseek-v4-pro |
推理与决策引擎 | 架构规划、根因分析、代码审查、重型多文件实现 |
deepseek/deepseek-v4-flash |
查询与执行引擎 | 代码库搜索、文档检索、轻量单文件编辑、简单任务、交接文档生成 |
deepseek/deepseek-v4-flash-vision-exp |
多模态引擎 | 读取图片、截图、图表、PDF 页面（flash 成本档） |
路由策略确保”杀鸡不用牛刀”：
- Flash 优先：搜索、查找、简单编辑等明确定义的任务优先走 Flash Agent
- Pro 专注推理：规划、分析、审查、复杂实现只用 Pro
- Vision 专项：涉及图像/截图/多模态输入的任务路由到 vision Agent（flash-vision-exp）
- 自动升级：Flash Agent 无法胜任时自动升级到 Pro，带完整上下文
这套分工的深层逻辑是：Pro 模型的推理能力更强但成本更高，Flash 模型速度快、成本低但推理深度有限。一个典型的开发任务中，80% 的步骤（搜索文件、查阅文档、生成提交信息、简单语法修复）不需要强推理模型，交给 Flash 即可。剩下 20% 的核心难度步骤（理解复杂逻辑、设计架构、多文件重构）才需要 Pro 出马。而涉及图像理解的任务（读截图、看图表）则交给专门的 vision Agent。
特性三：12 个专业化 Agent，职责清晰
每个 Agent 有严格定义的职责边界和模型绑定。12 个 Agent 分为 2 个主 Agent（primary，直接面向用户）和 10 个子 Agent（subagent，由主 Agent 调度）：
主 Agent（2 个）——用户入口：
| Agent | 模型 | 权限 | 核心职责 |
|---|---|---|---|
orchestrator |
flash | 读写 | 默认入口，意图门控、任务分类、模型感知路由、后备链 |
solo |
pro | 读写 | 单模型内联执行器：不委派子 Agent，直接完成分析/实现/验证 |
Pro 模型子 Agent（3 个）——推理与决策层：
| Agent | 权限 | 核心职责 |
|---|---|---|
deep-worker |
读写 | 重型实现、多文件改动、复杂调试（禁止研究/委托） |
oracle |
只读 | 根因分析、深度理解代码、问题溯源 |
reviewer |
只读 | 多维度代码审查、质量检查、对抗性自检、上下文校准 |
Flash 模型子 Agent（7 个）——查询与执行层：
| Agent | 权限 | 核心职责 |
|---|---|---|
planner |
读写 | 规划与架构设计、拆解复杂任务、制定技术方案 |
light-orchestrator |
读写 | 轻量任务、单文件编辑（禁止研究/委托） |
consultant |
读写 | 方案讨论、技术对比、最佳实践建议 |
ui-builder |
读写 | 前端与 UI 相关任务 |
explore |
只读 | 代码库搜索、并行探索、文件模式匹配 |
librarian |
只读 | 文档检索、Web 搜索、API 文档核对 |
vision |
flash-vision | 多模态：读取图片、截图、图表（只读） |
“禁止研究/委托”原则：deep-worker 和 light-orchestrator 是用来执行的，不是用来探索的。它们的上下文由 Orchestrator 在调度时提供完整，执行过程中不得自行发起研究或委托给其他 Agent。这避免了”Agent A 委托给 Agent B，Agent B 又委托给 Agent C”的上下文膨胀链。
模型分配逻辑：模型选择不只看”权限”（读写 vs 只读），更看”认知深度”。oracle/reviewer 虽只读但需要深度推理，故用 Pro；planner/consultant/ui-builder 虽涉及规划/建议/构建，但多为常规任务，用 Flash 即可，必要时自动升级。
特性四：25 个可复用技能，按需加载
技能（Skill）是本方案的能力模块。OpenCode 通过原生 skill 工具按需暴露——Agent 只在需要时才加载，不会常驻上下文。25 个 Skill 覆盖了从代码审查到版本发布的全流程：
过程与纪律类：
code-review— Token 高效双轴并行审查（含熵扫描+收敛检查+严重度校准）security-review— 合并前安全审查清单spec-workflow— 规约驱动变更工作流（propose→apply→update→archive）diagnosing-bugs— 系统化调试（先建可复现反馈环）simplify— 行为保持的代码简化remove-deadcode— 安全查找并删除死代码（LSP 验证后删除）
Git 与发布类：
gh-cli— GitHub CLI 全面操作（v2.100+，含 Agent Skills）git-master— 高级 Git：rebase、squash、bisect、reflog、worktreegit-release— 准备 Tag 发布（SemVer 推断+发布说明）resolving-merge-conflicts— 解决合并/变基冲突
探索与知识类：
codemap— 生成带标注的仓库结构图verify-with-docs— 编码前检索核对 API 文档librarian相关检索技能
配置与维护类：
opencode-config— 编写和维护 OpenCode 配置handoff— 会话压缩为交接文档（路径引用，不复制内容）reflect— 持续改进：发现摩擦→配置优化writing-for-agents— 编写 Agent 消费的文档（skill/AGENTS.md）
分析与领域类：
codebase-design— 模块边界与架构设计词汇表domain-modeling— 领域术语表（节省 Token）grilling/grill-with-docs— 需求澄清（一次一问，多选优先）wait-what— 复述确认模糊指令
办公与多模态类：
office-docs— 读写 Word/Excel（.docx/.xlsx）vision-prep— 预处理大图/PDF 供视觉模型读取
协作与流程类：
to-tickets— 将计划拆分为可追踪的 GitHub issuetriage— 基于标签的 issue 分流
注：技能清单随仓库持续演进，完整且最新的 25 个技能列表请以仓库
skills/目录与 README 为准。
特性五：18 条快捷命令别名
每个命令精准触发特定 Agent + Skill 组合，从 /deep（重型实现）到 /rmslop（清理死代码），覆盖日常开发的高频场景。详见第七章。
特性六：Token 效率优先的设计哲学
前面提到 Token 效率是核心理念，这里展开讲它的具体实现手段：
-
路径引用替代粘贴：AGENTS.md 明确规定”引用路径，不粘贴文件”。报告代码问题时写
src/app.ts:42，而不是把整个文件复制进提示词。 -
技能按需加载：25 个 Skill 通过
skill工具按需加载，不会在每次对话时全部注入上下文。一个代码审查任务不会拖着一整套 Git Release 流程的指令。 -
DCP 智能压缩：
dcp.jsonc按模型成本分层配置了 38K/77K Token 的主动压缩阈值——当会话上下文超过阈值时触发压缩，避免上下文无限膨胀。OpenCode 原生的 compaction 作为兜底。 -
去重与精简：v20 版本中，AGENTS.md 从 292 行精简到 229 行（22% 的减幅），Agent 提示词去重 20%。因为多个 Agent 的提示词共享同一套 AGENTS.md 全局规则，在各自提示词中重复声明只会浪费 Token。后续迭代进一步精简至当前的 218 行。
-
上下文管理策略：Orchestrator 明确要求”委托不积累”——大型文件由子 Agent 读取，不在 Orchestrator 上下文中加载；”压缩而非累积”——一个调查方向结束后立即压缩，只保留计划和发现，不保留原始探索记录。
特性七：执行与探索分离
这是本方案最独特的设计决策之一，用一个硬约束避免 Agent 的角色越界：
- 执行型 Agent（deep-worker、light-orchestrator）：收到任务→执行→返回结果。不自行探索代码库，所需上下文由调度方提供。如果发现信息不足，返回”需要更多上下文”而非自己搜索。
- 探索型 Agent（explore、librarian、oracle）：搜索、分析、返回发现。不修改文件。
这种分离避免了”执行 Agent 自己探索，探索结果又触发新的探索”导致的上下文雪崩。也是一种工程纪律——就好像你不能让一个负责砌墙的工人同时负责勘查地基。
1.4 与其他方案的对比
vs 原生 OpenCode
原生 OpenCode 安装后就有一个默认的 Agent 和基本配置，可以立刻用 DeepSeek 模型对话。但：
| 维度 | 原生 OpenCode | my-opencode-deepseek-config |
|---|---|---|
| Agent 体系 | 1 个默认 Agent | 12 个专业化 Agent，职责清晰 |
| 技能 | 无预置技能 | 25 个可复用技能，按需加载 |
| 全局规则 | 无 | 218 行 AGENTS.md，包含反模式、证据纪律、拒绝契约 |
| 命令别名 | 无 | 18 条快捷命令 |
| 上下文管理 | 原生 compaction | DCP 智能压缩 + 路径引用策略 |
| 模型分工 | 无策略 | Pro/Flash/Vision 严格分工，Flash 优先 |
| 配置沉淀 | 无模板 | 完整 Git 仓库，团队可直接 Fork |
总结：原生 OpenCode 像一台裸机，my-opencode-deepseek-config 像是装好了操作系统、驱动和常用软件的环境。
vs oh-my-openagent
oh-my-openagent 是 OpenCode 生态中另一个有影响力的配置仓库。本方案借鉴了它的意图门控、只读隔离和反模式约束理念。区别在于：
| 维度 | oh-my-openagent | my-opencode-deepseek-config |
|---|---|---|
| 模型绑定 | 多 Provider 支持 | 专注 DeepSeek V4 三模型 |
| Skill 数量 | 较少 | 25 个，覆盖更全面 |
| Agent 数量 | 相近 | 12 个，增加 solo、vision、ui-builder、consultant 等 |
| 上下文管理 | 基础 | DCP 智能压缩 + 路径引用 + 去重 |
| 迭代设计 | — | 38+ 个阶段，有完整设计决策记录 |
总结：oh-my-openagent 在通用性上更胜一筹，my-opencode-deepseek-config 在 DeepSeek 生态的深耕和 Token 效率优化上更极致。
vs Cursor / Copilot 等 IDE 插件
| 维度 | Cursor / Copilot | my-opencode-deepseek-config |
|---|---|---|
| 运行方式 | IDE 插件，图形界面 | 终端 CLI，纯文本配置 |
| 多 Agent | 有限或隐式 | 显式 12 Agent 体系，路由可审计 |
| 模型自由 | 通常绑定特定模型 | 可自由切换 Provider（当前锁定 DeepSeek） |
| 配置可审计 | GUI 配置，黑盒 | 纯文本 Git 仓库，完全可审计 |
| 离线/本地 | 部分支持 | 取决于 OpenCode 运行时 |
| 团队共享 | 部分可通过账号同步 | Fork + Git，完全自主 |
| 学习曲线 | 低（开箱即用） | 中（需要理解 Agent 和 Skill 概念） |
总结：IDE 插件追求”开箱即用的便利”，本方案追求”完全可控的透明”。选择取决于你是想”傻瓜式使用”还是”深度定制”。
vs oh-my-opencode-slim
oh-my-opencode-slim 是本方案借鉴的另一配置仓库，学到了调度器优先、后备链和拒绝契约的设计思路。区别在于：
| 维度 | oh-my-opencode-slim | my-opencode-deepseek-config |
|---|---|---|
| 定位 | 轻量化配置方案 | 功能完备的生产级方案 |
| Skill 数量 | 较少 | 25 个 |
| Agent 数量 | 较少 | 12 个 |
| 上下文管理 | 基础 | DCP + 路径引用 + 去重 |
| 迭代深度 | — | 38+ 个迭代阶段（v1–v38+） |
总结：oh-my-opencode-slim 是一个极简起点，本方案是在其理念上的全面深化。如果你的需求简单，用 slim 就够了；如果追求生产级的完整性，本方案更合适。
1.5 适用场景
最适配的场景
场景一：个人开发者追求 Token 效率最大化
你使用 DeepSeek API 按量付费，希望每一分钱都花在刀刃上。本方案的 Token 效率策略（Flash 优先路由、技能按需加载、DCP 智能压缩、路径引用）能让本来 50K Token 的一次对话控制在 20K 以内——不是夸张，是一系列设计决策的叠加效果。
场景二：团队希望标准化 AI 编码工作流
你的团队有 5-10 个开发者在用 AI 辅助编码，但大家的用法各不相同——有人直接用 ChatGPT 网页版、有人装 Cursor、有人用 OpenCode 的默认配置。代码质量和风格不统一。通过 Fork 本仓库并定制团队版的 AGENTS.md（添加团队特有的编码规范、命名约定、反模式），你可以让所有开发者在同一个”AI 编码操作系统”上工作。
场景三：DeepSeek API 用户
你选择了 DeepSeek 作为主力模型（可能是成本考量、可能是数据安全考量、可能是推理能力偏好），但发现大多数 AI 工具对 DeepSeek 的支持是”能用”而非”好用”。本方案是专门为 DeepSeek V4 三模型调优的，从 Agent 提示词到模型路由策略都针对 DeepSeek 的特点做了适配。
场景四：需要复杂多步骤开发任务自动化
你的日常开发中经常有这样的场景：新功能需要先探索代码结构→制定方案→多文件实现→代码审查→清理死代码→规范化提交。本方案的 /spec-propose → /spec-apply → /review → /rmslop → /commit 命令链和 spec-workflow 技能正是为这种多步骤流程设计的。
场景五：希望学习 OpenCode 多 Agent 配置最佳实践
你对 OpenCode 的多 Agent 能力感兴趣，但不清楚怎么设计 Agent 职责、怎么写 Skill、怎么管理上下文。本仓库是一份完整的学习材料——从 Agent 系统提示词到 Skill 结构到全局规则，每部分都有明确的注释和设计意图（详见 README 的”设计决策与迭代记录”部分）。读一遍代码，你就能理解 OpenCode 配置的核心模式。
不太适合的场景
场景一：你只用 Cursor/Copilot 的 Tab 补全
如果你对 AI 编码的需求仅仅是”写代码时自动补全下一行”，那么本方案的复杂度远超你的需求。IDE 内置的 Tab 补全足够。
场景二：你不需要多 Agent 协作
如果你的 AI 使用模式是”单轮问答”——问一个问题，得到一个答案，就结束了——那么单个默认 Agent 就够了，不需要 Orchestrator 的意图门控和路由。
场景三：你用的是 Anthropic 或 OpenAI 的模型且不想换
本方案目前锁定 DeepSeek Provider（provider.deepseek 三模型矩阵）。虽然改 Provider 配置不复杂，但 Agent 提示词中对模型行为的一些假设（如对 Token 效率的强调程度）是在 DeepSeek 上验证过的。换模型不是不行，但效果需要重新调优。
场景四：你不愿意花时间学习配置体系
纯配置驱动的代价是需要理解配置。如果”开箱即用”是你的首要诉求，IDE 插件类的方案（Cursor、Copilot）可能更适合。
1.6 技术架构全景图
用文字描述本方案的整体架构分层。可以把它想象成一个五层栈，层与层之间通过清晰的接口连接。
第一层：用户入口层
开发者与系统的交互界面。有两个入口通道：
- 自然语言入口：直接在 OpenCode 对话中输入需求描述——”帮我排查这个登录接口的报错”——Orchestrator 自动分析意图并路由到合适的 Agent。
- 命令别名入口：输入
/deep、/review、/plan等 18 条快捷命令，精确触发特定 Agent + Skill 组合。适合对系统熟悉后追求效率的场景。
两个入口共享同一套后端，只是调度方式不同——自然语言走意图推断，命令别名走预定义映射。
第二层：编排层
Orchestrator 是整个系统的中枢神经。它做的事情依次是：
- 意图门控（Intent Gating）：分析用户输入，判断任务类型——是”问个问题”还是”改段代码”还是”设计架构”？这一步决定后续的所有路由。
- 6 类任务分类：将意图归类为六种任务类型之一（探索/规划/实现/审查/咨询/维护），每种类型有预设的 Agent → Skill → 模型映射。
- 模型感知路由：根据任务类型决定用 Pro 还是 Flash——探索类走 Flash（explore/librarian），推理类走 Pro（planner/oracle/reviewer），重型实现走 Pro（deep-worker），轻量编辑走 Flash（light-orchestrator）。
- 后备链（Fallback Chain）：如果首选 Agent 无法完成任务（如 Flash Agent 遇到超出能力的复杂逻辑），自动升级到更强的 Agent（如 light-orchestrator → deep-worker），带完整上下文传递。
Orchestrator 自身运行在 deepseek/deepseek-v4-flash 上——因为路由决策虽需要一定推理，但绝大多数是模式匹配与分类，Flash 足够胜任且成本更低；遇到复杂任务时通过后备链升级到 Pro 子 Agent。
第三层：执行层
执行层分为两个子层，按模型能力划分：
Pro Agent 群（推理与决策）——运行在 deepseek/deepseek-v4-pro：
solo：主 Agent，单模型内联执行（不委派）deep-worker：多文件重型实现，复杂调试oracle：只读，深度分析代码逻辑、追溯问题根因reviewer：只读，多维度代码审查
Flash Agent 群（查询与轻量执行）——运行在 deepseek/deepseek-v4-flash：
orchestrator：主 Agent，意图门控与路由planner：将模糊需求转化为可执行的计划light-orchestrator：读写，单文件轻量编辑consultant：方案讨论和技术对比ui-builder：前端和 UI 专项explore：只读，代码库并行搜索librarian：只读，外部文档检索
Vision Agent——运行在 deepseek/deepseek-v4-flash-vision-exp：
vision：只读，读取图片、截图、图表等多模态输入
关键约束：
- 只读 Agent（oracle、reviewer、explore、librarian、vision）绝不修改文件
- 执行 Agent（deep-worker、light-orchestrator）禁止自行研究和委托
- Agent 嵌套深度限制为 3 层（
subagent_depth: 3），防止无限递归
第四层：能力层
执行层的 Agent 通过加载 Skill 获取专业能力。25 个 Skill 按功能域组织在 skills/ 目录下，通过 OpenCode 原生的 skill 工具按需加载。
此外还有两个插件增强系统能力：
- superpowers（obra/superpowers，固定 #v6.3.0）：提供过程型技能（brainstorming、systematic-debugging、TDD、writing-plans 等），在 Agent 启动时自动注入引导，确保 Agent 在面临特定类型任务时”先想清楚再动手”。
- DCP（@tarquinen/opencode-dcp@3.1.15）：智能上下文裁剪插件。按模型成本分层在 38K/77K Token 阈值区间内主动压缩会话上下文，裁剪冗余但保留关键信息。与 OpenCode 原生的 compaction 形成双保险。
插件遵循”增效但不喧宾夺主”的原则——它们增强系统的过程纪律和能力，但不会引入额外的模型或打破纯配置驱动的设计。
第五层：配置层
整个系统的”宪法”由三个文件组成：
| 文件 | 作用 | 关键内容 |
|---|---|---|
opencode.jsonc |
核心配置 | 模型绑定、Agent 定义与权限、subagent_depth: 3、权限基线 |
dcp.jsonc |
压缩配置 | DCP 插件的按模型分层阈值设定（38K/77K）、压缩策略 |
AGENTS.md |
全局规则 | 核心原则、语言策略、反模式清单、质量基准、证据纪律、Task Rejection Contract、Self-Verification 流程、Stop Condition |
AGENTS.md 是第五层中最重要的文件——它不属于任何一个 Agent，但被所有 Agent 共享。它定义的不是”某个 Agent 该怎么做”，而是”所有 Agent 都必须遵守“的契约。从”禁止创建 utils.ts“到”没有证据不能声称完成”，这些规则构成了系统的质量底线。
架构全景图（文字版）
┌─────────────────────────────────────────────────────────────┐
│ 用户入口层 │
│ ┌──────────────────────┐ ┌────────────────────────────┐ │
│ │ 自然语言输入 │ │ 17 条命令别名 │ │
│ │ "帮我排查这个bug..." │ │ /deep /review /plan ... │ │
│ └─────────┬────────────┘ └─────────────┬──────────────┘ │
│ └──────────────┬──────────────┘ │
├───────────────────────────┼─────────────────────────────────┤
│ 编排层 ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Orchestrator (deepseek-v4-flash) │ │
│ │ 意图门控 → 任务分类 → 模型感知路由 → 后备链 │ │
│ └──────────────────────┬─────────────────────────────────┘ │
├─────────────────────────┼───────────────────────────────────┤
│ 执行层 ▼ │
│ ┌──────────────────────┴──────────────────────────────┐ │
│ │ Pro Agent 群 (deepseek-v4-pro) │ │
│ │ solo(主) · deep-worker · oracle · reviewer │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ Flash Agent 群 (deepseek-v4-flash) │ │
│ │ planner · light-orchestrator · consultant │ │
│ │ ui-builder · explore · librarian │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ Vision Agent (deepseek-v4-flash-vision-exp) │ │
│ │ vision (只读多模态) │ │
│ └──────────────────────┬──────────────────────────────┘ │
├─────────────────────────┼───────────────────────────────────┤
│ 能力层 ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 25 Skills (按需加载) │ │
│ │ code-review · security-review · spec-workflow · ... │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ 2 Plugins (增效但不喧宾夺主) │ │
│ │ superpowers#v6.3.0 · DCP@3.1.15 │ │
│ └──────────────────────┬───────────────────────────────┘ │
├─────────────────────────┼───────────────────────────────────┤
│ 配置层 ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ opencode.jsonc (核心配置 · 模型 · Agent · 权限) │ │
│ │ dcp.jsonc (压缩阈值 · 策略) │ │
│ │ AGENTS.md (全局规则 · 218行 · 所有Agent共享) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
1.7 设计哲学
本方案不是东拼西凑的配置集合，每一行配置背后都有一个明确的意图。以下六条设计原则是理解整个系统的钥匙。
原则一：纯配置驱动，零额外依赖
“Configuration is code.”
项目的能力增长不靠引入新的工具或库，而是靠更精细、更智能的配置。原因有三：
- 可审计：纯文本配置的每一次变更都可以通过
git diff审查，没有任何”黑盒”行为。 - 可复现：在任何机器上
git clone就能得到完全相同的行为，不需要安装依赖、配置环境。 - 低维护成本：配置文件的复杂度远低于代码项目，不会出现依赖冲突、版本不兼容的问题。
这也意味着本方案的能力上界是 OpenCode 框架本身的能力上界。我们不能在配置里”创造” OpenCode 不支持的机制，只能”用好”已有的机制。这不是限制，而是策略——与其在框架外造轮子，不如把框架内的能力组合到极致。
原则二：DeepSeek V4 三模型极致利用
“Right model for the right job.”
这个原则有两个维度：
纵向维度：按任务难度分配模型。简单的搜索和查询用 Flash，复杂的推理和决策用 Pro，图像理解用 vision-exp。这不是粗暴的二分法，而是通过 Orchestrator 的意图门控 + 后备链实现的动态路由——如果一个任务在路由时被判断为”简单”但执行中发现需要更深的推理，后备链会将它自动升级到 Pro。
横向维度：在 Agent 层面做模型隔离。只读的探索 Agent 用 Flash（只需找到信息，不需深度理解），但只读的分析 Agent（oracle、reviewer）用 Pro（需要深度推理）。这说明模型的选择不只看”权限”（读写 vs 只读），更看”认知深度”（查找 vs 理解 vs 创造）。
原则三：Token 效率优先
“Every token spent is a cost.”
Token 效率不是一个口号，而是一套可量化的工程实践：
- 路径引用：
src/app.ts:42替代粘贴整个文件——节省 95% 以上的 Token。 - 按需加载：Skill 在触发时才注入，不在每次对话中都携带 25 个 Skill 的全部内容——节省 80% 的 Skill Token。
- 智能压缩：DCP 按模型成本分层在 38K/77K Token 阈值触发压缩，避免上下文无限膨胀——将长会话的 Token 成本控制在可预测范围内。
- 去重：AGENTS.md 的全局规则不与 Agent 提示词重复声明——节省 20% 的 Agent 提示词 Token。
- 委托而非累积：子 Agent 执行任务时，Orchestrator 不把子 Agent 的全部探索过程加载到自己上下文中——压缩而非累积。
这些实践单独看每一项节省的 Token 都不算多，但叠加在一起，一次典型的多步骤开发任务能从 50K–80K Token 降到 20K–30K Token——这在 API 按量付费模式下是实实在在的成本差异。
原则四：插件增效但不喧宾夺主
“Plugins are enhancers, not replacements.”
两个插件各有明确的边界：
- superpowers：不引入新的 Agent，而是在 Agent 启动时注入过程引导——”遇到 Bug→先系统诊断→再修复”。它增强的是 Agent 的过程纪律，而不是替代 Agent 的能力。
- DCP：不做模型的输入输出，只在上下文管理层面做智能压缩。它替换的是”简单截断”这种粗暴策略，而不是 Agent 的决策能力。
两者共同的约束：不使用额外的模型、不修改 OpenCode 的核心行为、不引入新的依赖。它们是”增效器”而非”替代品”。
原则五：执行与探索分离
“Builders don’t explore. Explorers don’t build.”
这是本方案最反直觉但最重要的设计决策。很多 AI 编码系统的一个通病是”角色模糊”——一个 Agent 既探索代码又修改代码，探索的结果未经审查就变成修改的依据，修改后又触发新的探索。这种循环导致：
- 上下文爆炸：每次探索都在累积上下文，最终超出模型窗口
- 决策混乱：Agent 在不同角色间切换，失去对当前任务的专注
- 质量漂移：Agent 既是”问题的发现者”又是”问题的修复者”，缺乏对抗性审查
解决方案是硬性分离：
- deep-worker 和 light-orchestrator 的系统提示中明确规定”禁止研究、禁止委托”——它们只能基于给定的上下文执行，不能自行探索。
- explore、librarian、oracle 虽然可以研究，但前两者运行在 Flash 上且只读，oracle 运行在 Pro 上但只读——它们”理解”但不”修改”。
这种分离像是一个”工厂流水线”：explore/librarian 是勘探队，只负责定位矿藏；oracle/reviewer 是质检员，只负责评估；planner 是设计师，只负责出图纸；deep-worker/light-orchestrator 是施工队，只负责按图施工。每个人只管自己的环节，信息通过 Orchestrator 有控制地流转。
原则六：持续改进
“Reflect, don’t regret.”
系统不会”做完就完了”。两个机制确保持续进化：
-
/reflect命令：在任何开发任务完成后，可以触发 reflect 技能，让 oracle Agent 回顾刚才的工作——有没有反复出现的问题？有没有可以优化的配置？——然后提出一个最小的配置改动建议。 -
迭代记录：README 中的”迭代里程碑”表格记录了从 v1 到 v38+ 的每一次关键变更，形成了可追溯的演进历史。这不是文档的装饰，而是后续决策的依据——”上次我们为什么把 AGENTS.md 精简到 218 行？因为分析发现大量内容在 Agent 系统提示中已经重复声明了。”
1.8 仓库结构概览
下面是克隆本仓库后看到的完整目录结构。配置统一放在 opencode/ 子目录下，通过环境变量 OPENCODE_CONFIG_DIR 或符号链接指向后即可被 OpenCode 识别。
my-opencode-deepseek-config/
│
├── opencode/ ← OpenCode 配置目录（可独立部署）
│ ├── agents/ ← 12 个 Agent 系统提示词 (.md)
│ │ ├── orchestrator.md ← flash 主入口：意图门控 + 模型感知路由
│ │ ├── solo.md ← pro 主入口：单模型内联执行（不委派）
│ │ ├── planner.md ← flash：架构与规划
│ │ ├── deep-worker.md ← pro：重型实现【禁止研究/委托】
│ │ ├── oracle.md ← pro：深度代码分析【只读】
│ │ ├── reviewer.md ← pro：双轴代码审查【只读】
│ │ ├── consultant.md ← flash：方案讨论与建议
│ │ ├── ui-builder.md ← flash：前端与 UI
│ │ ├── explore.md ← flash：代码库搜索【只读】
│ │ ├── librarian.md ← flash：外部检索【只读】
│ │ ├── light-orchestrator.md ← flash：简单编辑【禁止研究/委托】
│ │ └── vision.md ← flash-vision：多模态读取【只读】
│ │
│ ├── skills/ ← 25 个可复用技能 (SKILL.md)
│ │ ├── code-review/ ← 双轴并行审查 + 严重度校准
│ │ ├── codemap/ ← 生成仓库结构图
│ │ ├── gh-cli/ ← GitHub CLI v2.100+ 参考（含 Agent Skills）
│ │ ├── git-master/ ← 高级 Git 操作
│ │ ├── git-release/ ← Tag 发布（SemVer 推断 + 发布说明）
│ │ ├── handoff/ ← 会话压缩为交接文档
│ │ ├── opencode-config/ ← 元技能：本仓库配置编写
│ │ ├── reflect/ ← 持续改进
│ │ ├── remove-deadcode/ ← 死代码检测与删除
│ │ ├── security-review/ ← 安全审查清单
│ │ ├── simplify/ ← 行为保持的代码简化
│ │ ├── spec-workflow/ ← 规约驱动开发
│ │ ├── verify-with-docs/ ← 检索优先 API 验证
│ │ ├── office-docs/ ← 读写 Word/Excel
│ │ ├── vision-prep/ ← 预处理大图/PDF 供视觉模型
│ │ ├── ... ← 其余技能见 README 技能表
│ │
│ ├── opencode.jsonc ← 核心配置（17 条命令别名）
│ │ 模型绑定（Pro + Flash + Vision）、
│ │ Agent 定义与权限（subagent_depth: 3）、
│ │ Provider 模型矩阵、权限基线
│ │
│ ├── AGENTS.md ← 全局规则（218 行），所有 Agent 共享
│ │ 核心原则、语言策略、反模式、质量基准、
│ │ 证据纪律、Task Rejection Contract、
│ │ Self-Verification、Comment Discipline
│ │
│ └── dcp.jsonc ← DCP 智能压缩配置
│ 按模型分层压缩阈值（38K/77K Token）、
│ 压缩策略、保护规则
│
├── scripts/ ← 辅助脚本
│ ├── estimate-cost.js ← 成本估算脚本
│ ├── sync-config.ps1 ← 同步配置到 ~/.config/opencode
│ └── validate-jsonc.js ← JSONC 校验脚本
│
├── README.md ← 项目文档与使用指南（中文）
├── README.en-US.md ← 英文版 README
└── LICENSE ← MIT 开源许可证
文件统计
| 类别 | 数量 | 说明 |
|---|---|---|
| Agent 系统提示 | 12 个 | agents/ 目录下每个 .md 文件定义一个 Agent |
| Skill 技能 | 25 个 | skills/ 目录下每个子目录包含一个 SKILL.md |
| 核心配置 | 3 个 | opencode.jsonc + dcp.jsonc + AGENTS.md |
| 辅助脚本 | 3 个 | scripts/ 下的成本估算、同步、校验脚本 |
| 文档与许可 | 3+ 个 | README.md + README.en-US.md + LICENSE |
目录结构的设计逻辑
这个目录结构不是随意摆放的，它直接映射 OpenCode 框架的配置约定：
opencode/是整个配置的根——通过环境变量OPENCODE_CONFIG_DIR或符号链接指向后，OpenCode 自动识别其下所有文件。agents/目录被 OpenCode 自动识别——放在这里的.md文件会成为可用的 Agent。skills/目录通过skill工具按需加载——Agent 在运行时通过skill工具传入 Skill 名称，OpenCode 自动查找对应目录下的SKILL.md。AGENTS.md是 OpenCode 约定的全局规则文件——如果存在，所有 Agent 的上下文会自动包含这个文件的内容。opencode.jsonc是 OpenCode 的主配置文件——控制模型、权限、实验功能等。scripts/存放辅助脚本：sync-config.ps1将opencode/同步到~/.config/opencode，estimate-cost.js估算不同模型的调用成本。
与早期版本不同，当前配置统一放在 opencode/ 子目录下，而非仓库根目录。这样做的好处是：仓库根目录可以存放 README、LICENSE 等项目管理文件，配置目录保持纯净，可直接通过环境变量或符号链接独立部署。
本章小结
回到开头的问题：my-opencode-deepseek-config 是什么？
它是一个为 DeepSeek V4 三模型精心调优的 OpenCode 配置仓库。它有 12 个各司其职的 Agent、25 个按需加载的 Skill、18 条快捷命令、218 行全局规则，以及贯穿始终的 Token 效率优先哲学。
但它不只是”功能列表的堆砌”。它背后的设计理念——纯配置驱动、执行与探索分离、Token 效率优先——才是它区别于其他方案的本质。这些理念不是拍脑袋想出来的，而是在 38+ 个迭代阶段（v1–v38+）中，通过与实际开发任务的反复磨合形成的。
如果你读完本章后决定继续深入，下一章会带你完成安装部署——把这个配置仓库变成你日常开发的”AI 编码操作系统”。
| ← 返回目录 | 下一章：安装部署与环境配置 → |