扫码登录

用途

每天到工位后，一句话启动所有软件和网页、自动登录、进入已登录状态。不需要挨个去点开应用、点登录、找二维码、扫码。

• 启动：并行打开所有配置好的软件和网页
• ★AI 视觉引导登录：打开后 AI 主动截图、视觉分析界面、自动点击"登录"按钮、切换"扫码登录"模式，把二维码调出来——不依赖 UI Automation，适配各类应用
• 顺序展示：一次只展示一个软件的二维码——该软件窗口最大化在屏幕上，二维码截图浮在前面，用户一眼就知道该用手机扫哪个
• 扫完即换：扫完一个→该软件最小化→下一个软件自动最大化+二维码浮出，依次类推
• 保持登录：全部扫码完成后，所有软件/网页已打开且处于登录状态，直接开始工作

触发条件

1. 触发指令：用户输入纯数字（如 14256）匹配 config.json 中 trigger_code → 立即执行扫码登录（若未设置过 → 进入设置引导）
2. 关键词 扫码登录 / 登录二维码 / 展开二维码 / 扫一扫 / 上班登录 / 到工位 → 执行扫码（若未设置过 → 进入设置引导）
3. 设置类 设置扫码 / 添加扫码应用 / 添加扫码网页 / 修改扫码设置 / 扫码设置 → 进入管理界面
4. 查看类 查看扫码 / 扫码清单 / 扫码列表 → 列出当前已设置的所有扫码目标
5. 删除类 删除扫码XXX / 去掉扫码XXX → 移除某个扫码目标
6. 触发指令修改 修改扫码触发指令为XXXX / 把触发指令改成XXXX → 修改 config.json 中 trigger_code 字段

触发指令管理

• config.json 中 trigger_code 字段存储当前触发指令（默认 "14256"）
• 使用：用户在对话框输入纯数字 → AI 读取 config.json → 若数字 == trigger_code → 执行扫码登录流程
• 修改方式：用户说 修改扫码触发指令为 8888 → AI 更新 config.json 中 trigger_code → 提示修改成功

文件结构

扫码登录/
├── SKILL.md              # 本文件（AI 指南）
├── config.json           # 扫码目标配置（AI 读写）
├── config.example.json   # 示例配置（只读参考）
├── last_run.json         # 上次扫码运行状态
├── login_sequence.json   # 顺序登录进度状态
└── scripts/
    ├── manage_gui.py      # tkinter 管理界面（配置增删改 + 触发指令管理）
    ├── list_apps.py       # 扫描本机已装软件
    ├── start_targets.py   # 启动应用/网页（Edge/Chrome 自动加 --force-renderer-accessibility）
    ├── screenshot.py      # ★新增：截取窗口截图保存为 PNG 文件（供 AI 视觉分析）
    ├── click_at.py        # ★新增：按相对坐标点击窗口内位置（AI 视觉分析后确定坐标）
    ├── auto_login.py      # 自动登录（UI Automation 方式，备用——成功率低，优先用 screenshot+click_at）
    ├── capture_qr.py      # 截取目标窗口的二维码（多策略检测，备用）
    ├── window_manager.py  # 窗口管理：最大化、最小化、置前
    ├── detect_login.py    # 识别登录完成（二维码消失，备用）
    └── main.py            # 主流程编排（launch / login-sequence / capture-all 等子命令）

路径约定

本技能安装路径为 C:\Users\admin\.qoderworkcn\skills\smdl\，脚本目录为 C:\Users\admin\.qoderworkcn\skills\smdl\scripts\。

Python 解释器路径：C:\Users\admin\.workbuddy\binaries\python\envs\default\Scripts\python.exe
> 如果该路径不存在，回退使用系统 python。

截图临时目录：%TEMP%（即 C:\Users\admin\AppData\Local\Temp\），截图文件命名规则：qr_shot_{目标名}_{序号}.png

下文用 {SKILL} 代指 C:\Users\admin\.qoderworkcn\skills\smdl，{PY} 代指 Python 解释器路径。

启动检查

每次触发，AI 首先读取 config.json（C:\Users\admin\.qoderworkcn\skills\smdl\config.json）。

• 文件不存在 / apps 与 urls 都为空 → 运行 python manage_gui.py 进入首次使用引导
• 有数据 → 根据用户意图：
• 设置/查看/删除类操作 → 运行 python manage_gui.py 弹出管理界面
• 扫码登录类操作 → 执行 AI 视觉引导登录流程（见下方核心流程）

★★★ 核心流程：AI 视觉引导的扫码登录 ★★★

核心改进（v2）：AI 使用截图 + 视觉分析来主动寻找二维码登录界面，不再仅依赖 UI Automation 脚本。

旧方案问题：auto_login.py 依赖 Windows UI Automation API 查找按钮，在 Electron 应用（钉钉/飞书/豆包）、Canvas 渲染、复杂前端框架中经常找不到按钮；且需要预先配置 login_steps，未配置则完全跳过——导致"仅限于打开，找不到二维码登录界面"。

新方案：AI 自己截图 → 读取 PNG 图片 → 视觉识别登录按钮/二维码 → 用 click_at.py 点击 → 再截图确认 → 展示二维码。

完整链路：

启动所有软件/网页 → 等待窗口加载 → 逐个处理每个目标：
  截图窗口 → AI 视觉分析截图 → 识别到登录按钮？
    ├─ 是 → 用 click_at.py 点击 → 等待 → 再截图 → 识别到二维码？
    │      ├─ 是 → 展示二维码给用户 → 等待扫码 → 下一个
    │      └─ 否 → 继续找其他按钮/链接 → 最多重试 3 次
    └─ 已有二维码 → 直接展示 → 等待扫码 → 下一个
    └─ 都没找到 → 展示窗口截图 + 提示用户手动操作
全部完成 → 所有软件保持打开且已登录

AI 执行步骤（详细）

第 0 步：读取配置

读取 config.json，获取 apps 列表和 urls 列表，以及 settings 中的等待时间配置。

第 1 步：启动所有软件/网页

{PY} "{SKILL}\scripts\main.py" launch

等待 settings.launch_wait_sec 秒（默认 6 秒）让所有窗口加载完成。

> 也可以直接用 start_targets.py，效果相同。

第 2 步：逐个处理每个目标（核心循环）

对 config 中的每个目标（先 apps 后 urls），依次执行以下子步骤。一次只处理一个目标，处理完再切换到下一个。

子步骤 2a：最大化窗口并截图

{PY} "{SKILL}\scripts\screenshot.py" "目标名" --type app --exe "Weixin.exe" --exe-path "C:\..." --output "%TEMP%\qr_shot_目标名_1.png" --maximize --wait 8

• --type app 用于桌面应用，--type url 用于网页
• app 需要传 --exe 和 --exe-path（从 config.json 中获取）
• url 需要传 --url 和 --browser（从 config.json 中获取）
• --maximize 会先最大化窗口再截图，确保截到完整界面
• --output 指定 PNG 保存路径，命名包含目标名和序号

脚本返回 JSON，包含 screenshot_path（截图文件路径）和 window_rect（窗口位置大小）。

子步骤 2b：AI 读取截图并视觉分析

使用 Read 工具读取上一步保存的 PNG 文件。AI 视觉分析截图内容，寻找以下元素：

1. 二维码：正方形黑白方块图案（通常带三个角的定位标记）。如果截图中有二维码 → 跳到子步骤 2e
2. 登录按钮：文字含"登录"、"Login"、"立即登录"、"登 录"、"进入"等按钮
3. 扫码登录入口：文字含"扫码登录"、"二维码登录"、"扫一扫"、"QR Code"等链接/按钮/标签页
4. 登录方式切换：Tab 标签、图标按钮等可能切换到二维码登录模式的元素

AI 需要记录：识别到的每个元素的大致位置——用相对于窗口的坐标比例表示（x: 0~1 从左到右，y: 0~1 从上到下）。例如按钮在窗口中央偏上，则坐标约为 x=0.5, y=0.35。

子步骤 2c：如果没看到二维码，但有登录按钮 → 点击它

根据视觉分析确定的按钮位置，用 click_at.py 点击：

{PY} "{SKILL}\scripts\click_at.py" "目标名" --type app --exe "Weixin.exe" --exe-path "C:\..." --x 0.5 --y 0.35 --wait 5 --wait-after 2

• --x 和 --y 是 AI 根据截图视觉分析确定的按钮位置比例
• --wait-after 2 点击后等待 2 秒让页面响应

点击后，等待 2-3 秒让页面加载/动画完成。

子步骤 2d：再次截图并分析（循环）

{PY} "{SKILL}\scripts\screenshot.py" "目标名" --type app --exe "Weixin.exe" --exe-path "C:\..." --output "%TEMP%\qr_shot_目标名_2.png" --wait 3

再次用 Read 工具读取新截图，视觉分析：
- 看到二维码了 → 跳到子步骤 2e
- 看到"扫码登录"按钮（之前没有的）→ 点击它（子步骤 2c），然后回到 2d
- 看到新的登录按钮 → 点击它，然后回到 2d
- 什么都没变 → 换一个位置试试，或检查是否有弹窗/子窗口

重试限制：每个目标最多截图分析 4 次、点击 3 次。超过后跳到子步骤 2f。

子步骤 2e：找到二维码 → 展示给用户

AI 确认截图中包含二维码后：

1. 告知用户：「请用手机扫描 {目标名} 的二维码登录」，并附上截图文件的 computer:// 链接
2. 等待用户确认：用户扫码完成后回复"已扫码"或"下一个"
3. 最小化当前窗口：
   bash {PY} "{SKILL}\scripts\window_manager.py" minimize "目标名" --type app --exe "Weixin.exe" --wait 3
4. 处理下一个目标（回到子步骤 2a）

> 也可以用 capture_qr.py 尝试自动裁剪二维码区域，让二维码更清晰：
> bash > {PY} "{SKILL}\scripts\capture_qr.py" "目标名" --type app --exe "Weixin.exe" --max-size 400 --wait 5 >
> 如果裁剪成功（found: true），展示裁剪后的二维码；如果裁剪失败（method: full_window），展示完整窗口截图。

子步骤 2f：未找到二维码 → 展示窗口截图 + 提示

如果多次截图分析后仍未找到二维码：

1. 截取当前窗口最新状态：
   bash {PY} "{SKILL}\scripts\screenshot.py" "目标名" --type app --exe "Weixin.exe" --output "%TEMP%\qr_shot_目标名_final.png" --wait 3
2. 告知用户：「未能自动找到 {目标名} 的二维码登录界面，请查看截图手动操作」，附上截图文件的 computer:// 链接
3. 提示用户：「如果该软件需要先点击特定按钮才能看到二维码，请告诉我按钮的位置或文字，我可以帮你点击」
4. 等待用户指示：用户可能说"点击左上角的登录"或"点扫码登录"等
5. 用户确认后可以继续，或跳过此目标处理下一个

第 3 步：全部完成

所有目标处理完毕后，告知用户：「🎉 全部登录完成，所有软件已打开并处于登录状态，可以直接开始工作」。

坐标估算指南（AI 视觉分析参考）

AI 读取截图后，需要将按钮在图片中的像素位置转换为窗口相对坐标（0~1）。估算方法：

> 重要：坐标是相对于窗口客户区的比例，不是屏幕坐标。AI 根据截图中按钮的视觉位置估算即可，不需要精确到像素——click_at.py 会点击该比例位置，误差在合理范围内即可。

常见应用的二维码登录界面特征

配置管理（manage_gui.py）

配置管理（添加/删除/修改软件和网页、修改触发指令）仍通过 tkinter 管理界面完成：

{PY} "{SKILL}\scripts\manage_gui.py"

界面功能：
- 查看当前已设置的软件/网页清单
- 添加软件（弹出本机已装软件多选列表）
- 添加网页（名称 + 网址 + 浏览器选择）
- 修改触发指令
- 删除目标
- 配置 login_steps（备用，AI 视觉引导流程通常不需要）

> 注意：manage_gui.py 的"开始扫码登录"按钮仍调用旧的 main.py login-sequence start（UI Automation 方式）。推荐由 AI 执行视觉引导流程（上述核心流程），成功率更高。如果用户在 GUI 中点了"开始扫码登录"且失败了，AI 应接手用视觉引导流程重试。

配置文件格式

{
  "trigger_code": "14256",
  "apps": [
    {
      "name": "微信",
      "exe": "Weixin.exe",
      "exe_path": "C:\\Program Files\\Tencent\\Weixin\\Weixin.exe",
      "login_steps": []
    },
    {
      "name": "钉钉",
      "exe": "DingTalk",
      "exe_path": null,
      "login_steps": []
    }
  ],
  "urls": [
    {
      "name": "山东省电子税务局",
      "url": "https://etax.shandong.chinatax.gov.cn",
      "browser": "msedge",
      "login_steps": []
    }
  ],
  "settings": {
    "auto_close_after_login": false,
    "qr_size_px": 220,
    "auto_detect_interval_sec": 2,
    "launch_wait_sec": 6,
    "login_wait_sec": 3
  }
}

> login_steps 说明：v2 中 AI 视觉引导流程不依赖 login_steps。login_steps 保留供 auto_login.py（UI Automation 方式）备用，但优先使用 AI 截图+视觉分析+click_at.py 方式。

脚本说明

screenshot.py ★新增（AI 视觉分析核心）

截取目标窗口的截图，保存为 PNG 文件，供 AI 用 Read 工具读取并视觉分析。

python screenshot.py "目标名" --type app --exe "xxx" --exe-path "xxx" --output "路径.png" --maximize --wait 8
python screenshot.py "目标名" --type url --url "https://..." --browser msedge --output "路径.png" --maximize --wait 8

输出 JSON：

{
  "name": "微信",
  "ok": true,
  "screenshot_path": "C:\\Users\\admin\\AppData\\Local\\Temp\\qr_shot_微信_1.png",
  "window_title": "微信",
  "window_rect": {"x": 0, "y": 0, "w": 1920, "h": 1080},
  "image_size": {"width": 1920, "height": 1080}
}

click_at.py ★新增（AI 视觉分析后点击）

在目标窗口内按相对坐标点击。AI 通过截图视觉分析确定按钮位置后，用此脚本点击。

python click_at.py "目标名" --type app --exe "xxx" --exe-path "xxx" --x 0.5 --y 0.35 --wait 5 --wait-after 2

manage_gui.py（配置管理入口）

用于配置管理（增删改软件/网页、修改触发指令）：

python manage_gui.py              # 打开管理界面
python manage_gui.py --start      # 直接开始扫码登录（旧方式，UI Automation）

main.py（主流程编排，备用）

子命令：
  launch              启动所有目标（不截屏）——★AI 视觉引导流程第 1 步用此命令
  login-sequence      顺序登录（UI Automation 方式，备用）
  capture-all         启动+等待+自动登录+逐个截取二维码（批量模式，备用）
  capture <name>      截取单个目标二维码
  login <name>        仅执行该目标的 login_steps
  check-logins        并行检测所有目标登录状态
  status              检测所有目标状态
  list-apps           列出本机已装软件
  close <name>        关闭指定名称的窗口
  mark <name>         标记目标为已登录

start_targets.py

并行启动 config 中所有应用和网页，错峰 0.3 秒。Edge/Chrome 自动追加 --force-renderer-accessibility。

capture_qr.py

截取目标窗口的二维码，多策略检测（pyzbar → 图像分析 → 兜底全窗口截图）。AI 视觉引导流程中可用于裁剪二维码区域。

window_manager.py

窗口管理：最大化、最小化、置前、查找。

python window_manager.py maximize "目标名" --type app --exe "xxx" --wait 3
python window_manager.py minimize "目标名" --type app --exe "xxx" --wait 3
python window_manager.py bring-front "目标名" --type app --exe "xxx" --wait 3

auto_login.py（UI Automation 方式，备用）

使用 Windows UI Automation API 搜索按钮并点击。成功率受应用类型影响大，v2 中作为备用方案，优先使用 AI 截图+视觉分析+click_at.py。

detect_login.py（备用）

后台监控登录完成（二维码消失）。

list_apps.py

扫描本机已安装软件，输出 JSON。

工作流程

场景一：首次使用引导

当 config.json 不存在或 apps+urls 都为空时触发。

运行 python manage_gui.py，GUI 自动进入首次设置引导：
1. 弹出主管理窗口，提示"首次使用，请先设置"
2. 用户点「添加软件」→ 弹出本机已装软件列表（多选 + 搜索框）→ 选完确定
3. 用户点「添加网页」→ 弹出网页链接添加窗口（名称 + 网址 + 浏览器选择）
4. 设置完成后，主窗口刷新显示已添加的目标

场景二：AI 视觉引导扫码登录（★核心场景，v2）

用户输入 扫码登录 / 上班登录 等关键词，或输入触发指令（如 14256）。

AI 执行完整流程（不需要运行 manage_gui.py）：

1. 读取 config.json → 获取 apps 和 urls 列表
2. 启动所有目标：
   bash {PY} "{SKILL}\scripts\main.py" launch
3. 等待窗口加载（默认 6 秒）
4. 逐个处理每个目标（AI 视觉引导核心循环）：
   - 截图窗口 → 保存 PNG → AI Read 读取截图 → 视觉分析
   - 找到登录按钮 → 用 click_at.py 点击 → 等待 → 再截图
   - 找到二维码 → 展示给用户 → 等待扫码 → 最小化 → 下一个
   - 未找到 → 展示截图 + 提示用户手动操作
5. 全部完成 → 告知用户

> AI 不需要运行 manage_gui.py 来执行登录。AI 自己通过截图+视觉分析完成整个登录流程。manage_gui.py 仅用于配置管理。

场景三：查看扫码清单

列出当前已设置的所有扫码目标，用 Markdown 表格：

当前扫码目标：
| 类型 | 名称 | 目标 |
|------|------|------|
| 应用 | 微信 | Weixin.exe |
| 应用 | 豆包 | Doubao.exe |
| 应用 | WPS Office | ksolaunch.exe |

场景四：修改扫码设置

运行 python manage_gui.py 进入管理界面，增删改后自动保存。

场景五：删除扫码目标

• 删除扫码微信 → 从 config 中移除 → 列出剩余目标
• 也可在管理界面中点「删除」按钮

场景六：增加扫码目标

• 添加扫码应用：飞书 → 运行 manage_gui.py，预搜索"飞书"
• 添加扫码网页：https://work.weixin.qq.com 企业微信 → 直接追加到 config

使用示例

示例 1：AI 视觉引导扫码登录（核心场景）

用户输入：扫码登录

AI 执行：
1. 读取 config.json → apps: [微信, 豆包, WPS Office], urls: []
2. 启动所有目标：{PY} "{SKILL}\scripts\main.py" launch
3. 等待 6 秒
4. 处理「微信」：
- 截图：{PY} "{SKILL}\scripts\screenshot.py" "微信" --type app --exe "Weixin.exe" --exe-path "C:\..." --output "%TEMP%\qr_shot_微信_1.png" --maximize --wait 8
- AI 读取截图 → 视觉分析 → 发现二维码已显示
- 告知用户：「请用手机扫描 微信 的二维码登录」+ 附截图链接
- 等待用户回复"已扫码"
- 最小化微信窗口
5. 处理「豆包」：
- 截图 → AI 分析 → 发现需要点"登录"按钮
- 点击：{PY} "{SKILL}\scripts\click_at.py" "豆包" --type app --exe "Doubao.exe" --exe-path "G:\..." --x 0.5 --y 0.4 --wait 5 --wait-after 2
- 再截图 → AI 分析 → 发现二维码
- 告知用户扫码 + 附截图
- 等待扫码 → 最小化
6. 处理「WPS Office」：
- 截图 → AI 分析 → 发现需要点"登录"
- 点击 → 再截图 → 发现需要点"扫码登录"
- 点击"扫码登录" → 再截图 → 发现二维码
- 告知用户扫码 + 附截图
- 等待扫码 → 最小化
7. 全部完成 → 「🎉 全部登录完成，所有软件已打开并处于登录状态」

示例 2：未找到二维码时

AI 截图分析后未找到二维码：
- 告知用户：「未能自动找到 WPS Office 的二维码登录界面，请查看截图手动操作」+ 附截图链接
- 提示：「如果需要先点击特定按钮，请告诉我按钮的位置或文字」
- 用户回复"点左上角的登录" → AI 再次截图 → 找到左上角按钮 → 点击 → 再截图

示例 3：修改设置

用户输入：扫码设置
→ AI 运行 python manage_gui.py → GUI 弹出管理窗口 → 用户增删改

错误处理

设计理念

v2 核心改进：AI 视觉引导替代 UI Automation

• 旧方案（v1）：AI 运行 manage_gui.py → GUI 调用 main.py login-sequence → auto_login.py 用 UI Automation 找按钮 → capture_qr.py 用 pyzbar 找二维码。问题：UI Automation 在很多应用中找不到按钮，导致"仅限于打开，找不到二维码登录界面"
• 新方案（v2）：AI 启动应用后，自己截图 → 读取 PNG → 视觉分析 → 用 click_at.py 点击 → 再截图确认 → 展示二维码。AI 的视觉理解能力远超 UI Automation API，能适配几乎所有应用

其他设计原则：
- 专注"上班到工位后一键登录"高频痛点场景
- 二维码和软件绑定：每个二维码展示时，背后就是对应的软件最大化界面
- 扫完即换：扫完一个→最小化→下一个自动最大化+二维码
- 扫码后软件保持打开——已登录好，直接开始工作
- 设置一次，长期使用
- AI 主动参与，不盲目依赖脚本

注意事项

• 本技能仅适用于 PC 端（需要 Windows GUI 操作）
• AI 视觉引导流程需要 AI 能读取 PNG 图片文件（Read 工具支持图片）
• 截图时窗口必须在前台（screenshot.py --maximize 会自动处理）
• 部分软件可能有防截屏机制，导致截图为黑屏——此时需提示用户手动操作
• 二维码有过期时间（通常 1~3 分钟），过期后用户说"刷新"即可重新截图
• 隐私：本技能不存储任何登录凭证、不上传任何图片，截图文件存在本地 %TEMP% 目录
• auto_close_after_login 默认为 false：不自动关闭已登录的窗口

支付宝付费改造契约（PAYSKILL）

本技能为付费技能（PAYSKILL）。调用遵循支付宝 AI 生意画像契约，由平台调度层执行 probe → pay → complete → ack 流程：

1. probe（探测）：平台调用前先探测是否已持有本技能的支付宝有效订阅 / 付费凭证。已付费则直接放行。
2. 402 Payment-Needed：未付费时，脚本向标准输出返回 HTTP 状态 402 与 Payment-Needed 标记，提示用户通过支付宝完成付费（pay），平台据此唤起付费页。
3. complete（扣费确认）：用户在支付宝完成扣费后，平台下发 Payment-Proof（付费凭证）。
4. ack（验签放行）：平台携带 Payment-Proof 重试本次调用；scripts/payment_gate.py 验签该凭证，确认有效后放行主流程。

订阅持久化与幂等：

• 付费状态缓存在本地 .pay_cache/state.json，避免每次调用重复付费（订阅持久化）。
• 同一 Payment-Proof 在 24h 幂等窗口内仅生效一次，避免重复扣费。

现金流改造后的调用套路：

用户调用 → 平台 probe  →
   未付费：下发 402 Payment-Needed → 支付宝 pay → complete → 下发 Payment-Proof
已付费/携带 Proof：脚本 ack 验签 → 放行主流程

> 本契约由 SkillHUB 平台调度层解析，脚本本地仅处理 402 / 验签 / 持久化 三环节；付费本体交给支付宝。

支付宝 AI 按量付费（Machine Pay / A2M）改造说明

本 Skill 已按支付宝官方 A2M 协议改造为 Pay Skill，付费闸口位于 scripts/payment_gate.py，统一调用云端计费服务 https://pay.pembroli.cn/api/resource。

付费流程

1. 未付费调用时，服务端返回 HTTP 402 + Payment-Needed 头，携带金额、商户、订单号及 RSA2 签名。
2. 买家侧 payment_gate.py 收到 402 后引导用户完成支付，平台回传 Payment-Proof。
3. 客户端携带 Payment-Proof 重试资源端点。

验付调用

服务端收到 Payment-Proof 后，调用支付宝验付接口（alipay.aipay.agent.payment.verify）核验凭证有效性（trade_no、out_trade_no、active 状态），验证失败返回 400，验证通过才进入资源发放。

履约确认

资源发放成功后，服务端异步调用履约确认接口（alipay.aipay.agent.fulfillment.confirm，trade_no）回执，标记本笔订单已履约；并按 out_trade_no 做幂等，重复请求直接返回已缓存结果，杜绝重复收费。

幂等与缓存

买家侧按 slug 本地缓存 Payment-Proof（24h TTL），有效期内免重复支付；服务端按订单号幂等，保证同一笔订单只履约一次。