本技能用于对 Python 项目进行系统性整理和重构（默认通用风格，根据具体项目类型自动适配）重要原则：始终先生成整理建议，等待用户批准后再执行任何文件修改
整理/重构到最佳实践。所有优化措施均由用户主动选择，绝不默认执行
每次执行整理任务前，必须经过两轮用户确认，不可跳过：
可选策略列表
并给出推荐：
| 策略级别 | 适用场景 | 包含的整理措施 |
| ------------ | ------------------------------------- | ------------------------------------------------------------ |
| 轻量清理 | 单脚本、实验性代码、临时项目 | 无用代码清理、空目录删除、明显命名问题修复 + 简要文档 |
| 标准整理 | 小型工具、数据处理管道、原型项目 | 轻量清理 + 命名规范 + import 排序 + 代码格式 + 类型标注 + 规范注释 + 标准文档 |
| 深度重构 | 可发布的小库、API 服务、完整 pipeline | 标准整理 + 目录结构重组 + src layout + init.py + 配置参数化 + 测试覆盖 + 分层架构 + 详细文档 |
| 全面重构 | 团队项目、商业产品级应用 | 深度重构 + DDD 设计 + 完整测试套件 + pyproject.toml + 完整文档 + 代码质量检查 |
判断原则：
核心原则：使用并行子代理拆分任务，避免单会话超时导致的中断
对于复杂项目重构（超过个文件需要修改），必须采用以下模式：
# 错误做法：串行执行所有操作
for file in files_to_modify:
read(file) # 阻塞等待
edit(file) # 阻塞等待
# 正确做法：并行子代理 + 进度持久化
phases = [
{"id": "phase-a", "task": "创建目录结构"},
{"id": "phase-b", "task": "移动文件到对应目录"},
{"id": "phase-c", "task": "更新所有 import 路径"},
{"id": "phase-d", "task": "统一变量命名和类型提示"},
{"id": "phase-e", "task": "生成三个文档文件"}
]
for phase in phases:
spawn_sub_agent(phase["id"], phase["task"]) # 并行启动
由主会话执行，轻量级操作
exec 或 background=true 模式进行耗时操作（如 robocopy, tree）
# 推荐：后台执行长时间任务
cmd /c "robocopy E:\\LPR E:\\LPR_backup /MIR" > backup.log 2>&1 &
基于用户选择的策略级别，生成详细整理方案。
在收到明确批准后，按以下顺序通过 sub-agents 并行执行
# 主会话根据用户选择的策略级别选择任务
strategy = user_selected_strategy # "轻量清理" | "标准整理" | "深度重构" | "全面重构"
tasks = {
# === 所有策略都适用 ===
"code-cleanup": "清理无用代码和空目录",
# === 标准整理及以上 ===
"style-unify": "代码风格统一（格式/命名/import/类型/注释）" if strategy in ["标准整理", "深度重构", "全面重构"] else None,
# === 深度重构及以上 ===
"create-structure": "创建目录结构/.gitignore" if strategy in ["深度重构", "全面重构"] else None,
"move-files-phase1": "移动核心脚本到对应目录" if strategy in ["深度重构", "全面重构"] else None,
"config-extract": "配置参数化" if strategy in ["深度重构", "全面重构"] else None,
"add-tests": "补充单元测试" if strategy in ["深度重构", "全面重构"] else None,
# === 全面重构 ===
"quality-check": "代码质量与设计规范检查" if strategy == "全面重构" else None,
"generate-docs": "生成三份文档" if strategy == "全面重构" else None,
}
tasks = {k: v for k, v in tasks.items() if v is not None} # 过滤掉不适用的任务
# 分批启动子代理（避免 token 溢出）
batch_size = 3 # 每批最多 3 个子代理
for i in range(0, len(tasks), batch_size):
batch = tasks[i:i+batch_size]
for task_id, task_desc in batch.items():
sessions_spawn(
agentId="main",
label=task_id,
task=f"""执行代码整理任务：{task_desc}
注意事项：
1. 使用相对路径操作文件
2. 每个子代理只负责自己的任务
3. 完成后将结果写入进度文件 memory/organize-progress.json
4. 如果任何步骤失败，记录错误并继续其他步骤
输出格式：
{{\"status\": \"success|failed\", \"task\": \"{task_id}\",
\"files_modified\": [...], \"errors\": [...]}}""")
轻量/标准策略：保持现有结构，不做目录重组
深度重构及以上：
project-root/
├── src/ # 源代码
│ └── package_name/ # 主包
├── tests/ # 测试代码（可选）
├── configs/ # 配置文件（可选，参数 >3 时建议）
├── scripts/ # 辅助脚本、CLI 工具
├── docs/ # 项目文档（仅中型以上）
└── ...
根据项目类型可调整：
src/app/routes.py, src/app/services/
src/pipeline/, data/, notebooks/
models/, trainers/, experiments/
轻量清理策略跳过此步骤 - 标准整理及以上策略执行以下全部规则：
"（字符串内容含双引号时使用单引号 '）
a + b），一元运算符紧贴操作数（-x）
[1, 2, 3]）
snake_case，简短描述性（data_loader.py，user_service/）
PascalCase（DataLoader，UserService）
snake_case，动词开头（fetch_user()，validate_input()）
snake_case，语义化命名（user_list 而非 ul，parsed_records 而非 data）
UPPER_SNAKE_CASE（MAX_RETRIES = 3，API_BASE_URL）
_internal_cache，__private_method）
is_/has_/can_/should_ 前缀（is_valid，has_permission）
i/j/k 循环索引和数学公式外）、缩写（usr 为 user）
遵循三段式分组 + 组内字母序：
# 1. 标准库
import os
import sys
from pathlib import Path
# 2. 第三方库
import numpy as np
import requests
from flask import Flask
# 3. 本地模块
from .config import Settings
from .models.user import UserModel
from utils.helpers import format_date
from .models.user import UserModel），而非 import models.user
I 规则）或 isort 自动排序
def fetch_user(user_id: int, include_deleted: bool = False) -> User | None:
...
__init__ 或类体中声明类型
class DataProcessor:
batch_size: int = 32
shuffle: bool = True
list[str] 而非 list，dict[str, int] 而非 dict）
X | None（Python 3.10+）或 Optional[X]
A | B（Python 3.10+）或 Union[A, B]
typing.TypeAlias 定义类型别名
注释哲学：注释是"必要的恶"。优先选择重命名而非写注释
必须添加注释的情况：
# TODO:, # HACK:, # FIXME:）
Docstring 规范（公共函数/类必须）：
def process_data(records: list[Record], batch_size: int = 32) -> list[Batch]:
"""将记录列表分批处理
对输入记录进行过滤、转换和分批，返回处理后的批次列表
Args:
records: 原始记录列表
batch_size: 每个批次的记录数，默认 32
Returns:
处理后的批次列表，每个批次包含最多 batch_size 条记录
Raises:
ValueError: 当 records 为空或 batch_size 小于 1 时
"""
类 Docstring：
class DataProcessor:
"""高效处理并分批输入记录
处理记录的过滤、转换和分批操作，设计为可子类化
以支持自定义处理管道
Attributes:
batch_size: 每批次记录数（默认 32）
shuffle: 每个 epoch 是否打乱数据集
num_workers: 数据加载的并行工作线程数
Example:
>>> processor = DataProcessor(batch_size=64, shuffle=True)
>>> for batch in processor:
... print(len(batch))
"""
行内注释规范：
# 后跟一个空格
禁止：
深入分析并优化：
.idea/, __pycache__/：确保所有 IDE 缓存、Python 字节码被排除在版本控制外
utils/
# 改进前（参数超过 2-3 个）
api_client = create_client(host="api.example.com", port=8080, timeout=30)
# 改进后 - 通过配置文件
config = load_config("configs/default.yaml")
api_client = create_client(config.api.host, config.api.port, config.api.timeout_seconds)
每个子代理完成后必须写入进度文件
// memory/organize-progress.json (由主会话创建和维护)
{
"project": "E:\\LPR",
"started_at": "2026-04-28T00:00:00+08:00",
"phases": {
"create-structure": {"status": "completed", "files_created": [".gitignore"]},
"move-files-phase1": {"status": "in_progress"},
...
},
"resumable": true,
"last_checkpoint": "2026-04-28T00:05:00+08:00"
}
主会话在启动时检查进度：
memory/organize-progress.json 且包含未完成阶段 - 跳过已完成阶段，继续执行剩余任务
核心原则：仅在用户选择全面重构策略时执行深度代码质量检查
对每个类用以下自检问题检验：
[]、空字典 {} 等；仅在语义上确实可能缺失时才用 Optional[Type]
注释是"必要的恶"。优先选择重命名而非写注释。仅以下情况应添加注释：
公共函数/方法必须添加，遵循以下格式：
def fetch_user(user_id: int, include_deleted: bool = False) -> User | None:
"""Fetch a user by ID with optional deleted flag."""
...
class DataProcessor:
"""Efficiently processes and batches input records.
This class handles filtering, transformation, and batching of data.
It is designed to be subclassed for custom processing pipelines.
Attributes:
batch_size: Number of records per batch (default: 32).
shuffle: Whether to shuffle the dataset every epoch.
num_workers: Number of parallel workers for data loading.
Example:
>>> processor = DataProcessor(batch_size=64, shuffle=True)
>>> for batch in processor:
... print(len(batch))
"""
from .models.resnet import ResNet50），而非 import models.resnet
所有 4 级策略均生成三份文档（README.md、MODIFICATIONS.md、NOTE.md），区别在于详尽程度
| 策略级别 | README.md | CHANGELOG.md | NOTE.md |
| ------------ | ------------------------------------------- | ---------------------------------- | ------------------------------------ |
| 轻量清理 | 1-2 句话的项目说明 | 仅列出修改的文件 | 1-2 句话的项目用途 |
| 标准整理 | 标准模板（Features + Quick Start） | 列出修改类别和关键变更 | 标准模板（用途 + 快速开始 + 技术栈） |
| 深度重构 | 完整模板（Features + 结构 + 配置 + 许可证） | 详细变更记录 + 验证清单 | 完整模板（含常用配置表） |
| 全面重构 | 完整模板 + 架构图/流程图 | 详细记录 + 常见问题排查 + 验证清单 | 完整模板 + 注意事项 |
~~~markdown
[简短的项目描述 - 一句话概括项目目的]
[新的目录结构树]
pip install -r requirements.txt
python main.py --config configs/default.yaml
~~~
## Configuration
[配置文件说明]
## License
[许可证信息，如已知]
要求：简洁明了，面向最终用户或使用者
# Modifications Log
## Directory Restructuring
- Moved `model.py` to `models/definition.py`
- Created `utils/helpers.py` from scattered functions
- ...
## Code Style Changes
- Renamed variable `raw_data` to `parsed_records` (semantic naming)
- Added type annotations to [N] functions
- Reorganized imports in [N] files
- ...
## Cleanup
- Removed unused import: `os.path.join` (replaced by `pathlib`)
- Consolidated duplicate validation logic into `utils/validators.py`
- ...
## Comment Updates
- Added docstrings to [N] functions
- Standardized comment format across all files
## Troubleshooting Notes（常见问题排查）
### 问题 1: [错误描述]
**原因**: [根本原因分析]
**解决**: [解决方案步骤]
---
验证清单：
- [x] 所有 import 路径已更新
- [x] 类型提示已添加
要求：具体、可追溯，列出实际变更项。轻量策略可简化为文件列表
~~~markdown
[用一两句中文概括这个项目是做什么的、解决什么问题]
# 安装依赖
pip install -r requirements.txt
# 基本使用示例
python main.py [options]
~~~
## 常用配置（按需调整）
| 配置项 | 说明 |
| -------- | ------------------------------ |
| [配置 A] | [默认值/建议范围] - [简要用途] |
| [配置 B] | [默认值/建议范围] - [简要用途] |
## 技术栈
- [技术栈描述，如 Python + Flask / Node.js / etc.]
要求：保持精简（不超过一页），中文撰写，只包含核心使用信息。不要包含修改记录、常见问题排查、代码改进说明等内容
| 文件 | 侧重 |
|------|--------|
| README.md | 是什么 + 怎么用 - 面向外部用户 |
| CHANGELOG.md | 改了什么 - 变更历史记录 |
| NOTE.md | 项目概况 - 个人快速参考 |
避免内容重复：README 不记录修改细节，MODIFICATIONS 不解释功能用途，NOTE 不做详细技术文档
针对深度学习项目的额外考虑（如适用）：
models/ 目录下按架构分类（如 models/resnet.py, models/custom_net.py）
data/ 或 datasets/，区分预处理和原始数据路径
experiments/ 目录存放训练脚本、checkpoint、日志
configs/ YAML 文件
logging 或 loguru）
针对 Web/API 项目的额外考虑：
routes/users.py, routes/orders.py）
针对命令行工具和 ETL 管道的额外考虑：
__init__.py，也不需要 __all__
__init__.py 不应包含业务逻辑，仅用于重新导出子模块的公开接口
__all__ 显式声明公共 API - 不在列表中的 symbol 视为私有
```python
# __init__.py
from .user_service import UserService
from .auth import AuthProvider
__all__ = ["UserService", "AuthProvider"]
- 消费者应 `import package` 然后使用公开符号，而非直接 `import package.inner_module`
### B. src/ vs Flat Layout - 决策框架
| 特征 | src/ layout（推荐） | Flat layout |
| ------------ | ------------------------------------------------- | ---------------------------------------- |
| **适用场景** | 库、可发布项目、测试需要模拟包导入 | 简单脚本、一次性分发/Notebook |
| **优点** | 防止误用未安装包运行；`pip install -e .` 行为一致 | 结构简单，路径简单 |
| **缺点** | 多一层目录嵌套 | 开发时可能无意中导入本地模块而非安装的包 |
- **深度重构及以上策略** - 建议使用 `src/` layout：`src/package_name/` + `tests/`
- **轻量/标准策略 / Flat Layout** - 保持扁平结构即可（如 `main.py`, `utils.py`, `config.yaml`）
- 现有 flat 项目无需强制迁移，除非有明确的包隔离需求
### C. Layered Architecture - 分层架构（全面重构策略）
- **轻量/标准/深度重构策略** - **不要强行拆分多层**。保持现有结构或轻度重组即可
- **全面重构策略且涉及多模块交互时**，按技术栈分层（从高层到低层），依赖只能单向向下：
api/ # FastAPI/Flask 路由、请求/响应模型
services/ # 业务逻辑入口点，调用 repositories
repositories/ # 数据访问层，与数据库/外部 API 交互
models/ # Pydantic 模型 / SQLAlchemy ORM
schemas/ # DTOs, input validation schemas
config/ # 配置加载、环境管理
- 每层只能 `import` 下层模块，禁止跨层或反向导入
- 通过依赖注入（构造函数参数）而非全局实例来耦合层间关系
### D. Domain-Driven Organization（DDD 风格，全面重构策略）
当项目复杂度较高且用户选择全面重构策略时，按业务域划分而非技术层：
users/ # 用户域
├── models.py # 领域模型
├── services.py # 领域服务
└── api.py # API 端点
orders/ # 订单域
...
shared/ # 跨域的公共基础设施（日志、缓存等）
- DDD 结构适用于团队多人协作的大型项目
- 轻量/标准/深度重构策略仍推荐传统的 layered architecture，避免过度工程化
### E. 模块粒度 - "一个概念一个文件"（深度重构及以上策略）
- **拆分阈值**：单个文件超过 300-500 行或处理多个不相关职责时应拆分为独立文件
- **文件命名**：`snake_case`、描述性强（如 `user_repository.py`，而非 `repo.py`）
- **类名与文件名匹配**：`UserService` 应放入 `user_service.py`
### F. 测试组织 - Co-located vs Parallel（深度重构及以上策略）
- **轻量/标准策略** - **不写单元测试**
- 深度重构及以上策略
\- 两种策略任选其一并在整个项目中保持一致：
| 策略 | 结构 | 适用场景 |
| ---------------------- | ------------------------------------- | --------------------------------- |
| **Co-located**（推荐） | `tests/test_<module>.py` 与源码同目录 | 小型项目、测试逻辑与实现紧密相关 |
| **Parallel directory** | `tests/` 镜像 `src/` 目录结构 | 大型项目、CI 需要独立运行所有测试 |
### G. pyproject.toml - 工具链配置（全面重构策略，或发布为库时）
- **轻量/标准/深度重构策略** - 不需要。脚本直接运行即可
- **全面重构策略 / 需要发布到 PyPI 的项目**：在根目录创建 `pyproject.toml`
[tool.ruff]
line-length = 120
target-version = "py311"
[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "UP", "SIM"]
[tool.ruff.lint.per-file-ignores]
"tests/*/" = ["S101"] # allow assert in tests
"__init__.py" = ["F401"] # unused imports are re-exports by convention
[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false # production code: true; tests: override to false
------
## ⚠️ 避免过度工程化 - 具体禁令
以下行为**不应默认执行**，仅在用户明确选择对应策略级别或明确提出需求时才执行：
1. **不要为只有几个变量的脚本创建 YAML/TOML 配置文件 + argparse CLI** - inline 参数更简单（除非用户选择深度重构及以上策略）
2. **不要将简单的函数拆分成多个子函数以符合 4-10 行规则** - 保持逻辑完整性优先于行数限制（除非用户选择全面重构策略）
3. **不要在扁平布局的项目中强制创建 `__init__.py` + `__all__`** - 除非用户选择深度重构及以上策略
4. **不要对只有一个类的文件做 SRP/OCP/LSP/ISP/DIP 分析** - OOP 原则只在存在继承和多态关系时才适用（除非用户选择全面重构策略）
5. **不要为只有几个文件的深度学习/数据处理项目创建完整的分层架构或 DDD 结构** - 除非用户选择全面重构策略
6. **不要在原型代码中强制要求单元测试和覆盖率阈值** - 除非用户选择深度重构及以上策略
7. **不要对只有一两个使用者的内部工具生成 README + MODIFICATIONS + NOTE 三份文档** - 除非用户选择对应策略级别
8. **不要将 `main.py` 强行塞进 `src/package_name/` 的目录结构中** - src layout 只对库或大型应用有意义（除非用户选择深度重构及以上策略）
> **核心原则：优化是为了让人更容易理解和维护代码，不是为了达到最佳实践。如果改动让项目变得更复杂而不是更简单，那就做过头了。用户的策略选择是最终决定**
共 4 个版本