# ZCLAW 新会话提示词后续工作计划 ## 一、目标 围绕 ZCLAW 的“新会话提示词”能力，完成一条从 **真实 Agent 配置** 到 **真实会话初始化行为** 的可交付链路。 这项能力的目标不是增加一个前端文本框，而是让用户可以： - 为当前 Agent 设置默认的新会话提示词 - 在开启某个新会话时临时覆盖这段提示词 - 让提示词真实影响本次会话第一轮 Agent 行为 - 让该能力在快速配置、右侧 Agent 面板、聊天区之间语义一致 --- ## 二、当前已确认基础 以下基础能力已经打通，可作为本轮工作的前提： - Gateway 连接稳定可用 - token 注入、自动连接、Control UI 握手已修好 - `zclaw-ui` 插件已加载 - `zclaw.clones.list`、`zclaw.plugins.status` 可用 - Agent 创建、右侧 Agent 面板编辑、保存回刷已验证通过 - 快速配置应视为创建/更新 OpenClaw 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 / OpenClaw 演进升级为结构化原生协议。 --- ## 五、目标能力定义 ### 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` - 后续同一会话继续发送消息时不重复注入 ### 建议包装格式 ```text [ZCLAW_NEW_SESSION_PROMPT] [/ZCLAW_NEW_SESSION_PROMPT] [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 还未完全映射到 OpenClaw runtime agent 影响： - 即使 Agent Profile 已切换，底层仍可能没有原生 agent routing 处理： - 本轮先用“首轮消息注入”保证真实行为变化 - 后续把 `agentId` 传输与 runtime routing 作为独立里程碑推进 ### 风险 2：提示词注入格式可能影响回答质量 影响： - 包装格式不佳时，可能让模型输出不稳定 处理： - 采用清晰、边界明确的包裹格式 - 在真实模型上做几组样例测试 ### 风险 3：会话切换与持久化逻辑容易变脆 影响： - 草稿、历史会话、当前会话三者状态可能串扰 处理： - 优先把 store 状态边界设计清楚 - 先覆盖核心状态迁移测试，再做 UI 微调 --- ## 十、完成定义 当以下条件同时满足时，可视为“新会话提示词”能力第一阶段完成： - Agent 默认新会话提示词可创建、编辑、保存、回刷 - 新会话开始前用户可临时覆盖该提示词 - 首轮真实发送到 Gateway 的消息中包含该提示词上下文 - 同一会话后续消息不重复注入 - 历史会话可以恢复其实际使用过的提示词信息 - 快速配置、右侧 Agent 面板、聊天区三处语义一致 --- ## 十一、下一步建议 在本计划落地后，建议立即开始： - **P1：先补数据模型与插件透传** - **P2：再补 chatStore 的会话级状态模型** - **P3：最后接入首轮消息注入并做联调验证** 这会以最小改动建立一条真正可用的闭环，也是当前最符合 ZCLAW 产品化推进方向的高杠杆路径。