# opencode

自定义 `opencode-ai` Docker 镜像构建仓库。镜像内置 Python 数据栈依赖与一套用于把业务数据需求转成可执行 PySpark SQL 的 Claude Code skills。

## 包含什么

- **Node.js 22** + **`opencode-ai` CLI**（全局安装）
- **Python 3.11**（通过 [`uv`](https://github.com/astral-sh/uv) 管理）+ 数据栈依赖（`requirements.txt`）：PySpark、pandas、polars、clickhouse-connect、pymongo、redis、hdfs 等
- **ripgrep**（预编译二进制）
- **`skills/`** 自动部署到 `/root/.config/opencode/skills/`，Claude Code 启动时自动发现

## 构建

```bash
docker build -t opencode:latest .
```

Dockerfile 为多阶段构建：builder 阶段拉取 Node.js 22 与 Python 3.11，最终镜像只保留运行所需文件。

## 运行

```bash
docker run -itd --name opencode -p 14096:4096 \
    -e OPENCODE_SERVER_PASSWORD=Cupdata123 \
    -v /root/.config/opencode:/root/.config/opencode \
    -v /root/.local/share/opencode:/root/.local/share/opencode \
    -v /root/OpenCode:/root/workspace \
    opencode:latest \
    web --hostname 0.0.0.0 --mdns --port 4096 --print-logs --log-level DEBUG
```

参数说明：
- `-p 14096:4096` 主机 `14096` 端口映射到容器内 `4096`（opencode web 服务端口）
- `-e OPENCODE_SERVER_PASSWORD=...` 设置 web 服务登录密码（生产环境请改为强密码并通过 secret 管理）
- 三个 `-v` 挂载分别持久化 opencode 配置、运行数据、以及工作区文件
- `web` 子命令以 `0.0.0.0` 监听并启用 mDNS，端口 `4096`，日志级别 DEBUG

## Skills 概览

`skills/` 下是一套端到端流水线，把中文业务数据需求一步步推到可评审的 PySpark SQL：

```
requirements-analysis → metadata-validator → logic-planner
    → sql-context-builder → (SQL 生成) → pyspark-sql-guardrails → sql-review
```

`pyspark-sql-pipeline` 是 orchestrator，负责在阶段之间维护用户确认门。

详细的输入/输出契约、状态名（`READY_FOR_VALIDATION` / `VALIDATED` / `PLANNED` / `READY` / `PASS` / `FAIL`）、以及 SQL 校验闸门规则见 [`CLAUDE.md`](./CLAUDE.md)。

## 目录结构

```
.
├── Dockerfile                          # 多阶段镜像构建
├── requirements.txt                    # Python 数据栈依赖
├── ripgrep-*.tar.gz                    # ripgrep 预编译包（构建时复制进镜像）
├── skills/
│   ├── requirements-analysis/          # 需求解读与 DRD 输出
│   ├── metadata-validator/             # 表/字段/关联验证
│   ├── logic-planner/                  # 业务逻辑拆解（固定步骤分类法）
│   ├── sql-context-builder/            # 冻结字段别名、类型、角色标签
│   ├── pyspark-sql-guardrails/         # SQL 白名单校验器（闸门）
│   │   └── scripts/
│   │       ├── sql_guard.py            # 规范实现
│   │       ├── validate_sql.py         # CLI 入口
│   │       └── test_sql_guard.py       # 18 个用例的标准测试集
│   ├── sql-review/                     # 静态评审（10 项检查）
│   └── pyspark-sql-pipeline/           # 全流程 orchestrator
└── CLAUDE.md                           # 给 Claude Code 的详细指南
```