AI 助手

12. AI 助手

Lantide Data 内建 AI 副驾驶（Agent），可理解你的工作状态并直接操作 IDE（建立 SQL 标签页、执行查询、编辑 Plan / Report）。五阶段分析流程见 §1.3；第一次完整体验见 §2。

12.1 打开 AI 面板

点击界面右侧 icon 列底部的 Astroid 图标（AI 助手），即可展开 AI 对话面板。

• 后续启动： 面板默认收合，需手动点击 Astroid 展开。首次启动体验（自动展开、Welcome Dialog）见 §2.1。
• 背景执行： 再次点击 Astroid 收起面板，或切换至 Export Tasks，不会停止进行中的 Agent 回应；对话区仅隐藏，串流在背景继续（详见 §12.2）。

12.2 AI 生成中操作防护

当 AI 正在生成回应时，部分操作可能会中断生成过程。为了防止你意外打断 AI，系统在下列操作上加入了确认防护机制——执行时会弹出确认对话框，让你决定是否继续：

如果你选择取消，操作不会执行，AI 继续正常生成。

不会中断生成的操作：

提示： 当 AI 未在生成时，受保护操作不会显示确认对话框，直接执行。

12.3 设置 AI 连接配置文件（Profile）

使用 AI 助手前，需要先设置连接。首次启动时，系统会自动建立一个 OpenAI 默认 Profile（默认官方 Base URL、API Key 为空），WelcomePanel 会提供「Open AI Settings」按钮引导你完成设置。

1. 在 AI 面板中点击设置图标（齿轮），或点击 WelcomePanel 的「Open AI Settings」按钮，打开设置窗口。
2. 点击「新建 Profile」（或编辑默认 Profile），选择连接类型：

• Ollama — 连接本机执行的 Ollama 模型服务。
• OpenAI — 连接 OpenAI 官方 API（默认 Base URL 固定为官方 endpoint），需填入 API 金钥；填入后可透过 Refresh 拉取模型列表。若你使用其他兼容端点或非 OpenAI 供应商，请改用 Custom 并自行填写 Base URL。
• Custom — 自订 OpenAI 兼容的 API 端点。

3. 填入对应的设置信息（服务网址、API 金钥等），然后选择模型：

• OpenAI 模式： Base URL 为官方默认（唯读）；填入 API Key 后可拉取模型清单并选择模型（或手动输入）。若旧版设置曾指向 Anthropic 等非 OpenAI endpoint，请改选 Custom。
• Ollama / Custom 模式： Model 字段旁有 Refresh 按钮，点击自动从伺服器拉取可用模型清单。若拉取失败或清单为空，会自动降级为手动文字输入。

4. 保存后，将该 Profile 设为使用中。

你可以建立多个 Profile，并随时从面板顶部的下拉选单切换。设置完成后，WelcomePanel 会自动从引导状态切换为简短欢迎词。

OpenAI / Custom Profile 可在设置中将 Vision（贴图） 设为「自动侦测」、「支持」或「不支持」，用于判断能否把截图送给模型。

12.3.1 在对话中贴上图片（Vision）

仅 OpenAI 与 Custom 连接支持在聊天输入框贴上截图（Ollama 不支持）。

1. 在输入框内 Ctrl/Cmd+V 贴上剪贴簿中的图片（例如 BI 截图、错误界面）。
2. 图片会出现在输入框上方的待送缩图列（48×48）；点缩图右上角 × 可移除尚未送出的图片。
3. 可附加文字后按 Send；最多 4 张 图/则讯息。
4. 送出后，图片会显示在用户气泡内上方（48×48），文字在下方。

限制与说明：

• 仅当轮送给模型「看」图；之后对话轮次不会自动带上历史图片（若需再分析请重新贴图）。
• 若模型不支持 Vision，系统会提示；确认后可仅送文字（图片不会进模型，气泡中也不会保留缩图）。
• 已送出的讯息无法删除气泡内图片；重新产生（regenerate）含图讯息时仅重送文字。

12.4 Agent 状态指示器

AI 面板的 Top Bar 下方有一个固定状态列，即时显示 AI Agent 当前所处的工作状态。状态会随着你的操作（聚焦/取消聚焦项目、切换标签页、变更 Plan 状态等）自动更新，无需手动触发。

点击状态列右侧的 ? 按钮，可打开说明对话框，详细了解每种状态下 Agent 的能力范围。

提示： 状态指示器的计算逻辑与后端完全同步——你在前端看到的状态，就是 Agent 实际运作的状态。Agent 在不同状态下可使用的工具不同（例如 SQL Tab 操作仅在 Quick Analysis 与 Executing 状态下可用）。进入 Executing 状态后，Agent 会先读取 Plan，再询问你偏好的分析执行模式（前台／混合）。后台代理分析（chat-only）仅在 Quick Analysis 提供。

提示： 当 Executing 状态下 Agent 处于闲置（例如因中断、超时等原因停止回应），状态描述会切换为「Paused」提示。此时回到 Plan 标签页，点击工具列的 Continue 按钮即可恢复执行（详见 11.6 节）。

12.5 两种分析模式：快速分析 vs 项目分析

AI 助手支持两种分析工作流程，会根据你当前的状态自动选择适当的模式：

快速分析模式（无需建立项目）

当你没有聚焦任何项目时（状态列显示 Quick Analysis），如果向 AI 提出数据分析需求，AI 会先询问你偏好哪种工作方式：

• 快速分析 — 可选前台 SQL 标签页、后台代理分析（chat-only） 或混合模式；适合一次性查询或快速验证想法。
• 项目分析 — AI 引导你建立项目，进入结构化的「计划 → 执行 → 报告」工作流程。

提示： 如果你只是问一个简单的 SQL 问题（例如「怎么用 DuckDB 做 PIVOT？」），AI 会直接回答，不会要求你选择模式。

项目分析模式（结构化工作流程）

当你已聚焦某个项目时，AI 会自动进入项目分析模式。完整流程（接题 → Plan → 批注 → Execute → Report）见 §2.4–§2.7。

两种分析执行模式（Plan Executing）

当 Plan 进入 Executing 状态后，AI 会先读取 Plan，再透过互动问题询问你偏好的分析执行方式：

后台代理分析（chat-only、不操作编辑器） 仅在 Quick Analysis 提供；Plan Executing 仅提供前台／混合二选一。若项目 Plan 在规划阶段宣告 background_materialized 策略，Executing 时请选 混合模式。

进入 Executing 后，Agent 的典型启动顺序为：读取 Plan → 询问执行模式 → 写入 Todo → 依模式执行 SQL（Pipeline 阶段必走 SQL tab）。

AI 只会在 Executing 阶段 询问一次执行模式（同一段对话内）。若你曾在 Quick Analysis 选过后台模式，按下 Execute 开始新 Plan 时仍会重新询问前台／混合。若你已表达过 Executing 偏好，AI 会直接沿用，不会重复询问。

Plan 与 Report 的配对关系

每个 Plan 执行完成后会产出一份独立的 Report，两者一对一配对（Plan 1 → Report 1，依此类推）。

• AI 在完成所有分析步骤后，会一次性产出完整报告，同时自动将 Plan 标记为已完成（Executed）。
• AI 不会修改旧的 Report。 执行新 Plan 时只会生成新的 Report；微调已产出 Report 须透过批注或对话指示修订。

Plan 与 Report 的增量编辑

当 AI 需要修改 Plan 或 Report 的部分内容时（例如根据你的批注修订某段分析步骤），AI 会优先使用增量编辑（找到需要修改的段落，仅替换该段落），而非整份文件覆写。这带来两个好处：

• 更精准： 只改动需要修改的部分，不会影响其余内容。
• 即时同步： 如果你正在编辑器中查看 Plan 或 Report，修改后的内容会即时反映在编辑器中，无需手动重新打开。

提示： 如果你在快速分析过程中发现需求越来越复杂（如需要多步骤分析、产出正式报告），AI 会主动建议你升级为项目模式。

12.6 AI 直接操作你的 IDE（UICommand）

这是 Lantide Data AI 最强大的能力——Agent 不只是「出一张嘴的顾问」，而是能直接操作你的 IDE 的副驾驶。

AI 可以执行的操作：

查询执行与步骤记忆（Quick Analysis 后台／Executing 混合模式）：

• run_query / run_sql_tab：Plan Executing 时必须传 purpose（≤40 字，本步意图，写入 Query Step Ledger）。run_query 另依上下文推断是否物化；多步时可用 result_label 供 FROM 引用。
• 步骤亦记入对话级 Query Step Ledger；可选在正文写 [[QUERY_STEP]] 补充 pitfalls。
• 系统 prompt 会注入 Recent Query Steps 摘要（不含完整 SQL）。回溯完整 SQL 的三级路径：(1) query_result(result_id=...)（结果仍在记忆体时）；(2) get_cache_source(cache_name=...|tab_id=...|result_id=...)（结果已 spill 或过期、但快取仍存在）；(3) list_query_steps(include_sql=true) 列出本对话步骤。人类亦可于 Data → Cached 右键 查看 SQL（与 get_cache_source 同源解析）。

所有操作都在你眼前发生 — 当 AI 建立一个 SQL Tab 时，你会看到新标签页出现；当 AI 执行查询时，你会看到结果显示在结果面板中。你随时可以接管或修改 AI 的工作。手动 SQL 或快速分析示例见 §2.8、§12.5。

提示（Agent 查询工具）： 探索／试错阶段以轻量验证确认 SQL 可执行（无数据列）；正式取数的预览最多 200 行。后台查询在多步分析、多表 JOIN 或复杂 CTE 时会物化为快取，供后续 FROM "步驟名" 引用；前台 SQL 标签页则一律物化。你可在 Data → Cached 右键 查看 SQL 审阅来源。历史对话若仍显示旧工具名 test_query，仅为旧纪录展示。

注意： AI 的所有操作都是唯读的——它可以建立 SQL Tab 并执行 SELECT 查询，但无法修改你的原始数据文件。

12.7 AI 提问互动（ask_user）

在分析过程中，AI 可能需要你做出选择或确认。此时 AI 会在对话中显示一个互动问题区块：

• 如果 AI 提供了选项按钮，你只需点击对应的按钮即可回答。
• 如果 AI 需要自由文字回复，你可以在输入框中输入回答。

常见的 AI 提问场景：

• 「你想要快速分析，还是建立项目进行结构化分析？」（模式选择）
• 「请选择你偏好的分析执行模式：前台自动分析 / 混合模式」（Executing 阶段；Quick Analysis 另可选后台代理分析）
• 「确认要将 Plan 标记为已完成吗？此操作无法撤销。」
• 「有多个相关的表，你想优先分析哪一个？」
• 「探索配额已用尽，是否继续探索？」（选项：Continue exploring / Stop for now）

提示： AI 的提问会在对话气泡中以明显的互动区块呈现，与一般文字回复区分开来。如果你没有回答，AI 会等待你的回复而不会自行推进。超过 5 分钟未回复会自动超时。

12.8 与 AI 对话：询问数据、产生 SQL

设置完成后，你可以直接在对话框中输入问题，例如：

• 「这个数据集有哪些字段？」
• 「为什么这条 SQL 会报错？」
• 「帮我分析每个月的销售总额变化趋势」

AI 助手会自动参考你目前工作区的数据结构（表名、字段名），提供贴合你实际数据的回答。根据问题的复杂度，AI 可能会：

• 直接回答：简单问题直接给出答案或 SQL 示例。
• 建立 SQL Tab 并执行：复杂分析需求会在你的 IDE 中建立标签页、撰写并执行查询（详见 12.6 节）。
• 询问你的偏好：需要确认时透过互动问题提问（详见 12.7 节）。

提示： AI 助手在回答过程中可能会以 validate_query 验证 SQL、或以 run_query 执行查询取得预览，这些操作都是唯读的，不会修改你的数据。验证不会回传数据列；执行查询的预览上限为 200 行（见 §12.6）。

提示（回看历史结果）： 使用 query_result 读取先前 run_query 的结果时，回应可含 sql 摘要与 cached_table_name（若已物化），便于在对话压缩后仍追溯查询定义。

提示（含 Markdown 批注情境）： Plan / Report 批注存于 sidecar（*.annotations.json）；Agent 透过 read_plan / read_report 取得含 mark 的磁碟正文与 annotation_summary（详见 §11.8）。

12.9 AI 数据分析工具

除了 SQL 查询之外，AI Agent 还内建了一组统计与机器学习分析工具，能直接在对话中为你完成高级数据分析——无需安装额外套件。

使用方式： 你只需要用自然语言描述分析需求（例如「帮我检定这两组数据是否有显著差异」），AI 会自动选择合适的工具。在执行任何分析工具之前，AI 一定会先向你确认（透过 ask_user 互动问题），你同意后才会执行。

可用的分析能力：

分析结果呈现： AI 会在对话中以结构化格式呈现分析结果，包含统计量、p 值、效果量与文字解读，让你不需要查阅统计教科书就能理解结论。

提示： 在快速分析或项目执行阶段，AI 会先用 SQL 准备数据，再透过 activate_analysis 启用所需的统计工具并执行。规划 Plan 阶段仅做数据探索与修订计划，不执行统计分析。无论哪个阶段，执行分析前 AI 都会先向你确认参数。

提示： 分析工具的计算结果仅在对话中呈现，不会修改你的原始数据或快取表。

12.10 AI 分析方法论（Analysis Methodology）

AI Agent 内建结构化分析方法论，能自动识别你的分析场景并套用对应的最佳实践——你不需要手动指定方法论，AI 会自动判断并应用。

场景识别： AI 会将你的分析需求归类为以下场景之一，并据此决定分析策略与验证重点：

分析品质保障： 根据识别的场景，AI 会在 Plan 中加入验证 checkpoint、在统计结果中报告效果量与显著性，并在 Report 附带 limitations。漏斗分析的 stage 定义、分母与最大流失等要求，已于 §1.3、§2.5、§2.7 示范。

12.11 AI 自动感知的上下文（Context Engine）

每次你发送讯息给 AI 时，系统会自动将以下信息打包传送，让 AI 完整理解你的工作状态——你不需要额外操作，一切自动进行：

这代表什么？

• 你不需要告诉 AI「我在写什么 SQL」 — 它已经看到你当前标签页的内容。
• 你不需要重复解释项目背景 — 聚焦项目后，AI 自动知道你在做哪个分析、Plan 的进度如何。
• 你可以直接说「帮我用 clean_orders 这张表」 — AI 已知道你有哪些快取表、每张表有哪些字段。
• 你不需要手动复制错误讯息 — 当查询失败时，AI 会自动看到完整的报错内容与触发的 SQL，你只需说「为什么这条 SQL 报错？」即可获得修正建议。
• Markdown 标签页的批注走 sidecar + MD mark — Agent 读取磁碟正文（含 mark）与 annotation_summary（详见 §11.8）。
• Agent Memory — 仅在总开关打开且内容已写入知识档时，模型才会带入你的长期记忆；伫列中待核准项不会注入（详见第 13 章）。

效能优化： 系统采用分层传递策略——每次对话时仅自动传送精简摘要（工作区名称、活跃标签页标题、快取表清单等），AI 需要深入了解时会自动呼叫内部工具取得完整上下文（字段定义、SQL 内容、项目文件等），无需你额外操作。这大幅降低了每次对话的 token 消耗，同时确保 AI 在需要时仍能取得完整信息。

高级： 送给模型的系统提示词分为核心规则、当前工作状态指引与上下文摘要；完整可呼叫的工具列表由模型收到的 function 定义提供，而非在状态指引中重复列举。

隐私说明： 上下文数据仅在你发送讯息的当下组装并传送给你设置的 AI 模型服务（Ollama / OpenAI / Custom），不会保存在任何第三方伺服器。

12.12 Context Usage 圆环

AI 输入框的右侧（Send 按钮旁）有一个小型的 Context Usage 圆环，让你即时掌握当前对话的 token 消耗状况：

• 圆环以弧形进度条呈现 context 使用比例——弧越长表示消耗越多。
• 将鼠标移到圆环上，tooltip 会显示详细数值，例如 42.3% · 18.5K / 43.7K context used。
• 仅在 AI 回复过至少一次（有 token 用量数据）后才会出现。
• 切换到新对话时，圆环会重置。

提示： 如果你在 AI Profile 设置中指定了自订 context window 大小（≥ 1024 tokens），圆环的分母会使用你的自订值，而非模型回报的默认值。

提示： 当你切换或编辑 AI Profile 的模型 / context window 设置后，圆环会自动清除旧值并重新取得最新用量，确保显示的数据与当前模型一致。

12.13 对话 Token 用量与截断警告

系统会自动管理每次 AI 回复的输出 token 上限，尽可能避免回应被截断。当遇到极端情况时，对话中会出现以醒目的琥珀色边框标示的警告讯息：

提示： 大多数情况下你不会看到这些警告。系统会在背景自动进行接续尝试，仅在自动接续仍无法完成时才显示警告。

12.14 AI 思考过程与工具调用的即时呈现

AI 助手在回复过程中可能会经历多个步骤——思考、呼叫工具、取得结果、再继续回复。这些步骤会按照实际发生的时序逐段堆叠在对话中，让你随时掌握 AI 正在做什么。

五种区块类型：

对话中的 fenced code block：

多行 ````` 代码区块在串流完成后可将鼠标移入区块，右上角会出现工具按钮（由左至右：Open in new SQL tab → Copy）：

• 串流中：最后一段正文尚在输出时，工具列不显示；完成后才出现。
• 触控装置（v1 限制）：无 hover 能力时工具列可能不可见；请待串流完成后改用桌面鼠标操作，或手动建立 SQL 标签页贴上内容。

串流中的行为：

• Thinking 与 Tool Call 区块有最大高度限制，超出时会自动向下滚动并在底部加上渐层淡出效果，确保不会占据整个界面。
• 串流完成后，Thinking 与 Tool Call 区块会自动折叠，只留下一行摘要（如「Thinking (12 lines)」或「tool_call: show_tables」／validate_query 的 SQL 摘要），让你专注于最终回复。需要时点击即可展开查看。

对话卷动：

• 新讯息到达时，对话区会自动跟随卷至底部。
• 若你向上卷动阅读（含在 Thinking / Tool 区块内卷动），自动跟随会暂停，右下角出现圆形向下箭头按钮。
• 只要自动跟随已暂停，该按钮一定显示（即使你已手动卷到最底部）。
• 暂停后需点击按钮或发送新讯息才恢复跟随；Agent 生成结束不会自动跳回最新讯息。
• 点击按钮可恢复跟随并卷至最新讯息，按钮随即隐藏。

Tool Call 自动分组收合：

当 AI 连续发出 3 次以上的 tool call，系统会自动将这些呼叫收合为一个 「N tool calls」 分组，避免大量展开的工具区块占满对话界面。点击分组标题即可展开查看每笔 tool call 的详细内容。

活动指示器（Activity Indicator）：

在 AI 回复过程中，有些阶段 AI 正在运作但尚未产出可见的文字（例如工具呼叫执行中、多轮迭代间重新呼叫 LLM 时）。为了消除「界面停住」的体感，系统会在这些静默期自动显示 trailing spinner 与状态文字提示（如「Processing tool calls...」、「Thinking...」），告知你 Agent 仍在正常运作中。spinner 在工具呼叫期间也会持续显示，直到工具回传结果后才清除状态提示，避免闪烁。此外，当 AI 回复的文字串流暂停超过数秒时（例如模型在内部整理工具呼叫），系统也会自动显示「Working...」spinner，确保你知道 AI 仍在正常运作。

提示： 停止按钮采用中性灰色设计，降低视觉突兀感，让你在需要时才注意到它。

文件变更条（File changes）：

当一则 AI 回复在该回合内成功写入工作区文件时，讯息底部（正文与 Copy / Fork 操作列之间）会出现 文件变更条，汇总本则回复影响的资源——无需展开多个 Tool Call 即可追踪 Agent 动了哪些档。

撤回限制与语意：

• 安全模式： 若你在 Agent 写入后又手动编辑过该档正文，系统会侦测内容已偏离 Agent 写入结果而阻挡撤回，并提示冲突——请改以批注、对话或手动还原处理。
• 新建档： Agent 在本则回复内新建的 Plan / Report / SQL tab / HTML，撤回时清空内容但保留文件与标签栏（不删档、不关 tab）。
• add_report 连带： 若本则回复的 add_report 已使 Plan 进入 Executed，撤回该 Report 列时可能因 Plan 状态副作用而被阻挡；需依提示手动处理 Plan 状态。
• 范围： 撤回仅针对单则 assistant 回复内的写入，不跨 message、不跨对话；与 git 无关。
• 重新加载对话： 已撤回的列会标示为已还原；历史对话重新打开后仍可看到变更条与统计。

提示： 批注 Resolve、Query Step Ledger、run_query 物化快取、Reference 档写入等不在文件变更条范围内。Plan 进度 sidecar（Todo）由 Progress 面板呈现，见 §11.6。

讯息操作列（Message Actions）：

每则 AI 回复的讯息气泡右侧外缘会显示操作按钮：

仅在回复已完成持久化后显示 Fork 图标。若回复在中途被停止、或工具回合尚未写入完成，则无法分支。

提示： 来源对话若有进行中的 ask_user 互动，你仍可在其他已完成的回复上 Fork；来源对话的提问不受影响。

提示： 如果你使用的模型（如 DeepSeek-R1、QwQ）会在回复中夹带 <think> 标签，系统会自动拦截这些标签并将其内容正确归类为 Thinking 区块，不会出现在正文中。

12.15 对话管理（新建 / 切换 / 删除 / 清除全部）

• 新建对话： 点击 AI 面板顶部的「新建」按钮，打开一个全新的对话（空白上下文）。
• 分支对话（Fork）： 在已完成 AI 回复的操作列点击 Fork 图标，会复制截至该则回复的完整对话纪录（含工具轨迹）到新对话，并自动切换过去。与「新建对话」的差异在于 Fork 保留既有上下文，适合平行探索不同假设而不弄丢原分析线。
• 自动命名： 新对话的第一条讯息发出后，系统会自动以 LLM 生成一个简明的对话标题，即时显示在对话历史列表中。若自动命名失败，系统会以讯息前几个字作为 fallback 标题。Fork 产生的对话标题以 Fork · 为前缀。
• 手动重命名： 将游标移至 Top Bar 的对话标题区域，会出现铅笔图标。点击后进入 inline 编辑模式（文字自动反白全选），修改完按 Enter 确认或按 Escape 取消。标题最长 60 字。修改后即时同步至对话历史列表。
• 切换对话： 点击 Top Bar 的历史图标，弹出浮层选单，可搜寻、浏览并切换至之前的对话。对话按日期分组显示（Today / Yesterday / Earlier），当前活跃的对话以高亮标示。
• 删除对话： 在对话历史浮层中点击删除按钮，移除不需要的对话。
• 清除全部历史： 在对话历史浮层的搜寻框下方，点击 Clear All History 按钮，可一次清除所有历史对话。系统会显示二次确认提示，确认后会删除所有对话但保留当前正在进行的对话。

每个工作区的对话记录是独立的。

12.16 连接状态指示

AI 面板顶部有一个连接状态指示灯：

• 绿色 — 连接正常，可以开始对话。
• 红色 / 灰色 — 连接异常。点击可查看错误详情，请检查 Profile 设置是否正确。

[图片] AI 对话面板：对话介面、Agent 状态指示器与连接状态

[图片] AI 设置窗口：Profile 设置界面

设计说明： 分析模式与 ask_user 见 Agent 时代的数据分析工作流 §二、§十；统计工具与方法论护栏见 Agent 时代的数据分析工作流 §十一；Context 工程见 Prompt 与 Context 工程。