# @agent-native/pinpoint 中文文档

规范地址：https://npmcn.com/package/%40agent-native/pinpoint/

版本：0\.1\.108
npm 元数据更新时间：2026-11-05T01:29:24.296Z
中文译文更新时间：2026-11-06T00:42:07.968Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agent-native/pinpoint
原文对照：https://npmcn.com/package/%40agent-native/pinpoint/?lang=original
项目主页：https://github.com/BuilderIO/agent-native#readme
源码仓库：https://github.com/BuilderIO/agent-native

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

- 包体积（解压后）：827 kB，57 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react \>=18\.0\.0，@agent-native/core \>=0\.224\.0-0
- 首次发布：2026-04-30T13:27:58.135Z
- 最新版本发布：2026-11-05T01:29:23.661Z
- 近 30 天下载量：8073（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：135（近 12 个月 135 个）

## 中文简介

代理本地网络应用程序的视觉反馈和注释工具

## 安装

```sh
npm install @agent-native/pinpoint
```

也可以使用：`pnpm add @agent-native/pinpoint`、`yarn add @agent-native/pinpoint`、`bun add @agent-native/pinpoint`

## README

# @ agent- native/ pinpoint (帮助)

网络应用的视觉反馈和注释工具. 用户选择UI元素,添加反馈,并将结构化上下文发送到任何AI代理.

Pinpoint是按要求安装的工具包能力模块。 它生活在一个 拥有 npm 软件包, 因此应用程序只接收视觉反馈表面和代理 他们需要融合.

独立工作,与 [构建者.io](https://builder.io/?utm_source=agent-native&utm_medium=readme&utm_campaign=pinpoint&utm_content=overview),或者与任何能说代理人-内设协议的代理运行时间(Builder.io, Claude Code, Codex, 双子座CLI, Cursor等).

## AI 代理设置指南

指示AI代理(Builder.io,克洛德代码,Codex,Cursor等)在代理本地寄存器中添加Pinpoint.

### 步骤1:安装

```sh
pnpm add @agent-native/pinpoint
```

### 第2步:初始化代理行动和技能

```sh
npx @agent-native/pinpoint@latest init
```

此复制代理动作到 `actions/` 和平点技能 `.agents/skills/pinpoint/`。不需要手动复制文件.

### 第3步: 挂载客户端

查找根反应组件( 通常为 `app/App.tsx` 或者说 `src/App.tsx`) (中文(简体) ). 添加数据 `<Pinpoint />` 组件 :

```tsx
import { Pinpoint } from "@agent-native/pinpoint/react";

// Add as a sibling to your app root — renders nothing, mounts overlay in Shadow DOM
<Pinpoint author="User" endpoint="/api/pins" autoSubmit colorScheme="auto" />;
```

如果应用程序不基于反应,请使用必须的 API :

```ts
import { mountPinpoint } from "@agent-native/pinpoint";
mountPinpoint({ author: "User", endpoint: "/api/pins", autoSubmit: true });
```

### 第4步: 添加服务器中间软件

查找 Express 服务器设置( 通常是) `server/index.ts`) (中文(简体) ). 添加指针路径 :

```ts
import { pagePinRoutes } from "@agent-native/pinpoint/server";

// Add before your page routes
app.use("/api/pins", pagePinRoutes());
```

创建 REST 端点 `/api/pins` 为针 CRUD。 纸作为 JSON 文件存储于 `data/pins/`。 。 。 .

### 步骤5:核实

1.  启动 dev 服务器
2.  在浏览器中打开应用程序
3.  新闻 `Cmd+Shift+.` 切换 Pinpoint 工具栏
4.  单击任意元素,添加注释,并点击"Add Pin"
5.  单击发送按钮 — 应在代理聊天中显示注释

### 与 Pins 合作

柱子作为单个 JSON 文件存储于 `data/pins/{uuid}.json`数字 :

```json
{
  "id": "uuid",
  "pageUrl": "/dashboard",
  "comment": "This button color is wrong",
  "element": {
    "tagName": "button",
    "selector": ".sidebar button.primary",
    "classNames": ["primary", "btn"]
  },
  "framework": {
    "framework": "react",
    "componentPath": "<Sidebar> <ActionButton>",
    "sourceFile": "src/components/Sidebar.tsx:42"
  },
  "status": { "state": "open" }
}
```

**代理人关键字段 :**

-   `sourceFile` ——要编辑的确切文件和行
-   `componentPath` ——反应/Vue 组件分级
-   `selector` —— CSS 选择器在 DOM 中查找元素
-   `comment` - 用户想要的改变

**代理命令** (在 `npx @agent-native/pinpoint@latest init`:

-   `pnpm action get-pins --status open` - 列表中未解决的指针
-   `pnpm action resolve-pin --id <uuid>` ——在修复后标为已解决
-   `pnpm action create-pin --pageUrl / --selector ".btn" --comment "Fix this"`
-   `pnpm action update-pin --id <uuid> --comment "Updated feedback"`
-   `pnpm action delete-pin --id <uuid>` -取出一针

**工作流量 :**

1.  用户在浏览器中创建注释
2.  读取 `pnpm action get-pins --status open`
3.  使用 `sourceFile` 查找和编辑相关代码
4.  修复后, 标记解析 : `pnpm action resolve-pin --id <uuid>`

### 解决问题

| 问题 | 修补 |
| --- | --- |
| 工具栏没有出现 | 检查 `<Pinpoint />` 已挂载。 新闻 `Cmd+Shift+.` |
| 未持续 | 保证 `endpoint="/api/pins"` 设置并添加服务器中间软件 |
| `sourceFile` 为空 | 源检测需要dev模式. 生产建筑 `_debugSource` |
| "找不到模块" | 运行 `pnpm install`检查软件包 `dependencies` |

* * *

## 安装

```sh
pnpm add @agent-native/pinpoint
# or
npm install @agent-native/pinpoint
```

## 快速启动

### 反应

```tsx
import { Pinpoint } from "@agent-native/pinpoint/react";

function App() {
  return (
    <>
      <Pinpoint author="Designer" endpoint="/api/pins" autoSubmit />
      <YourApp />
    </>
  );
}
```

### 香草JS/脚本标签

```html
<script src="https://unpkg.com/@agent-native/pinpoint/dist/index.browser.js"></script>
<script>
  Pinpoint.mountPinpoint({ author: "Designer" });
</script>
```

### 强制性 API( 非反应)

```ts
import { mountPinpoint } from "@agent-native/pinpoint";

const { dispose } = mountPinpoint({
  author: "Designer",
  endpoint: "/api/pins",
});
// Call dispose() to unmount
```

## 在代理本地应用程序中设置

### 1\. 安装

```sh
pnpm add @agent-native/pinpoint
```

### 2\. 初始化

```sh
npx @agent-native/pinpoint@latest init
```

复制代理动作到 `actions/` 和平点技能 `.agents/skills/pinpoint/`。 。 。 .

### 3\. 客户端-挂载

```tsx
// app/App.tsx
import { Pinpoint } from "@agent-native/pinpoint/react";

function App() {
  return (
    <>
      <Pinpoint
        author="Designer"
        endpoint="/api/pins"
        autoSubmit
        colorScheme="auto"
      />
      <YourApp />
    </>
  );
}
```

### 4\. 服务器 -- -- 添加 REST 中间软件

```ts
// server/index.ts
import { createServer } from "@agent-native/core/server";
import { pagePinRoutes } from "@agent-native/pinpoint/server";

const app = createServer({
  /* ... */
});
app.use("/api/pins", pagePinRoutes());
```

## 如何运作

1.  **切换** 工具栏 : `Cmd+Shift+.` (或 `Ctrl+Shift+.`(中文(简体) )
2.  **点击** 说明它的任何元素
3.  **类型** 弹出中反馈
4.  **发送** 给代理人的: `Cmd+Shift+Enter`

代理接收结构化上下文: CSS 选择器,组件等级,源文件位置,以及用户的评论.

## 配置

所有选项都可以作为道具传递到 `<Pinpoint />` 或作为配置对象 `mountPinpoint()`数字 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `author` | `string` | —— 说 | 谁在注解 |
| `endpoint` | `string` | —— 说 | REST 持久性的终点(例如, `/api/pins`(中文(简体) ) |
| `colorScheme` | `'auto' | 'light' | 'dark'` | `'auto'` | 主题 |
| `outputFormat` | `'compact' | 'standard' | 'detailed'` | `'standard'` | 代理输出的详细级别 |
| `autoSubmit` | `boolean` | `true` | 自动提交代理聊天说明 |
| `clearOnSend` | `boolean` | `false` | 发送后清除指针 |
| `sendToAgent` | `(output) => void | Promise<void>` | —— 说 | 自定义批注发送桥 |
| `blockInteractions` | `boolean` | `false` | 选择时点击块页 |
| `compactPopup` | `boolean` | `true` | 切换后隐藏技术细节 |
| `freezeJSTimers` | `boolean` | `false` | 选择时冻结 JS 计时器 |
| `allowedOrigins` | `string[]` | —— 说 | 后Message允许的出处 |
| `webhookUrl` | `string` | —— 说 | 针事件使用 Webhook URL |
| `includeSourcePaths` | `boolean` | —— 说 | 在输出中包含源文件路径 |
| `markerColor` | `string` | `'#3b82f6'` | 附加说明元素上的标记颜色 |
| `plugins` | `Plugin[]` | —— 说 | 插件扩展 |
| `storage` | `PinStorage` | —— 说 | 自定义存储适配器 |
| `position` | `{ x, y }` | —— 说 | 初始工具栏位置 |

## 国 际

```sh
npx @agent-native/pinpoint@latest init   # Copy actions and skill to your project
npx @agent-native/pinpoint@latest        # Show help
```

## 键盘快捷键

| 快捷键 | 行动 |
| --- | --- |
| `Cmd/Ctrl+Shift+.` | 切换工具栏 |
| `Cmd/Ctrl+Shift+C` | 复制剪贴板的注释 |
| `Cmd/Ctrl+Shift+Enter` | 向代理机构发送注释 |
| `Esc` | 关闭弹出/ 倒塌工具栏 |
| `Shift+Drag` | 多选择元素 |

## 软件包导出

| 导入路径 | 它提供什么 |
| --- | --- |
| `@agent-native/pinpoint` | `mountPinpoint()`, (中文(简体) ), `unmountPinpoint()`,类型 |
| `@agent-native/pinpoint/react` | `<Pinpoint />` 反应组件 |
| `@agent-native/pinpoint/server` | `pagePinRoutes()` 显示中间软件 |
| `@agent-native/pinpoint/primitives` | `getElementContext()`, (中文(简体) ), `freeze()`, (中文(简体) ), `unfreeze()`, (中文(简体) ), `openFile()` |
| `@agent-native/pinpoint/types` | 类型 :`Pin`, (中文(简体) ), `PinpointConfig`页:1 |

## 服务器中端软件

表示针 CRUD 的中间软件 :

```ts
import { pagePinRoutes } from "@agent-native/pinpoint/server";

app.use("/api/pins", pagePinRoutes({ dataDir: "data/pins" }));
```

| 方法 | 终点 | 说明 |
| --- | --- | --- |
| 获取 | `/api/pins` | 列表指针( 克里: `pageUrl`, (中文(简体) ), `status`(中文(简体) ) |
| 获取 | `/api/pins/:id` | 拿个针 |
| 邮政 | `/api/pins` | 创建指针 |
| 帕齐 | `/api/pins/:id` | 更新针头 |
| 迪莱特 | `/api/pins/:id` | 删除指针 |
| 迪莱特 | `/api/pins` | 清除针( 克里: `pageUrl`(中文(简体) ) |

## 代理动作

运行后可用 `npx @agent-native/pinpoint@latest init`数字 :

| 行动 | 目的 | 参数 |
| --- | --- | --- |
| `get-pins` | 列表指针 | `--pageUrl`, (中文(简体) ), `--status` |
| `create-pin` | 创建指针 | `--pageUrl`, (中文(简体) ), `--selector`, (中文(简体) ), `--comment` |
| `resolve-pin` | 标记为已解决 | `--id`, (中文(简体) ), `--message` |
| `update-pin` | 更新针头 | `--id`, (中文(简体) ), `--comment`, (中文(简体) ), `--status` |
| `delete-pin` | 删除指针 | `--id` |
| `list-sessions` | 带有指针的列表页面 | —— 说 |

## 初级 API

方案要素检查的独立职能(无UI):

```ts
import {
  getElementContext,
  freeze,
  unfreeze,
  openFile,
  detectFramework,
} from "@agent-native/pinpoint/primitives";

const context = getElementContext(document.querySelector(".sidebar"));

freeze(); // Pause all animations
unfreeze(); // Resume

openFile("src/components/Sidebar.tsx", 42); // Open in editor
```

## 插件系统

```ts
import type { Plugin } from "@agent-native/pinpoint/types";

const myPlugin: Plugin = {
  name: "analytics",
  hooks: {
    onPinCreate(pin) {
      analytics.track("pin_created", { page: pin.pageUrl });
    },
    onPinResolve(pin) {
      analytics.track("pin_resolved", { id: pin.id });
    },
    transformOutput(output) {
      return output + "\n\n_Sent via Pinpoint_";
    },
  },
  actions: [
    {
      label: "Export to Jira",
      handler(element, context) {
        createJiraTicket(context);
      },
    },
  ],
};
```

## A2A & MCP 软件

通过 A2A 或 MCP 向外部代理显示指针:

```ts
import {
  registerPinpointA2A,
  createPinpointMCPTools,
} from "@agent-native/pinpoint/server";

registerPinpointA2A(app); // /.well-known/agent-card.json

const { tools, handleTool } = createPinpointMCPTools(); // MCP tool handlers
```

## 框架支助

| 框架 | 检测 | 组件信息 | 来源位置 |
| --- | --- | --- | --- |
| 反应18/19 | 自动( 通过双盘) | 构成部分等级 | `_debugSource` / 元素来源 |
| 第3组 | 自动( A)`__VUE__`(中文(简体) ) | 组件树 | `$options.__file` |
| 其它 | 倒计时 | 仅限 DOM | 不详 |

## 存储适配器

| 适配器 | 使用大小写 | 持久性 |
| --- | --- | --- |
| `MemoryStore` | 独立, 没有服务器 | 仅会话( 重新装入时丢失) |
| `RestClient` | 带有服务器的浏览器 | 服务器端通过 REST API |
| `FileStore` | 服务器侧 | `data/pins/{uuid}.json` |

## 构建者.io 集成

内部 [构建者.io的融合](https://builder.io/?utm_source=agent-native&utm_medium=readme&utm_campaign=pinpoint&utm_content=fusion)页:1 `sendToAgentChat()` 从 `@agent-native/core`数字 :

```tsx
<Pinpoint author="Builder User" autoSubmit outputFormat="standard" />
```

在 Builder.io 项目内运行时不需要额外的配置 .

主机拥有自己的聊天执行可以通过 `sendToAgent` 重新使用平分针, 投递时绘制、队列并提示 UI `{ message, context, submit }` 他们自己.

## 建筑

-   **实心JS 覆盖** 内 **阴影DOM** ——对主机应用程序样式或React调节的零干扰
-   **基于帆布** 以 LERP 插值- 平滑 60fps 来突出显示
-   **每针一个文件** ——消除并发写冲突
-   **可插件存储** — 内存站, 休息站, 文件站
-   麻省理工学院图书馆: [双](https://github.com/aidenybai/bippy), (中文(简体) ), [@ medv/ finder (英语)](https://github.com/antonmedv/finder), (中文(简体) ), [元素来源](https://www.npmjs.com/package/element-source)

## 许可证

麻省理工学院

## 常见问题

### @agent-native/pinpoint 是什么？

代理本地网络应用程序的视觉反馈和注释工具

### 如何安装 @agent-native/pinpoint？

在项目目录运行 npm install @agent-native/pinpoint，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@agent-native/core（\>=0\.224\.0-0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 pinpoint，可以用 npx pinpoint 直接运行。

### @agent-native/pinpoint 支持 TypeScript 吗？

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

### @agent-native/pinpoint 支持 ESM 还是 CommonJS？

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

### @agent-native/pinpoint 可以商用吗？

@agent-native/pinpoint 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agent-native/pinpoint 的下载量有多少？

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

### @agent-native/pinpoint 还在维护吗？

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