Skip to content

AGENTS.md

Latest commit

 

History

History
176 lines (133 loc) · 7.32 KB

AGENTS.md

File metadata and controls

176 lines (133 loc) · 7.32 KB

AGENTS.md

What This Repo Is

A collection of OpenCode agent configuration files. No code, no build, no tests — only .md files that define agent behavior via YAML frontmatter + prompt body. Hosted on Gitee at aerlee/opencode-agents.

Structure

agents/
  *.md          # 26 agent definitions (2 primary + 24 subagent)
plugins/
  image-paste-saver.js  # Auto-saves pasted images to /tmp/ for vision-dev
README.md       # Chinese (outdated — lists 18 agents, actual count is 26)
README.en.md    # English (same)
LICENSE         # MIT

Agent File Format

Every file in agents/ uses this structure:

---
description: <Chinese description — this is what OpenCode uses to decide when to invoke the agent>
mode: primary | subagent
model: <provider/model-name>
temperature: <0.0-1.0>
tools:            # optional — omit keys to allow all
  write: false
  edit: false
  bash: false
---

<System prompt in English or Chinese>

Key Conventions

  • description is always in Chinese — this is the trigger text OpenCode matches against. Match the style: role name + capabilities + trigger scenarios.
  • mode: primary means the agent can be a top-level session. Only Zero.md and Erribaba.md are primary agents.
    • Zero.md (opencode-go/mimo-v2.5) — rapid prototyping, multimodal (image input), lightweight tasks
    • Erribaba.md (Xianyu/mimo-v2.5-pro) — production code, complex algorithms, deep analysis
  • mode: subagent means the agent is only invoked via delegation from a primary agent.
  • Filename = agent name used in delegation (e.g., reviewer.md → delegate as reviewer).
  • Model naming: provider prefix matters — models include opencode-go/mimo-v2.5, opencode-go/mimo-v2.5-pro, opencode-go/deepseek-v4-pro, opencode-go/kimi-k2.6, opencode-go/qwen3.6-plus, opencode-go/minimax-m2.7, opencode-go/glm-5.1. Primary agents use different providers: opencode-go/ vs Xianyu/.
  • Tool access defaults to all tools allowed when tools key is omitted (primary agents). Subagents that need to write code must explicitly set write: true, edit: true. Read-only subagents set all three to false. Agents needing shell access add bash: true.

All 26 Agents

Primary (2)

File Model Role
Zero.md opencode-go/mimo-v2.5 Rapid prototyping, multimodal input, quick iteration
Erribaba.md Xianyu/mimo-v2.5-pro Production code, complex algorithms, full-stack engineering

Subagents — Read-only (8)

File Model
architect.md opencode-go/glm-5.1
frontend-reviewer.md opencode-go/mimo-v2.5
git-assistant.md opencode-go/mimo-v2.5
research.md opencode-go/qwen3.6-plus
reviewer.md opencode-go/deepseek-v4-pro
security-auditor.md opencode-go/deepseek-v4-pro

Plus perf-optimizer and validator — read-only for file edits but have bash: true for running commands.

Subagents — With write/edit (16)

File Model Has bash
api-designer.md opencode-go/mimo-v2.5-pro ✗
code-generator.md opencode-go/mimo-v2.5-pro ✗
db-engineer.md opencode-go/deepseek-v4-pro ✓
debugger.md opencode-go/deepseek-v4-pro ✓
devops.md opencode-go/mimo-v2.5-pro ✓
doc-writer.md opencode-go/qwen3.6-plus ✗
e2e-tester.md opencode-go/mimo-v2.5-pro ✗
executor.md opencode-go/minimax-m2.7 ✓
frontend-dev.md opencode-go/kimi-k2.6 ✗
migration.md opencode-go/deepseek-v4-pro ✓
project-manager.md opencode-go/qwen3.6-plus ✗
refactorer.md opencode-go/mimo-v2.5-pro ✗
software-engineer.md opencode-go/mimo-v2.5 ✓
test-writer.md opencode-go/mimo-v2.5-pro ✗
ui-designer.md opencode-go/kimi-k2.6 ✗
vision-dev.md opencode-go/mimo-v2.5 ✗

When Adding or Editing Agents

  1. Match the frontmatter field order: description, mode, model, temperature, then optional tools.
  2. Write description in Chinese — start with the role name (e.g., "代码审查智能体"), then describe capabilities and trigger scenarios.
  3. Keep system prompts concise and structured with ## sections.
  4. Primary agents must list all available subagents in their body — update both Zero.md and Erribaba.md if adding a new subagent.
  5. Do not add build/CI/tooling — this repo has none and needs none.
  6. After adding a new agent, update the tables in this file.

Plugin: image-paste-saver

Source: plugins/image-paste-saver.js Install target: ~/.config/opencode/plugins/ (handled by install scripts)

Automatically detects pasted images in the TUI conversation, saves them to {project}/.opencode/tmp/, and injects file path references into the prompt. This enables text-only primary agents (Erribaba) to delegate image analysis to vision-dev.

How it works:

  1. User pastes an image in the OpenCode TUI
  2. Plugin intercepts via chat.message hook
  3. Image is decoded from base64 and saved to {project}/.opencode/tmp/
  4. A text reference [Image saved to: .opencode/tmp/opencode-img-xxx.png] is injected into the prompt
  5. Primary agent sees the file path and delegates to @vision-dev

Cleanup:

  • On plugin dispose (OpenCode exit): deletes all temp files created during the session
  • On startup: cleans up stale files older than 1 hour (crash recovery)

Supported formats: PNG, JPEG, GIF, WebP, SVG, BMP (max 10MB)

Parallel Task Management

Both primary agents use an async first-come-first-serve pattern for parallel subagent delegation.

1. 配置（必须）

在 shell 配置文件（~/.bashrc 或 ~/.zshrc）中添加：

export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true

或者在 Windows 中设置用户环境变量：

[Environment]::SetEnvironmentVariable("OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS", "true", "User")

没有此配置，所有子代理任务将同步阻塞执行。

2. 使用方式（必须）

配置只是开启了功能，代理还必须主动使用 background=true 参数：

// ❌ 错误：同步阻塞，等待完成才继续
@code-generator (task A)
@ui-designer (task B)
@db-engineer (task C)

// ✅ 正确：异步并行，立即返回，按完成顺序处理
@code-generator (task A, background=true)
@ui-designer (task B, background=true)
@db-engineer (task C, background=true)

3. 结果处理（必须）

收到任何一个子代理结果时，立即处理，不要等待其他任务：

收到 code-generator 结果 → 立即验证并处理 → 启动后续任务（如 reviewer）
收到 db-engineer 结果 → 立即验证并处理 → 继续等待
收到 ui-designer 结果 → 立即验证并处理 → 所有任务完成

4. 注意事项

  • 独立任务才用 background=true：有依赖关系的任务不要并行
  • 不要轮询：系统会自动通知完成，不要主动查询状态
  • 超时处理：复杂任务超过 30 分钟应考虑取消重试
  • 冲突解决：多个子代理修改同一文件时，以高优先级为准（security-auditor > reviewer > validator > others）

Language

  • Frontmatter description: Chinese
  • System prompt body: English (most files) or Chinese (acceptable)
  • README: Chinese primary, English secondary