6. 综合练习

这是什么：工作流 = 一套固定下来、能重复执行的协作流程——从「装好工具」到「让 opencode 按你的规矩长期干活」。

为什么用：前面五章的零件单看都好用，串起来才发现缝隙：AGENTS.md 没提交、agent 权限开太大、上下文越聊越满……这些坑不走一遍完整流程就踩不到。

如何用：本章按四步走完一个真项目，每步都有验收标准，最后给一张翻车排查表。

6.1 目标与验收清单

目标：给一个真实仓库（哪怕是你自己的小项目）配出一套「进项目就能开工」的 opencode 环境。

第 1 步：opencode --version 有输出，/models 能列出模型
第 2 步：仓库根目录有 AGENTS.md，已提交 Git
第 3 步：有一个自己的 agent 和一条自己的斜杠命令
第 4 步（选做）：接上至少一个 MCP，opencode mcp list 显示 connected

6.2 第 1 步：装好、接上模型

opencode --version
opencode auth login
opencode models

你会看到（示意）：

1.19.3
  ✓ anthropic
  anthropic/claude-sonnet-4-5
  anthropic/claude-haiku-4-5

然后在全局配置 ~/.config/opencode/opencode.json 里定下默认模型：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

确认一下配置被读到：

$ opencode debug config
{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

6.3 第 2 步：写一份真的 AGENTS.md

进项目、启动、/init，然后手改它。判断标准很简单：换个人来看，照着这份文件能不能立刻上手。

# 项目说明

## 这是什么
个人博客，静态站用 Python 构建（`v2/`），后端 FastAPI，数据存在 SQLite。

## 常用命令
- 装依赖：uv sync
- 构建站点：python v2/build.py --all
- 本地预览：python -m http.server 8931 --directory v2/dist
- 跑测试：uv run pytest -q

## 目录约定
- docs/ 是内容源，改章节在 docs/<栏目>/ 下新建 .md
- v2/ 是站点构建：nav.json（导航）、template/、assets/、tools/
- 改完必须跑一次 python v2/build.py --all && python v2/tools/check_site.py

## 代码约定
- 正文一律简体中文，英文术语首次出现要加中文解释
- 代码块里的引号和括号用英文标点
- 改完必须跑一次 python v2/build.py --all && python v2/tools/check_site.py

改完提交：

git add AGENTS.md
git commit -m "chore: add AGENTS.md for opencode"

你会看到（示意）：

[main 3f9c1a2] chore: add AGENTS.md for opencode
 1 file changed, 24 insertions(+)

6.4 第 3 步：造 agent 和命令

写 .opencode/agents/reviewer.md——一个只读评审员：

---
description: 审查改动，只读不改
mode: subagent
temperature: 0.1
permission:
  edit: deny
  shell:
    "*": deny
    "git diff*": allow
---

只输出问题清单，不改任何文件。每条给出文件路径和行号。

写 .opencode/commands/changelog.md：

---
description: 总结最近改动
---

最近的提交：!`git log --oneline -10`
按「新增 / 修复 / 破坏性变更」三段总结，只基于上面的提交内容。

验收：在 TUI 里敲 /changelog 能出结果；消息里 @reviewer 能叫出评审员，并且它改不了文件。

6.5 第 4 步：接一个 MCP（选做）

opencode mcp add
opencode mcp list

你会看到（示意）：

  context7  connected  (12 tools)

接完就在 AGENTS.md 里补一条规则，让它养成用 MCP 的习惯：

## 工具约定
查第三方库的最新用法时，用 context7 工具查官方文档，不要凭记忆猜。

6.6 常见翻车现场

现象	原因	修法
模型列表是空的	还没登录提供商	`opencode auth login`，或 TUI 里 `/connect`
`/undo` 没反应	项目不是 Git 仓库	`git init` 后再试
agent 改文件了	`permission` 里 `edit` 是 `allow`	改成 `deny`
上下文越聊越满	工具太多 + 对话太长	关掉用不上的 MCP；`/compact` 压缩
MCP 一直显示 failed	本地命令没跑起来 / 远程要鉴权	`opencode mcp debug <名字>` 看详情
配置改了没生效	改的不是当前生效的那份	`opencode debug config` 看最终合并结果

动手改

把第 3 步的 reviewer agent 再加一个 security-auditor：只允许读文件，专门找注入、越权、密钥硬编码三类问题。
给你的项目加一条 docs:build 的自定义命令：跑构建，失败时把完整报错贴给你并给出修复建议。
装两个 MCP，然后按 agent 把它们拆开：researcher 只能用文档那个，debugger 只能用监控那个，然后故意问一个需要两个 MCP 配合的问题，看看模型怎么选。

小结

四步走完：装好接模型 → 写 AGENTS.md → 造 agent 和命令 → 接 MCP
AGENTS.md 是整套工作流的基石，手改、提交、持续维护
agent 的价值一半在提示词，一半在权限边界
MCP 接完要写进 AGENTS.md，模型才会主动去用
出问题先跑 opencode debug config 和 opencode mcp list，八成能定位

到这里你就有了一个属于自己的 AI 结对程序员：装在终端里、认得你的项目、懂你的规矩、能接外部工具。往后想升级，看官方文档的 Agents、Commands、MCP servers 三页就够 🐸