内容
# Loupe
> 将反馈固定到实时UI上，并将其交给Claude。
Loupe 允许产品经理检查运行中的产品上的任何元素，固定评论，并截取屏幕截图 - 然后将该反馈直接交给Claude Code，作为一个可行的、具有完整上下文的待办事项。评论在重新部署时持续存在并重新锚定。
📖 **[阅读完整文档 →](https://mohamed-ashraf-elsaed.github.io/loupe/guide/)**
这是一个 monorepo（npm 工作区）。每个部分都可以在本地运行，无需外部服务 - 数据库是嵌入式 Postgres（PGlite），因此 `npm install && npm run build && npm run seed && npm start` 就是整个设置。
## 软件包
```
packages/
shared/ 规范类型 + normalizeUrl() （构建到 dist，由所有包消费）
sdk/ 可嵌入的浏览器 SDK — 检查、评论（元素/区域/自由注释）、捕获、重新锚定；可停靠的控制面板
demo/ 一个模拟产品（“Acme Analytics”），用于尝试 Loupe
server/ 评论 API — node:http、Postgres、对象存储、HMAC 身份验证、静态托管
dashboard/ 看板式分类管理面板（读取 API）
mcp/ MCP 服务器 — 向 Claude Code 公开评论
extension/ MV3 浏览器扩展 — 检查/评论任意网站，像素级捕获
laravel/ Laravel 的 Loupe — Composer 包：小部件 + 您的数据库 + 访问控制 + 管理面板 + MCP
```
### Laravel 的 Loupe
是否更喜欢在自己的应用中运行整个循环？[`loupekit/laravel`](packages/laravel) 是一个 Composer 包，它嵌入了小部件，在**您的**数据库中存储评论，使用**您的**授权规则控制访问，在**您的**路由上提供管理面板，并通过 MCP 将待办事项暴露给 Claude — 无需单独的 Node 后端。参见[完整指南](docs/LARAVEL.md)。
```bash
composer require loupekit/laravel
php artisan loupe:install && php artisan migrate
# 在您的布局中添加 @loupeWidget，然后打开 /loupe/dashboard
```
## 运行
```bash
npm install
npm run build # shared → sdk → dashboard → extension
npm run seed # 创建演示项目；打印其管理员密钥 + 演示 HMAC
npm start # 一个进程在 http://localhost:8787 上提供 API + 管理面板 + 演示 + SDK
```
然后打开：
- **演示产品** — http://localhost:8787/demo/ （留下反馈；持续到 API）
- **分类管理面板** — http://localhost:8787/dashboard/?key=<管理员密钥从 `npm run seed` 中获取>
将 **Claude Code** 指向评论：
```json
{
"mcpServers": {
"loupe": {
"command": "node",
"args": ["/绝对路径/to/loupe/packages/mcp/index.ts"],
"env": {
"LOUPE_API": "http://localhost:8787",
"LOUPE_PROJECT_KEY": "pk_demo_acme",
"LOUPE_ADMIN_KEY": "<管理员密钥从 npm run seed 中获取>"
}
}
}
}
```
然后：*“列出开放的 Loupe 评论并逐一处理。”* Claude 调用 `list_comments` → `get_comment` （请求 + 元素 HTML + 计算样式 + 截图 URL）→ 进行更改 → `update_status`。
## 架构说明
**数据库** — `server/db.ts` 是一个单一功能的 `query()` 接口。当设置了 `DATABASE_URL` 时，它使用 node-postgres 连接到真实/托管的 Postgres；否则使用嵌入式 PGlite 存储在磁盘上。相同的 SQL，相同的 `$1` 参数。
**身份验证** — 每个项目都有一个 `secret`。写入操作需要 `X-Loupe-User` + `X-Loupe-Hmac` = HMAC-SHA256(userId, secret) （宿主应用的服务器计算并注入此值 — 演示中的值由 `npm run seed` 预计算）。管理面板和 MCP 服务器使用 `X-Loupe-Admin` = secret 进行身份验证。截图 blob 由不可猜测的 ID 提供（生产环境中使用签名 URL）。
**对象存储** — `server/blobs.ts` 是接口（目前为本地磁盘，未来为 S3）。SDK 将截图上传到 `POST /v1/blobs`，并仅在评论上存储返回的 **URL**，因此列表/读取操作保持较小。
**URL 规范化** — `@loupekit/shared` 中的 `normalizeUrl()` 删除 `utm_*`、点击 ID 和 Loupe 的开发参数，因此对 `/checkout?utm_source=x` 和 `/checkout` 的评论不会分散。 在写入和查询时在服务器端应用。
## 浏览器扩展
扩展程序重用了完全相同的 SDK 核心；其唯一的区别是截图源 — `chrome.tabs.captureVisibleTab` （真实像素），裁剪到元素并进行编辑，通过 SDK 的 `captureScreenshot` 重载实现。手动加载：
```bash
npm run build:extension # 构建 packages/extension/content.js
```
1. `chrome://extensions` → 启用 **开发者模式** → **加载解包** → 选择 `packages/extension`。
2. 点击 Loupe 图标 → 设置项目密钥（`pk_demo_acme`）、用户、API 基址（`http://localhost:8787`）和（可选）演示 HMAC → **在此选项卡上启动 Loupe**。
> 注意：扩展程序通过构建 + 清单/包检查进行验证；完整的浏览器端到端测试未在此存储库的无头设置中自动化。
## 路线图
1. **客户端 SDK** ✓ — 检查、评论、捕获、重新锚定到重新部署。
2. **后端 API** ✓ — Postgres、HMAC 身份验证 + 按项目密钥、对象存储、静态托管。
3. **MCP 服务器** ✓ — 作为 Claude Code 待办事项的评论。
4. **管理面板** ✓ — 看板式分类管理。
5. **强化** ✓ — monorepo、Postgres、强制身份验证、blob 存储、URL 规范化。
6. **浏览器扩展** ✓ — 任意网站的像素级捕获。
**下一步：** 真实的云对象存储（S3/R2）+ 签名 URL、项目/团队管理 UI、Postgres 迁移工具和将 SDK/MCP 打包到 npm + 扩展到 Chrome 应用商店。
## 作者
**Loupe 由 [Mohamed Ashraf Elsaed](https://www.linkedin.com/in/mohamedashrafelsaed/) 创建和维护。**
- 💼 LinkedIn: [mohamedashrafelsaed](https://www.linkedin.com/in/mohamedashrafelsaed/)
- 🐙 GitHub: [@mohamed-ashraf-elsaed](https://github.com/mohamed-ashraf-elsaed)
- ✉️ 邮箱: [m.ashraf.saed@gmail.com](mailto:m.ashraf.saed@gmail.com)
如果 Loupe 对您有帮助，存储库上的 ⭐ 和 LinkedIn 上的连接始终是受欢迎的。对于咨询或合作，请通过上述任何链接联系。
## 许可证
MIT © [Mohamed Ashraf Elsaed](https://www.linkedin.com/in/mohamedashrafelsaed/)
