Notebook Intelligence

Notebook Intelligence

Notebook Intelligence（NBI）是面向 JupyterLab 的 AI 编码助手和可扩展 AI 框架。它提供聊天、内联编辑、自动补全功能，以及一个能够操作 Notebook 的 Agent；底层可使用 GitHub Copilot、兼容 OpenAI 或 LiteLLM 的端点、本地 Ollama 模型，或 Anthropic 的 Claude Code CLI。

NBI 免费且开源。你可以连接自己选择的免费或付费大模型提供商——GitHub Copilot、任何兼容 OpenAI 或 LiteLLM 的端点、本地 Ollama，或 Anthropic Claude（通过 Claude Code CLI）。如需付费，费用将直接支付给相应提供商。

目录

• 要求
• 快速开始
• 概念
• 功能亮点
  • Claude 模式
  • Agent 模式
  • ACP Agent 模式
  • Chatbook
  • 使用内联聊天生成代码
  • 自动补全
  • 聊天界面
  • 单元格输出操作
  • Notebook 工具栏生成
  • 多语言和内核感知 Notebook
  • 磁盘上的文件变更时重新加载已打开的文件
  • 使用你的语言回复
• 配置
  • 配置文件
  • 记住 GitHub Copilot 登录状态
• 内置工具
• Model Context Protocol（MCP）支持
  • MCP 配置示例
• 规则集
• Claude Skills
• Claude MCP 服务
• Claude 插件
• 聊天反馈
• 配置就绪情况
• 性能诊断
• 文档
• 延伸阅读
• 路线图
• 许可证

要求

• Python 3.10+
• JupyterLab 4.x
• Node.js — 用于 Claude 模式（Claude Code CLI）、ACP Agent 模式使用的预装 codex-acp 适配器，以及通过 npx 启动的 MCP 服务。ACP 模式要求适配器已预装在受信任的位置；NBI 不会在启动时下载适配器。
• 建议使用全新的 virtualenv 或 conda 环境，以免 NBI 与系统 Python 发生冲突。

快速开始

pip install notebook-intelligence
jupyter lab     # restart JupyterLab if it was already running

重启后：

1. 点击左侧边栏中的 NBI 图标，打开聊天面板。
2. 打开 NBI 设置（聊天面板中的齿轮图标，或 Settings → Notebook Intelligence Settings）。
3. 登录你的提供商——使用 GitHub Copilot 时，点击 Sign in；使用兼容 OpenAI 或 LiteLLM 的端点时，粘贴 API 密钥；使用 Ollama 时，指定本地守护进程。若要使用 Claude，请启用 Claude 模式（见下文）。
4. 在聊天面板中输入消息并按 Enter。

如果面板一直为空或登录操作没有反应，请参阅故障排除。

概念

这些文档中会引用到的一份简短术语表。

• 大模型提供商 — 运行模型的服务。NBI 内置四种提供商适配器：GitHub Copilot、OpenAI 兼容、LiteLLM 兼容和 Ollama。Anthropic Claude 通过 Claude 模式 提供，而不是作为顶层提供商。
• 聊天参与者 — 聊天面板中可通过 @mention 提及的角色（@workspace、@mcp……）。参与者将请求路由到特定的工具界面。
• 默认模式与 Claude 模式 — 默认 模式使用配置的大模型提供商进行聊天、内联聊天和自动补全。Claude 模式 使用 Claude Code CLI 处理聊天面板（获得其工具、技能、MCP 服务及自定义命令），并使用 Anthropic API 的 Claude 模型进行内联聊天和自动补全。需要在 PATH 中安装 Claude Code CLI。
• Claude Code 与 Anthropic API — Anthropic API（api.anthropic.com）是 NBI 在 Claude 模式下进行内联聊天和自动补全时直接调用的 HTTPS 端点。Claude Code 是 Anthropic 的本地 CLI Agent，NBI 通过 shell 调用它来处理聊天面板；它自行与 Anthropic 通信。
• MCP — Model Context Protocol。大模型调用外部工具（读取文件、访问 API、运行脚本）的一种方式。
• 规则集 — ~/.jupyter/nbi/rules/ 中的 markdown 文件，会被注入系统提示词，以强制执行约定、编码标准或领域规则。
• 技能：~/.claude/skills/（或 <project>/.claude/skills/）下的一个目录，包含 SKILL.md 及辅助文件。Claude 可以像调用作用域限定于工作区的可调用插件一样调用它。
• Claude 插件：为 claude plugin install 打包的单元，通过 marketplace 分发（通常是一个发布插件清单的 GitHub 仓库）。与 NBI 自身的 labextension 不同；插件在 Claude Code 会话中运行。

功能亮点

Claude 模式

NBI 为 Claude Code 集成提供了专用模式。在 Claude 模式下，NBI 使用 Claude Code CLI 驱动聊天面板，并使用 Claude 模型（通过 Anthropic API）提供内联聊天和自动补全建议。这会将 Claude Code 的工具、技能、MCP 服务和自定义命令引入 JupyterLab。

通过 NBI 设置对话框（聊天面板中的齿轮图标，或 设置 → Notebook Intelligence Settings）进行配置。开启 Enable Claude mode，然后：

• Chat model —— 用于聊天面板和内联聊天的 Claude 模型。
• Auto-complete model —— 用于自动补全建议的 Claude 模型。
• Chat Agent setting sources —— 用户、项目或两者，对应 Claude Code 的设置。
• Chat Agent tools —— 要启用哪些工具集。Claude Code tools 始终开启。Jupyter UI tools 是 NBI 自有的工具（编写 Notebook、运行单元格等）。
• API key 和 Base URL —— 指向 Anthropic 或可自托管的端点。
• Show turn usage：默认关闭。开启后，每个完成的轮次末尾会附上一行斜体脚注，给出该轮次的时长和 token 数量。仅当 NBI 使用直接的 Anthropic API 密钥连接到 Anthropic 自有端点时，才会显示 $ 费用数字：SDK 依据 CLI 内置的公开列表价格计价，这既不是订阅登录下的边际成本，也不是自定义 base_url 的费率，因此 NBI 宁可省略一个它无法担保的数字，也不显示误导性的数字。

模型默认值。 未选择模型时，聊天模型会解析为最新的 Sonnet（目前为 claude-sonnet-5），自动补全解析为最新的 Haiku，两者都与从所配置端点获取的模型列表进行匹配，而非使用硬编码 ID。如果配置的 ID 已不存在，NBI 会按版本在同一层级内回退，而非按字母顺序，因此 claude-sonnet-99 会解析为最新的 Sonnet。获取的列表按端点缓存，因此更改 Base URL 不会复用前一个端点的模型。自动补全响应上限为 1024 tokens，因为一条建议最多只有几十行；NBI_CLAUDE_INLINE_COMPLETION_MAX_TOKENS 可覆盖该上限，并被限制在 [1, 4096] 范围内。

如果 Claude Code CLI 位于 PATH 中，NBI 会自动启动它。要覆盖其位置，请在启动 JupyterLab 之前设置 NBI_CLAUDE_CLI_PATH 环境变量。

#### 权限模式

在 Claude 模式下，聊天输入框底部会显示一个盾牌图标按钮（位于发送按钮左侧），用于设置聊天面板中 Agent 的权限模式，与 Claude Code 和 Claude VS Code 扩展中的模式一致。点击它可选择：

• Default：Agent 想要执行的每次工具调用都会经过 NBI 的确认提示。你需要逐一批准或拒绝。这是初始模式。
• Accept Edits：Agent 所做的文件编辑会直接生效，无需逐次编辑确认；其他工具调用（运行命令等）仍会经过确认提示。适用于你信任编辑但仍希望对其他操作设一道关卡的迭代式工作。
• Plan：Agent 会进行研究并提出一个计划，不做任何更改，然后提交给你批准。批准后会运行该计划并将选择器恢复为 Default；拒绝则继续保持规划状态。此模式取代了旧的 /enter-plan-mode 斜杠命令。
• Bypass Permissions：每次工具调用都会跳过 NBI 的确认提示，包括在 Agent 子进程中运行的 Claude Code CLI 自带的 Bash / Write / Edit。Agent 将以你的完整账户权限运行所有操作，且没有任何确认，它读取的任何不受信任的内容都可能影响其运行内容。请参阅下方的管控说明。

Default、Accept Edits 和 Plan 在你选择的瞬间就会切换。所选模式会随你发送的每条消息一同传递，并在该轮运行前应用于 Agent；对话中途切换会在你的下一条消息生效。

Bypass Permissions 从不持久化：启动新的聊天会话（或 /clear）总会将其清除，必须手动重新启用。其他模式在重置后会保留，新的 Claude 客户端的初始模式为 Default（或管理员设定的 permissions.defaultMode）。

选择 Bypass Permissions 不会立即启用它。它会打开一个确认步骤；只有在你确认后绕过才会生效，并且在其激活期间，盾牌图标会变为红色警告图标作为持续指示。每次会话都必须重新启用绕过：启动新聊天或重启 Claude 客户端都会回到 Default。而且由于服务器会在每条消息上重新检查所请求的模式，已启用的绕过永远无法超越管理员此后关闭的策略。

管理员管控。 Bypass Permissions 默认关闭，除非管理员启用，否则在选择器中隐藏：它受 claude_bypass_permissions 策略（NBI_CLAUDE_BYPASS_PERMISSIONS_POLICY）管控，这是三个管理员策略之一，其默认值为 force-off 而非 user-choice（另外两个分别控制实验性 ACP Agent 模式和 ACP 完整访问）。所请求的模式还会在服务器端对每条消息进行钳制，因此无法通过手工构造的请求绕过此管控。此外，NBI 遵循 Claude Code 的企业托管设置：无论 NBI 策略如何，permissions.disableBypassPermissionsMode 都会移除该选项，而 permissions.defaultMode 设置选择器的初始模式（Bypass 除外，因为它从不自动启用）。请参阅管理员指南中的允许绕过权限。

/enter-plan-mode 和 /exit-plan-mode 斜杠命令在手动输入时仍然有效，但不再出现在自动补全中；选择器取代了它们，并将在未来版本中淘汰这些命令。

恢复之前的 Claude 会话

当 Claude 模式开启时，聊天侧边栏会在齿轮图标旁显示一个历史图标。点击它会列出为当前工作目录记录的 Claude Code 会话（即 Claude Code CLI 存储在 ~/.claude/projects/ 下的相同转录记录）。选择某个会话会通过 resume 重新连接，因此你发送的下一条消息会带着完整的先前上下文继续该转录记录。齿轮旁的 New chat session 按钮会在不输入 /clear 的情况下重启 SDK 客户端。

较长的 Claude 轮次会显示已用时间计数器，并在 30 秒后以心跳驱动的脉冲及 "may be slow" 文案翻转进行提示。Agent 运行的每个工具都会以持久状态卡片的形式显示，带有类型图标和实时的进行中 / 已完成 / 失败状态；编辑会附带内联 diff，一连串连续的调用会折叠为一个可展开的分组，因此侧边栏能反映 Agent 正在做什么，而不是看起来卡住了。

在 Claude 模式下，作为聊天上下文附加的工作区文件以 @ 提及指针的形式到达，而非内联文件内容。Claude 的 Read 工具会按需获取它们，这意味着图片、大文件和 notebook（可感知单元格）现在都能正常工作，而旧的内容注入路径会静默截断或跳过它们。

用量页脚

在 Settings 对话框中启用 Show usage after each turn，即可在每条 Claude 模式回复下方附加一个小页脚，显示该轮次的时长、token 数量（含缓存输入的细分）以及成本——例如 12.3s · 45.2K in (38.1K cached) / 1.2K out · $0.0842。该功能默认关闭。

成本数字来自 Claude Code CLI，依据 Anthropic 的公开目录价格计算。仅当 NBI 配置了默认端点上的直接 Anthropic API 密钥时才会显示，否则会省略——在订阅登录（边际成本实际上为 $0）、企业协商合同或自定义 Base URL（代理、网关或非 Anthropic 端点）的情况下——因为目录价格数字不会与你的实际账单相符。时长和 token 数量始终显示。

Claude Code 启动器磁贴

当 Claude CLI 位于 PATH 中时，JupyterLab 启动器（随新标签页打开的面板）会在标准内核启动器旁显示一个 Claude Code 磁贴。点击它会打开会话选择器；可搜索过往转录记录并在新终端中恢复其中一个，或在文件浏览器的活动子目录中启动新会话。会话 ID 可从选择器中复制，以便粘贴到 claude --resume <id> 命令中。

其他编码 Agent 启动器磁贴

当以下任一 CLI 位于 PATH 中时，启动器会为每个添加一个磁贴。点击磁贴会在文件浏览器的当前目录打开终端并运行该 CLI：

• opencode（用 NBI_OPENCODE_CLI_PATH 覆盖路径）
• Pi（用 NBI_PI_CLI_PATH 覆盖路径）
• GitHub Copilot CLI（用 NBI_GITHUB_COPILOT_CLI_PATH 覆盖路径）
• OpenAI Codex（用 NBI_CODEX_CLI_PATH 覆盖路径）

磁贴会随着 CLI 变得可用或不可用而自行添加和移除；它们不要求 Claude 模式。点击任何磁贴（或 Claude 恢复对话框中的 New Session）都会提示输入起始目录，因此终端会在你希望的位置打开，而不是始终在文件浏览器的 cwd。

Agent 模式

在 Agent 模式下，内置 AI Agent 会以交互方式为你创建、编辑和执行 notebook。它可以检测单元格中的问题并修复它们。

ACP Agent 模式

一种实验性的第二 Agent 模式，通过 Agent Client Protocol 驱动外部编码 Agent，目前仅支持 OpenAI Codex。该 Agent 以子进程形式运行，自行处理文件和命令，并通过 NBI 的确认卡片请求批准；NBI 不会将 Jupyter 服务的文件系统或终端提供给它。

此模式默认关闭，只有管理员允许后才会显示 Settings 标签页，并且不能与 Claude 模式同时使用。请参阅 docs/acp.md。

Chatbook

Chatbook 是一种可以用英文编写单元格的笔记本。运行提示词单元格会为笔记本的后端内核生成代码并运行；每个单元格都有徽标，标明它是提示词（NL）还是普通代码（Cd），按 Ctrl J 可在两者之间切换。

生成的代码运行前如何处理，由你选择：始终确认（默认选项）会显示代码并等待确认；有风险时确认仅在扫描发现破坏性调用时等待；自动运行则会立即执行。管理员可以在整个部署范围内限制此选项，也可以完全关闭 Chatbook。

提示词可以通过 @ 提及引入上下文，规则对生成过程的约束方式与对聊天的约束方式相同，后端内核不必是 Python。需要将结果而非提示词交给其他人时，可以把 Chatbook 导出为普通代码笔记本；现有笔记本也可以转换为 Chatbook。请参阅 docs/chatbook.md。

使用内联聊天生成代码

使用单元格工具栏上的闪光图标或键盘快捷键，显示内联聊天弹出框。

Ctrl+G / Cmd+G 可打开弹出框。Ctrl+Enter / Cmd+Enter 可接受建议。Esc 可关闭弹出框。接受建议的快捷键仅在弹出框打开时覆盖 JupyterLab 默认的 运行单元格 快捷键绑定；在弹出框外，Ctrl+Enter / Cmd+Enter 仍会运行当前活动单元格。

自动补全

输入时会显示自动补全建议。建议显示时按 Tab 可接受建议，否则会缩进。NBI 在代码单元格和 Python 文件编辑器中提供自动补全。

聊天界面

你可以在聊天提示词中粘贴或附加图片；如果当前模型支持视觉能力，图片会作为输入发送给模型。

单元格输出操作

右键单击单元格输出（或将鼠标悬停以显示工具栏），即可将其直接作为上下文发送到聊天中：

• 解释单元格错误 — 在发生错误的单元格上显示“排查输出中的错误”选项；打开聊天轮次并附上回溯信息。
• 询问单元格输出 — 将输出作为结构化上下文附加，以供后续提问。对于支持视觉能力的模型，也会包含图片。
• 显示输出工具栏 — 在每个输出上方显示浮动工具栏，其中提供快捷的解释 / 询问 / 排查操作。

每项功能均可由用户在 Settings 中单独切换（保存为 config.json 中的 enable_explain_error、enable_output_followup、enable_output_toolbar，默认开启），管理员也可通过 NBI_EXPLAIN_ERROR_POLICY / NBI_OUTPUT_FOLLOWUP_POLICY / NBI_OUTPUT_TOOLBAR_POLICY 锁定设置。

如果文档的内核正忙，则会跳过还原操作，因此执行过程中产生的更改会在单元格运行结束后应用，而不会在执行期间替换内容；只有在你正在查看的文档中，才会显示标明重新加载文件的通知。

笔记本工具栏生成

活动笔记本的工具栏上会显示闪光图标。点击该图标可打开弹出框，将生成请求限定到该特定笔记本，适合在多笔记本会话中使用，以免聊天侧边栏争用上下文。

多语言和内核感知型笔记本

创建笔记本、插入单元格和内联生成时，会遵循你当前使用的笔记本，而不是默认假设使用 Python。NBI 会解析活动笔记本的内核和语言，并将两者贯穿于聊天上下文、内置工具和规则集的作用范围中，因此生成的代码会匹配目标笔记本；作用于 languages: ['r'] 或 kernel_names: ['ir'] 的规则也会在预期位置生效（包括此前未获取内核信息的内联生成）。

当 Agent 需要使用当前上下文尚未确定的语言创建笔记本时，它会调用 list-available-notebook-kernels 工具，并从实际已安装的内核规范中选择，而不是猜测名称。现在，如果请求的内核未安装，操作会报出清晰的错误，而不会悄悄生成 Python 笔记本。

磁盘文件更改时重新加载打开的文件

当文件在磁盘上发生更改时，NBI 会重新加载已打开的文档标签页，因此 AI Agent 通过读取/写入工具所做的编辑会显示在编辑器中，无需手动刷新。未保存本地编辑的标签页会跳过，以免覆盖用户的工作。可通过 NBI Settings dialog → External changes → "Refresh open files when changed on disk" 切换（默认开启）。

使用你的语言回复

当 JupyterLab 通过语言包设置为其他语言时，开启 NBI Settings dialog → Language → "Reply in my JupyterLab language"（默认关闭），即可让 AI 使用该语言撰写聊天回复和 Chatbook 单元格描述，适用于所有聊天模式（已配置的提供商、Claude 和 ACP Agent）。代码、标识符、文件名和文件内容保持不变。发送给模型的语言名称采用其 JupyterLab 语言包的英文名称（"German (Germany)"）；当 JupyterLab 使用英语或该设置关闭时，提示词不会改变。在 Claude 和 ACP 模式下，该指令会随每条消息发送，而不是作为斜杠命令发送；关闭该设置后，对话仍会遵循此指令，直到你开始新的聊天。

配置

在 NBI Settings 中配置提供商、模型和 API 密钥——可通过聊天面板中的齿轮图标、/settings 聊天命令或 JupyterLab 命令面板打开。背景信息请参阅提供商博客文章。

配置文件

NBI 将配置保存在 ~/.jupyter/nbi/config.json。它还支持环境级基础配置文件 <env-prefix>/share/jupyter/nbi/config.json——组织可以在此提供默认配置，用户的更改则作为覆盖项保存在其上。

这些配置文件会保存提供商、模型和 MCP 配置。自定义大模型提供商的 API 密钥也会以明文形式保存在这里——切勿将 ~/.jupyter/nbi/config.json 提交到 git、分享或在用户之间同步。如果密钥泄露，请立即在提供商处更换。

手动编辑 config.json 后，必须重启 JupyterLab 才能生效。通过 Settings 对话框进行的编辑会实时生效。

管理员策略

组织管理员可以锁定设置面板中的大多数切换项。策略分为两种形式：

布尔策略使用 *_POLICY 后缀，并接受三个值：user-choice（默认值——用户可自由切换）、force-on（锁定为启用）和 force-off（锁定为禁用）。强制设置时，面板控件会被禁用，并显示“已被管理员锁定”提示；任何客户端写入都会被忽略。

环境变量	锁定 Settings 面板中的控件
NBI_EXPLAIN_ERROR_POLICY	"Explain cell errors"
NBI_OUTPUT_FOLLOWUP_POLICY	"Ask about cell outputs"
NBI_OUTPUT_TOOLBAR_POLICY	"Show output toolbar"
NBI_CLAUDE_MODE_POLICY	"Enable Claude mode"
NBI_ACP_MODE_POLICY	"Enable ACP mode"（基于 Agent Client Protocol 的实验性 Agent 模式，Codex 是首个 Agent 类型；默认为 force-off，设置为 user-choice 可允许启用）
NBI_ACP_FULL_ACCESS_POLICY	ACP Agent 的 "Full access"：无需询问即可编辑工作区文件并运行命令，运行于 Codex 的 workspace-write 沙箱内，除非 Codex 的配置启用网络访问，否则网络访问关闭（默认为 force-off，因此除受信任的只读命令外，Agent 在执行任何操作前都会先询问；user-choice 允许用户选择启用无人值守运行）
NBI_CLAUDE_CONTINUE_CONVERSATION_POLICY	"Remember conversation history"
NBI_CLAUDE_CODE_TOOLS_POLICY	"Claude Code tools"
NBI_CLAUDE_JUPYTER_UI_TOOLS_POLICY	"Jupyter UI tools"
NBI_CLAUDE_SETTING_SOURCE_USER_POLICY	Setting source: User
NBI_CLAUDE_SETTING_SOURCE_PROJECT_POLICY	Setting source: Project
NBI_STORE_GITHUB_ACCESS_TOKEN_POLICY	"Remember my GitHub Copilot access token"
NBI_SKILLS_MANAGEMENT_POLICY	Skills 标签页（force-off 会将其隐藏并对 API 返回 403；同时禁用 managed-skills reconciler）
NBI_CLAUDE_MCP_MANAGEMENT_POLICY	Claude 模式的 MCP Servers 标签页（force-off 会将其隐藏并对 /claude-mcp/* 返回 403；与非 Claude 的 MCP Servers 标签页相互独立）
NBI_CLAUDE_PLUGINS_MANAGEMENT_POLICY	Claude 模式的 Plugins 标签页（force-off 会将其隐藏并对 /plugins/* 返回 403）
NBI_CLAUDE_BYPASS_PERMISSIONS_POLICY	Claude 权限模式选择器中的 "Bypass Permissions"（默认为 force-off，NBI_ACP_MODE_POLICY 和 NBI_ACP_FULL_ACCESS_POLICY 也是如此；user-choice 会显示该选项，用户仍需在每个会话中手动启用）
NBI_TERMINAL_DRAG_DROP_POLICY	终端拖放文件附加功能
NBI_REFRESH_OPEN_FILES_ON_DISK_CHANGE_POLICY	"Refresh open files when changed on disk"
NBI_CHATBOOK_POLICY	Chatbook 自然语言 notebook 单元格（force-off 会隐藏内核、启动器磁贴、Settings 标签页和命令，并对 generate 和 mention API 返回 403）
Chatbook 的 NL 执行有单独的上限（不是布尔策略）：

环境变量 / traitlet	效果
NBI_CHATBOOK_MAX_EXECUTION_MODE	用户不能选择比此更宽松的 Chatbook 模式。取值：always-confirm、confirm-if-risky、auto-run（默认，无上限）。

对应的 traitlets 是 c.NotebookIntelligence.chatbook_policy 和 c.NotebookIntelligence.chatbook_max_execution_mode。参见 docs/chatbook.md。

前三项在 NotebookIntelligence 上也有对应的 traitlets（explain_error_policy、output_followup_policy、output_toolbar_policy）；其余项可按需以相同形式添加：

c.NotebookIntelligence.claude_mode_policy = "force-on"
c.NotebookIntelligence.claude_jupyter_ui_tools_policy = "force-off"

每用户偏好设置（单元格输出相关功能默认开启）位于 config.json 中，分别为 enable_explain_error、enable_output_followup、enable_output_toolbar。

列表形式的拒绝名单（LLM 提供商、内置工具、编码 Agent 启动器磁贴）使用 traitlets，而非 *_POLICY 环境变量。有关 disabled_providers、disabled_tools 和 disabled_coding_agent_launchers 的配置示例，参见 docs/admin-guide.md。

针对非布尔设置的取值存在性锁定：将环境变量设为非空值会将对应控件固定为该值并禁用。空值/未设置 = 由用户选择。

环境变量	固定项
NBI_CHAT_MODEL_PROVIDER	General → Chat model → Provider
NBI_CHAT_MODEL_ID	General → Chat model → Model
NBI_INLINE_COMPLETION_MODEL_PROVIDER	General → Auto-complete model → Provider
NBI_INLINE_COMPLETION_MODEL_ID	General → Auto-complete model → Model
NBI_CLAUDE_CHAT_MODEL	Claude → Chat model（以及 Inline chat model，除非另行固定）
NBI_CLAUDE_INLINE_CHAT_MODEL	Claude → Chat model → Inline chat model
NBI_CLAUDE_INLINE_COMPLETION_MODEL	Claude → Auto-complete model
ANTHROPIC_API_KEY	Claude → API Key（输入被锁定并清空；SDK 直接读取环境变量）
ANTHROPIC_BASE_URL	Claude → Base URL
NBI_ACP_CHAT_MODEL	ACP → Chat model
OPENAI_API_KEY	ACP → API Key（输入被锁定并清空；Agent 直接读取环境变量）
OPENAI_BASE_URL	ACP → Base URL

Inline chat 直接调用 Anthropic API，而其他 Claude 模式则通过 Claude Code CLI，因此一次部署可能对每种模式需要不同的 model id。它使用 inline_chat_model，当该项未设置时回退到 chat_model。因此 NBI_CLAUDE_CHAT_MODEL 同时管控这两个界面：当它被设置时，存储的 inline_chat_model 会被忽略，其控件也会被禁用。同时设置 NBI_CLAUDE_INLINE_CHAT_MODEL 可将 inline chat 固定为不同的模型 —— 它具有更高优先级，且不会重新启用任何内容，因此两个界面都保持由管理员控制。 NBI_ACP_AGENT_COMMAND（不受设置锁定）用于通过绝对可执行文件路径选择已安装的适配器，例如 /opt/nbi/acp/bin/codex-acp；其值会按 Shell 规则拆分，因此包含空格的路径需要加引号。请将其指向已安装的适配器本身，而不是 npx、npm exec、pnpm dlx、bunx 或 env 包装器：即使将包运行器的路径设为绝对路径，也无法阻止它从项目中选择代码。对于 Codex，适配器必须遵循 NBI 附加的 -c 审批和沙箱选项。设置覆盖项属于管理员的信任决策，涉及命令、其运行时和软件包、继承的 PATH 以及它们的父目录。

将覆盖项留空，以便在 Jupyter 工作区之外的绝对服务端 PATH 目录中发现预装的 codex-acp。空值或仅包含空白字符的值会导致错误；在 POSIX Shell 中使用 unset NBI_ACP_AGENT_COMMAND 可恢复默认发现行为。NBI 会在启动前解析符号链接；依赖名称 codex-acp 的 shim 的安装方式需要显式指定该受信任 shim 的绝对路径。默认启动时会从 Agent 及其命令继承的 PATH 中移除工作区目录，这可能会排除项目的 .venv/bin；显式设置覆盖项则会保留完整的服务端 PATH。请安装经过测试的 @zed-industries/[email protected] 并自行维护该版本：对于这两种发现方式，NBI 都不会验证或更新版本。有关具体安装命令、主目录工作区布局，以及 Windows 搭配 Python 3.10 或 3.11 时必须显式指定适配器路径的要求，请参阅适配器安装和迁移指南。

提供商 ID：github-copilot、openai-compatible、litellm-compatible、ollama、none。*_MODEL_ID 的值取决于所选提供商公开的内容（例如 gpt-4o、llama3:latest）。Claude 模型 ID 必须是 Anthropic API 中的字面 ID（例如 claude-opus-4-7、claude-sonnet-4-6）；空字符串 =“默认（推荐）”；NBI_CLAUDE_INLINE_COMPLETION_MODEL 还接受 none（Claude 模式下不提供行内补全）或 inherit（使用“常规”选项卡中的“自动补全”模型）。

上传可调参数控制聊天侧边栏文件附件和终端拖放共用的上传端点：

环境变量	默认值	行为
NBI_UPLOAD_MAX_MB	50	单个文件的大小上限，单位为 MB。超出上限的请求会返回 HTTP 413。设为 0 可完全禁用上限。
NBI_UPLOAD_RETENTION_HOURS	24	暂存上传文件在临时目录中的保留时长，之后会在下一次上传时清理。设为 0 则仅在退出时清理（上传文件会保留到会话结束）。

也可以通过 NotebookIntelligence 上的 upload_max_mb 和 upload_retention_hours traitlets 配置相同的值。

记住 GitHub Copilot 登录状态

NBI 可以记住你的 GitHub Copilot 登录状态，这样 JupyterLab 或系统重启后就不必重新登录。

注意

如果启用此功能，NBI 会加密令牌并将其存储在 ~/.jupyter/nbi/user-data.json 中。切勿分享此文件。除非将 NBI_GH_ACCESS_TOKEN_PASSWORD 设置为自定义值，否则加密会使用默认密码——在共享或多租户系统上，请先设置自定义密码，再启用此选项。

NBI_GH_ACCESS_TOKEN_PASSWORD=my_custom_password

要启用此功能，请在设置对话框中勾选 记住我的 GitHub Copilot 访问令牌。

如果存储的令牌无法通过身份验证（已过期、已撤销或密码不匹配），NBI 会提示你重新登录。

内置工具

这些工具可在 Agent 模式和支持 MCP 的聊天中使用。

工具	功能
Notebook 编辑 (nbi-notebook-edit)	通过 JupyterLab 笔记本编辑器编辑笔记本。
Notebook 执行 (nbi-notebook-execute)	在 JupyterLab 界面中运行笔记本。
Python 文件编辑 (nbi-python-file-edit)	通过 JupyterLab 文件编辑器编辑 Python 文件。
文件编辑 (nbi-file-edit)	编辑 Jupyter 根目录中的文件。
文件读取 (nbi-file-read)	读取 Jupyter 根目录中的文件。
命令执行 (nbi-command-execute)	使用 Agent 界面中的嵌入式终端或 JupyterLab 终端执行 shell 命令。

在多租户部署中，nbi-command-execute 和 nbi-file-edit 实际上允许以用户身份执行任意代码。有关如何禁用这些工具的指南，请参阅 docs/admin-guide.md。

模型上下文协议（MCP）支持

NBI 可与 MCP 服务集成。它支持 stdio 和 Streamable HTTP 两种传输方式。支持工具和提示词；不支持资源。 服务的提示词会显示在聊天输入框的斜杠命令自动补全中，格式为 /mcp:<server>:<prompt>。

编辑 ~/.jupyter/nbi/mcp.json 以添加 MCP 服务。也支持使用环境范围的基础配置文件 <env-prefix>/share/jupyter/nbi/mcp.json。

说明

MCP 需要具备工具调用能力的大模型。NBI 支持所有 GitHub Copilot 模型。对于其他提供商，请选择具备工具调用能力的模型。

注意

大多数 MCP 服务与 JupyterLab 运行在同一台机器上，并且可能会进行不可逆更改或访问私有数据。请仅安装来自可信来源的 MCP 服务。

MCP 配置示例

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/mbektas/mcp-test"
      ]
    }
  }
}

对于 stdio 服务，可以在 env 下传递额外的环境变量：

"mcpServers": {
    "servername": {
        "command": "",
        "args": [],
        "env": {
            "ENV_VAR_NAME": "ENV_VAR_VALUE"
        }
    }
}

对于 Streamable HTTP 服务，还可以指定请求标头：

"mcpServers": {
    "remoteservername": {
        "url": "http://127.0.0.1:8080/mcp",
        "headers": {
            "Authorization": "Bearer mysecrettoken"
        }
    }
}

要临时禁用已配置的服务而不将其移除，请设置 "disabled": true：

"mcpServers": {
    "servername2": {
        "command": "",
        "args": [],
        "disabled": true
    }
}

规则集

NBI 的规则集系统允许你定义指南和最佳实践，并自动注入 AI 提示词，以保持编码标准、项目约定或领域知识的一致性。规则是存放在 ~/.jupyter/nbi/rules/ 中的 Markdown 文件，可以按文件模式、内核、目录或模式（ask、agent、inline-chat、chatbook）进行限定。

一个两行示例：

---
priority: 10
---

- Always use type hints in Python functions.
- Add docstrings to all public functions.

完整详情（frontmatter 参考、特定模式的规则、自动重新加载），请参阅 docs/rulesets.md。

Claude 技能

设置面板提供顶级的 技能 选项卡，用于管理 Claude 可以调用的技能。技能存储在 ~/.claude/skills/（用户级）或 <project>/.claude/skills/（项目级）下。你可以直接创建和编辑技能、复制、重命名、删除（可撤销），或从公开的 GitHub 仓库导入。此选项卡在任何模式下都会显示；关闭 Claude 模式时，会显示提示横幅，说明技能仅在 Claude 会话中生效（方便你现在编写技能，并在之后开启 Claude 模式时使用）。

对于组织范围的部署，管理员可以通过设置 NBI_SKILLS_MANIFEST 下发精选的技能清单，并使其保持同步。通过这种方式安装的技能会标记为 托管，且在 UI 中为只读。若管理员希望保留托管技能，同时禁止临时从 GitHub 导入，可使用 NBI_ALLOW_GITHUB_SKILL_IMPORT=false。

完整详情请参阅 docs/skills.md。

Claude MCP 服务

启用 Claude 模式且 Claude CLI 可用时，设置面板会提供 MCP 服务 选项卡，用于管理 Claude Code 从 ~/.claude.json 和项目的 .mcp.json 中读取的用户级、项目级和本地范围的 MCP 条目。这与 NBI 自带的 MCP 服务选项卡不同（后者管理非 Claude 聊天路径使用的服务）；两个选项卡不会同时出现，设置对话框会显示与你当前模式对应的选项卡。

读取操作直接从 Claude 的 JSON 配置文件中进行。写入操作（添加和移除）会调用 claude mcp add 和 claude mcp remove，以便由 Claude 负责处理所有副作用（项目信任提示、OAuth 记录）。每个服务条目都可以按工作区启用或停用，而无需移除；添加 MCP 服务对话框支持粘贴 JSON，通过 Claude / Cursor / VS Code MCP 配置内容预填表单，并会先验证其格式。管理员可以通过 NBI_CLAUDE_MCP_MANAGEMENT_POLICY=force-off 锁定此选项卡。

Claude 插件

启用 Claude 模式且 Claude CLI 可用时，设置面板会提供 插件 选项卡，通过 claude plugin 执行安装、卸载、启用、停用和添加市场操作（例如：从 GitHub 仓库添加市场，然后安装其发布的插件）。每个已安装插件的描述、作者、版本和来源都会直接显示；当上游有更新版本时，此选项卡会显示该插件专属的 更新 按钮。市场选择器可让你浏览已配置的市场并直接从中安装插件。托管在 GitHub 上的市场会沿用 Skills 导入时相同的 GITHUB_TOKEN / GH_TOKEN / gh auth token 优先级；令牌通过环境变量传递给子进程，不会出现在 argv 或 DEBUG 日志中。关于插件的定义和市场的运作方式，请参阅 Anthropic 的插件文档。

管理员可以通过 NBI_CLAUDE_PLUGINS_MANAGEMENT_POLICY=force-off 锁定整个选项卡，也可以保留此选项卡，只禁止从 GitHub 来源的市场导入插件，方法是设置 NBI_ALLOW_GITHUB_PLUGIN_IMPORT=false。

聊天反馈

通过设置以下内容，启用对 AI 回复的点赞/点踩反馈：

c.NotebookIntelligence.enable_chat_feedback = True

……或通过 CLI 设置：

jupyter lab --NotebookIntelligence.enable_chat_feedback=true

反馈会在进程内触发 telemetry 事件。默认情况下，不会有任何数据离开进程。关于完整的 telemetry 事件列表以及如何将其接入可观测性技术栈，请参阅管理员指南。

默认情况下，悬停时才会显示点赞按钮。若要让按钮始终可见，请启用：

c.NotebookIntelligence.enable_chat_feedback_always_visible = True

## 配置就绪状态

NBI Settings 打开时会显示一张状态卡片，用来回答一个问题：此部署是否已配置好并能正常工作？如果不能，具体缺少什么？每项检查都会报告 ok、warn 或 blocked，任何状态不是 ok 的检查都会说明后续操作，而不只是指出问题（“未找到 claude CLI”，并给出“安装它，或设置 NBI_CLAUDE_CLI_PATH 后重启”）。

打开时就会运行这些检查，且不产生费用：解析你的提供商和模型，检查模型列表是否可访问，以及所选模型是否确实由该端点提供；通过 --version 检查 Claude CLI；并检查 ACP 的适配器可执行文件，但不会运行它。两种 Agent 模式都会检查凭据是否存在。缺少密钥只会发出警告，而不会报错，因为 Claude CLI 和 ACP Agent 可以使用各自的订阅登录信息，而 NBI 无法查看这些信息。

测试端点会先征求确认，然后向你配置的模型发送一条简短请求。这是唯一能发现以下两种问题的方式，其他成本更低的检查都无法发现：网关返回 200 响应，却只缓冲内容而不进行流式传输；代理移除了 tools 字段，导致 Agent 模式悄无声息地从不调用工具。不会保留模型输出，因此可以放心将结果粘贴到支持工单中。

此按钮是唯一会产生费用的就绪检查，因此可以通过以下开关禁用：NBI_READINESS_LIVE_CHECK=off（traitlet readiness_live_check_allowed，默认开启）；禁用后会拒绝该项检查，但其他所有检查仍可使用。每台服务一次只能运行一项实时测试；如果有第二个并发请求，将返回 429，而不会消耗令牌。

性能诊断

一种可选启用的模式，用于回答“这一轮的时间花到哪里去了”，面向那些 NBI 感觉比应有的速度慢的部署场景：内部 LLM 网关、网络主目录、TLS 拦截代理。默认关闭，关闭时每个埋点位置的开销仅为一次布尔检查。

开启它。 NBI 设置，Performance 标签页，Enabled。立即生效，无需重启。

解读一轮对话。 每个聊天轮次都会记录一条阶段时间线（规则与上下文准备、Agent 连接与启动、首个 token 的耗时、带停顿事件的流式输出、工具调用、等待你的时间），外加 token 计数和 SDK 报告的 API 耗时。表格显示最近的轮次，每行一轮，并带有一列 Verdict，指明占主导地位的阶段。最重要的对比是 Active 与 API ms：两者接近意味着时间花在网关或模型上，相差较大则意味着花在本地。展开一行会将该轮次的各个 span 显示为成比例的条形图及其属性。每个轮次还会在 Jupyter 服务器日志中汇总为一行 perf turn ... INFO 日志，因此无头安装也能获得相同的信号，无需 UI。

解读环境。 Run probe 测量的是机器而非某一轮对话：配置目录和 ~/.claude 目录的文件系统延迟与吞吐量（含文件系统类型和挂载选项）、解释器和 CLI 的冷启动开销，以及进程和主机争用情况。结果按组分类并分级，因此缓慢的网络文件系统或被限流的容器会以一句话被明确指出，而不是留在一个 JSON blob 里。一个可选启用的网络检查会增加对已配置端点的连接，以测量 DNS、TCP 和 TLS 耗时，并捕获所呈现的证书链，这正是让 TLS 拦截变得可见的原因。它会先请求确认，并指明将要联系的主机。

隐私。 会记录：耗时、计数、字节大小、状态枚举、token 计数，以及工具、服务、模型和提供方名称。绝不记录：提示词或响应文本、文件内容、绝对路径、环境变量值、API 密钥、异常消息或主机名。这由一份固定的逐属性允许列表强制执行，而非依靠约定，并且默认的 redacted 详细级别还会额外对文件基名以及模型、工具和服务名称进行哈希处理。

跨会话收集。 轮次可以选择性地以 JSON Lines 形式追加到 <nbi-dir>/perf/，并按大小和时长上限进行保留。在网络主目录上，可通过 NBI_PERF_LOG_DIR 将日志指向本地暂存目录。

完整指南，包括 span 与事件参考、探针阈值、针对缓慢网关、缓慢主目录和拦截代理的实际诊断案例，以及 JSONL schema：docs/performance-diagnostics.md。

环境变量	作用
NBI_PERF_DIAGNOSTICS	将启用状态锁定为开或关（值锁定；UI 会将开关显示为已锁定）。
NBI_PERF_DIAGNOSTICS_POLICY	user-choice（默认）、force-off 或 force-on（全组织范围收集，强制使用已脱敏的属性）。
NBI_PERF_PROBE_NETWORK	off 仅禁用探针的网络检查，其余功能仍然可用。
NBI_PERF_LOG_DIR	重定向 JSONL 性能日志目录。

文档

• docs/admin-guide.md — 部署、环境变量、安全模型、气隙环境、多租户。
• docs/skills.md — Claude Skills 管理和 org-manifest 协调器。
• docs/rulesets.md — 规则集 frontmatter 和发现机制。
• docs/acp.md — 使用实验性的 ACP Agent 模式及其限制。
• docs/chatbook.md：编写 Chatbook 单元、执行模式、转换和导出，以及为何没有单元级沙箱。
• docs/chatbook-extensions.md — 动态 Chatbook 上下文和提及提供程序。
• docs/troubleshooting.md — 常见问题及可直接复制粘贴的解决方法。
• docs/performance-diagnostics.md：轮次时间线、环境探测工具，以及如何解读两者。
• docs/translating.md：使用本地语言的 NBI，以及修复或添加翻译。
• PRIVACY.md — NBI 会向哪些提供商发送什么内容，以及出口允许列表。
• SECURITY.md — 如何报告漏洞。
• CHANGELOG.md — 发布历史。
• CONTRIBUTING.md — 从源代码构建 NBI。如果你只想使用 NBI，请跳过此文档。

延伸阅读

• Notebook Intelligence 介绍！
• 为 JupyterLab 构建 AI 扩展
• 为 JupyterLab 构建 AI Agent
• Notebook Intelligence 现已支持任意 LLM 提供商和 AI 模型！

路线图

NBI 6.x 是当前版本系列。新功能会在次要版本中推出（6.1、6.2……）；重大变更仅在主版本中引入，并会在更新日志中公布。6.0 标志着 Chatbook 的推出，没有重命名或移除任何 traitlet、环境变量、REST 路由或磁盘格式。使用实验性 ACP 模式的部署现在必须预先安装其适配器；请参阅迁移指南。要从 4.x 升级？请参阅 5.0.0 迁移说明，了解 fastmcp → mcp 依赖项替换、新的路径沙箱，以及工作区文件附加行为变更。

许可证

基于 GPL-3.0 许可。