PanWatch 贡献指南Conventional Commits、分支策略与 PR 规范全解读【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK US markets, powered by TradingAgents. Portfolio insights, real-time alerts automated reports.盯盘侠覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatchPanWatch 是一款覆盖 A股、港股、美股的 AI 盯盘工具提供持仓分析、实时提醒与自动报告。本文贡献指南将完整解读它的 Conventional Commits 提交规范、分支策略与 Pull RequestPR规范帮助新手一次性提交出规范的 Pull Request顺利进入开源协作流程。开始之前先读官方贡献指南的 4 条铁律 动手之前先通读官方指南中文版 CONTRIBUTING.zh-CN.md 与英文版 CONTRIBUTING.md。官方列出了 4 条基本原则先搜后做开发前先搜索已有 Issue 和 PR避免重复劳动先提 Issue大型功能、架构调整、新依赖或破坏性变更先开 Issue 说明用户问题和计划边界零敏感信息绝不提交 API Key、Token、Cookie、个人持仓、本地数据库或含隐私数据的日志保持 PR 聚焦与功能无关的清理请拆到单独的 PR。一键启动开发环境PanWatch 前后端分离Python 后端:8000 React 前端:5183。环境要求工具版本Python3.10Docker 运行时为 3.11Node.js24.14.0pnpm9.15.9克隆仓库并启动git clone https://gitcode.com/GitHub_Trending/pa/PanWatch cd PanWatch make dev-api # 终端 1自动创建 venv、装依赖启动后端 :8000 make dev-web # 终端 2安装前端依赖启动 :5183 make install-hooks # 安装 pre-push 测试钩子强烈建议前端开发服务器会自动把/api代理到127.0.0.1:8000无需额外配置。需要本地配置时把.env.example复制为.env并使用可丢弃的测试凭据。所有命令都定义在 Makefile 中make help可查看完整清单。读懂仓库结构贡献前先定位代码路径职责src/modules/产品模块及其 API、服务与业务流程src/modules/automation/定时/按需 Agent、目录、调度器与 TradingAgents 集成src/platform/AI、持久化、行情、通知、可观测与运行时基础设施packages/marketdata/支持数据源故障转移的独立强类型行情包frontend/src/React 应用、页面、组件、Hook 与多语言资源prompts/分析流程使用的 Prompt 模板tests/ / frontend/tests/后端与前端测试⚠️ 模块归属是硬约束产品模块可以依赖平台服务但独立包绝不能反向导入 PanWatch 应用或数据库。架构测试 tests/test_architecture_boundaries.py 会在 CI 中自动检查这些边界跨边界导入会直接导致测试失败。分支策略3 个要点 一道推送门禁从最新默认分支创建开发分支所有改动在分支上进行不直接向默认分支提交Codex 分支前缀通过 Codex 开发的改动除非维护者另有要求统一使用codex/前缀分支如codex/fix-quote-volumeSquash 合并仓库默认采用 squash merge你分支上的多个提交会在合并时压缩为一个干净提交——所以提交信息要写规范见下一节。pre-push 钩子测试不过推不出去仓库自带推送前门禁脚本 scripts/pre-push安装后每次git push会先执行后端测试失败即中止推送make install-hooks安装脚本 scripts/install-hooks.sh 会把钩子复制到.git/hooks/pre-push。它是新手最实用的最后一道保险避免把坏代码推到远端。Conventional Commits9 种类型写出让评审一眼看懂的提交PanWatch 要求提交信息统一使用英文并严格遵循 Conventional Commits 格式type(scope): subject常用 type 速查表type用途feat新功能fix缺陷修复refactor重构不改变行为perf性能优化test测试相关docs文档chore杂项维护build构建系统/依赖ciCI 配置scope 使用受影响的模块名如assistant、marketdata、frontend、i18nsubject 用简洁的英文祈使句不以句号结尾。官方示例feat(automation): add a pre-market risk digest fix(marketdata): handle empty quote volume docs(readme): clarify Docker startup behavior提交 PR 前跑一遍验证清单官方原则迭代时先跑最小聚焦测试开 PR 前再跑相关测试集。# 后端完整测试 .venv/bin/python -m pytest -q # 前端测试、多语言门禁、类型检查与生产构建 pnpm --dir frontend exec vitest run pnpm --dir frontend run check:i18n pnpm --dir frontend run build # 空白符和冲突标记检查 git diff --check几条容易踩坑的要求✅单元测试必须模拟网络调用不得依赖付费 API 或真实发送通知✅ 修改独立包时追加对应包测试如pytest packages/marketdata/tests -q✅ 前端文案变更必须通过 i18n 门禁它会拦截 frontend/src/ 与共享包中的硬编码字面量见 frontend/scripts/check-i18n-literals.mjs没有实际执行的检查不要写成已通过。环境受限跑不了检查时请在 PR 中明确说明限制。标准 PR 模板标题 5 段正文PR 标题和正文统一使用英文标题同样采用 Conventional Commits 格式。正文必须包含以下 5 个部分Background— 要解决什么问题、对用户有何影响Changes— 按模块分组说明实现与行为变化Validation— 实际执行的命令及其结果对应上一节的验证清单Boundaries and risks— 兼容性、未测试路径与已知限制Follow-up— 只记录明确留到后续处理的工作。常见贡献场景Agent、行情源与前端 i18n新增或修改 Agent—— 先判断类型workflow agent用户可见、可调度还是capability agent被其他流程调用、不独立调度。扩展点在 src/modules/automation/继承BaseAgent并分离collect()与build_prompt()用户可见定义写入 src/modules/automation/agent_catalog.py 的AGENT_SEED_SPECS可直接执行的 Agent 还要登记进 server.py 的AGENT_REGISTRY长 Prompt 放入 prompts/。新增行情数据源—— 先选对层级强类型 vendor报价、K线、基本面、资金流等放 packages/marketdata/ 并在registry.py注册PanWatch 特有的编排、缓存、适配逻辑放 src/platform/marketdata/collectors/。文档需说明认证、限流、市场覆盖与数据质量限制且种子对账绝不能覆盖用户凭据。前端文案—— 所有用户可见文案放入 frontend/src/i18n/locales/ 的中英文目录并保持结构同步语言只影响界面与报告不得隐式改变市场、币种、时区或股票代码。Issue 反馈与安全规范普通 Bug提交 Issue 时附上复现步骤、预期/实际行为、版本信息和脱敏日志——务必移除 Token、Cookie、账户标识、持仓等金融隐私数据安全问题不要在公开 Issue 中发布利用细节或凭据遵循 SECURITY.md 中的私密报告方式。常用命令速查表命令作用make dev-api启动后端:8000自动装依赖make dev-web启动前端:5183自动 pnpm installmake test跑全部后端单测默认不发通知make install-hooks安装 git pre-push 测试钩子make doctor系统自检数据源/AI/通知/DB/磁盘/调度git diff --check开 PR 前的空白符与冲突标记检查掌握「分支策略 → Conventional Commits → 验证清单 → 5 段 PR 模板」这条主线再配合官方指南与架构测试的约束你的第一个 PanWatch PR 就会像项目现有提交一样清晰、可评审、可合并。【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK US markets, powered by TradingAgents. Portfolio insights, real-time alerts automated reports.盯盘侠覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
