# session-first 架构回流计划（通用客服平台）

> 状态：架构已回流本仓库；房产垂直能力未移植
> 目标仓库：`E:\workspace\QIWEI-skill`
> 来源：`E:\企微技能包测试\.claude\plugins\qiwei-assistant`（只取架构，不取找房/22问）
> 关联：`docs/specs/bun-training-package-plan.md`

## 回流结果（2026-08-20）

已落地：

- `mcp/src/core/thin-red-lines.js`：通用引擎 + 客服规则（声称已完成动作、无凭据状态断言）
- `sessionFirstMode` / `buildThinPrompt` / `sessionFirstSystemPrompt` / `applyThinRedLines`：接入 `agent-runtime.js`
- 服务层在 session 模式跳过 `verifyResponseQuality`
- `QIWEI_AGENT_CONVERSATION_MODE=session` 写入 `loadAgentConfig`；培训入口默认打开
- `scripts/session-first-smoke-test.js`：断言 session 不改稿、厚路径仍改稿、否定句零误报

未移植：房源搜索、新房网、22 问知识库、销冠话术。厚闸门代码保留为对照，未设 env 时行为不变。

## 1. 为什么需要这份计划

本仓库与那份插件副本已经分叉，且分叉是双向的，不是一边领先一边落后。

| | 本仓库 | 插件副本 |
| --- | --- | --- |
| 产品方向 | 通用客服平台（最近提交「剥离看房经纪人角色」） | 房产垂直（找房、22 问、销冠话术） |
| 对话架构 | 厚闸门单路径 | session-first 薄路径 + 厚路径双轨 |
| `agent-runtime.js` | 51 KB | 244 KB |
| 版本控制 | git | 无 |
| 独有文件 | 87 个 | 56 个 |

培训要演示的是**通用客服平台**形态，因此回流的是**架构**，不是房产能力。房源搜索、新房网对接、22 问知识库、销冠话术一律不进本仓库。

## 2. 核心结论

**session-first 架构本身高度通用，房产耦合集中在两处且可隔离。**

`buildThinPrompt` 全长约 35 行，其中只有一行是房产专用：

```javascript
`房源推荐历史：${JSON.stringify(recommendations)}`
```

其余的知识库检索授权、JSON 输出契约、客户画像、待办、预警、工具结果、会话历史、记忆索引，全部与行业无关。

`thin-red-lines.js` 情况相反：**检测词表几乎全是房产专用**（常州地名、小区名后缀、绿化/学区/采光、在售状态、问过业主），但**豁免机制完全通用**，且那套豁免是踩过误报的坑才总结出来的，属于最值钱的可移植资产。

## 3. 回流清单

### 3.1 要移植（架构层）

| 来源 | 内容 | 规模 |
| --- | --- | --- |
| `agent-runtime.js:3382` | `sessionFirstMode(config)` 开关判定 | 1 个函数 |
| `agent-runtime.js:2954` | `buildPrompt` 入口的薄/厚分支 | 1 行 |
| `agent-runtime.js:3017` | `buildThinPrompt` 方法 | ~35 行，去掉房源一行 |
| `agent-runtime.js:3717` | 回复链上的 `sessionFirst` 分支 | 需对齐本仓库结构 |
| `agent-workbench-service.js:892` | 服务层在 session 模式跳过厚闸门 | ~10 行 |
| `agent-service.js:256` | 读取 `QIWEI_AGENT_CONVERSATION_MODE` | 1 行配置 |
| `thin-red-lines.js` | 通用引擎层（见 3.3） | 约 40% 的文件 |
| `scripts/thick-path-leak-check.js` | 泄漏体检，防止厚逻辑漏回薄路径 | 整个文件，需换基准 |
| `scripts/session-first-smoke-test.js` | session 模式冒烟 | 整个文件，需换用例 |
| `testing/session-loop/` | 新架构验证 loop（10 个 js） | 研发资产，不进分发包 |

接入点总计 6 处加 1 个新模块。本仓库已有 `ClaudeCodeSessionStore` 和 `ClaudeCodeClient`，会话基础设施共通，这是移植量可控的根本原因。

### 3.2 不移植（房产垂直层）

`property-search-service.js`、`xnfang-translator.js`、`xnfang-property-provider.js`、`qiwei-property-match-run.js`、`need-collection-slots.js`、`property-feedback-repository.js`、`knowledge/real-estate/更新版本/`、全部 `sales-champion-*` 与 `property-*` 冒烟、`golden-question-set-smoke-test.js`、`testing/` 下的 listings/personas/question-books fixtures。

### 3.3 需改写（通用化）

**薄红线分两层。** 现在是单文件混合，回流时拆开：

- **引擎层（原样移植）**：`splitSentences`、`sentenceAt`、`adjacentSentenceText`、`pushUnique`、以及全套豁免——`isNegated`（否定语境）、`isQuestionSentence`（疑问句）、`isHedged`（一般/大概）、`isHedgedByConfirm`（我去确认一下）、`isFutureIntent`（回头帮你核实）、`restatedByCustomer`（客户自己说过的）。
- **规则层（重写）**：词表、工具名、字段名按通用客服场景重定义。

三类检测的通用化对应关系：

| 房产版 | 通用客服版 | 可行性 |
| --- | --- | --- |
| `detectClaimedPastAction`（实地看过、问过业主、查了库） | 声称已完成动作但无工具轨迹（已帮您提交、已经发给您、我查过了） | 直接通用，只换词表 |
| `detectListingStatusClaim`（断言在售但没核验） | 断言可核实状态但无凭据（库存有货、审核通过、名额还有） | 结构通用，词表按业务定 |
| `detectUnsourcedQualitativeClaim`（绿化好、学区好） | 无据定性描述 | 词表须按行业配置，默认可留空 |

**`buildThinPrompt` 的房源行改成可插拔槽位**，由业务侧注入领域上下文，通用客服默认不注入。

**记忆模块对接。** 插件副本把 `memoryIndexText`、`memoryRelBase` 内联在 `agent-runtime.js` 里；本仓库有独立的 `agent-memory.js`、`agent-memory-worker.js`。移植时接本仓库的独立模块，不要照搬内联实现。

## 4. 对打包计划的影响

架构切换改变了 Bun 打包的前提，`bun-training-package-plan.md` 需相应改写。

**代码保护的收益下降。** 厚闸门时代值钱的东西在代码里（1500 行 verifier、364 处正则、10 个改稿点），编译能藏住。薄路径把这些拆掉后，能力转移到三处：`knowledge/` 话术、十几行 session 提示词、很薄的红线。而 `knowledge/` 必须明文落盘——模型要用 Read/Glob/Grep 去翻它。**最值钱的话术资产在新架构下天然无法被编译保护。**

**G6 从体验降级升为演示失败。** 原判断是「培训机没装 Claude Code，消息仍进工作台，只是不生成草稿」。薄路径下整个回复能力都在 Claude Code 侧，没有它就是零 Agent 能力。Claude Code 从可选依赖变成命门，必须列入现场硬前置。

**依赖无变化。** 两边 `package.json` 的 dependencies 完全一致，新架构没有引入新 npm 包，打包外置清单只需补新增的本地模块。

## 5. 执行前置条件

1. 插件副本那边的 P2（薄红线补全）与 P0.5（`deriveHumanReviewState` 去厚依赖）跑完并达标
2. 那边的七条验收线全过，尤其是误报率 0 与 session 存活率 1.0
3. 确认定稿快照，此后回流期间不再变更来源

条件 1、2 未满足前不要开始移植，否则拿到的是半成品。本文档记录的行号以调研时刻为准，那边仍在改动，执行时需重新定位。

## 6. 执行顺序

1. 取来源定稿快照，锁定版本
2. 移植薄红线引擎层，配通用客服规则层，补变异测试
3. 移植 `sessionFirstMode` 开关与 `buildThinPrompt`（去房源行、接本仓库记忆模块）
4. 移植服务层跳过逻辑与环境变量读取
5. 移植泄漏体检，基准换成本仓库的厚路径数据
6. 跑本仓库全量 `npm run check` 与 smoke，确认厚路径零回归
7. 更新打包计划文档，重跑 `npm run training:check`
8. 打包并按验收清单冒烟