把Cursor式diff审查引入AI文稿改写：margin-agent开源内核解析

在实际的 AI 辅助写作场景里，Cursor 给人最大的启发不是代码补全速度，而是它把 AI 产生的结果摊开成 diff，让开发者可以像 review 代码一样逐块确认。这种交互模式完全可以迁移到文稿改写：AI 帮你把一段话改得更通顺、更有逻辑，但不是直接替换全文，而是把每一次改写的前后差异显示出来，由作者决定哪些改动保留、哪些改动退回。围绕这个思路，margin-agent 作为一个基于 pi 的开源内核，把“AI 改稿 + diff 审查”的核心流程拆成了可复用的模块。下面从交互设计、开源内核的数据建模、最小可运行命令行的实现，讲到生产环境落地时需要注意的工程问题。

对于经常使用 Cursor 的人来说，这种体验并不陌生：代码补全或重构建议出来后，编辑器里用绿红高亮标出每一处新增和删除，你可以逐个 accept、reject，也可以把整个改动恢复到某个检查点。文稿编辑需要的正是同样的控制感。因为写文章和写代码有一点极其相似：AI 的建议未必完全正确，而最终为文本负责的人，必须能看到每一处变化从哪里来、到哪里去。

1. 先理解核心问题：AI 改稿为什么要走 diff 审查

1.1 全文替换模式的问题藏在“看不见的变更”里

很多人第一次用 AI 改稿，都是把一段文字丢给模型，等它吐出一段改写后的完整文本，然后复制粘贴覆盖原文。这个流程看起来很快，但一旦进入真实写作场景，问题立刻出现。

首先是变更不可见。模型可能在第一段帮你调整了主语，在第三段悄悄删掉了一个限定语，在最后一段补充了一句原文根本没有的意思。你很难一眼扫出全部变化，尤其是对上万字的文章。其次是无法局部接受。原文有三处需要改，但模型把整个段落都重写了，你可能只想要其中一半效果，却很难只保留那一半。第三是版本历史丢失。覆盖之后，原始版本去哪里了？如果新版本引入语义偏差，你只能凭记忆找回原稿。

这些问题的本质不是模型不够聪明，而是工作流缺少一个“变更展示与确认”的中间层。模型输出的是整段文本，但人真正需要的是“改了什么”的精确说明。

1.2 diff 审查模式把控制权交还给作者

diff 是代码协作里最基础也最有效的工具，它把一次变更拆解成若干最小差异，并在文件的上下文里显示出来。margin-agent 做的事情，就是把这个思路用到文稿改写里：AI 先生成改写后的文本，内核并不直接采用，而是将原文与改写结果做一次 diff，解析成多个独立的 hunk（差异块），再由作者对每个 hunk 分别做出接受、拒绝或跳过决定。

这样改稿的流程就变成了：

1. 给出原文和改写要求。
2. 模型返回改写后的完整文本。
3. margin-agent 生成 unified diff。
4. 作者像评审代码一样逐块查看差异。
5. 只把通过的 hunk 合并回原文。

这里的关键不是“自动替换”，而是“可审查的变更”。AI 仍然负责产出，但最终决定权回到作者手里。每一处改动都有上下文、有定位、有决策记录，不再是一次黑箱覆盖。

下面是全文替换模式和 diff 审查模式的对比：

1.3 Cursor 真正值得迁移的不是编辑器，而是 diff 交互

Cursor 这几年热度很高，相关内容里讨论最多的其实是“Cursor 怎么用”“Cursor 怎么设置中文”这类入门问题。但真正让 Cursor 和普通 AI 编辑器拉开差距的，是它对 diff 审查体验的打磨：AI 生成不是终点，把生成结果放进可确认、可反悔、可逐块操作的状态里，才是生产力来源。

文稿版 Cursor 并不需要复刻一个完整代码编辑器。它要复刻的是这个交互模型。margin-agent 作为内核，把“AI 改写 → 生成 diff → 逐块评审 → 应用结果”这条链路抽象出来，编辑器、命令行、Web 端都只是它的前端。

这里要澄清一个容易误解的点：diff 审查模式并不是让作者把 AI 的每处修改都检查一遍，而是让作者有机会在关键位置停下来判断。实际使用中，大多数 hunk 可以快速通过，真正值得关注的是那些改变语义、删除内容、重排段落的大块改动。这也是 review 对代码的意义——不是不信任，而是确保变更被理解。

2. 产品形态：把 Cursor 式 diff 交互落到文稿场景

2.1 文稿 diff 和代码 diff 的差异不能被忽略

如果直接把代码 diff 工具搬到文稿场景，会碰到一些自然语言特有的问题。代码的最小单位是语句和表达，而文稿的最小单位是句子和段落，行长度差异很大。一段长句被改写后，可能整行都变了，diff 看起来就像一个巨大的 hunk，反而不容易定位到具体词组变化。

另外，文稿中的换行不像代码那样有严格语义。Markdown 中一个自然段可能是连续多行，也可能被空行分开；中文文稿里全角标点和半角标点混用，Windows 下还有 CRLF 行尾问题。这些都可能导致 diff 产生大量无关噪声。

所以在 margin-agent 的设计里，生成 diff 之前需要先做文本规范化：统一行尾、去除行尾空格、避免把单纯的换行调整当成内容变更。否则使用者会在细碎差异里花掉大量时间，最后觉得“还不如自己改”。

2.2 一条完整的改稿审查链路

一套可用的文稿版 Cursor 交互流程，可以从用户选中文本开始。用户在编辑器里选中一段文字，调用“AI 改稿”命令，输入改写意图，比如“更正式一点”“精简到 200 字”“补强论证逻辑”。模型返回改写结果后，系统并不立刻替换原文，而是把原文和改写结果交给 margin-agent。

margin-agent 会做四件事：

1. 规范化原文和改写结果的文本格式。
2. 生成 unified diff，把差异拆成若干 hunk。
3. 为每个 hunk 提供起始行、结束行、改动前后范围等定位信息。
4. 等待上层 UI 收集用户决策，再按决策应用改动。

前端拿到 hunk 列表后，可以像 Cursor 一样在文档里内联显示：绿色表示新增，红色表示删除，用户对每个 hunk 按下批准或拒绝键。最后把所有 accepted 状态的 hunk 合并回文档，生成新版本，并写入一份评审记录。

2.3 margin-agent 在这种形态里的位置

很多开发者把 margin-agent 理解为又一个 AI 写作助手，这个理解不够准确。它更像一个规则引擎加数据结构层：只负责把“改写前文本”和“改写后文本”变成可审查的补丁，不负责调用哪个模型，也不负责渲染 UI，更不负责存储用户文档。

这种边界设计有一个直接好处：上层产品可以自由替换模型、切换编辑器、改造界面，而核心的 diff 解析、hunk 管理和决策状态机不用重写。如果你的目标是做一款自己的“文稿版 Cursor”，margin-agent 可以成为底层内核，而不是被某个编辑器绑死的插件。

与 open code review、code review graph 这类工具类似，margin-agent 也在做同一件事：让变更过程被结构化、可视化、可记录。区别只在于 review 对象是代码还是文字。理解了这一点，再看 margin-agent 的数据结构和工作流程，就会容易很多。

3. margin-agent 开源内核对 diff 工作流的建模

3.1 内核职责：不碰模型，不碰 UI，只碰 diff

margin-agent 的定位是“内核”，这意味着它有清晰的职责边界。它接收两个字符串：source_text 和 target_text，前者是原始文稿，后者是模型改写后的文本。它输出的是一组结构化的 diff hunk，以及围绕这些 hunk 的评审状态。

它不负责的事包括：

• 不内置模型，模型调用由接入方完成。
• 不提供编辑器界面，交互层可以放在 VS Code、命令行或 Web。
• 不管理用户文件，文件读写由外层负责。
• 不做语义判断，只是一套“把改动拆开并追踪决策”的机制。

这样设计的好处是接入成本低。你可以在任意语言、任意编辑器里调用它，只要把两个字符串传进去，就能得到一棵 diff 树。

3.2 用 DiffSet + Hunk + ReviewState 描述一次改写

一次完整的改稿审查过程，可以用三个核心数据结构表达：DiffSet 表示一次改写产生的全部差异，Hunk 表示其中一块连续差异，ReviewState 表示每块差异的决策状态。

下面是一个 Python 数据建模示例，展示 margin-agent 内部可以怎样组织这些对象：

from dataclasses import dataclass, field @dataclass class Hunk: old_start: int # 原文本中的起止行号，从 1 开始 old_count: int # 原文本中被替换的行数 new_start: int # 改写文本中的起止行号 new_count: int # 改写文本中新增的行数 lines: list # 该 hunk 的每一行，带 +、-、空格前缀 decision: str = "pending" # pending / accepted / rejected / skipped @dataclass class DiffSet: source_text: str target_text: str hunks: list = field(default_factory=list) @property def pending_count(self) -> int: return sum(1 for h in self.hunks if h.decision == "pending") @property def accepted_lines(self) -> int: return sum(h.new_count for h in self.hunks if h.decision == "accepted")

每个 Hunk 都保留 old_start、old_count、new_start、new_count，这四组数字决定了“改动从哪里来、到哪里去、影响多少行”。decision 字段记录该 hunk 当前处于什么状态，默认是 pending，表示等待用户评审。

3.3 基于 pi 的 skill 扩展方式

margin-agent 基于 pi 这个 agent 运行时构建。pi 提供了 agent 运行、工具调用和 skill 机制，开发者可以把一段具体的任务流程封装成 skill。margin-agent 把“文本改写评审”设计成一个 skill：接收原文和改写要求，调用模型，但不在模型返回结果后直接结束，而是把结果交给 diff 模块生成补丁，再进入评审状态。

下面是一段示意性代码，用来表达这个接入思路。实际 pi 版本的接口可能会不同，落地前需要以自己使用的 pi 版本为准：

# 示例：基于 pi 的 skill 注册，接口以实际 pi 版本为准 from margin_agent import DiffTool, ReviewState def register_text_review_skill(agent): @agent.skill("text_review") def text_review(original: str, instructions: str): # 调用模型，允许接入方替换为任意 LLM rewritten = agent.call_llm(original, instructions) # 生成 diff 而不是直接返回改写文本 diff_set = DiffTool().build(original, rewritten) # 进入评审状态机，等待用户逐块确认 state = ReviewState(diff_set) return state.wait_for_review()

这样接入方的职责就变得很清晰：只需要实现 call_llm，以及把 state.wait_for_review() 展示到界面上。模型换掉不影响 diff 逻辑，UI 换掉不影响状态机。

3.4 为什么把评审决策做成状态机

评审决策不能只用一个布尔变量表示。一个 hunk 从生成开始，可能经历 pending → accepted，也可能会从 accepted 被改回 pending，允许用户反悔。如果某个 hunk 被拒绝后，用户想重新查看，它应该可以被重新开启。这就是状态机的价值。

常见状态迁移是：

• pending：初始状态，等待处理。
• accepted：用户接受该 hunk，后续应用时会合并进新文档。
• rejected：用户拒绝该 hunk，应用时跳过。
• reopened：用户重新打开已处理的 hunk，状态回到 pending。

状态机的存在让整个 review 过程可审计、可恢复。即使中途关闭程序，只要把评审记录持久化，下次启动依然可以继续未完成的评审。

4. 动手实现：一个最小可用的文稿版 Cursor 命令行工具

4.1 环境准备和项目结构

为了验证 margin-agent 的 diff 审查思路，可以不依赖复杂框架，先用 Python 标准库实现一个命令行原型。它做的事情很简单：输入原文和改写结果，生成 diff，逐块询问用户，最后输出合并后的文稿。

环境要求如下：

项目结构保持精简：

text_review_cli/ ├── review_core.py # diff 生成、hunk 解析、hunk 应用 ├── cli.py # 命令行交互循环 └── samples/ ├── original.md └── rewritten.md

原型阶段可以不接真实模型，而是把模型改写后的文本先放到 rewritten.md 里。这能帮助你专注验证 diff 审查逻辑，不被模型波动干扰。

4.2 生成和解析 unified diff

核心逻辑在 review_core.py 里。先用 difflib 生成 unified diff，再解析出 hunk。这里选择 unified diff 是因为它包含文件头、@@ 定位行以及带 +、- 前缀的行，信息足够完整，适合做 hunk 级别的评审。

import re import difflib HUNK_HEADER = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@") def make_unified_diff(original: str, rewritten: str, context: int = 3): old_lines = original.splitlines(keepends=True) new_lines = rewritten.splitlines(keepends=True) diff_text = difflib.unified_diff( old_lines, new_lines, fromfile="original", tofile="rewritten", n=context, ) return "".join(diff_text) def parse_hunks(diff_text: str): hunks = [] current = None for line in diff_text.splitlines(keepends=True): m = HUNK_HEADER.match(line.strip()) if m: if current: hunks.append(current) current = { "old_start": int(m.group(1)), "old_count": int(m.group(2) or 1), "new_start": int(m.group(3)), "new_count": int(m.group(4) or 1), "lines": [], } elif current is not None: current["lines"].append(line) if current: hunks.append(current) return hunks

make_unified_diff 返回完整的 diff 文本，parse_hunks 把它拆成 hunk 列表。每个 hunk 里的 lines 保留了带前缀的原始行，后续展示和决策都基于这个结构。

4.3 逐块审批的交互循环

cli.py 负责把 hunk 展示给用户，并接收决策。为了让代码可运行，这里把决策收集做成命令行输入：a 表示接受，r 表示拒绝，s 表示跳过，q 表示退出并保存当前进度。

from review_core import make_unified_diff, parse_hunks def apply_hunk(source_lines: list, hunk: dict) -> list: old_start = hunk["old_start"] - 1 old_count = hunk["old_count"] inserted = [] for line in hunk["lines"]: if line.startswith("+") and not line.startswith("+++"): inserted.append(line[1:]) return ( source_lines[:old_start] + inserted + source_lines[old_start + old_count:] ) def review_loop(original: str, rewritten: str): diff_text = make_unified_diff(original, rewritten) hunks = parse_hunks(diff_text) source_lines = original.splitlines(keepends=True) accepted_hunks = [] for index, hunk in enumerate(hunks, start=1): print(f"\n--- Hunk {index}/{len(hunks)} " f"@@ -{hunk['old_start']},{hunk['old_count']} " f"+{hunk['new_start']},{hunk['new_count']} @@") for line in hunk["lines"]: print(line.rstrip("\n")) while True: choice = input("[a] accept / [r] reject / [s] skip / [q] quit: ").strip().lower() if choice == "a": accepted_hunks.append(hunk) break if choice in ("r", "s", "q"): if choice == "q": break break if choice == "q": break # 从后往前应用，避免行号偏移 for hunk in sorted(accepted_hunks, key=lambda h: h["old_start"], reverse=True): source_lines = apply_hunk(source_lines, hunk) return "".join(source_lines)

这里最容易被忽视的是 apply_hunk 的顺序。如果从前往后应用，第一个 hunk 插入新行后，后续 hunk 的 old_start 就会失效，造成行号错位。代码里把 accepted_hunks 按 old_start 从大到小排序，从文件尾部开始应用，可以避免偏移。

4.4 运行验证与预期输出

准备一份简单的样例。original.md 内容：

今天天气很好。 我们决定去公园散步。 公园里人很多。 我们玩得很开心。

rewritten.md 内容（假设是模型改写结果）：

今天天气不错。 我们决定去公园散步。 公园里人虽然很多，但气氛很好。 我们玩得很开心。

运行：

python cli.py samples/original.md samples/rewritten.md

终端会先显示第一个 hunk，内容可能包含“今天天气很好。”被替换为“今天天气不错。”。如果输入 a，第二个 hunk 会显示“公园里人很多。”处的新增行。输入 r 拒绝后，最后输出的文稿里只有第一个 hunk 被应用：

今天天气不错。 我们决定去公园散步。 公园里人很多。 我们玩得很开心。

这个结果说明评审机制生效了：模型改写内容被拆成了独立差异，用户只保留了想要的部分。

5. 关键实现细节：hunk 解析、上下文行和决策持久化

5.1 为什么行级 diff 更适合文本改写

文本改写中，模型可能只修改一个词组，但因为行太长，diff 会把整行标记为删除和新增。这是行级 diff 的天然局限，但它依然是当前最实用的方式，原因有三点。

第一，行级 diff 天然支持定位。光标停在某个 hunk 上时，你可以直接知道它对应原文第几行、改写后第几行。第二，行级 diff 容易应用和回滚。按行删除、插入，不会破坏没被修改的行。第三，行级 diff 适合人和程序共同处理。编辑器插件、命令行工具、评审系统都支持统一的行概念。

如果觉得行级太粗，可以进一步在词级别做高亮，但 margin-agent 的 hunk 结构仍然以行为单位。词级高亮只是展示层增强，不会改变 hunk 的决策粒度。

5.2 context 参数决定 hunk 的粗细

unified diff 的 n 参数控制上下文行数。n 越大，每个 hunk 周围保留的未修改行越多，视觉上更容易理解；但 hunk 数量会减少，单块差异会变大。n 越小，hunk 越聚焦，但应用时对行号精确度要求更高。

文稿改写建议从 context=2 或 context=3 开始。如果发现单块 hunk 过大，可以调小 context，让模型只产生更局部的小改动，或者先把大段落拆成多个小段再分别改写。

5.3 用 JSONL 保存评审记录

评审不只是人与 AI 之间的交互过程，也是内容生产的审计记录。margin-agent 推荐把每次 hunk 决策保存为 JSONL 文件，一行一条记录。每条记录至少包括时间、hunk 定位、决策结果和可选原因。

{"ts": "2025-01-10T10:20:30Z", "old_start": 1, "old_count": 1, "new_start": 1, "new_count": 1, "decision": "accepted", "reason": ""} {"ts": "2025-01-10T10:20:35Z", "old_start": 3, "old_count": 1, "new_start": 3, "new_count": 2, "decision": "rejected", "reason": "新增内容改变了原意"}

这份记录有两个价值。一是可以重放：把同一份 original 和同一批决策重新应用，能得到完全一致的输出。二是可审计：团队协作时，任何人都能看到某处改动是谁在什么时间决定保留或拒绝的。

5.4 这块最容易踩的三个坑

第一个坑是顺序应用 hunk。前面已经提过，需要从后往前应用，否则先插入的行会改变后续行号。第二个坑是行尾符不一致。Windows 下文件可能是 CRLF，Linux 下是 LF，如果规范化时把整行改写，diff 可能会把整个文件都标记为变化。处理方式是在生成 diff 前统一转成 LF。第三个坑是模型输出包含 Markdown 代码块。有些模型会在回复里用 ``` 包裹 diff，直接把这段文本交给解析器会出错。接入方需要在调用模型时要求只输出纯文本 diff，或者在解析前剥离代码块标记。

注意：不要只验证程序能启动。要拿一份有中文标点、有空行、有长段落的真实文稿去测，确认 diff 的 hunk 数量和行号定位都符合预期。

6. 从命令行到编辑器：接入更完整的 review 工作流

6.1 命令行批处理与 dry-run

命令行原型的价值不只是演示。在批量处理场景里，margin-agent 完全可以走“非交互式”流程：先生成评审报告，再由编辑或审稿人在另一个环节逐块确认。

比如可以设计两个命令：

margin-agent diff --original chapter1.md --rewritten chapter1.rewritten.md --out review.json margin-agent apply --review review.json --output chapter1.final.md

diff 命令只生成评审文件，不修改原文；apply 命令按照评审文件里的决策输出最终结果。这样就能接入自动化流程，也方便在 CI 或内容发布前做一次 dry-run，先看看会有哪些改动。

dry-run 对生产环境尤其重要。执行 apply 前，先用 diff 命令生成一份 hunk 清单，人工确认没有大段误改，再执行合并。即使某个 hunk 决策错误，也可以从评审文件里找到原始范围，手动恢复。

6.2 在 VS Code 里复现 Cursor 式内联体验

命令行工具解决了“可以用”的问题，但日常写作体验还需要更顺滑的界面。以 VS Code 为例，扩展可以把 margin-agent 包装成“文稿版 Cursor”：

1. 在编辑器里选中一段文字，右键执行“AI 改稿”。
2. 模型改写结果通过 margin-agent 生成 hunk。
3. 扩展用装饰器或内联提示把 hunk 显示在原文位置。
4. 用户通过 CodeLens 或快捷键对每个 hunk 执行 accept、reject、next、prev。
5. 最终生成的新文档可以直接替换原文，也可以另存为新文件。

实现时不需要重新发明编辑器。VS Code 本身提供丰富的 diff 展示、装饰器和命令机制，核心工作只是把 margin-agent 的 hunk 映射到编辑器的文本范围上。如果你参考过 open code review 这类扩展，会发现它在很多地方都提供了类似思路：把 review 数据可视化，并让操作走标准的文件修改 API。

6.3 团队评审：diff 变成可追踪的变更记录

当一个人写稿、一个人审稿时，diff 的价值已经很突出。当团队协作时，diff 的价值会进一步放大。margin-agent 生成的评审记录可以提交到 Git 仓库，形成一份和文稿同步的变更报告。

在团队场景里，margin-agent 输出的 hunk 定位信息非常有用。评审人不需要打开整个文档去猜“这句话在哪里”，而是直接看到 old_start 到 old_count 的范围，再结合 diff 上下文判断改动是否合理。

7. 常见问题排查与生产落地建议

7.1 先按这条链路排查问题

margin-agent 使用中常见的故障，大部分集中在文本规范、行号定位和状态管理上。下面表格按“现象 → 原因 → 检查方式 → 解决方案”给出排查顺序。

排查时先确认输入文本是否规范，再看 hunk 定位，最后检查应用顺序。这个顺序可以覆盖大多数问题。

7.2 学习环境和生产环境的配置差异

学习环境里跑原型，可以直接在 Python 脚本里读文件、输出到终端，评审记录可以只保存在内存里。但进入生产环境，需要补齐以下部分：

生产环境里最重要的原则是“可回滚”。margin-agent 的评审机制天然支持按 hunk 回滚，但前提是原文档有备份，评审记录有保存。没有这两样，任何回滚都无从谈起。

7.3 落地 margin-agent 前先过一遍检查清单

不是所有文本都适合走 AI 改稿加 diff 审查。落地前建议按下面清单确认一次：

• 原文是否已经确定，还是仍在自由创作阶段？草稿阶段更适合直接生成全文，审稿阶段才需要 diff。
• 模型输出是否稳定？如果模型经常大段重写，先设计好提示词，避免 hunk 数量爆炸。
• 文本规范是否统一？如果没有统一行尾和空格，先做规范化。
• 评审记录能否对应到具体版本？建议在记录里保存版本号或原文 hash。
• 应用 diff 前是否备份原文档？这条必须执行，不能省略。
• 是否设置了 dry-run？批量任务中，先看 diff 再应用，能避免大规模误改。

这份清单不是一次性 checklist，而是每次批量改稿前都应该跑一遍的固定流程。margin-agent 把 diff 审查机制做成了内核，但真正保证内容安全的是编辑器、脚本和生产流程里的这些细节。

7.4 下一步扩展方向

margin-agent 目前的思路以行级 diff 为基础，适合处理 Markdown、纯文本和结构化文档。要把它扩展成完整的“文稿版 Cursor”，可以从这几个方向入手。

一是词级对比增强。在 hunk 内部继续用词级相似度算法高亮具体变化的词组，让作者更快定位到修改点。二是结构化文档支持。对 Markdown 的表格、代码块、列表和标题做更细的解析，避免 diff 把一块完整结构拆碎。三是与团队 review 管道集成。把 margin-agent 的评审记录发送到内容管理平台或代码评审系统，形成跨团队审稿流程。四是引入多模型对比。同一段原文由不同模型改写，再把多个版本的 diff 并列展示，辅助作者选择更合适的表达。

这些方向都不需要改变 margin-agent 的核心建模，只需要在它的 hunk 结构之上增加展示层、策略层和集成层。这也是把一个流程抽象成内核的价值所在：底层把“改动”这件事建模清晰，上层才有空间去生长出各种产品形态。

文稿编辑想要真正获得 Cursor 式体验，关键不是堆更多 AI 功能，而是让每一次 AI 改写都变得可见、可确认、可回滚。margin-agent 把这条链路做成开源内核，正是为了让你可以在此基础上，搭出一套最适合自己写作和审稿流程的工具。