第十二章：最佳实践与定制指南

阅读目标：本章是整套教程的收尾之作，汇聚了从实际使用中提炼的 Token 效率技巧、团队协作模式、定制化方法、成本优化策略、常见问题解答和故障排查指南。无论你是个人开发者还是团队管理者，读完本章后都将掌握将 my-opencode-deepseek-config 适配到自己场景的完整方法论。

12.1 Token 效率最佳实践

Token 是 AI 编程助手的”燃料”，也是成本的核心变量。这套配置从设计第一天起就贯彻 Token 效率优先 的理念，以下是在日常使用中最大化 Token 效率的具体操作建议。

12.1.1 用命令别名替代自然语言路由

这是最能立竿见影的优化。当你输入自然语言描述任务意图时，Orchestrator 需要调用 Flash 模型进行一次完整的意图门控推理，根据 7 类任务分类规则决定路由。这一轮”理解意图”本身就要消耗 Token。

而使用命令别名（如 /review、/commit）时，路由是确定性的——直接跳转到目标 Agent，跳过 Orchestrator 的推理步骤。

方式	Token 开销	延迟	路由准确性
自然语言路由	高（Orchestrator 推理 + Agent 执行）	高	取决于描述质量
命令别名路由	低（直接启动 Agent）	低	100% 确定

实践建议：把常用命令别名的肌肉记忆建立起来。日常 80% 的任务都可以用命令别名覆盖：

/review — 代码审查
/commit — 规范化提交
/reflect — 配置优化回顾
/handoff — 会话交接
/rmslop — 清理死代码
/simplify — 代码简化
/codemap — 生成仓库结构图

12.1.2 长会话定期用 `/handoff` 压缩交接

OpenCode 会话的上下文会随着交互累积而线性增长。一次 2 小时的长会话可能积累 80K-120K Token 的上下文窗口——其中大量是已经被解决的历史对话，对当前任务毫无帮助。

操作建议：

每完成一个独立的子任务后，运行 /handoff 生成交接文档
交接文档是一个紧凑的结构化摘要（通常 < 2K Token），保留了关键决策、当前进度和未完成事项
新会话从交接文档恢复上下文，上下文窗口从零开始

实际效果：假设一个 100K Token 的会话被压缩为 2K Token 的交接文档，新会话直接节省 98K Token。如果当天有 3 次这样的压缩，节省的 Token 足以完成 5-8 个额外的中型任务。

12.1.3 Flash 优先策略

DeepSeek V4 Flash 模型的价格约为 Pro 的 1/4 到 1/2，Token 消耗更少。日常使用中应遵循以下优先级：

Flash 适合（优先使用）：

代码库搜索与探索（grep、glob 类操作）
单文件简单编辑（修改变量名、调整格式）
文档查阅和问答
简单的 Git 操作
交接文档生成

Pro 适合（保留给复杂任务）：

多文件架构重构
根因分析（/oracle）
代码审查（/review）
复杂功能的规划与设计
Orchestrator 的调度决策

实践技巧：当你用自然语言描述一个任务时，如果它明显是”查询/搜索/简单修改”类，可以在描述末尾加一句”用 Flash 处理”，帮助 Orchestrator 正确路由。例如：

帮我在项目中找到所有使用 deprecated_api 的地方并替换为 new_api，用 Flash 处理。

12.1.4 善用 codemap 技能避免重复探索

在不熟悉的项目中，Agent 往往会反复执行 glob 和 grep 来探索项目结构，每次探索都消耗 Token。codemap 技能在首次激活时生成项目的结构化地图，之后 Agent 可以直接查询地图而非重新探索。

使用方式：在新项目或新目录中，首先执行：

请用 codemap 生成当前项目的结构地图

之后 Agent 的路由和探索会基于这份缓存的地图，避免重复扫描。

12.1.5 及时清理死代码

死代码（未使用的函数、变量、导入、文件）不仅让代码库膨胀，还会在 Agent 探索和审查时消耗额外的 Token——Agent 会阅读、分析这些无效代码。使用 /rmslop 命令定期清理：

每完成一个功能模块后运行一次
合并 PR 前作为最后一步
每周或每个迭代结束时作为例行维护

12.1.6 写代码前规划验证路径

AGENTS.md 要求”计划验证再实现”——这不仅仅是一个纪律要求，也是 Token 效率的优化。没有验证规划时，常见的情况是：

写完代码后发现没有写测试
补写测试后发现逻辑有误
回退修改，重新实现
每个回退循环消耗大量 Token

而预先规划验证路径后，实现是一次到位的。AGENTS.md 的 Self-Verification 与 Quality Bar 规则要求实现前先规划最窄的验证路径——在动手前明确：

修改后将影响哪些调用者
需要运行哪些测试
需要检查哪些边界条件
验证通过的客观标准是什么

版本说明：早期版本曾用独立的 verification-planning 技能承载这一职责，v38 起已将其吸收进 AGENTS.md 的 Self-Verification 规则与 spec-workflow 的 Propose 阶段，不再需要单独加载技能。

12.1.7 Token 效率检查清单

每次开始新任务前，快速过一遍这个清单：

这个任务能否用命令别名直接路由？（省去 Orchestrator 推理）
当前会话是否已超过 30 分钟？是否需要 /handoff？
这个任务是 Flash 级别还是 Pro 级别？
项目结构已经探索过吗？是否可以用 codemap 缓存？
有没有已知的死代码可以先用 /rmslop 清理？
验证路径规划好了吗？

12.2 团队协作最佳实践

这套配置天然支持团队协作——所有配置都是 Git 管理的纯文本文件，Fork→定制→共享的流程与日常开发工作流完全一致。

12.2.1 Fork 后定制团队版本

推荐的团队接入流程：

团队负责人 Fork znlgis/my-opencode-deepseek-config
在 Fork 的仓库中修改 AGENTS.md，添加团队特定规则
根据需要调整 Agent prompt（如添加领域知识）
团队成员 git clone Fork 仓库到 ~/.config/opencode
团队成员配置各自的 DeepSeek API Key
后续通过 PR 持续同步上游更新

关键原则：上游仓库保持通用性，团队 Fork 负责定制。不要在 Fork 中修改与团队无关的通用配置——这些应该通过 PR 贡献回上游。

12.2.2 在团队 AGENTS.md 中添加团队特定规则

AGENTS.md 的全局规则对所有 Agent 生效。团队可以在 Fork 版本中添加自身约定，例如：

## 团队特定规则（仅在 acme-corp 团队生效）

- 所有 API 路由必须注册在 `src/routes/` 目录下，遵循 RESTful 命名
- 数据库迁移文件按 `YYYYMMDDHHMMSS_description.sql` 格式命名
- 日志级别：开发环境 DEBUG，生产环境 INFO
- PR 标题必须包含 Jira issue key（如 `[PROJ-123]`）
- 禁止直接使用 `console.log`，统一使用 `logger` 模块

这些规则会被注入到每个 Agent 的上下文中，确保所有 AI 辅助生成的代码自动符合团队规范。

12.2.3 使用 Git 管理配置版本

配置即代码，版本管理是其中的基础设施：

语义化提交：用 /commit 命令确保所有配置变更都有规范的 commit message
分支策略：重大配置变更在单独分支上测试，确认无问题后合并
回滚机制：配置问题导致 Agent 行为异常时，git revert 即刻恢复
变更日志：利用 Conventional Commits 格式自动生成 CHANGELOG

12.2.4 定期运行 `/reflect` 发现工作流摩擦

/reflect 是这套方案最被低估的命令之一。它会回顾近期的交互记录，识别出反复出现的摩擦点，然后建议对配置进行优化。

推荐的团队节奏：

每周：个人运行 /reflect，优化个人使用体验
每两周：团队集中讨论 /reflect 发现的问题，决定是否调整团队共享配置
每月：汇总团队级的配置优化，合并到 Fork 仓库，全员同步

真实案例：某个团队发现 Agent 生成的错误处理代码总是使用 try/catch 包裹整个函数，与团队惯用的 early-return + 显式错误模式不符。通过 /reflect 发现这个模式后，在 AGENTS.md 中添加了”避免 try/catch 包裹整个函数体”的规则，之后生成的代码立即符合团队风格。

12.2.5 用 `/commit` 统一提交信息格式

团队中每个人手写 commit message 的格式往往不一致。/commit 命令自动分析变更内容并生成符合 Conventional Commits 规范的提交信息：

feat(agent): add database-expert agent for SQL review tasks
fix(skill): correct code-review severity threshold for minor issues
docs(guide): update installation steps for Windows users

统一的提交格式带来的好处远超表面：自动生成 CHANGELOG、按类型过滤提交历史、量化各类变更的比例。

12.2.6 `/review` 作为团队代码审查标准

将 /review 设为团队的代码审查前置步骤。/review 在 v38 起合并了 PR 审查与本地 diff 审查两种模式：

开发者完成功能后，先本地运行 /review（本地 diff 模式），修复发现的所有 Critical/Major 级别问题
创建 PR 后，运行 /review <PR 引用>（PR 模式），reviewer 会加载 gh-cli 技能并把审查结果作为 GitHub Review 回帖（event=COMMENT，绝不自动 approve）
人工 Reviewer 聚焦于架构和业务逻辑——语法和反模式问题已被 AI 处理

版本说明：早期版本用独立的 /review-pr 命令承载 PR 审查，v38 起已合并进 /review——传入 PR 引用即进入 PR 模式自动回帖，否则审查本地 diff。

这减少了人工 Reviewer 在低价值问题上的时间消耗，让 Code Review 回归到它本来的目的：知识共享和架构把关。

12.2.7 团队的”新手保护”策略

对于刚接触这套配置的团队成员：

第一周：只使用命令别名（/review、/commit），不碰自然语言路由
第二周：尝试自然语言描述简单任务，观察 Orchestrator 的路由决策
第三周：阅读 AGENTS.md 全文，理解规则背后的逻辑
第四周：尝试修改个人 Fork 中的 Agent prompt 或 Skill

循序渐进的方式避免了”配置太多不知道从哪开始”的困境。

12.3 定制化指南

本节是动手操作的实用手册，覆盖添加自定义 Agent、Skill、命令、修改 AGENTS.md 和调整权限配置的完整步骤。

12.3.1 添加自定义 Agent

目录位置

所有 Agent 定义存放在 ~/.config/opencode/agents/ 目录下，文件名格式为 <agent-name>.md。

创建步骤

第 1 步：确定 Agent 的角色和职责

在动手写 prompt 之前，先回答三个问题：

这个 Agent 负责什么类型的任务？（单一职责）
它需要 Pro 还是 Flash 模型？（推理密集型用 Pro，查询执行型用 Flash）
它是否允许修改文件？（读写 vs 只读）

第 2 步：在 agents/ 目录下创建 .md 文件

例如创建一个数据库专家 Agent：agents/database-expert.md

第 3 步：编写 Agent prompt

Agent prompt 应包含以下核心要素：

# Database Expert

You are a database specialist agent. You handle SQL query optimization,
schema design, migration generation, and database-related code review.

## Role Boundaries
- You MAY read and modify database-related files (SQL, migrations, ORM models)
- You MUST NOT modify application logic outside the data layer
- If asked to do non-database work, reject with a clear reason

## Model
- Use deepseek/deepseek-v4-pro for complex optimization and schema design
- Use deepseek/deepseek-v4-flash for simple query formatting

## Capabilities
- Analyze EXPLAIN plans and suggest index improvements
- Generate safe, reversible migration scripts
- Review ORM usage patterns for N+1 queries
- Suggest connection pool and caching strategies

## Constraints
- Never generate a migration that drops a column without explicit confirmation
- Always include ROLLBACK instructions for every migration
- Prefer parameterized queries over string concatenation

第 4 步：在 .md 文件 frontmatter 中声明模型与权限

Agent 通过 .md 文件的 YAML frontmatter 声明元数据，无需在 opencode.jsonc 中注册。frontmatter 支持 mode（primary/subagent）、model、steps、color、permission 等字段：

---
mode: subagent
model: deepseek/deepseek-v4-pro
steps: 60
color: "#2ECC71"
permission:
  task: "*": deny
  bash:
    "git status*": allow
    "git diff*": allow
    "rg *": allow
    "*": deny
---

版本说明：早期版本在 opencode.jsonc 的 agents 字段中用 name/model/prompt/permissions.files 结构注册 Agent，v20 起改为 agents/<name>.md 文件 + frontmatter 声明，v38 的权限模型也从 files.allow/ask/deny 数组演进为 permission.read/bash/skill 对象形式（bash 采用 allow-list + ask-list + 兜底 *: ask 的 last-match-wins 结构）。

第 5 步：添加路由规则（可选）

如果希望 Orchestrator 自动识别数据库相关任务并路由到此 Agent，需要在 agents/orchestrator.md 的路由规则中添加对应的任务分类。

Agent 权限模式对比

权限级别	适用场景	实现方式
读写（Read-Write）	实现类 Agent（deep-worker, light-orchestrator）	`permission.task` 允许 + bash allow-list 放行常用命令
只读（Read-Only）	探索/分析类 Agent（oracle, reviewer, explore, librarian, vision）	`permission.task: "": deny` + bash allow-list 仅放行 `git status/diff/log/show`、`rg`、`Get-ChildItem`、`Get-Content`，其余 `: deny`
受限（Restricted）	审查类 Agent（reviewer）	只读 + 通过 bash 兜底 `*: deny` 禁止写操作

模型选择指南

模型	适用 Agent 类型	思考状态	成本级别
`deepseek/deepseek-v4-pro`	solo（主）、deep-worker、oracle、reviewer	默认开启（深度推理）	较高（输入 $0.66/1M）
`deepseek/deepseek-v4-flash`	orchestrator（主）、planner、light-orchestrator、consultant、ui-builder、explore、librarian	关闭（temperature 0）	较低（输入 $0.22/1M，约 1/3）
`deepseek/deepseek-v4-flash-vision-exp`	vision	关闭（temperature 0）	同 Flash

经验法则：如果 Agent 的核心工作是”理解和分析”（推理），用 Pro；如果核心工作是”查找和执行”（检索），用 Flash。中档任务（planner、light-orchestrator）用 Flash + reasoningEffort: low 在成本与深度间取得平衡。

12.3.2 添加自定义技能

目录位置

技能文件存放在 ~/.config/opencode/skills/<skill-name>/SKILL.md。

技能的结构规范

每个技能文件应遵循以下结构：

# Skill Name

[1-2 句描述技能用途和触发场景]

## When to Use
- 明确列出触发条件
- 用户说了什么关键词时激活
- 什么场景下应该加载此技能

## Workflow
### Step 1: [阶段名称]
[具体操作指导]

### Step 2: [阶段名称]
[具体操作指导]

## Rules
- 技能执行期间必须遵守的规则
- 输出格式要求
- 边界条件处理

## Examples
### Example 1: [场景]
[输入/输出的具体示例]

完整示例：API 文档生成技能

创建 skills/api-doc-gen/SKILL.md：

# API Doc Gen

Generate OpenAPI 3.0 documentation from backend route handlers.
Use when the user mentions "API 文档", "生成文档", "Swagger", "OpenAPI",
or asks to document API endpoints.

## When to Use
- User says: "生成 API 文档", "写接口文档", "document this API"
- User asks to create OpenAPI/Swagger specs
- Codebase has route handlers without documentation

## Workflow
### Step 1: Route Discovery
Scan the project for route definitions. Common patterns:
- Express: `app.get/post/put/delete()`
- FastAPI: `@app.get/post()`
- Spring: `@GetMapping/@PostMapping`
- Next.js: files under `app/api/` or `pages/api/`

### Step 2: Schema Extraction
For each route found:
1. Identify request parameters (path, query, body)
2. Extract validation rules (required, type, min/max)
3. Identify response types from return statements or TypeScript types
4. Note authentication requirements (middleware, decorators)

### Step 3: OpenAPI Generation
Generate an OpenAPI 3.0 YAML document with:
- `info` section (title, version, description)
- `paths` section (one entry per route)
- `components/schemas` section (reusable type definitions)
- `components/securitySchemes` (if auth detected)

### Step 4: Output
Write the result to `docs/openapi.yaml`. If the file exists, merge new routes
into the existing document instead of overwriting.

## Rules
- Use OpenAPI 3.0.x format, not 3.1 (wider tool compatibility)
- Group routes by tag based on their URL prefix
- Include `summary` and `description` for every endpoint
- Mark deprecated endpoints with `deprecated: true`
- If a route's behavior is ambiguous, add a `# TODO: verify` comment

触发条件和加载时机

技能的加载时机由两方面决定：

OpenCode 框架层：框架根据当前任务与技能描述的语义匹配度决定是否推荐加载
Orchestrator 路由层：Orchestrator 在意图门控阶段检查是否有匹配的技能，如果有则调用 skill 工具加载

你不需要显式注册技能——只要 SKILL.md 放在正确的目录下，OpenCode 会自动发现。

技能开发的注意事项

保持单一职责：一个技能只做一件事。API 文档生成和数据库迁移生成应分成两个技能
提供足够的上下文：技能 prompt 要足够详细，让 Agent 不需要额外探索就能执行
包含边界条件处理：告诉 Agent 遇到什么情况应该停止、询问还是跳过
避免与已有技能重叠：先检查 skills/ 目录，确认没有功能重复的技能

12.3.3 添加自定义命令

配置文件位置

命令定义在 opencode.jsonc 的 commands 字段中。

命令结构

每个命令条目包含以下字段：

{
  "commands": {
    "命令名称": {
      "description": "命令的简短描述（显示在帮助信息中）",
      "agent": "目标 Agent 名称",
      "template": "注入给 Agent 的具体指令模板。可包含 Load the xxx skill 来自动加载技能，可使用 !git status 等形式嵌入实时 shell 输出"
    }
  }
}

命令的 template 设计

template 是命令的核心——它定义了 Agent 收到命令后的行为指令。技能加载通过 template 中的 Load the xxx skill 语句触发，而非单独的 skill 字段：

"/review": {
  "agent": "reviewer",
  "template": "Load the code-review skill. Scope the diff, scale depth to its size, review the dimensions it touches, and report findings by severity."
}

设计要点	说明
`agent`	必填，指定命令路由的目标 Agent
`template`	必填，Agent 收到的完整指令，可内联 `!` shell 命令嵌入实时数据
技能加载	在 template 中用 `Load the xxx skill` 触发，无需单独 `skill` 字段
shell 嵌入	`!git status --short` 等形式在命令执行时替换为 shell 输出

命名规范

使用小写字母和连字符：/my-command，不是 /MyCommand 或 /my_command
名称应直观反映功能：/gen-docs 好于 /cmd3
避免与 OpenCode 内置命令冲突（如 /help、/exit、/undo）
团队自定义命令建议加前缀：/team-lint、/team-deploy-check

完整示例

{
  "commands": {
    "gen-docs": {
      "description": "Generate OpenAPI documentation from route handlers",
      "agent": "deep-worker",
      "template": "Scan the project for API route handlers and generate OpenAPI 3.0 documentation. Output to docs/openapi.yaml. For each endpoint, include request/response schemas, auth requirements, and error codes."
    },
    "db-migrate": {
      "description": "Generate a database migration script",
      "agent": "database-expert",
      "template": "Analyze the changes in ORM models and generate a safe, reversible migration script. Include UP and DOWN sections. Never generate destructive operations (DROP COLUMN, DROP TABLE) without explicit confirmation."
    }
  }
}

12.3.4 修改 AGENTS.md

AGENTS.md 是所有 Agent 共享的全局规则文件，位于 ~/.config/opencode/AGENTS.md。

添加项目特定规则

在 AGENTS.md 的适当位置添加规则块，遵循现有格式：

## 项目特定规则：my-project

### 目录结构约定
- 所有页面组件放在 `src/pages/`，按路由路径建子目录
- 共享组件放在 `src/components/shared/`
- API 调用封装在 `src/services/`，禁止在组件中直接调用 fetch/axios

### 命名约定
- React 组件文件使用 PascalCase：`UserProfile.tsx`
- 工具函数文件使用 camelCase：`formatDate.ts`
- 类型定义文件使用 PascalCase + `.types.ts` 后缀：`User.types.ts`

### 状态管理
- 全局状态使用 Zustand store，文件放在 `src/stores/`
- 组件本地状态使用 `useState` 或 `useReducer`
- 禁止混合使用 Redux 和 Zustand —— 本项目只用 Zustand

调整代码风格约束

AGENTS.md 中原有的反模式清单和质量基准是通用规则，你可以根据团队偏好调整：

## 团队代码风格偏好（覆盖通用规则）

### 允许的模式
- `try/catch` 允许用于异步操作的错误处理，但必须记录日志
- `else` 允许在需要互斥分支的场景使用
- `for...of` 循环允许用于需要 `await` 的异步迭代

### 禁止的模式
- 禁止使用 `any` 类型（TypeScript 项目）
- 禁止在 React 组件中定义超过 3 层的嵌套三元表达式
- 禁止使用 `var` 声明变量

添加团队约定

## 团队约定

### 提交前检查清单
- [ ] 所有测试通过（`npm test`）
- [ ] 无 TypeScript 错误（`npx tsc --noEmit`）
- [ ] Lint 无警告（`npm run lint`）
- [ ] 无遗漏的 console.log
- [ ] PR 描述包含变更原因和测试说明

### 分支命名规则
- `feat/description` — 新功能
- `fix/description` — Bug 修复
- `refactor/description` — 重构
- `docs/description` — 文档

12.3.5 调整权限配置

权限配置位于 opencode.jsonc，控制 Agent 对文件系统和命令行的访问权限。

权限模式说明

OpenCode 的权限按工具维度划分，支持 allow / ask / deny 三级：

权限级别	含义	适用场景
`allow`	允许操作，无需确认	安全可信的操作
`ask`	每次操作前询问用户确认	有风险但有时需要的操作
`deny`	禁止操作，Agent 无法执行	危险或敏感操作

版本说明：v38 的权限模型是 permission.read / permission.bash / permission.skill 三个对象（外加 permission.task 控制子 Agent 委派、external_directory 控制外部目录）。早期版本的 permissions.files.allow/ask/deny 数组与 external_dirs 结构已废弃。

调整文件读取权限（permission.read）

{
  "permission": {
    "read": {
      "*": "allow",
      ".env": "deny",
      "*.env": "deny",
      "*.env.*": "deny",
      ".envrc": "deny",
      "*.envrc": "deny",
      "*.env.example": "allow"
    }
  }
}

调整 bash 命令权限（permission.bash）

bash 权限采用 allow-list + ask-list + 兜底 *: ask 的结构。解析是 last-match-wins，因此兜底 * 必须放在最后——它让任何未列出的命令（包括拼写变体的破坏性命令）默认询问，而不是默认放行：

{
  "permission": {
    "bash": {
      "git status*": "allow",
      "git diff*": "allow",
      "git log*": "allow",
      "git show*": "allow",
      "git add *": "allow",
      "git commit*": "allow",
      "node scripts/*": "allow",
      "npm run *": "allow",
      "npm test*": "allow",
      "rg *": "allow",
      "rm -rf*": "ask",
      "git push --force*": "ask",
      "git reset --hard*": "ask",
      "git clean -fd*": "ask",
      "git checkout .*": "ask",
      "git branch -D*": "ask",
      "gh repo delete*": "ask",
      "gh pr close*": "ask",
      "*": "ask"
    }
  }
}

调整外部目录访问权限

外部目录访问由 external_directory 控制，默认 ask（每次访问需确认）。如需放行特定外部目录，可改为 allow：

{
  "permission": {
    "external_directory": "ask"
  }
}

安全提醒：外部目录权限应尽量收紧。每个放行的目录都增大了安全风险面。只开放 Agent 真正需要访问的路径。

12.4 不同场景的配置建议

不同开发场景对安全性、协作性和灵活性的要求不同。以下是四种典型场景的配置建议。

12.4.1 个人开发者

特点：单人使用，无协作需求，追求效率最大化。

推荐配置：

配置项	建议	理由
权限策略	适度放宽 `ask` 规则，减少确认弹窗	个人项目无安全风险，效率优先
Agent 数量	保留默认 12 个	完整能力覆盖
subagent_depth	保持默认 3	个人任务复杂度通常不需要更深嵌套
实验功能	可全部开启	个人使用容错空间大
外部目录	按需放开	个人开发环境路径固定

额外建议：

将 API Key 设置为环境变量而非硬编码
定期用 /reflect 优化配置
不用太担心权限收紧——个人使用场景下，效率损失比安全风险更值得关注

12.4.2 小型团队（3-10 人）

特点：有协作需求，需要统一的规范但不需要重流程。

推荐配置：

配置项	建议	理由
权限策略	保持默认 `ask` 规则	团队成员技能水平不一，确认机制保护新手
团队规则	Fork 仓库 + AGENTS.md 添加团队约定	代码风格统一，减少 Code Review 摩擦
命令别名	团队统一命令集，/commit 强制 Conventional Commits	提交信息一致，方便生成 CHANGELOG
Code Review	强制 `/review` 前置（PR 模式自动回帖）	AI 处理机械检查，人工聚焦架构
实验功能	团队负责人决定，统一开关	避免成员间体验不一致

额外建议：

指定一人为”配置维护者”，负责 Fork 仓库的更新和团队规则的管理
每两周一次配置回顾会议（15 分钟），讨论 /reflect 发现的问题
新人入职时提供”OpenCode 配置入门”的 30 分钟 onboarding

12.4.3 开源项目

特点：贡献者多样，代码质量要求高，安全性是第一优先级。

推荐配置：

配置项	建议	理由
权限策略	收紧：更多 `deny` 规则	外部贡献者的代码必须有严格的安全把关
安全审查	必须启用 `security-review` 技能	防止注入、SSRF、密钥泄露等安全问题
Code Review	`/review`（PR 模式）+ 人工审查双重把关	开源项目声誉依赖代码质量
贡献指南	AGENTS.md 中明确贡献流程和规范	降低贡献者学习成本
外部目录	全部 `deny`	开源贡献不应访问维护者本地环境

额外建议：

在 CONTRIBUTING.md 中推荐贡献者也使用此配置
在 CI 中集成 OpenCode 的 /review（PR 模式）作为自动化检查步骤
AGENTS.md 中包含项目的架构约定和设计决策记录

12.4.4 企业内部

特点：安全合规要求高，有专职安全团队，代码库通常较大。

推荐配置：

配置项	建议	理由
权限策略	严格收紧：最少权限原则	合规要求，防止 IP 泄露
安全审查	启用所有审查技能（code-review + security-review）	满足安全审计要求
数据保护	所有 `.env`、`credentials/`、`.pem` 设为 `deny`	防止 AI 读取敏感信息
外部 API	禁止 Agent 主动调用外部 URL	防止数据外泄
模型选择	可考虑私有部署模型替代公有 API	满足数据不出境的要求
审计日志	建议开启会话日志	安全审计需要追溯 Agent 行为

额外建议：

与安全团队合作审查 AGENTS.md 中的权限配置
为不同项目设置不同的权限配置文件
大型团队建议设立”OpenCode 管理员”角色，负责配置维护和员工支持

12.5 成本优化建议

DeepSeek V4 的定价已经极具竞争力，但合理的使用策略能进一步降低月度支出。

12.5.1 DeepSeek API 定价分析

以 2026-08-16 生效的 DeepSeek 官方离峰定价为参考（实际价格以 platform.deepseek.com 为准，高峰时段价格翻倍）：

模型	输入（每百万 Token）	输出（每百万 Token）	缓存读取	相对成本
DeepSeek V4 Pro	$0.66	$1.98	$0.022	基准（1x）
DeepSeek V4 Flash	$0.22	$0.66	$0.007	约 0.33x
DeepSeek V4 Flash-Vision-Exp	$0.22	$0.66	$0.007	同 Flash

关键洞察：Flash 的输入价格约为 Pro 的 1/3，而缓存读取（cache_read）比普通输入便宜约 30 倍（Pro $0.022 vs $0.66）——这正是 AGENTS.md 强调”字节稳定前缀”以最大化 prompt-cache 命中的原因。如果 70% 的任务能用 Flash 完成，总体成本可以降低约 50%。仓库提供 scripts/estimate-cost.js 脚本可按输入/缓存/输出 Token 量精确估算成本。

12.5.2 典型工作流的 Token 消耗估算

任务类型	模型	预估 Token（输入+输出）	预估成本
简单搜索（grep 一个关键词）	Flash	~500 Token	< $0.001
代码库探索（了解一个新模块）	Flash	~3000 Token	~$0.001
单文件修改（修复一个 typo）	Flash	~2000 Token	~$0.001
多文件重构（3-5 个文件）	Pro	~15000 Token	~$0.02
代码审查（500 行 diff）	Pro	~20000 Token	~$0.03
复杂调试（root cause analysis）	Pro	~30000 Token	~$0.04
完整功能开发（规划+实现+审查）	Pro	~80000 Token	~$0.10

以上为离峰价估算，实际成本取决于任务复杂度、会话长度和路由效率。可用 scripts/estimate-cost.js 精确计算。

12.5.3 月度成本预估

使用程度	日交互次数	日均 Token	月估算成本	典型用户画像
轻度	5-10 次	~10K	$1-3	偶尔使用 AI 辅助的开发者
中度	20-30 次	~50K	$5-15	日常依赖 AI 编程的开发者
重度	50-80 次	~150K	$15-40	全天使用 AI 的主力开发者

12.5.4 省钱技巧

技巧一：Flash 优先策略的实际节省

假设一个中度用户每天 25 次交互，其中 70%（17 次）可以走 Flash，30%（8 次）必须走 Pro：

全 Pro 方案：25 × $0.004 ≈ $0.10/天，≈ $3/月
Flash 优先方案：(17 × $0.001) + (8 × $0.004) ≈ $0.05/天，≈ $1.5/月

节省幅度：约 50%。

技巧二：定期 `/handoff` 压缩长会话

一次 100K Token 的长会话如果不压缩，新任务继续累积上下文，很快就达到上下文窗口上限。每完成一个子任务就 /handoff，月均可减少 30% 的冗余上下文消耗。

技巧三：合理使用 `subagent_depth` 限制嵌套

subagent_depth: 3 意味着 Orchestrator → Worker → Subagent 最多三层。超过这个深度的嵌套通常不会带来更好的效果，反而因为每一层都携带完整上下文而造成 Token 浪费。

如果你的任务通常不需要深度嵌套，可以降低到 subagent_depth: 2，减少不必要的调度开销。

技巧四：关闭不需要的实验功能

OpenCode 的某些实验功能会额外消耗 Token（例如额外的上下文注入、额外的验证步骤）。检查 opencode.jsonc：

{
  "experimental": {
    "feature_x": false,  // 不需要就关掉
    "feature_y": true    // 只保留真正有用的
  }
}

每个实验功能大约增加 5%-15% 的 Token 开销。关闭 3 个不需要的功能，月均可节省 15%-45%。

技巧五：精简 Agent Prompt

Agent prompt 中的冗余描述会每次都注入上下文。每减少 100 个单词的 prompt，按每天 20 次激活计算，月均可节省约 ¥1-2。积少成多，不要轻视 prompt 的精简。

12.6 常见问题（FAQ）

Q: 为什么我的 Orchestrator 没有自动路由？

A: 检查以下几点：

确认 opencode.jsonc 中 Orchestrator 的配置正确，特别是 model 字段
检查 AGENTS.md 中是否删除了路由规则相关的部分
如果使用命令别名（/review 等），路由是确定性的，不是”自动路由”
自然语言路由只在 Orchestrator Agent 处于活跃状态时生效——如果你的默认 Agent 不是 Orchestrator，需要先切换到它

Q: 如何确认当前正在使用哪个 Agent？

A: 有几种方式：

查看 OpenCode TUI 的状态栏，通常会显示当前 Agent 名称
在对话中直接问”当前是哪个 Agent 在处理？”
观察 Agent 的行为特征——Explorer 只读不写，Worker 会修改文件
查看 OpenCode 的日志输出（如果开启了日志）

Q: Flash Agent 处理不了的复杂任务怎么办？

A: Flash 遇到超出能力范围的任务时，框架会自动升级到 Pro。具体机制：

Flash 检测到任务复杂度过高（或自身无法完成）
向上级 Agent（通常是 Orchestrator）报告
Orchestrator 将任务重新路由到 Pro Agent（如 deep-worker、oracle、reviewer）
上下文会被保留并传递给 Pro Agent，不会丢失已有进展

你也可以主动指定用 Pro 处理，例如：”用 Pro 模型分析这个性能瓶颈”。

Q: 如何知道一个技能是否已加载？

A: 技能的加载是可见的：

在对话中，技能加载时会显示类似 [Skill loaded: code-review] 的提示
Agent 的行为会按技能的指导流程执行——这说明技能已生效
你可以直接问”当前加载了哪些技能？”
查看 skills/ 目录确认技能文件存在且格式正确

Q: 命令别名和自然语言路由哪个更快？

A: 命令别名更快，原因：

命令别名跳过 Orchestrator 的意图门控推理（省去一次 Flash 模型调用）
路由是确定性的，不需要语义匹配
延迟更低，Token 消耗更少

建议：高频操作（审查、提交、清理）用命令别名，低频或描述性强的操作用自然语言。

Q: 更新 OpenCode 后配置不兼容怎么办？

A: 按以下步骤处理：

先备份当前配置：cp -r ~/.config/opencode ~/.config/opencode.backup
更新 OpenCode 到最新版本
检查上游仓库 znlgis/my-opencode-deepseek-config 是否有对应的更新
如果有，git pull 同步上游更改
如果没有，逐一检查 opencode.jsonc 中的字段是否仍被新版支持
运行一个简单任务验证配置是否正常工作

Q: 可以同时使用 DeepSeek 和其他模型吗？

A: 可以，但不推荐。my-opencode-deepseek-config 的设计前提是纯 DeepSeek 环境。混合使用其他模型会导致：

Agent prompt 中针对 DeepSeek 优化的指令可能对其他模型效果不佳
路由策略基于 DeepSeek 的三模型特性设计（Pro/Flash/Flash-Vision-Exp），混用会打乱路由逻辑
Token 成本估算失去参考意义

如果确实需要多模型，建议 Fork 后创建独立的配置分支，为每个模型组合维护独立的配置文件。

Q: 如何备份我的自定义配置？

A: 这套方案天然以 Git 为备份机制：

所有配置文件都在 ~/.config/opencode/ 下
确保该目录是一个 Git 仓库（clone 方式部署时自动满足）
定期 git push 到远程仓库
对于 API Key 等敏感信息，使用环境变量而非文件存储，这样备份仓库不包含密钥

Q: DCP 压缩会丢失重要上下文吗？

A: DCP（Deduplication and Context Pruning）的设计目标是保留关键信息、去除冗余。它通过去重和摘要方式压缩上下文，而非简单截断：

重复的探索结果只会保留一份
已完成任务的中间过程被压缩为简短摘要
关键决策、当前进度、待办事项被优先保留

一般来说，DCP 压缩后的上下文丢失重要信息的概率很低。但如果你发现某个特定场景下丢失了关键上下文，可以在 AGENTS.md 中为该场景添加 DCP 保护标记。

Q: 如何给项目添加自定义的反模式规则？

A: 编辑 AGENTS.md，在反模式清单部分添加：

## 项目反模式清单（my-project 追加）

- 禁止在 Redux action 中执行副作用（用 Redux Saga 或 Thunk）
- 禁止在 `useEffect` 中直接定义 async 函数而不处理 cleanup
- 禁止使用 `index` 作为 React `key`（除非列表是静态且不会重新排序）
- 禁止在 TypeScript 中使用 `as` 类型断言绕过类型检查（用类型守卫替代）

确保每条规则都是可验证的——Agent 能够在代码中检测到违规。

Q: 什么是 `subagent_depth=3` 的实际意义？

A: subagent_depth 控制任务委托的最大嵌套层级：

depth=1：只有 Orchestrator 可以直接分派任务。Worker 不能再委托子任务。
depth=2：Orchestrator → Worker 可以，但 Worker 不能再创建自己的 Subagent。
depth=3（默认）：Orchestrator → Worker → Subagent，允许三层委托。

实际影响：假设你需要审查一个大型 PR：

depth=1：Orchestrator 直接审查，可能因上下文不够深入而遗漏问题
depth=2：Orchestrator 分派给 Reviewer，Reviewer 可以并行检查多个维度但不能委托子任务
depth=3：Orchestrator → Reviewer → 每个文件独立 Subagent 深度审查

对于大多数开发任务，depth=3 已经足够。超过 3 层的嵌套通常意味着任务分解有问题。

12.7 故障排查指南

问题：Agent 没有响应或响应异常

可能原因与排查步骤：

API Key 问题（最常见）
- 检查 DeepSeek API Key 是否有效：在 platform.deepseek.com 的 API Keys 页面确认状态
- 检查账户余额是否充足
- 检查 API Key 是否正确设置在环境变量中
网络连接问题
- 确认网络可以访问 api.deepseek.com
- 检查是否配置了代理（如有需要，设置 HTTPS_PROXY 环境变量）
- 尝试 curl https://api.deepseek.com/v1/models 测试连通性
配置文件问题
- 检查 opencode.jsonc 的 JSON 语法是否正确（可以用 opencode validate-config 验证）
- 确认 Agent prompt 文件路径正确，文件存在且可读
- 检查是否有加载失败的日志输出
OpenCode 版本问题
- 确认版本 >= v1.18.x（本配置 README 声明的最低支持版本）
- 运行 opencode --version 查看当前版本
- 如版本过低，升级到最新版

问题：Token 消耗异常高

排查步骤：

检查会话长度：当前会话是否已经运行很久？是否需要 /handoff？
检查是否加载了不必要的技能：查看对话历史，确认没有意外加载不需要的技能
检查 Agent prompt 长度：自定义的 Agent prompt 是否过于冗长？
检查实验功能：是否开启了不必要的实验功能？
检查路由效率：是否因自然语言描述模糊导致 Orchestrator 多次推理失败重试？

诊断命令：向 Agent 询问”当前会话的上下文大概消耗了多少 Token？”——Agent 可以根据自身的上下文窗口使用量给出估算。

问题：配置文件未生效

排查步骤：

确认文件位置：配置文件必须放在 ~/.config/opencode/（Linux/macOS）或 %USERPROFILE%\.config\opencode\（Windows）
重启 OpenCode：配置修改后需要重启 OpenCode 才能生效
检查文件名：AGENTS.md（不是 agents.md）、opencode.jsonc（不是 opencode.json）
验证 JSON 语法：opencode validate-config 可以检查配置文件的正确性
检查配置优先级：项目级配置（.opencode/opencode.jsonc）会覆盖全局配置

问题：权限设置过严或过松

诊断与调整：

过严的症状：Agent 频繁请求权限确认，每次操作都弹出询问框
- 解决：将高频低风险操作从 ask 改为 allow
过松的症状：Agent 执行了你没想到的修改、访问了预期之外的目录
- 解决：收紧 allow 规则，将高风险操作改为 ask 或 deny

安全基线建议：

// 最小权限基线：所有操作默认 ask，只有明确安全的才 allow
{
  "permissions": {
    "files": {
      "allow": ["**/*.{ts,js,md,css,html}"],
      "ask": ["**/*"],
      "deny": ["**/.git/**", "**/*.env*", "**/*.pem", "**/credentials/**"]
    },
    "bash": {
      "allow": ["git status", "git diff", "git log*"],
      "ask": ["*"],
      "deny": ["rm -rf *", "sudo *", "git push --force*"]
    }
  }
}

问题：技能加载失败

排查步骤：

检查文件位置：技能文件必须在 skills/<skill-name>/SKILL.md
检查文件名：必须命名为 SKILL.md（全大写）
检查格式：确保 Markdown 语法正确，没有损坏的 frontmatter
检查触发词：技能的描述是否包含了明确的触发条件？如果触发词太模糊，可能永远不会被匹配
手动加载测试：直接在对话中说”加载 [技能名] 技能”来测试是否能手动激活

问题：命令别名不工作

排查步骤：

检查命令定义：确认 opencode.jsonc 中 commands 字段包含该命令
检查 Agent/Skill 存在：命令映射的 Agent 或 Skill 是否确实存在
检查命令格式：输入命令时是否带上了 / 前缀？/my-command 正确，my-command 不正确
检查命名冲突：是否与 OpenCode 内置命令重名？
重启 OpenCode：命令定义变更后需要重启

12.8 进阶技巧

12.8.1 利用 spec-workflow 管理大型功能开发

spec-workflow 是一套轻量级的”提案→规格→设计→任务清单→实现→归档”流程，适合管理超过 3 天的大型功能开发。

使用流程：

1. /spec-propose → 探索代码并起草提案（proposal.md + tasks.md）
2. /spec-apply   → 按 tasks.md 逐项实现并自动归档（无需单独 /archive）

适用场景：

跨多个模块的新功能
涉及架构变更的重构
需要团队 review 的技术方案

12.8.2 用 reflect 机制持续优化配置

/reflect 不只是发现问题——它还会给出具体的优化建议。这是”配置的自我进化”：

优化循环：

使用 → 积累摩擦 → /reflect 发现 → 修改配置 → 再次使用 → 验证效果

进阶用法：

在 /reflect 的提示中指定关注领域：”回顾一下最近代码审查相关的交互，看看有没有可以优化的地方”
结对使用：两个人分别运行 /reflect，对比发现的问题，优先解决两人共同的痛点
建立优化日志：在 Fork 仓库的 README 中记录每次 /reflect 驱动的配置变更和效果

12.8.3 借助 gh-cli 技能实现 GitHub 自动化

gh-cli 技能让 Agent 可以直接操作 GitHub 的 Issues、PRs、Releases 等。

实用场景：

# 审查 PR 并自动回帖到 GitHub（PR 模式，发布为 GitHub Review）
/review <PR 引用或 URL>  # 使用 gh-cli + code-review 技能，将审查结果发布为 GitHub Review（event=COMMENT）

# 批量处理 Issues
"帮我把所有标记为 'bug' 且超过 30 天未更新的 issue 加上 'stale' 标签"

# 自动关联 PR
"根据这个分支的 commit 历史，找到关联的 Issue 并在 PR 描述中引用"

12.8.4 串联多个命令实现复杂工作流

可以将多个命令组合成流水线，适合在 CI 或定期任务中使用：

示例：发布前检查流水线

/review             # AI 审查代码（自动加载 code-review + security-review 技能）
/rmslop             # 清理死代码
（人工修复发现的问题）
/commit             # 生成规范提交
/release            # 生成 Release

示例：每日维护流水线

/reflect            # 发现配置优化点
/rmslop             # 清理死代码
（手动 review /reflect 的建议并调整配置）
git commit -m "chore: daily config maintenance"

12.8.5 在 CI/CD 中集成 OpenCode Agent

OpenCode 可以以非交互模式运行，适合集成到 CI 流水线：

# GitHub Actions 示例
- name: AI Code Review
  run: |
    opencode run --non-interactive --command "/review" \
      --agent "reviewer" \
      --max-tokens 30000
  env:
    DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}

CI 集成的注意事项：

使用 --non-interactive 模式避免挂起等待输入
设置 --max-tokens 防止成本失控
API Key 通过 GitHub Secrets 传入，不要硬编码
CI 中的 AI 审查作为辅助检查，不应阻断流水线（可设为 warning 级别）

12.8.6 多项目配置管理策略

当你有多个项目，每个需要不同的配置时：

策略一：单一配置 + 项目级覆盖

~/.config/opencode/          # 全局基础配置
project-a/.opencode/         # 项目 A 覆盖配置
project-b/.opencode/         # 项目 B 覆盖配置

OpenCode 会合并全局和项目级配置，项目级覆盖优先。

策略二：多配置仓库 + 符号链接

~/.config/opencode-projects/
  ├── web-frontend-config/   # Web 前端专用配置
  ├── backend-config/        # 后端专用配置
  └── library-config/        # 库开发专用配置

# 切换配置
ln -sf ~/.config/opencode-projects/web-frontend-config ~/.config/opencode

策略选择：

如果差异小（只是 AGENTS.md 中几个规则不同），用策略一
如果差异大（Agent 配置、权限模型完全不同），用策略二

12.9 配置备份与迁移

12.9.1 备份策略：Git 仓库即备份

这套配置方案的最大优势之一是天然免备份——所有配置都在 Git 仓库中。

日常备份流程：

# 1. 查看变更
cd ~/.config/opencode
git status
git diff

# 2. 提交变更（或用 /commit 命令）
git add -A
git commit -m "chore: update agent prompts and permissions"

# 3. 推送到远程
git push origin main

注意：确认 .gitignore 中包含：

.env
*.pem
credentials/

这些敏感文件不应进入 Git 历史。

12.9.2 迁移到新机器

完整迁移流程：

# 第 1 步：在新机器上安装 OpenCode
curl -fsSL https://opencode.ai/install | bash

# 第 2 步：克隆配置仓库
git clone https://github.com/YOUR_USERNAME/my-opencode-deepseek-config.git ~/.config/opencode

# 第 3 步：配置 DeepSeek API Key
export DEEPSEEK_API_KEY="sk-your-key-here"
# 建议写入 shell 配置文件（~/.bashrc 或 ~/.zshrc）

# 第 4 步：验证安装
opencode --version
# 启动 OpenCode，执行一个简单任务验证
opencode
# > 帮我列出当前目录的文件

迁移后检查清单：

opencode --version 显示正确版本
DeepSeek API Key 已配置且有效
命令别名（如 /review）可正常使用
常用技能（如 codemap）可正常加载
Git 配置中 remote origin 指向正确的仓库

12.9.3 团队共享：Fork → 定制 → Pull Request 贡献

团队配置的演化流程：

上游仓库 (znlgis/my-opencode-deepseek-config)
    │
    └── Fork: 团队仓库 (my-team/my-opencode-deepseek-config)
            │
            ├── 分支: team-rules     # 团队特定规则
            ├── 分支: team-skills    # 团队自定义技能
            └── 分支: main          # 与上游同步 + 团队规则合并

同步上游更新：

# 添加上游仓库
git remote add upstream https://github.com/znlgis/my-opencode-deepseek-config.git

# 拉取上游更新
git fetch upstream
git checkout main
git merge upstream/main

# 解决冲突（如果有的话）
# 推送合并后的结果
git push origin main

贡献回上游：如果你的团队开发了通用性强的 Skill 或优化，欢迎通过 PR 贡献回上游仓库，让更多人受益。

12.10 附录：快速参考卡片

Agent 速查表

Agent 名称	模型	权限	核心用途
orchestrator	Flash	读写	意图门控、任务路由、调度决策——系统默认主入口（主入口）
solo	Pro	读写	单模型内联执行、零委派——需要全程单一模型时的主入口（主入口）
planner	Flash	读写	战略规划、架构设计、项目拆解——”设计然后建造”（中档思考层）
deep-worker	Pro	读写	重型多文件实现、复杂重构——系统的”主力工程师”
oracle	Pro	只读	深度代码分析、根因诊断、代码简化分析——”透视眼”
reviewer	Pro	只读	代码审查、安全审查（PR 或本地 diff）——”质量守门人”
consultant	Flash	读写	技术顾问、方案对比、最佳实践建议——”智囊”
ui-builder	Flash	读写	前端 UI 组件、样式、布局、交互——”界面专家”
explore	Flash	只读	代码库搜索、文件探索、信息检索
librarian	Flash	只读	外部文档检索、Web 搜索、API 研究
light-orchestrator	Flash	读写	轻量单文件编辑、简单修改 + `/commit`/`/handoff`/`/simplify` 宿主
vision	Flash-Vision	只读	多模态图像识别、截图/图片解读（读图后转交 deep-worker）

命令别名速查表

命令	功能	路由目标
`/deep`	重型实现、多文件改动	deep-worker
`/quick`	轻量任务、单文件编辑	light-orchestrator
`/ui`	前端/UI 工作	ui-builder
`/vision`	多模态图像识别	vision
`/review`	代码审查（PR 模式自动回帖 / 本地 diff 模式）	reviewer + code-review（+ gh-cli）
`/plan`	制定技术方案	planner
`/oracle`	深度分析与根因调试	oracle
`/commit`	生成 Conventional Commits 提交	light-orchestrator
`/release`	准备 Tag 发布	deep-worker + git-release
`/reflect`	发现摩擦→配置优化	oracle + reflect
`/handoff`	压缩会话为交接文档	light-orchestrator + handoff
`/codemap`	生成仓库结构图	explore + codemap
`/learn`	提炼经验写入目录级 AGENTS.md	deep-worker
`/simplify`	行为保持的代码简化（两阶段：派 oracle 分析→自身应用）	light-orchestrator + simplify
`/rmslop`	清理死代码和 AI slop	deep-worker + remove-deadcode
`/spec-propose`	起草变更提案	planner + spec-workflow
`/spec-apply`	按清单实施并自动归档	deep-worker + spec-workflow

技能速查表

技能名称	触发场景	是否自动加载
codemap	开始探索不熟悉的项目	`/codemap` 触发
code-review	代码审查、PR 审查	`/review` 触发
security-review	安全检查	`/review` 自动评估是否需要
spec-workflow	规约驱动变更管理	`/spec-propose`、`/spec-apply` 触发
diagnosing-bugs	系统化调试 bug	遇到 bug/测试失败时
remove-deadcode	清理死代码	`/rmslop` 触发
simplify	代码简化	`/simplify` 触发
verify-with-docs	API 文档验证	涉及第三方库时自动
gh-cli	GitHub CLI 操作	涉及 GitHub PR/Issue 时自动
git-master	高级 Git 操作	涉及复杂 Git 时自动
git-release	版本发布管理	`/release` 触发
resolving-merge-conflicts	解决合并冲突	遇到 git 冲突时
opencode-config	修改 OpenCode 配置	修改配置文件时自动
reflect	配置回顾优化	`/reflect` 触发
handoff	会话交接	`/handoff` 触发
writing-for-agents	编写 Agent 消费的文档	编写/编辑技能、AGENTS.md 时
codebase-design	架构与模块边界设计	设计架构、评审结构时
domain-modeling	领域术语统一	术语模糊、反复解释时
grilling / grill-with-docs	需求澄清	需求模糊时
wait-what	确认模糊指令	用户消息令人困惑时
office-docs	读写 Word/Excel	处理 .docx/.xlsx 时
vision-prep	预处理大图/PDF	读大图、PDF 页时
to-tickets	拆解为 GitHub Issue	计划需拆成工单时
triage	Issue 分流	批量 Issue 排序时

后备链速查图

任务输入
    │
    ▼
Orchestrator (Flash) — 意图门控（主入口）
    │
    ├──→ explore (Flash) — 探索不熟悉代码库
    │       └── 失败 → 升级到 oracle (Pro)
    │
    ├──→ librarian (Flash) — 文档/Web 检索
    │       └── 失败 → 升级到 consultant (Flash)
    │
    ├──→ planner (Flash) — 规划/架构设计
    │       └── 失败 → 升级到 oracle (Pro) 重新分类
    │
    ├──→ light-orchestrator (Flash) — 简单编辑
    │       └── 失败 → 升级到 deep-worker (Pro)
    │
    ├──→ deep-worker (Pro) — 复杂实现
    │       └── 失败 → planner 重新规划 → deep-worker
    │
    ├──→ reviewer (Pro) — 代码审查
    │       └── critical/major → oracle → deep-worker 修复 → 新 reviewer（≤2 轮）
    │
    ├──→ oracle (Pro) — 根因诊断、简化分析
    │       └── 无根因 → deep-worker 探索性排查
    │
    ├──→ consultant (Flash) — 方案讨论
    │       └── 不确定 → planner / oracle
    │
    └──→ vision (Flash-Vision) — 多模态读图
            └── 无法读取 → deep-worker

路由决策流程图

开始
  │
  ├─ 用户输入命令别名（以 / 开头）？
  │   └─ 是 → 直接路由到命令定义的 Agent/Skill → 结束
  │
  └─ 自然语言任务 → Orchestrator 意图门控
        │
        ├─ 任务涉及文件探索/搜索？
        │   └─ 是 → 路由到 explore (Flash)
        │
        ├─ 任务涉及文档查阅？
        │   └─ 是 → 路由到 librarian (Flash)
        │
        ├─ 任务是简单单文件修改？
        │   └─ 是 → 路由到 light-orchestrator (Flash)
        │
        ├─ 任务是复杂多文件修改？
        │   └─ 是 → 路由到 deep-worker (Pro)
        │
        ├─ 任务是代码审查？
        │   └─ 是 → 路由到 reviewer (Pro)
        │
        ├─ 任务是架构设计/项目拆解？
        │   └─ 是 → 路由到 planner (Flash)
        │
        ├─ 任务是根因诊断/深度分析？
        │   └─ 是 → 路由到 oracle (Pro)（只读分析）
        │
        ├─ 任务是读图/多模态识别？
        │   └─ 是 → 路由到 vision (Flash-Vision)
        │
        └─ 无法分类？
            └─ Orchestrator 直接处理或询问用户澄清

本章小结

第十二章涵盖了从日常使用到深度定制的完整知识体系：

Token 效率：命令别名优先、定期 /handoff、Flash 优先策略、codemap 缓存——这些习惯每月可节省 30%-50% 的 Token 消耗
团队协作：Fork→定制→共享的标准流程，AGENTS.md 统一团队规则，/review 标准化代码审查（PR 模式自动回帖）
定制化：从添加 Agent、Skill、命令到修改权限配置的完整操作指南，每一步都有实际示例
成本控制：DeepSeek 定价分析、典型工作流成本估算、五个实用省钱技巧
问题解决：9 个常见 FAQ、6 类故障排查场景、从 API Key 到配置兼容性的全覆盖
进阶应用：spec-workflow 管理大型功能、reflect 驱动配置进化、CI/CD 集成、多项目配置管理

学习建议：本章可以作为日常参考手册使用。不需要一次性读完——遇到具体问题时，直接跳到对应小节查找答案。附录中的速查表建议打印或收藏，高频使用时可大幅提升效率。

本章是整套教程的最后一章。恭喜完成全部 12 章的学习！如果对本教程有任何反馈或改进建议，欢迎通过 GitHub Issues 提出。

第十二章：最佳实践与定制指南

12.1 Token 效率最佳实践

12.1.1 用命令别名替代自然语言路由

12.1.2 长会话定期用 /handoff 压缩交接

12.1.3 Flash 优先策略

12.1.4 善用 codemap 技能避免重复探索

12.1.5 及时清理死代码

12.1.6 写代码前规划验证路径

12.1.7 Token 效率检查清单

12.2 团队协作最佳实践

12.2.1 Fork 后定制团队版本

12.2.2 在团队 AGENTS.md 中添加团队特定规则

12.2.3 使用 Git 管理配置版本

12.2.4 定期运行 /reflect 发现工作流摩擦

12.2.5 用 /commit 统一提交信息格式

12.2.6 /review 作为团队代码审查标准

12.2.7 团队的”新手保护”策略

12.3 定制化指南

12.3.1 添加自定义 Agent

目录位置

创建步骤

Agent 权限模式对比

模型选择指南

12.3.2 添加自定义技能

目录位置

技能的结构规范

完整示例：API 文档生成技能

触发条件和加载时机

技能开发的注意事项

12.3.3 添加自定义命令

配置文件位置

命令结构

命令的 template 设计

命名规范

完整示例

12.3.4 修改 AGENTS.md

添加项目特定规则

调整代码风格约束

添加团队约定

12.3.5 调整权限配置

权限模式说明

调整文件读取权限（permission.read）

调整 bash 命令权限（permission.bash）

调整外部目录访问权限

12.4 不同场景的配置建议

12.4.1 个人开发者

12.4.2 小型团队（3-10 人）

12.4.3 开源项目

12.4.4 企业内部

12.5 成本优化建议

12.5.1 DeepSeek API 定价分析

12.5.2 典型工作流的 Token 消耗估算

12.5.3 月度成本预估

12.5.4 省钱技巧

技巧一：Flash 优先策略的实际节省

技巧二：定期 /handoff 压缩长会话

技巧三：合理使用 subagent_depth 限制嵌套

技巧四：关闭不需要的实验功能

技巧五：精简 Agent Prompt

12.6 常见问题（FAQ）

Q: 为什么我的 Orchestrator 没有自动路由？

Q: 如何确认当前正在使用哪个 Agent？

Q: Flash Agent 处理不了的复杂任务怎么办？

Q: 如何知道一个技能是否已加载？

Q: 命令别名和自然语言路由哪个更快？

Q: 更新 OpenCode 后配置不兼容怎么办？

Q: 可以同时使用 DeepSeek 和其他模型吗？

Q: 如何备份我的自定义配置？

Q: DCP 压缩会丢失重要上下文吗？

Q: 如何给项目添加自定义的反模式规则？

Q: 什么是 subagent_depth=3 的实际意义？

12.7 故障排查指南

问题：Agent 没有响应或响应异常

问题：Token 消耗异常高

问题：配置文件未生效

问题：权限设置过严或过松

问题：技能加载失败

问题：命令别名不工作

12.8 进阶技巧

12.8.1 利用 spec-workflow 管理大型功能开发

12.1.2 长会话定期用 `/handoff` 压缩交接

12.2.4 定期运行 `/reflect` 发现工作流摩擦

12.2.5 用 `/commit` 统一提交信息格式

12.2.6 `/review` 作为团队代码审查标准

技巧二：定期 `/handoff` 压缩长会话

技巧三：合理使用 `subagent_depth` 限制嵌套

Q: 什么是 `subagent_depth=3` 的实际意义？