autowsgr 2.2.0__tar.gz → 2.2.1__tar.gz

autowsgr-2.2.1/.agents/skills/emulator-debug/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: emulator-debug
+description: 'Debug and fix emulator connection issues in AutoWSGR. Use when: ADB device not found, scrcpy connection timeout, ModuleNotFoundError for cv2/retry/adbutils, emulator serial mismatch, no first frame, screenshot timeout, emulator detection failure.'
+argument-hint: 'Describe the error message or connection symptom'
+---
+
+# Emulator Connection Debugging
+
+Diagnose and fix emulator connection problems in AutoWSGR's scrcpy-based device control pipeline.
+
+## Connection Pipeline Overview
+
+```
+usersettings.yaml (emulator.type / serial)
+  -> resolve_serial()          # autowsgr/emulator/detector.py
+  -> adb connect <serial>      # TCP devices only (port in serial)
+  -> adbutils.adb.device()     # autowsgr/emulator/controller/scrcpy.py
+  -> window_size()             # adbutils shell
+  -> deploy scrcpy-server.jar  # push to /data/local/tmp/
+  -> start scrcpy server       # app_process on device
+  -> connect video socket      # LOCAL_ABSTRACT 'scrcpy'
+  -> wait first frame (10s)    # H264 decode via av
+```
+
+## Diagnostic Procedure
+
+### Step 1: Confirm Emulator is Running
+
+```powershell
+Get-Process | Where-Object {
+  $_.ProcessName -match 'ld|dnplayer|bluestacks|mumu|nox|memu'
+} | Select-Object ProcessName, Id
+```
+
+Map process names to emulator types:
+
+| ProcessName pattern | Emulator type |
+|---|---|
+| `LdVBoxHeadless`, `dnplayer` | 雷电 |
+| `MuMuVMMHeadless`, `MuMuNx*` | MuMu |
+| `HD-Player`, `Bluestacks` | 蓝叠 |
+
+### Step 2: Verify ADB Connectivity
+
+Locate the ADB binary used by the project:
+
+```python
+uv run python -c "from adbutils._utils import adb_path; print(adb_path())"
+```
+
+Then check devices:
+
+```powershell
+& "<adb_path>" devices -l
+```
+
+If the device list is empty, find the listening port and connect manually:
+
+```powershell
+netstat -ano | Select-String "LISTENING" | Select-String "16384|16416|7555|5555|5554"
+& "<adb_path>" connect 127.0.0.1:<port>
+```
+
+### Step 3: Validate usersettings.yaml
+
+Key fields in `usersettings.yaml`:
+
+```yaml
+emulator:
+  type: MuMu        # Must match the actual running emulator
+  serial: null       # null = auto-detect; or explicit like 127.0.0.1:16384
+  path: null         # null = auto-detect from registry
+  process_name: null # null = auto-infer
+```
+
+**Supported `type` values**: 雷电, 蓝叠, MuMu, 云手机, 其他 (see `autowsgr/types.py`)
+
+## Common Errors and Fixes
+
+| Error | Cause | Fix |
+|---|---|---|
+| `device 'emulator-5554' not found` | Config `type` mismatches actual emulator (e.g., 雷电 config but MuMu running) | Change `emulator.type` in usersettings.yaml |
+| `device '127.0.0.1:16384' not found` | ADB server not connected to TCP device | Code auto-connects now; if still failing, manually `adb connect 127.0.0.1:16384` |
+| `ModuleNotFoundError: cv2` | opencv-python + opencv-python-headless conflict | `uv pip uninstall opencv-python` then `uv sync` (project uses headless) |
+| `ModuleNotFoundError: retry` | `retry2` not installed (provides `retry` module) | `uv sync` (retry2 is a transitive dep of adbutils) |
+| `scrcpy video stream no first frame` | JAR not pushed, device too slow, or port conflict | Check `autowsgr/data/bin/scrcpy-server.jar` exists; increase screenshot_timeout |
+| `未发现已连接的 ADB 设备` | No emulator process running or ADB server down | Start emulator; run `adb start-server` |
+| `EmulatorConnectionError` after 3 retries | Persistent ADB issue | Kill all adb processes, restart emulator, then retry |
+
+## Serial Auto-Detection Logic
+
+`resolve_serial()` in `autowsgr/emulator/detector.py` follows this priority:
+
+1. `config.serial` explicitly set -> use directly
+2. Only 1 ADB device online -> auto-select
+3. Multiple devices, but `config.type` matches exactly 1 -> auto-select
+4. Multiple ambiguous devices -> interactive prompt (TTY only)
+5. No devices -> raise `EmulatorConnectionError`
+
+Serial-to-type matching patterns:
+
+| Pattern | Type |
+|---|---|
+| `emulator-\d+` | 雷电 |
+| `127.0.0.1:1638x-16xxx` | MuMu 12 |
+| `127.0.0.1:620xx` | MuMu (old) |
+| `127.0.0.1:555x-59xx` | 蓝叠 |
+
+## Key Source Files
+
+| File | Role |
+|---|---|
+| `autowsgr/emulator/controller/scrcpy.py` | ScrcpyController: connect, screenshot, deploy |
+| `autowsgr/emulator/detector.py` | detect_emulators, resolve_serial, identify_emulator_type |
+| `autowsgr/infra/config.py` | EmulatorConfig model, YAML loading |
+| `autowsgr/types.py` | EmulatorType enum |
+| `autowsgr/scheduler/launcher.py` | Launcher.connect() entry point |
+| `autowsgr/data/bin/scrcpy-server.jar` | Bundled scrcpy server (v2.7) |

autowsgr-2.2.1/.agents/skills/generic-issue-log-analysis/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: generic-issue-log-analysis
+description: 分析当前仓库或用户明确指定的公开 GitHub issue（完整 URL 或 `#1234`）。优先读取 issue 正文和评论，按需下载日志包、截图、配置导出和崩溃转储，建立时间线后结合仓库代码、文档和必要的上游依赖判断根因，并给出修复建议或下一步排查建议。
+---
+
+# Generic Issue Log Analysis
+
+## Scope
+
+- 默认把 `#1234` 视为当前仓库 issue。
+- 如果用户给了完整 issue URL，则以该 URL 为准。
+- 只分析可以直接访问的公开 issue、评论、截图和附件。
+- 如果缺少日志、现场图、配置导出或崩溃信息，要先明确说明证据不足，再基于现有材料给出初步判断。
+- 如果问题依赖私有环境、外部服务或用户本地状态，而仓库内证据不足，要明确列出还缺哪些材料。
+
+## AutoWSGR Repository Hints
+
+- 任务 API 入口优先看 `autowsgr/server/routes/task.py`，请求模型看 `autowsgr/server/schemas.py`。
+- 常规战与活动战执行链路优先看 `autowsgr/ops/normal_fight.py` 与 `autowsgr/ops/event_fight.py`。
+- 作战计划解析看 `autowsgr/combat/plan.py`，重点字段：`plan_id`、`fleet_id`、`fleet`。
+- 编队切换与按舰船名换船优先看 `autowsgr/ui/battle/fleet_change/` 与 `autowsgr/ui/choose_ship_page.py`。
+- 日志关键词可优先检索：`[Task]`、`[OPS]`、`[UI]`、`[Combat]`、`[识别]`。
+- 涉及“只切舰队号不换船”的问题时，先核对路由层是否把请求里的 `plan.fleet` 覆盖透传到执行器。
+
+## Workflow
+
+1. 规范化输入。
+
+   - `#1234` 视为当前仓库 issue。
+   - 完整 issue URL 以 URL 为准。
+   - 如果用户给的是模糊描述，先在 issue 文本里定位编号、链接或关键上下文。
+
+2. 获取 issue 内容。
+
+   - 读取正文和评论。
+   - 提取这些信息：版本、分支、平台、环境、任务或入口、预期行为、实际行为、复现步骤、维护者评论、附件链接。
+   - 如果维护者、机器人或其他评论已经给出结论，不要直接照抄；仍要用日志、代码和文档自行验证。
+
+3. 提取附件和现场证据。
+
+   - 优先关注日志包、截图、配置导出、崩溃转储、诊断报告和资源导出。
+   - 不要假定附件命名固定；除了项目约定命名，也要留意 `log`、`report`、`debug`、`crash`、`dump`、`config`、`trace`、`screenshot` 等常见关键词。
+   - 如果同一个 issue 有多份日志，先看最新一次复现；如果 issue 在对比不同版本、不同环境或不同控制器，再补看旧样本。
+
+4. 下载并解压附件。
+
+   - 二进制附件不要只靠网页抓取工具直接分析，应先下载到工作区临时目录，例如 `.cache/issue-logs/issue-<number>/`。
+   - 解压后先列目录，不要假定内部结构固定。
+   - 只读取和结论直接相关的文件，不要把整份大日志、整份配置或整个转储内容直接塞进回复。
+
+5. 建立时间线。
+
+   - 先从 issue 文本确定“用户认为出问题的时刻”和复现条件。
+   - 再把界面日志、服务日志、运行时日志、截图、配置快照和崩溃信息串成一条时间线。
+   - 优先锁定这次复现对应的 `task_id`、`session_id`、请求 ID、时间戳或其他稳定标识，再追踪细节。
+
+6. 回溯到代码和文档。
+
+   - 先看本仓库文档、配置定义和实现代码。
+   - 如果问题明显落在上游依赖、共享组件、绑定层或外部工具，再按需查看相关仓库或文档。
+   - 只看真正相关的模块，不要为了“完整”而把整个依赖栈都扫一遍。
+
+7. 区分 issue 当时环境和当前分支。
+
+   - 先以 issue 文本、附件、配置快照和缓存资源还原用户当时的实际环境。
+   - 再对照当前仓库代码，判断问题是当前仍存在，还是当时存在但现在可能已修复。
+   - 如果 issue 很旧，或日志流程与当前主线明显不一致，必要时按对应 tag、release 或历史提交复核旧逻辑。
+   - 输出给用户时，如果提到任务名、入口名、设置项、按钮名、错误提示或日志前缀，先在仓库里搜索翻译 / 本地化文件，不要直接把 `t("...")`、`i18n.t("...")`、`LocalizationHelper.GetString("...")`、`DynamicResource` key、枚举名或内部 ID 当成最终展示文本。
+
+8. 输出结论。
+
+   - 明确区分“已证实的根因”“高概率怀疑点”“证据不足的待确认项”。
+   - 给出能执行的下一步，例如修复方向、需要补充的材料、临时绕过方案、是否建议升级或回滚。
+
+## Artifact Map
+
+### Runtime / Core Logs
+
+- 模块归属：核心运行时、执行引擎、任务调度层。
+- 最适合看：
+  - 实际执行路径
+  - 识别、调用、动作失败
+  - 超时、重试、异常栈
+- 对任务行为和底层错误通常最权威。
+
+### UI / Frontend Logs
+
+- 模块归属：GUI、前端或用户交互层。
+- 最适合看：
+  - 用户到底点了什么
+  - 参数是否真的提交
+  - 用户可见报错和时间线入口
+
+### Service / Bridge / Agent Logs
+
+- 模块归属：后台服务、桥接层、agent、进程编排或 IPC 层。
+- 最适合看：
+  - 服务启动失败
+  - 子进程异常
+  - IPC、HTTP、RPC、FFI、资源加载或实例生命周期错误
+
+### Config Snapshots
+
+- 模块归属：配置快照、导出配置、任务参数、缓存配置。
+- 最适合看：
+  - 实际启用了哪些选项
+  - issue 文字里说的配置是否真和日志一致
+  - 当前行为是配置问题还是实现问题
+
+### Screenshots / On-Error Artifacts
+
+- 模块归属：出错现场图、保存的识别图、界面截图。
+- 最适合看：
+  - 当时停留画面
+  - 是否被弹窗、遮罩、加载态、分辨率、缩放、主题或权限影响
+  - 日志和用户描述冲突时，画面证据是否支持其中一方
+
+### Dumps / Crash Reports
+
+- 模块归属：崩溃现场、转储、调用栈、诊断报告。
+- 最适合看：
+  - 闪退、崩溃、进程退出
+  - 是否需要进一步用符号表、调试器或上游信息分析
+
+### Exported Resources / Cached Definitions
+
+- 模块归属：缓存资源、导出的任务定义、运行时生成的元数据。
+- 最适合看：
+  - issue 当时到底使用了哪一版资源或配置定义
+  - 当前主线和用户当时环境是否不一致
+
+## How To Filter Evidence
+
+1. 先从 issue 文本拿到这些锚点：
+
+   - 版本、分支、提交、发布日期
+   - 平台、设备、环境、控制方式
+   - 任务名、入口名、操作路径
+   - 用户说“出问题”的具体时间、阶段或界面
+
+2. 再从日志里找高价值信号：
+
+   - `Error`、`Warn`、`Fatal`
+   - `timeout`、`retry`
+   - `failed`、`exception`
+   - `task_id`、`session_id`、请求 ID
+   - 保存截图、导出现场、崩溃恢复、资源加载失败
+
+3. 先锁定“这一次复现”再下钻。
+
+   - 一个日志包里通常会混有很多历史运行。
+   - 如果 issue 文本说失败，但对应这次复现的任务最终成功，要明确写出“本次日志未复现用户描述的问题”。
+
+4. 区分表象和根因。
+
+   - 高层日志、UI 提示或机器人评论经常只是表象。
+   - 如果更靠近执行层的日志已经给出更直接的错误链路，应优先以那层为准，再回头解释用户看到的现象。
+
+5. 回答时只保留关键片段。
+
+   - 只摘足够支撑结论的少量证据。
+   - 不要把整份日志、整段 issue 讨论或整份配置直接倾倒进回复。
+
+## Common Patterns
+
+- 维护者评论已经给出判断，但日志和代码证据并不支持：
+  - 以可验证证据为准，把维护者评论当成补强而不是唯一依据。
+
+- issue 文本说“失败 / 卡死 / 误点”，但对应复现日志最终成功：
+  - 先明确“本次日志没有复现出用户描述的问题”。
+  - 再区分是用户补错了日志，还是代码里确实存在脆弱点但这次没触发。
+
+- 用户日志里的流程与当前主线代码明显不一致：
+  - 先确认 issue 当时的版本、tag 或 release。
+  - 不要用当前主线直接否定旧版本问题。
+
+- 配置快照和实际运行日志不一致：
+  - 不要立刻认定是用户表述错误。
+  - 先确认配置是否在复现后又被修改、是否有多个配置文件、是否存在缓存或导出时机差异。
+
+- 日志显示现场图、诊断包或转储已保存，但附件里没有对应文件：
+  - 把“缺失的关键证据”单独写出来。
+  - 不要假装已经验证过那部分现场。
+
+- 多层架构项目里某一层日志只暴露表象：
+  - 先在最接近问题根因的那层日志定性，再回到上层解释用户看到的现象。
+
+- 证据更接近“场景不支持”而不是“实现缺陷”：
+  - 必须给出代码、配置白名单、文档限制或运行时分支依据，而不是只给主观判断。
+
+## Correlating With Code
+
+- 先看 issue 模板、README、开发文档、排障文档。
+- 再看任务入口、配置定义、流水线或调度定义。
+- 然后看运行时、服务层、桥接层、前端或 GUI 实现。
+- 只有当证据已经明显指向上游依赖时，才继续看外部仓库、SDK、框架或绑定层。
+
+## Localized Copy
+
+- 总结任务、入口、设置项、按钮、错误提示、日志前缀等用户可见文案时，先在仓库里主动搜索翻译 / 本地化文件。
+- 优先搜索这些常见目录、文件名和关键词：
+  - `locale`、`locales`、`i18n`、`lang`、`langs`、`translations`、`messages`
+  - `zh-cn`、`zh_cn`、`zh-hans`、`zhHans`、`zh`
+  - `*.json`、`*.yaml`、`*.yml`、`*.toml`、`*.resx`、`*.xaml`、`*.ts`、`*.js`
+- 再从实际代码调用反查 key：
+  - `t("...")`、`i18n.t("...")`、`intl.formatMessage(...)`
+  - `LocalizationHelper.GetString("...")`、`GetString("...")`
+  - `DynamicResource SomeKey`、`StaticResource SomeKey`
+  - 其他项目自定义的资源读取函数
+- 查找顺序建议：
+  - 先从报错日志、配置字段、界面代码里提取疑似 key / id / 枚举名
+  - 再在本地化文件中找对应中文文案
+  - 如果同时存在多语言，优先使用简体中文；若没有简体中文，则退回 issue 正文更接近的语言或仓库主语言，并说明未找到中文文案
+- 如果配置或日志里带有用户自定义名称，输出时优先保留用户自定义名称；必要时再括号补默认任务 / 入口文案或原始 key。
+- 如果仓库里确实找不到翻译 / 本地化文件，要明确说明“未发现可用的翻译文件 / 本地化资源”，再退回原始 key、英文字符串或内部 ID。
+
+## Linking Code Evidence
+
+- 如果要指向具体代码行，不要写本地路径加行号，也不要写绝对路径。
+- 统一给出对应仓库的远端 GitHub `blob` 行号链接，用尖括号包裹。
+- 链接格式：
+  - `https://github.com/<owner>/<repo>/blob/<commit>/<path>#L14-L20`
+- `<owner>/<repo>` 应使用本次实际分析的代码仓库；如果引用的是上游依赖或外部仓库，就用那个仓库自己的链接。
+- `<commit>` 必须是本次分析实际依据的代码版本：
+  - 默认使用当前检出的 `HEAD`
+  - 如果为了复核旧 issue 切到了某个 tag / commit，就使用那个版本解析后的 SHA
+- 如果引用的是文档、配置样例或资源定义，也尽量给对应远端链接，而不是本地路径。
+
+## Output Format
+
+最终回答用这个结构：
+
+```markdown
+## Issue 概要
+
+- issue：`#1234`
+- 版本 / 分支 / 环境：
+- 任务 / 入口 / 相关设置：优先写翻译文件里的用户可见文案；必要时再补 key / id / 枚举名
+- 关键提示 / 报错文案：优先写翻译文件中的实际显示文本
+- 用户现象：
+
+## 附件概览
+
+- 实际可读文件：
+- 缺失或未上传的证据：
+
+## 关键证据
+
+<details><summary>点击此处展开</summary>
+
+- issue 正文 / 评论：
+- 运行时日志：
+- UI / 服务日志：
+- 配置快照：
+- 现场图 / 转储：
+- 代码依据：如需指向具体实现，直接附远端 GitHub 行号链接
+
+</details>
+
+## 根因判断
+
+- 直接结论：
+- 证据链：
+- 当前主线是否可能已修复：
+
+## 修复方案
+
+1. 代码 / 配置 / 资源层修复
+2. 需要补充的测试、日志或截图
+3. 如问题属于不支持场景，应如何限制入口或改进提示
+
+## 给用户的建议
+
+- 用户现在可以直接尝试的动作：
+- 是否建议升级 / 重下完整包 / 重置配置 / 更换环境：
+- 是否有临时绕过方案：
+
+## 给修复 AI 的建议（可复制）
+
+<details><summary>点击此处展开</summary>
+
+~~~text
+现象：
+[一句话描述用户可见的问题]
+
+关键证据：
+[粘贴原始日志、堆栈、监控截图中的关键文本]
+
+可能相关线索（待验证）：
+[根据日志/现象推测的可能方向，不保证准确，供参考]
+~~~
+
+</details>
+
+## 置信度
+
+- 高 / 中 / 低
+- 还缺什么证据
+```
+
+## Reminders
+
+- 不要只看一个日志文件下结论。
+- 不要把 issue 评论、机器人提示或维护者判断当成唯一证据。
+- 不要把当前分支代码直接当成 issue 当时的真实环境。
+- 日志和截图冲突时，优先解释冲突，再决定更可信的证据链。
+- 如果问题本身没有在当前日志中复现，要明确写“证据未复现”，不要硬凑结论。
+- 如果 issue 版本较旧，要明确区分“当时的根因”和“当前主线是否已修复”。
+- 如果回答里出现任务名、入口名、设置项、按钮名、提示文案，优先先搜索项目里的翻译 / 本地化文件，再使用实际用户可见文案；必要时才补原始 key / id。
+- 如果回答里引用了具体代码行，直接给远端 GitHub `blob` 行号链接，用尖括号包裹，不要给本地路径加行号。
+- 如果证据表明问题已在新版本修复，明确建议升级；如果怀疑安装包、资源文件或配置损坏，明确建议重建；如果判断为真实代码缺陷且暂无 workaround，明确建议等待修复。

autowsgr-2.2.1/.agents/skills/release-backend/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: release-backend
+description: 'Release AutoWSGR Python backend to PyPI and GitHub. USE WHEN: bumping backend version, publishing to PyPI, creating backend release, tagging backend build. Includes mandatory local CI check before push.'
+---
+
+# Release AutoWSGR Backend
+
+发布 AutoWSGR Python 后端包到 PyPI + 创建 GitHub Release 的完整流程。
+
+## 前置条件
+
+- Python 3.12+ 虚拟环境已激活
+- `pre-commit install` 已执行
+- 所有待发布改动已合并到 `main`
+
+## 发布步骤
+
+### 1. 更新版本号
+
+编辑 `autowsgr/__init__.py`：
+
+```python
+__version__ = 'x.y.z'
+```
+
+`pyproject.toml` 通过 `{attr = "autowsgr.__version__"}` 动态读取，无需手动编辑。
+
+版本号遵循语义化版本：
+- **patch** (x.y.Z): bug 修复、小调整
+- **minor** (x.Y.0): 新功能、新 API
+- **major** (X.0.0): 破坏性变更
+
+### 2. 本地跑 CI（必须！）
+
+**远端 CI 经常因环境差异失败，必须先在本地确认通过后再推送。**
+
+```bash
+# 跑全部 pre-commit 检查（等同 CI lint job）
+pre-commit run --all-files
+
+# 确认包能正常构建
+python -m build
+```
+
+常见本地 CI 失败原因及修复：
+
+| 检查项 | 失败原因 | 修复方式 |
+|--------|----------|----------|
+| `check-shebang-scripts-are-executable` | 有 shebang 的脚本未标记可执行 | `git add --chmod=+x <file>` |
+| `ruff-check` | 代码风格/lint 错误 | `ruff check --fix .` 自动修复；无法自动修复的需手动改 |
+| `ruff-format` | 格式不规范 | `ruff format .` |
+| `trailing-whitespace` | 行尾空格 | pre-commit 自动修复后 re-add |
+| `end-of-file-fixer` | 文件末尾缺换行 | pre-commit 自动修复后 re-add |
+| `codespell` | 拼写错误 | 修正拼写或加入 `docs/spelling_wordlist.txt` |
+
+#### ruff 常见错误处理策略
+
+- **E402** (import not at top): 把 `_log = get_logger(...)` 移到 import 之后
+- **UP042** (str+Enum): 改为继承 `StrEnum`
+- **RUF015** (list(...)[0]): 改用 `next(iter(...))`
+- **FURB110** (ternary if/else): 改用 `or` 运算符
+- **SIM401** (if/else → dict.get): 改用 `.get(key, default)`
+- **不适合修复的规则**: 已在 `pyproject.toml [tool.ruff.lint] ignore` 中配置忽略（如 N818, RUF022, RUF012）
+
+**如果 pre-commit 自动修了文件，需要重新 `git add` 再跑一遍（跑两遍是正常的）。**
+
+### 3. 提交并推送
+
+```bash
+git add -A
+git commit -m "release: vX.Y.Z"
+git push origin main
+```
+
+**注意**：backend 不需要手动打标签。`release.yml` workflow 会自动从 `__init__.py` 提取版本号并创建 `vX.Y.Z` 标签。
+
+### 4. CI 自动执行
+
+推送到 `main` 且 `autowsgr/__init__.py` 有变更时，两个 workflow 并行触发：
+
+**python-publish.yml**（PyPI 发布）：
+1. `python -m build` 构建 sdist + wheel
+2. `pypa/gh-action-pypi-publish` 上传到 PyPI
+
+**release.yml**（GitHub Release）：
+1. **lint job**: `pre-commit run --all-files` + `python -m build`（质量门禁）
+2. **release job**（依赖 lint 通过）：
+   - 从 `__init__.py` 提取版本号
+   - 创建 git tag `vX.Y.Z`
+   - 创建 GitHub Release（自动生成 release notes）
+
+### 5. 验证发布
+
+- [ ] [PyPI 包页面](https://pypi.org/project/autowsgr/) 版本已更新
+- [ ] GitHub Release 页面有新版本
+- [ ] `pip install autowsgr==X.Y.Z` 能正常安装
+
+## 关键文件
+
+| 文件 | 说明 |
+|------|------|
+| `autowsgr/__init__.py` | 版本号定义（唯一版本源） |
+| `pyproject.toml` | 包配置、依赖声明 |
+| `.github/workflows/python-publish.yml` | PyPI 发布 workflow |
+| `.github/workflows/release.yml` | GitHub Release workflow（含 lint 门禁） |
+| `.pre-commit-config.yaml` | 本地 + CI lint 规则 |
+
+## 回滚
+
+如果发布了有问题的版本：
+1. PyPI: 在 pypi.org 项目管理页面 yank 该版本（无法删除，只能 yank）
+2. GitHub Release: 删除对应 Release 和 tag
+3. 修复后发一个新的 patch 版本

autowsgr-2.2.1/.gitattributes

@@ -0,0 +1,7 @@
+# Force LF for all text files.
+* text=auto eol=lf
+
+# Binary files — do not touch.
+*.png binary
+*.PNG binary
+*.jpg binary

autowsgr-2.2.1/.github/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# 贡献到 AutoWSGR
+
+我们欢迎对 [AutoWSGR](https://github.com/OpenWSGR/AutoWSGR) 的贡献！在贡献之前，请阅读以下指南。
+
+技术规范（开发环境、代码风格、测试、约定式提交等）详见项目根目录的 [`AGENTS.md`](../AGENTS.md)。
+
+------
+
+## 开发设置 Development Setup
+
+1. 克隆仓库。
+
+    ```bash
+    git clone git@github.com:OpenWSGR/AutoWSGR.git
+    cd AutoWSGR
+    ```
+2. 设置开发环境。
+
+    ```bash
+    uv sync
+    pre-commit install
+    ```
+
+------
+
+## 合并请求指导 Pull Request Guidelines
+
+### 原则 Principles
+
+1. **小的变更 Small Changes**: 做出小的、增量的变更，这些变更易于审查。
+2. **清晰的提交信息 Clear Commit Messages**: 编写清晰、简洁的提交信息来解释变更。我们推荐使用 [Semantic Commit Messages](https://www.conventionalcommits.org/zh-hans/v1.0.0/) 格式。
+3. **PR 描述 PR Description**: 在合并请求中提供变更的清晰描述。
+4. **代码审查 Code Review**: 在创建合并请求之前审查自己的代码。在合并之前，获得至少一个其他团队成员的批准（不包括你自己）。
+5. **测试 Testing**: 确保在创建合并请求之前本地测试代码，并确保在合并之前 CI/CD 流水线中的测试通过。
+
+### 如何贡献 How to Contribute
+
+1. 为你的特性或错误修复创建一个新的分支。
+   1. 如果你不是项目管理者：从 GitHub 仓库 (<https://github.com/OpenWSGR/AutoWSGR>) 创建一个 Fork 仓库，随后克隆并创建自己的功能分支。
+
+        ```bash
+        git clone https://github.com/<yourname>/AutoWSGR
+        cd AutoWSGR
+        git checkout -b <my-feature-branch>
+        ```
+
+    2. 如果你是项目管理员：可以不用 Fork，转为在主仓库创建一个分支。
+
+        ```bash
+        git fetch --all
+        git checkout main
+        git checkout -b <my-feature-branch>
+        ```
+
+2. 做出你的变更并将它们提交到分支。提交前不要忘记运行 `pre-commit` 检查。
+
+3. 将你的变更推送到远程仓库并创建一个合并请求。
+
+    ```bash
+    git push -u origin <my-feature-branch>
+    ```
+
+4. 转到 GitHub 仓库 (<https://github.com/OpenWSGR/AutoWSGR>) 并创建一个新的合并请求。
+
+5. 将合并请求分配给至少一个团队成员进行审查。在获得至少一个批准之前，**不要合并** 请求！
+
+   在审查过程中，你可能需要根据反馈对代码进行更改。保持分支与 `main` 分支保持最新。
+
+    ```bash
+    git fetch --all
+    git rebase -i origin/main
+    ```
+
+6. 合并请求获得批准后，压缩并将其合并到 `main` 分支中。
+
+------
+
+## 测试 Testing
+
+在创建合并请求之前，请确保在本地测试你的变更。可以运行 [`examples`](../examples) 目录中的各种脚本进行测试。
+
+------
+
+## 文档 Documentation
+
+如果你对代码库进行了更改，请更新 [用户文档](https://docs-autowsgr.notion.site)。同样鼓励在代码中编写注释和文档字符串。
+
+------
+
+如果你有任何问题或需要帮助，请通过 qq 群 568500514 联系团队。