4. 数据浏览器（侧边栏）
侧边栏是你浏览和管理数据的主要入口，由多个可展开／收合的区块（手风琴）组成。内容较长时，侧边栏主区域可垂直卷动；卷动时卷轴会短暂显示，平时尽量不干扰阅读。
4.1 浏览与搜寻数据文件
侧边栏底部有搜寻框。输入后会稍作停顿（约 0.5 秒）再套用过滤，避免每打一个字就重算；停顿期间输入框旁会出现小加载图标。清空搜寻会立即还原列表。
过滤范围包含：本地数据文件、快取表、外部连接 schema（已连接者会在背景加载 schema 以便用关键字搜表名）、以及 MCP Sources 内的来源与物化表。搜寻状态下，摘要列与标题上的数字皆与目前稳定后的搜寻字一致。
Data 区块标题旁括号内的数字为加总：本地表数（Excel 依工作表数；未知工作表数时先计 1）+ 快取表数 + 目前加载的外部表数（仅统计已成功加载 schema 的连接）。在输入搜寻后，外部连接可能尚在加载 schema，数字可能先较少、加载完成后再增加——属正常现象，不代表数据遗失。
主手风琴区块由上而下为：
- Workspace — 管理工作区与已保存的 SQL 持久标签页（侧栏仅列出 persist SQL tab，不含 markdown 快取 tab；见 §5.6）。
- Projects — 管理项目与 Plan / Report Markdown 文件，并可设置显示别名（§11.2）或将文件封存至 Archived docs 区以保持列表简洁（§11.3）。
- Data — 依序包含：Cached 一级节点（快取表列于其下；见第 7 章）、本地文件夹文件树、以及外部连接 schema 树。标题列右侧：Connections 胶囊（已连接数）、Refresh（一次重新扫描本地文件、刷新快取列表、并对已加载的连接重新抓取 schema）。
- 提示： 收合 Data 区不会清掉已加载的外部数据表。若连接中断（未处于连接成功状态），侧边栏可能暂时看不到该连接底下的表；连回后可再展开，或按 Data 标题列的 Refresh（仅会对已加载过且仍连接成功的外部连接重抓结构）。
- MCP Sources — 管理 MCP 来源与物化表（详见 §4.6）。
各区块的展开／收合状态会依工作区分别记住；Data 子列表的排序偏好亦会依工作区（以及本地文件夹路径、各外部连接 alias）分别保存。切换工作区时，侧边栏版面（含各区收合、宽度与列表排序）可各自不同。
快取表与本地文件的重新整理可由 Data 标题列的 Refresh 一次完成；MCP Sources 区块仍有独立的重新整理按钮。
列表排序（Data 子列表）：
在下列父列或连接列上右键 → Sort by…，可调整其下清单的显示顺序。此排序仅影响侧边栏显示，不改变 DuckDB 表名、show_tables 或查询解析；与第 6 章「结果表格排序」无关。
| 右键目标 | 选单 | 默认 | 备注 |
|---|---|---|---|
| 本地文件夹列（文件夹名称） | File name（升序／降序）或 Modified time（最新／最旧优先） | 档名升序 | 依文件相对路径（含子目录）排序；修改时间须先按 Data 标题列 Refresh（↻）后才准确 |
| Cached (n) 父列 | Name 或 Modified time（同上四种） | 修改时间最新优先 | 父列另可 Clear Agent Cache／Clear All Cache（见 §7.4） |
外部连接 alias 列（例如 pg_warehouse） |
Name（升序／降序） | 名称升序 | 仅重排该连接下各 schema 组内的数据表；schema 标题顺序不变，亦不影响其他连接 |
侧边栏搜寻过滤后，结果仍依你选的排序显示。Excel 工作表子列表维持依工作表名称排列，不受文件层排序影响。
[图片] 侧边栏展开状态，显示 Workspace、Projects、Data（含外部连接与 Cached）、MCP Sources 等各区块
4.2 Excel 工作表展开与选择
Excel 文件（.xls / .xlsx）在侧边栏中会以可展开的方式呈现：
- 点击 Excel 文件旁的展开箭头。
- 系统会自动加载该活页簿中所有工作表的名称。
- 你可以点击或双击特定工作表名称，将它插入到编辑器中。
注意： 查询 Excel 文件时，必须指定工作表。例如：
SELECT * FROM "report.xlsx"."Sheet1" LIMIT 10
4.3 快速插入表名到编辑器
- 双击侧边栏中的文件名称或快取表名称，即可自动在编辑器的游标位置插入对应的表名（已自动加上双引号）。
4.4 右键选单：SELECT 前 100 笔
在单一数据文件、快取表或 Excel 工作表上按右键，选择「SELECT 100 rows」，系统会自动侦测该文件的字段结构，并在编辑器中插入一条包含所有字段名称的 SELECT ... LIMIT 100 查询语句。
若要调整整份列表的显示顺序，请在本地文件夹列、Cached 父列或外部连接 alias 列上使用 Sort by…（见 §4.1「列表排序」）。
[图片] 侧边栏展开状态，显示 Workspace、Projects、Data（含 Cached 与外部连接）、MCP Sources 等各区块
[图片] 数据文件的右键选单
4.5 外部数据库连接（Connections）
Data 区段标题列右侧有 Connections 按钮，可管理外部数据库连接。
支持类型：
- PostgreSQL
- MySQL
- SQLite
建立连接：
- 点击 Data 区段的 Connections。
- 在弹窗中选择数据库类型，填入连接信息与 alias。窗口内容较多时会出现卷轴，可于固定高度内卷动浏览。
- 先点 Test Connection 验证连接，再点 Connect 挂载。
连接状态与限制：
- 已连接数量会显示在按钮上（例如
Connections (1)）。 - 若任何连接为错误状态，按钮会显示黄色警示。
- Trial 角色最多同时 1 条 active 连接；超过时会收到
402升级提示（讯息为英文）。新安装的桌面版在未启用正式授权前，Header 通常显示 Trial，故第二条连接会触发此限制。
移除或重新连接若发生错误，系统会以 Toast 通知显示讯息（错误内容可能为英文）。远端中断连接等操作若耗时较长，请耐心等候完成。
外部表浏览与插入 SQL：
- 连接成功后，Data 区段会出现外部 schema 树（
alias -> schema -> table）。 - 双击表名可插入引用。
- 在连接 alias 列右键可用 Sort by… → Name 调整该连接下各 schema 组内数据表顺序（见 §4.1「列表排序」）。
- 在单一数据表列右键可用「SELECT 100 rows」快速产生预览 SQL。
引用格式：
-- PostgreSQL
SELECT * FROM pg_db.public.orders LIMIT 10;
-- MySQL / SQLite
SELECT * FROM my_db.orders LIMIT 10;
跨源 JOIN 示例：
SELECT o.order_id, l.name
FROM sdb.main.orders o
JOIN "local.csv" l ON o.customer_id = l.customer_id;
4.6 MCP Sources（物化数据源）
MCP Sources 区段用于管理 MCP 来源与已物化表（区块位置与操作请参考 §4.1）。来源卡片与侧边栏 alias 都提供 Edit／Connect 或 Disconnect／Remove。
内建 Agent 与处于 Execute／Admin 的外部 Agent 可使用同一套 MCP Source 控制。凭证绝不会再次显示；新建、替换或清除凭证，以及 Remove 都需要确认。
管理来源：
- 点击 MCP Sources 标题列右侧的 齿轮 或 ＋，打开管理对话框。
- 左侧 Add MCP Source 可设置：
transport=stdio：填入启动命令（如npx ...）。transport=http：填入 URL、可选 Token 与 Headers JSON。
- 点击 Test 先测试连接；结果会显示在独立结果弹窗（可复制 JSON）。
- 点击 Add 仅加入来源设置，默认状态为
disconnected。 - 右侧来源卡片可用：
- Edit：alias 不可改；command、token、headers 不会回显，请明确选择保留、替换或清除。
- Connect／Disconnect：HTTP Connect 会先验证 endpoint。
- Remove：选择 Keep data 只移除设置，或 Clear data 连物化表一并删除。
编辑后 Save 会回到 disconnected，请再 Connect。
从其他工作区导入： 在 Existing Sources 标题列选择 Import from other workspaces。选择来源工作区、加入要导入的来源、可调整 alias 后 Confirm。只会复制来源设置，不会复制物化资料、下载快取或秘密；导入后的来源为 disconnected。
状态说明：
connected：连接可用disconnected：已设置但尚未连接error：最近一次重连/测试失败（可从卡片讯息查看错误）unbound（仅侧边栏）：来源设置已移除但物化表仍在；再次 Remove 才会删除这些表
重启 App 或回到工作区时，先前已连接的来源各会自动尝试重连一次；使用者主动 Disconnect 的来源不会自动重连。disconnected／error 时，侧边栏来源名称旁会显示黄色警示图标。
侧边栏控制：
- 在 MCP 来源列（alias 父行，非底下的物化表列）上按右键，可选择 Edit、Connect／Disconnect 或 Remove；unbound 列只有 Remove。
- 成功或失败都会显示 Toast；操作进行中会暂时停用重复操作。
Start in Chat 引导：
- 当来源尚未有物化表时，可点 Start in Chat。
- 选择 Scan Source 时，系统会自动打开 AI 面板、建立新对话并填入探索提示。
- 选择 Skip 时，不会填入任何提示。
物化表使用方式：
- Agent 拉取完成后，表会出现在 MCP Sources 区段。
- SQL 可直接引用
mcp_alias__table（系统会在执行期映射到对应 Parquet 文件）。 - 在物化表列上按右键，可进行
SELECT 100 rows、Agent Refresh、View details、Delete。 - Agent Refresh 会提供脱敏的 refresh contract。Agent 必须取得本轮新的 write ID，再使用
mcp_pull_table；不会重用旧 task、URL 或结果 handle。外部 Agent mode 下 Agent Refresh 会改为复制 handoff，Add to chat 则改为 Copy table name。