IPinb Skill 技能

技能简介

IPinb（PyPI 包名 ipinb，Python 命令与 import 名为 ipi）是一款专为 MCP 智能体设计的「持久化 IPython 内核 + Jupyter 笔记本」基础设施。它为 Codex、Claude Code 等 AI 编程智能体提供跨会话保留的 Python 内核、可被智能体读取/写入的 .ipynb 笔记本文件，以及与宿主智能体（Harness）事件打通的状态钩子系统。IPinb 不是一个 LLM 框架——它不包含模型客户端、智能体循环或上下文窗口管理；它专注做一件事：让智能体能像人类数据科学家一样在笔记本里长期保留 Python 状态与产出，并在合适时机把控制权交还宿主智能体。

核心能力

• 持久化 IPython 内核：通过 create_kernel / list_kernels / close_kernel 三个 MCP 工具管理显式内核资源，调用 ipython(kernel_id, code) 后可在多次会话之间保持 Python 全局变量、数据帧、模型对象。
• 重叠执行 + 共享全局：同一内核上多次 ipython 调用可并发执行并共享全局命名空间，AI Agent 在多轮「思考-验证」循环中能直接复用前一步的中间结果。
• 可选 IPDB 调试：暴露 ipdb 工具支持真实断点/单步控制，普通异常处理附带一次插桩检测线索，调试体验贴近 IDE。
• Cell 级光标与中断：read_cell 检索 Python 状态/输出/Markdown 源并支持等待完成；interrupt 请求取消单个 cell；多个 reader 各自维护独立输出光标，互不干扰。
• notebook 协作：list_cells 与 markdown 让 Agent 直接审阅/编写保留的笔记本内容；publish(kernel_id, cells=...) 把指定 cell 提炼为可分享产物。
• Harness 钩子双向打通：ipi install --provider all 自动写入 Codex 的 .codex/config.toml + hooks.json 与 Claude Code 的 .mcp.json + .claude/settings.json，并在 SessionStart / SubAgentStart 等事件上向前端 Agent 推送笔记本状态变更通知。

安装配置

• 环境要求：Python 3.10+；Linux 或 macOS（Windows 暂不支持内核宿主）；需要 uv（项目已把它作为运行时分发机制）。
• 免安装直跑：uvx --isolated --from "ipinb[mcp]" ipi 直接启动 stdio MCP 服务器，无需全局污染。
• 安装到项目级：在仓库根目录执行 uvx --isolated --from "ipinb[mcp]" ipi install --provider all，会自动写入 Codex / Claude Code 各自的配置文件并保持幂等（重跑不会破坏未相关设置，冲突的 ipi 条目会被拒）。
• 单宿主接入：只想用其中一个时，指定 --provider codex 或 --provider claude_code；加 --scope user 写入用户级配置，加 --scope project 写入仓库级（可被提交）。
• 私有仓库凭证：通过 Git 自带的凭据管理（如 SSH Key 或 GitHub Token）注入到 uvx；可用 IPI_INSTALL_REQUIREMENT="ipinb[mcp] @ git+...@ref" 锁定到特定 ref，避免子内核重建时拉不到对应版本。
• Codex 异步启动：ipi install-hooks --provider codex --async-startup 会让 Codex 在第一轮 turn 期间笔记本可选启动而不阻塞对话，默认等待 300 秒可通过 --startup-wait 自定义。

使用步骤

• 步骤 1：在 Claude Code 或 Codex 项目目录下运行 ipi install --provider all，让 Harness 加载 IPinb MCP 服务器并注册钩子。
• 步骤 2：AI 接到任务后会按需调用 ipython(kernel_id="main", code=...) 在保留内核中执行 Python，多轮思考可在同一内核里持续累积状态。
• 步骤 3：当 AI 决定「沉淀结论」时调用 publish(kernel_id="main", cells={"cell_xyz": "Caption"})，把指定 cell 提炼为可分享的笔记本产物。
• 步骤 4：人类或后续 Agent 读取笔记本时，调用 list_cells 检索目录、markdown 或 read_cell 查看具体 cell 的源 + 输出（含图像、stderr、print 输出），所有信息按 cell 独立保留。
• 步骤 5：调试失败场景时调用 ipdb 设置真实断点/单步，普通错误情况下会附带一次插桩检测线索。
• 步骤 6：在跨任务/跨会话场景下，再次调用 ipython 时会自动恢复到之前的全局变量、数据帧、模型对象，无需重新初始化。
• 步骤 7：Hook 系统把笔记本启动/完成事件推送给 Harness，Codex/Claude Code 在合适的上下文边界更新工具目录与背景信息。

适用场景

• 数据科学 Agent 长期记忆：让 AI 数据分析师在保留的 IPython 内核里持续累积数据探索与建模状态，无需每次都从头加载数据。
• 可重现的 Agent 实验：把 AI 调用的 Python 代码、输出、图表沉淀到 .ipynb 文件，作为可被同行复核的实验记录。
• 复杂多步调试：IPDB 集成让 AI Agent 能像 IDE 一样设置断点、单步执行，普通异常附带 prompt 插桩提示，加速根因定位。
• 跨 Agent 协作：一个 Agent 的中间结果（数据帧、特征、模型）被下一个 Agent 直接复用，避免重复劳动。
• 异步 notebook 启动：Codex 项目可在 AI 第一轮 turn 时继续对话，同时后台异步拉起 notebook MCP 工具。
• 可分享的研究产物：通过 publish 把 cell 提炼为带 caption 的研究产物，可直接嵌入报告或博客。

适用人群

• 数据科学家 / ML 工程师，希望让 AI Agent 真正用上 Jupyter 工作流
• Codex / Claude Code 重度用户，希望让 Agent 拥有跨会话的 Python 状态
• AI Agent 工具开发者，需要给 Agent 提供可控的 Python 执行环境
• 科研人员，需要可重现、可被同行的实验记录
• 教育/培训场景，把 AI 助教与 Jupyter 教学结合

工作原理

IPinb 把「保留型 IPython 内核」与「Harness 钩子桥」两个子系统封装在同一个 MCP 服务器里：MCP 端负责暴露 ipython / ipdb / read_cell / list_cells / markdown / publish 等工具，工具调用落到由 ZMQ 通道管理的真实 Jupyter 内核上执行；钩子桥则监听 Codex / Claude Code 的 SessionStart / SubAgentStart / 各种 stop 事件，按需把当前 notebook 状态变更通知 Harness。两个子系统之间通过 Unix socket 与进程谱系（process ancestry）做 host 身份识别——Linux/macOS 上只有从已知 Harness 进程派生的 IPinb 子进程才会激活钩子转发，否则仅暴露 notebook 能力。MCP 工具目录与钩子运行时分别由 ipinb[mcp] 与 typed-agent-hooks 两个独立 pinned 依赖负责，避免互相污染版本。

官方链接

• PyPI 包：https://pypi.org/project/ipinb/
• GitHub 仓库：https://github.com/nimashoghi/ipi
• 协议：MIT License
• 当前版本：0.1.2