张胜宇
c91bbcbdc1
一、密钥轮换（新增工具 + 操作手册） - 新增 tools/rotate_api_keys.py：--check 体检 + 交互式轮换；getpass 不回显、 自动备份 .env.bak-<时间戳>（已被 ignore 命中）、校验不过整体不写入、 三个 Qwen 变量写同一值 / 两个 DeepSeek 变量写同一值。 实测 --check：Qwen 三变量同值且非空、DeepSeek 两变量同值且非空。 - 新增 开发文档/D3.8-模型密钥轮换与凭据安全操作手册-2026-09-20.md（CS-OPS-2026-023）： .env 5 个变量与读取方取证、五步流程、3 个坑、复核清单、回退方式、能力边界。 - 口径确认：model_endpoint_config.secret_ref 存变量名 ⇒ 轮换只改 .env，不动 DB； 但必须重启 API + Worker。 二、门禁修复：docs/ 编号撞车 - tools/check_authoritative_docs.py（D3.4 N-14 登记的验收命令集之一）实测 FAIL： 我方 docs/46 docs/47（2026-09-20 建）与投顾组 docs/46-投顾Agent需求文档.md docs/47-投顾Agent功能架构文档.md（2026-09-16 建）同号。 - 按「后到者让位」改名：docs/48-可改文件白名单.md / docs/49-底座会签申请单-2026-09-19.md， 同步 8 处引用。修复后：checked 54 documents, no number collision，exit 0。 三、前端品牌残留（W12 合并静默回退） - employee-advisor/dashboard/index.html 与 customer/advisor-plans/index.html 的 <title> 仍是 南方财富（投顾组分支带回）→ 按 DEC-27 改为 南方基金。 - HTTP 实测两页标题已正确；全仓 app/ 复查 南方财富 = 0。 四、文档口径校准（12 处事实漂移） - D1.1：D2.1 版本 v5.3 → v6.26（§4.0 / §4.1 / §1 / §2 四处长期错误）； §8 四行遗留项闭合（D-5 / D-6 / D-7 / 仓库副本同步）+ 新增 §22 §23 留痕； §10.2「本区不在任何 git 仓库内」更正为已入库；新增两编号 ⇒ 计数 56 → 58 全量同步。 - D2.2：顶栏徽标 v2.4 与元数据 v2.5 自相矛盾 → 统一；「投顾已清除」→ 状态更新 （模块 2026-09-20 已恢复，但客服范围裁定 §1.7 / RK-10 不变）。 - D2.3：徽标 v1.0 · 7 批次 51 项 → v1.1 · 8 批次 57 项；投顾清除后果 + §7.1 头号风险 + 风险表 + 不触碰行全部加恢复口径。 - D2.4：v1.3 变更说明 ⑦ / §1.4 Out of scope / Q-09 加投顾恢复口径。 - D2.5：advisor_t 自相矛盾口径改写为账号表一行 + 口径更正；五项自检首选改为 一键脚本 启动演示.bat / demo.ps1；补 D3.8 与未发布 advisor:* 白名单登记。 - D2.6：门禁数字 1856/2 → 1909/3 skipped、ruff 19 → 20、补 portal_api_check 行； §10 两项已闭环（密钥轮换已工具化、A-10 组 3/4 已补签）；头部加 W12/W13 状态更新。 - D4.5：顶部状态更新补指向 D4.7。 - 新增 开发文档/D4.7-投顾模块恢复记录-2026-09-20.md（CS-PURGE-2026-014）： 时间线、8 项恢复动作、客服线不变的结论、DEC-19 理由更正、遗留 1 项、失误登记。 - _consistency.py（维护侧）：§三 改为「投顾状态口径检查」，合法语境扩为 清除史 / 恢复史 / 不属本 Agent 范围。 五、回归实测（全绿） - pytest -q：1909 passed / 3 skipped / 0 failed - ruff check app tools tests：20（与 W12 持平，未引入新债） - mypy app：2（= 既有基线） - tools/check_authoritative_docs.py：54 文档无编号冲突（exit 0） - tools/e2e_smoke_test.py --read-only：31/31 - tools/portal_api_check.py：40 项 通过 35 / 失败 0 / 跳过 5 - _eval_harness/http_probe.py：11/11 succeeded - _consistency.py：GATE PASS - demo.ps1 -SkipStart -NoBrowser：五项自检全过、退出码 0 - 权威副本 ↔ 仓库：逐字节一致（客服agent 24 / 开发文档 52） 六、未做（如实登记） - 投顾 config_release 工具白名单（advisor:*）仍未发布 ⇒ 投顾 Agent 工具调用 fail closed （实测 active_agent_tools 仅 customer_service:* 4 项 + risk:* 4 项）。与客服线无关； 要演投顾线先跑 tools/publish_advisor_demo_config.py --apply。 - 两把 key 的实际轮换需你在控制台建新 key（无法代做），流程见 D3.8。
8.2 KiB
8.2 KiB
可改文件白名单（客服 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/49-底座会签申请单-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 的项（需会签，已登记）：
app/api/**、app/worker/**、app/service/agent/base.py—— 由批次 G 触碰（D2.1§1.3，G-01/G-01b）。app/core/knowledge_contracts.py、app/core/knowledge_schema.py—— 原在 §1.5 零改动清单内，乙-7（第 4 集合白名单）与H-05（档位分区/双 schema 收敛）触碰，已于 2026-09-20 补签受理，见A-10§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。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 会签申请单。