Markdown Review

Markdown Review 是一个本地优先的 MCP Apps 界面，用于审阅渲染后的 Markdown，而不会创建文档的第二个可编辑副本。选择一段文字或选择一张图片，排队基于行的反馈，并将完整审阅一次性提交给编码代理。Codex App 是首个已发布的交互式主机；核心契约、状态和 UI 有意保持主机中立，以便未来适配 Claude、pi、终端和 Tauri。

状态： 早期开发。Codex App 是已发布的交互式主机；可复用的 UI 和 MCP 传输遵循 MCP Apps 标准，因此无需重写审阅核心即可添加其他主机适配器。

提供的功能

• 侧面板中的全屏、GitHub 风格 Markdown 预览。

• 正常的文本选择和复制，以及针对选中文本、图片和整篇文档反馈的审阅菜单。

• 可聚焦的图片审阅目标，支持指针、触摸和键盘评论。

• 不显眼的图片反馈控件，仅在悬停、键盘聚焦或主动触摸时出现在图片右下角。

• 内联评论标记，编号为 #1、#2 等。

• 审阅队列，将所有评论一起提交以避免冲突编辑。

• 使用 #N 引用已排队的评论；如需字面文本，请写 \#N 或 `#N`。

• 相对本地 PNG、JPEG 和静态 WebP 渲染，采用有界、私有的分块传输。

• 在 Codex 创建或实质性编辑 Markdown 文档后自动审阅。

Markdown 源始终是规范版本。该组件是只读审阅界面；只有 Codex 使用其正常的文件系统工具编辑源文件。

Related MCP server: md-annotate

工作原理

local .md file
    │
    ├── open_markdown_review ──► sanitized rendered component (private UI payload)
    │                                  │
    │                                  └── queued, line-anchored comments
    │                                                   │
    └◄──────────── Codex edits the original file ◄──────┘
                              one batch message

MCP 服务器刻意保持狭窄：

1. open_markdown_review 验证并渲染绝对 .md 或 .markdown 路径。

2. 仅组件工具水合渲染后的文档，并以有界块流式传输已批准的本地光栅图片。

3. 模型可见的工具结果包含文件元数据，而非完整文档。渲染内容私下传递给组件。

4. 技能说明 Codex 应如何解释审阅反馈并安全地修改底层 Markdown。

这种分离是项目包含 MCP 的原因：服务器将 Codex 工具调用连接到受信任的交互式组件。静态 HTML 文件本身无法接收选定的源文件、将结构化审阅评论返回给活动任务，或维持此上下文边界。

实现分为主机中立的 TypeScript 工作区。contracts 验证每个边界，core 拥有纯审阅状态，markdown-node 读取并渲染本地文件，review-ui 挂载到狭窄的文档、提交、呈现和状态端口上。host-mcp-apps 提供基于标准的运行时，其默认提交是结构化 JSON；Codex 浏览器组合明确添加了简洁的 $markdown-review 格式化器。审阅状态在其不透明的审阅会话 ID 下本地持久化，因此排队的评论在组件重新挂载后仍然存在，同时永远不会作为模型可见的旧版小部件上下文发布。未来的 Tauri 外壳可以重用契约、核心和 UI，并提供 Rust IPC 端口；目前不包含 Tauri。

主机支持

未发布的适配器和浏览器验收后续事项在 ROADMAP.md 中跟踪。

从仓库市场安装

要求：

• 支持插件的 ChatGPT 桌面应用中的 Codex。

• Node.js 22 或更高版本可作为 node 使用。

• 用于添加市场源的 codex CLI。

将此仓库添加为市场：

codex plugin marketplace add tjs-w/markdown-review --ref main

重启桌面应用，打开插件目录，选择 Markdown Review，然后安装插件。安装后启动新任务，以便任务接收插件工具注册。

要刷新现有安装：

codex plugin marketplace upgrade markdown-review

升级后重启桌面应用并启动新任务。现有任务保留其启动时使用的工具和技能注册。

使用

要求 Codex 打开绝对 Markdown 路径：

Open /absolute/path/to/document.md for Markdown review.

在审阅中：

1. 选择文本并按需正常复制，或选择渲染后的图片。

2. 右键单击文档或选择 Review 以进行复制和评论操作。选区的 + 操作和每个图片目标仍然是直接快捷方式。

3. 按 Enter 排队评论；使用 Shift+Enter 换行。

4. 使用 #1、#2 等引用较早排队的评论。

5. 审阅轮次完成后选择 Submit。

成功提交后，队列清空，下一轮审阅从 #1 重新开始。刻意没有单独提交操作：批处理为 Codex 提供一个连贯的修订目标，并减少源冲突。

本地开发

git clone https://github.com/tjs-w/markdown-review.git
cd markdown-review
bun install --frozen-lockfile
bun run verify

开发和 CI 使用固定的 Bun 1.4 工具链。已安装的插件不需要 Bun：仓库检入了可读的 Node 兼容 server.cjs 以及压缩的浏览器包。更改 TypeScript 源后重新构建：

bun run build

针对 Markdown 文件运行浏览器测试工具以进行 UI 工作：

bun run browser:harness -- /absolute/path/to/document.md

设置 MARKDOWN_REVIEW_PREVIEW_COMPOSER=1 以在测试工具中自动打开反馈编辑器。

插件默认抑制主机的原生上下文菜单。仅用于本地插件调试，在 MCP 服务器环境中设置 MARKDOWN_REVIEW_DEVTOOLS=1 并重启 Codex；然后 Shift+右键单击 绕过审阅菜单并打开主机原生菜单。普通右键单击继续显示审阅操作。该标志严格解析——只有确切值 1 启用绕过——并且永远不会在检入的 .mcp.json 中启用。

要将此检出作为本地市场测试，请添加其绝对目录：

codex plugin marketplace add /absolute/path/to/markdown-review

然后重启桌面应用并从本地市场源安装插件。

安全与隐私边界

• 组件无法写入 Markdown 文件。

• 除非本地 MCP 服务器以明确的开发者标志启动，否则插件内会抑制原生浏览器上下文菜单；这是 UI 加固，而非围绕 Codex App 自身菜单或快捷方式的安全边界。

• 渲染后的 HTML 在到达组件之前经过清理。

• 不加载远程、绝对或目录外的图片。

• 仅支持 Markdown 文件目录内相对路径的 PNG、JPEG（.jpg/.jpeg）和静态 WebP 文件。服务器在浏览器执行原生解码之前验证扩展名、签名、有界容器结构、尺寸和动画策略。GIF、AVIF、SVG、APNG 和动画 WebP 不渲染。

• 组件资源声明无网络或远程资源域，仅请求显式 Copy selected text 操作的剪贴板写入访问。

• Markdown 文件限制为 2 MiB。

• 一次审阅最多处理 64 个本地图片引用（包括无效引用）、每个唯一图片 5 MiB，以及总共 12 MiB 的唯一图片快照，并具有严格的每图片解码尺寸限制。每个有效引用都会渲染：浏览器在文档中公平共享有界的 24 兆像素画布预算，并将大图片缩小显示而不是省略。解析到相同规范文件或相同摘要的引用共享一个不可变快照和经过验证的客户端解码。

• 规范路径和打开的文件身份在每次有界读取周围重新检查。这些检查是纵深防御，而非针对另一个本地进程的 OS 沙箱，该进程可能在读取期间持续替换文档目录层次结构。

• 组件访问使用不透明、过期的审阅会话能力。会话滑动两小时，并由六会话 LRU 和 72 MiB 聚合图片缓存限制。

• 图片字节和 SHA-256 摘要被快照到会话中，因此后续文件变更无法更改进行中的审阅。

• 完整文档内容和图片块放置在组件私有元数据中，而非模型可见的结构化输出中。

仅审阅你打算暴露给本地插件进程的文件。提交的评论是可操作的用户反馈；选中的引用和其他审阅的文档内容保持为不受信任的上下文，而非指令。

项目布局

故障排除

插件文件存在，但审阅工具未注册。 重启桌面应用并启动新任务。任务不会动态获取在任务开始后安装或更新的插件中的工具。

Codex 报告缓存的技能路径已移动。 升级或重新安装市场插件，重启应用，并在新任务中调用稳定的技能名称 $markdown-review。不要依赖版本化缓存路径。

侧面板为空白。 在插件检出中运行 bun run verify，使用 bun run build 重新构建，刷新市场安装，然后在新任务中重试。

本地图片不渲染。 使用 Markdown 文件目录内相对路径的 .png、.jpg、.jpeg 或静态 .webp，并确认其在文档记录的尺寸和大小限制内。

文档

• OpenAI：打包你的插件

• OpenAI 插件文档

这是一个独立项目，不是 OpenAI 或 GitHub 的官方产品。产品名称和标志归其各自所有者所有。