代理说明
在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分钟)
- 安装 (单位:千美元)
pnpm add -D @gchust/agent-annotations,添加 Vite 插件 还有CLI二进制. - 注册扩展名 定义工具栏动作(参见 最小客户端扩展) (中文(简体) ).
- 运行 dev 服务器 ——工作室码头出现在页面上.
- 捕获: 选择一个元素
Ctrl+Alt+P,键入注释,保存。 这个 任务土地.agent-annotations/tasks/active-task.json。 。 。 . - 手拿开: 一个代码代理编辑源, 运行相关的工程
检查,然后用
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;不读取或迁移 以前的主机特定计划,目录,终点,或抓取工具.