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

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

本章分析的配置文件版本对应 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",
  "enabled_providers": ["deepseek"],
  "disabled_providers": ["openai", "anthropic", "google", "openrouter"]
}

model（主模型）

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

small_model（小模型）

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

enabled_providers（启用的 Provider 白名单）

• 类型：string[]
• 值：["deepseek"]
• 作用：明确指定允许使用的 Provider 列表。这里只保留了 deepseek，是”深度锁定”策略的正面限制——只允许使用 DeepSeek 的模型，任何其他 Provider 都不会被加载。

disabled_providers（禁用的 Provider 黑名单）

• 类型：string[]
• 值：["openai", "anthropic", "google", "openrouter"]
• 作用：显式禁用常见的其他 Provider。与 enabled_providers 形成 “双重锁”机制：
  • 第一层（白名单）：只 enabled DeepSeek，其余 Provider 不会被激活。
  • 第二层（黑名单）：即使有用户误操作、OpenCode 默认行为变更、或某些 Provider 被自动发现，disabled_providers 也会阻止它们被加载。

  这种双重锁设计确保了模型隔离的防御深度——不是依赖单点约束，而是通过正反两个方向同时加固。

8.1.2 Provider 配置

Provider 决定了 OpenCode 如何与模型服务商对接。本配置方案中，DeepSeek 是唯一的 Provider，但其配置并非在 opencode.jsonc 中完整展开（OpenCode 内置了 DeepSeek 的 Provider 定义），而是通过 enabled_providers 启用。如果需要自定义模型参数（例如开启 thinking/reasoning 模式），可以在顶层追加 provider 字段：

"provider": {
  "deepseek": {
    "models": {
      "deepseek-v4-pro": {
        "options": {
          "thinking": { "type": "enabled" }
        }
      }
    }
  }
}

Provider 对象结构说明：

thinking/reasoning 模式：

DeepSeek V4 Pro 支持 thinking（深度推理）模式。当 thinking.type 设为 "enabled" 时，模型会在生成回答前先进行内部推理链，对需要多步推理的复杂任务（如根因分析、架构设计）有显著提升效果。该模式会增加 Token 消耗，因此本配置默认不开启，而是通过 Agent 级别的配置按需开启。

如需进一步了解双模型分工和 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，系统自动完成意图识别与任务分发。

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-pro",
      "mode": "subagent"
    },
    "plan": { "model": "deepseek/deepseek-v4-pro" },
    "title": {
      "model": "deepseek/deepseek-v4-flash",
      "fallback": "deepseek/deepseek-v4-pro"
    },
    "summary": {
      "model": "deepseek/deepseek-v4-flash",
      "fallback": "deepseek/deepseek-v4-pro"
    },
    "compaction": {
      "model": "deepseek/deepseek-v4-flash",
      "fallback": "deepseek/deepseek-v4-pro"
    }
  }
}

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 处理的是框架层面的通用任务：

注意 title、summary、compaction 三个 Agent 都配置了 fallback 字段：当 Flash 模型不可用或执行失败时，自动回退到 Pro 模型。这种”先尝试低成本方案，失败再升级”的策略遵循了模型分级使用的核心原则。

Agent 自动注册机制：

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

agents/orchestrator.md  → Agent "orchestrator"
agents/deep-worker.md   → Agent "deep-worker"
agents/oracle.md        → Agent "oracle"

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

8.1.5 插件配置

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

plugin（插件列表）

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

superpowers 插件：

• 来源：superpowers@git+https://github.com/obra/superpowers.git

• 功能：提供 12 个过程型技能（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	编写新技能	创建或编辑技能定义时

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

DCP 插件：

• 来源：@tarquinen/opencode-dcp@latest
• 功能：Dynamic Context Pruning（动态上下文裁剪），负责智能管理对话上下文的大小，在 Token 消耗和上下文质量之间取得最优平衡。它是 OpenCode 原生压缩的主动增强层。
• 版本控制：@latest 表示始终使用最新版本。DCP 作为上下文管理的基础设施，保持最新可以及时获得策略优化和 bug 修复。

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"
    }
  }
}

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 理解何时该查阅此引用源

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

8.1.7 压缩配置

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

auto（自动压缩）

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

prune（裁剪模式）

• 类型：boolean
• 值：false
• 作用：禁用纯裁剪模式。false 意味着压缩是”摘要化”而非”直接丢弃”——早期对话会被压缩为精炼的摘要，保留关键信息而不是完全删除。这是更安全的压缩策略，因为人工智能摘要能保留上下文逻辑链。

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.4 节。

8.1.8 会话与快照配置

{
  "share": "disabled",
  "snapshot": true
}

share（会话分享）

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

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

snapshot（Git 快照）

• 类型：boolean
• 值：true
• 作用：开启 Git 快照功能。每次 Agent 修改文件后，OpenCode 自动创建一个 Git 提交快照。这带来的好处：
  • 可回滚：如果 Agent 的修改出现问题，可以通过 /undo 回滚到上一个快照。
  • 变更追溯：每次修改都有明确的历史记录，审查者可以清楚看到 AI 做了什么改动。
  • 安全网：即使 Agent 误删了重要代码，也能通过快照恢复。

  前提：项目必须在 Git 仓库中（git init 初始化后），快照功能才能生效。这也是为什么 第二章 强调 Git 是前置依赖。

8.1.9 权限配置详解

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

"permission": {
  "read": {
    "*": "allow",
    "*.env": "deny",
    "*.env.*": "deny",
    "*.env.example": "allow"
  },
  "bash": {
    "*": "allow",
    "rm -rf*": "ask",
    "rm -fr*": "ask",
    "rm -rf *": "ask",
    "rm -fr *": "ask",
    "Remove-Item -Recurse -Force*": "ask",
    "rd /s /q*": "ask",
    "rd /s*": "ask",
    "del /f /s*": "ask",
    "del /f /q*": "ask",
    "format *": "ask",
    "git push --force*": "ask",
    "git push -f *": "ask",
    "git reset --hard*": "ask",
    "git branch -D*": "ask",
    "git stash clear*": "ask",
    "git stash drop*": "ask",
    "gh repo delete*": "ask",
    "gh pr close*": "ask"
  },
  "skill": {
    "*": "allow"
  },
  "external_directory": "ask"
}

8.1.9.1 读取权限（read）

设计逻辑：

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

权限生效顺序：OpenCode 采用”最早匹配”策略。当 Agent 尝试读取 app/.env 时，系统按顺序匹配：

• * 匹配（allow）→ 继续检查下一条
• *.env 匹配（deny）→ 拒绝，停止匹配

因此更具体的规则后写才能覆盖通用规则。编写规则时需确保 deny 规则列在 allow 规则之后。

8.1.9.2 Bash 执行权限（bash）

Bash 权限按”默认开放 + 破坏性操作确认”的策略设置：

为什么默认 allow 而非 ask：

如果所有命令都需要确认，Agent 的每个操作都会被打断，严重降低效率。绝大多数命令（git status、npm test、cargo build）是安全且必需的。采用”默认允许 + 破坏性命令单独确认”的策略，在安全和效率之间取得了平衡。

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

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

跨平台命令覆盖：

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

rm -rf* 和 rm -rf * 两条规则是为了处理星号前后的空格变化，防止恶意构造绕过。

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": 2000,
  "max_bytes": 51200
}

max_lines（最大输出行数）

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

max_bytes（最大输出字节数）

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

8.1.11 实验功能

"experimental": {
  "batch_tool": true
}

batch_tool（批量工具调用）

• 类型：boolean
• 值：true

• 作用：启用批量工具调用。当 Agent 需要同时执行多个独立的工具调用（如并行读取 3 个不同的文件）时，可以一次性发出批量请求，而非逐个串行等待。这显著减少了等待时间和 Token 消耗。

  以代码探索为例：

  • 未启用：读取 fileA.ts → 等待返回 → 读取 fileB.ts → 等待返回 → 读取 fileC.ts
  • 启用后：一次性发出读取 fileA.ts、fileB.ts、fileC.ts 的批量请求，三个结果同时返回

  batch_tool 是 AGENTS.md 中 “Run independent work in parallel” 原则的技术基础。没有这个功能，Agent 即使被指示并行操作，也无法在单次工具调用中完成。

"$schema": "https://opencode.ai/config.json" 是 JSON Schema 声明，为支持 JSONC 的编辑器提供智能补全和验证，本身不影响运行时行为。

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

commands 字段定义了 23 个自定义命令别名，每个命令将用户输入映射到特定的 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",
    "agent": "reviewer",
    "template": "Load the code-review skill. ..."
  }
}

命令 JSON 结构：

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

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

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

本配置的 23 个命令别名覆盖了以下任务域：

8.2 dcp.jsonc 完全解析

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

8.2.1 基础配置

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

enabled（总开关）

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

autoUpdate（自动更新）

• 类型：boolean
• 值：true
• 作用：允许 DCP 插件自动检查并更新到最新版本。DCP 的策略算法持续优化，保持自动更新可以及时获得改进。

debug（调试模式）

• 类型：boolean
• 值：false
• 作用：关闭调试日志输出。在正常使用时不需要调试信息，设为 false 避免噪音。

pruneNotification（裁剪通知级别）

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

pruneNotificationType（通知类型）

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

8.2.2 手动模式配置

"manualMode": {
  "enabled": false,
  "automaticStrategies": true
}

manualMode.enabled

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

manualMode.automaticStrategies

• 类型：boolean
• 值：true
• 作用：允许自动应用裁剪策略（去重、错误输出清理等）。即使压缩本身是被动的，这些轻量级策略仍然可以在后台自动运行。

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.json",
  "**/AGENTS.md",
  "**/*.env*",
  "**/.opencode/**"
]

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

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

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

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

"compress": {
  "mode": "range",
  "permission": "allow",
  "showCompression": true,
  "summaryBuffer": true,
  "maxContextLimit": 75000,
  "minContextLimit": 35000,
  "nudgeFrequency": 3,
  "iterationNudgeThreshold": 12,
  "nudgeForce": "strong",
  "protectedTools": ["task", "skill", "todowrite", "todoread"],
  "protectTags": false,
  "protectUserMessages": true
}

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 的上下文窗口为 128K Token。DCP 的设计不是等窗口快满了才救火，而是提前预警：

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

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

8.2.5.3 压缩提醒频率

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

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

8.2.5.4 受保护工具

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

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

8.2.5.5 用户消息保护

"protectUserMessages": true

• 作用：保护用户消息不被压缩。用户的原始请求是最重要的上下文锚点——如果用户的原始意图被压缩成摘要，Agent 可能在后续操作中偏离目标。true 确保用户说的每一句话都在上下文中原样保留。

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 主动层                     │          │
│  │  • 35K Token → 温和提醒           │          │
│  │  • 75K Token → 强力范围压缩       │          │
│  │  • 实时去重 + 错误清理             │          │
│  │  • 轮次保护（最近 4 轮）          │          │
│  └───────────────┬───────────────────┘          │
│                  │ DCP 无法完全阻止溢出           │
│                  ▼                               │
│  ┌───────────────────────────────────┐          │
│  │  OpenCode 原生兜底层              │          │
│  │  • Token 超限 → 摘要压缩          │          │
│  │  • tail_turns: 8                  │          │
│  │  • preserve_recent_tokens: 12000  │          │
│  └───────────────────────────────────┘          │
│                                                 │
└─────────────────────────────────────────────────┘

协同关系：

1. 正常运行：DCP 在 35K-75K 区间运作，主动去重和压缩，保持上下文远低于限制。OpenCode 原生压缩不触发，因为 Token 从未超限。
2. 高负载会话（大量文件读写、长对话）：DCP 在 75K 触发强力压缩。如果压缩后 Token 仍在增长（例如产生了很多新的上下文），最终 OpenCode 原生压缩作为最后防线介入。
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、disabled_providers 等）：项目级值追加到全局值之后，形成并集。
• 对象字段（permission、compaction 等）：项目级值浅层合并到全局值之上（项目级的 key 覆盖全局同名的 key）。
• agents/ 目录下的 Agent 文件：全局和项目级的 Agent 都会加载，同名 Agent 以项目级为准。

实例如：

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

再如，全局 disabled_providers 设为 ["openai"]，项目级追加 ["anthropic"]，最终生效的禁用列表为 ["openai", "anthropic"]。

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",   // [必需] 小模型
  "enabled_providers": ["deepseek"],             // [必需] Provider 白名单
  "disabled_providers": [                        // [推荐] Provider 黑名单
    "openai", "anthropic", "google", "openrouter"
  ],

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

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

  // ★ 推荐：权限配置（默认值全 allow，需根据安全需求调整）
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    "bash": {
      "*": "allow",
      "rm -rf*": "ask",
      "rm -fr*": "ask",
      // ... 其他破坏性命令
      "git push --force*": "ask",
      "git reset --hard*": "ask"
    },
    "skill": { "*": "allow" },
    "external_directory": "ask"
  },

  // ★ 推荐：插件加载
  "plugin": [
    "superpowers@git+https://github.com/obra/superpowers.git",
    "@tarquinen/opencode-dcp@latest"
  ],

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

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

  // ★ 推荐：实验功能
  "experimental": {
    "batch_tool": true
  },

  // ★ 推荐：系统 Agent 模型配置
  "agent": {
    "build": {
      "model": "deepseek/deepseek-v4-pro",
      "mode": "subagent"
    },
    "plan": { "model": "deepseek/deepseek-v4-pro" },
    "title": {
      "model": "deepseek/deepseek-v4-flash",
      "fallback": "deepseek/deepseek-v4-pro"
    },
    "summary": {
      "model": "deepseek/deepseek-v4-flash",
      "fallback": "deepseek/deepseek-v4-pro"
    },
    "compaction": {
      "model": "deepseek/deepseek-v4-flash",
      "fallback": "deepseek/deepseek-v4-pro"
    }
  },

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

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

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

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": true,          // [推荐] 自动更新
  "debug": false,              // [可选] 调试模式

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

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

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

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

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

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

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

    // ★ 必需：上下文阈值
    "maxContextLimit": 75000,          // [必需] 强力压缩阈值
    "minContextLimit": 35000,          // [必需] 温和提醒阈值

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

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

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

  // ★ 推荐：自动裁剪策略
  "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 的压缩日志（如开启 debug: true）分析 Agent 的操作链。
4. 收紧权限：必要时将相关命令临时改为 deny。
5. 撤销密钥：如果怀疑密钥泄露，立即在 DeepSeek 控制台删除并重建 API Key。

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