fuscan 0.1.1__tar.gz

fuscan-0.1.1/.copier-answers.yml

@@ -0,0 +1,20 @@
+# Changes here will be overwritten by Copier
+_commit: v0.4.2
+_src_path: https://github.com/gookeryoung/coopie
+author_email: gooker_young@qq.com
+author_name: gooker_young
+coverage_fail_under: 95
+description: 极速通用文件扫描器.
+initial_version: 0.1.0
+license: MIT
+max_python_version: '3.14'
+min_python_version: '3.8'
+package_name: fuscan
+project_name: fuscan
+project_type: gui
+use_cicd: true
+use_cli: true
+use_docker: false
+use_docs: true
+use_domestic_mirrors: true
+use_tox: true

fuscan-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & Typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Sync dependencies
+        run: uv sync --frozen --extra lint
+
+      - name: Ruff check
+        run: uv run ruff check src tests
+
+      - name: Ruff format check
+        run: uv run ruff format --check src tests
+
+      - name: Pyrefly check
+        run: uv run pyrefly check
+
+  test:
+    name: Test (Python 3.8 & 3.14)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --frozen --extra test --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run pytest -m "not slow" --cov=fuscan --cov-fail-under=95 --cov-report=term-missing

fuscan-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*.*.*']
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Build & Publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI (OIDC)
+        run: uv publish
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG_NAME: ${{ github.ref_name }}
+        run: |
+          gh release create "$TAG_NAME" \
+            --title "Release $TAG_NAME" \
+            --generate-notes \
+            dist/*

fuscan-0.1.1/.gitignore

@@ -0,0 +1,35 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# 测试与覆盖率
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+
+# 工具缓存
+.ruff_cache/
+.pyrefly_cache/
+.mypy_cache/
+.uv-cache/
+
+# IDE
+.idea/
+*_profile.html
+
+# 环境变量与凭证（勿提交）
+.env
+.env.*
+
+# Sphinx 文档构建输出
+docs/_build/
+.trae/refs

fuscan-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+# prek / pre-commit 配置
+# See https://pre-commit.com for more information
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff 版本 - 与 pyproject.toml 保持同步
+    rev: v0.15.8
+    hooks:
+      # 运行 linter
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      # 运行格式化
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: fix-byte-order-marker
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: end-of-file-fixer

fuscan-0.1.1/.python-version

@@ -0,0 +1 @@
+3.8

fuscan-0.1.1/.readthedocs.yaml

@@ -0,0 +1,23 @@
+# ReadTheDocs 配置
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+# 构建配置
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.8"
+
+# Python 依赖与构建命令
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+# Sphinx 构建
+sphinx:
+  configuration: docs/conf.py
+  builder: html
+  fail_on_warning: false

fuscan-0.1.1/.trae/.ignore

@@ -0,0 +1,15 @@
+# PYTHON
+.coverage
+.pytest_cache/
+.ruff_cache/
+.tox/
+.venv/
+__pycache__/
+
+# NODEJS
+node_modules/
+
+# IDE
+.idea
+.trae
+.vscode

fuscan-0.1.1/.trae/docs/iter-11-multi-rules.md

@@ -0,0 +1,56 @@
+# iter-11 多规则文件加载与排序
+
+## 本轮目标
+
+允许加载多个规则文件，GUI 以列表展示，支持上下排序调整，后面的规则覆盖前面的同名规则。
+
+## 改动文件清单
+
+### 核心逻辑
+
+- `src/fuscan/rules/merge.py`：新增 `merge_multiple_rulesets(*rulesets)`，按顺序链式合并多个规则集
+- `src/fuscan/rules/__init__.py`：导出 `merge_multiple_rulesets`
+- `src/fuscan/builtin/__init__.py`：`load_with_builtin` 参数从 `Optional[Path]` 改为 `Optional[Sequence[Path]]`，支持多文件顺序合并
+
+### CLI
+
+- `src/fuscan/cli.py`：
+  - `scan`/`tray` 子命令的 `-r/--rules` 改为 `action="append"`，支持重复指定
+  - 新增 `_load_ruleset_from_args(args)` 辅助函数，统一处理 `--no-builtin` + 多 `-r` 的加载逻辑
+
+### GUI
+
+- `src/fuscan/gui/main_window.py`：
+  - `_rules_path: Optional[Path]` → `_rules_paths: List[Path]`
+  - `_init_ui` 拆分为 `_build_top_controls` / `_build_main_splitter` / `_build_left_panel` 三个子方法（避免 PLR0915）
+  - 左侧面板新增 `QListWidget`（规则文件列表）+ 上移/下移/移除按钮
+  - `_on_load_rules` 改为追加模式（非替换），支持去重
+  - 新增 `_on_move_rule_up` / `_on_move_rule_down` / `_on_remove_rule` / `_refresh_rules_file_list` / `_build_rules_label` / `_reload_and_refresh`
+  - `_reload_ruleset` 适配列表路径：builtin 开启时 `load_with_builtin(self._rules_paths)`，关闭时 `merge_multiple_rulesets(*[load_ruleset(p) for p in self._rules_paths])`
+
+### 测试
+
+- `tests/test_merge.py`：新增 `TestMergeMultipleRulesets`（8 个测试：无参/单参/双参覆盖/三参链式/不相交规则/ignore并集/版本号/综合场景）
+- `tests/test_builtin.py`：所有 `load_with_builtin(path)` 调用改为 `load_with_builtin([path])`
+- `tests/test_cli.py`：新增 `test_parse_scan_multiple_rules`、`test_scan_multiple_user_rules_merged`、`test_scan_multiple_user_rules_order_matters`
+- `tests/test_gui.py`：新增 `TestMultiRulesList`（10 个测试：初始空列表/多文件加载/去重/上移/下移/边界noop/移除/全移除/顺序影响覆盖/标签展示）
+
+## 关键决策与依据
+
+1. **合并语义**：`merge_multiple_rulesets` 采用顺序链式合并，后者覆盖前者同名规则；ignore 列表取并集。复用已有 `merge_rulesets` 的逻辑，避免重复实现。
+2. **GUI 交互**：规则文件列表用 `QListWidget`（非 `QTreeWidget`），因为只需展示路径无需层级。上移=优先级降低，下移=优先级升高，与"后者覆盖前者"语义一致。
+3. **去重策略**：同一路径不重复加载，通过 `path in self._rules_paths` 检查，提示用户而非静默忽略。
+4. **错误回滚**：`_on_load_rules` 加载失败时移除刚追加的路径并重新加载，恢复到操作前状态。
+5. **`_init_ui` 拆分**：ruff PLR0915 限制 50 语句，拆分为三个 `_build_*` 方法，每个职责单一且可独立测试。
+
+## 验证结果
+
+- ruff check：全部通过
+- pytest：397 passed, 1 skipped
+- coverage：88.62%（门槛 80%）
+- `rules/merge.py` 覆盖率 100%
+- `builtin/__init__.py` 覆盖率 100%
+
+## 遗留事项
+
+- iter-06～10 已满 5 轮，按 dev-workflow 规则应归档至 skills 并清理 docs 目录，待后续处理。

fuscan-0.1.1/.trae/docs/iter-12-config-persistence.md

@@ -0,0 +1,67 @@
+# iter-12 配置文件持久化
+
+## 本轮目标
+
+实现配置文件持久化，存储在 `~/.fuscan/config.yaml` 中，包括窗口几何、
+历史扫描文件夹、加载规则文件列表、通用规则开关等。应用启动时自动恢复，
+关闭时自动保存。
+
+## 改动文件清单
+
+### 新增
+
+- `src/fuscan/config.py`：配置持久化模块
+  - `Config` dataclass：窗口几何、窗口状态、分割器大小、扫描路径历史、
+    规则文件路径列表、通用规则开关
+  - `load_config(path)`：从 YAML 加载配置，文件不存在或解析失败返回默认值
+  - `save_config(config, path)`：保存配置到 YAML，自动创建父目录
+  - `CONFIG_PATH`：默认路径 `~/.fuscan/config.yaml`
+  - `MAX_HISTORY`：历史记录上限 15 条
+- `tests/test_config.py`：配置模块单元测试（12 个测试）
+
+### 修改
+
+- `src/fuscan/gui/main_window.py`：
+  - 导入 `Config`、`load_config`、`save_config`、`MAX_HISTORY`、`QComboBox`
+  - `__init__` 中调用 `load_config()` 加载配置，新增 `_apply_config()` 恢复状态
+  - 顶部路径标签 `QLabel` 改为 `QComboBox`（`_path_combo`），支持历史下拉选择
+  - `_build_main_splitter` 存储分割器引用 `self._splitter`，用于保存/恢复大小
+  - 新增 `_apply_config()`：恢复窗口几何、最大化状态、分割器大小、通用规则开关、
+    规则文件列表（跳过不存在的文件）、扫描路径历史
+  - 新增 `_save_config()`：序列化当前窗口状态到 Config 并调用 `save_config`
+  - 新增 `_add_scan_path_history(path)`：去重、最近优先、限制数量
+  - 新增 `_on_path_selected(index)`：从下拉选择路径时设置 `_scan_root`
+  - `_on_select_path` 更新为调用 `_add_scan_path_history`
+  - `closeEvent` 新增 `_save_config()` 调用
+- `tests/test_gui.py`：
+  - 新增 `_isolate_config` autouse fixture，将配置读写重定向到 `tmp_path`，
+    避免测试污染用户主目录
+  - 新增 `TestConfigPersistence` 测试类（13 个测试）：规则路径恢复、
+    不存在路径跳过、通用开关恢复、扫描历史恢复、关闭保存、路径下拉选择、
+    去重、数量限制、窗口几何恢复、分割器比例恢复
+
+## 关键决策与依据
+
+1. **配置位置**：用户主目录 `~/.fuscan/config.yaml`，跨平台、多用户隔离
+2. **保存时机**：`closeEvent` 中自动保存，无需手动操作
+3. **路径标签→下拉框**：用 `QComboBox` 替换 `QLabel`，用户可从历史记录中
+   直接选择扫描路径，不必每次打开对话框浏览
+4. **信号隔离**：`_apply_config` 中用 `blockSignals` 阻止 checkbox 和 combo
+   的信号触发，避免在恢复状态时引发不必要的规则重载
+5. **不存在的规则文件**：恢复时跳过 `Path(p).exists() == False` 的路径，
+   避免因文件移动/删除导致启动失败
+6. **测试隔离**：autouse fixture 将 `load_config`/`save_config` 重定向到
+   `tmp_path/config.yaml`，确保测试不读写用户真实配置
+
+## 验证结果
+
+- ruff check：全部通过
+- pytest：421 passed, 1 skipped
+- coverage：88.66%（门槛 80%）
+- `config.py` 覆盖率 90%
+- `gui/main_window.py` 覆盖率 84%
+
+## 遗留事项
+
+- iter-06～10 已满 5 轮，按 dev-workflow 规则应归档至 skills 并清理 docs 目录。
+- tray 模式未集成配置持久化（tray 有自己的 CLI 参数，暂不需要）。

fuscan-0.1.1/.trae/docs/iter-13-antivirus-ui.md

@@ -0,0 +1,78 @@
+# iter-13：杀毒软件风格 UI 重构
+
+## 本轮目标
+
+将 GUI 扫描界面重构为杀毒软件风格，支持三种扫描模式（全盘扫描/选择盘符/选择文件夹），
+使扫描操作和结果列表更为醒目。
+
+## 改动文件清单
+
+| 文件 | 改动类型 | 说明 |
+|------|---------|------|
+| `src/fuscan/scanner/walker.py` | 修改 | 新增 `list_drives()` 跨平台盘符枚举 |
+| `src/fuscan/scanner/__init__.py` | 修改 | 导出 `list_drives` |
+| `src/fuscan/gui/worker.py` | 重写 | `ScanWorker` 参数从 `root: Path` 改为 `roots: List[Path]`，支持多根路径扫描与结果合并 |
+| `src/fuscan/config.py` | 修改 | 新增 `scan_mode` 与 `last_drive` 字段（注：`window_geometry`/`window_state`/`splitter_sizes` 的默认值由用户提交 `38fbc0a` 改为 `default_factory`） |
+| `src/fuscan/gui/main_window.py` | 重写 | 杀毒软件风格 UI：模式卡片 + 醒目扫描按钮 + 大进度条 + QSS 样式 |
+| `src/fuscan/watcher/tray.py` | 修改 | `_init_main_window(show=False)` 时显式 `hide()`，避免 `showMaximized` 副作用 |
+| `tests/test_gui.py` | 修改 | 更新 `ScanWorker` 测试为 `roots` 参数；新增 `TestScanWorkerMultiRoot`、`TestScanMode`、`TestScanModePersistence` |
+| `tests/test_config.py` | 修改 | 更新默认值断言以匹配 `default_factory` 变更 |
+
+## 关键决策与依据
+
+### 1. 三种扫描模式
+
+- **全盘扫描（full）**：调用 `list_drives()` 枚举所有盘符，`ScanWorker` 依次扫描并合并结果
+- **选择盘符（drive）**：`QComboBox` 展示可用盘符，扫描单个盘符
+- **选择文件夹（folder）**：保持原有路径选择行为（历史下拉 + 文件对话框）
+
+选择按钮用 `QButtonGroup`（exclusive）管理，三个 `QPushButton#modeCard` 可选中样式。
+
+### 2. ScanWorker 多根路径支持
+
+`ScanWorker.__init__` 参数从 `root: Path` 改为 `roots: List[Path]`，
+`run()` 依次扫描所有根路径，累加统计并合并 `results`，
+最终构造单一 `ScanReport`（单路径时 `root` 为实际路径，多路径时为 `Path("（多路径）")`）。
+
+### 3. 目标选择器可见性
+
+`_update_target_visibility()` 根据扫描模式切换可见性：
+- full：隐藏路径行与盘符下拉
+- drive：显示盘符下拉，隐藏路径行
+- folder：显示路径行，隐藏盘符下拉
+
+### 4. 扫描按钮就绪逻辑
+
+`_update_scan_button()` 按模式判断就绪状态：
+- full：有规则即可
+- drive：有规则且有盘符
+- folder：有规则且有路径
+
+### 5. QSS 样式
+
+- 模式卡片：选中时蓝色边框 + 浅蓝背景 + 加粗
+- 扫描按钮：绿色背景 + 白色文字 + 大字号 + 悬停/按下变色
+- 进度条：绿色 chunk + 圆角
+- 结果树：交替行颜色 + 增大行高
+
+### 6. tray.py hide 修复
+
+`MainWindow._apply_config()` 在 `window_state == "maximized"` 时调用 `showMaximized()`，
+导致 tray 的 `_init_main_window(show=False)` 创建窗口后变为可见。
+修复：`show=False` 时显式调用 `hide()`。
+
+## 验证结果
+
+- ruff：全部通过
+- pytest：437 passed, 1 skipped
+- coverage：88.35%（branch）
+
+## 新增测试
+
+- `TestScanWorkerMultiRoot`：多根路径扫描（2 个测试）
+- `TestScanMode`：模式切换、可见性、按钮状态、根路径构造（9 个测试）
+- `TestScanModePersistence`：scan_mode 与 last_drive 持久化（4 个测试）
+
+## 遗留事项
+
+- 无（iter-06～10 已归档至 `.trae/skills/fuscan-development.md`）

fuscan-0.1.1/.trae/docs/iter-14-realtime-progress.md

@@ -0,0 +1,40 @@
+# iter-14：扫描实时进度反馈与按钮字体差异化
+
+## 本轮目标
+
+1. 扫描过程显示实时进展：当前正在解析的文件、已扫描/跳过/命中/错误数量、已用时间。
+2. 关键主操作按钮字体大小差异化，更醒目。
+
+## 改动文件清单
+
+| 文件 | 改动 |
+|------|------|
+| `src/fuscan/scanner/result.py` | 新增 `ProgressInfo` frozen dataclass，加入 `__all__` |
+| `src/fuscan/scanner/__init__.py` | 导出 `ProgressInfo` |
+| `src/fuscan/scanner/scanner.py` | `Scanner.__init__` 新增 `on_progress`/`progress_interval` 参数；新增 `_emit_progress` 方法（时间节流 + `force=True` 跳过节流）；`scan()` 在遍历阶段每 200 条 emit、扫描阶段逐文件 emit、压缩包阶段逐包 emit、最终 `force=True` emit；`_scan_sequential`/`_scan_concurrent` 签名新增 `start, total, skipped` |
+| `src/fuscan/gui/worker.py` | 信号 `progress = Signal(int)` → `progress_info = Signal(object)`；新增累计字段 `_cum_*` 与 `_start_time`；新增 `_on_progress` 回调累加前序根路径统计后 emit；`run()` 传 `on_progress` 给 Scanner |
+| `src/fuscan/gui/main_window.py` | 新增 `_current_file_label`（QLabel#currentFileLabel）；`_build_scan_control_area` 拆分为 `_build_rules_row` + `_build_target_row`（修复 PLR0915）；`_on_scan` 连接 `progress_info` 信号、显示当前文件标签；`_on_scan_progress` 重写为接收 `ProgressInfo`，更新进度条/当前文件/详细统计；`_on_scan_finished`/`_on_scan_failed` 隐藏当前文件标签；QSS 字体层级：scanBtn 18px > modeCard 14px > statsLabel 13px > currentFileLabel 12px |
+| `tests/test_scanner.py` | 新增 `TestScannerProgress`（6 个测试：回调触发、并发、节流、None 安全、最终 force、字段填充） |
+| `tests/test_gui.py` | 新增 `TestScanWorkerProgress`（3 个测试：信号 emit、多根累计、字段类型）；修复 `test_window_geometry_restored` 高度断言为 ±2px |
+
+## 关键决策与依据
+
+1. **`ProgressInfo` 用 frozen dataclass**：进度信息是不可变快照，跨线程传递需保证线程安全，frozen 避免误改。
+2. **时间节流（默认 150ms）**：扫描小文件时每文件 emit 会淹没 UI 事件循环；节流后 UI 仍流畅，最终 `force=True` 保证完成时进度准确。
+3. **Scanner 层 emit vs Worker 层累计**：Scanner 只知道单根路径的进度，Worker 负责把多根路径的进度累加（`_cum_*` 字段），UI 看到的是全局累计值。
+4. **`progress_info = Signal(object)`**：PySide2 信号传递 Python 对象用 `object` 类型，避免 QVariant 转换问题。
+5. **QSS 字体层级**：主操作（扫描按钮）18px 加粗，模式卡片 14px，统计 13px，当前文件 12px 灰色——视觉层次清晰，扫描按钮最醒目。
+6. **进度条确定模式**：扫描启动时不确定进度（`setRange(0,0)`），收到首个有 `total` 的进度后切换为确定模式。
+
+## 验证结果
+
+- ruff：全部通过
+- pytest：452 passed, 1 skipped
+- 覆盖率：88.79%（≥ 80% 门槛）
+  - `scanner.py` 91%、`worker.py` 100%、`main_window.py` 84%
+
+## 遗留事项
+
+- ~~`worker.py` 覆盖率偏低（50%）~~：已解决。根因是 coverage 无法跟踪 QThread（C++ 线程）内执行的代码，
+  通过新增 `TestScanWorkerDirect` 直接调用 `run()`/`_on_progress()` 在主线程执行，覆盖率提升至 100%。
+- 若后续需要更精细的进度（如压缩包内条目计数），可扩展 `ProgressInfo` 字段。

fuscan-0.1.1/.trae/docs/iter-15-/346/250/241/346/235/277/346/270/205/347/220/206.md

@@ -0,0 +1,65 @@
+# iter-15：coopie 模板残留清理与 pyfilescan→fuscan 命名统一
+
+## 本轮目标
+
+项目使用 coopie 模板初始化并更名为 fuscan，但 commit `d299aa6` 仅改了包目录结构，代码内容、文档、配置中的旧名称与模板残留未清理。本轮完成全面清理。
+
+## 改动文件清单
+
+### 源代码（10 文件）
+
+- `src/fuscan/__init__.py`：docstring `pyfilescan` → `fuscan`
+- `src/fuscan/__main__.py`：docstring `python -m pyfilescan` → `python -m fuscan`
+- `src/fuscan/cli.py`：logger 名、prog、版本输出、用法示例
+- `src/fuscan/config.py`：`CONFIG_DIR` 从 `~/.pyfilescan` 改为 `~/.fuscan`，docstring 同步
+- `src/fuscan/rules/parser.py`：docstring 中 `:mod:` 引用
+- `src/fuscan/scanner/matchers.py`：docstring 中 `:mod:` 引用
+- `src/fuscan/gui/main_window.py`：窗口标题、关于对话框、导出报告默认文件名
+- `src/fuscan/gui/app.py`：`setApplicationName`
+- `src/fuscan/watcher/tray.py`：`setApplicationName`、tooltip、托盘通知文案
+- `src/fuscan/builtin/rules.yaml`：注释
+
+### 测试（2 文件）
+
+- `tests/test_gui.py`：9 处 `pyfilescan.gui.main_window.*` mock 路径 → `fuscan.gui.main_window.*`；配置路径注释、窗口标题断言
+- `tests/test_cli.py`：`pyfilescan.gui` 模块注入路径、`python -m pyfilescan` 入口测试注释
+
+### 模板残留清理（2 文件）
+
+- `README.md`：从模板特性介绍重写为 fuscan 项目说明（特性/安装/CLI+GUI 用法/规则配置/示例/开发）
+- `pyproject.toml`：移除 `extend-exclude = ["template"]`、`project-excludes` 中 `"template/**"`、`exclude = ["template/*"]`
+
+### 文档与示例（9 文件）
+
+- `.trae/skills/pyfilescan-development.md` → `fuscan-development.md`：重命名并更新全部 pyfilescan 引用
+- `.trae/docs/iter-11~14`：改动清单中 `src/pyfilescan/` → `src/fuscan/`，配置路径与 skills 引用同步
+- `examples/README.md`、`examples/basic_scan.py`：标题、说明、代码示例中的引用
+- `rules/example.yaml`、`rules/examples/README.md`：注释与命令示例
+
+### 旧规则文件清理
+
+- 删除 `.trae/rules/` 下 4 个旧规则文件（`dev-workflow.md`、`git-commit-message.md`、`python-standards.md`、`self-driven.md`），这些已重命名为 `rule-NN-*.md` 但删除操作未提交
+
+## 关键决策与依据
+
+1. **`.copier-answers.yml` 保留**：用户确认保留以便后续 `copier update` 同步模板上游修复。
+2. **配置目录 `~/.pyfilescan` → `~/.fuscan`**：项目版本 0.1.0 无实际用户，可安全更改，与包名一致避免混淆。
+3. **skills 文件重命名**：`pyfilescan-development.md` → `fuscan-development.md`，文件名与内容同步更新。
+4. **README 重写而非微调**：原内容是模板特性介绍（构建工具链/CI/CD/多版本测试），非项目说明。重写为基于 `src/fuscan` 实际功能的项目文档。
+5. **iter 历史文档更新路径引用**：虽为历史记录，但 `src/pyfilescan/` 路径已不存在，更新为 `src/fuscan/` 避免读者困惑。
+
+## 验证结果
+
+- **pyfilescan 残留检查**：`grep -ri pyfilescan` 无匹配（0 处残留）
+- **ruff check**：209 个预存错误（UP006/UP007 类型注解升级建议），与原始状态完全相同，本次清理未引入新问题
+- **ruff format --check**：3 个文件需格式化，与原始状态相同，预存问题
+- **pytest**：456 passed, 1 failed, 1 skipped
+  - 失败项 `test_window_geometry_restored`：PySide2 offscreen 环境下窗口高度断言（548 vs 500，差 48 > 2），环境相关问题，与改名无关
+  - **关键修复**：原始状态下测试因 `ModuleNotFoundError: No module named 'pyfilescan'` 完全无法运行（mock 路径与包名不匹配），本次清理修复后 456 个测试得以通过
+- **覆盖率**：88.26%，预存水平（iter-14 记录 88.79%），低于 95% 门槛但非本次引入
+
+## 遗留事项
+
+- ruff 的 209 个类型注解升级错误（UP006/UP007）为预存问题，需单独迭代处理（将 `typing.List`/`Optional` 升级为内置泛型，因项目已用 `from __future__ import annotations`）
+- 覆盖率 88.26% 低于 95% 门槛，预存问题
+- `test_window_geometry_restored` 在 offscreen 环境下的断言需调整（可放宽至 ±50 或跳过 offscreen 模式）

fuscan-0.1.1/.trae/docs/iter-16-/346/211/253/346/217/217/346/216/247/345/210/266.md

@@ -0,0 +1,68 @@
+# iter-16：扫描过程控制（开始/暂停/继续/停止）
+
+## 本轮目标
+
+实现需求02-1：扫描过程支持开始/暂停/继续（同一按钮切换状态）、停止功能。要求暂停时扫描线程阻塞且不消耗 CPU，停止时快速退出并返回已扫描的部分结果。
+
+## 改动文件清单
+
+### 源代码（4 文件）
+
+- `src/fuscan/scanner/result.py`：`ScanReport` 新增 `cancelled: bool = False` 字段，标识扫描是否被取消
+- `src/fuscan/scanner/scanner.py`：
+  - 新增 `threading.Event` 控制机制（`_pause_event` / `_cancel_event`）
+  - 新增 `pause()` / `resume()` / `cancel()` / `is_paused` / `is_cancelled` / `_check_control()` 方法
+  - 重构 `scan()`：提取 `_scan_archive_phase()` 消除 PLR0912（分支过多）；进度上下文移至实例属性
+  - 简化 `_emit_progress()` / `_scan_sequential()` / `_scan_concurrent()` 签名（移除 `start`/`total`/`skipped` 参数，改用实例属性），同时消除 PLR0913
+- `src/fuscan/gui/worker.py`：
+  - 新增 `cancelled = Signal(object)` 信号
+  - 新增 `_cancel_requested` 标志，解决 Scanner 尚未创建时 cancel 丢失的竞态
+  - `cancel()` 设置标志并委托 Scanner；`run()` 创建 Scanner 后检查标志
+  - `run()` 在 roots 循环中检查取消标志；取消时 emit `cancelled` 而非 `finished_report`
+- `src/fuscan/gui/main_window.py`：
+  - 新增 `ScanState` 枚举（IDLE / RUNNING / PAUSED）驱动三态按钮
+  - 扫描按钮 + 停止按钮 HBox 布局（停止按钮初始隐藏，扫描时显示）
+  - `_set_scan_controls_text()` 同步按钮与菜单文本
+  - `_on_scan` 三态分发：IDLE→启动、RUNNING→暂停、PAUSED→恢复
+  - 新增 `_pause_scan` / `_resume_scan` / `_on_stop` / `_on_scan_cancelled` / `_reset_scan_ui` / `_cleanup_worker`
+  - `_update_scan_button` 在 RUNNING/PAUSED 时保持按钮启用
+  - `closeEvent` 改用 `cancel()` 替代 `quit()`（ScanWorker 重写 `run()`，非事件循环模式）
+
+### 测试（2 文件）
+
+- `tests/test_scanner.py`：新增 `TestScannerControl`（9 项测试）
+  - 初始状态、暂停/恢复/取消标志、cancel 解除暂停阻塞
+  - 扫描前取消返回 cancelled 报告
+  - 扫描中取消返回部分结果（进度回调触发取消，无时序依赖）
+  - 并发扫描取消
+  - 暂停/恢复后扫描正常完成
+- `tests/test_gui.py`：新增 3 个测试类共 17 项测试
+  - `TestScanControlUI`（11 项）：状态转换、按钮文本同步、停止按钮可见性、`_update_scan_button` 在 RUNNING/PAUSED 的行为、暂停/恢复/重置
+  - `TestScanControlIntegration`（4 项）：MainWindow 全流程扫描完成、取消回调、worker 清理、无路径告警
+  - `TestScanWorkerControl`（2 项）：Worker cancel emit cancelled 信号（进度回调触发）、pause/resume 委托 Scanner
+
+### 需求文档（2 文件）
+
+- `.trae/req/需求01.md`：格式化为 `- [x]` 复选框格式
+- `.trae/req/需求02.md`：格式化为 `- [x]` 复选框格式；需求02-1 标记为 `[x]`
+
+## 关键决策与依据
+
+1. **threading.Event 实现暂停/取消**：`_pause_event.wait()` 阻塞扫描线程且不占 CPU；`_cancel_event` 在遍历、扫描、并发收集、压缩包扫描各阶段检查，确保快速退出。
+2. **取消竞态修复**：`ScanWorker.cancel()` 可能在 `run()` 创建 Scanner 之前调用（如快速点击停止）。新增 `_cancel_requested` 标志，`run()` 创建 Scanner 后立即检查并转发取消。
+3. **进度回调触发取消（测试策略）**：扫描 50 文件仅需 0.6ms，`threading.Event` + `sleep` 的时序测试不可靠。改用 `on_progress` 回调在首次进度事件时调用 `scanner.cancel()`，无时序依赖。
+4. **三态按钮 vs 双按钮**：需求明确"开始/暂停/继续（同一按钮）"，故扫描按钮三态切换；停止功能用独立红色按钮，避免三态以上复杂度。
+5. **PLR0912 重构**：`scan()` 分支数 14 > 12。提取 `_scan_archive_phase()` 并将进度上下文移至实例属性，同时简化多个方法签名，消除 PLR0912 和 PLR0913。
+
+## 验证结果
+
+- ruff check：213 errors（全部为既有 UP006/UP045/ARG005/PLR0913，本轮新增 3 个 UP006 与既有风格一致，消除 1 个 PLR0913）
+- pytest：483 passed, 1 failed（`test_window_geometry_restored` 为既有 PySide2 offscreen 环境问题）, 1 skipped
+- coverage：89.36%（较基线 88.26% 提升 1.1%）
+- pyrefly：322 errors（全部为既有 PySide2 类型存根问题）
+
+## 遗留事项
+
+- `test_window_geometry_restored`：PySide2 offscreen 平台 `propagateSizeHints()` 不支持，窗口高度 548 vs 预期 500（偏差 48 > 2）。既有问题，非本轮引入。
+- coverage 89.36% 低于 95% 门槛：既有技术债，主要缺口在 extractors/office.py（76%）、gui/worker.py（80%）、watcher/ignore_dirs.py（65%）。
+- UP006/UP045 全量迁移（`List`→`list`、`Optional[X]`→`X | None`）：213 个错误，需单独迭代处理。