learn-opencode 自定义 Agent 全攻略：4 种设计模式 + 权限安全，打造专属 AI 员工

• 文档
• 教程

在 OpenCode 中，自定义 Agent就是给 AI 发一份"岗位说明书"：它是谁、擅长什么、能做什么、不能做什么。学会它，你就不再是每次都要说"你是代码审查专家……"的重复玩家，而是拥有一支随叫随到的专属 AI 员工团队。本文基于 learn-opencode 中文实战课 第五阶段的 Agent 专题（docs/5-advanced/02a-agent-quickstart.md、docs/5-advanced/02b-agent-patterns.md），带你从零学会创建自定义 Agent、套用 4 种设计模式、配置权限安全，全程不用啃源码。

一、先搞懂：OpenCode 里的 Agent 是什么？

OpenCode 的 Agent 本质是可配置的 AI 人格，你可以定义三样东西：

它分成两种"工种"，外加一种混合：

• Primary（主 Agent）：你直接对话的对象，用Tab键切换，内置的build（全能开发）和plan（只读规划）就是两类；
• Subagent（子 Agent）：干专项活的专家，用@agent名 任务手动调用，或由主 Agent 根据description自动调用；
• All（混合）：既可当主 Agent，也可被 @ 调用。

一句话理解：主 Agent 是项目经理，子 Agent 是专家。项目经理接到任务后，可以把它拆给专家去做，专家在独立的子会话里工作，完成后把结果交回项目经理。

💡 一个小细节：子 Agent 运行在全新会话里，看不到你和主 Agent 的历史对话，所以调用时必须把任务所需信息写完整。

二、3 步创建你的第一个自定义 Agent

创建 Agent 不需要写代码，一个 Markdown 文件就是一个 Agent。

第 1 步：放对位置

文件名即 Agent 名称：docs-writer.md创建的 Agent 就叫docs-writer，用@docs-writer调用。目录名是agent不是agents，这是新手最常踩的坑。

第 2 步：写一份岗位说明书

文件上半部分是"人事信息"（YAML 头部），下半部分就是写给 AI 的系统提示词。以文档写作专家为例：

--- description: 技术文档写作专家，擅长 API 文档、README mode: subagent temperature: 0.3 --- 你是技术文档专家，擅长把复杂概念讲得通俗易懂。 # 工作原则 - 先理解代码，再写文档 - 快速开始的代码必须可直接复制运行 - 不确定的地方要验证

几个关键字段：

• description：强烈建议填写，它决定了主 Agent 什么时候会自动选中这个专家；
• mode：primary/subagent/all，注意不要写成plan、build；
• temperature：0~1，数值越低越稳定严谨，审计类建议 0.1 左右；
• steps：最大迭代步数，防止 Agent 陷入死循环。

第 3 步：调用它

@docs-writer 帮我写一个 README

也可以用Tab切换主 Agent，或按Ctrl+X再按a查看全部 Agent 列表。

三、4 种设计模式：让 Agent 团队高效协作

会创建一个 Agent 只是入门，怎么设计才好用才是关键。业界（Anthropic、Lilian Weng）总结出的 Agent 设计模式里，有 4 种在 OpenCode 中最实用，完整示例可参考 docs/5-advanced/02b-agent-patterns.md 和 docs/4-scenarios/coder-agents.md。

模式 1：提示链（Prompt Chaining）—— 像流水线一样分步走

原理：把任务拆成顺序执行的步骤，上一步的输出是下一步的输入。

适用：步骤清晰固定的任务，如"翻译 → 润色 → 术语检查 → 格式化"。

做法：在提示词里明确写出"按以下步骤执行，每步完成后再进行下一步"，并用steps限制总步数。用延迟换准确性，适合翻译、格式化这类"一步不能错"的活。

模式 2：路由（Routing）—— 分诊台模式

原理：先判断任务属于哪一类，再分派给对应的专家处理。

适用：不同类别需要不同处理方式的场景，比如代码问题分为 Bug 修复 / 性能优化 / 安全审计 / 重构。

做法：写一个"路由 Agent"，提示词里列清楚每类的判断特征和去向（如"涉及认证、数据处理 → 交给 @security-auditor"），再配合task权限把它的可调用范围锁死在几个白名单专家内。

模式 3：并行化（Parallelization）—— 多专家同时开工

原理：多个独立子任务同时执行，最后汇总结果。

适用：子任务相互独立、需要加速或需要多视角交叉验证。

做法：在提示词中要求"同时调用"多个子 Agent。经典案例是代码质量并行检查：安全、性能、风格、测试覆盖四位专家同时开工，最后汇总成一份带综合评分的报告——这是 PR 审计最常用的套路。

模式 4：编排-工人（Orchestrator-Workers）—— 项目经理动态拆活

原理：中央 Agent（编排器）先理解需求，再动态决定需要哪些专家、以什么顺序调用。

适用：无法提前预测需要哪些子任务的复杂问题，如"帮我全面体检这个项目"。

做法：编排器提示词中列出"可用专家清单 + 各自适用场景"，并强调"不要过度分析，简单问题不需要专家"。路由是"分类固定"，编排是"动态拆活"，两者经常被混合使用。

怎么选？记住一个决策流程：步骤固定 → 用提示链/固定命令；类别可分 → 用路由；任务独立 → 用并行；完全不可预测 → 用编排。三条原则：能用单 Agent 解决的不用多 Agent；能固定流程的不用动态决策；每一步都要可见。

四、权限安全：给 AI 员工发"门禁卡"

自定义 Agent 最大的风险不是它不听话，而是它权限太大。OpenCode 的权限系统给了三种动作：

核心规则：最后匹配获胜

当多条规则都命中时，写在最后的那条生效。所以配置习惯是：通配符*放最前，具体规则放后面：

{ "permission": { "bash": { "*": "ask", // 默认都需确认 "git log*": "allow", // 查日志放行 "git push*": "deny" // 推送禁止，写在最后所以生效 } } }

执行git push会依次匹配三条规则，最终以最后的deny为准。

黄金实践：最小权限原则

设计自定义 Agent 时，只授予完成任务所需的最小权限。以只读审计专家为例，在 Markdown 头部直接配置：

--- description: 只读代码审计 Agent mode: subagent permission: edit: deny # 禁止一切文件修改 bash: "*": deny "git log*": allow # 只允许查看日志 task: "*": deny # 禁止再调用其他 Agent ---

四条安全心法：

1. 禁止所有，再允许需要的（"*": "deny"打底，白名单放行），而不是允许所有再禁危险的；
2. 敏感操作一律ask：git push、npm publish、docker 等；
3. 锁文件与密钥文件设deny：.env、package-lock.json、node_modules/*；
4. 编排器锁task白名单：它只能调用你点名的专家，防止乱派活。

另外 OpenCode 自带一些安全护栏：.env文件读取默认需确认、子 Agent 默认不能再调用子 Agent（防无限递归）、同一工具连续 3 次相同输入会触发死循环检测。详细规则可查阅 docs/5-advanced/02c-agent-permissions.md 与 docs/5-advanced/05-permissions.md。

五、踩坑清单与延伸阅读

设计完成前，自问 5 个问题：能用更简单的方案吗？description 写具体了吗？设 steps 限制了吗？权限是否最小化了？出错时如何恢复？

想系统学习，建议按这个顺序阅读：

• 快速入门：docs/5-advanced/02a-agent-quickstart.md
• 设计模式：docs/5-advanced/02b-agent-patterns.md
• 权限安全：docs/5-advanced/02c-agent-permissions.md
• 高级技巧（提示词工程与调试）：docs/5-advanced/02d-agent-advanced.md
• 开发者场景实战：docs/4-scenarios/coder-agents.md
• 零基础先入门：docs/3-workflow/02-agents.md

照着本文做一遍，你就能拥有一支有门禁卡、分工明确、随叫随到的专属 AI 员工团队。

• 文档
• 教程