固化接口体检脚本，并交付双击即用的启动 bat

## tools/portal_api_check.py（新）

把 2026-09-13 那轮"照着接口内容把前端测一遍"的验证固化成可重复跑的脚本。
当时靠这套验证查出 6 个真缺陷，但它们只存在于一次会话里，下次改动没人会重跑：

- `K002`/`K003` 是裸信封，前端按 `payload.data` 取 -> 知识库页显示"已入库 0 块 / 为空"
- 委托/成交详情页照着建表字段写，而接口返回视图没带那些列 -> 5 行永远显示 `--`
- 配置项/路由规则的 `PUT` 要 `If-Match`，却没有端点能返回该 digest -> 首次编辑必然 409
- 回复模板 `scene` 只校验长度不校验枚举 -> 非法值撞数据库 CHECK、冒成 500
- 路由规则表单固定 `max_attempts=2` 且 `fallbacks` 为空 -> 后端必然 422
- 模型端点手填 ID -> 未激活的 ID 直接 422

与 `e2e_smoke_test.py` 分工互补：后者测**业务链路通不通**，本脚本测**接口契约对不对**
（状态码、信封形状、字段名与前端期望是否一致）。

三档，默认只跑第一档：
- 默认只读 41 项（不动数据）
- `--write` 加测写操作：配置项 ETag 链路、`max_attempts` 越界、知识库上传+失效、
  回复模板非法枚举、敏感词、推广物料全链路
- `--dangerous` 再加测会改生效配置的操作（激活配置版本会整版本替换，默认不跑，
  脚本内注明了恢复办法）

实测：只读 39/39、写入档 54/54 全绿。

## 桌面一键启动（双击即用）

桌面 `启动金融Agent平台.bat` + 仓库 `启动平台.bat`，由
`tools/make_launcher_bat.py` 生成，只负责"双击"这一层，启动逻辑复用 `start.ps1`
（不重复实现，避免两边漂移）。参数可透传：`-Port 8100` / `-NoBrowser` / `-SkipPriceSync`。

不要手写这个 bat：必须同时满足 **GBK 编码 + CRLF 换行 + 无 BOM**。生成器自己
读回来校验这三条。踩过的坑：用 `write_bytes` 直接落盘时没转 CRLF，cmd 对 LF-only
批处理会行边界错乱，把 `echo` 的说明文字当命令执行（实测报
`AT 命令已弃用`、`']' 不是内部或外部命令`）。

## start.ps1 的三处修复

1. **解释器探测选错环境（真机双击失败的主因）**
   原先只验证 `--version` 成功就选中，结果挑到一个 Python 3.10 环境：
   本项目用了 `datetime.UTC`（3.11+）且依赖 `asyncmy`，启动当场 ImportError ——
   而报错发生在**行情刷新**那一步，看起来像"行情源坏了"。
   现在实测两项：**版本 >= 3.11** + `import fastapi, sqlalchemy, asyncmy, pydantic` 通过，
   并在跳过时打印具体原因。

2. **`Select-Object -First 1` 掐断 native 管道**
   `& $exe -c ... 2>&1 | Select-Object -First 1` 拿到首个对象后停掉上游管道，
   等于把进程掐了、`$LASTEXITCODE` 变脏，于是**每个候选都被误判成"无法执行"**
   （连装好的 jr_py313 也被跳过）。改为先整体接住输出、再在结果上取行。

3. **幂等 + 就绪探测 + Docker 自动拉起**
   重复双击不再起第二个 API/Worker（API 按端口、Worker 按进程判断）；
   起完等 `/internal/health/ready` 真正应答才报成功；Milvus 不可达时尝试拉起
   Docker Desktop 并最多等 60 秒（它不常驻，是"知识检索静默降级"最常见的原因）。

## 实测

- `启动平台.bat` 重复执行：解释器正确选中 jr_py313、依赖检查全 OK、行情已刷新、
  两个服务识别为已在跑并跳过、就绪探测 1 秒
- `-Port 8199` 冷启动：新起 API 窗口，8199 的 `/internal/health/ready` 与 `/portal/` 均 200，
  测试后已清理
- `ruff check app tests tools alembic hq.py` -> All checks passed
- `start.ps1` 语法解析通过（BOM 已保留）、bat 三项编码约束校验通过

文档同步：`AGENTS.md`（启动方式、bat 生成器、解释器探测两个坑）、
`docs/44-演示流程.md` §0.3/§0.4（双击启动、两条自检线的分工）。

AGENTS.md

@@ -31,16 +31,31 @@
 > 启动：`python -m uvicorn app.main:app --port 8000`（注意模块级变量是 **`app`**，不是 `application`）。
 > `tools/portal.py`（8101）**只是跨角色联调工具，不是产品前端**，不要再往它加功能。
 >
-> **🚀 一键启动与演示（2026-09-13 起）**：根目录 **`start.ps1`**
-> （`powershell -ExecutionPolicy Bypass -File start.ps1`）按序做四件事：
-> 找解释器 → 检查 MySQL/Redis/Milvus → **刷新行情** → 起 **API 与 Agent Worker 两个窗口**。
+> **🚀 一键启动与演示（2026-09-13 起）**：**不想敲命令就直接双击桌面的
+> `启动金融Agent平台.bat`**（仓库里也有一份 `启动平台.bat`）。它按序做六件事：
+> 找解释器 → 检查 MySQL/Redis/Milvus → **刷新行情** → 起 **API 与 Agent Worker 两个窗口**
+> → **等 API 真正应答** → 自动开浏览器。**重复双击是安全的**（API 按端口、Worker 按进程判断，
+> 不会起第二份）；参数可透传，如 `启动平台.bat -Port 8100`、`-NoBrowser`、`-SkipPriceSync`。
+> bat 由 **`python tools/make_launcher_bat.py`** 生成（改完 `start.ps1` 或想换路径就重跑它，
+> 桌面与仓库两份一起更新）—— 不要手写那个 bat，它必须同时满足 **GBK 编码 + CRLF 换行 + 无 BOM**，
+> 缺任何一条 cmd 都会解析错乱（LF 换行会把 `echo` 的说明文字当命令执行，
+> 实测报 `AT 命令已弃用`、`']' 不是内部或外部命令`）。
+> 也可以直接用脚本：`powershell -ExecutionPolicy Bypass -File start.ps1`。
 > 演示数据一键准备：`python tools/seed_demo_data.py`（10 步，顺序有依赖，见脚本内表格）；
 > **演示流程（8 个场景照读版 + 排障表 + 账号速查）见 `docs/44-演示流程.md`**；
-> 交付自检：`python tools/e2e_smoke_test.py`（6 条线 40 项，`--read-only` 不动数据）。
+> 交付自检（**两条线互补，都跑一遍**）：
+> `python tools/e2e_smoke_test.py`（**业务链路**冒烟：登录→下单→成交、风控扫描→处置闭环、客服问答，6 条线 40 项，`--read-only` 不动数据）；
+> `python tools/portal_api_check.py`（**接口契约**体检：按前端的方式调每个端点，核对状态码、信封形状与字段是否与前端期望一致，41 项；`--write` 加测写操作、`--dangerous` 再加测会改生效配置的操作）。
 > ⚠️ **`start.ps1` 必须保存为 UTF-8 with BOM**：Windows PowerShell 5.1 在缺 BOM 时按系统
 > ANSI（简中为 GBK）解析，中文注释直接抛 `Unexpected token '[璀﹀憡]'` 这类语法错误。
 > 用 `edit`/`write` 类工具改完**务必补回 BOM**（只加字节、别重写换行：
 > `d=open(p,'rb').read(); open(p,'wb').write(b'\xef\xbb\xbf'+d)`）。
+> ⚠️ **解释器探测必须实测「能 import 依赖」，不能只看 `--version` 成功**：
+> 曾经因此选中一个 Python 3.10 环境（本项目用 `datetime.UTC`，3.11+ 才有，且依赖 `asyncmy`），
+> 报错却发生在**行情刷新**那一步，看起来像"行情源坏了"。现在的门槛是
+> **版本 ≥ 3.11 + `import fastapi, sqlalchemy, asyncmy, pydantic` 通过**。
+> 另注：`... 2>&1 | Select-Object -First 1` 会掐断上游 native 进程、把 `$LASTEXITCODE` 弄脏，
+> 在探测循环里用它会**把每个候选都判成"无法执行"** —— 先接住输出再取行。
 > ⚠️ **行情有效期只有 15 分钟**（`app/service/trade_service.py` 的 `MAX_QUOTE_AGE`），
 > 超时后**所有委托一律 503「行情已过期」**且无自动刷新 —— 这是演示最容易翻的一环。
 > 补刷用 `python tools/sync_market_prices.py`，**立即生效、无需重启服务**。