Pointcast

pointcast

将 pointcast 录音——包含麦克风转录文本和你讲解时指向的元素——转换为编码 Agent 可读的 Markdown 规格说明，或通过 MCP 直接提供给编码 Agent。录音来自 pointcast Chrome 扩展 （从发行页面安装）。

公开测试版（0.2）：欢迎提供反馈和报告 Bug，见 issues。

安装

无需安装——使用 npx 运行：

npx pointcast --help

扩展已在浏览器中完成转录，因此 CLI 默认不会安装语音模型。若要在本机转录（pointcast transcribe、process --force，或扩展无法转录的录音），请添加 @huggingface/transformers（与 ONNX Runtime 一起约 450 MB）：

npm install -g pointcast @huggingface/transformers
# or, without installing:
npx -p pointcast -p @huggingface/transformers pointcast process --force

--engine openai 则两者都不需要。

本地模型为 Xenova/whisper-base（扩展中的 Fast）。--model Xenova/whisper-small 是它的 Accurate：误听的词更少，速度约慢一倍，首次下载需要 512 MB。

命令

pointcast setup                    Set pointcast up in this project: your coding agents, your
                                   stack, the browser extension, then doctor. Asks first.
pointcast process [session-dir]   Transcribe (if needed), fuse and render session.md.
                                   Default session-dir: the latest session in
                                   --dir / POINTCAST_DIR / <Downloads>/pointcast.
pointcast transcribe <session-dir | file.wav>
                                   Write words.json from audio, on its own.
pointcast mcp                      Run a stdio MCP server exposing sessions read-only. While it
                                   runs, it also receives the extension's recordings on
                                   127.0.0.1, so they skip Chrome's downloads.
pointcast issue [session-dir] --repo owner/name
                                   Experimental: file the spec as a GitHub issue, linked to the code.
pointcast doctor                   Check this machine's setup, with a fix for each problem.

process 会在录音旁写入 session.md，并将其复制到剪贴板，可直接粘贴给编码 Agent。运行 pointcast --help 查看所有标志（--engine、--format、--stdout，等等）。--style precise 会将规格说明中的指令写成“仅修改引用的元素，且只按要求修改”，--style intent 则写成“按照应用的风格，实现新需求所表达的内容”；不指定时，规格说明会采用录音在弹出窗口中选择的模式（对设置推出前录制的内容，默认采用 intent）。

设置

npx pointcast@latest setup

在项目中运行此命令，它会查找 Claude Code、Codex、Gemini CLI（在 PATH 中）和 Cursor（有 .cursor 文件夹，或在 PATH 中）。对于尚未配置 pointcast 的工具，它会显示计划执行的操作并询问 y/N：Claude Code 和 Codex 的插件安装命令、Gemini CLI 的 gemini extensions install，以及 Cursor 的操作——将固定为此确切版本的 pointcast 服务合并到项目的 .cursor/mcp.json 中。随后，它会说明你的技术栈需要做什么（Django 项目需要添加 pointcast-django 配置行，React、Vue 或 Svelte 开发构建不需要），如何添加浏览器扩展，并运行 doctor。它绝不会自行修改你的 Python 设置或 Agent 配置文件。

--dry-run 会打印计划且不做任何更改（并跳过 doctor）；--yes 会执行所有步骤而不询问；--json 会为 Agent 打印计划和结果；--repo <path> 会为另一个文件夹进行设置。没有终端且未指定 --yes 时，会执行试运行。

检查设置

npx pointcast doctor

每项检查会打印一行，每个问题下方会给出修复方法：Node.js 版本（22.12 或更高）、读取录音的会话文件夹（--dir / POINTCAST_DIR / <Downloads>/pointcast）、其中的录音数量和最新录音；pointcast MCP 服务是否正在 127.0.0.1:20547 接收扩展发送的录音（以及服务版本：如果同时打开了多个 Agent 会话，其中一个会话的服务负责接收，所有会话都会读取同一个文件夹；如果某个服务版本早于 CLI，通常是因为它在更新前就已启动，值得重启）；本地转录是否已安装 @huggingface/transformers；以及在 Linux 上是否存在剪贴板工具（wl-copy、xclip 或 xsel）。它只会读取信息：会向 MCP 服务发送问候，但绝不会发送录音；除非添加 --online，否则不会使用网络。添加该标志后，它会将你的版本与 npm 上的最新版本进行比较。--json 会为脚本打印相同的报告。只有在 pointcast 依赖的组件发生故障时（Node.js 版本过旧，或 --dir / POINTCAST_DIR 指向的路径不存在），它才会以 1 退出；未设置的可选部分会显示为警告。

代码位置

如果录制是在开发版（React、Vue、Svelte）上进行的，每个指向的元素都会带有渲染它的组件链。随后，pointcast 会在这些文件中查找元素文本，并将对应的行添加到规范中：

- [a] «Export» → code:
  - used at: `src/pages/Dashboard.tsx` — `<OrdersTable>`
  - text at: `src/components/OrdersTable.tsx:22` — `<button type="button" id="orders-export" className="btn btn-export"> Export </button>`
  - within: `<Dashboard>` in `src/App.tsx` ← `<App>` in `src/main.tsx`

在一项小规模评估中，这使编码 Agent 查找元素所花费的 token 数减少了一半以上（docs/eval）。查找需要访问你的源代码，因此会在源代码所在的位置运行：

• pointcast process 会使用当前目录（前提是录制文件在其中），也可以使用 --repo <project folder>。否则，它会在不包含代码行的情况下生成规范，并用一行说明原因。在 monorepo 中，请从代码库根目录运行：录制中标记为 src/App.tsx 的文件，也可以在仅有一个匹配文件时，通过 apps/web/src/App.tsx 找到。
• MCP 服务（见下文）会使用启动时指定的项目。
• pointcast issue 会读取 GitHub 代码库（见下文）。

只有恰好匹配一次的代码行才会被添加；匹配结果不唯一时，不会添加任何内容。 session.json 永远不会被修改。

GitHub issue（实验性）

目前，issue 正文就是原始规范；在脱离实验阶段之前，我们会将其改写为易读的 issue。

pointcast issue --repo owner/name --dry-run   # print the title and body
pointcast issue --repo owner/name             # create the issue
pointcast issue --repo owner/name --open      # print and open a prefilled issues/new link

issue 会获取最新会话（或你指定的会话），读取默认分支或 --ref <branch|tag|sha> 指定的引用中的代码库，在其中解析代码位置，并将每个 file:line 链接到对应提交中的文件，因此链接不会变动。创建 issue 需要令牌：GITHUB_TOKEN，或 gh auth login 保存的令牌。读取公开代码库无需令牌，但受 GitHub 速率限制约束。--open 无需令牌；如果正文太长而无法放入链接，它会打印正文，供你粘贴。如果录制中的文件没有任何一个存在于代码库中，issue 会拒绝创建 issue，因为这看起来像是选错了代码库。

MCP 服务

pointcast mcp 会运行一个 stdio MCP 服务，这是 Agent 获取录制内容的主要方式：按下 Stop 时，扩展会将录制内容交给它，Agent 随后自行获取规格说明，其中每个元素都会解析到你项目中的对应代码行。对于不支持 MCP 的 Agent，可以从剪贴板粘贴规格说明作为备用方式。它提供 4 个只读工具：

• list_sessions — 按时间倒序列出最近的录制内容，每行一条，格式为 { "sessions": [...] }：包含 id、日期、时长、指向的 pages、requests 和 elements 的数量、第一条请求的 preview、matchesProject（其源文件是否位于项目中：true、false；如果未指定源文件，则为 "unknown"），以及 rendered（其 session.md 是否已写入磁盘）。
• get_session — 按 id、"latest-here"（此项目中最新的录制内容：会跳过文件在此处全部缺失的较新录制内容，并说明跳过了哪些），或 "latest"（所有录制内容中最新的一条），获取录制内容的 Markdown 规格说明。如果 session.md 尚未写入磁盘，则根据 session.json/words.json 渲染；绝不转录。规格说明以类似 8 requests · 17 elements · ~3,100 tokens 的一行开头。
• get_element — 按会话 id 和事件 id（例如 "e3"），获取一个事件捕获的完整详情（选择器、源代码位置、样式、框架组件等）。
• wait_for_recording — 等待你在此项目中进行下一次录制（对任意项目录制时使用 anyProject: true），并在你按下 Stop 后立即返回其规格说明，形式与 get_session 相同；经过 timeoutSeconds 后，会回答“No new recording yet”，Agent 会再次调用。/pointcast watch 会循环调用此工具。

如果会话 id 不存在，错误信息会列出最新的 3 个 id 及其预览；如果事件 id 不存在，则会显示有效范围（e1…e17）。

它会像 pointcast process 一样查找会话：--dir / POINTCAST_DIR / <Downloads>/pointcast。

在 MCP 配置中固定版本（如下所示，使用 [email protected]）：对于未指定版本的 pointcast，npx 会继续使用缓存副本，而该副本可能较旧。插件会固定到确切版本，并在每次发布时更新。

get_session、get_element 和 wait_for_recording 会解析启动服务时所指定项目中的代码位置：优先使用 --repo，否则使用 CLAUDE_PROJECT_DIR（Claude Code 会设置此变量），再否则使用服务的工作目录。它们和 list_sessions 也接受可选的 repo 参数。如果录制内容中的文件都不在该项目中，结果开头会显示一行警告，说明该录制内容可能来自其他项目。

get_session 和 wait_for_recording 还接受可选的 style（"intent" 或 "precise"），与 pointcast process --style 类似：规格说明会按指定样式渲染，无论录制时选择了哪种样式，而且不会缓存为 session.md。/pointcast precise 会传入 "precise"。

监听：wait_for_recording

wait_for_recording 会在收到新录音时立即返回：该录音在 Agent 首次调用此工具时尚未出现在 sessions 文件夹中，并且之前没有任何工具返回过该录音。默认情况下，只返回属于当前项目的录音，判断规则与 "latest-here" 相同：如果录音的所有源文件都不在项目中，则跳过；如果录音未注明任何文件，则保留。被跳过的录音不会被消耗：在正确项目中的 Agent 会话仍会收到它，而 anyProject: true 会返回所有录音，并在适用时附上其他项目警告。因此，当 Agent 仍在处理上一条录音时，你录制的新内容会由下一次调用返回；而 Agent 已通过 get_session 读取过的录音不会重复返回。它支持同时打开多个 Agent 会话：只有一台服务会从扩展接收录音，其他会话则会看到录音出现在共享的 sessions 文件夹中。

工具调用无法无限期持续，而且不同客户端会在不同时间终止调用，因此默认等待时长会根据客户端而定：

客户端	工具调用时限	默认等待时长
Claude Code	stdio 服务没有时限（MCP_TOOL_TIMEOUT 可设置时限）；30 分钟内没有响应或进度时终止	9 分钟
Gemini CLI	服务设置中的 timeout，默认 10 分钟	9 分钟
Codex	tool_timeout_sec，默认 60 秒	50 秒
Cursor 和其他客户端	未说明	50 秒

Agent 可以传入 timeoutSeconds（最多 1,500 秒，即 25 分钟）。等待结束时如果没有录音，返回结果不会是错误，Agent 会再次调用，因此较短的时限只意味着需要调用更多次。等待期间，如果客户端请求进度通知，服务会发送进度通知。

接收来自扩展的录制内容

运行 pointcast mcp 时，它还会监听 127.0.0.1:20547，绝不会监听你的网络（你设置的端口转发除外，见下文 远程开发服务）。点击 Stop 时，扩展（0.2+）会将录制内容交给它，服务会将其存储在自己的会话文件夹中，工具会从该文件夹读取内容。Chrome 不会下载任何内容，因此不会弹出“保存”对话框，即使 Chrome 已开启“下载前询问每个文件的保存位置”也是如此。如果没有服务响应，扩展会像以前一样通过 Chrome 下载内容。弹出窗口会显示每份录制内容的保存位置。

• 仅接收来自 pointcast 扩展的内容。 服务只会接收来自官方扩展 ID（其 chrome-extension:// 源）的录制内容，并要求带有 pointcast 专用标头和内容类型，因此网页无法向其发送录制内容。对于分支版本，或在 Edge Add-ons 上安装但 ID 尚未随正式版本发布的情况，可通过 POINTCAST_EXTENSION_IDS=<id>[,<id>…] 添加 ID；服务拒绝请求时，弹出窗口会显示该 ID。ID 无效会导致接收功能关闭（服务会记录原因）；工具仍可正常工作。
• 文件绝不会写入一半，也不会被覆盖。 文件会先写入隐藏的 .incoming-* 文件夹，然后重命名为会话 ID。如果该文件夹已存在，扩展会改用 Chrome 下载。
• 多个服务（多个 Agent 或项目）：最先启动的服务会接收内容。其他服务会记录端口被占用，并每隔 3 s 重试一次，因此该服务退出后 3 s 内就会有另一个服务接管。如果这些服务的 --dir 不同，录制内容会存入接收服务的文件夹。
• 关闭此功能：使用 --no-handoff 或 POINTCAST_HANDOFF=off，也可以在扩展的 Settings 中关闭（发送到你的 Agent 的 Pointcast MCP 服务）。
• 多人共用的计算机： 该计算机上的所有用户共用 127.0.0.1，因此其他用户可能会向你的服务发送录制内容，或者在你的服务停止时接收你的录制内容。请在两端都关闭此功能。
• 远程开发服务（你的 Agent 和 pointcast mcp 通过 SSH 在另一台计算机上运行）：在你的计算机上使用 ssh -L 20547:127.0.0.1:20547 <host> 转发端口，并确保 pointcast mcp 在主机上运行。扩展的请求会通过隧道发送，主机上的服务会将录制内容存储在其工具读取的位置。请注意，任何对本地端口 20547 的转发都会产生这种效果，包括编辑器为远程工作区自动进行的端口转发（VS Code Remote-SSH、Codespaces）：录制内容会从你的计算机发送到该主机；在共用主机上，监听其端口 20547 的服务也可能属于其他用户。转发占用该端口期间，本地的 pointcast mcp 无法接收内容。切勿将转发开放到你的网络（ssh -g、GatewayPorts）：任何能连接到该转发的人都可以向主机上的服务发送录制内容。
• 服务只将日志写入 stderr（stdout 是 MCP 通道）：开始监听时写入一行日志，每存储一份录制内容时也写入一行日志。

POINTCAST_HANDOFF_PORT 是一个测试钩子：扩展的端口在构建时固定。

Claude Code channels（实验性）

Claude Code channels（研究预览版） 允许 MCP 服务向会话推送消息，让 Claude 无需收到请求也能做出响应。服务会声明一个 channel；收到扩展程序发来的录制后，它会通知所属的 Claude Code 会话：New pointcast recording 2026-09-29_10-00-00: 3 requests on localhost:5173/orders. Apply it with the pointcast tools (get_session, id "…"). 然后 Claude 会使用工具读取规范，例如 /pointcast。

• 默认关闭，需主动启用。 除非启动 Claude Code 时启用了 channel，否则 Claude Code 会忽略它。在预览期间，只有允许列表中的插件才能注册为 channel，而 pointcast 不在列表中，因此需要使用开发标志，启动时系统会要求你确认： claude --dangerously-load-development-channels plugin:pointcast@pointcast。
• 只传递 ID、数量和页面信息。 消息不会包含规范，也不会包含你说过的任何内容或页面上显示的内容：网页文本不得作为消息发送给 Agent 并由其据此采取行动。页面路径会精简为 URL 字符并截断。
• 只有接收消息的服务会发出通知。 如果打开了多个 Claude Code 会话，持有交接端口的那个会收到消息。/pointcast watch 可在任意会话中使用。
• 其他 Agent 不会收到消息；它们可以通过 wait_for_recording 监听。

Claude Code：插件

该插件会添加 MCP 服务和 /pointcast 命令，用于获取项目中最新的录制并应用；/pointcast watch 会持续监听并在每次录制完成后应用。参见 integrations/claude-code-plugin。

claude plugin marketplace add Hugelidus/pointcast
claude plugin install pointcast@pointcast

Claude Code：仅 MCP 服务

claude mcp add pointcast -- npx -y [email protected] mcp

或者，指定一个会话文件夹：

claude mcp add pointcast -- npx -y [email protected] mcp --dir /path/to/pointcast-sessions

Codex CLI

同一个插件也适用于 Codex：它包含 MCP 服务和一个 pointcast 技能。安装后启动新会话，然后输入 $pointcast:pointcast [session-id]（或 $pointcast:pointcast watch），也可以请求“应用我最新的 pointcast 录制”：

codex plugin marketplace add Hugelidus/pointcast
codex plugin add pointcast@pointcast

Codex 会在会话文件夹中启动服务，因此代码位置会在该文件夹中解析。它只会向 MCP 服务传递一组固定的环境变量：若要使用 POINTCAST_DIR（或其他 POINTCAST_ 变量），请在 ~/.codex/config.toml 的 [mcp_servers.pointcast] 下列出该变量：env_vars = ["POINTCAST_DIR"]。Codex 不会在首条消息发送前等待 MCP 服务就绪，因此启动时立即发送的消息可能无法使用这些工具：请重新发送。

Gemini CLI

该扩展会添加 MCP 服务（npx -y [email protected] mcp --repo <the folder you run gemini in>）和 /pointcast [session-id | watch] 命令：

gemini extensions install https://github.com/Hugelidus/pointcast

Gemini 只会在你信任的文件夹中启动扩展命令和 stdio MCP 服务（首次使用时会询问）。使用 gemini extensions update pointcast 更新。

Cursor

将以下内容添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）。${workspaceFolder} 会告知服务应在哪个项目中解析代码位置：

{
  "mcpServers": {
    "pointcast": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp", "--repo", "${workspaceFolder}"]
    }
  }
}

Windsurf

将以下内容添加到 ~/.codeium/windsurf/mcp_config.json。配置是全局的，因此当服务的工作目录不是项目目录时，Agent 会将项目文件夹作为工具的 repo 参数传入：

{
  "mcpServers": {
    "pointcast": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp"]
    }
  }
}

环境变量

POINTCAST_DIR（会话文件夹）、POINTCAST_LANGUAGE；使用 --engine openai 时： POINTCAST_API_BASE、POINTCAST_API_KEY（仅当使用 api.openai.com 时才会使用 OPENAI_API_KEY）；使用 issue 时：GITHUB_TOKEN（或 GH_TOKEN）；使用 mcp 时：CLAUDE_PROJECT_DIR、POINTCAST_HANDOFF（off 或 0：不接收录制，与 --no-handoff 相同）、POINTCAST_EXTENSION_IDS（可接受其录制的其他扩展 ID，以逗号分隔）和 POINTCAST_HANDOFF_PORT（仅用于测试）。

许可证

MIT