MRSF (Wictorwilen)

Markdown评论侧车格式（MRSF）——草稿

  ](https://www.npmjs.com/package/@mrsf/cli) ](https://www.npmjs.com/package/@mrsf/mcp) ](https://www.npmjs.com/package/@mrsf/cli) ](https://www.npmjs.com/package/@mrsf/mcp)    ](https://www.npmjs.com/package/@mrsf/markdown-it-mrsf) ](https://www.npmjs.com/package/@mrsf/marp-mrsf) ](https://www.npmjs.com/package/@mrsf/marked-mrsf) ](https://www.npmjs.com/package/@mrsf/rehype-mrsf) 

Markdown评论侧车格式（MRSF），也称为 侧面标记，是一种可移植、版本控制和机器可操作的方式来存储评论 *外面* Markdown文件。

🌐 sidemark.org · 💻 VS代码扩展

这使得：

• Markdown文档干净整洁
• 审查历史记录在编辑过程中持续存在
• 能够可靠地推理评论的自动审查工具和人工智能代理/技能

🧠 这解决了什么问题

如今的Markdown工作流程在持久、上下文感知的评论方面遇到了困难：

• 内联注释不能随文本移动
• GitHub/GitLab评论随着编辑而消失
• 自动化代理（LLM、机器人）没有用于反馈的结构化API

MRSF通过以下方式解决了这个问题 sidecar文件 其将审查元数据与内容分开，并为工具提供CLI/MCP接口。

🚀 特性

• Markdown评论的标准化sidecar格式
• 具有线/跨度+回退匹配的锚点(selected_text)
• 使用可配置策略在编辑后重新锚定
• 用于验证的JSON模式
• 用于验证、重新定位、状态检查的CLI工具
• MCP服务器，用于与LLM和助理客户端集成
• Python CLI和SDK(pip install mrsf)--Node.js CLI的1:1端口
• 用于Marp、Marked、markdown it和重新键入/统一生态系统的渲染插件
• VS Code、Monaco、Milkdown/Crepe和实验性Tiptap主机的交互式编辑器集成

📄 规格

完整规格可在 MRSF-v1.0.md.

🔧 快速开始

安装

# Node.js
npm install -g @mrsf/cli

# Python
pip install mrsf

典型工作流程

# create a sidecar for a Markdown file
mrsf init docs/architecture.md

# add a comment anchored at line 12
mrsf add docs/architecture.md -l 12 "Add more detail about this architecture."

# check for issues
mrsf validate

# after the document changes
mrsf reanchor

# see comment health
mrsf status

您还可以在创建注释时附加特定于工具的扩展字段。公共SDK和MCP服务器接受这些作为键/值映射，并将其作为平面存储在磁盘上 x_* 领域：

mrsf add docs/architecture.md \
  --author "review-bot" \
  --text "Needs a second pass" \
  --line 12 \
  --ext x_source=review-bot \
  --ext x_score=0.91 \
  --ext 'x_labels=["needs-review","docs"]'

请参阅中的完整CLI文档 cli/README.md，或运行 mrsf --help.

📦 示例

小型侧车(.review.yaml)Markdown旁边）：

mrsf_version: "1.0"
document: docs/architecture.md
comments:
- id: abc123
  author: Jane Doe
  timestamp: '2026-03-02T18:22:59Z'
  text: "Can you clarify this section?"
  resolved: false
  line: 9

具有精确跨度的高级示例：

- id: def456
  author: Jane Doe
  timestamp: '2026-03-02T18:24:51Z'
  text: "Is this phrasing accurate?"
  type: question
  resolved: false
  line: 12
  end_line: 12
  start_column: 42
  end_column: 73
  selected_text: "While many concepts are represented"

更多示例：请参见 examples 文件夹。

🛠 MCP 服务器

您可以将MRSF作为MCP（模型上下文协议）服务器运行，用于LLM/助手集成。

安装：

npm install -g @mrsf/mcp

示例（Claude桌面配置）：

{
  "mcpServers": {
    "mrsf": {
      "command": "npx",
      "args": ["-y", "@mrsf/mcp"]
    }
  }
}

服务器公开以下资源：

• mrsf://sidecar/{path}
• mrsf://comment/{path}/{id}
• mrsf://anchors/{path}

请参阅中的完整MCP服务器文档 mcp/README.md.

💻 VS代码扩展

VS代码的侧标 将MRSF评论直接带入您的编辑器中——边栏图标、内联预览、悬停卡片、侧边栏面板和保存时自动重新排序。

从安装 Visual Studio市场 或搜索 “侧标” 在VS代码扩展视图中。

🧪 Monorepo测试

所有Types/Vitest包现在都可以从存储库根运行：

npm install
npm test

对于观看模式或从根开始的覆盖范围：

npm run test:watch
npm run test:coverage

根Vitest项目汇总了：

• cli/
• mcp/
• plugins/shared/
• plugins/markdown-it/
• plugins/monaco/
• plugins/rehype/
• vscode/

🐍 Python CLI和SDK

CLI和库的完整Python端口，可通过pip安装：

pip install mrsf

相同的9个命令，相同的库API，相同的134个测试：

import mrsf

doc = mrsf.parse_sidecar("README.md.review.yaml")
for comment in doc.comments:
    print(f"{comment.author}: {comment.text}")

result = mrsf.validate(doc)

Python在添加注释时使用相同的显式扩展映射契约：

opts = mrsf.AddCommentOptions(
  author="review-bot",
  text="Needs a second pass",
  line=12,
  extensions={
    "x_source": "review-bot",
    "x_score": 0.91,
    "x_labels": ["needs-review", "docs"],
  },
)

看 python/README.md 获取完整的SDK参考。

🎨 渲染插件

在Markdown输出中直接将MRSF评论渲染为徽章、亮点和工具提示。

markdown it插件

对于VitePress，markdown it和任何基于markdown it的渲染器：

npm install @mrsf/markdown-it-mrsf

import MarkdownIt from "markdown-it";
import { mrsfPlugin } from "@mrsf/markdown-it-mrsf";

const md = new MarkdownIt();
md.use(mrsfPlugin, { sidecarPath: "doc.md.review.yaml" });

看 plugins/markdown-it/README.md.

Marp插件

对于Marpit和Marp显示管道：

npm install @mrsf/marp-mrsf

import { Marpit } from "@marp-team/marpit";
import { mrsfPlugin } from "@mrsf/marp-mrsf";

const marpit = new Marpit();
marpit.use(mrsfPlugin, { comments: sidecarData, interactive: true });

插件添加 data-mrsf-page 元数据到渲染的页面容器，并且只接受供应商 x_page 当演示级别锚点比行锚点更有用时，注释会提示。

看 plugins/marp/README.md.

标记插件

对于Node.js或浏览器中的基于标记的渲染器：

npm install marked @mrsf/marked-mrsf

import { Marked } from "marked";
import { markedMrsf } from "@mrsf/marked-mrsf";

const parser = new Marked();
parser.use(markedMrsf({ sidecarPath: "doc.md.review.yaml" }));

看 plugins/marked/README.md.

重新键入插件

对于Astro、Next.js MDX、Docusaurus和统一生态系统：

npm install @mrsf/rehype-mrsf

import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { rehypeMrsf } from "@mrsf/rehype-mrsf";
import rehypeStringify from "rehype-stringify";

const file = await unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeMrsf, { sidecarPath: "doc.md.review.yaml" })
  .use(rehypeStringify)
  .process(markdown);

看 plugins/rehype/README.md.

✍️ 交互式编辑器集成

当您希望在实时编辑界面中而不是呈现HTML中查看工作流时，MRSF还提供了编辑器本地集成。

摩纳哥插件

对于浏览器和桌面应用程序中的摩纳哥编辑器：

npm install @mrsf/monaco-mrsf monaco-editor

看 plugins/monaco/README.md.

Tiptap插件（实验版）

对于浏览器托管的Tiptap编辑器，具有内联高亮显示、排水沟和明确的保存审查工作流：

npm install @mrsf/tiptap-mrsf @tiptap/core @tiptap/starter-kit

看 plugins/tiptap/README.md.

牛奶+奶油插件

这 @mrsf/milkdown-mrsf 该包在Milkdown直接编辑器和更高级别的Crepe shell中运行相同的MRSF审查控制器。它涵盖了sidecar加载/保存/重新加载/重新加载流、内联锚点、沟槽覆盖、线程工具提示以及通过浏览器主机适配器进行的基于选择的注释操作。

尝试演示：

cd examples
npm install
npm run demo:milkdown

然后打开打印的本地Vite URL并导航到 / 在共享同一审阅运行时的情况下，在直接Milkdown和Crepe之间切换。

看 plugins/milkdown/README.md.

🧪 状态

草稿：本规范和工具开放供反馈和改进。

提交问题或带建议的拉取请求。

❤️ 贡献

我们欢迎：

• 规范审查
• CLI/MCP/Python SDK的实施反馈
• 与编辑器、渲染器和机器人的集成示例

看 CONTRIBUTING.md

免责声明 MRSF是一个个人开源项目。 它是 不隶属于、不受微软认可或不符合微软官方标准. 任何内部实验都不意味着产品采用。

📄 许可证

MIT