OpenCode学习笔记

这篇先作为 OpenCode 的长期学习笔记，不急着写成完整教程。后面关于 OpenCode 的配置、踩坑、Agent 设计、Skill 复用，都放在这里。

OpenCode 客户端的 Agent、Tool 与 Skill 架构

目前的理解

一开始我也容易把 OpenCode 当成一个更强的 autocomplete：描述需求，让它写代码，我 review 一遍再合并。

后来发现这个理解太窄。OpenCode 更值得用的地方不是“帮我写一段代码”，而是把工作拆成不同角色：有人负责想清楚需求，有人负责实现，有人只读审查，有人负责发布和验证。也就是说，重点不是让一个 Agent 变得全能，而是把项目里的常见工作分给合适的 Agent。

这里有一个容易混淆的点：Agent 和 Skill 不是同一个东西。

类型	作用	适合放什么
Agent	角色、权限边界、委派入口	reviewer、frontend delivery、release manager 这类“负责人”
Skill	可复用方法、流程、资料和脚本	审查流程、发布流程、TOEFL 训练流程、AgentInfra 资产发布流程

所以我现在更倾向于：Skill 做能力库，Agent 做调度员和权限边界。

如果只是固化一套方法，优先写 Skill；如果需要一个稳定角色、独立权限、可被 @ 拉进对话，才写 Agent。

本机 OpenCode 的全局 agent 放在：

~/.config/opencode/agents/

Skill 镜像放在：

~/.config/opencode/skills/

这里有一个原则：~/git/AgentInfra 仍然是 AgentInfra 管理类 Skill 的源头，OpenCode 的 skill 目录只是发现入口，尽量用软链接，不复制一份新的。

这次配置了 6 个 Agent：

Agent	什么时候用	权限设计	主要调用的 Skill
`@agentinfra-maintainer`	维护 AgentInfra skill、workflow、manifest、OpenCode skill 镜像	读自由，编辑和高风险命令 ask	`agentinfra-skill-authoring`、`workflow-local-skill-consolidation`、`workflow-agentinfra-asset-release`
`@quality-reviewer`	审查代码、diff、架构、AI-native 仓库成熟度、完成声明	只读，测试/验证命令 ask	`frontend-code-review`、`codebase-audit`、`ai-native-repo-audit`、`verification-gate`
`@frontend-delivery`	做前端 UI、浏览器检查、视觉证据	常见前端目录可编辑，依赖和高风险命令 ask	`workflow-frontend-production-delivery`、`frontend-design`、`browser-smoke-harness-template`
`@release-manager`	拆 commit、写提交信息、导出离线同步包、整理验证说明	Git 查看允许，提交/推送 ask，破坏性 Git deny	`commit-helper`、`gitlab-commit-batcher`、`git-offline-sync-export`
`@demand-researcher`	消化链接、整理想法、做需求/市场判断	允许 web research，写文件 ask	`valuable-demand-miner`、`link-notes-digester`、`first-principles-review`
`@toefl-coach`	跑 `sprint-practice` 的 TOEFL 训练和复盘	可编辑 `~/git/sprint-practice`，其他路径 ask	`toefl-sprint-router`、`qirifushu`、`shirizhongyan` 等

对应的说明文件在：

~/.config/opencode/agents/README.md

这次配置之后，我觉得后面加 Agent 要克制一点：

一个比较稳的判断标准是：

如果这个能力只是“怎么做”，它是 Skill；如果它还需要“谁来做、能不能改文件、能不能跑命令”，它才值得做成 Agent。

后面继续使用时，我重点看几件事：

如果这些 Agent 只是增加了一层复杂度，就应该删掉或合并。配置 Agent 的目的不是让列表变长，而是把常用工作流变得更稳。