QIWEI-skill/docs/specs/session-first-port-plan.md

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 行，其中只有一行是房产专用：

`房源推荐历史：${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. 打包并按验收清单冒烟