group_fqcd_jr

AI260626/group_fqcd_jr

Fork 0

Commit Graph

Author	SHA1	Message	Date
张胜宇	e5b4d02b0d	merge: 集成投顾组 3 个提交（解除与「投顾模块清除」的冲突）+ 客服 Agent 重构收口 ## 为什么要合并远端 `origin/qyqy_develop` 领先 3 个提交（`5607751` / `2fe7d0c` / `74b7d00`：投顾需求与架构文档、客户主动申报投顾方案 + 受理自动出草稿、方案交付落点与推荐依据 LLM 增强），而本地 `5d0becb` 按 `D4.4` / `D4.5`（CS-PURGE-2026-012/013）把投顾模块整体清除了。两个目标不可兼得：远端新代码反向 import 已被清除的模块（`app.model.investment_goal`、 `app.service.product_recommendation_service`、`app.service.advisor_rollout_service`），强行推进只会让两边都跑不起来。裁定：投顾组的新功能 > 本地的投顾清除。依据是 `D4.4` §0-②③ 自己写下的风险 ——按名字清投顾会同时拆掉产品数据底座与 MVP 硬阻断，并失去"改 6 个底座文件时的对照组"。本次合并因此恢复投顾模块；就代码面而言，`D4.4` / `D4.5` 的清除结果被本次合并取代（留痕见 `开发文档\D1.6` §4.37）。 ## 冲突怎么解的（12 处） - 8 处 modify/delete 取远端：`recommendations.py` / `product_recommendation_service.py` / `employee-advisor/dashboard/{actions-module.js,dashboard.css,dashboard.js,index.html}` / `tools/{check_portal_modules.py,grant_advisor_role.py}` —— 即"我删、远端改"，保留投顾文件。 - 3 处内容冲突取远端：`app/main.py`（投顾 import 与 `include_router`）、 `common/api-client.js`（投顾端点表）、`tests/unit/api/test_portal_frontend.py`（4 条投顾前端契约）。 - 1 处取远端 + 保留我方：`app/main.py` 解除冲突的同时，保留本轮的 `/customer-service-test` 挂载移除（该联调页与用例已随重构作废）。 ## 因"取消清除"而必须回滚的语义改动（否则恢复出来的投顾代码跑不动） - `app/service/agent/bootstrap.py`：恢复 `AdvisorAgent` 与 5 个投顾工具注册（`query_investment_goal` / `analyze_portfolio` / `generate_asset_allocation` / `recommend_products` / `compare_products`）；客服 Agent 注释按本轮口径保留。 - `app/core/config.py`：恢复 `advisor_rollout_enabled` / `advisor_rollout_customer_ids`。 - `app/static/portal/common/layout/app-shell.js`：恢复投顾工作台导航与 `advisor` 角色名。 - `tools/seed_test_rbac.py`：恢复"admin 取全量元组"的授权模型（保留远端新增的 9070-9074 权限码与客户侧 9071/9072 绑定）。 - `tools/portal_api_check.py`：恢复投顾实测用例（AD003/AD005/AD011/A047 与 `advisor_t` 登录），并新增判定：被渲染的集合为空（0 条）时判 `SKIP` 而不是 `FAIL` —— "没有行"与"字段没带"是两回事，混报会把排查方向带偏。 - `app/static/portal/common/api-client.js`：以远端为基准，重新叠加本轮的访客令牌 `Authorization` 优先修复（浮窗访客身份稳定性）。 ## 数据库夹具同步（代码恢复 ⇒ 夹具也要恢复） - `tools/grant_advisor_role.py`：新建 `advisor` 角色并授权（实测 34 项权限）。 - `tools/create_test_user.py --id 9020 --username advisor_t --role advisor`：重建演示账号。 ## 集成期发现并修掉的过期断言 - `tests/unit/test_advisor_migration_contract.py`：alembic 末端钉死值仍是 `20260914_baseline_auto_increment`，而远端新增了 `20260916_advisor_service_request` ⇒ 这条断言在远端分支上本身就是红的。本次把它更新到新末端并补了注释。 ## 验证（本机实测） \| 门禁 \| 结果 \| \|---\|---\| \| `pytest -q`（全量，含集成） \| 1909 passed / 3 skipped / 0 failed \| \| `ruff check app tools tests` \| 20（远端分支 22，本地仅客服线基线 19） \| \| `mypy app` \| 2（= 既有基线） \| \| `tools/portal_api_check.py` \| 40 项：通过 35 / 失败 0 / 跳过 5 \| \| `tools/e2e_smoke_test.py --read-only` \| 31/31 \| \| `_eval_harness/http_probe.py` \| 11/11 succeeded \| \| `_consistency.py` \| GATE PASS \| \| `_fe_boundary_http.py`（前端入参边界真机） \| 全部符合预期 \| ## 未做（如实登记） - 投顾演示数据未灌：`AD011` / `A047` 需要 `advisor_product_suitability_reference` 这类带 `source_url` + `document_sha256` 的证据行，而披露文件不在仓库里； `tools/seed_advisor_demo.py` 明确"不编证据"（fail closed），故这两条按空集 SKIP。 - 客服线文档目录仍未入库：`客服agent/`、`开发文档/`（权威副本在本机）与 `_chunks_report.txt`（本地构建产物）依旧排除在提交之外。	2026-09-20 14:52:35 +08:00
张胜宇	5d0becb67d	客服 Agent 重构收口：五出口决策链 + 知识库档位隔离 + 前端入参边界（答辩演示版本）一、客服 Agent 智能增强（正面回应"不智能、动不动就转人工"） - 决策链由 2 个出口扩到 5 个：E1 澄清 / E2 计算型 / E3 知识直返 / E4 证据约束生成 / E5 分级回退 - 转人工从"默认动作"降为最后一档 E5c，只保留 4 类白名单： P0 反诈 / P1 账户与个人数据 / P2 写操作与争议 / 用户明确要求人工 - 46 条金标实测（修复前 → 修复后）：转人工率 43.5% → 10.9%；出口准确率 45.7% → 100%；事实正确率 69.6% → 100% 禁忌违反 1 → 0；档位越权 / 无出处数字 / 误拒四项零容忍全 0 - 安全不变量 INV-1~INV-5；零容忍规则未删，改的是挂载点（输出侧字面黑名单 → 检索层档位隔离 + 判定层合规词表 + 输出守护）二、知识库：档位单点化与物理隔离 - 新增 app/core/knowledge_tier.py 作为档位规则唯一落点（G-03）， knowledge_contracts.py 原定义块改为显式再导出（X as X，非副本） - 档位过滤由 bool 默认值（fail-open）改为 tiers 必填集合（缺参即 TypeError） - Milvus 侧四集合按 visibility 分区键物理隔离；双 schema 收敛为一套 - 新增 app/core/actor.py：访客三元组与匿名判定的唯一构造/判定点（G-01/G-01b） - 新增 app/core/fund_fee_rules.py：费率计算纯函数三、前端入参边界对齐（本轮 W11 新修，4 处"校验宽于存储"） - message 加 max_length=8000（与浮窗 widget.js 的 maxlength 一致） - session_id 加 1—64；idempotency_key 上限 128 → 64（对齐列宽 String(64)） - feedback_type 加 max_length=32（对齐列宽 String(32)） - 8 条路径参数补 min_length=1 + max_length=64 + 字符集正则（{session_id} / {run_id} / {handover_id}） - 改前超限值会落到 MySQL 才失败（500）；改后一律 422 AGENT_INPUT_INVALID + 字段级定位 - 新增 tests/unit/api/test_frontend_boundaries.py（33 例），含"端点表 ↔ OpenAPI 全量对照" 四、投顾模块整体清除（D4.4 / D4.5） - 删除投顾相关 controller / schema / model / repository / service 及门户页面 - tools/portal_api_check.py 同步作废 AD003/AD005/AD011/A047 四条用例与 advisor_t 登录（端点与账号均已不存在，此前稳定报 3 条假红）五、验证（提交前实测） - pytest -q：1856 passed / 2 skipped / 0 failed - ruff check app tools tests：19（= 基线）；mypy app：2（= 基线） - 前端接口契约体检 portal_api_check.py：38 项，通过 34，失败 0，跳过 4 - 全链路冒烟 e2e_smoke_test.py --read-only：31/31 - HTTP 全链路探针 http_probe.py：11/11 succeeded - 跨文档一致性 _consistency.py：GATE PASS - 真机边界复验 12 条：12/12 符合预期六、纪律与文档 - 可改文件白名单 A-09（docs/46）与底座会签申请单 A-10（docs/47，组 1—组 4 全部受理） - 零 DDL：未新增/修改任何表结构，89 张业务表与基线一致 - 证据留痕：docs/evidence/**（含 46 条金标 score、快照、清除与重建记录） - 未提交（刻意排除，见提交说明）：仓库内客服agent/ 与开发文档/ 是 2026-09-16 前的过期副本（Todolist 440 行 vs 权威 D2.1 1167 行），权威正本在仓库外； _chunks_report.txt 是 tools/build_knowledge_chunks.py 生成的本地产物	2026-09-20 14:33:30 +08:00
lzf_0626	404f8f6aa5	固化接口体检脚本，并交付双击即用的启动 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（双击启动、两条自检线的分工）。	2026-09-14 01:59:46 +08:00

Author

SHA1

Message

Date

张胜宇

e5b4d02b0d

merge: 集成投顾组 3 个提交（解除与「投顾模块清除」的冲突）+ 客服 Agent 重构收口

## 为什么要合并
远端 `origin/qyqy_develop` 领先 3 个提交（`5607751` / `2fe7d0c` / `74b7d00`：投顾需求与架构文档、
客户主动申报投顾方案 + 受理自动出草稿、方案交付落点与推荐依据 LLM 增强），而本地 `5d0becb`
按 `D4.4` / `D4.5`（CS-PURGE-2026-012/013）把投顾模块整体清除了。**两个目标不可兼得**：
远端新代码反向 import 已被清除的模块（`app.model.investment_goal`、
`app.service.product_recommendation_service`、`app.service.advisor_rollout_service`），
强行推进只会让两边都跑不起来。

**裁定：投顾组的新功能 > 本地的投顾清除。** 依据是 `D4.4` §0-②③ 自己写下的风险
——按名字清投顾会同时拆掉产品数据底座与 MVP 硬阻断，并失去"改 6 个底座文件时的对照组"。
本次合并因此**恢复投顾模块**；就代码面而言，`D4.4` / `D4.5` 的清除结果被本次合并取代
（留痕见 `开发文档\D1.6` §4.37）。

## 冲突怎么解的（12 处）
- **8 处 modify/delete 取远端**：`recommendations.py` / `product_recommendation_service.py` /
  `employee-advisor/dashboard/{actions-module.js,dashboard.css,dashboard.js,index.html}` /
  `tools/{check_portal_modules.py,grant_advisor_role.py}` —— 即"我删、远端改"，保留投顾文件。
- **3 处内容冲突取远端**：`app/main.py`（投顾 import 与 `include_router`）、
  `common/api-client.js`（投顾端点表）、`tests/unit/api/test_portal_frontend.py`（4 条投顾前端契约）。
- **1 处取远端 + 保留我方**：`app/main.py` 解除冲突的同时，保留本轮的
  `/customer-service-test` 挂载移除（该联调页与用例已随重构作废）。

## 因"取消清除"而必须回滚的语义改动（否则恢复出来的投顾代码跑不动）
- `app/service/agent/bootstrap.py`：恢复 `AdvisorAgent` 与 5 个投顾工具注册
  （`query_investment_goal` / `analyze_portfolio` / `generate_asset_allocation` /
  `recommend_products` / `compare_products`）；客服 Agent 注释按本轮口径保留。
- `app/core/config.py`：恢复 `advisor_rollout_enabled` / `advisor_rollout_customer_ids`。
- `app/static/portal/common/layout/app-shell.js`：恢复投顾工作台导航与 `advisor` 角色名。
- `tools/seed_test_rbac.py`：恢复"admin 取全量元组"的授权模型（保留远端新增的
  9070-9074 权限码与客户侧 9071/9072 绑定）。
- `tools/portal_api_check.py`：恢复投顾实测用例（AD003/AD005/AD011/A047 与 `advisor_t` 登录），
  并**新增判定**：被渲染的集合为空（0 条）时判 `SKIP` 而不是 `FAIL`
  —— "没有行"与"字段没带"是两回事，混报会把排查方向带偏。
- `app/static/portal/common/api-client.js`：以远端为基准，重新叠加本轮的
  **访客令牌 `Authorization` 优先**修复（浮窗访客身份稳定性）。

## 数据库夹具同步（代码恢复 ⇒ 夹具也要恢复）
- `tools/grant_advisor_role.py`：新建 `advisor` 角色并授权（实测 34 项权限）。
- `tools/create_test_user.py --id 9020 --username advisor_t --role advisor`：重建演示账号。

## 集成期发现并修掉的过期断言
- `tests/unit/test_advisor_migration_contract.py`：alembic 末端钉死值仍是
  `20260914_baseline_auto_increment`，而远端新增了 `20260916_advisor_service_request`
  ⇒ 这条断言**在远端分支上本身就是红的**。本次把它更新到新末端并补了注释。

## 验证（本机实测）
| 门禁 | 结果 |
|---|---|
| `pytest -q`（全量，含集成） | **1909 passed / 3 skipped / 0 failed** |
| `ruff check app tools tests` | 20（远端分支 22，本地仅客服线基线 19） |
| `mypy app` | 2（= 既有基线） |
| `tools/portal_api_check.py` | 40 项：通过 35 / 失败 0 / 跳过 5 |
| `tools/e2e_smoke_test.py --read-only` | 31/31 |
| `_eval_harness/http_probe.py` | 11/11 succeeded |
| `_consistency.py` | GATE PASS |
| `_fe_boundary_http.py`（前端入参边界真机） | 全部符合预期 |

## 未做（如实登记）
- **投顾演示数据未灌**：`AD011` / `A047` 需要 `advisor_product_suitability_reference`
  这类带 `source_url` + `document_sha256` 的证据行，而披露文件不在仓库里；
  `tools/seed_advisor_demo.py` 明确"不编证据"（fail closed），故这两条按空集 SKIP。
- **客服线文档目录仍未入库**：`客服agent/`、`开发文档/`（权威副本在本机）与
  `_chunks_report.txt`（本地构建产物）依旧排除在提交之外。

2026-09-20 14:52:35 +08:00

张胜宇

5d0becb67d

客服 Agent 重构收口：五出口决策链 + 知识库档位隔离 + 前端入参边界（答辩演示版本）

一、客服 Agent 智能增强（正面回应"不智能、动不动就转人工"）
- 决策链由 2 个出口扩到 5 个：E1 澄清 / E2 计算型 / E3 知识直返 / E4 证据约束生成 / E5 分级回退
- 转人工从"默认动作"降为最后一档 E5c，只保留 4 类白名单：
  P0 反诈 / P1 账户与个人数据 / P2 写操作与争议 / 用户明确要求人工
- 46 条金标实测（修复前 → 修复后）：
  转人工率 43.5% → 10.9%；出口准确率 45.7% → 100%；事实正确率 69.6% → 100%
  禁忌违反 1 → 0；档位越权 / 无出处数字 / 误拒 四项零容忍全 0
- 安全不变量 INV-1~INV-5；零容忍规则未删，改的是挂载点
  （输出侧字面黑名单 → 检索层档位隔离 + 判定层合规词表 + 输出守护）

二、知识库：档位单点化与物理隔离
- 新增 app/core/knowledge_tier.py 作为档位规则唯一落点（G-03），
  knowledge_contracts.py 原定义块改为显式再导出（X as X，非副本）
- 档位过滤由 bool 默认值（fail-open）改为 tiers 必填集合（缺参即 TypeError）
- Milvus 侧四集合按 visibility 分区键物理隔离；双 schema 收敛为一套
- 新增 app/core/actor.py：访客三元组与匿名判定的唯一构造/判定点（G-01/G-01b）
- 新增 app/core/fund_fee_rules.py：费率计算纯函数

三、前端入参边界对齐（本轮 W11 新修，4 处"校验宽于存储"）
- message 加 max_length=8000（与浮窗 widget.js 的 maxlength 一致）
- session_id 加 1—64；idempotency_key 上限 128 → 64（对齐列宽 String(64)）
- feedback_type 加 max_length=32（对齐列宽 String(32)）
- 8 条路径参数补 min_length=1 + max_length=64 + 字符集正则
  （{session_id} / {run_id} / {handover_id}）
- 改前超限值会落到 MySQL 才失败（500）；改后一律 422 AGENT_INPUT_INVALID + 字段级定位
- 新增 tests/unit/api/test_frontend_boundaries.py（33 例），含"端点表 ↔ OpenAPI 全量对照"

四、投顾模块整体清除（D4.4 / D4.5）
- 删除投顾相关 controller / schema / model / repository / service 及门户页面
- tools/portal_api_check.py 同步作废 AD003/AD005/AD011/A047 四条用例与 advisor_t 登录
  （端点与账号均已不存在，此前稳定报 3 条假红）

五、验证（提交前实测）
- pytest -q：1856 passed / 2 skipped / 0 failed
- ruff check app tools tests：19（= 基线）；mypy app：2（= 基线）
- 前端接口契约体检 portal_api_check.py：38 项，通过 34，失败 0，跳过 4
- 全链路冒烟 e2e_smoke_test.py --read-only：31/31
- HTTP 全链路探针 http_probe.py：11/11 succeeded
- 跨文档一致性 _consistency.py：GATE PASS
- 真机边界复验 12 条：12/12 符合预期

六、纪律与文档
- 可改文件白名单 A-09（docs/46）与底座会签申请单 A-10（docs/47，组 1—组 4 全部受理）
- 零 DDL：未新增/修改任何表结构，89 张业务表与基线一致
- 证据留痕：docs/evidence/**（含 46 条金标 score、快照、清除与重建记录）
- 未提交（刻意排除，见提交说明）：仓库内 客服agent/ 与 开发文档/ 是 2026-09-16 前的
  过期副本（Todolist 440 行 vs 权威 D2.1 1167 行），权威正本在仓库外；
  _chunks_report.txt 是 tools/build_knowledge_chunks.py 生成的本地产物

2026-09-20 14:33:30 +08:00

lzf_0626

404f8f6aa5

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

2026-09-14 01:59:46 +08:00