# D1.1 · 文档索引与权威声明
> **体系编号**：`D1.1` · 域：一、治理与索引 · 编号体系见 `D1.1` §4.0
> **编号**：CS-DOC-2026-017 | **版本**：v1.19 | **日期**：2026-09-21 | **状态**：**现行（活文档，随文档区变动同步更新）**
> **性质**：本文件是 `开发文档\` 的**唯一入口**。任何人（含三个月后的自己）打开这一份，就应知道：先读什么、哪份为准、每份什么状态。
> **盘点范围**：`开发文档\`（**54 个文件** = 53 份编号文档 + 1 份入口存根 `CLAUDE.md`，无归档子目录）+ `客服agent\`（**10 份**对外交付文档）。
---
## 0. 一句话结论
**63 份文档（62 份编号 + 1 份不占编号的入口存根 `CLAUDE.md`）已按 8 个域统一编号为 `D<域>.<序>`（规则见 §4.0，层级见 §3）。开工只读 5 份 = `D2.1` / `D2.2` / `D2.3` / `D2.4` / `D3.3`（见 §2）。**
| 域 | 名称 | 份数 | 定位 |
|---|---|---|---|
| **D1** | 一、治理与索引 | 6 | 先读 `D1.1`（本文件）——编号体系、权威链、开工只读集 |
| **D2** | 二、对外交付 | 10 | 🔴 **开工必读**（A1—A4；另含 `D2.5` 演示脚本、`D2.6` 答辩报告、`D2.7` 记忆与画像联动、`D2.8` RAG 全链路、`D2.9` 手动对话测试用例、`D2.10` 端到端答辩文档） |
| **D3** | 三、现行权威·完整版与专项 | 9 | 查证据、查 FR 推导过程（含 A5 鉴权专项 `D3.3`；检索升级 `D3.5`；架构 `D3.6`；**评测金标 `D3.7`**；**密钥轮换 `D3.8`**；**智能路由与行情出口 `D3.9`**） |
| **D4** | 四、清除与重建留痕 | 7 | 追溯「删了什么、怎么恢复」；`D4.1` 即**重建指南**，`D4.6` 为验收基线留痕，`D4.7` 为**投顾恢复现状** |
| **D5** | 五、业务流程基线 | 1 | 两条业务线 / 三条红线 / 演示跑通验收 |
| **D6** | 六、公司事实与知识源 | 17 | 🔴 改写知识库、核对数据口径 |
| **D7** | 七、早期系统文档 | 5 | 状态待确认；仅在追查历史口径时读（**不可删**，见 §10） |
| **D8** | 八、AI 协作规则 | 8 | 让 AI 接手时的规则文件（含 1 份**不占编号**的入口存根 `CLAUDE.md`） |
> 🔑 **编号三处必须一致**：① 索引 §4.0 总表；② 文档标题正下方（体系编号行）；③ 文件名前缀（`<编号>-<描述名>`）。**唯一例外 `CLAUDE.md`**（规则见 §5 R7；迁移记录见 §11）。🔁 **2026-09-19 起**：语言规范正文已独立成文 `D8.1-项目语言规范.md`，`CLAUDE.md` 收缩为**三行入口存根**（见 §4.7 与 §20）。
> 🔑 **`客服agent\` 与 `开发文档\` 是「收敛版 vs 完整版」关系，不是分叉。**
> `客服agent\` 的 9 份是**对外交付 + 唯一开工入口**；`开发文档\` 内的同名旧版是**取证底稿**（含被收敛掉的备选方案与逐条证据）。
> 两者若冲突，**一律以 `客服agent\` 为准**。
---
## 1. 权威链与更新顺序
```
对外交付（客服agent\） 配套完整版 / 前身（开发文档\）
────────────────────────────────── ─────────────────────────────────────
A1 [D2.1] D2.1-客服Agent执行Todolist.md v6.39 ←→ [D3.4] D3.4-客服Agent重构Todolist.md v5.1
A2 [D2.2] D2.2-客服Agent需求文档.html v2.7 ←→ [D3.1] D3.1-客服Agent需求开发文档与设计方案.html v2.6
A3 [D2.3] D2.3-客服Agent开发计划.html v1.1 ←→ （无旧版）
A4 [D2.4] D2.4-客服Agent知识库设计方案.html v1.8 ←→ [D3.2] D3.2-知识库设计方案.html v1.6
A5 [D3.3] 访客与角色分离的鉴权方案建议（仅此一份，无新旧之别）
```
**更新顺序（改需求必须先动上游）**：
```
① 需求文档（A2） → ② Todolist（A1） → ③ 开发计划（A3） → ④ 知识库设计方案（A4）
↓
⑤ 知识源（开发文档\公司信息|公司业务|金融政策|用户研判规则）
```
> ⚠️ **不要反向改**：先改 Todolist 再回头改需求，会让 A1/A2 的 FR 编号错位（A2 的 **FR-CS-001~052** 是全项目编号源；v2.5 起新增域 H 的 `FR-CS-049`~`052`）。
---
## 2. 🔴 开工只读这 5 份
| # | 体系编号 | 文档 | 版本 | 作用 |
|---|---|---|---|---|
| **A1** | **D2.1** | `客服agent\D2.1-客服Agent执行Todolist.md` | **v6.39** | **唯一开工入口**。**57 项 / 8 批次（A—H）** / 12 步关键路径 / 2 组会签 / **完工判据 13 条**。**新增批次 H · 智能增强**（`H-01`~`H-06`） |
| **A2** | **D2.2** | `客服agent\D2.2-客服Agent需求文档.html` | **v2.7** | 对外需求：**FR-CS-001~052**（52 条，新增域 H）+ NFR-CS-001~021 全量、身份与鉴权模型、验收标准（**新增 AC-13 金标门禁**） |
| **A3** | **D2.3** | `客服agent\D2.3-客服Agent开发计划.html` | **v1.1** | 前置条件、测试环境就位（G-00）、会签流程、门禁、交付物、**批次 H（§3.4b）** |
| **A4** | **D2.4** | `客服agent\D2.4-客服Agent知识库设计方案.html` | **v1.8** | 三集合 / 三档可见性 / **集合内分区隔离（§7.2.1）** / 8 模块 / 7 步入库 8 步检索 / 8 项决策 / **附录F 五出口对接** |
| **A5** | **D3.3** | `开发文档\D3.3-访客与角色分离的鉴权方案建议-2026-09-16.md` | CS-AUTH-2026-011 | 鉴权专项：四方案对比、三条不变量、甲乙时序 |
---
## 3. 文档层级与编号域
### 3.1 三层结构
```
第 0 层 唯一入口 D1.1 D1.1-文档索引与权威声明.md
第 1 层 域（8 个） D1 ─ D8
第 2 层 子域（仅域 6 有） D6.1 ─ D6.5
第 3 层 文档（63 份） D<域>.<序> / D<域>.<子域>.<序>
```
### 3.2 八个域（＝逻辑顺序＝阅读优先级）
| 域 | 域名称 | 份数 | 状态 | 什么时候读 |
|---|---|---|---|---|
| **D1** | 一、治理与索引 | 6 | 现行 | **先读 D1.1**（唯一入口，本文件） |
| **D2** | 二、对外交付 | 10 | 现行 | 🔴 **开工必读**（含「开工只读 5 份」的 4 份） |
| **D3** | 三、现行权威·完整版与专项 | 8 | 现行 | 查证据、查 FR 推导过程时读 |
| **D4** | 四、清除与重建留痕 | 7 | 已完成 | 追溯「删了什么、怎么恢复」时读（D4.1 是重建指南；D4.7 是投顾恢复现状） |
| **D5** | 五、业务流程基线 | 1 | 现行 | 核对业务范围与三条红线时读（**冲突时以它为准**） |
| **D6** | 六、公司事实与知识源 | 17 | 现行 | 🔴 改写知识库、核对数据口径时读 |
| **D7** | 七、早期系统文档 | 5 | **待确认** | 只在追查历史口径时读；已被上游依据表引用，**不可删**（见 §10） |
| **D8** | 八、AI 协作规则 | 8 | 现行 | 让 AI 接手时的规则文件（`D8.1`=语言规范正文；`CLAUDE.md`=入口存根，不占编号） |
> 合计：10 + 6 + 9 + 7 + 1 + 17 + 5 + **8** = **63 份**（其中 `客服agent\` 的 10 份不计入 `开发文档\` 的 52 个文件；域 D8 的 8 份含 1 份**不占编号**的入口存根 `CLAUDE.md`）。
---
## 4. 全量文档清单
> **本节结构**：**§4.0 = 编号规则 + 全量编号总表（63 份，按编号顺序）——查找入口**；§4.1—§4.8 = 按类别展开的明细表（编号见 §4.0 总表，同一逻辑顺序）。
### 4.0 编号规则与全量编号总表（64 份）
**编号规则**
| 项 | 规则 |
|---|---|
| **格式** | `D<域>.<序>`；域 6（公司事实与知识源）向下再一级 → `D<域>.<子域>.<序>` |
| **域号定义** | 1 治理与索引 · 2 对外交付 · 3 现行权威·完整版与专项 · 4 清除与重建留痕 · 5 业务流程基线 · 6 公司事实与知识源 · 7 早期系统文档 · 8 AI 协作规则 |
| **排序语义** | 编号 = **逻辑顺序 = 阅读优先级**。跨域 D1→D8：「治理 → 交付 → 权威 → 留痕 → 基线 → 知识源 → 旧版 → 协作规则」；域内按「入口 → 参考 → 留痕」排 |
| **三处一致** | 同一个编号必须同时出现在：① **本节总表**（目录）；② **文档标题正下方**（`.md` 引用块 / `.html` 状态条 / 交付文档 `doc-meta` 行）；③ **新写的交叉引用**（见 §9 第 5 条） |
| **文件名格式** | **`<编号>-<描述名>.<扩展名>`**（编号**进**文件名）：域号即用途、按编号排序即逻辑顺序，**看见文件名就知道它干什么**。唯一例外 `CLAUDE.md`（AI 工具按固定名读取规则文件）。⚠️ **`group_fqcd_jr\knowledge\**` 的镜像副本不改名**——其文件名被入库脚本 `tools/build_knowledge_chunks.py` 的 `SOURCES` 字典直接引用，改名会打断代码侧 |
| **`.txt` 例外** | 3 个纯数据件（`D6.1.3-南方基金-高频问答对.txt`、`D6.4.4-用户信息数据示例.txt`、`ai\D8.2-README.txt`）**不注入编号行**——知识库导入要求「1 行 1 制表符」，加行即破坏格式；其编号由同名 `.md` 与本总表承载 |
| **注入脚本** | `.workbuddy\_inject_docno.py`（**幂等**：判据为文件是否已含「体系编号」，可重复执行） |
**全量编号总表（按编号 = 逻辑顺序排列）**
| 编号 | 文档 | 版本 / 既有编号 | 状态 | 定位 · 何时读 |
|---|---|---|---|---|
| **D1.1** | `开发文档\D1.1-文档索引与权威声明.md` | CS-DOC-2026-017 v1.2 | 现行 | 🔴 **唯一入口**：权威链、编号体系、开工只读集 |
| **D1.2** | `开发文档\D1.2-南方基金业务事实基座与虚构数据规范-2026-09-17.md` | CS-CONTENT-2026-015 **v1.1** | 现行 | 🔴 **内容口径唯一权威**：三分法 / C—R 矩阵 / 品牌映射 |
| **D1.3** | `开发文档\D1.3-文档规整方案与开发前待决事项-2026-09-17.md` | CS-DOC-2026-014 | 现行 | 规整方案 + 待决 E-1~E-4 + 四轮执行记录 |
| **D1.4** | `开发文档\D1.4-知识源与品牌整改变更说明-2026-09-17.md` | CS-CONTENT-2026-016 | 现行 | 逐份变更说明（§3.1—§3.9 改写映射 + G-01~G-09） |
| **D1.5** | `开发文档\D1.5-开发前决策清单与阻塞项-2026-09-17.md` | CS-DOC-2026-018 v1.0 | 现行 | 🔴 **开工前唯一决策登记册**：28 项待你拍板 + 阻塞分级（P0 12 / P1 10 / P2 6）+ 需你提供的 7 项输入；§7 为回填表（增补项见 `D1.6` §4.3） |
| **D1.6** | `开发文档\D1.6-对话上下文提取与开工前补充决策-2026-09-17.md` | CS-DOC-2026-019 v1.0 | 现行 | 🔴 **本轮会话上下文提取件**：已读清单与权威链校正 / 可复用事实（含实测）/ 旧实现 **7 条转人工通路** / 文档缺陷 `Q-1.1`~`Q-1.6` / 前提风险 `K-01`~`K-08` / 待拍板 `N-01`~`N-09` |
| **D2.1** | `客服agent\D2.1-客服Agent执行Todolist.md` | **v6.39** | 现行 | 🔴 **唯一开工入口**：**57 项 / 8 批次** / 12 步关键路径 / **批次 H 智能增强** |
| **D2.2** | `客服agent\D2.2-客服Agent需求文档.html` | **v2.7** | 现行 | 🔴 对外需求：**FR-CS-001~052** + NFR-CS-001~021 |
| **D2.3** | `客服agent\D2.3-客服Agent开发计划.html` | **v1.1** | 现行 | 🔴 前置条件 / 批次 / 会签 / 门禁 / 交付物 |
| **D2.4** | `客服agent\D2.4-客服Agent知识库设计方案.html` | **v1.8** | 现行 | 🔴 三集合 / 三档可见性 / **分区隔离** / 7 步入库 8 步检索 / **附录F** |
| **D2.5** | `客服agent\D2.5-客服Agent演示脚本与账号速查-2026-09-19.md` | `F-03`+`F-04`+`A-05` | 现行 | 🔴 **演示当天照着念**：五项自检 / 账号速查（实测可登录）/ 游客线 5 条 + 客服线 6 组台词（带**实测答复**）/ 排障表 / 对「不智能」的正面回答 |
| **D2.6** | `客服agent\D2.6-客服Agent答辩报告-2026-09-19.md` | 2026-09-19 | 现行 | 🔴 **答辩主文档**：批评 → 根因（2 个出口 / 10 处失败方向全指向转人工）→ 出口决策链（**起步** `E1`—`E5`；**现行七出口 + `L0`**，见其 §3）→ `INV-1`~`INV-5` → 金标 11 项**修复前 → 修复后**对比 → 零容忍词挂载点口径 → 坑与教训 → 诚实未做项 → 现场速答 |
| **D2.7** | `客服agent\D2.7-客服Agent中长期记忆与画像联动设计-2026-09-20.md` | 2026-09-20 | 现行 | 🔴 **记忆与画像专项**：三问直答 / 客服侧五道闸门取证 / 字段分域（`investor_type` 红线）/ **主设计主张：记忆改「行为」不改「输入」** / `INV-M1`~`INV-M6` / 两处过期理由更正 / 分期 P0—P2 / 待决 4 项 |
| **D2.8** | `客服agent\D2.8-客服Agent知识库RAG全链路与选型说明-2026-09-20.md` | 2026-09-20 | 现行 | 🔴 **RAG 全链路**：解析 → 切片（叶子标题 + 表格行级子块）→ 向量化（`text-embedding-v3` / 1024 维）→ 入库七步 → 在线八步 → **检索增强 7 个动作** → 阈值与五出口 / 选型 8 项决策 26 备选 / **已知不一致与风险 5 项** |
| **D2.9** | `客服agent\D2.9-客服Agent手动对话测试用例-2026-09-20.md` | 2026-09-20（**v1.1**，2026-09-21 全链路复跑回填） | 现行 | 🔴 **动手验收件**：46 条金标**逐条可问**（问句 / 期望出口 / 期望要点 / 禁止出现 / 实测基线）+ 11 条边界 `Z` 组 / 判分四问 / `M-1`~`M-10` 手动汇总 / 真 HTTP 核验配方 / 3 项实测缺口 |
| **D2.10** | `客服agent\D2.10-客服Agent端到端答辩文档-2026-09-21.html` | **v1.0** | 现行 | 🔴 **端到端答辩文档**：**十段流水线**（入口 → 队列 → Worker → 安全路由 → 档位 → 意图 → 检索增强 → 出口 → 输出守护 → 治理返回）+ **4 张 Mermaid 图**（主流程图 / 时序图 / 安全路由 / 出口判定）+ **七出口 + `L0` 表层判定层** + `INV-1`~`INV-5` 与 `INV-M1`~`INV-M6` + 46 条金标前后对比 + 演示台词 + **必问主观题（Vibe Coding）** + 坑与教训 10 条 + 诚实未做项 10 条 |
| **D3.1** | `开发文档\D3.1-客服Agent需求开发文档与设计方案.html` | **v2.6** | 现行 | D2.2 的**完整版**：逐条需求带证据引用与推导过程 |
| **D3.2** | `开发文档\D3.2-知识库设计方案.html` | **v1.6** | 现行 | D2.4 的**完整版**：含被收敛掉的备选方案与否决理由 |
| **D3.3** | `开发文档\D3.3-访客与角色分离的鉴权方案建议-2026-09-16.md` | CS-AUTH-2026-011 | 现行 | 🔴 鉴权专项（＝开工只读 5 份之 A5）：四方案 / 三不变量 / 甲乙时序 |
| **D3.4** | `开发文档\D3.4-客服Agent重构Todolist.md` | v5.1 | 底稿 | D2.1 的前身（含更细的 DoD 描述） |
| **D3.5** | `开发文档\D3.5-知识库检索升级备选方案建议-2026-09-17.md` | CS-KB-2026-020 v1.0 | 现行 | 知识库检索升级**备选方案池**（**不是**任务来源）：`K-01`~`K-08` 前提风险 / `§3-A`~`§3-H` 八个升级方向 / 与 `DEC-11` 耦合的推荐组合 / 对 `D2.4`·`D2.1` 的 10 条修订建议 / 可证伪验收判据 |
| **D3.6** | `开发文档\D3.6-客服Agent智能增强架构建议-2026-09-17.md` | CS-ARCH-2026-021 **v1.1** | 现行 | 🔴 **智能增强架构（**已裁定件**）**：诊断（10 条转人工通路 / 设计有澄清与生成但未实现）/ 「智能」7 条可验收定义 / **五出口决策链** E1—E5（**起步定义**；现行七出口 + `L0`，见 `D3.9`）/ 安全不变量 `INV-1`~`INV-5` / 转人工白名单 4 类 / **§9 八项决策已拍板** |
| **D3.7** | `开发文档\D3.7-客服Agent评测金标集与判分规则-2026-09-17.md` | CS-EVAL-2026-022 v1.0 | 现行 | 🔴 **验收依据**：46 条金标（含四要素：期望出口 / 期望证据 / 期望关键事实 / 禁止出现）+ 10 项指标 + **4 项零容忍**（禁忌·越权·无出处数字·误拒）+ 前置阻塞 `B-1`~`B-4` + 问法分级（难例 32 条） |
| **D3.8** | `开发文档\D3.8-模型密钥轮换与凭据安全操作手册-2026-09-20.md` | CS-OPS-2026-023 v1.0 | 现行 | 🔴 **答辩后当轮执行**：为什么轮换 / `.env` 5 个变量与读取方取证 / **三个 Qwen 同值 + 两个 DeepSeek 同值** / 五步流程 / 3 个坑 / 复核清单（工具 `tools/rotate_api_keys.py`） |
| **D3.9** | `开发文档\D3.9-客服Agent智能路由与行情出口设计-2026-09-21.md` | CS-ARCH-2026-024 v1.0 | 现行 | 🔴 **`W27` 设计与实施依据**：三项异议的实测根因（阈值区间重叠不可分 / 跨集合回退未实现 / 走势无数据源 / 闲聊兜底 / 收益数值黑名单可绕过）+ **`L0` 表层判定层** + **能力路由** + **出口 `E6` 行情** + 判据迁移到实体锚点 + 槽位白名单 + `INV-6`/`INV-7` + 12 项决策 |
| **D4.1** | `开发文档\D4.1-客服Agent重构报告-2026-09-16.md` | CS-REFACTOR-2026-010 | 底稿 | 🔴 **重建指南**：清除了什么 / 缺什么 / 按什么顺序装回去 |
| **D4.2** | `开发文档\D4.2-客服模块清除影响面清单.md` | CS-PURGE-2026-007 | 已完成 | 客服形态A 清除的影响面 |
| **D4.3** | `开发文档\D4.3-客服模块清除执行报告-2026-09-16.md` | CS-PURGE-2026-008 | 已完成 | 客服清除验证数据 + **安全能力损失清单**（重建须补回） |
| **D4.4** | `开发文档\D4.4-投顾模块清除范围与影响面清单-2026-09-17.md` | CS-PURGE-2026-012 | 已完成 | 投顾清除范围 |
| **D4.5** | `开发文档\D4.5-投顾模块清除执行报告-2026-09-17.md` | CS-PURGE-2026-013 | 已完成 | 投顾清除验证数据 + 恢复方式 |
| **D4.6** | `开发文档\D4.6-客服Agent一期合规红队与业务评测集-留痕-2026-09-18.md` | CS-DOC-2026-020 v1.0 | 留痕 | 🔴 **验收基线**：一期红队 `RT-001`~`018` 原文 + `C-06` 实测回填；`A-01`/`C-06`/`C-07` 的唯一对比基准 |
| **D4.7** | `开发文档\D4.7-投顾模块恢复记录-2026-09-20.md` | CS-PURGE-2026-014 v1.0 | 现行 | 🔴 **投顾现状**：2026-09-17 清除 → 2026-09-20 随合并恢复的时间线 / 恢复动作清单 / 客服线不变的结论 / **一处必须更正的理由表述**（`DEC-19`）/ 遗留 1 项 |
| **D4.8** | `开发文档\D4.8-客服Agent智能度体检与整改报告-W21-2026-09-21.md` | CS-RPT-2026-024 v1.1 | 现行 | 🟡 **智能度留痕**：81 条口语 + 8 组多轮真 HTTP 体检；`C-8`/`C-9`/`C-10` 已修；**§9 = `W21` 第二轮：§6 四项（`D1`~`D4`）已全部裁定并落地**，含 `I-01` 金标期望修订留痕与 `docs/43` 未入库的缺口登记 |
| **D5.1** | `开发文档\D5.1-业务流程-MVP版-最终交付-2026-09-15.md` | — | 现行 | 🔴 MVP 业务基线：两条业务线 / 三条红线 / 演示跑通验收（**冲突时以它为准**） |
| **D6.1.1** | `开发文档\公司信息\D6.1.1-南方基金-企业信息.md` | **V2.0** | 现行 | 🔴 **母本**：品牌 / 工商 / 资质 / 组织 / 财务的唯一权威 |
| **D6.1.2** | `开发文档\公司信息\D6.1.2-南方基金-高频问答对.md` | NF-FAQ-2026-001 **V2.0** | 现行 | 64 组 FAQ（档位 public 54 / registered 10） |
| **D6.1.3** | `开发文档\公司信息\D6.1.3-南方基金-高频问答对.txt` | 同上 | 现行 | 知识库批量导入用（制表符两列，**64 行 × 1 tab**）〔.txt 例外：无编号行〕 |
| **D6.1.4** | `开发文档\公司信息\D6.1.4-公司新人指南.md` | **V4.0** | 现行 | 员工视角公司介绍（是否入库见待决 C-01） |
| **D6.2.1** | `开发文档\公司业务\D6.2.1-个人理财产品手册.md` | **V3.0** | 现行 | 公募基金与专户产品手册（6 只〔示例〕产品，代码 9005xx） |
| **D6.2.2** | `开发文档\公司业务\D6.2.2-企业金融服务方案.md` | **V3.0** | 现行 | 机构客户服务方案（原「企业金融服务方案」） |
| **D6.2.3** | `开发文档\公司业务\D6.2.3-高净值客户服务规范.md` | **V3.0** | 现行 | 尊享 / 私人财富顾问服务规范 |
| **D6.3.1** | `开发文档\金融政策\D6.3.1-理财产品销售管理办法.md` | **V4.0**（JR-SPM-2026-003） | 现行 | 销售管理制度（监管依据已改为基金口径） |
| **D6.3.2** | `开发文档\金融政策\D6.3.2-个人投资者适当性管理指南.md` | — | 现行 | 双录 / 冷静期 / 专业投资者 / C—R 匹配 |
| **D6.3.3** | `开发文档\金融政策\D6.3.3-反洗钱合规操作手册.md` | — | 现行 | 客户身份识别 / 大额与可疑交易（**不入客服知识库**） |
| **D6.4.1** | `开发文档\用户研判规则\D6.4.1-投资者风险画像研判规则.md` | — | 现行 | 画像标签体系与 FM 规则 |
| **D6.4.2** | `开发文档\用户研判规则\D6.4.2-反洗钱可疑交易识别规则.md` | — | 现行 | 可疑交易特征规则 |
| **D6.4.3** | `开发文档\用户研判规则\D6.4.3-用户信息数据示例.md` | NF-DATA-2026-001 **V2.0** | 现行 | 五类客户画像样本（**入库禁区**） |
| **D6.4.4** | `开发文档\用户研判规则\D6.4.4-用户信息数据示例.txt` | 同上 | 现行 | 纯文本摘要版（**入库禁区**）〔.txt 例外〕 |
| **D6.5.1** | `开发文档\公司业务\用户测试数据\D6.5.1-客户A-高净值.md` | NF-TEST-2026-001 **V2.0** | 现行 | `customer` / C4 进取型 / 钻石-专户链路（**入库禁区**） |
| **D6.5.2** | `开发文档\公司业务\用户测试数据\D6.5.2-客户B-普通投资者.md` | NF-TEST-2026-002 **V2.0** | 现行 | `customer` / C1 保守型 / 适老化 / 防诈骗（**入库禁区**） |
| **D6.5.3** | `开发文档\公司业务\用户测试数据\D6.5.3-访客-未注册意向客户.md` | YH-TEST-2026-003 | 现行 | `guest` / 访客边界 / 禁推介 / 转化引导（**入库禁区**） |
| **D7.1** | `开发文档\D7.1-需求文档.html` | v4.53（2024-06-26） | 待确认 | 早期系统级需求；🔴 **是 D2.1 中 `F-07` 未完成任务的直接对象**，不可删 |
| **D7.2** | `开发文档\D7.2-功能设计文档.html` | v1.5（2025-06-26） | 待确认 | 早期系统级 Agent 功能设计（含已清除的投顾能力） |
| **D7.3** | `开发文档\D7.3-记忆架构设计.html` | v2.3 | 待确认 | 通用教材体裁，但 **§6.2 是被 A2/A4 引用的上游依据** |
| **D7.4** | `开发文档\D7.4-开发引导.md` | — | 待确认 | 早期技术实施引导（已被 D2.3 覆盖；技术参考仍被引用） |
| **D7.5** | `开发文档\D7.5-答辩须知.md` | — | 现行 | 答辩要求（15 分钟 / 重点讲思路与坑） |
| **D8.1** | `开发文档\D8.1-项目语言规范.md` | — | 现行 | **项目语言规范正文**（四条硬规则 / 规则优先级 / 高风险区 / 编码准入）；🔁 2026-09-19 自 `CLAUDE.md` 独立成文（`乙-27` / `DEC-28`） |
| —〔存根〕 | `开发文档\CLAUDE.md` | — | 现行 | `D8.1` 的**入口存根**（仅三行，AI 工具按固定名读取）；**不占编号**，不得再追加规则正文 |
| **D8.2** | `开发文档\ai\D8.2-README.txt` | — | 现行 | AI Agent 治理框架（用法说明）〔.txt 例外〕 |
| **D8.3** | `开发文档\ai\D8.3-01_READING_RULES.md` | — | 现行 | 读文档规则（阅读八问 / 完成门） |
| **D8.4** | `开发文档\ai\D8.4-02_EXECUTION_RULES.md` | — | 现行 | 执行规则 |
| **D8.5** | `开发文档\ai\D8.5-03_TESTING_RULES.md` | — | 现行 | 测试规则 |
| **D8.6** | `开发文档\ai\D8.6-04_OUTPUT_RULES.md` | — | 现行 | 产出规则（§5 高风险变更须先确认） |
| **D8.7** | `开发文档\ai\D8.7-05_PROJECT_CONTEXT.md` | — | 现行 | 项目背景速览 |
> **注入校验**：**59 份**可注入文档（**45** `开发文档\*.md` + 5 `开发文档\*.html` + **4** `客服agent\*.html` + `客服agent\D2.5-…md` + `客服agent\D2.6-…md` + `客服agent\D2.7-…md` + `客服agent\D2.8-…md` + `客服agent\D2.9-…md`）**已全部带「体系编号」行**；3 份 `.txt` 按上表例外处理。（原表述的 49 份**未计入** `客服agent\D2.1` 的 `.md` —— 该漏计是历史口径，本轮**只补新增件、不追改历史**。）「开工只读 5 份」对应 **D2.1 / D2.2 / D2.3 / D2.4 / D3.3**。
### 4.1 Ⅰ 对外交付 / 现行权威（`客服agent\`，10 份）
| 文件名 | 版本 | 日期 | 定位 | 关联 |
|---|---|---|---|---|
| `D2.1-客服Agent执行Todolist.md` | **v6.39** | 2026-09-21 | 唯一开工入口 | 收敛自 `开发文档\D3.4-客服Agent重构Todolist.md` v5.1 |
| `D2.2-客服Agent需求文档.html` | **v2.7** | 2026-09-20 | 对外需求（FR **52** / NFR 21） | 完整版见 §4.2 |
| `D2.3-客服Agent开发计划.html` | **v1.1** | 2026-09-17 | 批次 / 会签 / 门禁 | 与 A1 批次号一一对应 |
| `D2.4-客服Agent知识库设计方案.html` | **v1.8** | 2026-09-21 | 三集合 / 三档 / 入库检索流程；**索引统一 `AUTOINDEX`、语料 755 块** | 完整版见 §4.2 |
| `D2.5-客服Agent演示脚本与账号速查-2026-09-19.md` | — | 2026-09-19 | 演示脚本（`F-03`/`F-04`/`A-05` 三合一） | 台词证据：`group_fqcd_jr\docs\evidence\20260919-t8-demo-lines*.json` |
| `D2.6-客服Agent答辩报告-2026-09-19.md` | — | 2026-09-19 | 答辩报告（问题定义 / 根因 / **出口决策链：起步五出口 → 现行七出口 + `L0`** / 安全不变量 / 前后对比 / 现场速答） | 数字来源：46 条金标 `score_before` vs `score_w11b` + `e2e_smoke_test` + `http_probe` + 12 条真机边界 |
| `D2.7-客服Agent中长期记忆与画像联动设计-2026-09-20.md` | — | 2026-09-20 | 中长期记忆与画像联动（读码取证 / `INV-M1`~`INV-M6` / 分期 P0—P2） | 上游依据：`开发文档\D7.3` §1.3 与 §6.2；口径：`D2.2` §1.7 第 12 / 18 / 21 项 |
| `D2.8-客服Agent知识库RAG全链路与选型说明-2026-09-20.md` | — | 2026-09-20 | RAG 全链路（按流程逐步：解析 / 切片 / 向量化 / 入库 / 检索 / 增强 / 判定） | 上游：`D2.4` §6 / §7、`D3.2`、`D3.5`；实测：`knowledge\_chunks.jsonl` **755 块**（2026-09-21 `W24` 复测）+ Milvus 四集合直查 |
| `D2.9-客服Agent手动对话测试用例-2026-09-20.md` | **v1.4** | 2026-09-20 | 手动对话测试用例（46 条金标逐条可问 + **每组实测答复原文** + 11 条边界 + 判分四问 + 汇总表 + §2.10 场内基金演示线） | 同口径输入件：`_eval_harness\cases_46.json` / `result_w25.json` / `score_w25.json`；答复全文：`_w25_http_manual.json` / `.txt` |
| `D2.10-客服Agent端到端答辩文档-2026-09-21.html` | **v1.0** | 2026-09-21 | 端到端答辩文档（十段流水线 + 主流程图 / 时序图 / 安全路由图 / 出口判定图；**七出口 + `L0`**；不变量；演示台词；必问主观题） | 承接 `D2.6`（结论）与 `D2.8`（RAG 链路）；台词以 `D2.5` 为准；实测答复源自 `D2.9` |
### 4.2 Ⅱ 开发文档区内的现行权威（9 份）
| 文件名 | 版本 | 定位 |
|---|---|---|
| `D3.3-访客与角色分离的鉴权方案建议-2026-09-16.md` | CS-AUTH-2026-011 | 鉴权四方案 / 三不变量 / 甲乙时序（同 §2 A5） |
| `D3.1-客服Agent需求开发文档与设计方案.html` | **v2.6** | A2 的**完整版**：逐条需求带证据引用与推导过程 |
| `D3.2-知识库设计方案.html` | **v1.6** | A4 的**完整版**：含被收敛掉的备选方案与否决理由 |
| `D3.4-客服Agent重构Todolist.md` | v5.1 | A1 的前身（**底稿**）：含更细的 DoD 描述，冲突时以 A1 为准 |
| `D3.5-知识库检索升级备选方案建议-2026-09-17.md` | CS-KB-2026-020 | 知识库检索升级**备选方案池**（**建议**，非需求/任务来源） |
| `D3.6-客服Agent智能增强架构建议-2026-09-17.md` | CS-ARCH-2026-021 **v1.1** | 智能增强架构（**§9 八项已拍板**）：五出口决策链（**起步定义**；现行七出口 + `L0`，见 `D3.9`）/ 安全不变量 / 转人工白名单 4 类 / 访客档计算型分项开放口径 |
| `D3.7-客服Agent评测金标集与判分规则-2026-09-17.md` | CS-EVAL-2026-022 | **评测输入件**：46 条金标 + 判分规则 + 门槛（**验收依据**，非需求/任务来源） |
| `D3.8-模型密钥轮换与凭据安全操作手册-2026-09-20.md` | CS-OPS-2026-023 | **操作手册**：模型密钥轮换（工具 `tools/rotate_api_keys.py`）+ 复核 + 回退；**不落任何 key 值** |
| `D3.9-客服Agent智能路由与行情出口设计-2026-09-21.md` | CS-ARCH-2026-024 | **设计与实施依据**：`L0` 表层判定层 / 能力路由 / 出口 `E6` 行情 / 实体锚点判据 / 槽位白名单 / 免责声明分档；**更正 `FR-CS-008`** |
### 4.3 Ⅲ 内部复核底稿（2 份）
| 文件名 | 编号 | 定位 |
|---|---|---|
| `D4.1-客服Agent重构报告-2026-09-16.md` | CS-REFACTOR-2026-010 | 清除了什么 / 缺什么 / 按什么顺序装回；§9 决策记录 |
| `D5.1-业务流程-MVP版-最终交付-2026-09-15.md` | — | MVP 业务流程基线 |
### 4.4 Ⅳ 清除执行记录与重建留痕与测评留痕（7 份）
| 文件名 | 编号 | 定位 |
|---|---|---|
| `D4.2-客服模块清除影响面清单.md` | CS-PURGE-2026-007 | 客服形态A 清除的影响面 |
| `D4.3-客服模块清除执行报告-2026-09-16.md` | CS-PURGE-2026-008 | 客服清除验证数据 |
| `D4.4-投顾模块清除范围与影响面清单-2026-09-17.md` | CS-PURGE-2026-012 | 投顾清除范围 |
| `D4.5-投顾模块清除执行报告-2026-09-17.md` | CS-PURGE-2026-013 | 投顾清除验证数据 + 恢复方式 |
| `D4.6-客服Agent一期合规红队与业务评测集-留痕-2026-09-18.md` | CS-DOC-2026-020 | 🔴 一期红队 `RT-001`~`018` 原文留痕 + `C-06` 实测回填（验收基线） |
| `D4.7-投顾模块恢复记录-2026-09-20.md` | CS-PURGE-2026-014 | 🔴 **投顾的「现状」单据**：清除 → 恢复的时间线与动作清单；`D4.4`/`D4.5` 降级为历史留痕 |
| `D4.8-客服Agent智能度体检与整改报告-W21-2026-09-21.md` | CS-RPT-2026-024 | 🟡 **智能度体检留痕**：81 条口语 + 8 组多轮（真 HTTP）；3 类缺陷已修；**`W21` 第二轮 §6 四项已落地**（含 1 条金标期望修订）；含 `_chunks_report.txt` 可删判定 |
### 4.5 Ⅴ 本次整改工作文档（5 份）
| 文件名 | 编号 | 定位 |
|---|---|---|
| `D1.2-南方基金业务事实基座与虚构数据规范-2026-09-17.md` | CS-CONTENT-2026-015 **v1.1** | 🔴 **事实基座**：三分法数据规范、C—R 矩阵、品牌映射表 |
| `D1.4-知识源与品牌整改变更说明-2026-09-17.md` | CS-CONTENT-2026-016 | 逐份变更说明（§3.1—§3.9 改写映射） |
| `D1.3-文档规整方案与开发前待决事项-2026-09-17.md` | CS-DOC-2026-014 | 规整方案 + 待决事项 + 四轮执行记录 |
| `D1.5-开发前决策清单与阻塞项-2026-09-17.md` | CS-DOC-2026-018 **v1.0** | 🔴 **开工前唯一决策登记册**：28 项待拍板 + 阻塞分级（P0 12 / P1 10 / P2 6）+ §5 需你提供的 7 项输入 |
| `D1.6-对话上下文提取与开工前补充决策-2026-09-17.md` | CS-DOC-2026-019 **v1.0** | 🔴 **本轮会话上下文提取件**：已读清单 / 可复用事实 / 7 条转人工通路 / `Q-1.1`~`Q-1.6` / `K-01`~`K-08` / `N-01`~`N-09`；§4.3 为回填表 |
### 4.6 Ⅵ 公司事实与知识源（17 份）
**`公司信息\`（4 份）**
| 文件名 | 编号 / 版本 | 定位 |
|---|---|---|
| `D6.1.1-南方基金-企业信息.md` | **V2.0** | 🔴 **母本**：品牌 / 工商 / 资质 / 组织 / 财务的唯一权威 |
| `D6.1.2-南方基金-高频问答对.md` | NF-FAQ-2026-001 **V2.0** | 64 组 FAQ（含档位标注 public 54 / registered 10） |
| `D6.1.3-南方基金-高频问答对.txt` | 同上 | 知识库批量导入用的制表符两列版 |
| `D6.1.4-公司新人指南.md` | **V4.0** | 员工视角公司介绍 |
**`公司业务\`（3 份）**
| 文件名 | 版本 | 定位 |
|---|---|---|
| `D6.2.2-企业金融服务方案.md` | **V3.0** | 机构客户服务方案（原「企业金融服务方案」） |
| `D6.2.1-个人理财产品手册.md` | **V3.0** | 公募基金与专户产品手册（6 只〔示例〕产品，代码 9005xx） |
| `D6.2.3-高净值客户服务规范.md` | **V3.0** | 尊享 / 私人财富顾问服务规范 |
**`公司业务\用户测试数据\`（3 份）**
| 文件名 | 编号 / 版本 | 主体类型 | 定位 |
|---|---|---|---|
| `D6.5.1-客户A-高净值.md` | NF-TEST-2026-001 **V2.0** | `customer` | C4 进取型 / 钻石-专户链路 |
| `D6.5.2-客户B-普通投资者.md` | NF-TEST-2026-002 **V2.0** | `customer` | C1 保守型 / 适老化 / 防诈骗 |
| `D6.5.3-访客-未注册意向客户.md` | YH-TEST-2026-003 | `guest` | 访客边界 / 禁推介 / 转化引导 |
**`金融政策\`（3 份）**
| 文件名 | 版本 | 定位 |
|---|---|---|
| `D6.3.1-理财产品销售管理办法.md` | **V4.0**（JR-SPM-2026-003） | 销售管理制度（监管依据已改为基金口径） |
| `D6.3.2-个人投资者适当性管理指南.md` | — | 双录 / 冷静期 / 专业投资者 / C—R 匹配 |
| `D6.3.3-反洗钱合规操作手册.md` | — | 客户身份识别 / 大额与可疑交易 |
**`用户研判规则\`（4 份）**
| 文件名 | 定位 |
|---|---|
| `D6.4.1-投资者风险画像研判规则.md` | 画像标签体系与 FM 规则 |
| `D6.4.2-反洗钱可疑交易识别规则.md` | 可疑交易特征规则 |
| `D6.4.3-用户信息数据示例.md` | NF-DATA-2026-001 **V2.0**：五类客户画像样本 |
| `D6.4.4-用户信息数据示例.txt` | 上述样本的纯文本摘要版 |
### 4.7 Ⅶ 早期系统文档处置（6 项 · 含 `CLAUDE.md`＝`D8.1` 的入口存根，故与 §3.2「D7＝5 份」不冲突 · 2026-09-17 已按 D-2 处置 · 2026-09-19 `CLAUDE.md` 改为三行存根）
| 文件名 | 日期 | 现状 | 2026-09-17 处置 |
|---|---|---|---|
| `CLAUDE.md` | 2026-06-05 | **入口存根（三行）** —— 语言规范正文已迁至 `D8.1-项目语言规范.md` | 🔁 **2026-09-19 改造**（`乙-27`/`DEC-28`）：正文迁入 `D8.1`；本文件**保留原名**以维持 AI 工具约定与既有引用锚点（被 A2/A4 与 `客服Agent需求开发文档` 依据表按文件名引用） |
| `D7.5-答辩须知.md` | 2026-06-26 | 答辩要求，**仍有效** | ✅ 保留，未改动（被 `客服Agent需求开发文档:4203` 引用） |
| `D7.4-开发引导.md` | 2026-07-17 | 开发实施引导（技术参考·代码示例） | ✅ 加**状态标注**；**保留**（被 A2/A4 依据表 + 知识库设计 §1.4 分块参数出处引用） |
| `D7.1-需求文档.html` | 2026-07-17 | 项目**整体**需求 v4.53 | ✅ 加**状态标注**；**保留**（被 A2/A4 依据表引用，且是 Todolist **F-07 未完成任务的直接对象**）
⚠️ 品牌仍为 `XX科技`、热线仍为 `400-XXX-XXXX` |
| `D7.2-功能设计文档.html` | 2026-07-20 | 系统级 Agent 功能设计 v1.5 | ✅ 同上
⚠️ 品牌仍为 `XX科技`（含系统 Prompt 示例） |
| `D7.3-记忆架构设计.html` | 2026-07-20 | 通用教材**体裁**，但 §6.2 内容被引用 | ✅ **保留在原位**（16:26 曾归档 → 16:40 **撤销归档移回**，理由见 §7.1 纠正栏） |
> 🔴 只加标注、**不改品牌**的理由：这两份 HTML 的**业务正文仍属早期模型**（客户等级 `私行`、系统 Prompt 含早期品牌、Agent 清单含已清除的投顾能力）。**只替换品牌会造出「品牌已对、业务仍旧」这一更危险的状态** —— 比留下明显的旧品牌更易被误用（CS-CONTENT-2026-016 §0.3 已点明该坑）。待系统级口径确认后整批同步。
### 4.8 Ⅷ AI 协作脚手架（`ai\`，6 份）
| 文件名 | 定位 |
|---|---|
| `D8.2-README.txt` | 用法说明 |
| `D8.3-01_READING_RULES.md` | 读文档的规则 |
| `D8.4-02_EXECUTION_RULES.md` | 执行规则 |
| `D8.5-03_TESTING_RULES.md` | 测试规则 |
| `D8.6-04_OUTPUT_RULES.md` | 产出规则 |
| `D8.7-05_PROJECT_CONTEXT.md` | 项目背景速览 |
> `ai\` 是**给 AI 用的**，不是交付文档；命名风格（下划线 + 大写）与其余文档不同，**属有意为之，不改**。
---
## 5. 命名规范
### 5.1 文件名
| 规则 | 说明 | 示例 |
|---|---|---|
| **R1** 中文优先 | 交付与知识源文档一律用中文名 | `D6.2.1-个人理财产品手册.md` |
| **R2** 日期后缀 | 一次性工作成果（报告 / 方案 / 变更说明）加 `-YYYY-MM-DD` | `D4.1-客服Agent重构报告-2026-09-16.md` |
| **R3** 系列用 `-` 连接 | 主语 + `-` + 类别 | `D6.1.1-南方基金-企业信息.md`、`D6.1.2-南方基金-高频问答对.md` |
| **R4** 不用空格、不用书名号 | —— | ✅`D6.5.1-客户A-高净值.md` ❌`客户A 高净值.md` |
| **R5** 编号前缀置顶 | **文件名以体系编号开头**（`D1.1-…`）⇒ 资源管理器里按名排序即等于**逻辑顺序**（D1→D8），索引自然排在最前 | `D1.1-文档索引与权威声明.md` |
| **R6** 例外 | `ai\` 脚手架用 `NN_ENGLISH.md`；`CLAUDE.md` / `D8.2-README.txt` 沿用工具约定 | —— |
| **R7** 文件名带体系编号 | 文档文件名统一为 **`<编号>-<描述名>.<扩展名>`**，编号即 §4.0 的 `D<域>.<序>`——**域号本身就是用途**（D1 治理 / D2 交付 / D3 权威 / D4 留痕 / D5 基线 / D6 知识源 / D7 旧版 / D8 AI 规则），看见文件名就知道它干什么、排第几。**唯一例外：`CLAUDE.md`**（AI 工具按此固定名读取规则文件，改名会静默失效） | 见 §4.0 总表 |
### 5.2 既有业务编号（留痕用；与 §4.0 **体系编号并存互补**）
> **两套编号的分工**：**体系编号 `D<域>.<序>`**（§4.0）解决「**排在哪、先读哪**」——面向前向检索与阅读优先级；**既有业务编号 `CS-*` / `NF-*` / `YH-*` / `JR-*`**（本节）解决「**这是哪次动作的留痕**」——面向追溯与互引，已散落在报告、Todolist 与代码注释中，**不可重编**。两者**同时保留**，不互相替代。
| 域 | 格式 | 用途 |
|---|---|---|
| `CS-REFACTOR-<年>-<序号>` | 重构类报告 | CS-REFACTOR-2026-010 |
| `CS-PURGE-<年>-<序号>` | 清除执行类 | CS-PURGE-2026-013 |
| `CS-AUTH-<年>-<序号>` | 鉴权专项 | CS-AUTH-2026-011 |
| `CS-DOC-<年>-<序号>` | 文档治理类 | CS-DOC-2026-014 / 017 / **018** |
| `CS-CONTENT-<年>-<序号>` | 内容与品牌整改类 | CS-CONTENT-2026-015 / 016 |
| `NF-<类>-<年>-<序号>` | 知识源与测试数据 | NF-FAQ-2026-001、NF-DATA-2026-001 |
| `YH-TEST-<年>-<序号>` | 访客类测试样本 | YH-TEST-2026-003 |
| `JR-<类>-<年>-<序号>` | 早期遗留编号（**保留，不重编**） | JR-SPM-2026-003、JR-DATA-2024-001 |
### 5.3 文档头部元数据（**推荐统一块**）
新文档与改写后的知识源，文件头建议统一为：
```markdown
> | 项目 | 内容 |
> |------|------|
> | 文件编号 | <编号> |
> | 版本号 | **V<主>.<次>**（含变更摘要） |
> | 更新日期 | YYYY-MM-DD |
> | 编制 / 审核部门 | <部门> |
> | 定位 | <一句话说明这份文档解决什么问题> |
> | 关联文档 | <编号或文件名> |
```
> 已采纳该块的文件：`D6.1.1-南方基金-企业信息.md`、`D6.1.2-南方基金-高频问答对.md/.txt`、`D6.1.4-公司新人指南.md`、`D6.2.2-企业金融服务方案.md`、`D6.2.1-个人理财产品手册.md`、`D6.2.3-高净值客户服务规范.md`、`D6.4.3-用户信息数据示例.md`、`D6.5.1-客户A-高净值.md`、`D6.5.2-客户B-普通投资者.md`、`D6.5.3-访客-未注册意向客户.md`。
### 5.4 状态标注口径
| 状态 | 含义 | 对待方式 |
|---|---|---|
| **现行** | 与当前口径一致，可据此工作 | 按权威链顺序更新 |
| **底稿** | 结论已进现行文档，本身只作证据 | **只读不改** |
| **已完成** | 记录一次性动作（清除 / 执行） | 只读，供追溯 |
| **已归档** | 使命结束，移到 `_archived_docs_20260917\` | 不读 |
| **待确认** | 状态未定，需人工决策 | 见 §8 |
---
## 6. 命名偏差清单与「暂不改名」决策
🔴 **重要前提**：本区文档按**完整路径 + 行号**互引（如 `group_fqcd_jr\app\...\customer_service.py:193-206`、`docs/33 §1.2`、`开发文档\D4.1-客服Agent重构报告-2026-09-16.md:209`）。
**任何改名或移动都会批量打断引用** —— 且 `开发文档\` 已推送至远程分支。
| # | 偏差 | 是否改 | 理由 |
|---|---|---|---|
| N-1 | 根目录 13 份带日期后缀、5 份不带（如 `CLAUDE.md`、`D7.5-答辩须知.md`） | **不改** | 均为**已互引文件**，改名即断链；且"带日期 = 一次性成果 / 不带 = 长期文档"本身已是可读的隐含规则 |
| N-2 | `D6.4.3-用户信息数据示例.md` 与 `.txt` 同名并存 | **不改** | 设计如此：`.md` 为人读画像，`.txt` 为纯文本摘要版，服务于不同消费方 |
| N-3 | `D3.1-客服Agent需求开发文档与设计方案.html` 一名字含两类文档 | **不改** | 已被 A2、CS-REFACTOR-2026-010、多个 HTML 按名称引用；拆名风险大于收益 |
| N-4 | `ai\D8.3-01_READING_RULES.md` 等下划线大写风格 | **不改** | 脚手架文件，遵循 AI 工具约定，与交付文档本非同类 |
| N-5 | 早期编号 `JR-*`（`JR-SPM-2026-003`、`JR-DATA-2024-001`）与新 `NF-*` 体系并存 | **不改** | 重编号会改变 `理财销售管理办法` 等文件的自引编号；在新文档中统一用 `NF-*` 即可，旧编号**自然淘汰** |
| N-6 | 4 份知识源目录名（`公司信息\`/`公司业务\`/`金融政策\`/`用户研判规则\`）粒度不完全对齐（业务 vs 政策 vs 规则） | **不改** | 已与 `tools\build_knowledge_chunks.py` 的扫描路径、以及 A4 知识库设计的集合划分绑定；改名会同时打断文档与代码两侧引用 |
| N-7 | ~~`00-` 前缀~~ → **文件名编号前缀 `D<域>.<序>-`** | **已执行（第六轮）** | 46 份已改名、引用已全量迁移；`CLAUDE.md` 为例外。详见 §11 与 D1.3 §11 |
> **结论**：第三～五轮**零物理移动、零改名**；**第六轮已推翻**（编号进文件名，46 份改名，见 §11.2）。规整 = **索引 + 状态标注 + 命名规范 + 统一编号**，而非搬文件。
---
## 7. D-2 / D-3 / D-4 执行记录（2026-09-17 · 第三轮）
> **用户指令**：「除了 D5，其他全都按照你建议的来」 ⇒ **D-2 / D-3 / D-4 执行，D-5 明确跳过。**
### 7.1 ✅ D-2 早期系统文档（已执行）
| 文件 | 处置 | 结果 |
|---|---|---|
| `CLAUDE.md` | 保留；**2026-09-19 改为三行存根**（正文迁 `D8.1`，见 §4.7 与 §20） | ✅ |
| `D7.5-答辩须知.md` | 保留，未改动 | ✅ |
| `D7.4-开发引导.md` | 顶部加状态横幅「已被现行开发计划覆盖 · 开工勿依据」 | ✅ |
| `D7.1-需求文档.html` | `` 内加状态标注块（品牌待同步 / 业务口径待复核 / 说明为何不做「只改品牌」/ 指向权威入口） | ✅ |
| `D7.2-功能设计文档.html` | 同上 | ✅ |
| `D7.3-记忆架构设计.html` | **~~归档~~ → 撤销归档、已移回原位**（16:26 归档 → 16:40 移回） | ✅ 60,881 字节，位置 `开发文档\D7.3-记忆架构设计.html` |
> 🔴 **纠正（2026-09-17 16:40）**：本条原为「归档到 `_archive\`」，前提是「通用教材，与项目**无直接引用关系**」。**该前提被证伪** —— A2《D2.2-客服Agent需求文档.html》§0.2 上游依据表 与 A4《D2.4-客服Agent知识库设计方案.html》§0.2/§1.8.3 **均把 `D7.3-记忆架构设计.html` v2.3（§6.2 `customer_id` 为必填身份标识）列为上游依据**（FR-CS-042 的裁决理由即出自此处）。
> ⇒ 已**撤销归档**：文件移回 `开发文档\`，`_archive\` 目录已删。教训：**「像不像项目文档」不足以下判据，必须按文件名反查引用**。
🔴 **关键决策（对原建议的收紧）**：`D7.1-需求文档.html` / `D7.2-功能设计文档.html` **只标注、不改品牌**。
理由：两份文档的**业务正文仍属早期模型**（客户等级枚举含 `私行`、系统 Prompt 写死 `你是XX科技的智能财富管家`、Agent 清单含已清除的投顾能力）。**只替换品牌会造出「品牌已对、业务仍旧」的状态——比留下明显的旧品牌更危险**，因为旧品牌一眼可辨、而"品牌已对"会让人误以为口径已同步。
> ⚠️ 因此这两份文档内**仍有旧品牌值**（`D7.1-需求文档.html` 约 8 处 + 热线占位符 1 处；`D7.2-功能设计文档.html` 约 5 处）。这是**有意为之**，不是遗漏。
### 7.2 ✅ D-3 `admin` 角色投顾域权限（已执行）
**先只读核查 → 再清**，核查推翻了我原先的判断：
| 项 | 原判断 | 实测 |
|---|---|---|
| 条数 | 「15 条」 | admin 持有 **16 条**（库内），另 3 条（9066-9068）种子定义存在但库中未建 ⇒ 排除集合取 **19 条** |
| 是否有消费者 | 「投顾功能已全删，**任何角色上都不会被调用**」 | ❌ **错。**`app/service/profile_governance_service.py` 与 `app/service/product_governance_monitor_service.py` **仍存活**，分别要求 `profile-governance:read/review`（9027/9028）与 `product-governance:read/review/sync`（9041-9043） |
🔴 **`admin=True` 不是旁路**：`app/service/authorization_service.py:31-34` 先判 `permission in context.permissions`，再判角色是否含 admin ⇒ 删掉绑定会让**保留中的端点直接 403**。
处置：
- **删除 16 条**（9020-9026、9029-9034、9057-9059）—— 无任何消费者，纯投顾清除残留。
- **保留 5 条**（9027/9028、9041-9043）—— 有存活消费者。
- **不删 `sys_permission` 定义行**（保新旧环境 schema 一致 + `check_permission_coverage.py` 仍需对账）。
- **同步改种子脚本** `tools/seed_test_rbac.py`：新增 `ADVISOR_DOMAIN_PERMISSION_IDS`（19 个）并把 `ADMIN_PERMISSIONS` 由「全量元组」改为「全量 − 投顾域」⇒ 离线核算 admin **59 → 44**。
- 备份：`.workbuddy\backups\d3_20260917_rbac_before.sql`（`sys_role_permission` / `sys_permission` / `sys_role` / `sys_user_role` 的 INSERT 集）。
**验证结果**：`admin 43`（59 − 16）、`customer 18`、`risk_operator 10`、`operator 2`；残留投顾域 **0 行**；5 条保留项 **全部在位**。
### 7.3 ✅ D-4 代码侧品牌残留（已执行，含一处纠正）
| # | 位置 | 改动 | 状态 |
|---|---|---|---|
| 1 | `app/service/agent/governance.py:47` | `CUSTOMER_SERVICE_HOTLINE`：`15936583816` → **`400-889-8899`**（并补注释说明「脱敏放行」语义与两侧必须同值） | ✅ |
| 2 | `tools/seed_compliance_baseline.py:98-101` | 两条话术（`TPL_TRANSFER_HUMAN` / `TPL_SYSTEM_BUSY`）：热线 → `400-889-8899`；服务时间 `工作日 09:00-18:00` → **每日 7:00—22:00**（对齐 CS-CONTENT-2026-015 v1.1 真值） | ✅ |
| 3 | `app/static/portal/employee-operations/promotion/promotion.js:29` | `南方基金管理有限公司` → **`南方基金管理股份有限公司`**（缺「股份」） | ✅ |
| 4 | ~~`tools/build_knowledge_chunks.py` 品牌白名单~~ | 🔴 **纠正：该白名单在代码里并不存在。**`build_knowledge_chunks.py` 全文只有 `assert_no_duplicate_contents` 一个守卫；「四查 / 品牌白名单（含 `南方财富`+`nanfangwm.com`）」只写在**文档**里（`D4.1-客服Agent重构报告-2026-09-16.md:209`、Todolist B-01），**属"文档声称已实现、代码未实现"**（即 CS-CONTENT-2026-016 §4 的 G-01）。⇒ **无可改之代码**；正确的新白名单值 = `南方基金` + `nffund.com`，**待 B-01 实现时使用**（属代码工作，未做） | ⚠️ 转登记 |
**验证**：三个 `.py` 全部 `py_compile` 通过；全仓复查 `15936583816` / `南方基金管理有限公司` / `400-826-9518`，剩余命中**均为合法处**（脱敏测试样本号码、`_docbuilder.py` 替换规则表、测试 fixture 输入、本次改动注释）。
**DB 侧无同步项**：`agent_reply_template` 表当前 **0 行**，`sys_permission` 亦无品牌字段。
### 7.4 ⏭ D-5 前端品牌面（**本轮跳过**）
用户明确「除了 D5」。**未做**：`app\static\portal\**` 24 文件（18 个 `index.html` 的 ``、`app-shell.js:64`、`brandmark.svg` 的 `aria-label`、`products.js` / `product-detail.js` 的 `document.title`）+ 风控 5 处（`risk_analysis_service.py:27`、`risk_agent.py:1/192/364`、`employee-risk\dashboard\index.html:80/139`、`risk_scan_scheduler.py:173`）。
---
## 8. 遗留与待决
> 🔴 **本节全部事项已并入 `D1.5-开发前决策清单与阻塞项-2026-09-17.md`（唯一决策登记册，编号 `DEC-01`~`DEC-28`）。** 本节保留原编号（`D-5`~`D-8`）以便追溯，交叉映射见 `D1.5 §1.1`；拍板后回填 `D1.5 §7`。
| # | 事项 | 我的建议 | 影响 |
|---|---|---|---|
| **D-5** | 前端 24 份 + 风控 Agent 5 处曾用 `南方财富`（G-02 / G-05） | ✅ **2026-09-18 已执行**（`C-05` 品牌面清零）；🔴 **2026-09-20 复查发现 2 处残留** —— 投顾组分支带回的 `employee-advisor/dashboard/index.html` 与 `customer/advisor-plans/index.html` 的 `<title>`（`W12` 合并引入），**已于 `W13` 按 `DEC-27` 修正**；全仓 `app\` 复查 = 0 处 | ✅ 已闭环 |
| **D-6** 🆕 | **系统名不统一**（母本曾用「智能财富管家系统」） | ✅ **2026-09-19 已执行**（`乙-25`）：母本 `D6.1.1` / `D6.1.4` 与 `D6.5.x` / `D6.4.3` 已统一为「**南方基金·智能服务系统**」；本轮复查 `开发文档\公司信息|公司业务` = **0 处**。剩余命中全部为**合法语境**：① 变更说明（`D1.2`/`D1.4`/`D1.5`）；② **早期文档**（`D7.1`/`D7.2`/`D7.4`）—— 按 §4.7「只标注不改品牌」裁定**有意保留**；③ 仓库 `docs\` / `_flows\`（另一套编号空间） | ✅ 已闭环 |
| **D-7** 🆕 | **B-01 语料入库门禁（四查）并未实现** | ✅ **已实现**：`tools\knowledge_corpus_gate.py`（品牌白名单为 `南方基金` + `nffund.com`，旧值进了**黑名单**；单测 `tests\unit\tools\test_knowledge_corpus_gate.py`） | ✅ 已闭环 |
| — | ~~`_chunks.jsonl` 未重灌库；`开发文档\` 的仓库副本未同步~~ | ✅ **均已闭环**：三集合已于 2026-09-18 `drop` 重建重灌（`DEC-29`「不用旧数据，全部用新数据」）；`开发文档\`（50 份）+ `客服agent\`（24 份）已于 2026-09-20 随 `bc61d5c` **入库并与权威副本逐字节一致**（`D1.6` §4.38） | ✅ 已闭环 |
> ⚠️ **D-5 / D-7 属前端与代码改动**；本轮已按指令完成 D-2/D-3/D-4（其中 D-4 含 3 处代码改动）。
---
## 9. 引用约定（**新文档一律遵守**）
1. **引用其他文档——三级优先**：① **体系编号**（`D2.2 §1.6.1`、`D4.1`）——**新写的引用一律用这一级**，因为它与 §4.0 总表一处定义、全局可解析；② 既有业务编号（`CS-CONTENT-2026-015 §4.2`）——用于追溯历史留痕；③ 文件名——仅在**代码注释、脚本路径、生成件**里必须用文件名时使用。**绝不用行号**（行号会随编辑漂移）。
2. **引用代码**：用 `仓库内相对路径:行号`（如 `app\service\knowledge_search_service.py:138-154`）。
3. **引用需求**：用 `FR-CS-0xx` / `NFR-CS-0xx`；引用任务用 `A-01` / `G-03` 等 Todolist 编号。
4. **旧值与新值对照**：文档中**允许出现旧值**（`XX科技` / `南方科技` / `南方财富` / `nanfangwm.com` / `400-XXX-XXXX`），但**仅限**「修订说明」「禁止清单」「变更说明」三类上下文，且必须紧邻新值。其余位置出现旧值即为缺陷。
5. **编号 ↔ 文件名双向可解析**：任何人看到 `D6.1.1` 应能在 §4.0 总表查到 `开发文档\公司信息\D6.1.1-南方基金-企业信息.md`；反之，看到文件名也应能查到编号（总表按编号排序，文件名可检索）。**新增文档必须同时登记两处**：文件内标题下方 + §4.0 总表。
---
## 10. 可删性核查（2026-09-17 · 第四轮）
> **用户指令**：「把我这个文件夹里你觉得没用的文档都清除，只需要留下协助开发的文档。」
> 🔴 **核查结论：`开发文档\` 43 份中，没有可以安全删除的文档。** 每一份要么是开发输入，要么被上游依据表或编号引用——**删任何一份都会打断别人的依据链**。
### 10.1 逐项核查证据
| 候选（"看起来没用"） | 结论 | 证据 |
|---|---|---|
| `D7.4-开发引导.md` | ❌ 不可删 | A2/A4 §0.2 依据表列为技术参考；`D3.2-知识库设计方案.html` **§7.5「决策 4：分块策略」** 的分块参数明写「取自 `D7.4-开发引导.md` §1.4」；`D7.1-需求文档.html` 内 5 处链接指向它 |
| `D7.1-需求文档.html` | ❌ 不可删 | A2/A4 依据表列为「需求条目与验收标准的原始出处」；🔴 **它是 Todolist `F-07` 未完成任务的直接操作对象**（修复其 24 个失效目录锚点）——删了该任务将无法完成 |
| `D7.2-功能设计文档.html` | ❌ 不可删 | A2/A4 依据表列为「§2.2 意图分类 / §2.3 生成约束 / §8.1 `rag_search` 工具契约」出处 |
| `D7.3-记忆架构设计.html` | ❌ 不可删 | A2/A4 依据表列为「§6.2 `customer_id` 为必填身份标识 → 据此排除『虚拟访客账号』方案」的上游依据（`FR-CS-042` 的裁决理由即出自此处） |
| `D7.5-答辩须知.md` | ❌ 不可删 | `D3.1-客服Agent需求开发文档与设计方案.html` **附录E「参考资料索引」** 引用为「演示要求（15 分钟、重点讲思路与坑）」 |
| `CLAUDE.md` + `ai\` 6 份 | ❌ 不可删 | `客服Agent需求开发文档:483/489/3822` 依赖其 Rule Priority 与「阅读完成门」；`ai\D8.3-01_READING_RULES.md:126` 亦引用 `CLAUDE.md`。🔁 2026-09-19 起规则正文在 `D8.1`，本文件为存根 ⇒ **仍不可删**：文件名本身是引用锚点 |
| `D5.1-业务流程-MVP版-最终交付-2026-09-15.md` | ❌ 不可删 | A2/A4 依据表列为「三条红线 / 演示跑通为唯一验收方式」出处；`客服Agent需求开发文档:489` 明文规定「与《业务流程 MVP 定稿》冲突，**以 MVP 定稿为准**」 |
| 4 份清除留痕（CS-PURGE-2026-007 / 008 / 012 / 013） | ❌ 不可删 | `D3.4-客服Agent重构Todolist.md:19`、`客服Agent重构报告:6`、`tools/seed_test_rbac.py:198` 按编号引用；删则引用悬空 |
| `知识源与品牌整改变更说明`（CS-CONTENT-2026-016） | ❌ 不可删 | `南方基金业务事实基座与虚构数据规范:357` 引用为「每处修改的原因与影响范围」 |
| `文档规整方案与开发前待决事项`（CS-DOC-2026-014） | ❌ 不可删 | 本索引 §4.5 / §7 引用；内含 E-1~E-4「已授权待发令」 |
| 17 份知识源 + 测试数据 | ✅ 开发输入 | 灌库、业务口径、E2E 验证 |
| 本索引 | ✅ 唯一入口 | —— |
### 10.2 结论与替代做法
**本轮不做删除。** 「只留协助开发的文档」这个目标由 **分类（§3）+ 状态标注（§4.7）+ 开工只读 5 份（§2）** 达成，而不是靠删文件——本区文档按「**文件名 + 编号**」互引（§9），删任何一份都会打折别人的依据链。
若仍要物理瘦身，唯一不破坏引用的方式是**移动而非删除**（移入 `开发文档\_archive\`），但代价有三：① 路径型引用（如 §7.5 的 `开发文档\D4.5-投顾模块清除执行报告-2026-09-17.md`）失效；② `_archive\` 目录本身会被后续盘点再认作「待归档」；③ **本区**已于 2026-09-20 入库**（`group_fqcd_jr\开发文档\` / `group_fqcd_jr\客服agent\`，见 `D1.6` §4.38）
> 🔴 **本轮最重要的教训**：判断一份文档「有没有用」**不能凭体裁**（"像通用教材"「像过程记录」），**必须按文件名反查引用**。本轮因此发现了 `D7.3-记忆架构设计.html` 被误归档（§7.1 纠正）、以及 5 份「看起来没用」的文档其实全部被上游依据表引用。
---
## 11. 编号体系落地记录（第五、六轮）
### 11.1 第五轮：建立体系编号
| 位置 | 落地 |
|---|---|
| 目录 | **§3 文档层级与编号域** + **§4.0 编号规则与全量编号总表**（第五轮 47 行；第六轮加入 `D1.5` 后为 **48 行**；第八轮加入 `D1.6`、`D3.5`、`D3.6`、`D3.7` 后为 **52 行**，见 §11.2 与 §12） |
| 文档标题 | 44 份在标题正下方加「体系编号」行（`.md` 引用块 36 / `.html` 状态条 5 / 交付文档 `doc-meta` 3） |
| 引用 | §9 第 1 条三级优先（体系编号 → 既有业务编号 → 文件名）+ 第 5 条「编号↔文件名双向可解析」 |
| 校验 | `.workbuddy\_verify_docno.py` → **47/47 通过**；`.txt` 例外件未被污染 |
### 11.2 第六轮：编号进文件名（**推翻**第五轮「不改名」的判断）
用户要求「文件名带号，以区分每份文档干什么」⇒ 文件名统一为 **`<编号>-<描述名>.<扩展名>`**，**域号本身就是用途**。
| 项 | 结果 |
|---|---|
| 重命名 | **46 份**（`开发文档\` 42 + `客服agent\` 4） |
| 🔴 唯一例外 | **`CLAUDE.md` 保留原名** —— AI 工具按固定名读取规则文件，改名会**静默失效**。🔁 2026-09-19 起其内容收缩为三行存根，规则正文见 `D8.1-项目语言规范.md`（§20） |
| 引用迁移 | **55 个文件**改写（正文 / `<a href>` / 依据表 / `_build\_spec_*.json` 的 `out_file`） |
| 注入行 | 41 处改为「编号体系见 `D1.1` §4.0」（**不写路径**，再改名也不失效） |
| 备份 | `.workbuddy\backups\rename_20260917_devdocs.zip`（64 文件 / 812,649 B） |
| 脚本 | `.workbuddy\_rename_docs_with_no.py`（迁移）、`.workbuddy\_verify_rename.py`（复核） |
### 11.3 🔴 关键区分：**母本改名，镜像不改名**
`tools/build_knowledge_chunks.py` 的 `SOURCES` 字典键指向 **`group_fqcd_jr\knowledge\**` 的镜像副本**（`company/企业信息.md` 等），**不是** `开发文档\` 里的母本。
⇒ **改名母本不打断代码；改名镜像才会。** 故 `开发文档\公司信息\D6.1.1-南方基金-企业信息.md`（母本，带编号）与 `knowledge/company/企业信息.md`（镜像，原名）**并存**，对应关系由 §4.0 总表维护。
### 11.4 未同步（遗留）
| # | 事项 | 说明 |
|---|---|---|
| 1 | `group_fqcd_jr\开发文档\`（40 份） | 陈旧仓库副本，**旧名 + 旧内容**，未同步（叠加在 §8 的 **D-8** 上） |
| 2 | `group_fqcd_jr\客服agent\` | 同上 |
| 3 | `group_fqcd_jr\docs\**` / `_flows\**` 的历史引用 | 属历史记载，**有意不改** |
| 4 | `客服agent\_build\` 的脚手架文件名 | 非文档，保持原名；其内容已随迁移更新 |
---
## 12. 第八轮：会话上下文提取、知识库升级、智能增强架构与评测金标登记（2026-09-17）
| 编号 | 文档 | 既有编号 | 性质 · 作用 |
|---|---|---|---|
| **D1.6** | `开发文档\D1.6-对话上下文提取与开工前补充决策-2026-09-17.md` | CS-DOC-2026-019 **v1.0** | **会话上下文提取件**：回答「开工前还需你决策什么」——在 `D1.5` 的 28 项之外补登 `N-01`~`N-09`；并给出旧实现 **7 条转人工通路**的代码取证、6 处文档缺陷 `Q-1.1`~`Q-1.6`、8 项前提风险 `K-01`~`K-08` |
| **D3.5** | `开发文档\D3.5-知识库检索升级备选方案建议-2026-09-17.md` | CS-KB-2026-020 **v1.0** | **知识库专项建议（备选方案池）**：`§3-A`~`§3-H` 八个升级方向（含代价与适用条件）+ 推荐组合 + 对 `D2.4`/`D2.1` 的 10 条修订建议 + 可证伪验收判据 |
| **D3.6** | `开发文档\D3.6-客服Agent智能增强架构建议-2026-09-17.md` | CS-ARCH-2026-021 **v1.1** | 🔴 **智能增强架构（已裁定件）**：① 诊断——`handle()` **10 处**失败方向全部指向转人工；② 旧设计 §4 **本就写了**「多命中应组织语言」与澄清标记，**实现从未落地**；③ 「智能」7 条可验收定义；④ **五出口决策链** `E1`—`E5`（**起步定义**，现行已扩为**七出口 + `L0`**，见 `D3.9`）；⑤ 安全不变量 `INV-1`~`INV-5` 与转人工白名单 4 类；⑥ **§9 八项决策已于 2026-09-17 拍板** |
| **D3.7** | `开发文档\D3.7-客服Agent评测金标集与判分规则-2026-09-17.md` | CS-EVAL-2026-022 **v1.0** | 🔴 **评测输入件（验收依据）**：46 条金标 / 问法分级（难例 32 条）/ 10 项指标 + 4 项零容忍 / 判分规则 / 前置阻塞 `B-1`~`B-4` / 实测回填表；**核心口径：白名单外"正确地转人工"也判不合格** |
| 项 | 本轮落地 |
|---|---|
| 盘点范围 | `开发文档\` 44 → **48 份**；全量 **52 份**（＋`客服agent\` 4 份） |
| §3.1 / §3.2 / §4.0 | 域一 5 → **6**；域三 4 → **7**；总表补 `D1.6`、`D3.5`、`D3.6`、`D3.7` 四行（总表 **52 行**） |
| §4.2 / §4.5 | 开发文档区现行权威 3 → **7 份**；本次整改工作文档 4 → **5 份** |
| **第八轮 · 下游回灌**（2026-09-17） | **四份交付文档已按 `D3.6` 的裁定同步**（`D1.1` §1 规定的上游优先顺序：需求 → 执行 → 计划 → 知识库）：`D2.2` **v2.4 → v2.5**（`FR-CS-003` 澄清 / `FR-CS-008` 分级回退 / `FR-CS-023` 转人工白名单 **三条重写** + 新增 **§1.4.8 域 H**（`FR-CS-049`~`052`）+ 新增 **`AC-13`** + **§1.6.3 修正**（`public` 删除「产品参数与费率」））；`D2.1` **v5.2 → v5.3**（新增 **批次 H · 智能增强 6 项** + 完工判据 **13 条**）；`D2.3` **v1.0 → v1.1**（新增 **§3.4b 批次 H**）；`D2.4` **v1.2 → v1.3**（**§7.2.1 集合内分区隔离** + 附录A/B/D/F + 取消 `over-fetch`） |
| 三处一致 | 两份新文档的「体系编号」行均位于标题正下方（`D1.6` / `D3.5`），与本总表一致；§9 第 5 条「新增文档必须同时登记两处」已满足 |
| 本文件版本 | **v1.1 → v1.2**（同步 §4.0 总表 `D1.1` 行的版本标注） |
## 13. 第九轮：两份完整版对齐（`D3.1` v2.4 / `D3.2` v1.2，2026-09-17）
> **本轮做什么**：把 `开发文档\` 的两份**完整版**（`D3.1` / `D3.2`）从「收敛前的旧口径」对齐到 `客服agent\` 的**现行收敛版**（`D2.2` **v2.5** / `D2.4` **v1.3**），并**在源头闭环**两处此前登记为「待确认」的跨文档缺陷（`Q-08` / `Q-09`）。本轮**只改文档，不写代码**。
| 项 | 本轮落地 |
|---|---|
| **`D3.1` v2.3 → v2.4** | 标题 / 侧栏 / 文档元信息 → 南方基金·智能服务系统；新增 **§1.4.8 域 H**（`FR-CS-049`~`052`）并重写 `FR-CS-003` / `FR-CS-008` / `FR-CS-023` / `FR-CS-033`；新增 **§3.12 五出口与智能增强落地映射**；§3.3.5 改为**分级回退**（`E5a`/`E5b`/`E5c` + 不得跨档位）；§3.7.1 触发条件 → **白名单 4 类**；§5.3 / §5.5.1 `visibility` 由「标量字段 + 倒排索引」改为 <strong>NOT NULL 分区键（分区裁剪）</strong>；§7.3 新增 `A8` / `A9` 验收；§6.5.1 品牌字段「示例实际值」全表更新 |
| **`D3.2` v1.1 → v1.2** | 标题 / 文档元信息 → 南方基金·智能服务系统；**§4.2 三档表重写**（`public` 删除「产品参数、费率、起购金额」，`registered` 补「全部产品参数」，实现方式 → 分区键 + 分区裁剪）；§4.2 判断记录 3 改为「服务等级门槛公开 / 产品要素门槛不公开」；附录D「over-fetch」→ **v1.2 起取消**并加分区行；附录E 同步 `D3.1` **v2.4** |
| **缺陷 `Q-08` 闭环** | 档位口径定案 **`public` 54 / `registered` 10**（合计 64）。源头 `D6.1.2` §四 已订正：`public` 名单**补回 Q15、移出 Q33**，`registered` 保持逐条列明的 10 条并加 Q33 从严说明，另增「变动前后口径」对账段（**V1.0 = 55 / 9 成员不同，勿再引用**）。`D2.2` / `D2.4` / `D3.1` / `D1.4` §3.6 已同步为 54 / 10 |
| **缺陷 `Q-09` 闭环** | 「39 组版 FAQ」在母本**已不存在**——`D3.1` 附录D/E 与 `D3.2` §4.1 / §4.5 / 附录B 的相关行已删除，FAQ 集合**只登记 64 组一份**（`D6.1.3`）；规模预估按 64 条重算（FAQ 64 + 产品 155—220 + 政策 190—250 = **约 410—535 块**，`D3.2` §4.5 / §8.1 / 附录D 与 `AC-02` 四处一致） |
| **新增待决 `T-11`** | `D3.2` §12.1 补登 **`T-11`**：FAQ `Q14`（客户分层门槛）与 `Q43`（专户门槛）含数值门槛，严格套用判据应归 `registered`；现行按「服务等级标准 / 适当性规则属公开信息」保留 `public`。**若改判，两档将由 54 / 10 变为 52 / 12**（须同步 5 份文档） |
| **行号引用清理** | §10.1 中两处**行引用**（原 `D3.2:1557`、`D3.1:4203`）因完整版行数变动已失效，按 §9 第 1 条改为**体系编号 + 章节**引用 |
| 🔴 **构建脚本已过期（勿重跑）** | `客服agent\_build\` 下的 `_docbuilder.py` + `_body_requirements.html` / `_body_kb.html` / `_body_plan.html` / `_shell_*.html` / `_spec_*.json` 是 `D2.2`/`D2.3`/`D2.4` 的**一次性生成器**，其正文源与锚点**均已滞后于交付件**（`D3.1` 的标题/品牌/侧栏在 v2.4 已改，`_body_kb.html` 仍为 39 组 ≠ 64 组、`public` 仍含「产品参数」）。**重新执行 `python _docbuilder.py` 会覆盖并回退全部现行口径**——交付件以 `客服agent\*.html` 为准，如需重建须先同步 `_build\` 源与锚点。详见 `客服agent\_build\README-已过期-请勿重新生成.txt` |
| 本文件版本 | **v1.2 → v1.3**（同步 §4.0 总表与 §4.2 的 `D3.1` / `D3.2` 版本标注） |
---
> 🔴 **`D3.5` 不是需求、也不是任务来源**：它是**备选方案池**。其中任何一项要落地，都必须先按 §1 的顺序修订上游（`D2.2` 需求 → `D2.4` 设计 → `D2.1` 任务），再同步 `D1.5` / `D1.6` 的回填表。
## 14. 第十轮：`D3.2` / `D2.4` / `D2.2` 的「倒排索引 → 分区键」残留清理（2026-09-17）
> **背景**：第九轮把两份**完整版**（`D3.1` / `D3.2`）对齐到「集合内分区键 + 分区裁剪」口径，但该口径**只在部分章节落地**——`D3.2` / `D2.4` / `D2.2` 的其余章节仍**同时**陈述「`visibility` 建 `INVERTED` 倒排索引」与「`PARTITION KEY`」，构成**同字段双机制的自相矛盾**；`D2.4` / `D2.2` 的 §5.4 / §8.3 / §9 / §11 / 附录 A / 附录 C 甚至仍把 `over-fetch ×3` 当作**现行实现**（而二者各自的 `v1.3` / `v2.5` 修订行**已声明取消**）。本轮**只改文档，不写代码**，把三份文档的**正文**与各自的**修订行**对齐。
| 项 | 本轮落地 |
|---|---|
| **`D3.2` 语义修补（`v1.2` 内，不改版本号）** | ① §5.3 字段表 `visibility` 由「`INVERTED`（倒排） + `NOT NULL` + `PARTITION KEY`」改为 **`PARTITION KEY`（分区键） + `NOT NULL`**；② §5.3 集合创建代码块由 `col.create_index("visibility", {"index_type": "INVERTED"})` 改为 `is_partition_key=True` + `ensure_partition()` + 只建向量索引；③ §5.3 选型对照表 §5.1 术语表 / §5.1 链路 / §7 技术前提 / §7.2 选型 / §8.2 性能分解 / §8.3 优化手段 / §9 启动自检 / §10.5 指标 / §11.1 测试矩阵 / `AC-01` / 附录 A 共 **14 处**同步（13 处逐点替换 + §5.3 集合创建代码块整段重写）。**依据**：`D3.1` §5.5.1 已定「分区键由引擎管理，无需再为 `visibility` 建倒排索引」——保留 `INVERTED` 会误导实现，并在评审时被读成方案不确定 |
| **`D3.2` §8.3 重复行合并** | 优化手段表原有「① `visibility` 建倒排索引」与「② `visibility` 声明为 partition key」两行**同义重复**（第九轮改造遗留），合并为一行并顺延编号（**6 项 → 5 项**） |
| **`D2.4` 对齐（`v1.3` 内，不改版本号）** | §1 术语表 / §5.1 链路 / §5.4 设计点表（补「（历史）」标记） / §5.4 检索代码块（`limit=top_k * OVERFETCH_FACTOR` → `partition_names=sorted(allowed)`） / §5.5 判断表 / §7.3 步骤 / §8.2 性能 / §8.3 优化手段（**6 项 → 5 项**） / §8.4 测试矩阵 / §9 启动自检 / §10 配置（`VISIBILITY_OVERFETCH_FACTOR=3` → `VISIBILITY_PARTITION_KEY=visibility`） / §11 指标 / `AC-01` / 验收脚本一 / `RK-16` / 附录 A / 附录 C / §12.1 `T-08` / §12.3 `J-04` 共 **27 处** |
| **`D2.2` 对齐（`v2.5` 内，不改版本号）** | ① `FR-CS-033` **重写**为「档位隔离走集合内分区裁剪（`v2.5` 重写，替代 over-fetch）」；② `FR-CS-032` 由「强制拼装**过滤表达式**」改为「强制拼装**分区裁剪范围**」；③ 附录术语 `over-fetch` 加「🔴 `v2.5` 已取消」；④ `AC-01` / 验收脚本一 / `RK-16` / `T-08` / `J-05` 同步，共 **9 处**；⑤ §0.4 `v2.5` 行补第 ⑦ 条；⑥ 文末「需求文档 v2.4」→ **v2.5**（版本停滞） |
| **校验（本轮实跑）** | 四份 HTML 均通过项目自带 `verify_html_doc.py`：标签闭合 / 锚点有效 / 围栏成对 / 无占位残留（`D2.2` 1084 行、`D2.4` 1751 行、`D3.1` 4549 行、`D3.2` 2544 行）；`_consistency.py` 重跑：**TOC 失效 0**，四文档交叉引用 **7/7 ✅** |
| 🆕 **新增待决 `N-10`** | `D3.2` §12.1 的 **`T-11`**（客户分层门槛 / 合格投资者门槛的**档位归属**）**是否同步登记进 `D2.4` §12.1**——`D2.4` 现只有 `T-01`—`T-10`，`T-11` 号位**空闲**。不补，则「`D3.2` 镜像 `D2.4`」这一说法**在待决项上不成立**。**建议：补登** |
| 🆕 **新增待决 `N-11`** | **`T-nn` 跨文档撞号**：`D3.1` §5.6 的 `T-11` 是「金融行业基础信息的知识源」、`D3.2` §12.1 的 `T-10` 是「数据库表结构现状 / `fin_knowledge_meta`」，而 `D3.2` / `D2.4` 的 `T-11` 是「门槛档位归属」——**不同文档的同号是不同事项**。现行体系已确认 `T-nn` **按文档独立编号**（`D1.5` §3 即按此映射 `D2.2 T-nn` ↔ `D2.4 T-nn`），故**不构成缺陷**；仅当要求 `D2.1` 的「`T-01`~`T-11`」行文在三份文档间**严格同构**时才需各自顺延。**非功能影响，可低优先处理** |
| 🆕 **发现（本轮未改）· `_consistency.py` 的核对清单已过期** | 该脚本 §二 的「关键事实」仍按 **`功能需求 48 条` / `51 项`** 等旧值匹配（`D2.2` `v2.5` 已把功能需求 **48 → 52 条**、功能域 **7 → 8**），因此其「`0 = 遗漏`」列会**误报遗漏**。**建议**：把 `FACTS` 清单同步到 `v2.5` 口径后再作为门禁使用，否则不宜据其下结论 |
| 🆕 **发现（本轮未改）· `group_fqcd_jr\` 内的旧命名镜像** | 代码仓 `group_fqcd_jr\开发文档\` 与 `group_fqcd_jr\客服agent\` 存有**旧命名镜像** 20 份（`知识库设计方案.html` / `客服Agent知识库设计方案.html` 等，最后写入 2026-09-17 11:32—15:14），`over-fetch` 残留**最高 35 处**、`倒排` **22 处**。经 `git ls-files -- 开发文档 客服agent` 核对：**该两目录未被 git 跟踪**（0 条命中），属工作区遗留物，**不随提交外发**。**建议**：归档进 `.workbuddy\backups\` 或删除，避免演示时误开旧版 |
---
## 15. 第十一轮：`DEC-19` 记忆口径裁定与 `Q-1.8` 闭环（2026-09-18）
> **背景**：`D2.2` §1.7 范围表与附录第 12 项写「客户侧长期 / 画像记忆**亦关闭**」，与 `D3.1` §3.5 三层权限表的「中期只读」冲突；且 `D2.2` **自身**的主体模型（客户可查「自己的画像与风评」）、`FR-CS-024`（转人工摘要含**画像关键标签**）、`D3.1` §3.5.2 适当性过滤三处**都要求画像可读**。按字面执行「亦关闭」会同时废掉这三处功能。
| 项 | 本轮落地 |
|---|---|
| **裁定（`DEC-19`）** | 由「是否关闭」改为**三分口径**，裁为 **(a)**：**短期会话记忆＝开（读 / 写）／ 长期记忆召回（`memory_unit` / `user_facts`）＝关 ／ 画像＝客户侧字段级只读（仅 `risk_level` / `customer_level`，供确定性规则）且禁止注入生成上下文**；客服**不写**画像、**不产生**画像候选 |
| **`D2.2` 同步** | §1.7 范围表行重写；附录第 12 项拆为「长期记忆召回」并明确关闭；第 18 项画像候选由「可产生（待确认后开启）」改为**关闭**；**新增第 21 项**「画像字段级读取」；表后新增澄清 callout（三件独立的事） |
| **`D3.1` 同步** | §3.5 中期行改为「**字段级只读**（仅两个字段）+ 禁止注入生成上下文」；长期行拆为「知识侧只读 / 记忆侧不召回 / 图谱不读」三支；§3.5 新增 design callout 说明拆分口径 |
| **`D1.5` 同步** | `DEC-19` 三处（登记册 §4 / 详表 §5 / 简表 §7）改为三分口径，并标记 ✅ 已裁定 (a) 与完整理由链 |
| **缺陷登记** | `D1.6` §3.3 新增 **`Q-1.8`**（本轮已闭环）；C 类计数 7 → **8**，§3.3 标题与 §0 汇总表同步；§4.4 决策单 `乙-20` 标记 ✅ 已定 (a) |
| **校验（本轮实跑）** | 改动后重跑项目自带 `verify_html_doc.py`：**`D2.2` 1086 行 / `D3.1` 4550 行，均通过**（标签闭合 / 锚点有效 / 围栏成对 / 无占位残留）；`_consistency.py` 重跑：**TOC 失效 0**，四文档交叉引用 **7/7 ✅** |
---
## 16. 第十二轮：甲类受理、模型选型核对与 `K-01` 修正（2026-09-18）
> **本轮做什么**：① 受理甲类 6 项输入（两把模型 key + 四类授权）；② 就「嵌入 / 生成模型选哪个」给出结论（依据为**读码 + 读证据文件**，**非实测**）；③ 确立**密钥落点规则**；④ **修正 `K-01`** 的推断。**本轮未写任何代码、未连库、未起 Milvus。**
| 项 | 本轮落地 |
|---|---|
| **甲类受理** | `D1.6` §4.4 甲类 6 行全部标记 ✅ 已定（甲-4 答辩约 **2026-09-19**；甲-6 一次性授权，但本轮明确「**先不要开发**」⇒ **发令暂缓**）；`D1.6` §6「需要你提供的输入」6 项同步为已满足 |
| **模型结论（嵌入）** | **不另选**：沿用底座已登记的 `qwen3.7-text-embedding-flash`（见 `tools\configure_embedding_endpoint.py`）。理由：**换模型＝换向量维度＝已灌数据全部作废**；维度仍须 `E-3` 实测（`DEC-01`） |
| 🔴 **高价值纠正** | 嵌入端点的 `secret_ref` 是 **`env:QWEN_EMBEDDING_API_KEY`**，**不是** `DASHSCOPE_API_KEY`——只配后者时症状是「**没有可用的模型端点**」，与病因无关，排查方向被带偏。`DASHSCOPE_API_KEY` **另有用途**（推广图 `wan2.2-t2i-flash`），故**同一把 key 建议同时写两个变量名**。另确认 `app\core\config.py` 的 `load_dotenv(override=False)` 已把 `.env` 注入 `os.environ`，密钥写 `.env` **有效** |
| **模型结论（生成）** | **不另选**：沿用库内 `status='active'` 的产线端点；`.env.example` 的离域默认模型为 `deepseek-v4-flash`（`OFFSITE_DEEPSEEK_MODEL`） |
| 🔴 **`K-01` 修正** | `docs\evidence\knowledge-collections.json` 显示三集合**已含 `visibility` 字段**（`fin_faq_collection` 125 / `fin_policy_collection` 297 / `fin_product_collection` 214 ＝ **636** 行）⇒ `K-01`「现有 schema 很可能无 `visibility`」的推断**不成立**。`N-07` 的实质随之变为「**重判档位 + 补灌 `registered` 行**」，而非「加字段重建」 |
| 🔴 **本轮新发现** | ① `knowledge\_chunks.jsonl` **617** 行**全部 `public`**（`registered 0`）⇒ 档位隔离**有字段、无数据**，`AC-11` / `A8` 的双向验证**必然失败**；② FAQ 集合 **125** 行 vs 交付口径「FAQ 64 组」**待对账**；③ 向量**维度仍未确定**（证据只给 Milvus 类型码 `101`），`D3.1` 的 `dim=1024` 与 `settings.EMBEDDING_DIM` 两处口径需一并收口 |
| **密钥落点规则** | 密钥**只落** `group_fqcd_jr\.env`（`.gitignore` 已含 `.env` 与 `.env.bak*`，后者是含真实密钥的完整备份）；**绝不写入任何 `.md` / `.html` 文档、绝不入 git、绝不出现在交付件**；文档只登记「已提供 / 存于 `.env`」。两把 key 已明文出现在对话文本中 ⇒ **建议答辩结束后轮换** |
| **对话上下文登记** | `D1.6` 新增 **§2.4「2026-09-18 实测补充」**（8 条）与 **§4.5「2026-09-18 会话记录」**。按你的要求：**人机对话持续登记在 `D1.6`，作为后续会话的上下文来源** |
| **未做（诚实声明）** | 未写代码；未连 MySQL / Milvus；**未写 `.env`**（等你解除「先不要开发」）；本轮**未改 HTML**，故未重跑 `verify_html_doc.py` |
---
## 17. 第十三轮：零容忍词去留诊断与三层联动冲突检查（2026-09-18）
> **背景**：你提出「零容忍词规则会不会让转人工频率大增、要不要去掉」，并授权「必要时可删旧 Milvus 重建」。本轮**只做诊断与决策登记**——未写代码、未连 MySQL / Milvus、**未删任何 Milvus 集合**（沿用你「先不要开发」的指令）。
| 项 | 本轮结论 |
|---|---|
| 🔴 **前提纠正（本轮最重要）** | 「零容忍词」在项目中是**三层不同载体**：① **输入侧** `ZERO_TOLERANCE_WORDS`（11 条，含裸词「安全」「年化收益率」「预期收益率」）→ `hits_zero_tolerance()` ← `route_message()`；② **输出侧硬编码** `app\service\agent\governance.py:320` 的 `hard_patterns`（5 条）；③ **输出侧库内** `agent_negative_word`（11 行 `severity='block'`）。**当下**制造强制转人工的是 **②③**——① **的代码已随客服模块整体清除而不存在**（`app\service\agent\implementations\` 只剩 `financial_nl2sql` / `fund_query_demo` / `platform_probe` / `risk_agent`），属**重建时**待写的项 |
| 🔴 **陷阱 1** | **只删库内 11 行 = 白删**：`hard_patterns` 是**硬编码**，`governance.py:326` 独立于库规则，仍会「整条替换 + `transfer_required=True`」 |
| 🔴 **陷阱 2** | `tools\seed_compliance_baseline.py` 是**幂等 upsert**（`ON DUPLICATE KEY UPDATE … status='active'`）⇒ **删掉的行会在下次重跑种子时自己长回来** |
| **合规口径** | 合规约束的是**结论**（不给收益承诺）、不是**字面**（不出现「年化」二字）。与 `D3.6` §1.1 根因诊断、§4.2 已裁定的「**概念豁免层 / 承诺拦截层**」一致 |
| **冲突检查（7 条，已逐条收口）** | `C-1` 删词表 ⊥ `D3.7` `M-7`（禁忌违反 = 0，删了则**不可测**）；`C-2` **维持现状 ⊥ `D3.7` `M-10`（误拒率 = 0）**——`A-05`「什么叫七日年化」正是 `D3.7` 指定的探针，判据明写「不得走合规拒答」⇒ **「不去掉」与「去掉」都不满足你自己的验收集，只有分层能同时满足**；`C-3` 只删库 ⊥ `hard_patterns` 硬编码；`C-4` 删库行 ⊥ `docs/02` §10.2 逐字要求 + 种子幂等；`C-5` 裸词「安全」是**纯误杀**且**只在输入侧为害**（`hard_patterns` 不含它）；`C-6` 「删 Milvus 重建」与 `K-07` / `B-4` / `DEC-I6` **不冲突、正是正解**；`C-7` `D3.6` §4.2 与 `D3.4` `C-01` **重叠，应合并为一条**（否则出现两套常量） |
| **时机（窗口只有一次）** | 客服实现**当前不在代码里**（已清除、待重建）⇒ 本轮是「**一开始就写对**」的唯一窗口；等重建完再改即**二次改造**（口径同 `D3.4` `C-01`） |
| **新增待决** | `D1.6` §4.4 新增 **乙-E 组**：`乙-31`（零容忍词三层联动处理方式，建议 **分层重构**）· `乙-32`（输出侧命中后动作，建议 **分档**：仅真承诺转人工）· `乙-33`（裸词「安全」改为**共现判定**）。乙类计数 30 → **33** |
| ✅ **裁定（2026-09-18）** | 你已批复 **乙-E 组三项全部按建议落地**：`乙-31` **分层重构**（词表保留为检测集 + 概念豁免层 / 承诺拦截层，并入 `D3.4` `C-01`）· `乙-32` **分档**（仅真承诺转人工，改 `governance.py:332-337`）· `乙-33` **共现判定**（裸词「安全」需与承诺词共现才拦，库行不动）。**连带**：你「必要时可删旧 Milvus 重建」**= `乙-16` 选 (a) 授权重建**（待正式确认） |
| ✅ **乙类 29 项批复（2026-09-18）** | 你批复「**乙类 29 项全部同意**」，**无一项改写**。回填：`D1.5` §7 决策回填表 28 项（`DEC-01`~`DEC-28`）+ `D1.6` §4.4 乙-1~乙-30；会话登记 `D1.6` §4.6「八」。**闸门项** `乙-2` = (a) **只做 P0 保演示**；**`乙-16`** = (a) **授权重建**；**`乙-1`** = (b) 维持 `public` + 回改 `D2.4` 附录B |
| 🆕 **`D2.1` 升 `v5.4`（2026-09-18）** | 新增 **§10「今日一天执行计划」**（57 项裁剪为 **6 个时间盒段 T0—T5**，附「今日不做」清单、6 条今日红线、降级阶梯、**对 `C-01`/`C-04`/`C-06`/`H-01`/`H-04`/`H-05` 的 DoD 增补**）；新增 v5.4 修订要点 6 条；§9 决策状态补乙类/甲类批复行。⚠️ 行尾为**混合**（原文件即混合，插段与邻近块一致），未做全文件规范化以免产生大 diff |
| **Milvus 重建的代价（须先知悉）** | 636 行重灌；`knowledge\_chunks.jsonl` **617 行全 `public`** ⇒ `registered` **无数据可召回**（需**补内容**，非「改判」可解）；FAQ **125** 行 vs 交付「64 组」**待对账**；向量**维度未实测**，定错要**再重建一次**。你「必要时可删旧库重建」的表述 **≈ 已认 `乙-16` 选 (a) 授权重建**，待正式确认 |
| **对话上下文登记** | `D1.6` 新增 **§4.6「2026-09-18 第二轮会话记录」**（三层载体表 / 冲突检查表 / 时机）。按你的要求：**人机对话持续登记在 `D1.6`** |
| **未做（诚实声明）** | 未写代码；未连 MySQL / Milvus；**未删任何 Milvus 集合**；未写 `.env`；本轮未改 HTML，故未重跑 `verify_html_doc.py` |
---
## 18. 第十四轮：`D4.6` 落档（`C-06-a`）与计数同步（2026-09-18）
> **本轮做什么**：按你 2026-09-18「**按照你建议的来**」的口径，把 `C-06` 的对比基准 —— 客服 Agent 一期红队与业务评测集 —— **从 git 索引落成 `开发文档` 内的正式留痕件**（`D4.6`），并同步本文件的全部计数（**52 → 53 份**；`开发文档\` **48 → 49 份**）。本轮**未写任何代码、未连库**。
| 项 | 本轮落地 |
|---|---|
| 新增文档 | `开发文档\D4.6-客服Agent一期合规红队与业务评测集-留痕-2026-09-18.md`（CS-DOC-2026-020 **v1.0**，域 4「清除与重建留痕」） |
| 落档理由 | `A-01` 基线原文件在 worktree 已删、**仅存 git 索引**；`D4.1` 明写「**不要只依赖 git 历史**」。`C-06` 实测时**已不得不走 `git show HEAD:<path>`**，`C-07` 还要拿它做安全对照 ⇒ 必须落档 |
| 原文完整性 | 正文**逐字保留**原文档（含其 2026-09-16 的「当前结果」段），另设 §0 落档说明与 §2 `C-06` 实测回填（18 条），**不改动原文** |
| 计数同步 | §0 结论 52 → **53**；§3.1 第 3 层 52 → **53**；§3.2 表 D4 5 → **6** 并改「合计」行；§4.0 标题 / 说明 / 总表加行；§4.4 标题（4 → 5 份）与明细行；§4.0 尾「注入校验」48 → **49**（41 `开发文档\*.md` + 5 html + 3 `客服agent\*.html`） |
| 交叉引用 | `D1.6` §4.17 六-1 由「建议落档」改为「✅ 已落档 = `D4.6`」；`D2.1` `C-06-a` 标记 ✅ 已办；`tests/unit/core/test_customer_service_rules.py` 的基线注释改指 `D4.6` |
| **未做（诚实声明）** | 未恢复仓库内被删的同名文件（文档区 = `开发文档\`，不是 repo）；未追改 §11.2 的「52 行」记载（那是第八轮的**历史事实**，不追溯修改） |
---
## 19. 第十五轮：`D2.5` 演示脚本与账号速查落档（`F-03`/`F-04`/`A-05` 三合一，2026-09-19）
> **本轮做什么**：把 `D2.1` 批次 `F` 的三项交付（`F-03` 演示脚本 / `F-04` 演示前自检 + 账号速查 / `A-05` 五项检查清单固化）落成**一份**可在答辩现场照着念的文档 `D2.5`，并同步本文件的计数（**53 → 54 份**；`客服agent\` **4 → 5 份**）。本轮**不改代码**（代码侧的种子与同步脚本改动见 `D1.6` §4.33）。
| 项 | 本轮落地 |
|---|---|
| 新增文档 | `客服agent\D2.5-客服Agent演示脚本与账号速查-2026-09-19.md`（域 2「对外交付」，`D2.x` 续号） |
| 为什么值得单独成文 | `A-05` 的产物**本就是文档**、`F-04` 要求「产出账号速查表并实测可登录」——三者同一读者、同一时点（演示当天），拆开必然漂移 |
| 口径来源 | 全部台词与预期答复 **2026-09-19 真 HTTP 实测**（`POST /api/v1/agent-runs` + 轮询），原始答复留痕在 `group_fqcd_jr\docs\evidence\20260919-t8-demo-lines.json`（17 条）与 `…-lines2.json`（5 条） |
| 计数同步 | §0 结论 53 → **54**；§3.1 第 3 层与 §3.2 表 D2 4 → **5**（含「合计」行）；§4.0 标题 / 说明 / 总表加 `D2.5` 行；§4.1 标题（4 → 5 份）与明细行；§4.0 尾「注入校验」49 → **50** |
| 已登记的**工具口径问题** | `tools/dependency_health_check.py` 把 **neo4j** 当硬前置（未起即抛异常），而客服链路**不需要** neo4j（长期记忆召回按 `DEC-19` 为**关**）⇒ 它会把「演示环境已就绪」误报为「没准备好」。`D2.5` §1 已写明**替代判据**；**本文档不修该工具**（改动属底座工具，须另立会签） |
| 已登记的**过期内容** | `docs/44-演示流程.md` 与 `docs/40-前端验收清单.md` 仍列 `advisor_t / abc12345`（投顾模块已清除，账号**已不存在**）。`D2.5` §2.1 已加「不要念它」警示；正式回写属 `F-05` |
| **未做（诚实声明）** | 未追改 §11.2 的「52 行」记载（历史事实，同第十四轮口径）；未重跑 HTML 校验（本轮未改 HTML） |
---
---
## 20. 第十六轮：`D8.1` 语言规范独立成文、`A-09`/`A-10` 落档与计数同步（2026-09-19）
> **本轮做什么**：按 `乙-27` / `DEC-28` 把《项目语言规范》自 `CLAUDE.md` **独立成文**（新编号文档 `D8.1-项目语言规范.md`，`CLAUDE.md` 收缩为**三行入口存根**）；并把 `A-09`《可改文件白名单》与 `A-10`《底座会签申请单》两份**纪律凭据**落进仓库 `docs\`；同步本文件的全部计数。代码与门禁见 `D1.6` §4.34 / §4.35。
| 项 | 本轮落地 |
|---|---|
| 新增文档 | `开发文档\D8.1-项目语言规范.md`（域 8「AI 协作规则」，**语言规范正文**：四条硬规则 + AI 入口协议 + 编号落位） |
| 改造文档 | `开发文档\CLAUDE.md` → **三行入口存根**（保留文件名以维持 AI 工具约定与既有引用锚点） |
| 新增纪律凭据（写在仓库 `docs\`，**不占** `开发文档\` 编号） | `group_fqcd_jr\docs\48-可改文件白名单.md`（`A-09`：类 1 纯新增 / 类 2 客服业务层 / 类 3 须会签 / 类 4 禁止修改 + **零 DDL 声明** + 实际改动对照表）；`group_fqcd_jr\docs\49-底座会签申请单-2026-09-19.md`（`A-10`：组 1 六文件八处 + 组 2 四文件 + 🆕 **组 3 组外扩张 2 文件（须补签）**） |
| 计数同步 | §0 结论 54 → **55**；§0 盘点范围 49 → **50 个文件**；§0 域表与 §3.2 表 D8 **7 → 8**；§3.1 第 3 层 54 → **55**；「合计」行改 `… + 8 = 55`；§4.0 标题 / 说明 54 → **55**；§4.0 总表 `D8.1` 行改指新文件并**新增存根行**；§4.0 尾「注入校验」**50 → 51**（`开发文档\*.md` 41 → **42**） |
| 交叉引用 | `D1.6` 新增 §4.34（`W9`）/ §4.35（`W10`）；`D2.1` 标题 **v6.20 → v6.22**（补 v6.21 / v6.22 两段） |
| **未做（诚实声明）** | ① 未改 `D7.1` / `D7.2` 的品牌，沿用 §4.7「只标注不改品牌」的既有裁定；② 未追改 §11.2 的历史计数（第八轮史实，不追溯）；③ `CLAUDE.md` **未删除**（文件名被 A2/A4 与 `ai\D8.3` 引用）；④ `docs\46` / `docs\47` **未计入**本节 55 份（它们是仓库 `docs\` 编号空间，与 `开发文档\` 编号体系两套） |
> 🔑 **口径一句话**：域 D8 的 8 份 = **7 份编号文档（`D8.1`—`D8.7`）+ 1 份不占编号的入口存根 `CLAUDE.md`**。因此「55 份」= 54 份编号文档 + 1 份存根；`开发文档\` 的「50 个文件」同理。这样写是为了**不让存根虚占一个编号**，同时又不把文件从盘点范围里藏掉。
## 21. 第十七轮：`D2.6` 答辩报告成文 + `D2.1` v6.23（`W11` 收尾）与计数同步（2026-09-19）
> **本轮做什么**：把答辩老师「客服 Agent 不智能、动不动就转人工」这条批评，落成一份**可举证的答辩主文档** `D2.6`；同步 `D2.1`（`G-03` 档位单点化收口 → **v6.23**）与 `A-09`/`A-10`（新增组 4「前端入参边界对齐」）。代码与门禁见 `D1.6` §4.36。
| 项 | 本轮落地 |
|---|---|
| 新增文档 | `客服agent\D2.6-客服Agent答辩报告-2026-09-19.md`（域 2「对外交付」，`D2.x` 续号） |
| 为什么单独成文 | 答辩现场需要一份**只看它就能讲完**的主文档：批评 → 根因 → 方案 → 安全 → **修复前/后对比** → 演示口径 → 坑与教训 → 诚实未做项 → 现场速答。这些内容分散在 `D3.6` / `D3.7` / `D2.1` / `D1.6` 四份里，现场翻不动 |
| 口径来源 | 全部真机实测：`_eval_harness\score_before.json`（修复前）vs `score_w11b.json`（修复后）、`e2e_smoke_test --read-only`、`http_probe.py`、12 条真机边界用例 `_fe_boundary_http.py` |
| 计数同步 | §0 结论 55 → **56**；§0 盘点范围 `客服agent\` 5 → **6 份**；§0 域表与 §3.2 表 D2 **→ 6**；§3.1 第 3 层 55 → **56**；「合计」行改 `6 + 6 + … + 8 = 56`；§4.0 标题 / 说明 55 → **56**；§4.0 总表新增 `D2.6` 行；§4.1 标题（5 → **6 份**）与明细新增行；§4.0 尾「注入校验」**51 → 52 份** |
| 交叉引用 | `D1.6` 新增 §4.36（`W11`）；`D2.1` 标题 **v6.22 → v6.23**（新增 v6.23 段 + §5 `G-03` 勾选）；`D2.6` §0/§6 引用 `score_before` 与 `score_w11b` |
| ⚠️ **顺带修正一处旧口径** | §0 域表的 `D2` 行此前记为 **4**（只数了 A1—A4），而 §3.2 与「合计」用的是 **5**（含 `D2.5`）—— 两处**长期不一致**。本轮统一为 **6**（含 `D2.5` + `D2.6`），并在此留痕 |
| **未做（诚实声明）** | ① 未追改 §11.2 的历史计数（第八轮史实，不追溯）；② `docs\46` / `docs\47` 仍未计入本节 56 份（仓库 `docs\` 是另一套编号空间） —— 📌 **2026-09-20 更正**：该两份因与投顾组编号撞车已改名为 `docs\48` / `docs\49`，详见 §23；③ `D2.2`/`D2.3`/`D2.4` 三份 HTML **本轮未改**（无需求变更），因此其版本号不动 |
---
---
## 22. 第十八轮：`W12` 合并与权威文档入库（2026-09-20）
> **本轮做什么**：把投顾组 3 个远端提交并入 `qyqy_develop`（**「投顾整体清除」被取代**），并把权威文档目录**入库**。代码与门禁见 `D1.6` §4.37—§4.38。
| 项 | 本轮落地 |
|---|---|
| 合并 | `e5b4d02`（parents = `5d0becb` + `74b7d00`）：14 文件重叠 / 12 处冲突；**未用 `--force`** |
| 🔴 **结论被取代** | `D4.4`/`D4.5` 的「投顾整体清除」**不再成立**（组员新功能反向依赖被删模块）⇒ `D4.5` 顶部加**状态更新**；`D4.4` 的范围清单**仍是有效的历史留痕** |
| 新增文档 | 本轮**无**新编号文档（`D4.7` 为下一轮补记） |
| 文档入库 | 仓库 `客服agent\` 21→**24** 文件、`开发文档\` 40→**50** 文件；**权威覆盖过期**，入库后逐文件零差异 |
| 计数影响 | `W12` 当轮**未改本文件计数**（56 份不变）—— 本轮只做「替换过期副本」，未新增体系编号 |
| ⚠️ 顺带登记 | `docs\46` / `docs\47` 编号撞车（我方与投顾组**同号**），当时未登记；**下一轮修正**（见 §23） |
---
## 23. 第十九轮：`W13` 密钥轮换工具 + 两份目录审计与口径校准（2026-09-20）
> **本轮做什么**：新增模型密钥轮换工具与操作手册；对 `客服agent\` + `开发文档\` 做一次**逐份审计**，修掉 12 处事实漂移与 1 处门禁失败。会话留痕见 `D1.6` §4.39。
| 项 | 本轮落地 |
|---|---|
| 新增文档 | `开发文档\D3.8-模型密钥轮换与凭据安全操作手册-2026-09-20.md`（域 3 续号，**CS-OPS-2026-023**）；`开发文档\D4.7-投顾模块恢复记录-2026-09-20.md`（域 4 续号，**CS-PURGE-2026-014**） |
| 为什么单独成文（`D3.8`） | 工具 `tools/rotate_api_keys.py` 已在，但**没有任何文档说明它为什么存在、怎么复核、怎么回退**；`D2.6` §10-4 当时只指向 `D1.6` 的一个自然段。密钥轮换是**答辩后当轮就要执行**的动作，必须有可独立执行的 SOP |
| 为什么单独成文（`D4.7`） | `D4.4`/`D4.5` 两份文档标题都叫「**清除**」，未来检索「投顾 恢复」**查不到**；而「你删了投顾又恢复了？」是答辩**必被追问**的一点。需要一个描述**仓库现状**的单据 |
| 计数同步 | §0 结论 56 → **58**；§0 域表 D3 7 → **8**、D4 6 → **7**；§0 盘点范围 `开发文档\` 50 → **52 个文件**；§3.1 第 3 层 56 → **58**；§3.2 域表与「合计」行 → `6 + 6 + 8 + 7 + 1 + 17 + 5 + 8 = **58 份**`；§4.0 标题与说明 56 → **58**；§4.0 总表新增 `D3.8` / `D4.7` 两行；§4.2 标题（7 → **8 份**）与 §4.4 标题（5 → **6 份**）各新增一行；§4.0 尾「注入校验」52 → **54 份**（`开发文档\*.md` 42 → **44**） |
| 🔴 **修正一处长期错误** | §4.0 总表与 §4.1 明细把 `D2.1` 的版本记为 **v5.3**（第十一轮口径），而 `D2.1` 早已到 **v6.26**；§1 权威链与 §2「开工只读 5 份」表也同步更正 |
| 🔴 **修正一处门禁失败** | `tools/check_authoritative_docs.py`（`D3.4` `N-14` 登记的门禁）因 `docs\46`/`docs\47` **编号撞车实测 FAIL**。按「**后到者让位**」（组员 2026-09-16 建、我方 2026-09-20 建）把我方两份改名为 `docs\48-可改文件白名单.md` / `docs\49-底座会签申请单-2026-09-19.md`，并同步 **8 处引用** |
| §8 遗留项闭合 | `D-5`（前端品牌面）、`D-6`（系统名统一）、`D-7`（语料入库门禁）、以及「`_chunks.jsonl` 未重灌库 / 仓库副本未同步」**四行**逐项标注为**已闭环**，并如实登记 `D-5` 的 **2 处真实残留**（`W12` 合并引入，本轮修正） |
| §10.2 表述更正 | 「本区不在任何 git 仓库内」→ **已于 2026-09-20 入库** |
| 外部文档同步 | `客服agent\`：`D2.1` → **v6.26**（新增 v6.26 段）；`D2.2`/`D2.3`/`D2.4` 三份 HTML 加**投顾口径状态更新**并修正过期徽标；`D2.5` 修正 `advisor_t` 口径 + 切入一键脚本；`D2.6` 更新门禁数字并闭环两项「未做项」 |
| ⚠️ **未做（诚实声明）** | ① 未追改 §11.2 的历史计数（第八轮史实，不追溯）；② `docs\` 仍是另一套编号空间，**不并入本节 58 份**；③ 未改 `D7.1`/`D7.2` 的品牌（§4.7 既定裁定）；④ 投顾 `config_release` 工具白名单（`advisor:*`）**仍未发布** —— 与客服线无关，见 `D4.7` §5 |
## 24. 第二十轮：`W15` 修 `P1` 错分「风险测评结果」+ `D2.2` v2.6 / `D3.1` v2.5（2026-09-20）
> **本轮做什么**：把「本人画像问答」这条能力从 `P1` 的误分类里解放出来，并同步三份权威文档的版本位。**本轮改代码 + 改文档 + 补守卫**。
| 项 | 内容 |
|---|---|
| **触发** | 用户指出 §1.2.1「客户能看本人的持仓/交易/账户/画像与风评」与 §1.4.5 `P1`「账户与个人数据（含风险测评结果）Agent 无权限读取」读起来互相矛盾 |
| **根因（实测）** | `route_message()` 在画像分支之前，且 `P1_KEYWORDS` 含裸词「风险测评结果」⇒「我的风险**等级**是多少」走画像作答，「我的风险**测评结果**是什么」被降级成「无法读取本人账户数据」——**同一诉求两种结论** |
| **依据（决定性）** | `D2.2` **§1.7 第 21 项**：「画像字段级读取…**画像问答字段直返**」；`D3.1` **§0.3 术语表「画像问答」**：「**画像问答属客服能力，与持仓查询严格区分**」⇒ 原收录属**错分**，不是安全收紧 |
| **代码改动** | ① `app/core/customer_service_rules.py`：`P1_KEYWORDS` 移除裸词、`P1_PATTERNS` 新增**混问法守卫**（新发现的第二处漏网：画像词在前、账户词在后时会落到 `P3`）；② `customer_service.py::render_profile` 与 `profile_projection.py` 补「**投影层白名单 ⊇ 客服对话渲染集**」口径（`total_asset` / `behavior_score` / `risk_tags` 刻意不陈述——渲染它们等于用画像工具绕过 `P1`） |
| **守卫** | `tests/unit/core/test_customer_service_rules.py`：`RT-004` → `None`、新增 `RT-004b` → `P1`、`SAFETY_CASES` 改**显式名单**；`tests/unit/service/test_customer_service_agent.py`：新增端到端 + 反向守卫用例 |
| **文档改动** | `D2.2` **v2.5 → v2.6**（`FR-CS-023` 的 `P1` 列表 + ⚠️ 口径更正 + §1.2.1 跨节说明 + 变更记录行）；`D3.1` **v2.4 → v2.5**（`FR-CS-023` 行 / §3.7.1 触发条件矩阵 / 转人工白名单汇总表**三处** + 变更记录行）；`D4.6` **追加 §3**（不改正文）登记 `RT-004` 口径更正 |
| **计数同步** | **58 份不变**（无新增 / 改名 / 归档）；版本位同步见 §3 / §4.0 / §4.2 / §4.4 对应行（`D2.2` → **v2.6**、`D3.1` → **v2.5**） |
| **交叉引用** | `D1.6` 新增 §4.42（承接 §4.41）；`D2.1` 标题 **v6.28 → v6.29** |
| ⚠️ **判断更正（如实登记）** | ① `D1.6` §4.41 曾把画像出口误标为 `FR-CS-003` —— 实际 `FR-CS-003` 是**澄清（出口 `E1`）**，已更正两处；② 原建议「金标集加一条」，本轮**未采纳**：46 条是已发布指标的**冻结基线**，中途加第 47 条会让 `D2.6` / `D3.7` 的转人工率 / 出口准确率 / 事实正确率全部失效；改落在单元/集成守卫（覆盖等价、成本为零），**演示后可扩到 47 条再重算** |
## 25. 第二十一轮：`W16` 中长期记忆与画像联动设计成文（`D2.7`）+ 计数同步（2026-09-20）
> **本轮做什么**：把「Agent 与用户画像是什么关系 / 对话能否更新画像 / 要不要做中长期记忆」这个咨询问题，落成一份**可独立答辩的专项文档** `D2.7`，并同步本文件计数（**58 → 59 份**；`客服agent\` **6 → 7 份**）。**本轮不改代码**（咨询与成文两轮，代码口径见 `D1.6` §4.43）。
| 项 | 内容 |
|---|---|
| **新增文档** | `客服agent\D2.7-客服Agent中长期记忆与画像联动设计-2026-09-20.md`（域 2「对外交付」，`D2.x` 续号） |
| **文档内容** | 三问直答 / 客服侧五道闸门逐行取证 / `D7.3` 三层记忆上游依据 / 「对话 → 画像」既有链路 / 字段分域（`investor_type` 代码级红线）/ **主设计主张：记忆改「行为」不改「输入」** / `INV-M1`~`INV-M6` / 两处过期理由更正 / 分期 P0—P2 / 验收守卫 / 待决 4 项 |
| **计数同步** | §0 结论 58 → **59**（57 → **58 份编号**）；§0 盘点范围 `客服agent\` 6 → **7 份**；§0 域表与 §3.2 表 D2 6 → **7**；§3.1 第 3 层 58 → **59**；「合计」行改 `7 + 6 + 8 + 7 + 1 + 17 + 5 + 8 = **59 份**`；§4.0 标题 / 说明 58 → **59**；§4.0 总表新增 `D2.7` 行；§4.1 标题（6 → **7 份**）与明细新增行；§4.0 尾「注入校验」**54 → 55 份**（+1 `客服agent\D2.7-…md`） |
| **版本位同步** | 本文件头部 **v1.5 → v1.6**；`客服agent\D2.1` 标题 **v6.30 → v6.31**（新增 v6.31 段） |
| **交叉引用** | `D1.6` 新增 §4.44；`D2.7` §8 登记 `D2.2` §1.7 第 12 项与第 998 行澄清框的**过期理由①**（投顾已于 2026-09-20 恢复） |
| ⚠️ **未做（诚实声明）** | ① `D2.2` §1.7 第 12 项与第 998 行澄清框的**文本更正尚未执行** —— 属 `D2.7` §12 待决第 3 项，等用户裁定；② `INV-M1` / `INV-M2` / `INV-M6` 三条守卫单测**尚未补** —— 属 `D2.7` §10；③ **`§4.2` / `§4.4` 两类明细无需新增行**：`D2.7` 属 `客服agent\`（§4.1 一类），不在 `开发文档\` 的两类明细范围内 |
## 26. 第二十二轮：知识库 RAG 全链路与选型说明成文（`D2.8`）+ 计数同步（2026-09-20）
> **本轮做什么**：把「解析 / 切片 / 检索增强 / 选型原因」按**流程**写成一份可独立答辩的文档 `D2.8`，并同步本文件计数（**59 → 60 份**；`客服agent\` **7 → 8 份**）。**本轮不改代码**。
| 项 | 内容 |
|---|---|
| **新增文档** | `客服agent\D2.8-客服Agent知识库RAG全链路与选型说明-2026-09-20.md`（域 2「对外交付」，`D2.x` 续号） |
| **文档主线** | 按**八个阶段**逐步讲：语料与解析 → 切片 → 向量化 → 存储 → 入库七步 → 在线八步 → **检索增强 7 个动作** → 判定与五出口；另附选型 8 项决策（26 备选）、实测数据、已知不一致 5 项、复现命令 |
| **含 4 张 Mermaid 图** | 端到端全景图 / 切片与派生字段 / 检索增强 / 出口决策树 |
| **实测取证** | 切片件 **675 块**（policy 288 / product 191 / faq 150 / basic 46）；档位 `public 650` + `registered 25`；Milvus 四集合 `count(*)` 与切片件**逐集合一致**、索引全 `Finished` |
| **本轮新登记的 3 项不一致** | ① 文档写 `HNSW/IVF_FLAT` 而**实库是 `AUTOINDEX`**（且 `D2.4` §1466 已按实库登记 ⇒ 文档内部矛盾）；② `tools\configure_embedding_endpoint.py` 会建出**第二个 embedding 端点**（`qwen-embedding` / `qwen3.7-text-embedding-flash`），而现役端点是 `knowledge-embedding-qwen-v3` / `text-embedding-v3` ⇒ 重跑可能造成「索引与查询不同模型」的**无声质量崩塌**；③ `agent_faq_synonym` 表存在但**检索链路不读它**（术语归一化未落地） |
| **计数同步** | §0 结论 59 → **60**（58 → **59 份编号**）；§0 盘点范围 `客服agent\` 7 → **8 份**；§0 域表与 §3.2 表 D2 7 → **8**；§3.1 第 3 层 59 → **60**；「合计」行改 `8 + 6 + 8 + 7 + 1 + 17 + 5 + 8 = **60 份**`；§4.0 标题 / 说明 59 → **60**；§4.0 总表新增 `D2.8` 行；§4.1 标题（7 → **8 份**）与明细新增行；§4.0 尾「注入校验」**55 → 56 份**（+1 `客服agent\D2.8-…md`） |
| **版本位同步** | 本文件头部 **v1.6 → v1.7**；`客服agent\D2.1` 标题 **v6.31 → v6.32**（新增 v6.32 段） |
| **交叉引用** | `D1.6` 新增 §4.45 |
| ⚠️ **未做（诚实声明）** | ① §12 的 5 项不一致**只登记、未修复**（索引类型文档口径、二次端点守卫、术语归一化、`K-06` FAQ 阈值、basic 集合启用）；② 本文**未跑金标评测** —— §11 的数字是**语料与库的实测**，不是**效果指标**（效果指标见 `D2.6` / `D3.7`） |
---
## 27. 第二十三轮：`D2.4` 索引与语料口径更正（v1.6）+ `D2.9` 手动对话测试用例成文 + 空白消息 500 修复（2026-09-20）
> **本轮做什么**：三件事 —— ① 按上一轮登记的**建议 A**，把 `D2.4` 的**索引口径**改成与实库一致（`AUTOINDEX`），
> 顺带把**语料口径**从 628 更正为 **675 块**、补上第四集合的说明；② 新增 `客服agent\D2.9`（**手动对话测试用例**，
> 46 条金标 + 11 条边界，供人**亲自跟 Agent 对话**验收）；③ 修掉一条**真实测出来的缺陷**：`message` 纯空白 → 500（现为 422）。
| 项 | 内容 |
|---|---|
| **新增文档** | `客服agent\D2.9-客服Agent手动对话测试用例-2026-09-20.md`（域 2「对外交付」，`D2.x` 续号） |
| **`D2.4` 索引口径更正（v1.3 → v1.6）** | **直查 Milvus（2026-09-20）**：四集合索引名均为 `knowledge_autoindex`、类型 **`AUTOINDEX`**、度量 `COSINE`、`pending_index_rows = 0`、全部 `Loaded`。设计初稿的「FAQ→`HNSW` / 长文档→`IVF_FLAT`」**未落地**，且 `D2.4` 内部早已自我矛盾（§1466 按实库写了 `AUTOINDEX`）⇒ 本轮一次性更正 **9 处**（§4.1 表 / §5 schema 行 / 索引参数行 / §7.1 决策总览第 6 行 / §7.3 决策 6 全文 / 附录A / 附录D 索引行 + 规模行）并**新增「§4.1 索引口径落地注」**说明为什么不按初稿差异化（百条量级下收益不成立；`AUTOINDEX` 免调参；`IVF_FLAT` 的 `nlist` 错配反而伤召回） |
| **`D2.4` 语料口径更正** | 628 → **675 块**；实库 `policy 288 / product 191 / faq 150 / basic 46`，与 `knowledge\_chunks.jsonl` **逐集合一致**；**新增 `fin_basic_collection` 说明**——三集合仍是唯一默认检索面，基础集合为补充语料、**不入默认面**（2026-09-19 实测并入会使金标 `M-1` 100% → 91.3%）；附录F.1「现状」列改按 675 块复核（`family_id` 675/675、`param_class` 非 `none` 186 块）、F.6 复测数字更新、F.7 的四个前置标注**已全部关闭**；版本表新增 **v1.6** 行，全文版本位同步 |
| **`D2.9` 内容** | ① §0 三条对话路径（前端挂件 / 真 HTTP / 本地控制台）+ **三条铁律**（刷新＝新会话、登录限流 10 次/60 秒、先抄原文再判分）+ **界面看不到「出口」的原因与六种答复形状对照表**；② §1 判分四问 + 两条特别口径 + **`M-1`~`M-10` 门槛与实测基线**；③ §2 **46 条金标逐条可问**（问句 / 档位 / 期望出口 / 期望要点 / 禁止出现 / 实测基线 / 判分栏）；④ §3 **11 条边界 `Z` 组** + 三个实测缺口；⑤ §4 安全 4 条必演话术；⑥ §5 手动汇总表；⑦ §6 可粘贴的真 HTTP 核验配方 + 会话回放；⑧ §7 排障（把环境问题与实现问题分开） |
| **实测缺口 ①（已修）** | `POST /api/v1/agent-runs` + `message=" "` → **500 Internal Server Error**。根因：入口 schema 只有 `min_length=1`（`" "` 长度 3 能过），随后**领域层** `AgentRequest` 的 `message must not be blank` 抛 `pydantic.ValidationError`，不属于 FastAPI 请求校验异常 ⇒ 被兜底处理器变成 500。**修复**：把同一判据补到入口（`app/api/schemas/agent_runs.py` 加 `field_validator`），错误形状与其余参数错误一致（422 `AGENT_INPUT_INVALID`）；新增回归测试 `tests/unit/api/test_request_validation_envelope.py::test_blank_message_is_rejected_at_the_gateway` |
| **实测缺口 ②③（只登记、待裁定）** | ② **语料档位口径矛盾**：`public` 的 `FAQ-0014` 完整给出五档门槛（50/200/600/1000 万）、`FAQ-0050` 含「600 万元以上的钻石客户」、`PROD-017` 含四档权益摘要，而切片脚本注明「不泄露档位与门槛」⇒ 设计意图在语料层被自己推翻（**检索未越权，`M-8` 仍为 0**，已逐块核对来源）；③ **同会话重复同一模糊问句会漂移**（轮1 澄清 → 轮2 改答澄清候选里的第 2 项 → 轮3 落 chitchat，**100% 可复现**，根因未定）。两项的甲/乙选项与建议见 `D2.9` §8.1 `D-1` / `D-2` |
| **顺带修正** | `tools\chat_console.py` 的页面提示语示例含**已下线产品名**（`季季盈90天起投多少`）→ 改为 `基金申购和赎回有哪些费率`（1 行，避免给演示者错误引导） |
| **计数同步** | §0 结论 60 → **61**（59 → **60 份编号**）；§0 盘点范围 `客服agent\` 8 → **9 份**；§0 域表与 §3.2 表 D2 8 → **9**；§3.1 第 3 层 60 → **61**；「合计」行改 `9 + 6 + 8 + 7 + 1 + 17 + 5 + 8 = **61 份**`；§4.0 标题 / 说明 60 → **61**；§4.0 总表新增 `D2.9` 行 + `D2.4` 版本位 `v1.3 → v1.6`；§4.0 尾「注入校验」**56 → 57 份**；§4.1 标题 8 → **9 份** + 新增 `D2.9` 行 + `D2.1` 版本位 `v6.32 → v6.33` + `D2.4` 版本位 `v1.3 → v1.6` |
| **版本位同步** | 本文件头部 **v1.7 → v1.8**；`客服agent\D2.1` 标题 **v6.32 → v6.33**（新增 `v6.33` 段）；`客服agent\D2.4` **v1.3 → v1.6** |
| **交叉引用** | `D1.6` 新增 §4.46 |
| ⚠️ **未做（诚实声明）** | ① **建议 B（「active 的 `embedding` 端点必须恰好 1 个」配置守卫）本轮未做** —— 上一轮判定为「演示后加」，本轮沿用该计划（它只影响 `tools\configure_embedding_endpoint.py` 被重跑的场合）；② `D2.9` §8.1 的 `D-1`/`D-2`/`D-3`/`D-4` 四项**待用户裁定**；③ `D3.1`/`D3.2`/`D2.2` 的 `HNSW` / `IVF_FLAT` 表述**本轮未改** —— 它们是**完整版 / 底稿**，按「加状态更新注而非逐处改写」的口径处理，尚未执行 |
## 28. 第二十四轮：三份完整版/收敛版索引口径状态更新注 + `embedding` 端点唯一性配置守卫 + 门槛口径更正（2026-09-20）
> **本轮做什么**：四件事 —— ① 按上一轮登记的**建议 B**，加「active 端点中声明 `embedding` 能力者**必须恰好 1 个**」的**配置守卫**（只告警、不改行为）；
> ② 把 `D3.1` / `D3.2` / `D2.2` 三处仍在写 `HNSW` / `IVF_FLAT` 的地方**加状态更新注**（不逐处改写）；
> ③ 按 `D-1` 裁定（**选乙**）把「**分层体系与门槛属公开宣传口径**」写进 `D2.4` §4.4 与附录B，并**删掉切片脚本里自相矛盾的注释**；
> ④ 按 `D-3` 把 `D3.7` §3 的难例口径与 `M-2b` 分母**统一到实跑口径**（并补正初稿表格的条数）。
| 项 | 内容 |
|---|---|
| **建议 B 已落地（配置守卫）** | `app\service\model_gateway.py` 的 `DatabaseModelEndpointResolver.resolve()`：`required == "embedding"` 且 `len(matched) > 1` 时 `logger.warning`。**只告警、不改行为**（筛选仍返回全部声明 embedding 的端点）。顺手删掉重复的 `return endpoints`（死代码）。新增单测 2 条（多端点告警 / 单端点静默），`tests\unit\service\test_model_gateway.py` **10 passed** |
| **为什么这条守卫值得留** | 实库现役只有 **1** 个 embedding 端点（`knowledge-embedding-qwen-v3` / `text-embedding-v3`，`id=1`）⇒ **守卫平时是静默的**；风险来自误重跑 `tools\configure_embedding_endpoint.py` —— 它写的是 `qwen-embedding` / `qwen3.7-text-embedding-flash`，**重跑会凭空多出一个 embedding 端点**：索引向量与查询向量可能来自**不同模型**，`COSINE` 相似度整体失真且**不报错**（越答越差的哑故障）。已在该脚本头部加「**已废弃，勿重跑**」标注 |
| **`D3.1` v2.5 → v2.6** | §5.3 加「索引口径落地更正」注：`HNSW` / `IVF_FLAT` 为**设计初稿**、落地统一 `AUTOINDEX`（索引名 `knowledge_autoindex`、度量 `COSINE`；直查 Milvus 四集合 `Loaded`、`pending_index_rows = 0`）；**同注覆盖 §2.5 决策表 / `FR-CS-007` / 排期 `T4` 三处同源表述**；并补「**字段表同属初稿**」——实库 **18 字段全 NOT NULL**、`doc_id` 主键、无 `metadata` JSON |
| **`D3.2` v1.2 → v1.6** | §4.1 加「向量索引口径」注（同口径 + 「索引选择」不再是三集合划分的支撑理由）；**版本位追平**：该文档 `doc-meta` 停在 `v1.2`、顶栏停在 `v1.1`，而自身变更记录已记到 `v1.5` ⇒ 统一为 **v1.6**（与 `D2.4` v1.7 同轮） |
| **`D2.2` v2.6 → v2.7** | §1.4.2 域 B 加「`FR-CS-007` 索引口径」注：原文为设计初稿、落地 `AUTOINDEX`；**TopK（3 / 5）/ 阈值（0.75 / 0.70）/ 度量 `COSINE` / 集合选择均未变 ⇒ 不影响本条验收** |
| **`D2.4` v1.6 → v1.7（`D-1` 选乙）** | §4.4 加「**门槛金额不再单独构成 `registered` 的理由**」注 + 附录B `v1.3` 裁定条追加更正段。**实测依据**：`public` 的 `FAQ-0014` **已完整给出五档门槛**（普通 / 金卡 50—200 万 / 白金 200—600 万 / 钻石 600—1000 万 / 专户 1000 万+）、`FAQ-0050` 含「600 万元以上钻石客户」⇒ **分层体系与门槛属公开宣传口径**；`HNW-004`—`HNW-007` **保持 `registered`，但依据收窄为「各层级权益明细与专属服务内容」**。**`HNW-*` 档位本轮不动**（`visibility` 是**分区键**，改档位须重建集合） |
| **切片脚本注释已删改** | `tools\build_knowledge_chunks.py`：原注释「**不泄露档位与门槛**」与 `D2.4` 新口径冲突 ⇒ 改写为「`registered` 的依据是**权益明细**而非门槛；门槛属公开宣传口径；改档位前先读 `D2.4` §4.4 与附录B」 |
| **`D3.7` §3 口径统一（`D-3`）** | 难例 **32 条**（改写 8 + 口语 16 + 多轮 4 + 禁忌 4）是「非原句照搬」的**定义式**总数（14 + 32 = 46）；`M-2b` 的**分母是其中带「期望证据家族」的 18 条**（其余 14 条 `E-01`—`E-04` / `F-01`—`F-03` / `F-05` / `G-01`—`G-05` / `H-03` 不考检索 `top1`，由 `M-1` / `M-4` / `M-6` / `M-7` 覆盖）。**同时补正**：§3 初稿表格的「改写 18 / 口语 8 / 多轮 3 / 禁忌 3」与落地件 `_eval_harness\cases_46.json` 的 `phrasing` 字段不符 ⇒ **一律以落地件为准** |
| **版本位同步** | `D2.2` **v2.6 → v2.7**、`D2.4` **v1.6 → v1.7**、`D3.1` **v2.5 → v2.6**、`D3.2` **v1.2 → v1.6**；本文件 §1 编号对、§4.0 总表、§4.1 明细、§4.2 明细四处版本位同步；本文件头部 **v1.8 → v1.9** |
| **顺带修正（此前遗留）** | §4.0 / §4.1 里 `D2.4` 的版本位**长期停在 `v1.3`**（实际早已 `v1.6`）⇒ 本轮一并更正为 **v1.7**；§4.2 里 `D2.2` 的日期列停在 `2026-09-17` ⇒ 更正为 `2026-09-20` |
| **交叉引用** | `D1.6` 新增 §4.47；`D2.1` 新增 `v6.34` 段 |
| ⚠️ **未做（诚实声明）** | ① 三份完整版/收敛版的 `HNSW` / `IVF_FLAT` **原文保留**（按「加状态更新注而非逐处改写」的口径，避免把历史推导改花）；② `D2.9` §8.1 的 `D-2`（重复问句漂移）仍**只登记不修**、演示避开；③ `D-4`（英文问句落 `E5b`）登记为已知边界，未改代码 |
## 29. 第二十五轮：`W20` 咨询轮 —— 「按我的风险等级能买什么」被安全门禁误拦的根因定位（2026-09-20）
> **本轮做什么**：用户提问「这个为什么不能根据自己的风险等级去给他列出来他能买的产品」（附前端截图）。本轮**只做定位**：真机复现 6 条 + 离线判据复算 + 读码，**不改代码、不改任何文档版本位**。
| 项 | 内容 |
|---|---|
| **现象** | 已登录客户 `cust_t` 问「我现在可以买什么等级的产品」→ 拿到 `ADVICE_BOUNDARY_REPLY`（「不能为您推荐具体产品…」整段边界话术） |
| **根因** | `app\core\customer_service_rules.py` 的 `route_message()` 中 `PROMOTION_REQUEST_PATTERNS` **第 4 条**命中；其 `{0,6}` 窗口不认「等级 / 风险等级」限定词 ⇒ 把「问等级范围」（公开规则题）判成「问产品」（推介请求）。**与 `G-01` 同一缺陷形态** |
| **为何后果严重** | 该门禁在 `_route_and_answer()` **第一行**，命中即短路 ⇒ 后面**本来能答**的路径（画像出口 / `E2` 计算型）**全部跑不到** |
| **反证（能力已在）** | 同账号下「我是 C1，能买 R3 的产品吗？」→ `E2c` 矩阵答对；「我的风险等级是多少」→ 答出**保守型（C1）** |
| **第二处缺口** | 现行出口**无**「本人等级 + 匹配矩阵」的组合路径 ⇒ 建议新增 `E2c-my` |
| **合规依据** | `PROD-012` §4.2（**`public` 档**）明文给出 C1—C5 的 R 范围（**C1 → R1—R2**），且自行声明不含配置比例与收益区间 ⇒ 告知「可购买哪些风险等级」**不构成投资建议** |
| **待决** | `DEC-W20-1`…`-5` 五条（含**回归钉子**「帮我推荐一只基金」修完后**必须仍拦**），详见 `D1.6` §4.48 五 |
| **版本位** | **本轮不改任何文档版本位**（纯会话记录）；本文件头部 v1.9 → **v1.10** |
| **交叉引用** | `D1.6` 新增 §4.48；`D2.1` 新增 `v6.35` 段 |
| ⚠️ **未做（诚实声明）** | 未改代码、未跑全量回归、未改金标；五项待决**等用户裁定**后再执行 |
---
## 30. 第二十六轮：`W20` 实施轮 —— 新增出口 `E2c-my` + 展示层净化 + 两处真实业务缺陷修复（2026-09-20）
> **本轮做什么**：按用户「**贴合真实业务场景，自己去推理、自己判断、自己修复**」的要求，把「推理 → 测试 → 修复」一次性跑完，并把五出口扩为**六出口**（新增 `E2c-my`）。
| 项 | 内容 |
|---|---|
| **新增出口 `E2c-my`** | 按**客户本人权威测评等级**给出「可购买范围 + 在售清单」。依据 `PROD-012` §4.2（**`public` 档**）C—R 矩阵；清单只含**代码 / 名称 / 类别 / 风险等级**，**按产品代码升序**（不按收益排 —— 排序即隐性推荐）；出口后置 `promotional_wording_violation` 护栏，命中即降级为只讲范围 |
| **新增工具与发布** | `query_eligible_products`（`suitability:read`，customer / advisor / operator / admin），发布 **release 220**（active）。⚠️ 提示词模板与工具白名单**不在同一张表**，发布脚本必须**两级继承**（`platform_config_item` + `active_prompt_templates()`），否则提示词被静默丢弃 |
| **点名档位的直接裁决（新）** | 「我可以买 R3 的产品吗」修复前**只给清单、不说"不可以"**；现在先给一句直接裁决再列范围（裁决由矩阵结果反推，措辞与 `E2c` 同源） |
| **`P2` 自助流程问法豁免（新）** | 「怎么修改绑定的银行卡」修复前**建单转人工**，而 `FAQ` 里**就有**这条答案；新增 `P2_SELF_SERVICE_PATTERNS` + `P2_DELEGATION_MARKERS`（「帮我把绑定银行卡换一下」**仍转人工**） |
| **展示层净化（新）** | `render_plain`（去 markdown 标记）/ `drop_yield_claims`（收益数值不得输出）/ `prettify_title`（澄清候选），接在 `E3` / `E4` / `E5b` / 澄清候选**四处**；**空结果护栏**：被清空的块（实测 15 个纯收益切片）**回退 `E5b`，不给空气泡** |
| **测试** | 定向 **334 passed**；全量回归 **1969 passed / 3 skipped / 0 failed**（本轮基线 1946 passed） |
| **金标 46 条** | `M-1` **46/46 = 100%** / `M-4` **100%** / `M-6` **5/46 = 10.9%** / `M-7`·`M-8`·`M-9`·`M-10` **全 0**；与上一轮 `score_w11b` **逐项一致 ⇒ 零回归** |
| **真机场景扫描** | 25 条客户问法 + 3 条访客问法 ⇒ 转人工 **3/25**，全部为**应转**（投诉 / 销户 / 代办写操作） |
| **顺带修掉一处测试隐患** | 旧测试用 `Class.attr` 存取 `staticmethod` 再赋回，会把静态方法**静默变成普通方法**（后置测试全部少传 `self`）⇒ 改存取 `__dict__` 里的描述符 |
| **四项待决已裁定（2026-09-21）** | 用户「**按照你建议的来**」⇒ `DEC-W20-6` / `-7` / `-8` / `-9` 按建议口径定案（**全部为"维持现状 / 演示后再做"**），本轮**无代码变更**；详见 `D1.6` §4.49 六 |
| **`W21` 第二轮：§6 四项待决按建议落地（2026-09-21）** | 用户「**按照你建议的改**」⇒ `W21-D1`（`E4` 提示词禁止输出收益数值，system ② + 模板 ④ 双处）/ `W21-D2`（适当性出口明示指代依据）/ `W21-D3`（`E5b` 答非所问闸门）/ `W21-D4`（`E5b` 作答语气 + FAQ 直入）**四项全部落地**。三条「检索命中完全正确却拿兜底话术」的问句由 **0/9 → 9/9** 走 `E4` 真实作答；金标 `M-1 46/46`（**含 1 条期望修订：`I-01` 补 `E4`**）、全量 **`1994 passed / 3 skipped`**；`ruff` 零新增。⚠️ **新发现**：`docs/43-场内基金产品手册` **从未进 `SOURCES`**（702 块里「科创债」0 处）—— 已登记为下一轮第一顺位待决 |
| **版本位** | 本文件头部 **v1.13 → v1.14**；`客服agent\D2.1` 标题 **v6.37 → v6.38**；`客服agent\D2.9` **v1.1 → v1.2**；`开发文档\D3.7` **v1.0 → v1.1**（`I-01` 注）；`开发文档\D4.8` **v1.0 → v1.1**（新增 §9）；`开发文档\D1.6` **v1.0 → v1.1**（新增 §10） |
| **`D2.9` 手动测试用例全量复跑（v1.0 → v1.1）** | 46 条金标 + 11 条边界 + 安全 4 条走**真 HTTP（路径 B）**：出口 **46/46**、事实 **46/46**、禁忌 **0**、转人工 **5 条**；同时**校准 `D2.9` 里因本轮改模板而过时的出口话术**（澄清「您想了解的是下面哪一项呢？」/ `E5b`「我先帮您把找到的公开资料放上来」）并回填 §2 的 46 个判定与 §5 的 11 项指标。⚠️ 另登记一处**判据更正**：首版跑批脚本的出口形状判定写成"首个期望命中即返回"，造成 13 条假阴性，改为"任意命中"后 46/46 |
| **版本位** | 本文件头部 **v1.11 → v1.12**；`客服agent\D2.9` **v1.0 → v1.1** |
| **版本位** | 本文件头部 **v1.10 → v1.11**；`客服agent\D2.1` 标题 **v6.35 → v6.36**；§2 开工只读表 / §4.0 总表 / §4.2 明细**三处 `D2.1` 版本位一并同步**（此前长期分别停在 `v6.30` / `v6.32` / `v6.33`） |
| **交叉引用** | `D1.6` 新增 §4.49；`D2.1` 新增 `v6.36` 段 |
| ⚠️ **未做（诚实声明）** | ① 人设只做"语气层"，未做更外显的人设；② 收益过滤只在**展示层**，未推回语料层；③ 金标仍为 **46 条**；④ `D2.9` §8.1 的 `D-2` **残余**（同句重问**候选**仍会变，形状已稳）与 `D-4`（英文问句落 `E5b`）仍只登记不修 |
---
> **维护责任**：本文件为活文档。**新增 / 改名 / 归档 / 改版本号后，须同步更新本文件 §3 与 §4.0 总表对应行**。
>
> 编制：项目文档组 | 审核：合规稽核部 | 日期：2026-09-17
---
## 31. 第二十七轮：`W24` 语料入库轮 —— `docs/43` 场内基金手册入库 + `B-02` 展示候选集收口（2026-09-21）
> **本轮做什么**：按用户「**先把语料修复吧 在进行下一步 不单独立项了**」执行 `W21` §9.5 第 3 条登记的待决 —— 把 **20 只场内基金**（`docs/43`）正式纳入切片 `SOURCES` 并重建重灌四个 Milvus 集合；收尾时修掉一处 `B-02` 的 `M-4` 回归。
| 项 | 内容 |
|---|---|
| **语料入库** | `docs/43-场内基金产品手册（知识库入库版）.md` 纳入 `SOURCES`（`prefix=ETF` / `fin_product_collection` / `public` / `V1.0` / `2026-09-11` / `JR-ETF-2026-001`）；切片件 **702 → 755 块**（`policy 288 / product 251 / faq 154 / basic 62`），档位 `public 730 / registered 25` |
| **新增三个按源开关** | `strip_editorial_marks`（丢 `>` 行 + 清 `⚠️`；该手册含**内部编辑说明**，不能给客户看）/ `qualify_table_rows`（7 列、5 列表格**按表头逐列**串成自解释正文）/ `exclude_sections`（导航型小节「3.2 其他产品的查询」不入库）；**默认关** ⇒ 其它 8 个源实测 `changed existing blocks: 0` |
| **修掉两个真实缺陷** | ① `W24-A` **切片器行标签取错列**：多列表格第 0 列是**代码**（`159700[:2]`=`15`）⇒ 上游 `_prefer_section` 判不出重合 ⇒ **每一问都被换成整节块**（实测「科创债ETF南方怎么样」返回 20 只产品的整张表）；改取表头「名称」列。② `W24-B` `text-embedding-v3` **单请求上限 10 条**，`load_knowledge_milvus.embed()` 只在灌库路径分批 ⇒ **自检路径**超 10 条即在**数据写完后**崩（14 条触发）；分批下沉进 `embed()`（`MAX_BATCH = 10`） |
| **`B-02` 的 `M-4` 回归修复** | `_exit_partial` 两条调用路径**候选集不同**（主路径 TopK 全量 vs 证据路径被 `E4_MAX_EVIDENCE=6` 截断）⇒ **同一句问句的答复质量取决于「`E4` 有没有调用模型」**。`_answer_from_evidence` 新增 `display_hits`，**展示候选一律用 TopK 全量**；送模型的证据包保持 6 块不变 |
| **产品名识别补全** | `_PRODUCT_NAME_SHAPE` 后缀集补 `定期开放混合\|股票\(LOF\)[ABC]?\|\(LOF\)\|原油[ABC]?`；新增 `_BRANDLESS_PRODUCT_NAMES`（`沪深300ETF`，**唯一无厂商字样**的产品，只能枚举不能用通用后缀）；`_strip_product_name_lead` 增「先切掉前一只基金」 |
| **测试** | 新增 **2 条守卫**（20 只产品名全覆盖 / 无厂商字样产品不在类目问句上开门）；全量回归 **`1996 passed / 3 skipped`**（上一轮 `1994`）；`ruff` **零新增**（本轮曾引入 2 条 `B905`，当场改 `zip(..., strict=True)` 清零） |
| **金标 46 条** | `M-1 46/46`、`M-4 46/46`、`M-6 5/46`、`M-7/M-8/M-9/M-10 = 0`、`M-2 28/31`、`M-2b 15/18`、`M-3 4/4` —— **与 `w23` 基线逐项一致**；**两次独立复跑**（`result_w24d` / `result_w24e`）指标完全相同 |
| ⚠️ **判据变更（3 条，必须知情）** | ① `B-01`（访客）`expected_evidence` 补 `ETF`；② `B-05`（客户，**同一句问句**）`expected_exits` `[E3]` → `[E3, E4]`；③ `load_knowledge_milvus` 自检 `BAS-CON-006` → `ETF-005`。**本轮不适用「零回归」表述** |
| **裁定** | `docs/45`（R1—R5 问答）**不入库**（与 `FAQ-0018` / `POL-AST-011/012` 重复，会抢 top1）—— 历史承诺里的 `docs/45` 部分据此关闭 |
| **版本位** | 本文件头部 **v1.14 → v1.15**；`客服agent\D2.1` 标题 **v6.38 → v6.39**；`客服agent\D2.4` **v1.7 → v1.8**；`客服agent\D2.9` **v1.2 → v1.3**；`开发文档\D4.8` **v1.1 → v1.2**（新增 §10）；`开发文档\D1.6` **v1.1 → v1.2**（新增 §11） |
| **交叉引用** | `D1.6` 新增 §11（本轮对话上下文提取件）；`D4.8` 新增 §10（实施与验收）；`D2.1` 新增 `v6.39` 段；`D2.8` 新增 §3.6 与 §11 复测 |
| ⚠️ **未做（诚实声明）** | ① `_exit_partial` **仍按分数挑块**（不接收问句）—— 本轮只统一了**候选集**，**挑选语义**未改；② `E5b` 展示层净化仍不覆盖「收益 + 数字%」形态（`W21` §9.5 第 4 条继续挂账）；③ 语料里 **2 个零容忍地雷块**（`POL-SPM-016` / `POL-SPM-022-01`）为**禁令条款**，**故意保留** |
---
## 32. 第二十八轮：`W25` 手动测试用例按实测重建 + 展示层误删真缺陷修复（2026-09-21）
> **本轮做什么**：用户要求「**按照所有的问题帮我更新测试用例 我要看 我要依据测试用例去演示**」⇒ 用**当前实现**把 `D2.9` 的 46 条金标（含多轮 `chain`）+ 11 条边界 + 安全 4 条 + 场内基金 5 条**全部重跑真 HTTP**，逐条回填**客户可见的答复原文**；过程中发现并修掉一处**展示层净化误删答复正文**的真缺陷。
| 项 | 内容 |
|---|---|
| **为什么重做** | 旧版 `D2.9` 的「基线」列只到 `出口 · top1`，甲方**看不到答复原文**，没法「照着念」验收；且基线取自 2026-09-19，与 `W20` / `W24` 之后的实现早已不同步 |
| **真 HTTP 跑批** | `_w25_http_manual.py`（46 金标含多轮 + 11 条 `Z` + 安全 4 + 场内基金 5）⇒ `_w25_http_manual.json` / `.txt`（答复**全文**）；46 条全部 `succeeded`，HTTP 非 200 **0 条** |
| **出口与命中明细** | `_eval_harness/probe.py` → `result_w25.json`；`score.py` → `score_w25.json`（十项指标）—— 出口 / `Top1` / 引用可解析这类指标**只在进程内判**，HTTP 响应里看不到 |
| 🔴 **真缺陷（已修）** | `A-06`「什么是业绩比较基准？」只回「问：…」而**「答：」整段消失**。根因：`drop_yield_claims()` 判「整行含收益数值就不输出」，而 `FAQ-0022` 里的「沪深300指数收益率×60%＋中证全债指数收益率×40%」是**权重**不是收益数值 ⇒ 整行被删。**金标抓不到**：`A-06` 的 `key_facts` 是「业绩比较基准」这个纯词，它在「问：」那行里还在 ⇒ `M-4` 照样判过（「事实判据通过、客户看到的东西是坏的」） |
| **修复口径** | `drop_yield_claims` 增加**权重豁免**（收益词与百分比之间出现 `×` / `✕` / `＊` / `乘` / `指数` ⇒ 判为业绩基准公式）；两种语序的**真实收益数值照删**；新增回归测试 `test_drop_yield_claims_keeps_the_benchmark_formula_but_drops_both_word_orders` |
| ✅ **附带改善** | `Z-04`（英文问句）从 `E5b` 兜底抬到 `E4`；**未**为英文问句单独加召回路 |
| **文档落点** | `客服agent\D2.9` **v1.3 → v1.4**（§2 每条回填「实测（出口 · top1）」+ 每组追加**实测答复原文**；§3 / §4 / §1.3 / §5 实测列刷新；**新增 §2.10 场内基金演示线**）；`客服agent\D2.5` §4.7 **出口口径更正**（第 1 条 `E3 → E4`、第 2 条 `E3 → E5b`，逐条用进程内 harness 复核） |
| **测试** | 新增 **1 条**回归测试；全量 **`1997 passed / 3 skipped`**（上一轮 `1996`）；`ruff check app tests tools` **零新增**（27 条既有告警全在**未改动**的行上） |
| **金标 46 条** | `M-1 46/46`、`M-4 46/46`、`M-6 5/46`、`M-2 28/31`、`M-2b 15/18`、`M-3 4/4`、`M-7/M-8/M-9/M-10 = 0` —— **与 `w24e` 逐项相同** |
| **版本位** | 本文件头部 **v1.15 → v1.16**；`客服agent\D2.1` 标题 **v6.39 → v6.40**；`客服agent\D2.9` **v1.3 → v1.4**；`客服agent\D2.5` §4.7 出口口径更正（**属更正**，版本位不变）；`开发文档\D4.8` 新增 §11；`开发文档\D1.6` 新增 §12 |
| **交叉引用** | `D1.6` §12（本轮对话上下文提取件）；`D4.8` §11（缺陷与验收）；`D2.1` `v6.40` 段 |
| ⚠️ **未做（诚实声明）** | ① `E-02` / `H-01`（「那风险高吗？」）实测只回 28 字的**一行风险等级**（`E3` 原文直返一个单行块）—— 内容正确但**偏短**，要更饱满需另立改项；② `D-2` 残余（同句重问**候选会变**）仍未修；③ 本轮只做了「**不误删**」，**没有**把收益过滤推回语料层 |
## 33. 第二十九轮：端到端答辩文档成文（`D2.10`）+ 计数同步（2026-09-21）
| 项 | 内容 |
|---|---|
| **新增文档** | `客服agent\D2.10-客服Agent端到端答辩文档-2026-09-21.html`（域 2「对外交付」，`D2.x` 续号，**v1.0**） |
| **为什么单独成文** | `D2.6` 回答「凭什么说改好了」、`D2.8` 回答「RAG 链路怎么走的」，但答辩现场最常被问的是「**一条提问进来，到底经过了什么、为什么变成那句答复**」。这条**端到端**链路（入口 → 队列 → Worker → 安全路由 → 档位 → 意图 → 检索增强 → 出口 → 输出守护 → 治理返回）此前分散在 4 份文档里，**无一份可独立讲完** |
| **结构** | 0 一页速览 / 1 系统边界 / 2 端到端全景（**主流程图** + 十段说明 + 时序图）/ 3 十段流水线逐段详解 / 4 出口判定与阈值 / 5 安全不变量与白名单 / 6 实测效果与门禁 / 7 演示路径与台词 + 15 分钟分配 / 8 现场速答（含**必问主观题 Vibe Coding**）/ 9 坑与教训 10 条 / 10 诚实未做项 10 条 / 11 引用与留痕 |
| **含 4 张 Mermaid 图** | 端到端主流程图（10 阶段 + 4 类安全分支）/ 端到端时序图（`sequenceDiagram`，含 202 + 轮询）/ 五档安全路由优先级图 / 出口判定决策树 |
| **口径来源（不引入新数字）** | `D2.6`（金标 11 项前后对比）/ `D2.8`（阈值、常量、检索 7 动作）/ `D2.5`（台词与账号）/ `D2.7`（`INV-M1`~`INV-M6`）/ `D2.9`（实测答复原文）/ `D3.6`（出口依据）/ `D3.7`（判分）/ `D5.1`（三红线）/ `D4.8`（`W21`/`W24`/`W25` 三处缺陷） |
| **交付前校验** | 项目自带校验脚本：**1466 行 / 25 锚点 / 41 表格 / 4 Mermaid / 1 代码块，全部通过**（标签闭合 / 锚点有效 / 围栏成对 / 无占位残留） |
| **计数同步** | §0 结论 61 → **62 份**（60 → **61 份编号**）；§0 盘点范围 `客服agent\` 9 → **10 份**；§0 域表与 §3.2 表 D2 9 → **10**；§3.1 第 3 层 61 → **62**；「合计」行改 `10 + 6 + 8 + 7 + 1 + 17 + 5 + 8 = **62 份**`；§4.0 说明 61 → **62**；§4.0 标题 62 → **63**；§4.0 总表新增 `D2.10` 行；§4.1 标题（9 → **10 份**）与明细新增行；§4.0 尾「注入校验」**57 → 58 份**（`客服agent\*.html` 3 → **4**，即本文件） |
| **版本位同步** | 本文件头部 **v1.16 → v1.17** |
| ⚠️ **未做（诚实声明）** | ① **未做全量文件普查**，故本轮只做**增量同步**：§0 的「61 份 = 60 编号 + 1 存根」与「`开发文档\` 53 文件 = 52 编号 + 1 存根」+「`客服agent\` 9 份」三者**本就对不上**（52 + 9 = 61 编号 ≠ 60 编号），且 §4.0 标题长期比 §0 **多 1**。本轮**按原有偏移同步、未就地改写**——要定案须一次**全量文件普查**。② 本文档**已同步到仓库镜像** `group_fqcd_jr\客服agent\`（`D1.6` §4.38 单向覆盖；两侧 **SHA256 前 16 位一致** `f3a0102983563b4e`、**117078 字节**，已回读校验）。 |
## 34. 第三十轮：智能路由与行情出口设计专册（`D3.9`）+ 计数同步（2026-09-21）
| 项 | 内容 |
|---|---|
| **新增文档** | `开发文档\D3.9-客服Agent智能路由与行情出口设计-2026-09-21.md`（域 3「现行权威·完整版与专项」，`D3.x` 续号，**v1.0**，约 26 KB） |
| **为什么单独成文** | 甲方在 `W26` 提出三项异议（意图识别不清 / 分级回退阈值不可靠 / 走势答不对 / 闲聊触发检索），**根因各不相同**，需要一份可实施的设计依据；同时 `FR-CS-008` ①「跨集合回退（阈值 0.65）」**与实现不一致**（`FALLBACK_COLLECTIONS` 为死代码），必须就地更正 |
| **结构** | §0 一句话结论 / §1 甲方原话 / §2 实测诊断（6 组证据）/ §3 目标架构（`L0` 表层判定层 · 能力路由 · 判据迁移 · 阈值标定 · `FR-CS-008` 更正）/ §4 出口 `E6` 行情 / §5 槽位白名单 / §6 闲聊与免责声明分档 / §7 `INV-6`/`INV-7` / §8 决策登记 12 项 / §9 实施与验收 / §10 文档对齐清单 / §11 诚实未做项 |
| **关键实测（不引入新数字）** | 阈值标定件：应直答 26 条 `score ∈ [0.6115, 1.0]`、不许直答 20 条 `∈ [0.5049, 0.8226]` ⇒ **区间重叠、单点阈值不可分**；DB：`fin_product` **20 条全为场内**、净值序列 122—160 日；闲聊 **9/9** 判对；收益数值改写绕过实测（`近一年表现 ｜ 约 4.12%`） |
| **计数同步** | §0 结论 62 → **63 份**（61 → **62 份编号**）；§0 盘点范围 `开发文档\` 53 → **54 个文件**（52 → **53 份编号**）；§0 域表与 §3.2 表 D3 8 → **9**；§3.1 第 3 层 62 → **63**；「合计」行改 `10 + 6 + 9 + 7 + 1 + 17 + 5 + 8 = **63 份**`；§4.0 说明 62 → **63**；§4.0 标题 63 → **64**；§4.0 总表新增 `D3.9` 行；§4.2 标题（8 → **9 份**）与明细新增行；§4.0 尾「注入校验」**58 → 59 份**（`开发文档\*.md` 44 → **45**） |
| **版本位同步** | 本文件头部 **v1.17 → v1.18** |
| **后续动作** | `D2.2` / `D3.1` 的 `FR-CS-008` 口径更正、`D3.6` §3.4 补 `E6`/`L0`、`D3.7`/`D2.9` 补用例、代码实施 —— 见 `D3.9` §9/§10 |
| ✅ **同轮补充（2026-09-21 · `W27` 代码实施已完成）** | `D3.9` 的**代码实施与回归已同轮完成**（不再是"待后续轮次"）：`L0` 表层判定层 / 出口 `E6` 行情 / 收益过滤槽位白名单 / 免责声明分档全部落地；配置版本 **`244`** 已发布；金标由 46 扩容至 **55 条**并**全绿**（`M-1 55/55`、`M-4 55/55`、`M-5` 与四项零容忍 `M-7`/`M-8`/`M-9`/`M-10` 全 0）；全量 `pytest` **2094 passed / 3 skipped**、`ruff` **零新增**。实绩见 `D2.1` v6.41、`D3.7` §6.4、`D3.9` §12 |
| ⚠️ **未做（诚实声明）** | ① 本次**只登记新增件与计数**，仍**未做全量文件普查**（历史偏移沿用，`§0` 与 `§4.0` 仍差 1）；② ~~`D3.9` 的**代码实施与回归在后续轮次完成**，本件是设计与依据，**不是完成声明**~~ → **已作废：同轮完成，见上一行** |
---
## 35. 第三十一轮：`W27` 交付面口径统一 —— 出口「五 / 六 → 七 + `L0`」+ 金标计数对齐 55 条（2026-09-21）
| 项 | 内容 |
|---|---|
| **本轮做什么** | `W27` 的**代码与设计已入库**（`3e24033`），但**交付面文档仍留旧口径**（「五出口 / 六出口」）—— 这是最容易被评委当场戳到的自相矛盾点。本轮**只改文档**（12 份，**无代码改动**），把口径统一到「**七出口 + `L0` 表层判定层**」。 |
| **口径统一的写法（重要）** | **不重写历史**：`D3.6` 的「五出口」是它的**起步定义**，原文保留并加**口径更新横幅**（列明 `W20` 六出口 → `W27` 七出口 + `L0` 的演进线，并写明**不变的**：转人工仍只是 `E5c`、白名单仍 4 类、`INV-1`~`INV-5` **一条未改**）；`D3.6` 另加 **§3.0**说明 §3.1—§3.4 的适用范围（含「分数区间重叠 ⇒ 单点阈值不存在」）。 |
| **改到哪几份** | `D3.6`（横幅 + §3.0 + 配套行计数）· `D1.1`（7 处索引/清单行）· `D2.6`（配套行 + **新增 `W27` 状态更新段** + §11 新增 3 条追问）· `D3.7`（性质行/读法/§0 计数 + **§4 增补 `W27` 扩容后的分母口径**）· `D2.9`（引用表 + 判分输入件 `cases_46` → **`cases_55`**）· `D2.8`（`W27` 判定补充行，前批已入库并核对通过）· `D2.5`（**新增 §4.8** 行情与闲聊实测台词）· `D2.10`（徽标 / meta / Mermaid / S8 表 / 时间分配 / 文档关系表 + §3.8 新增 `E6` 行与 `L0` 段 + §4.1 阈值口径块 + §6.1 + §8.1 三条追问 + §7.3/§7.4 台词）· `D3.1` / `D3.2` / `D2.2` / `D2.4`（HTML 四处 `§0.1` 前加 `callout-warn` 口径横幅） |
| **四份 HTML 规格文档的处理** | 它们是**手上维护的成品**（`客服agent\_build` 已标注「已过期 · 请勿重新生成」），故**不重跑生成器**，只在 `§0.1` 前插一段口径横幅：声明「五出口」是 v1.x / v2.x 时点的起步定义、**现行七出口 + `L0`**、**语义与安全结论全部有效、只是不再是全集**，并指向 `D3.9` 与 `D2.6` §3。 |
| **`D2.5` §4.8（新增）** | 针对甲方上轮点名的两类，全部用 **2026-09-21 真 HTTP 实跑**的答复：`159382` 走势（`E6`：近 5/20/60/120 个净值日涨跌 + 区间高低 + 数据区间 + 数据来源）／无数据源产品**如实告知**（`E6-miss`）／闲聊（**零检索**）／**反向守卫**（「在吗，想问下…起投金额」**必须走知识作答**）。并写明两个易混口径：`E6` **不调模型**（固定模板 + 纯函数，数字全部来自 `fin_nav_history`）；闲聊**调模型但完全不查库**。 |
| **`D2.6` §11（新增 3 条追问）** | 直接回答甲方原话提的问题：① 「阈值凭什么保证精确检索」→ 两组分数区间**重叠**（`[0.6115, 1.0]` vs `[0.5049, 0.8226]`），**单点阈值不存在**；② 「回退后降阈值岂不就不精准」→ 该规则**在代码中根本不存在**（`FALLBACK_COLLECTIONS` 是死代码），真接上会让 `M-1` 从 100% 掉到 91.3%，现在的回退只降**答复完整度**、**不降证据门槛**；③ 「意图识别为何不准」→ 意图分类已**降级为「增益 + 兜底」**，前面插一层 `L0` **确定性判定**。 |
| **验证** | `_sync_check.py`：权威目录 → 仓库镜像 **0 缺失 / 0 不一致**；5 份 HTML 的 `blockquote` / `table` / `tr` / `td` 开闭标签**逐项配平**；`git diff --name-only` **12 份全部是 `.md` / `.html`，无任何代码改动** ⇒ **不影响**已绿的 `pytest 2094 passed / 3 skipped`（`3e24033` 已复跑）。 |
| **版本位同步** | 本文件头部 **v1.18 → v1.19**（本轮未增删文档，`§0` 与 `§4.0` 的计数**不变**） |
| **提交** | `qyqy_develop` = `279a632`（12 files, `+172/−39`）；`zsy_developcc` = `a810f46`（覆盖式同步，与 `qyqy_develop` **树完全一致**，`git diff` 为空）。 |
| ⚠️ **未做（诚实声明）** | ① `D1.6` 会话留痕（含本轮）**待补**；② `D2.1` 执行看板的 `W27` 条目**未逐项回填**（仅头部 v6.41）；③ 历史段的「五出口」**有意保留**（`D1.6` 会话留痕 / `D4.7` / `D2.1` 批次历史 / `D3.6` 原文），**未做全文替换** —— 那会把「当时的决策」改成「现在的结论」，反而失真。 |