opencode

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

包含什么

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

构建

docker build -t opencode:latest .

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

运行

docker run -itd --name opencode -p 14096:4096 \
    -e OPENCODE_SERVER_PASSWORD=<your password> \
    -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

使用 docker compose

仓库根目录提供 docker-compose.yml，与上面的 docker run 命令等价但更易管理（声明式、自动重启、--build 一条命令搞定）。首次启动前 需要从模板创建 .env（.env 已被 .gitignore 忽略，不会被提交）：

cp .env.example .env
# 编辑 .env，把 OPENCODE_SERVER_PASSWORD 改成你自己的密码

# 首次启动（或 Dockerfile / skills 变更后）：现场构建并后台启动
docker compose up -d --build

# 后续重启
docker compose restart

# 查看实时日志
docker compose logs -f

# 停止并移除容器
docker compose down

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。

目录结构

.
├── .env.example                        # 环境变量模板（复制为 .env 并填值，.env 本身被 .gitignore 忽略）
├── .gitignore                          # 忽略 .env、Python 缓存、IDE/OS 杂项
├── CHANGELOG.md                        # 镜像版本演进记录
├── Dockerfile                          # 多阶段镜像构建
├── docker-compose.yml                  # 等价于"运行"小节的 docker run
├── 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 的详细指南
└── README.md                           # 本文件