docs: clarify AI sidebar session lifecycle

This commit is contained in:
tianma-if committed 2026-09-29 12:50:16 +08:00
1 parent 6ffa52f1a6
commit 185ad0a56b
1 file changed
+5 -3
+5 -3
View File
@@ -63,6 +63,7 @@
* 彻底解决遮挡问题,用户可一边阅读/编写长笔记,一边观看 AI 推理。
* **小屏/平板/手机端**:自动响应式降级。
* 当编辑器宽度低于阈值(例如 `< 768px`)时,侧栏转为右侧滑出抽屉(Sheet / Drawer),关闭时不占用宝贵宽度。
* **会话生命周期**:普通收起/展开侧栏或关闭/重开小屏抽屉只改变可见性,不卸载正在执行的会话组件;明确点击“停止”才取消任务。当前 `CompanionChat` 卸载时会中止请求,因此新布局须避免把“收起”直接实现为卸载。页面刷新、应用升级或进程退出可能中断进行中的会话,这一限制可以接受;不为跨升级续跑引入全局会话管理器或后台队列。
* **选区感知(Context Linking)**:
* 用户在编辑器中划选文本时,右侧栏输入框上方自动出现轻量选区徽标(如 `选中 320 字 · 当前笔记`);
* 用户提问时自动将选区作为上下文注入,无需二次复制粘贴。
@@ -188,9 +189,9 @@ sequenceDiagram
| 评估维度 | 详细说明 |
| :--- | :--- |
| **功能价值** | 彻底消除弹窗遮挡编辑器的交互硬伤;减少手写冗余代码;统一操作心智;让图片、PDF 与文本资料真正进入 Agent 上下文;打通本地 Agent 生态。 |
| **影响范围** | `apps/web/src/components/EditorPane.tsx` 布局容器、`apps/web/src/components/dialogs/AiAssistantDialog.tsx`(废弃并替换)、旧问答与行内 AI 编辑入口、原有动作卡片交互、`WorkspaceApp.tsx` 侧栏布局排布、AI 附件准备逻辑、Companion 输入 Schema/路由/模型消息、Electron ACP 桥接和 i18n 文案。 |
| **最坏后果** | 1. 窄屏下侧边栏挤压主编辑器可视区;<br>2. 旧版一键改写与行内替换被移除后,在新编辑流程上线前,用户只能获取文本建议并手动修改笔记;<br>3. 附件被静默遗漏、误发给错误通道,或大文件使请求失败;<br>4. 本地连接异常时出现无响应等待;<br>5. 若错误地将 Agent 输出当成可信笔记动作,可能覆盖旧内容或绕过写入确认。 |
| **回滚与防范方案** | 1. **弹性布局**:严格设定桌面最小断点,小屏强制降级为遮罩抽屉(Drawer);<br>2. **明确过渡能力**:新编辑流程完成前,只提供 Agent 回复和人工编辑,不保留旧行内写入实现;<br>3. **附件独立开关**:附件通路异常时可关闭该能力,纯文本会话继续可用;发送前校验目标通道与文件内容,不允许静默降级;<br>4. **版本回滚**:保留模型调用链路,新版体验不可接受时通过版本回滚恢复旧实现;<br>5. **写入门禁与连接状态**:未经后端校验和用户确认不得应用提案;本地通道区分程序未找到、需要登录、会话可用和连接失败。 |
| **影响范围** | `apps/web/src/components/EditorPane.tsx` 布局容器、`apps/web/src/components/dialogs/AiAssistantDialog.tsx`(废弃并替换)、旧问答与行内 AI 编辑入口、原有动作卡片交互、`WorkspaceApp.tsx` 侧栏布局与组件挂载、AI 附件准备逻辑、Companion 输入 Schema/路由/模型消息、Electron ACP 桥接和 i18n 文案。 |
| **最坏后果** | 1. 窄屏下侧边栏挤压主编辑器可视区;<br>2. 旧版一键改写与行内替换被移除后,在新编辑流程上线前,用户只能获取文本建议并手动修改笔记;<br>3. 附件被静默遗漏、误发给错误通道,或大文件使请求失败;<br>4. 误把收起侧栏实现为卸载,导致进行中的任务意外中断;刷新或升级时任务也可能中断;<br>5. 本地连接异常时出现无响应等待;<br>6. 若错误地将 Agent 输出当成可信笔记动作,可能覆盖旧内容或绕过写入确认。 |
| **回滚与防范方案** | 1. **弹性布局**:严格设定桌面最小断点,小屏强制降级为遮罩抽屉(Drawer);<br>2. **明确过渡能力**:新编辑流程完成前,只提供 Agent 回复和人工编辑,不保留旧行内写入实现;<br>3. **附件独立开关**:附件通路异常时可关闭该能力,纯文本会话继续可用;发送前校验目标通道与文件内容,不允许静默降级;<br>4. **轻量生命周期约定**:收起侧栏不卸载会话,停止任务走显式操作;接受刷新、升级和进程退出造成的中断,不承诺跨升级恢复;<br>5. **版本回滚**:保留模型调用链路,新版体验不可接受时通过版本回滚恢复旧实现;<br>6. **写入门禁与连接状态**:未经后端校验和用户确认不得应用提案;本地通道区分程序未找到、需要登录、会话可用和连接失败。 |
| **跨运行时验证项** | 严格禁止在核心 Server 代码中引入 Node 本地沙箱依赖,确保 Cloudflare Workers 与 Docker 镜像构建 100% 保持纯净与通过。 |
---
@@ -201,6 +202,7 @@ sequenceDiagram
- [ ] 在 `WorkspaceApp.tsx` / `EditorPane.tsx` 建立右侧扩展面板插槽(`AiSidebar`)。
- [ ] 实现侧边栏的展开/折叠状态管理、键盘快捷键(`Cmd/Ctrl + J`)以及宽度拖拽调宽(支持 `localStorage` 记忆)。
- [ ] 完成小屏断点响应:`width < 768px` 时降级为浮动抽屉(Sheet)。
- [ ] 验证进行中任务在桌面收起/展开和小屏抽屉关闭/重开后继续运行;显式停止才取消。刷新或升级时的中断按已接受的限制处理,不建设跨升级续跑机制。
### 第二阶段:基于 `ai-elements` 重构对话流(UI Modernization)
- [ ] 复用已有 `conversation.tsx` 和 `message.tsx`,从官方 AI Elements 组件仓库按需引入 `reasoning`、`prompt-input`、`attachments`,核对新增依赖与项目现有 `shadcn/ui` 版本;不自行仿写同名组件,也不安装整套组件。