固化接口体检脚本，并交付双击即用的启动 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（双击启动、两条自检线的分工）。

docs/44-演示流程.md

@@ -40,25 +40,48 @@ python tools/sync_market_prices.py
 
 ### 0.3 启动平台
 
+**最省事的办法：双击桌面上的 `启动金融Agent平台.bat`。** 不用开 PowerShell、不用敲命令。
+（仓库根目录也有一份 `启动平台.bat`，是同一个东西。）
+
+它按顺序做六件事：**找解释器 → 检查 MySQL/Redis/Milvus → 刷新行情 → 起两个窗口
+→ 等 API 真正应答 → 自动开浏览器**，然后打印访问入口与账号。
+
+> **重复双击是安全的**：API 按端口判断、Worker 按进程判断，已经在跑的不会起第二份。
+> 演示前如果服务已经开着，直接双击它就等于"刷新行情 + 打开页面"。
+
+想传参数就用命令行（bat 会把参数原样转给 `start.ps1`）：
+
 ```powershell
-powershell -ExecutionPolicy Bypass -File start.ps1
+powershell -ExecutionPolicy Bypass -File start.ps1              # 等价于双击
+powershell -ExecutionPolicy Bypass -File start.ps1 -NoBrowser   # 不自动开浏览器
+powershell -ExecutionPolicy Bypass -File start.ps1 -Port 8100   # 换端口（8000 被别的程序占了）
 ```
 
-它按顺序做四件事：**找解释器 → 检查 MySQL/Redis/Milvus → 刷新行情 → 起两个窗口**，然后打印访问入口与账号。
-它会**开两个窗口**：
+它**开两个窗口**：
 
 | 窗口 | 作用 | 少了它会怎样 |
 |---|---|---|
 | API | 所有接口与页面 | 什么都没有 |
 | **Worker** | Agent 对话、知识向量同步、记忆抽取、风控扫描 | 客服对话一直"超时"；新知识不进 Milvus 且**无任何报错** |
 
+> ⚠️ 两个窗口都别关。启动脚本自己的窗口跑完就可以关（服务在独立窗口里）。
+
 ### 0.4 开场前自检（务必做）
 
+两条线互补，都跑一遍：
+
 ```powershell
-python tools/e2e_smoke_test.py --read-only
+python tools/e2e_smoke_test.py --read-only    # 业务链路：登录→下单→成交、风控闭环、客服问答
+python tools/portal_api_check.py              # 接口契约：按前端的方式核对每个端点的状态码与字段
 ```
 
-看最后一行：**40/40 通过**才开始演示。有 FAIL 就按 §4 排查。
+看最后一行：**40/40** 与 **41 项全通过**才开始演示。有 FAIL 就按 §4 排查。
+
+> 两者的分工：`e2e_smoke_test.py` 回答"**这条业务走得通吗**"，
+> `portal_api_check.py` 回答"**接口返回的东西前端能不能正确显示**"。
+> 后者是 2026-09-13 那轮"照着接口把前端测一遍"的固化 —— 当时靠它查出 6 个真缺陷
+> （知识库页永远显示 0 块、详情页 5 行全是 `--`、配置项首次编辑必然 409、非法场景值冒成 500 等）。
+> 加 `--write` 会再测一遍写操作（会产生数据）；`--dangerous` 会动生效配置，**演示前不要加**。
 
 ### 0.5 打开第一个页面