如何在 opencode 中组织主代理、子代理与 Skill

在 opencode 里配了几个读论文的代理，顺手整理一下分工。这套配置主要处理两个问题：子代理读到主代理的草稿后跟着附和，以及装了太多 skill 后模型乱选。这篇讲配置怎么拆，论文阅读的具体例子放在另一篇。

配套文件：

• 完整示例配置：opencode-paper-suite.json
• 主代理示例：paper.agent.md.txt
• 子代理示例：reader-deep.agent.md.txt
• 仲裁代理示例：arbiter.agent.md.txt
• 诊断代理示例：diagnose.agent.md.txt
• Skill 示例：paper-reading.skill.md.txt
• 项目路由规则：AGENTS.routing.md.txt

几种配置分别放什么

Agent 文件写角色和任务范围，比如读论文、审代码、核对两份分析。Skill 写某类任务的做法，比如读实验表格时检查数据集、指标和消融。工具能不能调用，则在权限配置里限制。

例如，给审阅代理写一句“只读文件”还不够，配置里也要拒绝编辑和执行命令。

推荐结构

1
2
3
4
5
6
7
8
9
10
11

your-project/
├── opencode.json
├── AGENTS.md
└── .opencode/
    ├── agents/
    │   ├── main.md
    │   ├── reviewer.md
    │   └── researcher.md
    └── skills/
        └── some-skill/
            └── SKILL.md

适合所有项目的能力放全局，只适合当前项目的规则放项目里。项目配置会覆盖全局配置。

主代理：负责收口

主代理用 mode: primary，负责和用户对话、拆任务、派活，最后验货收口。子代理的结果也要检查，尤其是引用位置、执行结果和互相矛盾的结论，不能原样拼进答案。

子代理：只做窄任务

子代理用 mode: subagent。找某个功能的实现、查一组资料、独立审阅方案，都可以单独派出去。需要跟用户反复确认的事留给主代理；一两行的小改动也没必要多开一个代理。

派活时写清楚读哪些材料、查什么、返回什么。比如“核对表 3 的提升是否来自同一测试集，返回原文位置和判断”，就比“检查一下论文”容易验收。要求独立阅读时，只给原文和问题，别把主代理的结论一起塞过去。

审阅、阅读、仲裁类子代理通常只需要读权限。实现类子代理可以写，但要说明能改哪些文件。

Skill：沉淀方法

Skill 放在：

1

.opencode/skills/my-skill/SKILL.md

文件开头的 front-matter 要有 name 和 description，正文放流程、模板和检查项。description 写明适用的任务，例如“阅读论文 PDF，核对实验与消融，整理带原文位置的笔记”，方便模型判断何时加载。

限制 Skill

装了很多 skill 后，模型看到一长串描述，容易选错。（尤其是 Gemini 这种蠢家伙）论文代理可以先拒绝全部，只放开阅读和画图需要的几个。deny 会隐藏对应 skill，也会拒绝加载；允许的 skill 只展示名称和描述，正文按需读取，详见 官方说明。

配套配置采用了这种白名单写法：opencode-paper-suite.json。

权限设计

这套阅读配置的权限是：

• 读文件、搜索文件：全允许。
• 访问网络：询问。
• 写文件：询问。
• shell 命令：询问，只放行安全查看命令。
• 子代理：按角色收窄权限。

其中阅读、仲裁和诊断代理拒绝写文件、运行命令及继续派生任务。需要别的权限时，再按用途改。

AGENTS.md：写项目规则

AGENTS.md 写项目共用的规则：哪些任务需要独立核查，何时调用仲裁代理，哪些操作禁止，以及交付前要检查什么。单个代理的职责放回它自己的配置文件，免得改一处还要同步几份。

下载示例：AGENTS.routing.md.txt。

放在一起看

1
2
3
4
5
6
7
8
9

主代理：理解意图，拆任务，收口
├── 探索子代理：找资料、找代码、摸结构
├── 实现子代理：按明确计划改文件
├── 审阅子代理：独立检查风险
└── 仲裁子代理：分歧时按证据裁决

Skills：提供任务方法
Permissions：限制工具边界
AGENTS.md：规定调度纪律

以论文 Agent 为例

配套文章里，论文 Agent 系统拆成：

1
2
3
4
5

paper 主代理
├── reader-deep：独立阅读子代理
├── arbiter：仲裁
├── diagnose：诊断
└── paper-reading skill：论文阅读流程

完整教程见：Paper-Agent 在 opencode 中的实现。

刚开始配时，可以先留主代理和一个独立阅读代理。确实遇到两份分析互相矛盾，再加仲裁和诊断，省得每读一篇短论文都跑完整套流程。

配置字段可查官方文档：Agent、权限。