diff --git a/README.md b/README.md
index bdecfc7..a7bdcbc 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,39 @@
 # huni-probe-agent
 
-ModelHub XC 适配智能体·只读探针骨架
\ No newline at end of file
+信创模盒 ModelHub XC 适配智能体 · **只读探针骨架 (probe-only)**。
+
+对照官方样例 `luopingyi/xc_agent_platform_demo`（最小合规骨架）扩了一个零副作用探针。
+
+## 用途
+
+1. 验证平台「建仓 → Kaniko 构建 → 部署 → `/health` → 运行/停止」整条链路是否通。
+2. 零副作用观测平台注入的 `STRATEGY_ID` / `EXTERNAL_SERVICE_TOKEN` 是否为有效凭证：
+   启动时用注入 token 调一次**只读** `GET /api/adapt/task/page`，看返回 `code`：
+   `0` = 凭证有效；`40100` = 未登录/凭证无效。
+
+## 满足的运行时契约
+
+- 根目录 `Dockerfile`，`EXPOSE 8080`
+- `GET /health` 返回 HTTP 200（K8s livenessProbe）
+- 读取 `STRATEGY_ID` 与 `EXTERNAL_SERVICE_TOKEN` 环境变量
+- 处理 `SIGTERM`，优雅停机（30s 窗口内退出）
+- 资源占用极小，符合 requests 100m/256Mi、limits 1C/512Mi
+
+## 明确不做
+
+- **绝不提交任何验证任务**（不调 `task/add`，不调 `build-config`）。
+- 不打印 token 值、不落盘任何凭证；探针仅调只读 GET，仅记录 `http/code/计数`。
+
+## 本地运行
+
+```bash
+python main.py
+curl http://localhost:8080/health     # {"status":"ok"}
+curl http://localhost:8080/           # 查看探针结果
+```
+
+## 上平台
+
+推到 `https://dev.modelhub.org.cn/<user>/<repo>` 并保留一个**真 git 标签**（如 `v1.0.0`；
+平台 Kaniko 按 `refs/tags/<tag>` 解析，用分支名会失败）。再在「我的适配智能体 → 新增智能体」
+填 名称 / 仓库地址 / 标签 提交。