zclaw_openfang/docs/plans/new-session-prompt-roadmap.md

ZCLAW 新会话提示词后续工作计划

一、目标

围绕 ZCLAW 的“新会话提示词”能力，完成一条从 真实 Agent 配置 到 真实会话初始化行为 的可交付链路。

这项能力的目标不是增加一个前端文本框，而是让用户可以：

• 为当前 Agent 设置默认的新会话提示词
• 在开启某个新会话时临时覆盖这段提示词
• 让提示词真实影响本次会话第一轮 Agent 行为
• 让该能力在快速配置、右侧 Agent 面板、聊天区之间语义一致

---

二、当前已确认基础

以下基础能力已经打通，可作为本轮工作的前提：

• Gateway 连接稳定可用
• token 注入、自动连接、Control UI 握手已修好
• zclaw-ui 插件已加载
• zclaw.clones.list、zclaw.plugins.status 可用
• Agent 创建、右侧 Agent 面板编辑、保存回刷已验证通过
• 快速配置应视为创建/更新 ZCLAW Agent
• 右侧 Agent 面板已经是当前 Agent 配置的真实编辑入口

这意味着“新会话提示词”应该优先挂在 Agent Profile 真实配置链路 上，而不是再创建一套独立的本地状态。

---

三、问题定义

当前“新对话”链路还存在几个明显缺口：

3.1 会话初始化仍是本地 UI 行为

现状：

• chatStore.newConversation() 只清空本地消息与 sessionKey
• 首次发送时才临时生成 sessionKey
• 当前没有“会话初始化参数”的明确模型

影响：

• 新会话无法承载独立初始化上下文
• 会话开场行为不可控、不可审计

3.2 Agent 配置与新会话行为未打通

现状：

• Agent 已有真实配置入口
• 但聊天区不会消费“新会话默认提示词”这一能力

影响：

• Agent 身份和会话起始行为割裂
• 用户改了 Agent，不一定影响新会话

3.3 当前没有原生会话初始化协议

现状：

• 当前 Gateway agent 请求只传 message / sessionKey / model
• 尚未形成 sessionInit、agentId、conversationContext 等结构化初始化协议

影响：

• 若不做桥接，“新会话提示词”很难真实生效

---

四、设计原则

4.1 必须改变真实运行行为

验收标准不是“页面上能输入”，而是：

• 第一条发给 Gateway 的真实消息已经体现新会话提示词
• 不同会话可以有不同初始化上下文
• 会话恢复后能够看出本会话使用过什么提示词

4.2 必须依附真实 Agent 配置链路

能力入口必须统一在以下两处：

• 快速配置创建 Agent
• 右侧 Agent 面板编辑当前 Agent

不新增与 Agent 平行、脱节的新设置体系。

4.3 先做最小真实闭环，再继续原生化

本轮优先实现：

• Agent 级默认 newSessionPrompt
• 会话级 sessionPromptDraft
• 首轮消息注入

后续再根据 Gateway / ZCLAW 演进升级为结构化原生协议。

---

五、目标能力定义

5.1 Agent 级默认提示词

语义：

• 某个 Agent 在每次开始新会话时默认携带的启动上下文
• 属于 Agent Profile 的一部分
• 可以由快速配置或右侧 Agent 面板编辑

建议字段：

• newSessionPrompt?: string

5.2 会话级临时覆盖

语义：

• 仅对本次新会话生效
• 发出第一条用户消息前可编辑
• 发出后固化到会话元数据中，不应在后续回合反复注入

建议字段：

• sessionPromptDraft: string
• conversation.sessionPrompt?: string | null

5.3 首轮运行时注入

语义：

• 前端保留原始用户输入展示
• 发送给 Gateway 的第一条消息在内部包装为“新会话提示词 + 原始用户问题”
• 从而让提示词立即影响真实模型行为

---

六、实施阶段拆分

Phase 1：数据模型与 RPC 链路补齐

目标

让“新会话提示词”成为真实 Agent 数据结构的一部分。

涉及位置

• plugins/zclaw-ui/index.ts
• desktop/src/store/gatewayStore.ts
• desktop/src/store/chatStore.ts
• desktop/src/components/CloneManager.tsx
• desktop/src/components/RightPanel.tsx

具体任务

• 插件层 CloneConfig 增加 newSessionPrompt
• zclaw.clones.create/update/list 全链路透传该字段
• 前端 Clone、快速配置草稿、右侧面板草稿模型补齐字段
• 保证创建后、编辑后、刷新后都能回刷正确数据

交付物

• Agent Profile 可持久化 newSessionPrompt
• UI 能读取并展示该字段

验收标准

• 创建 Agent 时可设置默认新会话提示词
• 右侧 Agent 面板可编辑并保存该字段
• 重新连接或刷新后字段仍存在

---

Phase 2：聊天会话模型扩展

目标

为“新会话提示词”建立真正的会话级承载结构。

具体任务

• chatStore 增加 sessionPromptDraft
• Conversation 增加 sessionPrompt、agentId
• newConversation() 时重置当前会话的提示词草稿
• 当切换 Agent 且当前尚未开始聊天时，提示词草稿应回填为当前 Agent 默认值
• 切换到历史会话时，恢复该会话使用过的 sessionPrompt

交付物

• 会话层面拥有独立的提示词状态
• 会话与 Agent 的关系更清晰

验收标准

• 新会话默认读取当前 Agent 的默认提示词
• 修改草稿只影响当前新会话，不污染其他历史会话
• 切回历史会话时能恢复对应提示词信息

---

Phase 3：首轮消息注入，打通真实运行行为

目标

让“新会话提示词”真正影响 Gateway 收到的第一条消息。

具体任务

• 在 chatStore.sendMessage() 判断当前是否为该会话首轮用户消息
• 若有有效 sessionPromptDraft，则构造包装后的发送内容
• UI 中仍展示用户原始输入，不暴露包装结构
• 首轮发出后，将实际使用过的提示词固化到当前 Conversation
• 后续同一会话继续发送消息时不重复注入

建议包装格式

[ZCLAW_NEW_SESSION_PROMPT]
<session prompt>
[/ZCLAW_NEW_SESSION_PROMPT]

[USER_MESSAGE]
<original user message>
[/USER_MESSAGE]

交付物

• 新会话提示词真正进入第一轮 Gateway 请求
• 该能力不再是展示层占位

验收标准

• 第一轮消息有提示词时，模型行为明显受影响
• 第二轮起不再重复注入
• 无提示词时发送链路与当前一致

---

Phase 4：交互与可见性优化

目标

让用户知道“当前会话将以什么上下文启动”，同时避免界面复杂度失控。

具体任务

• 在聊天区空态增加“新会话提示词”输入区
• 提供简洁说明文案，明确这是“仅本次会话”的覆盖入口
• 在右侧 Agent 面板非编辑态显示默认新会话提示词摘要
• 在历史会话列表或会话详情中，保留轻量提示，帮助用户理解该会话的启动上下文

交付物

• 新会话前可见、可改、可理解
• Agent 默认值与会话覆盖值关系明确

验收标准

• 用户能区分“Agent 默认值”和“当前会话覆盖值”
• 用户不会误以为这是长期人格或全局系统提示词

---

Phase 5：质量保障与回归验证

目标

确保能力上线后不会破坏现有已打通链路。

测试范围

• Agent 创建后默认提示词可保存
• 右侧 Agent 面板编辑提示词可回刷
• 新会话读取默认值
• 新会话覆盖值只作用于当前会话
• 首轮消息注入只发生一次
• 切换历史会话后元数据恢复正确
• 无提示词情况下原有发送链路不回归

建议验证方式

• Store 层单元测试
• 关键组件交互测试
• 手工联调验证 Gateway 请求行为

交付物

• 至少覆盖核心 store 行为的测试
• 一份人工回归清单

验收标准

• 核心交互不回归
• 会话状态与 Agent 状态一致性可验证

---

七、推荐执行顺序

建议按以下顺序推进，避免前后反复返工：

第一步

先做 Phase 1。

原因：

• 没有真实字段，就谈不上后续真实会话能力
• 这一步风险最低，收益明确

第二步

做 Phase 2。

原因：

• 会话级草稿与历史恢复能力是首轮注入的前提

第三步

做 Phase 3。

原因：

• 这是从“有配置”到“真生效”的关键跃迁
• 也是这轮工作的核心里程碑

第四步

补 Phase 4 + Phase 5。

原因：

• 在核心链路稳定后，再做可见性和质量封口最合适

---

八、本轮建议的最小可交付版本

如果本轮只做一个最小但高价值版本，建议交付以下内容：

• 插件与前端数据模型支持 newSessionPrompt
• 快速配置与右侧 Agent 面板都可编辑该字段
• 聊天区空态可查看/修改当前新会话提示词
• 首轮消息自动注入该提示词
• 会话中记录本次实际使用的提示词

这版已经满足：

• 有真实配置入口
• 有真实运行时行为
• 有会话级语义
• 能被用户实际使用

---

九、主要风险与处理策略

风险 1：当前 selected Agent 还未完全映射到 ZCLAW runtime agent

影响：

• 即使 Agent Profile 已切换，底层仍可能没有原生 agent routing

处理：

• 本轮先用“首轮消息注入”保证真实行为变化
• 后续把 agentId 传输与 runtime routing 作为独立里程碑推进

风险 2：提示词注入格式可能影响回答质量

影响：

• 包装格式不佳时，可能让模型输出不稳定

处理：

• 采用清晰、边界明确的包裹格式
• 在真实模型上做几组样例测试

风险 3：会话切换与持久化逻辑容易变脆

影响：

• 草稿、历史会话、当前会话三者状态可能串扰

处理：

• 优先把 store 状态边界设计清楚
• 先覆盖核心状态迁移测试，再做 UI 微调

---

十、完成定义

当以下条件同时满足时，可视为“新会话提示词”能力第一阶段完成：

• Agent 默认新会话提示词可创建、编辑、保存、回刷
• 新会话开始前用户可临时覆盖该提示词
• 首轮真实发送到 Gateway 的消息中包含该提示词上下文
• 同一会话后续消息不重复注入
• 历史会话可以恢复其实际使用过的提示词信息
• 快速配置、右侧 Agent 面板、聊天区三处语义一致

---

十一、下一步建议

在本计划落地后，建议立即开始：

• P1：先补数据模型与插件透传
• P2：再补 chatStore 的会话级状态模型
• P3：最后接入首轮消息注入并做联调验证

这会以最小改动建立一条真正可用的闭环，也是当前最符合 ZCLAW 产品化推进方向的高杠杆路径。