# 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-custom:latest .
```

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

## 运行

```bash
docker run --rm -it opencode-custom:latest
```

ENTRYPOINT 为 `opencode`，可直接传入 Claude Code 参数。

## 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 的详细指南
```