内容
# nbskill
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
`nbskill` 是为 nbdev 项目中的智能体和维护人员提供的一种笔记本感知工具。它提供了聚焦的上下文、结构化的编辑、安全的执行和通过 Python、CLI 和 MCP 的审查。
## 为什么存在
在 nbdev 中，笔记本是真相的来源。它包含了实现、解释、示例、输出和元数据。原始的 JSON 编辑容易丢失，而对生成的 Python 的更改会被覆盖。`nbskill` 使笔记本工作变得有意和可审查。
## 功能
使用 `nbskill` 来查找相关的项目、笔记本、章节、单元格或符号；编辑正确的单元格；运行项目上下文中的聚焦检查；并审查生成的差异和样式。MCP 服务器公开了相同的流程，供编码智能体使用。
## 提供的内容
| 需求 | 工具 |
|----|----|
| 查找正确的上下文 | [context](https://morscerta-crypto.github.io/nbskill/cli.html#context) 读取项目、笔记本、章节、单元格 ID 或符号，而不产生原始 JSON 噪音。 |
| 进行聚焦编辑 | [edit_notebook](https://morscerta-crypto.github.io/nbskill/edit.html#edit_notebook)、[write_nb](https://morscerta-crypto.github.io/nbskill/cli.html#write_nb) 和 [update_cell](https://morscerta-crypto.github.io/nbskill/cli.html#update_cell) 保留单元格结构并清除过时的输出。 |
| 验证行为 | [exec_nb](https://morscerta-crypto.github.io/nbskill/cli.html#exec_nb) 在项目上下文中运行笔记本，具有用于审查循环的仅检查模式。 |
| 审查更改 | [diff_nb](https://morscerta-crypto.github.io/nbskill/cli.html#diff_nb)、[style_check](https://morscerta-crypto.github.io/nbskill/cli.html#style_check) 和 `doctor` 关注代码单元格、笔记本卫生和工具诊断。 |
| 将代码移入 nbdev | [convert](https://morscerta-crypto.github.io/nbskill/cli.html#convert) 将 Python 文件或包转换为 nbdev 笔记本。 |
| 为智能体服务 | [nbskill_mcp](https://morscerta-crypto.github.io/nbskill/cli.html#nbskill_mcp) 公开了与 MCP 工具相同的流程。 |
## 解析笔记本单元格
笔记本文本使用 `%%markdown`、`%%code` 和 `---` 作为一种紧凑的单元格格式。[`parse_cells`](https://MorsCerta-crypto.github.io/nbskill/foundation.html#parse_cells) 将该文本转换为笔记本单元格，同时保留每个单元格的类型和源。
``` python
cell_text = "\n".join(["%%markdown", "## Demo", "---", "%%code", "value = 42"])
parsed_cells = parse_cells(cell_text)
[(cell.cell_type, cell_source(cell).splitlines()[0]) for cell in parsed_cells]
```
[('markdown', '## Demo'), ('code', 'value = 42')]
## 读取笔记本
从最小的有用视图开始。[`context`](https://MorsCerta-crypto.github.io/nbskill/cli.html#context) 解析项目、笔记本、章节、单元格或符号，而不暴露笔记本 JSON。
``` bash
context --target nbs/02_write.ipynb --overview
context --target nbs/02_write.ipynb#write_nb
```
第一个调用解释了笔记本。第二个调用跟随公共的 [`write_nb`](https://MorsCerta-crypto.github.io/nbskill/cli.html#write_nb) 符号到其所属单元格和相关用法。
``` python
with redirect_stdout(StringIO()): notebook_context = context("02_write.ipynb", overview=True)
print("\n".join([x['source'] for x in notebook_context["selection"]["markdown"]]))
```
## 编写和更改
单元格创建、目标更新、文档插入和示例。
安全地编写笔记本比向文件中追加文本更难。笔记本编辑需要保留单元格 ID、清除过时的输出、在可能的情况下验证 Python、通过 nbdev 自动导出并避免覆盖错误的单元格。
`write_nb` 插入单元格；`replace_str` 替换笔记本单元格源中的字面文本。
有两种编写模式，因为笔记本编辑有两种不同的形状。对于添加或替换结构化单元格，请使用单元格块写入；对于现有单元格中的精确重命名，仅使用字面替换。两种路径都将 nbskill 元数据戳记并在具有 nbdev 导出目标时自动导出受影响的笔记本。
## MCP 和 CLI
当智能体客户端支持 MCP 时，运行 [`nbskill_mcp`](https://MorsCerta-crypto.github.io/nbskill/cli.html#nbskill_mcp)。它公开了与结构化工具相同的读取、编辑、执行、审查、引用和图形操作。当在 shell 中工作时使用 CLI。[CLI 参考笔记本](https://github.com/MorsCerta-crypto/nbskill/blob/main/nbs/13_cli.ipynb) 列出了每个命令。
使用以下命令安装 Codex 技能并注册本地 MCP 服务器：
``` bash
uv run install_nbskill --target codex
codex mcp add nbskill -- nbskill_mcp
```
直接启动服务器进行测试：
``` bash
uv run nbskill_mcp
uv run context --target nbs/02_write.ipynb
```
MCP 客户端以健康检查开始，然后请求聚焦的上下文：
``` python
mcp__nbskill__.healthcheck()
mcp__nbskill__.context(target="nbs/02_write.ipynb#write_nb", overview=True)
```
## 引用
引用是本地实现知识库，而不是要复制的代码。使用 [`reference_discover`](https://MorsCerta-crypto.github.io/nbskill/knowledge.html#reference_discover) 或 [`reference_add`](https://MorsCerta-crypto.github.io/nbskill/knowledge.html#reference_add) 发现或注册仓库，使用 [`reference_ingest`](https://MorsCerta-crypto.github.io/nbskill/knowledge.html#reference_ingest) 消化它们，然后使用 [`reference_query`](https://MorsCerta-crypto.github.io/nbskill/knowledge.html#reference_query) 查询它们，然后再添加 nontrivial 助手。在将匹配项转换为审查材料时使用 [`reference_propose`](https://MorsCerta-crypto.github.io/nbskill/knowledge.html#reference_propose)。结果结合了结构化过滤器、混合 BM25/矢量搜索、依赖状态和可选分支上下文。
``` python
mcp__nbskill__.reference(
action="query",
query="AST 定义助手",
top_k=5,
include_branch=True,
)
```
## 图形结构
本地图记录笔记本、单元格、标题、符号和导入。它的边记录包含、定义、调用、导入、文档顺序和相关符号。调用和导入边分别携带证据，而启发式相似性边则不同。
这使 `nbskill` 拥有快速的项目范围内的笔记本源地图：智能体可以评估更改的影响，跟随符号到其调用者，并在不读取每个笔记本的情况下发现跨笔记本的私有助手使用情况。它是一种导航和维护辅助工具，而不是运行时依赖分析器。
在需要遍历笔记本结构中的符号时，使用附加图形的项目上下文：
``` python
mcp__nbskill__.context(target="project", scope="nbs", include_graph=True)
```
## 问题解决方案记忆
在选择方法之前，请查询 [`problem_memory`](https://MorsCerta-crypto.github.io/nbskill/cli.html#problem_memory) 以获取来自此项目和其他项目的类似验证经验。在验证后，使用简短证据和至少四个标准化标签（例如主题、子主题、库、问题类别和解决方案类别）添加可重用的问题解决方案对。
标签使经验教训足够精确，可以重用：带有标签的查询应用精确的全部过滤器，而自然语言问题对剩余的匹配项进行排序。这样可以防止广泛相似的记忆被误认为是直接适用的解决方案。
``` python
graph = notebook_knowledge_graph_data("nbs")
dict(nodes=len(graph["nodes"]), edges=len(graph["edges"]), node_types=sorted({node["type"] for node in graph["nodes"]}), edge_types=sorted({edge["type"] for edge in graph["edges"]}))
```
{'nodes': 3588,
'edges': 13426,
'node_types': ['cell', 'heading', 'import', 'notebook', 'symbol'],
'edge_types': ['calls',
'contains',
'defines',
'documents',
'imports',
'precedes',
'similar_to']}
