72 lines
3.3 KiB
Markdown
72 lines
3.3 KiB
Markdown
# 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=<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
|
||
|
||
## 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 的详细指南
|
||
```
|