|
|
# 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、部署链路）。
|
|
|
|
|
|
2. 是否是 Issue（Valid Issue）
|
|
|
- 属于缺陷/功能缺失/回归/文档错误之一，而非纯咨询或环境误用。
|
|
|
- 能定位到仓库责任边界；若是三方服务波动，也需判断是否需要仓库侧兜底。
|
|
|
- 如果是使用问题，应转为文档改进或 FAQ，而不是代码缺陷。
|
|
|
|
|
|
3. 是否好解决（Solvability）
|
|
|
- 可否稳定复现。
|
|
|
- 依赖是否可控（第三方 API、网络、权限、密钥）。
|
|
|
- 变更范围与风险等级（低/中/高）。
|
|
|
- 是否存在临时缓解方案（降级、兜底、开关、重试、回退策略）。
|
|
|
|
|
|
### Issue 结论模板
|
|
|
|
|
|
- 结论：`成立 / 部分成立 / 不成立`
|
|
|
- 分类：`bug / feature / docs / question / external`
|
|
|
- 优先级：`P0 / P1 / P2 / P3`
|
|
|
- 难度：`easy / medium / hard`
|
|
|
- 建议：`立即修复 / 排期修复 / 文档澄清 / 关闭`
|
|
|
|
|
|
## 3. PR 分析原则
|
|
|
|
|
|
每个 PR 需按以下顺序审查：
|
|
|
|
|
|
1. 必要性（Necessity）
|
|
|
- 是否解决明确问题，或提供明确业务价值。
|
|
|
- 是否避免“为了改而改”的重构。
|
|
|
|
|
|
2. 关联性（Traceability）
|
|
|
- 是否关联对应 Issue（建议必须有：`Fixes #xxx` 或 `Refs #xxx`）。
|
|
|
- 若无 Issue，PR 描述必须给出动机、场景与验收标准。
|
|
|
|
|
|
3. 类型判定（Type）
|
|
|
- 明确标注：`fix / feat / refactor / docs / chore / test`。
|
|
|
- 对“fix/bug”类 PR：必须说明原问题、根因、修复点、回归风险。
|
|
|
|
|
|
4. 描述完整性（Description Completeness）
|
|
|
- 必须包含：
|
|
|
- 背景与问题
|
|
|
- 变更范围（改了哪些模块）
|
|
|
- 验证方式与结果（命令、关键输出）
|
|
|
- 兼容性与破坏性变更说明（如有）
|
|
|
- 回滚方案（至少一句）
|
|
|
- 若为 issue 修复：在 PR description 中显式写明关闭语句（如 `Fixes #241` / `Closes #241`）
|
|
|
|
|
|
5. 合入判定（Merge Readiness）
|
|
|
- 可直接合入（Ready to Merge）条件：
|
|
|
- 目标明确且必要
|
|
|
- 有 Issue 或同等质量的问题描述
|
|
|
- 变更与描述一致，无隐藏副作用
|
|
|
- 关键验证已通过（语法/测试/关键链路）
|
|
|
- 无阻断性风险（安全、数据损坏、明显性能回退）
|
|
|
- 不可直接合入（Not Ready）条件：
|
|
|
- 描述不完整，无法确认动机和影响
|
|
|
- 无验证证据
|
|
|
- 引入明显风险且无回滚策略
|
|
|
- 与仓库方向无关或重复实现
|
|
|
|
|
|
## 4. 交付与发布同步原则
|
|
|
|
|
|
- 功能开发、缺陷修复完成后，必须同步更新文档：
|
|
|
- `README.md`（用户可见能力、使用方式、配置项变化）
|
|
|
- `docs/CHANGELOG.md`（版本变更记录、影响范围、兼容性说明）
|
|
|
- 发布语义必须与改动规模匹配，在提交说明中添加对应 tag 标签：
|
|
|
- `#patch`：修复类、小改动
|
|
|
- `#minor`：新增可用功能、向后兼容
|
|
|
- `#major`：破坏性变更或重大架构调整
|
|
|
- `#skip` / `#none`：明确不触发自动版本标签
|
|
|
- 若改动用于解决已有 issue，PR description 必须声明关闭该 issue（`Fixes #xxx` / `Closes #xxx`），避免修复完成后 issue 悬挂。
|
|
|
|
|
|
## 5. 建议评审输出格式
|
|
|
|
|
|
### Issue 评审输出
|
|
|
|
|
|
- `是否合理`：是/否 + 理由
|
|
|
- `是否是 issue`：是/否 + 理由
|
|
|
- `是否好解决`：是/否 + 难点
|
|
|
- `建议动作`：修复/排期/文档/关闭
|
|
|
|
|
|
### PR 评审输出
|
|
|
|
|
|
- `必要性`：通过/不通过
|
|
|
- `是否有对应 issue`：有/无（编号）
|
|
|
- `PR 类型`：fix/feat/...
|
|
|
- `description 完整性`：完整/不完整（缺失项）
|
|
|
- `是否可直接合入`：可/不可 + 必改项
|
|
|
|
|
|
## 6. 快速检查命令（可选）
|
|
|
|
|
|
```bash
|
|
|
./test.sh syntax
|
|
|
python -m py_compile main.py src/*.py data_provider/*.py
|
|
|
flake8 main.py src/ --max-line-length=120
|
|
|
```
|
