# opencode-plugins

**Repository Path**: hivedark/opencode-plugins

## Basic Information

- **Project Name**: opencode-plugins
- **Description**: 本仓库包含 Opencode 插件，通过事件钩子扩展 Opencode 的功能。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Opencode 插件

通过事件钩子扩展 Opencode 功能的插件集合。

## 功能特性

- 🎣 **事件驱动** - 监听并响应命令、文件、会话等多种事件
- 🧩 **模块化** - 独立的插件文件，易于扩展和维护
- 🔌 **热加载** - 修改插件后无需重启即可生效

## 项目结构

```
./
├── opencode.json          # 插件配置
├── README.md              # 中文文档
├── README-en.md           # English docs
├── AGENTS.md              # 开发指南
├── .opencode/
│   ├── package.json      # 依赖管理
│   └── plugins/          # 插件源文件 (*.js)
│       └── notification.js
```

## 快速开始

### 加载插件

**本地插件**（放在插件目录）:
- `.opencode/plugins/` - 项目级插件
- `~/.config/opencode/plugins/` - 全局插件

**npm 包**（在 `opencode.json` 配置）:
```json
{
  "plugins": ["notification", "@my-org/custom-plugin"]
}
```

### 创建插件

`.opencode/plugins/my-plugin.js`:
```javascript
export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  return {
    session: {
      idle: async () => {
        console.log('Session idle!')
      },
    },
  }
}
```

### 插件参数

| 参数 | 说明 |
|------|------|
| `project` | 当前项目信息 |
| `directory` | 当前工作目录 |
| `worktree` | git worktree 路径 |
| `client` | Opencode SDK 客户端 |
| `$` | Bun shell API，执行命令 |

## 可用插件

| 插件 | 说明 |
|------|------|
| [notification](./.opencode/plugins/notification.js) | 会话空闲时发送 Windows 通知 |
| [opencode-mobile](https://github.com/doza62/opencode-mobile) | 移动推送通知，通过 Expo 向移动设备发送 Opencode 事件通知 |

## 事件类型

### 会话
`session.created`, `session.compacted`, `session.deleted`, `session.diff`, `session.error`, `session.idle`, `session.status`, `session.updated`

### 工具
`tool.execute.before`, `tool.execute.after`

### 消息
`message.part.removed`, `message.part.updated`, `message.removed`, `message.updated`

### 文件
`file.edited`, `file.watcher.updated`

### 其他
`command.executed`, `installation.updated`, `lsp.client.diagnostics`, `lsp.updated`, `permission.asked`, `permission.replied`, `server.connected`, `todo.updated`, `shell.env`, `tui.prompt.append`, `tui.command.execute`, `tui.toast.show`

## 添加依赖

在 `.opencode/package.json` 添加 npm 包:
```json
{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}
```

## TypeScript 支持

```typescript
import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // 类型安全的钩子实现
  }
}
```

## 移动推送通知插件 (opencode-mobile)

通过 Expo 向移动设备发送 Opencode 事件通知，支持会话空闲、错误、权限更新等事件。

### 功能特性

- 📱 **移动通知** - 在移动设备上接收 Opencode 事件通知
- 🔗 **隧道连接** - 支持 Cloudflare、ngrok、Localtunnel 隧道
- 📲 **QR 码连接** - 扫描二维码快速连接移动设备
- ⚡ **事件驱动** - 自动监听会话事件发送通知

### 安装配置

1. 安装插件：
   ```bash
   npx opencode-mobile install
   ```

2. 在 `opencode.json` 中添加插件：
   ```json
   {
     "plugins": ["opencode-mobile"]
   }
   ```

3. 启动 Opencode 并使用：
   ```bash
   opencode serve
   # 在会话中输入 /mobile 获取连接码
   ```

### 使用示例

1. 启动 Opencode 服务器
2. 运行 `/mobile` 命令获取 QR 码
3. 在移动设备上安装 OpenCode Mobile 应用或 Expo Go
4. 扫描 QR 码连接
5. 接收 Opencode 事件通知

### 相关命令

- `npx opencode-mobile install` - 安装插件
- `npx opencode-mobile update` - 检查更新
- `npx opencode-mobile filters` - 管理通知过滤器
- `npx opencode-mobile qr` - 显示 QR 码

### 环境变量

- `TUNNEL_PROVIDER` - 隧道提供商 (`auto`, `ngrok`, `cloudflare`, `localtunnel`)
- `OPENCODE_MOBILE_DEBUG` - 调试模式 (`1` 启用)
- `OPENCODE_PORT` - 本地服务器端口

### 常见问题

1. **连接失败**：检查网络连接，尝试不同的隧道提供商
2. **通知不显示**：确认移动设备已正确连接并授予通知权限
3. **QR 码无效**：重新运行 `/mobile` 命令生成新的连接码

## 相关链接

- [开发指南](./AGENTS.md)
- [Opencode 官方文档](https://opencode.ai)