Skip to content

AGENTS.md

Latest commit

 

History

History
165 lines (119 loc) · 6.5 KB

AGENTS.md

File metadata and controls

165 lines (119 loc) · 6.5 KB
Raw

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. 验证矩阵

CI 覆盖原则：本项目 CI 目前仅覆盖 Python 语法检查（py_compile）和致命 Flake8 错误（E9/F63/F7/F82）。对这两项，若 CI 已通过，PR 描述中可直接引用 CI 结果，无需重复贴本地输出。./scripts/ci_gate.sh 不在 CI 覆盖范围内；若该 gate 未执行，PR 描述须说明原因，否则缺失证据应在建议项中注明。

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；自然语言关联（如"关联 issue 为 #xxx"）也可接受，不作为阻断项
  3. 描述完整性：是否包含背景、范围、验证、风险、回滚
  4. 实现正确性：是否符合现有架构，是否存在明显回归风险
  5. 合入判定：是否具备直接合入条件

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

合入阻断条件（必须满足才能合入）

  • 代码存在正确性或安全性问题（逻辑错误、异常吞没、安全漏洞等）
  • CI 检查未通过（语法检查、lint、构建失败等）
  • PR 描述与实际改动内容存在实质性矛盾（如声称更新了某文件但 diff 中没有）
  • 缺少回滚方案

建议条件（不阻断合入，但建议改进）

  • issue 关联格式不规范（如自然语言关联而非 Fixes/Refs #xxx）
  • 验证证据不完整但 CI 已通过对应检查
  • PR 描述中存在非关键性的措辞或格式问题
  • 注释语言风格不统一
  • 无关的锁文件或格式化变更（建议清理但不阻断）

评审输出模板：

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

7. 发布规则摘要

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