PolyWeather/AGENTS.md

PolyWeather Agent Instructions

语言和沟通

• 默认用中文回复用户。
• 直接说明正在做什么、查到了什么、下一步是什么；不要写空泛客套话。
• 如果用户要求“提交推送”“部署”“看日志”，必须在本地验证后再提交、推送，并检查 GitHub Actions 或线上状态。
• 不要把多个不相关任务混在一个结论里；遇到新方向时，建议用户在同一个 Project 下开新 Thread。

项目和线程使用

• 一个 Project 对应 PolyWeather 这个共享代码库和长期方向。
• 每个具体任务使用一条独立 Thread / Chat，例如：
  • 落地页与产品包装
  • 观测数据采集与 SSE patch
  • Telegram 推送
  • 付款与会员
  • 部署、CI、服务器状态
• 同一个 Project 下的 Thread 共享文件夹和 AGENTS.md，但上下文分开，避免旧问题影响新任务判断。

代码工作原则

• 先读现有代码和配置，再改动；优先沿用项目已有模式。
• 使用 rg / rg --files 查找文件和文本。
• 手动编辑文件使用 apply_patch。
• 不要回滚用户或其他 agent 已经做过的无关改动。
• 只改和当前任务直接相关的文件，避免顺手重构。
• 新增复杂逻辑时补充聚焦测试；窄改动保持验证范围匹配风险。

前端约定

• 前端位于 frontend/，使用 Next.js、React、TypeScript。
• UI 修改必须关注移动端响应式、文本不重叠、按钮和标签不溢出。
• 图表、终端、详情面板等工作界面应保持信息密度和可扫描性，避免营销式装饰。
• 常用验证：
  • cd frontend && npm run test:business
  • cd frontend && npm run typecheck
  • 必要时启动本地预览并用浏览器检查桌面和移动视口；检查完关闭本地端口。

后端和数据约定

• Python 代码主要位于 src/、web/、tests/。
• 观测数据刷新应以数据源原生频率为准，避免 Web、collector、Telegram 同时强刷同一外部源。
• Telegram 默认只读最新缓存/DB；除非完全没有缓存，才允许兜底刷新。
• 对外部源调用要考虑 singleflight、冷却、缓存和失败降级，避免 502/408 或 Supabase/磁盘 IO 压力。
• 常用验证：
  • python -m ruff check .
  • python -m pytest

CI、提交和部署

• main push 会触发 .github/workflows/ci.yml：
  • python-quality
  • frontend-quality
  • build-and-push
  • deploy
• 提交前至少运行和改动相关的验证；推送前确认 git status --short。
• 推送后检查 GitHub Actions 最新 run；如果失败，先定位失败 job 和 step，再修改。
• 线上 smoke check 优先检查：
  • https://api.polyweather.top/healthz
  • https://polyweather.top/
  • 相关页面或 API 路径

产品方向备忘

• PolyWeather 当前重点不是售卖 API。
• 核心差异化是结算源优先、实时观测源、跑道/城市细粒度温度、SSE patch、Telegram 缓存读取和面向交易/预测市场的解释能力。
• 公开包装、教育内容、图表变量完整度和付费分层可以加强，但不要把产品定位改成通用天气 API。

Memory 说明

• AGENTS.md 是项目内显式规则，跟随仓库和 Project。
• Memory 是用户账号级偏好设置，agent 不能代替用户开启。
• 建议在 Codex / ChatGPT 设置中开启 Memory，并保存长期偏好，例如：
  • PolyWeather 项目默认中文回复。
  • 每个任务开独立 Thread。
  • 修改后优先验证、提交、推送并检查部署状态。
  • 不要主动把 PolyWeather 包装成 API 售卖产品。