docs: expand VitePress user guide

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 不作为工作栏中的独立面板。