0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
421 lines
10 KiB
Markdown
421 lines
10 KiB
Markdown
# 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`
|
||
- 后续同一会话继续发送消息时不重复注入
|
||
|
||
### 建议包装格式
|
||
|
||
```text
|
||
[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 产品化推进方向的高杠杆路径。
|