harden probe agent v1.0.3

安全鉴权、默认只读、显式提交开关、状态接口与测试

README.md

@@ -1,39 +1,69 @@
 # huni-probe-agent
 
-信创模盒 ModelHub XC 适配智能体 · **只读探针骨架 (probe-only)**。
+信创模盒 ModelHub XC 适配智能体安全探针 `v1.0.3`。
 
-对照官方样例 `luopingyi/xc_agent_platform_demo`（最小合规骨架）扩了一个零副作用探针。
+它用于验证「建仓 → Kaniko 构建 → 部署 → `/health` → 平台 API 鉴权 → 可控提交」链路。默认只读，只有显式开启提交开关后才会创建验证任务。
 
-## 用途
+## 安全行为
 
-1. 验证平台「建仓 → Kaniko 构建 → 部署 → `/health` → 运行/停止」整条链路是否通。
-2. 零副作用观测平台注入的 `STRATEGY_ID` / `EXTERNAL_SERVICE_TOKEN` 是否为有效凭证：
-   启动时用注入 token 调一次**只读** `GET /api/adapt/task/page`，看返回 `code`：
-   `0` = 凭证有效；`40100` = 未登录/凭证无效。
+- 默认只调用一次只读接口 `GET /api/adapt/task/page`。
+- 空凭证和 `tmp`、`placeholder` 等占位值会被拒绝，不会继续请求。
+- 任何日志和 HTTP 状态响应都不包含 token 值或长度。
+- 只有 `ALLOW_SUBMIT=1` 且只读鉴权成功，才会调用 `build-config` 和 `task/add`。
+- 每个进程生命周期最多调用一次 `task/add`，没有自动重试。
+- `/health` 始终只代表容器存活；链路结果请查看 `/status`。
 
-## 满足的运行时契约
+## 凭证注入
 
-- 根目录 `Dockerfile`，`EXPOSE 8080`
-- `GET /health` 返回 HTTP 200（K8s livenessProbe）
-- 读取 `STRATEGY_ID` 与 `EXTERNAL_SERVICE_TOKEN` 环境变量
-- 处理 `SIGTERM`，优雅停机（30s 窗口内退出）
-- 资源占用极小，符合 requests 100m/256Mi、limits 1C/512Mi
+按以下优先级读取凭证：
 
-## 明确不做
+1. `XC_TOKEN_FILE`：Kubernetes Secret 挂载文件路径，推荐。
+2. `XC_TOKEN`：由 Kubernetes Secret 注入的环境变量。
+3. `EXTERNAL_SERVICE_TOKEN`：兼容平台旧变量名。
 
-- **绝不提交任何验证任务**（不调 `task/add`，不调 `build-config`）。
-- 不打印 token 值、不落盘任何凭证；探针仅调只读 GET，仅记录 `http/code/计数`。
+不要把 token 写进代码、Dockerfile、Git 仓库或智能体名称。平台侧应通过 Kubernetes Secret 注入真实凭证；如果仍注入 `tmp`，探针会进入 `blocked_missing_auth`，不会误提交。
 
-## 本地运行
+## 运行时变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `STRATEGY_ID` | 无 | 平台策略 ID，必填 |
+| `ALLOW_SUBMIT` | `0` | 设置为 `1` 才允许单次提交 |
+| `MAIN_HOST` | `https://modelhub.org.cn` | 平台 API 地址 |
+| `PORT` | `8080` | HTTP 监听端口 |
+| `TEST_MODEL` | TrialSpace-1225-GGUF | 验证模型地址 |
+| `GPU` | `MetaX_c-500` | 目标 GPU |
+| `FW` | `vllm` | 推理框架 |
+| `TT` | `text-generation` | 任务类型 |
+
+## 状态接口
+
+- `GET /health`：容器存活检查，HTTP 200。
+- `GET /status`（或 `/`）：返回安全状态，不返回凭证。
+
+关键 `phase`：
+
+- `blocked_missing_strategy_id`：平台未注入策略 ID。
+- `blocked_missing_auth`：没有可用凭证，或只拿到了占位凭证。
+- `auth_failed`：只读鉴权请求未通过。
+- `read_only_complete`：鉴权通过，默认只读流程完成。
+- `build_config_failed`：配置生成失败，已阻止后续提交。
+- `submit_complete` / `submit_failed`：显式开启后，单次提交成功或失败。
+
+## 本地验证
 
 ```bash
-python main.py
-curl http://localhost:8080/health     # {"status":"ok"}
-curl http://localhost:8080/           # 查看探针结果
+python -m unittest -v
+
+PORT=8080 STRATEGY_ID=local-test python main.py
+curl http://localhost:8080/health
+curl http://localhost:8080/status
 ```
 
+本地没有凭证时，预期状态是 `blocked_missing_auth`。
+
 ## 上平台
 
-推到 `https://dev.modelhub.org.cn/<user>/<repo>` 并保留一个**真 git 标签**（如 `v1.0.0`；
-平台 Kaniko 按 `refs/tags/<tag>` 解析，用分支名会失败）。再在「我的适配智能体 → 新增智能体」
-填 名称 / 仓库地址 / 标签 提交。
+推到 `https://dev.modelhub.org.cn/<user>/<repo>` 并创建真实 Git 标签（例如 `v1.0.3`）。在「我的适配智能体 → 新增智能体」填写名称、仓库地址、标签。平台 Kaniko 按 `refs/tags/<tag>` 构建，不能用分支名代替标签。
+
+建议先保持 `ALLOW_SUBMIT=0`，确认 `/status` 为 `read_only_complete`；再由平台管理员把它改为 `1`，仅跑一次验证任务，验证后立即恢复为 `0`。