用途
onUI 用于在任意 Web UI 上做标注与绘制，为 AI 智能体导出结构化上下文，无需对应用代码做任何集成。它由轻量级浏览器扩展（Chrome + Edge + Firefox）和本地 MCP 桥接组成，定位是“标注优先”的 UI 结对编程。
主要能力
- 无需集成到应用代码。
- 每个标签页独立 ON/OFF 控制（默认关闭）。
- 页内标注对话框，包含意图（intent）与严重程度（severity）。
- 绘制模式，可做区域标注（矩形 + 椭圆）。
- 紧凑工具栏，弹出式设置（输出级别 + 复制后清除）。
- 视觉标记与悬停定位。
- 导出格式支持紧凑、标准、详细、取证（compact / standard / detailed / forensic）。
- 使用 Shadow DOM 隔离，保持样式稳定。
- 本地 MCP 服务器 + 原生桥接（无需云端后端）。
安装方式
方式 A：浏览器扩展商店（推荐）
- Chrome Web Store：https://chromewebstore.google.com/detail/onui/hllgijkdhegkpooopdhbfdjialkhlkan?authuser=0&hl=en-GB
- Microsoft Edge Add-ons：https://microsoftedge.microsoft.com/addons/detail/onui/fkcmlckehjhcicihbnmhkadfhjhfnond
方式 B：从最新 GitHub Release 一键安装
若需要最新版本（商店更新可能滞后）或使用 Firefox，可用此方式。安装器会处理扩展安装，并可在同一流程中设置 MCP。当提示 Set up local MCP bridge now? [y/N] 时，输入 y 启用 MCP。
安装后在 Chrome 或 Edge 中加载：
- 打开 chrome://extensions 或 edge://extensions
- 开启开发者模式
- 点击“加载已解压的扩展程序”
- 选择 ~/.onui/extensions/current（Windows 为 %USERPROFILE%.onui\extensions\current） Chromium 浏览器对未打包扩展需这最后一步手动操作。
Firefox 手动安装（从 Release 产物）：
- 从 GitHub Release 页面下载 onui-firefox-add-ons-vX.Y.Z.zip
- 解压到本地文件夹
- 打开 about:debugging#/runtime/this-firefox
- 点击“临时载入附加组件…”
- 选择解压出的 manifest.json
使用方式
- 打开任意受支持的网站标签页。
- 点击 onUI 扩展图标。
- 启用“This Tab”。
- 使用页内启动器打开紧凑工具栏。
- 切换标注模式（用于元素定位）或绘制模式（用于区域定位）。
- 按住 Shift 并点击多个元素可批量选择目标。
- 松开 Shift 打开共享标注对话框，为所选目标填写标注。
- 保存一次即为每个选中元素创建一条标注（或绘制流程中创建一条区域标注）。
- 打开工具栏设置选择输出级别并配置“复制后清除”。
- 从工具栏复制导出的输出。
本地 MCP 设置
推荐路径：使用上文同一安装器命令，并在提示时输入 y。
若要在非交互模式下强制设置 MCP，可使用 --mcp（macOS/Linux）；Windows PowerShell 在运行安装器前设置环境变量。
MCP 设置现在使用预构建的 Release 包（无需本地构建），但仍需 Node 20+。
也仍支持从源码手动设置 MCP。
自定义 MCP 路由/客户端的 JSON 配置： 若你的 MCP 路由器使用对象式 mcpServers 映射，使用以下规范条目（onui-cli.js 请用绝对路径，相对路径常被路由器拒绝或解析错误）。若路由器使用列表/数组结构而非对象映射，按同样 command/args 形状适配。
设置/验证说明：
- 先运行
pnpm build:mcp，使 packages/mcp-server/dist/bin/onui-cli.js 存在。 - 保持服务器条目名称为 onui-local。
- 接好配置后运行
pnpm doctor:mcp确认本地设置健康状态。 - 当已安装 Claude Code 和 Codex CLI 时，会自动注册 onui-local。
- 本版本浏览器支持：Chrome 稳定版 + Edge 稳定版 + Firefox 稳定版（未打包）。
- @onui/mcp-server 为工作区本地（private: true），因此需在本仓库内运行 setup/doctor。
适用场景
- 在 Web UI 上进行标注与绘制，为 AI 智能体提供结构化上下文。
- 标注优先的 UI 结对编程。
限制
- Chromium 浏览器对未打包扩展需手动加载步骤。
- MCP 设置需要 Node 20+。
- 本版本浏览器支持为 Chrome 稳定版、Edge 稳定版、Firefox 稳定版（未打包）。
- @onui/mcp-server 为工作区本地（private: true），需在仓库内运行 setup/doctor。
维护者构建与发布
app.sh 是本地发布入口（不依赖 CI/CD）。 本地验证 + 产物打包：前置检查（Node 20+、pnpm、git、zip）；构建顺序为 @onui/core -> @onui/extension -> @onui/mcp-server；MCP doctor 冒烟检查（警告允许，错误则失败）；产物打包到 artifacts/vX.Y.Z/，包括 onui-extension-unpacked-vX.Y.Z.zip、onui-chrome-web-store-vX.Y.Z.zip（为 CWS 剥离 manifest key）、onui-edge-add-ons-vX.Y.Z.zip（为 Edge Add-ons 剥离 manifest key）、onui-firefox-add-ons-vX.Y.Z.zip、onui-mcp-bundle-vX.Y.Z.zip。 本地发布 + GitHub 发布：当前分支为 main，gh auth status 成功；操作包括从根 package.json 自动 patch 升版、同步扩展 + MCP 运行时字符串版本、运行完整 --build、提交并打标签 vX.Y.Z、推送提交/标签、创建带打包产物的 GitHub Release。
