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

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

12.1 Token 效率最佳实践

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

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

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

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

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

• /code-review — 代码审查
• /commit — 规范化提交
• /reflect — 配置优化回顾
• /handoff — 会话交接
• /rmslop — 清理死代码
• /verify-plan — 验证路径规划

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

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

操作建议：

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

实际效果：假设一个 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 适合（保留给复杂任务）：

• 多文件架构重构
• 根因分析（/diagnose）
• 代码审查（/code-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 写代码前用 /verify-plan 规划验证路径

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

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

而预先规划验证路径后，实现是一次到位的。/verify-plan 帮助你在写第一行代码之前明确：

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

12.1.7 Token 效率检查清单

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

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

12.2 团队协作最佳实践

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

12.2.1 Fork 后定制团队版本

推荐的团队接入流程：

1. 团队负责人 Fork znlgis/my-opencode-deepseek-config
2. 在 Fork 的仓库中修改 AGENTS.md，添加团队特定规则
3. 根据需要调整 Agent prompt（如添加领域知识）
4. 团队成员 git clone Fork 仓库到 ~/.config/opencode
5. 团队成员配置各自的 DeepSeek API Key
6. 后续通过 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 技能，自动分析变更内容并生成符合 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-pr 作为团队代码审查标准

将 /review-pr 设为团队的代码审查前置步骤：

1. 开发者完成功能后，先本地运行 /review-pr
2. 修复 /review-pr 发现的所有 High/Critical 级别问题
3. 创建 PR 时，将审查报告作为评论贴出
4. 人工 Reviewer 聚焦于架构和业务逻辑——语法和反模式问题已被 AI 处理

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

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

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

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

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

12.3 定制化指南

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

12.3.1 添加自定义 Agent

目录位置

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

创建步骤

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

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

1. 这个 Agent 负责什么类型的任务？（单一职责）
2. 它需要 Pro 还是 Flash 模型？（推理密集型用 Pro，查询执行型用 Flash）
3. 它是否允许修改文件？（读写 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 步：在 opencode.jsonc 中注册 Agent

在 agents 字段中添加新条目：

{
  "name": "database-expert",
  "model": "deepseek/deepseek-v4-pro",
  "prompt": "agents/database-expert.md",
  "permissions": {
    "files": {
      "allow": ["**/*.sql", "**/migrations/**", "**/models/**/*.ts"],
      "deny": ["**/*.env*", "**/credentials/**"]
    }
  }
}

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

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

Agent 权限模式对比

模型选择指南

经验法则：如果 Agent 的核心工作是”理解和分析”（推理），用 Pro；如果核心工作是”查找和执行”（检索），用 Flash。

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

触发条件和加载时机

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

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

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

技能开发的注意事项

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

12.3.3 添加自定义命令

配置文件位置

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

命令结构

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

{
  "commands": {
    "命令名称": {
      "description": "命令的简短描述（显示在帮助信息中）",
      "agent": "目标 Agent 名称（可选，与 skill 二选一或都指定）",
      "skill": "目标 Skill 名称（可选）",
      "prompt": "注入给 Agent 的具体指令模板"
    }
  }
}

命令的 agent/skill 映射逻辑

命名规范

• 使用小写字母和连字符：/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",
      "skill": "api-doc-gen",
      "prompt": "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",
      "prompt": "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 支持三层权限模型：

添加/修改文件权限规则

{
  "permissions": {
    "files": {
      "allow": [
        "**/*.ts",
        "**/*.tsx",
        "**/*.js",
        "**/*.md"
      ],
      "ask": [
        "**/*.json",        // 配置文件修改前确认
        "**/package.json",  // 依赖变更需确认
        "**/*.env*"         // 环境变量文件需确认
      ],
      "deny": [
        "**/.git/**",      // 禁止直接操作 Git 内部文件
        "**/node_modules/**", // 禁止修改依赖
        "**/*.pem",         // 禁止读取私钥
        "**/credentials/**" // 禁止读取凭证目录
      ]
    }
  }
}

添加/修改 bash 命令权限

{
  "permissions": {
    "bash": {
      "allow": [
        "git status",
        "git diff",
        "git log*",
        "npm test",
        "npm run lint",
        "npx tsc*"
      ],
      "ask": [
        "git commit*",
        "git push*",
        "npm install*",
        "npm publish*"
      ],
      "deny": [
        "rm -rf *",
        "git push --force*",
        "sudo *",
        "curl * | bash",
        "eval *"
      ]
    }
  }
}

添加外部目录访问权限

默认可访问的目录限于工作区。如果 Agent 需要访问外部目录（如全局配置文件、共享库），需要在权限中显式声明：

{
  "permissions": {
    "external_dirs": {
      "allow": [
        "/etc/nginx/",                    // Nginx 配置目录
        "~/.ssh/config",                  // SSH 配置
        "/usr/local/share/proto/"         // 共享 Protobuf 定义
      ]
    }
  }
}

安全提醒：外部目录权限应尽量收紧。每个添加的目录都增大了安全风险面。只开放 Agent 真正需要访问的路径，使用精确路径而非通配符。

12.4 不同场景的配置建议

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

12.4.1 个人开发者

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

推荐配置：

额外建议：

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

12.4.2 小型团队（3-10 人）

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

推荐配置：

额外建议：

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

12.4.3 开源项目

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

推荐配置：

额外建议：

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

12.4.4 企业内部

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

推荐配置：

额外建议：

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

12.5 成本优化建议

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

12.5.1 DeepSeek API 定价分析

以 2025 年 DeepSeek 官方定价为参考（实际价格以 platform.deepseek.com 为准）：

关键洞察：Flash 的价格约为 Pro 的 1/4，如果 70% 的任务能用 Flash 完成，总体成本可以降低约 50%。

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

12.5.3 月度成本预估

以上为估算值，实际成本取决于任务复杂度、会话长度和路由效率。

12.5.4 省钱技巧

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

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

• 全 Pro 方案：25 × ¥0.013 ≈ ¥0.33/天，≈ ¥10/月
• Flash 优先方案：(17 × ¥0.003) + (8 × ¥0.013) ≈ ¥0.16/天，≈ ¥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: 检查以下几点：

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

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

A: 有几种方式：

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

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

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

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

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

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

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

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

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

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

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

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

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

A: 按以下步骤处理：

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

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

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

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

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

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

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

1. 所有配置文件都在 ~/.config/opencode/ 下
2. 确保该目录是一个 Git 仓库（clone 方式部署时自动满足）
3. 定期 git push 到远程仓库
4. 对于 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 层的嵌套通常意味着任务分解有问题。

Q: 审查修复循环（/review-loop）什么时候会停止？

A: 审查修复循环的停止条件是：

1. 零严重问题：所有 High/Critical 级别的问题都被修复
2. 收敛稳定：连续两轮审查的新问题数量不再增长（在一个稳定的小范围内波动）
3. 手动终止：用户认为剩余问题可接受，手动中断循环
4. 最大轮次：达到预设的最大循环次数（通常为 3-5 轮）

如果循环始终不收敛（每轮都发现大量新问题），通常是原始代码的质量太差，建议从更根本的层面重构而非继续循环修复。

12.7 故障排查指南

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

可能原因与排查步骤：

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

问题：Token 消耗异常高

排查步骤：

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

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

问题：配置文件未生效

排查步骤：

1. 确认文件位置：配置文件必须放在 ~/.config/opencode/（Linux/macOS）或 %USERPROFILE%\.config\opencode\（Windows）
2. 重启 OpenCode：配置修改后需要重启 OpenCode 才能生效
3. 检查文件名：AGENTS.md（不是 agents.md）、opencode.jsonc（不是 opencode.json）
4. 验证 JSON 语法：opencode validate-config 可以检查配置文件的正确性
5. 检查配置优先级：项目级配置（.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*"]
    }
  }
}

问题：技能加载失败

排查步骤：

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

问题：命令别名不工作

排查步骤：

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

12.8 进阶技巧

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

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

使用流程：

1. 执行 /spec-workflow 启动流程
2. 编写 proposal.md（WHY + WHAT）
3. 编写 spec.md（系统做什么）
4. 编写 design.md（怎么做）
5. 生成 tasks.md（分解为可执行任务）
6. 逐任务实现，每个完成后标记
7. 全部完成后归档到 specs/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 等。

实用场景：

# 让 Agent 帮你生成 Release Notes
/release  # 自动分析 commit 历史，生成 changelog 和 release

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

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

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

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

示例：发布前检查流水线

1. /code-review        # AI 审查代码
2. /rmslop             # 清理死代码
3. /security-review    # 安全检查
4. （人工修复发现的问题）
5. /commit             # 生成规范提交
6. /release            # 生成 Release

示例：每日维护流水线

1. /reflect            # 发现配置优化点
2. /rmslop             # 清理死代码
3. （手动 review /reflect 的建议并调整配置）
4. 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-pr" \
      --agent "light-orchestrator" \
      --max-tokens 30000
  env:
    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 已配置且有效
• 命令别名（如 /code-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 速查表

命令别名速查表

技能速查表

后备链速查图

任务输入
    │
    ▼
Orchestrator (Pro) — 意图门控
    │
    ├──→ Explore (Flash) — 探索不熟悉代码库
    │       └── 失败 → 升级到 Oracle (Pro)
    │
    ├──→ Librarian (Flash) — 文档检索
    │       └── 失败 → 升级到 Oracle (Pro)
    │
    ├──→ General (Flash) — 简单编辑
    │       └── 失败 → 升级到 deep-worker (Pro)
    │
    ├──→ Flash-worker (Flash) — 批量简单操作
    │       └── 失败 → 升级到 deep-worker (Pro)
    │
    ├──→ deep-worker (Pro) — 复杂实现
    │       └── 可委派子任务到 Flash Agent
    │
    ├──→ Reviewer (Pro) — 代码审查
    │       └── 可委派子任务到 Flash Agent 探索
    │
    └──→ Oracle (Pro) — 架构分析、简化建议

路由决策流程图

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

本章小结

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

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

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

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