第八章：配置文件完全参考

本章对 my-opencode-deepseek-config 配置仓库中的两个核心配置文件 —— opencode.jsonc 和 dcp.jsonc —— 进行逐字段、逐层的完全解析。理解每个配置项的含义、作用以及它们之间的协同关系，是深入掌握这套多 Agent 系统的关键。无论你是想审查默认配置的合理性，还是打算基于此进行定制，本章都提供完整的参考依据。

版本说明：本章内容对应仓库 v38+ 版本。相比早期版本（v23 及以前），本版发生了多项结构性变化：enabled_providers/disabled_providers 双重锁已移除（v31），改为 provider.deepseek.models 三模型矩阵 + AGENTS.md 约束；snapshot、experimental.batch_tool 字段已从 schema 移除；compaction.prune 由 false 改为 true；tool_output 由 1500/40960 收紧为 800/20480；插件改为固定版本（superpowers #v6.3.0、DCP @3.1.15）；内置系统 Agent（build/plan/title/summary/compaction）全部迁移到 Flash；命令别名由 18 个调整为 17 个。仓库还包含 opencode/ 子目录（存放项目级 OpenCode 配置）。本章分析的配置文件版本对应 znlgis/my-opencode-deepseek-config 仓库当前版本。OpenCode 本身迭代很快，部分字段的行为可能随版本更新而调整，请以 opencode --help 和官方文档为最终参考。

8.1 opencode.jsonc 完全解析

opencode.jsonc 是整个多 Agent 系统的核心枢纽文件。它定义了模型选择、Provider 配置、Agent 体系、权限策略、插件加载、命令别名、上下文压缩策略等所有关键行为。以下是按字段分组后的完整解析。

8.1.1 模型配置部分

{
  "model": "deepseek/deepseek-v4-pro",
  "small_model": "deepseek/deepseek-v4-flash"
}

model（主模型）

• 类型：string
• 值："deepseek/deepseek-v4-pro"
• 格式：provider_id/model_id
• 作用：指定默认 Agent 在推理、规划、代码生成等重量级任务中使用的模型。DeepSeek V4 Pro 是该配置方案中算力最强、推理能力最优的模型，承担所有需要深度思考的工作。它是全局兜底模型——任何未显式指定模型的 Agent（如 solo）都会回落到 Pro。
• 命名规则：OpenCode 中模型的完整标识必须采用 provider/model 格式，即 Provider ID 在前、模型 ID 在后，用 / 分隔。

small_model（小模型）

• 类型：string
• 值："deepseek/deepseek-v4-flash"
• 作用：指定轻量级任务（快速查找、简单编辑、标题生成、会话摘要、上下文压缩等）使用的模型。DeepSeek V4 Flash 价格更低、速度更快，适合有明确量化指标的任务，例如 explore Agent 的代码库扫描、librarian 的文档检索、light-orchestrator 的轻量编排。
• 分工原则：Pro 模型 —— 复杂推理、架构设计、多文件重构；Flash 模型 —— 快速搜索、文件读取、标题生成、压缩摘要。

关于 Provider 锁定：早期版本（v23 及以前）通过 enabled_providers（白名单）+ disabled_providers（黑名单）的”双重锁”机制强制模型隔离。该机制在 v31 被移除——OpenCode 的 Provider 发现机制已足够可靠，且纯配置方案更倾向于用 provider.deepseek.models 显式声明三模型矩阵 + AGENTS.md 中”no new models”的规则约束来达成同样的隔离目标。当前版本不再使用这两个字段。

8.1.2 Provider 配置

Provider 决定了 OpenCode 如何与模型服务商对接。本配置方案中，DeepSeek 是唯一的 Provider，其配置在 opencode.jsonc 的 provider 字段中完整展开，声明了三模型矩阵及其成本与思考模式：

"provider": {
  "deepseek": {
    "models": {
      "deepseek-v4-flash": {
        "cost": {
          "input": 0.22,
          "output": 0.66,
          "cache_read": 0.007,
          "cache_write": 0.22
        },
        "options": {
          "temperature": 0,
          "thinking": { "type": "disabled" }
        }
      },
      "deepseek-v4-flash-vision-exp": {
        "modalities": {
          "input": ["text", "image"],
          "output": ["text"]
        },
        "cost": {
          "input": 0.22,
          "output": 0.66,
          "cache_read": 0.007,
          "cache_write": 0.22
        },
        "options": {
          "temperature": 0,
          "thinking": { "type": "disabled" }
        }
      },
      "deepseek-v4-pro": {
        "cost": {
          "input": 0.66,
          "output": 1.98,
          "cache_read": 0.022,
          "cache_write": 0.66
        }
      }
    }
  }
}

Provider 对象结构说明：

三模型矩阵：

关键设计点：

1. options.thinking 是 Provider 透传字段：它不是 OpenCode 原生 schema 字段，而是被原样转发给 DeepSeek API（OpenAI 格式的 thinking 开关 {"type":"enabled"|"disabled"}）。这是 deepseek-harness 官方推荐的思考模式控制方式。
2. Pro 不写 options = 思考默认开启：deepseek-v4-pro 没有 options 块，因此继承 DeepSeek 的默认行为（thinking on）。早期版本曾显式写 thinking: enabled，现在无需——默认即开启。
3. Flash 与 Vision-Exp 关闭思考 + temperature 0：这是官方成本优化方案——Flash 层级的模型关闭思考以获得最快、最便宜的响应，temperature 0 保证确定性。
4. modalities 声明图像输入：deepseek-v4-flash-vision-exp 通过 modalities.input: ["text","image"] 声明支持图像输入。没有这个声明，OpenCode 会把模型当作纯文本模型，拒绝 read_image 调用。
5. cost 用于成本估算：cost 字段（USD/1M tokens，off-peak 2026-08-16 定价）供 OpenCode 估算每次请求的成本。峰值时段价格翻倍。DeepSeek 未发布独立的 cache-write 价格，因此 cache_write 从 input 映射而来。

如需进一步了解三模型分工和 routing 策略，请参考 第三章：模型配置详解。

8.1.3 基础行为配置

{
  "default_agent": "orchestrator",
  "autoupdate": "notify",
  "lsp": true,
  "formatter": true
}

default_agent（默认入口 Agent）

• 类型：string
• 值："orchestrator"
• 作用：指定用户每次发起对话时默认使用的 Agent。设为 orchestrator 意味着每个用户请求首先由 Orchestrator 接收并进行意图分析，然后路由到最合适的专业 Agent。这是整个多 Agent 路由体系的入口点。
• 设计意图：将 Orchestrator 设为默认，用户无需手动指定 Agent，系统自动完成意图识别与任务分发。注意：Orchestrator 运行在 Flash 上（v38 起），因为路由本质是模式匹配而非深度推理；重型工作通过 fallback 升级到 Pro。

autoupdate（自动更新策略）

• 类型：string（枚举值："notify" / "auto" / "off"）
• 值："notify"
• 作用：控制 OpenCode 的自动更新行为。
  • "notify"：有新版本时提醒用户，但不自动安装。这是推荐的安全策略——让用户自己决定何时升级。
  • "auto"：自动下载并安装更新。
  • "off"：完全不检查更新。
• 选择理由：OpenCode 迭代快速，"notify" 使用户能及时了解新版本，同时避免自动升级可能引入的不兼容问题。

lsp（语言服务器协议支持）

• 类型：boolean
• 值：true
• 作用：启用 LSP（Language Server Protocol）集成。开启后，Agent 可以获取代码的智能提示——跳转到定义、查找引用、类型推断等。这对于代码审查、重构、调试等任务至关重要。

formatter（代码格式化）

• 类型：boolean
• 值：true
• 作用：启用 OpenCode 内置的代码格式化功能。Agent 在修改文件后可以自动运行项目的格式化器（如 Prettier、rustfmt），保持代码风格一致。

8.1.4 Agent 与子代理配置

{
  "subagent_depth": 3,
  "agent": {
    "build": { "model": "deepseek/deepseek-v4-flash" },
    "plan": { "model": "deepseek/deepseek-v4-flash" },
    "title": { "model": "deepseek/deepseek-v4-flash" },
    "summary": { "model": "deepseek/deepseek-v4-flash" },
    "compaction": { "model": "deepseek/deepseek-v4-flash" }
  }
}

subagent_depth（子代理嵌套深度）

• 类型：number
• 值：3
• 作用：控制 Agent 可以派生子代理的最大嵌套层级。设为 3 意味着支持三级代理嵌套：
  • 第 1 级：Orchestrator（用户请求的入口）
  • 第 2 级：Orchestrator 派生的 Planner 或 Deep-Worker
  • 第 3 级：Planner / Deep-Worker 再派生的 Light-Orchestrator 或其他子 Agent

  以实际工作流为例：

  Orchestrator → Planner（规划方案）→ Light-Orchestrator（执行某个子任务）

  三级深度覆盖了「用户意图 → 高层规划 → 具体执行」的完整链路。超过 3 层的嵌套在实际使用中极少出现，且每增加一层都会显著增加 Token 消耗和延迟，因此 3 是一个在灵活性和效率之间取得平衡的值。

agent（系统 Agent 配置）

此字段配置的是 OpenCode 内置的系统级 Agent（不需要 .md 文件定义），而非 agents/ 目录下的用户自定义 Agent。这些系统 Agent 处理的是框架层面的通用任务：

注意 全部 5 个系统 Agent 都指定 Flash 模型。这是 v38 的重要变化——早期版本中 build 和 plan 运行在 Pro 上，现在统一迁移到 Flash。这种”将 Pro 算力留给复杂推理、Flash 处理轻量操作”的策略遵循了模型分级使用的核心原则。fallback 字段已从 OpenCode schema 中移除（fallback is not a real schema key），OpenCode 会在内部自动执行 small_model -> model 的回退，无需显式配置。

Agent 自动注册机制：

你可能会注意到 opencode.jsonc 中没有显式列出 Orchestrator、Planner、Deep-Worker 等 12 个自定义 Agent。这是因为 OpenCode 会自动扫描 agents/ 目录下的 .md 文件，将文件名（去掉扩展名）作为 Agent 名称进行注册。例如：

agents/orchestrator.md  → Agent "orchestrator"
agents/deep-worker.md   → Agent "deep-worker"
agents/solo.md          → Agent "solo"
agents/vision.md        → Agent "vision"

这种设计使得添加新 Agent 只需在 agents/ 目录下创建一个新的 .md 文件，无需修改 opencode.jsonc。

8.1.5 插件配置

"plugin": [
  "superpowers@git+https://github.com/obra/superpowers.git#v6.3.0",
  "@tarquinen/opencode-dcp@3.1.15"
]

plugin（插件列表）

• 类型：string[]
• 作用：声明加载的插件。每个元素是 <package>@<source> 格式。

superpowers 插件：

• 来源：superpowers@git+https://github.com/obra/superpowers.git#v6.3.0
• 版本固定：通过 #v6.3.0 锚定到具体的 Git tag。插件固定版本是 v36 引入的实践——避免上游更新引入不兼容变化，保证配置的可复现性。

• 功能：提供 14 个过程型技能（process-oriented skills），覆盖软件开发的完整生命周期：

  技能名称	用途	触发场景
  brainstorming	创意构思与需求分析	任何创造性工作之前
  systematic-debugging	结构化调试方法论	遇到 bug 或测试失败时
  test-driven-development	测试驱动开发流程	实现功能或修复 bug 前
  dispatching-parallel-agents	并行代理调度	多个无依赖的独立子任务
  subagent-driven-development	子代理驱动开发	执行含独立任务的实现计划
  writing-plans	编写实现计划	有多步骤任务的规格或需求时
  executing-plans	执行实现计划	已有书面实现计划时
  requesting-code-review	请求代码审查	完成任务、实现重要功能后
  receiving-code-review	接收并处理审查反馈	收到代码审查意见后
  finishing-a-development-branch	完成开发分支	实现完成、测试通过后
  using-git-worktrees	Git worktree 隔离环境	开始需要隔离的功能开发时
  writing-skills	编写新技能	创建或编辑技能定义时
  verification-before-completion	验证后完成	声称任务完成/修复/通过前，先运行验证命令确认输出
  using-superpowers	技能引导入口	每个会话自动注入，确保 Agent 优先检查并调用相关技能

  此外，using-superpowers 技能会自动注入到每个会话中，确保 Agent 在每次响应前都优先检查并调用相关技能，形成技能优先的行为准则。

DCP 插件：

• 来源：@tarquinen/opencode-dcp@3.1.15
• 版本固定：DCP 同样固定到 @3.1.15 具体版本，与 superpowers 的固定策略一致。
• 功能：Dynamic Context Pruning（动态上下文裁剪），负责智能管理对话上下文的大小，在 Token 消耗和上下文质量之间取得最优平衡。它是 OpenCode 原生压缩的主动增强层。

DCP 的详细配置由独立的 dcp.jsonc 文件控制，见 8.2 节。

8.1.6 指令与规则配置

{
  "instructions": ["AGENTS.md"],
  "references": {
    "opencode-docs": {
      "repository": "anomalyco/opencode",
      "branch": "dev",
      "description": "Official opencode docs, schema, and configuration examples"
    },
    "deepseek-harness": {
      "repository": "deepseek-ai/deepseek-harness",
      "description": "Official DeepSeek model config guidance: thinking toggle, temperature, prompt-caching, context-window handling, OpenAI-compatible API setup"
    }
  }
}

instructions（全局指令文件）

• 类型：string[]
• 值：["AGENTS.md"]

• 作用：指定 OpenCode 在每个会话启动时自动加载为上下文前缀的规则文件。AGENTS.md 是整个多 Agent 系统的 “宪法”文件——它对所有 Agent 施加统一的约束（代码风格、安全性、工作纪律等），确保无论哪个 Agent 执行任务，行为都在统一的框架内。

  自动加载机制：

  1. 会话启动时，OpenCode 读取 instructions 列表中的所有文件。
  2. 将文件内容注入到每个 Agent 的系统提示中（作为共享上下文）。
  3. Agent 自己的 .md 提示文件在共享上下文之上叠加。
  4. 当 AGENTS.md 和 Agent 自己的提示冲突时，遵循更严格者优先的原则。

AGENTS.md 的完整解读见 第九章：全局规则 AGENTS.md 深度解读。

references（参考文档挂载）

• 类型：object
• 作用：声明可供 Agent 引用的外部文档源。Agent 可以通过引用名称（如 opencode-docs）来查阅官方文档，而无需每次从网络获取。
• opencode-docs 条目：
  • repository: "anomalyco/opencode"：官方的 OpenCode 仓库
  • branch: "dev"：使用开发分支（包含最新的 schema 和配置示例）
  • description：人类可读的描述，帮助 Agent 理解何时该查阅此引用源

• deepseek-harness 条目：DeepSeek 官方的模型配置指南（thinking 开关、temperature、prompt-caching、上下文窗口处理、OpenAI 兼容 API 设置）。这是 v35 引入的引用源，为 Agent 提供 DeepSeek 模型配置的权威依据。

  references 机制与 verify-with-docs 技能协同工作，形成”检索优先”的知识策略——Agent 在不确定 API 签名或配置 schema 时，应先查阅挂载的引用源，而非从记忆或猜测出发。

8.1.7 压缩配置

"compaction": {
  "auto": true,
  "prune": true,
  "tail_turns": 8,
  "preserve_recent_tokens": 12000,
  "reserved": 10240
}

auto（自动压缩）

• 类型：boolean
• 值：true
• 作用：启用 OpenCode 原生的自动上下文压缩。当对话上下文接近 Token 限制时，系统自动将早期的对话轮次压缩为摘要，释放空间给新的交互内容。

prune（裁剪模式）

• 类型：boolean
• 值：true
• 作用：启用纯裁剪模式。true 意味着压缩会丢弃过时的工具输出（而非仅摘要化）。这是 v38 的变化——早期版本为 false。改为 true 的原因：DCP 插件（见 8.2 节）负责主动的智能范围压缩，而 OpenCode 原生压缩作为近溢出的兜底层，此时直接裁剪过时的工具输出比生成摘要更高效。两层互补而非重叠。

tail_turns（保留尾部轮次）

• 类型：number
• 值：8
• 作用：压缩时至少保留最后 8 轮对话不被压缩。最近轮次包含当前任务的最新进展，压缩它们会导致 Agent “失忆”，因此必须受到保护。8 轮是一个经过经验调优的值——足够覆盖一个典型子任务的完整对话链，又不会过度浪费 Token 预算。

preserve_recent_tokens（保留最近 Token 数）

• 类型：number
• 值：12000
• 作用：直接指定保留最近 12000 个 Token 不被压缩。这是对 tail_turns 的补充保护——有时 8 轮对话的 Token 数可能超过或不足，直接按 Token 数保护更精确。

reserved（预留 Token 数）

• 类型：number
• 值：10240
• 作用：为模型输出保留 10240 Token 空间。在计算何时触发压缩时，需要确保压缩后不仅有空间放压缩后的上下文，还要有足够的空间容纳模型的生成内容。10240（约 10K）Token 足以覆盖绝大多数 Agent 的单次响应。

两层压缩协同：

OpenCode 的 native compaction 和 DCP 插件形成了两层互补的压缩体系：

DCP 负责主动管理——在上下文还没满之前就进行分析和优化。OpenCode 原生压缩负责被动兜底——当 DCP 未能完全阻止溢出时，原生压缩作为最后的保障。详见 8.2.8 节。

8.1.8 会话与图像配置

{
  "share": "disabled",
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 1600,
      "max_height": 1600,
      "max_base64_bytes": 2097152
    }
  }
}

share（会话分享）

• 类型：string（枚举值："disabled" / "enabled"）
• 值："disabled"
• 作用：关闭 OpenCode 的会话分享功能。会话分享会将对话内容上传到 OpenCode 的服务器生成分享链接，这会带来两方面的问题：
  1. Token 消耗：上传过程本身消耗资源。
  2. 隐私风险：对话内容可能包含敏感信息（代码片段、API 密钥相关讨论等）。

  禁用会话分享是”最小权限”安全原则的体现。

attachment.image（图像附件配置）

• 类型：object
• 作用：约束发送给多模态模型（deepseek-v4-flash-vision-exp）的图像大小，控制 Token 成本。注意键名是单数 attachment（schema 合法），复数形式会被忽略。
  • auto_resize: true：自动缩放超限图像。
  • max_width / max_height: 1600：超过 1600px 的图像会被缩放。
  • max_base64_bytes: 2097152：超过 2MB 的 base64 会被拒绝。

  设计理由：DeepSeek 内部会把图像缩放到约 800x800，因此过大的上传只会浪费 base64 字节。在图像到达 API 之前就限制大小，能有效控制多模态任务的 Token 成本。

关于 snapshot：早期版本（v23 及以前）配置了 "snapshot": true 开启 Git 快照。该字段已从 OpenCode schema 中移除，当前版本不再使用。Git 快照功能由 OpenCode 的 /undo 机制和 Git 本身管理。

8.1.9 权限配置详解

权限配置是整个系统的安全防线。它定义了 Agent 可以对文件系统和命令执行做什么、不能做什么。合理的权限设置可以防止 AI 误操作（如删除关键文件、泄露敏感信息），同时又不妨碍正常的开发流程。

"permission": {
  "read": {
    "*": "allow",
    ".env": "deny",
    "*.env": "deny",
    "*.env.*": "deny",
    ".envrc": "deny",
    "*.envrc": "deny",
    "*.env.example": "allow"
  },
  "bash": {
    "git status*": "allow",
    "git diff*": "allow",
    "git log*": "allow",
    "git show*": "allow",
    "git stash list*": "allow",
    "git add *": "allow",
    "git commit*": "allow",
    "node scripts/*": "allow",
    "npm run *": "allow",
    "npm test*": "allow",
    "rg *": "allow",
    "rm -rf*": "ask",
    "rm -fr*": "ask",
    "Remove-Item -Recurse -Force*": "ask",
    "rd /s*": "ask",
    "del /f /s*": "ask",
    "del /f /q*": "ask",
    "format *": "ask",
    "git push --force*": "ask",
    "git push -f *": "ask",
    "git push --force-with-lease*": "ask",
    "git reset --hard*": "ask",
    "git clean -fd*": "ask",
    "git checkout .*": "ask",
    "git checkout --*": "ask",
    "git branch -D*": "ask",
    "git stash clear*": "ask",
    "git stash drop*": "ask",
    "gh repo delete*": "ask",
    "gh pr close*": "ask",
    "*": "ask"
  },
  "skill": {
    "*": "allow"
  },
  "external_directory": "ask"
}

重要：permission.bash 的解析采用 last-match-wins（最后匹配生效）策略，因此 catch-all "*": "ask" 必须放在最后——它上面的每一条 allow/ask 规则都会覆盖它。这是 v38 权限重构的核心：从”默认 allow + 精准 ask”改为”默认 ask + 高频安全操作 allow”。

8.1.9.1 读取权限（read）

设计逻辑：

1. 默认宽松，精准收紧："*": "allow" 给 Agent 必要的自由度，方便在项目中查找和阅读代码。过严的读取限制会严重影响 Agent 的工作效率。
2. 敏感文件保护：.env、.envrc 类文件可能包含 API Key、数据库连接串等敏感信息。通过 deny 阻止 Agent 读取这些文件，从源头防止密钥泄露。.envrc 是 v38 新增的防护（direnv 配置同样可能含敏感内容）。
3. 模板文件例外：*.env.example 是环境变量模板，不含真实密钥，通常需要开发者参考来配置本地环境。明确 allow 此模式确保 Agent 可以读取模板并提供配置指导。

8.1.9.2 Bash 执行权限（bash）

Bash 权限按”默认 ask + 高频安全操作 allow + 破坏性操作 ask”的策略设置：

为什么默认 ask 而非 allow：

这是 v38 权限重构的核心变化。早期版本采用”默认 allow + 破坏性命令 ask”，但存在一个漏洞：一个未识别的破坏性命令变体（例如 rm -rf 换一种拼写或空格方式）会匹配到 * 而直接运行，不受保护。改为”默认 ask + 高频安全操作 allow”后，任何未列入 allow-list 的命令（包括未识别的破坏性变体）都会触发确认，从根本上堵住了这个漏洞。

为什么这些命令设为 ask 而非 deny：

设为 deny（完全禁止）会导致 Agent 在某些场景下无法完成任务（例如需要 git push --force 来修正错误推送的情况）。ask 则让人类做最终的判断——系统弹出确认提示，用户可以看到完整的命令内容，选择允许或拒绝。这实现了”人在回路”的安全模型。

跨平台命令覆盖：

注意破坏性命令的规则覆盖了三大平台的语法变体：

8.1.9.3 技能权限（skill）

"skill": { "*": "allow" }

• 作用：允许 Agent 加载所有技能。技能是预定义的、经过审核的工作流，加载技能本身不涉及写文件或执行命令的风险，因此默认 allow。如果未来需要限制某个特定技能的调用，可以在此处添加 deny 规则。

8.1.9.4 外部目录权限（external_directory）

"external_directory": "ask"

• 类型：string（枚举值："allow" / "ask" / "deny"）
• 值："ask"
• 作用：当 Agent 尝试在项目工作区之外的目录执行操作（读取、写入、执行命令）时，弹出确认提示。这是防止 Agent “越界”访问的关键防线——例如 Agent 不应该读取用户的 ~/.ssh 目录或修改系统文件。

8.1.10 工具输出配置

"tool_output": {
  "max_lines": 800,
  "max_bytes": 20480
}

max_lines（最大输出行数）

• 类型：number
• 值：800
• 作用：限制工具（如 Bash、文件读取）输出内容在对话中的显示行数。超过 800 行的输出会被截断并保存到临时文件，对话中只显示摘要。这防止了某次误操作（如 cat 一个大文件）瞬间占满上下文窗口。

max_bytes（最大输出字节数）

• 类型：number
• 值：20480
• 作用：以字节为单位的输出限制，与 max_lines 互补——某些输出可能行数少但单行极长（如 minified JSON），字节限制能兜底捕获这种情况。

调优说明：800 行 / 20KB 是 v38 的取值，比 OpenCode 官方默认（max_lines: 2000）更保守，但比早期版本（200/8192）宽松。200/8192 太紧，会截断正常的文件读取，迫使 Agent 反复重读，反而消耗更多 Token。800/20480 在”避免截断正常读取”和”防止超大输出占满上下文”之间取得平衡。

8.1.11 命令别名配置（commands 字段）

commands 字段定义了 17 个自定义命令别名，每个命令将用户输入映射到特定的 Agent + Skill 组合。这是”意图即路由”理念的技术实现——用户无需知道哪个 Agent 负责什么任务，只需使用语义化的命令名。

命令别名的完整结构和详解见 第七章：命令别名完整指南。此处仅展示结构示例：

"command": {
  "/deep": {
    "description": "Route to deep-worker for heavy implementation",
    "agent": "deep-worker",
    "template": "Handle this task with thoroughness and precision."
  },
  "/review": {
    "description": "Route to reviewer for code review (local diff or PR)",
    "agent": "reviewer",
    "template": "Load the code-review skill. If a PR ref or URL is present in the arguments, also load the gh-cli skill and post findings as a pending GitHub review per its 'Reviewing PRs' section (event=COMMENT, never auto-approve). Otherwise scope the local diff and scale depth to its effective size, then review and report findings by severity. Scope-first gate: if the diff is large (>500 effective lines) or trivial, report a scoped plan and stop rather than deep-reviewing. Do not modify code."
  }
}

命令 JSON 结构：

template 中的 !…`` 是命令插值语法，在运行时会将命令输出替换到模板中。例如 /commit 命令：

!`git status --short`
!`git diff HEAD`

运行时先执行 git status --short 和 git diff HEAD，将输出插入模板，再发送给 light-orchestrator。

本配置的 17 个命令别名覆盖了以下任务域（4 大类，与 README 一致）：

命令演进：早期版本（v23）有 18 个命令，其中 /review-pr、/search、/consult 在 v38 被移除——/review-pr 合并进 /review 的 PR 模式，/search 与 /consult 因能力被现有 Agent 覆盖而删除；同时新增了 /vision（多模态）和 /learn（经验提炼）。

8.2 dcp.jsonc 完全解析

dcp.jsonc 是 DCP（Dynamic Context Pruning，动态上下文裁剪）插件的配置文件。DCP 在 OpenCode 原生压缩之上提供了一层主动、智能的上下文管理。它的核心设计理念是：在上下文还没撑满 Token 限制之前，就进行分析、去重和压缩，保持对话的精炼和高效。

版本说明：本版 dcp.jsonc 相比早期版本（v23）有重大变化——上下文阈值从 35K/75K 改为 38K/77K（绝对值），并新增了按模型成本分层的 modelMaxLimits/modelMinLimits（Pro 提前压缩，因为其输入成本是 Flash 的 3 倍）。autoUpdate 由 true 改为 false（与插件固定版本策略一致），showCompression 由 true 改为 false，protectUserMessages 由 true 改为 false。

8.2.1 基础配置

{
  "$schema": "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/master/dcp.schema.json",
  "enabled": true,
  "autoUpdate": false,
  "pruneNotification": "minimal",
  "pruneNotificationType": "toast"
}

enabled（总开关）

• 类型：boolean
• 值：true
• 作用：DCP 插件的启用/禁用总开关。设为 false 时整个插件不工作，仅依赖 OpenCode 原生压缩。在遇到 DCP 相关的兼容性问题时可以临时关闭排查。

autoUpdate（自动更新）

• 类型：boolean
• 值：false
• 作用：关闭 DCP 插件的自动更新。这与插件固定版本（@3.1.15）的策略一致——DCP 作为上下文管理的基础设施，其行为变化会影响整个会话的稳定性，因此固定版本、手动更新更可控。

pruneNotification（裁剪通知级别）

• 类型：string
• 值："minimal"
• 作用：设置压缩发生时的通知级别。"minimal" 仅显示压缩完成的摘要信息，不展开具体细节。这保持了 TUI 界面的清洁，让用户知道发生了什么但不被细节淹没。

pruneNotificationType（通知类型）

• 类型：string
• 值："toast"
• 作用：通知以 toast（浮动提示）的形式出现，不阻塞操作流程。

8.2.2 手动模式配置

"manualMode": {
  "enabled": false
}

manualMode.enabled

• 类型：boolean
• 值：false
• 作用：关闭手动模式。当设为 true 时，DCP 只有在用户手动输入 /dcp 命令时才会执行压缩。设为 false 意味着 DCP 会根据上下文阈值自动触发压缩，无需人工干预。

8.2.3 轮次保护

"turnProtection": {
  "enabled": true,
  "turns": 4
}

turnProtection.enabled

• 类型：boolean
• 值：true
• 作用：启用轮次保护——保护最近的对话轮次不被 DCP 压缩。

turnProtection.turns

• 类型：number
• 值：4

• 作用：保留最近 4 轮对话不被裁剪。最近的对话包含当前任务的状态和上下文——正在排查的 bug、刚读取的代码、待执行的下一步操作——这些信息如果被压缩成摘要，会导致 Agent “失忆”或理解偏差。

  为什么是 4 轮，而非更多或更少？

  • 少于 4 轮：可能某次工具调用的结果还在处理中就被压缩，打断 Agent 的思考链。
  • 多于 4 轮：浪费 Token 预算，因为 DCP 的存在就是为了在”够用”和”节省”之间找平衡。

  4 轮是在本配置方案的使用场景下经过经验调优的值，大致覆盖 Agent 执行一个原子操作所需的完整交互：读取 → 分析 → 修改 → 验证。

8.2.4 受保护文件模式

"protectedFilePatterns": [
  "**/opencode.jsonc",
  "**/AGENTS.md",
  "**/*.env*",
  "**/.opencode/**"
]

作用：指定不被 DCP 压缩的文件操作记录。即使包含这些文件的对话轮次属于应被裁剪的范围，它们的内容也会被保留。

注意 **/*.env* 的保护策略是”在压缩时不裁剪相关轮次”，而非”读取时拒绝”（那是 opencode.jsonc 中 permission.read 的职责）。两个层面的保护互补但不重叠。

8.2.5 压缩模式配置（compress 字段）

这是 DCP 的核心配置段，决定了何时压缩、怎么压缩、压缩力度如何。

"compress": {
  "mode": "range",
  "permission": "allow",
  "showCompression": false,
  "summaryBuffer": true,
  "maxContextLimit": 77000,
  "minContextLimit": 38000,
  "modelMaxLimits": {
    "deepseek/deepseek-v4-pro": 55000
  },
  "modelMinLimits": {
    "deepseek/deepseek-v4-pro": 26000
  },
  "nudgeFrequency": 3,
  "iterationNudgeThreshold": 12,
  "nudgeForce": "strong",
  "protectedTools": ["task", "skill", "todowrite", "todoread"],
  "protectTags": false,
  "protectUserMessages": false
}

8.2.5.1 压缩模式（mode）

• 类型：string
• 值："range"

• 含义：范围压缩模式。DCP 选择一个连续的范围（如第 5 轮到第 20 轮），将该范围压缩为一段高保真的结构化摘要。

  与”简单截断”的区别：

  • 简单截断（OpenCode 原生 prune: true）：直接丢掉最早的 N 轮对话，信息永久丢失。
  • 范围压缩（DCP mode: "range"）：将历史对话提炼为摘要——保留关键决策、代码变动、待办事项等核心信息——大幅减少 Token 的同时保留了语义。

  range 模式是 DCP 的核心优势：它不是”忘记”，而是”记住要点”。

8.2.5.2 上下文阈值

为什么是这两个值？

DeepSeek V4 的上下文窗口为 1M Token（远大于早期假设的 128K）。DCP 的阈值采用绝对值而非百分比——因为如果按百分比设置，1M 窗口的 1% 就是 10K，永远不会触发压缩。77K/38K 是经过调优的绝对值，确保 DCP 在上下文还远未到极限时就主动管理：

• 38K 温和提醒：上下文还远未到极限，但 DCP 开始”轻声提醒”模型可以考虑压缩。这相当于”黄灯”——不需要立刻行动，但要有意识。
• 77K 强力压缩：此时开始强力推动压缩，留出充足缓冲给新内容和压缩后的摘要。这相当于”红灯”——必须压缩才能继续。

这种”提前预警、梯级响应”的策略避免了两种极端：过早压缩导致信息丢失，过晚压缩导致无法继续对话。

8.2.5.3 按模型成本分层（modelMaxLimits / modelMinLimits）

"modelMaxLimits": {
  "deepseek/deepseek-v4-pro": 55000
},
"modelMinLimits": {
  "deepseek/deepseek-v4-pro": 26000
}

• 作用：为特定模型覆盖全局的 maxContextLimit/minContextLimit。这是 v38 引入的成本感知压缩——Pro 模型的输入成本是 Flash 的 3 倍，因此在更低的阈值（55K/26K）就触发压缩，避免昂贵的 Pro 上下文无限膨胀。
• 设计逻辑：Flash 会话使用全局的 77K/38K 阈值；一旦会话升级到 Pro（如 deep-worker/oracle/reviewer），DCP 会在 55K 就强力压缩、26K 就温和提醒，从而控制 Pro 的 Token 成本。

8.2.5.4 压缩提醒频率

这套 “高频、早提醒、强力推” 的参数组合是经过 Token 效率调优的结果：

• 本配置方案高度重视 Token 效率（AGENTS.md 中整个 “DeepSeek Cache & Thinking Discipline” 章节都在强调这点）。
• nudgeFrequency: 3 确保模型不会在长时间对话中”忘记”压缩这件事。
• iterationNudgeThreshold: 12 在不打断短对话的前提下，尽早启动提醒机制。
• nudgeForce: "strong" 让提醒不只是建议，而是具有强制性的引导。

8.2.5.5 受保护工具

"protectedTools": ["task", "skill", "todowrite", "todoread"]

压缩时，这些工具的输出不会被压缩，完整保留在上下文中。

8.2.5.6 其他压缩参数

summaryBuffer: true 是一个精巧的设计：压缩后的摘要是”上下文投资”——它用少量 Token 换取了更大的有效工作空间。如果不把摘要 Token 计入限制，压缩的效果会更加显著——模型有更多的空间做实际的推理和生成。

8.2.6 子代理策略

"experimental": {
  "allowSubAgents": false,
  "customPrompts": false
}

allowSubAgents（子代理压缩）

• 类型：boolean
• 值：false
• 作用：禁止 DCP 在子代理会话中运行。理由：
  • 子代理的会话通常很短（执行一个具体任务），Token 数不会超过阈值。
  • 子代理的上下文由 Orchestrator 管理，DCP 在子代理中运行是多余的。
  • 在子代理中运行 DCP 会引入不必要的延迟。

  结合 AGENTS.md 中 “Compress aggressively” 的原则——由 Orchestrator 层的 DCP 统一管理上下文，子代理不过问。

customPrompts

• 类型：boolean
• 值：false
• 作用：不使用自定义提示模板。DCP 使用内置的、经过优化的压缩提示。

8.2.7 去重策略

"strategies": {
  "deduplication": {
    "enabled": true,
    "protectedTools": ["task", "skill", "todowrite", "todoread"]
  },
  "purgeErrors": {
    "enabled": true,
    "turns": 3,
    "protectedTools": ["task", "skill", "todowrite", "todoread"]
  }
}

8.2.7.1 工具调用去重（deduplication）

• 作用：当 Agent 重复执行相同的工具调用（相同的工具名称 + 相同的参数）时，仅保留最新一次的输出，之前的结果被视为冗余。
• 实际场景：Agent 在调试循环中可能会多次读取同一个文件（read file.ts），但中间该文件并未被修改。去重策略会自动移除去重读取，节省 Token。
• Token 节省效果：在长时间的调试或探索对话中，去重可以节省 10-20% 的上下文空间。

8.2.7.2 错误输出清理（purgeErrors）

• 作用：当某个工具调用在 3 轮后仍然处于错误状态，DCP 会移除错误调用的输入体（保留错误信息本身），清理”失效”的内容。
• turns: 3：给予 3 轮的缓冲期——如果错误在 3 轮内被修复，相关的调试信息是有价值的。超过 3 轮仍未解决，说明该错误已不再处于活跃排查状态，可以清理。
• protectedTools：task、skill、todowrite、todoread 的错误输出不受此策略影响——这些工具的错误信息对于理解任务状态至关重要。

8.2.8 DCP 与 OpenCode 原生压缩的协同

这是整个上下文管理体系中最重要的架构设计点。两个压缩系统如何共处？

┌─────────────────────────────────────────────────┐
│              用户对话上下文                       │
│                                                 │
│  ┌───────────────────────────────────┐          │
│  │     DCP 主动层                     │          │
│  │  • 38K Token → 温和提醒           │          │
│  │  • 77K Token → 强力范围压缩       │          │
│  │  • Pro 模型 26K/55K 提前压缩      │          │
│  │  • 实时去重 + 错误清理             │          │
│  │  • 轮次保护（最近 4 轮）          │          │
│  └───────────────┬───────────────────┘          │
│                  │ DCP 无法完全阻止溢出           │
│                  ▼                               │
│  ┌───────────────────────────────────┐          │
│  │  OpenCode 原生兜底层              │          │
│  │  • Token 超限 → 裁剪/摘要         │          │
│  │  • prune: true（裁剪过时工具输出）│          │
│  │  • tail_turns: 8                  │          │
│  │  • preserve_recent_tokens: 12000  │          │
│  └───────────────────────────────────┘          │
│                                                 │
└─────────────────────────────────────────────────┘

协同关系：

1. 正常运行：DCP 在 38K-77K 区间运作，主动去重和压缩，保持上下文远低于限制。OpenCode 原生压缩不触发，因为 Token 从未超限。
2. 高负载会话（大量文件读写、长对话）：DCP 在 77K 触发强力压缩。如果压缩后 Token 仍在增长（例如产生了很多新的上下文），最终 OpenCode 原生压缩作为最后防线介入——此时 prune: true 直接裁剪过时的工具输出，比生成摘要更高效。
3. 设计意图：DCP 负责预防——在问题出现前解决它。OpenCode 原生压缩负责兜底——在预防失败时确保系统不会崩溃。

8.3 配置文件优先级

在 OpenCode 的多层配置体系下，不同来源的配置存在优先级关系。理解这个顺序可以避免配置冲突和”改了配置但没生效”的困惑。

8.3.1 配置加载顺序（从低到高）

1. OpenCode 内置默认值
       ↓（覆盖）
2. 全局配置文件：~/.config/opencode/opencode.jsonc
       ↓（覆盖）
3. 项目级配置文件：<项目根目录>/.opencode/opencode.jsonc
       ↓（覆盖）
4. 环境变量：DEEPSEEK_API_KEY、OPENCODE_CONFIG_DIR 等
       ↓（覆盖）
5. TUI 交互式设置：/connect、/models 等命令的选择

优先级规则：靠后的覆盖靠前的。TUI 交互式设置拥有最高优先级，因为它代表用户最近的显式操作。

8.3.2 全局 vs 项目级配置

配置 Merge 规则：

• opencode.jsonc 中的标量字段（model、subagent_depth 等）：项目级值完全替换全局值，不进行合并。
• 数组字段（plugin、instructions 等）：项目级值追加到全局值之后，形成并集。
• 对象字段（permission、compaction 等）：项目级值浅层合并到全局值之上（项目级的 key 覆盖全局同名的 key）。
• agents/ 目录下的 Agent 文件：全局和项目级的 Agent 都会加载，同名 Agent 以项目级为准。

实例如：

假设全局 opencode.jsonc 设置了 "subagent_depth": 3，某个项目的 .opencode/opencode.jsonc 设置了 "subagent_depth": 2，则该项目中的子代理最大深度为 2。

8.3.3 环境变量覆盖

以下环境变量可以覆盖配置文件中的对应设置：

8.3.4 TUI 配置优先级

TUI 中通过 /connect、/models 等交互式命令所做的选择会临时覆盖配置文件和环境变量的对应值。这些选择的持久化策略：

• /connect 的认证信息 → 写入 ~/.local/share/opencode/auth.json
• /models 的模型选择 → 仅在当前会话生效（重启后恢复配置文件设置的模型）

8.4 完整配置模板参考

以下展示两个配置文件在当前版本下的完整结构。标注中 [必需] 表示删除该字段会导致 OpenCode 启动失败或核心功能异常；[推荐] 表示本配置方案的核心设计依赖该字段；[可选] 表示可删除而不影响基本功能。

8.4.1 opencode.jsonc 完整结构

{
  // ★ 必需：JSON Schema 声明
  "$schema": "https://opencode.ai/config.json",

  // ★ 推荐：默认入口 Agent
  "default_agent": "orchestrator",

  // ★ 必需：模型选择
  "model": "deepseek/deepseek-v4-pro",           // [必需] 主模型（兜底）
  "small_model": "deepseek/deepseek-v4-flash",   // [必需] 小模型

  // ★ 推荐：基础行为
  "autoupdate": "notify",                        // [推荐] 更新通知策略
  "share": "disabled",                            // [推荐] 关闭会话分享
  "lsp": true,                                    // [可选] LSP 集成
  "formatter": true,                              // [可选] 代码格式化

  // ★ 必需：子代理深度
  "subagent_depth": 3,

  // ★ 推荐：权限配置（默认 ask + 高频操作 allow）
  "permission": {
    "read": {
      "*": "allow",
      ".env": "deny",
      "*.env": "deny",
      "*.env.*": "deny",
      ".envrc": "deny",
      "*.envrc": "deny",
      "*.env.example": "allow"
    },
    "bash": {
      "git status*": "allow",
      "git diff*": "allow",
      "git log*": "allow",
      "git show*": "allow",
      "git stash list*": "allow",
      "git add *": "allow",
      "git commit*": "allow",
      "node scripts/*": "allow",
      "npm run *": "allow",
      "npm test*": "allow",
      "rg *": "allow",
      "rm -rf*": "ask",
      "rm -fr*": "ask",
      "Remove-Item -Recurse -Force*": "ask",
      "rd /s*": "ask",
      "del /f /s*": "ask",
      "del /f /q*": "ask",
      "format *": "ask",
      "git push --force*": "ask",
      "git push -f *": "ask",
      "git push --force-with-lease*": "ask",
      "git reset --hard*": "ask",
      "git clean -fd*": "ask",
      "git checkout .*": "ask",
      "git checkout --*": "ask",
      "git branch -D*": "ask",
      "git stash clear*": "ask",
      "git stash drop*": "ask",
      "gh repo delete*": "ask",
      "gh pr close*": "ask",
      "*": "ask"                                  // [必需] catch-all 必须最后
    },
    "skill": { "*": "allow" },
    "external_directory": "ask"
  },

  // ★ 推荐：插件加载（固定版本）
  "plugin": [
    "superpowers@git+https://github.com/obra/superpowers.git#v6.3.0",
    "@tarquinen/opencode-dcp@3.1.15"
  ],

  // ★ 推荐：全局规则文件
  "instructions": ["AGENTS.md"],

  // ★ 可选：参考文档挂载
  "references": {
    "opencode-docs": {
      "repository": "anomalyco/opencode",
      "branch": "dev",
      "description": "Official opencode docs, schema, and configuration examples"
    },
    "deepseek-harness": {
      "repository": "deepseek-ai/deepseek-harness",
      "description": "Official DeepSeek model config guidance"
    }
  },

  // ★ 推荐：Provider 三模型矩阵
  "provider": {
    "deepseek": {
      "models": {
        "deepseek-v4-flash": {
          "cost": { "input": 0.22, "output": 0.66, "cache_read": 0.007, "cache_write": 0.22 },
          "options": { "temperature": 0, "thinking": { "type": "disabled" } }
        },
        "deepseek-v4-flash-vision-exp": {
          "modalities": { "input": ["text", "image"], "output": ["text"] },
          "cost": { "input": 0.22, "output": 0.66, "cache_read": 0.007, "cache_write": 0.22 },
          "options": { "temperature": 0, "thinking": { "type": "disabled" } }
        },
        "deepseek-v4-pro": {
          "cost": { "input": 0.66, "output": 1.98, "cache_read": 0.022, "cache_write": 0.66 }
        }
      }
    }
  },

  // ★ 推荐：系统 Agent 模型配置（全部 Flash）
  "agent": {
    "build": { "model": "deepseek/deepseek-v4-flash" },
    "plan": { "model": "deepseek/deepseek-v4-flash" },
    "title": { "model": "deepseek/deepseek-v4-flash" },
    "summary": { "model": "deepseek/deepseek-v4-flash" },
    "compaction": { "model": "deepseek/deepseek-v4-flash" }
  },

  // ★ 可选：工具输出限制
  "tool_output": {
    "max_lines": 800,
    "max_bytes": 20480
  },

  // ★ 推荐：上下文压缩
  "compaction": {
    "auto": true,
    "prune": true,
    "tail_turns": 8,
    "preserve_recent_tokens": 12000,
    "reserved": 10240
  },

  // ★ 可选：图像附件成本控制
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 1600,
      "max_height": 1600,
      "max_base64_bytes": 2097152
    }
  },

  // ★ 推荐：命令别名（数量较多，此处省略具体内容）
  "command": {
    "/deep": { /* ... */ },
    "/review": { /* ... */ },
    "/plan": { /* ... */ }
    // ... 共 17 个命令
  }
}

8.4.2 dcp.jsonc 完整结构

{
  // ★ 必需：Schema 声明
  "$schema": "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/master/dcp.schema.json",

  // ★ 必需：基础开关
  "enabled": true,             // [必需] DCP 总开关
  "autoUpdate": false,         // [推荐] 关闭自动更新（固定版本）

  // ★ 可选：通知设置
  "pruneNotification": "minimal",
  "pruneNotificationType": "toast",

  // ★ 推荐：手动模式（设为 false，启用自动压缩）
  "manualMode": {
    "enabled": false
  },

  // ★ 推荐：轮次保护
  "turnProtection": {
    "enabled": true,
    "turns": 4
  },

  // ★ 可选：命令设置
  "commands": {
    "enabled": true
  },

  // ★ 推荐：子代理策略
  "experimental": {
    "allowSubAgents": false,
    "customPrompts": false
  },

  // ★ 推荐：受保护文件模式
  "protectedFilePatterns": [
    "**/opencode.jsonc",
    "**/AGENTS.md",
    "**/*.env*",
    "**/.opencode/**"
  ],

  // ★ 必需：压缩核心配置
  "compress": {
    "mode": "range",                   // [必需] 范围压缩模式
    "permission": "allow",             // [必需] 允许自动压缩
    "showCompression": false,          // [可选] 不展示压缩摘要
    "summaryBuffer": true,             // [推荐] 摘要缓冲

    // ★ 必需：上下文阈值（绝对值）
    "maxContextLimit": 77000,          // [必需] 强力压缩阈值
    "minContextLimit": 38000,          // [必需] 温和提醒阈值

    // ★ 推荐：按模型成本分层
    "modelMaxLimits": {
      "deepseek/deepseek-v4-pro": 55000
    },
    "modelMinLimits": {
      "deepseek/deepseek-v4-pro": 26000
    },

    // ★ 推荐：提醒参数
    "nudgeFrequency": 3,
    "iterationNudgeThreshold": 12,
    "nudgeForce": "strong",

    // ★ 推荐：受保护工具
    "protectedTools": [
      "task", "skill", "todowrite", "todoread"
    ],

    // ★ 可选：标签和用户消息保护
    "protectTags": false,
    "protectUserMessages": false
  },

  // ★ 推荐：自动裁剪策略
  "strategies": {
    "deduplication": {
      "enabled": true,
      "protectedTools": ["task", "skill", "todowrite", "todoread"]
    },
    "purgeErrors": {
      "enabled": true,
      "turns": 3,
      "protectedTools": ["task", "skill", "todowrite", "todoread"]
    }
  }
}

8.5 配置安全最佳实践

配置安全是整个多 Agent 系统的基石。一个错误的安全配置可能导致数据丢失、密钥泄露或远程仓库被破坏。以下是最佳实践检查清单：

8.5.1 密钥安全

8.5.2 命令执行安全

8.5.3 会话安全

8.5.4 定期审查

8.5.5 应急响应

如果怀疑 Agent 执行了不当操作：

1. 立即回滚：使用 /undo 回滚到上一个 Git 快照。
2. 检查变更：git diff HEAD~1 查看最近一次快照的改动内容。
3. 审查日志：检查 DCP 的压缩日志分析 Agent 的操作链。
4. 收紧权限：必要时将相关命令临时改为 deny。
5. 撤销密钥：如果怀疑密钥泄露，立即在 DeepSeek 控制台删除并重建 API Key。

下一章：第九章：全局规则 AGENTS.md 深度解读 —— 逐段解析管理所有 Agent 行为规范的”宪法文件”AGENTS.md，包括核心原则、代码风格要求、Token 效率策略、反模式禁令等。