feat: ModelHub XC 适配智能体（/health + /stats + 批量提交 worker）

README.md

@@ -0,0 +1,97 @@
+# 信创模盒适配智能体（ModelHub XC Adapt Agent）
+
+按《信创模盒适配智能体提交说明》（https://www.modelhub.org.cn/#/docs/6 ）实现的策略镜像：
+自动从社区模型库挑选候选模型，按卡批量提交国产算力适配验证任务。
+
+## 一、平台契约对照
+
+| 平台要求 | 本仓库实现 |
+|---|---|
+| 仓库根目录 Dockerfile | `Dockerfile`，基于 `modelhubxc-4pd.tencentcloudcr.com/xc_agent_platform/python:3.11-slim` |
+| 暴露运行端口 | `EXPOSE 8080` |
+| `GET /health` 返回 200 | `main.py` 内置 HTTP 服务，`/health` → `{"status":"ok"}` |
+| 环境变量 `STRATEGY_ID` | 提交任务时填入请求体 `strategyId` |
+| 优雅停机（SIGTERM，30s） | 收到信号置位 `STOP`，worker 退出后关闭服务，保存状态 |
+| 资源 100m/256Mi ~ 1C/512Mi | 纯标准库、单线程 worker，常驻内存 < 40MB |
+
+另外平台会注入 `EXTERNAL_SERVICE_TOKEN`（即个人主页的 xcToken），请求头用 `Xc-Token`。
+
+## 二、目录结构
+
+```
+.
+├── Dockerfile         # 镜像构建
+├── main.py            # 服务入口：/health、/stats + 后台提交 worker
+├── cards.py           # 11 张目标算力卡的 GPU 标识、默认框架、configParams 模板
+├── requirements.txt   # 空文件（仅用 Python 标准库，无需第三方依赖）
+└── README.md
+```
+
+`cards.py` 里的 `configParams` 直接取自平台网页端选择「适配成功率最高」框架后自动生成的 YAML，
+与手工在页面提交时下发的配置完全一致，避免因启动命令/端口/显存参数写错导致验证失败。
+
+## 三、业务流程
+
+1. `POST /api/computility/models/list/page/vo` 拉模型库（22 个种子关键词 × 最多 5 页）；
+2. 过滤：仅 `文本生成`、已在 ≥`MIN_MACHINES` 张卡适配成功（说明仓库完整）、
+   排除 GGUF / AWQ / GPTQ / 量化（int4/int8/w8a8/w4a16/quantized/fp8/nvfp4）/ LoRA / adapter 等仓库；
+3. 逐卡提交 `POST /api/adapt/task/add`，请求头 `Xc-Token`，请求体含 `strategyId`；
+4. 返回码处理：
+   - `0` 成功，计入进度并落盘；
+   - `60027` 该卡已适配成功 → 跳过该组合；
+   - `60028` 该组合正在验证中 → 跳过该组合；
+   - `50000` 上游仓库拉取失败（模型已删除等）→ 跳过；
+   - `401/403/60014` 凭证或策略问题 → 记录错误并退避，不空转；
+5. 每个模型最多提交 `QUOTA_PER_MODEL` 次（默认 2），避免同一模型刷满所有卡。
+
+## 四、环境变量
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `STRATEGY_ID` | 平台注入 | 策略 ID，必填 |
+| `XC_TOKEN` / `EXTERNAL_SERVICE_TOKEN` | 平台注入 | xcToken，请求头 `Xc-Token` |
+| `TARGET_TASKS` | 250 | 本策略要提交成功的任务数 |
+| `QUOTA_PER_MODEL` | 2 | 同一模型最多提交几次 |
+| `MIN_MACHINES` | 2 | 模型至少已在几张卡适配成功才入选 |
+| `INTERVAL_SEC` | 1.5 | 两次提交间隔 |
+| `MAX_ATTEMPTS` | 4000 | 总尝试上限，防止无限循环 |
+| `MODELHUB_API_BASE` | https://www.modelhub.org.cn | 接口域名 |
+| `DRY_RUN` | 空 | 置 1 时不真正提交，用于本地自测 |
+| `STATE_FILE` | /tmp/modelhub_agent_state.json | 进度落盘，重启可续跑 |
+
+## 五、本地自测（不联网提交）
+
+```bash
+pip install -r requirements.txt
+DRY_RUN=1 STRATEGY_ID=demo TARGET_TASKS=5 python main.py
+curl http://127.0.0.1:8080/health     # {"status":"ok"}
+curl http://127.0.0.1:8080/stats      # 进度、错误码分布、最近一次事件
+```
+
+## 六、上线步骤
+
+1. **建仓库**：在 https://dev.modelhub.org.cn 新建仓库（例如 `xc-adapt-agent`），把本目录推上去：
+
+   ```bash
+   git init && git add . && git commit -m "feat: modelhub xc adapt agent"
+   git remote add origin https://dev.modelhub.org.cn/<你的用户名>/xc-adapt-agent.git
+   git push -u origin main
+   ```
+
+2. **生成 xcToken**：官网个人主页 → 设置里生成/刷新 xcToken（该 token 由平台注入到容器）。
+
+3. **注册智能体**：官网 → 个人主页 →「我的适配智能体」→「新增智能体」，
+   填写名称、仓库地址、标签，提交后列表出现该智能体。
+
+4. **运行**：在列表点「运行」启动，点「停止」中止。运行后访问 `/stats` 查看提交进度：
+
+   ```json
+   {"submitted": [...], "attempts": 63, "codes": {"0": 20, "60028": 41}, "progress": "20/250"}
+   ```
+
+## 七、注意事项
+
+- 平台对「重复/低质提交」有监控，`TARGET_TASKS` 不建议一次性设得很大，可分日多轮运行；
+- 提交成功的任务仍需平台排队验证，`/stats` 只统计**提交成功**，最终是否适配成功以任务列表为准；
+- 若 `/stats` 出现 `60014`，说明 `Xc-Token` 或 `strategyId` 不匹配，检查 token 是否刷新、智能体是否已上线；
+- 容器被 RESTART 后 worker 会读取 `STATE_FILE` 续跑，不会重复提交已成功的组合。