MarkuprPlus

MarkuprPlus

你看到了。你说出来。AI 来修复。

一款用于视觉反馈的 Windows 和 macOS 桌面应用、命令行工具及 MCP 服务。
在桌面上录制并标注，通过终端处理录制内容，或为你的 AI Agent 提供屏幕截图工具。

下载 Windows 或 macOS 版本 · 使用命令行工具 · 连接 MCP 客户端 · GitHub Action

▶ 观看 33 秒的产品导览

选择一个窗口。说说哪里不对。问题发生时直接圈出来。
每个圈选都会成为一个独立问题，并附带自己的截图，可直接粘贴到你的编码 Agent 中。

快速入门 · 工作循环 · 输出 · 截图 · 服务提供方 · MCP · 命令行工具

---

  

在 Windows 上按住 Ctrl，或在 macOS 上按住 Cmd，圈出问题，继续讲解。这道笔迹会成为 MX-001。

问题所在

你的编码 Agent 看不到屏幕。于是你只能停下手头的工作，开始转述：用文字描述布局问题，截屏、裁剪，再拖到合适的位置，并说明要关注哪一部分。你每分钟能说 150 个词，却只能打 60 个词，信息在传达过程中不断流失。

解决方案

MarkuprPlus 是一款适用于 Windows 和 macOS 的桌面应用，并提供 CLI、MCP 服务和用于自动化工作流的 GitHub Action。桌面应用位于 Windows 系统托盘或 macOS 菜单栏中。它会录制你指定的确切窗口，在你讲解时进行收音，还允许你直接在实时屏幕上绘图，不会妨碍你点击。停止后，它会在设备本地转录语音，将你的话与每个标记对应起来，并生成一份可供 Agent 采取行动的报告——每个圈选对应一条问题，且各自附有标注后的画面。

使用 MarkuprPlus 的方式	可执行的操作	开始使用
Windows 桌面应用	录制屏幕和语音、绘制实时标注，并在系统托盘中查看报告。	下载 Windows 版
macOS 桌面应用	在 Apple Silicon 或 Intel Mac 上通过菜单栏进行捕获和标注。	下载 macOS 版
CLI	分析已有录制内容、监视文件夹，并在脚本中生成报告。	CLI 命令
MCP 服务	让 AI 编码 Agent 捕获屏幕截图、录制会话并接收结构化报告。	连接你的 Agent
GitHub Action	在 GitHub Actions 工作流中处理录制内容。	Action 设置

Windows: Ctrl+Shift+F → talk → Ctrl-drag → Ctrl+Shift+F → paste into your agent
macOS:   Cmd+Shift+F  → talk → Cmd-drag  → Cmd+Shift+F  → paste into your agent

操作流程

1. 按下捕获快捷键并选择目标

在 Windows 上使用 Ctrl+Shift+F，或在 macOS 上使用 Cmd+Shift+F。

选择器会显示在所有窗口上方。光标下方的窗口会亮起——点击它，录制器就会锁定该窗口，并在窗口移动、调整大小或切换应用时继续保持锁定。如果问题需要更大的画面，也可以一键切换到区域或整个显示屏模式。

如果会话中途窗口身份或原生几何信息变得不明确，捕获会停止，而不会扩大范围去捕获后方的内容。你绝不会误分享不打算分享的画面。

捕获控件集中在一个纵向弹出窗口中，可从 Windows 系统托盘或 macOS 菜单栏访问。

2. 边工作边讲解

像平常一样继续点击应用。MarkuprPlus 会同时录制窗口和麦克风音频，并在停止后使用 Whisper 在设备本地进行转录。

选择器、绘图画布和录制 HUD 都会在操作系统层面排除在屏幕捕获之外——**MarkuprPlus 绘制的内容不会出现在视频中。**视频只包含你的应用，以及你有意留下的笔迹。

3. 按住 Ctrl（Windows）或 Cmd（macOS）并绘图

按住修饰键并拖动，即可直接在实时屏幕上绘制——可以自由绘制、画圆或高亮，并选择颜色。松开修饰键后，你的下一次普通点击既会传递给下方的应用，也会保存标记，同时清空画布，以便添加下一个标记。

三个圈就代表三个问题，而不是一张上面画着三道涂鸦的截图。每条问题记录都带有自己的 PNG、时间戳、工具和颜色。

### 4. 再次按下录制快捷键以停止

在 Windows 上使用 Ctrl+Shift+F，在 macOS 上使用 Cmd+Shift+F。

Whisper 会运行，将你的旁白与每个标记对齐，并将报告写入磁盘。Markdown 路径准备就绪后会立即复制到剪贴板——直接粘贴到 Claude Code、Codex、Cursor 或任何能读取文件的工具中。

本次会话的所有内容都会放在一个文件夹中：报告、截图、会话视频、旁白音频和元数据。

快速开始

Windows 和 macOS 桌面应用（推荐）

从 markuprplus.com 或发布页面下载。选择适用于 Apple Silicon 或 Intel 的 Windows 安装程序（.exe） 或 macOS 磁盘映像（.dmg）。

**macOS 安装说明：**从 GitHub Releases 直接下载的文件均已签名、公证并附加公证票据。如果 Gatekeeper 拒绝某个文件，请联系 MarkuprPlus 支持，以便调查该发布版本。

1. 按下 Cmd+Shift+F（macOS）或 Ctrl+Shift+F（Windows），然后点击要捕获的窗口。
2. 讲述你看到的内容。按住 Cmd / Ctrl 并拖动，即可在实时屏幕上标记。
3. 松开按键，然后正常点击——这会保存标记并清空画布。每发现一处问题就重复此操作。
4. 再次按下热键停止。报告路径已复制到剪贴板。

MCP 服务（适用于 AI 编码 Agent）

npx --yes --package markuprplus markuprplus-mcp

CLI（适用于已有的录制内容）

npx markuprplus analyze ./recording.mov

**兼容性：**公开的软件包和命令为 markuprplus 和 markuprplus-mcp。现有的 .markuprx 项目文件、存储路径和应用标识符 保持不变，因此升级后原有设置和会话仍会保留。

Mac App Store CLI 集成的可选配套工具

沙盒版 Mac App Store 应用可通过可选的 MarkuprPlus CLI Bridge，使用已安装并登录 Mac 的 AI 命令行工具。本地规则、Ollama、LM Studio 和 Anthropic API 无需此配套工具。

在终端中安装并配对：

npm install -g markuprplus
markuprplus bridge install     # installs and starts a per-user LaunchAgent
markuprplus bridge token       # paste this value in Settings → Advanced
markuprplus bridge status

公开的 npm 软件包包含与源代码发布版本相同的、带版本号的 CLI 和 MCP 入口点。

该服务仅监听 127.0.0.1:49647，每个提供商请求都必须携带随机配对令牌，并且只接受固定的结构化报告协议，不接受 shell 文本。App Store 应用不会运行 shell 命令或启动外部工具；单独安装的配套工具只会调用“设置”中选定的提供商。

生命周期和恢复命令：

markuprplus bridge start
markuprplus bridge stop
markuprplus bridge status
markuprplus bridge token
markuprplus bridge rotate-token
markuprplus bridge uninstall

轮换令牌后需要重新配对。卸载时会移除由 MarkuprPlus 管理的准确 LaunchAgent 和 Bridge 配置；不会卸载你的 AI CLI。

保存到文件夹中的内容

一次会话，一个目录：

originplayer-test-iphone-20260818-104731/
├── feedback-report.md          # the file you paste
├── feedback-summary.md         # counts and duration
├── metadata.json               # per-issue capture context
├── processing-trace.json       # which provider ran, how long, why it fell back
├── screenshots/
│   ├── marked-issue-001.png    # one frame per mark, your stroke composited in
│   ├── marked-issue-002.png
│   └── marked-issue-003.png
├── session-recording.webm      # the window, with annotations
└── session-audio.webm          # your narration

该会话中一条真实、未经编辑的问题记录：

### MX-001

- **Timestamp:** 00:08
- **Tools:** freehand
- **Colors:** #ff3b30

#### User Comment

> So there's a search menu and over here by default, if there's been
> previous searches, it should list out all the searches that have
> happened in the past.

#### Marked Evidence

![Marked issue MX-001](./screenshots/marked-issue-001.png)

每条问题记录都包含的不只是像素：

随问题一起传递的内容	示例
独立的带注释 PNG	screenshots/marked-issue-001.png
当时的旁白	transcript-segment-0001 … 0002
标记方式	freehand · #ff3b30
来源	window:5976:0 · OriginPlayer Test iPhone · darwin
光标、活动应用和焦点提示	在绘制的瞬间捕获
触发元数据	annotation、manual、pause 或 voice-command

已标记的问题按 MX-001… 编号；仅来自旁白的条目按 FB-001… 编号。

全方位体验

报告提供方 15 种将会话转为报告的方式，每种都会显示当前是否可访问——CLI 版本和路径、本地端口、缺失的密钥。	审阅编辑器 重新排列发现项，为其修改标题、更改类别和严重程度，还可以删除那些只是随口一说的内容。	实时 Markdown 预览 保存前查看 Agent 将要读取的确切文件。复制文件、打开文件夹或导出。
最近捕获 每个会话都会保存在磁盘上，并显示其项目数和截图数。无需在 Finder 中翻找，即可复制任意报告路径。	热键 录制、截图和暂停热键均为全局热键，且可重新绑定；面板中还附有快速参考。	外观 10 种强调色，另有自定义选择器，并提供实时预览。浅色和深色模式会跟随系统设置。
录制和音频 录制前倒计时、音频波形反馈和麦克风选择。	转录和密钥 优先在本地运行 Whisper。只有本地恢复失败且你已保存密钥时，音频才会发送给 OpenAI。	菜单栏 无需打开弹出面板，即可开始录制、跳转到设置或退出。

本地转录

桌面应用启动时，如果尚未安装本地模型，MarkuprPlus 会在后台下载多语言 Whisper tiny 模型（约 75 MB）。现有模型会重复使用。下载进度和可重试的错误会显示在 设置 > 高级 > 本地转录中。中断的下载会在下次启动时继续；离线或下载失败不会阻止应用打开。 下载完成后，本地转录无需互联网连接即可运行。

界面语言

桌面界面默认使用英语，包括从此前会自动显示繁体中文的安装版本升级时。选择 Settings > General > Language > Interface language，即可选择使用繁体中文或切换回英语。该偏好设置会保存，并立即应用到所有已打开的窗口，无需重启或中断录音。重置 General 设置会恢复为英语。

界面语言与转录语言相互独立。反馈文本、录音和生成的报告不会因该设置而翻译。

如需添加其他界面语言，请在 src/shared/uiLanguage.ts 中注册其标识符和显示名称，并在 src/renderer/i18n/catalogs.ts 中添加其翻译目录。英语标签是源文本，也是缺少翻译时的回退文本；请使用 translate="no" 标记用户内容区域。

报告提供方

选择将录制内容转换为结构化报告的模型。MarkuprPlus 会在你开始录制之前检查每个提供方，并向你展示实际检测到的内容。

在 Mac App Store 应用中，CLI 提供方使用上文所述的可选本地伴侣。直接桌面构建版本会在应用内调用相同的适配器。两种方式都会在失败时以本地规则生成报告作为保障。

提供方	类型	使用方式
Codex CLI	CLI	你已安装的 CLI，或 Codex Mac 应用捆绑的 CLI，以及现有的 ChatGPT 登录信息；在只读临时会话中运行
Claude Code CLI	CLI	你已登录的 Claude Code CLI
GitHub Copilot CLI	CLI	Copilot CLI 1.0.83+ 和现有的 GitHub 登录信息；在隔离且不含工具的会话中运行
OpenCode	CLI	你配置的 OpenCode 提供方；每次运行时使用禁止所有工具操作的 Agent
Cursor Agent CLI	CLI	以非交互式只读 Ask 模式运行的 Cursor Agent
Qwen Code	CLI	以安全的非交互式计划模式运行的 Qwen Code，不包含修改类工具
Goose	CLI	你配置的 Goose 提供方，以不含工具的聊天模式运行，不使用配置档案，也不保留会话
Amp	CLI	你的 Amp 登录信息，以及隔离的默认拒绝工具策略
Kiro CLI	CLI	Kiro 无头模式，仅信任读取和 grep
Aider	CLI	你配置的 Aider 模型，以 dry-run、no-git 模式运行
Ollama	本地	在 127.0.0.1:11434 上提供服务的模型——不会有任何内容离开本机
LM Studio	本地	在 127.0.0.1:1234 上运行的 LM Studio 服务
Anthropic API	云端	你自己的密钥，存储在系统钥匙串中，且仅用于此处
本地规则	无需设置	仅根据转录文本和标记生成确定性报告，无需凭据

设计上，失败不会造成风险。 如果你选择的提供方出错，仍会生成确定性的本地规则报告，并在弹出框中指出提供方和原因。分析开始前，你的录制内容、音频和标记就已写入磁盘。明确选择 CLI 后，绝不会在没有提示的情况下改用 Anthropic 调用。

Codex CLI、GitHub Copilot CLI 和 OpenCode 可以接收捕获的屏幕截图。仅支持转录文本的 CLI 适配器会拒绝只有屏幕截图的会话，而不会臆造视觉发现。

要使用 GitHub Copilot CLI，请安装或更新 copilot，在终端中运行 copilot login，然后在报告设置中选择 GitHub Copilot CLI 并刷新提供方列表。将模型留空可使用你的 Copilot 默认模型，也可以输入 Copilot 模型 ID。检测过程会验证已安装的版本；运行报告时会验证身份验证。可选的 CLI Bridge 为 Mac App Store 应用提供相同的集成。

Copilot 通过 stdin 接收转录文本，并将屏幕截图作为附件。每份报告都会使用临时 Copilot 配置，仅复用你的登录身份（凭据仍保存在操作系统的凭据存储中）和默认模型，不会复用你的插件、钩子、MCP 服务或已保存的权限。所有模型工具和自定义指令均已禁用。成功或失败后都会移除临时上下文。也支持使用环境变量令牌进行身份验证；不会将明文凭据回退项复制到临时配置中。

processing-trace.json 会准确记录实际发生的情况：

{
  "requestedProvider": "codex-cli",
  "actualProvider": "rules",
  "aiFallbackReason": "Codex analysis exited with status 1.",
  "aiEnhanced": false,
  "totalMs": 4220
}

为什么选择 MarkuprPlus

证据，而不是录像。 屏幕录像会留给你的 Agent 一段它无法观看的视频，而你还得再把内容口述一遍。使用 MarkuprPlus，你会获得独立的发现，每项发现都附有一张标注截图、对应时间戳的口述内容，以及窗口和光标上下文。

本地优先。 Whisper 在你的设备上运行，本地规则无需凭据。只有在你明确选择后，才会运行云端转录和云端模型。无需账号，不收集遥测数据，也不进行分析。

不会录下自身。 选择器、绘图画布和录制 HUD 在操作系统层面受到内容保护。你的标注会进入报告；应用自身的界面元素不会进入视频。

融入你的工作流。 Windows 和 macOS 桌面应用适用于日常捕获，命令行适用于脚本和 CI，MCP 服务适用于 Agent，还有用于拉取请求的 GitHub Action。

开源。 采用 MIT 许可。阅读、分叉、发布，随你所需。

MCP 服务

为你的 Agent 提供视觉和听觉能力。它可以捕获屏幕截图、录制带语音的屏幕内容，并在对话过程中接收结构化报告。

使用设置命令连接 GitHub Copilot CLI、Claude Mac 应用或 Codex：

npm install -g markuprplus
markuprplus integrate copilot
markuprplus integrate claude-desktop
markuprplus integrate codex

对你使用的每个客户端运行此命令，然后重启该客户端。Claude 设置同时涵盖 Chat 和 Code。Codex 与其 CLI 共用配置。添加 --dry-run 可预览；现有设置和其他服务都会保留，修改过的文件会备份。若存在冲突的 markuprplus 条目，则需要使用 --force。详情请参阅客户端设置和功能。

手动设置时，Claude Code（~/.claude.json 或项目中的 .mcp.json）、Cursor 和 Windsurf 使用相同的配置格式：

{
  "mcpServers": {
    "MarkuprPlus": {
      "command": "npx",
      "args": ["--yes", "--package", "markuprplus", "markuprplus-mcp"]
    }
  }
}

工具

工具	说明
capture_screenshot	捕获当前屏幕，并附上光标、活动应用/窗口和焦点提示。
capture_with_voice	按指定时长录制屏幕和麦克风，并返回结构化报告。
describe_screen	描述当前屏幕内容。
start_recording	开始交互式录制会话。
stop_recording	结束会话并运行完整处理流程。
analyze_video	将现有的 .mov / .mp4 处理为包含提取帧的 Markdown。
analyze_screenshot	使用分析流程处理单张截图。
push_to_github	根据报告创建 GitHub 问题。
push_to_linear	根据报告创建 Linear 问题。

You: "The sidebar is overlapping the main content on mobile. Can you see it?"

Agent: [calls capture_screenshot]
       "I can see it — the sidebar is position: fixed with no z-index,
        280px wide with no responsive breakpoint. Fixing the CSS..."

完整 MCP 文档：README-MCP.md。

命令行

npx markuprplus analyze ./recording.mov

命令	功能
markuprplus analyze <video>	将现有录制内容转换为结构化报告
markuprplus watch [dir]	处理文件夹中新出现的录制内容
markuprplus doctor	检查环境中的依赖项和配置
markuprplus init	生成配置脚手架
markuprplus push github <report>	根据报告创建 GitHub 问题
markuprplus push linear <report>	根据报告创建 Linear 问题

markuprplus analyze ./recording.mov --output ./reports
markuprplus analyze ./recording.mov --template github-issue
markuprplus analyze ./recording.mov --no-frames        # transcript only
markuprplus watch ~/Desktop --output ./reports
markuprplus push github ./report.md --repo myorg/myapp --dry-run

输出模板： markdown（默认） · json · github-issue · linear · jira 桌面应用还可导出 html 和 pdf。

要求： Node.js 20.9+，以及位于 PATH 中的 ffmpeg（brew install ffmpeg / apt install ffmpeg / choco install ffmpeg）。

集成

GitHub Action

在 CI 中分析录制内容，并在需要反馈的拉取请求中发布结构化反馈：

- uses: eddiesanjuan/markuprx-action@v1
  with:
    video-path: ./recordings/
    github-token: ${{ secrets.GITHUB_TOKEN }}
    create-issues: 'true'

所有输入参数请参阅 markuprx-action/README.md。

问题跟踪器

将每项发现直接推送到 GitHub Issues 或 Linear，截图、口述内容、时间戳和捕获上下文均已整理好；你可以通过应用、命令行或经由 MCP 的 Agent 完成操作。

键盘快捷键

操作	macOS	Windows
开始 / 停止录制	Cmd+Shift+F	Ctrl+Shift+F
标记实时屏幕	按住 Cmd 并拖动	按住 Ctrl 并拖动
手动截图	Cmd+Shift+S	Ctrl+Shift+S
暂停 / 恢复	Cmd+Shift+P	Ctrl+Shift+P
设置	Cmd+,	Ctrl+,

录制、截图和暂停的快捷键为全局快捷键，可在 设置 → 热键 中重新绑定。完整参考：docs/KEYBOARD_SHORTCUTS.md。

工作原理

                    +-----------+
  Screen + Voice -> | Whisper   | -> Timestamped transcript
                    +-----------+
                         |
                    +-----------+
                    | Aligner   | -> Marks matched to the words around them
                    +-----------+
                         |
                    +-----------+
                    | Provider  | -> Structure and severity (or local rules)
                    +-----------+
                         |
                    +-----------+
                    | Generator | -> Markdown, HTML, JSON, PDF, or tracker-ready
                    +-----------+

整个处理流程的每一步都能优雅降级。没有 ffmpeg？输出仅包含转录文本。没有 Whisper 模型？使用基于计时器的截图。没有提供方？使用本地规则。任何地方发生故障，磁盘上仍会保留报告和原始会话。

架构详情请参阅 CLAUDE.md。

开发

npm install
npm run dev

命令	说明
npm run dev	开发模式，支持热重载
npm run build	构建所有内容（桌面应用 + CLI + MCP）
npm test	运行所有测试
npm run lint	运行代码检查
npm run typecheck	类型检查

参与贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/your-feature
3. 运行测试：npm test && npm run lint && npm run typecheck
4. 提交 Pull Request

完整指南请参阅 CONTRIBUTING.md。

许可证

MIT — 详见 LICENSE。

---

www.markuprplus.com