XCOpenCodeWeb/README.md

# XCOpenCodeWeb

XCOpenCodeWeb 是一个基于 Web 的 AI 编程助手界面，用于与 OpenCode 服务器交互。

## 快速开始

### 使用单文件 exe（推荐）

直接下载 `XCOpenCodeWeb.exe`，双击运行：

```bash
# 默认端口 3000
XCOpenCodeWeb.exe

# 指定端口
XCOpenCodeWeb.exe --port 8080

# 查看帮助
XCOpenCodeWeb.exe --help
```

启动后访问 http://localhost:3000

### 从源码运行

需要安装 [Bun](https://bun.sh) 或 Node.js 20+

```bash
# 安装依赖
bun install

# 构建前端
bun run build

# 启动服务器
bun server/index.js --port 3000
```

## 构建单文件 exe

```bash
cd web
bun run build:exe
```

输出：`web/XCOpenCodeWeb.exe`（约 320MB）

详细文档：[docs/single-file-exe-build.md](docs/single-file-exe-build.md)

## 项目结构

```
├── ui/                 # 前端组件库
├── web/
│   ├── src/           # 前端源码
│   ├── server/        # 后端服务器
│   ├── bin/           # CLI 工具
│   └── dist/          # 构建输出
├── docs/              # 文档
└── AGENTS.md          # AI Agent 参考文档
```

## 常用命令

```bash
# 开发模式
bun run dev                    # 前端热更新
bun run dev:server             # 启动开发服务器

# 构建
bun run build                  # 构建前端
bun run build:exe              # 构建单文件 exe

# 代码检查
bun run type-check:web         # TypeScript 类型检查
bun run lint:web               # ESLint 检查
```

## 依赖

- [Bun](https://bun.sh) - 运行时和打包工具
- [React](https://react.dev) - 前端框架
- [Express](https://expressjs.com) - 后端服务器
- [Tailwind CSS](https://tailwindcss.com) - 样式框架

## 配置

### 环境变量

| 变量 | 说明 |
|------|------|
| `XCOpenCodeWeb_PORT` | 服务器端口（默认 3000） |
| `OPENCODE_HOST` | 外部 OpenCode 服务器地址 |
| `OPENCODE_PORT` | 外部 OpenCode 端口 |
| `OPENCODE_SKIP_START` | 跳过启动 OpenCode |

## 许可证

MIT