5.6 Opencode 增强实践

前面五节讲解了智能增强的原理，本节展示如何在 Opencode 中落地实践。

5.6.1 反思机制实现

在 Opencode 中实现反思有三种方式：

方式一：Self-Critique Prompts 嵌入 AGENTS.md

在项目的 AGENTS.md 文件中加入反思指令，让每次输出都经过自我检查：

## 输出质量规范

每次生成内容后，请执行以下自我审查：
1. 检查数据准确性：引用是否正确、是否最新
2. 检查逻辑完整性：推理是否有跳跃
3. 检查风险披露：是否充分说明了风险
4. 检查用词合规：是否避免了不当承诺

如发现问题，自行修正后输出。

方式二：专用反思 Skill

创建一个专门用于反思的 Skill，在需要时调用：

# Skill: 财务分析自我审查

## 触发条件
当完成财务分析相关输出后

## 审查维度
- 计算准确性：各指标计算是否正确
- 数据时效性：使用的是否是最新数据
- 分析完整性：是否涵盖关键维度
- 结论支撑度：结论是否有充分依据

## 输出格式
列出发现的问题和改进后的版本

Skill 创建步骤：

在项目根目录创建 .opencode/skills/ 目录（如不存在）
创建 Skill 文件 .opencode/skills/financial-self-review.md
写入上述内容
使用时在提示词中明确提及：「使用财务分析自我审查 Skill 检查这份报告」

故障排除

如果 Opencode 没有自动使用该 Skill，尝试： 1. 确认文件名和路径正确 2. 在提示词中明确提及 Skill 名称 3. 重启 Opencode 会话

方式三：ultrathink 深度反思

对于重要输出，使用 ultrathink 进行深度反思：

ultrathink 请对上述分析进行深度审查，从数据、逻辑、风险、合规四个维度检查，列出所有可能的问题。

5.6.2 推理技术配置

Extended Thinking 模式

使用思考关键词触发深度推理：

ultrathink 请分析这家公司的估值是否合理，需要考虑：
- 历史估值区间
- 可比公司估值
- 成长性溢价
- 风险折价

推理 Skill 模板

创建结构化的推理 Skill：

# Skill: 投资价值分析

## 分析框架

### 第一步：基本面分析
- 业务模式
- 竞争优势
- 财务状况

### 第二步：估值分析
- 绝对估值
- 相对估值
- 安全边际

### 第三步：风险评估
- 业务风险
- 财务风险
- 市场风险

### 第四步：综合结论
- 投资评级
- 目标价格
- 关键假设

ReAct 模式实现

结合工具调用实现 ReAct：

请使用ReAct模式分析这只股票，每一步都说明你的思考，然后执行相应操作。

可用工具：
- 搜索财务数据
- 查询行业信息
- 计算估值指标

请按 Thought → Action → Observation 的格式展开分析。

5.6.3 规划工具使用

TodoWrite 工具

TodoWrite 是 Opencode 内置的任务管理工具，用于分解和跟踪复杂任务：

任务状态符号：
◯ pending（待处理）
◐ in_progress（进行中）
● completed（已完成）

适用场景： - 复杂的多步骤任务（3 个以上步骤） - 涉及多个文件修改的操作 - 需要系统化跟踪进度的项目

使用示例：

我需要完成以下任务：
1. 收集公司财务数据
2. 进行杜邦分析
3. 对比行业水平
4. 撰写分析报告

请创建任务列表并开始执行。

Plan Mode 规划模式

按 Shift+Tab 在不同模式间循环切换。模式切换顺序：

default → acceptEdits → plan → bypassPermissions → default

切换时，Opencode 会在界面显示当前模式。进入 Plan Mode 后，Opencode 会显示 Plan Mode 标识。

快捷键记忆

1 次 Shift+Tab：进入 acceptEdits（自动接受编辑）
2 次 Shift+Tab：进入 plan（只读规划模式）
3 次 Shift+Tab：进入 bypassPermissions（跳过所有确认，需安全环境）
4 次 Shift+Tab：返回 default（每次确认）

建议在复杂任务开始前，先按 2 次 Shift+Tab 进入 Plan Mode 制定方案。

在 Plan Mode 下，Opencode 只进行只读操作和规划分析，不会执行写操作。

Plan Mode 工作流： 1. 分析任务需求 2. 读取相关代码和文件 3. 制定详细计划 4. 等待用户确认 5. 确认后切换到执行模式

最佳实践：复杂任务先进入 Plan Mode 制定方案，确认后再执行，避免方向错误导致返工。

5.6.4 护栏机制配置

Hooks 机制

Opencode 的 Hooks 允许在特定事件发生时执行自定义逻辑：

事件类型	触发时机	用途
PreToolUse	工具执行前	验证参数、阻止危险操作
PostToolUse	工具执行后	格式化输出、记录日志
Stop	响应结束时	任务完成统计
Notification	发出通知时	外部告警集成

Hooks 匹配规则

matcher 字段支持以下匹配模式：

精确匹配："Bash" 匹配 Bash 工具的所有调用
通配符匹配："*" 匹配所有工具
参数匹配："Bash(rm:*)" 匹配包含 rm 命令的 Bash 调用
正则匹配："Bash(/rm\\s+-rf/)" 使用正则表达式匹配（注意 JSON 中反斜杠需转义）

Hooks 通过 opencode.json 配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python ~/.config/opencode/hooks/check_command.py"
          }
        ]
      }
    ]
  }
}

审计日志示例

记录所有工具调用，便于事后审计：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date) PRE: $TOOL_NAME\" >> ~/.config/opencode/audit.log"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date) POST: $TOOL_NAME\" >> ~/.config/opencode/audit.log"
          }
        ]
      }
    ]
  }
}

5.6.5 人在回路实现

权限控制系统

Opencode 提供分层的权限控制：

模式	说明
default	首次使用每个工具时提示权限
acceptEdits	自动接受文件编辑权限
plan	计划模式 - 只分析不执行
bypassPermissions	跳过所有权限提示（需安全环境）

切换方式：按 Shift+Tab 在模式间循环切换。

工具权限配置

通过 opencode.json 的 permission 字段配置工具权限，允许或禁止特定工具自动执行：

{
  "permission": {
    "allow": ["Read", "Grep", "Glob"],
    "deny": ["Bash(rm:*)", "Bash(sudo:*)"]
  }
}

AskUserQuestion 机制

Opencode 可以主动暂停执行并询问用户：

场景：执行敏感操作前

Opencode: 即将删除 /data/old_logs 目录下所有文件，共 1,234 个。
        确认执行吗？

[确认] [取消] [查看文件列表]

这种交互让用户保持对关键操作的控制权。

5.6.6 多模式组合实践

实际任务往往需要组合使用多种增强模式。以下是一个完整的工作流示例：

场景：完成一份投资分析报告

第一步：Plan Mode + ultrathink（深度规划）
进入 Plan Mode，请求：
ultrathink 分析"某公司投资价值"这个任务，制定详细的分析框架和写作计划

第二步：TodoWrite（任务分解）
确认计划后，创建任务列表：
◐ 收集财务数据和行业资料
◯ 分析业务模式和竞争优势
◯ 评估财务状况
◯ 进行估值分析
◯ 撰写投资建议

第三步：CoT + 反思（执行分析）
逐个完成任务，使用链式思维展示分析过程
每完成一部分，进行自我审查

第四步：护栏检查（合规验证）
输出前检查：
- 无收益承诺表述
- 风险提示充分
- 数据来源标注

第五步：HITL（人工确认）
Opencode: 报告初稿已完成。请确认：
        [定稿输出] [需要修改] [重新分析]

阶段	使用的增强模式	作用
规划	Plan Mode + ultrathink	深度思考，制定全面计划
分解	TodoWrite	任务拆解，进度跟踪
分析	CoT + 反思	系统推理，质量保证
检查	护栏机制	合规验证，风险控制
确认	HITL	人工把关，最终决策

组合策略建议

任务类型	推荐组合
多步骤实现	TodoWrite + Plan Mode
复杂调试	ultrathink + 反思
安全敏感操作	Hooks + HITL
长期项目	TodoWrite + AGENTS.md + Hooks

--- title: "5.6 Opencode 增强实践" --- 前面五节讲解了智能增强的原理，本节展示如何在 Opencode 中落地实践。 ### 5.6.1 反思机制实现在 Opencode 中实现反思有三种方式： **方式一：Self-Critique Prompts 嵌入 AGENTS.md** 在项目的 AGENTS.md 文件中加入反思指令，让每次输出都经过自我检查： ```markdown ## 输出质量规范每次生成内容后，请执行以下自我审查： 1. 检查数据准确性：引用是否正确、是否最新 2. 检查逻辑完整性：推理是否有跳跃 3. 检查风险披露：是否充分说明了风险 4. 检查用词合规：是否避免了不当承诺如发现问题，自行修正后输出。 ``` **方式二：专用反思 Skill** 创建一个专门用于反思的 Skill，在需要时调用： ```markdown # Skill: 财务分析自我审查 ## 触发条件当完成财务分析相关输出后 ## 审查维度 - 计算准确性：各指标计算是否正确 - 数据时效性：使用的是否是最新数据 - 分析完整性：是否涵盖关键维度 - 结论支撑度：结论是否有充分依据 ## 输出格式列出发现的问题和改进后的版本 ``` **Skill 创建步骤**： 1. 在项目根目录创建 `.opencode/skills/` 目录（如不存在） 2. 创建 Skill 文件 `.opencode/skills/financial-self-review.md` 3. 写入上述内容 4. 使用时在提示词中明确提及：「使用财务分析自我审查 Skill 检查这份报告」 ::: {.callout-caution} ## 故障排除如果 Opencode 没有自动使用该 Skill，尝试： 1. 确认文件名和路径正确 2. 在提示词中明确提及 Skill 名称 3. 重启 Opencode 会话 ::: **方式三：ultrathink 深度反思** 对于重要输出，使用 ultrathink 进行深度反思： ``` ultrathink 请对上述分析进行深度审查，从数据、逻辑、风险、合规四个维度检查，列出所有可能的问题。 ``` ### 5.6.2 推理技术配置 **Extended Thinking 模式** 使用思考关键词触发深度推理： ``` ultrathink 请分析这家公司的估值是否合理，需要考虑： - 历史估值区间 - 可比公司估值 - 成长性溢价 - 风险折价 ``` **推理 Skill 模板** 创建结构化的推理 Skill： ```markdown # Skill: 投资价值分析 ## 分析框架 ### 第一步：基本面分析 - 业务模式 - 竞争优势 - 财务状况 ### 第二步：估值分析 - 绝对估值 - 相对估值 - 安全边际 ### 第三步：风险评估 - 业务风险 - 财务风险 - 市场风险 ### 第四步：综合结论 - 投资评级 - 目标价格 - 关键假设 ``` **ReAct 模式实现** 结合工具调用实现 ReAct： ``` 请使用ReAct模式分析这只股票，每一步都说明你的思考，然后执行相应操作。可用工具： - 搜索财务数据 - 查询行业信息 - 计算估值指标请按 Thought → Action → Observation 的格式展开分析。 ``` ### 5.6.3 规划工具使用 **TodoWrite 工具** TodoWrite 是 Opencode 内置的任务管理工具，用于分解和跟踪复杂任务： ``` 任务状态符号： ◯ pending（待处理） ◐ in_progress（进行中） ● completed（已完成） ``` 适用场景： - 复杂的多步骤任务（3 个以上步骤） - 涉及多个文件修改的操作 - 需要系统化跟踪进度的项目使用示例： ``` 我需要完成以下任务： 1. 收集公司财务数据 2. 进行杜邦分析 3. 对比行业水平 4. 撰写分析报告请创建任务列表并开始执行。 ``` **Plan Mode 规划模式** 按 Shift+Tab 在不同模式间循环切换。模式切换顺序： ``` default → acceptEdits → plan → bypassPermissions → default ``` 切换时，Opencode 会在界面显示当前模式。进入 Plan Mode 后，Opencode 会显示 Plan Mode 标识。 ::: {.callout-tip} ## 快捷键记忆 - **1 次 Shift+Tab**：进入 acceptEdits（自动接受编辑） - **2 次 Shift+Tab**：进入 plan（只读规划模式） - **3 次 Shift+Tab**：进入 bypassPermissions（跳过所有确认，需安全环境） - **4 次 Shift+Tab**：返回 default（每次确认）建议在复杂任务开始前，先按 2 次 Shift+Tab 进入 Plan Mode 制定方案。 ::: 在 Plan Mode 下，Opencode 只进行只读操作和规划分析，不会执行写操作。 Plan Mode 工作流： 1. 分析任务需求 2. 读取相关代码和文件 3. 制定详细计划 4. 等待用户确认 5. 确认后切换到执行模式最佳实践：复杂任务先进入 Plan Mode 制定方案，确认后再执行，避免方向错误导致返工。 ### 5.6.4 护栏机制配置 **Hooks 机制** Opencode 的 Hooks 允许在特定事件发生时执行自定义逻辑： | 事件类型 | 触发时机 | 用途 | |----------|----------|------| | PreToolUse | 工具执行前 | 验证参数、阻止危险操作 | | PostToolUse | 工具执行后 | 格式化输出、记录日志 | | Stop | 响应结束时 | 任务完成统计 | | Notification | 发出通知时 | 外部告警集成 | **Hooks 匹配规则** `matcher` 字段支持以下匹配模式： - **精确匹配**：`"Bash"` 匹配 Bash 工具的所有调用 - **通配符匹配**：`"*"` 匹配所有工具 - **参数匹配**：`"Bash(rm:*)"` 匹配包含 `rm` 命令的 Bash 调用 - **正则匹配**：`"Bash(/rm\\s+-rf/)"` 使用正则表达式匹配（注意 JSON 中反斜杠需转义） Hooks 通过 `opencode.json` 配置： ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "python ~/.config/opencode/hooks/check_command.py" } ] } ] } } ``` **审计日志示例** 记录所有工具调用，便于事后审计： ```json { "hooks": { "PreToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "echo \"$(date) PRE: $TOOL_NAME\" >> ~/.config/opencode/audit.log" } ] } ], "PostToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "echo \"$(date) POST: $TOOL_NAME\" >> ~/.config/opencode/audit.log" } ] } ] } } ``` ### 5.6.5 人在回路实现 **权限控制系统** Opencode 提供分层的权限控制： | 模式 | 说明 | |------|------| | default | 首次使用每个工具时提示权限 | | acceptEdits | 自动接受文件编辑权限 | | plan | 计划模式 - 只分析不执行 | | bypassPermissions | 跳过所有权限提示（需安全环境） | 切换方式：按 Shift+Tab 在模式间循环切换。 **工具权限配置** 通过 `opencode.json` 的 `permission` 字段配置工具权限，允许或禁止特定工具自动执行： ```json { "permission": { "allow": ["Read", "Grep", "Glob"], "deny": ["Bash(rm:*)", "Bash(sudo:*)"] } } ``` **AskUserQuestion 机制** Opencode 可以主动暂停执行并询问用户： ``` 场景：执行敏感操作前 Opencode: 即将删除 /data/old_logs 目录下所有文件，共 1,234 个。确认执行吗？ [确认] [取消] [查看文件列表] ``` 这种交互让用户保持对关键操作的控制权。 ### 5.6.6 多模式组合实践实际任务往往需要组合使用多种增强模式。以下是一个完整的工作流示例： **场景：完成一份投资分析报告** ``` 第一步：Plan Mode + ultrathink（深度规划）进入 Plan Mode，请求： ultrathink 分析"某公司投资价值"这个任务，制定详细的分析框架和写作计划第二步：TodoWrite（任务分解）确认计划后，创建任务列表： ◐ 收集财务数据和行业资料 ◯ 分析业务模式和竞争优势 ◯ 评估财务状况 ◯ 进行估值分析 ◯ 撰写投资建议第三步：CoT + 反思（执行分析）逐个完成任务，使用链式思维展示分析过程每完成一部分，进行自我审查第四步：护栏检查（合规验证）输出前检查： - 无收益承诺表述 - 风险提示充分 - 数据来源标注第五步：HITL（人工确认） Opencode: 报告初稿已完成。请确认： [定稿输出] [需要修改] [重新分析] ``` | 阶段 | 使用的增强模式 | 作用 | |------|----------------|------| | 规划 | Plan Mode + ultrathink | 深度思考，制定全面计划 | | 分解 | TodoWrite | 任务拆解，进度跟踪 | | 分析 | CoT + 反思 | 系统推理，质量保证 | | 检查 | 护栏机制 | 合规验证，风险控制 | | 确认 | HITL | 人工把关，最终决策 | ::: {.callout-tip} ## 组合策略建议 | 任务类型 | 推荐组合 | |----------|----------| | 多步骤实现 | TodoWrite + Plan Mode | | 复杂调试 | ultrathink + 反思 | | 安全敏感操作 | Hooks + HITL | | 长期项目 | TodoWrite + AGENTS.md + Hooks | :::