@ agent- native/ pinpoint (帮助)

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

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

独立工作,与 构建者.io,或者与任何能说代理人-内设协议的代理运行时间(Builder.io, Claude Code, Codex, 双子座CLI, Cursor等).

AI 代理设置指南

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

步骤1:安装

pnpm add @agent-native/pinpoint

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

npx @agent-native/pinpoint@latest init

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

第3步: 挂载客户端

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

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 :

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

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

查找 Express 服务器设置( 通常是) server/index.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数字 :

{
  "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>

解决问题

安装

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

快速启动

反应

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

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

香草JS/脚本标签

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

强制性 API( 非反应)

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

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

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

1. 安装

pnpm add @agent-native/pinpoint

2. 初始化

npx @agent-native/pinpoint@latest init

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

3. 客户端-挂载

// 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 中间软件

// 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()数字 :

国 际

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

键盘快捷键

软件包导出

服务器中端软件

表示针 CRUD 的中间软件 :

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

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

代理动作

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

初级 API

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

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

插件系统

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 向外部代理显示指针:

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

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

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

框架支助

存储适配器

构建者.io 集成

内部 构建者.io的融合页:1 sendToAgentChat() 从 @agent-native/core数字 :

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

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

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

建筑

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

许可证

麻省理工学院