visual-intent-layer

Visual Intent Layer

指向浏览器渲染的界面，描述需要更改的内容，然后让 Agent 基于这一精确的视觉上下文进行处理。Visual Intent Layer 是一个本地 MCP 服务和 Review Surface，用于保存的 HTML 文档和本地 Web 应用。

关于

你好，世界！这个项目是我的试验场，让我体验新鲜、随机或热门的东西！ 供参考，以下是我测试的内容：

• pstack 的验证技能
• matt 的技能
• 在 pi 中通过 openrouter 使用 ds v4.1 flash
• ...

主要功能

• 直接指点。 直接指向、拖动或框选可见目标，而不必用文字描述其位置。
• 带有上下文的注释。 将目标归入一个 Annotation，并在需要时附上参考图片。
• 一目了然的交付状态。 将未发送和已交付的 Annotation 放在一起，并保留其修订和解决状态。
• 由人来判断。 在浏览器中查看结果，并手动决定每个 Annotation。
• 默认本地运行。 将审核数据保存在本地机器上。

不支持移动端构建版本、原生窗口、设计文件和 PDF。

要求

• Node.js 20 或更高版本
• 运行服务的机器上需安装浏览器
• 如果希望 Agent 使用 Review Surface，则需要支持 MCP 的 Agent

无需托管账户或 Rust 工具链。

快速开始

向 Agent 注册本地 stdio 服务，然后重启 Agent：

{
  "mcpServers": {
    "visual-intent-layer": {
      "command": "npx",
      "args": ["-y", "--package", "visual-intent-layer@latest", "visual-intent-mcp"]
    }
  }
}

服务必须运行在你查看屏幕的那台机器上。它会在该机器上启动浏览器并绑定一个回环端口。在容器、远程主机或云端 Agent 中运行的服务无法显示该机器上的 Review Surface。

支持注册表的客户端也可以在官方 MCP Registry 中找到此服务，名称为 io.github.willa-code/visual-intent-layer。该注册表会列出获取方式，而非托管此服务。

claude mcp add visual-intent-layer -- npx -y --package visual-intent-layer@latest visual-intent-mcp

codex mcp add visual-intent-layer -- npx -y --package visual-intent-layer@latest visual-intent-mcp

-y --package visual-intent-layer@latest visual-intent-mcp

{
  "mcpServers": {
    "visual-intent-layer": {
      "command": "npx",
      "args": ["-y", "--package", "visual-intent-layer@latest", "visual-intent-mcp"]
    }
  }
}

无需 Agent 即可开始审核

此软件包还提供本地 CLI：

npx -y --package visual-intent-layer@latest visual-intent open --html ./checkout.html
npx -y --package visual-intent-layer@latest visual-intent open --app http://localhost:5173

每条命令都会打开默认浏览器并打印审核 URL。无头或脚本化使用时，添加 --no-open。若只运行本地服务：

npx -y --package visual-intent-layer@latest visual-intent serve --port 3742

运行 npm install -g visual-intent-layer 后，也可以使用 visual-intent 命令。

数据与隐私

默认情况下，服务会将审核数据写入 ~/.visual-intent-layer/data。它不会写入 Agent 配置。卸载软件包不会删除审核记录；只有在需要删除这些记录时，才移除该数据目录。

设置 VISUAL_INTENT_DATA_DIR 可选择其他数据目录。设置 VISUAL_INTENT_NO_OPEN=1 可禁止自动打开浏览器。

更新与卸载

npx 获取软件包时会解析 @latest，因此通常无需手动更新。pi-mcp-adapter 会将解析后的命令缓存 24 小时；删除 ~/.pi/agent/mcp-npx-cache.json 即可强制重新获取。在配置项中将 @latest 替换为确切版本号即可固定版本；使用 npm install -g visual-intent-layer@latest 更新 全局安装。

要卸载，请使用添加配置项时采用的方式将其移除——claude mcp remove visual-intent-layer、codex mcp remove visual-intent-layer，或编辑 客户端的配置。docs/guide.md 列出了各客户端对应的 文件。卸载不会删除任何评审记录：它们会保留在数据目录中，直到你将其移除。

文档

• docs/guide.md — 产品手册、评审界面、注释模型、MCP 工具、数据、架构、开发和布局。
• design.md — 规范性的评审界面设计契约。
• docs/design-references.md — 组件参考和验证说明。
• docs/reference-foundations.md — 候选参考基础的比较。
• SECURITY.md — 威胁模型、支持的版本和漏洞披露流程。
• docs/adr/ — 架构决策。
• docs/pi-validation.md — Pi 实时验证检查清单。

许可证

Apache-2.0。