Qwen Code 改进建议

April 5, 2026 · View on GitHub

核心洞察：随着大模型在数据科学、金融分析领域的普及，越来越多的数据科学家开始使用 AI Agent 辅助编写代码。然而，他们主要的工作载体是 Jupyter Notebook (.ipynb)，而不是传统的 .py 文件。如果大模型直接使用普通的 replace 或 write_file 工具去修改 .ipynb 文件，会大概率破坏其底层的 JSON 结构，导致文件损坏、输出结果丢失或 Cell ID 追踪错乱。Claude Code 专门为此开发了一套属于数据科学家的“手术刀”——原生的 Notebook 单元格级别的读取与编辑能力；而 Qwen Code 目前在处理此类场景时极易引发“破坏性修改”。

返回改进建议总览

一、被破坏的 Jupyter JSON 结构

1. Qwen Code 现状：当成普通文本粗暴处理

如果在当前的 Qwen Code 中说：“帮我修改 data_cleaning.ipynb 里的缺失值处理逻辑”：

痛点一（JSON 结构灾难）：大模型会尝试使用正则表达式或者字符串替换去修改这个 JSON 文件。它极其容易漏掉引号转义（Escape Quotes）或者逗号闭合，一旦改错一个字符，整个 Jupyter 前端（如 VS Code 或 JupyterLab）就会拒绝加载该文件，抛出 Invalid JSON 错误。
痛点二（Metadata 与输出丢失）：一个典型的 .ipynb 文件不仅包含代码（Source），还包含执行结果（Outputs，如 Base64 编码的 matplotlib 图表）以及执行时间等 Metadata。普通文本替换很容易一刀把这些珍贵的输出日志全部切掉，让数据科学家前面跑了几个小时的训练结果灰飞烟灭。

2. Claude Code 解决方案：Cell 级粒度的原子操作

在 Claude Code 的内部机制中，他们将 .ipynb 识别为“一等公民”，并绕过了常规的文件编辑流水线，为其打造了专属的语法树解析器。

机制一：智能解析与降级呈现

当大模型调用 read_file 去看一个 Notebook 时，系统并不会返回带有满屏 Base64 图片的原始 JSON 给它（那会瞬间撑爆 Token）。相反，系统在后台使用 JSON.parse 将其解析，并转换成对大模型极度友好的 Markdown 格式：

[Cell #3] (Code)
```python
import pandas as pd
df = pd.read_csv('data.csv')

只给大模型看它能看懂的，彻底屏蔽底层 Metadata 干扰。

#### 机制二：基于 Index/ID 的原子级修改 (Atomic Edit)
为了实现绝对安全的修改，Claude Code 设计了专门的 Notebook Edit 工具（或者在底层拦截 `edit_file` 时进行特化路由）。
大模型在修改时，不再提交“从哪行到哪行替换什么”，而是提交指令：
> "请把 `data_cleaning.ipynb` 的 **Cell #3** 的代码替换为以下新代码..."

系统接收到指令后：
1. `JSON.parse` 内存加载整个 Notebook。
2. 极其精准地寻址到 `cells[3].source`。
3. 仅仅替换这一小块数组，原封不动地保留该 Cell 原有的 `metadata`、`outputs` 和全文件结构。
4. 调用文件系统安全的覆写，甚至结合之前讨论的 [自动检查点](./automatic-checkpoint-restore-deep-dive.md) 功能打下防崩快照。

## 二、Qwen Code 的改进路径 (P2 优先级)

如果想吸引数据和 AI 算法工程师，Notebook 原生支持是不可或缺的敲门砖。

### 阶段 1：Notebook 序列化视图层
在 `packages/core/src/tools/` 增强现有的读取工具。
1. 检测到后缀为 `.ipynb` 时，拦截常规 `fs.readFile` 输出。
2. 将其转化为包含 `[Cell ID: x]` 标注的格式化纯文本视图返回给大模型。

### 阶段 2：开发专有的 `NotebookEditTool`
1. 注册新工具：`notebook_edit`。参数为 `filepath`, `cell_index` 或 `cell_id`, `new_source`。
2. 该工具在执行时，反序列化原 JSON，替换对应 Cell 的内容数组，清空该 Cell 原有的 `outputs`（因为代码变了，旧图表不再适用），并重新 `JSON.stringify` 回写磁盘。

### 阶段 3：保护全局状态 (Jupyter State Preservation)
确保在重写时不修改任何最高层级的 Notebook `metadata`，特别是 Jupyter 内核版本（kernelspec）信息，保证开发者在本地打开时体验完全无缝。

## 三、改进收益评估
- **实现成本**：中等。核心是写一个 JSON 解析和转换的中间件，代码量 200 行左右。
- **直接收益**：
  1. **攻占数据科学高地**：让广大的 Python 算法、数据分析师群体能够无痛、安全地使用 Qwen Code 去自动补全他们的实验脚本。
  2. **根除格式破坏型报错**：彻底消灭“AI 弄坏了我的 Notebook 文件”这类足以导致用户立刻卸载工具的恶性体验。