ClickStack 的 AI 笔记本
AI Notebooks 是 ClickStack 中的一种交互式调查工具，将 AI 智能体与人工分析结合起来。您可以用自然语言描述问题，AI 智能体会代您查询日志、追踪和指标，并以一系列卡片的形式呈现相关数据、图表和摘要。您也可以在 AI 生成的输出旁添加自己的卡片 (图表、表格、搜索和 Markdown 注释) ，构建完整的调查记录。
AI Notebooks 仅在托管版 ClickStack 部署中可用。
设置
AI Notebooks 当前在 ClickHouse Cloud 中处于私有预览阶段。AI 模型和提供商由平台自动管理。
使用 AI Notebooks 之前：
- 启用 Generative AI — 团队管理员必须开启 Generative AI 同意开关。请参阅 启用 Generative AI。
- Notebook 访问权限 — 您的角色必须具有 Notebooks 的读写权限。
启用后，左侧边栏中会向所有具有相应角色的用户显示 Notebooks 条目。
启用生成式 AI
必须先由团队管理员启用生成式 AI 同意开关，之后才能使用笔记本 (及其他 AI 功能) 。
- 前往 Team Settings > Security Policies。
- 将 Generative AI 切换为开启状态。
- 查看并接受同意对话框。
使用 AI 笔记本
创建笔记本
- 在左侧边栏中选择 Notebooks。
- 点击 New Private Notebook (仅您可见) 或 New Shared Notebook (您的团队可见) 。
笔记本列表页面显示您可访问的所有笔记本。您可以按名称或标签筛选，也可以在 My Notebooks 和 All Notebooks 之间切换。
运行 AI 调查
在笔记本底部，输入一条提示，描述您想调查的内容——例如，"为什么过去一小时内 checkout 服务的错误率激增？"
按 Send (或按 Enter 键) 。AI 智能体将：
- 查看您可用的数据源。
- 针对您的日志、追踪和指标运行搜索与聚合查询。
- 生成一系列卡片，展示其思考过程、运行的查询、中间图表，以及包含结论的最终总结。
每个步骤都会以笔记本中的一个卡片显示。思考过程 卡片会展示每个查询背后的推理，输出 卡片则包含智能体的结论和可选图表。与普通的 AI 聊天不同，笔记本让您可以清楚看到 AI 在每一步具体基于哪些数据开展工作——这样您就可以验证其推理，发现它可能忽略的有价值线索，并通过分支功能将调查引导到不同方向。
调查运行期间，您可以点击 Stop 取消。
调查分支
在 AI 调查过程中，你可能会注意到某个中间步骤出现了有价值的线索，但 agent 已继续沿着另一条路径展开。分支功能可让你从该节点使用不同的提示重新开始，而不会丢失原始调查路径。
要创建分支：
- 展开一个思考过程图块，然后点击 Restart from Here。
- 在对话框中输入修改后的提示，将调查引导到新的方向。
- 点击 Interrupt & Create Branch。AI 会从该节点启动一个新的调查分支。
当一个图块包含多个分支时，图块头部会显示左右箭头按钮，以及一个徽标 (例如 1/2) 来指示分支数量。点击箭头即可在各个分支之间切换。
添加手动卡片
除了 AI 生成的卡片外，您还可以使用笔记本底部的按钮添加自己的分析区块：
| Button | Shortcut | Description |
|---|---|---|
| Search | S | 日志/链路搜索视图，等同于搜索页面。 |
| Chart | L | 时间序列折线图，使用与仪表板相同的可视化构建器。 |
| Table | T | 表格聚合视图。 |
| Markdown | M | 用于记录备注、假设或结论的自由文本。 |
添加卡片后，它会以内联编辑模式打开，您可以在其中配置数据源、筛选器和聚合——与构建仪表板可视化时使用的是同一界面。点击 Save 以保存并完成该卡片。
手动卡片会添加到当前分支中最后一个可见卡片的下方。您可以拖动卡片的底边来垂直调整其大小。
如果当前有 AI 调查正在运行，添加或编辑手动卡片会取消该调查。继续前会显示确认对话框。
共享与组织
- 私有与共享 — 切换笔记本标题栏中的锁形图标，即可在私有 (仅自己可见) 和共享 (团队可见) 之间切换。只有笔记本创建者才能修改此设置。
- 标签 — 为笔记本添加标签，便于在列表页面中筛选。
- 命名 — 点击笔记本标题即可重命名。如果你在一个未命名的笔记本中开始调查，AI 会自动建议一个名称。
自定义 agent 上下文
团队管理员可以提供额外的上下文，这些内容会包含在团队内每次 AI 笔记本 调查中。这有助于让 AI 了解你的系统架构、命名约定或已知问题等背景信息。
要进行配置：
- 在左侧边栏中进入 Notebooks。
- 打开 Agent Settings (仅团队管理员可用) 。
- 输入自定义上下文 (最多 50,000 个字符) 并保存。
对于团队中的所有 笔记本 调查，此上下文都会附加到 AI 的系统提示中。
