18. 常见问题（FAQ）
为什么查询结果最多只显示 500 笔？
界面中的结果预览限制为 500 笔，这是为了保持介面流畅。如果你需要完整的查询结果，请使用导出功能将数据保存为文件，导出不受此限制。
为什么我的 Excel 文件无法直接查询？
查询 Excel 文件时，必须指定工作表名称。正确的写法是：
SELECT * FROM "档案名称.xlsx"."工作表名称"
你可以在侧边栏展开 Excel 文件，查看并选取工作表名称。
为什么导出不支持 .json 格式？
Lantide Data 使用 .jsonl（JSON Lines）格式替代 .json。JSON Lines 格式每行一笔数据，更适合大量数据的读写。导出时将副档名改为 .jsonl 即可。
可以执行 INSERT、UPDATE 等写入操作吗？
不可以。Lantide Data 仅支持唯读查询，包括 SELECT、DESCRIBE、SHOW、PRAGMA。这是为了保护你的原始数据不被意外修改。
快取表在什么时候会消失？
快取表会在以下情况被清除：
- 切换到另一个工作区时。
- 重新启动应用程序时。
清除后，只要重新执行对应的持久标签页，即可重新产生快取表。
来源执行显示错误「需要单一 SQL 语句」怎么办？
来源执行和血统分析要求每个标签页只包含一条 SQL 语句。请确认标签页中没有多条以分号分隔的语句。如果你需要组合多个步骤，请将每个步骤放在独立的标签页中，透过快取表串连。
我可以跨工作区查询快取表吗？
不可以。每个工作区的快取表是完全隔离的，你无法在工作区 A 中引用工作区 B 的快取表。
原因在于 Lantide Data 的快取机制是基于 DuckDB 的记忆体暂存表（Temp Table）实作的——每次切换工作区时，系统会先清除前一个工作区的所有暂存表，再加载新工作区的数据环境。因此，同一时间只有当前工作区的快取表存在于记忆体中。
如果你需要在不同工作区之间共用某份查询结果，建议先将该结果导出为文件（例如 CSV 或 Parquet），然后在另一个工作区的数据目录中加载该文件。亦或是将需要分析的数据都放置在同一个工作区目录下。
AI 建立的 SQL Tab 和我手动建立的有什么不同？
没有不同。AI 建立的 SQL Tab 与你手动建立的完全一致——它们是同样的持久标签页（Persist Tab），保存在工作区中，查询结果同样会物化为快取表。你可以在 AI 建立的 Tab 上继续手动编辑、重新执行，或用来源执行串连上下游依赖。
AI 可以修改或删除我的原始数据文件吗？
不可以。AI Agent 的所有操作都是唯读的——它只能执行 SELECT 类查询，无法透过 INSERT、UPDATE、DELETE 等语句修改你的原始数据。这个安全限制由后端的 SQL 验证层强制执行，AI 无法绕过。
为什么 PostgreSQL / MySQL 连接测试失败（Connection refused）？
这通常表示本机没有启动对应数据库服务，或主机/埠号设置不正确（例如 127.0.0.1:5432、127.0.0.1:3306）。
请依序检查：
- 数据库服务是否已启动。
- host / port / database / username / password 是否正确。
- 本机防火墙与网络策略是否允许连接。
- 若是远端数据库，是否已将你的 IP 加入白名单。
AI 面板的状态指示器显示的状态和实际不一致？
极少情况下，前端计算的 Agent 状态可能与后端不一致。此时以后端为准——后端的 State Router 决定 AI 可以使用哪些工具。你可以尝试切换标签页或重新整理页面来同步状态。
AI 说「已建立 Tab」但我没看到新标签页？
多数情况下，侧边栏工作区列表会在 Agent 建立持久标签页后即时更新。若编辑器标签栏仍未出现，可点击侧边栏中对应的持久标签页重新打开；仍缺漏时可切换工作区再切回，或重新加载页面。
Agent 写入 SQL 后为什么没有 * 号？
Agent 透过工具写入的内容已直接落盘至工作区，标签页不会标示未保存 *。只有你手动编辑后才会出现 *，关闭标签页时亦会照常提示保存或舍弃（见 §5.2）。
对话里 validate_query 和 run_query 有什么差别？
validate_query 以 LIMIT 1 试跑 SQL，仅回传成功或错误，不回传数据列，适合探索与试错。run_query 执行查询并回传预览，最多 200 行，供 Agent 分析取数。历史对话若显示旧工具名 test_query，仅为旧纪录。详见 §12.6。
run_query 什么时候会物化成快取表？
系统自动推断，无需每次手动设 materialize=true。一般会物化的情况：对话中已有成功的查询步骤（多步分析）、SQL 引用了既有快取表、或查询较复杂（例如多表 JOIN、大量 CTE）。单表探索查询（含 LIMIT、无 JOIN/GROUP）通常仅回传预览、不物化。若模型传 materialize=false 但系统判定必须物化，仍会物化并在工具结果附 warnings 说明。详见 §12.6 与 §7.4。
agent 快取和 persist 快取有什么不同？
| 类型 | 来源 | Source Run | 查看 SQL |
|---|---|---|---|
| persist 快取 | 持久标签页执行（run_sql_tab / 手动 Run） |
支持 | 通常来自标签页 SQL |
| agent 快取 | 后台 run_query 条件物化 |
不支持 | 来自 registry / ledger |
两者皆可在 Data → Cached 右键 查看 SQL、SELECT 100 rows 或于 SQL 中 FROM 引用（同一工作区内）。
查看 SQL 显示「已不可用」怎么办？
表示系统无法从快取 registry、对话 ledger 或结果管理器还原该快取的 SQL（常见于旧版快取、重启后 metadata 遗失、或对应 result_id 已过期）。你可删除该快取后让 Agent 重新执行，或对 persist 快取使用 Open Tab / Run 从标签页重新取得 SQL。
HTML Report 产出的报告支持哪些浏览器？
HTML Report 会以系统默认浏览器打开。产出的 HTML 是标准网页文件，支持所有现代浏览器（Chrome、Firefox、Safari、Edge）。Presentation 模式 + CDN 需网络加载 reveal.js；Chart.js 互动图表（Standard + CDN）需网络加载 Chart.js。关闭 CDN 则产出完全离线的 HTML，无需网络即可查看（不含 Chart.js）。
Context Usage 圆环显示的数字代表什么？
圆环显示的是当前对话的 token 消耗量占模型 context window 的比例。tooltip 中的数值如 42.3% · 18.5K / 43.7K context used，代表已使用 18.5K tokens，模型 context window 为 43.7K tokens，消耗了 42.3%。当比例越高，表示剩余空间越少——若接近 100%，建议打开新对话以获得最佳回复品质。
AI 正在回应时，我不小心切换了工作区怎么办？
当 AI 正在生成时，切换工作区、新建／切换对话、Fork 等操作会先弹出确认对话框。若你选择取消，操作不会执行，AI 继续生成；若你确认，当前生成会被中断，但已完成的回复会保留在对话历史中。
收起 AI 面板或切换至 Export 不会中断生成；Agent 在背景继续执行时，右侧 Astroid 图标会 pulse 并显示绿点（见 §12.2）。
记忆体用量过高怎么办？
点击标题列右上角的记忆体条图标（MemoryStick），打开 Memory Dashboard。你可以：逐一删除不需要的快取表、降低「Max In-Memory Results」让多余的结果自动溢出磁碟，或直接点击 Emergency Clean 一键释放所有可回收的记忆体。详见第 17 章。
AI 的分析工具需要安装额外套件吗？
不需要。统计分析工具（t 检定、回归、预测等）全部内建于 AI Agent，不需要你额外安装任何套件。AI 会在需要使用分析工具时先向你确认，你只需同意即可。
Agent Memory 已打开，为什么 Agent 好像不记得我的业务规则？
请先确认对话框中的 Enabled 是否为打开，以及该条知识是否已从 Queued Knowledge 套用到 User 或 Project 知识档——伫列中尚未核准的项目不会注入模型。关闭 Automatic suggestions 只会停止对话后背景萃取，不会停用已核准知识的注入。你亦可打开 Agent Memory 标签页直接查看或手动编辑知识档。
我在卡片上套用了知识，为什么 Queued Knowledge 里找不到？
Queued Knowledge 只显示尚未处理的 pending 项目。 套用成功后该笔会从伫列移除，这是预期行为。请到 Agent Memory 标签页查看：User 套用 → 左侧选 User Knowledge；Project 套用 → 左侧选对应项目的 Project Knowledge（不会出现在 User Knowledge）。套用当下应有英文 toast 说明写入位置。
我点了 Project 套用，但知识好像没写进去？
常见原因：(1) 该笔先前已 Dismiss 或已套用，再次点击不会重写（会提示 Already dismissed / Already saved）；(2) 在 User Knowledge 里找 Project 套用的内容——应到该项目的 Project Knowledge 档查看；(3) 若无聚焦项目且建议未指定项目，需手动 Pick project。
重开应用后，工具呼叫显示「Tool execution interrupted」？
新版会从对话历史还原已完成的工具结果与知识提案卡片状态。升级前建立的旧对话若仍异常，请由开发者在本机对 chat_sessions 执行 backend/scripts/migrate_tool_call_ids.py（先 dry-run，确认后加 --apply；执行前请备份数据）。
Agent Memory 的知识会被 AI 提供者看到吗？
在 Agent Memory 的 Enabled 为打开、且相关内容已作为知识注入时：是的。该些知识会作为系统提示词的一部分传送给你设置的 LLM 服务（Ollama / OpenAI / Custom），与其他上下文信息的隐私保护方式一致。若你使用本地模型（Ollama），数据不会离开你的电脑。若总开关关闭，则不会因记忆功能向模型注入这类知识。
我手动编辑了 user_knowledge.md，AI 会立即感知吗？
是的。系统使用文件修改时间（mtime）侦测变更，下一次 AI 对话时会自动重新读取最新内容，无需重启应用程序。
知识库太大了，重组后还是超过上限怎么办？
LLM 重组时会尝试合并相似条目并压缩描述。如果知识确实很多且都不重复，你可以手动删除过时或较少使用的条目。知识库的 6,000 字元上限约可容纳 30-50 条结构化知识。
App 界面突然变成错误提示怎么办？
这是 Error Boundary（错误边界）机制，用来防止应用程序完全白屏。如果是局部区域（编辑器或 AI 面板）显示错误，点击「Retry」按钮即可恢复；如果是全荧幕错误页面，点击「Reload App」重新加载应用程序。错误信息已自动记录在本机，后续回馈时可一并附上。