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 中成功运行并通过验证。