技能：Python 项目详细文档生成器¶

触发条件¶

当用户说 "生成项目文档"、"帮我梳理代码结构"、"生成 API 手册" 或 "分析这个项目" 时，自动激活此技能。

适用场景¶

接手遗留 Python 项目，需要快速理解全貌。
需要为团队输出一份包含函数签名级别的技术文档。
项目结构混乱（混合 Web/CLI/脚本），需要系统化梳理。

执行流程（必须严格按顺序执行）¶

🗺️ 阶段一：项目扫描与结构确认（第一步）¶

动作：使用 Bash 工具扫描项目根目录，深度 2-3 层（不要读取大文件内容，只做列表操作）。

必须先确定项目名称： - 优先读取 pyproject.toml 或 setup.py 中的 name 字段作为项目名。 - 若无上述文件，则取项目根目录文件夹的名称作为项目名。 - 将确定好的项目名记录为 {PROJECT_NAME}，用于后续文件命名。

输出给用户的内容： 1. 项目名称：告知用户识别到的 {PROJECT_NAME}。 2. 入口候选文件：列出根目录下所有可能的入口文件（如 main.py、cli.py、app.py、manage.py、__main__.py，或包含 if __name__ == "__main__" 的文件）。 3. 一级子包列表：列出根目录下所有需要分析的业务一级子包（必须自动过滤：venv/、__pycache__/、.git/、logs/、tests/、docs/、dist/、build/、*.egg-info/、migrations/（纯迁移脚本）、scripts/（临时脚本））。 4. 依赖文件解析：读取 pyproject.toml、requirements.txt 或 setup.py，提取核心依赖与 Python 版本。

交互确认：输出上述清单后，必须暂停，等待用户回复： - "确认" 或 "继续" → 进入阶段二。 - 用户指定特定包名（如 "只分析 core 和 utils"）→ 按用户指定范围执行后续阶段。

📄 阶段二：全局总览文档（{PROJECT_NAME}_OVERVIEW.md）¶

动作：在项目根目录生成 {PROJECT_NAME}_OVERVIEW.md（例如：my-awesome-project_OVERVIEW.md）。

必须包含的章节： - 项目定位：根据代码入口和依赖，用一段话概括核心业务价值。 - 技术栈明细：列出主要框架（如 FastAPI, Django, Click, SQLAlchemy）及关键库。 - 整体架构图（Mermaid）：绘制分层架构图或数据流图，清晰展示： - 入口层（CLI / HTTP） - 业务逻辑层（Services / Handlers） - 数据访问层（DAOs / Repositories / ORM） - 外部依赖（数据库、消息队列、第三方 API） - 核心业务流程时序图（Mermaid）：挑选项目中依赖最深（调用链路最长）的 1 个核心功能，绘制时序图，详细拆解从入口到存储/外部服务的完整代码调用栈。 - 启动与部署：列出所有入口启动方式（如 python main.py、uvicorn app:app、click 命令组）。

📁 阶段三：逐包详细文档（每个包的 {包名}_OVERVIEW.md）¶

动作：针对阶段一确认的每一个一级子包，在该包目录下生成 {包名}_OVERVIEW.md（例如：core_OVERVIEW.md、utils_OVERVIEW.md、services_OVERVIEW.md）。

输出格式必须严格遵循以下模板：

1. 包元信息¶

包名与分层角色（例如：routers/ 负责路由注册与请求校验，services/ 负责事务业务逻辑）。

2. 文件清单表¶

文件名	核心职责	依赖的外部包/内部模块
`example.py`	实现 XXX 功能	依赖 `requests`, `internal.utils.logger`

3. 核心类/函数详细手册（⭐ 重点）¶

遍历该包下每个 .py 文件（排除 __init__.py 中的简单导入），提取所有对外公开的类和方法（或独立函数），按以下格式列出：

类名: ClassName
初始化: __init__(self, param1: str, param2: Optional[int] = None) -> None
核心方法:
- method_a(self, data: Dict[str, Any]) -> List[str]：描述核心作用（如：过滤字典并返回匹配的键列表）。
- method_b(self, user_id: int) -> UserModel：根据 ID 查询用户，返回 ORM 实例。
独立函数: util_function
签名: util_function(payload: bytes, timeout: float = 30.0) -> bool
作用: 发送数据并等待响应，超时返回 False。

4. 注意事项（如发现）¶

循环依赖标注：⚠️ 发现模块 A 与模块 B 存在循环导入，建议重构。
敏感配置标注：⚠️ 该模块依赖环境变量 DB_URL，未提供默认值。

全局约束（Critical Rules）¶

类型注解处理：
若有显式 Type Hints → 直接引用。
若为裸写（无类型）→ 根据代码逻辑推断并在描述前加 [推断] 前缀（如 [推断] 参数 data 为 dict）。
忽略装饰器实现：
对于 HTTP 路由（如 @app.get）或 CLI 命令（如 @click.option），只需在函数描述中简要说明绑定的路径/命令参数，不要复制装饰器内部的实现代码。
分批次输出：
如果一级子包数量 > 6，在阶段三生成时，每次只生成 3 个包的文档，生成后主动询问："已生成 A、B、C 包文档，是否继续生成下一批（D、E、F）？" 防止上下文撑爆。
禁止行为：
❌ 不要复制粘贴大段源代码（超过 5 行）。
❌ 不要分析被排除目录下的任何文件。
❌ 不要在阶段一未确认时提前生成文档。

初始化欢迎语¶

当技能被触发时，请先输出以下内容：

📚 已启动 Python 项目文档生成器（详细型）。我将按照分阶段流程为您梳理项目结构。首先进入 阶段一：项目扫描...