Feature Request: Remark Mode — AI 协作中的文档标注闭环

[liyuankui]

背景

我自己做了一个本地小工具 Remarker（隐私优先的 in-browser 标注工具），用于 AI 协作场景中的 Review-Revise 闭环。工作流如下：

AI 生成文档 → 用户在 Remarker 中标注（高亮 + 批注 + 行号引用）
           → 导出为结构化 prompt → AI 按行号精确修改 → 循环

效果截图：

这个流程在我的日常 AI 协作中使用频率很高（每日 10+ 次），但 Remarker 是一个独立的网页，需要额外启动本地 server 或部署到某个 Pages 服务。

---

为什么是 docu.md / markdown-viewer？

我在 Twitter 上看到 docu.md 后，觉得它是更好的载体：

1. 已经在浏览器里了——不需要额外启 server，打开 .md 文件天然触发
2. 渲染质量高——29 个主题 + Mermaid/PlantUML/LaTeX 完整支持，比我的 marked.js 单文件版好很多
3. 多平台——Chrome + Firefox + VSCode，一次实现多处可用
4. chrome.storage.local——Extension 有天然隔离的持久存储

核心观点：Remark（标注）是 AI 协作时代 Markdown 阅读器的自然延伸。

以前我们读文档是为了理解，现在我们读 AI 生成的文档是为了审查和反馈。从"只读 viewer"到"可标注 reviewer"，是一个很自然的功能演进。

---

提案：Remark Mode

交互设计

┌─────────────────────────────────────────────────┐
│ 🎨 Theme  📑 TOC  🔍 Zoom  ✏️ Remark  ⬇️ Export │  ← toolbar 加一个 toggle
└─────────────────────────────────────────────────┘

点击 ✏️ 进入 Remark Mode：
- 选中文字 → 弹出标注颜色选择（🟡 Suggestion / 🟢 Keep / 🔵 Question / 🩷 Concern）
- 写简短批注
- 文字高亮显示 + 行号标记
- Esc 退出 Remark Mode

导出格式

I reviewed "document.md" and have the following feedback:

1. [🟡 Suggestion] L5–L12: "原文片段..."
   Note: "建议修改为..."
2. [🟢 Keep] L15: "这段很好"
3. [🔵 Question] L23: "这里的逻辑是什么？"

这个格式对 AI（Claude/GPT/Gemini）非常友好——行号引用让 AI 能精确定位和修改。

存储

• chrome.storage.local，key 按文件内容 hash 组织
• 按文件内容 hash 存储（同一文件不同版本各自独立）
• 跨 tab 持久，关闭浏览器后重新打开仍在

---

使用场景

场景	流程
AI 代码 review	AI 生成 PR summary.md → 打开 → 标注需要修改的点 → Copy → AI 执行
文章编辑	AI 生成草稿 → 打开 → 标注改进建议 → Copy → AI 重写
技术文档审查	同事写的 RFC → 打开 → 标注疑问和建议 → Copy → 发到 chat
学习笔记	读长文 → 标注重点和疑问 → 导出为学习卡片

---

我能贡献什么

我愿意提交 PR 实现 MVP（先做 Chrome 版）：

• src/ui/remark-mode.ts — 模式管理 + 文字选中交互
• src/ui/remark-overlay.ts — 高亮层 + 标注 UI
• src/ui/remark-export.ts — 导出为结构化 prompt
• chrome/src/webview/ui/toolbar.ts — 加 ✏️ toggle button
• 预估 ~600 行新代码

---

相关参考

• 我的独立实现：Remarker（单文件 HTML，~160KB，完全本地运行，隐私优先）
• 类似理念：Hypothesis（但它是 SaaS，数据上云）
• 设计原则：内容不离开浏览器，零网络请求，纯本地标注

---

期待作者的想法！如果方向认可，我立刻开始写代码。

[xicilion]

这个主意很棒！我觉得 chrome/firefox 已经很赞了。vscode/obsidian 是窄面板，空间很局促。

我们需要讨论一下，工作区模式如何布局。在独立文件预览的时候，Remarker 面板，可以布局在现在文件面板的位置，在工作区模式，在一侧显示两个面板有些奇怪。
我看到你的应用里，把文件和 toc 放在一个面板里，这是个很好的主意，但是我担心这样影响面较大。

不知道你是怎么考虑。

[liyuankui]

感谢！截图中是本地在用的版本，比较随意。

MVP 我打算这样做：

• 先给 chrome/firefox 提供 remark 功能，vscode/obsidian 本身编辑能力强，优先级低
• Remark 面板打算放在右侧（独立预览时复用文件面板位置）。TOC 在左侧，两边共存，优点是 remark 的时候也能通过 TOC 跳转，缺点是可能有点乱，我们先看看效果
• 工作区模式先不处理，MVP 只在独立预览模式下启用 remark
• 不动整体框架结构，专注 remark 功能本身的迁移

关于你看到的 TOC + 文件合并的样子，这也是本地的版本。MVP 不碰， 左侧持现有面板结构。

[xicilion]

动作好快。我晚上来研究一下。

[xicilion]

我合并了 pr，修复了多语种适配。目前试用下来，有以下体验问题：

一、拖选文本，弹出批注框，点击其他位置时，没有批注，也会留下一条批注。需要手动删除。不太符合操作预期，需要考虑一下如何交互。我觉得批注还是要用户点击提交才保留，关闭时取消
二、目前支持一个段落多个批注，但是选择是整个段落，这一点会让人有些困惑，不知道其它批注软件怎么设计的
三、批注面板右上角删除全部，点击后没有生效

[liyuankui]

感谢详细反馈！已在 PR #83 中修复问题一和问题三。

问题一（点击外部留空批注） ✅ 已修复

现在只有用户主动交互（点击颜色按钮 或 输入内容）时，点击外部才会保留批注。否则视为取消，静默删除。

问题三（全部删除无效） ✅ 已修复

改为单击立即清除 + 5 秒 undo 倒计时（和单条删除体验一致）。不再需要二次点击确认。

问题二（段落多条批注 + 全段高亮） 💬 待讨论

这是设计层面的权衡。目前 block 级高亮是为了定位到段落，而不是精确标记选中文字（选中文字保存在批注内容里）。一个段落支持多条批注是预期的功能，但可能需要更好的视觉区分。

你有什么想法？比如：

• 限制同一段落只能有一条批注？
• 悬停某条批注时高亮对应的引用文字？

[xicilion]

我觉得批注的体验，可以参考微信读书的划线。用户可以选择一段文字，标记并批注。显示的时候，只在选中的文本增加样式，这样可以在一个段落显式多个批注。

[liyuankui]

这个方向我研究了一下，微信读书的划线体验确实很好，但在这个场景里实现代价较高，建议 defer：

技术难点：
Inline 精确高亮需要处理跨 DOM 元素选择（如 <strong>/<td> 边界），Range.surroundContents() 遇到跨元素就会抛错。正确做法是逐 text node 包装，类似 web-highlighter 或 hypothesis 的实现。

更麻烦的是序列化：每次 Markdown 重新渲染，DOM 节点全部重建，保存的高亮位置必须重新 anchor。Hypothesis 为此实现了 XPath + 文字偏移 + 前后缀模糊匹配三级 fallback，大约 200+ 行核心代码，且只有这套能稳定存活在 re-render 之后。

设计立场：Remark Mode 的核心用途是把标注导出给 AI 处理（文字引用 + 颜色语义已经足够），而不是给人阅读时的视觉精确标注。Block 级高亮在这个场景下足够准确，且实现稳定。

可以考虑的折中：在 sidebar 里，hover 某条批注时 scroll-to 并短暂闪烁对应 block，用交互而不是颜色来区分同一 block 的多条批注。改动小，效果明确。

你觉得呢？inline 精确高亮可以作为 v2 的方向，等需求更明确再做。

[liyuankui]

PR #85 已 rebase 到最新 main，冲突已解决（采用了 72dedef 的 behavior: 'auto' + landing pulse 结合）。

本次更新包含：

Sub-block 粒度（已有）：

• 表格行级、列表项级、代码块行级标注

UX 大修（新增）：

• Gmail 风格 undo toast 替代倒计时删除
• 编排式退出动画（无闪烁）
• 侧边栏点击 → ring pulse 落地动画
• scrollIntoView 统一使用 auto（与 72dedef 一致）

Ready for review 🙏