obelisk

Obelisk

为 Obsidian 提供行内评论和 GitHub 风格的建议编辑。

选中一段文字，为其留下评论，还可以提出替换建议，只需单击一次即可应用。评论存储在笔记自身的 frontmatter 中，因此会随文件一起同步、提交到 git、导出和重命名。

obelus（†）是古代编辑在手稿页边绘制的标记，用来表示：这段内容存在争议。

状态

目前处于早期阶段。锚定、装饰、侧边栏、建议编辑和 Agent 集成都已实现。该插件已上架 Obsidian 社区插件目录，CLI 和 MCP 服务已发布到 npm，包名为 obelisk-mcp。目前所有功能都尚未在大型库中进行过测试。

安装

在 Settings → Community plugins → Browse 中搜索 Obelisk，安装并启用。可在同一面板中获取更新。

也可以通过其目录页面中的 Add to Obsidian 按钮添加该插件。

功能

• 评论任意段落。 选择文本，右键，然后选择 添加评论。
• 处处支持 Markdown。 评论和回复都是普通的 Markdown，输入时可在“编写／预览”之间切换。链接、列表、提示框、嵌入内容和数学公式都会在侧边栏中准确渲染，效果与笔记中相同。
• 建议修改。 修改建议是在评论内部用围栏代码块 ```suggestion 写成的，方式与 GitHub 相同。它会以差异形式显示与引用段落的对比，并附带“应用”按钮，因此一条评论既可以解释问题，也可以提出修改；回复则可以提供相反的建议。如果原文已更改，则无法应用修改。应用后，评论也会标记为已解决；如果评论提出的问题并未通过修改得到解答，还可以选择重新打开。
• 侧边栏。 按文档顺序显示笔记的所有评论，也可以通过排序开关改为最新评论优先。点击评论即可滚动编辑器至对应位置。筛选标签可用于筛选未解决的评论、带有建议的评论，或某个 Agent 的审阅记录。已解决的评论仍会显示在列表中，只是呈灰色，而不会隐藏，因为它们在笔记中仍有高亮标记。
• 文内高亮。 被评论的段落会高亮显示，并带有 † 标记，点击即可在侧边栏中打开评论。
• 存储在 frontmatter 中。 使用 obelisk 键下的纯 YAML 格式。易于阅读、比较差异和移植。
• 编辑后仍然保留。 评论锚定在引用的文本上，因此即使笔记其他位置发生编辑（包括在 Obsidian 之外进行的编辑），评论也会保持关联。如果编辑或删除了引用段落本身，评论会脱离锚点：在侧边栏中标记出来、不再高亮任何内容、绝不会移到其他段落上，也不会被删除。恢复原文后，评论会重新关联。已解决的评论不会被标记，因为完成评论所要求的修改时，评论通常会脱离锚点。
• 沿用你熟悉的编辑器。 评论使用 Obsidian 自带的 Markdown 编辑器编写，因此 Cmd+B、列表续写、[[ 自动补全和实时预览在评论中的表现与笔记中完全相同。
• 支持嵌套回复。 可在任意评论下回复，回复与评论一起存储，并且全程支持 Markdown。
• 可编辑。 可通过卡片上的 编辑 按钮或右键点击段落，在编写该评论或回复的同一个编辑框中修改内容，建议按钮也一并保留。编辑过的内容会标记出来。锚点不会更改，因此修改评论内容不会改变评论所针对的对象。
• 可删除。 可通过卡片上的 删除 删除整条评论，也可以通过回复标题中的垃圾桶图标删除单条回复，这样从讨论串中删除一条评论时，不会一并删除整段对话。两种操作都会提供撤销选项，而非确认对话框。
• 支持 Agent。 命令行工具和 MCP 服务可从 Obsidian 外部读写同一批评论，因此模型可以审阅笔记并将评论加入侧边栏，也可以回复留给它的评论。模型的评论会带有标记；一轮审阅中的所有评论会在标题栏中显示为一个标签，并提供全部关闭选项。详见下文。

数据格式

---
obelisk:
  - id: cq7fk2m9x
    author: zach
    created: 2026-08-29T14:02:11.000Z
    body: |-
      This paragraph does two things at once.

      ```suggestion
      The horse bolted.
      ```
    anchor:
      from: { line: 12, col: 0 }
      to: { line: 12, col: 47 }
      quote: The horse, which had been standing there, bolted.
---

一条评论就是一段 Markdown。建议修改使用评论内部的围栏代码块 ```suggestion，应用时其内容会精确替换锚定范围，因此一条评论可以同时包含说明文字、链接和修改建议。

quote 是评论锚定的文本。行／列范围记录了编写评论时段落所在的位置，用于排列侧边栏，并在引用文本重复出现时区分位置；该范围永远不会被重写。行号从 frontmatter 块后的第一行开始计数，因此添加评论不会使其他评论失效。

由模型编写的评论还会带有一个额外的键 origin，其中保存模型名称和一个 ID；同一轮审阅中的所有评论都共享该 ID。如果没有这个键，则表示评论由用户编写，因此知识库中已有的内容无需迁移。

Agent

在 Obsidian 外部添加相同的批注。模型审阅一条笔记，批注会出现在你当前打开的笔记侧边栏中。或者，你可以留下请求，模型会阅读请求、进行编辑并解决这些批注。

npm install -g obelisk-mcp            # puts `obelisk` and `obelisk-mcp` on PATH

obelisk list note.md
obelisk comment note.md --quote "The horse, which had been standing there, bolted." \
  --body "Two clauses fighting over one sentence." --run r7k2mq

对于支持 MCP 的 Agent，请向其注册服务：

claude mcp add obelisk --scope user -- npx -y obelisk-mcp

注册一次即可覆盖所有库：工具会作用于 Agent 当前运行所在的库，而绝对路径可以指向它不在其中的库里的笔记。对于从官方 MCP 注册表安装的客户端，该服务在注册表中的名称为 io.github.zachhannum/obelisk。

由 Agent 启动服务。 服务通过 stdio 使用 MCP：会话打开时，Agent 会启动一个进程；会话结束时，Agent 会终止该进程，因此无需端口，也无需守护进程。每个会话运行一个进程，也正是同一会话的批注会在侧边栏共用一个运行标记的原因。会话会保留它启动的进程，因此新版本的软件包要到下一个会话才会生效。若要提前更新，请从 /mcp 重新连接。

要检查注册情况，请运行 claude mcp list，或在会话中使用 /mcp。若要在不通过 Agent 的情况下检查服务本身：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | npx -y obelisk-mcp

这会打印握手信息，然后列出四个工具。服务在此处运行失败时，通过 Agent 运行也会以相同方式失败。

对于不支持 MCP 的 Agent，请将 docs/agents-fragment.md 粘贴到库的 AGENTS.md 或 CLAUDE.md 中。

只需记住一条规则：引文才是锚点。 行号永远不是锚点。让模型提供行号，它可能会给出看似合理但实际错误的数字；这样一来，批注就会附到错误的段落上，却看不出有任何问题。因此，--near-line 只会在引文完全相同的情况下进行选择，并且需要使用从 obelisk list 复制的数字。--quote 必须与笔记中的内容逐字一致；如果不一致或出现两次，就不会写入任何内容，并会打印原因。obelisk list 会为正文标上行号，方便复制准确文本。

写入操作只修改 frontmatter，正文的字节内容保持不变，因此笔记在 Obsidian 中打开时也可以安全写入。写入前还会重新读取文件；如果文件在此期间发生变化，操作就会拒绝执行。

开发

npm install
npm run dev      # watch build, plugin only
npm run build    # typecheck, then main.js plus dist/cli.mjs and dist/mcp.mjs

src/core/ 是不导入 Obsidian 的部分：包含模型、锚点运算、YAML 和四种操作。插件、CLI 和 MCP 服务是建立在它之上的三个前端。

site/ 是文档站点，是独立的 Astro 项目，有自己的 npm install。它不属于 npm run build 的构建范围。

将仓库符号链接到测试库即可试用：

ln -s "$PWD" /path/to/vault/.obsidian/plugins/obelisk

许可证

MIT