Agent Review

Agent Review

Agent Review is an Obsidian plugin for structured reading annotations — highlights, inline comments, free-form spatial sticky notes, and visual Bézier relation lines — built around Human / AI Agent collaboration on a shared review dataset.

Review data is stored as structured records in your vault's .agent-review/ directory, kept separate from the Markdown so the source text stays clean. The same Review renders consistently across Live Preview, Source and Reading modes, the Review View, and the visual layers beside the content.

Both humans and external AI agents operate on the same data layer: humans through the editors and a review view, agents through a local file-command queue, a CLI, and a versioned in-vault API. Agent Review ships no built-in LLM, makes no network requests on its own, and sends no telemetry — everything stays local. Install via the community plugin directory or from the GitHub Releases (see below).

---

Agent Review 是一个面向 Obsidian 的结构化阅读批注插件，支持高亮、批注、回复、自由便签、可视化关系线，以及 Human / AI Agent 协作。

批注数据独立保存在 Vault 的 .agent-review/ 中，不会向 Markdown 正文写入额外标记。人类用户与外部 AI Agent 可以基于同一套 Review 数据进行创建、回复、修改、筛选和管理。

同一条 Review 可以在实时预览、源码模式、阅读模式、ReviewView 和正文附近的视觉层中保持一致。

当前版本：2.0.3

插件 ID：agent-review

最低 Obsidian 版本：1.7.2

---

核心功能

结构化阅读批注

Agent Review 将高亮、批注、回复和关系数据统一管理为结构化 Review。

支持：

• 高亮
• 普通批注
• 建议
• 问题
• 核实项
• 回复
• 标签
• 状态
• 历史记录
• 多颜色标记

每个 Review 都拥有稳定的 ID、Anchor 和历史记录。

---

高亮系统

支持多种高亮样式：

• 背景颜色
• 文字颜色
• 单下划线
• 双下划线
• 波浪线
• 左侧竖线
• 边框
• 透明背景

支持：

• 常用颜色循环
• 连续高亮
• 批量操作

连续高亮默认关闭，可随时通过 Esc 退出。

---

ReviewView

ReviewView 是 Agent Review 的统一管理界面。

可以查看：

• 当前 Review
• 当前文档 Review
• 整个 Vault Review

支持筛选：

• 文本内容
• 状态
• 来源
• 类型
• 标签
• 颜色
• 时间顺序

统计数据会根据当前筛选结果实时更新。

---

批量管理

支持多选 Review 后执行：

• 解决（Resolve）
• 重新打开（Reopen）
• 归档（Archive）
• 修改颜色
• 添加标签
• 导出
• 永久删除

永久删除需要用户确认。

---

空间便签

重要 Review 可以固定到正文附近，形成空间便签。

桌面端支持：

• 自由拖动
• 调整位置
• 就地编辑
• 与正文建立视觉联系
• 与其他便签建立关系

便签拖动过程中只更新界面状态，松开后才保存最终布局。

位置数据基于 Anchor 保存。

取消固定只会移除视觉呈现，不会删除：

• Review
• Anchor
• 评论
• 回复
• Relation

---

可视化关系线

Agent Review 支持建立 Review 之间的视觉关系。

支持：

• 正文 ↔ 正文
• 正文 ↔ 便签
• 便签 ↔ 便签

关系使用 SVG Bézier 曲线显示。

---

Relation 编辑

支持：

• 调整端点
• 调整控制柄
• 修改颜色
• 修改线宽
• 实线 / 虚线
• 显示 / 隐藏
• 正文上层 / 下层显示

删除 Relation 时，只删除关系本身，不会删除：

• Review
• Anchor
• 高亮
• 评论
• 回复
• 便签

---

Bézier 控制

普通拖动保持自由曲线。

按住 Shift 时，控制柄方向自动吸附到：

• 0°
• 90°
• 180°
• 270°

同时保持拖动距离。

拖动过程中：

• 按下 Shift → 开启吸附
• 松开 Shift → 返回自由模式
• 按 Esc → 取消当前操作

---

Undo / Redo

Relation 编辑支持：

• Ctrl + Z
• Ctrl + Shift + Z
• Ctrl + Y

支持撤销 / 重做：

• 创建 Relation
• 删除 Relation
• 移动端点
• 调整控制柄

Markdown 编辑器、输入框和便签编辑拥有快捷键优先权，不会影响 Obsidian 原有撤销逻辑。

---

调整 Review 范围

Agent Review 支持在不删除原 Review 的情况下重新调整正文范围。

提供两种方式：

拖动范围控制柄

适合对现有范围进行小幅扩大或缩小。

重新选择正文

“调整标注范围”允许重新选择一段正文，并将新的 Anchor 应用到原 Review。

两种方式都会保留原有：

• Review ID
• 评论
• 回复
• 标签
• 状态
• 便签
• Relation

不会通过“删除旧 Review → 新建 Review”的方式替换数据。

---

正文定位与跳转

Review 卡片、ReviewView 和 Margin 中的 Review 可以跳转回正文对应位置。

定位过程包括：

1. 查找对应 Review ID 的正文标记
2. 滚动到可见区域
3. 短暂闪烁提示位置

Reading View 中通过：

data-agent-review-id

识别具体 Review。

在复杂情况下，插件会结合 Anchor、正文位置和文本内容进行定位。

---

Reading View

Agent Review 支持在 Obsidian 阅读模式中显示 Review。

Reading Processor 会：

• 读取当前文档 Review
• 根据 Anchor 定位正文
• 处理相同文本重复出现的情况
• 支持跨多个 Text Node 的高亮范围
• 避免重复嵌套 Agent Review 标记
• 不删除用户或其他插件创建的普通 <mark>

Reading View 中的 Review 标记使用：

data-agent-review-id

和：

data-agent-review-reading-view

用于正文定位和安全重新渲染。

---

阅读背景

阅读模式可以使用独立背景，不会修改：

• 编辑器
• Obsidian 全局主题
• 其他视图

内置选项包括：

• 白色
• 米黄色
• 浅灰
• 护眼绿
• 深色
• 自定义背景

---

Anchor 与正文变化

每个 Review 都通过 Anchor 与正文关联。

Anchor 会保存与正文位置相关的信息，用于在 Markdown 内容发生变化后重新定位。

当正文修改导致 Anchor 无法可靠恢复时：

• Review 不会被静默删除
• Review 数据仍然保留
• 状态可以转为 orphaned
• 用户可以重新绑定 Anchor

---

重复高亮处理

创建高亮时，Agent Review 会检查当前位置是否已经存在相同或冲突的 Review。

用于减少：

• 重复高亮
• 相同 Anchor 重复创建 Review
• 重复渲染

Reading View 和 Editor View 会使用统一的渲染选择逻辑，决定最终需要显示的 Review。

---

导出与汇总

支持：

• 当前文档导出
• 全库导出
• 当前筛选结果导出
• 所选 Review 导出

导出格式包括：

• Markdown
• JSON

JSON 可用于后续导入或其他程序处理。

还可以将 Review 汇总为普通 Markdown 笔记：

Agent Review Summaries/

导出不会修改 .agent-review/ 中的原始数据。

如果目标文件已经存在，会自动创建带数字后缀的新文件，避免覆盖。

---

Review 深链

Agent Review 支持通过：

obsidian://agent-review

形式的链接返回具体 Review。

深链基于稳定 Review ID，而不是依赖固定正文位置，因此正文发生变化后仍可以尝试定位到当前实际位置。

---

AI Agent 协作

Agent Review 不内置 LLM，也不会替用户选择 AI 模型。

插件提供的是一套可以被外部 Agent 使用的结构化 Review 数据层。

Human 与 Agent 使用同一套 Review 数据，而不是维护两套独立批注系统。

外部 Agent 可以通过以下方式与 Agent Review 协作。

文件命令队列

.agent-review/commands/

Agent 可以通过文件方式提交命令并读取结果。

CLI

提供：

agent-review

命令行接口。

插件内 API

提供版本化的：

window.AgentReviewAPI

外部工具可以通过 API 与插件集成。

Agent 可以根据权限执行例如：

• 读取 Review
• 创建 Review
• 回复
• 修改状态
• 修改标签
• 管理关系
• 查询变化

权限、Schema、幂等结果和变化索引用于限制和追踪写入。

详细文档：

• Agent 文件接口
• CLI
• 公共 API

---

数据保存位置

Agent Review 默认将数据保存在当前 Vault 根目录：

.agent-review/
├── reviews/       # 每个笔记对应的 ReviewDocument
├── index/         # 清单、变化索引和事件
├── commands/      # Agent 命令与结果
├── backups/       # 自动和手动备份
├── archive/       # 已删除笔记对应的 Review 归档
├── styles/        # 颜色与样式预设
├── conflicts/     # 无法安全读取的数据
└── logs/          # 操作日志

Review 数据不会批量写入 Markdown 正文。

ReviewDocument v2 在同一文档中管理：

• items
• layout
• relations

三者通过稳定 Review ID 建立关联。

---

数据安全

Agent Review 的 Review 数据独立保存在 Vault 中，不会批量写入 Markdown 正文。

插件使用安全写入、备份、归档和恢复机制，尽量避免因为异常覆盖或删除导致 Review 数据丢失。

支持：

• 自动备份
• 手动备份
• 归档
• 恢复
• 索引重建
• Anchor 检查
• v1 → v2 数据迁移

---

隐私

Agent Review 本身：

• 不要求注册账号
• 不内置大模型
• 不包含遥测
• 不主动联网
• 不自动上传 Markdown
• 不自动上传 Review
• 不要求用户填写 API Key

数据默认保存在当前 Vault。

只有用户主动执行导出或汇总时，才会在 Vault 中创建额外文件。

如果用户连接外部 AI Agent：

是否联网、使用哪个模型、发送哪些内容，以及如何保存这些数据，都取决于用户选择的 Agent、模型和权限配置。

这些行为不是 Agent Review 自动执行的。

CLI 只在用户明确运行时访问用户指定的 Vault。

---

安装

Obsidian 社区插件目录

Agent Review 通过 Obsidian 社区插件目录审核后，可以在：

设置 → 第三方插件 → 浏览

搜索：

Agent Review

进行安装。

在社区目录审核期间，也可以通过 GitHub Release 手动安装。

---

手动安装

从对应版本的 GitHub Release 下载：

• main.js
• manifest.json
• styles.css

然后在 Vault 中创建：

<Vault>/.obsidian/plugins/agent-review/

将三个文件放入该目录：

agent-review/
├── main.js
├── manifest.json
└── styles.css

重新加载 Obsidian 后，在：

设置 → 第三方插件

启用 Agent Review。

---

从源码构建

需要 Node.js 和 pnpm。

pnpm install --frozen-lockfile
pnpm build

构建后的安装文件位于仓库根目录：

• main.js
• manifest.json
• styles.css

---

基本使用

创建高亮或批注

选择 Markdown 正文后，可以通过：

• 右键菜单
• 选区浮动工具栏
• 命令面板

创建 Review。

插件默认不占用全局快捷键。

如有需要，可以在：

设置 → 快捷键

中为 Agent Review 的相关命令配置快捷键。

---

编辑 Review

Review 可以执行：

• 编辑内容
• 修改标签
• 修改颜色
• Resolve
• Reopen
• Archive
• Delete

Human UI 中的永久删除需要确认。

Agent 命令的删除权限由 Agent 权限机制单独控制，不会因为 UI 可以删除就自动获得相同权限。

---

固定便签与关系操作

固定 Review

在 Review 卡片或 ReviewView 中选择“固定到正文附近”，即可将 Review 显示为空间便签。

桌面端可以：

• 拖动便签
• 调整位置
• 就地编辑
• 与正文建立关系
• 与其他便签建立关系

取消固定不会删除 Review 本体。

---

创建 Relation

从正文 Review 或固定便签发起“创建关系”，然后选择目标 Review。

关系可以存在于：

• 正文与正文之间
• 正文与便签之间
• 便签与便签之间

---

编辑 Relation

选中关系后，可以：

• 修改线条样式
• 调整 Bézier 控制柄
• 移动端点
• 删除关系
• 调整显示层级
• 显示或隐藏关系

点击正文空白区域或按 Esc 可以退出 Relation 选中状态。

---

删除 Relation

可以通过：

• 关系上的删除按钮
• Delete
• Backspace

删除当前 Relation。

删除 Relation 不会删除两端的 Review。

---

移动端

Agent Review 在移动端采用降级交互。

移动端保留：

• ReviewView
• 阅读模式 Review
• 高亮
• 批注
• 简化固定卡片
• Relation 显示

复杂空间操作主要面向桌面端，包括：

• 自由拖动便签
• Bézier 端点编辑
• Bézier 控制柄编辑
• 精细 Relation 布局

Android / iOS 的实机测试覆盖仍在持续扩大。

---

备份与恢复

重要 JSON 文件在覆盖前，会在：

.agent-review/backups/auto/

中保留旧版本。

用户还可以：

• 创建手动备份
• 恢复备份
• 重建 Review 索引
• 检查 Anchor

删除 Markdown 笔记后，其关联 ReviewDocument 会进入归档，而不是立即永久删除。

---

卸载

禁用或删除 Agent Review 插件文件：

不会自动删除 .agent-review/。

这样可以避免用户因为卸载插件而意外丢失批注数据。

卸载前建议创建一次手动备份。

只有在确认不再需要以下数据后：

• Review
• 回复
• Relation
• 便签
• 备份
• 归档

才建议用户自行删除：

.agent-review/

---

常见问题

为什么正文没有显示 Review？

请检查：

1. 当前文件是否为 Markdown；
2. Review 是否已经归档；
3. Anchor 是否仍然有效；
4. 是否需要重新绑定 Anchor；
5. 是否需要重建 Review 索引。

可以运行：

检查全部锚点

或：

重建审阅索引

正文变化导致 Anchor 无法恢复时，Review 会保留为 orphaned，不会被静默删除。

---

为什么移动端不能编辑 Bézier 控制柄？

精细空间关系编辑目前主要针对桌面端。

移动端仍可以查看 Review、批注和简化关系，但复杂端点与 Bézier 控制柄建议在桌面端完成。

---

数据可以同步吗？

.agent-review/ 位于 Vault 内，因此可以随用户选择的 Vault 同步方式一起同步。

例如：

• Obsidian Sync
• 文件同步工具
• 云盘
• Git
• 其他用户自己的同步方案

但多设备同时修改同一 ReviewDocument 时，高级三方合并界面目前尚未实现。

建议在多设备同步前保留备份。

---

已知限制

当前版本仍存在以下限制：

• 自动避让采用稳定的外侧 Bézier 路径，并不是完整的障碍物感知 pathfinding。
• 复杂 Markdown inline token、嵌入块和极端跨段选择仍需要更多真实文档回归。
• 移动端不提供自由便签拖动和复杂 Relation 控制柄编辑。
• 多设备同时修改同一 ReviewDocument 时，高级三方冲突合并 UI 尚未完成。
• Android / iOS 实机和视觉回归测试覆盖仍在扩展。

部分复杂视觉交互仍需要在真实 Obsidian 环境中进行人工验收。

详见：

人工验收清单

---

路线图

计划中的方向包括：

• 更精细的复杂 Markdown Anchor 映射
• 更可靠的跨块定位
• 多设备同步冲突三方合并界面
• 更高级但保持可预测的 Relation 避障
• Android / iOS 实机矩阵
• 自动化视觉回归
• 可选 Agent 连接器
• 更丰富的 Review 查询和管理能力

文件命令队列仍会保留为一种简单、可检查、可靠落盘的 Agent 协作协议。

---

开发

安装依赖：

pnpm install --frozen-lockfile

开发模式：

pnpm dev

执行完整验证：

pnpm verify

运行测试：

pnpm test

生成覆盖率：

pnpm test:coverage

贡献代码前请阅读：

CONTRIBUTING.md

开发时请注意：

• 新增 Schema 字段必须提供 migration
• Editor / Reading / 移动端 UI 变化需要真实 Obsidian 回归
• 不要提交私人 Vault
• 不要提交 .agent-review/ 用户数据
• 不要提交 API Key、Token 或其他密钥

---

License

MIT License

Copyright © 2026 JiaoXiu