picren-ai 0.1.0__tar.gz

picren_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anyuer678
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

picren_ai-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: picren-ai
+Version: 0.1.0
+Summary: 图片批量 AI 重命名/整理器：AI 看图、改名、归档一条龙
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PicRename AI —— 图片批量 AI 重命名/整理器
+
+> 把 `IMG_20230101_103055.jpg` 变成 `旅行_日本_东京塔_2026.jpg`：AI 看图 → 中文语义命名 → 归档，一条龙。
+
+[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-110%20passed-brightgreen)](tests/)
+[![Deps](https://img.shields.io/badge/deps-Pillow%20%2B%20httpx-blueviolet)](requirements.txt)
+
+高频、隐私刚需场景：相册几百张图批量整理。图片压缩至最长边 800px 后才发送给视觉模型，支持完全本地模型（Ollama 等）。
+
+## 功能特性
+
+| 能力 | 说明 |
+|---|---|
+| AI 视觉识别 | 主体/场景分类/置信度，category 封闭枚举校验（旅行/美食/文档/宠物/人物/街拍/风景/运动/建筑/其他） |
+| 模板化命名 | `{date}_{category}_{subject}_{index}.{ext}`，支持 strftime 自定义日期格式 |
+| 安全第一 | 默认 `--dry-run` 只预览；真实改名必须显式 `--execute` |
+| 可回滚 | 每次执行记录 `rename_map.csv`，`--undo` 一键回滚（含 mtime 恢复） |
+| 绝不覆盖 | 目标重名自动追加 `_1` 序号；非法字符过滤；可选按类别移入子目录 |
+| 三种界面 | CLI / 零依赖 Web UI / JSON 输出 |
+
+## 快速开始
+
+```bash
+pip install -e .        # 安装 picren 命令（Pillow / httpx 自动装）
+
+# 生成示例图（可选）
+python sample\gen_sample.py
+
+# 配置 API Key（优先级：--api-key > 环境变量 API_KEY > 工作目录 .env）
+set API_KEY=sk-xxxx     # Windows
+
+# dry-run 预览（默认，不修改任何文件）
+picren --dir sample --dry-run
+
+# 真实执行（自动记录 rename_map.csv，可 --undo 回滚）
+picren --dir photos --execute --move-by-category
+
+# 回滚
+picren --dir photos --undo
+
+# 本地模型（Ollama OpenAI 兼容端点）
+picren --dir photos --api-base http://localhost:11434/v1 --model qwen2.5vl --api-key ollama
+```
+
+## 命令参考
+
+| 参数 | 说明 |
+|---|---|
+| `--dir DIR` | 图片目录（必选） |
+| `--recursive` | 递归子目录 |
+| `--pattern "*.jpg"` | 扩展名/通配模式，可重复 |
+| `--template` | 命名模板（默认 `{date}_{category}_{subject}_{index}.{ext}`） |
+| `--dry-run` / `--execute` | 预览 / 执行（默认预览） |
+| `--undo` | 回滚最近的 rename_map.csv |
+| `--move-by-category` | 按类别移入子目录 |
+| `--tags-only` | 只生成 tags.csv，不改名 |
+| `--workers N` | 并发线程数（默认 4） |
+
+退出码：`0` 成功 · `1` 参数错误/无 Key · `2` 无匹配文件 · `3` 识别质量过低（超过 `--max-fail-ratio` 阈值中止）。
+
+## 项目结构
+
+```
+main.py           CLI 入口、API key 优先级、退出码
+pipeline.py       收集 → 并发识别 → 渲染计划 → 执行/预览
+vision.py         视觉模型调用与严格 JSON 解析（不访问文件系统）
+reader.py         图片收集与预览压缩
+rename_rules.py   模板渲染、非法字符过滤、重名去重
+executor.py       改名执行 + undo_map 追加（绝不覆盖）
+undo.py           回滚解析与逆序执行
+webui.py + webui.html   零依赖 Web 界面
+tests/            pytest 测试（110 例，不触网）
+```
+
+## 测试
+
+```bash
+python -m pytest tests/ -q
+```
+
+## 隐私与免责
+
+- 图片压缩至最长边 800px 后才发送到模型服务；完全本地模型（Ollama）可零上传使用。
+- 工具只做文件名/目录层操作，**绝不删除文件**；`--keep-original`（默认开）让新名保留原名便于回溯。
+- AI 命名仅供参考，执行前请核对 dry-run 预览；建议在副本目录上先试验。
+
+本项目仅供学习交流与演示用途，不构成任何形式的商业服务或技术承诺。软件按「现状」提供，不作任何明示或暗示的保证，包括但不限于适销性、特定用途适用性与非侵权性。
+您理解并同意：使用本项目即表示您自行承担全部风险。如您在使用过程中发现缺陷或问题，欢迎通过 GitHub Issues 反馈，但作者不因使用本软件所直接或间接产生的任何损失（包括但不限于数据丢失、业务中断、第三方索赔）承担责任。
+本项目以功能演示与学习交流为主要目的，其架构设计、安全基线、容错机制与性能表现均未按生产级标准进行验证与加固，不适用于实际生产环境或关键业务场景。任何将本项目部署于生产系统、对外提供服务、或将其接入真实业务工作流的做法，均属使用者的自主决策行为；由此产生的任何直接或间接不良后果，包括但不限于服务中断、数据损坏或泄露、业务损失、合规风险、以及因依赖本软件而引发的第三方纠纷，**开发者均不承担任何责任**。若您确有生产级使用需求，请在充分评估与自行加固（包括但不限于安全审计、压力测试、代码审查）后，自行承担相应风险。
+
+## License
+
+[GPL-3.0](LICENSE) — Copyright (C) 2026 anyuer678

picren_ai-0.1.0/README.md

@@ -0,0 +1,95 @@
+# PicRename AI —— 图片批量 AI 重命名/整理器
+
+> 把 `IMG_20230101_103055.jpg` 变成 `旅行_日本_东京塔_2026.jpg`：AI 看图 → 中文语义命名 → 归档，一条龙。
+
+[![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-110%20passed-brightgreen)](tests/)
+[![Deps](https://img.shields.io/badge/deps-Pillow%20%2B%20httpx-blueviolet)](requirements.txt)
+
+高频、隐私刚需场景：相册几百张图批量整理。图片压缩至最长边 800px 后才发送给视觉模型，支持完全本地模型（Ollama 等）。
+
+## 功能特性
+
+| 能力 | 说明 |
+|---|---|
+| AI 视觉识别 | 主体/场景分类/置信度，category 封闭枚举校验（旅行/美食/文档/宠物/人物/街拍/风景/运动/建筑/其他） |
+| 模板化命名 | `{date}_{category}_{subject}_{index}.{ext}`，支持 strftime 自定义日期格式 |
+| 安全第一 | 默认 `--dry-run` 只预览；真实改名必须显式 `--execute` |
+| 可回滚 | 每次执行记录 `rename_map.csv`，`--undo` 一键回滚（含 mtime 恢复） |
+| 绝不覆盖 | 目标重名自动追加 `_1` 序号；非法字符过滤；可选按类别移入子目录 |
+| 三种界面 | CLI / 零依赖 Web UI / JSON 输出 |
+
+## 快速开始
+
+```bash
+pip install -e .        # 安装 picren 命令（Pillow / httpx 自动装）
+
+# 生成示例图（可选）
+python sample\gen_sample.py
+
+# 配置 API Key（优先级：--api-key > 环境变量 API_KEY > 工作目录 .env）
+set API_KEY=sk-xxxx     # Windows
+
+# dry-run 预览（默认，不修改任何文件）
+picren --dir sample --dry-run
+
+# 真实执行（自动记录 rename_map.csv，可 --undo 回滚）
+picren --dir photos --execute --move-by-category
+
+# 回滚
+picren --dir photos --undo
+
+# 本地模型（Ollama OpenAI 兼容端点）
+picren --dir photos --api-base http://localhost:11434/v1 --model qwen2.5vl --api-key ollama
+```
+
+## 命令参考
+
+| 参数 | 说明 |
+|---|---|
+| `--dir DIR` | 图片目录（必选） |
+| `--recursive` | 递归子目录 |
+| `--pattern "*.jpg"` | 扩展名/通配模式，可重复 |
+| `--template` | 命名模板（默认 `{date}_{category}_{subject}_{index}.{ext}`） |
+| `--dry-run` / `--execute` | 预览 / 执行（默认预览） |
+| `--undo` | 回滚最近的 rename_map.csv |
+| `--move-by-category` | 按类别移入子目录 |
+| `--tags-only` | 只生成 tags.csv，不改名 |
+| `--workers N` | 并发线程数（默认 4） |
+
+退出码：`0` 成功 · `1` 参数错误/无 Key · `2` 无匹配文件 · `3` 识别质量过低（超过 `--max-fail-ratio` 阈值中止）。
+
+## 项目结构
+
+```
+main.py           CLI 入口、API key 优先级、退出码
+pipeline.py       收集 → 并发识别 → 渲染计划 → 执行/预览
+vision.py         视觉模型调用与严格 JSON 解析（不访问文件系统）
+reader.py         图片收集与预览压缩
+rename_rules.py   模板渲染、非法字符过滤、重名去重
+executor.py       改名执行 + undo_map 追加（绝不覆盖）
+undo.py           回滚解析与逆序执行
+webui.py + webui.html   零依赖 Web 界面
+tests/            pytest 测试（110 例，不触网）
+```
+
+## 测试
+
+```bash
+python -m pytest tests/ -q
+```
+
+## 隐私与免责
+
+- 图片压缩至最长边 800px 后才发送到模型服务；完全本地模型（Ollama）可零上传使用。
+- 工具只做文件名/目录层操作，**绝不删除文件**；`--keep-original`（默认开）让新名保留原名便于回溯。
+- AI 命名仅供参考，执行前请核对 dry-run 预览；建议在副本目录上先试验。
+
+本项目仅供学习交流与演示用途，不构成任何形式的商业服务或技术承诺。软件按「现状」提供，不作任何明示或暗示的保证，包括但不限于适销性、特定用途适用性与非侵权性。
+您理解并同意：使用本项目即表示您自行承担全部风险。如您在使用过程中发现缺陷或问题，欢迎通过 GitHub Issues 反馈，但作者不因使用本软件所直接或间接产生的任何损失（包括但不限于数据丢失、业务中断、第三方索赔）承担责任。
+本项目以功能演示与学习交流为主要目的，其架构设计、安全基线、容错机制与性能表现均未按生产级标准进行验证与加固，不适用于实际生产环境或关键业务场景。任何将本项目部署于生产系统、对外提供服务、或将其接入真实业务工作流的做法，均属使用者的自主决策行为；由此产生的任何直接或间接不良后果，包括但不限于服务中断、数据损坏或泄露、业务损失、合规风险、以及因依赖本软件而引发的第三方纠纷，**开发者均不承担任何责任**。若您确有生产级使用需求，请在充分评估与自行加固（包括但不限于安全审计、压力测试、代码审查）后，自行承担相应风险。
+
+## License
+
+[GPL-3.0](LICENSE) — Copyright (C) 2026 anyuer678

picren_ai-0.1.0/picren/__init__.py

@@ -0,0 +1,3 @@
+"""Picren：图片批量 AI 重命名/整理器。"""
+
+__version__ = "0.1.0"

picren_ai-0.1.0/picren/executor.py

@@ -0,0 +1,73 @@
+"""改名执行与 dry-run 展示：逐个 os.rename、失败隔离、成功后追加 undo_map。"""
+
+from __future__ import annotations
+
+import csv
+import os
+from dataclasses import dataclass
+from typing import List, Tuple
+
+
+@dataclass
+class RenameOp:
+    src_abs: str
+    dst_abs: str
+    mtime_before: float
+
+
+@dataclass
+class ApplyStats:
+    renamed: int
+    failed: list  # [(src, err), ...]
+
+
+_HEADER = ("old_name", "new_name", "mtime")
+
+
+def _map_dir(path: str) -> str:
+    return os.path.dirname(os.path.abspath(path))
+
+
+def _rel(path: str, base: str) -> str:
+    try:
+        return os.path.relpath(path, base)
+    except ValueError:  # 跨盘符时回退绝对路径
+        return path
+
+
+def _fmt_mtime(mtime: float) -> str:
+    return repr(mtime) if mtime else "0"
+
+
+def _append_map_row(undo_map: str, op: RenameOp) -> None:
+    base = _map_dir(undo_map)
+    fresh = not os.path.exists(undo_map) or os.path.getsize(undo_map) == 0
+    with open(undo_map, "a", newline="", encoding="utf-8-sig") as f:
+        writer = csv.writer(f)
+        if fresh:
+            writer.writerow(_HEADER)
+        writer.writerow([_rel(op.src_abs, base), _rel(op.dst_abs, base), _fmt_mtime(op.mtime_before)])
+
+
+def apply_renames(ops: List[RenameOp], *, undo_map: str = "rename_map.csv") -> ApplyStats:
+    """逐个 os.rename；单个失败只记录不中断整批，成功后 append 一行到 undo_map。"""
+    ops = [RenameOp(os.path.abspath(o.src_abs), os.path.abspath(o.dst_abs), o.mtime_before)
+           for o in ops]
+    stats = ApplyStats(renamed=0, failed=[])
+    for op in ops:
+        if os.path.lexists(op.dst_abs):
+            stats.failed.append((op.src_abs, "目标已存在，拒绝覆盖: %s" % op.dst_abs))
+            continue
+        try:
+            os.rename(op.src_abs, op.dst_abs)
+        except OSError as e:
+            stats.failed.append((op.src_abs, str(e)))
+            continue
+        _append_map_row(undo_map, op)
+        stats.renamed += 1
+    return stats
+
+
+def dry_run_render(ops: List[RenameOp]) -> List[Tuple[str, str]]:
+    """纯展示 (src→dst) 列表，绝不触碰文件系统。"""
+    return [(op.src_abs, op.dst_abs) for op in ops]

picren_ai-0.1.0/picren/main.py

@@ -0,0 +1,251 @@
+"""PicRename AI 命令行入口：参数解析、API key 优先级、退出码、tags/undo 装配。"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+import sys
+
+from .pipeline import UNDO_MAP_NAME, PipelineConfig, run_pipeline
+from .undo import undo_from_map
+
+DEFAULT_API_BASE = "https://api.openai.com/v1"
+DEFAULT_MODEL = "gpt-4o-mini"
+KEY_NAMES = ("PICREN_API_KEY", "PICRENAME_API_KEY", "API_KEY")  # 首选专用名，旧名向后兼容
+
+KEY_HINT = (
+    "[picren] 错误：未找到 API Key，无法调用视觉模型。\n"
+    "  请用以下任一方式提供：\n"
+    "    1) 命令行参数：--api-key <你的Key>\n"
+    "    2) 环境变量：API_KEY=<你的Key>\n"
+    "    3) 工作目录 .env 文件写入：API_KEY=sk-xxx\n"
+    "  提示：图片会压缩至最长边 800px 后发送给第三方模型服务；\n"
+    "  本地模型（如 Ollama）可传 --api-key ollama。"
+)
+
+
+class _UsageError(Exception):
+    """参数错误（退出码 1）。"""
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message):
+        raise _UsageError(message)
+
+
+def _build_parser() -> _Parser:
+    p = _Parser(prog="picren",
+                description="图片批量 AI 重命名/整理器（PicRename AI）")
+    p.add_argument("--dir", help="图片目录")
+    p.add_argument("--recursive", action="store_true", help="递归子目录")
+    p.add_argument("--pattern", action="append", default=[],
+                   help="扩展名/通配模式，可重复（如 *.jpg）")
+    p.add_argument("--template", default="{date}_{category}_{subject}_{index}.{ext}",
+                   help="命名模板")
+    p.add_argument("--tags-only", action="store_true", help="只生成 tags.csv，不改名")
+    mode = p.add_mutually_exclusive_group()
+    mode.add_argument("--dry-run", action="store_true", help="仅预览，不写盘（默认模式）")
+    mode.add_argument("--execute", action="store_true", help="真实执行（先自动预览）")
+    p.add_argument("--undo", action="store_true", help="回滚最近的 rename_map.csv")
+    p.add_argument("--move-by-category", action="store_true", help="按类别移入子目录")
+    p.add_argument("--keep-original", action="store_true", default=True,
+                   help="目标名保留原名以可回溯（默认开启）")
+    p.add_argument("--no-keep-original", dest="keep_original", action="store_false")
+    p.add_argument("--api-base", default=DEFAULT_API_BASE, help="OpenAI 兼容 API 地址")
+    p.add_argument("--model", default=DEFAULT_MODEL, help="视觉模型名")
+    p.add_argument("--api-key", default=None, help="API key（也可用环境变量/.env）")
+    p.add_argument("--workers", type=int, default=4, help="并发线程数")
+    p.add_argument("--max-fail-ratio", type=float, default=0.2,
+                   help="识别失败比例阈值，超过则中止")
+    p.add_argument("--json", action="store_true", help="以 JSON 输出结果")
+    return p
+
+
+def _read_dotenv_key() -> str:
+    """从工作目录 .env 中读取 API_KEY（手写 dotenv，不引依赖）。"""
+    path = os.path.join(os.getcwd(), ".env")
+    if not os.path.exists(path):
+        return ""
+    try:
+        with open(path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                k, v = line.split("=", 1)
+                if k.strip() in KEY_NAMES and v.strip():
+                    return v.strip()
+    except OSError:
+        return ""
+    return ""
+
+
+def _load_api_key(cli_key) -> str:
+    """key 优先级：--api-key > 环境变量 > .env 文件。"""
+    if cli_key:
+        return cli_key
+    for name in KEY_NAMES:
+        v = os.environ.get(name)
+        if v:
+            return v
+    return _read_dotenv_key()
+
+
+def _iter_plan(planned):
+    """把 planned 元素统一为 (src, dst) 元组（兼容 RenameOp 与二元组）。"""
+    for item in planned:
+        if hasattr(item, "src_abs"):
+            yield item.src_abs, item.dst_abs
+        else:
+            yield item
+
+
+def _format_plan(planned) -> str:
+    """把 [(src, dst)] 渲染成对齐的文本表。"""
+    if not planned:
+        return "  （无）"
+    items = list(_iter_plan(planned))
+    width = max((len(str(s)) for s, _ in items), default=0)
+    lines = [f"  {src:<{width}}  ->  {dst}" for src, dst in items]
+    return "\n".join(lines)
+
+
+def _write_tags_csv(directory: str, report) -> str:
+    """写 tags.csv（文件名,日期,类别,主题,场景,置信度）。"""
+    path = os.path.join(directory, "tags.csv")
+    with open(path, "w", newline="", encoding="utf-8-sig") as f:
+        w = csv.writer(f)
+        w.writerow(["文件名", "日期", "类别", "主题", "场景", "置信度"])
+        for img, result in (report.tagged or []):
+            rel = os.path.relpath(img.path, directory)
+            date = img.taken_at.strftime("%Y-%m-%d") if img.taken_at else ""
+            w.writerow([rel, date, result.category, result.subject,
+                        result.scene, f"{result.confidence:.2f}"])
+    return path
+
+
+def _report_to_json(report) -> dict:
+    """把 PipelineReport 序列化为 JSON 可打印结构。"""
+    executed = None
+    if report.executed is not None:
+        executed = {
+            "renamed": report.executed.renamed,
+            "failed": [[src, str(err)] for src, err in report.executed.failed],
+        }
+    return {
+        "planned": [[src, dst] for src, dst in _iter_plan(report.planned)],
+        "executed": executed,
+        "failed": [[path, err] for path, err in report.failed],
+        "tags": [
+            {"subject": t.subject, "category": t.category, "scene": t.scene,
+             "confidence": t.confidence}
+            for t in report.tags
+        ],
+        "elapsed_s": round(report.elapsed_s, 3),
+    }
+
+
+def _cmd_undo(args) -> int:
+    """--undo：读取目录下最近的 rename_map.csv 回滚。"""
+    directory = args.dir or os.getcwd()
+    map_path = os.path.join(directory, UNDO_MAP_NAME)
+    if not os.path.exists(map_path):
+        print(f"[picren] 未找到回滚映射：{map_path}", file=sys.stderr)
+        return 1
+    stats = undo_from_map(map_path)
+    print(f"[picren] 已回滚 {stats.renamed} 个文件"
+          + (f"，失败 {len(stats.failed)} 个" if stats.failed else ""))
+    for src, err in stats.failed:
+        print(f"  - {src}: {err}", file=sys.stderr)
+    return 0
+
+
+def _cmd_run(args) -> int:
+    """--dir 主流程：校验→建配置→跑管道→按退出码/模式输出。"""
+    if not args.dir:
+        raise _UsageError("缺少必选参数 --dir")
+    if not os.path.isdir(args.dir):
+        raise _UsageError(f"目录不存在：{args.dir}")
+    key = _load_api_key(args.api_key)
+    if not key:
+        print(KEY_HINT, file=sys.stderr)
+        return 1
+    cfg = PipelineConfig(
+        directory=args.dir,
+        recursive=args.recursive,
+        patterns=args.pattern or None,
+        template=args.template,
+        dry_run_first=not args.execute,  # 默认 dry-run；--execute 才落盘（--dry-run 与其互斥）
+        workers=max(1, args.workers),
+        api_base=args.api_base,
+        model=args.model,
+        api_key=key,
+        move_by_category=args.move_by_category,
+        keep_original=args.keep_original,
+        max_fail_ratio=args.max_fail_ratio,
+    )
+    report = run_pipeline(cfg)
+    total = len(report.failed) + len(report.tags)
+    if total == 0:
+        print(f"[picren] 未找到匹配的图片文件：{args.dir}", file=sys.stderr)
+        return 2
+    fail_ratio = len(report.failed) / total
+    if fail_ratio > cfg.max_fail_ratio:
+        print(f"[picren] 识别质量过低（失败 {len(report.failed)}/{total}），已中止；"
+              f"阈值 {cfg.max_fail_ratio:.0%}", file=sys.stderr)
+        for path, err in report.failed[:5]:
+            print(f"  - {path}: {err}", file=sys.stderr)
+        return 3
+    if args.tags_only:
+        path = _write_tags_csv(args.dir, report)
+        print(f"[picren] 已生成 {path}（{len(report.tags)} 行），未改名")
+        return 0
+    if args.json:
+        print(json.dumps(_report_to_json(report), ensure_ascii=False, indent=2))
+        return 0
+    mode = "干跑预览（未修改任何文件）" if not args.execute else "执行前预览"
+    print(f"[picren] 收集 {total} 张，成功识别 {len(report.tags)} 张"
+          f"（失败 {len(report.failed)}），耗时 {report.elapsed_s:.1f}s：{mode}")
+    print(_format_plan(report.planned))
+    if args.execute:
+        stats = report.executed
+        if stats is None:
+            print("[picren] 未执行（无可用计划）", file=sys.stderr)
+            return 1
+        print(f"[picren] 已重命名 {stats.renamed} 个文件"
+              + (f"，失败 {len(stats.failed)} 个" if stats.failed else ""))
+        for src, err in stats.failed:
+            print(f"  - {src}: {err}", file=sys.stderr)
+    return 0
+
+
+def _fix_win_encoding() -> None:
+    """Windows 下重定向/管道输出统一为 UTF-8，避免中文乱码。"""
+    if sys.platform != "win32":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+
+def main(argv=None) -> int:
+    """CLI 入口，返回进程退出码。"""
+    _fix_win_encoding()
+    parser = _build_parser()
+    try:
+        args = parser.parse_args(argv)
+        if args.undo:
+            return _cmd_undo(args)
+        return _cmd_run(args)
+    except _UsageError as exc:
+        print(f"[picren] 参数错误：{exc}", file=sys.stderr)
+        parser.print_usage(file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())