添加计划注释：掌握四种注释类型

学完你能做什么

✅ 选中计划文本，添加四种不同类型的注释（删除、替换、插入、评论）
✅ 使用 type-to-comment 快捷键直接输入评论
✅ 在注释中附加图片（参考图、截图等）
✅ 理解每种注释类型的含义和使用场景
✅ 查看注释导出后的 Markdown 格式

你现在的困境

问题 1：知道要删除某段内容，但选中文本后不知道点击哪个按钮。

问题 2：想替换一段代码，但工具栏里只有"删除"和"评论"，没有"替换"选项。

问题 3：选中多行文本想直接输入评论，每次都要先点击"Comment"按钮，效率低。

问题 4：想给某段代码附加参考图，但不知道怎么上传图片。

Plannotator 能帮你：

清晰的按钮图标，一眼看出删除、替换、插入、评论的区别
type-to-comment 快捷键，直接输入无需点击按钮
注释中支持图片附件，方便添加参考图
注释自动转换为结构化 Markdown，AI 准确理解

什么时候用这一招

使用场景：

评审 AI 生成的实施计划，需要精确反馈修改意见
某段内容不需要（删除）
某段内容需要改成另一种写法（替换）
某段内容后面需要补充说明（插入）
对某段内容有疑问或建议（评论）

不适用场景：

只是整体批准或拒绝计划（无需注释，直接决策即可）
已经在评审代码变更（使用代码评审功能）

🎒 开始前的准备

前置条件：

✅ 已完成计划评审基础教程
✅ 了解如何触发 Plannotator 计划评审界面

本课假设：

你已经打开了 Plannotator 计划评审页面
页面中显示了一个 AI 生成的 Markdown 计划

核心思路

注释类型详解

Plannotator 支持四种计划注释类型（外加一种全局评论）：

注释类型	图标	用途	是否需要输入内容
删除 (DELETION)	🗑️	标记此内容应从计划中移除	❌ 不需要
评论 (COMMENT)	💬	对选中内容提出问题或建议	✅ 需要输入评论
替换 (REPLACEMENT)	通过评论实现	用新内容替换选中内容	✅ 需要输入新内容
插入 (INSERTION)	通过评论实现	在选中内容后插入新内容	✅ 需要输入新内容
全局评论 (GLOBAL_COMMENT)	页面底部输入框	对整个计划提出反馈	✅ 需要输入评论

为什么替换和插入没有独立按钮？

因为从源码实现来看，替换和插入本质上是特殊的评论类型（packages/ui/utils/parser.ts:287-296）：

替换：评论内容作为替换的新文本
插入：评论内容作为插入的新文本

它们都使用 评论 (COMMENT) 按钮创建，区别在于你如何描述意图。

工具栏工作流程

选中文本 → 工具栏弹出（菜单步骤）
                 │
                 ├── 点击 Delete → 立即创建删除注释
                 ├── 点击 Comment → 进入输入步骤 → 输入内容 → 保存
                 └── 直接输入字符 → type-to-comment → 自动进入输入步骤

两个步骤的区别：

菜单步骤：选择操作类型（删除、评论、取消）
输入步骤：输入评论内容或附加图片（从评论/替换/进入）

type-to-comment 快捷键

这是提升效率的关键功能。当你选中一段文本后，直接开始打字（不需要点击任何按钮），工具栏会自动：

切换到"评论"模式
将你输入的第一个字符放入输入框
光标自动定位到输入框末尾

源码实现位置：packages/ui/components/AnnotationToolbar.tsx:127-147

跟我做

第 1 步：启动计划评审

为什么 需要一个实际的计划来练习添加注释。

操作

在 Claude Code 或 OpenCode 中触发计划评审：

bash

# Claude Code 示例：让 AI 生成计划后，它会调用 ExitPlanMode
"请生成一个用户认证功能的实施计划"

# 等待 AI 完成计划，Plannotator 会自动在浏览器中打开

你应该看到：

浏览器打开计划评审页面
页面显示一个 Markdown 格式的实施计划

第 2 步：添加删除注释

为什么 删除注释用于标记不希望出现在最终计划中的内容。

操作

在计划中找到你不需要的段落（例如某个不相关的功能描述）
鼠标选中文本
工具栏自动弹出，点击 删除按钮（🗑️）

你应该看到：

被选中的文本显示为删除样式（通常是删除线或红色背景）
工具栏自动关闭

删除注释的特点

删除注释不需要输入任何内容。点击删除按钮后，注释立即创建完成。

第 3 步：使用 type-to-comment 添加评论

为什么 评论是最常用的注释类型，type-to-comment 能让你少点一次按钮。

操作

在计划中选中文本（例如某个函数名或描述）
不要点击任何按钮，直接开始打字
输入你的评论内容（例如："这个函数名不够清晰"）
按 Enter 键保存，或点击 Save 按钮

你应该看到：

工具栏自动切换到输入框模式
你输入的第一个字符已经在输入框中
光标自动定位到输入框末尾
按 Enter 后，选中的文本显示为评论样式（通常是黄色背景）

type-to-comment 的快捷键

Enter：保存注释（如果输入框有内容）
Shift + Enter：换行（输入多行评论时使用）
Escape：取消输入，返回菜单步骤

第 4 步：添加替换注释

为什么 替换注释用于用新内容替换选中内容，AI 会根据你的注释修改计划。

操作

在计划中选中文本（例如 "使用 JWT token 进行认证"）
使用 type-to-comment 或点击评论按钮
在输入框中输入新的内容（例如："使用 session cookie 进行认证"）
按 Enter 保存

你应该看到：

选中的文本显示为评论样式
注释侧边栏中显示你的评论内容

导出后的格式（packages/ui/utils/parser.ts:292-296）：

markdown

## 1. Change this

**From:**

使用 JWT token 进行认证


**To:**

使用 session cookie 进行认证

替换与删除的区别

删除：直接移除内容，不需要说明理由
替换：用新内容替换旧内容，需要指定新内容

第 5 步：添加插入注释

为什么 插入注释用于在选中内容后补充说明或代码片段。

操作

在计划中选中文本（例如函数签名的末尾）
使用 type-to-comment 或点击评论按钮
在输入框中输入要插入的内容（例如："，需要处理认证失败的情况"）
按 Enter 保存

你应该看到：

选中的文本显示为评论样式
注释侧边栏中显示你的评论

导出后的格式（packages/ui/utils/parser.ts:287-290）：

markdown

## 1. Add this

，需要处理认证失败的情况

第 6 步：在注释中附加图片

为什么 有时候文字描述不够直观，需要附加参考图或截图。

操作

选中任意文本，进入输入步骤（点击评论按钮或 type-to-comment）
在工具栏输入框旁边，点击 附件按钮（📎）
选择要上传的图片（支持 PNG、JPEG、WebP 格式）
可以继续输入评论内容
按 Enter 保存

你应该看到：

图片缩略图显示在输入框中
保存后，图片显示在注释侧边栏中

图片存储位置

上传的图片保存在本地 /tmp/plannotator 目录（源码位置：packages/server/index.ts:163）。如果清理临时文件，图片会丢失。

第 7 步：添加全局评论

为什么 当你对整个计划有反馈（不是针对具体某段文本）时，使用全局评论。

操作

在页面底部找到输入框（标签可能是 "Add a general comment about the plan..."）
输入你的评论内容
按 Enter 保存或点击发送按钮

你应该看到：

评论出现在页面底部的全局评论区域
评论显示为独立卡片，不关联任何文本块

全局评论 vs 文本评论

全局评论：对整个计划的反馈，不关联具体文本（例如"整个计划缺少性能考虑"）
文本评论：对某段文本的反馈，会高亮显示对应的文本

检查点 ✅

完成上述步骤后，你应该：

[ ] 成功添加了至少一个删除注释
[ ] 使用 type-to-comment 添加了评论
[ ] 添加了替换和插入注释
[ ] 在注释中附加了图片
[ ] 添加了全局评论
[ ] 在右侧侧边栏看到所有注释列表

踩坑提醒

坑 1：找不到"替换"按钮

错误操作：

选中文本后，工具栏只有 Delete 和 Comment，没有 Replace 或 Insert 按钮

正确做法：

替换和插入通过 评论 (COMMENT) 按钮实现
在评论内容中描述你的意图（替换或插入）
AI 会根据评论内容理解你的意图

坑 2：type-to-comment 失效

可能原因：

没有选中文本
先点击了某个按钮，工具栏已进入输入步骤
输入了特殊键（Ctrl、Alt、Escape 等）

正确做法：

先选中文本，确保工具栏显示在菜单步骤（有 Delete、Comment 按钮）
直接输入普通字符（字母、数字、标点）
不要按功能键

坑 3：图片上传后找不到

可能原因：

图片保存在 /tmp/plannotator 目录
系统清理了临时文件

正确做法：

如果需要长期保存图片，建议复制到项目目录
导出注释时，图片路径是绝对路径，确保其他工具可以访问

坑 4：按 `Enter` 换行却保存了注释

错误操作：

在输入框中想换行，直接按 Enter，结果注释被保存

正确做法：

使用 Shift + Enter 换行
Enter 键专用于保存注释

本课小结

四种注释类型：

删除 (DELETION)：标记不希望出现在计划中的内容
替换 (REPLACEMENT)：用新内容替换选中内容（通过评论实现）
插入 (INSERTION)：在选中内容后补充内容（通过评论实现）
评论 (COMMENT)：对选中内容提出问题或建议
全局评论 (GLOBAL_COMMENT)：对整个计划的反馈

关键操作：

选中 → 工具栏弹出 → 选择操作类型
type-to-comment：直接输入字符，自动进入评论模式
Shift + Enter：换行；Enter：保存
附件按钮：上传图片到注释

注释导出格式：

删除：## Remove this + 原文本
插入：## Add this + 新文本
替换：## Change this + From/To 对比
评论：## Feedback on: "..." + 评论内容

下一课预告

下一课我们学习 添加图像标注。
你会学到：
如何在计划评审中附加图像
使用画笔、箭头、圆形工具进行标注
标注图像作为参考反馈

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-24

功能	文件路径	行号
注释类型枚举定义	`packages/ui/types.ts`	1-7
Annotation 接口	`packages/ui/types.ts`	11-33
注释工具栏组件	`packages/ui/components/AnnotationToolbar.tsx`	29-272
---	---	---
注释导出格式化	`packages/ui/utils/parser.ts`	246-323
Markdown 解析为 Blocks	`packages/ui/utils/parser.ts`	70-244
Viewer 组件（文本选择处理）	`packages/ui/components/Viewer.tsx`	66-350

关键常量：

AnnotationType.DELETION = 'DELETION'：删除注释类型
AnnotationType.INSERTION = 'INSERTION'：插入注释类型
AnnotationType.REPLACEMENT = 'REPLACEMENT'：替换注释类型
AnnotationType.COMMENT = 'COMMENT'：评论注释类型
AnnotationType.GLOBAL_COMMENT = 'GLOBAL_COMMENT'：全局评论类型

关键函数：

exportDiff(blocks, annotations)：将注释导出为 Markdown 格式，包含 From/To 对比
parseMarkdownToBlocks(markdown)：将 Markdown 解析为线性 Block 数组
createAnnotationFromSource()：从文本选择创建 Annotation 对象

5 分钟快速上手

评审 AI 计划和代码

多人协作+笔记存档

遇到问题怎么办

查 API 和数据结构

看看新功能

添加计划注释：掌握四种注释类型

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

注释类型详解

工具栏工作流程

type-to-comment 快捷键

跟我做

第 1 步：启动计划评审

第 2 步：添加删除注释

第 3 步：使用 type-to-comment 添加评论

第 4 步：添加替换注释

第 5 步：添加插入注释

第 6 步：在注释中附加图片

第 7 步：添加全局评论

检查点 ✅

踩坑提醒

坑 1：找不到"替换"按钮

坑 2：type-to-comment 失效

坑 3：图片上传后找不到

坑 4：按 `Enter` 换行却保存了注释

本课小结

下一课预告

附录：源码参考

添加计划注释：掌握四种注释类型 ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

核心思路 ​

注释类型详解 ​

工具栏工作流程 ​

type-to-comment 快捷键 ​

跟我做 ​

第 1 步：启动计划评审 ​

第 2 步：添加删除注释 ​

第 3 步：使用 type-to-comment 添加评论 ​

第 4 步：添加替换注释 ​

第 5 步：添加插入注释 ​

第 6 步：在注释中附加图片 ​

第 7 步：添加全局评论 ​

检查点 ✅ ​

踩坑提醒 ​

坑 1：找不到"替换"按钮 ​

坑 2：type-to-comment 失效 ​

坑 3：图片上传后找不到 ​

坑 4：按 Enter 换行却保存了注释 ​

本课小结 ​

下一课预告 ​

附录：源码参考 ​

添加计划注释：掌握四种注释类型

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

注释类型详解

工具栏工作流程

type-to-comment 快捷键

跟我做

第 1 步：启动计划评审

第 2 步：添加删除注释

第 3 步：使用 type-to-comment 添加评论

第 4 步：添加替换注释

第 5 步：添加插入注释

第 6 步：在注释中附加图片

第 7 步：添加全局评论

检查点 ✅

踩坑提醒

坑 1：找不到"替换"按钮

坑 2：type-to-comment 失效

坑 3：图片上传后找不到

坑 4：按 `Enter` 换行却保存了注释

本课小结

下一课预告

附录：源码参考