Update README.md

README.md

@@ -8,4 +8,133 @@ pinned: false
 license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# OpenSpace 后端部署指南 (HuggingFace Space)
+
+本目录 (`Backend_HF`) 包含了 OpenSpace 的核心执行引擎、Skill 进化逻辑以及 API 服务。它被设计为通过 Docker 容器部署在 **HuggingFace Space** 上，并使用 **Turso** 作为 Serverless 云端数据库以保证数据持久化。
+
+## 🚀 部署到 HuggingFace Space
+
+### 1. 准备工作
+
+在部署后端之前，您需要完成以下服务的配置：
+*   **Turso 数据库**：
+    1. 登录 [Turso](https://turso.tech/) 并创建一个新数据库 (如 `openspace-db`)。
+    2. 获取连接 URL (如 `libsql://openspace-db-yourusername.turso.io`)。
+    3. 生成 Auth Token (通过 `turso db tokens create openspace-db`)。
+*   **大语言模型 API Key**：OpenSpace 的进化引擎依赖 LLM（如 OpenAI、Anthropic 或其他兼容模型）。
+
+### 2. 在 HuggingFace 创建 Space
+
+1. 登录 [HuggingFace](https://huggingface.co/)。
+2. 点击右上角头像，选择 **"New Space"**。
+3. 填写 Space Name (例如 `openspace-backend`)。
+4. **License**: 建议选择 `MIT`。
+5. **Select the Space SDK**: 必须选择 **Docker**，然后选择 **Blank** 模板。
+6. **Space Hardware**: 免费的 `CPU basic` (2 vCPU, 16GB RAM) 已经足够运行此后端服务。
+7. **Visibility (可见性)**: 
+   * **建议选择 Public (公开)**：如果您的前端部署在 EdgeOne 等外部平台，必须将 Space 设为 Public，否则前端的跨域 API 请求将被 HuggingFace 的鉴权层拦截拦截导致无法访问。
+   * *(注：虽然是 Public，但由于您的核心数据在外部的 Turso 数据库中，且您的前端有 Clerk 白名单保护，安全性是有保障的。为了防止他人滥刷 API，建议在 `dashboard_server.py` 中增加简单的 API_KEY 校验。)*
+8. 创建 Space。
+
+### 3. 配置环境变量 (Secrets)
+
+在新创建的 Space 页面，进入 **Settings -> Variables and secrets**。添加以下 **Secrets** (注意不是 Variables，因为这些是敏感信息)：
+
+| Secret Name | 示例值 | 说明 |
+| :--- | :--- | :--- |
+| `TURSO_DATABASE_URL` | `libsql://your-db.turso.io` | **必填**。Turso 数据库的连接地址。 |
+| `TURSO_AUTH_TOKEN` | `ey...` | **必填**。Turso 数据库的访问令牌。 |
+| `OPENSPACE_API_KEY` | `your_secret_api_key_here` | **必填**。用于保护您的 API 不被恶意调用。前端也需要配置此 Key。 |
+| `OPENAI_API_KEY` | `sk-...` | （根据需要）您使用的大语言模型的 API Key。支持 `ANTHROPIC_API_KEY` 等其他受 LiteLLM 支持的密钥。 |
+| `PORT` | `7860` | **必填**。HuggingFace Docker 默认暴露端口为 `7860`，请勿更改此值。 |
+
+### 4. 推送代码触发部署
+
+将此 `Backend_HF` 目录中的所有文件直接推送到您的 HuggingFace Space 仓库。
+
+如果您在本地：
+```bash
+# 克隆您的 HF Space 仓库
+git clone https://huggingface.co/spaces/your-username/openspace-backend
+
+# 将 Backend_HF 里的文件复制进去
+cp -r /path/to/Backend_HF/* openspace-backend/
+
+# 提交并推送
+cd openspace-backend
+git add .
+git commit -m "Deploy OpenSpace backend"
+git push
+```
+
+推送完成后，HuggingFace 会自动读取根目录下的 `Dockerfile`，构建镜像并启动服务。当状态变为 **Running** 时，您的后端就部署成功了。
+
+---
+
+## ⏰ 防止休眠与自动备份 (GitHub Actions)
+
+HuggingFace 的免费 Space 如果长时间无人访问，会自动进入 **Sleeping** 状态。同时，Turso 的免费数据库如果 10 天不活跃也会被深度归档。
+
+为了保持服务 24/7 在线并定期备份高价值数据，强烈建议在您的 **GitHub 仓库**（存放本项目的私有仓库）中配置以下 GitHub Action：
+
+1. 在您的 GitHub 仓库中创建文件 `.github/workflows/keepalive_and_backup.yml`。
+2. 填入以下配置：
+
+```yaml
+name: OpenSpace Sync & KeepAlive
+
+on:
+  schedule:
+    - cron: '0 0,12 * * *' # 每天 UTC 0点和12点触发
+  workflow_dispatch:
+
+jobs:
+  backup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          
+      - name: Install Dependencies
+        run: pip install libsql-experimental
+      
+      - name: Ping HuggingFace Space
+        # 将这里的 URL 替换为您自己的 HF Space 的实际域名
+        run: curl -s -o /dev/null -w "%{http_code}" https://your-username-openspace-backend.hf.space/api/v1/health
+        
+      - name: Backup Core Data from Turso
+        env:
+          TURSO_DATABASE_URL: ${{ secrets.TURSO_DATABASE_URL }}
+          TURSO_AUTH_TOKEN: ${{ secrets.TURSO_AUTH_TOKEN }}
+        run: |
+          python -c '
+          import os, json, libsql_experimental as sqlite3
+          conn = sqlite3.connect(os.environ["TURSO_DATABASE_URL"], auth_token=os.environ["TURSO_AUTH_TOKEN"])
+          cursor = conn.cursor()
+          # Handle column mapping manually since libsql_experimental may not support row_factory
+          def fetch_dicts(cur, query):
+              cur.execute(query)
+              cols = [c[0] for c in cur.description]
+              return [dict(zip(cols, row)) for row in cur.fetchall()]
+          records = fetch_dicts(cursor, "SELECT skill_id, name, description, category, total_selections, total_applied, total_completions FROM skill_records")
+          lineage = fetch_dicts(cursor, "SELECT * FROM skill_lineage_parents")
+          os.makedirs("backups", exist_ok=True)
+          json.dump(records, open("backups/skill_records.json", "w"), ensure_ascii=False, indent=2)
+          json.dump(lineage, open("backups/skill_lineage.json", "w"), ensure_ascii=False, indent=2)
+          '
+          
+      - name: Commit and Push Backups
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git add backups/
+          git diff --quiet && git diff --staged --quiet || (git commit -m "Auto-backup: Turso Core DB" && git push)
+```
+
+3. 在该 GitHub 仓库的 **Settings -> Secrets and variables -> Actions** 中，添加 `TURSO_DATABASE_URL` 和 `TURSO_AUTH_TOKEN`。
+
+这样，GitHub Action 每天会自动访问您的 HF Space 防止其休眠，并将 Turso 中最有价值的技能树和元数据备份回 GitHub 的 `backups/` 目录中。