anycap-human-interaction

AnyCap 人机交互

开始前请通读整个文件。 跳过章节会导致工作流错误——每种媒体类型都有不同的功能和限制。

使用 AnyCap 标注工具收集结构化人工视觉反馈的工作流指南。本技能将教你何时以及如何通过视觉标注和屏幕录制，在工作流中引入人工参与。

如需 CLI 命令参考，请阅读 anycap-cli 技能。如需媒体生成工作流，请阅读 anycap-media-production 技能。

前置条件

必须安装并完成身份验证 AnyCap CLI。如需设置帮助，请阅读 anycap-cli 技能。

两种核心场景

AnyCap 标注适用于两种不同的审核工作流。请选择符合你需求的一种：

场景	最适用于	主要产物	亮点
URL / 网页审核	网页、本地开发服务器、实时 UI	带旁白的屏幕录制	浏览、标注并录制旁白——录制内容会捕捉所有操作
图像协作审核	生成的图像、屏幕截图、设计稿	合并反馈后的标注图像	多位审核者实时同时进行标注

两种场景都支持所有标注工具（Rect、Arrow、Point、Freehand）和文本标签。不同之处在于最终获得的内容以及审核的进行方式。

命令速查

# Blocking -- opens browser, waits for Done click, outputs result
anycap annotate <target> [-o output.png]

# Non-blocking -- starts background server, returns session info
anycap annotate <target> --no-wait [-o output.png]

# Poll for result after human confirms done
anycap annotate poll --session <session_id>

# Stop background server
anycap annotate stop --session <session_id>

# List all active sessions (useful for recovery after context loss)
anycap annotate list

<target> 会根据内容自动检测：图像文件、URL（http:// 或 https://）、视频文件或音频文件。

关键标志

标志	说明
--no-wait	非阻塞模式（推荐用于 Agent）
-o, --output	将标注后的图像保存到此路径
--port <port>	绑定到固定端口（默认：随机）
--bind <addr>	绑定地址（默认：127.0.0.1）

提示： 在不同会话中使用 --port 并保持端口值一致（例如 --port 8888）。浏览器会将每位用户的显示名称存储在 localStorage 中，其作用域由来源（主机 + 端口）决定。使用固定端口后，回访的协作者会被自动识别，无需再次输入姓名。

浏览器自动打开

阻塞和非阻塞模式都会自动尝试在默认浏览器中打开标注 URL。在无头环境（SSH、容器）中，CLI 会改为将 URL 打印到 stderr。不会引发错误。

向人工参与者介绍流程——指南

向人工参与者介绍标注会话时，应根据具体情况调整说明。需要传达的要点：

• 浏览器自动打开：在桌面环境中，页面会自动打开——请说明这一点（“审核页面应该已经打开了”）。在无头环境/SSH 中，请分享 URL 并告知对方如何访问。
• 务必提及 Done：告诉对方完成后点击 Done。反馈将通过此操作保存。
• URL 模式下的录制：强调录制（Rec 按钮），因为 URL 模式无法导出带标注的屏幕截图。录制内容是主要反馈产物。
• 多用户：如果有多位审核者参与，请说明支持实时协作，且每个人都可以独立保存。例外：URL/iframe 模式为单用户模式（录制内容是主要反馈产物，多人的光标会造成混乱）。
• 无头环境访问：使用 --bind 0.0.0.0 时，请分享包含实际主机 IP 的 URL。如果位于 SSH 后方，建议使用端口转发。
• 标注内容：简要介绍可用工具（Rect、Arrow、Point、Freehand），并说明每条标注都可以添加文本标签。

不要使用固定话术。请根据具体情况自然组织说明（刚刚生成/修改的内容、桌面还是无头环境、单人还是多人审核）。

无头 / 远程访问

在无头环境（SSH、容器、云 VM）中运行时，人无法直接访问 127.0.0.1。使用 --bind 和 --port 使标注服务器可访问：

# Bind to all interfaces on a fixed port
anycap annotate screenshot.png --no-wait --bind 0.0.0.0 --port 8888

随后，人可以通过以下方式访问标注 UI：

• 直接访问： http://<server-ip>:8888（如果端口已开放）
• SSH 端口转发： ssh -L 8888:localhost:8888 user@host，然后打开 http://localhost:8888
• 容器端口映射： docker run -p 8888:8888 ...，然后打开 http://localhost:8888
• 反向代理： 通过 nginx、Caddy 或任何带路径前缀的反向代理开放访问

在无头环境中，始终使用带固定数字的 --port，以便 URL 可预测且可转发。

反向代理兼容性

标注 UI 可在带任意路径前缀的反向代理后运行。所有资源、API 和 WebSocket URL 均相对于页面 URL 解析，因此以下配置开箱即用：

https://yourserver.com/tools/annotate/  ->  http://localhost:8888/

如果代理会传递查询参数（例如用于访问控制的 ?token=...），这些参数会自动保留在所有内部请求中。无需在标注服务器端进行额外配置。

何时使用标注

在以下情况下使用标注：

• 你生成了图像 / 视频，需要人指出要修改的地方
• 你构建或修改了网页，需要人进行视觉审查
• 你需要基于空间位置的反馈（“把这个移到这里”“这块不对”）
• 仅通过文本反馈无法明确位置或视觉细节
• 你希望人通过录制讲解来说明反馈

以下情况不要使用标注：

• 你只需要是 / 否的确认（直接在聊天中询问即可）
• 反馈纯粹是文本内容（例如“将标题文字改为 X”）

交互模式

所有标注工作流都遵循以下模式：

sequenceDiagram
    participant Agent
    participant CLI as AnyCap CLI
    participant Human

    Agent->>CLI: anycap annotate <target> --no-wait
    CLI-->>Agent: {session, url, session_file, poll_command, stop_command}
    Agent->>Human: Present URL with guidance
    Human->>Human: Annotate, record, click Done
    Human->>Agent: Confirms done
    Agent->>CLI: poll_command
    CLI-->>Agent: Annotations + recording
    Agent->>Agent: Process feedback
    Agent->>CLI: stop_command

“Done”按钮

人点击标注工具栏中的 Done，即可保存反馈。不同模式下的行为有所不同：

• 阻塞模式（未使用 --no-wait）：点击 Done 会结束会话。CLI 命令会立即返回结果。在协作模式（图像、视频、音频）中，其他已连接用户会看到“已提交反馈”覆盖层。
• 非阻塞模式（使用 --no-wait）：点击 Done 会保存反馈，但不会结束会话。在协作模式中，其他用户会看到提示通知，并可继续标注。之后每次点击 Done 都会覆盖已保存的结果。Agent 会轮询以获取最新保存状态。

对于 Agent： 务必告知人完成后点击 Done。在有多位审阅者的非阻塞模式中（仅限图像 / 视频 / 音频），每位审阅者都可以独立保存——轮询结果会反映最近一次保存的内容。

会话恢复

会话状态会持久化到工作目录中的 .anycap/annotate/<session_id>.json（在启动响应中作为 session_file 返回）。如果上下文重置后丢失了会话 ID 或命令：

# List all sessions with their status and recovery commands
anycap annotate list

list 输出中包含每个会话的 poll_command 和 stop_command，因此你无需手动读取会话文件即可恢复会话。

---

场景 1：URL / 网页审阅

当你构建或修改了网页、UI 或任何可通过浏览器访问的内容，并需要人类进行视觉审阅时使用。

URL 模式为单用户模式。 录制内容是主要的反馈产物（跨源 iframe 会阻止导出带标注的截图）。多位用户的光标和标注会让录制内容变得混乱。客户端名称标签和参与者指示器会隐藏。每次只能有一人审阅 URL 会话。

录制内容为何重要： 与图像模式不同，URL 模式无法导出带标注的截图（跨源 iframe 限制）。带旁白的屏幕录制是主要的反馈产物。人类在标注框架内浏览你的页面，在页面上绘制标注，并录制带旁白的浏览过程——你将同时获得视觉标记和一段记录他们所见所说内容的视频。

开始会话

# Local dev server
anycap annotate http://localhost:3000 --no-wait

# Live URL
anycap annotate https://staging.example.com --no-wait

收集并分析反馈

# Poll for result
anycap annotate poll --session <session_id>

# Check if recording exists
RECORDING=$(anycap annotate poll --session <session_id> | jq -r '.recording // empty')

# Analyze the recording with AI video understanding
if [ -n "$RECORDING" ]; then
  anycap actions video-read --file "$RECORDING" \
    --instruction "List all issues the user pointed out. For each issue, describe what they are looking at, what is wrong, and what they want changed. Include timestamps."
fi

# Also read text annotations
anycap annotate poll --session <session_id> \
  | jq -r '.annotations[] | "#\(.id) [\(.type)]: \(.label)"'

# Clean up
anycap annotate stop --session <session_id>

录制内容可能为空。 Rec 按钮使用浏览器的 getDisplayMedia API，需要用户授予屏幕共享权限。如果用户拒绝权限提示，或始终没有点击 Rec，轮询结果中将不包含 recording 字段。尝试读取视频前，务必检查该字段是否存在。无论如何，文本标注仍可用。

应用 URL 反馈——迭代审阅

URL 审阅反馈通常对应代码修改，而非图像生成。分析录制内容和标注后：

1. 根据视觉反馈，确定需要修改哪些文件
2. 修改代码
3. 停止之前的会话
4. 启动一个新的标注会话，让人类进行验证

每一轮修改都需要启动一个新会话，因为 URL 内容已发生变化：

# Round 1: Initial review
anycap annotate http://localhost:3000 --no-wait
# ... human reviews, you poll and analyze ...
anycap annotate stop --session <session_1>

# Apply code changes based on feedback
# ... edit files ...

# Round 2: Verification review
anycap annotate http://localhost:3000 --no-wait
# ... human confirms or gives more feedback ...
anycap annotate stop --session <session_2>

在消息中为每一轮标注版本，以便人类跟踪进度（“第 2 轮：我已处理你第一次审阅中提出的问题 #1 和 #3”）。

录制内容分析模式

录制内容是从浏览器标签页捕获的 .webm 视频，其中包含绘制标注的过程和语音旁白。使用 anycap actions video-read 进行分析：

# General feedback extraction
anycap actions video-read --file <recording_path> \
  --instruction "List all issues and desired changes the user described"

# UI-specific review
anycap actions video-read --file <recording_path> \
  --instruction "For each UI element the user points at, describe the current state and the desired change"

# Prioritized feedback
anycap actions video-read --file <recording_path> \
  --instruction "Categorize the user's feedback by priority (critical, important, nice-to-have)"

---

场景 2：图像协作审阅

当你生成了图像，并需要一位或多位人类标注希望修改的内容时使用。此场景特别适合实时多人协作——多位审阅者可以打开同一个 URL 并同时添加标注，实时看到彼此的光标和绘图。

注意： 图像、视频和音频模式支持多人协作。URL / iframe 模式仅支持单用户。

如需了解完整的图像到图像优化循环（生成 -> 标注 -> 编辑 -> 迭代），请阅读 anycap-media-production 技能。

开始会话

# Single reviewer
anycap annotate hero-banner.png --no-wait -o hero-banner-annotated.png

# Multi-user review -- bind to network so teammates can join
anycap annotate hero-banner.png --no-wait -o hero-banner-annotated.png \
  --bind 0.0.0.0 --port 8888

收集并使用反馈

# Poll for result
anycap annotate poll --session <session_id>

# Extract annotation labels for image-to-image prompt
anycap annotate poll --session <session_id> \
  | jq -r '[.annotations[] | select(.label != "") | "#\(.id): \(.label)"] | join(". ")'

# Apply changes via image-to-image
anycap image generate \
  --prompt "<annotations as prompt>. Keep all other elements unchanged." \
  --model <model-id> \
  --mode image-to-image \
  --param images=./hero-banner-annotated.png \
  -o hero-banner-v2.png

# Clean up
anycap annotate stop --session <session_id>

---

其他媒体类型

视频审阅

当你生成了视频，或需要人类审阅视频内容时使用。人类可以暂停视频并在任意帧上添加标注。带标注的图像输出是暂停帧的快照，所有标注都会合成在其上。

开始

anycap annotate output.mp4 --no-wait

告诉人类在关键时刻暂停视频，在画面上绘制标注，可选择录制带旁白的内容，并在完成后点击 Done。

收集并分析

# Poll for result
anycap annotate poll --session <session_id>

# The annotated_image is a snapshot of the paused frame with annotations
# Read the annotations for spatial feedback on that frame
anycap annotate poll --session <session_id> \
  | jq -r '.annotations[] | "#\(.id) [\(.type)]: \(.label)"'

# If recording exists, analyze it for time-specific feedback
RECORDING=$(anycap annotate poll --session <session_id> | jq -r '.recording // empty')
if [ -n "$RECORDING" ]; then
  anycap actions video-read --file "$RECORDING" \
    --instruction "What feedback did the user give about the video? For each issue, note the timestamp in the original video, what is wrong, and what they want changed."
fi

# Clean up
anycap annotate stop --session <session_id>

视频反馈通常会用于调整提示词后重新生成；如果模型支持，也可以针对特定帧进行编辑。

音频审阅

当你生成了音乐或音频，并需要人类提供反馈时使用。人类会看到一个音频播放器，下方有一个绘图画布。

开始

anycap annotate track.mp3 --no-wait

告诉人类播放音频，在画布上绘制标注以标记时间区间或片段，添加描述所需修改的标签，并在完成后点击 Done。

收集并分析

# Poll for result
anycap annotate poll --session <session_id>

# Read annotation labels -- these describe desired audio changes
anycap annotate poll --session <session_id> \
  | jq -r '.annotations[] | "#\(.id) [\(.type)]: \(.label)"'

# If recording exists, analyze the narrated feedback
RECORDING=$(anycap annotate poll --session <session_id> | jq -r '.recording // empty')
if [ -n "$RECORDING" ]; then
  anycap actions video-read --file "$RECORDING" \
    --instruction "What audio changes did the user request? Note any specific time ranges or sections they mentioned."
fi

# Clean up
anycap annotate stop --session <session_id>

音频反馈通常会通过调整提示词后重新生成来处理，而非进行空间编辑。

---

迭代审查循环

对于复杂任务，请反复迭代：

graph TD
    A[Agent produces work] --> B[Start annotation session]
    B --> C[Human reviews and annotates]
    C --> D[Agent collects feedback]
    D --> E[Agent applies changes]
    E --> F{More changes needed?}
    F -->|Yes| B
    F -->|No| G[Deliver final result]

迭代提示：

• 为输出添加版本号（v1、v2、v3），方便人工比较
• 在修改中引用之前的反馈（“已处理上次审查中的 #1：……”）
• 经过 2-3 轮后，总结所有已做的修改，确认没有遗漏

选择合适的场景

情况	场景	原因
构建或修改了网页	URL 审查（单用户）	录制会捕捉浏览、滚动和语音反馈
本地开发服务需要审查	URL 审查（单用户）	同上——使用 http://localhost:PORT
生成的图像需要编辑	图像审查	带注释的图像可直接用于图生图编辑
团队需要审查设计	图像审查（多用户）	所有人可以一起添加注释，所有反馈都集中在一处
与利益相关者进行设计评审	图像审查（多用户）	实时光标和注释让所有人保持步调一致
生成的视频需要反馈	视频审查	在关键时刻暂停，为特定帧添加注释
音乐/音频需要反馈	音频审查	在画布上添加注释，标记时间区间
需要创建或迭代图表	改用 anycap draw	交互式白板，支持 Mermaid 输入，Agent 可以推送更新
架构图需要人工参与	改用 anycap draw	支持实时同步的协作式 Excalidraw 编辑器