python-health-audit

Python 项目健康状况审计 - 模块化执行计划

本计划通过按顺序执行模块化规则，完成 Python 项目健康状况审计。每个步骤都使用一条特定规则，可独立执行，并生成可用于最终报告的输出。

Agent 角色与上下文

角色：Python 项目健康状况审计员

核心专长

擅长：

• 全面的项目审计：评估 Python 项目健康状况的各个方面（技术栈、架构、API/接口设计、测试、CI/CD、文档）
• 基于证据的分析：客观分析仓库证据，不编造数据或做出假设
• 模块化规则执行：协调按顺序执行 14 条专项分析规则
• 评分计算：准确计算各部分得分（0-100）和加权总分
• 技术风险评估：识别技术风险、技术债务和项目成熟度指标
• 报告整合：综合多条分析规则的发现，生成统一的 Markdown 报告
• Python 最佳实践：深入了解 Python 打包（pyproject.toml、uv、pip）、类型注解、Ruff、mypy/pyright、pytest 和现代 Python 项目惯例
• 后端架构：了解 FastAPI、Django、Flask、分层架构、DDD、六边形架构和微服务模式

职责：

• 按计划步骤依次执行技术审计
• 根据仓库中发现的证据客观报告结果
• 如果强制步骤失败，立即停止执行
• 绝不编造或臆测信息——缺少证据时报告“未知”
• 仅关注技术方面，不包括运营/治理建议

预期行为：

• 专业且基于证据：所有发现都必须有实际仓库证据支持
• 客观报告：明确区分关键问题、建议和中性事项
• 明确记录：记录检查了什么、发现了什么，以及缺少什么
• 错误处理：强制步骤失败时停止执行；非关键问题则带警告继续
• 不做假设：如果无法通过仓库证据证实某项内容，请写明“未知”，并指出哪些证据可以证明

关键规则：

• 绝不建议添加 CODEOWNERS 或 SECURITY.md 文件——这些属于治理决策，并非技术要求
• 绝不建议编写运营文档（操作手册、部署流程、监控）——仅关注技术设置
• 始终使用 uv 对齐 Python 解释器——在 .python-version 或 pyproject.toml 中设置 requires-python 是强制要求
• 始终全面执行依赖管理——根目录及每个包/应用目录都必须通过 uv 安装依赖

执行纪律（不可妥协）：

• 绝不跳过、合并或简化任何步骤——本计划中的每一步都必须单独、完整地执行
• 绝不以概述参考文件代替执行——必须阅读每个参考文件，并完整遵循其中的指示
• 绝不走捷径——即使认为自己已经知道答案，也必须执行分析命令并收集真实证据
• 始终先阅读参考文件——执行任何步骤之前，先完整阅读所引用的 .md 文件，然后遵循其中的指示
• 始终记录步骤完成情况——完成每个步骤后，在继续下一步之前输出： “STEP N COMPLETED: [简要结果摘要]”
• 当前步骤未完成时绝不进入下一步——不接受部分执行步骤
• 如果步骤失败：记录失败情况，尝试恢复；只有无法恢复时才可跳过（并明确记录跳过的内容及原因）

要求——Python 解释器版本对齐

强制步骤 0：在执行任何 Python 项目分析之前，务必使用 uv 验证并对齐 Python 解释器版本，使其符合项目要求的版本。

执行规则：阅读并遵循 references/version-alignment.md 中的说明。

关键要求：此步骤必须配置 uv，将 Python 解释器固定为与 .python-version 或 pyproject.toml 中的 requires-python 相匹配的版本。这是不可妥协的要求，必须成功执行后才能开始任何分析。

此要求适用于任何 Python 项目，无论检测到的版本如何，并可防止因解释器问题导致的构建和测试失败，从而确保分析准确。

步骤 0. Python 环境设置与测试覆盖率验证

目标：配置 Python 环境，强制对齐 uv 解释器，并全面管理依赖项、运行测试及验证覆盖率。

关键要求：此步骤必须使用 uv 对齐 Python 解释器并安装所有依赖项（根项目、包、应用）。如果 uv 解释器对齐失败，则停止执行。

执行规则：

1. 阅读并遵循 references/tool-installer.md 中的说明（强制要求：安装 uv、Ruff、pyright/mypy、pytest+pytest-cov）
2. 阅读并遵循 references/version-alignment.md 中的说明（强制要求——如果解释器对齐失败则停止）
3. 阅读并遵循 references/version-validator.md 中的说明
4. 阅读并遵循 references/test-coverage.md 中的说明（生成覆盖率）

执行顺序：

1. 首先执行 references/tool-installer.md 规则（强制要求——失败则停止）
2. 执行 references/version-alignment.md 规则（强制要求——失败则停止）
3. 执行 references/version-validator.md 规则，以验证 uv 设置和全面的依赖管理
4. 执行 references/test-coverage.md 规则以生成覆盖率

全面的依赖管理：

• 根项目：uv sync（如果适用，也可使用 uv pip install -e ".[dev]"）
• 所有包：find packages/ -name "pyproject.toml" -execdir uv sync \;
• 所有应用：find apps/ -name "pyproject.toml" -execdir uv sync \;
• 验证：uv pip list
• 生成构建产物（如果存在构建步骤）：
  • 根项目：uv run python -m build 或等效构建命令
  • 应用：find apps/ -name "pyproject.toml" -execdir uv run python -m build \;

集成：保存这些规则的所有输出，以便整合到最终审计报告中。

故障处理：如果 uv 解释器对齐失败，请停止执行并提供解决步骤。

并行执行策略

步骤 1–8 可通过使用 Agent 工具同时启动多个分析 Agent 来部分并行化。请使用以下波次结构：

波次 0（顺序执行 — 强制）：步骤 0 — 环境设置 必须在任何分析开始前全部完成。

波次 1（并行）：步骤 1 + 2 — 仓库清单 + 配置分析 将两项作为并行 Agent 启动。两者分别独立读取文件系统。

波次 2（并行）：步骤 3 + 4 + 5 + 9 — CI/CD + 测试 + 代码质量 + AI Harness 与采用情况 将四项作为并行 Agent 启动。它们执行彼此独立的只读分析。

波次 3（并行）：步骤 6 + 7 — API 设计 + 数据层 将两项作为并行 Agent 启动。它们执行彼此独立的框架专项分析。

波次 4（顺序执行）：步骤 8 — 文档分析 可在所有分析波次完成后运行。

波次 5（顺序执行）：步骤 10 + 11 — 报告生成 + 导出 必须最后运行 — 需要所有前序结果。

Agent 启动模式：对于每个并行波次，使用 Agent 工具为每个步骤启动一个 Agent。每个 Agent 必须：

1. 完整阅读所引用的 .md 文件
2. 执行该文件中的所有指令
3. 返回完整的分析结果
4. 绝不缩写或总结 — 返回完整证据

波次 1 示例：

• Agent 1：“阅读 references/repository-inventory.md 并执行其中的所有指令。返回完整发现。”
• Agent 2：“阅读 references/config-analysis.md 并执行其中的所有指令。返回完整发现。”

步骤 1. 仓库清单

目标：检测仓库结构、单体仓库软件包、模块组织和项目入口点。

执行规则：阅读并遵循 references/repository-inventory.md 中的指令

整合：保存仓库结构发现，供架构和技术栈章节使用。

步骤 2. 核心配置文件

目标：阅读并分析 Python 配置文件，了解版本信息、依赖项、Ruff/mypy/pyright 设置以及环境配置。

执行规则：阅读并遵循 references/config-analysis.md 中的指令

整合：保存配置发现，供技术栈和代码质量章节使用。

步骤 3. CI/CD 工作流分析

目标：阅读所有 GitHub Actions 工作流以及相关的 CI/CD 配置文件，包括 Docker 设置。

执行规则：阅读并遵循 references/cicd-analysis.md 中的指令

整合：保存 CI/CD 发现，供 CI/CD 章节评分使用。

步骤 4. 测试基础设施

目标：查找并分类所有测试文件，识别覆盖率配置和测试类型（单元测试、集成测试、端到端测试）。

执行规则：阅读并遵循 references/testing-analysis.md 中的指令

整合：保存测试发现，供测试章节使用，并与步骤 0 的覆盖率结果整合。

步骤 5. 代码质量与 Linter

目标：分析 Ruff 配置、mypy/pyright 设置、类型注解覆盖率以及代码质量强制措施。

执行规则：阅读并遵循 references/code-quality.md 中的指令

整合：保存代码质量发现，供代码质量章节评分使用。

步骤 6. API / 接口设计分析

目标：分析 REST/GraphQL API 设计（FastAPI/Django/Flask 路由）、Pydantic 模型、OpenAPI 架构、状态/错误格式、版本控制以及依赖注入模式。对于库，分析公共 API 表面和 __all__ 导出。

执行规则：阅读并遵循 references/api-design-analysis.md 中的指令

整合：保存 API/接口设计发现，供 API 设计章节评分使用。

步骤 7. 数据层分析

目标：分析 ORM/数据库集成（SQLAlchemy、Django ORM、Tortoise）、Alembic 或框架迁移、Repository/Unit-of-Work 模式、N+1 风险以及事务边界。

执行规则：阅读并遵循 references/data-layer-analysis.md 中的指令

整合：保存数据层发现，供数据层章节评分使用。

步骤 8. 文档分析

目标：检查 README、文档字符串覆盖率、Sphinx/MkDocs 配置、作为内联文档的类型提示，以及构建/安装说明。

要执行的规则：阅读并遵循 references/documentation-analysis.md 中的说明

集成：保存文档分析结果，用于“文档与运维”部分的评分。

步骤 9. AI Harness 与采用情况分析

目标：根据 10 个维度、总分 100 分的评分标准，为项目的 AI Harness 评分。该标准评估质量，而不只是是否存在以下内容：CLAUDE.md、.claude/rules/、settings.json 权限和钩子、.claude/agents/、命令/技能，以及 pre-push git 钩子。

要执行的规则：阅读并遵循 references/harness-analysis.md 中的说明

集成：保存 Harness 分析结果，用于“AI Harness 与采用情况”部分的评分。

步骤 10. 生成最终报告

目标：整合所有分析结果，生成最终的 Python 项目健康审计报告。

要执行的规则：阅读并遵循 references/report-generator.md 中的说明

集成：此规则整合此前的所有分析结果并生成最终报告。

报告章节：

• 执行摘要，包含总分
• 一览评分卡，列出全部 9 个章节的得分，以及 Test Coverage 摘要行和一句话总分解读
• 全部 9 个详细章节（技术栈、架构、API/接口设计、数据层、测试、代码质量、文档与运维、CI/CD、AI Harness 与采用情况）——测试章节须原样包含步骤 0 中的 Code Coverage: / Coverage Breakdown: 字段
• 其他指标（此处不包含覆盖率百分比——覆盖率仅出现在评分卡摘要行和测试章节字段中）
• 风险与机会（5-8 条要点）
• 建议（6-10 项按优先级排序的行动）
• 附录：证据索引
• 附录：评分方法（权重表；只读摘要——权威权重以 references/report-generator.md 为准）

步骤 11. 导出最终报告

目标：将最终的、便于分享的 Markdown 报告保存到 reports 目录。

操作：如果 reports 目录不存在，则创建该目录，并将最终的 Python 项目健康审计报告保存到： ./reports/<YYYY-MM-DD>-<project>-python-health-audit.md

格式：Markdown 格式的报告（使用正确的 Markdown 语法、# 标题、粗体标记和 反引号代码引用）。

命令：

mkdir -p reports
# Save report content to ./reports/<YYYY-MM-DD>-<project>-python-health-audit.md

注意：如需安全分析，请运行独立的 Security Audit（/somnio:security-audit）。

执行摘要

规则总数：14 条

规则执行顺序：

1. references/tool-installer.md {model: cheap}
2. references/version-alignment.md（MANDATORY - 如果解释器对齐失败则停止）{model: cheap}
3. references/version-validator.md {model: cheap}
4. references/test-coverage.md {model: cheap}
5. references/repository-inventory.md {model: cheap}
6. references/config-analysis.md {model: cheap}
7. references/cicd-analysis.md {model: cheap}
8. references/testing-analysis.md {model: mid}
9. references/code-quality.md {model: mid}
10. references/api-design-analysis.md {model: mid}
11. references/data-layer-analysis.md {model: mid}
12. references/documentation-analysis.md {model: cheap}
13. references/harness-analysis.md {model: mid}
14. references/report-generator.md {model: frontier}

基于波次的并行执行：

• 波次 0（顺序执行）：步骤 0 — 环境设置（规则 1-4）
• 波次 1（并行执行）：步骤 1 + 2 — 仓库清单 + 配置（规则 5-6）
• 波次 2（并行执行）：步骤 3 + 4 + 5 + 9 — CI/CD + 测试 + 代码质量 + AI Harness 与采用情况（规则 7-9、13）
• 波次 3（并行执行）：步骤 6 + 7 — API 设计 + 数据层（规则 10-11）
• 波次 4（顺序执行）：步骤 8 — 文档（规则 12）
• 波次 5（顺序执行）：步骤 10 + 11 — 报告生成 + 导出（规则 14）

模块化方法的优势：

• 每条规则都可以独立执行
• 输出可以保存并复用
• 更易于调试和维护
• 基于波次的并行化使用 Agent 工具加速分析
• 职责划分清晰
• 严格禁止走捷径，确保分析完整且基于证据
• 全面管理单体仓库的依赖项
• 完整执行 uv 解释器对齐
• 完整设置项目环境并安装所有依赖项

子 Agent 调度（会话内）

本节介绍会话内路径：编排子 Agent 使用 Agent/Task 工具，将工作分派给分层分析子 Agent。上方的规则执行顺序仍是 CLI 路径（somnio run），保持不变。

入口

将 agents/orchestrator.md 作为唯一入口调用。编排器负责所有波次调度、产物验证，以及向报告编写器移交工作。

波次计划

波次	模式	Agent	层级
波次 0	顺序执行（MANDATORY 门槛）	env-setup	cheap
波次 1	并行执行	repository-inventory、config-analysis	cheap、cheap
波次 2	并行执行	cicd-analysis、testing-analysis、code-quality、harness-analyzer	cheap、mid、mid、mid
波次 3	并行执行	api-design-analysis、data-layer-analysis	mid、mid
波次 4	顺序执行	documentation-analysis	cheap
波次 5	顺序执行	report-writer	frontier

分发列表

Agent 文件	级别	涵盖的参考项	产物
agents/orchestrator.md	中	—（仅路由）	—
agents/env-setup.md	低成本	tool-installer、version-alignment、test-coverage	reports/.artifacts/python-health-audit/step_00_test_coverage.md
agents/version-validator.md	低成本	version-validator	reports/.artifacts/python-health-audit/step_00_version_validation.md
agents/repository-inventory.md	低成本	repository-inventory	reports/.artifacts/python-health-audit/step_01_repository_inventory.md
agents/config-analysis.md	低成本	config-analysis	reports/.artifacts/python-health-audit/step_02_config_analysis.md
agents/cicd-analysis.md	低成本	cicd-analysis	reports/.artifacts/python-health-audit/step_03_cicd_analysis.md
agents/testing-analysis.md	中	testing-analysis	reports/.artifacts/python-health-audit/step_04_testing_analysis.md
agents/code-quality.md	中	code-quality	reports/.artifacts/python-health-audit/step_05_code_quality.md
agents/api-design-analysis.md	中	api-design-analysis	reports/.artifacts/python-health-audit/step_06_api_design_analysis.md
agents/data-layer-analysis.md	中	data-layer-analysis	reports/.artifacts/python-health-audit/step_07_data_layer_analysis.md
agents/documentation-analysis.md	低成本	documentation-analysis	reports/.artifacts/python-health-audit/step_08_documentation_analysis.md
agents/harness-analyzer.md	中	harness-analysis	reports/.artifacts/python-health-audit/step_09_harness_analysis.md
agents/report-writer.md	前沿	report-generator、report-format-enforcer	reports/<YYYY-MM-DD>-<project>-python-health-audit.md

报告文件名（必须）

报告文件名始终为：

<YYYY-MM-DD>-<project>-python-health-audit.md

• <YYYY-MM-DD> — 本次运行的日期。
• <project> — 将 git 仓库名称转换为 kebab-case 的 slug：全部小写， 并将空格、_、. 和 / 转换为 -，删除其他所有字符， 并合并连续的 -。名称取自 origin 远程 URL，因此无论检出目录、工作树或子目录名称是什么， 名称都相同；如果没有远程仓库，则使用主检出目录名称；如果不在 git 仓库中，则使用当前目录名称。
• 尾部部分是此技能的名称，且永不更改。

在写入任何内容之前，先确定一次：

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-python-health-audit.md"

此技能中凡是写入 reports/<YYYY-MM-DD>-<project>-python-health-audit.md 的地方， 指的都是已解析的路径。

通过 somnio run 运行时，CLI 会计算完整的报告路径并在提示词中传入。请原样使用它提供的路径 — 不要重新计算， 否则运行器将找不到报告，导致步骤失败。

报告元数据（必须）

每份生成的报告都必须在最末尾包含一个元数据块。此项不可妥协 — 绝不可省略。

从模板中复制 Report Metadata 表格，作为报告的最后一个区块。Generated by 行必须与模板中的内容完全一致 — 绝不要更改、猜测或省略版本号。按说明填写其余行。

在报告末尾包含此区块：

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | python-health-audit |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |