feat: split group and direct context enhancement

2026-10-09 04:13:17 +08:00 · 2026-09-01 02:06:22 +08:00 · 2026-09-01 02:06:22 +08:00 · 75ebaebf2e
commit 75ebaebf2e
parent 38096d1589
21 changed files with 1423 additions and 873 deletions
--- a/docs/方案/dsh-im-产品价值与演进分析.md
+++ b/docs/方案/dsh-im-产品价值与演进分析.md
@ -194,13 +194,13 @@ HR 机器人
  → 告诉模型希望怎样理解和使用这些事实
 ```

-当前功能方案把“上下文增强”设计为机器人卡片上的设置入口。点击后打开弹窗，从上到下设置三个维度：
+当前功能方案把“上下文增强”设计为机器人卡片上的设置入口。点击后打开弹窗，群聊与私聊各自设置三个维度：

- **在哪些会话中使用**：群聊和私聊两个独立开关，默认均关闭。
- **提供哪些来源事实**：五个字段中默认只选 `senderId`，也可按当前入口增加或取消字段。
- **如何使用这些事实**：增强提示词默认留空，可从问号查看使用说明和示例，也支持一键填入示例或清空。
+- **是否在当前场景使用**：群聊和私聊两个独立开关，默认均关闭。
+- **为当前场景提供哪些来源事实**：每个场景都可从五个字段中选择，默认只选 `senderId`。
+- **当前场景如何使用这些事实**：群聊与私聊各有一份增强提示词，默认留空，可分别查看说明、填入示例或清空。

-群聊与私聊共用字段选择和提示词正文，分别决定是否启用。例如提示词可以是：
+群聊与私聊不共用字段选择或提示词正文。例如群聊提示词可以是：

 ```text
 有 senderId 时用它区分发言人；
@ -208,7 +208,7 @@ HR 机器人
 不要在普通回复中展示 senderId 和 botId。
 ```

-用户只编辑增强提示词正文；非空时，`<dsh_im_source_guidance>` 和 `</dsh_im_source_guidance>` 由 dsh-im 自动添加。清空并保存后不再附加提示词块，也不会自动填入示例；所选来源字段仍按会话开关发送。
+私聊可以另行配置更轻松或更详细的表达策略。用户只编辑各场景的增强提示词正文；非空时，`<dsh_im_source_guidance>` 和 `</dsh_im_source_guidance>` 由 dsh-im 自动添加。清空并保存某一场景后，该场景不再附加提示词块，也不会自动填入示例；另一场景不受影响。

 以当前会话已开启、五个字段全选且均可用、正文非空为例，dsh-im 最终发送：

@ -231,11 +231,11 @@ HR 机器人
 这项扩展已经超出原 Issue“传递五个字段”的最小范围。若实施，应该明确区分：

 - 来源字段语义和真实值由 dsh-im 维护；用户可以选择发送哪些字段，不能手工改写来源事实；
- 增强提示词按机器人保存正文，非空时由插件添加外围标签；首次未配置时保持为空，可选择填入示例；
- 群聊、私聊独立控制启用范围；当前会话类型关闭时，两个增强块都不附加；
+- 增强提示词按机器人、按群聊/私聊场景分别保存正文，非空时由插件添加外围标签；首次未配置时保持为空，可选择填入对应示例；
+- 群聊、私聊分别保存启用开关和来源字段；当前会话类型关闭时，两个增强块都不附加；
 - 所选字段无可用值时省略来源块，提示词为空时省略提示词块；两者都为空则保持原消息；
 - 使用说明属于用户提示词增强，不是系统提示词，也不是完整 Agent Preset；
- 本方案共用一份提示词；若未来需要分场景的不同模板，可以另行扩展，不等同于当前的两个启用开关。
+- 接收消息时只读取其真实会话类型对应的字段和提示词，不允许另一场景的配置串入。

 这让“上下文增强”从一次性的数据附加，进一步成为用户可以明确配置的上下文策略：哪些场景需要增强、提供哪些信息，以及希望模型怎样使用，三者各有独立的选择空间。

--- a/docs/方案/上下文增强-验收记录.md
+++ b/docs/方案/上下文增强-验收记录.md
@ -1,5 +1,7 @@
 # 上下文增强验收记录

+> 本文记录的是 Issue #58 初版（群聊与私聊共用字段和提示词）的历史验收结果。Issue #105 后续将两类会话拆成独立的完整配置，其验收以新版实现与测试为准；本文原始数据不回写改造。
+
 记录日期：2026-08-29。

 当前结论：自动检查、下列界面检查及实际设置保存/回读已通过。十一项真实场景中，8/11 具有主任务独立、完整的三轮证据：Telegram、飞书、微信、企业微信、WhatsApp、Slack、Discord 私聊，以及飞书 DeepSeek大会群聊；原设置均已确认恢复。QQ、钉钉私聊、钉钉指定群聊由用户明确确认已自行测试，并要求本任务不再重复操作。当前没有剩余客户端操作；独立证据与用户确认仍分别记录，不合并称为 11/11 独立通过。本记录不包含账号原始 ID、Session ID、昵称、手机号或私聊正文。
--- a/docs/方案/机器人消息来源元数据注入方案.md
+++ b/docs/方案/机器人消息来源元数据注入方案.md
@ -1,12 +1,12 @@
 # 机器人消息来源元数据注入方案

-> 状态：实施中，九渠道与设置界面已接入，正在完成回归与真实客户端验收
+> 状态：Issue #105 独立群聊/私聊配置已完成，自动化回归与飞书真实客户端验收通过
 >
 > 日期：2026-08-26
 >
-> 更新日期：2026-08-29
+> 更新日期：2026-09-01
 >
-> 关联：[Issue #58](https://github.com/xmanrui/dsh-im/issues/58)、[风险说明](https://github.com/xmanrui/dsh-im/issues/58#issuecomment-5414350619)
+> 关联：[Issue #58](https://github.com/xmanrui/dsh-im/issues/58)、[Issue #105](https://github.com/xmanrui/dsh-im/issues/105)、[风险说明](https://github.com/xmanrui/dsh-im/issues/58#issuecomment-5414350619)

 ## 1. 结论

@ -14,17 +14,17 @@

 > **上下文增强**

-点击按钮打开设置弹窗，按从上到下的顺序提供：
+点击按钮打开设置弹窗，顶部依次展示“私聊”和“群聊”两个 Tab，默认打开私聊，一次只显示当前 Tab 的编辑内容。每个场景都独立提供：

-1. **启用范围**：群聊、私聊两个独立开关，默认均关闭，不再设置一个总开关。
+1. **启用开关**：默认关闭，不再设置总开关。
 2. **来源字段**：从五个元数据字段中选择需要发送的字段，默认只勾选“发送者标识”（`senderId`）。
-3. **增强提示词**：正文默认留空，支持查看说明、填入示例和一键清空；非空时由插件自动包裹 `<dsh_im_source_guidance>` 标签。
+3. **增强提示词**：正文默认留空，支持查看说明、填入当前场景示例和一键清空；非空时由插件自动包裹 `<dsh_im_source_guidance>` 标签。

-字段选择和增强提示词按机器人保存，群聊与私聊共用；两个开关只分别决定对应会话类型是否应用这套配置。
+配置按机器人保存，群聊与私聊的开关、字段和提示词互相独立。消息进入时只选择真实会话类型对应的一套配置。

 方案遵守以下边界：

-1. 配置按机器人独立保存；群聊和私聊开关默认均关闭，已有机器人缺少配置时也按关闭处理。
+1. 配置按机器人、按群聊/私聊场景独立保存；两个开关默认均关闭，已有机器人缺少配置时也按关闭处理。
 2. 只使用平台入站事件和机器人运行时已经携带的数据，不查询联系人、用户资料或其他平台 API。
 3. 不修改 Harness 代码、Harness RPC 或 `session.prompt` 协议。
 4. 不修改系统提示词。当前会话类型开启后，由 dsh-im 插件按所选字段和提示词正文生成增强块，存在内容的块才自动加上成对标签并附加到普通用户消息前。
@ -84,8 +84,8 @@ dsh-im 当前已经按机器人和聊天维护 Harness Session，不同机器人
 ### 3.1 目标

 - 用户可以从每个机器人卡片打开设置，分别决定群聊、私聊是否启用上下文增强。
- 用户可以选择发送五个来源字段中的哪些字段，默认只选 `senderId`；仅发送选中且当前事件中可用的值。
- 通过按机器人自定义的增强提示词说明如何使用来源信息；正文默认留空，支持查看及填入示例和一键清空，非空正文由插件统一封装。
+- 用户可以为群聊和私聊分别选择五个来源字段中的哪些字段，均默认只选 `senderId`；仅发送当前场景选中且当前事件中可用的值。
+- 用户可以为群聊和私聊分别编写如何使用来源信息的增强提示词；正文默认留空，支持查看、填入对应示例和一键清空，非空正文由插件统一封装。
 - 群聊开启且选择发送者字段时，每条普通用户消息使用当次实际发送者的信息。
 - 九个渠道使用同一字段语义、同一设置交互和同一提示词封装格式。
 - 不增加每条消息的额外平台网络请求。
@ -122,35 +122,31 @@ Agent Preset

 ### 4.2 弹窗结构

-弹窗标题为“上下文增强”，包含以下三个设置区域及保存操作：
+弹窗标题为“上下文增强”，包含私聊、群聊两个 Tab、一个复用编辑区及一次保存操作：

 ```text
 上下文增强 [?]                                  [关闭弹窗]

-启用范围
-  群聊中启用（当前渠道不支持群聊）               [关闭]
-  私聊中启用                                    [关闭]
+[ 私聊 ] [ 群聊 ]

-来源字段 [?]
-  [ ] 渠道                  [ ] 会话类型
-      channel                  conversationType
-  [✓] 发送者标识            [ ] 发送者昵称 [?]
-      senderId                 senderName
-  [ ] 机器人标识
-      botId
-
-增强提示词 [?]                     [填入示例] [清空]
-  [多行正文编辑区域，不需要填写外围标签]
-  插件自动添加 <dsh_im_source_guidance> 成对标签。
+  启用                                          [关闭]
+  来源字段 [?]
+    [ ] 渠道                [ ] 会话类型
+    [✓] 发送者标识          [ ] 发送者昵称 [?]
+    [ ] 机器人标识
+  增强提示词 [?]                       [填入示例] [清空]
+    [当前 Tab 的正文编辑区域，不需要填写外围标签]

                                       [取消] [保存]
 ```

+切换 Tab 只切换正在编辑的场景，不保存、不丢弃草稿；两个场景仍由底部“保存”一次原子提交。
+
 标题右侧问号说明：

 > 选择在哪些会话中启用、提供哪些来源字段，以及如何使用这些信息。仅使用已有消息元数据，不查询平台 API。

-“来源字段”右侧问号说明：
+每个场景的“来源字段”右侧问号分别说明：

 > 增强提示词中请使用字段名（如 senderId、conversationType）引用这些信息。只发送勾选且当前消息中可用的字段，不会额外查询或补全。

@ -158,7 +154,7 @@ Agent Preset

 > 该字段不是每个渠道都能提供。当前消息没有发送者昵称时，即使已选择该字段，`<dsh_im_source>` 中也会省略 `senderName`。

-“增强提示词”右侧问号说明中包含：
+每个场景的“增强提示词”右侧问号说明中包含：

 > 只需填写正文，标签由插件自动添加。清空并保存后，不再附加增强提示词，已选来源字段仍按开关设置发送。

@ -166,44 +162,51 @@ Agent Preset

 > 发送者标识可能包含平台用户 ID 或电话号码形式的标识。关闭开关不会删除已经写入会话历史的信息。

-### 4.3 群聊与私聊开关
+### 4.3 群聊与私聊配置

- 两个开关相互独立，分别控制真实 `group` 与 `direct` 会话；不增加总开关。
- 新机器人和缺少配置的已有机器人，两个开关都默认关闭。
- 不论是否把 `conversationType` 发给模型，插件都使用入站事件的真实会话类型选择对应开关。
+- 群聊与私聊各自拥有完整的 `enabled`、`fields`、`guidance` 配置；不增加总开关，也不共享字段或提示词。
+- 新机器人和缺少配置的已有机器人，两个场景均默认关闭、只选 `senderId`、提示词留空。
+- 不论是否把 `conversationType` 发给模型，插件都使用入站事件的真实会话类型选择整套对应配置。
 - 只开启群聊时，私聊消息保持原样；只开启私聊时，群聊消息保持原样。
- 两个开关都关闭时，仍可以预先编辑字段选择和提示词，但不向任何消息附加增强内容。
- 仅支持私聊的渠道仍展示并禁用群聊开关，在“群聊中启用”右侧同行显示“（当前渠道不支持群聊）”，不承诺平台不存在的能力。
+- 两个开关都关闭时，仍可以分别预先编辑字段选择和提示词，但不向任何消息附加增强内容。
+- 仅支持私聊的渠道默认打开私聊 Tab；群聊 Tab 仍可查看，但其编辑区整体禁用并说明“当前渠道不支持群聊”。群聊字段和提示词保留、不被清空。

 ### 4.4 来源字段选择

- 五个字段全部以复选框展示，新配置默认只勾选“发送者标识”（`senderId`）；字段名称与 JSON 键的映射见 5.1 节。
+- 每个场景都展示相同的五个字段复选框，新配置各自默认只勾选“发送者标识”（`senderId`）；字段名称与 JSON 键的映射见 5.1 节。
 - 任意字段都可以取消，不设置强制勾选字段，也不暗中补回未选中的字段。
- 群聊与私聊共用这套字段选择；启用范围和发送字段是两个独立配置维度。
+- 群聊与私聊的字段选择互相独立；只投影当前消息所属场景勾选的字段。
 - 用户只能决定是否发送字段，不能手工修改平台来源值或内部机器人标识。
- 允许全部取消；此时不生成 `<dsh_im_source>` 块，非空增强提示词仍可按会话开关发送。
+- 任一场景允许全部取消；该场景不生成 `<dsh_im_source>` 块，非空增强提示词仍可按该场景开关发送。
 - 选中某字段不保证一定有值。例如仅选择 `senderName`，而本条消息没有昵称时，同样不生成来源块。
 - 字段选择变化不会自动重写用户的增强提示词；模板应按字段是否实际存在使用数据，不应猜测未提供的值。

 ### 4.5 增强提示词、帮助与一键清空

- 编辑项名称为“增强提示词”，群聊与私聊共用一份正文。
- 新配置的正文默认为空；用户可以自行编辑、点击“填入示例”，或点击“清空”。
+- 两个 Tab 内的编辑项都简洁命名为“增强提示词”，各自保存正文；当前场景由选中的“群聊”或“私聊”Tab 明确表达。
+- 两份新配置的正文均默认为空；用户可以分别编辑、点击对应“填入示例”，或点击对应“清空”。
 - 正文为空时，编辑框通过 `placeholder` 灰色展示与“填入示例”相同的示例正文；占位内容不是输入值，不参与保存，也不会生成 guidance 块。
 - 标题右侧显示问号帮助入口，鼠标悬停或键盘聚焦时展示使用说明和简短示例。
- 问号帮助中的“使用示例”与“填入示例”按钮共用同一份正文，不能分别维护两套示例。
+- 每个场景问号帮助中的“使用示例”与本场景“填入示例”按钮共用同一常量；群聊和私聊各维护一份明确的示例。
 - 用户只编辑正文；`<dsh_im_source_guidance>` 和 `</dsh_im_source_guidance>` 由插件在装配消息时自动添加，内置和自定义正文使用同一封装格式。
- “清空”只把当前编辑区置为空，不改变开关和字段选择，也不立即影响正在运行的配置。
+- “清空”只把当前场景编辑区置为空，不改变任一开关和字段选择，不修改另一场景，也不立即影响正在运行的配置。
 - 清空并保存后持久化显式空字符串；刷新、重启或重新开启时仍为空。
 - 正文为空或仅含空白字符时，不附加 guidance 块，也不发送一对空标签；来源块按所选字段独立生成。
- “填入示例”只把当前编辑区填入内置示例，点击“保存”后才生效。
+- “填入示例”只把当前场景编辑区填入对应内置示例，点击“保存”后才生效。
 - 内置示例必须以字段存在为前提提供说明，适应只选部分字段或当前事件缺少字段的情况。

-可一键填入的内置示例正文：
+群聊可一键填入的内置示例正文：

 ```text
 仅依据当前消息的 <dsh_im_source> 中实际提供的字段理解来源；没有提供的字段不要猜测或补全。
-conversationType是群聊时回复严肃一点，conversationType是私聊时回复一定要幽默搞笑，像周星驰的电影一样搞笑
+当前消息来自群聊，请使用严肃、克制、简洁的表达方式。
+```
+
+私聊可一键填入的内置示例正文：
+
+```text
+仅依据当前消息的 <dsh_im_source> 中实际提供的字段理解来源；没有提供的字段不要猜测或补全。
+当前消息来自私聊，可以使用更轻松、幽默、详细的表达方式。
 ```

 ### 4.6 保存与生效
@ -215,7 +218,7 @@ conversationType是群聊时回复严肃一点，conversationType是私聊时回
 - 点击“取消”或关闭弹窗不保存草稿；重新打开时仍显示已保存值。
 - 保存成功后接收的下一条普通用户消息采用新配置；保存前已经接收或入队的消息不追溯修改。
 - 保存不触发机器人重连，不清除 Session，不中断当前回复；刷新页面和重启插件后配置保持。
- 关闭某类会话或全部关闭不会清除字段选择与提示词正文；删除机器人时一并删除全部上下文增强配置。
+- 关闭某类会话或全部关闭不会清除任一场景的字段选择与提示词正文；删除机器人时一并删除全部上下文增强配置。
 - 修改 Workspace、Agent Preset、群响应模式或访问规则不改变本配置。

 ### 4.7 已确认的视觉样式
@ -234,9 +237,10 @@ conversationType是群聊时回复严肃一点，conversationType是私聊时回

 - 使用不透明主题背景、细边框与圆角，背景卡片加遮罩；标题在左上角，标题右侧问号通过悬停或键盘聚焦展示功能说明，关闭图标在右上角。
 - 参考最大宽度 450px、圆角 12px、内边距约 18px；窄屏自适应收缩，保持内容完整可见。
- “启用范围”将群聊、私聊两个独立开关上下排列，每行左侧为名称、右侧为对应开关，避免误解为二选一。
- “来源字段”标题右侧问号展示字段引用、选择和数据补全规则；下方以两列复选框排列，每项同时展示中文名称和可在增强提示词中直接使用的字段名。“发送者昵称”另带可悬停和聚焦的问号，说明字段缺失时的省略行为。五个字段的语义仍以 5.1 节为准。
- “增强提示词”标题左对齐，右邻问号帮助入口；使用说明、生效规则、隐私提示和与“填入示例”共用的示例正文均收纳在帮助框中，并向上展开。“填入示例”和“清空”为右侧轻量文字操作，下方只保留多行编辑区。
+- “私聊”和“群聊”按此顺序使用同一行的两个等宽 Tab，默认选中私聊；一次只展示当前场景的“启用”、来源字段和“增强提示词”，减少纵向空间。选中态沿用现有业务强调色与主题令牌。
+- Tab 支持点击及左右方向键、Home、End 切换，并通过 `tablist`、`tab`、`tabpanel`、`aria-selected` 和关联 ID 提供完整可访问语义。
+- 每个分区的“来源字段”问号都展示字段引用、选择和数据补全规则；下方以两列复选框排列，每项同时展示中文名称和可在提示词中直接使用的字段名。“发送者昵称”另带可悬停和聚焦的问号，说明字段缺失时的省略行为。五个字段的语义仍以 5.1 节为准。
+- 每个分区的增强提示词标题左对齐，右邻问号帮助入口；使用说明、生效规则、隐私提示和对应示例均收纳在帮助框中。“填入示例”和“清空”为右侧轻量文字操作，下方只保留多行编辑区。
 - 底部操作右对齐：“取消”为次级按钮，“保存”为主按钮。

 浅色和深色主题沿用项目配色，不为九个渠道分别定义外观。窄屏下按钮名称和最长状态标签均不可被挤压或截断；触控目标至少 44px，保留键盘焦点提示、弹窗焦点约束、Esc 取消及关闭后返回入口按钮的焦点行为。
@ -255,8 +259,8 @@ conversationType是群聊时回复严肃一点，conversationType是私聊时回

 字段约束：

- 新配置默认只选择 `senderId`，但在最终发送的 JSON 中五个字段均可省略，不把其中任何字段设为强制发送。
- 最终字段集合为“用户已选字段”与“本条消息可用字段”的交集；未勾选的字段不发送，也不以空值或其他位置补回。
+- 群聊和私聊的新配置各自默认只选择 `senderId`，但在最终发送的 JSON 中五个字段均可省略，不把其中任何字段设为强制发送。
+- 最终字段集合为“当前会话场景已选字段”与“本条消息可用字段”的交集；当前场景未勾选的字段不发送，也不从另一场景或其他位置补回。
 - 字段选择只控制发给模型的内容，不删除插件内部用于路由、访问控制和启用范围判断的真实事件信息。
 - 不发送值为 `undefined`、`null` 或空字符串的 `senderName`。
 - 不使用 `senderId` 冒充 `senderName`。
@ -401,35 +405,55 @@ conversationType是群聊时回复严肃一点，conversationType是私聊时回
  "agentPresets": {},
  "contextEnhancement": {
    "telegram_xxx": {
-      "groupEnabled": true,
-      "directEnabled": false,
-      "fields": ["channel", "conversationType", "senderId", "senderName", "botId"],
-      "guidance": ""
+      "group": {
+        "enabled": true,
+        "fields": ["channel", "conversationType", "senderId", "senderName", "botId"],
+        "guidance": "群聊提示词正文"
+      },
+      "direct": {
+        "enabled": false,
+        "fields": ["senderId"],
+        "guidance": "私聊提示词正文"
+      }
    }
  }
 }
 ```

-上例表示仅群聊开启、五个字段全选、增强提示词已经显式清空。缺少某个机器人配置时使用以下默认值：
+上例表示仅群聊开启；群聊和私聊已保存不同的字段与提示词。缺少某个机器人配置时使用以下默认值：

 | 配置项 | 类型 | 默认值与含义 |
 | --- | --- | --- |
-| `groupEnabled` | boolean | `false`，控制群聊 |
-| `directEnabled` | boolean | `false`，控制私聊 |
-| `fields` | 五个字段名组成的数组 | 默认仅选择 `senderId`；显式 `[]` 表示全部取消 |
-| `guidance` | string | 默认为空；非空时保存用户正文或填入的示例正文 |
+| `group` | object | 群聊完整配置 |
+| `direct` | object | 私聊完整配置 |
+| `group.enabled` / `direct.enabled` | boolean | 均为 `false` |
+| `group.fields` / `direct.fields` | 五个字段名组成的数组 | 均默认只选择 `senderId`；显式 `[]` 表示全部取消 |
+| `group.guidance` / `direct.guidance` | string | 均默认为空；非空时保存对应场景的用户正文或示例正文 |

 持久化约束：

- 按机器人保存完整配置，两个开关、字段选择和提示词正文一起更新。
- `guidance` 只保存正文，不保存插件自动添加的外围标签；空白正文可归一化为 `""`。
- `fields: []` 和 `guidance: ""` 都是有效用户选择，不能当作缺失值回退到默认字段或示例正文。
+- 按机器人保存完整配置，`group` 与 `direct` 通过一次原子写入一起更新。
+- 两个 `guidance` 都只保存正文，不保存插件自动添加的外围标签；空白正文可归一化为 `""`。
+- 任一场景的 `fields: []` 和 `guidance: ""` 都是有效用户选择，不能当作缺失值回退到默认字段、另一场景或示例正文。
 - 只允许五个已定义的字段名；去重并按规范顺序保存，不接收任意额外元数据字段。
- 两个开关都关闭时仍保留用户保存的字段和正文，不能以“关闭”为由删除配置。
+- 任一开关关闭时仍保留该场景保存的字段和正文，不能以“关闭”为由删除配置。
 - 配置缺失默认双关闭；配置损坏时安全降级为双关闭，不能因异常自动开启或扩大正在发送的字段范围。

 实现时可以扩展现有 `BotWorkspaceStore` 所承载的机器人设置，但对外语义应保持为通用机器人配置，不能让渠道 Bridge 直接读写配置文件。

+#### 8.1.1 旧配置自动迁移
+
+旧版精确结构 `{ groupEnabled, directEnabled, fields, guidance }` 在升级后按以下规则兼容：
+
+- `groupEnabled` 映射为 `group.enabled`，`directEnabled` 映射为 `direct.enabled`；
+- 旧 `fields` 无损复制到 `group.fields` 与 `direct.fields`；
+- 旧 `guidance` 无损复制到 `group.guidance` 与 `direct.guidance`；
+- 启动加载时只在内存中规范化，不因为读取而改写磁盘；机器人可立即按迁移结果继续运行；
+- 之后任意一次机器人设置成功写入时，复用 `BotWorkspaceStore` 现有原子持久化机制写成新结构，不增加一次性迁移器、版本文件或额外后台任务；
+- 新的保存 RPC 只接受新结构，避免旧、新或混合字段继续写入；结构损坏或混合时安全回退为双关闭默认值。
+
+因此升级本身即可完成运行时迁移，用户无需手工操作；落盘采用惰性迁移，既保留旧配置内容，也避免仅启动或查看设置就产生文件改动。
+
 ### 8.2 Host RPC 与状态

 九个渠道统一增加逻辑等价的设置接口，例如：
@ -444,10 +468,16 @@ bot.context-enhancement.set
 {
  "botId": "telegram_xxx",
  "config": {
-    "groupEnabled": true,
-    "directEnabled": false,
-    "fields": ["channel", "conversationType"],
-    "guidance": ""
+    "group": {
+      "enabled": true,
+      "fields": ["channel", "conversationType"],
+      "guidance": "群聊提示词正文"
+    },
+    "direct": {
+      "enabled": false,
+      "fields": ["senderId"],
+      "guidance": "私聊提示词正文"
+    }
  }
 }
 ```
@ -457,10 +487,16 @@ bot.context-enhancement.set
 ```json
 {
  "contextEnhancement": {
-    "groupEnabled": true,
-    "directEnabled": false,
-    "fields": ["channel", "conversationType"],
-    "guidance": ""
+    "group": {
+      "enabled": true,
+      "fields": ["channel", "conversationType"],
+      "guidance": "群聊提示词正文"
+    },
+    "direct": {
+      "enabled": false,
+      "fields": ["senderId"],
+      "guidance": "私聊提示词正文"
+    }
  }
 }
 ```
@ -469,17 +505,17 @@ bot.context-enhancement.set

 - 保存时校验完整配置，不允许非法类型、未知字段名或超出约定长度的正文进入运行状态。
 - 保存请求失败不部分更新任意字段；成功响应返回实际生效的规范化配置，界面据此更新状态。
- 清空通过提交 `guidance: ""` 表达；填入示例通过提交示例正文表达，不能依赖空字符串回退。
+- 清空通过提交对应场景的 `guidance: ""` 表达；填入示例通过提交对应示例正文表达，不能依赖空字符串回退或影响另一场景。
 - 保存的是 dsh-im 插件配置，不是向 Harness 新增的 RPC 或 `source` 参数。

 ### 8.3 Runtime 与 Bridge

 - 生产装配层把当前机器人 ID 和整套上下文增强配置的读取能力显式传给 Runtime/Bridge。
- 接收消息时取得内存中已提交配置的只读引用，先检查实际会话类型对应的 `groupEnabled` 或 `directEnabled` 是否严格为 `true`；无法可靠判断时按关闭处理。
+- 接收消息时取得内存中已提交配置的只读引用，根据实际会话类型只选择 `group` 或 `direct`，再检查该场景的 `enabled` 是否严格为 `true`；无法可靠判断时按关闭处理。
 - 对应开关未开启时立即跳过增强分支，继续原有链路；不访问或处理增强模板，不执行专用于增强的字段提取、投影、转义、序列化和内容重组。
- 对应开关开启后，后续排队和装配使用接收时的同一完整配置快照，不能混用不同版本的开关、字段和正文。
- 对应开关开启后，从已有元数据中筛选 `fields` 指定的可用字段，再安全序列化并生成非空来源块。
- 根据 `guidance` 是否非空独立生成提示词块，并自动添加成对标签；不因清空正文自动填入示例。
+- 对应开关开启后，立即捕获当前场景的只读配置快照；后续排队和装配只使用这份快照，不能混用另一场景或不同版本的开关、字段和正文。
+- 从已有元数据中筛选当前场景 `fields` 指定的可用字段，再安全序列化并生成非空来源块。
+- 根据当前场景 `guidance` 是否非空生成提示词块，并自动添加成对标签；不回退另一场景，也不因清空正文自动填入示例。
 - 每条消息不读取磁盘，也不调用平台 API。
 - 点击“保存”只产生一次浏览器到本地 Host 的设置 RPC；正常消息仍只有现有的 Harness 提交请求。
 - 不应把这项配置伪装成 Harness 能力或加入 Harness 客户端协议。
@ -489,7 +525,7 @@ bot.context-enhancement.set

 九个渠道应复用：

- 一个机器人卡片设置入口及共享弹窗，包含群聊/私聊双开关、五字段选择、正文编辑、问号帮助、填入示例和清空操作；
+- 一个机器人卡片设置入口及共享弹窗，以两个 Tab 复用同一个场景编辑组件，维护群聊、私聊两份开关、五字段选择、正文编辑、问号帮助、填入示例和清空操作；
 - 一套设置存储和 RPC 行为；
 - 一套会话类型启用判断、字段白名单投影和空内容省略规则；
 - 一个来源数据校验与安全序列化函数；
@ -556,7 +592,7 @@ Agent 或插件不能仅根据来源块：
 - 不改变 Agent Preset 的“只影响后续新 Session”语义。
 - 不改变群聊是否响应、谁可以访问机器人等现有规则。
 - 开启或关闭都不重新创建 Harness Session。
- 插件升级后保留双开关、字段选择和正文，包括显式空字段列表与清空后的正文；机器人删除后不残留孤立配置。
+- 插件升级后按 8.1.1 节自动保留旧双开关，并把旧字段选择和正文分别复制到群聊、私聊，包括显式空字段列表与清空后的正文；机器人删除后不残留孤立配置。

 ### 10.3 曾经开启后的历史边界

@ -569,31 +605,32 @@ Agent 或插件不能仅根据来源块：
 ### 11.1 UI 与配置

 1. 九个渠道的每张机器人卡片都有“上下文增强”按钮，点击打开该机器人的设置弹窗，不直接启停。
-2. 弹窗按顶部双开关、中间五字段选择、底部增强提示词编辑的顺序展示。
-3. 新机器人和缺少该项配置的旧机器人，群聊、私聊开关默认均为关闭，来源字段默认只选 `senderId`，增强提示词默认留空；已有有效保存值保持不变。
-4. 群聊/私聊双开关四种组合均能独立保存，卡片摘要正确；仅支持私聊的渠道明确标注群聊不可用。
-5. 同渠道不同机器人、不同渠道机器人之间的整套配置互不影响。
-6. 取消或关闭弹窗不保存草稿；点击“保存”才原子提交，失败时运行配置不变且草稿仍可重试。
-7. 保存不触发机器人重连、Session 重建或当前回复中断；刷新页面和重启插件后配置保持。
-8. 编辑区只编辑正文；问号可通过悬停或键盘聚焦查看使用说明和示例；“清空”仅清除正文，“填入示例”仅填入示例正文，均不改变字段和开关。
-9. 清空并保存后，刷新、重启、关闭再开启都保持为空，不自动填入示例；空字段列表同样保持为空。
-10. 关闭某类会话保留字段和正文，删除机器人时一并删除全部配置。
-11. 按钮与弹窗符合 4.7 节已确认样式；灰色“未开启”仍可点击，开启后仅状态标签使用强调色。
-12. 浅色/深色主题及 320px、360px、常规桌面宽度下不重叠、不横向溢出，最长状态标签完整显示；键盘和触控均可操作。
+2. 弹窗依次以私聊、群聊两个 Tab 复用一个编辑区，默认打开私聊，一次只显示当前场景；切换后草稿不丢失，每个场景均包含自己的开关、五字段选择和增强提示词编辑。
+3. 新机器人和缺少该项配置的旧机器人，群聊、私聊均默认关闭、各自只选 `senderId`、提示词留空。
+4. 旧版共用配置升级后，两个开关分别保留，字段和提示词无损复制到两个场景；仅加载不改写磁盘，下一次成功写入机器人设置时自动保存为新结构。
+5. 群聊/私聊双开关四种组合均能原子保存，卡片摘要正确；仅支持私聊的渠道明确标注并禁用整个群聊区域，同时保留其数据。
+6. 同渠道不同机器人、不同渠道机器人之间的整套配置互不影响。
+7. 取消或关闭弹窗不保存草稿；点击“保存”才原子提交两套配置，失败时运行配置不变且草稿仍可重试。
+8. 保存不触发机器人重连、Session 重建或当前回复中断；刷新页面和重启插件后配置保持。
+9. 两个编辑区分别提供问号说明与对应示例；任一“清空”或“填入示例”只改变本场景草稿，不改变另一场景、字段或开关。
+10. 任一场景清空并保存后，刷新、重启、关闭再开启都保持为空，不自动填入示例；空字段列表同样保持为空。
+11. 关闭某类会话保留该场景的字段和正文，删除机器人时一并删除全部配置。
+12. 按钮与弹窗符合 4.7 节已确认样式；灰色“未开启”仍可点击，开启后仅状态标签使用强调色。
+13. 浅色/深色主题及 320px、360px、常规桌面宽度下不重叠、不横向溢出，最长状态标签完整显示；键盘和触控均可操作。

 ### 11.2 提示词

 1. 当前会话类型关闭时，文本、图片和文件消息传给 Harness 的内容与当前版本一致，即使另一个会话类型已开启。
-2. 五个字段的全部 32 种选择组合均按白名单投影；未选字段不发送，勾选顺序不影响 JSON 键顺序。
+2. 群聊和私聊各自的五字段选择均按白名单投影；当前场景未选字段不发送，另一场景已选也不能补入，勾选顺序不影响 JSON 键顺序。
 3. 取消 `conversationType` 后，群聊/私聊启用判断仍根据真实事件正确执行，不因字段未发送而失效。
 4. `senderName` 缺失时完全省略；仅选择昵称但无昵称时不发送空来源块，不补查或伪造值。
-5. 正文非空时自动添加完整的 `<dsh_im_source_guidance>` 成对标签；内置模板与自定义模板使用同一规则。
-6. 正文清空或仅含空白时不附加 guidance 块、不回退默认，但来源块仍按字段选择发送。
-7. 字段全部取消且正文非空时只附加 guidance 块；二者都为空时原消息保持不变。
+5. 当前场景正文非空时自动添加完整的 `<dsh_im_source_guidance>` 成对标签；对应内置模板与自定义模板使用同一规则，另一场景正文不得出现。
+6. 当前场景正文清空或仅含空白时不附加 guidance 块，不回退默认或另一场景；来源块仍按当前场景字段选择发送。
+7. 当前场景字段全部取消且正文非空时只附加 guidance 块；二者都为空时原消息保持不变，另一场景配置不参与。
 8. 多模态消息只在有增强内容时增加一个前置文本项，不生成空项；文件清单、图片和文件内容保持原有顺序与内容。
 9. 插件本地命令、Harness 控制交互和被过滤消息不附加任何增强块。
 10. 同名标签出现在模板正文中不能破坏外围封装；插件每次最多附加一个来源块和一个提示词块，不改变用户原文。
-11. 每条消息使用接收时已提交的同一配置快照；关闭后只影响后续消息，现有 Session 和历史不变。
+11. 每条消息使用接收时已提交的当前场景配置快照；群聊提示词和字段不得出现在私聊，私聊提示词和字段不得出现在群聊；关闭后只影响后续消息，现有 Session 和历史不变。

 ### 11.3 九渠道与网络边界

@ -602,7 +639,7 @@ Agent 或插件不能仅根据来源块：
 3. 企业微信、微信、飞书、Slack 验证不会为昵称发起补查。
 4. 测试应断言普通消息处理没有新增平台 API 调用。
 5. 群聊连续由不同用户发言时，选中的 `senderId` 和可用昵称正确变化；未选发送者字段时不附加这些字段。
-6. 同时开启多个机器人时，各自的双开关、所选字段、可选 `botId` 和提示词正文正确，不串用配置。
+6. 同时开启多个机器人时，各机器人、各会话场景的开关、所选字段、可选 `botId` 和提示词正文正确，不串用配置。

 ### 11.4 安全与异常

@ -627,12 +664,12 @@ Agent 或插件不能仅根据来源块：

 ## 12. 建议实施顺序

-1. 增加公共配置字段、迁移兼容、状态投影和设置 RPC。
-2. 增加双开关判断、字段选择投影、空正文规则、安全序列化和提示词装配函数。
+1. 把公共配置改为 `group`、`direct` 两个同构对象，复用现有设置存储增加惰性迁移、状态投影和设置 RPC 校验。
+2. 按真实会话类型选择一套配置，继续复用现有字段投影、空正文规则、安全序列化和提示词装配函数。
 3. 为九个渠道补齐入站事件字段提取，保留事件中已经存在但当前被丢弃的昵称。
 4. 在共享 `TextHarnessBridge` 和五个独立 Bridge 中接入统一装配函数。
-5. 增加共享机器人卡片设置入口与弹窗，接入双开关、字段选择、正文编辑、清空及保存，并覆盖九渠道卡片。
-6. 完成公共契约测试、九渠道 Fixture 测试、UI 测试和不新增平台请求的回归测试；11.5 节关闭状态对照回归必须全部通过。
-7. 在至少一个私聊渠道和一个群聊渠道进行真实客户端验收，再逐步覆盖九渠道。
+5. 复用一个场景编辑组件，在现有共享弹窗通过两个 Tab 切换群聊和私聊配置；保留原子保存、草稿、帮助、清空与九渠道入口。
+6. 完成新旧配置契约、群聊/私聊互不泄漏、九渠道 Fixture、UI 和不新增平台请求的回归测试；11.5 节关闭状态对照回归必须全部通过。
+7. 使用同一个飞书机器人分别进行私聊与指定群聊真实验收，并在结束后恢复测试前配置。

 整个实施过程中，Harness 代码和 Harness 协议保持不变。