09. 交互模式

翻译说明： 本页是与 英文源规格 一一对应的机器辅助翻译。代码、协议字段和标识符保持原文；如翻译与英文源事实有歧义，以英文版本为准。

设计系统令牌：07-ui-design-system.md 组件剖析：08-component-spec.md 权限UX：03-permission-ux.md 命令面板：04-builtin-commands.md

1. 键盘快捷键基线

1. 1 全局快捷键

快捷方式	行动	背景
Option + Space (macOS) / Alt + Space (Windows/Linux)	打开插件启动器	应用程序启动后操作系统全局；可定制
Cmd/Ctrl + Shift + P	打开命令面板	全球 (D014)
Cmd/Ctrl + N	新 chat/session	全球
Cmd/Ctrl + O	打开项目	全球
Cmd/Ctrl + W	关闭窗口	全球
Cmd/Ctrl + ,	打开设置	全球
Cmd/Ctrl + B	切换侧边栏	全球
Cmd/Ctrl + J	打开工作面板	全球；活动会话
Cmd/Ctrl + [	之前的目的地	全球
Cmd/Ctrl + ]	下一个目的地	全球
Cmd/Ctrl + .	中止主动回合	全局（与中止按钮相同）
Cmd/Ctrl + K	打开命令面板	全球

1. 2 对话上下文快捷方式

快捷方式	行动	背景
Enter	发送消息	以输入框为中心
Shift + Enter	换行符	以输入框为中心
Escape	清晰输入/模糊编辑器	以输入框为中心
Cmd/Ctrl + ↑	滚动到文字记录顶部	注重成绩单
Cmd/Ctrl + ↓	滚动到文字记录底部	注重成绩单

1. 3 命令面板快捷键（面板内）

快捷方式	行动	背景
↑ / ↓	导航结果	调色板打开
Enter	执行选定的命令	调色板打开
Escape	关闭调色板	调色板打开

1. 4 快捷键规则

• macOS 应用程序菜单快捷方式可通过系统菜单发现 加速器。 Windows/Linux 快捷方式仍然可用，无需渲染 应用程序菜单栏；仅命令快捷方式可通过命令发现 调色板搜索（关键字“快捷方式”或“键绑定”）。
• 快捷方式不得与 macOS 系统快捷方式或常见浏览器快捷方式冲突
• 切勿覆盖 Cmd/Ctrl + C、Cmd/Ctrl + V、Cmd/Ctrl + A、Cmd/Ctrl + S
• macOS (Cmd) 和 Windows/Linux (Ctrl) 之间的快捷键是一致的
• 仅修饰符按键和 IME composition/229 按键永远不会调度 命令。重复的按键事件不会重复遍历目的地 历史；每个 back/forward 和弦每次物理按下最多前进一次。
• 仅命令快捷方式更改需要更新命令面板元数据； 本机角色和可见的应用程序菜单加速器仍然由菜单拥有
• 插件启动器通过 Electron 的本机全局快捷方式注册 API。 Windows' 保留的默认值 Alt + Space 另外使用 host-core 低级键盘钩子，消耗系统菜单和弦并发出 Electron 主机通知，因此它可以在另一个应用程序运行时工作 专注。如果钩子无法被调用，聚焦窗口后备仍然可用 安装。自定义绑定继续使用 Electron 的全局快捷方式 API。 启动器始终在最靠近指针的显示屏上打开。

1. 5 插件启动器快捷方式

快捷方式	行动	背景
↑ / ↓	循环匹配插件	专注于启动器
Enter	打开选定的插件面板	专注于启动器，而不是撰写 IME 文本
Escape	关闭启动器	专注于启动器

1. 5 平台应用菜单

• macOS 应用程序菜单加速器调度相同的白名单 shell 作为渲染器控件的命令。保留本机 Edit/View/Window 角色 平台文本编辑、缩放、全屏、隐藏和退出行为。
• Windows/Linux 在窗口中不呈现应用程序菜单。他们的无框 标题栏将侧边栏操作保留在左边缘，将本机窗口控件保留在 右边缘。当工作面板打开时，其唯一的折叠控制位于 在会话窗格右上角这些窗口控件之前，而不是在 工作面板内容标题。目的地历史记录没有可见的 back/forward 控制并通过渲染器快捷方式保持可用。第一个 转录行从 46px 标题栏控制带下方开始，因此用户和 助理内容不能与最小化、maximize/restore 或关闭重叠 目标。目标页面和插件详细信息表的开头相同 带，因此页眉操作和工作表关闭控件永远不会堆叠在 这些目标。 F10 和 Shift+F10 不会被 shell chrome 消耗。
• Windows/Linux 保留新任务、打开项目、设置、关闭窗口、 缩放、全屏、搜索、命令面板、侧边栏和工作面板快捷方式 通过渲染器键处理。标准编辑快捷方式仍然是原生的 网络内容行为。
• 开发者工具是可选的。启用开发者模式后，Main 会处理 F12 每个平台以及 Windows/Linux 上的 Ctrl+Shift+I； macOS 暴露其原生 View 中的开发人员工具角色。禁用该模式后，这些产品条目 点仍然不可用，禁用它会关闭打开的控制台。
• 主队列本机命令，直到渲染器确认其菜单 事件订阅在 macOS 上处于活动状态。关闭并重新创建窗口 重置本次握手。
• 无框最小化、maximize/restore 和关闭控件保留在范围之外 拖动区域。最大化状态在挂载时查询并从本机更新 窗口事件，因此恢复可供性永远不仅仅取决于乐观 渲染器状态。

1. 5.1 托盘驻留最小化

• 最小化意味着 macOS、Windows 和 Linux 上隐藏到托盘。渲染器的 Windows/Linux 最小化按钮、macOS 交通灯最小化按钮，以及 macOS 窗口 → 最小化角色共享此行为。
• 隐藏将从 taskbar/dock 窗口列表中删除主窗口，而 Electron 进程和后台工作仍然有效。它不坚持 最小化几何形状或处置 host/sidecar。
• 单击或双击 PI-Desktop 托盘图标，从其中选择“显示” 菜单，或从 macOS 扩展坞激活应用程序可恢复并聚焦 现有的窗口。如果窗口关闭，相同的操作会创建一个新的窗口 窗口。
• 托盘菜单使用活动的 English/zh-CN shell 语言环境进行本地化，并且 公开 Show PI-Desktop 以及显式退出 PI-Desktop 操作。戒烟使用 现有的有序关闭路径；关闭窗口仍然是退出操作 而不是隐式托盘隐藏。

1. 6 侧边栏项目和对话组织

侧边栏是主持人拥有的项目和会话的路径键控演示。 Sessions 标题首先出现，包含无路径对话以及 他们的创建和排序控件。它的有界列表使独立工作保持可见 而不消耗整个侧边栏。以下 Projects 部分标题 在保留的项目组上方公开项目选择器。多个项目组 当只有一个工作空间提供可见的 shell 上下文时，可能会被保留。

项目选项卡生命周期

1. 打开 — 从“设置”→“项目存档”中选择一个项目，或者选择器添加其项目 保留集的标准化路径并激活它。现有选项卡保留。
2. 激活 — 选择不同的组调用现有的 project.set 桥。然后，它的路径驱动顶栏标识、活动工作区状态，以及 新任务范围。
3. 折叠 — 披露状态属于每个项目路径。崩溃 仅隐藏儿童；它既不更改选定的会话，也不停止 跑。目录行是一个全角公开目标，包含其 V 形、文件夹和标签：选择非活动目录将其激活 首先，每次目录行单击都会切换该组的子级，而无需 改变任何其他组的状态。项目操作是独立的兄弟项目 控制并且从不切换目录。
4. 关闭 — 关闭仅删除保留的选项卡。如果它处于活动状态，则 选择最后一个剩余选项卡或清除可见工作区。耐用 项目、会议和成绩单仍然保留。

组织行动

• Pin 切换演示优先级。出现固定的 projects/conversations 在所选二级订单中取消固定的行之前。
• 存档是非破坏性的。默认情况下，存档的行是隐藏的， 可通过显示已存档且可恢复。存档不会取消 转动或删除成绩单。
• 创建分支快照空闲对话的完整活动状态 转录到同一 project/Temporary 范围内的独立会话中。 当源运行时该命令被禁用。成功选择了孩子 聚焦输入框；失败使源可见且未改变。
• 归档可见的 conversation/project 首先移动可见上下文 给一个未存档的兄弟姐妹。没有兄弟姐妹，谈话就会变得新鲜 同一范围内的草稿和项目清除了可见的工作空间；该应用程序 永远不会将隐藏的归档行保留为活动上下文。
• 排序优惠最近更新 (recent)、创建日期 (created)、 最旧的在前 (oldest)，以及名称 (name)。 Missing/invalid 值回落 至 recent。为了兼容性，接受持久的 manual 值，但是 此基线中不承诺任何拖动或手动重新排序交互。
• 每个项目组显示活动排序顺序中最新的十行 默认情况下；剩余的会话折叠在 加载 N 更多… 控件后面 （与时间分组溢出相同的可供性）。选择它展开 完整的时间分组列表，并且扩展状态是每个组的，对于 仅当前会话，不持久。
• 尽力保存演示文稿更改。存储故障不得阻塞 项目激活、会话选择或代理执行。

跨选项卡的会话隔离

• 选择一行会立即将该目的地标记为已选择。 120毫秒 指针悬停或键盘焦点可以预取其记录；重复读取 共享一个正在进行的请求，渲染器最多保留五个最近的请求 转录快照。
• 脚本加载开始，无需等待旧的被取代的选择。 当会话摘要元数据可用时，项目 activation/clearing 和 转录IO并行运行。单调导航生成仅允许 用于投影可见工作区、脚本、运行状态的最新选择， 导航历史记录和工作面板上下文。
• 工作区对齐后可能会出现温暖的转录快照，并且 总是重新验证。冷切换或 React 延迟切换会保留之前的切换 完整的转录本是一个暗淡的、非交互式的稳定框架，带有薄的 进度跟踪和 aria-busy；它从不合并目标会话 ID 与上一会话的消息。准备好后，目的地将绘制在 这是它最后的记录，没有创下历史之巅，也没有空置的闪光。
• 选择项目范围的对话会激活其项目作为 商店自有精选交易。选择临时对话将清除 可见的工作空间。项目范围内的新会话操作通过了目标 同一家商店交易的路径；侧边栏和项目索引处理程序执行以下操作 在会话创建或选择之前不执行第二个项目导航。
• 运行状态、权限授予和流式事件由会话 ID 键入。 project/tab 开关不会中止后台轮次或将其事件复制到 可见的转录本。背景消息、工具、完成和权限 事件永远不会激活其会话、更改可见的 project/page 或移动 焦点。创建一个新会话或切换到未运行的会话返回 输入框立即进入空闲发送状态：轮流仍在 先前选择的会话永远不会离开目标会话的发送按钮 卡在 Abort/stop 状态，并且该后台回合稍后完成 不改变目标输入框。他们的工作面板工件和 浏览器资源仅更新 原始会话保留的渲染器上下文，并且不显示或调整大小 可见面板。仅显式 session/notification 激活才能导航 并投影目标会话的保留面板上下文。
• 每个工具调用都会从原始持久性解析 workspaceRoot 会话，而不是来自当前选定的项目选项卡。后台完成 刷新匹配行而不重定向活动对话。

焦点和语义

• 项目目录行公开 aria-expanded 和 aria-controls； new-project/new-session 控件具有特定于范围的可访问名称，并且 sort/archive 菜单选项公开其选中状态。活动会话行 保留 aria-current。
• 切换披露或菜单操作可将焦点集中在其控制上。选择一个 加载后，project/session 将焦点返回给输入框。
• 保留排序、存档、恢复、固定、创建分支和关闭操作 可通过键盘操作； 它们不能仅仅作为指针悬停功能而存在。
• 从工具栏或行触发器打开的侧边栏主体级菜单仍然存在 内容大小并使用与右键菜单相同的固定规则：打开4px 锚点在右侧而不向左翻转。它们的表面宽度为 为窄视口设置了上限。这包括会话排序菜单， session/project 溢出菜单和部分创建菜单。

1. 6 本地个人资料页脚

• 44px 配置文件触发器切换菜单；它的V字形和 aria-expanded 状态一起改变。
• 280px 菜单在透明页脚带上方打开 8px。打开它 将焦点移至非交互式标识之后的第一个可操作行 标头和分隔符。
• ArrowDown / ArrowUp 包含在设置、日志和主题之间。 Home 和 End 移动到第一个和最后一个操作。
• Escape 关闭菜单并将焦点恢复到配置文件触发器。一个指针 按外侧可将其关闭，而不会窃取指针目标的焦点。
• 在执行操作之前选择“设置”、“日志”或“主题”会关闭菜单 行动。主题应用下一个主题值，无需重新打开菜单。
• 单独的 32px 帮助按钮绕过配置文件菜单并导航 直接进入设置 → 信息。
• 折叠侧边栏会关闭菜单并恢复折叠的栏杆 正常导航状态。

1. 7 通知收件箱（D117）

事件到表面的流

1. Renderer 将当前聊天的会话 ID 报告给 Electron Main；导航 离开清除它。 Main 将此提示与其自己的窗口可见性结合起来， 当转动达到 completed 或 error 时的焦点状态。
2. 如果确切的整理会话已在焦点窗口中可见， session.endTurn 关闭回合而不插入通知。任意 后台会话或 unfocused/hidden 窗口创建持久记录。 aborted 回合永远不会创建一个。
3. Electron 向每个实时渲染器发出 notification.changed，以便响铃 徽章和当前打开的收件箱刷新。
4. 如果主窗口获得焦点，则不会出现其他表面。如果是的话 支持未聚焦和本机通知，Electron 显示一个 从事件类型和会话标题派生的平台通知。开 Windows，该横幅归因于规范的 PI-Desktop AppUserModelID 与 NSIS 包和任务栏标识共享。
5. 单击本机通知 shows/restores 并聚焦于主通知 窗口，然后发出 notification.activated { sessionId }。
6. Renderer 激活选择绑定项目（如果存在），加载 会话，并使用与收件箱相同的路径聚焦 transcript/composer 行点击。本机激活和应用内激活不得不同。

弹出窗口行为

• 单击铃声可切换非模式弹出窗口；第二次单击、Esc 键或外部 按将其关闭。 Escape 将焦点恢复到铃声上。
• 打开时保留最近选择的 All / Unread 过滤器 当前渲染器生命周期并且从不标记隐式读取的行。
• 箭头键在禁用换行的情况下在行中移动； Home / End 跳转到 first/last 行； Enter/Space 标记该行已读取并激活其会话。
• 标记一个主机事务中每个未读行的所有读取更新。清除 删除一个主机事务中的所有收件箱行。两个操作都是 幂等，刷新确切的未读计数，并保持 sessions/turns 不变。
• 渲染器不会从流事件中合成通知记录。 Host-core 独特的 turn_id 是重复的一次边界 终端更新、渲染器重新加载和进程重新启动。
• 所有可见事件标签和本机 title/body 字符串均在 结构化字段的表示边界；持久化的行从不包含 本地化的散文。

1. 8 工作面板条目和资源（D128、D142、D154、D173、D179、D207）

• shell 启动时没有可见的工作面板。 Cmd/Ctrl + J 打开 活动会话的保留面板上下文，无需创建资源选项卡；它 当面板已经打开时是幂等的，并且是无操作的 活动会话或当“设置”是活动页面时。小组的背景 然后触发器可以创建四个工具资源之一。
• 工件触发器自动创建或重用其资源，激活它， 并打开面板。背景工件永远不会打开可见面板。
• 文件资源使用规范化路径作为标识。审查、终端和 浏览器是单例的；重复触发器保留资源顺序并且 激活现有资源。
• 打开后，面板的统一上下文触发器将锚定在标题的左侧 并打开一个下拉菜单。它的顶部列出了四个工具——审查、 终端、浏览器、文件 — 按固定顺序，每一行都有自己的打开状态 状态，一旦打开，它自己关闭控制。第二部分出现在 仅当成绩单打开更多资源时才使用分隔符，因此永远不会有任何条目 列出两次。右侧操作簇固定在标题的右边缘 位于分隔线后面，并且不随标签长度 (D173) 变化。
• 菜单行拥有 DOM 焦点。使用触发器的 ArrowDown/ArrowUp 着陆打开 分别为活动行或最后一行； Arrow/Home/End 然后走行 只是，从来没有他们的尾随关闭按钮。 Delete/Backspace 关闭焦点 行的资源而不关闭菜单并保持关注邻居 取代它的位置。选择一行、Escape 或 Tab 将关闭菜单并 将焦点恢复到触发器；只有会话切换才会隐式地解除它 （D173）。
• 激活已打开的工具会激活其现有资源 替换它，因此浏览器保留其 URL 和文件的选择 (D173)。
• 每个资源都可以从菜单中关闭，并且活动资源有 直接标题关闭控件。关闭活动资源选择正确 邻居，然后左边；关闭最后一个选项卡会隐藏面板。分开的 会话窗格右上角的面板折叠控件隐藏面板，但不显示 删除选项卡。
• 在每个平台上，打开可见面板都要求本机宽度等于 它的承诺宽度。折叠并最终关闭回收预订，并且 提交的分隔符调整大小会更新它。本机窗口边缘拖动更改 仅 MainChat，从不面板宽度（D163，ADR 0032）。
• 成功的工作区 Write/Edit 在其内部创建或激活 Review 发起会话。失败和临时写入不会。背景会议 工件仅更新其保留的上下文，并且从不打开、激活、调整大小， 焦点，或更改可见面板。
• 每个成功的工作区 Write/Edit 工具结果都会进行一次持久审查 快照。其紧凑的 InlineReviewCard 在同一个 Activity 中呈现 披露，紧随其工具行之后；它永远不会移动到 转录底部并且从未与其他会话共享。它的状态徽章 涵盖添加、修改和删除的更改，同时计数和可扩展 hunk 来自该消息的结果，而不是当前的 Git diff。
• 成绩单卡和复习会消耗活动会话的持续时间 消息历史记录。提交、工作区焦点更改或外部 Git 状态 更改无法删除或重写旧卡。评论是按时间顺序排列的 快照历史记录和每个可逆卡都会暴露主机保护的回滚； 报告冲突而不替换以后的编辑。划痕，失败， 被拒绝，非结构化结果不会呈现卡片。背景 会话的卡片保留其自己的成绩单并且仅变得可见 选择该会话后；它的事件永远不会呈现在当前 可见会话。成功的工作空间工件仍可能创建或 激活单例“审阅”选项卡。
• 终端仅在命令工件打开并保持安装状态后才安装 当该选项卡存在时跨选项卡切换。
• 每个会话在渲染器中保留 {open, tabs, activeTabId, browserResource} 记忆。选择另一个会话会自动交换可见上下文， 切换回来可以恢复它；选择没有活动的工作区 对话隐藏面板。 Session/workspace 身份仍附加到 每个相关资源，防止跨上下文重新解释。
• 重新启动会丢弃每个会话上下文，包括浏览器资源；仅 承诺的首选面板宽度仍然存在。存储本机窗口状态 独立于正常范围，包括当应用程序关闭时 最大化或在待处理的边界保存去抖完成之前。面板宽度 保持固定而不是被响应地夹紧。

1. 9 应用程序更新 (D120)

• Electron Main 在打包应用程序后 15 秒检查固定发布源 启动后以及之后每 6 小时一次。开发版本仍然被禁用。 检查器始终跟踪 GitHub 的最新稳定版本 (allowPrerelease = false)，因此安装仍带有预发行版 诸如 0.2.0-rc.6 之类的版本提供了较新的稳定标签，而不是 保持固定在同一个预发布频道上。
• 设置 → 信息和应用程序菜单检查共享一种类型的更新状态。 手动检查公开最新或错误反馈；自动故障不会 打开 Toast 或环境横幅。
• 手动交付（darwin 和非 AppImage Linux）在 available 停止，并且 提供固定的 GitHub 发布页面。应用内交付（Windows NSIS 和 Linux AppImage 准备就绪构建）自动推进 downloading 到稳定的 downloaded 状态。
• downloaded 保持可操作状态，直至重新启动更新或正常应用退出； 稍后的 scheduled/manual 检查不会将其替换为 checking。
• 紧凑的更新通知仅出现在主窗格的右上角安全区域中 适用于手动 available、应用内 downloading 或 downloaded。它保持清晰 每个受支持的窗口大小和草稿高度的底部编辑器。的 通知使用稳定的 icon/title/message 层次结构，显示确定的下载 可用时取得进展，并将相关操作保持在同一状态 表面。解雇会抑制当前版本和状态阶段；稍后 downloaded 等阶段再次出现。
• 当 Main 附加发现版本的双区域设置产品说明时 （UpdateState.releaseNotes，D164），通知和设置→信息更新 行在状态消息下显示紧凑的“新增内容”列表。笔记来了 从产品 UI 选择的已发货 EN/zh-CN 变更日志目录中 语言环境 — 绝不来自渲染器提供的提要或远程 URL。缺少目录 条目省略了该部分；区域设置更改重新解析注释，无需新的 检查。
• 设置 → 信息在每个更新程序中保留可用的发行说明操作 状态。它在“设置”上打开一个模式，具有完整的本地稳定 变更日志按最新到先的顺序，从同一共享目录本地化。 当前版本和发现的可用版本标识为 紧凑的徽章。列表独立滚动，通过其关闭控制关闭， 转义或背景，并将焦点恢复到调用控件。
• D126 标签版本发布所有平台清单和安装程序。 Windows 因此，NSIS 和 Linux AppImage 使用应用内通道； macOS 和 Linux deb 保持通知和链接传递模式。

2. 流消息行为

2. 1 Token渲染

• 令牌在到达时附加到当前助手 MessageBubble 中
• Renderer直接显示运行时流块；它不会排队 第二个 requestAnimationFrame 驱动的打字机状态循环
• 渲染使用增量降价解析 - 不要在每个标记上重新渲染整个消息
• 成绩单核对将完整的历史记录保留在记忆的历史边界中； 令牌更新不会协调 React 中的每个历史行，同时保留 选择、复制、小地图锚点和可访问性的完整历史记录。
• 未完成的 mermaid 栅栏仍然是源代码块。其关闭后 栅栏到达，回答散文加载并仅在它出现时渲染图表 接近视口；思维披露总是保留美人鱼的来源。
• 图表渲染失败或保持 20,000 个字符/500 个边的安全限制 源可见且可复制，而不是让助理轮不到。
• 光标指示器：流内容末尾的微妙脉冲重音点或线
• 在第一个助手或工具事件之前，活动回合显示一个紧凑的 具有经过时间的本地化 Working… 状态。它被混凝土取代 thinking/tool/answer反馈或内联权限卡尽快一张 存在这些状态。
• 当流完成时：光标指示器被成功状态取代（2秒淡出）

2. 2 自动滚动

• 打开会话会重置跟随模式并将记录放在最后 在浏览器绘制激活的转录本之前记录。激活 不会通过历史记录动画或暴露顶部或上一个会话的 滚动位置。
• 自动滚动到每个新令牌组的底部（限制：每 100 毫秒检查一次，而不是每个令牌）
• 第一次向上手动滚动运动会立即暂停自动滚动，并且 取消任何待处理的跟随帧；小触控板三角洲不得弹回 底部
• 发送新提示、重试或重新生成始终会重新固定跟随模式并在继续转动之前跳转到底部，即使用户已向上滚动
• 手动向上滚动时立即出现“滚动到底部”浮动按钮 释放跟随模式
• 单击“滚动到底部”按钮：恢复自动滚动并捕捉到底部
• 流完成：如果用户自动滚动，则保持在底部；如果是手动，则停留在该位置
• 异步完成的图表高度更新遵循相同的规则： ResizeObserver 在底部保留固定的记录，而拥有 向上滚动保持在其阅读位置。

2. 4 主动回合表面

• 主动转动可保持转录本下表面清晰。直播助手 工具行与记录保持一致；没有通用的理解， 工作卡或检查卡呈现在它们下方。
• 仅当代理被阻止时，权限卡才保持可见 明确批准。这是可操作的中断，而不是进度状态 卡。
• 后台会话继续，而不将进度镶边添加到可见内容中 会话或移动焦点。因此减少运动没有进度卡 过渡以保存。

2. 5 回合结果结束

• 失败的可见回合会在回合结束后呈现一张会话范围的恢复卡 转录内容。它基于终端代理事件，而不是超时 或猜测的旋转器状态。完成回合不会添加成功卡；他们的 现有的成绩单和消息范围的审查卡仍待完成 证据。
• 失败副本表明现有工作仍然可用。重试重新发送 通过现有重试路径的最新用户提示；继续退货 将注意力集中在输入框身上而不改变抄本。
• 中止的回合不会呈现失败卡。开始新的回合会清除 上一张卡和后台会话结果保持范围，直到该卡 会话已选择。

2. 3 流中断

• 如果连接中途中断：在部分消息上显示错误状态
• 保留部分消息 - 不删除
• 用户看到“流中断”并带有重试选项

3. 中止正在运行的代理

3. 1 触发方法

• 顶部栏中止按钮（在运行状态下可见）
• 键盘快捷键：Cmd/Ctrl + .
• 命令调色板：builtin.agent.abort

3. 2 中止行为

1. 立即取消当前代理轮次
2. 取消任何待处理的权限请求（根据 03-permission-ux.md §7）
3. 如果没有开始辅助文本、思考或工具行，则删除刚刚发送的 用户行并恢复其预序列化输入框草稿
4. 恢复后的草稿将普通文本和文件参考芯片分开 状态；序列化的规范路径永远不会占用文本区域
5. 如果回复已开始，则保留用户回合和部分 assistant/tool 行 处于中止状态并且不恢复任何草稿。保留测量的流 持续时间和使用提供商输出使用情况（如果可用）；否则存储一个 明显估计的输出计数，因此对话仍然显示吞吐量
6. Composer重新激活（解锁）
7. 中止是幂等的——当已经中止时按中止不会执行任何操作

3. 3 中止用户体验

• 中止按钮短暂更改为“正在中止...”（100 毫秒），然后消失
• 没有中止确认对话框——它总是立即发生
• 部分中止的消息会获得静音的“（中止）”后缀。只有 未应答的智能停止分支会删除其刚刚发送的用户行。

3A。上下文检查点生命周期

• turn_end 标记一个已完成的 model/tool 回合，之后可能会进行另一回合 提供商请求。它永远不会重新启用输入框或会话配置。
• 自动上下文保护在每个 turn_end 后进行评估并运行 inline：用户等待。该模型也可以通过提前要求 new_context，落在同一边界。
• compaction_start 保持会话运行。阈值和溢出 compaction_end 事件保留在活动运行中；仅 agent_end 或 error 解决了这个问题。仅手动检查点位于 compaction_end。
• 每次成功的压缩都会显示一个警告提示：早期的细节消失了， 开始新的会话是只有用户才能做出的决定。三个 更具体的 toast 保留在其之上 - 成功的手册 /compact 结果、溢出重试之前的警告以及下面的回退警告。
• 如果自动摘要生成失败，但保留尾部检查点 持续存在，compaction_end.fallback = "retained_tail" 显示一个警告 祝酒和积极的运行继续减少历史背景。
• 手动失败显示一个错误 toast。自动 hard/overflow 失败不会 不要用祝酒词重复助理错误；终端错误仍然存在 附加到失败的回合。
• 压缩永远不会删除可见的转录消息。检查点影响 仅未来模型上下文并在会话 switching/restart 中保留。
• 每次压缩都会在记录中添加一个分隔行，紧接在 它涵盖的最后一条消息，读取会话已压缩的次数以及 摘要的估计代币成本（或者没有生成摘要）。行 没有任何操作且不可选择。
• 上下文使用检查器为最新的检查点保留一条静音线， 显示在悬停或键盘焦点上 - 计数和汇总成本，在一个 还显示上下文的用途的地方。

4. 长内容折叠/展开

4. 1 崩溃阈值

内容类型	默认状态	崩溃阈值	扩大限制
助理降价消息	扩展	50 行 → 折叠至 20 行可见	满
工具活动输入	行倒塌	始终落后于披露	220px 滚动区域
工具活动输出	行倒塌	始终落后于披露	220px 滚动区域（根据 D033 主机上限）
bash 输出	行倒塌	始终落后于披露	220px 滚动区域
错误信息	扩展	不塌陷	—

4. 2 折叠指示器

• 工具活动以轻量级折叠行开始；打开呼叫失败 自动，因此错误仍然是其调用的本地错误。
• 连续的工具活动包含在一个折叠的处理组中。其 标头在活动时每秒更新一次经过时间，在 下一条记录消息，并公开包含的步骤数。
• 失败的行是调用局部事实并且立即保持可见。的 仅包含组报告处理持续时间并按处理结果结算， 即使稍后的呼叫恢复。终端转向故障仅源自 终端代理事件并通过助手错误出现， TurnOutcomeCard、侧边栏状态和通知界面。
• 展开处理组显示有序行；每行都保留其 自己的输出和输入的嵌套公开。
• 激活该行首先显示钳位输出，然后显示原始输入。
• 每个部分在内部滚动并公开其自己的复制操作。
• 披露 V 形在扩展时旋转。减少运动禁用 非必要的 shimmer/rotation 动画。

4. 3 工具结果截断

• 根据 D033：超过 256KB 或 4000 行的工具结果将被显式标记截断
• 截断标记：[truncated: output exceeded 256KB or 4000 lines]（主机强制，请参阅 16-tool-result-limits）
• 截断的内容永远不会被默默地省略——总是被标记
• 披露扩展不会加载超出主机强制上限的内容

5. 权限中断流程

5. 1 流程顺序

Agent calls a permission-gated tool (including Plan/Goal Bash under Ask or Accept edits)
  → PermissionCard inserted inline in transcript
  → Composer disabled (cannot send new prompt)
  → Countdown starts (120s)
  → User responds: Allow once / Allow session / Deny
  → Card transitions to resolved state
  → Composer re-enabled
  → Agent continues or receives denial result

5. 2 多个待处理权限

• 每个会话最多有一张活动权限卡，因为该代理会循环 已暂停；多个会话可以独立等待。
• 中止仅取消活动会话的待处理权限。
• 超时（从原始接收开始 120 秒）仅自动拒绝匹配的请求； 切换会话永远不会重置截止日期。

5. 3 权限期间的焦点管理

• 通过 aria-live 公布可见的权限卡，无需强制 焦点。后台会话的卡未安装并且无法移动焦点。
• 卡片内的操作按钮可通过选项卡访问
• 解决后：焦点返回到输入框
• 完整规范：03-permission-ux.md

5A。 Plan 和 Goal 工作流程

1. 用户在会话空闲时选择 Plan 或 Goal，或相同的 Agent 调用 EnterPlanMode / EnterGoalMode；主机 persists/validates 匹配合约模式和渲染器项目 planning。
2. Agent 使用选定的合约工具集进行调查。 Read/Glob/Grep 和 允许使用 BrowserPreview； Bash 遵循可见权限模式。一个 Contract-mode Bash 命令可能会在 Auto 下发生变化，因此模式芯片仍然可见。
3. Agent 在其工具批次中单独调用 SubmitPlan 或 SubmitGoal。 Host-core 将准确的 Markdown 字节保留在新的不可变中 .pi/plan/*.md 或 .pi/goal/*.md 工件，记录其 path/hash/size 并结构化 title/question，渲染器显示共享合同审批卡 只有标题和神器开启器；问题仍然是主机端合同数据。
4. 批准需要询问/接受编辑/自动选择。渲染器会记住 该设备上最后选择的模式并将其用作下一个批准的模式 默认。 Host-core提交批准，mode = agent，权限模式， 和 queued 原子状态；同样的 Agent 继续新的回合 Agent 工具。 5.拒绝停止挂起的运行并将持久会话保留在其合同中 模式。实时状态恢复为可编辑规划；修订是新的 SubmitPlan/SubmitGoal 使用新的完整 Markdown 快照和新工件进行调用。早期快照 保持不变；没有请求更改操作。
5. 过期、中止、持久性失败、renderer/host/sidecar 崩溃或过时 响应呈现失败关闭状态。主机重启中断挂起， 排队、运行且无需重播的工作；已经批准的中断 将会话保留在 Agent 中。

批准卡是会话范围的。后台会话可能会保留待处理的 plan_approvals 中批准或 queued/running 执行状态，但打开 另一场会议从未涵盖它或转移焦点；回到原点 会话恢复渲染器生命周期快照；当宿主还活着的时候， plans.pending 可以对仍待处理的行进行补充。审批卡没有 公开 validity/deadline 概念。 Mode/provider/model/permission/shell 配置和新提示仍然存在 当存在有效的 pending 批准或轮次时禁用。待处理期间 批准现有草案保留在文本区域中，但为只读；仅 批准和拒绝在批准界面上保持启用状态。拒绝、过期或 中断可以重新启用它们；终端提案快照不保留门 关闭。渲染器保留每个会话的最新 checkpoint/execution 状态 仅适用于其当前生命周期，因此被拒绝、过期、中断、批准， 排队，并且运行结果可能在会话切换期间保持可见。一个 渲染器重新加载仅重新水化挂起的行；终端卡掉落并且 没有恢复。主机重启会中断之前的工作而不会重播或过时 动作，并且UI不需要呈现被中断的终端 快照。 Composer 左侧的 Agent/Plan/Goal 芯片是唯一的活动会话模式 控制。

在项目或会话初始化期间，家庭输入框可以在之前渲染 预计 activeSessionId。空闲模式、思考和许可 控制装置在该时间间隔内仍然可用；他们的第一个配置操作 创建或重用目标草稿并保留选择。跑步 轮流和待批准继续限制控制。

6. Toast 与内联错误

6. 1 Toast 通知（用于）

场景	Toast类型	持续时间	基本原理
提供商连接测试结果	Success/Error	4s/8s	瞬时反馈，不阻塞工作流程
插件load/unload成功	成功	4秒	确认后台操作
设置已保存	成功	4秒	快速确认
手动菜单更新检查失败	错误	8秒	对明确命令的直接反馈
上下文检查点已完成	信息（溢出重试前警告）	4s/8s	确认后台上下文转换而不更改转录本行
手动上下文检查点失败	错误	8秒	直接反馈明确的 /compact；自动终端故障保持内联

6. 2 内联错误（用于）

场景	内联放置	基本原理
工具调用失败	ToolCallCard 上的错误状态	上下文相关，用户需要查看哪个工具失败了
拒绝许可	PermissionCard 上的已解决状态	已经内联，对话流程的一部分
串流中断	MessageBubble 上的错误状态	属于失败的消息
Provider/model 回合失败	抄本中的助理错误消息	保留失败回合的摘要、稳定代码、经过编辑的详细信息和恢复操作
提供商配置验证错误	内联设置表单	用户需要查看哪个字段是错误的
应用程序更新 status/error	设置 → 信息更新行	保留最新的 Main-owned 状态而不中断背景检查
输入框验证（无模型）	禁用状态+发送按钮上的工具提示	直接上下文

6. 3 规则

• 切勿对与特定消息或工具调用相关的错误使用 toast
• 助手错误详细信息使用键盘可操作的披露 aria-expanded / aria-controls；它在第一次渲染时打开，因此提供商 响应可立即发现，并支持复制编辑文本
• 切勿将内联错误用于瞬态后台操作（插件加载、连接测试）
• Toast 垂直堆叠，最新的位于顶部中央
• 错误 toast 需要手动关闭或超时 8 秒（比成功长）
• 成功祝酒在 4 秒后自动关闭

7. 焦点管理

7. 1 将流程聚焦于页面加载

1. Composer 文本区域在主聊天视图中获得初始焦点
2. 设置页面：第一个交互元素获得焦点 3.命令面板：搜索输入获得焦点打开

7. 2 操作后的焦点流程

行动	聚焦目标
新会话已创建	输入框文本区域
会话已切换	输入框文本区域
消息已发送	输入框文本区域（已清除，准备下一步）
直播已完成	Composer 文本区域（重新启用）
权限已解决	输入框文本区域
中止完成	输入框文本区域
命令面板关闭	先前聚焦的元素
对话框关闭	先前聚焦的元素
使用 Escape 关闭通知弹出窗口	通知铃声
通知 row/native 通知已激活	加载脚本后激活会话编辑器

7. 3 焦点陷阱

• 命令调色板：打开时焦点被困在调色板内
• 设置模式：焦点被困
• 逃脱总是关闭被困表面并返回焦点

7. 4 对焦环规则

• 仅在 focus-visible（键盘焦点）上显示对焦环，在 click/mouse 焦点上不显示对焦环
• 聚焦环：2px 强调色边框，距元素边缘 2px 偏移
• 根据 07-ui-design-system.md §6.4
• 切勿全局移除对焦环 - 可访问性要求

7. 5 文本选择

• 默认情况下，应用程序镶边是不可选择的，以防止意外 单击或拖动外壳时进行选择。
• 可编辑控件（input、textarea、select 和 [contenteditable]) 保留正常文本编辑和 Cmd/Ctrl+A/C/V 行为。
• 转录散文、渲染的 Markdown、代码块和工具 input/output 保持文本可选择以供检查和复制。
• 保留嵌套在可选内容内的交互式控件 不可选择，并且必须保持其单击和键盘行为。
• 选择规则不得禁用 focus-visible 反馈或本机窗口 拖动区域。

8. 拖/放

8. 1 MVP 状态

工作面板宽度调整是在 MVP 中实现的：

• 10px 左边缘分隔符锚定到按下位置并开始 width，然后跟随指针 delta 而不跳转。
• 承诺的宽度限制在固定的 244px–720px 范围内。
• 指针移动是帧合并的。指针释放持续一提交 首选宽度；转义、指针取消和丢失捕获都会回滚。
• 打开和关闭码头的 width 和 flex-basis 以及 有界 opacity/transform 反馈，因此 MainChat 不断回流 而不是在第一个运动帧之前更改宽度。
• 渲染器始终请求本机预留宽度为 0，因此操作系统窗口 永不扩展 (ADR 0033)。打开、折叠和最终关闭仅改变 承诺的首选宽度。重复目标是幂等的。
• 当面板弹性分配打开时，MainChat 会持续回流或 关闭，然后保持在设定的客户端宽度；窗口没有变化。 当固定窗口对于面板和可读聊天来说太窄时，聊天 可能会回流低于其 360px 目标。
• 本机窗口和侧边栏调整大小不会夹紧或重写面板。本地人 边缘仅通过回流调整 MainChat 的大小。
• Maximized/fullscreen 不受影响； display/work-area 更改协调 窗口边界正常。在一个不变的工作区域内进行普通移动不会 不重新应用几何图形。持久的基边界是用户的窗口大小 （预订始终为 0）。
• 后台会话工件永远不会更新可见面板。

以下手势仍为未来的里程碑保留：

• 拖动 project/session 项目来分配手动订单
• 文件拖入输入框仍未处理；剪贴板 file/image 粘贴 使用下面的会话临时参考流程

8. 2 规格保留

实施 drag/drop 时，应应用以下模式：

• 拖动手柄在悬停时必须可见（没有不可见的拖动可供性）
• 在悬停期间放置带有重音边框的目标突出显示
• 使用 Esc 键取消拖动
• 拖动反馈：源上不透明度 0.5，目标上强调轮廓

8a。输入框自动完成和剪贴板文件（D123–D125、D197）

8a.1 触发器

• / 仅当它是输入的第一个字符时才打开命令模式 并且光标仍在第一个标记内（尚未输入空格）。 命令名称后的空格关闭菜单；参数是自由文本。
• 当包含光标的标记以 @ 开头时，@ 打开文件模式 @ 之前的字符是输入开始、空格或其中之一 pi 分隔符（"、'、=）。查询是 @ 和 光标；包含 / 的查询跨路径段匹配。引用了一个 代币 (@"…) 在收盘报价之前被视为一种代币。
• 粘贴文本永远不会打开菜单，除非插入符号落在有效的区域内 触发令牌。
• 文件结果通过仅渲染叶名称（带有 目录尾随 /）。完整的相对路径仍然可用 行工具提示和可访问的名称。接受文件会创建一个压缩文件 由完整的 entry.path 支持的参考；接受目录保留 文本区域中的完整文字路径，以便可以继续进行更深入的补全。

8a.2 参考芯片和剪贴板文件

• 包含一个或多个 OS File 对象的粘贴在 文本区域；纯文本粘贴保持原生。
• 传输字节时，文本区域是只读的并公开 aria-busy="true"；发送和自动完成控件被禁用。
• Electron main 在原始会话的暂存下保存有界字节 root 并返回唯一的绝对路径以及经过清理的原始叶名称。 输入框保持可见文本不变，附加叶子名称参考 按剪贴板顺序排列，然后恢复文本区域选择和焦点。
• 如果家庭输入框没有活动会话，它会创建或重用之前的会话 写作。失败会使现有草稿保持不变并显示错误 正常的Toast表面。
• 芯片删除按钮仅删除草稿参考并恢复文本区域 焦点；它不会急切地删除会话临时字节。退格键 空文本区域会删除最近的活动引用。
• 仅供参考的草稿启用发送。在发送之前，有效的参考文献是 附加在可见文本之后并使用规范相对或序列化 绝对路径和现有的空白引用。成功发送清除 两者；失败或拒绝的派送保留两者。引用是会话范围的 并且永远不要跨越工作空间的变化。
• 接受的调度保留内存中的 session/turn-scoped 副本 仅在未答复时显示可见文本和结构化参考 智能停止可以 撤消发送。该撤消操作将恢复原始芯片顺序和标签；它 从不解析序列化的 @path 文本。一旦回复内容开始，中止就会继续 部分抄本，不恢复草稿。

8a.3 打开时的键盘

• ↑/↓ 以环绕方式移动突出显示； Home/End 留在文本区域。
• Enter / Tab 接受突出显示的项目；菜单时 Enter 永远不会发送 有一个突出显示的项目（该项目位于输入发送设置之前，该设置 否则保持其行为）。
• Escape 仅关闭菜单 - 它优先于输入框的菜单 “清除输入或模糊”转义并且不得传播到覆盖处理程序。
• 任何其他适当的打字重新过滤器；零匹配表现为闭合。

8a.4 IME（第一规范IME规则）

• 所有自动完成按键处理均位于标准防护装置后面 （isComposing || keyCode === 229）。
• 在主动合成期间，触发检测器既不打开、更新， 也不关闭菜单；状态重新评估 compositionend。
• 输入确认 IME 候选者从不发送且从不接受菜单 项目；候选导航期间的 ↑/↓ 属于 IME。

8a.5 关闭和聚焦规则

• 关闭：鼠标按下之外、文本区域模糊、删除过去的触发器 字符、会话或工作区切换，接受项目（@dir/ 除外） 延续，这使菜单在更深层次的查询上保持打开状态）。
• 在菜单的整个生命周期中焦点保持在文本区域（输入保留 覆盖）;菜单永远不会成为焦点陷阱，也不会抢走插入符号。

9. 滚动行为

9. 1 脚本滚动

• 默认：固定时在流中自动滚动到新内容的底部
• 第一次向上滚动会暂停自动滚动并显示 “↓滚动到底部”按钮；排队流或调整大小跟随工作不得 扭转该运动
• 用户发送/重试/重新生成：重新固定，隐藏跳转控件，并将最新内容放置在布局阶段，以便新的回合可见，而无需历史记录顶部的闪烁；后续的持久化行和流式传输行继续遵循底部
• 滚动到底部按钮：位置固定在转录区域的右下角，偏移 12px
• 向上滚动释放跟随模式后按钮立即出现
• 单击按钮：滚动到底部，恢复自动滚动
• 按钮在底部时消失

9. 1a 侧边栏项目路径和打开文件夹

• 悬停或聚焦保留的项目标题会显示完整的绝对路径。
• 截断的项目名称在行中仍然可见；完整路径是 仅 tooltip/accessible-description 并且从不强制水平滚动。
• 右键单击项目行或打开其溢出菜单会显示 Open 文件夹作为项目操作。对话溢出不再带有该内容 行动。
• 选择打开文件夹打开系统文件中的项目目录 管理器而不更改活动会话记录。

9. 2 侧边栏滚动

• 独立的会话主体有五个紧凑的行和卷轴 当存在附加会话时在内部。
• 保留的项目组占据剩余的侧边栏高度并滚动 单独的区域。这两个区域都独立于页脚和主要区域 导航。
• 侧边栏没有水平滚动
• 滚动指示器使用平台的微妙覆盖处理，无需 改变任一区域的宽度。

9. 3 设置滚动

• 设置内容在主区域内独立滚动
• 左侧导航（设置部分）是粘性的，不滚动

10. 减少运动

10. 1 政策

所有动画都必须遵循 prefers-reduced-motion: reduce：

1. **抑制：**流脉冲、expand/collapse 转换、下拉幻灯片、悬停颜色转换
2. **保持（即时）：**状态变化仍然发生（卡状态变化，加载→完成）但没有过渡持续时间
3. 切勿移除： 对焦环、状态颜色、布局定位 - 这些是结构性的，而不是装饰性的

10. 2 实施

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

这并不能阻止状态改变——它使状态改变变得即时。

10. 3 本文档中受影响的模式

图案	正常	减少运动
流脉冲	左边框上的重音脉冲	静态重音边框（无脉冲）
工具卡 expand/collapse	200ms 过渡	即时切换
悬停状态转换	150ms背景变化	瞬间变色
启动水花	品牌启动 + 进度，最短停留时间然后淡出	即时静态飞溅，无条形运动，即时显示
对话框/搜索输入	通过运动令牌覆盖-in + 表面-in	接近零持续时间输入
滚动到底部按钮淡入	150ms 不透明度	即时出现
Toast滑入式	200毫秒幻灯片	即时出现
Modal/dialog 输入	300ms 淡入淡出+缩放	即时出现
通知弹出框输入	menu-scale/fade 代币	即时出现

10. 4 编程滚动

• 会话激活使用立即布局阶段底部位置，因此 第一个可见帧已经稳定在最新记录。
• 跳转到最新和小地图导航仅在操作系统时才使用平滑滚动 没有请求减少运动。
• 启动跟随使用立即布局阶段更新，然后 帧合并即时跟随；它不会开始重叠平滑滚动 令牌组的动画。
• 手动向上移动会先取消排队的固定跟随帧 恢复之前的底部位置。关注跨内容发布的内容 增长，直到视口向下滚动到底部或底部 48px 以内 显式的启动/跳转到最新操作会重新固定它。
• 调整观察者安排工作的大小，并且从不同步测量每个 来自他们的回调的记录行。

11. 验收标准

1. §1中的所有键盘快捷键均有效且不与系统快捷键冲突 2.回车发送消息； Shift+Enter 在输入框中插入换行符
2. Abort 立即取消正在运行的回合和挂起的权限，无需确认对话框 4.长内容（>50行消息，>10行参数，>20行结果）默认通过展开链接折叠
3. 超过 256KB/4000 行的工具结果显示按照 D033 的截断标记 6.权限中断插入内联卡，禁用composer，显示倒计时，解决后重新启用
4. 用于短暂后台操作的Toast；用于特定于上下文的失败的内联错误
5. 会话切换、消息发送、权限解析、中止后焦点返回到composer 9.后台消息、工具、完成、权限事件永不改变 活动的 session/project/page 或键盘焦点；并发许可 请求在其原始记录中保持独立可操作性， 和后台工件仅更新其会话保留的工作面板 上下文 9a.创建新会话或切换到非运行会话返回 即使另一个会话仍然处于空闲状态，composer 也会恢复到其空闲发送状态 流式传输；目标会话自己的运行状态单独决定 send/abort 按钮
6. 聚焦环仅在 focus-visible 上可见，2px 重音偏移 2px 11.命令面板捕获焦点；逃脱回到之前的焦点
7. 所有动画均遵循 prefers-reduced-motion: reduce — 状态变化是即时的，没有装饰性动作 13.Project/session行支持无损pin/archive，独立 项目崩溃，以及记录的面向用户的排序模式
8. Shell chrome 不会创建意外的文本选择，同时可编辑 控件和 transcript/code/tool 内容保持可选择和可复制
9. 保留的项目选项卡在重启后仍然有效；激活其中一项会更改所选内容 不重定向后台会话工具根的 shell 工作区
10. Drag/manual重排序未实现； manual 仍保持兼容性 价值和未来阻力模式遵循§8
11. 已完成和失败的回合在持久收件箱中仅出现一次； 中止的回合永远不会出现
12. All/Unread、标记为全读、清除、行激活、Escape/focus 恢复以及 arrow/Home/End 键盘导航的行为如 §1.7 中所述
13. 本机通知仅在主窗口未聚焦且 它们的激活使窗口聚焦并打开相应的会话
14. 流式消息更新保持在聊天渲染边界内；外壳 导航、编辑器、已完成的行和工作面板内容不会重新呈现 仅仅因为当前助手消息附加了内容
15. 本机窗口边缘调整大小通过回流更改 MainChat，而不压缩 固定工作面板；分隔符提交更新提交的首选宽度， 而分隔线取消恢复之前的宽度（ADR 0033）