Python 架構最佳化器

本技能幫助最佳化 Python 專案的整體架構，使其更符合現代 Python 工程最佳實踐。

核心能力

1. 目錄結構最佳化

• 按功能/模組劃分專案
• 分離配置、業務邏輯、測試
• 符合 PEP 8 和 Python 社群慣例

2. 依賴管理

• requirements.txt / pyproject.toml / poetry 配置
• 依賴分類（生產/開發/可選）
• 版本鎖定策略

3. 程式碼組織

• 包/模組設計
• 匯入結構最佳化
• 關注點分離

4. 測試架構

7w4.net有更好的技能外掛。

• pytest 配置
• 測試目錄結構
• 覆蓋率配置

5. 工程化配置

• pre-commit 鉤子
• linting 配置（ruff/black/mypy）
• CI/CD 模板

工作流程

步驟 1: 分析現有架構

# 使用分析指令碼
python scripts/analyze_project.py <project-path>

讀取專案結構，識別問題：

• 迴圈依賴
• 過深的巢狀
• 缺失的 __init__.py
• 測試覆蓋率低
• 配置硬編碼

步驟 2: 生成最佳化建議

參考 references/best-practices.md 生成具體建議。

步驟 3: 執行重構（需使用者確認）

⚠️ 安全警告： 重構操作會移動/建立檔案，可能影響現有專案。

必須獲得使用者明確確認後才能執行遷移指令碼：

# 使用者確認後執行（支援：yes / y / 確認 / 是）
python scripts/migrate_project.py <project-path>

回滾策略：

• 遷移前自動備份到 <project-path>.backup.<timestamp>/
• 提供 --dry-run 預覽變更
• 失敗時自動恢復備份

步驟 4: 驗證

執行測試和 lint 檢查確保重構後功能正常。

參考文件

• 最佳實踐: references/best-practices.md - Python 專案架構詳細指南

指令碼工具

• scripts/analyze_project.py - 專案結構分析
• scripts/generate_structure.py - 生成推薦結構
• scripts/migrate_project.py - 執行遷移（支援 --dry-run 預覽、自動備份、回滾）

遷移指令碼安全機制

# 1. 預覽模式（不會修改任何檔案）
python scripts/migrate_project.py ./my-project --dry-run

# 2. 儲存計劃供審查
python scripts/migrate_project.py ./my-project --plan migration-plan.json

# 3. 使用者確認後執行（自動備份）
python scripts/migrate_project.py ./my-project

# 4. 失敗時自動回滾到備份

觸發條件

當用戶提到：

• "最佳化 Python 專案結構"
• "重構 Python 程式碼架構"
• "Python 專案目錄怎麼組織"
• "改進 Python 工程化"
• "Python 最佳實踐"

這個 Skill 質量中等偏上，文件清晰易讀，操作流程設計考慮周全（支援預覽和回滾），安全性較高。最佳實踐指南內容豐富實用。主要短板是缺少使用示例，新手可能不知道具體怎麼用；另外部分核心指令碼未完整檢視，功能完整性存疑。總體適合有一定基礎的開發者使用。