第一章：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）在 OpenCode 多 Agent 框架下的能力发挥到极致。

核心理念只有四个字：Token 效率优先——用最小的上下文成本达到最好的开发效果。这不是一个花哨的”AI 生产力工具”，而是一套经过 83+ 次提交、20 个迭代阶段打磨出来的务实方案：路径引用替代文件粘贴、技能按需加载而非全量注入、DCP 智能压缩替代简单截断、AGENTS.md 全局规则从 292 行精简到 229 行——每一步都在追问”能不能少花一点 token”。

如果你用一个比喻来记住它：它是 OpenCode 生态里专门为 DeepSeek 用户打造的”操作系统”——帮你分配算力（Pro vs Flash）、调度进程（Agent 路由）、装载驱动（Skills）、定义权限和契约（AGENTS.md），而你只需要用自然语言下达指令。

1.2 项目解决什么问题

传统 AI 编码工具和配置方案存在五个系统性问题，my-opencode-deepseek-config 针对每一个都给出了回答。

问题一：厂商/模型锁定

大多数 AI 编码工具将用户绑定到特定模型（GPT-4、Claude、Gemini），切换成本极高。即使工具本身支持多 Provider，默认配置也往往偏向某一个生态。这导致：

无法利用不同模型的差异化优势（DeepSeek 的成本优势、推理能力）
定价策略变化时没有议价能力
想尝试新模型时需要大量手动配置

本方案的答案：通过 enabled_providers: ["deepseek"] + disabled_providers 双重锁，确保只使用 DeepSeek。同时保留扩展性——换模型只需修改 provider 配置，Agent 和 Skills 体系零耦合。

问题二：上下文成本不可控

大语言模型的 API 调用按 Token 计费，上下文越长成本越高。很多配置方案缺乏系统的 Token 管理策略，导致：

每次对话无差别地注入全部 Skill 和规则，80% 的 Token 花在”可能用得上”的内容上
代码审查报告把整个文件贴进提示词，而不是用路径引用
会话历史无限增长，没有压缩机制

本方案的答案：贯彻 Token 效率优先——Skill 通过原生 skill 工具按需加载（只在触发时才注入上下文）；DCP 插件在 45K–85K Token 阈值主动压缩；AGENTS.md 明确要求”引用路径，不粘贴文件”；甚至在 Agent 系统提示的设计上也做了去重（v20 版本将 AGENTS.md 精简 22%）。

问题三：缺乏结构化的多 Agent 协作机制

单模型对话的局限性已经很明显：一个模型既要理解意图、又要探索代码、还要执行修改、还要自我审查——角色冲突导致每个环节都做不深。但多 Agent 方案如果缺少清晰的职责边界和路由规则，反而会造成上下文浪费和决策混乱。

本方案的答案：10 个 Agent 各司其职，通过 Orchestrator 的意图门控 + 6 类任务分类 + 模型感知路由实现精准调度。关键设计包括：

执行与探索分离：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`	10 个 Agent 的系统提示词，定义角色、能力、约束	orchestrator.md 包含意图门控逻辑和完整路由表
`skills/*/SKILL.md`	18 个可复用技能的详细指令，按需加载	code-review/SKILL.md 包含审查维度、严重度分级、熵扫描和收敛检查
`AGENTS.md`	全局规则，所有 Agent 共享	语言检测、反模式列表、证据纪律、Task Rejection Contract

不需要安装任何额外的 npm 包、Python 库、或外部服务。OpenCode 自身作为运行时，配置文件就是”程序”。

特性二：DeepSeek V4 双模型极致利用

这是本方案最核心的优化策略——用最小的模型开销完成任务：

模型	角色	典型用途
`deepseek/deepseek-v4-pro`	推理与决策引擎	架构规划、根因分析、代码审查、重型多文件实现、Orchestrator 调度
`deepseek/deepseek-v4-flash`	查询与执行引擎	代码库搜索、文档检索、轻量单文件编辑、简单任务、交接文档生成

路由策略确保”杀鸡不用牛刀”：

Flash 优先：搜索、查找、简单编辑等明确定义的任务优先走 Flash Agent
Pro 专注推理：规划、分析、审查、复杂实现只用 Pro
自动升级：Flash Agent 无法胜任时自动升级到 Pro，带完整上下文

这套分工的深层逻辑是：Pro 模型的推理能力更强但成本更高，Flash 模型速度快、成本低但推理深度有限。一个典型的开发任务中，80% 的步骤（搜索文件、查阅文档、生成提交信息、简单语法修复）不需要强推理模型，交给 Flash 即可。剩下 20% 的核心难度步骤（理解复杂逻辑、设计架构、多文件重构）才需要 Pro 出马。

特性三：10 个专业化 Agent，职责清晰

每个 Agent 有严格定义的职责边界和模型绑定：

Pro 模型 Agent 群（6 个）——推理与决策层：

Agent	权限	核心职责
`orchestrator`	读写	默认入口，意图门控、任务分类（6 类）、模型感知路由、后备链
`planner`	读写	规划与架构设计、拆解复杂任务、制定技术方案
`deep-worker`	读写	重型实现、多文件改动、复杂调试（禁止研究/委托）
`oracle`	只读	根因分析、深度理解代码、问题溯源
`reviewer`	只读	多维度代码审查、质量检查、对抗性自检、上下文校准
`consultant`	读写	方案讨论、技术对比、最佳实践建议
`ui-builder`	读写	前端与 UI 相关任务

Flash 模型 Agent 群（3 个）——查询与执行层：

Agent	权限	核心职责
`explore`	只读	代码库搜索、并行探索、文件模式匹配
`librarian`	只读	文档检索、Web 搜索、API 文档核对
`light-orchestrator`	读写	轻量任务、单文件编辑（禁止研究/委托）

“禁止研究/委托”原则：deep-worker 和 light-orchestrator 是用来执行的，不是用来探索的。它们的上下文由 Orchestrator 在调度时提供完整，执行过程中不得自行发起研究或委托给其他 Agent。这避免了”Agent A 委托给 Agent B，Agent B 又委托给 Agent C”的上下文膨胀链。

特性四：18 个可复用技能，按需加载

技能（Skill）是本方案的能力模块。OpenCode 通过原生 skill 工具按需暴露——Agent 只在需要时才加载，不会常驻上下文。18 个 Skill 覆盖了从代码审查到版本发布的全流程：

过程与纪律类（5 个）：

code-review — Token 高效多维度审查（含熵扫描+收敛检查）
security-review — 合并前安全审查清单
deepwork — 审查门控分阶段执行
spec-workflow — 规约驱动变更工作流（explore→propose→apply→update→archive）
verification-planning — 实现前规划最窄验证路径

Git 与发布类（3 个）：

gh-cli — GitHub CLI 全面操作（v2.96+，含 Issues 2.0）
git-master — 高级 Git：rebase、squash、bisect、reflog、worktree
git-release — 准备 Tag 发布（SemVer 推断+发布说明）
conventional-commits — 按规范写提交信息

分析与诊断类（3 个）：

diagnose — 6 阶段结构化调试（复现→最小化→假设→打点→修复→回归）
reflect — 发现摩擦→提出最小配置优化
simplify — 行为保持的代码简化

探索与知识类（2 个）：

codemap — 生成带标注的仓库结构图
verify-with-docs — 编码前检索核对 API 文档

配置与维护类（4 个）：

opencode-config — 编写和维护 OpenCode 配置
remove-deadcode — 安全查找并删除死代码（LSP 验证后删除）
handoff — 会话压缩为交接文档（路径引用，不复制内容）
gh-skill — 发现、安装、更新、发布 Agent 技能

特性五：23+ 快捷命令别名

每个命令精准触发特定 Agent + Skill 组合，从 /deep（重型实现）到 /rmslop（清理死代码），覆盖日常开发的高频场景。详见第七章。

特性六：Token 效率优先的设计哲学

前面提到 Token 效率是核心理念，这里展开讲它的具体实现手段：

路径引用替代粘贴：AGENTS.md 明确规定”引用路径，不粘贴文件”。报告代码问题时写 src/app.ts:42，而不是把整个文件复制进提示词。
技能按需加载：18 个 Skill 通过 skill 工具按需加载，不会在每次对话时全部注入上下文。一个代码审查任务不会拖着一整套 Git Release 流程的指令。
DCP 智能压缩：dcp.jsonc 配置了 45K–85K Token 的主动压缩阈值——当会话上下文超过 45K 时触发压缩，保留核心信息，裁剪冗余。低于这个阈值不做裁剪，高于 85K 时强制压缩。OpenCode 原生的 compaction 作为兜底。
去重与精简：v20 版本中，AGENTS.md 从 292 行精简到 229 行（22% 的减幅），Agent 提示词去重 20%。因为多个 Agent 的提示词共享同一套 AGENTS.md 全局规则，在各自提示词中重复声明只会浪费 Token。
上下文管理策略：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	10 个专业化 Agent，职责清晰
技能	无预置技能	18 个可复用技能，按需加载
全局规则	无	229 行 AGENTS.md，包含反模式、证据纪律、拒绝契约
命令别名	无	23+ 快捷命令
上下文管理	原生 compaction	DCP 智能压缩 + 路径引用策略
模型分工	无策略	Pro/Flash 严格分工，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 数量	较少	18 个，覆盖更全面
Agent 数量	相近	10 个，增加 ui-builder、consultant 等
上下文管理	基础	DCP 智能压缩 + 路径引用 + 去重
迭代设计	—	20 个阶段，83 次提交，有完整设计决策记录
社区活跃度	—	36 Star，9 Fork

总结：oh-my-openagent 在通用性上更胜一筹，my-opencode-deepseek-config 在 DeepSeek 生态的深耕和 Token 效率优化上更极致。

vs Cursor / Copilot 等 IDE 插件

维度	Cursor / Copilot	my-opencode-deepseek-config
运行方式	IDE 插件，图形界面	终端 CLI，纯文本配置
多 Agent	有限或隐式	显式 10 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 数量	较少	18 个
Agent 数量	较少	10 个
上下文管理	基础	DCP + 路径引用 + 去重
迭代深度	—	20 个迭代阶段，83 次提交

总结：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 的特点做了适配。

场景四：需要复杂多步骤开发任务自动化

你的日常开发中经常有这样的场景：新功能需要先探索代码结构→制定方案→多文件实现→代码审查→清理死代码→规范化提交。本方案的 /explore → /propose → /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（enabled_providers: ["deepseek"]）。虽然改 Provider 配置不复杂，但 Agent 提示词中对模型行为的一些假设（如对 Token 效率的强调程度）是在 DeepSeek 上验证过的。换模型不是不行，但效果需要重新调优。

场景四：你不愿意花时间学习配置体系

纯配置驱动的代价是需要理解配置。如果”开箱即用”是你的首要诉求，IDE 插件类的方案（Cursor、Copilot）可能更适合。

1.6 技术架构全景图

用文字描述本方案的整体架构分层。可以把它想象成一个五层栈，层与层之间通过清晰的接口连接。

第一层：用户入口层

开发者与系统的交互界面。有两个入口通道：

自然语言入口：直接在 OpenCode 对话中输入需求描述——”帮我排查这个登录接口的报错”——Orchestrator 自动分析意图并路由到合适的 Agent。
命令别名入口：输入 /deep、/review、/plan 等 23+ 快捷命令，精确触发特定 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-pro 上——因为路由决策需要推理能力，不能省这笔 Token。

第三层：执行层

执行层分为两个子层，按模型能力划分：

Pro Agent 群（推理与决策）——运行在 deepseek/deepseek-v4-pro：

orchestrator：主编排器，位于第二层和第三层的交叉点
planner：将模糊需求转化为可执行的计划
deep-worker：多文件重型实现，复杂调试
oracle：只读，深度分析代码逻辑、追溯问题根因
reviewer：只读，多维度代码审查
consultant：方案讨论和技术对比
ui-builder：前端和 UI 专项

Flash Agent 群（查询与轻量执行）——运行在 deepseek/deepseek-v4-flash：

explore：只读，代码库并行搜索
librarian：只读，外部文档检索
light-orchestrator：读写，单文件轻量编辑

关键约束：

只读 Agent（oracle、reviewer、explore、librarian）绝不修改文件
执行 Agent（deep-worker、light-orchestrator）禁止自行研究和委托
Agent 嵌套深度限制为 3 层（subagent_depth: 3），防止无限递归

第四层：能力层

执行层的 Agent 通过加载 Skill 获取专业能力。18 个 Skill 按功能域组织在 skills/ 目录下，通过 OpenCode 原生的 skill 工具按需加载。

此外还有两个插件增强系统能力：

superpowers（obra/superpowers）：提供 14 个过程型技能（brainstorming、systematic-debugging、TDD、writing-plans 等），在 Agent 启动时自动注入引导，确保 Agent 在面临特定类型任务时”先想清楚再动手”。
DCP（opencode-dcp）：智能上下文裁剪插件。在 45K–85K Token 阈值区间内主动压缩会话上下文，裁剪冗余但保留关键信息。与 OpenCode 原生的 compaction 形成双保险。

插件遵循”增效但不喧宾夺主”的原则——它们增强系统的过程纪律和能力，但不会引入额外的模型或打破纯配置驱动的设计。

第五层：配置层

整个系统的”宪法”由三个文件组成：

文件	作用	关键内容
`opencode.jsonc`	核心配置	模型绑定、Agent 定义与权限、subagent_depth: 3、实验功能、权限基线
`dcp.jsonc`	压缩配置	DCP 插件的阈值设定（45K–85K）、压缩策略
`AGENTS.md`	全局规则	核心原则、语言策略、反模式清单、质量基准、证据纪律、Task Rejection Contract、上下文管理、Self-Verification 流程、Stop Condition

AGENTS.md 是第五层中最重要的文件——它不属于任何一个 Agent，但被所有 Agent 共享。它定义的不是”某个 Agent 该怎么做”，而是”所有 Agent 都必须遵守“的契约。从”禁止创建 utils.ts“到”没有证据不能声称完成”，这些规则构成了系统的质量底线。

架构全景图（文字版）

┌─────────────────────────────────────────────────────────────┐
│  用户入口层                                                   │
│  ┌──────────────────────┐  ┌────────────────────────────┐  │
│  │  自然语言输入          │  │  23+ 命令别名               │  │
│  │  "帮我排查这个bug..."   │  │  /deep  /review  /plan ... │  │
│  └─────────┬────────────┘  └─────────────┬──────────────┘  │
│            └──────────────┬──────────────┘                  │
├───────────────────────────┼─────────────────────────────────┤
│  编排层                    ▼                                  │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Orchestrator (deepseek-v4-pro)                        │ │
│  │  意图门控 → 6类任务分类 → 模型感知路由 → 后备链         │ │
│  └──────────────────────┬─────────────────────────────────┘ │
├─────────────────────────┼───────────────────────────────────┤
│  执行层                  ▼                                    │
│  ┌──────────────────────┴──────────────────────────────┐    │
│  │  Pro Agent 群 (deepseek-v4-pro)                     │    │
│  │  planner · deep-worker · oracle · reviewer          │    │
│  │  consultant · ui-builder                            │    │
│  ├─────────────────────────────────────────────────────┤    │
│  │  Flash Agent 群 (deepseek-v4-flash)                 │    │
│  │  explore · librarian · light-orchestrator           │    │
│  └──────────────────────┬──────────────────────────────┘    │
├─────────────────────────┼───────────────────────────────────┤
│  能力层                  ▼                                    │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  18 Skills (按需加载)                                 │   │
│  │  code-review · security-review · diagnose · ...      │   │
│  ├──────────────────────────────────────────────────────┤   │
│  │  2 Plugins (增效但不喧宾夺主)                         │   │
│  │  superpowers (过程纪律) · DCP (智能压缩)              │   │
│  └──────────────────────┬───────────────────────────────┘   │
├─────────────────────────┼───────────────────────────────────┤
│  配置层                  ▼                                    │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  opencode.jsonc (核心配置 · 模型 · Agent · 权限)      │   │
│  │  dcp.jsonc      (压缩阈值 · 策略)                     │   │
│  │  AGENTS.md      (全局规则 · 229行 · 所有Agent共享)    │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

1.7 设计哲学

本方案不是东拼西凑的配置集合，每一行配置背后都有一个明确的意图。以下六条设计原则是理解整个系统的钥匙。

原则一：纯配置驱动，零额外依赖

“Configuration is code.”

项目的能力增长不靠引入新的工具或库，而是靠更精细、更智能的配置。原因有三：

可审计：纯文本配置的每一次变更都可以通过 git diff 审查，没有任何”黑盒”行为。
可复现：在任何机器上 git clone 就能得到完全相同的行为，不需要安装依赖、配置环境。
低维护成本：配置文件的复杂度远低于代码项目，不会出现依赖冲突、版本不兼容的问题。

这也意味着本方案的能力上界是 OpenCode 框架本身的能力上界。我们不能在配置里”创造” OpenCode 不支持的机制，只能”用好”已有的机制。这不是限制，而是策略——与其在框架外造轮子，不如把框架内的能力组合到极致。

原则二：DeepSeek V4 双模型极致利用

“Right model for the right job.”

这个原则有两个维度：

纵向维度：按任务难度分配模型。简单的搜索和查询用 Flash，复杂的推理和决策用 Pro。这不是粗暴的二分法，而是通过 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 在触发时才注入，不在每次对话中都携带 18 个 Skill 的全部内容——节省 80% 的 Skill Token。
智能压缩：DCP 在 45K 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 到 v20 的每一次关键变更，形成了可追溯的演进历史。这不是文档的装饰，而是后续决策的依据——”上次我们为什么把 AGENTS.md 从 292 行精简到 229 行？因为分析发现 22% 的内容在 Agent 系统提示中已经重复声明了。”

1.8 仓库结构概览

下面是克隆本仓库后看到的完整目录结构。每一条目录和文件都有明确的职责。

my-opencode-deepseek-config/
│
├── agents/                              ← 10 个 Agent 系统提示词 (.md)
│   ├── orchestrator.md                  ← 主编排器：意图门控、6类任务分类、
│   │                                       模型感知路由、后备链、上下文管理
│   ├── planner.md                       ← 规划师：架构设计、技术方案、任务拆解
│   ├── deep-worker.md                   ← 重型执行：多文件改动、复杂调试
│   │                                       【禁止研究/委托】
│   ├── oracle.md                        ← 深度分析：根因分析、代码理解、问题溯源
│   │                                       【只读】
│   ├── reviewer.md                      ← 代码审查：多维度、分级、对抗性自检、
│   │                                       上下文校准、熵扫描、收敛检查【只读】
│   ├── consultant.md                    ← 技术顾问：方案讨论、对比取舍、最佳实践
│   ├── ui-builder.md                    ← 前端专项：UI 组件、样式、交互逻辑
│   ├── explore.md                       ← 探索者：代码库搜索、并行探索、文件匹配
│   │                                       【只读 · Flash】
│   ├── librarian.md                     ← 图书管理员：文档检索、Web 搜索、API 查询
│   │                                       【只读 · Flash】
│   └── light-orchestrator.md            ← 轻量执行：单文件编辑、简单任务
│                                           【禁止研究/委托 · Flash】
│
├── skills/                              ← 18 个可复用技能 (SKILL.md)
│   ├── code-review/                     ← Token 高效多维度代码审查
│   │   └── SKILL.md                     ← 含熵扫描、收敛检查、严重度分级
│   ├── security-review/                 ← 合并前安全审查清单
│   │   └── SKILL.md
│   ├── conventional-commits/            ← Conventional Commits 规范提交
│   │   └── SKILL.md
│   ├── diagnose/                        ← 6 阶段结构化调试
│   │   └── SKILL.md                     ← 复现→最小化→假设→打点→修复→回归
│   ├── deepwork/                        ← 审查门控分阶段执行
│   │   └── SKILL.md
│   ├── spec-workflow/                   ← 规约驱动变更工作流
│   │   └── SKILL.md                     ← explore→propose→apply→update→archive
│   ├── verification-planning/           ← 实现前规划验证路径
│   │   └── SKILL.md
│   ├── verify-with-docs/                ← 编码前检索核对 API 文档
│   │   └── SKILL.md
│   ├── reflect/                         ← 持续改进：发现摩擦→配置优化
│   │   └── SKILL.md
│   ├── simplify/                        ← 行为保持的代码简化
│   │   └── SKILL.md
│   ├── remove-deadcode/                 ← 安全查找删除死代码（LSP 验证）
│   │   └── SKILL.md
│   ├── codemap/                         ← 生成带标注的仓库结构图
│   │   └── SKILL.md
│   ├── handoff/                         ← 会话压缩为交接文档
│   │   └── SKILL.md                     ← 路径引用，不复制内容
│   ├── git-master/                      ← 高级 Git 操作
│   │   └── SKILL.md                     ← rebase、squash、bisect、reflog、worktree
│   ├── git-release/                     ← 准备 Tag 发布
│   │   └── SKILL.md                     ← SemVer 推断 + 发布说明
│   ├── gh-cli/                          ← GitHub CLI 全面操作
│   │   └── SKILL.md                     ← v2.96+，含 Issues 2.0、copilot、agent-task
│   ├── gh-skill/                        ← Agent 技能管理
│   │   └── SKILL.md                     ← 发现、安装、更新、发布
│   └── opencode-config/                 ← 编写维护 OpenCode 配置
│       └── SKILL.md
│
├── AGENTS.md                            ← 全局规则（229行），所有 Agent 共享
│                                          核心原则、语言策略、反模式、质量基准、
│                                          证据纪律、Task Rejection Contract、
│                                          上下文管理、Self-Verification、
│                                          Stop Condition、Comment Discipline
│
├── opencode.jsonc                       ← 核心配置文件
│                                          模型绑定（Pro + Flash）、
│                                          Agent 定义与权限（含 subagent_depth: 3）、
│                                          Provider 锁（enabled + disabled）、
│                                          实验功能（batch_tool）、
│                                          权限基线（bash: ask, .env: deny）
│
├── dcp.jsonc                            ← DCP 智能压缩配置
│                                          压缩阈值（45K–85K Token）、
│                                          压缩策略、保留规则
│
├── README.md                            ← 项目文档与使用指南
│                                          安装部署、模型配置、Agent 结构、
│                                          快捷命令、技能列表、设计决策、
│                                          迭代里程碑、使用指南
│
└── LICENSE                              ← MIT 开源许可证

文件统计

类别	数量	说明
Agent 系统提示	10 个	`agents/` 目录下每个 `.md` 文件定义一个 Agent
Skill 技能	18 个	`skills/` 目录下每个子目录包含一个 `SKILL.md`
核心配置	3 个	`opencode.jsonc` + `dcp.jsonc` + `AGENTS.md`
文档与许可	2 个	`README.md` + `LICENSE`
总计	33 个文件	全部为纯文本，可直接 Git 管理

目录结构的设计逻辑

这个目录结构不是随意摆放的，它直接映射 OpenCode 框架的配置约定：

agents/ 目录被 OpenCode 自动识别——放在这里的 .md 文件会成为可用的 Agent。
skills/ 目录通过 skill 工具按需加载——Agent 在运行时通过 skill 工具传入 Skill 名称，OpenCode 自动查找对应目录下的 SKILL.md。
AGENTS.md 是 OpenCode 约定的全局规则文件——如果存在，所有 Agent 的上下文会自动包含这个文件的内容。
opencode.jsonc 是 OpenCode 的主配置文件——控制模型、权限、实验功能等。

这意味着本仓库的目录结构就是 OpenCode 期望的配置目录结构。你不需要做任何映射或转换，git clone 到 ~/.config/opencode 后立刻生效。

本章小结

回到开头的问题：my-opencode-deepseek-config 是什么？

它是一个为 DeepSeek V4 双模型精心调优的 OpenCode 配置仓库。它有 10 个各司其职的 Agent、18 个按需加载的 Skill、23+ 个快捷命令、229 行全局规则，以及贯穿始终的 Token 效率优先哲学。

但它不只是”功能列表的堆砌”。它背后的设计理念——纯配置驱动、执行与探索分离、Token 效率优先——才是它区别于其他方案的本质。这些理念不是拍脑袋想出来的，而是在 20 个迭代阶段、83 次提交中，通过与实际开发任务的反复磨合形成的。

如果你读完本章后决定继续深入，下一章会带你完成安装部署——把这个配置仓库变成你日常开发的”AI 编码操作系统”。

← 返回目录

下一章：安装部署与环境配置 →