mirror of
https://github.com/ZhuLinsen/daily_stock_analysis
synced 2026-09-20 10:53:33 +08:00
docs: refine AGENTS workflow and simplify config principles
This commit is contained in:
zhulinsen
235
AGENTS.md
235
AGENTS.md
@@ -1,151 +1,148 @@
|
||||
# AGENTS.md
|
||||
|
||||
本文件定义在本仓库中执行开发、Issue 分析、PR 审查时的统一行为准则。
|
||||
本文件用于约束本仓库的默认开发流程，目标是减少重复沟通、减少返工，并让改动和当前项目结构保持一致。
|
||||
|
||||
## 1. 通用协作原则
|
||||
## 1. 硬规则
|
||||
|
||||
- 语言与栈：Python 3.10+，遵循仓库现有架构与目录边界。
|
||||
- 配置约束：统一使用 `.env`（参见 `.env.example`）。
|
||||
- 代码质量：优先保证可运行、可回归验证、可追踪（日志/错误信息清晰）。
|
||||
- 风格约束：
|
||||
- 行宽 120
|
||||
- `black` + `isort` + `flake8`
|
||||
- 关键变更需至少做语法检查（`py_compile`）或对应测试验证。
|
||||
- 新增或修改的代码注释必须使用英文。
|
||||
- Git 约束：
|
||||
- 未经明确确认，不执行 `git commit`。
|
||||
- commit message 不添加 `Co-Authored-By`。
|
||||
- 后续所有 commit message 必须使用英文。
|
||||
- 遵循现有目录边界：
|
||||
- 后端逻辑优先放在 `src/`、`data_provider/`、`api/`、`bot/`
|
||||
- 前端改动在 `apps/dsa-web/`
|
||||
- 部署与流水线改动在 `scripts/`、`.github/workflows/`、`docker/`
|
||||
- 未经明确确认，不执行 `git commit`、`git tag`、`git push`。
|
||||
- commit message 使用英文，不添加 `Co-Authored-By`。
|
||||
- 不写死密钥、账号、路径、模型名或环境差异逻辑。
|
||||
- 新增配置项时，必须同步更新 `.env.example` 和相关文档。
|
||||
- 涉及用户可见能力、CLI/API 行为、部署方式、通知方式、报告结构变化时，必须同步更新 `README.md` 和 `docs/CHANGELOG.md`。
|
||||
- 注释、docstring、日志文案以清晰准确为准，不强制要求英文，但应与文件语境保持一致。
|
||||
|
||||
## 2. Issue 分析原则
|
||||
## 2. 默认开发流程
|
||||
|
||||
每个 Issue 必须先回答 3 个问题：
|
||||
1. 先判断任务类型：`fix / feat / refactor / docs / chore / test / review`
|
||||
2. 先读现有实现、配置、测试和文档，再动手修改
|
||||
3. 只做和当前任务直接相关的最小改动，不顺手夹带无关重构
|
||||
4. 改完后按下面的验证矩阵执行检查
|
||||
5. 最终交付默认要说明：
|
||||
- 改了什么
|
||||
- 为什么这么改
|
||||
- 跑了哪些验证
|
||||
- 哪些验证没跑以及原因
|
||||
- 风险点
|
||||
- 回滚方式
|
||||
|
||||
1. 是否合理（Reasonable）
|
||||
- 是否描述了真实影响（功能错误、数据错误、性能/稳定性问题、体验退化）。
|
||||
- 是否有可验证证据（日志、截图、复现步骤、版本信息）。
|
||||
- 是否与项目目标相关（股票分析、数据源、通知、API/WebUI、部署链路）。
|
||||
## 3. 验证矩阵
|
||||
|
||||
2. 是否是 Issue（Valid Issue）
|
||||
- 属于缺陷/功能缺失/回归/文档错误之一，而非纯咨询或环境误用。
|
||||
- 能定位到仓库责任边界；若是三方服务波动，也需判断是否需要仓库侧兜底。
|
||||
- 如果是使用问题，应转为文档改进或 FAQ，而不是代码缺陷。
|
||||
### Python 后端改动
|
||||
|
||||
3. 是否好解决（Solvability）
|
||||
- 可否稳定复现。
|
||||
- 依赖是否可控（第三方 API、网络、权限、密钥）。
|
||||
- 变更范围与风险等级（低/中/高）。
|
||||
- 是否存在临时缓解方案（降级、兜底、开关、重试、回退策略）。
|
||||
适用范围：`main.py`、`src/`、`data_provider/`、`api/`、`bot/`、`tests/`
|
||||
|
||||
### 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`：修复类、小改动（+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。**
|
||||
优先执行：
|
||||
|
||||
```bash
|
||||
# 正确：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
|
||||
./scripts/ci_gate.sh
|
||||
```
|
||||
|
||||
- CI（`docker-publish.yml`）会校验 tag 是否有非空注释，轻量 tag 会直接失败。
|
||||
- `.github/workflows/create-release.yml` 会在 tag 推送后**自动以注释内容创建 GitHub Release**，无需手动编辑。
|
||||
如果环境不足以跑完整 gate，最低要求：
|
||||
|
||||
**GitHub Release 的 "What's Changed" 自动生成规则（`.github/release.yml`）：**
|
||||
```bash
|
||||
python -m py_compile <changed_python_files>
|
||||
```
|
||||
|
||||
- 内容来源：两个 tag 之间**合并的 PR**，按 PR label 分类。
|
||||
- 直接 `git commit` 推送的提交**不会出现**在自动生成内容中。
|
||||
- 因此，团队规范：
|
||||
- 对用户可见的功能/修复，优先通过 **PR** 合入，并打好 label（`bug` / `enhancement` / `data-source` 等）。
|
||||
- 若直接推送了 commit（如紧急修复），需在 tag 的 `-m` 注释中**手动补充**这些变更，确保 Release Notes 完整。
|
||||
并在交付说明中写明缺失了哪些验证。
|
||||
|
||||
**`docs/CHANGELOG.md` 维护规则：**
|
||||
### Web 前端改动
|
||||
|
||||
- 新增版本条目时，将 `[Unreleased]` 下的内容移入 `## [X.Y.Z] - YYYY-MM-DD` 并重置 `[Unreleased]` 为空。
|
||||
- 打 tag 前不强制要求 CHANGELOG 同步（CI 已改为校验 tag 注释），但建议保持同步。
|
||||
适用范围：`apps/dsa-web/`
|
||||
|
||||
## 5. 建议评审输出格式
|
||||
默认执行：
|
||||
|
||||
### Issue 评审输出
|
||||
```bash
|
||||
cd apps/dsa-web
|
||||
npm ci
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
### 文档改动
|
||||
|
||||
适用范围：`README.md`、`docs/**`
|
||||
|
||||
- 不强制代码测试
|
||||
- 需确认文档中的命令、配置项、文件名与实际仓库一致
|
||||
- 交付时直接说明：`Docs only, tests not run`
|
||||
|
||||
### 工作流 / 脚本 / Docker 改动
|
||||
|
||||
适用范围：`.github/**`、`scripts/**`、`docker/**`
|
||||
|
||||
- 运行最接近改动面的本地验证
|
||||
- 交付时说明影响了哪条流水线或部署路径
|
||||
|
||||
### 网络或三方依赖相关改动
|
||||
|
||||
适用范围：数据源、通知、搜索、外部 LLM、网络 API
|
||||
|
||||
- 先跑离线或确定性检查
|
||||
- 若未执行在线验证，必须明确写出原因
|
||||
- `pytest -m network` 属于加分项，不是默认阻断项
|
||||
|
||||
## 4. 实现约束
|
||||
|
||||
- 优先复用现有模块、配置入口、脚本和测试，不新增平行实现。
|
||||
- 当前项目配置复杂度已经较高；新增能力时应优先减少配置负担，而不是继续叠加开关、模式和例外分支。
|
||||
- 新增配置应保持易用性：命名清晰、职责单一、默认值合理，优先做到不配置也能运行，配置后才增强能力。
|
||||
- 避免为同一能力引入多个语义重叠、互相依赖或容易冲突的配置项；能复用现有配置的，不新增。
|
||||
- 非明确需求下，不改变现有默认行为；新增能力优先采用向后兼容、默认关闭或渐进启用的方式接入。
|
||||
- 修改数据源、通知、搜索、Prompt、工作流时，必须评估兼容性、降级路径和回滚方式。
|
||||
- 修改已有配置语义、默认值或执行流程时，必须评估对本地运行、Docker、GitHub Actions、API/WebUI 的影响。
|
||||
- 不轻易破坏现有 fallback / fail-open 行为，除非需求明确要求。
|
||||
- 改 API / Schema / 前端联动时，要同时检查前后端兼容性。
|
||||
- 非必要不引入新的基础设施依赖、配置格式或大型抽象层。
|
||||
|
||||
## 5. Issue 分析
|
||||
|
||||
每个 Issue 默认先回答 4 个问题：
|
||||
|
||||
1. 版本是否明确
|
||||
2. 问题是否真实且可验证
|
||||
3. 是否属于仓库责任边界
|
||||
4. 是否值得立即处理
|
||||
|
||||
输出模板：
|
||||
|
||||
- `版本基线`：最新 / 非最新 / 未提供
|
||||
- `是否合理`：是/否 + 理由
|
||||
- `是否是 issue`：是/否 + 理由
|
||||
- `是否好解决`：是/否 + 难点
|
||||
- `建议动作`：修复/排期/文档/关闭
|
||||
- `结论`：`成立 / 部分成立 / 不成立`
|
||||
- `分类`：`bug / feature / docs / question / external`
|
||||
- `优先级`：`P0 / P1 / P2 / P3`
|
||||
- `难度`：`easy / medium / hard`
|
||||
- `建议动作`：`立即修复 / 排期修复 / 文档澄清 / 关闭`
|
||||
|
||||
### PR 评审输出
|
||||
## 6. PR 审查
|
||||
|
||||
PR 默认按以下顺序审查：
|
||||
|
||||
1. 必要性：是否解决明确问题，是否避免无关改动
|
||||
2. 关联性：优先有 `Fixes #xxx` 或 `Refs #xxx`
|
||||
3. 描述完整性：是否包含背景、范围、验证、风险、回滚
|
||||
4. 实现正确性：是否符合现有架构，是否存在明显回归风险
|
||||
5. 合入判定：是否具备直接合入条件
|
||||
|
||||
对 `fix` 类 PR，必须说明：原问题、根因、修复点、回归风险。
|
||||
|
||||
评审输出模板：
|
||||
|
||||
- `必要性`：通过/不通过
|
||||
- `是否有对应 issue`：有/无（编号）
|
||||
- `PR 类型`：fix/feat/...
|
||||
- `PR 类型`：`fix / feat / refactor / docs / chore / test`
|
||||
- `description 完整性`：完整/不完整（缺失项）
|
||||
- `验证情况`：已验证/部分验证/未验证
|
||||
- `主要风险`：无 / 有（说明）
|
||||
- `是否可直接合入`：可/不可 + 必改项
|
||||
|
||||
## 6. 快速检查命令（可选）
|
||||
## 7. 发布规则摘要
|
||||
|
||||
```bash
|
||||
./test.sh syntax
|
||||
python -m py_compile main.py src/*.py data_provider/*.py
|
||||
flake8 main.py src/ --max-line-length=120
|
||||
```
|
||||
- 自动 tag 默认不触发，只有 commit title 包含 `#patch`、`#minor`、`#major` 才会触发版本号更新。
|
||||
- 手动打 tag 必须使用 annotated tag。
|
||||
- 用户可见变更优先通过 PR 合入，并补齐 label 与验证说明。
|
||||
|
||||
Reference in New Issue
Block a user