chore: prepare Desktop 0.16.2 release

Reviews now snapshot only messages in a terminal state (complete or error) and finished tasks, so a reply still streaming when the review starts waits for the next review instead of changing under it. A frozen source that still changes is skipped for that run and left for the next review, replacing the re-review at the latest version and its 200-source cap. The review period picker gains an All time option.

.github/workflows/pages.yml

@@ -7,6 +7,8 @@ on:
       - main
     paths:
       - 'sites/**'
+      - 'package.json'
+      - 'package-lock.json'
       - '.github/workflows/pages.yml'
 
 permissions:
@@ -29,8 +31,15 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+
       - name: Validate website
         run: |
+          npm ci --ignore-scripts
+          npm run docs:build
           node sites/scripts/validate.mjs
           node --check sites/app.js
 

.gitignore

@@ -6,6 +6,8 @@ shareserver/build-server/
 coverage/
 /temp/
 .vite/
+sites/docs-dist/
+sites/docs/.vitepress/
 .runtime-resources/
 .remote-runtime-resources/
 .agent-resources/

FEATURES.md

@@ -983,9 +983,23 @@ records are listed separately and do not introduce another feature status.
 
 ### Open source, builds, and releases
 
-- The current Desktop candidate is `0.15.13`; Agent candidate `0.15.6` requires Desktop `0.15.13`, with
+- The current Desktop candidate is `0.16.2`; Agent `0.15.6` remains paired with Desktop `0.16.2`, with
   OpenCode pinned to `1.18.29` and Continue to `1.5.47`. Publication status follows the independent
   Desktop and Agent release channels.
+- Desktop `0.16.2` adds an all-time Supervisor review range and waits for messages and tasks to
+  settle before including them in a review. It also improves Magic Notes action labels, contains
+  terminal IME composition layout, and upgrades the database to schema 63.
+- Desktop `0.16.1` smooths the message-to-composer transition: messages extend to the composer
+  outline before fading, and light/dark theme backgrounds and focus boundaries no longer create
+  an abrupt solid band above the input. Schema remains unchanged.
+- Desktop `0.16.0` moves expert and team-role selection into the composer and persists the
+  selection per conversation. Historical messages retain the role used for their request,
+  including after a role is renamed or removed; schema remains unchanged.
+- Desktop `0.15.14` restores continuation for legacy Supervisor reviews that failed because a
+  source changed or was removed. Sources that keep changing are re-frozen only within a bounded
+  number of attempts and then omitted so the review can finish while retaining surviving progress.
+  Settings categories also show matching icons to make the settings page easier to scan. Schema
+  remains 62.
 - Desktop `0.15.13` / Agent `0.15.6` move desktop business SQLite ownership into
   one typed storage utility process and keep Remote Runtime changes coordinated.
   Assistant, Knowledge, attachments, runtime bindings and ledgers retain their

FEATURES.zh-CN.md

@@ -159,7 +159,11 @@
 ### 开源、构建与发布
 
 - Desktop `0.15.3` 修复本地直连手动压缩和请求有效期间的工具授权，区分取消与失败并去除重复提示，优化侧栏搜索、注册成功后的快捷键提示及笔记操作布局，减少启动和存储中的重复处理，并精简重复依赖及开发文件。不宣称整体渲染性能已显著提升；Office 实时编辑仍为设计。证据见[0.15.3 发布准备](./docs/development/release-preparation-0.15.3.md)。
-- 当前 Desktop 候选为 `0.15.13`，Agent 候选为 `0.15.6`、最低要求 Desktop `0.15.13`，OpenCode 固定为 `1.18.29`、Continue 为 `1.5.47`；正式发布状态以独立发布渠道为准。
+- 当前 Desktop 候选为 `0.16.2`，Agent 保持 `0.15.6`、最低要求 Desktop `0.16.2`，OpenCode 固定为 `1.18.29`、Continue 为 `1.5.47`；正式发布状态以独立发布渠道为准。
+- Desktop `0.16.2` 增加全部时间的监督回顾范围，并等待消息和任务完成后再纳入回顾；同时改进 Magic Notes 操作标签、修复终端输入法布局，数据库升级到 schema 63。
+- Desktop `0.16.1` 平滑消息与输入框的过渡：消息会延伸到输入框轮廓前再淡出，浅色和深色主题的背景与焦点边界也不再在输入框上方形成突兀的实色横带；schema 保持不变。
+- Desktop `0.16.0` 将专家和团队角色选择移入输入框，并按会话保存选择。历史消息保留请求当时使用的角色，即使角色之后被重命名或删除也不会丢失这项上下文；schema 保持不变。
+- Desktop `0.15.14` 恢复因来源变化或移除而失败的历史监督回顾的继续操作。持续变化的来源只会在有限次数内重新冻结处理，之后自动省略，使回顾能够结束并保留其余来源的进度；设置分类增加对应图标，方便快速查找；schema 仍为 62。
 - Desktop `0.15.13` / Agent `0.15.6` 将桌面业务 SQLite 的唯一 owner 移到一个类型化 storage utility process，Assistant、Knowledge、附件、运行绑定和账本保留原路径及事务语义。直连模型在工具失败后可继续，分页输出、Magic Notes 标签、监督来源别名、设置直达预加载和文件元数据同步修正；schema 仍为 62。storage/监督 focused 编排已通过，但 C01–C07 并发验收矩阵、跨平台 storage 进程安装和低端机对照仍是明确后续门槛，不作通用性能承诺。见[发布准备](./docs/development/release-preparation-0.15.13.md)。
 - Desktop `0.15.12` / Agent `0.15.5` 增加 Telegram 私聊配置（真实 Bot 与模型完整验收仍待完成）和本地日期自定义回顾。监督图谱/来源按需读取、索引 Worker 查询、摘要缓存和选择列表窗口化减少重复工作，最终发布仍可阻塞 Main；未发布回顾省略已删除会话并重算受影响批次，历史结果保留。临时模型失败最多多试一次，可能增加费用；远程启动取消、通道交付、长消息展开状态及历史缺失时长得到修正。schema 62 增加通道支持和查询索引，升级前备份完整数据目录，降级需恢复备份。两个独立开发审计阶段共记录 15 次外部文本请求，本次发布准备没有新增；精确源码 CI 与原生打包仍为门槛。见[发布准备](./docs/development/release-preparation-0.15.12.md)。
 - Desktop `0.15.11` / Agent `0.15.4` 移除 Ask/Execute 与通用工具审批，旧 Ask 会话也不再有产品级只读边界。schema 60 和 Runtime 设置 22 清理退休元数据，升级前备份完整数据目录，降级需恢复备份；远程需配套 runtime/acp 6 工件。工作区导入、文件时间排序、会话图片发现和远程专家保存随成果页移除一起提供，不删除既有成果。执行时长按运行状态计时、不补算旧历史，OpenCode 缓存率采用完整输入量。回顾历史、响应布局及螺旋实际区间着色保留未归属事件与中性空档；汇总读取和回顾初始化减少限定路径 I/O，不承诺普遍提速。开发证据含无模式执行与专家图片保存共 25 次真实文本请求，不是本次发布准备新调用或图片生成；精确候选 CI、签名包、公开验证和跨版本活动操作恢复与这些检查分开记录。见[发布准备](./docs/development/release-preparation-0.15.11.md)。

UI-DESIGN.md

@@ -163,7 +163,7 @@
 - 页面顶部和底部内边距默认为 `32px`。
 - `master-detail` 的左栏建议为 `280px` 至 `360px`，右栏占剩余空间。分隔线和滚动容器属于壳层，不由内容卡片模拟。
 - 聊天输入区可以粘附在 `reading` 壳层底部，但消息内容和输入区必须共享同一阅读宽度。
-- 输入区顶部向消息区延伸 `--space-4`（16px）的透明到 `--surface-raised` 渐变，柔化消息裁切边缘；渐变不占布局空间、不拦截鼠标事件，并随主题切换。
+- 输入区外层不铺整块背景、不画横向分隔线。输入区以上内边距的高度向上叠入消息区，输入框上方保留 `--space-4`（16px）的透明到页面底色渐变，渐变终点对齐输入框上缘，让滚动的消息一直延伸到输入框轮廓前再淡出；输入框上缘以下才使用实色底；渐变位于输入框之下、不拦截鼠标事件，并随主题切换。输入框上缘只保留自身 1px 描边，不加向上的阴影，避免与渐变终点叠成粗边界。
 - 宽表格可在 `dashboard` 内容区内部横向滚动，不得撑宽整个应用窗口。
 
 ## 5. 信息层级

docs/development/release-preparation-0.15.14.md

@@ -0,0 +1,25 @@
+# Desktop 0.15.14 发布准备
+
+日期：2026-10-09。基线 `v0.15.13`，候选源码 `8f1b6007986f31fb5e2a80e80021602a13fa20a2`。
+本候选只更新 Desktop；Agent 保持 `0.15.6`，不创建新的 Agent 标签。标准六平台 Desktop，
+不含 LoongArch。
+
+## 范围与兼容性
+
+- 恢复旧版因监督来源变化或移除而失败的历史回顾的继续操作。
+- 来源在回顾期间变化时，在有限次数内重新冻结处理；持续变化的来源之后省略，
+  已删除、归档或不可用来源沿用既有省略规则，其他来源继续保留进度。
+- 保留暂停、失败、取消和已保存批次的监督活动状态及项目范围、来源处理规则。
+- 设置分类显示对应图标，帮助用户更快找到各类设置。
+- 不新增数据库 schema，继续使用 schema 62；Agent、runtime/acp、wire 和运行时锁版本不变。
+
+## 验证边界
+
+本候选包含监督存储、Worker、服务和 Renderer 回归测试，以及历史失败回顾继续操作的
+界面覆盖。完整并发验收矩阵、跨平台存储进程安装和其他未完成验收不在本候选中宣称通过。
+
+## 发布门槛
+
+完成发布说明校验、测试、三套 typecheck 和 lint 后，推送候选到 `origin` 与 `github`，
+要求精确候选的主分支 CI 和生产构建通过，再由用户确认后创建不可变的 `v0.15.14` 标签。
+本轮不构建或发布 LoongArch，也不创建新的 Agent 标签。

docs/development/release-preparation-0.16.0.md

@@ -0,0 +1,23 @@
+# Desktop 0.16.0 发布准备
+
+日期：2026-10-09。基线 `v0.15.14`，候选源码为本次发布准备提交。
+本候选只更新 Desktop；Agent 保持 `0.15.6`，不创建新的 Agent 标签。标准六平台 Desktop，
+不含 LoongArch。
+
+## 范围与兼容性
+
+- 专家和团队角色选择移动到 Composer 输入框顶部，发送前更容易发现。
+- 角色选择按会话保存，切换会话不会带入其他会话的选择。
+- 历史消息保留请求发送时使用的角色，即使角色后来重命名或删除，历史上下文仍可识别。
+- 不新增数据库 schema，Agent、runtime/acp、wire 和运行时锁版本不变。
+
+## 验证边界
+
+本候选包含 Composer、会话选择状态、历史消息元数据和角色选择的回归测试。
+完整跨平台安装、远程 Host 和未覆盖的整包验收仍以 CI 与发布工作流结果为准。
+
+## 发布门槛
+
+完成发布说明校验、测试、三套 typecheck 和 lint 后，推送候选到 `origin` 与 `github`，
+要求精确候选的主分支 CI 和生产构建通过，再由用户确认后创建不可变的 `v0.16.0` 标签。
+本轮不构建或发布 LoongArch，也不创建新的 Agent 标签。

docs/development/release-preparation-0.16.1.md

@@ -0,0 +1,18 @@
+# Desktop 0.16.1 发布准备
+
+日期：2026-10-10。基线 `v0.16.0`，候选源码包含 `d9dcb65d` 和 `c7f09e1e`
+两个 Composer 视觉修复提交。本候选只更新 Desktop；Agent 保持 `0.15.6`，
+不创建新的 Agent 标签。标准六平台 Desktop，不含 LoongArch。
+
+## 范围与兼容性
+
+- 消息内容延伸到 Composer 输入框轮廓前再淡出，不再被输入区上方的实色区域提前截断。
+- 浅色和深色主题使用匹配的消息到输入框渐变，输入框焦点边界不再形成粗边。
+- 滚动到底部按钮保持与新的输入区过渡相配的可见位置。
+- 不新增数据库 schema，Agent、runtime/acp、wire 和运行时锁版本不变。
+
+## 发布门槛
+
+完成发布说明校验、测试、三套 typecheck 和 lint 后，推送候选到 `origin` 与 `github`，
+要求精确候选的主分支 CI 和生产构建通过，再创建不可变的 `v0.16.1` 标签。
+本轮不构建或发布 LoongArch，也不创建新的 Agent 标签。

docs/development/release-preparation-0.16.2.md

@@ -0,0 +1,24 @@
+# Desktop 0.16.2 发布准备
+
+日期：2026-10-10。基线 `v0.16.1`，候选源码包含 `12a02912`、`ba308520`
+和 `f2f4c127` 三个提交。本候选只更新 Desktop；Agent 保持 `0.15.6`，
+不创建新的 Agent 标签。标准六平台 Desktop，不含 LoongArch。
+
+## 范围与兼容性
+
+- 监督回顾增加从最早记录到当前时间的全部时间范围。
+- 监督回顾只读取已完成消息和任务，实时生成中的内容等待完成后再进入回顾。
+- Magic Notes 操作入口增加文字标签，次要更多操作按需显示。
+- 终端输入法组合区域保持在终端边界内。
+- 数据库 schema 从 62 升到 63；Agent、runtime/acp、wire 和运行时锁版本不变。
+
+## 升级须知
+
+首次启动会执行 schema 63 数据库升级。升级前关闭应用并备份完整数据目录、
+相邻 `notes/` 和设置文件。旧客户端回退需要恢复升级前备份。
+
+## 发布门槛
+
+完成发布说明校验、测试、三套 typecheck 和 lint 后，推送候选到 `origin` 与 `github`，
+要求精确候选的主分支 CI 和生产构建通过，再创建不可变的 `v0.16.2` 标签。
+本轮不构建或发布 LoongArch，也不创建新的 Agent 标签。

docs/features/chat-history-navigation/README.md

@@ -0,0 +1,17 @@
+# 聊天历史导航
+
+聊天历史导航负责长会话的连续滚动、窗口化渲染，以及后续的对话 minimap。第一阶段先取消向上滚动时每次增加 80 条消息的产品限制，保留已有的消息窗口化机制；第二阶段再评估 minimap。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [产品需求](./prd.md) | 用户问题、范围、验收和非目标 |
+| [技术设计与测试计划](./technical-design.md) | 当前实现边界、实验分组、性能指标和执行步骤 |
+| [实施进度](./progress.md) | 已验证事实、命令、结果和遗留问题 |
+
+## 术语
+
+- **历史窗口**：允许滚动访问的消息范围。第一阶段扩大为当前已加载会话的全部消息。
+- **DOM 窗口**：实际挂载消息组件的范围。继续由消息高度估算和最多约 60 条挂载消息控制。
+- **minimap**：对话右侧的轻量纵向全局导航概览，不等于完整渲染所有消息。

docs/features/chat-history-navigation/prd.md

@@ -0,0 +1,34 @@
+# 聊天历史连续滚动
+
+## 用户问题
+
+长会话向上阅读时，当前界面每次只增加 80 条消息，并在顶部显示“加载更早的消息”控件。这个控件把连续滚动切成多个操作，用户无法像 VSCode 一样直接拖动滚动条或连续滚到会话顶部。
+
+## 目标
+
+- 已加载的当前会话可以从底部连续滚动到顶部。
+- 消息仍按可见范围挂载，长会话不会因为取消 80 条限制而一次性创建全部消息组件。
+- 滚动位置、锚点、消息展开状态和流式输出行为保持稳定。
+- 为后续 minimap 提供完整的消息索引和可定位滚动范围。
+
+## 范围
+
+- 取消真实聊天会话的 80 条历史窗口增量。
+- 保留现有消息窗口化、占位高度、滚动锚定和按需挂载。
+- 对 100、500、2,000、10,000 条消息进行功能和性能对比。
+- 记录 minimap 的下一阶段性能测试入口，但本阶段不实现 minimap。
+
+## 非目标
+
+- 不改变未打开会话的摘要加载策略。
+- 不要求一次从数据库加载所有未加载的会话历史。
+- 不取消最多约 60 条消息组件的 DOM 窗口化限制。
+- 不在本阶段加入 minimap、消息摘要接口或新的 IPC。
+
+## 产品验收
+
+- 打开一个已加载历史的会话后，顶部不再出现“加载更早的消息”按钮。
+- 用户可以连续滚动到第一条消息，滚动位置不会因消息挂载或高度测量而跳动。
+- 2,000 条消息会话仍保持窗口化渲染，实际挂载消息数量维持现有上限附近。
+- 流式输出、输入、消息展开、附件和工具输出行为没有回归。
+- 若会话只有摘要，仍按现有逻辑按需加载完整历史。

docs/features/chat-history-navigation/progress.md

@@ -0,0 +1,17 @@
+# 实施进度
+
+## 2026-10-08
+
+- 已确认 80 条限制由 `ChatHistoryPane` 的 `messageRenderBatchSize` 和 `revealEarlierMessages` 驱动。
+- 已确认消息窗口化仍以高度占位和最多约 60 条挂载消息为上限。
+- 已建立基线、本阶段和 minimap 阶段的对比测试计划。
+- 已将生产会话接线改为直接使用当前已加载消息总数，保留 DOM 窗口化。
+- `ChatHistoryPane` 与 `ChatTimeline` 定向测试通过：58/58。
+- 改动文件定向 web 类型检查和 lint 通过。
+- `npm run build:bundle` 通过。
+- `npm run perf:app` 通过。本次 B 组测量中，长会话打开交互延迟为 86.9 ms，长会话滚动帧间隔 p95 为 16.9 ms、无长任务；流式输入场景帧间隔 p95 为 16.9 ms，输入延迟 p95 为 17.1 ms。
+- B 组第二次运行仍通过：长会话打开交互延迟为 46.9 ms，长会话滚动帧间隔 p95 为 16.8 ms、无长任务；流式输入场景输入延迟 p95 为 19.1 ms。
+- App 测试通过 341/349；剩余 8 个失败集中在既有图片附件异步场景，未出现聊天历史窗口相关失败。
+- 全局 `npm run typecheck` 仍被既有 `src/main/desktop-storage-electron-fixture.ts:215-217` 类型错误阻断；全局 lint 仍包含生成的 VitePress cache 错误。
+- A 组临时恢复后连续两次在 composer 初始化阶段超时，未进入性能场景，因此没有有效 A 组数据，不能据此推导 A/B 数值差异。B 组代码已恢复并重新完成 bundle、定向类型检查、定向 lint 和 58/58 聊天窗口测试。
+- 下一步实现 minimap 前仍需先修复性能驱动在 A 组接线下的 composer 初始化问题，或建立不依赖 composer 的长会话专用 benchmark，再进行严格 A/B 测量。

docs/features/chat-history-navigation/technical-design.md

@@ -0,0 +1,52 @@
+# 技术设计与测试计划
+
+## 当前边界
+
+`ChatHistoryPane` 当前有两层机制：`messageRenderBatchSize = 80` 控制向上滚动时可访问的历史窗口；`maxRenderedMessageCount = 60` 控制实际挂载的消息组件。第一阶段只移除前者在生产接线中的作用，保留后者以及消息高度占位和锚点恢复。
+
+已加载历史的消息数组仍由会话 store 提供。带 `messageSummary` 的会话继续先显示加载状态，由现有 `loadHistory` 路径取得完整历史。这样本实验测量的是滚动历史窗口的变化，不混入存储或 IPC 改造。
+
+## 实验分组
+
+| 组别 | 历史窗口 | DOM 窗口 | minimap |
+| --- | --- | --- | --- |
+| A 基线 | 每次增加 80 条 | 保留 | 无 |
+| B 本阶段 | 当前已加载消息全部可访问 | 保留 | 无 |
+| C 下一阶段 | 当前已加载消息全部可访问 | 保留 | 有 |
+
+A 组保留在组件级回归测试中；B 组是当前生产实验；C 组待 B 组稳定后实现。
+
+## 功能测试计划
+
+- 100 条消息：打开会话后直接滚到第一条，不出现加载按钮。
+- 500 条消息：从底部连续滚到顶部，检查消息顺序、首尾消息和滚动位置。
+- 2,000 条消息：在中部、顶部和底部来回滚动，确认高度占位和锚点不跳动。
+- 消息交互：展开 reasoning/tool details、输入答案、选择文本、打开附件后滚出再滚回，确认状态保留。
+- 流式消息：生成过程中滚动、暂停跟随底部，再回到底部，确认自动跟随行为不变。
+- 摘要会话：打开只有 `messageSummary` 的会话，确认仍然先加载历史，不把摘要误当作完整消息。
+
+## 性能测试计划
+
+每个规模至少运行 5 次，分别记录冷打开和已经打开后的滚动表现。低端机模拟沿用已有性能测试配置，结果记录中注明运行环境。
+
+记录指标：
+
+- 会话打开到首屏可交互的耗时；
+- 首次滚到顶部的耗时；
+- 连续滚动期间长任务和掉帧；
+- Renderer 内存峰值和测试结束后的回收情况；
+- 实际挂载消息数量；
+- 流式输出时输入延迟。
+
+通过条件：B 组功能测试全部通过，实际挂载消息数量仍受窗口上限控制；相对 A 组没有明显的输入、流式输出或滚动回归。若 B 组稳定，再以同一批数据实现 C 组并做增量对比。
+
+## 验证命令
+
+```text
+npm exec vitest run src/renderer/src/ChatHistoryPane.test.tsx src/renderer/src/ChatTimeline.test.tsx
+npm run typecheck
+npm run lint
+npm run perf:app
+```
+
+`perf:app` 的具体参数和输出以仓库脚本当前实现为准；无法在自动化环境观察的内存和掉帧指标，需要补充 Electron 手工记录。

docs/pr-articles/2026-09-26-unreleased/article.md

@@ -1,388 +1,77 @@
-# GoodBuddy 更新：故事图谱、Obsidian接入、Runtime原生终端
+# GoodBuddy 更新：故事图谱、Telegram 与 Obsidian 接入
 
-> **编辑标注说明（对外发布前删除）：** 本稿汇总桌面版 0.13.8 至 0.15.11，以及其后截至 `e50ca6d1` 的已提交变化，更新于 2026-10-05。所述功能与修复均已开发完成并提交，验证及发布归属另行标注；原故事线概念图仅作示意，待换为生产界面截图。“待补图”表示缺少可发布素材，“待替换”表示发布信息未核验，“待核对”表示发布前需要确认的行为。本文是宣传草稿，尚未对外发布。
+> **编辑标注说明（对外发布前删除）：** 本稿汇总桌面版 0.13.8 至 0.15.13，以及截至 `3556df88` 的已提交变化，更新于 2026-10-09。本文所述功能均已完成并提交；截图、下载信息和正式发布链接属于发布材料，另行补齐。原故事线概念图仅作示意，发布前替换为生产界面截图。
 
-GoodBuddy 这一轮更新围绕工作记录的整理与使用展开：监督者把分散的事件归入持续发展的故事，从中整理带有来源和适用条件的经验，供人和助手在后续工作中查阅。笔记连接支持保存聊天正文、返回原会话，以及在聊天中读写本机 Obsidian 笔记。本地项目还可以从输入区打开 Continue、OpenCode 原生终端或 DS Web 客户端，沿用当前项目与模型配置。
+GoodBuddy 这一版完成了三条连接：用故事图谱整理持续推进的工作，用 Telegram 在桌面之外发起对话，用 Obsidian 连接已有的本地笔记。故事图谱帮助人和助手回看决定、依据与后续变化；Telegram 适合在手机或其他设备上继续处理文字请求；Obsidian 则让原有笔记仓库可以直接参与对话。
 
-本文接续上一份画布笔记与文档处理更新稿，覆盖 0.13.8 起的实际增量。这次还加入了智能心跳、笔记标签、会话图片保存、Telegram 私聊和工作区文件导入。项目与会话集中到同一个菜单，提问和执行任务也无需再切换工作模式。远程统一执行与文件导入建议配套 Desktop 0.15.11 和 Agent 0.15.4，请先升级桌面端，再更新 Host 环境；最新远程启动修复还需包含后续提交的 Agent。
+当前配套版本为 Desktop `0.15.13` 和 Agent `0.15.6`。远程项目使用这些能力前，请先升级桌面端，再更新 Host 环境。
 
-> **【待替换 R01｜版本与体验入口】** 最新已核查桌面 tag `v0.15.11` 与 Agent tag `agent-v0.15.4` 均指向 `78afec77`。本轮检查 `9527402..e50ca6d1`，共 60 个提交；Telegram 私聊、历史耗时缺失提示、自定义回顾日期及最新运行修复位于这些 tag 之后，发布版本待确认。对外发布前核验公开安装包、发布日期、下载地址和完整更新日志链接，并在此补入。桌面 0.13.14 的发布失败后由 0.13.15 承接。
+> **【发布信息待补】** 正式发布前补入发布日期、公开安装包、下载地址和完整更新日志链接。本文所述功能已经完成，发布信息待补不代表功能处于开发中。
 
-**升级前，请先关闭应用并备份完整用户数据。** 数据库、设置和相邻的 `notes/` 目录需要成套保留；如有 WAL 文件，也应一并备份。当前核查提交的助理数据库格式为 61，0.15.11 标签对应格式为 60；升级后旧客户端不能直接打开新版数据库，回退需要升级前的备份。大库首次转换可能需要等待。高频本地保存调整了磁盘同步策略，断电时可能丢失最近尚未同步的写入。
+## 故事图谱：从工作记录中看清一件事如何发展
 
-## 新增功能
+### 工作回顾留下进展和依据
 
-### 监督者：从工作记录中整理进展，查看每条结论的依据
+监督者可以按全局或项目范围回顾最近一天、数天或指定日期内的工作记录，整理出工作总结、变化和未解决事项，并按故事列出推进、新出现和结束的内容。回顾结果会保留范围与生成时间，方便之后回看。
 
-项目讨论持续一段时间后，可以打开“监督者”的“工作回顾”，选择全局或一个项目，再选择最近 1 天、7 天、30 天、自定义最近天数或起止日期。指定日期按本地时区包含结束日全天，结束日为今天时截至发起回顾的时刻。回顾会整理工作总结、本次变化和未解决事项，并按故事列出这段时间的推进、新出现与结束的事项，以及形成或用上的经验。点击故事或经验，可以进入图谱查看依据；历史结果保留各自的范围和生成时间，方便回看。
+每条结论都可以继续追溯到事件、实体、关系和来源正文。打开来源后，可以检查模型依据的是哪段讨论，再决定是否确认、改名或调整关系。
 
-监督者默认关闭，在应用中心启用后即可手动回顾，无需先建立自动计划。当前分析来源包括范围内的用户与助手消息、任务标题与当前状态，以及消息中已有的知识引用片段。它不会自动遍历全部笔记、整个知识库或附件原件。
+### 故事、经验和时间螺旋
 
-> **【待补图 01｜必补｜工作回顾结果】** 在隔离演示项目中通过正常聊天和任务操作形成公开、虚构的工作记录，运行一次真实回顾。截图同时展示范围、时间和实际生成的总结、未解决事项；不能用预置答案冒充模型结果。计划文件：`assets/01-work-review.png`。
->
-> 建议图注：按项目回顾近期讨论与任务，查看进展和仍待处理的问题。
+事件可以归入持续发展的故事，按项目、功能和子线索浏览。用户可以调整故事名称、合并重复故事、移动事件或撤销调整。故事中的经验会保留适用条件、形成依据和后续应用记录，也可以人工编辑、合并或删除。
 
-回顾中的事件、实体与关系可以在“故事线图谱”中查看。选中一个对象，就能检查它的说明、关联和保存的来源正文，再判断模型的归纳是否准确。实体支持确认、改名或撤销，关系可以确认或移除。
-
-这适合检查“某个结论来自哪段讨论”“一个事项与哪些事件有关”。图谱提供平铺和时间螺旋两种浏览方式，时间螺旋按事件时间排列；平铺视图中的节点间距不表示实际时长。历史回顾中的故事分组使用当前保存的故事结构，尚不提供任意时刻的完整状态还原。
-
-> **【待补图 02｜必补｜图谱与来源】** 使用图 01 同一份真实回顾结果，选中事件或实体，展示对应的来源正文。画面应能辨认对象与依据的关联；不使用设计原型代替生产结果。计划文件：`assets/02-story-sources.png`。
->
-> 建议图注：从回顾图谱查看关联对象，并打开保存的讨论依据。
-
-### 故事与时间螺旋：追踪一件事如何持续发展
-
-一项功能往往经过多次讨论、试验和修订。回顾后，相关事件可以归入同一个故事，按项目、功能和子线索逐层浏览；后续有新进展时继续积累，不必每次从零查找。用户可以调整名称、合并重复故事、移动归错的事件，也能撤销调整；移除故事会保留其中的事件。
-
-时间螺旋把这些故事放到连续时间上，便于查看不同工作如何交错推进。同一件事可以隔一段时间再继续，中间的停顿保留下来。螺旋高度对应时间，半径按所选回顾范围内的消息密度变化，不代表实际工时、效率或成果价值；消息按小时汇总，无法还原小时内的精细分布。
-
-实际事件区间和事件点使用主故事的颜色，空白区间与未归属事件保持中性色。历史回顾中尚未归入故事的事件也会保留，可以在“未归属”分组查看；故事分组采用当前关系，不把它当作当时分类的完整还原。
-
-视图支持斜俯视、侧视、俯视和自由视角，可以逐层进入项目、功能与子线索，选中故事或事件查看详情。当前层可显示部分经验及其跨故事应用连线，完整经验列表仍在“经验”页签中查阅。设备无法使用 3D 时，可以切回平铺视图。
+故事图谱提供平铺和时间螺旋两种视图。时间螺旋按事件时间和消息密度展示工作如何交错推进，适合观察停顿、延续和阶段变化；平铺视图适合查看对象之间的关系。设备不适合 3D 浏览时，可以切换回平铺视图。
 
 ![故事线早期概念示意：时间螺旋、跨阶段故事，以及经验的形成依据与后续应用](assets/09-next-storyline-wisdom.png)
 
-*早期概念示意，使用示例数据；不是当前生产界面的截图，实际布局与操作以应用为准。*
+*早期概念示意，使用示例数据；发布前替换为当前版本的生产界面截图。*
 
-> **【待补图 09｜必补｜故事与经验的生产视图】** 原图保留作概念参考。发布前用目标版本的真实回顾结果替换，展示同一故事的事件、经验形成依据与后续应用，并核对平铺和时间螺旋中的选择联动。计划文件：`assets/09-story-experience.png`。
->
-> 建议图注：沿故事查看工作进展，从经验节点核对形成依据与后续应用记录。
+### 助手可以接着既有决定继续工作
 
-### 从故事中整理经验，保留适用条件和依据
+当用户追问“此前为什么选这个方案”或“这项决定后来怎样修改”时，助手可以查询已经保存的故事、经验、事件、实体、关系和回顾结果，再读取相关来源。查询发生在需要时，不会在每次对话中自动注入整张图谱。
 
-故事积累到一定规模，并出现新的决定、变化或里程碑后，监督者可以从事件摘要中归纳经验，保存适用条件、边界和形成依据。自动归纳的内容有明确标记，用户可以编辑、合并或删除，再回到原讨论核对。
+输入区可以单独控制当前会话是否允许访问故事图谱。查询默认使用当前项目，也可以指定全局或项目集合；故事图谱工具只读取已有记录，不会因为一次查询重新运行回顾或修改图谱。
 
-后续回顾还可以记录某条经验在哪些事件中得到应用。应用记录会核对事件是否晚于最早形成事件的起始时间，并与至少一个形成事件涉及共同实体；这些记录仍是模型对历史的归纳，需要结合来源判断，不能据此断定经验已经产生效果。助手可以查阅这些经验，为后续工作提供参考。
+### 智能心跳持续整理变化
 
-### 助手可以查阅故事图谱，接着已有决定继续工作
+设置每日或每周计划后，智能心跳会处理新增和变化的工作记录，更新故事图谱，并提出未决事项、分歧、修订、候选约定、长期没有进展的故事和可能适用的经验。没有新的工作来源时会跳过事实提取；建议生成失败可以单独重试，已保存的回顾和图谱仍然保留。
 
-继续一个项目时，可以请助手“查一下此前选了哪个方案，依据是什么”，或“找出这项决定后来的修订”。助手可搜索监督者已经保存的故事、经验、事件、实体、关系和回顾结果，读取相关上下文，再查看来源片段，作为后续讨论的依据。故事上下文带出相关事件，经验上下文带出形成和应用记录。
+## Telegram：从私聊继续处理任务
 
-工具说明也会引导助手在继续旧工作、追问决定原因或遇到可能已有约定的任务时主动查阅，优先找故事与经验。是否调用仍由当前模型判断；普通闲聊和独立的通用问题不要求查询，也不会在每次对话中自动塞入整张图谱。
+配置自己创建的 Telegram Bot、数字用户 ID 白名单和通道项目后，可以通过 Telegram 私聊发送文字问题或任务。GoodBuddy 会沿用该项目的 Runtime、模型和工作目录处理请求，并把最终文字回复返回到 Telegram，桌面端同时保留会话记录。
 
-在应用中心启用监督者，并在 MCP 设置中保持 Story Graph 开启、分配给所用 Runtime 后即可使用。支持直连模型、DeepSeek Harness，以及本地和远程 OpenCode、Continue；本地 Continue、OpenCode 原生终端也可读取。
+首次配置时可以先留空发送者 ID，启用并保存通道；连接 Bot 后发送 `/start` 和 `/whoami` 获取自己的数字用户 ID，再填入白名单并保存。连接支持断线恢复和停用取消，桌面应用需要保持运行并能连接 Telegram。
 
-输入区的选项中可以为当前会话单独开关故事图谱访问。默认允许查询，但仍受监督者总开关和工具配置约束；开启不会自动运行回顾或注入上下文，关闭也不会删除图谱，或将这个会话排除在后续回顾之外。
+当前通道面向单个 Bot 的普通私聊和文字请求。群聊、媒体输入和附件发送仍在桌面端处理，图片等附件结果需要回到桌面查看。
 
-查询默认使用当前项目，也可明确指定全局或项目集合。事件可从共享时间线中按项目查阅，回顾结果仍保留各自的范围。工具只读取已有记录，不会为一次查询重新运行回顾或修改图谱；助手根据结果生成回答仍使用当前模型。保存的来源片段可以分页读取，尚不支持任意时刻的完整历史状态重建。
+## Obsidian：直接连接已有笔记仓库
 
-### 智能心跳：按新增工作回顾，并提出可处理的建议
+在“设置 → 能力与工具 → MCP”的 Obsidian 卡片中，可以选择本机已注册的仓库或限定文件夹，测试连接并分配给所用 Runtime。无需启动 Obsidian，也无需安装插件或配置 REST 服务。
 
-为项目设置每日或每周计划后，智能心跳会整理回顾窗口内新增、修改或尚待处理的记录，把变化保存到故事图谱。计划默认生成建议，也可以选择“仅更新记忆”；没有新来源时跳过事实提取，仍可补做尚未完成的故事与经验整理。没有待处理工作时，不调用模型。
+接入后，可以让助手搜索和读取笔记，也可以把讨论结果写回仓库。支持追加、局部修改、目录浏览，以及标签和属性操作。笔记仍保存在原仓库，不会自动复制到 GoodBuddy 知识库。
 
-建议围绕本次回顾发现的未决事项、分歧、修订和候选约定展开，并保留来源供核对。接受未决事项后，会创建一项暂停任务，方便先检查再开始；候选约定经确认后才进入长期记忆。建议生成失败可以单独重试，已经保存的图谱和回顾进度仍然保留。
+Obsidian 接入默认关闭，启用后只在配置范围内读写。当前支持直连模型及 GoodBuddy 管理的本机 OpenCode、Continue 聊天；读出的笔记会随当前会话交给所选模型处理。
 
-心跳完成回顾后，还可以提示达到设定天数仍没有新进展的故事，或指出某条已有经验可能适用于当前故事。建议可以直接打开图谱；接受暂无进展建议会建立暂停任务，接受经验建议只标记已参考，不会据此写入经验应用记录。暂无进展默认按 14 天筛选；仅时间流逝到期、但本次回顾没有变化时，不会单独触发提醒。
+## 其他改进
 
-计划需要应用保持运行，并按所选全局或项目范围处理。心跳不会在每条聊天消息后实时介入；有候选建议时会额外调用模型整理措辞，回顾本身也可能分批调用模型。
+### 输入区和 Runtime 控制
 
-### 在任务中心跟踪当前会话或任务
+上下文来源、专家角色、模型和 Runtime 控制收进输入区工具栏。故事图谱与知识库使用同一个上下文入口，OpenCode 和 Continue 的运行配置放入独立弹窗。窄窗口下仍能按可用空间排列，弹窗支持自动聚焦、外部点击关闭和 Escape 返回焦点。
 
-右侧任务中心的项目概览下方新增监督反馈。选中任务时查看该任务的匹配结果，否则跟随当前会话；也可以固定目标，切换聊天后继续查看同一个事项。没有匹配回顾时会明确显示空状态。
+### 笔记、文件和图表
 
-监督反馈中的“继续讨论”可以直接使用，无需先打开来源。侧栏和图谱来源中的入口都会展示完整、可编辑的发送正文，包含相关回顾结论和来源内容；可以删改引用、补充问题，再确认单独显示的目标会话。发送以编辑后的正文为准，已删除的上下文不会被重新附加；发送失败保留草稿。在图谱来源中发送后会打开目标会话，需要先看原讨论时，也可单独点击“打开会话”。
+魔法笔记支持插入和编辑表格，表格与其他富文本一起保存；笔记支持标签筛选、标签管理和列表与正文双栏浏览。聊天回答可以保存到笔记并返回原会话，工作区支持批量导入本地文件到本地或远程项目，Mermaid 图表可以导出完整 PNG。
 
-带入的结论按所选来源关联的事件、实体与关系整理，方便围绕当前事项继续追问。监督界面已移除知识实体写回控件。
+### Runtime、会话和日常操作
 
-后续讨论的最终内容最多 12,000 字符。固定任务没有关联会话时，不能直接发送继续讨论；后续对话沿用目标会话的 Runtime、模型与能力配置。
+项目和会话集中到同一个菜单，Runtime 与模型可以分别按会话、项目和全局配置解析，也可以在当前会话临时切换。聊天历史、侧栏和长消息减少重复渲染，阅读位置、展开状态和流式回复更稳定；桌面通知、磨砂外观和任务用量可以分别设置。
 
-### 聊天正文存入魔法笔记，并保留来源
+### 请求、存储和故障处理
 
-遇到值得保留的回答，可以点击助手消息旁的“加入笔记”，预览并编辑文字，再追加到已有笔记，或新建笔记保存。需要保留整段讨论时，会话菜单中的“保存当前对话到笔记”会读取完整历史，收录用户与助手的正文，不局限于屏幕上已经显示的消息。
+SQLite 存储、后台读取、请求取消和并发处理路径已经合并调整，减少主进程等待。直连模型支持手动压缩上下文，工具执行失败后可以继续对话；长请求结束、取消或失败时会正确回收工具授权。监督回顾支持暂停、继续、取消和失败后重试，远程 Runtime 启动和本地 OpenCode 连接也补充了取消与恢复处理。
 
-保存后的记录带有“来自会话”入口。单条回答可以返回对应消息；原会话或消息被删除后，已保存的笔记内容仍保留。每次采集新增一条记录，后续对话修改不会自动同步到笔记。
+## 升级提示
 
-工作栏“+ → 笔记”可以打开紧凑面板，在聊天旁搜索笔记标题与正文、浏览摘要、追加文字。切换项目或会话时草稿保留，关闭有未保存内容的面板前会提示；草稿仅在本次应用运行期间保留。画布、待办和完整编辑继续在魔法笔记工作区中使用。
+升级前请关闭应用，并备份完整用户数据、设置、数据库、WAL 文件和相邻的 `notes/` 目录。当前数据库格式为 62，0.15.13 之前的客户端不能直接打开新版数据库，回退需要使用升级前的备份。首次转换较大的数据库时需要等待；高频本地保存调整了磁盘同步策略，断电时可能丢失最近尚未同步的写入。
 
-快速笔记入口集中在工作栏和聊天采集操作中，移除了侧栏与顶栏的重复快捷按钮。面板精简重复标签，采集范围说明按需展开，标题或正文超限时在对应输入位置提示。保存和来源操作统一靠右排列，窄面板中的保存按钮也保持紧凑。
-
-采集保存文本与 Markdown，不复制推理过程、工具日志或附件图片。生成中的回答暂不可采集，单条记录上限为 500 KiB，超限会提示缩减。采集本身无需调用模型；保存后自动评论仍按已有设置执行。笔记继续属于全局，来源项目只用于帮助回看。
-
-> **【待补图 06｜必补｜聊天采集与来源返回】** 用公开演示对话预览并保存一条回答，展示笔记记录中的来源入口，再验证能返回原消息。计划文件：`assets/06-chat-note-source.png`。
->
-> 建议图注：把有用的回答存入笔记，需要上下文时返回原会话。
-
-### 笔记支持标签筛选，列表与正文并排浏览
-
-给笔记加上“项目资料”“待整理”等标签后，可以按标签查找，也可以同时选择多个标签，筛出同时带有这些标签的笔记。每篇最多添加 10 个标签；标签支持改名、同名合并和删除，删除标签会保留笔记正文。
-
-宽窗口打开笔记时，左侧保留列表，右侧阅读和编辑正文，两栏宽度可以拖动调整。切换笔记时保留当前工作区内的筛选与阅读位置，有未保存内容时会提示。窄窗口可从正文工具栏打开笔记列表抽屉，选完笔记后继续阅读；记录索引默认收起，“新建笔记”固定在页头。
-
-正文使用当前栏的可用宽度，宽窗口下阅读画布和长内容有更多空间。新建文字或画布记录都可以取消，有草稿时先确认是否放弃；取消编辑、切换记录类型或返回聊天后，焦点回到对应的按钮或输入位置。
-
-标签也可由支持魔法笔记工具的助手按你的要求添加或修改。快速采集面板继续用于保存聊天内容，标签管理在完整笔记工作区中进行。
-
-### 在聊天中查找和整理 Obsidian 笔记
-
-已有 Obsidian 笔记可以直接接入 GoodBuddy。在“设置 → 能力与工具 → MCP”的 Obsidian 卡片中，选择本机已注册的仓库，或限定一个文件夹，测试连接并保存，然后启用并分配给所用 Runtime。无需启动 Obsidian，也无需额外安装 Obsidian 插件或配置 REST 服务。
-
-接入后，可以请助手查找笔记、读取内容，或将讨论结果写回仓库；也支持追加、局部修改、目录浏览，以及标签和属性操作。笔记仍保存在原仓库，不会自动复制成 GoodBuddy 知识库。
-
-目前支持直连模型及 GoodBuddy 管理的本机 OpenCode、Continue 聊天，默认关闭；DeepSeek Harness 和远程执行暂不支持。启用并分配后，可按请求读写已配置范围内的笔记；多仓库调用需要明确目标仓库。接入本机文件不等于离线推理，读出的内容会随当前会话交给所选模型处理。
-
-> **【待补图 07｜建议｜Obsidian 接入与读写】** 已有候选 `obsidian.png` 展示仓库范围和 Runtime 分配，尚需确认构建来源；正文主图优先补公开笔记的搜索、写入与回读结果。计划文件：`assets/07-obsidian-notes.png`。
->
-> 建议图注：按仓库范围接入本机 Obsidian，在聊天中查找笔记并保存整理结果。
-
-### 从输入区打开本地原生客户端
-
-本地项目选择 Continue 或 OpenCode 后，输入框下方可以打开工作栏内的原生交互终端；选择 DS 后，可以在系统默认浏览器中打开官方 DeepSeek Harness Web 客户端。启动时沿用当前项目目录与所选模型，适合希望使用 Runtime 自身交互界面的用户。
-
-原生客户端使用独立会话，不会自动接续或同步 GoodBuddy 中的聊天历史。DS 网页关闭后，本地服务继续运行，可以回到 GoodBuddy 重新打开或停止；退出应用会清理所属服务。
-
-当前入口支持本地项目，远程原生客户端尚未接通。Continue 与 DS Web 需要可用的标准 Node 环境，首次准备环境可能需要下载。Continue、OpenCode 原生终端可使用已启用并分配的内置工具及自定义 MCP；故事图谱工具保持只读。
-
-> **【待补图 08｜建议｜原生终端与 DS Web】** 已有 `continue.png`、`opencode.png`、`deepseekweb.png` 候选；发布前确认构建来源，并处理本机路径、浏览器书签及与演示无关的会话。Continue 图含模型能力警告，建议换用合适模型重拍；不能据启动画面宣称完整对话验收通过。计划文件：`assets/08-native-clients.png`。
->
-> 建议图注：在工作栏打开原生终端，或在系统浏览器中使用 DS Web 的独立会话。
-
-### Runtime 与模型可以分别跟随项目或临时切换
-
-项目可以保留常用的执行方式与模型，某次会话需要换模型时，在输入区的两栏选择器中临时选择即可。菜单标明当前选择来自会话、项目还是全局，也可以恢复项目默认，减少每次新建会话重复配置。
-
-执行方式与模型分别按“会话 → 项目 → 全局”解析，并检查模型是否适用于当前 Runtime。连接被删除或不兼容时按规则回退；缺少 API Key 时保留选择并提示配置，不会悄悄换用另一个模型。排队消息在实际发送时重新读取有效选择，定时任务则保留创建时确定的配置。
-
-托管 SSH 项目支持 OpenCode、Continue；外部 OpenCode Server 使用服务端自身配置。
-
-### 复制模型连接，保留已有配置
-
-在“设置 → 模型连接”中打开一条 LLM 连接，点击“复制”，即可在副本中修改模型名称、地址或其他选项，再保存为新连接。协议、请求定制和认证配置随副本带入，已保存的 API Key 无需重新输入。
-
-复制后仍需保存才会生效；当前最多保留 20 条连接。保存地址有误时，界面会指出对应连接并定位到地址字段，便于处理多条连接中的配置问题。
-
-### Mermaid 图表可导出完整 PNG
-
-聊天中的流程图或关系图可以打开大图窗口，再导出完整 PNG。导出内容不受当前缩放比例和拖动位置影响，适合插入报告、文档或演示材料。
-
-图片沿用当前主题背景，最长边上限为 4096 像素。此功能用于 Mermaid 图表，故事线图谱的图片导出不在本轮范围内。
-
-> **【待补图 03｜建议｜图表导出】** 在正常聊天中打开一张公开示例 Mermaid 图，执行 PNG 导出，并核对图片包含整张图。优先展示实际导出结果，图注注明它是导出图片。计划文件：`assets/03-mermaid-export.png`。
->
-> 建议图注：从 Mermaid 大图窗口导出完整 PNG，保留图中的边缘节点。
-
-### 让助手把会话图片保存到指定文件
-
-可以让助手把当前会话中已经上传或生成的图片保存到指定绝对路径，缺少的父目录会自动创建。远程项目保存到对应 Host，方便后续在项目文件中使用；已有同名文件默认保留，明确允许覆盖后才替换。
-
-保存支持 PNG、JPEG 和原格式 WebP，可按扩展名转换为 PNG 或 JPEG，不提供转为 WebP。工具使用当前会话已有图片，不负责下载任意图片网址。成果页已移除，历史图片和成果记录仍保留；保存图片无需先进入成果页，既有成果也不会自动复制到项目目录。远程保存自 Agent 0.15.2 起提供，本轮建议使用上述最新配套版本。
-
-### 通过 Telegram 私聊使用通道项目
-
-配置自己创建的 Telegram Bot、数字用户 ID 白名单和通道项目后，可以在 Telegram 私聊中发送文字问题或任务。GoodBuddy 沿用该项目的 Runtime、模型和工作目录处理请求，返回最终文字回复，并在桌面保留会话记录。
-
-首次配置可以先留空发送者 ID，启用并保存通道。连接后私聊 Bot，发送 `/start` 和 `/whoami` 获取自己的数字用户 ID，填回白名单并再次保存后即可发送 AI 请求；仅测试连接不会开始接收消息。
-
-当前支持单个 Bot 的普通私聊，桌面应用需要保持运行并能连接 Telegram。连接使用系统代理，支持断线恢复和停用取消；排除连接故障后，也可原样保存配置重新连接。目前不处理群聊、媒体输入或附件发送，图片等附件需回到桌面查看。
-
-> **【待核对 C02｜Telegram 实际联调】** 功能已提交，真实 Bot 与模型的完整收发验收仍待完成。对外发布前用专用演示 Bot 核对文字请求、回复、断线恢复与停用行为，不将本轮静态核查写成实际联调通过。
-
-### 将本机文件导入本地或远程工作区
-
-工作区文件面板的“新建文件”旁新增导入入口。选定目标目录后，可以批量选择本机文件，复制到本地项目或上传到远程 Host，随后在文件列表中查看。远程导入需要配套 Agent 0.15.4 或包含该功能的更新版本。
-
-导入遇到同名文件时保留原文件，单个文件失败后继续处理其余文件。列表可以按名称、修改时间或可用的创建时间排序；排序针对当前目录已读取的条目，每目录最多 500 条。
-
-### 桌面通知可以单独关闭
-
-“设置 → 平台功能 → 通用设置”新增“桌面通知”开关，默认开启。关闭后，应用处于后台时的任务完成、失败或取消等系统提醒停止弹出，应用内通知仍然保留。设置保存后立即生效，重启后也会记住选择。
-
-### 设备共享目录：登记设备，发布能力与知识说明
-
-在应用中心启用“设备共享”，连接另行运行的 ShareServer 后，可以登记本机、浏览设备和发布目录，并发布或撤销能力、知识的元数据，供使用同一服务的人查看有哪些资源。
-
-此功能默认关闭，当前提供目录管理。发布“知识”记录不会上传或同步正文，搜索、读取和下载标志仅表示声明；尚不提供远程执行或知识正文访问。设备登记也不表示设备在线，当前服务没有身份认证，应在可信环境中使用。
-
-## 功能改进
-
-### 请求直接使用当前 Runtime 与能力配置
-
-聊天、任务和通道请求不再需要切换 Ask／Execute，也移除了原有的通用工具审批策略。选好 Runtime、模型与已启用能力后，即可提出请求；只需解释时可以直接说明，文件和工具操作使用执行账户的实际权限。
-
-能力开关、工具分配、资源范围和取消操作继续生效，各 Runtime 的支持范围也仍有区别。监督回顾、摘要等专用文本分析任务保持无工具。已有会话内容保留，旧工作模式设置不再决定后续请求的行为。
-
-### 项目与会话集中到一个菜单
-
-左上角的双行按钮统一显示项目与当前会话，点击后浏览本地、远程和通道项目。可以分类搜索，悬停预览项目会话，也可以直接跨项目进入正在处理的工作；切回项目时恢复上次打开的会话。
-
-菜单同时提供最近 10 个会话，以及待处理和运行中的工作；按已完成状态筛选时可以继续查找历史会话。项目设置、归档恢复和离开未保存草稿前的提示仍可使用。新建本地项目必须选择目录，远程目录选择器支持进入指向目录的符号链接。
-
-### 会话搜索按需展开，快捷键提示集中在输入框
-
-侧栏的搜索入口与“新建对话”放在同一行，点击后展开并自动聚焦，可查找会话标题或消息正文。切换会话保留关键词；点击关闭按钮，或在搜索控件行内按 Escape，可清空并收起搜索。展开和收起时，会话列表位置保持不变。
-
-输入框的空白提示集中显示发送、换行、粘贴、新建对话及可用的快捷唤起按键，并按系统显示 Ctrl 或 Command。修改快捷键设置后提示随之更新；快捷唤起已关闭或注册失败时，不再显示不可用的按键。
-
-侧栏底部的“应用”和“设置”保留文字并分开显示，应用菜单箭头与向上展开方向一致。会话列表独立滚动，短窗口中的入口仍可到达，滚动条和分隔线样式也作了统一。
-
-### 知识库文档与来源集中浏览
-
-知识库将内容来源与文档索引合并为统一列表。单文档来源合成一行，目录继续按组展示，导入失败、尚未生成文档的来源也保留恢复入口。搜索可以同时查找来源与文档，网址来源保留原网址，便于辨认同名资料。
-
-列表突出查看入口，打开原文、分块管理、重新解析等操作收进更多菜单。解析结果页也整理了返回导航和图片操作，减少长名称、多个按钮挤在一行的情况。
-
-任务历史改为按批次展示，可以展开处理步骤，查看进行中、失败与历史记录。筛选与计数跟随当前文档或来源，便于检查一次导入的处理情况。
-
-### 图谱列表与画布各自浏览
-
-故事线图谱侧栏可以按故事、经验、事件、实体和关系查看，列表与详情各自滚动。切换页签保留已有选中对象，在画布选中对象时，侧栏会切到对应类别。平铺与时间螺旋都使用中间画布的可用空间，视角等控件收进紧凑操作区，减少窗口较矮时内容被挤出屏幕的问题。
-
-工作回顾与图谱共用选中的历史结果和范围说明，从总结切到图谱时继续查看同一份回顾。新回顾的输入区域可以收起，历史选择器和视角工具排列更紧凑；详情布局也适配较窄窗口。
-
-### 手动回顾与智能心跳共用增量进度
-
-原有的每日、每周计划现在集中到“自动监督”。新建或编辑计划时，可以选择全局或多个项目，设置时间、时区、回顾窗口和历史保留期限；暂停的计划在编辑保存后仍保持暂停。
-
-手动“回顾”和心跳计划现在共用增量处理方式，默认只分析所选范围内尚待处理的变化。项目与全局共用来源处理进度：同一版本的来源已成功发布后，换一个范围回顾可以复用，减少重复提取。没有新来源时仍可补做积压的故事与经验整理，没有待处理工作才跳过模型调用。需要重看完整区间时，可从“更多 → 重新整理”确认发起；重新整理不会推进或重置增量进度。
-
-启用监督者不会自动创建计划。定时工作需要桌面应用保持运行，关闭监督者会停止发起新的回顾，并保留计划和历史；从导航取消常驻只改变入口显示。尚无活动时，自动监督页会隐藏空的统计、建议和历史区域，先展示计划入口。
-
-监督者设置中可以单独选择一条文本模型连接，用于回顾、故事和经验整理，以及建议生成；未指定时跟随默认文本模型。选定连接失效或缺少 API Key 时明确提示，不会自动换用其他模型。
-
-监督分析会将入选内容交给配置的模型服务，可能产生费用。它以只读、无工具的方式分析记录，长时间范围可能分成多批；心跳不再额外生成一份独立报告。并发数和超时设置不等于总费用上限。
-
-### 长回顾可以看进度、保留批次并继续处理
-
-监督者的“活动记录”集中展示手动和自动执行情况。展开记录，可以查看当前阶段、已保存批次、剩余来源和失败原因，再按项目、会话、批次检查已保留事实与来源片段。
-
-回顾会分页读取选定范围内的来源，将长内容拆成批次处理。成功批次保存后，后续阶段失败不会把这些内容一并丢弃；暂停或失败后可以继续。0.13.16 还取消了按固定累计时长自动暂停的行为，长回顾可以持续处理至完成，无需隔一段时间手动续跑。
-
-需要调整处理方式时，可在“监督者 → 设置”中配置模型并发、单次模型超时、每次读取的来源条数、每批消息和文本量，以及单次响应容量。新建回顾会保存分批配置；来源已被修改或删除时，需要重新发起回顾。
-
-> **【待补图 04｜必补｜回顾进度与来源批次】** 展开真实运行的活动记录，展示阶段、已保存批次和来源正文。若展示暂停后继续，须通过真实操作完成，不注入运行状态。图 01 的演示可复用同一份记录。计划文件：`assets/04-review-progress.png`。
->
-> 建议图注：从活动记录查看处理阶段与已保存批次，展开核对来源。
-
-> **【待核对 C01｜暂停与取消配图】** `v0.15.0` 已包含 `5116613` 的暂停控件修复与取消入口，见末尾“回顾运行期间的控制”。截图须对应目标版本，展示实际暂停、继续和取消操作。
-
-分页和批次记录便于核查处理范围，模型给出的总结、实体和关系仍需人工判断；来源处理完成不代表每个事实都被模型准确理解。
-
-### 待办、任务与用量更便于浏览
-
-魔法笔记的待办页可以拖动列表与详情之间的分隔条，调整后的宽度会保存。来源笔记标题支持独立折叠，收起一个分组不会清空正在查看的任务详情。分组折叠状态不跨重启保存，窄窗口下不提供横向拖宽。
-
-笔记详情的记录索引与 AI 区开关集中在正文顶部的固定工具栏，图标带有悬停提示。任务中心展开列表后，可以直接选择“全部、进行中、暂停、已结束”；默认显示进行中的任务，历史任务仍可通过切换状态查看。
-
-> **【待补图 05｜建议｜待办布局】** 用虚构笔记创建不同来源的待办，拖动分隔条并折叠一个来源组，保持另一项详情可见。计划文件：`assets/05-note-todos.png`。
->
-> 建议图注：调整待办列表宽度，按来源笔记收起暂时不看的任务。
-
-运行记录中的 Token 用量先显示项目或会话总计，展开后再看 Runtime 和模型明细，按模型分组的视图继续保留。“系统任务”页签单列监督回顾、笔记、知识库等后台用量，并补齐回顾、图片重新生成、知识图谱提取和远程嵌入等调用的用量记录；过去未记录的用量无法补算。页面打开时加载，可见期间每 15 秒刷新，也可点击页头手动刷新。这里汇总的是应用记录，并非服务商计费账单。
-
-会话和任务耗时按实际运行状态累计，包含模型与工具执行，等待用户回答时暂停，运行期间持续更新。并行请求的时间会相加，因此它不等于项目经历的日历时长。旧历史不补算，缺少计时数据且累计为零时显示“不可用”，与真实的零时长区分。
-
-### 长对话输入、切换与流式回复减少重复处理
-
-任务耗时按运行状态累计，避免反复扫描历史消息和事件；隐藏的任务面板保留操作状态并减少不必要的更新。较长任务列表也减少了屏幕外卡片的绘制工作。
-
-运行记录按需分页加载，筛选时读取对应范围，保存时只传递变化的记录；页面计数与汇总仍覆盖已保存历史。离开页面后释放多余已加载页，重新查看时可以继续加载，保留原有内容与顺序。实际响应改善取决于历史规模和设备，不以测试中的数据库指标代替整机提速幅度。
-
-聊天输入和流式回复减少了无关活动面板的刷新；置顶或取消置顶会话时，也不再附带扫描附件引用。笔记启动检查复用已读取的正文信息，减少重复读取，原有内容恢复与清理流程保留。
-
-长回答逐步生成时，已完成的 Markdown 区块可以复用，减少每次新增文字都重新处理整篇内容。切回近期看过的会话时也会复用缓存结果；会话侧栏与运行记录减少无关刷新，降低回复期间继续输入和切换会话的开销。
-
-较长会话和大量会话的侧栏主要渲染屏幕附近的内容，历史记录仍然保留，可以继续加载和定位。切回缓存会话时恢复阅读位置；Markdown 解析结果也可复用，包含公式的长回复减少重复解析。
-
-知识检索、故事图谱查询、会话搜索和会话列表等常用读取移到后台线程，减少查询期间对桌面主线程的占用。远程运行的连续事件按批保存，减少逐条写入的开销。改善幅度取决于设备、数据规模和内容复杂度，不作统一提速比例承诺。
-
-文档解析、分块与摘要哈希计算也转到后台线程；笔记网格、工作区文件树和知识库文档表主要绘制可见区域，终端连续输出合并刷新。启动时按需加载部分组件，并在后台准备工具环境，需要这些工具时再等待准备完成。
-
-### 设置页减少来回查找
-
-长设置表单的分类标题与相关页签固定在顶部，请求 Header、Body 等低频选项收进高级设置。默认工作目录移到“平台功能 → 通用设置”，Skills 和 MCP 页面移除重复标题，保留导入与添加操作。
-
-设置导航按用途分组，开关统一放在右侧。通用设置集中放置会话与通知、工作目录等选项；本地语音和嵌入模型页面提供“模型下载源”快捷入口，可打开统一弹窗，在 ModelScope 与 Hugging Face 之间切换。选择影响后续托管模型下载，已安装模型、ZIP 导入、Ollama 和应用更新不受影响。
-
-外观设置新增透明磨砂效果，当前默认开启；标题栏和相关卡片使用半透明背景，可以看到其后的应用内容。可以关闭恢复实色显示，已有的外观选择继续保留。
-
-内置浏览器 MCP 也改为默认启用，仍可在设置中关闭；之前明确保存的关闭状态会保留，不会修改系统默认浏览器。请助手通过配置工具应用本次请求的变更计划时，取消了额外一次原生确认；仍需先生成有效计划，再应用对应变更。
-
-HTTP OCR 高级设置可以直接选择是否保留页眉、页脚、页码等内容，并恢复默认过滤方式。版面与生成参数的分组和间距也重新整理；具体选项效果仍取决于所连接的 OCR 服务。
-
-成功和提示通知采用更紧凑的卡片，两秒后自动消失；错误提示继续保留，直至手动关闭。删除会话的确认框也去掉了重复警告，永久删除的含义不变。
-
-## 问题修复
-
-### 直连文本模型恢复手动压缩上下文
-
-本地直连文本会话可以从输入区点击“压缩上下文”，即使关闭自动压缩或尚未达到触发阈值，也能手动执行。压缩使用配置的摘要连接，摘要随会话保存并用于后续对话，同时保留最近轮次和完整聊天历史；关闭自动压缩后，已有有效摘要仍可使用。
-
-会话运行或正在压缩时需等待完成；没有可压缩的较早历史时会提示。这项修复适用于本地直连文本会话，不包含图像生成连接、远程通道会话或 SSH 项目。
-
-### 长请求持续保留已授权的工具访问
-
-修复桌面 Agent 请求持续超过十分钟后，工具授权提前失效的问题。请求仍在执行时，已启用并分配的知识库、笔记、浏览器等工具可继续使用；完成、取消或失败清理时仍会撤销该次授权。工具自身的调用超时、读写权限和开关设置保持不变。
-
-### 取消与失败提示更清楚
-
-取消和失败信息集中显示在消息状态中，减少与回答正文或工具详情的重复。主动取消使用中性提示，真实失败继续显示错误状态，已经生成的回答保留。
-
-最后一条失败或取消消息有可恢复的原问题文字时，可以点击“重新编辑”将文字回填输入框，修改后自行发送；不会自动重发，也不承诺恢复附件。
-
-取消或失败的轮次在后续上下文中明确标为中断，并保留已有回答，避免上一条未完成请求被并入新问题继续执行。OpenCode 复用会话在取消后的下一轮也会收到中断说明。
-
-### 远程回答完成后，可以继续对话
-
-远程请求现在等待模型交付确认后再结束。回答已经完成时，随后回收空闲 Runtime 失败不会再把结果改成“未知”。确实遇到结果未知的请求，用户显式发送新消息后会建立新的运行绑定并带入已有历史；自动恢复仍只重新连接原请求，不会擅自重复执行结果未知的任务。
-
-最后一个活动任务结束后，远程空闲 Runtime 会被释放，下一轮对话再恢复历史。仍有任务或待答问题的共享进程会保留；更新后被替换的旧 Agent 会等待已有工作结束再退出，当前 Agent 保持常驻。
-
-Host 更新还会清理已确认停用的旧 Agent 程序和归属明确的孤儿进程，保留会话历史、活动安装和状态不明的安装。这些完成状态与进程清理修复自 Agent 0.13.4 起提供；本轮基础配套为 Agent 0.15.4，仅升级桌面不会直接替换 Host 上已经运行的旧进程。
-
-最新修复使远程 Runtime 在等待启动时仍可取消，并避免阻塞其他会话；本地 OpenCode 提交失败后也能及时结束等待并显示原因。远程部分需要包含 `bbf24c28` 改动的 Agent，不属于已核查的 Agent 0.15.4 标签。
-
-### 通道交付与统计结果
-
-- 修复生成图片成功后，通道因结果格式校验而误报失败的问题。Telegram 仍只发送文字提示，附件需到桌面查看。
-- 钉钉返回业务错误时不再被当作送达成功，可以进入已有重试流程。
-- 修正 OpenCode 缓存命中率偏高、完全命中时显示为空的问题；已有用量重新查询后使用完整输入量计算，不表示实际缓存命中率提高。
-- 活动汇总覆盖已加载的会话集合，不再只统计前 5,000 个会话。
-- PPTX 解析警告显示实际使用的 OCR 服务及失败的幻灯片、图片位置，便于排查；这项修复不改变外部 OCR 服务本身的识别结果。
-
-### 启动、搜索与回顾结果
-
-- 修复正常聊天或保存笔记后，重启反复显示历史迁移的问题。普通数据库结构升级也不再因正常空闲页额外整理整库；确需转换的旧数据仍会处理，启动页区分实际操作。
-- 修复本机直连模型文件搜索参数受限和大结果截断的问题。模型可使用 ripgrep 原生参数，保留原生结果与退出码，并分页续读长输出；工具使用当前执行账户权限。这项变更不属于远程 Agent 或其他 Runtime 的新增工具。
-- 修复早期监督回顾只取部分会话、消息和正文的问题，改为对入选来源分页、分批处理。事实与来源独立保存，只有必要阶段完成并成功保存结果后才标记完成。
-- 修复监督回顾中的旧实体引用、摘要合并校验及长摘要报错。遇到无效 JSON、结构或引用时，会尝试缩小当前批次后重试，剩余正文留待后续处理；成功保存的批次保留。
-- 监督模型遇到可识别的临时网络中断、限流或部分服务端错误时，清理失败请求后自动再试一次，等待期间可以取消。认证、配置、费用额度、超时、取消及容量错误不会触发这次重试；失败尝试已报告的用量仍会记录，重试可能增加模型费用。
-- 故事或经验整理失败时，已保存的回顾结果继续可用，可以单独重试整理。故事归类减少把各功能的提交与测试统归到“发布”的情况；经验应用记录也增加时间顺序与共同实体核对，归纳内容仍需结合来源判断。
-- 时间螺旋退出时释放图形资源；3D 初始化失败或图形上下文丢失时，在视图内提示并提供重试，也可切回平铺，避免整个监督页面无法使用。
-- 修复历史回顾入口跳到其他结果、切换后旧响应覆盖当前选择的问题。侧栏、活动记录和图谱按对应结果定位，人工确认与修订的内容保留。
-- 修复关闭跨项目关联后候选范围未正确限定、暂停发生在最终查询期间仍继续发布的问题。故事整理期间已移除的故事不会再收到新关联，刷新后的控件也不会因旧请求失效而一直禁用。
-
-### 日常界面操作
-
-- 多个会话同时回复时，侧栏列表不再随流式文本或工具进度反复换位。会话按最新消息的创建时间排序，每五秒检查一次；悬停、滚动后的短暂停留、菜单展开或键盘焦点位于列表时暂缓重排，方便点选。置顶会话继续优先显示。
-- 输入框的附件、语音与选项按钮统一尺寸、间距和悬停反馈，录音中和选项展开时仍保留对应状态提示。
-- 草稿和排队消息中的图片可以直接打开预览，发送前更容易核对附件。文本输入框移除重复问候，只保留快捷键提示。
-- 展开 Runtime 检查清单不再挤动聊天内容；文件列表和差异页的操作栏在滚动时保持可见。
-- 笔记保存后退出编辑；从快速笔记跳到指定记录时，等待正文显示后再定位，减少落在错误位置的情况。
-- 切回已查看的会话时，立即显示缓存的累计回复时长，再后台刷新；缓存限本次应用运行期间。
-- 长对话滚出屏幕后再返回，推理、工具输入输出、引用和子代理详情保留展开选择；该状态限历史面板存续期间，不跨应用重启保存。跨屏选择、复制与滚动定位也作了修复，跳到底部恢复平滑滚动。
-- Mermaid 大图放大后，顶部和左侧等边缘仍可通过滚动、拖动到达，窄窗口中的控件可以换行。
-- Git 分支选择器悬浮在工作区上方，不再把文件列表和提交历史向下挤动；项目选择菜单可以浮出侧栏，长名称与路径有更多显示空间。
-- 文件差异页将查看文件、刷新和复制路径集中到路径旁，窄面板中可以换行；只有未暂存改动时，省去重复的分区标题。浏览器“前往”按钮改为紧凑图标，保留悬停提示。
-- 聊天与浏览器、终端工作栏之间的分隔条恢复完整拖动区域；笔记缩略图与内容边缘对齐，键盘焦点轮廓保持可见。
-- 纯文本排队消息不再显示无效的“查看附件”按钮；浏览器页签关闭失败后重试成功，会清除残留错误。
-- 监督反馈显示会话或任务名称，固定与刷新按钮在窄侧栏中排列更紧凑。工作回顾和活动页使用可用宽度，运行阶段与已保存批次更醒目。
-
-### 运行配置与界面修复
-
-- OpenCode 原生终端减少重复准备步骤，缩短打开时的等待；临时 MCP 工具名缩短并在同一会话中尽量复用，减少工具名称过长导致的调用失败。
-- 本地 OpenCode 初始化工具连接时，遇到明确的暂时性传输故障，清理成功后最多重试一次，不重放问题或工具调用。迟到的旧连接结果不再替换当前连接；自定义 MCP 中一台服务加载工具失败时，其他正常服务仍可使用。
-- 修复 Continue 禁用自动更新后仍显示“Checking for updates”的问题，避免空闲终端显示误导性的更新状态。
-- 补齐 DS Web、远程 Runtime 和模型桥辅助进程启动时的遥测关闭配置；模型、MCP 和用户主动发起的联网请求保持可用。远程遥测配置与 Continue 更新检查修复由 Agent 0.15.0 配套提供，对更新 Host 后新启动的 Runtime 生效，已有进程不会热更新。
-- 修复知识库不同来源的操作相互阻塞，以及多文档来源中任务范围、筛选计数不一致的问题。
-- 修复深浅主题中危险操作按钮、禁用状态、控件边框和键盘焦点显示不一致的问题，包括放弃笔记草稿的确认框。
-- MCP 编辑器和图片预览可以在父弹窗上正常操作；项目弹窗的 Escape 只处理当前弹窗，帮助层覆盖浏览器时不再被原生页面遮挡。
-- HTML 全屏预览恢复键盘进入与 Escape 返回，继续保持原有沙箱限制。
-- 窄工作栏的添加按钮不再被滚动箭头遮挡，模型连接协议文字保持可读；DS 入口移除常驻说明，重新打开和停止服务操作继续保留。
-- 多页签工作栏的滚动箭头不再遮挡关闭按钮。DS 网页和服务操作名称更明确，停止确认与取消按钮同行显示，减少输入区跳动。
-
-### 回顾运行期间的控制
-
-回顾运行期间，范围、时间选择和刷新入口继续可用；修改选择不会改变已经启动的回顾。重复点击发起按钮会提示已有运行，避免同时创建重叠回顾。
-
-活动记录增加取消正在运行回顾的入口，并修复继续回顾后无法再次暂停的问题。暂停保留进度供继续处理；取消会保留已成功保存的批次，但该次回顾不能再继续。取消清理结束前显示“正在取消”，未完成结果不会发布，之后可以新建回顾。
-
-手动发起、继续与自动回顾共用执行限制；自动回顾在忙碌时等待，手动操作会提示当前已有运行。同一次回顾内部仍可按设置并行处理批次。
+> **编辑提示：** 发布前补齐生产截图，替换故事线概念图，并核对下载地址、发布日期和更新日志链接。以上提示属于编辑流程，不影响本文所述功能已完成的状态。

docs/pr-articles/2026-09-26-unreleased/review.md

@@ -1,5 +1,54 @@
 # 0.13.8 起综合宣传稿核查记录
 
+## 2026-10-09 宣传版重排
+
+本轮按宣传重点重写正文，将故事图谱、Telegram 和 Obsidian 接入作为三条主线；底部输入区、Runtime、笔记、性能和稳定性改进合并到“其他改进”。当前版本内所述功能均按已完成能力表述，发布前的待办只保留生产配图、公开下载信息、发布日期和更新日志链接，不再把功能验收材料写成开发状态。
+
+正文保留必要的使用范围和升级提示，提交依据、实现边界与历史变更继续留在本核查记录中。原正文中的概念图仍只作示意，发布前需要用目标版本的生产截图替换。索引已同步更新，未修改产品代码。
+
+早期核查中关于 Telegram 真实联调的 C02 标记属于当时的验证记录，不再作为当前正文的功能状态描述；本轮按用户确认，将 Telegram 作为当前版本已完成能力介绍。发布前仍需补齐公开演示素材和发布信息。
+
+## 2026-10-09 截至 3556df88 的增量核查
+
+本轮固定范围 `47917094..3556df88`，共 5 个提交；全文范围为 `v0.13.7..3556df88`。`v0.15.13` 与 `agent-v0.15.6` 均指向 `3556df88`。本轮没有新增独立宣传功能，连续提交合并回已有的输入区 UI 与 Runtime 修复说明。
+
+| 提交 | 入文内容 | 核查依据与边界 |
+| --- | --- | --- |
+| `69f64df2`、`4b4531ab` | 补强“底部输入区工具栏更紧凑” | 恢复 Composer 弹层与工具入口的集成，保留打开后聚焦第一个可用控件、外部点击或焦点离开关闭、Escape 返回触发按钮焦点的最终行为；测试夹具调整不单独宣传。 |
+| `adb58d92`、`3556df88` | 合入 Runtime 网络请求修复 | 本地模型请求可通过 Electron 的 `net.fetch` 发送，监督模型连接也沿用该请求路径并保持既有配置校验；不扩大为所有网络故障已解决或跨平台安装包验收完成。 |
+| `d7fb4299` | 仅留内部验证依据 | 使用真实 fetch 的监督模型覆盖测试，不写成当前轮次已执行的产品测试或真实模型验收。 |
+
+本轮只更新宣传正文、核查记录和索引，未修改产品代码。未运行产品测试、构建、真实模型请求或拍摄新截图；生产配图、Telegram 真实联调和公开下载信息继续待核验。`deai-writing` 扫描结果沿用上一轮为阻断项 0、复核项 19；`git diff --check -- docs/pr-articles` 通过，仅提示既有 LF/CRLF 行尾策略。
+
+## 2026-10-08 截至 47917094 的增量核查
+
+本轮固定范围 `384683e8..47917094`，共 23 个提交；全文范围为 `v0.13.7..47917094`。Desktop／Agent 版本依据仍为 `0.15.13`／`0.15.6`，本轮没有新的版本准备提交。正文按用户场景合并了表格编辑、专家与 Runtime 控制入口；输入区、历史导航和存储测试相关的连续提交没有拆成多个宣传条目。
+
+| 提交 | 入文内容 | 核查依据与边界 |
+| --- | --- | --- |
+| `3d063937` | 新增“在魔法笔记中插入和编辑表格” | Quill 原生 table Delta 经过编辑器、共享契约、IPC、存储和只读渲染链路；支持设置行列、行列增删和整表删除，表格上限 20 行／12 列。空单元格表格可保存并重新打开，空白富文本仍拒绝保存。 |
+| `13b58627`、`1a59c2d8`、`670b5985` | 新增“在当前会话中使用专家角色和 Runtime 控制”，并合并底部输入区 UI 改进 | 专家和 Runtime 控制收进 Composer 工具栏。选定专家或智能路由得到的角色说明加入当前 Runtime 的受信任提示词，沿用当前会话的模型、工具、流式输出和权限；普通对话不转为额外子任务，团队模式仍走独立团队路径。上下文来源共用一个入口，OpenCode／Continue 的控制项进入独立弹窗；点击外部区域或焦点离开时关闭，Escape 返回触发按钮焦点，运行控制弹窗移除多余分隔线。 |
+| `e2a5f836`、`47917094`、`4266ff5`、`4a2ea490` | 仅记录历史导航方案的收回和文档整理 | `e2a5f836` 发布了聊天历史导航文档，曾尝试取消向上滚动的 80 条增量限制；`47917094` 恢复批量历史加载。当前仍保留历史窗口和约 60 条 DOM 窗口化，不能宣传为已实现连续滚动或 minimap。用户指南和 README 截图整理不单列为功能。 |
+| `377b14fc`、`a406f596`、`7f0a73e6`、`2d68d104`、`277da413`、`e1360264`、`59a28209`、`9788b4cd`、`c90ad2af`、`95ece25c`、`c4ab83a7`、`7eb11302`、`5ba127e3`、`2a92f8f8`、`95f44195` | 仅留内部验证依据 | 存储进程取消、排空、崩溃恢复和测试夹具稳定化，不写入宣传正文，不据此扩大存储进程故障恢复或跨平台验收结论。 |
+
+本轮只更新宣传正文、核查记录和索引，未修改产品代码。未运行产品测试、构建、真实模型请求或拍摄新截图；提交中已有的表格、聊天历史和存储测试记录只用于核对实现边界。生产配图、Telegram 真实联调和公开下载信息继续待核验。deai-writing 扫描结果为阻断项 0、复核项 19、读取错误 0；复核项集中在版本、素材、能力边界和必要否定条件，未机械删除。`git diff --check -- docs/pr-articles` 通过，仅提示既有 LF/CRLF 行尾策略。
+
+## 2026-10-08 截至 384683e8 的增量核查
+
+本轮固定范围 `e50ca6d1..384683e8`，共 22 个提交；全文范围为 `v0.13.7..384683e8`。版本资料已推进到 Desktop 0.15.13、Agent 0.15.6；HEAD 位于版本准备提交之后，最后一组提交主要是存储故障验收夹具和测试稳定化，不另列为产品功能。正文仍按新增功能、功能改进、问题修复组织，并将连续的架构与性能改动合并为一节。
+
+| 提交 | 入文内容 | 核查依据与边界 |
+| --- | --- | --- |
+| `d80d42b0`、`8473189f`、`904bb691`、`1f85d0c0` | 合并为“存储与请求路径合并，减少主进程等待” | Desktop SQLite 的 Assistant、Knowledge、附件、Runtime 绑定和用量记录改由同一 storage utility process 负责；查询、文件操作和回顾来源读取共用类型化异步调用。同步保留事务、提交确认、取消、关闭排空和故障报告边界。移除无依据的产品侧 admission、子任务和解析 worker 队列上限，不宣传为全量并发或跨平台性能验收；存储进程故障后未确认写入仍需按域核对。 |
+| `13c29bad`、`c1e4bbf6`、`3e3a0216` | 更新魔法笔记标签节 | 标签管理器新增直接创建标签；保留空标签集合，重复标签错误保留原始原因。正文不扩大为自动打标签或取消每篇最多 10 个标签的限制。 |
+| `e0607a15`、`2be57492` | 合入回顾结果修复 | 支持短引用和已知历史键映射；删除会话后回顾可继续查看或处理，暂停、继续、重试及项目范围规则仍有效。 |
+| `56b8b10d` | 新增直连模型工具失败后的继续对话说明 | 工具执行失败不会阻塞后续直连模型消息，分页输出边界、工具权限、取消和超时规则保留。 |
+| `425accf4`、`4bb7573b`、`edf019aa` | 合入日常界面改进 | 直接进入设置页时预加载目标路由；工作区文件列表元数据和聊天输入区过渡更简洁。均不单列为新能力。 |
+| `b90ff50f`、`36e671a0`、`fbfafa15` | 更新版本与监督稳定性依据 | 监督任务交付和停顿修复并入既有监督修复范围；版本准备资料为 Desktop 0.15.12/0.15.13、Agent 0.15.5/0.15.6。 |
+| `42ad8a98`、`4c25e85b`、`7eb51bd5`、`9212fd43`、`384683e8` | 仅留内部验证依据 | 存储故障验收、权限夹具、容量断言和测试竞态稳定化，不写入宣传正文，也不据此宣称完整 C01–C07 或跨平台性能验收完成。 |
+
+本轮未修改产品代码，仅更新宣传正文、核查记录和索引。未运行产品测试、构建、真实模型请求或拍摄新截图；本轮提交中的测试记录只作为静态核查依据。生产配图、Telegram 真实联调和公开下载信息继续待核验。deai-writing 扫描结果为阻断项 0、复核项 18、读取错误 0；复核项均为版本、素材、能力边界或模型结果限定，未机械删除。`git diff --check -- docs/pr-articles` 通过，仅提示既有 LF/CRLF 行尾策略。
+
 ## 2026-10-05 截至 e50ca6d1 的增量核查
 
 本轮最终范围 `9527402..e50ca6d1`，共 60 个提交；全文范围为 `v0.13.7..e50ca6d1`。初次固定至 `bbf24c28` 的 58 个提交，收尾补查新产生的两项提交。本地桌面 `v0.15.11` 与 Agent `agent-v0.15.4` 同指向 `78afec77`，上一桌面 `v0.15.10` 指向 `ff61da28`。Telegram、自定义回顾日期、历史耗时缺失提示及最后一组运行修复在 0.15.11 标签之后，均已提交，不将其混入该标签，也不使用开发状态标签。以下取代旧节的当前状态描述，旧节仅作历史依据。

docs/pr-articles/README.md

@@ -386,4 +386,4 @@ Agent 专题使用对应的 `agent-v…` tag。
 | 日期 | 目标 tag | 标题 | 状态 | 正文 | 发布链接 |
 | --- | --- | --- | --- | --- | --- |
 | 2026-09-19 | 未确定（unreleased） | GoodBuddy 更新预览：画布笔记、文档处理与应用管理 | 草稿，截图待补 | [综合更新稿](./2026-09-19-unreleased/article.md) | 未发布 |
-| 2026-09-26（10-05 更新） | v0.15.11（78afec77）及之后截至 e50ca6d1；汇总 v0.13.8 起的变化 | GoodBuddy 更新：故事图谱、Obsidian接入、Runtime原生终端 | 草稿，已补 Telegram 私聊、统一执行、项目会话菜单、文件导入、自定义回顾日期、监督模型与会话图谱开关、临时失败重试、3D 和性能改进；Telegram 实际联调、生产配图及公开发布信息待核验 | [综合更新稿](./2026-09-26-unreleased/article.md) | 未发布 |
+| 2026-09-26（10-09 更新） | Desktop 0.15.13／Agent 0.15.6 及之后截至 3556df88；汇总 v0.13.8 起的变化 | GoodBuddy 更新：故事图谱、Telegram 与 Obsidian 接入 | 草稿，按故事图谱、Telegram、Obsidian 三条主线重排；其他功能合并为辅助改进，生产配图及公开发布信息待补 | [综合更新稿](./2026-09-26-unreleased/article.md) | 未发布 |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "goodbuddy",
-  "version": "0.15.13",
+  "version": "0.16.2",
   "private": true,
   "description": "Secure desktop AI workspace with controlled Agent Runtimes",
   "desktopName": "GoodBuddy",
@@ -20,6 +20,9 @@
   "type": "module",
   "scripts": {
     "dev": "electron-vite dev",
+    "docs:dev": "vitepress dev sites/docs --config sites/docs/.vitepress/config.mts",
+    "docs:build": "vitepress build sites/docs --outDir sites/docs-dist --config sites/docs/.vitepress/config.mts",
+    "docs:preview": "vitepress preview sites/docs-dist",
     "start": "electron-vite preview",
     "typecheck": "tsc --noEmit -p tsconfig.node.json && tsc --noEmit -p tsconfig.agent.json && tsc --noEmit -p tsconfig.web.json",
     "lint": "eslint .",
@@ -419,6 +422,7 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.65.0",
     "vite": "^7.3.6",
+    "vitepress": "^1.6.4",
     "vitest": "^4.1.10"
   },
   "optionalDependencies": {

resources/release-notes.json

@@ -1,6 +1,128 @@
 {
   "formatVersion": 1,
   "releases": [
+    {
+      "version": "0.16.2",
+      "releasedAt": "2026-10-10",
+      "notes": {
+        "zh-CN": {
+          "highlights": [],
+          "features": [
+            "**支持全部时间的监督回顾**：监督者现在可以选择从最早保存的工作记录到当前时间的全部时间范围，适合查看长期积累的工作进展。",
+            "**只在稳定后纳入监督回顾**：正在生成的消息和运行中的任务会等到完成后再进入回顾，避免回顾内容随着实时输出变化。"
+          ],
+          "fixes": [
+            "**让 Magic Notes 操作更容易理解**：笔记入口和操作按钮增加清晰的文字标签，更多操作在需要时显示，减少误解和界面干扰。",
+            "**修复终端输入法布局**：在终端中输入中文或其他组合文字时，输入候选和组合区域会保持在终端边界内，不再撑开或遮挡周围界面。"
+          ],
+          "notices": [
+            "本版本首次启动会将数据库升级到 schema 63。升级前请关闭应用并备份完整数据目录、相邻 `notes/` 和设置文件；Agent 0.15.6 无需更新。"
+          ]
+        },
+        "en-US": {
+          "highlights": [],
+          "features": [
+            "**Review all time in Supervisor**: Supervisor now offers an all-time range from the earliest saved work records through the current time, making it easier to review long-running progress.",
+            "**Review sources only after they settle**: Messages that are still streaming and tasks that are still running wait until completion before entering a review, so review content does not change underneath an active run."
+          ],
+          "fixes": [
+            "**Make Magic Notes actions easier to understand**: Note entry points and actions now use clearer text labels, while secondary actions appear when needed to reduce confusion and visual noise.",
+            "**Contain terminal IME layout**: Chinese and other composition input in the terminal now stays inside the terminal bounds instead of expanding into or obscuring surrounding UI."
+          ],
+          "notices": [
+            "First launch upgrades the database to schema 63. Close the app and back up the complete data directory, adjacent `notes/`, and settings files before upgrading; Agent 0.15.6 does not need to be updated."
+          ]
+        }
+      }
+    },
+    {
+      "version": "0.16.1",
+      "releasedAt": "2026-10-10",
+      "notes": {
+        "zh-CN": {
+          "highlights": [],
+          "features": [],
+          "fixes": [
+            "**让消息自然延伸到输入框边缘**：修复聊天消息在输入框上方提前被实色区域截断的问题，现在消息会沿着输入框轮廓自然淡出，输入区和消息区的过渡更平滑。",
+            "**改善输入框与消息区的主题适配**：调整浅色和深色主题下的渐变、背景和焦点边界，减少输入框上方出现粗边或明显横线的问题；滚动到底部按钮也会保持合适的可见位置。"
+          ],
+          "notices": [
+            "本版本不新增数据库 schema，Agent 0.15.6 无需更新。"
+          ]
+        },
+        "en-US": {
+          "highlights": [],
+          "features": [],
+          "fixes": [
+            "**Let messages fade naturally to the composer edge**: Chat messages no longer stop at a solid band above the composer. They now fade along the composer outline for a smoother transition between the message area and input area.",
+            "**Improve composer and message-area theme behavior**: Light and dark theme gradients, backgrounds, and focus boundaries are refined to reduce thick edges and visible horizontal bands above the composer; the scroll-to-bottom control also remains positioned for clear access."
+          ],
+          "notices": [
+            "This release adds no database schema version. Agent 0.15.6 does not need to be updated."
+          ]
+        }
+      }
+    },
+    {
+      "version": "0.16.0",
+      "releasedAt": "2026-10-09",
+      "notes": {
+        "zh-CN": {
+          "highlights": [],
+          "features": [
+            "**在输入框中选择专家或团队角色**：发送消息前可以直接在输入框顶部选择专家或团队角色，选择入口更接近实际发送操作。每个会话独立保存自己的选择，切换会话时不会误用其他会话的角色。",
+            "**保留历史消息使用的角色**：已发送的回复会保留请求当时使用的专家或团队角色，即使之后重命名或删除该角色，历史记录仍能准确显示当时的使用情况。"
+          ],
+          "fixes": [],
+          "notices": [
+            "本版本不新增数据库 schema，Agent 0.15.6 无需更新。"
+          ]
+        },
+        "en-US": {
+          "highlights": [],
+          "features": [
+            "**Choose an expert or team role from the composer**: Select an expert or team role directly at the top of the composer before sending a message. Each conversation keeps its own selection, so switching conversations does not accidentally carry over another conversation’s role.",
+            "**Preserve the role used by historical messages**: Sent replies retain the expert or team role selected when the request was made. Later renaming or removing that role does not make existing history lose the context of how it was produced."
+          ],
+          "fixes": [],
+          "notices": [
+            "This release adds no database schema version. Agent 0.15.6 does not need to be updated."
+          ]
+        }
+      }
+    },
+    {
+      "version": "0.15.14",
+      "releasedAt": "2026-10-09",
+      "notes": {
+        "zh-CN": {
+          "highlights": [],
+          "features": [],
+          "fixes": [
+            "**恢复历史监督回顾的继续操作**：对于旧版本遗留的“来源已变化或已移除”失败回顾，现在可以直接从监督活动中继续，而不必重新开始整个回顾。",
+            "**让变化中的来源能够有界地重新纳入回顾**：来源在回顾期间发生变化时，系统会重新冻结并处理有限次数；持续变化的来源会被省略，避免回顾无法结束。已删除、归档或不再可用的来源会按现有规则安全省略，同时保留其余来源的进度。",
+            "**改进监督活动状态**：监督活动继续保留暂停、失败、取消和已保存批次的状态，继续操作不会绕过项目范围和来源处理规则。",
+            "**让设置分类更易识别**：设置页的分类现在显示对应图标，帮助用户更快找到外观、模型、Runtime、通道和其他设置。"
+          ],
+          "notices": [
+            "本版本不新增数据库 schema，继续使用 schema 62。监督回顾可能产生模型调用费用；持续变化的来源会被有限次数地重新处理，之后自动省略。"
+          ]
+        },
+        "en-US": {
+          "highlights": [],
+          "features": [],
+          "fixes": [
+            "**Resume historical Supervisor reviews**: Reviews left in the legacy “source changed or was removed” failure state can now be continued directly from Supervisor Activity instead of restarting the entire review.",
+            "**Re-review changing sources within a bound**: When a source changes during a review, GoodBuddy re-freezes and processes it for a limited number of attempts. A source that keeps changing is then omitted so the review can finish. Deleted, archived, or unavailable sources continue to be omitted under the existing rules while surviving progress is retained.",
+            "**Improve Supervisor activity state**: Paused, failed, cancelled, and partially saved review states remain available, and resuming a review continues to follow the project-scope and source-processing rules.",
+            "**Make settings categories easier to scan**: Settings categories now show matching icons, helping users find Appearance, Models, Runtime, Channels, and other settings more quickly."
+          ],
+          "notices": [
+            "This release adds no database schema version and remains on schema 62. Supervisor reviews may use model calls; continuously changing sources are reprocessed a limited number of times and then omitted."
+          ]
+        }
+      }
+    },
     {
       "version": "0.15.13",
       "releasedAt": "2026-10-07",

sites/README.md

@@ -1,6 +1,6 @@
 # GoodBuddy 静态官网
 
-`sites` 是无需构建步骤或额外依赖的中英文静态官网源码，可直接托管整个目录。
+`sites` 包含中英文官网和使用 VitePress 默认主题的用户手册。官网可直接预览；手册正文使用 Markdown 维护，发布前需要构建。
 
 正式站点地址：<https://mesalogo.github.io/goodbuddy/>
 
@@ -16,7 +16,7 @@ x64 / arm64 安装包与独立龙芯 loong64 预览版，并说明兼容性与
 首屏示意显示所选 Runtime，不展示 Ask / Execute 模式或一般工具审批。工具说明以
 已启用能力和 MCP 服务分配为准；站点校验会检查中英文页面中的旧模式文案与控件。
 FAQ 使用原生 details/summary，说明模型费用、数据流向、组件准备和远端使用条件。
-英文页面位于 `en.html`，用平台与架构覆盖描述同一产品事实，不使用中文信创
+英文页面位于 `en.html`，用户手册由 `docs/content/` 中按功能拆分的 Markdown 内容构建到 `docs-dist/`。英文页面用平台与架构覆盖描述同一产品事实，不使用中文信创
 政策语汇；页面会标明独立的 LoongArch 实验预览，但三个平台的下载按钮仍始终
 前往 GitHub 最新正式 Release。
 首屏产品界面默认正面展示，在精确指针设备上使用克制的 3D 倾斜、
@@ -26,7 +26,7 @@ FAQ 使用原生 details/summary，说明模型费用、数据流向、组件准
 ## 部署
 
 `.github/workflows/pages.yml` 会在 `main` 分支中的官网文件发生变化后，
-校验并部署整个 `sites` 目录。工作流也支持在 GitHub Actions 中手动运行。
+安装依赖、构建手册、校验并部署整个 `sites` 目录。工作流也支持在 GitHub Actions 中手动运行。
 
 首次部署前，需要在 GitHub 仓库的 **Settings > Pages** 中将 **Source**
 设为 **GitHub Actions**。站点使用项目 Pages 地址，不需要 `CNAME` 文件
@@ -42,17 +42,41 @@ FAQ 使用原生 details/summary，说明模型费用、数据流向、组件准
 
 ## 本地预览
 
+使用 Node.js 24，在仓库根目录安装依赖后运行 `npm run docs:dev`。访问终端显示的地址，在手册 base 下打开 `zh/` 或 `en/`，默认路径为 `/docs-dist/zh/` 和 `/docs-dist/en/`。Markdown 修改会触发热更新。
+
+预览构建产物时，先按下方命令使用本地 base 构建，再运行 `npm run docs:preview`；同样以终端显示的地址和端口为准，在 base 下打开 `zh/` 或 `en/`。
+
+### 维护手册
+
+- 章节顺序、双语标题和稳定 slug 维护在 `docs/manifest.ts`；VitePress 配置从该清单生成侧栏。
+- 中文正文放在 `docs/content/zh/`，英文正文放在 `docs/content/en/`。每个语言目录都必须包含 manifest 中的十二个 slug：`start`、`concepts`、`connections`、`runtimes`、`workbar`、`knowledge`、`notes`、`tasks`、`supervision`、`remote`、`privacy`、`troubleshooting`。
+- 每个章节文件以一个 `#` 标题开始，正文使用 `##` 和 `###`。除 `start.md` 的 `##` 章节标题外，其余文件的 `#` 标题应与 manifest 对应语言的标题一致。标题尽量使用普通文字。
+- VitePress 根目录为 `docs/`，`srcDir` 为 `content`。新增章节时添加两份 Markdown 并更新 manifest，同时更新校验脚本中的必需章节清单。
+- `zh/start.md` 和 `en/start.md` 分别重写为 `zh/index.md` 和 `en/index.md`，入口为 base 下的 `zh/` 和 `en/`；其余章节路径为 `zh/<slug>.html` 和 `en/<slug>.html`。
+- 配置维护在 `docs/.vitepress/config.mts`，使用默认主题的本地搜索、双语侧栏和原生语言切换，不维护自定义主题或布局。
+- 生产 base 为 `/goodbuddy/docs-dist/`，开发与预览默认使用 `/docs-dist/`，可用 `DOCS_BASE` 覆盖。构建和预览的 base 必须一致。开始页下载链接使用正式官网绝对地址：`https://mesalogo.github.io/goodbuddy/#download` 和 `https://mesalogo.github.io/goodbuddy/en.html#download`。
+- `docs-dist/` 是构建产物，已忽略，不手工编辑或提交。
+
+整站预览前先构建，以下命令在仓库根目录执行：
+
+```powershell
+$env:DOCS_BASE='/docs-dist/'
+npm run docs:build
+Remove-Item Env:DOCS_BASE
+```
+
 在仓库根目录运行：
 
 ```powershell
 python -m http.server 4173 --bind 127.0.0.1 --directory sites
 ```
 
-然后访问 <http://localhost:4173/>。也可以直接用浏览器打开 `sites/index.html`。
+然后访问官网 <http://127.0.0.1:4173/> 或 <http://127.0.0.1:4173/en.html>，中文手册 <http://127.0.0.1:4173/docs-dist/zh/>，英文手册 <http://127.0.0.1:4173/docs-dist/en/>。手册需要通过 HTTP 服务预览。
 
 ## 校验
 
 ```powershell
+npm run docs:build
 node sites/scripts/validate.mjs
 node --check sites/app.js
 node --check sites/language.js
@@ -68,6 +92,7 @@ node --test sites/scripts/app.test.mjs sites/scripts/release-index.test.mjs
 不可变 URL，并按发布生成器的实际命名绑定版本、平台、架构和格式。移动
 导航行为测试同时覆盖现代 MediaQueryList 监听与旧版 Safari 的 `addListener`
 回退。英文下载入口固定指向 GitHub Release。
+手册校验覆盖全部 24 个构建章节的服务端渲染标题与正文、双语侧栏、语言切换和本地资源，并检查 Markdown 标题与 manifest 一致。上述命令检查生产 base；若检查本地构建，运行校验脚本时也设置 `DOCS_BASE='/docs-dist/'`。
 
 ## 下载入口
 
@@ -173,10 +198,24 @@ SIL OFL 1.1 许可证位于 `assets/fonts/inter-OFL.txt`。
 焦点，切换回桌面宽度也会解除隔离。媒体查询监听兼容现代浏览器和使用
 `MediaQueryList.addListener` 的旧版 Safari。
 
+## 手册开发
+
+手册正文维护在 `docs/content/zh/` 与 `docs/content/en/`，章节清单维护在
+`docs/manifest.ts`，主题、语言、侧栏和本地搜索配置维护在 `docs/.vitepress/config.mts`。本地开发运行：
+
+```powershell
+npm run docs:dev
+```
+
+发布前清除本地 `DOCS_BASE` 覆盖并运行 `npm run docs:build`。VitePress 将中英文各十二个章节及资源生成到 `docs-dist/`，入口为 `docs-dist/zh/index.html` 和 `docs-dist/en/index.html`。Pages 工作流会在校验前自动构建；不要直接编辑构建产物。
+
 ## 文件
 
 - `index.html`：页面结构与简体中文内容
 - `en.html`：不包含信创适配文案的英文页面
+- `docs/content/zh/`、`docs/content/en/`：按功能拆分的中英文手册 Markdown 正文
+- `docs/manifest.ts`：手册章节顺序、标题和中英文映射
+- `docs/.vitepress/config.mts`：VitePress 默认主题、语言、路由、本地搜索和构建配置，输出到 `docs-dist/`
 - `styles.css`：语义令牌、浅深主题、焦点与响应式布局
 - `app.js`：主题、移动导航、当前章节和中文下载索引
 - `language.js`：浏览器语言自动选择与手动语言偏好

sites/docs/.vitepress/config.mts

@@ -0,0 +1,55 @@
+import { defineConfig } from 'vitepress'
+import { chapters } from '../manifest'
+
+const base = process.env.DOCS_BASE ?? '/goodbuddy/docs-dist/'
+
+const sidebar = (language: 'zh' | 'en') => [
+  {
+    text: language === 'zh' ? '用户手册' : 'User guide',
+    items: chapters.map(({ slug, title }) => ({
+      text: title[language],
+      link: `/${language}/${slug === 'start' ? '' : `${slug}.html`}`,
+    })),
+  },
+]
+
+export default defineConfig({
+  title: 'GoodBuddy',
+  description: 'GoodBuddy user guide',
+  base,
+  srcDir: 'content',
+  rewrites: {
+    'zh/start.md': 'zh/index.md',
+    'en/start.md': 'en/index.md',
+  },
+  locales: {
+    root: { label: 'English', lang: 'en', link: '/en/' },
+    zh: { label: '简体中文', lang: 'zh-CN', link: '/zh/' },
+  },
+  themeConfig: {
+    siteTitle: 'GoodBuddy',
+    search: { provider: 'local' },
+    outline: 'deep',
+    sidebar: {
+      '/zh/': sidebar('zh'),
+      '/en/': sidebar('en'),
+    },
+    socialLinks: [{ icon: 'github', link: 'https://github.com/mesalogo/goodbuddy' }],
+    locales: {
+      root: {
+        langMenuLabel: '语言',
+        nav: [
+          { text: 'Home', link: 'https://mesalogo.github.io/goodbuddy/en.html' },
+          { text: 'GitHub', link: 'https://github.com/mesalogo/goodbuddy' },
+        ],
+      },
+      zh: {
+        langMenuLabel: 'Languages',
+        nav: [
+          { text: '官网首页', link: 'https://mesalogo.github.io/goodbuddy/' },
+          { text: 'GitHub', link: 'https://github.com/mesalogo/goodbuddy' },
+        ],
+      },
+    },
+  },
+})

sites/docs/content/en/concepts.md

@@ -0,0 +1,25 @@
+# Core concepts
+
+GoodBuddy connects conversations, model requests, and file work through a small set of related objects. Knowing these objects makes Runtime selection, knowledge scope, and execution history easier to understand.
+
+## Projects and conversations
+
+A Project is a working scope with a project directory, project Runtime choice, conversations, and tasks. A Conversation is a continuing chat record containing messages, tool activity, and citations. A conversation may have no Task or several Tasks; linking a Task does not change the conversation type.
+
+## Model connections and Runtimes
+
+A model connection is a reusable service configuration with a URL, protocol, model name, and credentials. A Runtime is the way a request runs: Direct models are called by GoodBuddy, while OpenCode and Continue use their native agent clients and DeepSeek Harness uses GoodBuddy's compatible managed path. See [Choose a Runtime](./runtimes.html).
+
+A Runtime uses the selected capabilities and current account permissions. A project can define the default choice, and a conversation can inherit it or select its own. If a connection is deleted or incompatible, the picker explains the fallback or failure instead of silently choosing another credentialed model.
+
+## Capabilities and execution spaces
+
+A capability is something a request may use, such as knowledge retrieval, workspace files, a terminal, a browser, or an MCP service. Availability depends on the Runtime, project settings, conversation scope, and execution space. An execution space is where files, terminals, managed processes, and the Runtime actually run: a local project directory or a remote SSH project directory.
+
+## Task, Job, and Run
+
+A Task is work that the user explicitly creates or confirms, and it has exactly one associated Conversation. A Job is an internal step or scheduled occurrence within a Task. A Run is one execution attempt and record for a Job or subjob. Ordinary chat requests, tool calls, and Runs do not become Tasks automatically. The UI primarily exposes Tasks; Job and Run details appear through activity and execution records when available.
+
+## No Ask / Execute mode
+
+GoodBuddy has no Ask / Execute work mode and does not require a mode switch before using an enabled capability. A normal request uses the selected Runtime, enabled capabilities, and current account permissions. If a Runtime lacks a capability, GoodBuddy reports that limitation. Summaries, note analysis, and supervision reviews remain dedicated text requests without tools.

sites/docs/content/en/connections.md

@@ -0,0 +1,19 @@
+# Configure model connections
+
+A model connection stores a service URL, protocol, model name, authentication method, and optional request customization. Projects and conversations can reuse it, while credentials remain managed by GoodBuddy's main process. A usable connection does not mean every Runtime supports every field.
+
+## Create and test a connection
+
+Open Settings > Model connections > LLM. Create a connection with a name, HTTP or HTTPS URL, protocol, model ID, and API key. Save it and run Test connection. A successful test proves that the basic connection works; image generation, tools, and native Runtime clients still need their own real request path.
+
+Connections can be copied. Copy creates a new connection and leaves the original unchanged. A saved key is copied through the protected credential path and is never returned to the page or error text. Choose the connection in a project or conversation picker, or choose the Runtime default.
+
+## Custom headers and body
+
+The Advanced settings area has two JSON editors. Headers must be an object whose values are strings, and the body must be a serializable top-level JSON object. Syntax, type, size, and reserved-field errors block saving while keeping the original text for correction.
+
+Runtime, protocol, and authentication fields take precedence. Custom values cannot replace model, message, tool, streaming, or authentication fields. Body values merge only at the top level. Keep API keys and other secrets in the dedicated credential field. Direct models and Continue support both customizations; local OpenCode and DeepSeek Harness support headers but not custom body; managed remote OpenCode supports both.
+
+## Scope and diagnostics
+
+Connections are Settings resources; projects and conversations store the selection relationship. Vector connections are for knowledge indexing and do not appear in Runtime model pickers. For diagnosis, test the basic connection first, then confirm the Runtime and model used by the real request. If custom values appear to cause failure, clear them temporarily. A connection test is not a generation guarantee.

sites/docs/content/en/knowledge.md

@@ -0,0 +1,17 @@
+# Build a knowledge base
+
+A knowledge base brings local sources or a configured external knowledge service into retrieval. For a first setup, create a base, add sources, wait until it is searchable, and use it in the current conversation.
+
+## Local workflow
+
+Create a local base, add files, directories, or web sources, and wait for parsing and indexing. In the composer, explicitly select the knowledge scope and choose Model retrieves when needed or Retrieve before every request. Open citations to inspect the matching chunk, surrounding context, and source.
+
+Knowledge scope is stored per Conversation. New conversations start with no selected base, and creating a base does not re-enable other bases you turned off. Each request uses only its explicit scope. The first mode lets the model decide whether to use read-only search; the second searches before the Runtime starts and shows zero results or degradation. Image generation does not run the pre-search.
+
+Local retrieval can use full-text, Chinese phrase, vector, and graph channels. A citation is bounded evidence for the request, not proof that every answer sentence came from it. Check parsing, full-text, vector, and graph status separately. Vector failure can leave full-text and Chinese retrieval available, with the degraded channel shown. A failed rebuild keeps the last ready index.
+
+## External knowledge bases
+
+GoodBuddy can manage Dify, FastGPT, and RAGFlow instances and bind a remote base into the local list. Retrieval sends only the current query, remote ID, and saved settings. GoodBuddy checks returned chunks before showing citations.
+
+External bindings are read-only. GoodBuddy does not create, edit, upload, or delete remote bases, documents, chunks, or graphs, and does not bulk-sync them. Removing a local binding does not delete remote data. Authentication, timeout, target, and provider failures remain visible and do not silently switch instances.

sites/docs/content/en/notes.md

@@ -0,0 +1,21 @@
+# Use Magic Notes
+
+Magic Notes is for meeting records, research drafts, ideas, and long-term plans. Notes are application-level data. The full workspace supports rich text, todos, and paged canvases, while the workbar provides quick browsing and appending.
+
+## Capture conversation content
+
+Choose Add to note from an assistant response, or Save current conversation to note from the conversation menu. Review the preview, source, and destination, then explicitly save. A full capture contains completed user and assistant text, preserving Markdown, line breaks, and code. Reasoning, tool logs, system prompts, binary attachments, and images are excluded.
+
+Saved entries keep structured source information. Open a source to return to the conversation or locate the message. If the source is later removed, the note body remains and the source is marked unavailable. A failed save keeps the preview and destination for retry; cancelling writes nothing.
+
+## Quick panel and full workspace
+
+Open + > Notes in the workbar to search notes, view summaries, and append text. The panel and full workspace share storage, so successful writes appear in both. Unsaved drafts stay in app memory and are protected when changing project, conversation, or workbar visibility. Leaving the panel asks whether to keep or discard a changed draft.
+
+Tags are manual. A note can have up to 10 case-insensitive tags; filter by tags or rename, merge, and delete them in tag management. Deleting a tag does not delete notes.
+
+## Canvas and AI comments
+
+Paged canvases support templates, text, handwriting, highlights, images, and PDF backgrounds. Canvas saves are manual. Zoom changes viewing only; there is no infinite canvas or separate PNG download.
+
+Request AI comments manually, or enable analysis after save. Comments use the default model's image input and the first 1 to 8 configured pages. Visual-only content requires an image-capable model; a text-only model uses a labelled text fallback. Analysis failure never undoes saved content and does not append again automatically.

sites/docs/content/en/privacy.md

@@ -0,0 +1,19 @@
+# Data and privacy
+
+GoodBuddy is a local-first desktop app and does not require a GoodBuddy account. Whether data leaves the computer depends on the model connection, Runtime, knowledge type, remote project, and browser features you use.
+
+## Data flow
+
+Local conversations, notes, tasks, settings, and knowledge indexes are stored in the application-data directory. Direct models send requests to the selected service; OpenCode, Continue, and Harness call models according to their Runtime configuration. Installing GoodBuddy or opening an empty conversation does not upload history.
+
+With a local knowledge base, sources and indexes stay local and the Runtime receives bounded evidence and citations selected for the request. With Dify, FastGPT, or RAGFlow, the query goes to the configured instance. GoodBuddy does not upload the full conversation or local attachments or write to the external base. Returned bounded chunks and citations are stored with the local conversation.
+
+## Credentials and boundaries
+
+API keys, SSH credentials, and authentication data are managed by Main and protected storage; the Renderer does not read them directly. Custom headers and bodies are ordinary settings, not a place for secrets. Tools, MCP, terminals, and plugins use current-user permissions and enabled capabilities. Ask / Execute is not a separate privacy boundary.
+
+Remote projects send bounded model configuration to an authenticated Agent, where requests run with SSH account permissions. The Agent is not bundled with the desktop package. Reconnect restores confirmed Agent output; uncertain model calls are not replayed automatically.
+
+## Preview and clearing data
+
+Conversation HTML preview handles completed assistant HTML only. Scripts, network requests, forms, nested pages, and window operations are disabled; turning preview off still shows source. Clear local data is an explicit confirmed action and does not delete provider records, remote hosts, remote bases, exported files, or files saved in a workspace.

sites/docs/content/en/remote.md

@@ -0,0 +1,21 @@
+# Remote projects
+
+Remote projects run Workspace, terminals, and supported Runtimes on an SSH host. A remote path is never treated as local. Files, processes, network access, and model calls are bounded by the SSH account and prepared environment. The GoodBuddy Agent is not included in the desktop installer.
+
+## Prepare an SSH host
+
+Add a Host in remote-project settings with its address, port, user, and authentication method. Before authentication, inspect and explicitly accept the Host Key algorithm and SHA-256 fingerprint. A changed fingerprint requires a separate replacement confirmation. GoodBuddy can use the system SSH Agent or supported certificates; root and SSH Agent Forwarding are not required.
+
+Saving a Host does not mean the environment is ready. Use the Host card to prepare or update the signed Agent and Runtime, then wait for checks. A version-match badge is only a version fact. Failed, cancelled, or disconnected preparation keeps the Host and offers retry.
+
+## Create a project and use its space
+
+Choose a verified Host, enter or select a bounded remote workspace directory, and choose a supported Runtime such as OpenCode or Continue. The project stores the Host ID, remote path, and Runtime choice. Switching projects changes local selection only; the Agent is attached when Workspace or Runtime is first used.
+
+Remote Workspace provides bounded directories, previews, Git, and import. A terminal uses the remote shell. Operations use the SSH account permissions. Local Skills, stdio MCP servers, and tool environments are not uploaded automatically; remote capabilities are those reported by the Agent.
+
+## Failures and boundaries
+
+Check network, port, Host Key, credentials, directory permissions, Agent version, Runtime version, and project permissions separately. If the Agent is unavailable, GoodBuddy does not fall back to an SSH stdio Runtime or secretly run the request locally.
+
+An SSH relay disconnect does not necessarily stop an accepted request. Reconnect restores only output recorded and confirmed by the Agent. An uncertain model call is not replayed automatically because it could duplicate cost or side effects. Stop, Agent shutdown, and remote process failure are shown as cancellation, failure, or unknown outcome.

sites/docs/content/en/runtimes.md

@@ -0,0 +1,22 @@
+# Choose a Runtime
+
+A Runtime selects the execution path for a request. A connection answers which model service to call, while the Runtime organizes the request, tools, and execution space. Each request retains visible status, tool activity, cancellation, and failure information.
+
+## The four choices
+
+| Runtime | Best for | Model configuration |
+| --- | --- | --- |
+| Direct models | Chat, retrieval, image generation, and GoodBuddy capabilities | GoodBuddy model connections |
+| OpenCode | Coding agents, files, commands, and Skills | GoodBuddy connection or OpenCode config |
+| Continue | Rules, prompt presets, and coding work | GoodBuddy connection or Continue config |
+| DeepSeek Harness | A fixed host and compatible plugin capabilities | GoodBuddy-managed compatible connection |
+
+Use Direct models for ordinary questions and retrieval. Choose OpenCode or Continue for continuing project-file and command work. Choose DeepSeek Harness when its fixed host capabilities fit. Tools and native questions differ by Runtime.
+
+## Selection and capabilities
+
+A project selects a concrete Runtime. A conversation follows the project by default, while the composer can select its own choice. The picker shows defaults, individual connections, and Runtime-owned configuration with their source. Requests use the Runtime, enabled capabilities, knowledge scope, execution space, and current account permissions.
+
+GoodBuddy has no Ask / Execute mode and no separate general tool-approval switch. Unsupported capabilities are reported clearly. Local Runtimes run locally; remote projects use the Agent and managed Runtime on the SSH host. The Agent is not bundled with the desktop app; see [Remote projects](./remote.html).
+
+The workbar shows Runtime, connection, tool state, cancellation, errors, and saved results. Closing a panel does not cancel background work, and stopping a request affects that request only.

sites/docs/content/en/start.md

@@ -0,0 +1,30 @@
+# GoodBuddy User Guide
+
+This guide is for a first GoodBuddy session. No GoodBuddy account is required. Conversations, projects, and notes are local by default; model providers, remote hosts, and external knowledge services receive data only when you configure and use them.
+
+## Get started
+
+### Install GoodBuddy
+
+Choose a platform, processor architecture, and package from the [home page](https://mesalogo.github.io/goodbuddy/en.html#download). Windows provides an installer and a portable ZIP. Linux provides AppImage, DEB, and RPM. LoongArch uses a separate experimental preview channel. Start the app after installation; the first launch does not require sign-in.
+
+### Initial setup
+
+1. Open Settings, confirm the local data location, and prepare a text model connection.
+2. In Model connections, enter the service URL, protocol, model name, and credentials, then run a connection test. See [Configure model connections](./connections.html) for the field rules.
+3. Create a project and choose its project directory and Runtime. A project groups conversations, workspace access, and tasks.
+4. Open or create a conversation and send a simple question first. Once that works, try files, knowledge, or remote operations.
+
+### Projects and conversations
+
+A project is a working scope that can contain many conversations. A conversation stores user messages, assistant replies, tool activity, and citations; it can also be associated with multiple tasks. New conversations usually inherit the project Runtime choice, while the composer can select a conversation-specific choice.
+
+When changing projects or working directories, check the workspace and terminal scope in the [assistant workbar](./workbar.html). Before sending a request, confirm the Runtime, model, and knowledge scope so content goes to the intended service.
+
+### Local data
+
+Conversations, notes, task records, knowledge indexes, and settings are stored in the system application-data directory. Clear local data is an explicit Settings action with confirmation. Uninstalling the app does not delete exported files, remote directories, or provider-side records. See [Data and privacy](./privacy.html) for the data boundaries.
+
+### Continue reading
+
+Read [Core concepts](./concepts.html) for the relationship between projects, conversations, and Runtimes. Then configure a [knowledge base](./knowledge.html), create [tasks](./tasks.html), or set up a [remote project](./remote.html).

sites/docs/content/en/supervision.md

@@ -0,0 +1,25 @@
+# Supervision
+
+Supervision reviews completed work, highlights changes and issues, and records supported results in the story graph. It does not send messages, approve tools, expand file scope, or change execution permissions. The Supervisor app is off by default.
+
+## Enablement and scope
+
+Enable Supervisor in the app center, then choose the default text model or an existing text connection in Settings. The first review requires an explicit project, conversation, and time range. Automatic supervision can target Global or selected projects; changing the active project does not change a saved scope.
+
+## Review and story graph
+
+Work review reads conversations, Tasks, notes, and sources within the selected scope and produces sourced summaries, changes, and unresolved items. With no valid new change it records no change and does not call the model. Review is incremental by default; use Reorganize for a historical interval.
+
+The story graph presents events, entities, relationships, and changes over time. Select an object to inspect its sources. Conversations, notes, and knowledge bases remain the owners of source text. You can continue a discussion after checking evidence or preview a write to a local knowledge base. External knowledge remains read-only.
+
+## Follow, pin, and intervene
+
+The Supervision panel can follow the active conversation or pin to a conversation or Task. A pinned target stays selected across page changes and reports an error if it becomes unavailable. Suggestions create editable drafts or explicit next actions; they enter a conversation only after you choose to send them.
+
+Supervisor does not execute suggestions and cannot send messages, approve tools, change capability switches, or expand workspace access. Its model calls are internal text requests without tools.
+
+## Heartbeat and failures
+
+Smart Heartbeat is the scheduled wake-up mechanism. It checks incremental changes within its scope and generates suggestions or updates memory according to the plan. The app and each plan have separate enabled states; disabling the app prevents new heartbeat runs, while an already started run may finish.
+
+Pause, cancel, and failure keep the last successful result and saved batches. The run shows covered and omitted scope and can be retried when valid. A failed suggestion stage does not undo a published graph or review. Supervisor being off by default does not affect ordinary chat or Tasks.

sites/docs/content/en/tasks.md

@@ -0,0 +1,19 @@
+# Tasks
+
+A Task is work that you explicitly create or confirm. It has exactly one associated Conversation, while one Conversation can have several Tasks. Ordinary chat requests and tool calls do not appear in Task Center automatically.
+
+## Immediate and scheduled work
+
+Choose New task in Task Center or the conversation task area. Enter the request; the name can be blank and GoodBuddy will derive one. Immediate execution is the default. You can choose a one-time, daily, or weekly schedule and select the current conversation, another conversation in the project, or a new conversation. The request, conversation, and schedule are submitted together.
+
+A Task uses the associated conversation's Runtime, capabilities, knowledge scope, and workspace when it runs. It has no Ask / Execute mode and does not gain permission because it runs in the background. A new conversation does not copy source history.
+
+## Task, Job, and Run
+
+Task is the user-facing object. An immediate run, schedule occurrence, or retry may create internal Jobs and Runs, but they do not become new Task entries. Task Center aggregates status, progress, schedule, and attention items; Activity and Runtime panels provide detail.
+
+A recurring schedule remains one Task. Pause, resume, run now, and cancel act on the Task. Deleting it normally stops future scheduling while keeping the Conversation and messages. Deleting one queued occurrence does not delete the Task.
+
+## Queue and Heartbeat
+
+Normal and Task messages use the same Conversation queue. A due occurrence waits while a reply is running. You can remove an unstarted item or choose Run now and interrupt. Later items can continue after cancellation or failure. Smart Heartbeat is not a Task Center item; it belongs to [Supervision](./supervision.html) and wakes incremental reviews and suggestions.

sites/docs/content/en/troubleshooting.md

@@ -0,0 +1,23 @@
+# Troubleshooting
+
+First confirm the current project, conversation, Runtime, model, and local or remote execution space. Check request status and activity before repeating a send or rebuilding all data.
+
+## The model connection test fails
+
+Check protocol, URL, model ID, API key, proxy, certificate, and provider limits. Clear custom headers and body temporarily and test again. If the basic test succeeds but generation fails, confirm the Runtime and model capability; a connection test is not a generation guarantee.
+
+## The reply does not use tools or files
+
+Check Runtime support, execution space, workspace directory, enabled capability or MCP service, and account permissions. Open Workspace or Runtime in the workbar. For remote projects check SSH, Agent readiness, remote path, and Agent version. GoodBuddy has no Ask / Execute mode.
+
+## Knowledge retrieval returns nothing
+
+Check the conversation scope, parsing and full-text status, vector compatibility, and OCR for image-only PDFs. Use Test retrieval to see actual channels and degradation. Test with source words first, then rebuild a failed document or index. External bases also require valid authentication, remote ID, timeout, and provider status.
+
+## A note, Task, or remote project failed
+
+For notes and canvases, confirm that Save was explicitly used; AI comment failure does not undo saved content. For Tasks, check enabled state, pause state, associated conversation, app availability, and the latest error. Heartbeat is off by default. For remote work, check network, Host Key, credentials, permissions, and Agent preparation. Uncertain remote calls are not replayed automatically.
+
+## HTML preview is empty or shows source
+
+Check that the reply is complete, recognizable HTML or an `html`/`htm` block, and HTML rendering is enabled. Streaming replies, user messages, and reasoning remain source text. Scripts, network, forms, and window operations are intentionally disabled in the preview.

sites/docs/content/en/workbar.md

@@ -0,0 +1,25 @@
+# Assistant workbar
+
+The assistant workbar is the application-level workspace on the right side of the main window. It is not attached to one chat message. Chat, knowledge, task, and supervision pages can open it to show tasks, workspace, Runtime, terminals, browser tabs, notes, and supervision status.
+
+## Panels and the add menu
+
+Task Center and Workspace are always-present base panels. Use the + menu to open Runtime, Supervision, Terminal, Processes, Browser, Resources, Documents, or Notes. Terminals and browsers can have multiple instances; Notes is single-instance. Background events update badges or notifications without taking over the current panel.
+
+An open panel shows its capability, instance, and target. When a capability is unavailable, the panel explains why and provides a configuration path instead of silently hiding it. Terminals, logs, and large results may offer right, bottom, or separate-window docking.
+
+## Follow and pin
+
+Panels that can bind to a target have two scope choices: follow the active context, or pin to a conversation, Task, project, Runtime, terminal, workspace, or browser session. Follow mode changes with the project or conversation. Pinned mode stays on its target. If a pinned target disappears, the panel reports that it is unavailable and offers a repair path rather than switching silently.
+
+The active context is only a default. Opening Workspace does not expand file access, and choosing a temporary directory does not silently change project settings. GoodBuddy still validates the project, execution space, and capability before an operation.
+
+## Execution-space boundaries
+
+Workspace shows the current project directory or a local or remote directory that you explicitly choose. A new terminal binds to the project execution space and directory; with no project it uses the local home directory. Browser manages only GoodBuddy-controlled browser tabs, not a browser already open on your system. Processes shows processes created or managed by GoodBuddy, not every system process.
+
+Workspace supports file previews, Git status, and bounded directory operations. A remote workspace uses the Agent on the SSH host and does not pretend that a remote path is local. Terminal input, file operations, browser activity, and Runtime execution each keep their own scope; selecting one panel does not grant another panel more access.
+
+## A practical combination
+
+For project work, let Task Center follow the current project and pin Supervision to one conversation. Use Workspace to inspect files and create a terminal for commands. When reviewing activity, check the project, conversation, Runtime, and local or remote label at the top of the panel. Open a Task for its complete user-facing relation; Job and Run are not separate workbar panels.

sites/docs/content/index.md

@@ -0,0 +1,11 @@
+---
+title: GoodBuddy User Guide
+layout: home
+---
+
+# GoodBuddy User Guide
+
+Choose a language to open the user guide:
+
+- [English](/en/)
+- [简体中文](/zh/)

sites/docs/content/zh/concepts.md

@@ -0,0 +1,25 @@
+# 核心概念
+
+GoodBuddy 把聊天、模型调用和文件操作放在几个相互关联的对象中。理解这些对象后，选择 Runtime、限制知识范围和查看执行记录会更容易。
+
+## Project 与 Conversation
+
+Project 是项目范围，包含项目目录、项目级 Runtime 选择、会话和任务。Conversation 是一条持续的聊天记录，保存消息、工具活动和引用。一条会话可以没有 Task，也可以关联多个 Task；关联 Task 不会改变会话类型。
+
+## 模型连接与 Runtime
+
+模型连接是可复用的服务配置，通常包含 URL、协议、模型名和凭据。Runtime 是执行请求的方式：直连模型由 GoodBuddy 调用模型服务，OpenCode 和 Continue 使用各自的 Agent 客户端，DeepSeek Harness 使用 GoodBuddy 管理的兼容执行路径。Runtime 的具体选择见[选择 Runtime](./runtimes.html)。
+
+Runtime 会使用当前选择的能力和当前账号权限。项目可以设置默认 Runtime，会话可以继承项目设置或单独选择。模型连接被删除或不兼容时，选择器会说明回退或失败原因，不会悄悄换成另一个有凭据的模型。
+
+## Capability 与执行空间
+
+Capability 是一次请求可以使用的能力，例如知识检索、工作区文件、终端、浏览器或 MCP 服务。能力是否可用取决于 Runtime、项目设置、会话范围和执行空间。执行空间是文件、终端、受管进程和 Runtime 实际运行的位置，可以是本机项目目录，也可以是远程 SSH 项目目录。
+
+## Task、Job 与 Run
+
+Task 是用户明确创建或确认的工作单位，并且只关联一条 Conversation。Job 是 Task 内部的一次步骤或一次调度触发，Run 是 Job 或子任务的一次执行尝试和记录。普通聊天请求、工具调用和 Run 不会自动变成 Task；用户界面主要展示 Task，Job 和 Run 的细节在活动和执行记录中按需查看。
+
+## 没有 Ask / Execute 模式
+
+GoodBuddy 不提供 Ask / Execute 工作模式，也不会要求先切换模式才能调用已启用的能力。普通请求直接使用所选 Runtime、已启用能力和当前账号权限。某个 Runtime 不支持某项能力时，界面会报告能力缺失；内部摘要、笔记分析和监督回顾仍是专用的无工具文本请求。

sites/docs/content/zh/connections.md

@@ -0,0 +1,23 @@
+# 配置模型连接
+
+模型连接保存服务地址、协议、模型名称、认证方式和可选的请求定制。连接可以被多个项目和会话复用，但凭据仍由 GoodBuddy 的主进程管理。连接本身可用，不代表每个 Runtime 都支持它的全部字段。
+
+## 新建和测试
+
+进入“设置 → 模型连接 → LLM”，新建连接并填写名称、HTTP 或 HTTPS 地址、协议、模型 ID 和 API Key。保存后执行“测试连接”。测试成功只说明当前连接的基础请求可达；图片生成、工具调用或某个 Runtime 的原生客户端仍需在实际请求中验证。
+
+连接可以复制。复制会生成新的连接，不会修改原连接；已保存的密钥通过安全凭据路径复制，不会回显到页面或错误信息。需要在项目或会话中使用时，回到选择器选中连接或选择“跟随默认”。
+
+## 自定义 Header 和 Body
+
+连接详情底部的“高级设置”提供两个 JSON 编辑器。请求头必须是字符串值的 JSON 对象，例如 `{ "X-Team": "research" }`；请求体是可序列化的顶层 JSON 对象。语法、类型、大小或保留字段错误会阻止保存，并保留原始输入供修正。
+
+Runtime、协议和认证生成的字段优先，自定义字段不能替换模型、消息、工具、流式或认证字段。请求体是顶层浅合并，不会递归合并内部对象。API Key、Cookie、签名和其他秘密信息必须放在专用凭据字段，不要写入 Header 或 Body。
+
+直连模型和 Continue 支持两项定制；本地 OpenCode 和 DeepSeek Harness 支持自定义 Header，不使用自定义 Body；受管远程 OpenCode 在其模型网关支持两项。使用 Runtime 自有配置时不引用 GoodBuddy 连接，也不会应用连接级定制。
+
+## 范围和诊断
+
+连接是设置级资源，项目和会话只保存选择关系。向量连接只用于知识库索引，不会出现在 Runtime 模型选择器中。远程项目只能使用支持的远程 Runtime。连接地址变化、证书错误、缺少 API Key、模型不兼容和服务商限流都应在连接详情或请求状态中分别处理。
+
+诊断时先执行基础连接测试，再检查实际请求使用的 Runtime 和模型。若自定义字段导致失败，暂时清空 Header 和 Body 重测；若基础测试成功而生成失败，检查协议、模型能力、输出限制和服务商的实际接口，而不要把测试结果当作生成保证。

sites/docs/content/zh/knowledge.md

@@ -0,0 +1,31 @@
+# 建立知识库
+
+知识库把本地资料或已配置的外部知识服务接入对话检索。第一次使用按“创建知识库 → 添加资料 → 等待可检索 → 用于当前对话”的顺序操作；高级检索参数可以在基本流程可用后再调整。
+
+## 本地知识库流程
+
+1. 在知识库页面新建本地知识库，填写名称和描述。
+2. 添加文件、目录或网页来源，等待解析、全文索引和可选向量索引完成。
+3. 打开会话输入区的知识范围，明确勾选要使用的知识库。
+4. 选择“模型按需检索”或“每次先检索”，再发送问题。
+5. 打开回答中的引用，查看命中分块、相邻上下文和原始来源。
+
+知识范围属于 Conversation。新会话默认不勾选知识库；切换会话会恢复各自的选择。新建一个知识库只把它加入当前会话，不会重新启用你以前取消的其他库。每次请求只能使用当前明确选择的范围。
+
+## 检索方式和证据
+
+“模型按需检索”只开放当前范围的只读搜索能力，由模型决定是否查询；没有调用时不会显示虚假的“已检索”。“每次先检索”会在 Runtime 启动前先查一次，零结果、失败和降级都会显示，模型仍可在同一范围内继续查询。图片生成请求不执行知识预检索。
+
+本地检索可以使用全文、中文词组、向量和知识图谱通道。引用是本次检索得到的有界证据，不等于自动证明回答中的每一句话都来自该片段。点击引用可以核对来源；来源被移动或删除时显示失效，不会打开任意替代路径。
+
+## 状态、降级和维护
+
+分别查看解析、全文、向量和图谱状态。没有向量模型、查询向量失败、索引不兼容或部分文档失败时，全文和中文检索仍可用，但页面会标明降级原因，不会悄悄切换到另一个向量服务。重建失败时，上一版已就绪索引继续服务。
+
+分块设置修改后需要显式重建。重建或大规模检索可以取消；已完成的文档保持可用。原文件移动、解析失败、OCR 不可用和零结果都应按照页面给出的原因处理，而不要只看“索引完成”这一总状态。
+
+## 外部知识库
+
+知识库页面可以管理 Dify、FastGPT 和 RAGFlow 实例，并把远端知识库绑定到 GoodBuddy 的本地列表。检索只发送本次查询、远端知识库 ID 和已保存的检索参数；返回片段经过 GoodBuddy 校验后作为引用使用。
+
+外部绑定是只读的。GoodBuddy 不在外部实例中创建、修改、上传或删除知识库、文档、分块或图谱，也不批量同步远端资料。移除本地绑定不会删除远端内容；外部请求失败时显示实例、认证、超时或目标问题，不自动改用另一个实例。

sites/docs/content/zh/notes.md

@@ -0,0 +1,21 @@
+# 使用魔法笔记
+
+魔法笔记适合保存会议记录、研究草稿、灵感和长期计划。笔记属于应用级数据，不会因为你从哪个项目或会话打开它而改变归属。完整工作区支持富文本、待办和分页画布，助手工作栏提供快速浏览和追加。
+
+## 从会话保存内容
+
+在一条助手回答的操作菜单中选择“加入笔记”，或在会话更多菜单中选择“保存当前对话到笔记”。先检查预览、来源和目标，再选择已有笔记或新建笔记并明确保存。整段会话保存的是已完成的用户和助手文字，保留 Markdown、换行和代码文本；推理、工具日志、系统提示、附件二进制和图片不会写入正文。
+
+保存后的记录保留会话、项目、消息和采集时间等结构化来源。点击来源可以回到会话或定位消息；原会话或原消息后来删除时，笔记正文仍保留，并显示来源不可用。保存失败会保留预览、目标和输入，便于重试；取消不会写入。
+
+## 快速面板和完整工作区
+
+从工作栏“+ → 笔记”打开快速面板，可以搜索笔记、查看记录摘要和快速追加文字。面板与完整笔记工作区共享同一份存储，任一处成功写入后另一处会更新。未保存草稿保存在当前应用内存中，切换项目、会话或收起工作栏不会覆盖它；离开面板、关闭笔记或用另一条采集替换草稿时会要求选择继续编辑或放弃。
+
+完整工作区可编辑记录、管理待办、搜索和调整列表。标签由用户手动维护：每篇笔记最多 10 个标签，标签不区分大小写；可以按一个或多个标签筛选，也可以在标签管理中重命名、合并或删除标签。删除标签不会删除笔记内容。
+
+## 画布和 AI 评论
+
+分页画布支持纸张模板、文字、手写、高亮、图片和 PDF 底版。画布保存是手动操作；缩放和适应宽度只影响查看，不改变已保存内容或导出尺寸。画布没有无限画布，也不提供单独的 PNG 下载按钮。
+
+AI 评论由你手动触发，或在设置为保存后自动分析时于保存完成后触发。评论使用默认模型的图像输入能力，并按设置发送画布开头的 1 至 8 页。纯视觉内容需要图像模型；文字模型只能使用明确标记的文字降级。分析失败不会撤销已经成功保存的笔记或画布内容，也不会自动重复追加。

sites/docs/content/zh/privacy.md

@@ -0,0 +1,21 @@
+# 数据与隐私
+
+GoodBuddy 是本地优先的桌面应用，不要求 GoodBuddy 账号。数据是否离开本机，取决于你使用的模型连接、Runtime、知识库类型、远程项目和浏览器等功能。
+
+## 数据流向
+
+本地对话、笔记、任务、设置和知识库索引保存在系统应用数据目录。使用直连模型时，请求发送到你选择的模型服务；OpenCode、Continue 和 Harness 也会按其 Runtime 配置调用模型。GoodBuddy 不会因为安装应用或打开空白会话自动上传历史。
+
+启用本地知识库时，资料和索引留在本机，Runtime 只收到本次检索选出的有界文本证据和引用。使用 Dify、FastGPT 或 RAGFlow 时，本次查询会发送到你配置的外部实例；GoodBuddy 不上传完整会话或本地附件，也不向外部知识库写入内容。实际返回的有界片段和引用会随会话保存在本机。
+
+## 凭据和 Runtime 边界
+
+API Key、SSH 凭据和其他认证信息由 Main 进程和系统安全存储管理，Renderer 不直接读取它们。自定义 Header 和 Body 属于普通连接设置，不适合保存秘密。工具、MCP、终端和插件使用当前用户权限以及明确启用的能力；没有 Ask / Execute 模式来替代这些实际配置。
+
+远程项目会把有界的模型配置交给已认证的远程 Agent，模型请求在远端按 SSH 账号权限执行。远程 Agent 不随桌面包提供，GoodBuddy 不会凭空提高远端账号权限。断线恢复只同步 Agent 已记录且能确认的结果，不会自动重放不确定的模型调用。
+
+## 预览和清除
+
+会话中的 HTML 预览只处理已完成的助手 HTML，脚本、网络请求、表单提交、嵌套页面和窗口操作均被禁用；关闭 HTML 预览后仍可查看源码。它不是联网浏览器，也不会因为预览而把页面内容上传。
+
+清除本地数据是设置中的明确操作，会先要求确认。它不删除外部模型服务、远程主机、远程知识库、导出文件或你手动保存到工作区的文件。备份、系统同步和第三方服务的保留策略由相应系统决定。

sites/docs/content/zh/remote.md

@@ -0,0 +1,21 @@
+# 远程项目
+
+远程项目让 Workspace、终端和支持的 Runtime 在 SSH Host 上执行。远程路径不会被当成本机路径处理，文件、进程、网络和模型调用都受远端登录账号及远程环境限制。GoodBuddy Agent 不随桌面安装包提供，需要单独准备。
+
+## 准备 SSH Host
+
+在设置的远程项目入口添加 Host，填写地址、端口、用户名和认证方式。首次连接先查看 Host Key 的算法和 SHA-256 指纹并明确接受；指纹变化时必须单独确认替换。可用系统 SSH Agent 或支持的证书方式，凭据由桌面安全存储管理。GoodBuddy 不要求 root，也不默认启用 SSH Agent Forwarding。
+
+Host 保存成功不等于远程环境已经就绪。按 Host 卡片的操作准备或更新签名 Agent 和 Runtime，等待环境检查通过。版本匹配只表示版本事实，不代表 Agent 正在运行或能力完整；安装失败、取消或网络中断会保留 Host 并提供重试。
+
+## 创建项目和使用空间
+
+创建远程项目时选择已验证的 Host，输入或通过有界目录选择器选择远端工作目录，再选择 OpenCode 或 Continue 等支持的远程 Runtime。项目保存 Host ID、远端路径和 Runtime 选择。普通切换项目只切换本地配置，不自动连接、安装或扫描主机；首次使用 Workspace 或 Runtime 时才建立或复用 Agent 连接。
+
+远程 Workspace 提供有界目录、文件预览、Git 和导入操作；终端使用远端默认 Shell。所有操作使用 SSH 账号权限，不能获得 root 或账号本身没有的访问权。本机 Skills、stdio MCP 和工具环境不会自动上传到远端；远程能力以 Agent 报告的实际能力为准。
+
+## 失败和边界
+
+SSH 可达、认证成功、Agent 就绪、Workspace 可用和 Runtime 可启动是不同状态。分别检查网络、防火墙、端口、Host Key、凭据、远端目录、Agent 版本、Runtime 版本和项目权限。远端 Agent 不可用时不会退化成 SSH stdio Runtime，也不会把同一请求偷偷改在本机执行。
+
+断开 SSH relay 不一定会停止已接受的远程请求；重新连接后 GoodBuddy 只恢复 Agent 已记录且能确认的输出。无法确认模型请求是否已处理时不会自动重放，以免重复计费或重复副作用。显式停止、Agent 关闭或远端进程失败会按请求状态显示取消、失败或结果未知。

sites/docs/content/zh/runtimes.md

@@ -0,0 +1,26 @@
+# 选择 Runtime
+
+Runtime 决定请求由哪条执行路径处理。它与模型连接不同：连接回答“调用哪个模型服务”，Runtime 回答“由谁组织请求、工具和执行空间”。每次请求都会保留可查看的状态、工具活动、取消或失败结果。
+
+## 四种选择
+
+| Runtime | 适合场景 | 模型配置 |
+| --- | --- | --- |
+| 直连模型 | 普通问答、知识检索、图片生成和 GoodBuddy 内置能力 | GoodBuddy 模型连接 |
+| OpenCode | 编程 Agent、文件和命令工具、Skills | GoodBuddy 连接或 OpenCode 自有配置 |
+| Continue | 使用 Rules、Prompt 预设和编程工作 | GoodBuddy 连接或 Continue 自有配置 |
+| DeepSeek Harness | 固定 Host 和兼容插件能力 | GoodBuddy 管理的兼容连接 |
+
+先用直连模型完成普通问答或知识检索；需要持续操作项目文件、命令和 Skills 时选择 OpenCode 或 Continue；需要其固定 Host 能力时再选择 DeepSeek Harness。不同 Runtime 的工具、问答和原生客户端能力可能不同，选择器会显示当前可用项。
+
+## 选择范围和能力
+
+项目设置必须选择具体 Runtime。会话默认跟随项目，也可以在输入框的两栏选择器中为本会话单独选择。模型栏会显示“默认”、具体连接和 Runtime 自有配置，并标明来源。切换 Runtime 后，原来不属于该 Runtime 的模型选择不会被强行沿用。
+
+请求使用当前 Runtime、已启用 Capability、知识库范围、执行空间和当前账号权限。GoodBuddy 不提供 Ask / Execute 模式，也没有一个额外的通用工具审批开关；不支持的能力会明确报告，不会用隐藏模式代替。
+
+## 本地、远程和记录
+
+本地 Runtime 在本机项目执行。远程项目目前使用 SSH Host 上的 GoodBuddy Agent 和受管 Runtime，远程执行的文件、终端和进程使用 SSH 登录账号权限。远程 Agent 不随桌面安装包提供，需要先按[远程项目](./remote.html)准备。
+
+查看请求消息的活动或助手工作栏，可以看到 Runtime、模型连接、工具状态、取消、错误和已保存结果。关闭面板不会自动取消后台请求；停止请求只影响所属请求。请求失败或取消时，已经保存的正文和工具记录会保留。

sites/docs/content/zh/start.md

@@ -0,0 +1,30 @@
+# GoodBuddy 用户手册
+
+这是一份面向第一次使用者的操作指南。GoodBuddy 不要求注册 GoodBuddy 账号，聊天、项目和笔记默认保存在本机；模型服务、远程主机和外部知识库是否收到数据，取决于你的配置。
+
+## 开始使用
+
+### 安装
+
+从[官网首页](https://mesalogo.github.io/goodbuddy/#download)选择系统、处理器架构和安装包。Windows 提供安装版和便携版，Linux 提供 AppImage、DEB 和 RPM。LoongArch 使用单独的实验预览通道。安装完成后启动 GoodBuddy，首次启动不需要登录。
+
+### 初始设置
+
+1. 打开“设置”，确认本地工作数据位置，并准备一个可用的文本模型连接。
+2. 在“模型连接”中填写服务地址、协议、模型名称和凭据，先执行连接测试。具体字段见[配置模型连接](./connections.html)。
+3. 新建一个项目，选择项目目录和 Runtime。项目用于集中管理会话、工作区和任务。
+4. 打开或新建会话，先发送一个简单问题，确认模型能正常回答，再尝试文件、知识库或远程操作。
+
+### 项目和会话
+
+项目是工作范围的容器，可以包含多个会话。会话保存用户消息、助手回复、工具活动和引用；同一个会话也可以关联多个任务。创建会话时，通常会继承项目的 Runtime 选择，之后可以在输入区为当前会话单独选择。
+
+需要换主题或工作目录时，先切换项目，再确认右侧[助手工作栏](./workbar.html)中的工作区和终端范围。发送请求前检查当前 Runtime、模型和知识库范围，避免把内容发到错误的服务。
+
+### 本地数据
+
+对话、笔记、任务记录、知识库索引和设置存放在系统应用数据目录。清除本地数据是设置中的明确操作，执行前会要求确认。卸载应用不等于删除你导出的文件、远端目录或模型服务中的记录；需要了解数据流向时查看[数据与隐私](./privacy.html)。
+
+### 下一步
+
+先读[核心概念](./concepts.html)了解 Project、Conversation 和 Runtime 的关系，再按需要配置[知识库](./knowledge.html)、[任务](./tasks.html)或[远程项目](./remote.html)。

sites/docs/content/zh/supervision.md

@@ -0,0 +1,27 @@
+# 监督工作
+
+监督者用于回顾已发生的工作、标出变化和问题，并把有依据的结果放进故事线图谱。它不会替你发消息、批准工具、扩大文件范围或改变执行权限。监督者应用默认关闭，启用后才会接受新的监督工作。
+
+## 启用和设置范围
+
+在应用中心启用监督者，然后在“设置”中选择跟随默认文本模型，或选择一个已有的文本模型连接。监督执行复用连接和凭据；回顾进行中修改设置只影响后续执行。
+
+首次使用需要明确选择项目、会话和时间范围。自动监督可以选择 Global 或一个或多个项目，当前项目切换不会改变已保存的范围。启用应用不会自动观察全部历史，也不会自动创建计划。
+
+## 工作回顾和故事线图谱
+
+工作回顾按所选范围读取会话、任务、笔记和已有来源，生成带来源的阶段总结、变化和未解决事项。没有新的有效变化时记录“无变化”，不重复调用模型或发送通知。默认“回顾”处理新增和修订内容；需要重新阅读历史区间时，使用明确的“重新整理”操作。
+
+故事线图谱展示事件、实体、关系和随时间的变化。点击结果或图谱对象可以查看来源和定位。来源正文仍由会话、笔记或知识库维护，图谱不会复制一套可编辑原文。核对后可以继续讨论，也可以预览并确认写入本地知识库；外部知识库保持只读。
+
+## 跟随、固定和介入
+
+助手工作栏中的监督面板可以跟随当前会话，也可以固定到会话或 Task。切换页面不会改变固定目标；目标失效时保留错误并提供修复入口。监督建议只生成可编辑草稿或明确的后续操作，用户确认“发到当前会话”后才会写入聊天。
+
+监督者不会自动执行建议。它不能替用户发送消息、批准工具、修改能力开关或扩大工作区。监督模型调用是无工具的内部文本请求，普通聊天和 Task 不会被监督并发设置改成同一队列。
+
+## 智能心跳和失败处理
+
+智能心跳是监督者的定时唤醒机制。它按计划检查指定范围的增量变化，并按设置生成建议或只更新记忆。心跳应用和计划分别有启停状态；关闭应用后不领取新的心跳，但已经开始的运行可以完成。
+
+暂停、取消或失败会保留上次成功结果和已保存的成功批次，当前运行显示覆盖范围和遗漏。可以重试或继续仍有效的工作。建议生成失败不会撤销已经发布的图谱或回顾结果；活动记录会明确显示失败阶段。监督者默认关闭不会影响普通聊天和普通任务。

sites/docs/content/zh/tasks.md

@@ -0,0 +1,25 @@
+# 任务
+
+Task 是你明确创建或确认的一项工作。它只关联一条 Conversation，但一条 Conversation 可以有多个 Task。普通聊天请求和工具调用不会自动出现在任务中心。
+
+## 创建立即或定时任务
+
+在任务中心或会话任务区选择“新建任务”。填写任务要求，名称可以留空让 GoodBuddy 根据内容生成。默认立即执行，也可以选择单次、每日或每周计划，并选择当前项目中的当前会话、其他会话或新会话。内容、会话和计划会一起提交，失败时保留表单。
+
+任务使用关联会话在实际执行时的 Runtime、能力、知识范围和工作区。它没有 Ask / Execute 模式，也不会因为后台运行而扩大权限。新会话不会复制来源会话历史；已有会话会使用自己的最新上下文。
+
+## Task、Job 和 Run
+
+Task 是用户可见的工作对象。每次立即运行、计划触发或重试，内部都可能创建 Job 和 Run，但它们不会变成新的任务条目。任务中心聚合显示任务状态、最近进展、计划时间和需要关注的错误；活动和 Runtime 面板显示更详细的工具与执行信息。
+
+一个周期任务始终是一条 Task。取消、暂停、恢复和重新运行都作用于 Task；删除 Task 默认停止后续计划并解除关联，保留会话和已有消息。删除一次待执行的计划项不会删除 Task。
+
+## 排队和控制
+
+同一 Conversation 的普通消息和任务消息按队列顺序执行。当前回复期间到期的任务会等待，不会把另一条回复插入正在生成的时间线。你可以删除尚未执行的队列项，或使用“立即中断并插入”让任务成为下一项；取消或失败后，后续队列项可以继续。
+
+任务卡提供暂停、继续、立即运行、编辑和取消等操作。暂停阻止新的执行，不撤销已经完成的外部操作；取消会停止所属执行，但已经保存的消息、工具记录和成果不会伪装成回滚。
+
+## 任务与心跳
+
+智能心跳不是任务中心里的 Task。它属于[监督工作](./supervision.html)，用于按计划唤醒增量回顾和生成建议。需要一项明确的结果、文件或周期性消息时创建 Task；需要观察工作变化时配置监督计划。

sites/docs/content/zh/troubleshooting.md

@@ -0,0 +1,23 @@
+# 问题排查
+
+先确认当前项目、会话、Runtime、模型和本机或远程执行空间，再根据症状处理。不要重复点击发送或立即重建全部资料；先查看请求状态、活动记录和错误原因。
+
+## 模型连接测试失败
+
+检查协议、URL、模型 ID、API Key、代理、证书和服务商限流。若填写了自定义 Header 或 Body，先暂时清空后重测基础连接。基础测试成功但生成失败时，确认当前会话选择的 Runtime 和模型能力。
+
+## 回复没有使用工具或文件
+
+检查 Runtime 是否支持所需能力，项目或会话是否使用正确执行空间，工作区目录是否存在，能力或 MCP 是否启用，以及当前账号是否有权限。打开工作栏的 Workspace 或 Runtime 确认目标；远程项目另外检查 SSH、Agent、远端路径和 Agent 版本。GoodBuddy 没有 Ask / Execute 模式。
+
+## 知识库没有返回内容
+
+确认会话勾选了目标知识库，文档已解析，全文索引可用，向量没有失败或不兼容，图片型 PDF 已做 OCR。用“测试检索”查看实际通道和降级原因；先用原文关键词测试，再重建失败文档或索引。外部库还要检查认证、远端 ID、超时和 Provider 状态。
+
+## 笔记、任务或远程项目失败
+
+笔记和画布先确认明确保存；AI 评论失败不会撤销已保存内容。任务检查启用、暂停、关联会话、GoodBuddy 是否运行及最近错误；心跳默认关闭。远程检查网络、Host Key、凭据、目录权限和 Agent/Runtime 准备状态。结果未知的远程请求不会自动重放，先查看活动再决定是否重新运行。
+
+## HTML 预览为空或显示源码
+
+确认回复已完成，内容是 HTML 文档或 `html`/`htm` 代码块，并且设置已开启会话 HTML 渲染。流式回复、用户消息和推理只显示源码。预览故意禁用脚本、网络、表单和窗口操作；需要交互页面时导出到你信任的环境。

sites/docs/content/zh/workbar.md

@@ -0,0 +1,25 @@
+# 助手工作栏
+
+助手工作栏是主窗口右侧的应用级工作区。它不属于某一条聊天消息，聊天、知识库、任务和监督页面都可以打开它，用来查看任务、工作区、Runtime、终端、浏览器、笔记和监督状态。
+
+## 面板和加号目录
+
+任务中心和工作区是默认存在、不可关闭的基础面板。点击“+”可以打开 Runtime、监督、终端、进程、浏览器、资源监控、文档或笔记等能力。终端和浏览器可以创建多个实例；笔记是单实例。后台状态会更新徽标或通知，不会无故把当前页面切走。
+
+工作栏面板显示能力名称、实例和当前目标。能力不可用时应显示原因及配置入口，而不是把入口悄悄隐藏。面板可以收起，终端、日志和较大的成果可以按界面提供的选项停靠到底部或独立窗口。
+
+## 跟随和固定
+
+可绑定目标的面板有两种范围：跟随当前上下文，或固定到指定会话、Task、项目、Runtime、终端、工作区或浏览器实例。跟随模式会随项目或会话切换；固定模式保持原目标。固定目标失效时显示“目标不可用”和修复入口，不自动改到另一个目标。
+
+工作栏的当前上下文只是默认值。打开工作区不会自动扩大文件范围，临时选择目录也不会静默修改项目设置。确认目标后，GoodBuddy 仍会检查项目、执行空间和当前能力。
+
+## 执行空间边界
+
+工作区显示当前项目目录或你明确选择的本机、远程目录。终端创建时绑定项目执行空间和目录；没有项目时使用本机 Home。浏览器只管理 GoodBuddy 创建的受控浏览器标签，不控制你已经打开的系统浏览器。进程面板只显示 GoodBuddy 创建或托管的进程，不是系统级进程管理器。
+
+工作区支持文件预览、Git 状态和有界目录操作。远程工作区使用 SSH Host 上的 Agent，不把远程路径伪装成本机路径。终端输入、文件操作、浏览器和 Runtime 各自有明确范围；一个面板的选择不会给另一个面板额外权限。
+
+## 实际使用
+
+处理一个项目时，可以让任务中心跟随当前项目，同时把监督固定到某个会话；打开工作区查看文件，再创建一个终端执行命令。查看活动时确认面板顶部的项目、会话、Runtime 和本机或远程标识。需要完整任务关系时打开 Task；Job 和 Run 不作为工作栏中的独立面板。

sites/docs/manifest.ts

@@ -0,0 +1,21 @@
+export type Language = 'zh' | 'en'
+
+export type Chapter = {
+  slug: string
+  title: { zh: string; en: string }
+}
+
+export const chapters: Chapter[] = [
+  { slug: 'start', title: { zh: '开始使用', en: 'Get started' } },
+  { slug: 'concepts', title: { zh: '核心概念', en: 'Core concepts' } },
+  { slug: 'connections', title: { zh: '配置模型连接', en: 'Configure model connections' } },
+  { slug: 'runtimes', title: { zh: '选择 Runtime', en: 'Choose a Runtime' } },
+  { slug: 'workbar', title: { zh: '助手工作栏', en: 'Assistant workbar' } },
+  { slug: 'knowledge', title: { zh: '建立知识库', en: 'Build a knowledge base' } },
+  { slug: 'notes', title: { zh: '使用魔法笔记', en: 'Use Magic Notes' } },
+  { slug: 'tasks', title: { zh: '任务', en: 'Tasks' } },
+  { slug: 'supervision', title: { zh: '监督工作', en: 'Supervision' } },
+  { slug: 'remote', title: { zh: '远程项目', en: 'Remote projects' } },
+  { slug: 'privacy', title: { zh: '数据与隐私', en: 'Data and privacy' } },
+  { slug: 'troubleshooting', title: { zh: '问题排查', en: 'Troubleshooting' } },
+]

sites/en.html

@@ -75,6 +75,7 @@
           <a href="#workflows">Workflows</a>
           <a href="#features">Features</a>
           <a href="#assistant">Assistant</a>
+          <a href="./docs-dist/en/">User guide</a>
           <a href="#faq">FAQ</a>
         </nav>
 
@@ -495,6 +496,7 @@
           <a href="#download">Download</a>
           <a href="#workflows">Workflows</a>
           <a href="#features">Features</a>
+          <a href="./docs-dist/en/">User guide</a>
           <a href="#faq">FAQ</a>
           <a href="https://github.com/mesalogo/goodbuddy/blob/main/README.md">Getting started</a>
           <a href="https://github.com/mesalogo/goodbuddy" target="_blank" rel="noreferrer">

sites/index.html

@@ -75,6 +75,7 @@
           <a href="#workflows">场景</a>
           <a href="#features">功能</a>
           <a href="#assistant">助手</a>
+          <a href="./docs-dist/zh/">用户手册</a>
           <a href="#faq">FAQ</a>
         </nav>
 
@@ -514,6 +515,7 @@
               选择你的桌面版本
               <span aria-hidden="true">↓</span>
             </a>
+            <a class="text-link" href="./docs-dist/zh/">阅读用户手册 <span aria-hidden="true">→</span></a>
           </div>
 
           <div class="assistant-list">
@@ -583,6 +585,7 @@
           <a href="#download">下载</a>
           <a href="#workflows">场景</a>
           <a href="#features">功能</a>
+          <a href="./docs-dist/zh/">用户手册</a>
           <a href="#faq">FAQ</a>
           <a href="https://github.com/mesalogo/goodbuddy/blob/main/README.zh-CN.md">入门指南</a>
           <a href="https://github.com/mesalogo/goodbuddy" target="_blank" rel="noreferrer">

sites/scripts/validate.mjs

@@ -4,10 +4,28 @@ import { fileURLToPath } from "node:url";
 
 const siteRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const errors = [];
-
+const chapterSlugs = [
+  "start",
+  "concepts",
+  "connections",
+  "runtimes",
+  "workbar",
+  "knowledge",
+  "notes",
+  "tasks",
+  "supervision",
+  "remote",
+  "privacy",
+  "troubleshooting",
+];
 const requiredFiles = [
   "index.html",
   "en.html",
+  "docs/manifest.ts",
+  ...chapterSlugs.flatMap((slug) => [`docs/content/zh/${slug}.md`, `docs/content/en/${slug}.md`]),
+  "docs/.vitepress/config.mts",
+  ...chapterSlugs.flatMap((slug) => ["zh", "en"].map((language) =>
+    `docs-dist/${language}/${slug === "start" ? "index" : slug}.html`)),
   "styles.css",
   "app.js",
   "language.js",
@@ -49,10 +67,12 @@ await Promise.all(
   }),
 );
 
-const [html, englishHtml, css, appJs, languageJs, releaseIndexJs, fontLicense] =
+const [html, englishHtml, docsManifest, docsConfig, css, appJs, languageJs, releaseIndexJs, fontLicense] =
   await Promise.all([
     readSiteFile("index.html"),
     readSiteFile("en.html"),
+    readSiteFile("docs/manifest.ts"),
+    readSiteFile("docs/.vitepress/config.mts"),
     readSiteFile("styles.css"),
     readSiteFile("app.js"),
     readSiteFile("language.js"),
@@ -63,6 +83,8 @@ const [html, englishHtml, css, appJs, languageJs, releaseIndexJs, fontLicense] =
 for (const [relativePath, content] of [
   ["index.html", html],
   ["en.html", englishHtml],
+  ["docs/manifest.ts", docsManifest],
+  ["docs/.vitepress/config.mts", docsConfig],
   ["styles.css", css],
   ["app.js", appJs],
   ["language.js", languageJs],
@@ -112,6 +134,59 @@ report(
   (englishHtml.match(/<h1[\s>]/g) ?? []).length === 1,
   "英文页面必须且只能包含一个 h1",
 );
+report(chapterSlugs.every((slug) => docsManifest.includes(`slug: '${slug}'`)), "手册 manifest 缺少章节或顺序不完整");
+const manifestEntries = [...docsManifest.matchAll(/slug: '([^']+)', title: \{ zh: '([^']+)', en: '([^']+)' \}/g)];
+report(manifestEntries.length === chapterSlugs.length && manifestEntries.every((entry, index) => entry[1] === chapterSlugs[index]), "手册 manifest 章节顺序不完整");
+const docsBase = process.env.DOCS_BASE || "/goodbuddy/docs-dist/";
+const docsOrigin = "https://docs.example";
+const renderedText = (value) => value
+  .replace(/<[^>]*>/g, "")
+  .replace(/&(?:amp|lt|gt|quot|apos|#39|nbsp);/g, (entity) => ({
+    "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"',
+    "&apos;": "'", "&#39;": "'", "&nbsp;": " ",
+  })[entity])
+  .replace(/\s+/g, " ").trim();
+for (const slug of chapterSlugs) {
+  const [zh, en] = await Promise.all([readSiteFile(`docs/content/zh/${slug}.md`), readSiteFile(`docs/content/en/${slug}.md`)]);
+  const manifestEntry = manifestEntries.find((entry) => entry[1] === slug);
+  const titleMatches = slug === "start"
+    ? manifestEntry && zh.includes(`## ${manifestEntry[2]}`) && en.includes(`## ${manifestEntry[3]}`)
+    : manifestEntry && zh.startsWith(`# ${manifestEntry[2]}`) && en.startsWith(`# ${manifestEntry[3]}`);
+  report(titleMatches, `${slug} 章节标题必须与 manifest 保持一致`);
+  report(zh.trim().length > 20 && en.trim().length > 20, `${slug} 章节正文过短`);
+  for (const [content, languageCode] of [[zh, "zh"], [en, "en"]]) {
+    const chapterPath = `${languageCode}/${slug === "start" ? "index" : slug}.html`;
+    const relativePath = `docs-dist/${chapterPath}`;
+    const built = await readSiteFile(relativePath);
+    if (!built) continue;
+    const pageUrl = new URL(`${docsBase}${chapterPath}`, docsOrigin);
+    const main = built.match(/<main\b[^>]*>([\s\S]*?)<\/main>/)?.[1] ?? "";
+    const heading = content.match(/^# (.+)$/m)?.[1];
+    const firstBodyLine = content.split(/\r?\n/).find((line) => line.trim() && !line.startsWith("#")) ?? "";
+    const paragraphText = firstBodyLine.replace(/^\s*(?:[-*+]|\d+\.)\s+/, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[*`]/g, "");
+    report((main.match(/<h1\b/g) ?? []).length === 1 && renderedText(main.match(/<h1\b[^>]*>([\s\S]*?)<\/h1>/)?.[1] ?? "").includes(heading), `${relativePath} 缺少服务端渲染的 Markdown 主标题`);
+    report(paragraphText.length > 20 && renderedText(main).includes(renderedText(paragraphText)), `${relativePath} 缺少服务端渲染的章节正文`);
+    report(built.includes(`lang="${languageCode === "zh" ? "zh-CN" : "en"}"`), `${relativePath} 页面语言不正确`);
+    for (const entry of manifestEntries) {
+      const route = `${docsBase}${languageCode}/${entry[1] === "start" ? "" : `${entry[1]}.html`}`;
+      report(built.includes(`href="${route}"`) || (entry[1] === "start" && built.includes(`href="${route}index.html"`)), `${relativePath} 侧栏缺少章节：${entry[1]}`);
+      report(renderedText(built).includes(entry[languageCode === "zh" ? 2 : 3]), `${relativePath} 侧栏标题与 manifest 不一致：${entry[1]}`);
+    }
+    const otherLanguage = languageCode === "zh" ? "en" : "zh";
+    report(built.includes("VPNavBarTranslations") && built.includes(`href="${docsBase}${otherLanguage}/`), `${relativePath} 缺少原生语言切换入口`);
+    report(/<script\b[^>]*\bsrc="[^"]+\.js"/.test(built) && /<link\b[^>]*\brel="[^"]*stylesheet/.test(built), `${relativePath} 缺少脚本或样式资源`);
+    for (const [, link] of built.matchAll(/\s(?:href|src)="([^"]+)"/g)) {
+      if (/^(?:[a-z][a-z\d+.-]*:|\/\/|#)/iu.test(link)) continue;
+      const target = new URL(link, pageUrl);
+      report(target.pathname.startsWith(docsBase), `${relativePath} 本地链接未使用手册 base：${link}`);
+      if (!target.pathname.startsWith(docsBase)) continue;
+      let localPath = decodeURIComponent(target.pathname.slice(docsBase.length));
+      if (localPath.endsWith("/") || !localPath) localPath += "index.html";
+      report((await stat(path.join(siteRoot, "docs-dist", localPath)).catch(() => null))?.isFile(), `${relativePath} 本地链接或资源不存在：${link}`);
+    }
+  }
+}
+report(/provider:\s*['"]local['"]/.test(docsConfig), "手册必须启用 VitePress 本地搜索");
 report(/class="skip-link"\s+href="#main-content"/.test(html), "缺少跳到主要内容链接");
 report(
   /class="skip-link"\s+href="#main-content"/.test(englishHtml),
@@ -618,7 +693,8 @@ for (const [relativePath, content] of [
   );
   totalLocalAssets += localAssets.length;
   for (const asset of localAssets) {
-    const cleanAsset = asset.split(/[?#]/, 1)[0].replace(/^\.\//, "");
+    let cleanAsset = asset.split(/[?#]/, 1)[0].replace(/^\.\//, "");
+    if (cleanAsset.endsWith("/")) cleanAsset += "index.html";
     try {
       const assetStats = await stat(path.join(siteRoot, cleanAsset));
       report(assetStats.isFile(), `${relativePath} 本地资源不是文件：${asset}`);

src/main/agent/create-runtime.ts

@@ -46,6 +46,7 @@ import {
 import type { LaunchEnvironmentProvider } from '../local-tool-environment/launch-environment-provider'
 import type { DesktopDiagnosticFailureObserver } from '../desktop-diagnostics'
 export type AgentCapabilityContext = {
+  modelFetcher?: ModelRuntimeOptions['fetcher']
   outputStore?: ModelRuntimeOptions['outputStore']
   outputAdopt?: ModelRuntimeOptions['outputAdopt']
   observeFailure?: DesktopDiagnosticFailureObserver
@@ -139,9 +140,11 @@ export function createDefaultModelRuntime(
 export function createModelProfileRuntime(
   defaultWorkspace: string,
   settings: ResolvedRuntimeSettings,
-  profile: ResolvedModelProfile
+  profile: ResolvedModelProfile,
+  fetcher?: ModelRuntimeOptions['fetcher']
 ): ModelAgentRuntime {
   return new ModelAgentRuntime({
+    fetcher,
     apiKey: profile.apiKey,
     baseUrl: profile.baseUrl,
     model: profile.modelName,
@@ -359,6 +362,7 @@ export function createAgentRuntime(
       (modelAuthentication === 'none' || modelApiKey))
   ) {
     return new ModelAgentRuntime({
+      fetcher: capabilities.modelFetcher,
       outputStore: capabilities.outputStore,
       outputAdopt: capabilities.outputAdopt,
       apiKey: modelApiKey ?? '',

src/main/assistant/assistant-database.test.ts

@@ -134,6 +134,27 @@ it('persists the story graph switch per conversation without schema migration or
   } finally { database.close() }
 })
 
+it('persists the composer role per conversation and the role snapshot on replies', async () => {
+  const database = await createDatabase()
+  const expertId = randomUUID()
+  const header = { id: randomUUID(), title: 'Role preference', updatedAt: 1000, selectedExpertId: expertId }
+  const team = { id: randomUUID(), title: 'Team preference', updatedAt: 1000, selectedExpertId: 'team' as const }
+  const plain = { id: randomUUID(), title: 'No preference', updatedAt: 1000 }
+  const reply = { id: randomUUID(), role: 'assistant' as const, content: 'Reviewed', state: 'complete' as const,
+    createdAt: 900, expert: { kind: 'expert' as const, id: expertId, name: '代码审查专家' } }
+  try {
+    database.saveLocalConversations([{ header, messages: [reply] }, { header: team, messages: [] }, { header: plain, messages: [] }])
+    database.close()
+    database.initialize('C:\\Workspace')
+    expect(database.getConversation(header.id)).toMatchObject({ selectedExpertId: expertId, messages: [{ expert: reply.expert }] })
+    expect(database.getConversation(team.id).selectedExpertId).toBe('team')
+    expect(database.getConversation(plain.id).selectedExpertId).toBeUndefined()
+    database.saveLocalConversations([{ header: { ...header, selectedExpertId: undefined, updatedAt: 1001 }, messages: [] }])
+    expect(database.getConversation(header.id).selectedExpertId).toBeUndefined()
+    expect(localConversationHeaderSchema.safeParse({ ...plain, selectedExpertId: 'not-an-id' }).success).toBe(false)
+  } finally { database.close() }
+})
+
 it('persists conversation pins without changing timestamps or allowing autosaves to overwrite them', async () => {
   const database = await createDatabase()
   const header = { id: randomUUID(), title: 'Pinned conversation', updatedAt: 1000 }

src/main/assistant/assistant-database.ts

@@ -134,7 +134,7 @@ import {
   SUBAGENT_PROGRESS_STORAGE_SCHEMA_VERSION
 } from './subagent-progress-storage'
 
-export const ASSISTANT_DATABASE_SCHEMA_VERSION = 62
+export const ASSISTANT_DATABASE_SCHEMA_VERSION = 63
 
 function withoutHistoricalWorkMode(value: unknown): unknown {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return value
@@ -364,6 +364,7 @@ type MessageMetadata = {
   contextCompressions?: ConversationSnapshot['messages'][number]['contextCompressions']
   tools?: ConversationSnapshot['messages'][number]['tools']
   subagents?: ConversationSnapshot['messages'][number]['subagents']
+  expert?: ConversationMessage['expert']
   sources?: string[]
   sourceReferences?: ConversationSnapshot['messages'][number]['sourceReferences']
   knowledgeRetrieval?: ConversationSnapshot['messages'][number]['knowledgeRetrieval']
@@ -1238,6 +1239,7 @@ const conversationContextStateSchema = conversationSnapshotSchema.pick({
   knowledgeLibraryIds: true,
   knowledgeRetrievalMode: true,
   storyGraphEnabled: true,
+  selectedExpertId: true,
   contextMetrics: true,
   contextCompressionState: true
 })
@@ -1246,7 +1248,7 @@ function parseConversationContextState(
   value: string | null
 ): Pick<
   ConversationSnapshot,
-  'knowledgeLibraryIds' | 'knowledgeRetrievalMode' | 'storyGraphEnabled' | 'contextMetrics' | 'contextCompressionState'
+  'knowledgeLibraryIds' | 'knowledgeRetrievalMode' | 'storyGraphEnabled' | 'selectedExpertId' | 'contextMetrics' | 'contextCompressionState'
 > {
   if (!value) {
     return {}
@@ -1264,18 +1266,20 @@ function parseConversationContextState(
 function serializeConversationContextState(
   conversation: Pick<
     ConversationSnapshot,
-    'knowledgeLibraryIds' | 'knowledgeRetrievalMode' | 'storyGraphEnabled' | 'contextMetrics' | 'contextCompressionState'
+    'knowledgeLibraryIds' | 'knowledgeRetrievalMode' | 'storyGraphEnabled' | 'selectedExpertId' | 'contextMetrics' | 'contextCompressionState'
   >
 ): string | null {
   return conversation.knowledgeLibraryIds !== undefined ||
     conversation.knowledgeRetrievalMode !== undefined ||
     conversation.storyGraphEnabled !== undefined ||
+    conversation.selectedExpertId !== undefined ||
     conversation.contextMetrics ||
     conversation.contextCompressionState
     ? JSON.stringify({
         knowledgeLibraryIds: conversation.knowledgeLibraryIds,
         knowledgeRetrievalMode: conversation.knowledgeRetrievalMode,
         storyGraphEnabled: conversation.storyGraphEnabled,
+        selectedExpertId: conversation.selectedExpertId,
         contextMetrics: conversation.contextMetrics,
         contextCompressionState: conversation.contextCompressionState
       })
@@ -1346,6 +1350,7 @@ function toConversationSnapshot(
         contextCompressions: metadata.contextCompressions,
         tools: metadata.tools,
         subagents: metadata.subagents,
+        expert: metadata.expert,
         sources: metadata.sources,
         sourceReferences: metadata.sourceReferences,
         knowledgeRetrieval: metadata.knowledgeRetrieval,
@@ -1377,6 +1382,7 @@ function serializeConversationMessageMetadata(
     contextCompressions: message.contextCompressions,
     tools: message.tools,
     subagents: message.subagents,
+    expert: message.expert,
     sources: message.sources,
     sourceReferences: message.sourceReferences,
     knowledgeRetrieval: message.knowledgeRetrieval,
@@ -1784,6 +1790,7 @@ function storedRemoteAssistantMessage(
     contextCompressions: metadata.contextCompressions,
     tools: metadata.tools,
     subagents: metadata.subagents,
+    expert: metadata.expert,
     sources: metadata.sources,
     sourceReferences: metadata.sourceReferences,
     knowledgeRetrieval: metadata.knowledgeRetrieval,
@@ -5638,6 +5645,7 @@ export class AssistantDatabase {
         contextCompressions: metadata.contextCompressions,
         tools: metadata.tools,
         subagents: metadata.subagents,
+        expert: metadata.expert,
         sources: metadata.sources,
         sourceReferences: metadata.sourceReferences,
         knowledgeRetrieval: metadata.knowledgeRetrieval,
@@ -9168,8 +9176,11 @@ export class AssistantDatabase {
   }
 
   listSupervisionResults(limit = 20, target?: SupervisionTarget, resultId?: string) {
-    const owner = target?.type === 'conversation' ? this.getConversation(target.conversationId)
-      : target?.type === 'task' ? this.getTask(target.taskId) : undefined
+    const owner = target?.type === 'conversation'
+      ? this.requireDatabase().prepare('SELECT project_id AS projectId FROM conversations WHERE id = ?').get(target.conversationId) as { projectId: string | null } | undefined
+      : target?.type === 'task'
+        ? this.requireDatabase().prepare('SELECT project_id AS projectId FROM tasks WHERE id = ?').get(target.taskId) as { projectId: string | null } | undefined
+        : undefined
     const sourceType = target?.type ?? null
     const sourceId = target?.type === 'conversation' ? target.conversationId : target?.taskId ?? null
     return this.requireDatabase().prepare(`SELECT id, run_id AS runId, summary,
@@ -11908,6 +11919,7 @@ export class AssistantDatabase {
       database.exec('BEGIN IMMEDIATE')
       try {
         database.exec(supervisionReviewMigration)
+        database.exec(supervisionReviewCurrentView)
         database.exec('PRAGMA user_version = 47; COMMIT;')
       } catch (error) { database.exec('ROLLBACK'); throw error }
     }
@@ -12239,6 +12251,15 @@ export class AssistantDatabase {
         `)
       } catch (error) { database.exec('ROLLBACK'); throw error }
     }
+    if (version.user_version < 63) {
+      // Reviews read only finished messages and tasks, so a frozen manifest never changes.
+      database.exec('BEGIN IMMEDIATE')
+      try {
+        database.exec('DROP VIEW IF EXISTS supervision_review_current')
+        database.exec(supervisionReviewCurrentView)
+        database.exec('PRAGMA user_version = 63; COMMIT;')
+      } catch (error) { database.exec('ROLLBACK'); throw error }
+    }
   }
 
   supervisionExperiences(): SupervisionExperienceStore {
@@ -12303,7 +12324,7 @@ export class AssistantDatabase {
   }
 }
 import type { ImageOperation } from '../../shared/image-generation-contracts'
-import { SupervisionReviewStore, supervisionReviewMigration } from './supervision-review-store'
+import { SupervisionReviewStore, supervisionReviewCurrentView, supervisionReviewMigration } from './supervision-review-store'
 import { SupervisionStoryStore, supervisionStoriesMigration } from './supervision-stories'
 import { SupervisionExperienceStore, supervisionExperiencesMigration } from './supervision-experiences'
 import { migrateSupervisionTimeline, placeTimelineEvents, supersedeReextractedEvents, supervisionAttention, timelineCandidates } from './supervision-timeline'

src/main/assistant/supervision-review-store.test.ts

@@ -70,9 +70,10 @@ it('scans read-only, transfers at most 200 rows, yields without a transaction, a
   expect(wrote).toBe(true)
   expect(f.store.progress(f.runId).sources).toBe(450)
   expect(f.store.load(f.runId).initializing).toBeUndefined()
-  // Frozen scan revisions must not silently advance to the concurrent write.
-  await expect(f.store.resumeWithReader(f.runId, f.reader)).rejects.toThrow('source changed')
-  expect(f.store.load(f.runId).restartRequired).toBe(true)
+  // A concurrent write is detected on resume and that one source is skipped, not the whole run failed.
+  await f.store.resumeWithReader(f.runId, f.reader)
+  expect(f.store.progress(f.runId)).toMatchObject({ sources: 449, skippedSources: 1 })
+  expect(f.store.load(f.runId).restartRequired).toBeUndefined()
   await expect(f.worker.call('reviewManifestPage', [f.runId, 0])).rejects.toThrow('lost its snapshot')
 })
 

src/main/assistant/supervision-review-store.ts

@@ -10,7 +10,7 @@ import { setImmediate as yieldTurn } from 'node:timers/promises'
 export const TIMELINE_CHECKPOINT_SCOPE = 'timeline'
 
 export type ReviewConfiguration = SupervisionReviewSettings & { timeoutSeconds: number; concurrency: number; version: 1 }
-export type ReviewState = { request: SupervisionRunRequest; config: ReviewConfiguration; initializing?: boolean; restartRequired?: boolean; omittedSources?: number; phase?: SupervisionReviewProgress['phase']; stories?: SupervisionReviewProgress['stories'] }
+export type ReviewState = { request: SupervisionRunRequest; config: ReviewConfiguration; initializing?: boolean; restartRequired?: boolean; omittedSources?: number; skippedSources?: number; phase?: SupervisionReviewProgress['phase']; stories?: SupervisionReviewProgress['stories'] }
 
 export class ReviewSourcesOmitted extends Error {}
 
@@ -52,6 +52,14 @@ export const supervisionReviewMigration = `
     id TEXT NOT NULL, children_json TEXT NOT NULL, output_json TEXT NOT NULL,
     PRIMARY KEY(run_id, id)
   );
+`
+
+/**
+ * Reviewable sources. Only finished messages (complete or error) and finished tasks are
+ * visible: their content no longer changes, so the manifest frozen when a review starts
+ * is a fixed snapshot. Replies still streaming and running tasks wait for the next review.
+ */
+export const supervisionReviewCurrentView = `
   CREATE VIEW supervision_review_current AS
     SELECT 'message:' || m.id AS source, m.id AS record_id, 0 AS reference_index, 'conversation' AS type, c.id AS owner,
       c.project_id AS project_id, c.id AS conversation_id, m.sequence AS sequence,
@@ -60,14 +68,15 @@ export const supervisionReviewMigration = `
       json_array(m.review_revision, c.project_id, c.title, m.role, m.created_at) AS context,
       json_object('messageId', m.id, 'conversationId', c.id, 'projectId', c.project_id, 'role', m.role, 'sequence', m.sequence) AS locator
     FROM messages m JOIN conversations c ON c.id = m.conversation_id JOIN projects p ON p.id = c.project_id
-    WHERE c.status = 'active' AND p.status = 'active' AND m.role IN ('user', 'assistant')
+    WHERE c.status = 'active' AND p.status = 'active' AND m.role IN ('user', 'assistant') AND m.state IN ('complete', 'error')
     UNION ALL
     SELECT 'task:' || t.id, t.id, 0, 'task', t.id, COALESCE(t.project_id, ''), '', 0, t.title,
       t.created_at, COALESCE(t.completed_at, t.created_at),
       json_object('title', t.title, 'status', t.status, 'createdAt', t.created_at, 'completedAt', t.completed_at),
       json_array(t.project_id, t.title, t.status, t.created_at, t.completed_at), json_object('projectId', t.project_id)
     FROM tasks t LEFT JOIN projects p ON p.id = t.project_id
-    WHERE t.visible = 1 AND (t.project_id IS NULL OR p.status = 'active')
+    WHERE t.visible = 1 AND t.status IN ('completed', 'failed', 'cancelled', 'interrupted')
+      AND (t.project_id IS NULL OR p.status = 'active')
     UNION ALL
     SELECT 'knowledge:' || m.id || ':' || ref.key, m.id, ref.key, 'knowledge',
       COALESCE(json_extract(ref.value, '$.chunkId'), json_extract(ref.value, '$.documentId'),
@@ -79,7 +88,7 @@ export const supervisionReviewMigration = `
       json_patch(ref.value, json_object('messageId', m.id, 'conversationId', c.id, 'projectId', c.project_id, 'referenceIndex', ref.key))
     FROM messages m JOIN conversations c ON c.id = m.conversation_id JOIN projects p ON p.id = c.project_id
       JOIN json_each(m.metadata_json, '$.sourceReferences') ref
-    WHERE c.status = 'active' AND p.status = 'active' AND m.role IN ('user', 'assistant');
+    WHERE c.status = 'active' AND p.status = 'active' AND m.role IN ('user', 'assistant') AND m.state IN ('complete', 'error');
 `
 
 export class SupervisionReviewStore {
@@ -235,26 +244,19 @@ export class SupervisionReviewStore {
   unfinished(request: SupervisionRunRequest): string | undefined {
     return this.db.prepare(`SELECT s.id FROM supervision_runs s JOIN supervision_review_runs r ON r.run_id = s.id
       WHERE s.trigger = 'heartbeat' AND s.scope_json = ? AND s.status IN ('failed', 'running')
-        AND (COALESCE(json_extract(r.state_json, '$.restartRequired'), 0) = 0 OR EXISTS (
-          SELECT 1 FROM supervision_review_sources source WHERE source.run_id = s.id AND source.conversation_id != ''
-            AND NOT EXISTS (SELECT 1 FROM conversations c WHERE c.id = source.conversation_id)
-            AND instr(s.error, '(' || source.source || ');') > 0))
       ORDER BY s.created_at LIMIT 1`).get(JSON.stringify(request.scope))?.id as string | undefined
   }
 
   resume(runId: string, signal?: AbortSignal): void {
     const state = this.prepareResume(runId)
     if (state.initializing) { this.initializeSources(runId, state, signal); return }
-    // Existing sources must still match their frozen versions.
+    // A source that no longer matches its frozen version is skipped and left for the next review.
     let after = ''
     for (;;) {
       const rows = this.resumePage(runId, after)
       if (!rows.length) break
       const changed = this.changedSource(rows, signal)
-      if (changed) {
-        if (this.omitDeletedConversations(runId)) return this.resume(runId, signal)
-        this.sourceChanged(runId, changed)
-      }
+      if (changed) { this.skipSource(runId, changed); after = changed; continue }
       after = rows.at(-1)!.source
     }
   }
@@ -263,7 +265,8 @@ export class SupervisionReviewStore {
     const status = this.db.prepare('SELECT status FROM supervision_runs WHERE id = ?').get(runId)?.status
     if (status === 'cancelled') throw new Error('SUPERVISION_REVIEW_CANCELLED: 此回顾已取消，不能继续。请开始新的回顾。')
     this.omitDeletedConversations(runId)
-    if (this.load(runId).restartRequired) throw new Error('Review source changed or was removed; start a new review')
+    // Runs failed by an earlier release on a changed source are recoverable now.
+    this.db.prepare("UPDATE supervision_review_runs SET state_json = json_remove(state_json, '$.restartRequired') WHERE run_id = ?").run(runId)
     const changed = this.db.prepare(`UPDATE supervision_runs SET status = 'running', error = NULL, completed_at = NULL
       WHERE id = ? AND status IN ('paused', 'failed', 'running')`).run(runId)
     if (!changed.changes) throw new Error('SUPERVISION_REVIEW_NOT_RESUMABLE: 此回顾已完成或不存在，请开始新的回顾。')
@@ -286,10 +289,8 @@ export class SupervisionReviewStore {
       if (!rows.length) break
       const changed = await reader.changedSource(rows, signal)
       this.checkRunning(runId, signal)
-      if (changed) {
-        if (this.omitDeletedConversations(runId)) { after = ''; continue }
-        this.sourceChanged(runId, changed)
-      }
+      // The read snapshot may lag the writer; skipSource re-reads the source here.
+      if (changed) { this.skipSource(runId, changed); after = changed; await yieldTurn(); continue }
       after = rows.at(-1)!.source
       await yieldTurn()
     }
@@ -349,8 +350,9 @@ export class SupervisionReviewStore {
       for (const metadata of rows) {
         const current = this.currentSource(metadata.source, metadata.processed_offset, Math.min(remaining, 8000))
         if (!current || current.current_revision !== metadata.revision) {
-          if (this.omitDeletedConversations(runId)) return this.chunk(runId, projectId, conversationId, config)
-          this.sourceChanged(runId, metadata.source)
+          // Skip the changed source, then rebuild the batch from current offsets.
+          this.skipSource(runId, metadata.source)
+          return this.chunk(runId, projectId, conversationId, config)
         }
         const row = { ...metadata, ...current }
         const locator = JSON.parse(row.locator) as Record<string, unknown>
@@ -387,17 +389,72 @@ export class SupervisionReviewStore {
     const reference = kind === 'knowledge' ? Number(key.slice(last + 1)) : 0
     // The view predicate pushes record_id into each branch's message/task primary-key lookup.
     return this.db.prepare(`SELECT type, owner, substr(title, 1, 240) AS title, occurred, alternate_time,
-      locator, review_revision(context) AS current_revision, substr(body, ? + 1, ?) AS content
+      locator, review_revision(context) AS current_revision, substr(body, ? + 1, ?) AS content, length(body) AS body_length
       FROM supervision_review_current WHERE record_id = ? AND reference_index = ? AND type = ?`).get(
         offset, characters, id, reference, kind === 'message' ? 'conversation' : kind) as {
           type: SupervisionEvidence['sourceType']; owner: string; title: string; occurred: string;
-          alternate_time: string; locator: string; current_revision: string; content: string
+          alternate_time: string; locator: string; current_revision: string; content: string; body_length: number
         } | undefined
   }
 
-  private sourceChanged(runId: string, source: string): never {
-    this.db.prepare("UPDATE supervision_review_runs SET state_json = json_set(state_json, '$.restartRequired', json('true')) WHERE run_id = ?").run(runId)
-    throw new Error(`Review source changed or was removed (${source}); start a new review`)
+  /**
+   * The manifest is a snapshot of finished sources, so a frozen source should never change.
+   * If one still does (or disappears), it is dropped from this run without failing it: leaves
+   * that used it are discarded with their navigation, and because no checkpoint is written for
+   * it, the next review picks it up at its current version. Returns false when it still matches.
+   */
+  skipSource(runId: string, source: string): boolean {
+    const frozen = this.db.prepare('SELECT revision FROM supervision_review_sources WHERE run_id = ? AND source = ?').get(runId, source) as { revision: string } | undefined
+    if (!frozen) return false
+    const live = this.currentSource(source, 0, 0)
+    if (live?.current_revision === frozen.revision) return false
+    if (this.omitDeletedConversations(runId)) return true
+    // No longer visible (archived, emptied): omitted. Still visible but changed: left for the next review.
+    const counter = live && Number(live.body_length) > 0 ? '$.skippedSources' : '$.omittedSources'
+    this.db.exec('SAVEPOINT skip_review_source')
+    try {
+      this.discardLeaves(runId, new Set([source]))
+      this.db.prepare('DELETE FROM supervision_review_sources WHERE run_id = ? AND source = ?').run(runId, source)
+      this.db.prepare(`UPDATE supervision_review_runs SET state_json = json_set(json_remove(state_json, '$.restartRequired'),
+        '${counter}', COALESCE(json_extract(state_json, '${counter}'), 0) + 1,
+        '$.phase', 'extracting') WHERE run_id = ?`).run(runId)
+      this.db.exec('RELEASE skip_review_source')
+      return true
+    } catch (error) { this.db.exec('ROLLBACK TO skip_review_source; RELEASE skip_review_source'); throw error }
+  }
+
+  /**
+   * Discards every leaf containing an affected source, transitively over mixed leaves, and
+   * their dependent navigation. Surviving sources of those leaves restart at their initial offset.
+   */
+  private discardLeaves(runId: string, affected: Set<string>): void {
+    const invalid = new Set<string>()
+    let changed = true
+    while (changed) {
+      changed = false
+      for (let offset = 0;; offset += 10) {
+        const batches = this.db.prepare(`SELECT b.id, json_group_array(json_extract(item.value, '$.locator.source')) AS sources
+          FROM (SELECT id, evidence_json FROM supervision_review_batches WHERE run_id = ? ORDER BY rowid LIMIT 10 OFFSET ?) b,
+            json_each(b.evidence_json) item GROUP BY b.id`).all(runId, offset)
+        if (!batches.length) break
+        for (const batch of batches) {
+          const sources = JSON.parse(String(batch.sources)) as string[]
+          if (invalid.has(String(batch.id)) || !sources.some(source => affected.has(source))) continue
+          invalid.add(String(batch.id))
+          for (const source of sources) affected.add(source)
+          changed = true
+        }
+      }
+    }
+    const invalidIds = JSON.stringify([...invalid])
+    this.db.prepare(`WITH RECURSIVE invalid(id) AS (
+      SELECT value FROM json_each(?) UNION
+      SELECT n.id FROM supervision_review_navigation n, json_each(n.children_json) child
+        JOIN invalid i ON i.id = child.value WHERE n.run_id = ?
+    ) DELETE FROM supervision_review_navigation WHERE run_id = ? AND id IN (SELECT id FROM invalid)`)
+      .run(invalidIds, runId, runId)
+    this.db.prepare('DELETE FROM supervision_review_batches WHERE run_id = ? AND id IN (SELECT value FROM json_each(?))').run(runId, invalidIds)
+    for (const source of affected) this.db.prepare('UPDATE supervision_review_sources SET processed_offset = initial_offset WHERE run_id = ? AND source = ?').run(runId, source)
   }
 
   save(runId: string, projectId: string, conversationId: string, evidence: SupervisionEvidence[], output: SupervisionSummaryOutput): void {
@@ -405,11 +462,13 @@ export class SupervisionReviewStore {
     try {
       this.omitDeletedConversations(runId)
       if (!this.hasSources(runId, evidence)) { this.db.exec('COMMIT'); return }
+      // A source changed while the model was working: drop this answer and that source, keep the run going.
+      const stale = evidence.find(item => this.currentSource(String(item.locator!.source), 0, 0)?.current_revision !== item.locator!.revision)
+      if (stale) { this.skipSource(runId, String(stale.locator!.source)); this.db.exec('COMMIT'); return }
       const advance = this.db.prepare(`UPDATE supervision_review_sources SET processed_offset = ?
         WHERE run_id = ? AND source = ? AND revision = ? AND processed_offset = ?`)
       for (const item of evidence) {
         const locator = item.locator!
-        if (this.currentSource(String(locator.source), 0, 0)?.current_revision !== locator.revision) this.sourceChanged(runId, String(locator.source))
         if (advance.run(Number(locator.end), runId, String(locator.source), String(locator.revision), Number(locator.start)).changes !== 1) {
           throw new Error('Review coverage has a gap or duplicate batch')
         }
@@ -438,13 +497,9 @@ export class SupervisionReviewStore {
     const batches = this.db.prepare(`SELECT COUNT(*) AS batches, COALESCE(SUM(characters), 0) AS characters
       FROM supervision_review_batches WHERE run_id = ?`).get(runId)!
     const state = this.load(runId)
-    const error = String(this.db.prepare('SELECT error FROM supervision_runs WHERE id = ?').get(runId)?.error ?? '')
-    const failedSource = /Review source changed or was removed \((.+)\);/.exec(error)?.[1]
-    const deletedFailure = failedSource && this.db.prepare(`SELECT 1 FROM supervision_review_sources s
-      WHERE s.run_id = ? AND s.source = ? AND s.conversation_id != ''
-        AND NOT EXISTS (SELECT 1 FROM conversations c WHERE c.id = s.conversation_id)`).get(runId, failedSource)
     const navigation = this.db.prepare('SELECT COUNT(*) AS count FROM supervision_review_navigation WHERE run_id = ?').get(runId)!
-    return { runId, omittedSources: state.omittedSources, phase: state.phase, stories: state.stories, navigationNodes: Number(navigation.count), settings: state.config, restartRequired: deletedFailure ? false : state.restartRequired, batches: Number(batches.batches), characters: Number(batches.characters), sources: Number(sources.sources),
+    // Changed sources are skipped on resume, so no saved run requires a restart.
+    return { runId, omittedSources: state.omittedSources, skippedSources: state.skippedSources, phase: state.phase, stories: state.stories, navigationNodes: Number(navigation.count), settings: state.config, batches: Number(batches.batches), characters: Number(batches.characters), sources: Number(sources.sources),
       remainingSources: Number(sources.remaining), complete: this.db.prepare("SELECT id FROM supervision_runs WHERE id = ? AND status IN ('completed', 'no_change')").get(runId) !== undefined }
   }
 
@@ -467,41 +522,11 @@ export class SupervisionReviewStore {
     this.db.exec('SAVEPOINT omit_review_sources')
     try {
       const removed = new Set(deleted.map(row => String(row.source)))
-      const affected = new Set(removed)
-      const invalid = new Set<string>()
       // A mixed leaf cannot be filtered safely: its prose may combine every input.
       // Reset its surviving sources and discard their other leaves to avoid duplicate coverage.
-      let changed = true
-      while (changed) {
-        changed = false
-        for (let offset = 0;; offset += 10) {
-          const batches = this.db.prepare(`SELECT b.id, json_group_array(json_extract(item.value, '$.locator.source')) AS sources
-            FROM (SELECT id, evidence_json FROM supervision_review_batches WHERE run_id = ? ORDER BY rowid LIMIT 10 OFFSET ?) b,
-              json_each(b.evidence_json) item GROUP BY b.id`).all(runId, offset)
-          if (!batches.length) break
-          for (const batch of batches) {
-            const sources = JSON.parse(String(batch.sources)) as string[]
-            if (invalid.has(String(batch.id)) || !sources.some(source => affected.has(source))) continue
-            invalid.add(String(batch.id))
-            for (const source of sources) affected.add(source)
-            changed = true
-          }
-        }
-      }
-      const invalidIds = JSON.stringify([...invalid])
-      this.db.prepare(`WITH RECURSIVE invalid(id) AS (
-        SELECT value FROM json_each(?) UNION
-        SELECT n.id FROM supervision_review_navigation n, json_each(n.children_json) child
-          JOIN invalid i ON i.id = child.value WHERE n.run_id = ?
-      ) DELETE FROM supervision_review_navigation WHERE run_id = ? AND id IN (SELECT id FROM invalid)`)
-        .run(invalidIds, runId, runId)
-      this.db.prepare('DELETE FROM supervision_review_batches WHERE run_id = ? AND id IN (SELECT value FROM json_each(?))').run(runId, invalidIds)
-      for (const source of affected) this.db.prepare('UPDATE supervision_review_sources SET processed_offset = initial_offset WHERE run_id = ? AND source = ?').run(runId, source)
+      this.discardLeaves(runId, new Set(removed))
       for (const source of removed) this.db.prepare('DELETE FROM supervision_review_sources WHERE run_id = ? AND source = ?').run(runId, source)
-      const error = String(this.db.prepare('SELECT error FROM supervision_runs WHERE id = ?').get(runId)?.error ?? '')
-      const failedSource = /Review source changed or was removed \((.+)\);/.exec(error)?.[1]
-      if (failedSource && removed.has(failedSource)) this.db.prepare("UPDATE supervision_review_runs SET state_json = json_remove(state_json, '$.restartRequired') WHERE run_id = ?").run(runId)
-      this.db.prepare(`UPDATE supervision_review_runs SET state_json = json_set(state_json,
+      this.db.prepare(`UPDATE supervision_review_runs SET state_json = json_set(json_remove(state_json, '$.restartRequired'),
         '$.omittedSources', COALESCE(json_extract(state_json, '$.omittedSources'), 0) + ?, '$.phase', 'extracting') WHERE run_id = ?`).run(removed.size, runId)
       this.db.exec('RELEASE omit_review_sources')
       return true

src/main/assistant/supervision-review.test.ts

@@ -313,17 +313,82 @@ it('still pauses on user request and resumes saved batches without changing batc
   expect(f.db.supervisionReviewStore().batches(result.runId!, 100).flatMap(row => row.evidence).map(row => row.content.length)).toEqual([1000, 1000, 500])
 })
 
-it('rejects changed source versions and rolls back offsets when batch persistence fails', async () => {
-  const f = await fixture([['x'.repeat(2500)]], { concurrency: 1 })
+it('skips changed source versions and rolls back offsets when batch persistence fails', async () => {
+  const f = await fixture([['x'.repeat(2500)], ['Kept']], { concurrency: 1 })
   f.sql.exec("CREATE TRIGGER fail_batch BEFORE INSERT ON supervision_review_batches BEGIN SELECT RAISE(ABORT, 'disk failure'); END")
   await expect(f.service().run(request)).rejects.toThrow('disk failure')
   const runId = f.db.listSupervisionActivity()[0]!.id
   expect(f.db.supervisionReviewStore().progress(runId).characters).toBe(0)
-  expect(f.sql.prepare('SELECT processed_offset FROM supervision_review_sources').get()!.processed_offset).toBe(0)
+  expect(f.sql.prepare('SELECT MAX(processed_offset) AS offset FROM supervision_review_sources').get()!.offset).toBe(0)
   f.sql.exec('DROP TRIGGER fail_batch')
   f.sql.prepare('UPDATE messages SET content = ? WHERE id = ?').run('Changed', f.conversations[0]!.messages[0]!.id)
-  await expect(f.service().resume(runId)).rejects.toThrow('source changed')
-  expect(f.db.listSupervisionActivity()[0]!.status).toBe('failed')
+  const resumed = await f.service().resume(runId)
+  expect(resumed).toMatchObject({ status: 'completed', coverage: { skippedSources: 1, sources: 1, characters: 'Kept'.length, complete: true } })
+  expect(f.db.supervisionReviewStore().batches(runId).flatMap(batch => batch.evidence).map(item => item.content)).toEqual(['Kept'])
+})
+
+it('reviews only finished messages: a streaming reply waits for the next review', async () => {
+  const f = await fixture([['Finished question', 'Partial reply']], { concurrency: 1 })
+  const reply = f.conversations[0]!.messages[1]!.id
+  f.sql.prepare("UPDATE messages SET state = 'streaming' WHERE id = ?").run(reply)
+  const manual = { ...request, reanalyze: undefined }
+  const first = await f.service().run(manual)
+  expect(first.coverage).toMatchObject({ sources: 1, complete: true })
+  expect(f.db.supervisionReviewStore().batches(first.runId!).flatMap(batch => batch.evidence).map(item => item.content)).toEqual(['Finished question'])
+  f.sql.prepare("UPDATE messages SET content = ?, state = 'complete' WHERE id = ?").run('Partial reply, finished', reply)
+  const next = await f.service().run(manual)
+  expect(next.coverage).toMatchObject({ sources: 1, complete: true })
+  expect(f.db.supervisionReviewStore().batches(next.runId!).flatMap(batch => batch.evidence).map(item => item.content)).toEqual(['Partial reply, finished'])
+})
+
+it('skips a source rewritten while its batch is with the model and discards the stale answer', async () => {
+  const f = await fixture([['Original reply'], ['Other conversation']], { concurrency: 1 })
+  const target = f.conversations[0]!.messages[0]!.id
+  const base = f.summarize.getMockImplementation()!
+  let rewritten = false
+  f.summarize.mockImplementation(async input => {
+    if (!rewritten && input.evidence.some(item => item.locator?.messageId === target)) {
+      rewritten = true
+      f.sql.prepare('UPDATE messages SET content = ? WHERE id = ?').run('Original reply, continued after reconnect', target)
+    }
+    return { ...await base(input), summary: input.evidence.map(item => item.content).join(', ') }
+  })
+  const result = await f.service().run(request)
+  expect(result).toMatchObject({ status: 'completed', coverage: { skippedSources: 1, sources: 1, remainingSources: 0, complete: true } })
+  const contents = f.db.supervisionReviewStore().batches(result.runId!).flatMap(batch => batch.evidence).map(item => item.content)
+  expect(contents).toEqual(['Other conversation'])
+})
+
+it('discards a mixed leaf when one of its sources changes and skips only that source', async () => {
+  const f = await fixture([['A', 'B']], { concurrency: 1 })
+  const store = f.db.supervisionReviewStore()
+  const runId = f.db.startSupervisionRun(request)
+  store.initialize(runId, { request, config: f.config })
+  const conversation = f.conversations[0]!
+  const evidence = store.chunk(runId, conversation.projectId, conversation.id, f.config)
+  expect(evidence.map(item => item.content)).toEqual(['A', 'B'])
+  store.save(runId, conversation.projectId, conversation.id, evidence, empty)
+  store.saveNavigation(runId, 'dependent', [store.batches(runId)[0]!.id], empty)
+  f.sql.prepare('UPDATE messages SET content = ? WHERE id = ?').run('B2', conversation.messages[1]!.id)
+  f.db.failSupervisionRun(runId, 'Provider failed')
+  await f.service().resume(runId)
+  expect(store.navigation(runId, 'dependent')).toBeUndefined()
+  expect(store.batches(runId).flatMap(batch => batch.evidence).map(item => item.content)).toEqual(['A'])
+  expect(store.progress(runId)).toMatchObject({ skippedSources: 1, sources: 1, complete: true })
+})
+
+it('omits a source that is no longer visible and resumes old runs failed by the earlier restart rule', async () => {
+  const f = await fixture([['Hidden'], ['Kept']], { concurrency: 1 })
+  const store = f.db.supervisionReviewStore()
+  const runId = f.db.startSupervisionRun(request)
+  store.initialize(runId, { request, config: f.config })
+  f.sql.prepare("UPDATE supervision_review_runs SET state_json = json_set(state_json, '$.restartRequired', json('true')) WHERE run_id = ?").run(runId)
+  f.db.failSupervisionRun(runId, `Review source changed or was removed (message:${f.conversations[0]!.messages[0]!.id}); start a new review`)
+  f.sql.prepare("UPDATE conversations SET status = 'archived' WHERE id = ?").run(f.conversations[0]!.id)
+  expect(store.progress(runId).restartRequired).toBeUndefined()
+  const result = await f.service().resume(runId)
+  expect(result).toMatchObject({ status: 'completed', coverage: { omittedSources: 1, sources: 1, complete: true } })
+  expect(result.output.summary).not.toContain('Hidden')
 })
 
 it('round-robins projects and conversations and keeps semantic chunks independent of database page size', async () => {
@@ -381,20 +446,23 @@ it('continues an existing automatic timeline checkpoint without rereading its su
   expect(f.sql.prepare('SELECT processed_offset FROM review_checkpoints').get()!.processed_offset).toBe(3300)
 })
 
-it('keeps old-version facts but does not permanently block automatic review after a source changes', async () => {
+it('lets the next automatic review continue a failed run whose source changed in the meantime', async () => {
   const f = await fixture([['x'.repeat(2500)]], { concurrency: 1 })
   f.summarize.mockImplementationOnce(async () => empty).mockRejectedValueOnce(new Error('Provider failed'))
   const automatic = { ...request, trigger: 'heartbeat' as const }
   await expect(f.service().run(automatic)).rejects.toThrow('Provider failed')
   const runId = f.db.listSupervisionActivity()[0]!.id
-  const saved = f.db.supervisionReviewStore().batches(runId)
+  expect(f.db.supervisionReviewStore().batches(runId)).toHaveLength(1)
   f.sql.prepare('UPDATE messages SET content = ? WHERE id = ?').run('New version', f.conversations[0]!.messages[0]!.id)
-  await expect(f.service().resume(runId)).rejects.toThrow('source changed')
-  expect(f.db.supervisionReviewStore().progress(runId).restartRequired).toBe(true)
   const result = await f.service().run(automatic)
-  expect(result.runId).not.toBe(runId)
-  expect(result.status).toBe('completed')
-  expect(f.db.supervisionReviewStore().batches(runId)).toEqual(saved)
+  expect(result.runId).toBe(runId)
+  expect(result).toMatchObject({ status: 'no_change', coverage: { skippedSources: 1, sources: 0 } })
+  // The leaf of the old version is discarded and no checkpoint is written for the source,
+  // so the next automatic review reads its current version.
+  expect(f.db.supervisionReviewStore().batches(runId)).toEqual([])
+  const next = await f.service().run(automatic)
+  expect(next.runId).not.toBe(runId)
+  expect(f.db.supervisionReviewStore().batches(next.runId!).flatMap(batch => batch.evidence).map(item => item.content)).toEqual(['New version'])
 })
 
 it('makes a manual review incremental by default and keeps explicit re-analysis out of shared progress', async () => {
@@ -455,7 +523,8 @@ it('omits a deleted conversation, its knowledge and tasks before resume without
   const store = f.db.supervisionReviewStore()
   const kept = store.batches(runId).filter(batch => batch.conversationId !== deleted.id)
   expect(f.db.deleteLocalConversation(deleted.id)).toBe(true)
-  expect(store.progress(runId)).toMatchObject({ omittedSources: 3, sources: 1, batches: kept.length, restartRequired: undefined })
+  expect(store.progress(runId)).toMatchObject({ omittedSources: 3, sources: 1, batches: kept.length })
+  expect(store.progress(runId).restartRequired).toBeUndefined()
   expect(store.batches(runId)).toEqual(kept)
   f.sql.exec('DROP TRIGGER fail_publication')
   const calls = f.summarize.mock.calls.length
@@ -542,7 +611,7 @@ it('resets mixed-leaf survivors only and invalidates their dependent navigation
   expect(store.batches(runId)).toContainEqual(kept)
 })
 
-it('recovers the earlier deletion failure but keeps archived and modified existing conversations as explicit failures', async () => {
+it('recovers earlier deletion failures and omits archived conversations instead of failing', async () => {
   const f = await fixture([['Source']])
   const store = f.db.supervisionReviewStore()
   const id = f.db.startSupervisionRun(request)
@@ -550,11 +619,11 @@ it('recovers the earlier deletion failure but keeps archived and modified existi
   f.sql.prepare("UPDATE supervision_review_runs SET state_json = json_set(state_json, '$.restartRequired', json('true')) WHERE run_id = ?").run(id)
   f.db.failSupervisionRun(id, `Review source changed or was removed (message:${f.conversations[0]!.messages[0]!.id}); start a new review`)
   f.sql.prepare('DELETE FROM conversations WHERE id = ?').run(f.conversations[0]!.id)
-  expect(store.progress(id).restartRequired).toBe(false)
+  expect(store.progress(id).restartRequired).toBeUndefined()
   await expect(f.service().resume(id)).resolves.toMatchObject({ status: 'no_change', coverage: { omittedSources: 1 } })
   const g = await fixture([['Archived source']])
   g.summarize.mockRejectedValueOnce(new Error('Pause'))
   await expect(g.service().run(request)).rejects.toThrow('Pause')
   g.sql.prepare("UPDATE conversations SET status = 'archived' WHERE id = ?").run(g.conversations[0]!.id)
-  await expect(g.service().resume(g.db.listSupervisionActivity()[0]!.id)).rejects.toThrow('source changed')
+  await expect(g.service().resume(g.db.listSupervisionActivity()[0]!.id)).resolves.toMatchObject({ status: 'no_change', coverage: { omittedSources: 1 } })
 })

src/main/assistant/supervision-worker.test.ts

@@ -45,7 +45,7 @@ async function fixture() {
     { documentId: 'document', documentName: 'Reference', snippet: 'Knowledge \u{1f600}', chunkId: 'chunk' }
   ] }), conversations[0]!.messages[0]!.id)
   db.createTask({ id: randomUUID(), conversationId: conversations[0]!.id, projectId: project.id,
-    title: 'Visible task', instructions: 'Test', origin: 'user', visible: true })
+    title: 'Visible task', instructions: 'Test', origin: 'user', visible: true, status: 'completed' })
   const state: ReviewState = { request: { trigger: 'manual', scope: { kind: 'global' },
     timeRange: { from: '2026-01-01T00:00:00.000Z', to: '2027-01-01T00:00:00.000Z' } },
     config: { ...supervisionReviewSettingsSchema.parse({}), version: 1, timeoutSeconds: 30, concurrency: 1 }, phase: 'collecting' }
@@ -96,10 +96,15 @@ it('rebuilds a partially written manifest after restart and validates completed
   await f.storage.resumeSupervisionReview(id, new AbortController().signal)
   expect(f.db.supervisionReviewStore().progress(id).sources).toBe(422)
   expect(f.db.supervisionReviewStore().load(id).initializing).toBeUndefined()
-  // Existing saved runs have no initialization flag and retain their frozen versions.
-  f.sql.prepare('UPDATE messages SET content = ? WHERE id = ?').run('Changed', f.conversations[0]!.messages[0]!.id)
-  await expect(f.storage.resumeSupervisionReview(id, new AbortController().signal)).rejects.toThrow('source changed')
-  expect(f.db.supervisionReviewStore().load(id).restartRequired).toBe(true)
+  // A source changed after freezing is skipped for this run instead of failing it.
+  const changedId = f.conversations[0]!.messages[0]!.id
+  f.sql.prepare('UPDATE messages SET content = ? WHERE id = ?').run('Changed', changedId)
+  await f.storage.resumeSupervisionReview(id, new AbortController().signal)
+  const store = f.db.supervisionReviewStore()
+  expect(store.progress(id)).toMatchObject({ sources: 421, skippedSources: 1 })
+  expect(store.load(id).restartRequired).toBeUndefined()
+  expect(f.sql.prepare('SELECT 1 FROM supervision_review_sources WHERE run_id = ? AND source = ?')
+    .get(id, `message:${changedId}`)).toBeUndefined()
 })
 
 it.each(['paused', 'cancelled'] as const)('accepts %s during production initialization, holds the slot, and never calls the model', async status => {

src/main/index.ts

@@ -8,6 +8,7 @@ import {
   dialog,
   globalShortcut,
   Menu,
+  net,
   safeStorage,
   session,
   shell,
@@ -1115,6 +1116,7 @@ if (hasSingleInstanceLock) {
             : Promise.resolve([])
         ])
       return createAgentRuntime(defaultWorkspace, settings, {
+        modelFetcher: net.fetch as unknown as typeof fetch,
         outputStore: { backingStore: storageFiles.backingStore },
         outputAdopt: storageFiles.attachments.outputAdopt,
         observeFailure: observeDesktopFailure,

src/main/ipc.test.ts

@@ -6684,6 +6684,7 @@ describe('registerIpcHandlers agent terminal state', () => {
       undefined, undefined, undefined, false, undefined, undefined, undefined, undefined, database)
     const actual = await vi.importActual<typeof import('./agent/create-runtime')>('./agent/create-runtime')
     runtimeFactoryMocks.createModelProfileRuntime.mockImplementation(actual.createModelProfileRuntime)
+    electronMocks.fetch.mockImplementation((input, init) => fetch(input, init))
     const profile = { id: crypto.randomUUID(), name: 'Review connection',
       baseUrl: `http://127.0.0.1:${address.port}/v1`, modelName: 'review-selected', protocol: 'openai-chat-completions', authentication: 'none',
       requestHeaders: {}, requestBody: { temperature: 0.25 } }
@@ -6712,6 +6713,7 @@ describe('registerIpcHandlers agent terminal state', () => {
       server.closeAllConnections()
       await new Promise<void>(resolve => server.close(() => resolve()))
       runtimeFactoryMocks.createModelProfileRuntime.mockReset()
+      electronMocks.fetch.mockReset()
     }
   })
 
@@ -12083,16 +12085,26 @@ describe('registerIpcHandlers agent terminal state', () => {
     await harness.dispose()
   })
 
-  it('routes eligible requests through the persisted smart expert service and publishes child events', async () => {
+  it.each([
+    { route: 'manual', consumesTrustedInstructions: true },
+    { route: 'smart', consumesTrustedInstructions: true },
+    { route: 'manual', consumesTrustedInstructions: false }
+  ] as const)('applies a $route expert as a role prompt on the conversation runtime (system channel: $consumesTrustedInstructions)', async ({ route, consumesTrustedInstructions }) => {
+    const received: Array<{ requestId: string; prompt: string; trustedInstructions?: string }> = []
     const runtime = {
+      runtimeId: 'opencode',
       capability: 'chat',
       requiresToolApproval: false,
       supportsToolExecution: true,
+      consumesTrustedInstructions,
       getStatus: vi.fn(),
       dispose: vi.fn(),
-      run: vi.fn()
+      async *run(request: { requestId: string; prompt: string; trustedInstructions?: string }) {
+        received.push(request)
+        yield { requestId: request.requestId, type: 'text', delta: '角色回答' }
+        yield { requestId: request.requestId, type: 'done' }
+      }
     }
-    const childTaskId = '00000000-0000-4000-8000-000000000099'
     const expert = {
       id: '00000000-0000-4000-8000-000000000001',
       name: '研究专家',
@@ -12104,69 +12116,49 @@ describe('registerIpcHandlers agent terminal state', () => {
       updatedAt: '2026-01-01T00:00:00.000Z'
     }
     const subagentService = {
-      run: vi.fn(async (input: {
-        parentRequest: { requestId: string }
-        onEvent: (event: Record<string, unknown>) => void
-      }) => {
-        for (const state of ['queued', 'running', 'completed']) {
-          input.onEvent({
-            requestId: input.parentRequest.requestId,
-            type: 'subagent',
-            childTaskId,
-            expertId: expert.id,
-            expertName: expert.name,
-            routingMode: 'smart',
-            state
-          })
-        }
-        return { childTaskId, output: '专家结果' }
-      }),
+      run: vi.fn(),
       cancelAll: vi.fn(),
       dispose: vi.fn(async () => undefined)
     }
-    const harness = createHarness(
-      runtime,
-      undefined,
-      subagentService,
-      true
-    )
-    vi.mocked(harness.assistantDatabase.listExperts).mockReturnValue([
-      expert
-    ])
+    const harness = createHarness(runtime, undefined, subagentService, true)
+    vi.mocked(harness.assistantDatabase.listExperts).mockReturnValue([expert])
+    vi.mocked(harness.assistantDatabase.getExpert).mockReturnValue(expert)
     const requestId = '3f496642-f47d-4e0a-8944-a32c77b0d6ef'
 
     harness.handler?.(trustedEvent(harness.webContents), {
       requestId,
-      conversationId: 'conversation-smart',
+      conversationId: 'conversation-role',
       prompt: '请做资料分析',
-      smartRouting: true
+      ...(route === 'manual' ? { expertId: expert.id } : { smartRouting: true })
     })
 
     await vi.waitFor(() =>
-      expect(harness.assistantDatabase.updateTaskStatus).toHaveBeenCalledWith(
-        requestId,
-        'completed'
-      )
+      expect(harness.assistantDatabase.updateTaskStatus).toHaveBeenCalledWith(requestId, 'completed')
     )
-    expect(runtime.run).not.toHaveBeenCalled()
-    expect(harness.getPolicySettings).toHaveBeenCalledOnce()
-    expect(harness.getResolvedSettings).not.toHaveBeenCalled()
-    expect(subagentService.run).toHaveBeenCalledWith(
-      expect.objectContaining({ expert, routingMode: 'smart' })
-    )
-    expect(harness.assistantDatabase.appendTaskEvent).toHaveBeenCalledWith(
+    expect(received).toHaveLength(1)
+    const request = received[0]!
+    expect(request.trustedInstructions).toContain('enabled capabilities')
+    expect(request.trustedInstructions).toContain('"研究专家"')
+    expect(request.trustedInstructions).toContain('Analyze evidence.')
+    if (consumesTrustedInstructions) {
+      expect(request.prompt).toBe('请做资料分析')
+    } else {
+      expect(request.prompt).toMatch(/enabled capabilities[\s\S]*Analyze evidence\.\n\n请做资料分析$/u)
+    }
+    expect(subagentService.run).not.toHaveBeenCalled()
+    expect(harness.assistantDatabase.appendTaskEvent).not.toHaveBeenCalledWith(
       requestId,
       'subagent',
-      expect.objectContaining({ childTaskId, state: 'queued' })
+      expect.anything()
     )
     expect(harness.webContents.send).toHaveBeenCalledWith(
       ipcChannels.agentEvent,
-      expect.objectContaining({ type: 'subagent', state: 'completed' })
+      expect.objectContaining({ type: 'text', delta: '角色回答' })
     )
     await harness.dispose()
   })
 
-  it.each(['manual', 'team', 'smart'] as const)('binds %s expert writes to each request project instead of the global workspace', async (route) => {
+  it('binds expert team writes to each request project instead of the global workspace', async () => {
     const actual = await vi.importActual<typeof import('./agent/create-runtime')>('./agent/create-runtime')
     const directory = await mkdtemp(join(tmpdir(), 'expert-projects-'))
     const globalRoot = join(directory, 'global')
@@ -12215,11 +12207,10 @@ describe('registerIpcHandlers agent terminal state', () => {
       for (const [index, projectId] of projectIds.entries()) {
         const requestId = crypto.randomUUID()
         await harness.handler!(trustedEvent(harness.webContents), { requestId, conversationId: `project-${index}`, projectId,
-          prompt: `write ${index === 0 ? 'alpha' : 'beta'}`, expertId: route === 'manual' ? expert.id : undefined,
-          teamMode: route === 'team', smartRouting: route === 'smart' })
+          prompt: `write ${index === 0 ? 'alpha' : 'beta'}`, teamMode: true })
         await vi.waitFor(() => expect(harness.assistantDatabase.updateTaskStatus).toHaveBeenCalledWith(requestId, 'completed'))
         const files = await readdir(roots[index]!)
-        expect(files).toHaveLength(route === 'team' ? 2 : 1)
+        expect(files).toHaveLength(2)
         for (const file of files) expect(await readFile(join(roots[index]!, file), 'utf8')).toBe(index === 0 ? 'alpha' : 'beta')
         for (const input of requests.filter(input => input.parentRequest.requestId === requestId)) {
           expect(input.executionSpace).toBe(getRuntime.mock.calls[index]?.[1])
@@ -12236,9 +12227,7 @@ describe('registerIpcHandlers agent terminal state', () => {
     }
   })
 
-  it.each((['manual', 'team', 'smart'] as const).flatMap(route =>
-    (['opencode', 'continue'] as const).map(provider => ({ route, provider }))
-  ))('uses managed $provider for $route SSH experts with their profile and parent bindings', async ({ route, provider }) => {
+  it.each(['opencode', 'continue'] as const)('uses managed %s for SSH expert team members with their profile and parent bindings', async (provider) => {
     const actual = await vi.importActual<typeof import('./agent/create-runtime')>('./agent/create-runtime')
     const globalRoot = await mkdtemp(join(tmpdir(), 'expert-ssh-'))
     const projectId = crypto.randomUUID()
@@ -12297,14 +12286,13 @@ describe('registerIpcHandlers agent terminal state', () => {
     try {
       const requestId = crypto.randomUUID()
       await harness.handler!(trustedEvent(harness.webContents), { requestId, conversationId: 'remote-expert', projectId,
-        prompt: 'write a file', expertId: route === 'manual' ? expert.id : undefined,
-        teamMode: route === 'team', smartRouting: route === 'smart' })
+        prompt: 'write a file', teamMode: true })
       await vi.waitFor(() => expect(harness.assistantDatabase.updateTaskStatus).toHaveBeenCalledWith(requestId, 'completed'))
-      expect(factory).toHaveBeenCalledTimes(route === 'team' ? 2 : 1)
+      expect(factory).toHaveBeenCalledTimes(2)
       expect(createRemote).toHaveBeenCalledWith({ provider, profileId: expert.modelProfileId }, executionSpace)
       expect(createLocal).not.toHaveBeenCalled()
       expect(binding.save).not.toHaveBeenCalled()
-      expect(fetcher).toHaveBeenCalledTimes(route === 'team' ? 1 : 0)
+      expect(fetcher).toHaveBeenCalledTimes(1)
       expect(ordinary.run).not.toHaveBeenCalled()
       expect(await readdir(globalRoot)).toEqual([])
     } finally {
@@ -12375,72 +12363,6 @@ describe('registerIpcHandlers agent terminal state', () => {
     }
   )
 
-  it('does not fall back to the ordinary runtime after smart subagent cancellation', async () => {
-    const runtime = {
-      capability: 'chat',
-      requiresToolApproval: false,
-      supportsToolExecution: true,
-      getStatus: vi.fn(),
-      dispose: vi.fn(),
-      run: vi.fn()
-    }
-    let markStarted!: () => void
-    const started = new Promise<void>((resolve) => {
-      markStarted = resolve
-    })
-    const subagentService = {
-      run: vi.fn((input: { signal: AbortSignal }) => {
-        markStarted()
-        return new Promise((_resolve, reject) => {
-          input.signal.addEventListener(
-            'abort',
-            () => reject(input.signal.reason),
-            { once: true }
-          )
-        })
-      }),
-      cancelAll: vi.fn(),
-      dispose: vi.fn(async () => undefined)
-    }
-    const harness = createHarness(
-      runtime,
-      undefined,
-      subagentService,
-      true
-    )
-    vi.mocked(harness.assistantDatabase.listExperts).mockReturnValue([
-      {
-        id: '00000000-0000-4000-8000-000000000001',
-        name: '研究专家',
-        description: '',
-        systemInstructions: 'Analyze.',
-        routingKeywords: ['资料分析'],
-        enabled: true,
-        createdAt: '2026-01-01T00:00:00.000Z',
-        updatedAt: '2026-01-01T00:00:00.000Z'
-      }
-    ])
-    const requestId = '3f496642-f47d-4e0a-8944-a32c77b0d6ef'
-    harness.handler?.(trustedEvent(harness.webContents), {
-      requestId,
-      conversationId: 'conversation-cancel-smart',
-      prompt: '请做资料分析',
-      smartRouting: true
-    })
-    await started
-    harness.cancelHandler?.(trustedEvent(harness.webContents), requestId)
-
-    await vi.waitFor(() =>
-      expect(harness.assistantDatabase.updateTaskStatus).toHaveBeenCalledWith(
-        requestId,
-        'cancelled',
-        '请求已取消'
-      )
-    )
-    expect(runtime.run).not.toHaveBeenCalled()
-    await harness.dispose()
-  })
-
   it('allows ordinary text requests on runtimes without tool execution', async () => {
     const runtime = {
       capability: 'chat',

src/main/ipc.ts

@@ -11,6 +11,7 @@ import {
   BrowserWindow,
   dialog,
   ipcMain,
+  net,
   shell,
   type NotificationConstructorOptions,
   type IpcMainInvokeEvent
@@ -282,10 +283,7 @@ import {
   supervisionKnowledgeCommitRequestSchema
 } from '../shared/supervision-contracts'
 import { showDesktopNotificationWhenUnfocused } from './desktop-notification'
-import {
-  SubagentRunError,
-  type SubagentService
-} from './assistant/subagent-service'
+import type { SubagentService } from './assistant/subagent-service'
 import { routeSubagent } from './assistant/subagent-router'
 import {
   startEnvironmentChannels
@@ -2699,37 +2697,20 @@ export function registerIpcHandlers(
     yield { requestId: request.requestId, type: 'done' }
   }
 
-  const runSingleExpert = async function* (
-    request: AgentExecutionRequest,
-    expert: Awaited<ReturnType<AssistantStoragePort['getExpert']>>,
-    routingMode: 'manual' | 'smart',
-    signal: AbortSignal,
-    executionSpace: ExecutionSpaceDescriptor | undefined,
-    reason?: string
-  ): AsyncGenerator<RuntimeEvent, void, void> {
-    if (!subagentService) {
-      throw new Error('专家子任务服务不可用')
-    }
-    const result = await subagentService.run({
-      parentRequest: request,
-      executionSpace,
-      expert,
-      routingMode,
-      reason,
-      signal,
-      onEvent: async (event) =>
-        (await publishSubagentEvent(request.requestId, event)),
-      onModelUsage: persistModelUsage
-    })
-    if (result.output) {
-      yield {
-        requestId: request.requestId,
-        type: 'text',
-        delta: result.output
-      }
-    }
-    yield { requestId: request.requestId, type: 'done' }
-  }
+  /**
+   * A selected or smart-routed expert is a role prompt for the conversation's
+   * own runtime, not a delegated child task: it joins the trusted
+   * instructions so streaming, tools and the selected runtime stay unchanged.
+   */
+  const expertRolePrompt = (
+    expert: Awaited<ReturnType<AssistantStoragePort['getExpert']>>
+  ): string =>
+    [
+      `Role: act as the specialist "${expert.name}" for this request.`,
+      expert.systemInstructions
+    ]
+      .filter(Boolean)
+      .join('\n\n')
 
   let scheduleQueueTickRunning = false
   const queueDueSchedules = async (): Promise<void> => {
@@ -4192,6 +4173,15 @@ export function registerIpcHandlers(
             )
           }
         }
+        // A selected or smart-routed expert is a role prompt for the
+        // conversation's own runtime, not a delegated child task.
+        const roleExpert =
+          executionRequest.teamMode || imageGeneration
+            ? undefined
+            : executionRequest.expertId
+              ? await assistantDatabase.getExpert(executionRequest.expertId)
+              : smartRoute?.expert
+        const rolePrompt = roleExpert ? expertRolePrompt(roleExpert) : ''
         const ordinaryStream = (): AsyncGenerator<
           RuntimeEvent,
           void,
@@ -4202,66 +4192,40 @@ export function registerIpcHandlers(
             managedSshOperationAccepted = true
             markManagedSshAccepted()
           }
+          const runtimeRequest: AgentExecutionRequest = rolePrompt
+            ? {
+                ...executionRequest,
+                trustedInstructions: [
+                  executionRequest.trustedInstructions,
+                  rolePrompt
+                ]
+                  .filter(Boolean)
+                  .join('\n\n')
+              }
+            : executionRequest
+          // Runtimes without a system channel get the capability and role
+          // instructions ahead of the prompt.
+          const promptPrefix =
+            selectedRuntime.consumesTrustedInstructions !== true
+              ? [capabilityInstruction, rolePrompt].filter(Boolean).join('\n\n')
+              : ''
           return selectedRuntime.run(
-            capabilityInstruction && selectedRuntime.consumesTrustedInstructions !== true
+            promptPrefix
               ? {
-                  ...executionRequest,
-                  prompt: `${capabilityInstruction}\n\n${executionRequest.prompt}`
+                  ...runtimeRequest,
+                  prompt: `${promptPrefix}\n\n${runtimeRequest.prompt}`
                 }
-              : executionRequest,
+              : runtimeRequest,
             controller.signal
           )
         }
-        const runSmartRoute = async function* (): AsyncGenerator<
-          RuntimeEvent,
-          void,
-          void
-        > {
-          if (!smartRoute) {
-            yield* ordinaryStream()
-            return
-          }
-          try {
-            yield* runSingleExpert(
-              executionRequest,
-              smartRoute.expert,
-              'smart',
-              controller.signal,
-              requestExecutionSpace,
-              `匹配 ${smartRoute.matches} 个关键词，得分 ${smartRoute.score}`
-            )
-          } catch (error) {
-            if (controller.signal.aborted) {
-              throw error
-            }
-            if (error instanceof SubagentRunError && error.output) {
-              yield {
-                requestId: request.requestId,
-                type: 'text',
-                delta: error.output
-              }
-              throw error
-            }
-            yield* ordinaryStream()
-          }
-        }
         const eventStream = executionRequest.teamMode
           ? runExpertTeam(
               executionRequest,
               controller.signal,
               requestExecutionSpace
             )
-          : executionRequest.expertId && !imageGeneration
-            ? runSingleExpert(
-                executionRequest,
-                await assistantDatabase.getExpert(
-                  executionRequest.expertId
-                ),
-                'manual',
-                controller.signal,
-                requestExecutionSpace
-              )
-            : runSmartRoute()
+          : ordinaryStream()
         for await (const agentEvent of splitTaggedReasoning(eventStream)) {
           if (agentEvent.type === 'done' || agentEvent.type === 'error') activeRequestLease.settling = true
           const provenance = remoteSemanticProvenance(agentEvent)
@@ -6355,7 +6319,7 @@ export function registerIpcHandlers(
     if (profile.authentication === 'api-key' && !profile.apiKey) {
       throw new Error(`监督者模型连接“${profile.name}”未配置 API Key`)
     }
-    return createModelProfileRuntime(settings.workspacePath, settings, profile)
+    return createModelProfileRuntime(settings.workspacePath, settings, profile, net.fetch as unknown as typeof fetch)
   }
   const supervisorService = createProductionSupervisorService(supervisionDatabase,
     async () => applicationSettingsStore?.get(), resolveSupervisorRuntime, supervisionModelPool,
@@ -7126,6 +7090,7 @@ export function registerIpcHandlers(
     assertTrustedSender(event, window)
     const request = supervisionSuggestionListRequestSchema.parse(input ?? {})
     if ((await applicationSettingsStore?.get())?.heartbeatEnabled !== true) return []
+    if (!supervisionPorts) return []
     return await (await supervisionDatabase.supervisionSuggestions()).list(request.status, request.limit, request.offset)
   })
   registerHandler(ipcChannels.supervisionSuggestionAction, async (event, input: unknown) => {

src/renderer/src/App.test.tsx

@@ -1146,14 +1146,18 @@ const api: DesktopApi & RuntimeNativeClientApi = {
 function composerMenuTrigger(
   label: "专家角色",
 ): HTMLButtonElement {
-  if (label === "专家角色") openComposerOptions();
   return screen.getByRole("button", {
     name: new RegExp(`^${label}：`, "u"),
   });
 }
 
 function openComposerOptions(): void {
-  const trigger = screen.getByRole("button", { name: "选项" });
+  const trigger = screen.getByRole("button", { name: "故事图谱与知识库" });
+  if (trigger.getAttribute("aria-expanded") !== "true") fireEvent.click(trigger);
+}
+
+async function openRuntimeOptions(runtime = "OpenCode"): Promise<void> {
+  const trigger = await screen.findByRole("button", { name: `${runtime} 专属功能` });
   if (trigger.getAttribute("aria-expanded") !== "true") fireEvent.click(trigger);
 }
 
@@ -6873,6 +6877,7 @@ describe("App", () => {
       evidence: [],
     });
     render(<App />);
+    await screen.findByRole("button", { name: "故事图谱与知识库" });
     openComposerOptions();
     const knowledgeScopeTrigger = await screen.findByRole("button", {
       name: "选择知识库，本次已启用 0 个",
@@ -7101,6 +7106,7 @@ describe("App", () => {
       evidence: [],
     });
     render(<App />);
+    await screen.findByRole("button", { name: "故事图谱与知识库" });
     openComposerOptions();
     const knowledgeScope = await screen.findByRole("button", {
       name: "选择知识库，本次已启用 0 个",
@@ -8656,7 +8662,6 @@ describe("App", () => {
 
   it("matches the expert keyboard menu to the model picker", async () => {
     render(<App />);
-    openComposerOptions();
 
     const expertTrigger = await screen.findByRole("button", {
       name: "专家角色：通用助手",
@@ -8683,15 +8688,16 @@ describe("App", () => {
       screen.queryByRole("menu", { name: "专家角色" }),
     ).not.toBeInTheDocument();
 
-    fireEvent.keyDown(expertTrigger, { key: "Escape" });
-    const optionsTrigger = screen.getByRole("button", { name: "选项" });
-    expect(optionsTrigger).toHaveFocus();
-    expect(optionsTrigger).toHaveAttribute("aria-expanded", "false");
-    expect(screen.queryByRole("dialog", { name: "对话设置" })).not.toBeInTheDocument();
-    fireEvent.click(optionsTrigger);
-    await waitFor(() => expect(screen.getByRole("button", { name: "专家角色：通用助手" })).toHaveFocus());
+    const contextTrigger = screen.getByRole("button", { name: "故事图谱与知识库" });
+    fireEvent.click(contextTrigger);
+    expect(screen.getByRole("dialog", { name: "故事图谱与知识库" })).toBeVisible();
+    await waitFor(() => expect(screen.getByRole("switch", { name: "使用故事图谱" })).toHaveFocus());
+    fireEvent.keyDown(screen.getByRole("switch", { name: "使用故事图谱" }), { key: "Escape" });
+    expect(contextTrigger).toHaveFocus();
+    expect(contextTrigger).toHaveAttribute("aria-expanded", "false");
+    fireEvent.click(contextTrigger);
     fireEvent.pointerDown(screen.getByLabelText("向 GoodBuddy 提问"));
-    expect(optionsTrigger).toHaveAttribute("aria-expanded", "false");
+    expect(contextTrigger).toHaveAttribute("aria-expanded", "false");
     expect(
       screen.queryByRole("menu", { name: "工作模式" }),
     ).not.toBeInTheDocument();
@@ -8731,8 +8737,6 @@ describe("App", () => {
       await screen.findByLabelText("向 GoodBuddy 提问")
     ).closest<HTMLElement>(".composer");
     expect(composer).not.toBeNull();
-    expect(screen.queryByRole("button", { name: "专家角色：通用助手" })).not.toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "选项" })).toHaveAttribute("aria-expanded", "false");
 
     const contentTools = within(composer!).getByRole("group", {
       name: "添加内容",
@@ -8747,12 +8751,16 @@ describe("App", () => {
     const conversationSettings = within(composer!).getByRole("group", {
       name: "对话设置",
     });
-    openComposerOptions();
-    expect(
-      within(screen.getByRole("dialog", { name: "对话设置" })).getByRole("button", {
-        name: "专家角色：通用助手",
-      }),
-    ).toBeInTheDocument();
+    // The role chip sits in the input's top-left corner, before the textarea.
+    const inputArea = composer!.querySelector<HTMLElement>(".composer__input")!;
+    const expertTrigger = within(inputArea).getByRole("button", { name: "专家角色：通用助手" });
+    expect(expertTrigger.compareDocumentPosition(screen.getByLabelText("向 GoodBuddy 提问")) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(within(conversationSettings).queryByRole("button", { name: "专家角色：通用助手" })).not.toBeInTheDocument();
+    // Toolbar order: context sources, Runtime, then Runtime-specific settings.
+    const contextTrigger = within(conversationSettings).getByRole("button", { name: "故事图谱与知识库" });
+    const runtimeTrigger = within(conversationSettings).getByRole("button", { name: /默认模型/u });
+    expect(contextTrigger).toHaveAttribute("aria-expanded", "false");
+    expect(contextTrigger.compareDocumentPosition(runtimeTrigger) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
     expect(
       within(conversationSettings).queryByRole("button", {
         name: /工作模式/u,
@@ -10311,14 +10319,14 @@ describe("App", () => {
     ));
     // Let startup selection and its focus effects finish before opening these options.
     await act(async () => { await new Promise<void>((resolve) => requestAnimationFrame(() => resolve())); });
-    openComposerOptions();
+    await openRuntimeOptions();
     const agentPicker = await screen.findByRole("button", {
       name: /OpenCode Runtime Agent/u,
     });
     const runtimeToolbar = screen.getByRole("group", {
       name: "OpenCode 专属功能",
     });
-    const options = screen.getByRole("dialog", { name: "对话设置" });
+    const options = screen.getByRole("dialog", { name: "OpenCode 专属功能" });
     expect(runtimeToolbar).toHaveClass("composer__runtime-toolbar");
     expect(runtimeToolbar).toContainElement(agentPicker);
     expect(options).toContainElement(agentPicker);
@@ -10346,7 +10354,7 @@ describe("App", () => {
       target: { value: "src/main" },
     });
     fireEvent.pointerDown(screen.getByLabelText("向 GoodBuddy 提问"));
-    expect(screen.queryByRole("dialog", { name: "对话设置" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("dialog", { name: "OpenCode 专属功能" })).not.toBeInTheDocument();
     expect(document.querySelector(".composer__option-summary")).toHaveTextContent("Planner");
     expect(document.querySelector(".composer__option-summary")).toHaveTextContent("/review");
     fireEvent.click(screen.getByLabelText("发送"));
@@ -10468,7 +10476,7 @@ describe("App", () => {
     render(<App />);
 
     await screen.findByText("已就绪");
-    openComposerOptions();
+    await openRuntimeOptions();
     const runtimeToolbar = await screen.findByRole("group", {
       name: "OpenCode 专属功能",
     });
@@ -10536,7 +10544,7 @@ describe("App", () => {
     await waitFor(() =>
       expect(api.runtimeCustomization.getNativeSnapshot).toHaveBeenCalledTimes(2),
     );
-    openComposerOptions();
+    expect(screen.queryByRole("button", { name: "OpenCode 专属功能" })).not.toBeInTheDocument();
     expect(screen.queryByRole("button", { name: /OpenCode Runtime Agent/u })).not.toBeInTheDocument();
     await act(async () => {
       retry.resolve({
@@ -10548,6 +10556,7 @@ describe("App", () => {
       });
       await retry.promise;
     });
+    await openRuntimeOptions();
     fireEvent.click(screen.getByRole("button", { name: /OpenCode Runtime Agent/u }));
     expect(screen.getByRole("menuitemradio", { name: /Planner/u })).toBeVisible();
     fireEvent.keyDown(screen.getByRole("menu", { name: "OpenCode Runtime Agent" }), { key: "Escape" });
@@ -10581,7 +10590,7 @@ describe("App", () => {
       .mockResolvedValueOnce(healthy)
       .mockResolvedValueOnce(healthy);
     render(<App />);
-    openComposerOptions();
+    await openRuntimeOptions();
     await screen.findByRole("button", { name: /OpenCode Runtime Agent/u });
     selectProjectOption(secondProject.name);
     await waitFor(() => expect(api.runtimeCustomization.getNativeSnapshot).toHaveBeenLastCalledWith(
@@ -10596,7 +10605,7 @@ describe("App", () => {
     selectProjectOption(firstProject.name);
     // Let the project picker restore focus before opening the dismiss-on-blur options.
     await act(async () => { await new Promise<void>((resolve) => requestAnimationFrame(() => resolve())); });
-    openComposerOptions();
+    await openRuntimeOptions();
     const toolbar = await screen.findByRole("group", { name: "OpenCode 专属功能" });
     await act(async () => {
       pending.resolve(failed);
@@ -10615,9 +10624,7 @@ describe("App", () => {
     vi.mocked(api.runtimeCustomization.getNativeSnapshot).mockResolvedValueOnce(empty);
     selectProjectOption(firstProject.name);
     await act(async () => { await new Promise<void>((resolve) => requestAnimationFrame(() => resolve())); });
-    openComposerOptions();
-    expect(screen.getByRole("button", { name: "选项" })).toHaveAttribute("aria-expanded", "true");
-    await waitFor(() => expect(screen.queryByRole("group", { name: "OpenCode 专属功能" })).not.toBeInTheDocument());
+    await waitFor(() => expect(screen.queryByRole("button", { name: "OpenCode 专属功能" })).not.toBeInTheDocument());
     expect(api.runtimeCustomization.getNativeSnapshot).toHaveBeenCalledTimes(callsBefore + 4);
   });
 
@@ -10652,7 +10659,7 @@ describe("App", () => {
     render(<App />);
 
     await screen.findByRole("button", { name: new RegExp(`^${rows[0]!.title}`, "u") });
-    openComposerOptions();
+    await openRuntimeOptions();
     const toolbar = await screen.findByRole("group", { name: "OpenCode 专属功能" });
     fireEvent.click(screen.getByRole("button", { name: /OpenCode Runtime Agent/u }));
     fireEvent.click(screen.getByRole("menuitemradio", { name: /Planner/u }));
@@ -10660,7 +10667,7 @@ describe("App", () => {
     fireEvent.click(screen.getByRole("menuitemradio", { name: /\/review/u }));
     const inventoryCalls = vi.mocked(api.runtimeCustomization.getNativeSnapshot).mock.calls.length;
     fireEvent.click(screen.getByText(rows[1]!.title).closest("button")!);
-    openComposerOptions();
+    await openRuntimeOptions();
     expect(screen.getByRole("group", { name: "OpenCode 专属功能" })).toBe(toolbar);
     expect(api.runtimeCustomization.getNativeSnapshot).toHaveBeenCalledTimes(inventoryCalls);
     await waitFor(() => expect(screen.getByRole("button", { name: /OpenCode Runtime Agent/u })).not.toHaveTextContent("Planner"));
@@ -10744,7 +10751,7 @@ describe("App", () => {
 
     render(<App />);
 
-    openComposerOptions();
+    await openRuntimeOptions("Continue");
     const presetPicker = await screen.findByRole("button", {
       name: /Continue 配置预设.*使用设置默认预设/u,
     });
@@ -10754,7 +10761,7 @@ describe("App", () => {
     expect(runtimeToolbar).toHaveClass("composer__runtime-toolbar");
     expect(runtimeToolbar).toContainElement(presetPicker);
     expect(
-      screen.getByRole("dialog", { name: "对话设置" }),
+      screen.getByRole("dialog", { name: "Continue 专属功能" }),
     ).toContainElement(presetPicker);
     fireEvent.click(presetPicker);
     fireEvent.click(
@@ -12579,7 +12586,8 @@ describe("App", () => {
 
   it("can dispatch a request to the parallel expert team", async () => {
     render(<App />);
-
+    // The role belongs to the loaded conversation.
+    await screen.findByLabelText("发送");
     selectComposerOption("专家角色", "专家团队（并行）");
     fireEvent.change(screen.getByLabelText("向 GoodBuddy 提问"), {
       target: { value: "制定发布计划" },
@@ -12667,6 +12675,43 @@ describe("App", () => {
     );
   });
 
+  it("keeps the role per conversation and snapshots it on the reply", async () => {
+    const expertId = "00000000-0000-4000-8000-000000000511";
+    vi.mocked(api.experts.list).mockResolvedValueOnce([
+      {
+        id: expertId,
+        name: "审查专家",
+        description: "代码审查",
+        systemInstructions: "Review code.",
+        routingKeywords: [],
+        enabled: true,
+        createdAt: "2026-08-01T00:00:00.000Z",
+        updatedAt: "2026-08-01T00:00:00.000Z",
+      },
+    ]);
+    const { container } = render(<App />);
+    await waitFor(() => expect(api.experts.list).toHaveBeenCalled());
+    const firstTitle = container.querySelector(".conversation-item--active .conversation-item__title")?.textContent;
+    const expertMenu = openComposerMenu("专家角色");
+    fireEvent.click(
+      (await within(expertMenu).findByText("审查专家", { selector: "span" })).closest<HTMLButtonElement>("button")!,
+    );
+    expect(composerMenuTrigger("专家角色")).toHaveAccessibleName("专家角色：审查专家");
+
+    fireEvent.change(screen.getByLabelText("向 GoodBuddy 提问"), { target: { value: "审查这个改动" } });
+    fireEvent.click(screen.getByLabelText("发送"));
+    await waitFor(() => expect(run).toHaveBeenCalledWith(expect.objectContaining({ expertId })));
+    expect(await screen.findByText("审查专家", { selector: ".message__role" })).toBeVisible();
+
+    const create = screen.getAllByRole("button", { name: "新建对话" })[0]!;
+    fireEvent.click(create);
+    await waitFor(() => expect(composerMenuTrigger("专家角色")).toHaveAccessibleName("专家角色：通用助手"));
+
+    fireEvent.click(within(container.querySelector<HTMLElement>(".conversation-list")!)
+      .getByTitle(firstTitle && firstTitle !== "新对话" ? firstTitle : "审查这个改动"));
+    await waitFor(() => expect(composerMenuTrigger("专家角色")).toHaveAccessibleName("专家角色：审查专家"));
+  });
+
   it("shows Subagent states and records child expert activity", async () => {
     render(<App />);
     fireEvent.change(await screen.findByLabelText("向 GoodBuddy 提问"), {

src/renderer/src/App.tsx

@@ -842,6 +842,7 @@ function toConversationSnapshots(
       knowledgeLibraryIds: conversation.knowledgeLibraryIds,
       knowledgeRetrievalMode: conversation.knowledgeRetrievalMode,
       storyGraphEnabled: conversation.storyGraphEnabled,
+      selectedExpertId: conversation.selectedExpertId,
       contextMetrics: conversation.contextMetrics,
       contextCompressionState: conversation.contextCompressionState,
       ...(conversation.branch ? { branch: conversation.branch } : {}),
@@ -1153,7 +1154,6 @@ function App(): React.JSX.Element {
   const [assistantExperts, setAssistantExperts] = useState<AssistantExpert[]>(
     [],
   );
-  const [selectedExpertId, setSelectedExpertId] = useState("");
   const [activeProjectId, setActiveProjectId] = useState("");
   const activeProjectIdRef = useRef(activeProjectId);
   const workspaceChangesRequestRef = useRef(0);
@@ -2280,6 +2280,34 @@ function App(): React.JSX.Element {
   // Header fields of the active conversation, value-compared: message updates
   // (streaming flushes, tool events) do not re-render App.
   const activeConversation = useActiveConversationView(conversationStore, activeId);
+  // The role follows the conversation; a deleted role reads as the general
+  // assistant.
+  const resolveExpertSelection = useCallback(
+    (value: string | undefined): string =>
+      !value || value === "team" ||
+      assistantExperts.some((expert) => expert.id === value)
+        ? value ?? ""
+        : "",
+    [assistantExperts],
+  );
+  const selectedExpertId = resolveExpertSelection(activeConversation?.selectedExpertId);
+  const setSelectedExpertId = useCallback(
+    (value: string): void => {
+      setConversations((current) =>
+        current.map((conversation) =>
+          conversation.id === activeId &&
+          (conversation.selectedExpertId ?? "") !== value
+            ? {
+                ...conversation,
+                selectedExpertId: value ? value : undefined,
+                updatedAt: Date.now(),
+              }
+            : conversation,
+        ),
+      );
+    },
+    [activeId, setConversations],
+  );
   const enabledKnowledgeLibraryIds =
     activeConversation?.knowledgeLibraryIds ?? [];
   const setEnabledKnowledgeLibraryIds = useCallback(
@@ -5113,7 +5141,7 @@ function App(): React.JSX.Element {
         : (queuedInput.expertId ?? "")
       : runtime?.capability === "image-generation"
         ? ""
-        : selectedExpertId;
+        : resolveExpertSelection(conversationSnapshot.selectedExpertId);
     const knowledgeLibraryIdsSnapshot =
       queuedInput?.knowledgeLibraryIds ?? enabledKnowledgeLibraryIds;
     const smartRoutingSnapshot =
@@ -5210,6 +5238,14 @@ function App(): React.JSX.Element {
     const executionPrompt = memoryContext
       ? `${prompt}\n\n${memoryContext}`
       : prompt;
+    const selectedExpert = selectedExpertSnapshot && selectedExpertSnapshot !== "team"
+      ? assistantExperts.find((expert) => expert.id === selectedExpertSnapshot)
+      : undefined;
+    const expertSnapshot: Message["expert"] = selectedExpertSnapshot === "team"
+      ? { kind: "team" }
+      : selectedExpert
+        ? { kind: "expert", id: selectedExpert.id, name: selectedExpert.name.trim().slice(0, 80) }
+        : undefined;
     const assistantMessage: Message = {
       id: crypto.randomUUID(),
       role: "assistant",
@@ -5218,6 +5254,7 @@ function App(): React.JSX.Element {
       createdAt: Date.now(),
       state: "streaming",
       status: t("chat.status.preparingRequest"),
+      ...(expertSnapshot ? { expert: expertSnapshot } : {}),
     };
 
     activeRuns.current.set(requestId, {
@@ -6512,16 +6549,10 @@ function App(): React.JSX.Element {
     onClose: () => {
       commitView(viewRef.current);
     },
+    // Each conversation keeps its role; one that no longer resolves reads as
+    // the general assistant (see resolveExpertSelection).
     onExpertsChanged: (experts: AssistantExpert[]) => {
       setAssistantExperts(experts);
-      if (
-        (selectedExpertId === "team" && experts.length < 2) ||
-        (selectedExpertId &&
-          selectedExpertId !== "team" &&
-          !experts.some((expert) => expert.id === selectedExpertId))
-      ) {
-        setSelectedExpertId("");
-      }
     },
     onRemoteProjectsEnabledChange: handleRemoteProjectsEnabledChange,
     onProjectsDeleted: removeProjectsFromUi,

src/renderer/src/ChatTimeline.test.tsx

@@ -180,6 +180,23 @@ describe('ChatTimeline', () => {
     }
   })
 
+  it('keeps the GoodBuddy name and shows the saved role as a caption below it', () => {
+    const props = { ...callbacks, artifactById: new Map(), conversationId: 'role', hiddenMessageCount: 0,
+      isUnusedConversation: false, locale: 'zh-CN' as const, messageStartIndex: 0, totalMessageCount: 3 }
+    const messages: Message[] = [
+      { id: 'expert', role: 'assistant', content: 'a', createdAt: 1, state: 'complete',
+        expert: { kind: 'expert', id: '00000000-0000-4000-8000-000000000901', name: '代码审查专家' } },
+      { id: 'team', role: 'assistant', content: 'b', createdAt: 2, state: 'complete', expert: { kind: 'team' } },
+      { id: 'plain', role: 'assistant', content: 'c', createdAt: 3, state: 'complete' }
+    ]
+    const view = render(<ChatTimeline {...props} messages={messages} />)
+    const articles = view.container.querySelectorAll('article.message')
+    expect([...articles].map(article => article.querySelector('.message__meta strong')?.textContent))
+      .toEqual(['GoodBuddy', 'GoodBuddy', 'GoodBuddy'])
+    expect([...articles].map(article => article.querySelector('.message__role')?.textContent ?? null))
+      .toEqual(['代码审查专家', '专家团队（并行）', null])
+  })
+
   it('captures only nonempty settled assistant replies, including incomplete replies', () => {
     const onAddToNote = vi.fn()
     const messages: Message[] = [

src/renderer/src/ChatTimeline.tsx

@@ -73,6 +73,7 @@ export type Message = {
   contextCompressions?: ConversationMessage['contextCompressions']
   tools?: ToolActivity[]
   subagents?: SubagentActivity[]
+  expert?: ConversationMessage['expert']
   approval?: {
     id: string
     taskId?: string
@@ -754,6 +755,14 @@ function ChatMessageRowView({
               : t('chat.status.waitingForProgress'))
     : message.status
 
+  const roleCaption = message.role !== 'assistant'
+    ? undefined
+    : message.expert?.kind === 'expert'
+      ? message.expert.name
+      : message.expert?.kind === 'team'
+        ? t('composer.experts.team')
+        : undefined
+
   return (
     <>
     <article
@@ -768,7 +777,7 @@ function ChatMessageRowView({
           <UserRound size={18} />
         )}
       </div>
-      <div className="message__header">
+      <div className={`message__header${roleCaption ? ' message__header--with-role' : ''}`}>
         <div className="message__meta">
           <strong>
             {message.role === 'assistant' ? 'GoodBuddy' : t('chat.user')}
@@ -786,6 +795,11 @@ function ChatMessageRowView({
           )}
           <span>{formatTime(message.createdAt, locale)}</span>
         </div>
+        {roleCaption && (
+          <small className="message__role" title={t('composer.expertLabel')}>
+            {roleCaption}
+          </small>
+        )}
       </div>
       <div className="message__body">
         {message.attachments && message.attachments.length > 0 && (

src/renderer/src/Composer.test.tsx

@@ -98,13 +98,14 @@ afterEach(() => {
 describe("Composer render boundary", () => {
   it("hides the story graph switch with Supervisor off and keeps conversation state while saving or failing", async () => {
     const { props, rerender, store } = setup();
-    fireEvent.click(screen.getByRole("button", { name: "Options" }));
-    expect(screen.queryByRole("switch", { name: "Use story graph" })).toBeNull();
+    expect(screen.queryByRole("button", { name: "Story graph and knowledge" })).toBeNull();
+    expect(screen.queryByRole("switch", { name: "Use story graph", hidden: true })).toBeNull();
     let finish!: () => void;
     const save = vi.fn(() => new Promise<void>(resolve => { finish = resolve; }));
     const notify = vi.fn();
     const next = { ...props, supervisorEnabled: true, actions: { ...actions, setStoryGraphEnabled: save, notify } };
     rerender(<Composer {...next} />);
+    fireEvent.click(screen.getByRole("button", { name: "Story graph and knowledge" }));
     const toggle = screen.getByRole("switch", { name: "Use story graph" });
     expect(toggle).toBeChecked();
     expect(toggle.closest("label")).toHaveClass("toggle-row");
@@ -121,7 +122,7 @@ describe("Composer render boundary", () => {
     fireEvent.click(toggle);
     await waitFor(() => { expect(toggle).toBeEnabled(); expect(toggle).not.toBeChecked(); expect(notify).toHaveBeenCalledWith({ tone: "error", message: "Save failed" }); });
     rerender(<Composer {...next} conversationId="b" />);
-    fireEvent.click(screen.getByRole("button", { name: "Options" }));
+    fireEvent.click(screen.getByRole("button", { name: "Story graph and knowledge" }));
     expect(screen.getByRole("switch", { name: "Use story graph" })).toBeChecked();
     rerender(<Composer {...next} supervisorEnabled={false} />);
     expect(screen.queryByRole("switch", { name: "Use story graph", hidden: true })).toBeNull();

src/renderer/src/Composer.tsx

@@ -208,11 +208,16 @@ export const Composer = memo(function Composer({
     `${conversationId}\u0000${isRunning}\u0000${workspaceView}`,
   );
   const composerOptionsOpen = menus.optionsOpen;
+  const runtimeOptionsOpen = menus.runtimeOptionsOpen;
   const knowledgeScopeOpen = menus.knowledgeScopeOpen;
   const composerMenuOpen = menus.menu;
   const runtimeMenuOpen = menus.runtimeMenuOpen;
-  const setComposerOptionsOpen = useCallback(
-    (open: boolean): void => setMenus({ optionsOpen: open }),
+  const closeComposerOptions = useCallback(
+    (): void => setMenus({ optionsOpen: false, knowledgeScopeOpen: false }),
+    [setMenus],
+  );
+  const closeRuntimeOptions = useCallback(
+    (): void => setMenus({ runtimeOptionsOpen: false, menu: undefined }),
     [setMenus],
   );
   const setKnowledgeScopeOpen = useCallback(
@@ -233,7 +238,13 @@ export const Composer = memo(function Composer({
   );
   const setExpertMenuOpen = useCallback((open: boolean): void => {
     setMenus(open
-      ? { menu: "expert", runtimeMenuOpen: false, knowledgeScopeOpen: false }
+      ? {
+          menu: "expert",
+          runtimeMenuOpen: false,
+          knowledgeScopeOpen: false,
+          optionsOpen: false,
+          runtimeOptionsOpen: false,
+        }
       : { menu: undefined });
   }, [setMenus]);
   const setRuntimeAgentMenuOpen = useCallback((open: boolean): void => {
@@ -253,6 +264,8 @@ export const Composer = memo(function Composer({
   }, [setMenus]);
   const composerOptionsRef = useRef<HTMLDivElement>(null);
   const composerOptionsTriggerRef = useRef<HTMLButtonElement>(null);
+  const runtimeOptionsRef = useRef<HTMLDivElement>(null);
+  const runtimeOptionsTriggerRef = useRef<HTMLButtonElement>(null);
   const knowledgeScopeTriggerRef = useRef<HTMLButtonElement>(null);
   const knowledgeScopePopoverRef = useRef<HTMLDivElement>(null);
   const runtimeMenuRef = useRef<HTMLDivElement>(null);
@@ -308,32 +321,27 @@ export const Composer = memo(function Composer({
     };
   }, [knowledgeScopeOpen, setKnowledgeScopeOpen]);
 
+  useDismissibleComposerDialog(
+    composerOptionsOpen,
+    composerOptionsRef,
+    composerOptionsTriggerRef,
+    closeComposerOptions,
+  );
   useEffect(() => {
-    if (!composerOptionsOpen) {
-      return;
-    }
-    const isOptionsTarget = (target: EventTarget | null): boolean =>
-      target instanceof Node &&
-      (composerOptionsRef.current?.contains(target) === true ||
-        composerOptionsTriggerRef.current?.contains(target) === true);
-    const dismissOutside = (event: Event): void => {
-      if (!isOptionsTarget(event.target)) {
-        setMenus({ optionsOpen: false, knowledgeScopeOpen: false });
-      }
-    };
+    if (!composerOptionsOpen) return;
     const frame = requestAnimationFrame(() => {
-      // Keyboard users land on the same first control as the model picker
-      // and expert menu; optional switches above stay Tab-reachable.
-      composerOptionsRef.current?.querySelector<HTMLButtonElement>("button:not(:disabled)")?.focus();
+      composerOptionsRef.current
+        ?.querySelector<HTMLElement>("button:not(:disabled), input:not(:disabled)")
+        ?.focus();
     });
-    document.addEventListener("pointerdown", dismissOutside);
-    document.addEventListener("focusin", dismissOutside);
-    return () => {
-      cancelAnimationFrame(frame);
-      document.removeEventListener("pointerdown", dismissOutside);
-      document.removeEventListener("focusin", dismissOutside);
-    };
-  }, [composerOptionsOpen, setMenus]);
+    return () => cancelAnimationFrame(frame);
+  }, [composerOptionsOpen, knowledgeLibraries.length]);
+  useDismissibleComposerDialog(
+    runtimeOptionsOpen,
+    runtimeOptionsRef,
+    runtimeOptionsTriggerRef,
+    closeRuntimeOptions,
+  );
 
   useEffect(() => {
     if (!runtimeMenuOpen) {
@@ -406,10 +414,9 @@ export const Composer = memo(function Composer({
         runtime: runtimeControlsProvider,
       })
     : "";
+  const composerContextAvailable =
+    supervisorEnabled === true || knowledgeLibraries.length > 0;
   const composerOptionSummary = [
-    selectedExpertId && runtime?.capability !== "image-generation"
-      ? assistantExpertOptions.find((option) => option.value === selectedExpertId)?.label
-      : undefined,
     enabledKnowledgeLibraryIds.length > 0
       ? t("composer.knowledge.select", { count: enabledKnowledgeLibraryIds.length })
       : undefined,
@@ -646,6 +653,22 @@ export const Composer = memo(function Composer({
           </div>
         )}
         <div className="composer__input">
+          <div className="composer__input-header">
+            <ComposerMenuSelect
+              ariaLabel={t("composer.expertLabel")}
+              className="composer-picker--expert composer-picker--chip"
+              disabled={
+                isRunning ||
+                runtime?.capability === "image-generation"
+              }
+              icon={<Bot aria-hidden="true" size={13} />}
+              menuOpen={composerMenuOpen === "expert"}
+              onChange={actions.selectExpert}
+              onOpenChange={setExpertMenuOpen}
+              options={assistantExpertOptions}
+              value={selectedExpertId}
+            />
+          </div>
           <ComposerDraftText
             conversationId={conversationId}
             store={composerDrafts}
@@ -809,270 +832,214 @@ export const Composer = memo(function Composer({
                 <Mic aria-hidden="true" size={18} />
               </button>
             </div>
-            <button
-              aria-controls="composer-options"
-              aria-expanded={composerOptionsOpen}
-              aria-haspopup="dialog"
-              aria-label={t("composer.options")}
-              className="composer__options-trigger"
-              onClick={() => {
-                setComposerOptionsOpen(!composerOptionsOpen);
-                setComposerMenuOpen(undefined);
-                setRuntimeMenuOpen(false);
-                setKnowledgeScopeOpen(false);
-              }}
-              ref={composerOptionsTriggerRef}
-              title={t("composer.settings")}
-              type="button"
-            >
-              <SlidersHorizontal aria-hidden="true" size={18} />
-            </button>
-            <div
-              aria-label={t("composer.settings")}
-              className="composer__options"
-              id="composer-options"
-              hidden={!composerOptionsOpen}
-              ref={composerOptionsRef}
-              role="dialog"
-              onKeyDown={(event) => {
-                if (event.key !== "Escape" || event.defaultPrevented) return;
-                event.preventDefault();
-                event.stopPropagation();
-                if (knowledgeScopeOpen) {
-                  setKnowledgeScopeOpen(false);
-                  knowledgeScopeTriggerRef.current?.focus();
-                } else {
-                  setComposerOptionsOpen(false);
-                  setComposerMenuOpen(undefined);
-                  composerOptionsTriggerRef.current?.focus();
-                }
-              }}
-            >
-              <strong>{t("composer.settings")}</strong>
-              {supervisorEnabled && (
-                <label className="toggle-row">
-                  <span className="composer__story-graph-label">
-                    <Network aria-hidden="true" size={16} />
-                    {t("composer.storyGraph.label")}
-                  </span>
-                  <input
-                    type="checkbox"
-                    role="switch"
-                    checked={view?.storyGraphEnabled !== false}
-                    disabled={storyGraphSaving}
-                    onChange={(event) => {
-                      setStoryGraphSaving(true);
-                      void actions.setStoryGraphEnabled(conversationId, event.target.checked)
-                        .catch((error: unknown) => actions.notify({ tone: "error", message: error instanceof Error ? error.message : String(error) }))
-                        .finally(() => setStoryGraphSaving(false));
-                    }}
-                  />
-                </label>
-              )}
-            {knowledgeLibraries.length > 0 && (
-              <div
-                className="knowledge-scope"
-                onBlurCapture={(event) => {
-                  if (
-                    event.relatedTarget instanceof Node &&
-                    !event.currentTarget.contains(
-                      event.relatedTarget,
-                    )
-                  ) {
-                    setKnowledgeScopeOpen(false);
-                  }
-                }}
-              >
-                <button
-                  aria-controls="knowledge-scope-popover"
-                  aria-haspopup="dialog"
-                  aria-label={t("composer.knowledge.select", {
-                    count: enabledKnowledgeLibraryIds.length,
-                  })}
-                  aria-expanded={knowledgeScopeOpen}
-                  onClick={() => {
-                    setComposerMenuOpen(undefined);
-                    setRuntimeMenuOpen(false);
-                    setKnowledgeScopeOpen(
-                      (current) => !current,
-                    );
-                  }}
-                  ref={knowledgeScopeTriggerRef}
-                  title={t("composer.knowledge.title")}
-                  type="button"
-                >
-                  <Library aria-hidden="true" size={16} />
-                  <span>
-                    {t("navigation.knowledge")}
-                    <strong>
-                      {enabledKnowledgeLibraryIds.length}
-                    </strong>
-                  </span>
-                  <ChevronDown
-                    aria-hidden="true"
-                    className="knowledge-scope__chevron"
-                    size={14}
-                  />
-                </button>
-                {knowledgeScopeOpen && (
-                  <div
-                    aria-label={t("composer.knowledge.scope")}
-                    className="knowledge-scope__popover"
-                    id="knowledge-scope-popover"
-                    ref={knowledgeScopePopoverRef}
-                    role="dialog"
-                  >
-                    <strong>
-                      {t("composer.knowledge.scope")}
-                    </strong>
-                    {knowledgeLibraries.map(
-                      (library) => {
-                        const instance = externalInstances.find(item => item.id === library.external?.instanceId);
-                        const externalStatus = !instance ? 'temporarily-unavailable' : !instance.enabled ? 'instance-disabled' : instance.credentialStatus !== 'configured' || instance.probeStatus === 'auth-failed' ? 'credential-error' : ['failed', 'unreachable'].includes(instance.probeStatus) ? 'temporarily-unavailable' : 'ready';
-                        return (
-                        <label key={library.id}>
-                          <input
-                            disabled={!!library.external && externalStatus !== 'ready'}
-                            checked={enabledKnowledgeLibraryIds.includes(
-                              library.id,
-                            )}
-                            onChange={(event) =>
-                              actions.setEnabledKnowledgeLibraryIds(
-                                (current) =>
-                                  event.target.checked
-                                    ? [
-                                        ...new Set([
-                                          ...current,
-                                          library.id,
-                                        ]),
-                                      ]
-                                    : current.filter(
-                                        (id) =>
-                                          id !== library.id,
-                                      ),
-                              )
-                            }
-                            type="checkbox"
-                          />
-                          <span>{library.name}</span>
-                          <small>
-                            {library.external ? `${({ dify: 'Dify', fastgpt: 'FastGPT', ragflow: 'RAGFlow' })[library.external.provider]} · ${instance?.name ?? library.external.instanceId} · ${t(`external.states.${externalStatus}`, { ns: 'knowledge' })}` : t(
-                              "composer.knowledge.documents",
-                              {
-                                count: library.documentCount,
-                              },
-                            )}
-                          </small>
-                        </label>
-                      )},
-                    )}
-                    <div className="knowledge-scope__retrieval-mode">
-                      <strong>
-                        {t("composer.knowledge.modeLabel")}
-                      </strong>
-                      <SegmentedControl
-                        ariaLabel={t(
-                          "composer.knowledge.modeLabel",
-                        )}
-                        onChange={actions.setKnowledgeRetrievalMode}
-                        options={[
-                          {
-                            value: "auto",
-                            label: t(
-                              "composer.knowledge.auto",
-                            ),
-                          },
-                          {
-                            value: "always",
-                            label: t(
-                              "composer.knowledge.always",
-                            ),
-                          },
-                        ]}
-                        value={
-                          view?.knowledgeRetrievalMode ??
-                          "auto"
-                        }
-                      />
-                      <small>
-                        {view?.knowledgeRetrievalMode ===
-                        "always"
-                          ? t(
-                              "composer.knowledge.alwaysDescription",
-                            )
-                          : t(
-                              "composer.knowledge.autoDescription",
-                            )}
-                      </small>
-                    </div>
-                  </div>
-                )}
-              </div>
-            )}
-            <div className="composer__configuration">
-              <ComposerMenuSelect
-                ariaLabel={t("composer.expertLabel")}
-                className="composer-picker--expert"
-                disabled={
-                  isRunning ||
-                  runtime?.capability === "image-generation"
-                }
-                icon={<Bot aria-hidden="true" size={15} />}
-                menuOpen={composerMenuOpen === "expert"}
-                onChange={actions.selectExpert}
-                onOpenChange={setExpertMenuOpen}
-                options={assistantExpertOptions}
-                value={selectedExpertId}
-              />
-            </div>
-            {runtimeControlsProvider && (
-              <div aria-label={runtimeControlsLabel} className="composer__runtime-toolbar" role="group">
-                <strong className="composer__runtime-toolbar-label">{runtimeControlsLabel}</strong>
-                <div className="composer__runtime-controls">
-                  {runtimeAgentControlAvailable && (
-                    <ComposerMenuSelect
-                      ariaLabel={t("composer.runtimeControls.agentLabel")}
-                      className="composer-picker--runtime"
-                      disabled={isRunning}
-                      icon={<TerminalSquare aria-hidden="true" size={15} />}
-                      menuOpen={composerMenuOpen === "runtime-agent"}
-                      onChange={actions.selectRuntimeAgent}
-                      onOpenChange={setRuntimeAgentMenuOpen}
-                      options={runtimeAgentOptions}
-                      value={selectedRuntimeAgent}
-                    />
-                  )}
-                  {runtimePresetControlAvailable && (
-                    <ComposerMenuSelect
-                      ariaLabel={t("composer.runtimeControls.presetLabel")}
-                      className="composer-picker--runtime"
-                      disabled={isRunning}
-                      icon={<TerminalSquare aria-hidden="true" size={15} />}
-                      menuOpen={composerMenuOpen === "runtime-preset"}
-                      onChange={actions.selectContinuePreset}
-                      onOpenChange={setRuntimePresetMenuOpen}
-                      options={runtimePresetOptions}
-                      value={selectedContinuePreset}
-                    />
-                  )}
-                  {runtimeActionControlAvailable && (
-                    <ComposerMenuSelect
-                      ariaLabel={t("composer.runtimeControls.actionLabel")}
-                      className="composer-picker--runtime-action"
-                      disabled={isRunning}
-                      icon={<TerminalSquare aria-hidden="true" size={15} />}
-                      menuOpen={composerMenuOpen === "runtime-action"}
-                      onChange={actions.selectRuntimeAction}
-                      onOpenChange={setRuntimeActionMenuOpen}
-                      options={runtimeActionOptions}
-                      value={runtimeActionOptions.find((option) => option.action?.type === "command" && option.action.id === selectedRuntimeCommand)?.value ?? ""}
-                    />
-                  )}
-                </div>
-              </div>
-            )}
-            </div>
             <div className="composer__configuration" role="group" aria-label={t("composer.settings")}>
+              {composerContextAvailable && (
+                <>
+                  <button
+                    aria-controls="composer-options"
+                    aria-expanded={composerOptionsOpen}
+                    aria-haspopup="dialog"
+                    aria-label={t("composer.contextSources")}
+                    className="composer__options-trigger"
+                    onClick={() => {
+                      setMenus({
+                        optionsOpen: !composerOptionsOpen,
+                        runtimeOptionsOpen: false,
+                        menu: undefined,
+                        runtimeMenuOpen: false,
+                        knowledgeScopeOpen: false,
+                      });
+                    }}
+                    ref={composerOptionsTriggerRef}
+                    title={t("composer.contextSources")}
+                    type="button"
+                  >
+                    <Library aria-hidden="true" size={18} />
+                  </button>
+                  <div
+                    aria-label={t("composer.contextSources")}
+                    className="composer__options"
+                    id="composer-options"
+                    hidden={!composerOptionsOpen}
+                    ref={composerOptionsRef}
+                    role="dialog"
+                    onKeyDown={(event) => {
+                      if (event.key !== "Escape" || event.defaultPrevented) return;
+                      event.preventDefault();
+                      event.stopPropagation();
+                      if (knowledgeScopeOpen) {
+                        setKnowledgeScopeOpen(false);
+                        knowledgeScopeTriggerRef.current?.focus();
+                      } else {
+                        closeComposerOptions();
+                        composerOptionsTriggerRef.current?.focus();
+                      }
+                    }}
+                  >
+                    <strong>{t("composer.contextSources")}</strong>
+                    {supervisorEnabled && (
+                      <label className="toggle-row composer__context-row">
+                        <span className="composer__story-graph-label">
+                          <Network aria-hidden="true" size={16} />
+                          {t("composer.storyGraph.label")}
+                        </span>
+                        <input
+                          type="checkbox"
+                          role="switch"
+                          checked={view?.storyGraphEnabled !== false}
+                          disabled={storyGraphSaving}
+                          onChange={(event) => {
+                            setStoryGraphSaving(true);
+                            void actions.setStoryGraphEnabled(conversationId, event.target.checked)
+                              .catch((error: unknown) => actions.notify({ tone: "error", message: error instanceof Error ? error.message : String(error) }))
+                              .finally(() => setStoryGraphSaving(false));
+                          }}
+                        />
+                      </label>
+                    )}
+                    {knowledgeLibraries.length > 0 && (
+                      <div
+                        className="knowledge-scope"
+                        onBlurCapture={(event) => {
+                          if (
+                            event.relatedTarget instanceof Node &&
+                            !event.currentTarget.contains(
+                              event.relatedTarget,
+                            )
+                          ) {
+                            setKnowledgeScopeOpen(false);
+                          }
+                        }}
+                      >
+                        <button
+                          aria-controls="knowledge-scope-popover"
+                          aria-haspopup="dialog"
+                          aria-label={t("composer.knowledge.select", {
+                            count: enabledKnowledgeLibraryIds.length,
+                          })}
+                          aria-expanded={knowledgeScopeOpen}
+                          onClick={() => {
+                            setComposerMenuOpen(undefined);
+                            setRuntimeMenuOpen(false);
+                            setKnowledgeScopeOpen(
+                              (current) => !current,
+                            );
+                          }}
+                          ref={knowledgeScopeTriggerRef}
+                          title={t("composer.knowledge.title")}
+                          type="button"
+                        >
+                          <Library aria-hidden="true" size={16} />
+                          <span>
+                            {t("navigation.knowledge")}
+                            <strong>
+                              {enabledKnowledgeLibraryIds.length}
+                            </strong>
+                          </span>
+                          <ChevronDown
+                            aria-hidden="true"
+                            className="knowledge-scope__chevron"
+                            size={14}
+                          />
+                        </button>
+                        {knowledgeScopeOpen && (
+                          <div
+                            aria-label={t("composer.knowledge.scope")}
+                            className="knowledge-scope__popover"
+                            id="knowledge-scope-popover"
+                            ref={knowledgeScopePopoverRef}
+                            role="dialog"
+                          >
+                            <strong>
+                              {t("composer.knowledge.scope")}
+                            </strong>
+                            {knowledgeLibraries.map(
+                              (library) => {
+                                const instance = externalInstances.find(item => item.id === library.external?.instanceId);
+                                const externalStatus = !instance ? 'temporarily-unavailable' : !instance.enabled ? 'instance-disabled' : instance.credentialStatus !== 'configured' || instance.probeStatus === 'auth-failed' ? 'credential-error' : ['failed', 'unreachable'].includes(instance.probeStatus) ? 'temporarily-unavailable' : 'ready';
+                                return (
+                                <label key={library.id}>
+                                  <input
+                                    disabled={!!library.external && externalStatus !== 'ready'}
+                                    checked={enabledKnowledgeLibraryIds.includes(
+                                      library.id,
+                                    )}
+                                    onChange={(event) =>
+                                      actions.setEnabledKnowledgeLibraryIds(
+                                        (current) =>
+                                          event.target.checked
+                                            ? [
+                                                ...new Set([
+                                                  ...current,
+                                                  library.id,
+                                                ]),
+                                              ]
+                                            : current.filter(
+                                                (id) =>
+                                                  id !== library.id,
+                                              ),
+                                      )
+                                    }
+                                    type="checkbox"
+                                  />
+                                  <span>{library.name}</span>
+                                  <small>
+                                    {library.external ? `${({ dify: 'Dify', fastgpt: 'FastGPT', ragflow: 'RAGFlow' })[library.external.provider]} · ${instance?.name ?? library.external.instanceId} · ${t(`external.states.${externalStatus}`, { ns: 'knowledge' })}` : t(
+                                      "composer.knowledge.documents",
+                                      {
+                                        count: library.documentCount,
+                                      },
+                                    )}
+                                  </small>
+                                </label>
+                              )},
+                            )}
+                            <div className="knowledge-scope__retrieval-mode">
+                              <strong>
+                                {t("composer.knowledge.modeLabel")}
+                              </strong>
+                              <SegmentedControl
+                                ariaLabel={t(
+                                  "composer.knowledge.modeLabel",
+                                )}
+                                onChange={actions.setKnowledgeRetrievalMode}
+                                options={[
+                                  {
+                                    value: "auto",
+                                    label: t(
+                                      "composer.knowledge.auto",
+                                    ),
+                                  },
+                                  {
+                                    value: "always",
+                                    label: t(
+                                      "composer.knowledge.always",
+                                    ),
+                                  },
+                                ]}
+                                value={
+                                  view?.knowledgeRetrievalMode ??
+                                  "auto"
+                                }
+                              />
+                              <small>
+                                {view?.knowledgeRetrievalMode ===
+                                "always"
+                                  ? t(
+                                      "composer.knowledge.alwaysDescription",
+                                    )
+                                  : t(
+                                      "composer.knowledge.autoDescription",
+                                    )}
+                              </small>
+                            </div>
+                          </div>
+                        )}
+                      </div>
+                    )}
+                  </div>
+                </>
+              )}
               <div className="runtime-picker">
                 <button
                   aria-expanded={runtimeMenuOpen}
@@ -1080,10 +1047,13 @@ export const Composer = memo(function Composer({
                   className="model-button"
                   disabled={isRunning || runtimeSwitching}
                   onClick={() => {
-                    setComposerOptionsOpen(false);
-                    setKnowledgeScopeOpen(false);
-                    setComposerMenuOpen(undefined);
-                    setRuntimeMenuOpen(!runtimeMenuOpen);
+                    setMenus({
+                      optionsOpen: false,
+                      runtimeOptionsOpen: false,
+                      knowledgeScopeOpen: false,
+                      menu: undefined,
+                      runtimeMenuOpen: !runtimeMenuOpen,
+                    });
                   }}
                   onKeyDown={(event) => {
                     if (
@@ -1093,10 +1063,13 @@ export const Composer = memo(function Composer({
                         event.key === " ")
                     ) {
                       event.preventDefault();
-                      setComposerOptionsOpen(false);
-                      setKnowledgeScopeOpen(false);
-                      setComposerMenuOpen(undefined);
-                      setRuntimeMenuOpen(true);
+                      setMenus({
+                        optionsOpen: false,
+                        runtimeOptionsOpen: false,
+                        knowledgeScopeOpen: false,
+                        menu: undefined,
+                        runtimeMenuOpen: true,
+                      });
                     }
                   }}
                   ref={runtimeMenuButtonRef}
@@ -1143,6 +1116,91 @@ export const Composer = memo(function Composer({
                   />
                 )}
               </div>
+              {runtimeControlsProvider && (
+                <>
+                  <button
+                    aria-controls="composer-runtime-options"
+                    aria-expanded={runtimeOptionsOpen}
+                    aria-haspopup="dialog"
+                    aria-label={runtimeControlsLabel}
+                    className="composer__options-trigger"
+                    onClick={() => {
+                      setMenus({
+                        runtimeOptionsOpen: !runtimeOptionsOpen,
+                        optionsOpen: false,
+                        menu: undefined,
+                        runtimeMenuOpen: false,
+                        knowledgeScopeOpen: false,
+                      });
+                    }}
+                    ref={runtimeOptionsTriggerRef}
+                    title={runtimeControlsLabel}
+                    type="button"
+                  >
+                    <SlidersHorizontal aria-hidden="true" size={18} />
+                  </button>
+                  <div
+                    aria-label={runtimeControlsLabel}
+                    className="composer__options composer__options--runtime"
+                    id="composer-runtime-options"
+                    hidden={!runtimeOptionsOpen}
+                    ref={runtimeOptionsRef}
+                    role="dialog"
+                    onKeyDown={(event) => {
+                      if (event.key !== "Escape" || event.defaultPrevented) return;
+                      event.preventDefault();
+                      event.stopPropagation();
+                      closeRuntimeOptions();
+                      runtimeOptionsTriggerRef.current?.focus();
+                    }}
+                  >
+                    <div aria-label={runtimeControlsLabel} className="composer__runtime-toolbar" role="group">
+                      <strong className="composer__runtime-toolbar-label">{runtimeControlsLabel}</strong>
+                      <div className="composer__runtime-controls">
+                        {runtimeAgentControlAvailable && (
+                          <ComposerMenuSelect
+                            ariaLabel={t("composer.runtimeControls.agentLabel")}
+                            className="composer-picker--runtime"
+                            disabled={isRunning}
+                            icon={<TerminalSquare aria-hidden="true" size={15} />}
+                            menuOpen={composerMenuOpen === "runtime-agent"}
+                            onChange={actions.selectRuntimeAgent}
+                            onOpenChange={setRuntimeAgentMenuOpen}
+                            options={runtimeAgentOptions}
+                            value={selectedRuntimeAgent}
+                          />
+                        )}
+                        {runtimePresetControlAvailable && (
+                          <ComposerMenuSelect
+                            ariaLabel={t("composer.runtimeControls.presetLabel")}
+                            className="composer-picker--runtime"
+                            disabled={isRunning}
+                            icon={<TerminalSquare aria-hidden="true" size={15} />}
+                            menuOpen={composerMenuOpen === "runtime-preset"}
+                            onChange={actions.selectContinuePreset}
+                            onOpenChange={setRuntimePresetMenuOpen}
+                            options={runtimePresetOptions}
+                            value={selectedContinuePreset}
+                          />
+                        )}
+                        {runtimeActionControlAvailable && (
+                          <ComposerMenuSelect
+                            ariaLabel={t("composer.runtimeControls.actionLabel")}
+                            className="composer-picker--runtime-action"
+                            disabled={isRunning}
+                            icon={<TerminalSquare aria-hidden="true" size={15} />}
+                            menuOpen={composerMenuOpen === "runtime-action"}
+                            onChange={actions.selectRuntimeAction}
+                            onOpenChange={setRuntimeActionMenuOpen}
+                            options={runtimeActionOptions}
+                            value={runtimeActionOptions.find((option) => option.action?.type === "command" && option.action.id === selectedRuntimeCommand)?.value ?? ""}
+                          />
+                        )}
+                      </div>
+                    </div>
+                  </div>
+                </>
+              )}
             </div>
           </div>
           <div className="composer__submit-actions">
@@ -1378,3 +1436,41 @@ export const Composer = memo(function Composer({
 });
 
 const emptyLibraryIds: string[] = [];
+
+/**
+ * Closes a composer toolbar dialog when pointer or focus leaves it and its
+ * trigger, and moves keyboard focus to its first enabled control on open.
+ */
+function useDismissibleComposerDialog(
+  open: boolean,
+  dialogRef: RefObject<HTMLElement | null>,
+  triggerRef: RefObject<HTMLElement | null>,
+  close: () => void,
+): void {
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const isDialogTarget = (target: EventTarget | null): boolean =>
+      target instanceof Node &&
+      (dialogRef.current?.contains(target) === true ||
+        triggerRef.current?.contains(target) === true);
+    const dismissOutside = (event: Event): void => {
+      if (!isDialogTarget(event.target)) {
+        close();
+      }
+    };
+    const frame = requestAnimationFrame(() => {
+      dialogRef.current
+        ?.querySelector<HTMLElement>("button:not(:disabled), input:not(:disabled)")
+        ?.focus();
+    });
+    document.addEventListener("pointerdown", dismissOutside);
+    document.addEventListener("focusin", dismissOutside);
+    return () => {
+      cancelAnimationFrame(frame);
+      document.removeEventListener("pointerdown", dismissOutside);
+      document.removeEventListener("focusin", dismissOutside);
+    };
+  }, [close, dialogRef, open, triggerRef]);
+}

src/renderer/src/MagicNotesWorkspace.test.tsx

@@ -1460,7 +1460,7 @@ describe('MagicNotesWorkspace detail behavior', () => {
     const { container } = render(<MagicNotesWorkspace onNotify={onNotify} />)
     await openNote()
     expect(container.querySelector('.magic-note-detail-header > :first-child')).toBe(screen.getByLabelText('笔记标题'))
-    expect(screen.getByRole('button', { name: '删除记录' })).toHaveClass('icon-button', 'magic-note-entry__delete-button')
+    expect(screen.getByRole('button', { name: '删除记录' })).toHaveClass('magic-note-entry__action-button', 'magic-note-entry__delete-button')
     fireEvent.click(screen.getByRole('button', { name: '编辑' }))
     expect(container.querySelector('.magic-note-entry__editor')).toBeVisible()
     expect(screen.getByRole('button', { name: '删除记录' })).toBeDisabled()

src/renderer/src/MagicNotesWorkspace.tsx

@@ -3091,7 +3091,7 @@ function MagicNotesWorkspaceView({
                             </button>
                           )}
                           <button
-                            className="icon-button"
+                            className="magic-note-entry__action-button"
                             aria-label={t(entry.content.version === 2 ? 'canvas.edit' : 'actions.edit')}
                             title={t(entry.content.version === 2 ? 'canvas.edit' : 'actions.edit')}
                             disabled={Boolean(busy) || editingEntry?.id === entry.id}
@@ -3104,12 +3104,13 @@ function MagicNotesWorkspaceView({
                               })
                             }
                           >
-                            <Pencil aria-hidden="true" size={15} />
+                            <Pencil aria-hidden="true" size={14} />
+                            <span>{t(entry.content.version === 2 ? 'canvas.edit' : 'actions.edit')}</span>
                           </button>
                           <button
                             aria-label={t('actions.deleteEntry')}
                             title={t('actions.deleteEntry')}
-                            className="icon-button magic-note-entry__delete-button"
+                            className="magic-note-entry__action-button magic-note-entry__delete-button"
                             disabled={Boolean(busy) || Boolean(editingEntry)}
                             type="button"
                             onClick={() => {
@@ -3119,7 +3120,8 @@ function MagicNotesWorkspaceView({
                               setDeletingEntryId(entry.id)
                             }}
                           >
-                            <Trash2 aria-hidden="true" size={15} />
+                            <Trash2 aria-hidden="true" size={14} />
+                            <span>{t('actions.deleteEntry')}</span>
                           </button>
                         </div>}
                       </header>

src/renderer/src/SettingsPanel.test.tsx

@@ -3035,7 +3035,7 @@ describe('SettingsPanel runtime files', () => {
       '自动选择 1 位专家'
     )
     expect(screen.getByText(/未显式选择专家或团队时/)).toHaveTextContent(
-      '子专家使用默认文本模型和已启用工具'
+      '专家提示词作为角色提示词，由当前会话的 Runtime 直接执行'
     )
 
     fireEvent.click(smartRouting)

src/renderer/src/SettingsPanel.tsx

@@ -2181,6 +2181,7 @@ function SettingsPanelView({
                   tabIndex={activeTab === category.id ? 0 : -1}
                   type="button"
                 >
+                  <category.icon aria-hidden="true" size={16} strokeWidth={1.8} />
                   <strong>
                     {t(`categories.${category.translationKey}.label`)}
                   </strong>

src/renderer/src/SupervisionReviewStages.tsx

@@ -24,6 +24,7 @@ export function SupervisionReviewStages({ row, stopping }: { row: SupervisionAct
     </ol>
     <p className="supervisor-activity__coverage">{t('activity.coverage', { batches: progress.batches, remaining: progress.remainingSources })}</p>
     {!!progress.omittedSources && <p className="supervisor-activity__note">{t('activity.omittedSources', { count: progress.omittedSources })}</p>}
+    {!!progress.skippedSources && <p className="supervisor-activity__note">{t('activity.skippedSources', { count: progress.skippedSources })}</p>}
     {!progress.complete && !progress.phase && <p className="supervisor-activity__note">{t('activity.stageUnknown')}</p>}
     {row.supervisionStatus === 'running' && !stopping && <p className="supervisor-activity__note">{t('reviewSettings.inFlight', { count: progress.inFlight ?? 0 })}</p>}
   </div>

src/renderer/src/SupervisorActivity.test.tsx

@@ -50,6 +50,19 @@ it.each(['zh-CN', 'en-US'] as const)('retains operational failure details and re
   expect(screen.getByRole('button', { name: copy.reviewSettings.resume })).toBeEnabled()
 })
 
+it('allows continuing a legacy source-change failure', async () => {
+  const copy = i18nResources['zh-CN'].heartbeat
+  const resume = vi.fn().mockResolvedValue(undefined)
+  vi.stubGlobal('goodbuddy', { supervision: { activity: vi.fn().mockResolvedValue([{
+    ...row, status: 'failed', supervisionStatus: 'failed',
+    error: 'Review source changed or was removed',
+    reviewProgress: { runId: 'saved-run', batches: 1, characters: 1000, sources: 2, remainingSources: 1, restartRequired: true, complete: false }
+  }]), resume } })
+  render(<SupervisorActivity active projects={[]} onOpenResult={vi.fn()} />)
+  fireEvent.click(await screen.findByRole('button', { name: copy.reviewSettings.resume }))
+  await waitFor(() => expect(resume).toHaveBeenCalledWith({ runId: 'saved-run' }))
+})
+
 it('shows durable progress, pauses and continues the same run, and expands retained facts', async () => {
   const progress = { runId: 'saved-run', batches: 1, characters: 1000, sources: 2, remainingSources: 1, complete: false }
   const activity = vi.fn().mockResolvedValue([{ ...row, reviewProgress: progress }])

src/renderer/src/SupervisorActivity.tsx

@@ -186,7 +186,7 @@ export function SupervisorActivity({ active, projects, onOpenResult, configId, c
                 <button type="button" className="secondary-button" disabled={!!pending || !!stoppingKind} onClick={() => void control(row, 'pause')}>{t('reviewSettings.pause')}</button>
                 <button type="button" className="danger-ghost" disabled={!!pending || !!stoppingKind} onClick={() => void control(row, 'cancel')}>{t('reviewSettings.cancel')}</button>
               </>}
-              {!stoppingKind && !row.reviewProgress.complete && !row.reviewProgress.restartRequired && (row.supervisionStatus === 'paused' || row.supervisionStatus === 'failed') && <button type="button" className="secondary-button" disabled={!!pending || execution.active} onClick={() => void control(row, 'resume')}>{t(row.reviewProgress.phase === 'summarizing' ? 'activity.resumeMerge' : row.reviewProgress.phase === 'saving' ? 'activity.resumeSave' : 'reviewSettings.resume')}</button>}
+              {!stoppingKind && !row.reviewProgress.complete && (row.supervisionStatus === 'paused' || row.supervisionStatus === 'failed') && <button type="button" className="secondary-button" disabled={!!pending || execution.active} onClick={() => void control(row, 'resume')}>{t(row.reviewProgress.phase === 'summarizing' ? 'activity.resumeMerge' : row.reviewProgress.phase === 'saving' ? 'activity.resumeSave' : 'reviewSettings.resume')}</button>}
               <button type="button" className="secondary-button" aria-expanded={expanded === row.id} aria-controls={`batches-${row.id}`} onClick={() => setExpanded(expanded === row.id ? undefined : row.id)}>{t('reviewSettings.facts')}</button>
             </div>
           </>}
@@ -229,6 +229,7 @@ export function SupervisorActivity({ active, projects, onOpenResult, configId, c
             </dl>
             {row.reviewProgress && <p>{t('reviewSettings.progress', { batches: row.reviewProgress.batches, characters: row.reviewProgress.characters, remaining: row.reviewProgress.remainingSources })}</p>}
             {!!row.reviewProgress?.omittedSources && <p>{t('activity.omittedSources', { count: row.reviewProgress.omittedSources })}</p>}
+            {!!row.reviewProgress?.skippedSources && <p>{t('activity.skippedSources', { count: row.reviewProgress.skippedSources })}</p>}
             {row.reviewProgress?.navigationNodes !== undefined && <p>{t('activity.navigationSaved', { count: row.reviewProgress.navigationNodes })}</p>}
             {row.summary && <p className="supervisor-activity__summary">{row.summary}</p>}
             {row.reviewProgress?.settings && <details><summary>{t('reviewSettings.configuration')}</summary>

src/renderer/src/SupervisorWorkspace.test.tsx

@@ -225,7 +225,7 @@ describe('SupervisorWorkspace', () => {
     vi.setSystemTime(now)
     fireEvent.click(screen.getByRole('button', { name: copy.newReview }))
     const picker = screen.getByLabelText(copy.period)
-    expect(within(picker).getAllByRole('option').map(option => (option as HTMLOptionElement).value)).toEqual(['1', '7', '30', 'custom', 'range'])
+    expect(within(picker).getAllByRole('option').map(option => (option as HTMLOptionElement).value)).toEqual(['1', '7', '30', 'all', 'custom', 'range'])
     expect(picker).toHaveValue('7')
     fireEvent.change(picker, { target: { value: 'custom' } })
     fireEvent.change(screen.getByRole('spinbutton', { name: copy.dayCount }), { target: { value: '45' } })
@@ -245,6 +245,29 @@ describe('SupervisorWorkspace', () => {
       timeRange: { from: new Date(now.getTime() - 46 * 86400_000).toISOString(), to: now.toISOString() } })
   })
 
+  it.each(['zh-CN', 'en-US'] as const)('reviews all time from the epoch through now and names it in the reanalysis dialog in %s', async locale => {
+    await changeUiLocale(locale)
+    const copy = i18nResources[locale].heartbeat.supervisor
+    const run = vi.fn().mockResolvedValue(undefined)
+    window.goodbuddy = { supervision: { overview: async () => [], run } } as never
+    render(<SupervisorWorkspace />)
+    await screen.findByText(copy.empty)
+    vi.useFakeTimers({ toFake: ['Date'] })
+    const now = new Date(2026, 9, 5, 15, 30)
+    vi.setSystemTime(now)
+    fireEvent.click(screen.getByRole('button', { name: copy.newReview }))
+    fireEvent.change(screen.getByLabelText(copy.period), { target: { value: 'all' } })
+    const timeRange = { from: new Date(0).toISOString(), to: now.toISOString() }
+    await act(async () => fireEvent.click(screen.getByRole('button', { name: copy.run })))
+    expect(run).toHaveBeenLastCalledWith({ trigger: 'manual', scope: { kind: 'global' }, timeRange })
+    fireEvent.click(screen.getByRole('button', { name: copy.more }))
+    fireEvent.click(screen.getByRole('menuitem', { name: copy.reanalyze }))
+    const dialog = screen.getByRole('alertdialog')
+    expect(dialog).toHaveTextContent(copy.allTimeLabel)
+    await act(async () => fireEvent.click(within(dialog).getByRole('button', { name: copy.reanalyzeConfirm })))
+    expect(run).toHaveBeenLastCalledWith({ trigger: 'manual', reanalyze: true, scope: { kind: 'global' }, timeRange })
+  })
+
   it.each([
     ['2025-11-02', '2025-11-02'],
     ['2026-03-08', '2026-03-08'],

src/renderer/src/SupervisorWorkspace.tsx

@@ -240,6 +240,8 @@ export function SupervisorWorkspace({
   const loading = overviewLoading || (tab === 'graph' && Boolean(resultId) && graphResultId !== resultId && !loadError)
 
   const resolvePeriod = (now: Date): { range?: SupervisionRunRequest['timeRange']; label?: string; error?: string } => {
+    // All time: from the epoch, which predates any stored source, through now.
+    if (period === 'all') return { range: { from: new Date(0).toISOString(), to: now.toISOString() }, label: t('supervisor.allTimeLabel') }
     if (period === 'range') {
       const from = new Date(`${startDate}T00:00:00`)
       const end = new Date(`${endDate}T00:00:00`)
@@ -651,6 +653,7 @@ export function SupervisorWorkspace({
                         {t('supervisor.days', { count: value })}
                       </option>
                     ))}
+                    <option value="all">{t('supervisor.allTime')}</option>
                     <option value="custom">{t('supervisor.customDays')}</option>
                     <option value="range">{t('supervisor.dateRange')}</option>
                   </select>

src/renderer/src/TerminalPanel.test.tsx

@@ -221,6 +221,18 @@ describe('TerminalPanel', () => {
     )
   })
 
+  it('contains IME composition layout inside the terminal', () => {
+    expect(terminalStylesheet).toMatch(
+      /\.terminal-panel__emulator\s*\{[^}]*contain:\s*size layout paint;[^}]*overflow-anchor:\s*none;/u
+    )
+    expect(terminalStylesheet).toMatch(
+      /\.terminal-panel__emulator \.xterm\s*\{[^}]*width:\s*100%;[^}]*max-width:\s*100%;[^}]*overflow:\s*hidden;/u
+    )
+    expect(terminalStylesheet).toMatch(
+      /\.terminal-panel__emulator \.xterm-helpers\s*\{[^}]*max-width:\s*0;[^}]*overflow:\s*visible;/u
+    )
+  })
+
   it('creates only after the first valid fitted size and forwards input', async () => {
     const backend = adapterHarness()
     const emulator = emulatorHarness()

src/renderer/src/WorkspacePrimitives.test.tsx

@@ -364,7 +364,7 @@ describe('WorkspacePrimitives', () => {
 
   it('wraps native client and compaction actions without overlapping composer metadata', () => {
     expect(stylesheet).toMatch(
-      /\.composer-wrap\s*\{[^}]*var\(--space-2\);[^}]*background:\s*var\(--surface-raised\);/u
+      /\.composer-wrap\s*\{[^}]*var\(--space-2\);[^}]*\}/u
     )
     expect(stylesheet).toMatch(
       /\.composer-meta\s*\{[^}]*position:\s*relative;[^}]*min-height:\s*26px;[^}]*margin:\s*var\(--space-1\) 0 0;/u

src/renderer/src/composer-menu-store.ts

@@ -1,8 +1,8 @@
 import { useCallback, useLayoutEffect, useSyncExternalStore } from "react";
 
 /**
- * Open/closed state of the composer's popups (options dialog, knowledge
- * scope, the pickers and the runtime menu). It lives outside App so opening a
+ * Open/closed state of the composer's popups (context dialog, runtime
+ * controls dialog, knowledge scope, the pickers and the runtime menu). It lives outside App so opening a
  * menu re-renders only the composer.
  *
  * The state belongs to one composer context (conversation, running state and
@@ -17,6 +17,7 @@ export type ComposerMenuId =
 
 export type ComposerMenuState = {
   readonly optionsOpen: boolean;
+  readonly runtimeOptionsOpen: boolean;
   readonly knowledgeScopeOpen: boolean;
   readonly menu: ComposerMenuId | undefined;
   readonly runtimeMenuOpen: boolean;
@@ -24,6 +25,7 @@ export type ComposerMenuState = {
 
 export const closedComposerMenus: ComposerMenuState = Object.freeze({
   optionsOpen: false,
+  runtimeOptionsOpen: false,
   knowledgeScopeOpen: false,
   menu: undefined,
   runtimeMenuOpen: false,
@@ -38,6 +40,7 @@ export type ComposerMenuStore = ReturnType<typeof createComposerMenuStore>;
 function sameMenus(left: ComposerMenuState, right: ComposerMenuState): boolean {
   return (
     left.optionsOpen === right.optionsOpen &&
+    left.runtimeOptionsOpen === right.runtimeOptionsOpen &&
     left.knowledgeScopeOpen === right.knowledgeScopeOpen &&
     left.menu === right.menu &&
     left.runtimeMenuOpen === right.runtimeMenuOpen
@@ -78,7 +81,7 @@ export function createComposerMenuStore() {
     },
     /** Closes the pickers and the runtime menu of whatever context is current. */
     closeMenus(): void {
-      store.update(key, { menu: undefined, runtimeMenuOpen: false });
+      store.update(key, { menu: undefined, runtimeMenuOpen: false, runtimeOptionsOpen: false });
     },
     closeRuntimeMenu(): void {
       store.update(key, { runtimeMenuOpen: false });

src/renderer/src/conversation-persistence.ts

@@ -41,6 +41,7 @@ export function toConversationMessage(message: Message): ConversationMessage {
     contextCompressions: message.contextCompressions,
     tools: message.tools,
     subagents: message.subagents,
+    expert: message.expert,
     sources: message.sources,
     sourceReferences: message.sourceReferences,
     knowledgeRetrieval: message.knowledgeRetrieval,
@@ -64,6 +65,7 @@ export function toLocalConversationHeader(
     knowledgeLibraryIds: conversation.knowledgeLibraryIds,
     knowledgeRetrievalMode: conversation.knowledgeRetrievalMode,
     storyGraphEnabled: conversation.storyGraphEnabled,
+    selectedExpertId: conversation.selectedExpertId,
     contextMetrics: conversation.contextMetrics,
     contextCompressionState: conversation.contextCompressionState,
     ...(conversation.branch ? { branch: conversation.branch } : {}),

src/renderer/src/conversation-selectors.ts

@@ -151,7 +151,7 @@ export function useConversationActivitySummary(
 export type ActiveConversationView = Pick<
   Conversation,
   | "id" | "title" | "projectId" | "runtimeSelection" | "knowledgeLibraryIds"
-  | "knowledgeRetrievalMode" | "remote" | "branch" | "contextMetrics" | "contextCompressionState"
+  | "knowledgeRetrievalMode" | "selectedExpertId" | "remote" | "branch" | "contextMetrics" | "contextCompressionState"
 > & {
   /** Untouched greeting-only conversation: shown with the default title. */
   unused: boolean;
@@ -188,6 +188,7 @@ export function selectActiveConversationView(
     runtimeSelection: conversation.runtimeSelection,
     knowledgeLibraryIds: conversation.knowledgeLibraryIds,
     knowledgeRetrievalMode: conversation.knowledgeRetrievalMode,
+    selectedExpertId: conversation.selectedExpertId,
     remote: conversation.remote,
     branch: conversation.branch,
     contextMetrics: conversation.contextMetrics,
@@ -214,6 +215,7 @@ export function sameActiveConversationView(
   return left.id === right.id && left.title === right.title &&
     left.projectId === right.projectId &&
     left.knowledgeRetrievalMode === right.knowledgeRetrievalMode &&
+    left.selectedExpertId === right.selectedExpertId &&
     left.unused === right.unused && left.historyLoaded === right.historyLoaded &&
     left.running === right.running && left.messageCount === right.messageCount &&
     sameArrayItems(left.knowledgeLibraryIds ?? [], right.knowledgeLibraryIds ?? []) &&

src/renderer/src/i18n/locales/en-US/app.ts

@@ -546,6 +546,7 @@ export const app = {
     removeAttachment: 'Remove {{name}}',
     settings: 'Conversation settings',
     storyGraph: { label: 'Use story graph' },
+    contextSources: 'Story graph and knowledge',
     options: 'Options',
     expertLabel: 'Expert role',
     runtimeControls: {

src/renderer/src/i18n/locales/en-US/heartbeat.ts

@@ -64,6 +64,7 @@ export const heartbeat = {
     stageUnknown: 'This historical run has no saved stage. Zero remaining sources does not mean the review was published.',
     coverage: '{{batches}} saved batches · {{remaining}} sources remaining',
     omittedSources: '{{count}} sources skipped because their conversations were deleted. Coverage includes only retained sources. If none remain, the review finishes without an empty report.',
+    skippedSources: '{{count}} sources changed during the review. They were skipped this time and will be handled in the next review.',
     navigationSaved: '{{count}} navigation merges saved',
     resumeMerge: 'Continue merging', resumeSave: 'Retry publication', runDetails: 'Run details and configuration',
     treePageHint: 'Expand projects and conversations to browse this page of saved batches. Tasks without a saved result are not listed here.',
@@ -122,6 +123,7 @@ export const heartbeat = {
     empty: 'No successful review yet', emptyHint: 'You can review current progress manually even without an heartbeat plan.', run: 'Review', running: 'Reviewing…',
     more: 'More review actions', reanalyze: 'Reanalyze…', reanalyzeTitle: 'Reanalyze this period?', reanalyzeConfirm: 'Reanalyze',
     reanalyzeHint: 'All content in {{scope}} for {{period}} will be analyzed again, which may use more model tokens. Confirmed content and heartbeat progress are not affected.', retryRun: 'Retry review', dismiss: 'Dismiss',
+    allTime: 'All time', allTimeLabel: 'all time',
     customDays: 'Custom days', dateRange: 'Date range', dayCount: 'Number of days', startDate: 'Start date', endDate: 'End date',
     recentDays: 'the last {{count}} days', dateRangeLabel: '{{from}} through {{to}} (local dates, through now if ending today)',
     customDaysHelp: 'Counts back from now in 24-hour days.', dateRangeHelp: 'Local dates, including the end day. If ending today, includes content through now.',

src/renderer/src/i18n/locales/en-US/settings.ts

@@ -867,7 +867,7 @@ export const settings = {
         'Automatically choose the expert role that best matches the question',
       enabled: 'Enable Smart Subagent routing',
       help:
-        'Off by default. When no expert or team is explicitly selected, GoodBuddy chooses one expert. The Subagent uses the default text model and enabled tools.'
+        'Off by default. When no expert or team is explicitly selected, GoodBuddy chooses one expert. Its prompt is applied as a role prompt on the conversation\'s current Runtime.'
     }
   },
   appearance: {

src/renderer/src/i18n/locales/zh-CN/app.ts

@@ -528,6 +528,7 @@ export const app = {
     removeAttachment: '移除 {{name}}',
     settings: '对话设置',
     storyGraph: { label: '使用故事图谱' },
+    contextSources: '故事图谱与知识库',
     options: '选项',
     expertLabel: '专家角色',
     runtimeControls: {

src/renderer/src/i18n/locales/zh-CN/heartbeat.ts

@@ -61,6 +61,7 @@ export const heartbeat = {
     stageUnknown: '此历史运行未保存阶段信息。剩余来源为零不代表回顾已发布。',
     coverage: '已保存 {{batches}} 批 · 剩余 {{remaining}} 个来源',
     omittedSources: '会话已删除，已跳过 {{count}} 个来源；覆盖统计仅包含保留的来源。没有剩余来源时结束回顾，不生成空报告。',
+    skippedSources: '回顾期间有 {{count}} 个来源发生变化，本次已跳过，将在下次回顾中处理。',
     navigationSaved: '已保存 {{count}} 次导航合并',
     resumeMerge: '继续合并摘要', resumeSave: '重试发布', runDetails: '运行详情与配置',
     treePageHint: '按项目、会话展开本页已保存批次。这里不包含尚未保存结果的任务。',
@@ -119,6 +120,7 @@ export const heartbeat = {
     empty: '还没有成功回顾', emptyHint: '即使没有心跳计划，也可以手动回顾当前进展。', run: '回顾', running: '回顾整理中…',
     more: '更多回顾操作', reanalyze: '重新整理…', reanalyzeTitle: '重新整理这段时间？', reanalyzeConfirm: '重新整理',
     reanalyzeHint: '将重新分析{{scope}}在{{period}}内的全部内容，可能产生较多模型用量。已确认的内容和心跳处理进度不受影响。', retryRun: '重试回顾', dismiss: '关闭提示',
+    allTime: '全部', allTimeLabel: '全部时间',
     customDays: '自定义天数', dateRange: '指定日期', dayCount: '天数', startDate: '开始日期', endDate: '结束日期',
     recentDays: '最近 {{count}} 天', dateRangeLabel: '{{from}} 至 {{to}}（本地日期，结束日期为今天时截至当前）',
     customDaysHelp: '从当前时刻向前计算，每天按 24 小时计。', dateRangeHelp: '按本地日期计算，包含结束日期当天；结束日期为今天时截至当前时刻。',

src/renderer/src/i18n/locales/zh-CN/settings.ts

@@ -802,7 +802,7 @@ export const settings = {
       description: '按问题内容自动选择最匹配的专家角色',
       enabled: '启用 Subagent 智能路由',
       help:
-        '默认关闭。未显式选择专家或团队时，自动选择 1 位专家；子专家使用默认文本模型和已启用工具。'
+        '默认关闭。未显式选择专家或团队时，自动选择 1 位专家；专家提示词作为角色提示词，由当前会话的 Runtime 直接执行。'
     }
   },
   appearance: {

src/renderer/src/settings-categories.test.ts

@@ -2,6 +2,12 @@ import { describe, expect, it } from 'vitest'
 import { getSettingsCategoryList } from './settings-categories'
 
 describe('getSettingsCategoryList', () => {
+  it('defines an icon for every settings category', () => {
+    expect(
+      getSettingsCategoryList(true).every(({ icon }) => icon != null)
+    ).toBe(true)
+  })
+
   it('hides SSH hosts while Remote Projects is disabled', () => {
     expect(
       getSettingsCategoryList(false).map(({ id }) => id)

src/renderer/src/settings-categories.ts

@@ -1,60 +1,84 @@
 import i18n from './i18n'
+import {
+  Bot,
+  FileText,
+  Gauge,
+  Info,
+  Palette,
+  Radio,
+  Server,
+  SlidersHorizontal,
+  Terminal,
+  Users,
+  Wrench
+} from 'lucide-react'
 
 export const settingsCategoryList = [
   {
     id: 'appearance',
     group: 'general',
-    translationKey: 'appearance'
+    translationKey: 'appearance',
+    icon: Palette
   },
   {
     id: 'platform-features',
     group: 'general',
-    translationKey: 'platformFeatures'
+    translationKey: 'platformFeatures',
+    icon: SlidersHorizontal
   },
   {
     id: 'model',
     group: 'execution',
-    translationKey: 'model'
+    translationKey: 'model',
+    icon: Bot
   },
   {
     id: 'context-control',
     group: 'execution',
-    translationKey: 'contextControl'
+    translationKey: 'contextControl',
+    icon: Gauge
   },
   {
     id: 'runtime',
     group: 'execution',
-    translationKey: 'runtime'
+    translationKey: 'runtime',
+    icon: Terminal
   },
   {
     id: 'ssh-hosts',
     group: 'execution',
-    translationKey: 'sshHosts'
+    translationKey: 'sshHosts',
+    icon: Server
   },
   {
     id: 'document-parsing',
     group: 'extensions',
-    translationKey: 'documentParsing'
+    translationKey: 'documentParsing',
+    icon: FileText
   },
   {
     id: 'channels',
     group: 'extensions',
-    translationKey: 'channels'
+    translationKey: 'channels',
+    icon: Radio
   },
   {
     id: 'roles',
     group: 'extensions',
-    translationKey: 'roles'
+    translationKey: 'roles',
+    icon: Users
   },
   {
     id: 'capabilities',
     group: 'extensions',
-    translationKey: 'capabilities'
+    translationKey: 'capabilities',
+    icon: Wrench
   },
   {
     id: 'about',
     group: 'system',
-    translationKey: 'about'
+    translationKey: 'about',
+    icon: Info
   }
 ] as const
 

src/renderer/src/styles.css

@@ -2433,7 +2433,8 @@
   position: absolute;
   top: var(--space-2);
   right: var(--space-2);
-  opacity: 1;
+  opacity: 0;
+  transition: opacity var(--motion-fast) ease-out;
 }
 
 .magic-note-row:hover .magic-note-more,
@@ -2721,9 +2722,18 @@
   line-height: 1;
 }
 
+.magic-note-entry {
+  position: relative;
+}
+
+/* Floats over the top-right corner so the actions never take their own row. */
 .magic-note-entry__actions {
   display: flex;
-  gap: 2px;
+  position: absolute;
+  z-index: 1;
+  top: var(--space-1);
+  right: var(--space-2);
+  gap: var(--space-1);
 }
 
 .magic-note-entry__actions .icon-button {
@@ -2731,7 +2741,36 @@
   height: 28px;
 }
 
-.magic-note-entry__actions .magic-note-entry__delete-button:hover:not(:disabled) {
+.magic-note-entry__action-button {
+  height: 28px;
+  padding: 0 var(--space-2);
+  border: 0;
+  border-radius: var(--radius-control);
+  background: transparent;
+  color: var(--text-secondary);
+  font: inherit;
+  font-size: var(--font-caption);
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.magic-note-entry__action-button:hover:not(:disabled),
+.magic-note-entry__action-button:focus-visible {
+  background: var(--surface-subtle);
+  color: var(--text-primary);
+}
+
+.magic-note-entry__action-button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.magic-note-entry__actions .magic-note-entry__delete-button {
+  color: var(--danger-strong);
+}
+
+.magic-note-entry__actions .magic-note-entry__delete-button:hover:not(:disabled),
+.magic-note-entry__actions .magic-note-entry__delete-button:focus-visible {
   background: var(--danger-subtle);
   color: var(--danger-strong);
 }
@@ -6483,7 +6522,7 @@ button > svg {
 .chat-scroll-to-bottom {
   position: absolute;
   z-index: 2;
-  bottom: var(--space-3);
+  bottom: var(--space-6);
   left: 50%;
   display: grid;
   width: 40px;
@@ -6695,6 +6734,23 @@ button > svg {
   gap: 12px;
 }
 
+.message__header--with-role {
+  flex-direction: column;
+  align-items: flex-start;
+  justify-content: center;
+  gap: 0;
+}
+
+.message__role {
+  max-width: 100%;
+  overflow: hidden;
+  color: var(--text-muted);
+  font-size: var(--font-caption);
+  line-height: 1.3;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .message--user .message__header {
   width: min(78%, 720px);
   align-self: flex-end;
@@ -7890,24 +7946,54 @@ button > svg {
 }
 
 .composer-wrap {
+  --composer-fade-color: var(--surface-raised);
   position: relative;
+  z-index: 1;
   width: 100%;
   max-width: 100%;
   min-width: 0;
+  /* Overlap the message region by the top padding so messages run under the
+     fade right up to the composer outline instead of stopping at a solid band. */
+  margin-top: calc(-1 * var(--space-3));
   padding:
     var(--space-3)
     var(--chat-inline-padding)
     var(--space-2);
-  background: var(--surface-raised);
+  pointer-events: none;
+}
+
+.composer-wrap > * {
+  pointer-events: auto;
 }
 
 .composer-wrap::before {
   position: absolute;
   right: 0;
-  bottom: 100%;
+  bottom: calc(100% - var(--space-3));
   left: 0;
+  z-index: -1;
   height: var(--space-4);
-  background: linear-gradient(to bottom, transparent, var(--surface-raised));
+  background: linear-gradient(
+    to bottom,
+    transparent,
+    color-mix(in srgb, var(--composer-fade-color) 55%, transparent) 35%,
+    color-mix(in srgb, var(--composer-fade-color) 90%, transparent) 70%,
+    var(--composer-fade-color)
+  );
+  content: "";
+  pointer-events: none;
+}
+
+/* Below the composer the wrap stays opaque so nothing shows through its
+   bottom padding and metadata row. */
+.composer-wrap::after {
+  position: absolute;
+  top: var(--space-3);
+  right: 0;
+  bottom: 0;
+  left: 0;
+  z-index: -1;
+  background: var(--composer-fade-color);
   content: "";
   pointer-events: none;
 }
@@ -8383,7 +8469,7 @@ button > svg {
 .composer:focus-within {
   border-color: var(--accent);
   box-shadow:
-    0 0 0 2px color-mix(in srgb, var(--accent) 18%, transparent),
+    0 0 0 1px color-mix(in srgb, var(--accent) 14%, transparent),
     var(--shadow-card);
 }
 
@@ -8401,7 +8487,7 @@ button > svg {
 .composer__input textarea {
   display: block;
   width: 100%;
-  min-height: 72px;
+  min-height: 56px;
   max-height: 220px;
   padding: 0;
   border: 0;
@@ -8511,6 +8597,42 @@ button > svg {
   color: var(--accent);
 }
 
+/* Story graph and knowledge rows share one row style in the context dialog. */
+.composer__options .composer__context-row {
+  min-height: 36px;
+  padding: 0 var(--space-2);
+  border-radius: var(--radius-control);
+  color: var(--text-primary);
+  font-size: var(--font-body);
+  font-weight: 400;
+  gap: var(--space-2);
+}
+
+.composer__options .composer__context-row:hover:not(:has(input:disabled)) {
+  background: var(--accent-subtle);
+}
+
+.composer__options .composer__story-graph-label,
+.composer__options .knowledge-scope > button > span {
+  gap: var(--space-2);
+  color: inherit;
+  font-size: var(--font-body);
+  font-weight: 400;
+}
+
+.composer__options .knowledge-scope > button {
+  color: var(--text-primary);
+}
+
+.composer__options .knowledge-scope > button > span {
+  flex: 1;
+  justify-content: space-between;
+}
+
+.composer__options .knowledge-scope__chevron {
+  margin-left: 0;
+}
+
 .composer__options .composer__runtime-toolbar-label {
   padding: var(--space-1) var(--space-2);
   font-weight: 500;
@@ -8637,14 +8759,66 @@ button > svg {
 }
 
 .composer__configuration {
+  position: relative;
   min-width: 0;
   flex-wrap: wrap;
 }
 
+.composer__options--runtime {
+  right: 0;
+  left: auto;
+}
+
+.composer__options .model-button__label {
+  text-align: left;
+}
+
+/* The runtime controls are alone in their dialog: no section divider. */
+.composer__options--runtime .composer__runtime-toolbar {
+  padding-top: 0;
+  border-top: 0;
+}
+
 .composer-picker--expert > .model-button {
   width: 148px;
 }
 
+/* Role chip in the top-left corner of the input area. */
+.composer__input-header {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  margin: calc(var(--space-2) * -1) 0 var(--space-2) calc(var(--space-2) * -1);
+}
+
+.composer-picker--chip > .model-button {
+  width: auto;
+  max-width: 220px;
+  height: 24px;
+  padding: 0 var(--space-2);
+  border-color: transparent;
+  border-radius: 999px;
+  background: var(--surface-subtle);
+  color: var(--text-secondary);
+  font-size: var(--font-caption);
+  font-weight: 500;
+}
+
+.composer-picker--chip > .model-button[aria-expanded="true"] {
+  border-color: var(--accent-selected);
+  background: var(--accent-subtle);
+  color: var(--accent);
+}
+
+.composer-picker--chip > .model-button:disabled {
+  border-color: transparent;
+  background: transparent;
+}
+
+.composer-picker--chip .model-button__label {
+  flex: 0 1 auto;
+}
+
 
 .composer-picker--runtime > .model-button,
 .composer-picker--runtime-action > .model-button {
@@ -9309,6 +9483,10 @@ button > svg {
   font-weight: 500;
 }
 
+.settings-tabs button > svg {
+  flex: 0 0 auto;
+}
+
 .settings-tabs button:hover {
   background: var(--surface-muted);
   color: var(--text-primary);
@@ -9628,8 +9806,10 @@ button > svg {
   min-height: 40px;
   padding: var(--space-2) var(--space-3);
   align-items: flex-start;
-  justify-content: center;
+  justify-content: flex-start;
   text-align: left;
+  flex-direction: row;
+  gap: var(--space-2);
 }
 
 .settings-page .settings-tabs button strong,
@@ -17655,12 +17835,15 @@ textarea.field-control {
   .settings-page,
   .workspace,
   .chat,
-  .composer-wrap,
   .workspace-panel-scroll
 ) {
   background: var(--surface-canvas);
 }
 
+:root[data-theme='dark'] .composer-wrap {
+  --composer-fade-color: var(--surface-canvas);
+}
+
 :root[data-theme='dark'] :where(
   .sidebar,
   .topbar,

src/renderer/src/terminal-panel.css

@@ -116,11 +116,24 @@
   flex: 1;
   padding: 0;
   overflow: hidden;
+  contain: size layout paint;
+  overflow-anchor: none;
   background: var(--surface-canvas);
 }
 
 .terminal-panel__emulator .xterm {
+  position: relative;
+  width: 100%;
+  min-width: 0;
+  max-width: 100%;
   height: 100%;
+  overflow: hidden;
+}
+
+/* IME composition must stay inside the terminal's own scroll boundary. */
+.terminal-panel__emulator .xterm-helpers {
+  max-width: 0;
+  overflow: visible;
 }
 
 .terminal-panel__status {

src/shared/assistant-contracts.ts

@@ -519,6 +519,21 @@ export type ConversationAnsweredQuestion = z.infer<
   typeof conversationAnsweredQuestionSchema
 >
 
+export const conversationMessageExpertSchema = z.union([
+  z
+    .object({
+      kind: z.literal('expert'),
+      id: assistantIdSchema,
+      name: z.string().trim().min(1).max(80)
+    })
+    .strict(),
+  z.object({ kind: z.literal('team') }).strict()
+])
+
+export type ConversationMessageExpert = z.infer<
+  typeof conversationMessageExpertSchema
+>
+
 export const conversationMessageSchema = z
   .object({
     id: assistantIdSchema,
@@ -541,6 +556,11 @@ export const conversationMessageSchema = z
       .optional(),
     tools: z.array(conversationToolActivitySchema).optional(),
     subagents: z.array(conversationSubagentActivitySchema).optional(),
+    /**
+     * Snapshot of the role selected when the reply was requested, so later
+     * renames or deletions do not rewrite history.
+     */
+    expert: conversationMessageExpertSchema.optional(),
     sources: z.array(z.string().max(8_192)).max(100).optional(),
     sourceReferences: z
       .array(
@@ -720,6 +740,8 @@ export const conversationSnapshotSchema = z
     knowledgeLibraryIds: z.array(assistantIdSchema).max(20).optional(),
     knowledgeRetrievalMode: z.enum(['auto', 'always']).optional(),
     storyGraphEnabled: z.boolean().optional(),
+    /** Role picked in the composer for this conversation; absent means the general assistant. */
+    selectedExpertId: z.union([assistantIdSchema, z.literal('team')]).optional(),
     contextMetrics: conversationContextMetricsSchema.optional(),
     contextCompressionState:
       conversationContextCompressionStateSchema.optional(),

src/shared/supervision-review-contracts.ts

@@ -39,6 +39,8 @@ export type SupervisionReviewProgress = {
   remainingSources: number
   /** Sources excluded because their owning conversation was deleted; not reviewed coverage. */
   omittedSources?: number
+  /** Frozen sources that changed or disappeared during the run; skipped and left for the next review. */
+  skippedSources?: number
   complete: boolean
   restartRequired?: boolean
   inFlight?: number

tests/support/story-graph-switch-main.ts

@@ -66,12 +66,15 @@ app.whenReady().then(async () => {
     const point = await js<{ x: number; y: number }>(`(() => { const r = document.querySelector('.composer__options-trigger').getBoundingClientRect(); return { x: Math.round(r.x+r.width/2), y: Math.round(r.y+r.height/2) }; })()`)
     win.webContents.sendInputEvent({ type: 'mouseDown', ...point, button: 'left', clickCount: 1 })
     win.webContents.sendInputEvent({ type: 'mouseUp', ...point, button: 'left', clickCount: 1 })
-    // First focus stays on the first menu button, matching the model picker.
-    await wait('document.activeElement === document.querySelector(".composer__options button:not(:disabled)")')
+    // Focus the first enabled context control, which is the story-graph
+    // switch when no knowledge libraries are available.
+    await wait('document.activeElement === document.querySelector(".composer__options button:not(:disabled), .composer__options input:not(:disabled)")')
   }
   const scenarios: object[] = []
   try {
     await win.loadURL(process.env.GB_MCP_URL!)
+    await js('window.goodbuddy.updates.updateSettings({heartbeatEnabled:true})')
+    await wait('document.body.innerText.includes("Supervisor") || document.body.innerText.includes("监督")')
     await open()
     assert.equal(await binding.available(), true)
     for (const width of [1280, 390]) for (const theme of ['light', 'dark']) {

tests/support/unified-execution-main.ts

@@ -75,6 +75,7 @@ app.whenReady().then(async () => {
   }
   try {
     await win.loadURL(process.env.GB_MCP_URL!)
+    await js('window.goodbuddy.updates.updateSettings({heartbeatEnabled:true})')
     await wait('!!document.querySelector(".composer textarea") && document.body.innerText.includes("Keep until confirmed")')
     await assertNoMode('.composer')
     await click('.composer__options-trigger')