DESIGN.md

# HuggingRun 设计

**Slogan:** Run anything on Hugging Face.

## 目标

- 把 Hugging Face Spaces 当成**通用容器**：只要应用能 Docker 化，就能在 HF 上跑。
- 参考 HuggingClaw 的持久化与入口模式，做成**可配置**的通用运行时。
- 通过至少一个「难例」部署验证（如 FastAPI+SQLite 或带状态的 Web 应用）。

## 架构

1. **单一 Docker 镜像**
   - 使用 `ARG BASE_IMAGE` 选择基础镜像（默认 `python:3.11-slim`）。
   - 在基础镜像上安装 Python3 + `huggingface_hub`（若基础镜像无），并加入通用脚本。
   - 通过 `ENV RUN_CMD` 指定要执行的命令（应用由用户通过 CMD/环境变量提供）。

2. **入口脚本 `entrypoint.sh`**
   - 调用 `sync_hf.py` 做启动时恢复与周期性上传（可选）。
   - 最后 `exec` 执行 `RUN_CMD`（或 Dockerfile 的 CMD），使主进程为 PID 1。

3. **持久化 `sync_hf.py`**
   - 可配置持久化目录 `PERSIST_PATH`（默认 `/data`）。
   - 可配置 HF Dataset repo：`HF_DATASET_REPO` 或由 `SPACE_ID` 推导 `{SPACE_ID}-data`。
   - 启动时：若存在 `HF_TOKEN` 与 repo，则 `snapshot_download` 到 `PERSIST_PATH`。
   - 后台线程：按 `SYNC_INTERVAL` 将 `PERSIST_PATH` 上传到 Dataset。
   - 退出时：最后一次上传。

4. **HF Spaces 约定**
   - `sdk: docker`，`app_port: 7860`。
   - 用户需在 Space 中设置 `RUN_CMD`（以及可选 `HF_TOKEN`、`HF_DATASET_REPO`、`PERSIST_PATH`）。
   - 若使用默认 demo，`RUN_CMD` 启动监听 7860 的简单服务并读写 `PERSIST_PATH`，用于验证持久化。

## 完成标准（迭代开发）

- [ ] **通用工具**：README 与 docs/HF_LIMITATIONS.md 明确“通用接口 + HF 限制应对”；entrypoint/sync 可配置 PERSIST_PATH、APP_PORT、RUN_CMD。
- [ ] 本地 `docker build` 与 `docker run` 成功，默认 demo 在 7860 响应。
- [ ] 持久化：重启容器后，写入 `PERSIST_PATH` 的内容仍在（通过 HF Dataset 恢复）。
- [ ] 示例最小化：FastAPI+SQLite、Ubuntu 桌面等仅演示“用通用工具”的用法，不增加额外通用逻辑。
- [ ] 代码推送到 HF Space，且在该 Space 中成功运行并通过验证。