Phase1 skeleton: replace demo main.py with src.server contract

- Overlay ModelHub XC Phase1 (health/status, STRATEGY_ID gate, dry-run) - Dockerfile CMD -> python -m src.server; FROM stays platform TCR base - Remove demo main.py and requirements.txt (stdlib only) - Add tests/, scripts/, docs/, Makefile, config/examples (no secrets)
2026-10-16 15:47:10 +08:00
parent 26351cefee
commit 0d0f3b611a
31 changed files with 1436 additions and 106 deletions
--- a/docs/api-probe-design.md
+++ b/docs/api-probe-design.md
@@ -0,0 +1,38 @@
+# API 探针设计（只读意图 · 禁止代调写接口）
+
+- 日期：2026-10-16 Asia/Shanghai
+- Phase1：**仅设计文档**；本仓不实现真实 HTTP 写客户端
+
+## 管理 API `/agent_platform/strategies*`
+
+| 方法 | 路径 | 本仓态度 |
+|------|------|----------|
+| POST | `/agent_platform/strategies` | **禁止代调**（注册） |
+| POST | `.../{id}/deploy` | **禁止代调** |
+| POST | `.../{id}/stop` | **禁止代调** |
+| DELETE | `.../{id}` | **禁止代调** |
+| GET | `.../{id}` | 未来只读探针可选（Phase3+，需 Victor 授权） |
+| GET | `.../{id}/logs` | 未来只读探针可选 |
+
+鉴权（浏览器）：`Authorization: Bearer <login token>`（等级 A）。
+
+## 适配任务 API
+
+| 方法 | 路径 | 本仓态度 |
+|------|------|----------|
+| GET | `/api/adapt/task/page` | 未来只读鉴权探针（对齐 huni-probe，`ALLOW_SUBMIT=0`） |
+| POST | `/api/adapt/task/build-config` | 设计可引用；Phase1 不实现 |
+| POST | `/api/adapt/task/add` | **禁止代调**；live 仅闸门 + 单测假客户端 |
+| GET | `/api/adapt/task/calculate-credit` | 只读索引；勿写死 KPI |
+
+容器内社区鉴权（C）：`Xc-Token` + body `strategyId` — **待 Victor 账号核实**后再实现探针。
+
+## Phase1 落地边界
+
+- `src/gate.py`：闸门逻辑 + `attempt_live_submit(..., client=Fake)` 仅供单测
+- **无**默认 `urllib`/`requests` 客户端指向 `task/add` 或 `strategies` POST
+- Makefile **无** register / submit / deploy / push
+
+## 冲突裁决提醒
+
+适配 W1：队列 ≥95 → 禁 live；智能体不抢验证空位。
--- a/docs/build-notes.md
+++ b/docs/build-notes.md
@@ -0,0 +1,59 @@
+# Build notes
+
+- 日期：2026-10-16 Asia/Shanghai
+- 默认 `FROM`：`modelhubxc-4pd.tencentcloudcr.com/xc_agent_platform/python:3.11-slim`
+- **禁止**因本地拉不下而改默认 FROM 为公网镜像
+
+## 本机（box）首次尝试
+
+| 项 | 结果 |
+|----|------|
+| `docker` CLI | **未安装 / 不可用**（`which docker` 空） |
+| `make build` | 预期失败：`docker not found`（Makefile 显式报错） |
+| 默认 FROM | **未修改** |
+
+### 后续建议（Victor）
+
+1. 在有 Docker 且能访问腾讯云 TCR 平台镜像的环境执行 `make build`
+2. 若 `docker pull` 平台 base 失败：把完整错误贴本文件「拉取失败记录」，仍保持默认 FROM
+3. 无镜像时用本地验收：`STRATEGY_ID=test make smoke-health` / `make test`
+
+## 拉取失败记录
+
+（尚无 Docker，无 pull 日志。有 Docker 后在此追加。）
+
+## 2026-10-16 13:46 Asia/Shanghai — `make build` 实测
+
+```text
+ERROR: docker not found. See docs/build-notes.md
+make: *** [Makefile:19: build] Error 1
+```
+
+- 原因：box 无 Docker 引擎/CLI，**未发生**平台 base `docker pull`（因此无 TCR 拉取错误日志）
+- 默认 `FROM modelhubxc-4pd.tencentcloudcr.com/xc_agent_platform/python:3.11-slim` **未改**
+- 替代验收：`make test` 绿；`STRATEGY_ID=test make smoke-health` 绿（本地 `python -m src.server`）
+
+## 2026-10-16 Asia/Shanghai — Victor Mac `make build`
+
+- Docker Desktop：已连接
+- 结果：失败 — `modelhubxc-4pd.tencentcloudcr.com/xc_agent_platform/python:3.11-slim` pull access denied / insufficient_scope
+- 默认 FROM：未修改
+
+## 2026-10-16 Asia/Shanghai — Codex 沙箱复测
+
+- `make build` 实际退出 2：`ERROR: docker not found. See docs/build-notes.md`。
+- 无 Docker，未尝试拉取 TCR；本机结果不能证明 TCR 可达或不可达。上文 Mac 的拒绝记录为已有人工证据，未在本轮复现。
+- `STRATEGY_ID=test make smoke-health` 实际退出 2：沙箱创建 socket 被拒，`PermissionError: [Errno 1] Operation not permitted`。
+- `make test`：优化后 19 项中 18 项通过，SIGTERM 集成项在监听前同样被 socket 权限阻塞；未跳过或标绿。
+- 默认平台 base / FROM 保持原样；须在允许本地 socket、具备 Docker 与 TCR 权限的环境复验完整 DoD。
+
+## 2026-10-16 ~15:20 Asia/Shanghai — tcr-then-build 探测（Mac）
+
+- Docker Desktop：已连接；`docker` CLI 可用
+- `~/.docker/config.json`：`auths` 空，`credsStore=desktop` → **未登录** TCR
+- `docker pull modelhubxc-4pd.tencentcloudcr.com/xc_agent_platform/python:3.11-slim`：
+  `Error response from daemon: pull access denied ... may require 'docker login'`
+- 默认 FROM：**未修改**
+- 既有 `agent-contrib:local`（sha256:95a4d01e2b55…）：**不算**本轮 DoD（CMD=`src.main`，基底公网 python:3.11-slim）
+- 验收标准：`/Users/vc/modelhub-adapt-logs/agent-image-dod-2026-10-16.md`（box 同源 `/workspace/modelhub-adapt/logs/agent-image-dod-2026-10-16.md`）
+- 阻塞：需 Victor 提供 TCR 账号并对 `xc_agent_platform/python` 有 pull，执行 `docker login modelhubxc-4pd.tencentcloudcr.com` 后重试 pull + `make build`
--- a/docs/diff-vs-demo.md
+++ b/docs/diff-vs-demo.md
@@ -0,0 +1,40 @@
+# 对照官方演示仓 `luopingyi/xc_agent_platform_demo`
+
+- 日期：2026-10-16 Asia/Shanghai
+- 官方演示：https://dev.modelhub.org.cn/luopingyi/xc_agent_platform_demo
+- 安全探针参照：`huni/huni-probe-agent`（只读）
+- **不要照搬**：`huni/huni-adapt-agent` 默认真提交循环
+
+## 对齐项（保留）
+
+| 项 | demo / 规划 | 本仓 |
+|----|-------------|------|
+| 根目录 Dockerfile | 是 | 是 |
+| 默认 base 镜像 | 平台 `python:3.11-slim` | 同（`BASE_IMAGE` 仅 build-arg，默认不改公网） |
+| `EXPOSE 8080` | 是 | 是 |
+| `GET /health` → 200 `{"status":"ok"}` | 是 | 是 |
+| 读 `EXTERNAL_SERVICE_TOKEN` 是否存在 | demo | `/status` 布尔；永不打值 |
+| stdlib / 轻依赖 | demo 极简 | Phase1 仅 stdlib |
+
+## 本仓相对 demo 的补强
+
+| 项 | 说明 |
+|----|------|
+| `STRATEGY_ID` 启动校验 | Phase1：**缺失则 exit ≠0**（产品规划；相对「仅读 token 保活」的社区变体） |
+| 双重 live 闸门 | `ALLOW_LIVE_SUBMIT` + `LIVE_CONFIRM=I_CONFIRM_LIVE_SUBMIT` |
+| `GET /status` | 仅布尔字段 |
+| dry-run 报告 | `scripts/dry_run.py` → `reports/dry-run-*.md` |
+| 单测 | health / 缺 STRATEGY_ID / 闸门默认拒绝 / SIGTERM |
+| 无默认真提交 | live 仅闸门 + **注入假客户端**单测；仓库无默认真打 `/api/adapt/task/add` 的 HTTP 客户端 |
+
+## 明确不照搬
+
+| 来源 | 行为 | 本仓 |
+|------|------|------|
+| huni-adapt-agent | 默认真提交循环 | **禁止** |
+| CoolBoy / 社区刷分脚本 | 绕队列 / 无闸门 | **禁止** |
+| 旧对话口径「缺 STRATEGY_ID 保活 + /health 仍 200」 | 与产品规划 Phase1 冲突 | **以产品规划为准：启动失败** |
+
+## 资源声明
+
+文档按约 **100m–1 CPU / 256–512Mi** 设计；Phase1 不做 k8s manifests。
--- a/docs/issues.md
+++ b/docs/issues.md
@@ -0,0 +1,47 @@
+# Issue / Phase 清单
+
+对齐 PRD M0–M4 与产品规划 Phase 0–5。
+
+## Phase / Milestone 映射
+
+| Phase（产品规划） | PRD | 状态（本仓） |
+|-------------------|-----|--------------|
+| Phase 0 调研冻结 | M0 | 文档已落 `docs/` |
+| Phase 1 本地可部署样例 | M1 | **本轮交付** |
+| Phase 2 Dry-run 闭环 | M2 | 骨架：`scripts/dry_run.py`；**待对接 pending-submit**：A→B / PASS / 硬门尚未自动核验 |
+| Phase 3 人工注册 + 只读探针 | M3 | 仅 runbook / api-probe-design；**不代注册** |
+| Phase 4 一次 live 验证 | M4 | 闸门已备；**无真实客户端** |
+| Phase 5 规模化 | — | 未开 |
+
+## P0 Issues
+
+- [x] docs: 冻结智能体平台契约（health/STRATEGY_ID/SIGTERM/资源）
+- [x] docs: 对照 xc_agent_platform_demo 写 diff-vs-demo
+- [x] chore: 初始化 Dockerfile / Makefile / example.env
+- [x] feat: GET /health 200 + STRATEGY_ID 校验（缺则启动失败）
+- [x] feat: SIGTERM 优雅退出（≤30s；测试 <5s）
+- [x] feat: dry-run 报告生成器（默认模式）
+- [x] feat: live 人工确认闸门 + 单测（默认拒绝）
+- [x] docs: 注册智能体 runbook — 仅人工
+- [x] chore: tag_release（只打本地 tag，不 push / 不注册）
+- [x] docs: api-probe-design（禁止代调写接口）
+
+Phase1 构建与运行验收须独立记录；环境阻塞不等于通过。
+
+## P1（未做）
+
+- [ ] 对接 `/workspace/modelhub-adapt/pending-submit.md` A→B 只读
+- [ ] 结构化 JSON 日志（禁密钥）
+- [ ] evidence-agent 模板填写
+
+## P2（未做）
+
+- [ ] 贡献台账 CSV
+- [ ] 多 Tag 矩阵
+
+## 硬边界（持续）
+
+- 无 register / submit / deploy / push Makefile 目标
+- 无 `/agent_platform/strategies*` 写调用
+- 无 `/api/adapt/task/add` 真客户端
+- 适配 W1 优先；不抢队列
--- a/docs/kickoff-for-victor.md
+++ b/docs/kickoff-for-victor.md
@@ -0,0 +1,43 @@
+# 开工包（一页）— Victor
+
+**仓路径（本地）**：`/workspace/modelhub-agent-contrib/`  
+**远程**：Gitea 命名空间/仓名 **未定** → Phase1 以本地验收为主  
+**模式**：默认 dry-run；**不代注册、不代提交**
+
+## 闸门
+
+| 条件 | 值 |
+|------|-----|
+| `ALLOW_LIVE_SUBMIT` | 默认 `0` |
+| `LIVE_CONFIRM` | 空；live 须 `I_CONFIRM_LIVE_SUBMIT` |
+| `STRATEGY_ID` | **启动必需**；缺失 → exit ≠0 |
+| 真实 `task/add` | Phase1 **未实现**（仅假客户端单测） |
+
+## 本地命令
+
+```bash
+cd /workspace/modelhub-agent-contrib
+make test
+make build          # 需 Docker + 可达平台 base；失败见 docs/build-notes.md
+make smoke-health   # 无镜像时脚本会拉起本地 server
+make dry-run        # 生成 reports/dry-run-*.md
+```
+
+入口：`python -m src.server`（Dockerfile `CMD` 同）
+
+## 验收勾选（Phase1）
+
+- [ ] `make test` 绿（health / 缺 STRATEGY_ID / 闸门拒绝 / SIGTERM）
+- [ ] `make build` 绿 **或** `docs/build-notes.md` 记录平台镜像拉取失败且 **未改默认 FROM**
+- [ ] `make smoke-health` 绿（镜像或本地 server）
+- [ ] 根目录 Dockerfile + `EXPOSE 8080`
+- [ ] README 写清：发布 = 0 分；积分待核实；不代注册/提交
+- [ ] Makefile **无** register/submit/deploy/push
+- [ ] dry-run 报告含「需 Victor 人工提交」「积分：待平台核实」
+- [ ] 未调用任何 ModelHub 写接口
+
+## 人工下一步（非本 Phase 自动化）
+
+1. 定 Gitea `<namespace>/<repo>`
+2. push + tag（`scripts/tag_release.py` 仅本地 tag）
+3. 控制台新增智能体（见 `docs/register-runbook.md`）
--- a/docs/platform-contract-agent.md
+++ b/docs/platform-contract-agent.md
@@ -0,0 +1,62 @@
+# 平台契约 — 适配智能体（Phase1）
+
+- 日期：2026-10-16 Asia/Shanghai
+- 依据：产品规划 `agent-product-plan-2026-10-16.md` §1 + PRD `02-agent-contribution-prd.md`
+- **冲突裁决：适配 W1 优先**（队列 ≥95 禁 live；本骨架默认 dry-run）
+
+## 核实等级
+
+| 等级 | 含义 |
+|------|------|
+| **A** | 官方演示仓 / 主站前端明文 |
+| **B** | PRD 已核实（docs/6 + 控制台，基线 2026-10-12） |
+| **C** | 社区样例，非平台承诺 |
+| **D** | 待核实 |
+
+## 运行契约
+
+| 项 | 内容 | 等级 |
+|----|------|------|
+| 代码托管 | `dev.modelhub.org.cn` 用户仓 | B |
+| 注册 UI | 名称、仓库地址、**Git Tag**（不可用分支名） | B |
+| 构建 | 平台 Kaniko，`refs/tags/<tag>` | B |
+| Dockerfile | **仓库根目录**；base `modelhubxc-4pd.tencentcloudcr.com/xc_agent_platform/python:3.11-slim` | A |
+| 端口 | **8080**，`EXPOSE 8080` | A |
+| 健康检查 | `GET /health` → 200 `{"status":"ok"}` | A |
+| 可选状态 | `GET /status` → 布尔 `strategy_id_present` / `external_service_token_present`（**不回传值**） | 本仓 Phase1 |
+| 优雅退出 | `SIGTERM`，约 **≤30s** 平台窗口；本实现目标 ~1s 退出主循环 | B |
+| 平台注入 | `STRATEGY_ID`；`EXTERNAL_SERVICE_TOKEN`（及社区别名） | A/B |
+| **STRATEGY_ID 缺失** | **Phase1：进程启动失败（exit ≠0）** | 产品规划 Phase1 + PRD |
+| 资源 | 约 100m–1 CPU / 256–512Mi | B |
+| **发布智能体得分** | **0 分**（发布 ≠ 得分） | B |
+| Live 默认 | **关**；双重闸门 `ALLOW_LIVE_SUBMIT=1` + `LIVE_CONFIRM=I_CONFIRM_LIVE_SUBMIT` | 本仓 |
+| 积分 | 来自**成功适配**；智能体代提成功计同一成功分；公式/周报 **待平台核实** | B / D |
+
+## 鉴权双轨（文档索引，Phase1 不代调）
+
+| 场景 | 头 | 等级 |
+|------|----|------|
+| 浏览器 / `agent_platform` | `Authorization: Bearer <login token>` | A |
+| 容器内社区实践 | `Xc-Token: <token>`；body 带 `strategyId` | C |
+
+## 禁止
+
+- 代注册、代 live 提交、Makefile 含 register/submit/deploy/push
+- 日志/响应/镜像层写入 token 或 STRATEGY_ID **值**
+- 把「智能体已发布」写入千分进度
+
+## 冲突裁决（强制）
+
+| 资源 | 裁决 |
+|------|------|
+| 异步验证队列 | 适配 W1 优先；≥95 全体停交（含智能体 live） |
+| Codex | hold 期扩池/归因 > 智能体脚手架 |
+| 本骨架 | 默认 dry-run；本轮无真实 `task/add` HTTP 客户端 |
+
+## 闸门配置以实现为准
+
+`src/gate.py` 只接受 `ALLOW_LIVE_SUBMIT=1` 与
+`LIVE_CONFIRM=I_CONFIRM_LIVE_SUBMIT`（去除首尾空白后精确匹配）。
+PRD 的 `ALLOW_LIVE_SUBMIT=true` / `CONFIRM_LIVE=YES` 仅为需求示例，
+本仓不支持这些值/别名，也不读取确认文件。开闸无客户端仍 blocked。
+这只是本地逻辑闸门，不代表已获 live 授权或已校验队列与候选硬门。
--- a/docs/register-runbook.md
+++ b/docs/register-runbook.md
@@ -0,0 +1,39 @@
+# 注册智能体 Runbook（仅人工 · Victor）
+
+> Agent / Bot **不代填、不代点、不代调写接口**。
+
+## 流程
+
+1. **本地绿**：`make test`（及有 Docker 时 `make build` + `make smoke-health`）
+2. **Gitea 建仓**（Victor）：`dev.modelhub.org.cn/<namespace>/<repo>`  
+   - 命名空间/仓名 **未定**时：仅本地验收，不阻塞 Phase1
+3. **推送代码**（Victor 本人）：本 Makefile **无 push 目标**
+4. **打 Git Tag**（可用本仓 `scripts/tag_release.py` **仅本地 tag**；push tag 由 Victor 执行）
+5. **控制台新增**：个人主页 → 我的适配智能体 → 新增  
+   - 名称  
+   - 仓库地址（远程 Git URL）  
+   - **Git Tag**（须先出现在远程；`GET .../tags` 下拉可选后再填）
+6. **Kaniko 构建**：等待状态；证据同时记中文文案与枚举（`building` / `ready` / `failed` / `running` / `stopped`）
+7. **部署后**：确认容器 `GET /health` → 200；积分应 **无变化**（发布 = 0 分）
+
+## POST `/agent_platform/strategies`（文档说明 · 禁止代调）
+
+| 字段 | 说明 |
+|------|------|
+| `name` | 策略显示名 |
+| `repo_url` | Gitea 仓库 URL |
+| `tag` | Git Tag（非分支） |
+
+成功响应含 `.id`（等级 A：前端 bundle）。  
+**本仓与 Agent 禁止代调该写接口。**
+
+相关写接口（同样禁止代调）：`/{id}/deploy`、`/{id}/stop`、`DELETE /{id}`。
+
+## 环境变量（平台注入 / 控制台）
+
+| 变量 | 说明 |
+|------|------|
+| `STRATEGY_ID` | 策略 id；本仓启动必需 |
+| `EXTERNAL_SERVICE_TOKEN` | 服务凭证；只检存在，不记值 |
+| `ALLOW_LIVE_SUBMIT` | 默认 `0` |
+| `LIVE_CONFIRM` | live 时须为 `I_CONFIRM_LIVE_SUBMIT` |