会话与消息

会话操作

• 新建会话
• 搜索会话
• 重命名会话
• 置顶会话
• 删除会话
• 会话运行状态隔离（每个会话独立管理）
• 会话模型选择（每个会话可独立选择模型）

会话模型选择

每个会话可独立选择使用的模型：

• 在聊天输入区域上方点击模型下拉菜单选择模型
• 切换模型时自动保存到当前会话
• 不同会话可使用不同的模型，满足不同任务需求
• 新建会话默认使用项目上次选择的模型或默认模型

适用场景：

• 复杂推理任务选择高性能模型
• 简单对话选择快速模型节省成本
• 不同主题会话使用最适合的模型

置顶会话

将重要会话置顶可以使其始终显示在会话列表顶部：

• 点击会话标题右侧的图钉按钮可切换置顶状态
• 已置顶的会话显示实心图钉图标
• 未置顶的会话在悬停时显示空心图钉图标
• 置顶的会话会排在列表最前面，便于快速访问

消息交互

• 在输入框发送问题
• 系统以流式方式返回回答
• 会话执行中，发送按钮会切换为"停止"按钮
• 点击"停止"会中断当前会话正在运行的对话与 Agent 执行
• 系统可流式返回 thinking 内容（若模型输出）
• Agent 工具调用会显示为 tool 消息（开始/结束/结果状态）
• 已安装 agent 也会作为工具暴露给模型；命中后会创建 agent ticket，而不是直接在聊天回合里同步执行
• 历史消息按会话保存

快捷命令

输入 / 会自动弹出快捷命令列表：

• 选择 compact 执行上下文压缩
• 选择 skill:<name> 调用已安装的 Skill
• 可直接输入命令名称快速筛选

消息操作

• 每条消息右侧显示复制按钮，点击可复制消息内容
• 长工具结果会自动折叠，点击可展开查看完整内容
• 工具消息显示执行状态指示器（运行中/成功/失败）

多步骤任务进度

当助手处理非一次性回答的复杂任务时，会自动维护当前会话的任务进度：

• 进度面板会显示简短步骤，以及 pending、in_progress、completed 三种状态
• 已完成步骤会划线显示，正在执行的步骤会显示旋转状态图标
• 进度只属于当前会话和当前分支；编辑历史消息生成新分支后，新分支可以拥有自己的进度
• 简单问答通常不会显示进度面板，避免打扰正常聊天

适用场景：

• 多文件修改、批量排查、长时间数据处理
• 先规划、再逐步执行、最后验证的工作
• 需要离开页面后再回来确认任务推进到哪一步

工具输出流式展示

长时间运行的工具调用现在会把输出持续写回聊天区：

• bash 等命令执行时，可在工具卡片中看到逐步产生的输出
• 工具结束后，卡片会保留成功、失败或中断状态
• 输出很长时仍会折叠，展开后可以查看详细日志
• 点击 停止 会尽量中断当前会话中的后台执行，并释放正在占用的执行锁或临时资源

这对安装依赖、运行测试、执行数据分析脚本等耗时任务尤其有用。

断线自动重连

聊天消息流、Agent 任务流和容器状态流支持自动重连：

• 浏览器网络短暂断开、标签页休眠或服务端连接被关闭后，前端会自动重新订阅
• 重连后会继续接收后续事件，并尽量补齐当前会话状态
• 如果任务已经完成，页面会显示最终状态；如果任务失败，错误信息会保留在对应卡片中

如果长时间没有恢复，可以手动刷新页面；已持久化的消息和任务状态不会因为刷新丢失。

计划模式

每个会话都可以在普通聊天模式和 Plan 模式之间切换：

• 在输入框附近的模式菜单中选择 Plan
• 计划模式只影响当前会话，不会改变项目或其他会话
• 在计划模式下，助手会优先产出一份结构化执行计划，而不是直接修改文件或执行任务
• 计划生成后，聊天区会显示 Proposed Plan 卡片
• 点击 Implement plan 会退出计划模式，并把该计划作为下一轮实施依据继续执行
• 点击 Keep planning 可以留在计划模式中继续补充约束、调整步骤或比较方案

适用场景：

• 需求还不够明确，需要先审方案再动手
• 代码修改、数据处理或外部工具调用风险较高
• 你希望先得到可沟通的步骤清单，再让助手执行

助手反问与结构化问题

当助手需要你的选择、参数或确认才能继续时，会通过 ask_user_question 工具发起结构化提问：

• 问题卡片显示在输入框上方；待回答时，普通输入会暂时锁定
• 一次最多显示 3 个问题，可在问题标签间切换
• 问题可以包含选项、可选自定义答案，以及文献/候选资料卡片
• 必填问题全部回答后，点击 Submit，系统会把答案送回当前会话并继续执行
• 如果本次提问不再需要，可以点击关闭按钮拒绝请求

适用场景：

• 在多个分析路线、文件、候选文献或参数之间做选择
• 让助手在执行前确认高层决策，而不是自行猜测
• 外部通道或较长任务中断后，回到项目页面补充必要信息

回答可靠性

系统提示会要求助手避免编造未确认的信息：

• 信息不足时，助手应说明不确定点，而不是把推测写成事实
• 需要用户决策时，优先通过结构化问题向你确认
• 需要最新事实、价格、政策或外部资料时，应使用已启用的搜索或外部工具，或明确说明当前无法验证
• 对文献、数据和文件内容的引用应基于实际可见上下文或工具结果

输入框 @ 文件搜索

聊天输入框支持直接通过 @ 检索当前项目文件并附加到消息：

• 输入 @ 后继续键入关键词，会出现文件搜索面板
• 搜索结果来自当前项目文件，选择后会作为消息附件加入，而不是把文件名硬编码进正文
• 支持键盘上下方向键切换候选项，按回车确认
• 如果只输入 @ 不继续键入关键词，系统只显示提示，不会立即展开完整文件列表

这个入口适合在长会话中快速补充某个文件上下文，省去切到文件树再插入的步骤。

文件引用复制与粘贴

输入框中的文件标签支持富文本复制和粘贴：

• 从用户消息或输入框复制含文件标签的内容，再粘贴回输入框时，会尽量恢复为可发送的文件引用
• 粘贴到普通文本编辑器时，会退化为可读的文件名或路径文本
• 如果引用的文件已删除、当前项目不可访问，或浏览器不支持富文本剪贴板，系统会按普通文本处理

这适合把一轮对话里的文件上下文复用到另一轮问题中，不需要重新搜索每个文件。

工作区文件路径链接

助手回复或工具输出中的项目工作区文件路径会自动识别为可点击链接：

• 支持 /workspace/...、相对路径、裸文件路径和常见 file:// 形式
• 只会把可解析到具体文件的路径转为链接，目录路径不会被误当作文件打开
• 如果多个同名文件造成歧义，建议让助手输出更完整的相对路径

点击链接会打开文件预览或定位到对应项目文件，便于从日志、测试输出或助手总结中快速跳转。

消息修改与分支

你可以直接修改历史中的用户消息，系统会基于修改后的内容重新生成一条新的对话分支：

• 将鼠标移到可编辑的用户消息上，点击右侧的编辑按钮
• 只有项目可写、且当前会话未在运行时，才会显示编辑入口
• 编辑完成后，系统会用新的内容重新发送这条消息，并从这条消息开始生成新分支
• 原有对话分支会保留，不会被覆盖
• 当同一条消息存在多个版本时，消息右侧会出现 上一版 / 下一版 切换按钮
• 切换版本后，当前会话会加载对应分支下的后续消息，方便对比不同修改结果

使用建议：

• 修改提示词、补充上下文或纠正输入错误时，优先直接编辑历史消息
• 如果你想保留多个尝试结果，可以先生成一个新分支，再分别沿不同版本继续对话
• 编辑后的分支适合做问题排查、方案对比和多轮试错，不需要手工复制整段历史内容

消息导出

对于 Assistant 消息（非用户消息、非工具消息），系统提供两种导出方式：

1. 下载到本地：点击消息右侧的下载按钮，选择"下载到本地"，将消息内容保存为 Markdown 文件（.md）到您的设备
2. 保存到工作区：点击下载按钮，选择"保存到工作区"，将消息保存到项目的工作目录中，便于 Agent 后续读取或进一步处理

导出的文件名格式为 chat-message-assistant-{时间戳}.md，其中时间戳来自消息创建时间。

使用场景：

• 在执行上下文压缩前导出重要消息，避免压缩后丢失细节
• 保存有价值的回复内容到工作区，作为后续任务参考
• 下载关键对话到本地设备，用于报告或归档

消息锚点导航

当会话较长时，消息区右侧会显示一条纵向锚点导航：

• 每个锚点对应一条用户消息，压缩节点也会单独显示
• 当前视口附近的锚点会高亮，帮助判断自己正浏览到哪一轮上下文
• 点击锚点可快速跳转到对应消息位置

适用场景：

• 在长排查会话中快速回到某一轮关键提问
• 在上下文压缩后定位压缩前后的分界点

上下文压缩

功能说明

当会话历史较长时，上下文窗口可能接近或超出模型的限制。压缩功能通过生成对话摘要，将早期对话内容压缩为一个检查点，释放上下文空间，同时保留关键信息。

触发方式

手动压缩

在输入框输入 /compact，或输入 / 后从快捷命令列表中选择 compact。

你可以附加自定义指令：

/compact 请重点关注代码修改记录

系统会将你的指令传递给摘要模型，引导其关注特定内容。

自动溢出压缩

当模型 API 返回上下文溢出错误时，系统会自动触发压缩：

• 检测到「上下文长度超限」等错误后，自动对历史对话生成摘要
• 压缩完成后自动重试原请求
• 整个过程对用户透明，无需手动干预

预防性压缩（Pre-turn）

管理员可以在模型配置中设置「预防性压缩阈值」（如 0.8 表示 80%）：

• 当上下文使用量超过阈值时，系统会在发送消息前自动压缩
• 避免等待 API 报错后再压缩，提供更流畅的用户体验
• 压缩完成后会显示提示信息，然后继续执行原请求

配置方式（管理员）：

1. 进入「模型管理」页面
2. 编辑模型配置
3. 设置「预防性压缩阈值」（0-1 之间，如 0.8 表示 80%）
4. 留空或设为 0 表示禁用预防性压缩

压缩结果

压缩成功后，会话中会出现一条带 Context Compressed 标识的消息卡片：

• 这条消息保存的是压缩后的摘要检查点
• 后续提问只会从「最近一次压缩摘要 + 压缩后的新增对话」继续回放
• 如果当前还没有可压缩的历史内容，系统会返回 Nothing to compact yet.

技术细节

使用建议

1. 阶段性压缩：在较长的规划、排查或实现阶段结束后执行一次 /compact，缩短后续上下文
2. 关联任务延续：如果希望后续问答继续基于这份摘要，就在当前会话里继续提问
3. 新任务独立会话：如果下一步任务已与之前无关，建议新建会话，避免历史干扰
4. 生物医学场景：压缩时会尽可能保留文献标识符（PMID、DOI 等）、实验步骤序列和关键决策理由

上下文使用量监测

系统会实时监测并显示当前会话的上下文使用情况：

• 环形指示器显示当前使用比例
• 点击可查看详细统计：当前 tokens、峰值 tokens、剩余空间
• 当使用量接近上下文窗口上限时，建议主动执行 /compact

注意事项

• 压缩是不可逆操作，摘要后原始对话细节可能丢失
• 建议在重要决策节点后再压缩，而非频繁压缩
• 如需完整保留对话历史，可在压缩前导出会话

中途检查点

对于包含多次工具调用的长回合，系统可以在中途保存工具结果检查点：

• 当上下文接近模型限制时，系统会基于已完成工具结果做压缩，再继续后续工具调用
• 已保存的工具结束消息会保留在会话历史里，避免刷新后只看到“运行中”
• 如果后台执行被中断或超时，状态控制器会尽量把长时间停留在运行中的工具修正为明确的结束状态

这项能力主要提升长任务稳定性，通常不需要用户手动操作。

运行控制（新增）

• 停止操作仅作用于当前会话，不会影响其他会话
• 若同时有多个会话在运行，停止其中一个不会中断其余会话
• 停止后，已生成并持久化的消息会保留在当前会话历史中
• 对于 Agent 的 docker 工具调用，停止会同步触发中断，避免继续占用执行资源

Agent

当前聊天链路不再先做单独的"agent 意图识别 JSON 步骤"，而是直接在主对话中使用工具调用：

• 已安装的每个 agent 会暴露为一个独立 tool
• 只有当前项目已安装、且依赖完整的 agent 才会进入工具列表
• agent tool 调用后会创建 agent ticket，并在消息区显示 agent 执行卡片
• agent 卡片会显示：
  • 具体 agent
  • 每个步骤调用了哪个 action
  • 每个步骤的参数
  • 失败原因（包括 docker action 失败原因）

多 Agent 并发执行

每个会话轮次支持同时触发多个 Agent 任务：

• 系统自动协调多个并发 Agent 的执行顺序
• 当多个 Agent 同时被触发时，会显示确认队列供用户逐个审批
• 每个 Agent 的执行状态和结果独立展示

会话继续

Agent 票据执行完成后，可在原会话中继续对话：

• Agent 执行结果会自动添加到会话历史
• 后续对话可引用 Agent 的输出结果
• 保持完整的上下文连续性

模型选择

• 每条消息可使用当前选中的模型发送
• 若项目未保存历史选择，系统会自动选中模型列表中的第一项

Agent 工具（当前）

当前聊天 Agent 内置以下工具：

• read：读取项目工作目录中的文件内容
• find：按 glob 模式搜索文件路径，只读
• grep：按关键字或正则搜索文件内容，只读
• ls：列出目录内容，只读
• bash：在项目工作目录中执行命令
• edit：对文件做精确文本修改
• write：创建或覆盖文件
• web_search：通过网络搜索获取实时信息（配置详见 网络搜索）

补充说明：

• find、grep、ls 属于只读工具，主要用于检索与浏览项目工作区内容，不会直接修改文件
• 当 Agent 在容器环境中调用这些工具时，优先使用项目工作区路径，例如 /workspace/src、/workspace/.agent
• 系统会自动把这类只读工具的 /workspace/... 路径映射到实际项目目录，因此同一个会话在不同执行环境下看到的目录结构和搜索范围应保持一致
• get_agent_task_result：加载已完成的 Agent 任务结果（手动确认模式下自动可用）

Read 工具图片预览

当 Agent 使用 read 工具读取图片文件时，聊天界面会自动显示图片预览：

• 支持格式：PNG、JPG、JPEG、GIF、WebP、SVG、BMP
• 预览区域显示在工具消息卡片中
• 如果图片加载失败，会显示相应的错误提示
• 图片路径会自动处理容器内外路径差异（如 /workspace/ 前缀）

补充说明：

• 工具执行状态会以 tool 消息流式展示（开始/结束/成功或失败）
• /skill:<name> 不是独立工具；它会展开为指令，再由上述工具执行
• 这些工具的工作目录是当前项目的本地 workspace，不是代码仓库根目录
• docker 形态下，工具在容器内看到的工作目录是 /workspace
• agent 不再通过系统提示额外注入目录说明，而是通过注册的 agent tools 暴露给模型

工具权限确认

功能说明

当 Agent 在会话中执行文件写入（write）、文件编辑（edit）或 Shell 变更命令（bash 变更类操作）时，系统会根据项目配置决定是否需要用户确认。这确保用户对 AI 的每一次文件变更和命令执行都有完全的掌控权。

确认触发条件

系统根据以下规则判断是否需要用户确认：

Bash 命令分类

系统自动识别 Bash 命令是否为变更操作：

• 变更类命令（需确认）：rm、mv、cp、mkdir、chmod、chown、sed -i、perl -pi、patch、git apply、Shell 重定向（>/>>）、tee、脚本解释器（python/node/bash 等）、find -exec、xargs、heredoc
• 只读命令（自动放行）：ls、cat、head、tail、grep、find（无 -exec）、echo（无重定向）、which、pwd 等

确认面板操作

当有待确认的工具调用时，聊天区域顶部会显示工具权限确认面板：

1. 面板显示工具名称（如 write、edit、bash）、操作标题和具体内容摘要
2. 显示操作涉及的目标文件路径或命令内容
3. 显示触发确认的原因说明（如"手动模式需要确认此文件变更操作"）
4. 点击 「批准」 按钮：系统执行该工具调用，并继续对话
5. 点击 「拒绝」 按钮：系统拒绝该工具调用，停止当前对话执行

差异预览

对于待确认的 write 和 edit 请求，确认面板在你批准前可以显示逐行差异预览：

• 文本文件会以 hunk 形式展示新增、删除和上下文行
• 大文件、二进制文件、缺失目标或歧义较多的编辑匹配会退回为摘要或摘录，而不是完整 diff
• 该预览是只读的，不会额外写入工作区状态

回滚已执行变更

当文件变更类工具调用已经执行完成后，工具卡片可以显示已执行的 diff 和 回滚变更 操作：

• 点击 回滚变更 会打开确认面板，并列出受影响的文件及其状态
• 点击 确认回滚 会恢复到执行前的内容
• 新增文件会被删除，已删除文件会被恢复，修改文件会回滚到之前的内容
• 如果工具执行后工作区又发生了新的改动，回滚会被阻止，卡片会显示引发冲突的文件
• 发生冲突时，工作区不会被改写

批量确认

当一次对话轮次中触发多个需要确认的工具调用时，确认面板会按顺序展示所有待处理请求，用户可逐个审批。

配置方式

• 自动执行模式：在项目设置中开启后，所有工具调用自动执行，无需手动确认
• 手动确认模式（默认）：每次文件变更和 Shell 变更命令都需要用户手动批准

安全说明

• 标准模式下，Agent 无法修改 .agent/ 目录下的配置文件（memory.md 和 memory/ 子目录除外），防止 Agent 擅自修改自身的技能或动作定义
• 开发模式下无此限制，允许 Agent 修改 .agent/ 下的所有文件
• 权限请求状态包括：pending（待确认）、approved（已批准）、denied（已拒绝）、executed（已执行）、expired（已过期）

使用建议

为不同研究子主题建立独立会话，方便后续回看与复用。