資料瀏覽器（側邊欄）

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 章）、初始文件夹文件树、以及经 Connections 挂载且目前可查询的来源（数据库 schema 树、connected 的外部 DB；Additional folder 为 available；Cloud folder 为 available 或 degraded）。Disconnect 后的来源仅在 Connections 对话框可见，不会出现在 Data 树中。标题列右侧：Connections 胶囊（Link2 数字 = 所有已连线／已挂载来源：外部 DB connected + folder available + cloud available／degraded，不含 MCP 与 offline 绑定）、Refresh（一次重新扫描本地文件与额外文件夹、刷新快取列表、并对已载入的连线重新抓取 schema）。v1 不会自动监听文件系统变更，新增文件后请按 Refresh。
• 提示： 收合 Data 区不会清掉已载入的外部数据表。若外部 DB 未连线（disconnected／error 等），侧边栏不显示该 alias 的 schema 树；请到 Connections 对该来源按 Connect（或 Edit 修正设定后 Save），再视需要按 Data → Refresh 重抓 schema。
• MCP Sources — 管理 MCP 来源与物化表（详见 §4.6）。

各区块的展开／收合状态会依工作区分别记住；Data 子列表的排序偏好亦会依工作区（以及本地文件夹路径、各外部连线 alias）分别保存。切换工作区时，侧边栏版面（含各区收合、宽度与列表排序）可各自不同。

快取表与本地文件的重新整理可由 Data 标题列的 Refresh 一次完成；MCP Sources 区块仍有独立的重新整理按钮。

列表排序（Data 子列表）：

在下列父列或连线列上右键 → Sort by…，可调整其下清单的显示顺序。此排序仅影响侧边栏显示，不改变 DuckDB 表名、show_tables 或查询解析；与第 6 章「结果表格排序」无关。

侧边栏搜寻过滤后，结果仍依你选的排序显示。Excel 工作表子列表维持依工作表名称排列，不受文件层排序影响。

[图片] 侧边栏展开状态，显示 Workspace、Projects、Data（含外部连线与 Cached）、MCP Sources 等各区块

本机来源改名、搬移与重新定位

工作区开启时会在背景检查本机根目录；Data → Refresh 会一并检查来源位置，相关查询与直接 Workspace 汇出也会按需检查。没有持续监看文件系统，文件变更后请重新整理。

• 原位置仍可读时，使用该位置的目前版本；同路径替换不代表内容与上次相同。
• 原生追踪可用时，可尝试恢复本机同 volume 改名或搬移的根目录与已登记文件；仍须符合原来源范围。不能可靠判定时，保留失联状态，不以同名档猜测或搜寻整颗磁碟。
• Data 下的状态提示提供 Locate folder／Locate file。单档必须仍位于原来源文件夹内；若要改到另一根目录，先重新绑定文件夹。可读但无法追踪时仍可正常查询。
• View source reference changes 可查看 SQL 引用更新前后；Restore as unsaved edit 可把旧内容还原为待储存编辑。干净分页可同步新引用；未储存或并行修改会保留并提示，请处理后再 Run。
• 长路径、跨磁碟、外接碟、NAS 与云端同步位置不保证自动恢复；可重试或手动定位。来源对应不证明文件内容未变，也不取代备份。

4.2 Excel 工作表展开与选择

Excel 文件（.xls / .xlsx）在侧边栏中会以可展开的方式呈现：

1. 点击 Excel 文件旁的展开箭头。
2. 系统会自动载入该活页簿中所有工作表的名称。
3. 你可以点击或双击特定工作表名称，将它插入到编辑器中。

注意： 查询 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 按钮，可管理本工作区的数据源：常见数据库、额外本机文件夹、Cloud folder 与 SQL Server／Azure SQL。初始文件夹仍由 Data 区本机文件夹列管理（见 §2.2、§3.2），不经此对话框建立。

Source Type：

完整开放： 所有数据来源可建立、测试、连线与重连，外部数据库没有产品设定的同时连线数上限；Header 不显示方案或升级入口。

建立数据源：

1. 点击 Data 区段的 Connections。
2. 选择 Source Type 与唯一的 Alias（与初始文件夹语意、其他连线、MCP alias 不得冲突）。视窗内容较多时会出现卷轴。
3. 依类型填写：数据库连线资讯、Additional folder 的 Browse 路径、Cloud folder 的 provider／bucket／prefix／credential，或 SQL Server／Azure SQL 的 Server／Database／帐密等。
4. 数据库类型：先 Test Connection，再 Connect。Additional folder：确认路径后挂载即可。Cloud folder：可先 Test connection，再 Add Cloud Folder（Add 时也会 list／验证）。

Additional folder：

• 工作区须先绑定初始文件夹，才能新增 Additional folder（空工作区请先完成 §2.2 或 §3.2）。
• 支援与初始文件夹相同的常见格式（CSV／TSV／TXT／Parquet／JSON／JSONL／Excel .xlsx 等）。
• 引用："alias"."file.csv"；子路径："alias"."subdir/orders.csv"；Excel："alias"."book.xlsx"."Sheet1"。
• 文件不会被搬移或删除；新增档后请按 Data → Refresh（无自动 filesystem watcher）。
• 侧边栏 Additional folder alias 列右键可 Edit、Connect、Disconnect（英文选单）；Connect 会重新扫描索引并挂载，无须到 Connections 找 Refresh 按钮。
• Additional folder 提供独立 alias、Connect／Disconnect 与可携管理；不是本机文件 DRM（仍可自行改初始文件夹指向等方式读多路径）。

Cloud folder：

• 支援 Amazon S3、Alibaba Cloud OSS、ADLS Gen2、Azure Blob，以及已 OS 挂载的 Azure Files 路径。
• 引用格式与 Additional folder 相同："alias"."file.parquet"、"alias"."subdir/orders.csv"、"alias"."book.xlsx"."Sheet1"。
• Credential 存于 OS vault；Remove 只解绑 Lantide，不删除云端物件。汇出工作区预设不含云端 physical data，汇入后需 Edit／重填 credential 并 Connect。
• 远端文件建议优先使用 Parquet；Connect 会重新 list prefix 下物件并建索引（有硬上限，避免扫描整桶）。若 Sidebar 展开后提示需索引，请到 Connections 或侧边栏右键对该 alias Connect。
• 侧边栏 Cloud folder alias 列右键可 Edit、Connect、Disconnect（英文选单）。
• ADLS Gen2／Azure Blob 表单可用 Autofill from SAS URL 贴上 Azure SAS 连结，拆出 account／container／token（原始 URL 不会存档）。
• Add 前可选 Test connection（list 验证）；Add 仍可直接提交。Sidebar Select 100 rows 走 POST /api_v1/probe/describe（与本机／Additional folder 相同），不经 /query。

SQL Server / Azure SQL：

• 本机须安装 Microsoft ODBC Driver 18；App 会侦测并提供安装指引（含 Detect again、Open installation guide）。侦测通过后即可填写连线。
• Deployment 可选 SQL Server 或 Azure SQL；Authentication 为 SQL login（v1 不支援 Entra／Azure AD）。可用 Autofill from connection string 贴上连线字串填入栏位（原始字串不会存档）。
• 连线成功后密码存于 OS vault（macOS Keychain／Windows Credential Manager）。
• 查询为 read-only（SELECT／CTE）。SQL 须为 DuckDB 相容语法；表引用格式为 "alias"."schema"."object"（或省略 schema 时 "alias"."object"）。系统会将可下推的筛选／聚合转为 T-SQL 在远端执行，其余在本机处理。
• ODBC staged 跨源规则（与 ATTACH 原生 DB 不同）： PostgreSQL／MySQL／SQLite 经 DuckDB ATTACH 后，可与本机文件在同一 SQL 中 JOIN。SQL Server 不 ATTACH；每条远端查询须单源（仅引用该 alias），先在远端筛选／聚合并物化为本机 cache，再与本地文件、其他 cache 或已 ATTACH 的 DB 做第二步 JOIN。不支援在单一 statement 中对 SQL Server 与其他来源做透明跨源 JOIN。
• 大结果 preflight： 当远端优化器估计结果超过 500,000 列 时，Agent 的 validate_query 或 run_query 会回传需确认的警告（含 warning_id）。Agent 应先 ask_user，你同意后再以 large_remote_warning_id 重试。若无法取得估计值，可能仍执行但附 REMOTE_ESTIMATE_UNAVAILABLE 软警告——此时 Agent 应收敛筛选或再次请你确认。

连线状态：

• Link2 旁数字 = 所有已连线／已挂载来源（外部 DB + Additional folder + Cloud folder），非仅 DB 条数。
• 若任何外部 DB 为 error，Connections 按钮会显示黄色警示（MCP 断线仍走 §4.6 黄标，不计入此数字）。
• 常见状态：connected（DB 已 ATTACH）、available（folder 已挂载）、degraded（cloud 可用但索引可能不完整）、disconnected（使用者主动 Disconnect，仅 Connections 可见）、error／missing 等。
• 移除、断连或改绑若会影响 SQL 分页引用，系统会先显示 impact 确认（列出引用 tab 数；必要时须勾选确认）。

管理现有连线（Connections 对话框右侧卡片）：

每笔 DB／Additional folder／Cloud folder 绑定有三个图示（英文 tooltip）：

从其他工作区汇入（Import from other workspaces）：

• 在 Existing Connections 标题列右侧点 ☰，选 Import from other workspaces。
• 开启第二层对话框：左侧 From 选来源工作区并浏览连线卡片；点 → 将绑定加入右侧 To 待汇入清单（可跨多个工作区累积）。
• 右侧可 ✎ 修改汇入后的 alias，或 × 移除该笔；若 alias 与本工作区既有名称冲突，Confirm 会整批挡下并提示改名。
• Confirm 后才复制设定至目前工作区；不会切换工作区、不会改动来源工作区，也不会自动 Connect。新汇入的 DB／folder／cloud 皆为 disconnected，请在卡片上按 Connect 后再查询。

浏览与插入 SQL：

• 数据库连线成功后，Data 区出现 schema 树（alias -> schema -> table）。Additional folder 以该 alias 下列出可查文件。
• 双击表名／档名可插入引用；右键可用「SELECT 100 rows」。
• 在连线 alias 列右键可用 Sort by… → Name（见 §4.1）。

引用格式：

-- PostgreSQL
SELECT * FROM pg_db.public.orders LIMIT 10;

-- MySQL / SQLite
SELECT * FROM my_db.orders LIMIT 10;

-- Additional folder
SELECT * FROM "sales_drop"."orders.csv" LIMIT 10;

跨源 JOIN 范例（本地／cache／已 ATTACH 的原生 DB）：

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）。MCP 仍维持独立管理对话框，但来源卡片与 Sidebar alias 右键现在同样提供 Edit／Connect 或 Disconnect／Remove。

内建 Agent 与外部 Agent（Execute／Admin） 也可透过 MCP source 控制工具管理同一组来源设定（mcp_upsert_source、mcp_connect_source、mcp_test_source 等）。凭证永不回显；新增、替换或清除凭证与 Remove 需先取得你的确认。Sidebar 会在 Agent 变更来源后自动刷新。

管理来源：

1. 点击 MCP Sources 标题列右侧的 齿轮 或 ＋，开启管理对话框。
2. 左侧 Add MCP Source 可设定：

• transport=stdio：填入启动命令（如 npx ...）。
• transport=http：填入 URL、可选 Token 与 Headers JSON。

3. 点击 Test 先测试连线；结果会显示在独立结果弹窗（可复制 JSON）。
4. 点击 Add 仅加入来源设定；不论 stdio 或 HTTP，初始状态皆为 disconnected。
5. 右侧来源卡片可用：

• Edit icon：编辑来源；alias 不可改。command、token、headers 不会回显，请选择保留、替换或清除。
• Connect／Disconnect icon：连线或停止目前 runtime；HTTP 的 Connect 会先验证 endpoint。
• Remove icon：先选择 Keep data（仅移除连线设定，物化表保留）或 Clear data（连线与物化表一并删除）；进行中的 MCP operation 会取消。

编辑并储存后不会自动连线，会回到 disconnected，请再按 Connect。切换 stdio / HTTP 时需明确确认，且原 transport 的 credentials 会清除。

从其他工作区汇入（Import from other workspaces）：

• 在 Existing Sources 标题列右侧点 ☰，选 Import from other workspaces。
• 左侧选来源工作区并点来源卡片上的 → 加入右侧待汇入清单；右侧可改 alias 或移除项目。
• Confirm 后复制 MCP 来源设定至目前工作区（不含物化表与下载快取）；汇入后为 disconnected，请再按 Connect。

状态说明：

• connected：连线可用
• disconnected：已设定但尚未连线
• error：最近一次重连/测试失败（可从卡片讯息查看错误）
• unbound（仅侧边栏）：连线设定已移除但物化表仍在；父列图示为 CloudOff，右键仅 Remove；管理对话框不显示此列

重启 App 或切换回工作区时，系统会对先前已 Connect 的来源各自动尝试重连一轮；若远端暂时不可用，来源会显示 error，你可稍后再手动 Connect。若你曾主动 Disconnect，该来源不会在重启后自动重连。编辑并 Save 后当次仍不会自动连线。

当来源为 disconnected 或 error 时，侧边栏来源名称旁会显示黄色警示图示；将滑鼠移上去可查看错误摘要。

侧边栏来源控制：

• 在 MCP 来源列（alias 父行，非底下的物化表列）上按右键，可选择 Edit、Connect／Disconnect 或 Remove（已移除连线、仅剩数据的 unbound 列仅 Remove）。
• 成功或失败皆会以 Toast 通知；同一来源操作进行中会暂时停用重复操作。
• Remove 会跳出 Keep data／Clear data／Cancel：Keep 只删连线设定，侧边栏仍显示同 alias 的 unbound 列且 SQL 仍可查；Clear 连线与物化表一并删除。unbound 列再 Remove 则清掉剩余物化表并从侧边栏消失。
• 单表删除请在物化表列右键选择 Delete。

Start in Chat 引导：

• 当来源尚未有物化表时，可点 Start in Chat。
• 选择 Scan Source 时，系统会自动开启 AI 面板、建立新对话并填入探索提示。
• 选择 Skip 时，不会填入任何提示。

物化表使用方式：

• Agent 拉取完成后，表会出现在 MCP Sources 区段。
• SQL 可直接引用 mcp_alias__table（系统会在执行期映射到对应 Parquet 文件）。
• 在物化表列上按右键，可进行 SELECT 100 rows（插入 LIMIT 100 预览查询）、Agent Refresh（unbound 来源无此项）、View details、Delete。
• View details 会显示脱敏后的 Pull contract（来源工具、流程与查询），可用来理解或重建表；它不是短效 batch／task ID 或下载 URL。
• Agent Refresh 会将 canonical mcp_table_info 送到聊天。Agent 依目前来源 schema 重新完成 submit／status／fetch；取得本轮 ready write ID 后，以 mcp_pull_table 安全覆写本地表（inline／builtin download 用 mcp_result_id；自订 download 配方 validate 后用 normalization_id）。系统不会重用历史 task、batch、URL 或其他短效 handle，也不会从后端自动重播远端流程。有效 write ID 存活期间请勿再次 fetch，以免旧 ID 作废。
• 当 External agent mode（Execute／Admin 外部工作阶段）启用、内建 Agent 暂停时，Agent Refresh 改为复制含完整 refresh 契约的 GUI handoff 到剪贴簿，供贴到外部 agent；Add to chat 在数据表列上改为 Copy table name（复制 SQL 可用的 quoted identifier）。
• 若来源仍在处理中，请让 Agent 依该来源的工具契约继续确认状态；关闭或中断对话后，重新从表的 Agent Refresh 或新的查询开始。并行 Refresh 遇到数据已更新时不会覆盖较新的表，请先查看最新 details 再决定是否重跑。
• 在**来源列（alias 父行）**上按右键，可选择 Edit、Connect／Disconnect 或 Remove（见上文「侧边栏来源控制」）。