┌─────────────────────────────────────────────────────────┐
│                   插件加载顺序                           │
├─────────────────────────────────────────────────────────┤
│  1️⃣ 全局配置插件 (~/.config/opencode/opencode.json)    │
│                         ↓                               │
│  2️⃣ 项目配置插件 (./opencode.json)                     │
│                         ↓                               │
│  3️⃣ 全局目录插件 (~/.config/opencode/plugins/)         │
│                         ↓                               │
│  4️⃣ 项目目录插件 (.opencode/plugins/)                  │
└─────────────────────────────────────────────────────────┘

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["oh-my-opencode", "@your-org/custom-plugin"]
}

interface PluginContext {
  /**
   * OpenCode SDK 客户端
   * 用于与 AI 核心交互
   */   client: OpenCodeClient;

  /**
   * 项目信息
   */   project: {
    /** 项目标识符 */     id: string;
  };

  /**
   * Bun Shell API
   * 用于执行系统命令
   */   $: BunShell;

  /**
   * 当前工作目录
   */   directory: string;

  /**
   * Git worktree 路径
   */   worktree: string;
}

// ❌ 错误：将 context 当作 client 使用 export const MyPlugin = async (ctx) => {
  await ctx.send("Hello"); // TypeError: ctx.send is not a function }

// ✅ 正确：解构 context 对象 export const MyPlugin = async ({ client, project, $, directory, worktree }) => {
  // 使用 client 进行 AI 交互   await client.app.log({
    service: "my-plugin",
    level: "info", 
    message: `Working in: ${directory}`   });
}

// 结构化日志（推荐替代 console.log） await client.app.log({
  service: "my-plugin",    // 插件名称   level: "info",           // debug | info | warn | error   message: "操作完成",
  extra: { key: "value" }  // 可选的额外数据 });

export const MyPlugin = async ({ $ }) => {
  // 基本命令执行   const result = await $`git status`.text();

  // 静默执行（不输出到控制台）   await $`npm install`.quiet();

  // 获取退出码   const { exitCode } = await $`cargo test`;

  // 管道操作   const files = await $`find . -name "*.ts" | head -10`.lines();
}

export const SecurityPlugin = async ({ client }) => {
  return {
    "tool.execute.before": async (input, output) => {
      // input 包含工具调用信息       console.log(`Tool: ${input.tool}`);
      
      // 通过 output.args 修改参数       if (input.tool === "bash") {
        // 将危险的 rm -rf 替换为更安全的 rm -i         output.args.command = output.args.command.replace(/rm -rf/g, "rm -i");
      }

      // 通过 throw 中止执行       if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Security: Cannot read environment files");
      }
    }
  }
}

export const FormatterPlugin = async ({ $ }) => {
  return {
    "tool.execute.after": async (input, output) => {
      // 自动格式化编辑后的文件       if (input.tool === "edit" || input.tool === "write") {
        const filePath = output.args.filePath;
        const ext = filePath.split('.').pop();

        if (["ts", "tsx", "js", "jsx"].includes(ext)) {
          await $`prettier --write ${filePath}`.quiet();
        }
      }
    }
  }
}

import { tool } from "@opencode-ai/plugin" 
export default tool({
  // 工具描述（供 LLM 理解何时使用此工具）   description: "Query the project database",
  
  // 参数定义（使用 Zod schema）   args: {
    query: tool.schema.string().describe("SQL query to execute"),
  },
  
  // 执行函数   async execute(args) {
    // 实现你的逻辑     return `Executed: ${args.query}`;
  }
});

// .opencode/tools/math.ts import { tool } from "@opencode-ai/plugin" 
export const add = tool({
  description: "Add two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a + args.b;
  }
});

export const multiply = tool({
  description: "Multiply two numbers",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args) {
    return args.a * args.b;
  }
});

// .opencode/tools/python-analyzer.ts import { tool } from "@opencode-ai/plugin" 
export default tool({
  description: "Analyze code using Python script",
  args: {
    filePath: tool.schema.string().describe("File to analyze"),
  },
  async execute(args) {
    // 调用 Python 脚本     const result = await Bun.$`python3 .opencode/scripts/analyze.py ${args.filePath}`.text();
    return result.trim();
  }
});

// .opencode/plugins/notification.js export const NotificationPlugin = async ({ $ }) => {
  return {
    event: async ({ event }) => {
      if (event.type === "session.idle") {
        await $`osascript -e 'display notification "Session completed!" with title "OpenCode"'`;
      }
    }
  };
}

// .opencode/plugins/env-protection.js export const EnvProtection = async () => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files");
      }
    }
  };
}

// .opencode/plugins/compaction.ts import type { Plugin } from "@opencode-ai/plugin" 
export const CompactionPlugin: Plugin = async () => {
  return {
    "experimental.session.compacting": async (input, output) => {
      // 注入额外上下文到压缩提示       output.context.push(`
## 项目特定上下文

请在压缩时保留以下信息：
- 当前任务状态
- 重要的设计决策
- 正在修改的文件列表
`);
    }
  };
}

用户输入: "帮我做一次代码审查"             │
            ▼
   ┌─────────────────┐
   │  Agent 分析意图  │
   └────────┬────────┘
            │
            ▼
   ┌─────────────────┐
   │ 调用 skill 工具  │  ← 查看可用的 Skills 列表
   └────────┬────────┘
            │
            ▼
   ┌─────────────────┐
   │  发现匹配 Skill  │  ← 找到 "code-review" Skill    │ "code-review"   │
   └────────┬────────┘
            │
            ▼
   ┌─────────────────┐
   │ 加载 SKILL.md   │  ← 将内容注入到 System Prompt
   └────────┬────────┘
            │
            ▼
   ┌─────────────────┐
   │ 按照指导执行任务 │  ← AI 遵循 SKILL.md 中的指导
   └─────────────────┘

.opencode/skills/git-release/SKILL.md

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
--- 
## What I do 
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me 
Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"     }
  }
}

---
permission:
  skill:
    "documents-*": "allow"
---

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"         }
      }
    }
  }
}

## 执行流程 
### Phase 1: 信息收集 
1. 读取目标文件内容
2. 分析文件类型和语言
3. 识别相关依赖

### Phase 2: 分析 
1. 检查语法错误
2. 识别代码异味
3. 评估复杂度

### Phase 3: 报告 
1. 汇总发现
2. 优先级排序
3. 生成建议

## 输出示例 
### 发现严重问题时 
**位置**: `src/api/users.ts:45` **问题**: SQL 注入漏洞
**风险**: 攻击者可获取数据库内容
**修复建议**:
\```typescript
// 使用参数化查询
const result = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
\``` 

## ⛔ 禁止行为 
1. **不要自动修改代码** - 只提供建议，除非用户明确要求修复
2. **不要审查以下内容**:
   - `node_modules/` 目录
   - 自动生成的文件（*.generated.*）
3. **不要给出模糊建议**:
   - ❌ "代码可以更简洁"
   - ✅ "将第 45-52 行的 for 循环替换为 Array.map()"

# 方式 1: 使用 bunx（推荐） bunx oh-my-opencode install

# 方式 2: 手动配置 # 在 opencode.json 中添加 {
  "plugin": ["oh-my-opencode"]
}

优先级 1: Skills     ↓ 如果有匹配的 Skill，直接加载使用 优先级 2: Direct Tools     ↓ 范围明确的简单任务，使用内置工具 优先级 3: Background Agents     ↓ 可并行执行的任务，异步返回结果 优先级 4: Blocking Agents     ↓ 需要即时结果的复杂任务

用户: 调研主流的状态管理方案

Sisyphus 执行计划:
├── 后台任务 1: @librarian → 搜索 Redux 文档
├── 后台任务 2: @librarian → 搜索 Zustand 文档
├── 后台任务 3: @librarian → 搜索 Jotai 文档
├── 后台任务 4: @explore → 搜索项目现有状态管理
└── 主线程: Sisyphus 继续规划后续步骤

(所有后台任务并行执行，2-5秒后)
     ↓
汇总所有结果，生成对比分析报告

@librarian 搜索一下 JWT 认证的最佳实践
@explore 找一下项目中现有的认证代码
@oracle 帮我分析一下这两个方案哪个更好

用户: 帮我重构这个模块
Sisyphus: (自动分析后调用)
  → @explore 搜索相关代码
  → @prometheus 制定重构计划
  → @momus 审查方案