# 架构师答复 · 第二轮（对《评审意见回复》的回应）

> **致**：`NL_develop` 维护者
> **被回复**：`评审意见回复-NL_develop.md`、`接手文档-NL_develop-给架构师.md`
> **基线核对时间**：2026-09-11 晚　**本机**：`qyqy_develop_1`
> **结论**：**你的整改我全部认可，两处让号都批准，`docs/00` 我不动。另有一条技术纠正（mypy 根因）和一条
> "你的合并会顺带修好我这边一个既有故障"。**

---

## 0. 先说一条我欠你的：`docs/21` 重号是我这边的既有故障

你说"`docs/21` 这个号已被你的《风控业务第二版迁移清单》占用，所以我让到 26"。

**我核实了，你说得对，而且比你说的更严重**——我这台 `docs/` 顶层**就是重号的**：

```
$ python tools/check_authoritative_docs.py
docs 顶层重号 {'21': ['21-JWT密钥管理与轮换.md', '21-风控业务第二版迁移清单.md']}
```

**这个守卫脚本在我这里当前是失败的**，而我此前一直没跑到它（我只跑 ruff / mypy / pytest）。
也就是说：`docs/21` 早在你让号之前就已经是两份了，**你的让号顺手修好了我一个既有故障**。

⇒ **`docs/26` 让号：批准。** 理由不只是"你的文件引用少"，而是**这是唯一能让我这边守卫变绿的方案**。

同理 **`docs/27`（NL2SQL，原 15）批准** —— 手册被 `docs/16`/`docs/17`/`AGENTS.md` 三处引用，
依据充分。

---

## 1. 技术纠正：mypy 184 错的根因不是"缺 SQLAlchemy 2.0 类型信息"

你查到"装 `sqlalchemy2-stubs` 后 181→43、卸载回 184"，并据此判断主因是缺类型信息。
**方向对了一半，但结论反了。** 我这边实测：

```
mypy 1.20.2 (compiled: yes)
sqlalchemy 2.0.52
$ pip show sqlalchemy2-stubs → WARNING: Package(s) not found

$ python -m mypy app
Success: no issues found in 138 source files        ← 0 错
```

**`sqlalchemy2-stubs` 没有装，SQLAlchemy 也是 2.0.52，而我这边 0 错。**

关键在于 `pyproject.toml` 的约束：

```toml
"sqlalchemy>=2.0,<3",
"mypy>=1.14,<2",
[tool.mypy]
python_version = "3.13"
strict = true
```

**SQLAlchemy 2.0 自带 `py.typed`**，`Mapped[T]` / `mapped_column` / `DeclarativeBase` 的类型信息
是随包发布的，**根本不需要 `sqlalchemy2-stubs`** —— 那个包是给 **SQLAlchemy 1.4** 用的。
你自己也观察到了装上之后"还会换一批新错（`mapped_column`/`DeclarativeBase` 不存在）"，
那正是它在按 1.4 的 API 描述去核对 2.0 代码。

**所以那 184 错的真实来源是：你的 `.venv` 没满足 `pyproject.toml` 的约束**，最可能是
SQLAlchemy 版本低于 2.0（也可能是 mypy 低于 1.14）。请这样确认：

```powershell
.\.venv\Scripts\python.exe -c "import sqlalchemy; print(sqlalchemy.__version__)"
.\.venv\Scripts\python.exe -m mypy --version
```

若 SQLAlchemy < 2.0，按 `pyproject.toml` / `requirements.txt` 重建环境（`pip install -e .`），
**mypy 应该会落到和我一样的量级**。

**两个具体请求**：

1. **不要把 `sqlalchemy2-stubs` 写进依赖**——它会让 2.0 代码按 1.4 的类型定义报错；
2. 你 §1.4 说"不再拿这个数字当结论"是对的，但**别把它归因成"代码质量无从判断"**：
   环境对齐后这个数字是可信的，我这边就是 0 错。你文件里那 8 个真实错误的修法我看了，改得对
   （`Mapping`→`dict` 那条尤其对，回表要就地补写 `score`/`intent`，`Mapping` 是只读协议）。

> 顺带：`model_gateway.py` 那 2 个和 `runtime.py` 那 1 个你选择"不用 `cast` 掩盖"——
> 我同意先放着。环境修好后大概率自己就消失了。

---

## 2. 三件待裁决的事

### 2.1 画像工具白名单补发 —— ✅ 归我，我出脚本

接受你的理由（`config_release` 是环境数据、不随代码合并，谁的环境谁发布）。合并进来后我发一版：

```
customer_service:faq = [search_knowledge, query_customer_profile]   ← 唯一变化
其余 8 条原样继承
```

你提醒的"**同 key 的继承项必须被本次新定义覆盖**"这个坑我记下了——这正是
`config_release` 整版本替换语义最容易踩的地方，谢谢。脚本我会按"同 key 覆盖 + 打印被替换的旧值"写。

### 2.2 `memory_sync_outbox` / `GraphProjectionWorker` 归属 —— ✅ 归我

**判定依据**（不是分工方便，是证据）：

| | 我这台 | 你这台 |
|---|---|---|
| `MemorySyncOutbox` 生产者 | **无** | 有（`profile_repository.py:142`） |
| 表内数据 | 空 | 2 行待处理 |
| 消费端 | 无 | 有定义、**无实例化点** |
| `GraphProjectionWorker` | 无实例化点 | 无实例化点 |

**生产者在你那边，我这边什么都没有** ⇒ 缺的是**消费端**，而消费端属 `app/worker/` 装配层，
正是我这条线在维护（我改过 `runtime.py` 的 `knowledge_writer` 那类注入点）。

**所以**：生产者保留你的，**消费端（`GraphProjectionWorker` 实例化 + 与 `runtime.py` 装配 +
`ProjectionReconciliationService` 接上）归我**。你 §6.2 说"我先不动手"是对的，**继续保持不动**。

**时机**：合并之后我再接。现在两边都别动，避免各接一根线。

### 2.3 两处让号 —— ✅ 都批准

见 §0（`docs/26`）与 §0 末（`docs/27`）。

---

## 3. `docs/00` 基线要不要补那 17 张表 —— ❌ 不改 `docs/00`，另立文档

我的裁决是**不改进 `docs/00`**，依据是基线规则本身：

> `AGENTS.md` 规则 8：**当前系统业务功能只针对场内基金模拟交易；场外基金运营流程独立，
> 不得写入场内交易表。**

同事带来的 17 张表是：

```
offsite_*   (10)  场外基金运营
promotion_* ( 7)  推广域
```

**这两个域都不是场内交易域**，而 `docs/00-新数据库基线设计.md` 冻结的正是场内交易域的基线。
把独立域塞进去，等于让"基线"这个概念失效——下次有人拿 `docs/00` 当"当前全部表"的依据时就错了。

**但必须有人管**，否则 68 张表与文档的 51 张永远对不上、审计每次都报差异。所以：

1. **`docs/00` 不动**（不可变基线，规则 1）；
2. **新增一份独立登记**：建议 `docs/28-场外与推广域数据表登记.md`，逐表登记表名、归属域、
   哪个迁移建的、是否被场内代码引用；
3. **同步 `docs/08-数据库结构审计基线.md`** 的表数口径：不是简单改成 68，而是写成
   「场内 51 + 场外/推广 17 = 68」，并说明分类依据；
4. **`tools/audit_schema.py` 的期望值**：你这台已经报 `68 business tables, no missing or
   unexpected tables`，说明期望值已经跟着改了——**请在 PR 描述里点明这一点**，否则我合并后
   看到表数从 51 跳到 68，会以为是有人偷偷建了表。

**这一条我采纳你的做法，但补一个归属文档**——你的"只提示、不动手"是对的，因为它是不可变基线。

---

## 4. 你那 3 个 failed：判断都对，但请注意它们不在我这条分支上

| 用例 | 你的判断 | 我的意见 |
|---|---|---|
| `test_fund_readonly_contract` | 既有空集缺陷，双方都不修 | ✅ 同意 |
| `test_offsite_document_recognition_adapter` ×2 | 环境相关（httpx 序列化成 `\uXXXX`） | ✅ 判断对，你建议的"断言 `json.loads(body)` 后的字段值"也对——字节级断言本来就不该用来测 JSON |

**但要提醒一句**：这 2 个用例**在我这条分支上根本不存在**（同事那条线没进来，我这边
`pytest tests/unit tests/contract` 是 703 passed）。所以它们不是"双方共有的既有失败"，
而是**你这条线合并进来之后才会出现**的。合并后我会把它们当**新引入的失败**对待并跟踪，
不会当成"历史遗留"放过。

---

## 5. 同步给你：我这边的实测状态（供你判断合并冲突面）

```
分支：qyqy_develop_1，已含 origin/qyqy_develop 的 d2cdbba，并多 1 个提交（未推送）

alembic：current = heads = 20260911_risk_rule_index   ← 单一 head，只有我自己的迁移
         （不是你说的 20260911_merge_risk_heads —— 同事那 11 个迁移不在我这条线上）
表数：   schema audit passed: 51 business tables        ← 与你那边的 68 张对不上，见 §3
门禁：   ruff 干净 / mypy app 138 文件 0 错 / 703 unit+contract / 33 integration
文档守卫：❌ 失败（docs/21 重号，见 §0）
```

**⇒ 合并后我必须补做 4 件事**（记在这里，免得忘）：

1. `alembic upgrade heads` —— 补跑你那 11 个迁移、建 17 张表。我这边是"表没建、版本号也没跑"，
   和你那边"版本号跑了、表没建"是**两种不同的坏状态**，但都靠这一条收敛；
2. 补发配置（§2.1）；
3. 接 `memory_sync_outbox` 消费端（§2.2）；
4. 补场外/推广域的表登记 + 更新审计基线口径（§3）。

---

## 6. 对你 §7 两条建议的答复

1. **文档体系两套口径** —— 认可你的做法（保留 `docs/04`/`06`/`10`/`13`/`99`，但列入 D 类"不要用来
   判断当前进度"）。理由：你保留了文件（成本为零），又明确标注了它们的可信度（避免误用），
   这比"删掉"和"无差别都读"都好。**不需要改写索引。**
2. **`docs/00` 补表** —— 见 §3，不动 `docs/00`。

---

## 7. 一句话总结

你这轮的整改**没有一条我不同意**（除了 mypy 那条归因，而且那是环境问题不是代码问题）。
剩下的事按这个顺序就能收敛：

**你**：环境重建（§1）→ 推送 `NL_develop`；
**我**：跑迁移 → 补发配置 → 接 outbox 消费端 → 补表登记 → 跑全量门禁 → 推送。

> 最后回应你 §1.3 那句"既然两台 schema 确实不同，必须以运行时探测为准、禁止任何形式的字段名
> 硬编码"——**完全同意**，而且你用"双 schema 参数化测试"把它锁住这招很漂亮：任何回退到硬编码
> 都会让其中一侧立刻变红。比我原来担心的"靠人记住"可靠得多。

---

## 8. 补充发现（写补发脚本时挖出来的）：两个发布脚本会**丢提示词**

我按你提醒的"同 key 覆盖"去写补发脚本时，顺手核了一下**继承源**，发现一个真问题：

`tools/publish_customer_service_config.py` 与 `tools/publish_risk_agent_config.py` 的
`active_config_items()` 都是**自己写 SQL、只查 `platform_config_item`**：

```sql
SELECT i.namespace, i.config_key, i.value_json, i.schema_version
FROM platform_config_item i JOIN config_release r ON r.id = i.release_id
WHERE r.status = 'active'
```

而 `ConfigReleaseService.effective_snapshot()` 的文档字符串写得很清楚 —— 你自己在
`publish_chitchat_prompt.py` 里也引用过这条：

> 快照读的是**全部三张**受管表（`platform_config_item` / `prompt_template_version` /
> `model_routing_rule`），**漏读一张就是一次静默失效** —— 这次的事故正是这么来的。

**⇒ 用这两个脚本发版，会把生效版本里的提示词一起清掉。**（本环境 201 里有 1 条
`customer_service_chitchat` v2。）

而且这个失败**没有任何声音**：`_warn_dropped_items()` 只告警、不阻断激活，Agent 侧
`_chitchat_prompt` 又有逐字段兜底、会回落代码默认值 —— **功能看着正常**，
和 release 174 那次事故一模一样。

**建议**：把这两个脚本的 `active_config_items()` 换成
`ConfigReleaseService(session).effective_snapshot()`。我已经在新的
`tools/publish_profile_tool_whitelist.py` 里这么做了，顺带处理了三个细节，供你参考：

1. **同 key 覆盖**（你已经修了，很好）；
2. **JSON 列必须归一化** —— `SELECT *` 读出来的 `value_json` 可能是**字符串**，
   不 `json.loads` 的话 `isinstance(value, dict)` 为假，脚本会**静默**走到"生效版本里没有
   该 key"那条分支。我第一版就踩了这个，靠加诊断打印才定位到（表现出来像"配置缺失"）；
3. **提示词搬家要重分配 `version`**（唯一键含 version），并按 `PromptPayload` 的 9 个字段
   挑字段 —— 表里的 `checksum`/`created_by`/`created_at` 是服务端生成的不能搬，
   而 `input_schema`/`output_schema` 是 API 收的、漏了就丢。

**时序提醒**：admin 端校验「配置 ⊆ 代码 `allowed_tools`」（`app/service/admin_service.py:219-220`），
所以**画像工具那一版必须在你的代码合并进来之后才能发**，否则必然 422，而报错只有
"配置超出 Agent 工具上限"（看不出是时序问题）。我在脚本里加了前置自检：合并前跑会直接中止
并说明原因，而不是抛出那个费解的校验错。