Table of contents

AGENTS.md

# AGENTS.md

新建 Python 项目以以下约定作为默认开发基线。维护已有项目时尊重现有结构和工具并渐进调整，不为统一规范而迁移。专项约定仅在项目具备对应职责时适用；除安全、敏感信息和对外兼容性要求外，可按实际需要取舍。

## 项目结构

新建可安装的 Python 项目优先考虑 `src` layout：

```text
src/
  <package_name>/
    config.py          # Pydantic Settings 统一配置入口（按需）
    main.py            # 应用入口，仅负责注册和启动（按需）
tests/
docs/
```

该结构是默认建议；`config.py` 和 `main.py` 适用于可运行的应用项目，纯库或简单脚本可以省略。内部目录按项目职责组织，不预建空目录或无实际用途的基础设施。

## 开发工作流

使用 `uv` 管理依赖和环境，工具配置优先放在 `pyproject.toml`。

常用命令：

```bash
uv sync --group dev
uv run ruff check .
uv run ruff format --check .
uv run pytest
```

类型检查从 ty 和 mypy 中选择一种：使用 ty 时运行 `uv run ty check .`，使用 mypy 时运行项目约定的命令，例如 `uv run mypy .`。除明确的迁移任务外，不同时引入两套检查器。

## 可执行规范

能由工具稳定验证的规则优先写入项目配置；无法机械判断的选择依据和工程边界使用文字约定，同一规则不重复维护。

- `pyproject.toml` 承载项目元数据、依赖以及 Ruff、pytest、类型检查和 Commitizen 等工具配置。
- 项目使用 pre-commit 时，在 `.pre-commit-config.yaml` 中配置快速、稳定的本地检查，并复用 `pyproject.toml`。
- CI/CD 配置沿用实际平台；使用 GitHub Actions 时可放在 `.github/workflows/ci.yml`，并复用本地命令。
- 实际执行的项目配置优先；发现配置与文字约定不一致时，同步更新相关约定和文档。

## 代码与注释

- 使用 `ruff` 做 lint 和格式化。
- 涉及 HTTP API 时，路由处理函数保持薄，只做协议接入和轻量编排。
- 业务流程、外部调用、模型推理、数据模型和基础配置按职责分离，并优先沿用现有边界。
- 公共 API、领域类和复杂函数使用 Google Style docstring；注释只解释不明显的意图和约束，避免重复代码。
- 只实现当前需求；抽象应服务于稳定概念、明确边界或需要同步变化的重复逻辑，不预留缺乏用例支撑的扩展点。
- 复杂度影响可读性和测试时拆分职责，必要时引入类型化数据对象；度量结果只作为重构信号，不作为机械门槛。

## 配置（按需）

使用 `pydantic-settings` 作为统一配置入口；`config.yaml` 保存分层的非敏感配置，`.env` 保存必要的 secrets 和环境差异并覆盖 YAML。

- 配置模型使用 `pydantic.Field`，嵌套结构与 YAML 层级对应；业务代码只访问配置模型。
- 提交 `config.yaml` 和 `.env.example`，不提交 `.env` 或真实凭据；生产必需配置缺失时明确失败。

## 依赖与外部资源

- 项目依赖优先使用 `uv add`、`uv remove` 管理；临时使用 `uv pip install` 的依赖应在提交前写入项目配置。
- `pyproject.toml` 与 uv 管理的 `uv.lock` 随依赖变更一同提交。
- 新依赖应有明确用途。Git 依赖固定到 tag 或 commit，不在依赖 URL 中写入凭据。
- 大型外部制品默认不入库，并记录来源和版本；确需版本控制时再使用 Git LFS。
- 外部调用设置有界超时；重试应有次数上限和退避策略，仅用于幂等或可安全重放的操作。

## SQL 数据库（按需）

仅在项目实际使用关系型数据库时采用。常规 FastAPI CRUD 可使用 SQLModel，复杂模型、查询或异步场景使用 SQLAlchemy 2.x。

- 使用 SQLAlchemy 2.x 风格和类型化模型，数据库模型与对外 schema 保持清晰边界。
- Engine 和 session factory 可复用，Session 按请求或任务创建并及时关闭；事务边界由 service 或用例层控制。
- 生产结构使用 Alembic 迁移，不在应用启动时执行 `create_all()`；自动生成的迁移必须人工检查。
- 查询使用 ORM 或参数绑定，不拼接用户输入；数据库连接和超时放入配置，不暴露 SQL 参数或凭据。

## HTTP API 兼容性与错误处理（按需）

新 API 或新版本优先采用 RFC 9457 Problem Details；已有 API 保持兼容。

- 错误响应使用 `application/problem+json`，保持错误类型标识和 HTTP 状态码稳定一致。
- 使用最符合语义的 HTTP 状态码，不通过 `200` 包装错误，也不直接返回第三方错误正文。
- client 层将网络、超时和第三方 SDK 异常转换为基础设施异常；service 层抛出不依赖 HTTP 的业务异常；API 层通过统一异常处理器映射状态码和响应。
- 只捕获能够处理或转换的异常；未知异常返回通用 `500` 和 `request_id`，内部细节仅进入脱敏日志。
- 错误格式属于对外契约，变更时同步测试和文档。

## 日志（按需）

需要结构化应用日志时统一使用 `structlog`，业务代码不混用其他日志库。

- 本地使用无颜色的可读输出，生产使用 JSON 输出到 `stdout`；时间使用 `Asia/Shanghai` 和带偏移的 ISO 8601 格式。
- 字段名保持稳定；涉及 HTTP API 时记录请求结果和耗时，并传播 `request_id`、`trace_id` 等上下文。
- 标准库和第三方库日志统一接入 `structlog` 配置。
- 异常只在负责处理的边界记录一次并保留堆栈，避免多层重复记录。
- 不记录 secrets、认证信息、请求正文、原始文件或完整签名 URL；必要字段应脱敏或散列。

## 测试

使用 `pytest`；涉及 FastAPI 时，路由测试优先使用 `httpx.AsyncClient + ASGITransport`。

- 行为变更应补充测试，API 覆盖成功和错误路径，复杂 service 分支优先直接测试。
- 测试保持确定、可重复，不依赖本地 secrets 或真实外部网络。
- 确需外部资源的测试标记为 integration test，并默认不在常规测试中执行。

## CI/CD（按需）

仅在项目实际使用自动化流程时采用。

- CI 复用本地开发命令，在干净环境中完成依赖安装、静态检查和测试；自动化检查应稳定、可重复。
- 工作流遵循最小权限，不暴露 secrets，不让不可信代码访问发布凭据；外部 action、插件和工具使用明确版本。
- 构建、发布和运行保持分离。制品应不可变，并能追溯到对应的源码版本和构建记录。
- CD 从受控分支、tag 或审批流程触发；部署后进行必要验证，并保留明确的回滚或修复路径。

## 文档即代码

文档与代码存放在同一仓库，并在同次变更中评审和更新。

- `README.md` 作为项目入口，说明项目用途、快速开始、常用命令、配置入口和文档导航，不堆放详细设计。
- `docs/architecture.md` 按需记录系统边界和关键数据流；重要技术决策放入 `docs/adr/`，复杂关系可使用 Mermaid。
- 涉及 HTTP API 时，以 OpenAPI schema 作为契约的事实来源，避免手工维护重复定义。

## 提交规范

遵循 Conventional Commits。提交语言沿用仓库历史；没有既有约定时，摘要优先使用简洁中文。

格式为 `<type>[(scope)][!]: <摘要>`，必要时在正文说明原因、行为差异或迁移方式。

- 每个 commit 聚焦一个可独立理解、测试和回滚的逻辑变更，相关实现与测试放在一起，不混入无关修改。
- 需要交互式模板时优先使用 Python Commitizen；未配置时按上述模板提交，不为此额外引入 Node.js 工具链。

## 变更与验证

- 编辑前检查现有结构和相关实现，围绕任务保持最小必要改动；更大问题单独说明。
- 优先复用已有约定和依赖，修改既有行为时考虑兼容性和迁移方式。
- 仓库已配置 pre-commit 时，局部运行相关 hooks；修改 hooks 或工具配置时运行 `uv run pre-commit run --all-files`。

完成后按影响范围运行“开发工作流”中的相关检查及仓库配置的类型检查；共享模块、配置或依赖变更运行完整检查。只改文档时至少运行 `git diff --check`。不要为修复既有失败扩大范围，并汇报通过、失败和未运行的检查。

相关技术

• src layout：把可导入包放在 src/ 下，避免测试误用仓库根目录中的源码。
• uv：管理 Python 版本、虚拟环境、依赖和项目命令。
• pyproject.toml：集中保存项目元数据、依赖和开发工具配置。
• uv.lock：锁定完整依赖树，保证不同环境得到一致的安装结果。
• Ruff：提供 Python lint 和代码格式化。
• ty / mypy：两种静态类型检查器，按项目需要选择一种。
• pytest：负责测试发现、fixture、参数化和断言。
• FastAPI：用于构建类型化 HTTP API，并自动生成 OpenAPI schema。
• httpx.AsyncClient：异步 HTTP 客户端，可用于测试 FastAPI 路由。
• ASGITransport：直接连接 ASGI 应用，测试时无需启动真实服务器。
• pydantic-settings：把环境变量和配置文件加载为有类型的配置模型。
• SQLModel：结合 Pydantic 与 SQLAlchemy，适合常规 FastAPI CRUD。
• SQLAlchemy 2.x：提供 ORM、类型化模型、查询和事务管理。
• Alembic：管理生产数据库的结构迁移和版本历史。
• RFC 9457 Problem Details：定义统一、可扩展的 HTTP API 错误格式。
• structlog：使用稳定字段输出结构化日志。
• OpenAPI：描述 HTTP API 的路径、参数、请求体和响应契约。
• ADR：记录重要技术决策的背景、选择和后果。
• Mermaid：在 Markdown 中维护架构图和流程图。
• Conventional Commits：用 feat、fix 等类型统一提交信息。
• Commitizen：辅助生成符合 Conventional Commits 的提交信息。
• pre-commit：在提交前运行快速、稳定的本地检查。
• Git LFS：为确需版本控制的大型文件提供独立存储。
• Google Style docstring：统一公共 API、领域类和复杂函数的文档格式。
• CI/CD：自动执行检查、构建和受控发布流程。
• GitHub Actions：在 GitHub 仓库中运行 CI/CD 工作流。
• 最小权限：只授予工作流完成任务所需的权限，降低凭据泄露后的影响。
• 不可变制品：同一构建产物不再被覆盖，便于追溯、验证和回滚。