feat(template): 升级 desktop E2E 模板到本系列最佳实践

基于 disburse-payroll-icbc 实战经验沉淀，让所有未来新 skill 复制模板后直接
享受本系列全部改进：

- record_screencast.py.sample:
  · 字幕脚本改用 "step: N/X" 模式 + ASCII 关键词锚（避免编码问题）
  · 展示三元组 (keyword, text, duration) 用法（依赖 platform-kit subtitle.py）
  · 加 TEST_FILE_NAME / MUSIC_SUBDIR 切换常量
  · 文档说明绕开 SDK ask() / send_file 的最佳实践

- test_desktop_smoke.py.sample:
  · docstring 加"何时用此模板 / 何时改用 _with_attachment"指引
  · 标注已知 SDK 限制（ask() user_idx<0 / send_file NotImplementedError）

- test_desktop_smoke_with_attachment.py.sample（新增）:
  · 完整附件场景模板，import jiangchang_desktop_sdk.e2e_helpers 6 个 API
  · 7 步 step: N/7 模式，跟 record_screencast.py.sample 字幕脚本对齐
  · 占位符 SKILL_SLUG / PROMPT / EXPECTED_KEYWORDS_IN_REPLY

- README.md: 追加 3 节
  · 模板选择指南（纯问答 vs 附件场景）
  · 已知 SDK 坑（send_file / ask / 字幕关键词 / bring_to_front）
  · 录屏新能力（activate_window / monitor_index / 字幕三元组）

- conftest.py: 同步到支持新版 platform-kit src/ 布局的 SDK 路径推断

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

tests/desktop/README.md

@@ -32,3 +32,32 @@ pytest tests/desktop/test_desktop_smoke.py -v -s
 - **桌面 E2E**：仅在本目录用 **pytest** 维护，二者互补、互不替代。
 
 若仅需验证 **service 业务逻辑**、契约与 golden 回归，**不要**写 desktop E2E；desktop 只用于验证**宿主 UI、路由、`jiangchang://` 协议、真实用户交互链路**等与桌面宿主强相关的行为。
+
+## 模板选择指南
+
+| 场景 | 用哪个模板 |
+|---|---|
+| 纯问答 skill（不上传附件、不跑长流程） | `test_desktop_smoke.py.sample` |
+| 需要上传附件 / RPA 长流程 / Agent 多轮工具调用 | `test_desktop_smoke_with_attachment.py.sample` |
+
+录屏入口都用 `record_screencast.py.sample`，里面 `TEST_FILE_NAME` 常量切换测试文件。
+
+## 已知 SDK 坑（来自 disburse-payroll-icbc 实战）
+
+1. **`client.send_file()` 在 v2.0.17+ 抛 NotImplementedError**——附件场景必须用
+   `jiangchang_desktop_sdk.e2e_helpers.drop_file_into_composer`（DataTransfer 拖拽）。
+2. **`client.ask()` 内部 `user_msg_index<0` 死循环**——如果匠厂启动慢 / gateway 握手有
+   延迟，导致 15s 内没抓到 user 节点，ask() 会锁死后续 900s 等待。建议长流程 / 附件场景
+   绕开 ask()，用 `jiangchang_desktop_sdk.e2e_helpers` 里的 `send_prompt_via_composer`
+   + `wait_for_user_message` + `wait_for_agent_complete` 自己控时。
+3. **字幕关键词建议用 ASCII**——虽然 platform-kit 已修了 subprocess 编码乱码，
+   保险起见字幕脚本里关键词用 `step: 1/` 这种 ASCII 锚而非中文短语。
+4. **`client.bring_to_front()` 已升级**——v?? 起会 ctypes ShowWindow(SW_MAXIMIZE) +
+   SetForegroundWindow，能真正铺满桌面。dev 模式下也能用（不依赖 jiangchang:// 协议）。
+
+## 录屏新能力（platform-kit v??）
+
+- `run_screencast(..., activate_window=True)` 自动激活+最大化匠厂窗口
+- `run_screencast(..., monitor_index=1)` 多显示器场景显式录主屏
+- 字幕脚本支持三元组 `(keyword, text, duration)` 给个别字幕指定独立时长，
+  覆盖长等待场景中间没日志输出的"字幕真空"