企业官网建设流程全解析

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/PanWatch

PanWatch 是一款覆盖 A股、港股、美股的 AI 盯盘工具，提供持仓分析、实时提醒与自动报告。本文贡献指南将完整解读它的 Conventional Commits 提交规范、分支策略与 Pull Request（PR）规范，帮助新手一次性提交出规范的 Pull Request，顺利进入开源协作流程。

开始之前：先读官方贡献指南的 4 条铁律

📌 动手之前，先通读官方指南：中文版 CONTRIBUTING.zh-CN.md 与英文版 CONTRIBUTING.md。官方列出了 4 条基本原则：

1. 先搜后做：开发前先搜索已有 Issue 和 PR，避免重复劳动；
2. 先提 Issue：大型功能、架构调整、新依赖或破坏性变更，先开 Issue 说明用户问题和计划边界；
3. 零敏感信息：绝不提交 API Key、Token、Cookie、个人持仓、本地数据库或含隐私数据的日志；
4. 保持 PR 聚焦：与功能无关的清理请拆到单独的 PR。

一键启动开发环境

PanWatch 前后端分离：Python 后端（:8000）+ React 前端（:5183）。环境要求：

克隆仓库并启动：

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可查看完整清单。

读懂仓库结构：贡献前先定位代码

⚠️ 模块归属是硬约束：产品模块可以依赖平台服务，但独立包绝不能反向导入 PanWatch 应用或数据库。架构测试 tests/test_architecture_boundaries.py 会在 CI 中自动检查这些边界，跨边界导入会直接导致测试失败。

分支策略：3 个要点 + 一道推送门禁

1. 从最新默认分支创建开发分支，所有改动在分支上进行，不直接向默认分支提交；
2. Codex 分支前缀：通过 Codex 开发的改动，除非维护者另有要求，统一使用codex/前缀分支（如codex/fix-quote-volume）；
3. Squash 合并：仓库默认采用 squash merge，你分支上的多个提交会在合并时压缩为一个干净提交——所以提交信息要写规范（见下一节）。

pre-push 钩子：测试不过，推不出去

仓库自带推送前门禁脚本 scripts/pre-push，安装后每次git push会先执行后端测试，失败即中止推送：

make install-hooks

安装脚本 scripts/install-hooks.sh 会把钩子复制到.git/hooks/pre-push。它是新手最实用的"最后一道保险"，避免把坏代码推到远端。

Conventional Commits：9 种类型写出让评审一眼看懂的提交

PanWatch 要求提交信息统一使用英文，并严格遵循 Conventional Commits 格式：

<type>(<scope>): <subject>

常用 type 速查表：

scope 使用受影响的模块名，如assistant、marketdata、frontend、i18n；subject 用简洁的英文祈使句，不以句号结尾。官方示例：

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 个部分：

1. Background— 要解决什么问题、对用户有何影响；
2. Changes— 按模块分组说明实现与行为变化；
3. Validation— 实际执行的命令及其结果（对应上一节的验证清单）；
4. Boundaries and risks— 兼容性、未测试路径与已知限制；
5. 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 中的私密报告方式。

常用命令速查表

掌握「分支策略 → 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