# @commentkit/comment-kit 中文文档

规范地址：https://npmcn.com/package/%40commentkit/comment-kit/

版本：1\.5\.1
npm 元数据更新时间：2026-10-28T07:40:34.301Z
中文译文更新时间：2026-11-10T12:18:29.058Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40commentkit/comment-kit
原文对照：https://npmcn.com/package/%40commentkit/comment-kit/?lang=original
项目主页：https://commentkit.dev/
源码仓库：https://github.com/commentkit/comment-kit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，69 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- peer 依赖：vue \>=3，react \>=18，svelte \>=4
- 首次发布：2026-10-10T18:50:02.660Z
- 最新版本发布：2026-10-28T07:40:34.104Z
- 近 30 天下载量：3212（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

任何网站的图片样式注释 。 客户端用自动截图将反馈接上;开发者在本地主机上看到,然后交给他们的AI代理.

## 安装

```sh
npm install @commentkit/comment-kit
```

也可以使用：`pnpm add @commentkit/comment-kit`、`yarn add @commentkit/comment-kit`、`bun add @commentkit/comment-kit`

## README

# 注释Kit

任何网站的图片样式注释 .

您的客户点击页面中的部分, 并写下应该改变的内容 。 注释 Kit把评论贴到准确的点上,附上他们看到的东西的截图,并记录页面,浏览器和屏幕大小. 您可以在您的现场、 中程和预览链接上看到反馈 `localhost` 你可以直接把它交给你的AI编码代理商.

-   **一个安装,每个堆.** 脚本标记在任意网站(WordPress, Webflow, Shopify, plain HTML)工作. npm 用户获得 `init()` 加上小反应,Vue和斯维尔特的帮手。 没有其他要安装的: 不需要在您一方进行反应 .
-   **为从未使用过反馈工具的人所建.** 客户端打开客户端链接,点击,输入,确认其电子邮件一次. 没有帐户 没有密码.
-   **为开发者所建.** 每个分支和环境的反馈,元素选择器和源位置,控制台错误,包含列表和板视图的仪表板,电子邮件通知,以及克劳德代码,光标等代理的MCP服务器.

## 安装

### 任何网站

粘贴前 `</body>`数字 :

```html
<script src="https://commentkit.dev/cdn/v1/loader.js" data-project="pk_live_your_key" defer></script>
```

### 无

```bash
npm install @commentkit/comment-kit
```

```ts
import { init } from "@commentkit/comment-kit";

init({ project: "pk_live_your_key" });
```

### 反应 / Next.js

```tsx
import { CommentKit } from "@commentkit/comment-kit/react";

// Root layout, next to {children}. Works in Next.js server layouts.
<CommentKit project="pk_live_your_key" branch={process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF} />
```

### Vue / 坚果

```ts
import { CommentKitPlugin } from "@commentkit/comment-kit/vue";

app.use(CommentKitPlugin, { project: "pk_live_your_key" });
```

Nuxt: 创建 `plugins/commentkit.client.ts`数字 :

```ts
import { CommentKitPlugin } from "@commentkit/comment-kit/vue";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(CommentKitPlugin, { project: useRuntimeConfig().public.commentkitKey });
});
```

或地点 `<CommentKit project="pk_live_your_key" />` 从 `@commentkit/comment-kit/vue` 它接受下面每个选项作为道具.

### 斯维尔特/斯维尔特基特

```svelte
<!-- src/routes/+layout.svelte -->
<script>
  import { commentkit } from "@commentkit/comment-kit/svelte";
  let { children } = $props();
</script>

<svelte:body use:commentkit={{ project: "pk_live_your_key" }} />
{@render children()}
```

### 还有什么

Angular, Solid, Astro, Quik, Remix, 或自定义设置: 呼叫 `init()` 一次在浏览器中。 如果您喜欢加价, 请将自定义元素导入到您的捆绑中, 然后将标记放置在 :

```ts
import "@commentkit/comment-kit/element";
```

```html
<comment-kit project="pk_live_your_key" branch="main"></comment-kit>
```

属性 : `project` (必须), `branch`, (中文(简体) ), `commit`, (中文(简体) ), `locale`, (中文(简体) ), `theme`, (中文(简体) ), `position`, (中文(简体) ), `auth`, (中文(简体) ), `endpoint`, (中文(简体) ), `deployment-url`, (中文(简体) ), `hide-on-production="false"`, (中文(简体) ), `shortcuts="false"`更改 `project` 重新启动部件.

在仪表板下找到钥匙 **项目-设置** (或运行) `npx @commentkit/cli login` 接下来 `npx @commentkit/cli init`,或 `npx @commentkit/cli init --key pk_live_…` ,并添加其中的每个网站地址(活、中、预览等). `https://*.vercel.app`) (中文(简体) ). 本地人总是为你团队工作.

## 如何表现

| 何处 | 谁看到部件 |
| --- | --- |
| `localhost`, (中文(简体) ), `*.localhost`, (中文(简体) ), `*.test` | 永远可见,为你的团队 |
| 现场、中场和预览站点 | 躲在访客的身边 当某人打开客户端链接时显示( W)`?ck=…`),电子邮件链接,按 **Cmd/Ctrl + Shift + K 调制**,或者已经在该设备上签名 |

人们用一个工具留下反馈:

-   **点击** 需要对此进行评论.
-   **拖动** 以标记一个区域.
-   **先选择文本** 对案文作出准确的评论.

可见页面的截图随所取出之指针自动相接. 审查者可以在上面作画(狭义,盒子,笔,模糊来隐藏私人细节,文字). 密码,卡片字段,一次性代码和任何标记 `data-commentkit-redact` 从来没有被抓住.

签名会打开一个小的注释Kit窗口(或者在WhatsApp和Instagram等应用程序浏览器内部的同名标签中继续). 证书永远不要碰你的页面.

## 选项

```ts
init({
  project: "pk_live_…",        // required
  branch: "feature/checkout",  // filter feedback per branch
  commit: "a1b2c3d",
  deploymentUrl: "https://pr-12.example.vercel.app",
  hideOnProduction: true,      // default; false shows the launcher to everyone
  theme: "auto",               // "light" | "dark" — default from the dashboard
  position: "bottom-right",
  redact: [".customer-email"], // extra selectors never captured
  locale: "fr",                // default: <html lang>, then the browser (see Languages)
  auth: "auto",                // "popup" | "redirect"
  shortcuts: true,             // false turns off C, J / K, E and ? (Esc and Cmd/Ctrl+Shift+K stay)
  tools: { screenshots: true, markup: true, text: true, attachments: true }, // turn parts of the comment tools off
});
```

大多数行为都设置在仪表板上,在没有部署的情况下立即应用:对所有站点,主题,位置,口音颜色,隐私选择器,以及控制台/网络捕捉等进行反馈.

### 脚本标签属性

`data-project` (必须), `data-branch`, (中文(简体) ), `data-commit`, (中文(简体) ), `data-locale`, (中文(简体) ), `data-auth`, (中文(简体) ), `data-endpoint` (另一个评论Kit服务器), `data-hide-on-production="false"`, (中文(简体) ), `data-shortcuts="false"`。 。 。 . `theme`, (中文(简体) ), `position`, (中文(简体) ), `redact` 财务报告和审定财务报表 `deploymentUrl` 为: `init()` 选项;也可以在仪表板中设置主题、位置和隐私选择器.

## 语文

部件会说英语、西班牙语(`es`),法语`fr`),德语(`de`),葡萄牙语代表巴西`pt-BR`页:1`it`),荷兰语(`nl`),日语(`ja`),中文,简化(`zh-CN`印地语(`hi`)和阿拉伯语(`ar`,右至左侧).

选第一对 `init({ locale })` (或 `data-locale` 编号 : `<comment-kit locale>`),然后页面的 `<html lang>`,然后是读者的浏览器语言,然后回到英语。 地区回归语言: `es-MX` 拿西班牙语, `pt` 财务报告和审定财务报表 `pt-PT` 得到巴西葡萄牙语, `zh` 获得简化中文. 时间("5分前")和计数使用浏览器 `Intl` 用于该语言的格式.

英语是内置的。 其他每种语言都是单独的~2.5–3 KB(gzip)文件,只为需要的阅读者加载,而部件则开始. 当其语言是阿拉伯语时,部件右起左出,否则就跟随页面 `dir` 或者说 `<html lang>`。 。 。 .

仅翻译部件;仪表板和电子邮件目前为英文.

## API 密码

`init()` 返回实例 :

```ts
const kit = init({ project: "pk_live_…" });

kit.show();               // bring a hidden widget back (Cmd/Ctrl + Shift + K does too)
kit.hide();
kit.open("CK-12");        // show the widget and open one conversation (id or reference)
kit.comment();            // start comment mode from your own "Leave feedback" button; comment(false) stops it
await kit.signIn();       // call from a click
await kit.signOut();
kit.session();            // { person, role, project, environment, capabilities } | null
kit.on("thread:created", ({ thread }) => {});
kit.destroy();            // removes every trace from the page
```

活动 : `ready`, (中文(简体) ), `session:change`, (中文(简体) ), `thread:created`, (中文(简体) ), `thread:updated`, (中文(简体) ), `message:created`, (中文(简体) ), `mode` (单位:千美元)`{ commenting }`,当注释模式开始或停止时),和 `error` (部件无法启动;); `error.code` 列在 [https://commentkit.dev/docs/errors 页面存档备份,存于互联网档案馆](https://commentkit.dev/docs/errors)) (中文(简体) ).

当部件显示时, **Cmd/Ctrl + Shift + K 调制** 打开或关闭收件箱。 人们从它的部件中隐藏 **再来** 菜单(Hide CommentKit),同样的键将其带回.

### 脚本标签 API : `window.CommentKit`

在使用脚本加载器的站点上,装入器在部件准备好后设置了1个全局, `window.CommentKit`,以及 `destroy()` 又取出取来. 它是唯一的全局注释Kit添加; npm 安装使用 `init()` 以实例代替.

```js
CommentKit.version;                          // "1.0.0"
CommentKit.show();                           // Promise
CommentKit.hide();
CommentKit.open("CK-12");                    // or a thread id
CommentKit.comment();                        // start comment mode (Promise); comment(false) stops it
const onNew = ({ thread }) => console.log(thread.reference);
CommentKit.on("thread:created", onNew);
CommentKit.off("thread:created", onNew);
CommentKit.destroy();                        // removes the widget, its listeners and window.CommentKit
```

`window.CommentKit` 仅在该页面显示部件时存在(本地开发、共享或电子邮件链接、签名人,或Cmd/Ctrl + Shift + K后)。 打电话前检查一下: `window.CommentKit?.open("CK-12")`。 。 。 .

无注释 Kit 确实可以打破您的页面: 下载失败、 设置错误 或部件内部发生崩溃 .

`@commentkit/comment-kit/headless` 出口 `CommentKitClient`, (中文(简体) ), `createAnchor` 财务报告和审定财务报表 `resolveAnchor` 用于自定义界面和浏览器扩展.

## AI探员

最简单的方式:添加 `https://commentkit.dev/mcp` 作为Claude, Cursor 或 VS 代码中的远程MCP服务器并签名. 你选择项目 和代理可以做什么.

```sh
claude mcp add --transport http commentkit https://commentkit.dev/mcp
```

或在您的计算机上运行服务器: 在 **项目-连接**,然后添加到您的经纪人中:

```json
{
  "mcpServers": {
    "commentkit": {
      "command": "npx",
      "args": ["-y", "comment-kit-mcp"],
      "env": { "COMMENTKIT_PROJECT_ID": "123", "COMMENTKIT_TOKEN": "…" }
    }
  }
}
```

**从收件箱寄给探员.** 团队成员在收件箱中选择注释(所有显示的注释都开始勾选,因此页面,分支和过滤器决定去向)并迅速发送. **在光标中打开**, (中文(简体) ), **在 Claude 代码中打开** 财务报告和审定财务报表 **在编码中打开** 以填充的提示打开代理,直到按 Enter 键时才发送。 完整的提示总是被复制到剪贴板上,对于其他代理来说,当一个批次对于链接来说太长时(然后链接带有更短的版本). 与MCP服务器连接, `/fix_feedback` 在特工内部也一样.

代理可以列出,搜索并读取反馈和仪表板任务(包括截图,由ID或 `CK-12`) (中文(简体) ). 根据您选择的权限, 他们可以回复、 链接承诺并标记任务 **备供审查**;默认情况下,一个人先批准其中每一项(代理请求)。 复审者再查并解. 代理从不解析,指派或删除. 见 [`mcp/README.md`](https://npmcn.com/package/%40commentkit/comment-kit/mcp/README.md)。 。 。 .

## 终端和构建工具

-   [`@commentkit/cli`](https://npmcn.com/package/%40commentkit/comment-kit/cli/README.md)数字 : `commentkit login` (浏览器中确认的简短代码), `init` (添加密钥、构建插件和 `.gitignore` 条目, `pull` (开放反馈给 `.commentkit/feedback.md` 对任何代理人, `open CK-12`和CI的标志.
-   [`@commentkit/build`](https://npmcn.com/package/%40commentkit/comment-kit/build/README.md): Vite, Next.js,webpack和Astro插件,用源文件和行在开发中标记元素,并记录分支和承诺. 在本地主机上, 部件首先显示此分支的反馈, 并点击“ 所有分支 ” .

## 隐私和安全

-   项目密钥( E)`pk_…`)只识别一个项目。 服务器上授权所有内容: 部件只在您列出的网站工作, 会话被绑定在该网站上, 而审查人员只看到他们被邀请的项目 .
-   部件在阴影 DOM 中运行, 在页面中添加一个元素, 不需要 `unsafe-eval`,并完全删除 `destroy()`。 。 。 .
-   信任类型: 部件在下面工作 `require-trusted-types-for 'script'`截图引擎通过一个狭义命名的政策写出两个固定字符串, `commentkit-capture`,则不接受其他;没有创建默认政策。 如果您的 CSP 限制策略名称 `trusted-types`,添加 `commentkit-capture` (没有它, 截图被跳过, 其它一切都起作用了).
-   控制台和网络抓取关闭,除非项目打开,然后每个审查者选择每个评论("Include 浏览器错误来帮助开发者"). 只保存元数据(消息;或方法、 URL、状态、时间 `fetch` 财务报告和审定财务报表 `XMLHttpRequest`),绝不是正文或正文,从URL和文本中按名称和值去除证书外观值. "Copy for AI agent"也将其删除.
-   反馈文本作为纯文本提供,只有安全链接。 代理输出标记反馈为不信任 .
-   见 [警卫](https://npmcn.com/package/%40commentkit/comment-kit/SECURITY.md) 如何报告脆弱性.

## 大小

| 已装入 | 吉普语Name |
| --- | --- |
| 脚本加载器( 每页) | ~1.3 KB 键 |
| 启动时的部件( 包括 Preact) | ~31 KB 键 |
| 屏幕截图引擎( 仅在评论时) | ~51 KB 键 |
| 实时(仅限签名者) | ~21 KB 键 |

## 版本和支持

注释 标本跟随 [语义版本](https://semver.org/):一个补丁修补错误,一个次要添加选项或特性而不中断任何东西,只有一个新的主要版本可以去除或改变行为. `init()` 选项,实例 API,事件, `data-*` 属性,自定义元素和适配器是公共 API。 部件的外观及其措辞可以在任何版本中改进.

**脚本标记通道**

| 地址 | 你得到的东西 |
| --- | --- |
| `https://commentkit.dev/cdn/v1/loader.js` | 移动通道:永远是最新的1.x放出,一出船就具有修正和新功能. 推荐给大多数地点. |
| `https://commentkit.dev/cdn/<version>/loader.js` (例如 `/cdn/1.2.3/`(中文(简体) ) | Pinned:准确的发布,发布后从未改变. |

要打针,请使用精确的版本及其子资源完整性散列,所以如果文件有差异,浏览器会拒绝它. 每个出版版本的散列器都在 `https://commentkit.dev/cdn/integrity.json` (从 `public/cdn/integrity.json` 在后端中:

```html
<script src="https://commentkit.dev/cdn/1.2.3/loader.js" integrity="sha384-…" crossorigin="anonymous" data-project="pk_live_your_key" defer></script>
```

装入器然后从同一被固定的文件夹中装入其余部件,这是不可改变的。 被绑定的版本获得无修补:故意移动到更新的版本,并先检查其更改日志.

**无**数字 : `npm install @commentkit/comment-kit@^1` 遵循 1.x 的方式与 `/cdn/v1`; 使用精确的版本 (`--save-exact`和你的锁文件针。 未来主修课程的候选课程公布于 `next` 标签并从未安装 `^1`全部规则在 [文件/核查](https://npmcn.com/package/%40commentkit/comment-kit/docs/VERSIONING.md)。 。 。 .

**支持窗口**:每个主要版本在下个主要版本发布后获得24个月的安全修复,并被错误修复到那时. 每个主要项目的结束日期在 [更改日志](https://npmcn.com/package/%40commentkit/comment-kit/CHANGELOG.md) 当它的后继船舶。 安全保护每个支持的少校中最新的未成年人的土地,所以移动通道和 `^` 区域自动接收它们;被绑定的版本没有。 见 [警卫](https://npmcn.com/package/%40commentkit/comment-kit/SECURITY.md) 报告脆弱性.

## 发展

```bash
npm ci
npm run typecheck
npm test               # unit tests (Vitest)
npm run build          # npm + CDN bundles, public types, size budgets
npm run test:e2e       # Playwright: Chromium, Firefox, WebKit
npm run test:visual    # screenshot tests of the main widget states (Chromium; baselines recorded on macOS)
npm run test:host-matrix   # packed SDK in Next.js, Nuxt, SvelteKit, Angular, Astro, React Router, HTML, WordPress (slow)
semgrep scan --config .semgrep.yml --error src   # security rules for the widget (brew install semgrep)
npm run ci             # every gate; HOST_MATRIX=1 npm run ci adds the host matrix
```

本地 Playwright 重用已在端口 5190 运行的 e2e 服务器; 当数个检出( git worktrees) 测试一次时, 给每个用户自己 `CK_E2E_PORT=5291 npm run test:e2e`。屏幕截图基线 `e2e/specs/visual.spec.ts-snapshots/`。在进行预期的视觉改变后,以 `npx playwright test e2e/specs/visual.spec.ts --project=chromium --update-snapshots` 并在承诺之前审查新图像。 主机矩阵`scripts/host-matrix.mjs`安装 `npm pack` 进入每个应用程序的焦距 `e2e/host-matrix/`,用于生产,并检查部件在本地主机上挂载一次,没有控制台错误,并且单页应用程序在没有它的路线上将其摧毁。 通过应用程序名来运行其中的一些( P)`npm run test:host-matrix -- next astro`; WordPress 需要编辑 `php` 在路径上被跳过.

建筑和行进图 [智利-布鲁普林特.md](https://npmcn.com/package/%40commentkit/comment-kit/ARCHITECTURE-BLUEPRINT.md) 财务报告和审定财务报表 [TASKS. md (英语)](https://npmcn.com/package/%40commentkit/comment-kit/TASKS.md)。 。 。 .

## 释放

版本和更改日志的管理方式 [更改](https://github.com/changesets/changesets) 用于四个已出版软件包: `@commentkit/comment-kit` (这个文件夹), `comment-kit-mcp` (单位:千美元)`mcp/`, (中文(简体) ), `@commentkit/cli` (单位:千美元)`cli/`和 `@commentkit/build` (单位:千美元)`build/`) (中文(简体) ). 浏览器扩展,Zapier应用和Make应用都是私人的,从来没有这样版本. 没有 npm 工作空间: 每个软件包都保存自己的锁文件,以及 `lerna.json` 只告诉更改软件包在哪里.

1.  如果使用软件包的人会注意到每个变化,请添加一个更改器: `npm run changeset`。选择软件包、凸起(patch、次要或主要,见上文版本),并为更改日志写出一个平话。 提交文件 `.changeset/` 与变化.
    
2.  准备发布,运行 `npm run release:status` 以观察将遭遇什么 `npm run version`。它对每个 `package.json` 并写下更改日志。 审查diff,更新每个软件包的锁文件(`npm install --package-lock-only` 并且承诺.
    
3.  1.x在β时,运行 `npx changeset pre enter beta` 第一次,所以版本出来作为 `1.0.0-beta.N` 而不是跳跃到 `1.0.0`· ; `npx changeset pre exit` 在稳定释放之前.
    
4.  出版时需要手动操作,每次需要所有者前行:在每个文件夹中, `npm run check` (或包裹的大门)和 `node scripts/check-pack.mjs`,则 `npm publish`不运行 `changeset publish`。 。 。 .
    
5.  CDN部件逐渐推出. 在后端, `scripts/sync-sdk.sh` 写出钉子 `public/cdn/<version>/` 文件夹( 有 SRI 散列); 然后部署它 `php artisan cdn:canary <version> --percent=1`,稍后时 `10` 财务报告和审定财务报表 `100`编辑 `/cdn/v1/` 装入器询问 `/api/v1/widget/channel` 哪个版本要装入,所以更改会在一分钟内生效. 每个版本都计算出部件相撞,当金丝雀在超过1%的负载中相撞时会自动回滚,或者时常出现三倍的稳定相撞(C`cdn:canary --status`, (中文(简体) ), `--rollback` (掌声) 当它保持100%,同步到 `/cdn/v1/` (稳定的档案),部署,以及 `cdn:canary --clear`。 。 。 .
    

`npm run version` 也是npm的生命周期钩 `npm version`这样 `npm version` 在此文件夹中也运行变换器; 使用以上步骤代替 `npm version`。 。 。 .

## 许可证

专有. 见 [自由主义](https://npmcn.com/package/%40commentkit/comment-kit/LICENSE)。 。 。 .

## 常见问题

### @commentkit/comment-kit 是什么？

任何网站的图片样式注释 。 客户端用自动截图将反馈接上;开发者在本地主机上看到,然后交给他们的AI代理\.

### 如何安装 @commentkit/comment-kit？

在项目目录运行 npm install @commentkit/comment-kit，或使用 pnpm add / yarn add / bun add。

### @commentkit/comment-kit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @commentkit/comment-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @commentkit/comment-kit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @commentkit/comment-kit 可以商用吗？

@commentkit/comment-kit 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @commentkit/comment-kit 的下载量有多少？

根据 npm 官方下载统计，@commentkit/comment-kit 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,212 次，日均约 107 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @commentkit/comment-kit 还在维护吗？

最新版本 1\.5\.1 发布于 2026/10/28（13 天前）；至今共发布 24 个版本，其中过去 12 个月发布了 24 个；首次发布于 2026/10/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。