update documents

2026-06-18 14:10:16 +08:00
parent a849d0b3de
commit 213b4db423
2 changed files with 106 additions and 20 deletions
@@ -1,3 +1,61 @@
 # opencode

-custome opencode image build
+自定义 `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 的详细指南
+```