@gchust/agent-annotations

中文文档
0.1.9发布于 2026/09/18MITTypeScriptES Module构建来源已验证近 30 天下载 2.1万

在 React/Vite 应用程序中仅交给代码代理的开发者可视化说明

中文使用文档
文档目录15 节
  1. 安装
  2. 维特
  3. 快速启动( 5分钟)
  4. 手动运行时间和自定义运输
  5. 配置
  6. 最小客户端扩展
  7. 没有浏览器运行时间的节点工具
  8. 国 际
  9. 本地化
  10. 运行时间诊断(主机和网络)
  11. 扩展失败隔离
  12. 警卫
  13. 释放核查
  14. API 参考
  15. 限制

代理说明

在React/Vite应用程序中,仅由开发者进行可视化说明交给了代码代理.

安装

代理说明要求节点20或更新,React 19,React DOM 19和Vite 6:

pnpm add -D @gchust/agent-annotations

一揽子措施仅限无害环境管理。 当根运行时间被嵌入时 Vite 是可选的 带有自定义 TaskTransport。 。 。 .

维特

注册只开发插件; 它自动注入客户端, 所以 应用程序入口不需要代理说明代码 :

import agentAnnotations from "@gchust/agent-annotations/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [agentAnnotations()],
});

屏幕截图证据模式可以在插件和 mountAgentAnnotations()数字 : screenshotEvidence: "auto" | "manual" | "off" (默认) "auto") (中文(简体) ). auto 在背景中获取最佳证据 在注解被保存后; manual 跳过自动抓取并曝光 Capture screenshot 行动 注释编辑器加 studio.commands.annotations.captureEvidence(id)· ; off 禁用完全抓取——没有条目,没有页面克隆. 无效的值 丢出一个 TypeError 在插件/挂载时间.

包根导出主机中性 agent-annotations.task.v1 核心项目 mountAgentAnnotations() 浏览器运行时间 。 也提供公共合同 从 @gchust/agent-annotations/types· ; MemoryTaskTransport 仅提供 从 @gchust/agent-annotations/testing 测试和操场.

当不存在保存的首选项时,工具栏默认会开始扩展 。 它的倒塌或被扩大的状态被记住每个起源和任务跨重载,优先于 initialState.collapsed。如果浏览器存储不可用或无效,则使用配置的初始状态。 当它倒塌时,它会变成 40 px 右下方带有开口数徽章的注解图标;图标可以是 拖曳并记住其任务特定位置,而点击会扩展它. 抓取快捷键( Pick/ Multi/ Area) 也会扩展码头并启动 而不是默默地失败。 保存注释退出捕获模式 。 这个 初始 UI 和内置动作可以在 Vite 插件上配置 mountAgentAnnotations()数字 :

// Minimal builtins: keep only Pick and Copy, move Pick to Ctrl+Alt+X.
agentAnnotations({
  builtins: {
    multi: false,
    area: false,
    clear: false,
    markers: false,
    help: false,
    list: false,
    collapse: false,
    shortcuts: { pick: { key: "X", code: "KeyX", primary: true, alt: true, shift: false } },
  },
});

// No builtins at all: only third-party extensions are mounted.
agentAnnotations({ builtins: false });

// Explicit initial UI state (default: { collapsed: false, markersVisible: true }).
agentAnnotations({ initialState: { collapsed: true } });

未配置的内建内容继续启用; 禁用其工具栏条目, 和快捷键一起运行 扩展注册冲突验证。 用户界面首选项从未写入 任务文件.

快速启动( 5分钟)

  1. 安装 (单位:千美元)pnpm add -D @gchust/agent-annotations,添加 Vite 插件 还有CLI二进制.
  2. 注册扩展名 定义工具栏动作(参见 最小客户端扩展) (中文(简体) ).
  3. 运行 dev 服务器 ——工作室码头出现在页面上.
  4. 捕获: 选择一个元素 Ctrl+Alt+P,键入注释,保存。 这个 任务土地 .agent-annotations/tasks/active-task.json。 。 。 .
  5. 手拿开: 一个代码代理编辑源, 运行相关的工程 检查,然后用 agent-annotations complete <id> --verified --summary-file <path>。 。 。 .

手动运行时间和自定义运输

没有Vite, 直接将运行时间挂载到任意 TaskTransport数字 :

import {
  mountAgentAnnotations,
  type AgentAnnotationsMutationRequest,
  type AgentAnnotationsTask,
} from "@gchust/agent-annotations";

// Your transport owns the task storage; the runtime validates and redacts
// every read/mutate crossing this boundary.
declare const task: AgentAnnotationsTask;
declare const persistMutation: (
  request: AgentAnnotationsMutationRequest
) => Promise<AgentAnnotationsTask>;

const mounted = await mountAgentAnnotations({
  transport: {
    read: async () => task,
    mutate: persistMutation,
  },
});

每个突变都经过验证和校正 在运输前 这个 CLI 对任务文件具有权威性, 当运输共享时会移交 相同的运行时任务文件 .agent-annotations (视频和文件) ; 完全定制的远程运输必须带来自己的CLI等同 权力.

配置

agentAnnotations({
  builtins: { help: false },                       // toggle built-in actions
  initialState: { collapsed: true, markersVisible: true },
  screenshotEvidence: "auto",                      // "auto" | "manual" | "off"
  diagnostics: { console: true, network: true },   // both default true
});
  • builtins: 配置或禁用内置工具栏贡献.
  • initialState数字 : collapsed 财务报告和审定财务报表 markersVisible 默认值.
  • screenshotEvidence:背景证据捕获、手动编辑器捕获或 关闭.
  • diagnostics: 闸机控制台错误和网络故障捕获(网络) 仅储存原产地+路径,从不储存尸体/头部/头部.

最小客户端扩展

创建 src/annotation-extension.ts 仅使用公共扩展条目:

import { defineClientExtension } from "@gchust/agent-annotations/extension";

export default defineClientExtension({
  id: "example.copy",
  apiVersion: 1,
  toolbar: [{
    id: "copy-open",
    group: "handoff",
    label: "Copy open annotations",
    icon: () => null,
    kind: "action",
    execute: ({ studio }) => studio.commands.annotations.copyOpen(),
  }],
});

用 Vite 插件注册其绝对浏览器模块路径 :

import { fileURLToPath } from "node:url";
import agentAnnotations from "@gchust/agent-annotations/vite";
import { defineConfig } from "vite";

// Node >= 20: fileURLToPath(new URL(...)) works on every supported minor.
export default defineConfig({
  plugins: [agentAnnotations({
    clientExtensions: [fileURLToPath(new URL("./src/annotation-extension.ts", import.meta.url))],
  })],
});

没有浏览器运行时间的节点工具

Root 导出保留浏览器运行时间加核心 API, 但节点工具 (任务文件操作,验证,变异,编辑,格式化, 切换、 id 、 选择、 放置、 选择器、 快捷键) 可以导入 纯, 主机中性 @gchust/agent-annotations/core 代之以子路径. /core 永不导入 React, React DOM, Vite, 或节点内置, 因此它运行在一个 没有安装的消费者:

import {
  parseAgentAnnotationsTask,
  formatAgentAnnotationsTaskMarkdown,
  redactAgentAnnotationsTask,
} from "@gchust/agent-annotations/core";

国 际

CLI读取 active-task.json 从已解析的运行时间数据目录 (单位:千美元).agent-annotations ),它总是使用 agent-annotations.task.v1数字 :

agent-annotations --root <path> --dir <path> <command> [options]
agent-annotations list [--json]
agent-annotations complete <annotation-id> --verified --summary <text>
agent-annotations complete <annotation-id> --verified --summary-file <path>
agent-annotations reopen <annotation-id>
agent-annotations print [--json|--markdown]
agent-annotations validate-task [--json]
agent-annotations revision [--json]
agent-annotations wait --referenced-source-revision <sha256> [--timeout-ms <n>] [--json]
agent-annotations diagnostics [--json|--clear]
agent-annotations evidence [--json|--prune [--json]]

validate-task 严格验证持续的任务文件 解析并报告任务编号、修订、计划和有效状态;从未 声明浏览器或运行中的 dev 服务器. --json 指纹 在 stdout 上精确一个可解析的 JSON 值; 没有它 CLI 打印稳定 人可读取的文本; 有稳定退出代码的错误会转到 stderr 。 正在完成一个 不再存在的注解是一意孤行的成功报告 skipped· ; reopen 仍然严格.

wait --referenced-source-revision <sha256> 监视已知的引用文件 返回一个未知的未显示结果.

默认 Copy 动作发出代码代理交接,而不是数据堆放: 注释上下文加上源编辑、立即完成、项目检查和 任务验证指令。 每个完成命令使用 UTF-8 --summary-file 占位符,绝不将用户的评论复制成完成证据。 这个 循环是 :

# 1. the agent edits real source files (never active-task.json)
# 2. as soon as relevant source changed, summarize the implementation and complete
agent-annotations complete <annotation-id> --verified --summary-file <path>
# 3. run only the smallest relevant check; skip the full suite unless requested
# 4. confirm the completed task file itself is valid
agent-annotations validate-task --json

复制后的说明保留了工作列表, 即使运行时状态有变化 正在编辑中。 完成时缺失的注释是非致命的,而且 未经重审。 交接是可配置的,并且有严格的界限(handoff: { command, verificationCommands, includeCompleted } 在 Vite 插件和 mountAgentAnnotations());它只格式文本,从来不执行任何东西. 明确 verificationCommands 仍按要求运行 。 默认包括 仅打开注释并询问最小的相关检查, 而非完整的测试 套间.

工作空间根和运行时间数据目录分别解决. --root编号 :AGENT_ANNOTATIONS_ROOT 设置工作空间根; --dir编号 : AGENT_ANNOTATIONS_DIR 设置运行时数据目录(其已有) (意为). 没有明确的路径, CLI 会发现最近的祖先 .agent-annotations/session.json ,然后返回到 最近的祖先工作空间(包含 package.json 或者说 .git),然后是当前目录。 从单列波子目录中运行 revision 财务报告和审定财务报表 wait 扎根于会话的工作空间根.

diagnostics 打印边框编辑的浏览器诊断在 .agent-annotations (与 --clear 只清空诊断,包括: 隐私安全网络故障(运输、方法、状况和消毒) 来源+路径 URL — 从不查询、机构、信头或认证; evidence 列出任务引用的截图文件及其注释 id, 永不 在运行时证据目录外接触文件. revision 报告 任务修订, referencedSourceRevision (或 null页:1 文档。 等待命令返回已观察到的源修订并使用有边框 30第二次暂停.

本地化

所有内置用户可见文本(工具栏、工具提示、作曲、编辑、列表、, (a) 船舶的状态、理由、确认) en-US 财务报告和审定财务报表 zh-CN 消息 词典( e)src/client/messages.ts) (中文(简体) ). 运行时间解决字典 相对主机区( e)host.locale(),则 <html lang>:

import { defineClientExtension } from "@gchust/agent-annotations/extension";
import { mountAgentAnnotations, type TaskTransport } from "@gchust/agent-annotations";

declare const myTransport: TaskTransport;

const localeHost = defineClientExtension({
  id: "host",
  apiVersion: 1,
  host: {
    locale: () => "zh-CN",
    brandColor: () => "#1677ff",
    messages: { "Pick": "Select" }, // overrides the built-in key
  },
});

const mounted = await mountAgentAnnotations({
  transport: myTransport,
  extensions: [localeHost],
});

公众快照 messages 合并为 已建词典 · 登记信息 · 主机 messages,所以一个主机可以 覆盖任何内置密钥( e)host.messages (见上文)。 有了Vite插件, 通过 clientExtensions 换句话说.

host.theme() 选择 "light", (中文(简体) ), "dark",或 "system"; 可选 host.brandColor() 供应不透明 #RRGGBB 口音。 发音。 一个主机 subscribe() 通知重读两个值并返回 undefined 恢复 默认口音 .

本地端切换器重新启用:工作室从不重新挂载和打开 作曲/编辑草稿活下来了. 多目标说明显示 resolved/total 具有稳定原因键的unresolved, (中文(简体) ), identity mismatch, (中文(简体) ), identity unverifiable, (中文(简体) ), iframe unsupported在标记工具提示中 编辑器和列表;列表还显示路径、类型和证据计数 默认的 Open 过滤器已保存.

页面上下文默认是无查询的:只存储注释 URLs origin + pathname键存储 pathname + hash。东道主 租户或过滤身份可以返回明确、允许上市的企业 密钥从 pageContext(); 其编号 url, (中文(简体) ), routeKey,以及 title 覆盖是 限定和验证,而原始查询参数永远不会被接受. 无效 或抛出覆盖物回到保险的默认值,并产生有界限的 扩展诊断而不中断捕获.

运行时间诊断(主机和网络)

挂载时, 运行时间记录 console.error 输出和失败的网络 请求(拒绝和4xxx/5xx回复、XHR错误/错误/超时) 和4xxx/5xx 答复),对有界限、经修改的诊断,在以下情况下继续存在: .agent-annotations。两者都是默认启用的,并可以明确设置门:

agentAnnotations({ diagnostics: { network: false } }); // console only
agentAnnotations({ diagnostics: { console: false } }); // network only

网络条目是保密的: URL 缩小为 origin + pathname (绳子和碎片被丢掉,其中的任何秘密都永远无法达到) 诊断、请求/答复机构、信头或饼干 ,失败原因是一个固定的软件包自有标签(任意错误) 文本从未嵌入,因为它本身可能包含敏感的完整 URL 或 查询),并且软件包自己的端点被压制. 获取/ XHR 补丁为 仅在运行时间挂起时安装, 保留原始时间 返回/扔出/事件行为,并安全地删除身份 重复的热重装挂载( 它从不堆叠) .

扩展失败隔离

第三方捐款在运行时间边界上被隔离:一个错误 贡献会禁用它自己注册的表面(工具栏条目、快捷键、, 面板、主机集成、导出者、重置者或信件),绝不中断 内建抓取/列表流程。 这包括已登记的捐款和 运行时间回调; 任意副作用 a setup 已在外部生产 抛出之前的地表不能翻回.

  • setup 将扩展的注册捐款滚回 解析(工具栏、快捷键、面板、主机集成、出口商、, 编辑器和信件全部被删除)并不断上升 信任的内置失败速度快 .
  • isVisible 抛出隐藏的贡献, isEnabled 丢弃禁用 这, isPressed 抛出未受压的花被 icon 制作一个 安全回落,一个扔 panel 渲染显示可分解的错误面板, 和所有主机调用加 execute编号 :enrich编号 :export编号 :redact 失败被抓住了 已存在的相相语义.
  • dispose 抛出从未阻挡 剩下的清理,和结构 处置诊断仍然到达诊断边界.
  • 每一次失败记录一次 (extensionId, phase, contributionId) 进入有线、有线、有线、可移动相的诊断 extensionId编号 :contributionId编号 :phase 字段; 高频上游 错误永远无法淹没诊断.
  • getSnapshot() 返回被深冻结的深层克隆:扩展 无法改变任务、诊断、快捷键、导出者或信息,以及 扩展名的配置对象永远不会被冻结.

警卫

Vite API 默认绑定回放, 需要随机私有会话 ,并验证 Host + Origin/Referer。 设定 allowRemote: true 仅在一个 可信开发网. 运行时间数据存储于 .agent-annotations· ; 不要这样做。 客户端不收集窗体值, cookie, 授权信头、请求机构或反应机构.

一般编辑是最后的持久性边界:每个变异路径 (浏览器、CLI、Vite API和直接商店通话) prepareAgentAnnotationsTaskForPersistence() (Parse) · 一般性修改 · 解析)在原子写入之前,所以更新注释, setExtension 数据, 完成摘要,证据元数据不能继续保密.

在最后边界之前,内置运行时间也会修改所有授权 变异: redactAgentAnnotationsMutationRequest() 验证当前任务 并重新验证 在自定义前已编辑的有效载荷 TaskTransport 看见了 延长 编辑器运行在客户端上,在稳定的情况下定型 (extensionId, redactorId) 顺序; 一般编辑运行前后 并且一个错误的重排器 无法关闭自己的命名空间。 截图 PNG 字节从未被字符串编辑; 捕获消毒器和服务器侧 PNG 边界手柄截取隐私 .

经过严格响应解析后,验证的运输边界要求 已经成功 mutate 财务报告和审定财务报表 writeEvidence 为保留请求的任务而作的回复 识别和推进预期的修订; writeEvidence 还必须保留 目标注释。 违章行为 TaskTransportProtocolError· ; read 财务报告和审定财务报表 subscribe 仍然是任务替换路径.

自定义持久性运输必须调用 prepareAgentAnnotationsTaskForPersistence() 在写入数据库之前 存储或文件。 图书馆会编辑它代表的一切和一切 但它不能控制运输工具的内部作用: 编辑担保适用于来自运行时间的请求和书面数据 通过官方帮助者,而不是任意第三方写作.

接收扩展设置 { studio } 仅生 TaskTransport 从不接触扩展。 CLI的范围为: 已解析的运行时间数据目录,而不执行 shell 命令或 显示任意文件已读 .

释放核查

pnpm release:verify 建立和包装一次,记录候选路径, SHA-256,大小和显示,然后进行打字、单位测试、结构/文件, 巴林特、美洲热带木材组织、柏油丸审计、Node 20/24核心/CLI烟雾和已安装的烟雾 浏览器消费者反对 确切的焦油球。 候选元数据、消费者、, 和每步日志保持不变 artifacts/release-candidate 检查. pnpm test:e2e:repeat 安装消费者和焦油丸的再利用 第一通道浏览器运行,仅重置运行时间输出.

API 参考

见 API.md (英语) 用于公共根、维特、扩展、类型、测试和 浏览器-运输条目.

限制

  • 只开发:生产建筑不包括注入的运行时间和API.
  • React 19和Vite 6是被支持的首发同位素范围.
  • 支持同样来源的iframes和打开的阴影根; 关闭的阴影根 据报告,跨界框架尚未解决.
  • 截图证据是最佳结构证据,而不是像素完美 页面抓取.
  • 此α只使用 agent-annotations.task.v1;不读取或迁移 以前的主机特定计划,目录,终点,或抓取工具.

版本与发布记录

@gchust/agent-annotations 共发布 10 个版本,首次发布于 2026/08/24;过去 12 个月发布了 10 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.1.9latest2026/09/181 个月前
0.1.82026/09/032 个月前
0.1.72026/08/292 个月前
0.1.62026/08/262 个月前
0.1.52026/08/262 个月前
0.1.42026/08/252 个月前

关于 @gchust/agent-annotations 的常见问题

@gchust/agent-annotations 是什么?

在 React/Vite 应用程序中仅交给代码代理的开发者可视化说明

如何安装 @gchust/agent-annotations?

在项目目录运行 npm install @gchust/agent-annotations,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^19.0.0)、react-dom(^19.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 agent-annotations,可以用 npx agent-annotations 直接运行。

@gchust/agent-annotations 支持 TypeScript 吗?

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

@gchust/agent-annotations 支持 ESM 还是 CommonJS?

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

@gchust/agent-annotations 需要什么版本的 Node.js?

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

@gchust/agent-annotations 可以商用吗?

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

@gchust/agent-annotations 的下载量有多少?

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

@gchust/agent-annotations 还在维护吗?

最新版本 0.1.9 发布于 2026/09/18(1 个月前);至今共发布 10 个版本,其中过去 12 个月发布了 10 个;首次发布于 2026/08/24。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。