python-code-quality

Python 代码质量

快速命令

所有命令均从 python/ 目录运行：

# Syntax formatting + checks (parallel across packages by default)
uv run poe syntax
uv run poe syntax -P core
uv run poe syntax -F    # Format only
uv run poe syntax -C    # Check only
uv run poe syntax -S    # Samples only

# Type checking
#
# Division of labor (see "Type checking architecture" below):
#   - Pyright (strict) is the source-code type checker.
#   - Pyright (relaxed `basic`), mypy, pyrefly, ty, zuban all check the TESTS;
#     pyright/pyrefly/ty also check the SAMPLES (mypy/zuban skip script-style samples).
uv run poe pyright       # Pyright (strict) over SOURCE, fan-out across packages
uv run poe pyright -P core
uv run poe pyright -A
uv run poe test-typing   # mypy + pyrefly + ty + zuban + pyright over each package's TESTS
uv run poe test-typing -P core
uv run poe test-typing -S                       # samples (pyrefly + ty + pyright)
uv run poe test-typing -P core --checker mypy   # narrow to one checker (repeatable)
uv run poe test-typing -P core --checker pyright # relaxed pyright over the tests
uv run poe mypy          # alias: MyPy over the tests only
uv run poe mypy -P core
uv run poe typing        # Pyright (source) + the tests checkers
uv run poe typing -P core
uv run poe typing -A

# All package-level checks in parallel (syntax + pyright)
uv run poe check-packages

# Full check (packages + samples + tests + markdown)
uv run poe check
uv run poe check -P core

# Samples only
uv run poe check -S
uv run poe pyright -S

# Markdown code blocks
uv run poe markdown-code-lint

Poe 和 pytest 工具链保留在跨版本开发环境中。Ruff 和类型检查器使用固定版本的 tooling/requirements-*.txt 文件；仅在需要时，才会从 tool-hooks 依赖组中选用 prek。

提交前钩子（prek）

Prek 钩子会在提交时自动运行。它们保持轻量，只检查有更改的文件。

# Install hooks
uv run poe prek-install

# Run all hooks manually
uv run --group tool-hooks prek run -a

# Run on last commit
uv run --group tool-hooks prek run --last-commit

它们会对有更改的包运行语法格式化/检查，仅在 Markdown 文件有更改时运行 Markdown 代码 lint，仅在 samples/ 下的文件有更改时运行示例语法 lint/pyright。 默认情况下，它们不会运行工作区级别的 pyright 或 mypy。

类型检查架构

遵循“类型检查器过多”的方法，按目标拆分类型检查器：

目标	检查器	模式	配置
源代码（agent_framework*）	pyright	strict	pyproject.toml 中的 [tool.pyright]
测试	pyright、mypy、pyrefly、ty、zuban	relaxed/basic	pyrightconfig.tests.json、[tool.mypy]、pyrefly.toml、ty 规则
示例	pyright、pyrefly、ty	basic	pyrightconfig.samples.json、pyrefly.samples.toml、ty.samples.toml

• Pyright 是唯一严格检查源代码的检查器，同时也会以宽松的 basic 配置检查测试和示例（因此，客户会复制使用的代码也会经过所有检查器验证，包括 pyright）。已从源代码检查中移除 MyPy；其 [tool.mypy] 配置块现在是仅用于测试/示例的宽松配置。
• 其他检查器会检查测试/示例，因为这些代码以用户的方式使用公共 API。配置特意保持宽松（允许访问私有内容、允许测试主体不带类型注解），这样作者就不必添加冗余的类型注解。
• 门禁检查器包括 pyright、mypy、pyrefly、ty 和 zuban，五种检查器默认都会运行，并作为 CI 门禁。zuban 是与 mypy 兼容的两种检查器中最严格的，因此相同的 [tool.mypy] 配置会产生更多发现；使用共享的 # type: ignore[code] 抑制仅由 zuban 引起的问题。使用 # pyright: ignore[rule] 抑制宽松 pyright 配置引起的问题。
• 示例在 pyrefly 和 ty 的基础上增加了 pyright——mypy/zuban 无法解析脚本式示例布局（带数字前缀的目录、重复的 main.py），但 pyright 可以处理。
• pyrefly.samples.toml 会启用回退查找，以处理独立的同级导入。 ty 示例配置使用一方依赖 root = ["."] 处理 PEP 723 同级辅助模块， 同时保留对现有示例的自动额外路径查找。
• 严格的源代码 pyright 配置（[tool.pyright]）会检查 reportUnnecessaryTypeIgnoreComment，并排除测试/示例；宽松的测试/示例 pyright 配置不会标记不必要的忽略注释。

Ruff 配置

• 行长度：120
• 目标：Python 3.10+
• 启用自动修复
• 规则：ASYNC、B、CPY、D、E、ERA、F、FIX、I、INP、ISC、Q、RET、RSE、RUF、SIM、T20、TD、W、T100、S
• 检查时排除脚本目录

Pyright 配置

• 源代码：严格模式（[tool.pyright]），reportUnnecessaryTypeIgnoreComment = "error"， 排除测试、示例、.venv、packages/devui/frontend。
• 测试：宽松的 basic 配置（pyrightconfig.tests.json）——允许导入/使用私有内容以及访问非必需的 TypedDict 字段；作为 test-typing 中的 pyright 检查器运行。
• 示例：宽松的 basic 配置（pyrightconfig.samples.json，另有 py310 变体）——作为 test-typing -S 中的 pyright 检查器运行。

并行执行

任务运行器（scripts/task_runner.py）使用 ThreadPoolExecutor 并行执行 （包 × 任务）的笛卡尔积。单项任务在进程内运行，并流式输出结果。

CI Workflow

CI splits into 4 parallel jobs:

1. Pre-commit hooks — lightweight hooks (SKIP=poe-check)
2. Package checks — syntax/pyright (source) via check-packages
3. Samples & markdown — check -S plus markdown-code-lint
4. Test Typing — change-detected mypy/pyrefly/ty over tests (ci-test-typing)