# OpenCode Delegator

MCP Server — 让 Codex、Claude Code 等 AI 编码助手**只做决策**，将代码编写、编辑、执行全部委派给 OpenCode。

## 快速开始

### 安装

```bash
npm install -g opencode-delegator
```

或直接使用 npx：

```bash
npx opencode-delegator
```

### 前置要求

- Node.js >= 18
- [OpenCode CLI](https://opencode.ai) 已安装并在 PATH 中

## 配置

**Codex CLI** — 编辑 `~/.codex/config.toml`：

```toml
[mcp_servers.opencode]
command = "npx"
args = ["-y", "opencode-delegator"]
env = { OPENCODE_DEFAULT_PROJECT = "/path/to/project" }
```

**Claude Code**：

```bash
claude mcp add opencode -- npx -y opencode-delegator
```

**Claude Desktop** — 编辑配置文件：

```json
{
  "mcpServers": {
    "opencode": {
      "command": "npx",
      "args": ["-y", "opencode-delegator"],
      "env": { "OPENCODE_DEFAULT_PROJECT": "/path/to/project" }
    }
  }
}
```

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `OPENCODE_MODE` | `spawn` | `spawn` 或 `persistent` |
| `OPENCODE_DEFAULT_PROJECT` | - | 默认项目绝对路径 |
| `OPENCODE_PATH` | `opencode` | OpenCode 可执行文件路径 |
| `OPENCODE_TIMEOUT` | `120000` | 超时时间 (ms) |
| `OPENCODE_WHITELIST` | `false` | 启用命令白名单 |
| `OPENCODE_PROJECTS` | - | JSON 格式多项目配置 |

也支持配置文件 `opencode-delegator.json`，参见 [config.example.json](config.example.json)。

## 工具

| 工具 | 说明 |
|------|------|
| `write_code` | 创建/覆写文件（支持 AI 生成） |
| `edit_code` | 通过 OpenCode 编辑文件（自动 lint/typecheck） |
| `read_file` | 读取文件内容 |
| `search_code` | ripgrep 搜索代码库 |
| `run_command` | 执行 shell 命令（带安全过滤） |
| `run_tests` | 运行测试套件（自动检测框架） |
| `git_status` | 查看分支和文件状态 |
| `git_diff` | 查看 diff |
| `git_commit` | 暂存并提交 |
| `git_log` | 查看提交历史 |
| `plan` | OpenCode 分析需求并输出方案 |
| `execute_plan` | 执行已生成的方案 |
| `list_projects` | 列出已注册项目 |
| `add_project` | 动态注册新项目 |
| `list_sessions` | 列出活跃会话（persistent） |
| `resume_session` | 恢复历史会话（persistent） |
| `ask_opencode` | 通用委派工具 |

### MCP Resources

| 资源 | URI | 说明 |
|------|-----|------|
| project-structure | `project://{project}/structure` | 项目文件树 |
| project-dependencies | `project://{project}/dependencies` | 依赖信息 |
| project-recent | `project://{project}/recent` | 最近 git 变更 |

## 安全

- **路径校验**：所有文件操作限制在项目目录内，防止路径遍历
- **命令过滤**：拦截危险 shell 命令（`rm -rf /`、`curl | sh` 等），支持白名单模式
- **审计日志**：所有工具调用记录到 `~/.opencode-delegator/audit.jsonl`

## 架构

```
┌─────────────────┐      MCP (stdio)      ┌──────────────────┐
│   Codex CLI     │ ◄────────────────────► │  opencode-       │
│   Claude Code   │                        │  delegator       │
│   Cursor 等     │                        │  (MCP Server)    │
└─────────────────┘                        └────────┬─────────┘
                                                    │
                                    ┌───────────────┼───────────────┐
                                    ▼               ▼               ▼
                              ┌──────────┐   ┌──────────┐   ┌──────────┐
                              │ Project A │   │ Project B │   │ Project C │
                              └──────────┘   └──────────┘   └──────────┘
```

## 文档

- [开发文档](docs/DEVELOPMENT.md) — 完整架构说明、开发指南
- [优化计划](docs/OPTIMIZATION_PLAN.md) — 已知问题与改进路线图

## License

MIT