re-xxm/AGENTS.md

开发约束

本文件适用于本仓库内的所有代码、测试、配置和文档变更。后续开发必须遵守以下约束；如与更深层目录中的 AGENTS.md 冲突，以更深层文件为准。

1. 测试是实现的一部分

• 新增或修改任何方法、函数、类方法或业务逻辑时，必须同步新增或更新自动化测试。
• 不依赖外部接口、文件系统、时钟、随机数或进程环境的纯函数必须有可靠的单元测试，覆盖：
  • 正常输入与预期输出；
  • 边界值；
  • 空值、异常值或非法输入（如函数设计需要处理）；
  • 已修复缺陷对应的回归用例。
• 不得以“仅人工运行验证”“代码简单”或“调用方已有测试”为由省略纯函数测试。
• 测试必须确定、可重复、离线运行；不得访问真实 B 站、Telegram 或其他外部服务。

2. 外部 API 调用必须使用契约一致的 Mock 验证

• 所有依赖外部 HTTP/API 接口的方法或函数必须有自动化测试。
• 测试中的 Mock 响应必须与实际接口的返回格式一致，包括：
  • 顶层字段和嵌套结构；
  • 字段类型（例如整数、字符串、数组、null）；
  • 成功响应的 code / data 等包装层；
  • 项目需要处理的失败响应、缺字段、空数组和异常响应。
• Mock 数据应优先来自已记录的真实接口样本，并完成脱敏；不得为方便测试而编造与接口契约不一致的简化结构。
• 每个 API 客户端至少覆盖：
  • 成功响应的解析与字段映射；
  • API 业务错误码；
  • HTTP/网络错误；
  • 本项目依赖的边界情形（例如 B 站 infos 静默缺失资源、view 返回 -404、鉴权失效）。
• Mock 应替换网络传输边界（HTTP client / transport），而不是替换正在测试的业务解析与错误处理逻辑。

3. 测试执行要求

• 所有测试命令必须通过 uv run 在项目锁定的 Python 3.14 环境中运行。
• 提交前至少运行受改动影响的测试；涉及共享模块、配置、数据库迁移、API 客户端或调度逻辑时，必须运行完整测试集。
• 测试失败时不得提交“已验证”的实现；应先修复代码或更新正确的测试预期。
• 测试命令、结果和未执行测试的原因必须在最终开发说明中如实记录。

当前已有测试示例：

uv run python tests/test_auth.py
uv run python tests/test_moves.py

新增测试应按功能放入 tests/，命名清晰，并保持可由 uv run python <测试文件> 直接执行；如后续引入测试框架，必须同时更新 pyproject.toml、uv.lock 与相关文档。

4. 阶段性本地 Git 提交

• 完成一个可独立验证的关键步骤后，必须先运行对应测试，再创建一次本地 Git 提交；不得推送远程仓库，除非用户明确要求。
• 关键步骤包括但不限于：
  • 一个完整的 API 客户端或认证能力；
  • 一个数据库迁移或数据模型阶段；
  • 一个调度任务；
  • 一个端到端业务动作（如候选收藏、忽略、拉黑）；
  • 一个完整页面/API 范围；
  • 重要缺陷修复或安全修复。
• 提交前检查工作区，确保不包含凭据、Cookie、数据库、日志、缓存、构建产物或其他运行期文件。
• 提交信息使用简洁的 Conventional Commits 风格，例如：

feat(sync): add favorite-folder import
fix(auth): preserve device fingerprint cookies
test(api): cover missing favorite resource responses
docs: document local uv workflow

• 若当前目录尚未初始化为 Git 仓库，或 Git 用户身份未配置，应向用户说明这一阻塞项；不得未经明确授权自行执行 git init、配置 Git 身份或创建提交。
• 不得执行会丢失用户工作区内容的 Git 命令，例如 git reset --hard、git checkout -- . 或强制清理未跟踪文件，除非用户明确要求。

5. 完成定义

一个开发任务只有在以下条件满足后才可视为完成：

1. 实现与文档/需求口径一致；
2. 新增或变更的纯函数已有可靠离线单元测试；
3. API 相关逻辑已有契约一致的 Mock 测试；
4. 受影响测试已通过；
5. 关键步骤已经创建本地 Git 提交，或已明确记录无法提交的原因；
6. 最终说明包含改动文件、验证命令与结果，以及未验证项（如有）。