WorkBuddy截图助手

怎么用（两种方式，装好即可用）

1. 直接按 Alt+S（首选） —— 在 WorkBuddy 窗口里按一下就行。
   ⚠️ 前提是安装时真的把后台进程装好了：市场安装只解压文件、不执行任何脚本，
   所以「装完就能按」这件事由安装脚本负责（见下节「安装」）。若你只是把技能文件
   拷进来、没跑过安装脚本，按 Alt+S 会毫无反应 —— 这时走方式 2。

2. 对 AI 说一声（兜底，也能顺手补装）：说「截图」/「截个图」/「看一下屏幕」，
   甚至只说一句「Alt+S 没反应」—— 都会触发下面的「AI 执行守则」。
   AI 的标准动作（本技能写死的约定，AI 照做即可）：
   ① 只读探测（不改任何设置）：跑 python scripts/install.py --check，
   或看 %TEMP%\wb_snip_daemon.log 末尾有没有「已就绪」；
   ② 已就绪 → 直接跳 ④；未就绪 → 先向用户申请授权（一句话说清要做什么、
   有什么影响，见下节话术），征得同意才装 —— 用户说「好 / 可以 / 继续」即视为同意；
   ③ 同意后跑 python scripts/install.py —— 幂等：后台已在跑就打印
   DAEMON|already-running 秒退（1.0.5 起），没在跑就自动装好并启动后台进程
   （约 5 秒），跑完看 RESULT=PASS 再汇报；
   ④ 再跑 python scripts/run_snip.py 截这一次的图 —— 它自己会挑一个
   带 tkinter + Pillow 的解释器，用哪个 python 起它都行。
   ⚠️ 这一步只截图：不写注册表、不拉起后台进程（1.0.11 起）。
   装常驻只有一条路 —— 上面的 ③ install.py，也就是必须经过用户同意。
   想让它顺带装常驻，得显式加 --ensure-daemon（只在已获授权时用）。
   （别直接跑 python scripts/wb_snip.py snip：随手拿的那个 python
   可能缺依赖，表现就是「截完图不贴进对话框」，而现场一句线索都没有。）

AI 执行守则（申请 → 授权 → 安装；每个会话的 AI 都照此执行）

为什么有这一节：常驻后台进程必须被启动一次才有 Alt+S
（市场安装只是解压文件、不会执行任何脚本 —— 这是平台硬约束）。
本技能把这个「第一次」设计成 AI 代办 + 用户一键授权：
用户不需要懂 Python、不需要找文件夹、不需要会双击 .py —— 会说一句话就行。

🔥 2026-09-29 更新（1.0.12）：正常安装后应当「装完即就绪」，不该再让用户说这句话。
用户在新电脑上的实测反馈是「安装好后需要配置缺失的环境，还需要在对话框让 AI
操作一下，比较不方便」—— 拆开是两步多余动作：A. 装完得重启一次 WorkBuddy；
B. 重启后还得对 AI 说一句话。1.0.12 已把 A 从根上修掉（见下「宿主环境」），
并把 B 收缩成「保险动作」：
- 装机路径正确时（安装脚本跑完、RESULT=PASS）→ 后台进程已起、自启已注册，
用户直接按 Alt+S 就行，不需要跟 AI 说任何话；
- 本节流程保留，作为「拷贝式安装 / 装了没跑脚本 / 后台被人为退出 / 换机迁移」
这几种情况的自愈通道 —— 它仍然是唯一会写系统的地方，所以授权话术不能省。

触发时机（任一即触发，不用等用户开口问）：
- 用户要求截图 / 截屏 / 框选 / 取色 / 提取屏幕文字；
- 用户说「按 Alt+S 没反应」「截图坏了」「刚装的技能用不了」；
- 用户刚安装完本技能（首次对话提到它）。

执行流程：
1. 静默探测：python scripts/install.py --check（只读，不写任何东西、不装依赖）。
2. 已就绪 → 直接执行本次截图，不打扰用户。
3. 未就绪 → 申请授权。话术模板（照此说，别省略影响说明）：
> 「截图助手还没装好。我可以现在帮你装好：启动后台常驻进程 + 注册开机自启
> （会写一条注册表 Run 项；不需要管理员权限、不弹窗；任务管理器 → 启动里
> 随时可以关掉）。装完 Alt+S 立即生效、重启电脑也自动就绪。要继续吗？」
4. 用户同意 → 跑 python scripts/install.py → 看到 RESULT=PASS 后汇报：
「装好了，Alt+S 现在就能用，以后重启也自动就绪」。
用户拒绝 → 真的什么都不装：只跑 run_snip.py 完成这一次截图。
（单次截图不依赖常驻；run_snip.py 默认不写任何注册表、不起后台进程，
只有显式加 --ensure-daemon 才会装 —— 这个开关只能在已获授权时用。）
并补一句：「每次截图都可以直接叫我；想一劳永逸随时说一声，或双击
scripts/install.py」。
5. 汇报要具体：装好说装好；失败就贴出 --check 的缺项（例如缺 Pillow 的
安装命令）和日志路径 %TEMP%\wb_snip_daemon.log，不含糊、不谎报。
6. 🔥 AI 会话沙箱陷阱（2026-09-29 实测）：在AI 会话的沙箱里跑 install.py，
daemon 能正常起来、复核也 PASS，但命令一结束就被连带杀掉 —— 表现为
「刚装完说能用，过一会儿按 Alt+S 又没反应」（实测：直接 Popen 被杀、
breakaway 被拒、explorer/startfile 链路不执行）。install.py 已内置检测
（_in_kill_on_close_job），命中会打 ⚠ 提醒。AI 的正确姿势：
- 首选免沙箱执行：拉起 daemon 的那条命令申请在沙箱外运行（用户批准
一次即可），daemon 就能一直活；
- 沙箱外不可用时，如实告诉用户两条恢复路径：双击 start_daemon.bat
（一次性）或注销重新登录（Run 键自启，永久生效）；
- 别谎报「永久常驻已生效」—— 沙箱里 spawn 的 daemon 活不过会话，
这么说是骗人。开机自启注册成功 = 下次登录起永久生效，这个可以承诺。

宿主环境：为什么装完就能用（1.0.12 修掉的老问题）

现象（用户 2026-09-29 报的）：新电脑上装完技能，install.py 跑得好好的、
报告也全绿，可按 Alt+S 没反应；必须先重启 WorkBuddy、再对 AI 说一句话才行。

根因（查了宿主源码才确认，不是猜的）：
WorkBuddy 每次启动时会把环境变量 WORKBUDDY_EXTRA_PATHS 猜出来交给子进程，
而它只由托管目录拼成：

~/.workbuddy/binaries/node/versions/*  +  ~/.workbuddy/binaries/python/versions/*  +  cli-connector

也就是说 —— 宿主只认它自己的托管 Python，不认我们另外装的。
于是出现两种"装了也用不上"：

而"宿主的 PATH 是启动那一刻的快照"这一条，让问题看起来像"重启就好了"。

1.0.12 的两处修法（都在 install.py 里，不依赖任何管理员权限）：

1. 校正宿主的运行时开关（ensure_host_can_find_python()）——
   往宿主自己的配置文件 ~/.workbuddy/app/app-config.json 写 bundledRuntime。
   宿主启动时会读这个键，用 bundledRuntime.tools.python 决定把不把
   binaries/python/** 纳入 WORKBUDDY_EXTRA_PATHS。
   · 默认本来就是开的 → 正常机器零改动（只读一次，发现是开的就返回）；
   · 只有发现被显式关掉（用户或误操作关了「设置 → 软件配置 → 内置运行时」）才纠正；
   · 写前留一份 .wbsnip.bak 备份，只加/改这一个键，不碰用户任何其它设置；
   · 宿主对该文件的读缓存按 mtime 失效 → 写完立即生效，不用重启宿主。
2. 把解释器目录补进用户级 PATH（refresh_user_path()）——
   写 HKCU\Environment\Path（只影响当前用户、不弹 UAC、不动系统 PATH），
   让"以后新开"的进程也能直接跑 python。幂等，已有就不重复追加。
   ⚠️ 这一条单独并不够（宿主只认托管目录，见上），它是给其它工具链用的补充。

依然需要重启宿主的唯一场景：宿主是在我们动手之前启动的，它的进程环境已经定死。
上面第 1 条靠 mtime 立刻生效的前提是"宿主会重新读配置"；若你遇到装了仍不生效，
重启一次 WorkBuddy 即可确定生效，之后再不需要任何手动动作。

依赖问题（1.0.6 起：能自动的就不让用户动手）

先分清两个依赖的性质，处理方式完全不同：

• 缺 Pillow（最常见）：裸跑 install.py 会自动 pip install pillow（先国内镜像、
  失败退官方源，约 5~20 秒），装完实测 import PIL 复核。AI 不需要做任何额外动作。
• 整台机器都没有带 tkinter 的 Python：这是唯一 pip 救不了的情况。
  此时 install.py --check 会明确告诉你，并给出两条路：
  1. 自动装（需用户同意）：python scripts/install.py --install-python ——
  从 python.org 下载官方安装器并静默安装（约 30 MB / 1~2 分钟）。
  仅当前用户：不弹 UAC、不写系统目录、不改 PATH、不抢 .py 关联、不建快捷方式；
  装完落点在 %LOCALAPPDATA%\Programs\Python\Python3xx，install.py 能自动找到。
  2. 用户自己去 python.org 下 3.9+ 安装版（提醒别用 Microsoft Store 版，它常缺 tkinter）。
• ⚠️ --install-python 会在用户机器上装软件，属于重操作：
  必须先征得用户明确同意，并把上面那段影响说明讲清楚再执行。
  用户不同意时，不要装，改为把下载链接给他、让他自己装。
• 用户级安装（不弹 UAC）的代价：其它程序不会自动用上这个 Python（因为没改 PATH）。
  对本技能无影响 —— install.py 是按绝对路径找解释器的。
  2. 按快捷键（装好之后更快）：在 WorkBuddy 窗口里按 Alt+S —— 默认值，
  想换就改 scripts/config.txt 里的 hotkey。
  ⚠️ 它依赖后台常驻进程（上面 ① 跑过一次即有）；从没跑过 ① 就按 = 完全没反应。
  好消息是跑过一次就不用再操心：install.py 会注册开机自启，
  之后每次开机自动就绪（不想要：install.py --no-autostart）。

截完的图会贴进聊天输入框，但不会自动发送 —— 发不发、要不要再补一句话，由你决定。
只想存文件不想贴聊天框，就点工具栏的 ⬇；想退出后台进程按 Ctrl+Alt+Q。

适用平台

仅 Windows 10 / 11。 用到 tkinter、ctypes 的 Win32 API（ImageGrab、
WH_KEYBOARD_LL 键盘钩子、剪贴板）等 Windows 专有接口，macOS / Linux 上无法运行。

安装（跑一次就好；跑完直接能按 Alt+S，不需要再对 AI 说一句话）

> 1.0.12 起，正常安装 = 装完即就绪。 安装脚本会一条龙做完：
> 挑解释器 → 补 Pillow → 让宿主能发现这个 Python → 生成启动器 →
> 注册开机自启 → 把后台进程起起来并复核。看到 RESULT=PASS 就可以直接按 Alt+S。
> 若因为"宿主是在你安装之前就启动的"而没立刻生效，重启一次 WorkBuddy 即可彻底生效
> —— 之后再也不需要任何手动动作。

# 1) 环境自检：会自己找一个能用的 Python，把缺什么打出来（只读，不装任何东西）
python scripts/install.py --check

# 2) 安装（**推荐路径**）：自动挑解释器 → 自动补 Pillow → 校正宿主运行时开关
#    → 生成 start_daemon.bat → 注册开机自启 → **并把后台进程起起来**
python scripts/install.py

# 3) 只想补"宿主能看到本 Python"这一步（不装任何东西），给"装完不想重启"用
python scripts/install.py --refresh-host

# 4) 仅当上面提示「没有带 tkinter 的 Python」时才需要（会自动下载并静默安装，需你同意）
#    1.0.11 起：下载完会先验 python.org 的 Authenticode 数字签名，验不过一律中止、不执行
python scripts/install.py --install-python

> 先决条件：Windows 10/11 + Python 3.9 或更高（必须自带 tkinter） + Pillow。
> · Pillow 缺了会自动装（1.0.6 起），不用你操心。
> · 机器上完全没有带 tkinter 的 Python 时，install.py 会明确告诉你 ——
> 这时可以 python scripts/install.py --install-python 自动装一个（需你同意，
> 仅当前用户、不弹 UAC、不改 PATH），或自己到 python.org 下 3.9+ 安装版
> （别用 Microsoft Store 版，它常缺 tkinter）。
> · 1.0.12 起，装完的 Python 会被主动"登记"给宿主（见上节「宿主环境」），
> 所以不会再出现"装了却用不上、得重启宿主"的情况。

• install.py 是幂等的（1.0.5 起）：后台已在跑时，裸跑它只打印一行
  DAEMON|already-running 就秒退 —— 所以 AI 拿到用户同意后可以直接跑它，
  不需要先判断状态，也不会重复安装。
  ⚠️ 别指望 run_snip.py 顺手把常驻装上 —— 1.0.11 起它默认什么都不装
  （见上文 ④），所以「拒绝授权」是真的不写任何东西。

• 上面两条用哪个 python 跑都行：install.py 会先找一个能用的解释器；
  要是当前这个跑不了（例如系统自带 python 没装 tkinter），它会自动换一个、重跑自己，
  而不是甩一句看不懂的 ImportError。

• 第 2 条跑完就能直接按 Alt+S 了（1.0.4 起）—— 它会启动后台进程并复核真的在跑，
  不再像以前那样只生成一个启动器、还得用户自己去双击。
  复核失败时它会明确叫你手动双击 scripts/start_daemon.bat。
• 需要 Python 3.9+（自带 tkinter） 与 Pillow。
  · 缺 Pillow 会自动装（1.0.6 起，先国内镜像、失败退官方源，约 5~20 秒），装完会实测复核。
  · 缺 tkinter 装不了（它是解释器自带的，pip 无解）→ 用 --install-python 自动装一个带它的 Python。
• 不需要 pywin32：找聊天窗口和写剪贴板都有内建实现，装不装都能用
  （装了只是走"快路径"）。1.0.3 起如此 —— 此前缺它会导致「截完图不贴进对话框」。
• OCR 是可选功能：想用工具栏的「文」提取文字，需 pip install winsdk；
  不装不影响截图、标注与粘贴。
• install.py 会把找到的解释器绝对路径写进 start_daemon.bat（GBK 编码），
  你不用手改任何路径。
• 后台进程默认就会开机自动就绪（1.0.5 起）：install.py 会往
  HKCU\Software\Microsoft\Windows\CurrentVersion\Run 写一条 WorkBuddy-Screenshot，
  登录时自动把常驻进程拉起来 —— "以后一直能用"不再依赖谁记得手动启动。
  这不需要管理员权限，也不会弹 UAC。
  · 不想要：python scripts/install.py --no-autostart（会顺手清掉 1.0.4 时代遗留在
  「启动」文件夹里的旧副本，免得"关了却没关掉"）；
  · 或到「任务管理器 → 启动」里禁用 WorkBuddy-Screenshot。
  （为什么用 Run 键而不是「启动」文件夹：后者每次登录都要闪一下黑框；
  两者在任务管理器里一样看得见、一样能一键禁用。）

按 Alt+S 没反应？先看这三条

1. 后台进程没在跑 —— 这是最常见的原因。按 Alt+S 靠的是常驻进程里的键盘钩子，
   进程不跑，这个键根本没人接。对 AI 说一句「Alt+S 没反应」即可 —— AI 会按
   上面的「AI 执行守则」先征得你同意再自动装好（装好 + 启动 + 注册开机自启，
   一般 5 秒内完成）；愿意自己动手的话，跑一次 python scripts/install.py 效果相同。
   ⚠️ 别先去双击 scripts/start_daemon.bat —— 那个文件是 install.py 生成的，
   从没跑过 install.py 的机器上根本没有它（刚从市场装完的副本正是这种状态）。
2. 鼠标不在 WorkBuddy 窗口内、它也不是前台窗口 —— 这是设计如此（防冲突）。
   把 WorkBuddy 切到最前再按。
3. 想看现场日志：%TEMP%\wb_snip_daemon.log 末尾应有
   「已就绪：Alt+S 截图…」和 HOTKEY|probe|key=Alt+S|free=1 两行。
   没有「已就绪」= 进程没起来；free=0 = 这个键被别的程序占着（改 config.txt 换一个）。

用法

> 工具栏是纯图标，把鼠标停在任意图标上会在图标下面弹出一行功能提示
> （如"另存为…（自己选保存位置）"），不用猜哪个按钮是干什么的。
> 点 ⬇ 存完后会闪一条「已保存」再关闭，避免"点了好像没反应"的错觉。

贴进输入框 ≠ 发送：默认只把图放进输入框、不按回车，
发不发、要不要再补一句话，由你自己决定。
（想让它在贴完立刻发出去，把 config.txt 里的行为改回自动发送即可 —— 见脚本顶部 AUTO_PRESS_ENTER。）

配置（不用改代码）

改 scripts/config.txt：

hotkey = Alt+S          # 截图热键（鼠标在 WorkBuddy 窗口内、或它是前台时生效）
quit = Ctrl+Alt+Q            # 退出后台进程
# save_dir = %USERPROFILE%\Pictures\WorkBuddy截图   # 不写 = 问系统要**真实桌面**（也是「另存为」的默认打开目录）
save_dialog = on             # on=点保存弹「另存为」自己选目录（默认）；off=直接存到 save_dir
scope_process = WorkBuddy.exe
scope_mode = cursor          # cursor=鼠标在窗口内也算(默认) / foreground=只认前台 / any=全局

• 组合键写法：Alt+S / Win+Shift+S / Ctrl+F4，大小写与空格随意；
  主键支持 A-Z、0-9、F1-F24、Space/Enter/Esc/Tab/PrintScreen 等。
• 必须带修饰键：单键会把那个键整个独占（在 WorkBuddy 里就再也打不出这个字），
  所以程序会直接拒绝这种配置并退回默认值。
• 改完要重启后台进程才生效（Ctrl+Alt+Q 退出 → 双击启动器）。
• 优先级：命令行 --hotkey/--save-dir > 环境变量 WB_SNIP_HOTKEY 等 > config.txt > 内置默认。
• 排查"改了没生效"：看 %TEMP%\wb_snip_daemon.log 里的 热键来源：… 那一行。
• 排查"按了没反应"：日志里 HOTKEY|trigger|…|via=cursor 说明命中过（via= 是哪条判据）；
  完全没有这一行 = 钩子压根没收到键（按错了键 / 判据不命中 / 别的软件先吞了）。

为什么不跟别的软件抢快捷键

截图热键只在 WorkBuddy 窗口"够得着"时生效（默认：鼠标压在 WorkBuddy 窗口上，
或它就是前台窗口）：实现上用的是低级键盘钩子，不满足判据就原样放行。
所以哪怕把它设成别的软件也常用的组合键，也不会影响那些软件 ——
你在别处按同一个键，仍然是那个软件的功能。

自检与回归（开发期工具，不随交付包分发）

> ⚠️ 1.0.11 起，发布包里不再包含自测脚本（_run_all_tests.py / _selftest_*.py /
> _probe_*.py）。两个原因：① 交付包不该混入开发脚本；② 安全审查会对整包做静态
> 扫描，探针里的 exec(...) 片段会被判成「命令执行风险」。移除后包体也从 485 KB
> 降到 248 KB。所以下面这些命令只在含这些脚本的源码目录里才跑得起来。

python scripts/_run_all_tests.py          # 一键跑全部 17 项，汇总到 %TEMP%\wb_snip_regress_all.txt

• 大部分项不碰鼠标/屏幕（秒级），少数几项会短暂接管鼠标（端到端真热键、真存图）。
• _run_all_tests.py 会先探测后台进程：若 wb-snip 已在跑（1.0.5 起默认开机自启，
  基本永远在跑），需要"干净初始状态"的 5 项会标为 SKIP、不计失败，并提示
  「按 Ctrl+Alt+Q 退出后重跑」—— 想完整验证就照做。
• _selftest_paste_fallback.py 专门强制不走 pywin32，验证"没装 pywin32 也能把图
  贴进对话框" —— 这是 1.0.3 修掉那个坑的回归。
• 若 _selftest_scope_behavior.py 报 SKIPPED: STEP3a：说明 Alt+S 被别的程序
  抢走了（QQ / 微信 / 钉钉的默认截图键恰好也是它）。不判失败，但会点名是谁抢的。
• 若你的 Python 没带 tkinter，_run_all_tests.py 会先打印一条明确的报错，
  而不是让你去看一堆看不懂的 ImportError。可用 WB_SNIP_PYTHON=<python.exe> 指定解释器。

排查：按快捷键完全没反应？

第一件事：确认后台在跑。 截图靠一个常驻后台进程，它不在的话按什么键都不会有反应
—— 而且日志里也是一片空白（这正是最容易误判的地方：2026-09-18 有用户报「按 Alt+S 没反应」，
真因就是后台压根没起来，而不是键不对）。

• 看日志 %TEMP%\wb_snip_daemon.log 末尾有没有 wb-snip 已就绪：Alt+S 截图…
• 没有这个文件，或最后一行是很久以前 → 后台没在跑 → 双击 scripts/start_daemon.bat
• 有「已就绪」但仍没反应，看这两行：
• 热键来源：hotkey=Alt+S(配置文件 config.txt) → 确认实际生效的是不是你设的键
  （改了 config.txt 必须重启后台才生效：先 Ctrl+Alt+Q，再双击启动器）
• HOTKEY|probe|key=Alt+S|free=0 → 这个键已被别的程序注册。
  本工具照样能用（键盘钩子优先于系统热键），但在 WorkBuddy 之外按它会触发那个程序；
  嫌串台就改 config.txt 的 hotkey（例如换成 Ctrl+Shift+X）。
• 还不行就看作用域：默认只在「鼠标在 WorkBuddy 窗口内 或 WorkBuddy 是前台窗口」时触发。
  鼠标停在别的窗口上、WorkBuddy 又不在前面 → 我们是故意放行的（不跟别的软件抢键），
  这是设计如此。想改成全局生效：config.txt 里把 scope_mode 设为 any（会独占该键，慎用）。

排查：截完图没落进对话框？

程序每次都会打一行环境体检和粘贴结果，照着看就知道卡在哪：

• ENV|…|clipboard=ctypes|find_window=ctypes
  → 没装 pywin32，正在用内建实现。这是正常的，不影响功能。
• CLIPBOARD|1 + PASTED|1 → 图已进剪贴板、已贴进输入框，在等你按回车。
  （1.0.5 起点对号 ✔ 不会再有 SAVED| 行 —— 不落盘是设计如此，不是丢了。）
• SAVED|<路径> → 你点的是 ⬇「另存为」，图已存到你选的位置（不贴聊天框）。
• SEND_SKIP|reason=clipboard_failed → 剪贴板被别的程序占着（输入法 / 剪贴板管理器），重试也没成。
• SEND_SKIP|reason=no_target_window → 没找到 WorkBuddy 窗口：被切走了？最小化了？
• SEND_SKIP|reason=action_save → 你点的是 ⬇「另存为」，本来就不该贴进聊天框。
• 完全没有任何输出 → 用的 python 不对。改用 python scripts/run_snip.py 起它。

已知限制

• 仅 Windows（见上）。
• 需要用户有一个带 tkinter 的 Python。缺 Pillow 会自动装；若整台机器都没有带
  tkinter 的 Python（pip 装不了它），install.py 会明确告诉你该装什么，并可用
  --install-python 自动装一个（需你同意），而不是静默失败。
• 预览图/测试产物写到 %TEMP%\wb-snip-artifacts（可用 WB_SNIP_ARTIFACTS 改）。
• 马赛克笔头圆圈直径 = 一笔马赛克的宽度（当前 14px），因此看着较小；
  要更大的颗粒感可调 wb_snip.py 顶部 MOSAIC_BLOCK。

版权与许可

本作品为专有软件（并非开源）。版权所有 (C) 2026 西永 · 保留所有权利。

• 允许：在您本人拥有或控制的设备上，安装并运行本作品的未修改副本，供个人使用。
• 禁止：复制、传播、修改、再分发、二次上架、反向工程、换皮复刻
  （含改写为其它语言或框架后重新发布），以及任何商业用途。
• 源码内嵌唯一水印 WB-SNAP-西永-2026-4371966c22，用于证明著作权归属；
  移除或篡改该水印同样属于违约。
• 完整条款见包内 LICENSE.md 文件。本作品不适用 MIT / Apache-2.0 / BSD / GPL
  等任何开源许可协议。

如需商业授权或其它许可，请联系著作权人。