Skip to content

AGENTS.md

Latest commit

 

History

History
151 lines (116 loc) · 6.08 KB

AGENTS.md

File metadata and controls

151 lines (116 loc) · 6.08 KB

AGENTS.md

本文件定义在本仓库中执行开发、Issue 分析、PR 审查时的统一行为准则。

1. 通用协作原则

  • 语言与栈：Python 3.10+，遵循仓库现有架构与目录边界。
  • 配置约束：统一使用 .env（参见 .env.example）。
  • 代码质量：优先保证可运行、可回归验证、可追踪（日志/错误信息清晰）。
  • 风格约束：
    • 行宽 120
    • black + isort + flake8
    • 关键变更需至少做语法检查（py_compile）或对应测试验证。
    • 新增或修改的代码注释必须使用英文。
  • Git 约束：
    • 未经明确确认，不执行 git commit。
    • commit message 不添加 Co-Authored-By。
    • 后续所有 commit message 必须使用英文。

2. Issue 分析原则

每个 Issue 必须先回答 3 个问题：

  1. 是否合理（Reasonable）
  • 是否描述了真实影响（功能错误、数据错误、性能/稳定性问题、体验退化）。
  • 是否有可验证证据（日志、截图、复现步骤、版本信息）。
  • 是否与项目目标相关（股票分析、数据源、通知、API/WebUI、部署链路）。
  1. 是否是 Issue（Valid Issue）
  • 属于缺陷/功能缺失/回归/文档错误之一，而非纯咨询或环境误用。
  • 能定位到仓库责任边界；若是三方服务波动，也需判断是否需要仓库侧兜底。
  • 如果是使用问题，应转为文档改进或 FAQ，而不是代码缺陷。
  1. 是否好解决（Solvability）
  • 可否稳定复现。
  • 依赖是否可控（第三方 API、网络、权限、密钥）。
  • 变更范围与风险等级（低/中/高）。
  • 是否存在临时缓解方案（降级、兜底、开关、重试、回退策略）。

Issue 结论模板

  • 结论：成立 / 部分成立 / 不成立
  • 分类：bug / feature / docs / question / external
  • 优先级：P0 / P1 / P2 / P3
  • 难度：easy / medium / hard
  • 建议：立即修复 / 排期修复 / 文档澄清 / 关闭

3. PR 分析原则

每个 PR 需按以下顺序审查：

  1. 必要性（Necessity）
  • 是否解决明确问题，或提供明确业务价值。
  • 是否避免“为了改而改”的重构。
  1. 关联性（Traceability）
  • 是否关联对应 Issue（建议必须有：Fixes #xxx 或 Refs #xxx）。
  • 若无 Issue，PR 描述必须给出动机、场景与验收标准。
  1. 类型判定（Type）
  • 明确标注：fix / feat / refactor / docs / chore / test。
  • 对“fix/bug”类 PR：必须说明原问题、根因、修复点、回归风险。
  1. 描述完整性（Description Completeness）
  • 必须包含：
    • 背景与问题
    • 变更范围（改了哪些模块）
    • 验证方式与结果（命令、关键输出）
    • 兼容性与破坏性变更说明（如有）
    • 回滚方案（至少一句）
    • 若为 issue 修复：在 PR description 中显式写明关闭语句（如 Fixes #241 / Closes #241）
  1. 合入判定（Merge Readiness）
  • 可直接合入（Ready to Merge）条件：
    • 目标明确且必要
    • 有 Issue 或同等质量的问题描述
    • 变更与描述一致，无隐藏副作用
    • 关键验证已通过（语法/测试/关键链路）
    • 无阻断性风险（安全、数据损坏、明显性能回退）
  • 不可直接合入（Not Ready）条件：
    • 描述不完整，无法确认动机和影响
    • 无验证证据
    • 引入明显风险且无回滚策略
    • 与仓库方向无关或重复实现

4. 交付与发布同步原则

  • 功能开发、缺陷修复完成后，必须同步更新文档：
    • README.md（用户可见能力、使用方式、配置项变化）
    • docs/CHANGELOG.md（版本变更记录、影响范围、兼容性说明）
  • 自动版本标签默认不触发，需在提交说明中显式添加对应标签才会创建 tag：
    • #patch：修复类、小改动（+0.0.1）
    • #minor：新增可用功能、向后兼容（+0.1.0）
    • #major：破坏性变更或重大架构调整（+1.0.0）
    • 不添加任何标签：默认不创建 tag
  • 若改动用于解决已有 issue，commit 或 PR description 必须声明关闭该 issue（Fixes #xxx / Closes #xxx），避免修复完成后 issue 悬挂。

Tag 与 Release 规范

Tag 必须使用 annotated tag（带 -m 注释），禁止使用轻量 tag。

# 正确：annotated tag，-m 内容即 GitHub Release 的正文
git tag -a v3.x.x -m "Bug fixes:
- fix(xxx): 描述 (#issue)

Features:
- feat(xxx): 描述 (#issue)"
git push origin v3.x.x
  • CI（docker-publish.yml）会校验 tag 是否有非空注释，轻量 tag 会直接失败。
  • .github/workflows/create-release.yml 会在 tag 推送后自动以注释内容创建 GitHub Release，无需手动编辑。

GitHub Release 的 "What's Changed" 自动生成规则（.github/release.yml）：

  • 内容来源：两个 tag 之间合并的 PR，按 PR label 分类。
  • 直接 git commit 推送的提交不会出现在自动生成内容中。
  • 因此，团队规范：
    • 对用户可见的功能/修复，优先通过 PR 合入，并打好 label（bug / enhancement / data-source 等）。
    • 若直接推送了 commit（如紧急修复），需在 tag 的 -m 注释中手动补充这些变更，确保 Release Notes 完整。

docs/CHANGELOG.md 维护规则：

  • 新增版本条目时，将 [Unreleased] 下的内容移入 ## [X.Y.Z] - YYYY-MM-DD 并重置 [Unreleased] 为空。
  • 打 tag 前不强制要求 CHANGELOG 同步（CI 已改为校验 tag 注释），但建议保持同步。

5. 建议评审输出格式

Issue 评审输出

  • 是否合理：是/否 + 理由
  • 是否是 issue：是/否 + 理由
  • 是否好解决：是/否 + 难点
  • 建议动作：修复/排期/文档/关闭

PR 评审输出

  • 必要性：通过/不通过
  • 是否有对应 issue：有/无（编号）
  • PR 类型：fix/feat/...
  • description 完整性：完整/不完整（缺失项）
  • 是否可直接合入：可/不可 + 必改项

6. 快速检查命令（可选）

./test.sh syntax
python -m py_compile main.py src/*.py data_provider/*.py
flake8 main.py src/ --max-line-length=120