附录

快捷键总表、CLI/MCP 速查、主题参数、常见问题

参考区：按需查阅。快捷键、命令、参数的口径与 README 门面同源。

A 快捷键总表

全局热键（任何界面生效）

快捷键	功能
`Alt+Shift+A`	区域截图
`Alt+Shift+W`	窗口截图
`Alt+Shift+F`	全屏截图
`Alt+Shift+T`	自动取字
`Alt+Shift+L`	长截图
`Alt+Shift+H`	打开主面板

热键冲突可在主面板「通用页」改键。

取景层内（截图过程中）

快捷键	功能
`Enter`	复制到剪贴板（有标注时合成成品）
`Ctrl+C`	同复制
`Ctrl+S`	保存到默认目录
`D`	贴图（选区原位贴出）
`L`	转入长截图模式
`Esc`	取消（先弃选区，再彻底退出；有标注时弹确认，可记住选择）
`Tab`	切换自动识别的窗口候选
右键	输出选项菜单（无选区时=退出）

标注工具单键

键	工具	键	工具
`V`	选择	`M`	马赛克/模糊
`A`	箭头	`T`	文字
`R`	矩形	`N`	序号
`O`	椭圆	`E`	橡皮擦
`P`	画笔	`C`	裁剪
`H`	荧光笔

标注编辑辅助

快捷键	功能
`Ctrl+Z` / `Ctrl+Y`	撤销 / 重做（20 步）
`Delete`	删除选中标注
方向键	微调选中标注（`Shift+方向键` = 10px）
`Shift`（拖箭头时）	锁定 45° 方向
`Alt`+点击（序号工具）	复用上一个序号不递增
双击文字	重新编辑文字内容

B CLI 速查

全部命令输出统一 JSON envelope：{ok, data, error, meta}，判断成功只看 ok 与退出码。

命令	功能
`once status [--json]`	实例/落盘/OCR/热键状态
`once capture window --json`	截前台窗口
`once capture fullscreen --json`	截全屏
`once capture region --json`	交互式框选（需 GUI；无 GUI 时用 `--x --y --w --h` 物理像素直采）
`once ocr last --json`	对最近截图取字（也可传图片路径）
`once annotate last --script s.json --out out.png`	按脚本标注
`once history --query "kind:window after:昨天"`	历史检索
`once doctor`	环境自检
`once mcp`	启动 stdio MCP Server

退出码（冻结契约）

码	含义	说明
`0`	成功
`1`	参数错误	envelope.error 里有逐条明细
`2`	捕获失败	锁屏/驱动/杀软拦截
`3`	OCR 失败	已自动重试 1 次
`4`	读写失败	文件/剪贴板
`5`	权限被拒	用户关闭了 Agent 总开关
`6`	黑名单命中	无「本次放行」，不要重试

标注脚本（ops JSON）示例

{
  "unit": "px",
  "operations": [
    { "type": "rect", "at": [520, 24], "size": [330, 40], "style": "outline" },
    { "type": "arrow", "from": [200, 100], "to": [535, 45] },
    { "type": "step_number", "at": [180, 90], "label": 1 },
    { "type": "text", "at": [620, 20], "text": "点击导出报表" },
    { "type": "mosaic", "at": [2200, 20], "size": [150, 50], "mode": "pixelate" }
  ]
}

坐标系：unit:"px" 物理像素；unit:"rel" 为 0–1 相对坐标（无精确像素时推荐）；
未显式指定的样式属性全部继承标注主题（见 D 节），显式传参优先；
支持的 type：arrow / rect / ellipse / text / step_number / highlight / pen / mosaic(pixelate|blur) / crop。

C MCP 工具速查

MCP Server 由 once mcp 启动（stdio），共 6 个工具：

工具	功能
`capture_screen`	截屏（窗口/全屏/区域）
`scroll_capture`	长截图（滚动采集）
`ocr_image`	对指定图片（或最近截图）取字
`annotate_image`	按标注脚本生成衍生图
`list_history`	检索历史（支持 kind:/after:/has:/ocr: 语法）
`doctor`	环境自检

D 标注主题参数表

以下全部参数在主面板「标注主题」页只读展示、在标注编辑器里即改即存；AI 的标注自动继承，未显式传参时按此默认值渲染。

组	参数	说明
通用	主题色、默认线宽	未单独记忆的工具回落主题色
每工具颜色	arrow / pen / marker / rect / ellipse / text / num	每个工具独立记忆
箭头	头型（终点/双向/起点/无）、线型（实线/虚线/点线）
形状	填充（描边/填充/描边+填充）、圆角、虚线、不透明度	矩形与椭圆共用
文字	字体、字号、行距、粗体/斜体/下划线/阴影、对齐、背景色、背景透明度、背景圆角、描边	描边自动取反色
序号	样式（实心/描边/纯数字）、直径、起始编号
马赛克	模式（马赛克/模糊）、强度
荧光笔	不透明度
整图输出	阴影（模糊半径/颜色）、边框（宽度/颜色）	衍生图整图特效

E 隐私与黑名单

权限总开关：关闭即拒绝全部 AI 调用（退出码 5）；
无感自动截图：允许 Agent 静默截图；关闭后仅影响弹窗行为，黑名单与审计不受影响；
App 黑名单：内置密码管理器、银行类应用，支持自定义条目；命中即拒（退出码 6），无「本次放行」。黑名单针对 Agent 自动截图与热键直采（你不在场的场景）；手动框选是本人在场的主动行为，不予拦截；
审计日志：记录每次 AI 调用的时间、动作、目标与结果，30 天自动清理，可一键清空；
删除保护：历史删除进系统回收站；衍生图永不覆盖原图。

F 常见问题与排障

截图整体发白、像曝光过度？ 系统开启了 HDR。HDR 下 Windows 以高亮度范围合成桌面，传统截图接口拿到的是亮度映射后的降维帧。解决：设置 → 系统 → 屏幕 → HDR → 关闭「使用 HDR」。

客户端没打开，Agent 能调用吗？ 能。CLI/MCP 与 GUI 共享同一内核，截图/取字/标注/历史检索均不依赖客户端运行；仅交互式框选与长截图需要 GUI。

热键按了没反应？ 多半是被其他软件占了（部分工具默认占用相同组合键）。主面板「通用页」给冲突的热键改键即可。另注意：后台驻留的同类截图软件可能注册了相同全局热键（如 F3），窗口内按键抢不过系统级全局热键，建议关闭或改键对方。

长截图拼不完整 / 丢段？ 慢速匀速滚动成功率最高；两次采样之间滚过一屏以上必丢段（物理边界）。滚到底部停一秒再点完成。

衍生图会覆盖原图吗？ 永远不会。标注/裁剪产物按 -ann 命名并记录 lineage，删除只进回收站。

一键接入后 Agent 没反应？ 重启该客户端让它重读 MCP 配置；同一家族的桌面端与 CLI 端配置互不相通，确认接的是你正在用的那个端；还不行去「诊断页」跑自检，看桥接管道一项。

Agent 调用被拒（退出码 5）？ 主面板 Agent 页的权限总开关被关了，打开即恢复。

怎么卸载？ 客户端：托盘退出后删除程序目录（图片在 图片\Onceglance，按需保留）；CLI：删除 ~/.onceglance 目录；MCP 配置：在 Agent 页对已接入客户端点「移除」。

G 版本说明

本教程对应 v0.1.1 功能基线，Windows 10 (19045+) / Windows 11；
「让 AI 替你写教程」（09 章）需要 v0.1.2+ 的 CLI/Skill；
更新日志见仓库 Releases 页。