opencode

OpenCode 子 Agent 协议

这是一套用于委派任务给 OpenCode Agent 的可执行协议。请严格遵循。

前提条件

• 已安装 opencode CLI，且位于 PATH 中（验证方式：opencode --version）
• 至少有一个提供商已完成身份验证（opencode providers list）
• 可用模型可通过 opencode models 列出

核心命令

OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json --model <provider/model> --agent <build|plan> --dir "<working-dir>" --dangerously-skip-permissions [options] "<prompt>" 2>/dev/null

关键标志：

• --format json —— 输出便于机器解析的 ndjson（始终使用此选项）
• --model provider/model —— 例如，openai/gpt-5.4、openai/gpt-5.3-codex
• --variant <level> —— 推理力度：minimal、medium、high、xhigh（因提供商而异）
• --dir <path> —— 任务的工作目录
• --dangerously-skip-permissions —— 自动批准工具调用（无头模式下必需）
• -f/--file <path> —— 将文件附加到提示词
• --agent <name> —— 实现时使用 build（文件系统 + bash），分析时使用 plan（只读）
• -c/--continue —— 继续上一个会话
• -s/--session <id> —— 继续指定会话

输出解析

--format json 标志会输出 ndjson（每行一个 JSON 对象）：

type	包含内容
text	.part.text —— 模型的文本回复
tool_call	.part.name、.part.input —— 工具调用
tool_result	.part.output —— 工具执行结果
step_start	会话 / 消息 ID
step_finish	.part.tokens（用量）、.part.cost、.part.reason

使用辅助脚本进行解析（始终重定向 stderr）：

opencode run --format json ... 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py [--mode text|full|tools|cost|session|diff|summary]

解析模式：

• text —— 模型的文本回复（默认）
• full —— 文本 + 工具调用 + 工具结果
• tools —— 仅工具调用和结果
• cost —— Token 用量和费用明细
• session —— 提取用于继续会话的会话 ID
• diff —— 从工具调用中提取文件修改
• summary —— 单行摘要（状态、Token、费用、耗时）

---

任务协议

根据用户请求确定任务类型，然后遵循相应协议。

协议 1：实现

当用户希望 OpenCode 编写或修改代码时使用。

步骤：

1. 范围 —— 明确要创建 / 修改的文件。逐一列出。
2. 上下文 —— 收集 Agent 需要查看的文件。使用 -f 附加。
3. 约束 —— 构建约束块（见下文的提示词工程）。
4. 执行 —— 使用 --agent build 运行：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4 --agent build \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     -f <file1> -f <file2> \
     "<prompt>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py --mode full
   

5. 验证 —— 阅读每个修改过的文件。检查正确性、约定和编译情况。
6. 报告 —— 总结更改内容，并指出任何可疑之处。

默认模型： openai/gpt-5.4 | 超时： timeout: 300000

协议 2：审查

当用户希望获得关于代码质量、Bug 或正确性的第二意见时使用。

步骤：

1. 目标 —— 确定要审查的文件。
2. 执行 —— 使用 --agent plan 运行（只读）：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4 --variant high --agent plan \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     -f <file1> "<review prompt>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py
   

3. 呈现 —— 向用户转达发现，并附上文件:行号引用。

默认模型： openai/gpt-5.4 + --variant high | 超时： timeout: 300000

协议 3：调试

当用户希望 OpenCode 调查 Bug 或错误时使用。

步骤：

1. 证据 —— 收集错误消息、堆栈跟踪和相关代码。
2. GAS 上下文 —— 对于 GAS Bug，指示 Agent 检查：标签阻止 / 要求、效果应用 / 移除顺序、MMC 依赖项、ASC 初始化时序。
3. 执行 —— 使用 --agent plan 运行：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.3-codex --variant high --agent plan \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     "<diagnostic prompt>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py
   

4. 分析 —— 在呈现之前，结合实际代码交叉核实发现。

默认模型： openai/gpt-5.3-codex + --variant high | 超时： timeout: 300000

协议 4：研究

当用户希望 OpenCode 探索并分析代码库时使用。

步骤：

1. 问题 —— 拟定清晰且范围明确的研究问题。
2. 执行 —— 使用 --agent plan 运行：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4-mini-fast --agent plan \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     "<research question>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py
   

3. 验证 —— 亲自阅读所引用的文件，抽查相关主张。

默认模型： openai/gpt-5.4-mini-fast | 超时： timeout: 300000

---

编排模式

这些模式将上述基本协议组合成更强大的工作流。 当任务适合多步验证或并行执行时，请使用它们。

模式 A：先实现，再审查

适用场景： 对质量有要求的实现任务。这是非简单实现任务的默认模式。

流程：

1. 使用 --agent build 运行 协议 1（实现）
2. 自行阅读并验证更改（快速进行合理性检查）
3. 使用不同的模型，对已更改的文件运行 协议 2（审查）：
   • 如果实现使用了 openai/gpt-5.4，则使用 openai/gpt-5.3-codex 进行审查
   • 跨模型审查可以发现特定模型的盲点
4. 质量关卡： 如果审查发现严重问题，请修复（自行修复，或重新运行实现并附上修复说明）
5. 向用户报告实现和审查结果

模式 B：多模型并行审查

适用场景： 用户希望进行全面验证，或表示“征求多个意见”。

流程：

1. 构造一次审查提示词
2. 并行启动 Bash 命令（使用 run_in_background 或 &）：

   # Run in parallel -- each to a temp file
   PROMPT="<review prompt>"
   DIR="C:/UnrealEngine/VHS"
   
   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4 --variant high --agent plan \
     --dir "$DIR" --dangerously-skip-permissions "$PROMPT" \
     2>/dev/null > /tmp/review_gpt54.txt &
   
   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.3-codex --variant high --agent plan \
     --dir "$DIR" --dangerously-skip-permissions "$PROMPT" \
     2>/dev/null > /tmp/review_codex.txt &
   
   wait
   

3. 分别解析每个结果：

   cat /tmp/review_gpt54.txt | python .claude/skills/opencode/scripts/parse_output.py
   cat /tmp/review_codex.txt | python .claude/skills/opencode/scripts/parse_output.py
   

4. 综合分析——区分多个模型都指出的问题（可信度高）和单个模型指出的问题（可信度较低），并给出统一报告。

模式 C：自主改进循环

适用场景： 用户希望迭代改进代码，或表示“继续改进这个”“优化”“润色”。

灵感来自 autoresearch 的迭代实验循环。Agent 会进行更改、验证更改、保留改进，并回退失败的更改。

流程：

LOOP (max N iterations, default 3):
  1. Identify the current quality baseline (read code, note issues)
  2. Construct an improvement prompt targeting the worst issue
  3. Run Protocol 1 (Implement) with --agent build
  4. Validate: read changed files, check for regressions
  5. Run Protocol 2 (Review) on changed files with a different model
  6. QUALITY GATE:
     - If review passes (no critical issues) → keep changes, report improvement
     - If review fails (critical issues found) → revert changes (git checkout the files), report why
  7. If no more meaningful improvements found → STOP
  8. Continue to next iteration

重要限制：

• 始终设置最大迭代次数（默认 3 次，用户可指定更多）
• 每次迭代都必须针对具体、可衡量的改进
• 失败时回退——绝不累积有问题的更改
• 如果改进幅度变得微不足道，则提前停止
• 报告每次迭代的结果，让用户了解进度

模式 D：后台 Agent

适用场景： Claude Code 需要在 OpenCode 运行时继续处理其他工作。适用于不会阻塞对话的长时间运行任务。

流程：

1. 使用 Bash 运行 OpenCode 命令，并设置 run_in_background: true：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4 --agent plan \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     "<prompt>" 2>/dev/null > /tmp/opencode_result.txt
   

2. 等待通知期间继续处理其他工作
3. 收到通知后，解析结果：

   cat /tmp/opencode_result.txt | python .claude/skills/opencode/scripts/parse_output.py
   

4. 向用户展示结果

模式 E：会话延续（多步工作流）

适用场景： 通过多轮交互逐步积累上下文的复杂任务。

流程：

1. 运行第一个任务并记录会话 ID：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --model openai/gpt-5.4 --agent plan \
     --dir "C:/UnrealEngine/VHS" --dangerously-skip-permissions \
     "<first task>" 2>/dev/null | tee /tmp/oc_step1.txt | python .claude/skills/opencode/scripts/parse_output.py --mode session
   

2. 使用会话 ID 执行后续任务：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --session "<session-id>" --dangerously-skip-permissions \
     "<follow-up task>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py
   

   或使用 --continue 延续上一个会话：

   OPENCODE_DISABLE_AUTOUPDATE=true opencode run --format json \
     --continue --dangerously-skip-permissions \
     "<follow-up task>" 2>/dev/null | python .claude/skills/opencode/scripts/parse_output.py
   

模式 F：Git 检查点实现

适用场景： 回滚安全至关重要的高风险实现。

灵感来自 autoresearch 的 git 即状态机模式。

流程：

1. 创建检查点——记录当前 git 状态：

   git stash  # or commit current work
   

2. 使用 --agent build 运行 协议 1（实现）
3. 验证——阅读所有已更改的文件，并在适用时运行构建和测试
4. 关卡：
   • 如果更改正确 → 保留更改并报告成功
   • 如果更改有误 → 回退：

     git checkout -- <modified-files>
     

   • 报告出了什么问题，以及为何执行回退
5. 绝不留下有问题的更改——如果验证失败，报告前务必回退

---

提示词工程

OpenCode 无法访问本次对话的上下文。每个提示词都必须完整自包含。

请勿使用 OpenCode 调用 Claude/Anthropic 模型或 Google/Gemini 模型——这些提供方在 OpenCode 中不可用。只能使用 OpenAI、GitHub Copilot、本地模型和 OpenCode 自带的模型。

提示词结构（必需）

发送给 OpenCode 的每个提示词都必须遵循以下结构：

[CONTEXT BLOCK]
<project type, conventions, key constraints>

[TASK]
<imperative description of what to do>

[SCOPE]
<explicit boundaries: which files/dirs to touch, which to ignore>

[CONSTRAINTS]
<naming conventions, patterns to follow, things to avoid>

[OUTPUT FORMAT]
<what form the response should take>

UE5/VHS 上下文块（项目任务始终包含）

This is an Unreal Engine 5.7 C++ project (VHS - first-person horror game).
Source: Source/VHS/  |  Module: VHS  |  No Public/Private split (side-by-side .h/.cpp)

Naming conventions:
- UE prefixes: A (actors), U (UObjects), F (structs), E (enums), I (interfaces)
- GAS: GA_ (abilities), GC_ (cues), MMC_ (magnitude calcs), GE_ (effects)
- Booleans: b prefix (bIsRecovering)
- #pragma once, CoreMinimal.h first, .generated.h last

Key systems: GAS (AbilitySystem/), Enhanced Input, StateTree (AI)
Dependencies: GameplayAbilities, GameplayTags, GameplayTasks, EnhancedInput, StateTreeModule

范围约束（避免超时的关键）

始终明确设定范围边界。宽泛的提示词会导致 Agent 探索整个文件系统并超时。

良好示例：

Search ONLY in Source/VHS/AbilitySystem/. Do NOT explore other directories.
Modify ONLY HorrorCharacter.h and HorrorCharacter.cpp. Do NOT touch other files.

不良示例：

Look through the project and find issues.  (too broad -- will timeout)

实现提示词模板

[CONTEXT]
This is an Unreal Engine 5.7 C++ project (VHS). <conventions block>

[TASK]
Implement <feature> in <file(s)>.
<detailed requirements>

[SCOPE]
- Create/modify ONLY: <explicit file list>
- Reference (read-only): <files to read for context>
- Do NOT touch: <exclusions>

[CONSTRAINTS]
- Follow existing patterns in <reference file>
- Use UPROPERTY(EditDefaultsOnly, Category = "<Category>") for configurable values
- All new UObject classes need UCLASS(ClassGroup=(VHS)) macro
- Header: #pragma once, CoreMinimal.h first, .generated.h last

[OUTPUT]
Write the implementation directly. No explanations needed.

审查提示词模板

[CONTEXT]
This is an Unreal Engine 5.7 C++ project using GAS. <conventions block>

[TASK]
Review the following files for: correctness, bugs, performance, security, UE5 best practices.
Be specific: cite file paths and line numbers. Suggest concrete fixes.

[SCOPE]
Review ONLY: <file list>
Do NOT explore other directories.

[OUTPUT FORMAT]
For each issue found:
- **[SEVERITY]** (critical/warning/info)
- **File:Line** -- specific location
- **Issue** -- what's wrong
- **Fix** -- concrete solution

调试提示词模板

[CONTEXT]
UE5.7 project (VHS) using GAS. <conventions block>

[BUG REPORT]
<symptom description>
<error messages / stack traces>
<reproduction steps if known>

[TASK]
Investigate root cause. Check:
- <specific things to check based on the bug>
- For GAS bugs: tag blocking, effect ordering, MMC deps, ASC init timing

[SCOPE]
Search ONLY in: <directory>

[OUTPUT FORMAT]
1. Root cause (most likely)
2. Evidence (file:line references)
3. Fix (concrete code changes)

---

模型选择

为任务选择合适的模型。完整指南请参阅 references/models.md。

快速默认选项：

任务	快速	默认	深度
实现	openai/gpt-5.4-mini-fast	openai/gpt-5.4	openai/gpt-5.3-codex
审查	openai/gpt-5.4-mini	openai/gpt-5.4 + --variant high	openai/gpt-5.3-codex + --variant high
调试	openai/gpt-5.4-mini-fast	openai/gpt-5.3-codex + --variant high	openai/gpt-5.4 + --variant xhigh
调研	openai/gpt-5.4-mini-fast	openai/gpt-5.4-fast	openai/gpt-5.4

使用 opencode models 查看所有可用模型。仅支持 OpenAI、GitHub Copilot、OpenCode 自有的免费层级模型，以及本地模型（Ollama/LM Studio）。

跨模型审查配对（用于流水线模式 A）：

• 使用 openai/gpt-5.4 实现 → 使用 openai/gpt-5.3-codex 审查
• 使用 openai/gpt-5.3-codex 实现 → 使用 openai/gpt-5.4 审查
• 审查时务必使用与实现不同的模型

注重成本的替代方案：

• github-copilot/gpt-5.4 —— Copilot 订阅免费
• github-copilot/gpt-5.3-codex —— Copilot 订阅免费
• opencode/big-pickle —— OpenCode 自有的免费层级
• 本地：ollama/qwen3-coder:latest —— API 成本为零

---

错误处理与恢复

错误检测

症状	原因	恢复措施
找不到 opencode	尚未安装	告知用户：npm i -g opencode
未配置提供商	未进行身份验证	告知用户：opencode providers login
模型不可用	模型 ID 错误	运行 opencode models，推荐替代选项
超时（>3 分钟）	范围过宽	缩小范围约束，使用更快的模型
JSON 解析失败	输出损坏	使用 --format default 重试，读取原始文本
退出代码非零	运行时错误	检查 stderr（最多 500 个字符），重试一次
文本响应为空	Agent 只调用了工具	使用 --mode full 查看工具调用结果

自动模型回退

如果模型失败或超时，按以下顺序回退：

1. openai/gpt-5.4（主选）
2. openai/gpt-5.3-codex（针对代码优化）
3. openai/gpt-5.4-mini-fast（最快，始终可用）
4. github-copilot/gpt-5.4（免费层级）
5. opencode/big-pickle（OpenCode 免费层级）

崩溃恢复

如果 OpenCode 在实现过程中崩溃（--agent build）：

1. 检查哪些文件已被修改：git diff --name-only
2. 读取每个已修改文件，评估完成情况
3. 如果更改不完整或有问题 → git checkout -- <files>
4. 缩小范围或更换模型后重试
5. 向用户报告崩溃和恢复情况

---

决策框架

使用此框架决定何时以及如何调用 OpenCode：

User request received
  │
  ├─ "use opencode" / names a model → Use OpenCode (user explicit)
  │
  ├─ "second opinion" / "cross-validate" → Pattern B (Parallel Multi-Model)
  │
  ├─ "implement with X" → Protocol 1, optionally Pattern A (Implement-Then-Review)
  │
  ├─ "review with X" → Protocol 2
  │
  ├─ "keep improving" / "optimize" / "polish" → Pattern C (Autonomous Loop)
  │
  ├─ Complex implementation → Pattern A (Implement-Then-Review) by default
  │
  ├─ Risky changes → Pattern F (Git-Checkpoint)
  │
  └─ Long-running task, user wants to continue chatting → Pattern D (Background)

高级模式

请参阅 references/advanced.md，了解：

• 持久会话的服务器模式
• 用于自动化的环境变量
• 导出/导入会话
• 统计和成本跟踪