企业官网建设流程全解析

tick-stock-panel贡献指南：从AGENTS.md到PR流程，快速成为A股量化工作台共建者

【免费下载链接】tick-stock-panelTSP自托管、零运维的 A 股「选股 + 监控 + 回测」量化工作台 | LLM能力驱使策略定制+个股分析+复盘 | 自由接入第三方数据源与个性化扩展数据 | 个人开源项目地址: https://gitcode.com/GitHub_Trending/ti/tick-stock-panel

tick-stock-panel（TSP）是一个自托管、零运维的 A 股「选股 + 监控 + 回测」量化工作台，支持 LLM 驱动的策略定制、个股分析与盘后复盘，并自由接入第三方数据源。本文是面向新手的 tick-stock-panel 贡献指南：带你读懂根目录的 AGENTS.md 与 CONTRIBUTING.md，掌握 PR 提交与复审流程，从第一个 bug 修复开始成为项目共建者。

3 份必读文档：贡献前先看什么

项目把贡献规范集中在 3 个文件里，修改任何代码前都值得完整读一遍：

💡 一个容易踩的坑：AGENTS.md 特别强调「不得根据设计示例虚构尚不存在的 API」。用 AI 辅助开发时，先让它读这 3 份文档，能大幅减少返工。

先懂主数据流：让改动落在正确的模块

CONTRIBUTING.md 定义了项目的主数据链路，贡献前务必沿这条链检查上下游：

数据源/数据插件 → services 同步与标准化 → Parquet 存储 → indicators 生成 enriched 数据 → 策略/监控/回测服务 → FastAPI API → 前端 TanStack Query → 页面组件

几个新手最需要注意的约定（摘自 CONTRIBUTING.md 第 2~4 节）：

• 模块边界：backend/app/api/保持薄层不放重计算；业务编排放backend/app/services/；数据源适配放backend/app/data_providers/。
• 数据契约不可混用：金融数据错了常常不报错、只产出「看起来合理」的错误结果。涨跌幅有小数制与百分数两种口径、enriched 价是前复权、涨停判断必须用原始价、窗口按交易日而非自然日——涉及这些字段时必须写单测证明口径。
• 数据源插件化：通用功能必须通过 provider 能力访问数据（如 capabilities.py 的能力路由矩阵），不能把单一数据源硬编码进策略或 API；缺能力时应明确降级（fail-closed），而不是静默换错数据。

一键搭建本地开发环境

Dev 模式只需要 4 步：

1. 克隆仓库（Python ≥ 3.11、Node ≥ 20，装好 uv 与 pnpm）：

   git clone https://gitcode.com/GitHub_Trending/ti/tick-stock-panel cd tick-stock-panel

2. 复制配置：cp .env.example .env，按需填TICKFLOW_API_KEY（留空即 None 模式，历史日K免费）。

3. 一键启动：执行根目录的 dev.sh（Windows 用dev.ps1），它会自动安装依赖、释放被占端口，同时拉起后端（3018）与前端（3011），Ctrl-C 同时关闭两端。

4. 验证改动，CONTRIBUTING.md 给出的标准命令组合：

   cd backend && uv run pytest tests/path/to/test_x.py -q uv run ruff check app/path.py tests/path.py cd ../frontend && pnpm build git diff --check

原则很简单：后端改动跑受影响模块的 pytest + Ruff；前端改动至少跑一次pnpm build。

PR 提交清单：一个可审查的 PR 长什么样

项目要求一个 PR 只解决一个问题，功能、重构、格式化、依赖升级不得混在一起。PR 描述必须覆盖 8 个部分（CONTRIBUTING.md 第 10 节）：

1. 问题与复现— 原行为、复现条件、影响范围
2. 根因— 具体到调用链或数据契约，不能只写「修复 bug」
3. 解决方案— 改了哪些模块、为什么没破坏插件化
4. 兼容性— 对历史配置、旧策略 JSON、旧 Parquet 的影响
5. 性能— 是否进入实时/列表热路径，性能主张要附前后数据
6. 验证结果— 列出实际执行的命令和结果，不写计划
7. 界面证据— 有可见变化时附修改前后截图，如 gui-test-screenshots/ 中的验证截图
8. 风险与回滚— 剩余风险与可行的回滚方式

提交前对照文档中的作者自检清单过一遍，核心是三条：改动可追溯到当前问题、核对过单位/复权/交易日/时区、错误路径 fail-closed 不静默返回错误金融结果。

PR 复审流程与 P0~P3 严重级别

复审按固定顺序进行（第 11 节），避免只看页面效果：复现问题 → 检查模块边界 → 核对数据契约 → 核对插件化 → 跟踪缓存与状态变化 → 检查兼容性 → 检查性能与并发 → 检查失败路径 → 评估测试质量 → 逐项看 diff → 给出结论。

问题按 4 级定档，直接决定能否合并：

另外，CI 质量门（.github/workflows/ci.yml）会在每次 PR 上自动跑后端全量 pytest + 前端构建，开放 API 契约快照有变化也会被拦下——本地跑绿只是起点，CI 通过才算数。

从第一个 PR 到共建者：推荐的进阶路线

1. 修一个真实 bug：从 issue 或自己使用中发现的问题入手，先写复现测试再修复（这正是 CONTRIBUTING.md 的完成标准）。
2. 补测试与文档：数据源契约测试、缺失能力降级路径、docs/ 下的领域文档，都是低门槛高价值的贡献。
3. 做一个扩展：新数据源插件（参考 docs/plugin-development.md、docs/custom-data-source.md）或自定义策略（放data/strategies/），优先走 L1/L2 低升级风险路径。
4. 参与复审：按第 11 节的输出格式（结论 + 阻断问题 + 已验证 + 剩余风险）给别人的 PR 提意见，复审能力是共建者的分水岭。

⚠️ 安全红线：不要提交data/目录、密钥、Token、用户策略或机器绝对路径；文件删除类操作必须校验范围并保持 fail-closed。这些是「不得合并」的硬性条款。

按这套指南提交你的第一个 PR 吧——改动范围更小、金融口径有证据、测试能真实复现问题，就是项目衡量贡献质量的标准。🚀

【免费下载链接】tick-stock-panelTSP自托管、零运维的 A 股「选股 + 监控 + 回测」量化工作台 | LLM能力驱使策略定制+个股分析+复盘 | 自由接入第三方数据源与个性化扩展数据 | 个人开源项目地址: https://gitcode.com/GitHub_Trending/ti/tick-stock-panel