refactor: vision_sop精简改写 + 新增vision_api.template.py

memory/vision_sop.md

@@ -3,41 +3,21 @@
 ## ⚠️ 前置规则（必须遵守）
 
 1. **先枚举窗口**：调用 vision 前必须先用 `pygetwindow` 枚举窗口标题，确认目标窗口存在且已激活到前台。窗口不存在就不要截图。
-2. **🚫 禁止全屏截图**：必须先 `win32gui.GetWindowRect` 获取目标窗口坐标，再 `ImageGrab.grab(bbox=...)` 截窗口区域。能截局部（如标题栏）就不截整窗口，能截窗口就绝不全屏。全屏截图在任何场景下都不允许。
+2. **🚫 禁止全屏截图**：必须先利用ljqCtrl截取窗口区域。能截局部（如标题栏）就不截整窗口，能截窗口就绝不全屏。全屏截图在任何场景下都不允许。
 3. **能不用 vision 就不用**：如果窗口标题/本地 OCR（`ocr_utils.py`）能获取所需信息，就不要调用 vision API，省 token 且更可靠。Vision 是最后手段。
 
 ## 快速用法
 
-### 函数签名
-```python
-ask_vision(
-    image_input,
-    prompt: str | None = None,
-    timeout: int = 60,
-    max_pixels: int = 1_440_000,
-) -> str
-```
-
-### 示例
 ```python
 from vision_api import ask_vision
-result = ask_vision("image.png", prompt="描述图片内容")  # 路径或PIL Image均可
+result = ask_vision(image, prompt="描述图片内容", backend="claude", timeout=60, max_pixels=1_440_000)
+# image: 文件路径(str/Path) 或 PIL Image
+# backend: 'claude'(默认) | 'openai' | 'modelscope'
+# 返回 str：成功为模型回复，失败为 'Error: ...'
 ```
-返回 `str`：成功为模型回复，失败为 `Error: ...`。
 
-## 核心参数
-- `image_input`: 文件路径(str/Path) 或 PIL Image 对象
-- `prompt`: 提示词（默认：详细描述这张图片的内容）
-- `max_pixels`: 最大像素数（默认1440000，超则自动缩放）
-- `timeout`: 超时秒数（默认60）
+## 如果没有 `vision_api.py`，初次构建vision能力
 
-## 故障排除
-| 问题 | 解决方案 |
-|------|--------|
-| 导入失败 | 可检查 `mykey.py` 文件是否存在（仅检查存在性，不读取内容） |
-| 超时 | 提高 timeout 或降低 max_pixels |
-| 格式错误 | 确保使用 PIL 支持的格式（PNG/JPG/GIF等） |
-
-## 关键风险与坑点 (L3 Caveats)
-- **无重试机制**: `vision_api.py` 内部未实现 API 错误重试（如 503、超时）。在自动化流程中使用时，**必须在上层代码手动实现重试逻辑**（建议指数退避），否则偶发网络波动会导致任务直接崩溃中断。
-- **API Config**: 失效时直接改 `vision_api.py` 中的 `cfg = mk.claude_configXXX`。
+1. 复制 `memory/vision_api.template.py` → `memory/vision_api.py`
+2. 只改头部"用户配置区"：去 `mykey.py` 里扫描变量名（⚠️ 只看名字，禁止输出 apikey 值），尝试找能用配置名填入 `CLAUDE_CONFIG_KEY` / `OPENAI_CONFIG_KEY`，`DEFAULT_BACKEND` 选后端，并测试
+3. 保底：没有可用 config 时去 `https://modelscope.cn/my/myaccesstoken` 申请 token 填入 `MODELSCOPE_API_KEY`