notebook-cli

Notebook CLI

所有 .ipynb 操作都使用 nb。如果 nb 能完成任务，就不要直接读取、写入、修补或编辑 Notebook JSON。

核心规则

• 编辑前先检查：除非需要查看输出，否则运行 nb read <notebook> --no-output。
• 优先使用 nb read 默认生成的 AI 优化 Markdown 输出；只有在确实需要 nbformat JSON 时才使用 --json。
• 检查 Notebook 后，优先使用单元格 ID（--cell / -c）进行持久性编辑。快速按位置操作时使用索引（--cell-index / -i）；支持负索引。
• 汇总结构或源代码时使用 --no-output。只有在诊断结果、失败、图表或显示值时才包含输出。
• 多行或带引号的内容使用标准输入（--source -），避免 shell 转义错误。
• 如果用户指定了 uv，或工作区显然是 uv 项目，则在整个任务中将 uv 作为 Notebook 执行环境。对于支持 --uv 的 nb 命令（例如 nb create 和 nb execute），使用 --uv。
• 创建包含多个部分的 Notebook 时，按逻辑部分分组，每批添加约 3–5 个单元格，并使用多单元格哨兵（@@markdown、@@code）。每批添加后都要执行并验证，再添加下一批。不要一次调用就添加整个 Notebook——这会增加延迟，也会让错误更难发现。
• 每个 Markdown 单元格都必须包含一个标题，并且至少包含一句说明后续代码的用途或其重要性的正文。仅有标题是不够的——请参阅 best-practices.md。
• 当 Notebook 代码依赖第三方软件包时，如果无法确定软件包是否可用，请在 Notebook 顶部、导入语句之前添加依赖安装单元格。
• 如果存在 uv 环境，依赖单元格应使用 !uv pip install ...。
• 如果不存在 uv 环境，依赖单元格应使用 %pip install ...。
• 命令语法不确定时，运行 nb <command> --help 或 nb cell <subcommand> --help。
• 在连接模式下，让 nb 使用通过 nb connect 保存的连接。不要将秘密令牌写入命令、提示词、日志或示例；如果无法自动检测，请让用户手动建立连接。
• 在运行需要与当前 Notebook 环境一致的非 Notebook Python 命令之前，先使用 nb status --python，并通过返回的前缀运行命令。

信任边界

nb 是一个外部可执行文件，可以读取 Notebook 内容，并且在连接模式下可以使用已保存的 Jupyter 连接状态。在工作区中首次使用前，请验证要运行的命令：

command -v nb
nb --version

使用通过仓库构建或文档说明的 nb-cli 二进制文件。如果找不到 nb、解析到意外路径，或报告了意外的版本或名称，请停止并让用户安装或选择可信的 nb-cli 二进制文件。不要将 Notebook 内容、输出、服务 URL 或连接状态传递给未经验证的可执行文件。

常见工作流

创建 Notebook

nb create analysis.ipynb
nb create analysis.ipynb --kernel python3
nb create notes.ipynb --markdown

创建 Notebook、选择内核或覆盖现有 Notebook 时，请阅读 references/create.md。

检查 Notebook

nb read analysis.ipynb --no-output
nb read analysis.ipynb --cell-index 3
nb search analysis.ipynb "fit_model"

有关筛选、输出处理以及解析 AI Markdown 格式的信息，请阅读 references/read.md。

编辑单元格

nb cell update analysis.ipynb --cell "cell-id" --source -
nb cell add analysis.ipynb --type markdown --source "# Results"
nb cell delete analysis.ipynb --cell-index -1

进行多单元格编辑、保留元数据、在单元格 ID 前后插入内容或删除范围前，请阅读 references/edit-cells.md。

执行与调试

nb execute analysis.ipynb --cell-index 4
nb execute analysis.ipynb --start 0 --end 5 --allow-errors
nb read analysis.ipynb --cell-index 4

有关内核选择、超时、环境标记和面向故障的工作流，请阅读 references/execute.md。

使用 JupyterLab

nb connect
nb status
nb cell update analysis.ipynb --cell "cell-id" --source -
nb disconnect

当 Notebook 在 JupyterLab 中打开，或更改必须通过运行中的服务同步时，请阅读 references/connect-mode.md。

管理输出

nb read analysis.ipynb --limit 8000 --output-dir ./notebook-outputs
nb output clear analysis.ipynb
nb output clean

请阅读 references/output-format.md，了解哨兵解析、外置输出文件、清除输出和提交规范。

编写高质量笔记本

创建或审查笔记本时，请阅读 references/best-practices.md，了解基于研究的叙事结构、代码组织、可复现性和命名规范指南。

权限说明

如果 Agent 因沙盒策略而无法运行 nb 或连接模式命令，请请求用户允许所需命令。如需反复使用，项目或用户规则应允许 nb 命令前缀。

验证提示词

检查此技能是否仍能引导 Agent 使用预期的 nb 工作流时，请使用 references/validation-prompts.md。