HellDots
插入式评论覆盖的web应用程序。你的团队在页面上任意点击， 在此元素上留下注释，而《HellDots》便能够抓住上下文 需要对它采取行动——屏幕截图，浏览器，视口，DOM路径。
特性
- 固定的评论 存活下来的，在页面加载后重新锚定 变化——或被标记为孤儿，从未无声地落下
- 自动背景：截图，区域裁剪，URL，视窗，浏览器， 操作系统和元素的DOM路径
- 分类：状态、类型、优先级、标签、反应和审计跟踪
- 指标指示板 与CSV和PDF导出
- 代理人副本：为AI编码助手构建的纯文本上下文块
- 你拥有数据：没有任何东西被发送到任何地方-将回调连接到您的
后端，或者让小部件持久化到
localStorage - 孤立的：在Shadow DOM内渲染，框架无关，类型
- 英语和西班牙语 建在
安装
npm install helldots
modern-screenshot（屏幕截图渲染器）是一个对等依赖。npm 7 +, PNPM 8+和bun自动安装；在Yarn上，显式地添加yarn add modern-screenshot。
快速启动
import { createCommentOverlay } from "helldots";
createCommentOverlay({
user: { name: "Ana" },
persistence: "localStorage",
});
就是这样。工具栏出现在页面底部。 Alt+C (或
Option+C 在macOS上)切换评论模式；单击任何地方留下一个
注释，或拖动以选择一个区域并附加该区域的屏幕截图。
将其连接到您自己的后端
跳过 persistence 用回调来代替。 onChange 有每
突变是一条溪流； onReady 是安全的地方恢复：
import { createCommentOverlay } from "helldots";
createCommentOverlay({
user: { name: currentUser.name, id: currentUser.id },
onChange: (event) => api.post("/helldots-events", event),
onReady: async (overlay) => {
overlay.loadComments(await api.get("/comments"));
},
});
每个注释都是纯JSON: pass serializeComments() 直接输出到
你的API并把它交还给 loadComments() 以后。希望每次回调一次
事件(onCommentCreated， onReplyAdded,……)?他们在同一时刻开火
看到 事件。
localStorage 拥有大约一百条评论和截图和假设
每个页面一个活动标签；在此之后，坚持回调。保持
Base64图像从您的数据库，上传他们与 transformScreenshot。
→ 持久性指南
框架
Server-rendered应用 （Next.js, Remix, Astro…）：导入是安全的-什么都没有 在导入时触及DOM。只在客户端上创建覆盖层：
useEffect(() => {
const overlay = createCommentOverlay({ user, persistence: "localStorage" });
return () => overlay.cleanup();
}, [user]);
单页面应用程序：当导航发生时，告诉小部件，并让它运行 自己的跨页跳转使用你的路由器：
const overlay = createCommentOverlay({
user,
navigate: (page) => router.push(page),
});
router.afterEach(() => overlay.notifyNavigation());
→ 框架指南
将注释传递给编码代理
每个评论都有一个 复制 控件上的纯文本上下文块 剪贴板，用于粘贴到AI编码助手中；
Page: /pricing
Viewport: 1440x900
Anchor state: anchored
Status: open
Selector: #plans > div.card:nth-child(2) > button
Element: <button class="cta" data-plan="pro">
DOM path: body > main.layout > section#plans > div.card > button.cta
Nearby text: "Upgrade to Pro"
Comment by Ana (2026-07-29T10:14:00.000Z):
"This button does nothing on mobile"
Type: bug
Priority: high
Tags: checkout, ios
URL: https://example.com/pricing
Screen: 390x844
Browser: Safari 17.2
OS: iOS 17.2
常见的选项
| 选项 | 默认的 | |
|---|---|---|
user | "Anonymous" | { name, id? } ——通过 id 只要两个人有相同的名字 |
persistence | "none" | "localStorage"，或者通过回调自己处理它 |
onChange | - - - - - - | 每个突变都有一个流 |
onReady | - - - - - - | 部件安装;安全的地方 loadComments() |
autoScreenshot | true | 捕获每个评论的屏幕截图和环境快照 |
transformScreenshot | - - - - - - | 上传每个图像并存储您的URL，而不是base64数据URL |
can | 只做自己的记录 | 谁可以编辑和删除——一个UI守卫，而不是授权 |
navigate | 全页面加载 | 用于小部件跨页面跳转的SPA路由器钩子 |
locale | 浏览器语言 | "en" 和 "es" 船 |
指南
- 捕捉 -什么是 记录，网页字体，缓慢或非常长的页面，iframe，超时
- 身份 - - - - - -
user.id， 谁可以编辑和删除，以及什么can不安全 - 分类 -状态、类型、 优先级、标签、反应和审计跟踪
- 指标 - - -
指示板,
getMetrics()， CSV和PDF导出 - 持久性 - - - - - -
localStorage限制，你自己的后端，截图上传 - 深度链接 - - - - - - 可共享的评论url，并且只加载链接的评论
- 实时 ——同步 通过套接字而不回显您自己的写入
- 框架 - - - - - - 服务器渲染，SPA路由器，热键，无绑定器设置，延迟挂载
浏览器支持
现代常绿浏览器。该小部件在Shadow DOM中呈现，因此 页面的CSS不能泄漏，它的样式也不能泄漏。
ESM只
这个包只提供ES模块。 import 无处不在——捆绑商，Vite，
Next.js，节点≥18，本机 <script type="module">． 没有CommonJS
构建,所以 require("helldots") 不会起作用。TypeScript定义船
和包裹一起。
为了一个普通的 <script> 标记，则启动了一个独立的UMD构建
CDN:
<script src="https://unpkg.com/helldots"></script>
<script>
HellDots.createCommentOverlay({ user: { name: "Ana" } });
</script>
许可证
麻省理工学院