# @gchust/agent-annotations 中文文档

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

版本：0\.1\.9
npm 元数据更新时间：2026-09-18T15:23:20.855Z
中文译文更新时间：2026-11-16T00:49:18.388Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：493 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- peer 依赖：vite ^6\.0\.0，react ^19\.0\.0，react-dom ^19\.0\.0
- 首次发布：2026-08-23T23:57:22.891Z
- 最新版本发布：2026-09-18T15:23:20.523Z
- 近 30 天下载量：21092（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

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

## 安装

```sh
npm install @gchust/agent-annotations
```

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

## README

# 代理说明

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

## 安装

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

```sh
pnpm add -D @gchust/agent-annotations
```

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

## 维特

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

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

```ts
// 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.  **注册扩展名** 定义工具栏动作(参见 [最小客户端扩展](https://npmcn.com/package/%40gchust/agent-annotations/#readme-minimal-client-extension)) (中文(简体) ).
3.  **运行 dev 服务器** ——工作室码头出现在页面上.
4.  **捕获**: 选择一个元素 `Ctrl+Alt+P`,键入注释,保存。 这个 任务土地 `.agent-annotations/tasks/active-task.json`。 。 。 .
5.  **手拿开**: 一个代码代理编辑源, 运行相关的工程 检查,然后用 `agent-annotations complete <id> --verified --summary-file <path>`。 。 。 .

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

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

```ts
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等同 权力.

## 配置

```ts
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` 仅使用公共扩展条目:

```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 插件注册其绝对浏览器模块路径 :

```ts
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, 或节点内置, 因此它运行在一个 没有安装的消费者:

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

## 国 际

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

```text
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` 占位符,绝不将用户的评论复制成完成证据。 这个 循环是 :

```text
# 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>`:

```ts
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`。两者都是默认启用的,并可以明确设置门:

```ts
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 (英语)](https://npmcn.com/package/%40gchust/agent-annotations/API.md) 用于公共根、维特、扩展、类型、测试和 浏览器-运输条目.

## 限制

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

## 常见问题

### @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 和提交记录判断。

