张胜宇
5d0becb67d
一、客服 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 生成的本地产物
94 lines
8.2 KiB
Markdown
94 lines
8.2 KiB
Markdown
# 可改文件白名单（客服 Agent 重构 · 纪律凭据）
|
||
|
||
> **文档编号**：`A-09` · **依据**：`D2.1` 决策 1（`P-1`）／决策 19 · **日期**：2026-09-19
|
||
> **一句话**：本次客服 Agent 重构**只允许**改动下面四类文件；**白名单之外一律不动**。
|
||
> **性质**：纪律凭据（可审计）。本文件与 `D2.1` §1.1 / §1.3 / §1.4 / §1.5 必须始终一致。
|
||
|
||
---
|
||
|
||
## 1. 四类白名单
|
||
|
||
### 类 1 · 纯新增（不触碰任何底座件）
|
||
|
||
客服模块自有**新文件**。新增不改变既有行为，风险最低。
|
||
|
||
| 新增件 | 说明 |
|
||
|---|---|
|
||
| `app/core/actor.py` | 访客三元组与匿名判定**单点构造**（`G-01`/`G-01b`） |
|
||
| `app/core/fund_fee_rules.py` | 费率计算纯函数（`H-02a` 参数层） |
|
||
| `app/core/knowledge_tier.py`、`app/core/customer_service_rules.py` | 客服业务层规则 |
|
||
| `tools/knowledge_corpus_gate.py` | 语料入库门禁（`乙-18`；从构建脚本抽出以便单测） |
|
||
| `knowledge/basic/*.md`、`knowledge/_chunks.jsonl` | 第 4 集合语料与分块产物（`乙-7`） |
|
||
| `tests/**` 新增用例 | 只增不改，不影响运行时代码 |
|
||
|
||
### 类 2 · 允许修改（客服业务层，无需会签）
|
||
|
||
| 目录 / 文件 | 边界 |
|
||
|---|---|
|
||
| `app/service/agent/implementations/customer_service.py` | 客服 Agent 本体 |
|
||
| `app/core/customer_service_rules.py` | 客服话术与规则常量 |
|
||
| `app/static/portal/**` | 门户前端（含客服浮窗 `customer-service-widget/`、`api-client.js`、`app-shell.js`） |
|
||
| `tools/**` | 开发/种子/自查脚本（不改运行时行为） |
|
||
| `docs/**`、`客服agent/**`、`开发文档/**` | 文档与证据 |
|
||
|
||
### 类 3 · 提案后由底座方修改（**须会签**）
|
||
|
||
即 `D2.1` **§1.1 六文件八处** + **§1.3 四文件**。逐项会签申请见 `A-10`（`docs/47-底座会签申请单-2026-09-19.md`）。
|
||
|
||
| 组 | 文件 | 触碰项 |
|
||
|---|---|---|
|
||
| 组 1 | `app/service/knowledge_search_service.py` | `D-01`（`tiers` 必填）、`D-02`（表达式按集合逐个拼） |
|
||
| 组 1 | `app/service/knowledge_tool.py` | `D-04`（档位由身份推导） |
|
||
| 组 1 | `app/core/compliance_context.py` | `C-04`（`NEGATION_CUES` 补短否定式） |
|
||
| 组 1 | `app/service/agent/governance.py` | `B-05`（删第 2 份热线副本与死分支） |
|
||
| 组 1 | `app/service/agent_run_application_service.py` | `D-06` + `F-01`（访客 `customer_id` 取值 + 历史读取主体过滤） |
|
||
| 组 1 | `app/service/agent_persistence_service.py` | `E-01`（建单白名单 + `priority` + `reason_code` 枚举化） |
|
||
| 组 1 | `app/service/tool_executor.py` | `C-10`（**条件触发**：仅当来源引用选「实现」且底座方受理） |
|
||
| 组 2 | `app/core/security.py`、`app/worker/runtime.py`、`app/api/dependencies/auth.py`、`app/service/agent/base.py` | `G-01` / `G-01b`（访客权威单点化） |
|
||
|
||
### 类 4 · 禁止修改（**红线**）
|
||
|
||
`D2.1` §1.5 零改动清单继续有效，**除类 3 已列明者外**一律不动：
|
||
|
||
`app/service/agent/factory.py`、`app/service/agent/authorizer.py`、`app/core/memory_scope.py`、`app/infrastructure/**`、`app/model/**`、`alembic/**`、`tools/seed_test_rbac.py`（只跑不改）、`docs/00-新数据库基线设计.md`、`check_suitability` / `query_customer_profile` / `query_fund_quote` 的实现、**产品数据底座全部文件**。
|
||
|
||
> ⚠️ **两条被明确移出类 4 的项（需会签，已登记）**：
|
||
> 1. `app/api/**`、`app/worker/**`、`app/service/agent/base.py` —— 由批次 G 触碰（`D2.1` §1.3，`G-01`/`G-01b`）。
|
||
> 2. `app/core/knowledge_contracts.py`、`app/core/knowledge_schema.py` —— 原在 §1.5 零改动清单内，`乙-7`（第 4 集合白名单）与 `H-05`（档位分区/双 schema 收敛）触碰，**已于 2026-09-20 补签受理**，见 `A-10` §3。
|
||
> 3. `app/api/schemas/agent_runs.py`、`app/api/schemas/conversations.py`、`app/api/controllers/public_platform.py`、`app/api/controllers/agent_runs.py`、`app/api/controllers/conversations.py` —— `W11` 前端入参边界对齐（`FE-01`/`FE-02`/`FE-03`），**已于 2026-09-20 补签受理**，见 `A-10` §4。
|
||
> 4. `app/core/knowledge_tier.py` —— **纯新增**（类 1），但它**接管**了 `knowledge_contracts.py` 原有的档位定义块（`G-03` 搬运），因此也在 `A-10` §3 留痕。
|
||
|
||
---
|
||
|
||
## 2. 零 DDL 声明
|
||
|
||
本次重构**不新增、不修改任何数据库表结构**：
|
||
|
||
| 断言 | 证据 |
|
||
|---|---|
|
||
| 零 DDL | 无 `alembic/versions/**` 新增或修改；表结构基线未变 |
|
||
| 表数量不变 | `python tools/audit_schema.py` = **89 张业务表**（与基线一致） |
|
||
| 新增字段一律复用既有列 | 工单 `priority` / `reason_code`、画像 `risk_tags`、`conversation_message.tool_calls` 均为**既有列** |
|
||
| Milvus 侧 | 集合重建属**数据层**动作（`drop` + 重灌），不涉及 MySQL 表结构 |
|
||
|
||
---
|
||
|
||
## 3. 实际改动对照（相对 `HEAD`，2026-09-19）
|
||
|
||
> 口径：`git status --porcelain` 中 `app/` / `tools/` / `tests/` 的**非删除项**。逐项归入上表四类。
|
||
> 结论：**全部落在类 1—类 3 之内**；其中落在类 4 原文清单、须补会签的只有 §1 表格末尾列出的两个文件（已登记）。
|
||
|
||
| 归类 | 文件（相对 `HEAD`） |
|
||
|---|---|
|
||
| 类 1 纯新增 | `app/core/actor.py`、`app/core/fund_fee_rules.py`、`app/core/knowledge_tier.py`（`G-03` 档位单点落点）、`tools/knowledge_corpus_gate.py`，以及 `tests/**` 全部新增用例（含 `tests/unit/core/test_knowledge_tier.py`、`tests/unit/api/test_frontend_boundaries.py`）、`knowledge/basic/**`、`knowledge/_chunks.jsonl` |
|
||
| 类 2 客服业务层 | `app/service/agent/implementations/customer_service.py`、`app/core/customer_service_rules.py`、`app/static/portal/**`（含 `common/customer-service-widget/widget.js`、`common/api-client.js`、`common/layout/app-shell.js`、`common/visitor-token.js`）、`tools/**`（`build_knowledge_chunks.py`、`e2e_smoke_test.py`、`seed_*.py`、`sync_nanfang_official_product_governance.py`、`setup_milvus_knowledge_collections.py`、`load_knowledge_milvus.py` 等） |
|
||
| 类 3 已会签组 1 | `app/service/knowledge_search_service.py`、`app/service/knowledge_tool.py`、`app/core/compliance_context.py`、`app/service/agent/governance.py`、`app/service/agent_persistence_service.py`、`app/service/agent_run_application_service.py` |
|
||
| 类 3 已会签组 2 | `app/core/security.py`、`app/worker/runtime.py`、`app/api/dependencies/auth.py`、`app/service/agent/base.py` |
|
||
| 类 3 **已受理**（`A-10` §3，2026-09-20 补签） | `app/core/knowledge_contracts.py`（`乙-7` 第 4 集合白名单 + `G-03` 档位定义改为再导出）、`app/core/knowledge_schema.py`（`H-05` 双 schema 收敛） |
|
||
| 类 3 **已受理**（`A-10` §4，`W11` 入参边界对齐，2026-09-20 补签） | `app/api/schemas/agent_runs.py`（`message`/`session_id`/`idempotency_key` 上限对齐）、`app/api/schemas/conversations.py`（`feedback_type` 上限 32）、`app/api/controllers/public_platform.py`、`app/api/controllers/agent_runs.py`、`app/api/controllers/conversations.py`（路径参数 `{session_id}`/`{run_id}`/`{handover_id}` 补长度与字符集约束） |
|
||
| 同批非客服模块改动（**不在本次客服重构范围**，属投顾清除与风控修复批次） | `app/api/controllers/admin.py`、`app/core/config.py`、`app/core/contracts.py`、`app/main.py`、`app/repository/profile_repository.py`、`app/service/agent/bootstrap.py`、`app/service/agent/implementations/risk_agent.py`、`app/service/auth_service.py`、`app/service/knowledge_config.py`、`app/service/knowledge_ingest_service.py`、`app/service/profile_assembly_service.py`、`app/service/profile_generation_service.py`、`app/service/public_platform_service.py`、`app/service/risk_analysis_service.py`、`app/worker/risk_scan_scheduler.py`、`tools/api_console.py`、`tools/chat_console.py`、`tools/portal.py`、`tools/check_rbac_seed_consistency.py`、`tools/seed_compliance_baseline.py`、`tools/seed_demo_data.py`、`tools/seed_knowledge_r1r5_faq.py`、`tools/seed_profile_demo.py`、`tools/seed_test_rbac.py`、`tools/setup_milvus_profile_collection.py` |
|
||
|
||
---
|
||
|
||
**维护**：白名单变更须同步 `D2.1` §1 与本文件；新增类 3 项**必须**先补 `A-10` 会签申请单。
|