AI 助手

12. AI 助手

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

12.1 开启 AI 面板

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

• 显示偏好： 预设依 Setup Mode 显示内建 Agent 或外部 Activity。从 View → Agent Panels 选 Internal Agent Only、External Activity Only 或 Display Both，手动偏好会保留。首次设定见 §2.1。
• 背景执行： 再次点击 Astroid 收起面板，或切换至 Export Tasks，不会停止进行中的 Agent 回应；对话区仅隐藏，串流在背景继续（详见 §12.2）。

12.1.1 Agent 与 Ask 模式

聊天输入区底部可在 Agent 与 Ask 之间切换（英文 UI；预设 Agent）。模式会跟著目前对话 session 保留，直到你手动切换。

Ask 开启时，输入框 placeholder 会提示 Agent 不会编辑你的 artifacts。若模型仍尝试写入工具，系统会拒绝（ASK_MODE_DENIED），对话中可看到被挡下的工具呼叫。

与工具列动作的关系： 在 Ask 下点 Generate HTML Report、Resolve Comments 或 Approve & Execute，会提示切回 Agent；可选 Switch & Continue 自动切换并继续，或取消。

不是 MCP Observe： 外部连线的 Observe 只约束外部 Agent，且不暂停内建 Agent。内建 Ask 只约束内建聊天工具，且不影响你在编辑器里手动改档。两者设定与文案分开，见 §13.5。

若你希望 Agent「改 Plan／补 HTML 一段」，请切回 Agent 再送讯息。

12.2 AI 生成中操作防护

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

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

生成期间输入框仍可编辑：你可以先草拟下一则文字、mention 或贴上图片，但 Enter 不会送出第二个请求；Shift+Enter 仍可换行。右下角按钮此时是 Stop generation，只停止目前生成，不会清除草稿。生成结束后，Enter 才恢复送出。

不会中断生成的操作：

提示： 当 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 会自动从引导状态切换为简短欢迎词。

Secondary model（次要模型）： 在 AI 设定列表底部可另选 Secondary model 下拉选单。预设为 Same as active model（与目前使用中 Profile 相同）；亦可指定另一个已设定的 Profile。次要模型用于对话自动命名与 知识抽取等背景任务，不取代主对话模型。仅列出已完整设定（含模型）的 Profile 供选择。

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

OpenAI / Custom Profile 亦可设定 Reasoning effort（可选）：Auto（预设；已知支援 reasoning effort 的 GPT／OpenAI 模型解析为 Medium，Claude、未知 Custom endpoint 保留 provider default；GLM 类模型沿用其 binary thinking policy）、Off（尽力关闭推理）、Low / Medium / High（开启并调节强度）。若 provider 明确拒绝此参数，系统会移除参数重试一次并继续对话。Ollama Profile 不显示此栏。 对话自动命名与知识抽取等背景任务不会套用此设定（避免额外成本）。

所有 Profile（含 Ollama）可选填 Max Output Tokens（k tokens）：限制单次回复的输出上限。留空为 auto（依模型能力与当前 Agent 状态预设，再由系统夹限；HTML 报告任务另有较高下限）。数值过小时长报告较易触发 §12.13 的 Output Truncated；过大则受模型与状态上限约束。背景次要任务不使用此栏。

对话执行与历史控制

在 AI Settings 的 Secondary model 下方，可为目前工作区调整两项对话偏好；变更会立即储存，下一则新讯息才会套用。这些是本机的工作区偏好：会随 Full backup 与 Application backup 备份，但不会写进 Workspace export，也不会同步到其他工作区。

History depth 会保留最近回合的完整内容，其余保留回合改为可信的执行摘要：5 rounds 为 2 完整 + 3 摘要、10 rounds 为 4 + 6、20 rounds 为 8 + 12。若选 10 / 20 rounds 而目前模型 context window 偏小，介面会提示风险；这是提示，不会阻止你选择。

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

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

1. 在输入框内 Ctrl/Cmd+V 贴上剪贴簿中的图片（例如 BI 截图、错误画面）。
2. 图片会出现在输入框上方的待送缩图列（48×48）；点缩图右上角 × 可移除尚未送出的图片。
3. 可附加文字后按 Send；最多 4 张 图/则讯息。
4. 送出后，图片会显示在用户气泡内上方（48×48），文字在下方。
5. 点击已送出的缩图可开启大图预览；可放大／缩小（50%–300%）、复制图片，或关闭预览。

从 Reference Visual 复制图片： Agent 的 read_reference 只读 Markdown 文字与图片连结，看不到图像素。若需要 Agent（内建 Chat 或外部 Agent）实际看某一张图：

1. 开启 Reference，切到 Visual。
2. 在图片上右键 → Copy image。
3. 回到对话输入框 Ctrl/Cmd+V 贴上（外部 Agent 则贴到其聊天视窗）。

限制与说明：

• 仅当轮送给模型「看」图；之后对话轮次不会自动带上历史图片（若需再分析请重新贴图）。
• 若模型不支援 Vision，系统会提示；确认后可仅送文字（图片不会进模型，气泡中也不会保留缩图）。
• 已送出的讯息无法删除气泡内图片；重新产生（regenerate）含图讯息时仅重送文字。
• 尚未送出的图片会保留 24 小时 pending lease，不会因另一则 Agent stream 结束而被清除；按缩图 × 会立即释放该待送图片。

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

提示（SQL Server 大结果）： 对 SQL Server／Azure SQL，若远端估计超过 500,000 列，validate_query 可能回传 warning_required 与 warning_id；run_query／run_sql_tab 须在你确认后带 large_remote_warning_id 重试。Agent 会透过 ask_user 请你决定是否继续。

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

12.7 AI 提问互动（ask_user）

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

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

常见的 AI 提问场景：

• 「你想要快速分析，还是建立专案进行结构化分析？」（模式选择）
• 「请选择你偏好的分析执行模式：前台自动分析 / 混合模式」（Executing 阶段；Quick Analysis 另可选后台代理分析）
• 「确认要将 Plan 标记为已完成吗？此操作无法撤销。」
• 「有多个相关的表，你想优先分析哪一个？」
• 「探索配额已用尽，是否继续探索？」（选项：Continue exploring / Stop for now）
• Plan Grilling（口径对齐）： Plan 草案写完后、或分析方向大改时，Agent 一次只问一个决策（指标口径、分母、筛选边界、粒度等），并标出建议答案；你确认后共识会写进 Plan。这与上方「选模式／选表」同属 ask_user，但节奏固定为一次一题、先查可查事实再问决策。见 §2.5。

提示： AI 的提问会在对话气泡中以明显的互动区块呈现，与一般文字回复区分开来。如果你没有回答，AI 会等待你的回复而不会自行推进。超过 5 分钟未回复会自动超时。偏好里的 Clarifying questions（§15.3.1）调节一般澄清积极度；Grilling 则是 Plan 对齐的结构化流程，两者互补。

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）。

在讯息中引用工作区物件（beta）

在聊天输入框输入 @ 可开启最近使用的物件；继续输入名称会搜寻目前工作区。可引用：Project、Plan、Report、HTML Report、Reference、持久 SQL Tab，以及数据表／数据档。数据表涵盖 Cached、MCP 已物化表、已连线数据库表、初始／Additional／Cloud folder 中可查询的文件或工作表。选取后会插入不可拆开的 mention chip；Agent 会依物件的稳定识别资讯定位，不只依画面上的名称猜测。

• ↑／↓ 选择，Enter 或 Tab 插入，Esc 关闭清单并保留原本的 @文字。
• 每则讯息最多 10 个物件；可用 Backspace／Delete 整颗删除。
• 同一工作区复制贴上会保留可用的 chip；跨工作区或已删除／封存的物件会个别降级为纯文字，其余内容不受影响。
• Recent 只记录人工选取、开启与聚焦，不会因 Agent 背景操作改变；封存或失效物件不会继续出现在清单。
• 也可从侧边栏将支援的 Project、文件、持久 SQL Tab 或数据列拖曳到聊天输入框；若不便拖曳，在该列右键选 Add to chat。这两种方式都插入同一种可验证的 mention，不会自动开档、读取完整内容或提高 Agent 权限。External agent mode（Execute／Admin）启用时，数据表列的 Add to chat 改为 Copy table name，复制 SQL 编辑器可用的 quoted 表名。
• 把同一批侧边栏列（含工作区、Local data、Additional folder、Cloud folder、MCP Source、DB 连线与 Cached Data 父列）拖到外部 Agent 的输入框时，会带上一笔可解析的物件参照，让该 Agent 用既有 Lantide 工具对准该物件。Plan／Report／Reference 的第一跳是 read_artifact（读）与 open_artifact（在 Lantide 打开分页）；专名 read_plan／read_report／read_reference 仍可经长尾搜寻呼叫。拖回 Lantide 内建聊天时，工作区与上述来源／集合父列不会插入 mention；@ 清单也仍不能把整个 workspace 当成新 mention。
• 暂不支援在内建聊天直接提及整个 data source／workspace／Cache 集合、临时 SQL Tab、批注或 OS 文件；请改选其中的可查询表／文件，或以文字说明。来源与 Cached Data 父列可拖给外部 Agent 指定探索范围，但不提供 Add to chat，也不进入 @／Recent。
• 对外部 Agent 说「看看这个文件夹下的数据表」时，会先探索该来源的表清单，再按需求读 schema 或抽样。父列代表目前完整来源，不受侧栏搜寻结果限制；文件夹遵守既有载入／索引设定，Cloud folder 使用已保存的索引，Cached Data 代表目前可用快取。改绑路径／云端位置或 rename alias 后请重新拖移；空来源、不可用与索引缺失会分别说明，不会自动重新连线或提高权限。

若 @ 清单无法载入，可按 Retry；这不影响输入或送出纯文字。若送出时物件刚好已被删除／封存，该回合不会写入对话或启动 Agent，请移除失效 chip 或重新搜寻后再送出。关闭 feature flag 时，新讯息不提供物件候选，但既有对话仍会以 chip 或安全的文字 projection 显示。

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 上限，尽可能避免回应被截断。当遇到极端情况时，对话中会出现以醒目的琥珀色边框标示的警告讯息：

提示： 大多数情况下你不会看到这些警告。系统会在背景自动进行接续尝试，仅在自动接续仍无法完成时才显示警告。若长回复经常被截断，可在 Profile 提高 Max Output Tokens（§12.3），或缩短单次任务范围。

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

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

五种区块类型：

对话中的 fenced code block：

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

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

串流中的行为：

• Thinking 与 Tool Call 区块有最大高度限制，超出时会自动向下滚动并在底部加上渐层淡出效果，确保不会占据整个画面。
• 写作型工具参数跑字期间，小窗约显示三行并自动折行（不出现横向卷轴），内容持续增长时往下滚；工具结束后收合为一行摘要，展开详情时仍为可横向卷动的单行／预格式化检视。若你按 Stop，已显示的部分参数会保留在该 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 写入结果而阻挡撤回，并提示冲突；可选择 Revert anyway 强制覆写回本则开始前内容（会丢失之后的手动／其他 Agent 改动）。
• 停止生成： 中途 Stop 后，已成功写入的文件仍会出现变更条并可 Undo（含 HTML 多 chunk 部分完成的情况）。
• 新建档： Agent 在本则回复内新建的 Plan / Report / SQL tab / HTML，撤回时清空内容但保留文件与分页列（不删档、不关 tab）。
• add_report 连带： 若本则回复的 add_report 已使 Plan 进入 Executed，撤回该 Report 列时可能因 Plan 状态副作用而被阻挡（不可 force）；需依提示手动处理 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 工程。