daily_stock_analysis/AGENTS.md

AGENTS.md

本文件用于约束本仓库的默认开发流程，目标是减少重复沟通、减少返工，并让改动和当前项目结构保持一致。

1. 硬规则

• 遵循现有目录边界：
  • 后端逻辑优先放在 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. 默认开发流程

1. 先判断任务类型：fix / feat / refactor / docs / chore / test / review
2. 先读现有实现、配置、测试和文档，再动手修改
3. 只做和当前任务直接相关的最小改动，不顺手夹带无关重构
4. 改完后按下面的验证矩阵执行检查
5. 最终交付默认要说明：
   • 改了什么
   • 为什么这么改
   • 跑了哪些验证
   • 哪些验证没跑以及原因
   • 风险点
   • 回滚方式

3. 验证矩阵

Python 后端改动

适用范围：main.py、src/、data_provider/、api/、bot/、tests/

优先执行：

./scripts/ci_gate.sh

如果环境不足以跑完整 gate，最低要求：

python -m py_compile <changed_python_files>

并在交付说明中写明缺失了哪些验证。

Web 前端改动

适用范围：apps/dsa-web/

默认执行：

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
• 建议动作：立即修复 / 排期修复 / 文档澄清 / 关闭

6. PR 审查

PR 默认按以下顺序审查：

1. 必要性：是否解决明确问题，是否避免无关改动
2. 关联性：优先有 Fixes #xxx 或 Refs #xxx
3. 描述完整性：是否包含背景、范围、验证、风险、回滚
4. 实现正确性：是否符合现有架构，是否存在明显回归风险
5. 合入判定：是否具备直接合入条件

对 fix 类 PR，必须说明：原问题、根因、修复点、回归风险。

评审输出模板：

• 必要性：通过/不通过
• 是否有对应 issue：有/无（编号）
• PR 类型：fix / feat / refactor / docs / chore / test
• description 完整性：完整/不完整（缺失项）
• 验证情况：已验证/部分验证/未验证
• 主要风险：无 / 有（说明）
• 是否可直接合入：可/不可 + 必改项

7. 发布规则摘要

• 自动 tag 默认不触发，只有 commit title 包含 #patch、#minor、#major 才会触发版本号更新。
• 手动打 tag 必须使用 annotated tag。
• 用户可见变更优先通过 PR 合入，并补齐 label 与验证说明。