mcp-cn-a-stock: Instructions file for Codex

项目开发约束

这是一个开源的 A 股数据服务。

运行与发布

• 服务启动、停止和重启统一通过 start.sh / stop.sh，不另起进程或手工改 pidfile。
• 发布前必须在待发布版本上运行 scripts/verify_release.py 并通过验证，保留报告。

一、优先级:数据完整 > 功能正确 > 性能

• 任何改动只要可能让某一维数据变少、变旧、变不准,就不做——哪怕它更快、更省内存。 缺一段数据用户看得见,快 200 毫秒看不见。
• 不为省资源换一条数据更差的路。
• 结论是"不值得改"同样是有效产出,写进注释即可。

二、取数:每一维都要能换源

• 一维数据不能只挂在一个源上。 加一个源的成本要低到愿意加——做不到是抽象没提对, 不是源难接。
• 回退是常态不是异常。 上一个源没给出结果就问下一个,空结果同样往下走。
• 每一级失败留下能定位到源的日志。 查一个数是谁给的,不该靠猜。
• 各给一部分字段就合起来用。 对同一字段给出不同的值是仲裁问题:按固定顺序判, 把差异记进已知差异清单——不能让"谁先返回"决定数据。

落地形态见 docs/architecture.md,两者冲突时以上面四条为准。

三、性能:有界、可比、等价

• 目标是降低 MCP 调用耗时,尤其多标的多批次并发下的 P95 和最长耗时。
• 消除排队、重复请求、串行等待。线程、任务、队列、连接池、缓存一律有界且可回收。 任何「N × 单次超时」的结构都要有总预算——调小单次超时只是换个系数。
• 验证覆盖单批 4 个标的,以及同时 5 批、10 批,比端到端耗时、P90/P95、最大、吞吐、错误率。
• 优化不得改变返回数据。前后用同一组请求做输出比对(逐字或哈希)证明等价:覆盖钉日期 和实时两类,先关掉报告缓存,并先用同一份代码连跑两次确认基线稳定——上游本身会抖。

四、资源与环境

• 峰值内存 ≤ 500 MiB,按服务及其全部子进程(浏览器、Xvfb 这些)的合计峰值算, 超限的性能提升一律不采纳。
• Ubuntu 优先,不依赖 macOS 专属能力。发布前在目标环境验证启动、停止、并发、 浏览器回退和内存峰值。

五、改动前先算,值要量出来

• 改关键配置、加缓存/回退/熔断、调并发上限,先写下三件事:省的是哪个可观测量、省多少; 代价落在哪(同一条链路上还有哪些阈值会跟着变);碰不碰数据完整性。有一件写不出来 就先别写代码。
• 可观测量指:命中率、P95、吞吐、峰值内存、上游请求数、积分消耗、数据陈旧度。 不能只说"更快"或"更稳"。收益说不清量级的、与副作用相当的,保持默认不动。
• 优先用生产日志或归档回放估收益,不靠推理。 已有机制可能已经把收益吃掉了。
• 参数的值要量出来,不是拍出来。 能自动量的做成 scripts/probe_tuning.py 的一项, 让它出推荐值和证据。预算/上限类参数按最大值定,不按分位数——分位数按定义会砍尾部, 而那正是要保住的部分。
• 报"没问题"之前,先证明这个测量测得出问题(注入一次已知故障看它报不报)。

六、这是开源项目,不绑任何一台机器

• 配置项的注释只写两样:这个参数是什么含义、怎么为自己的环境取值。不写某次事故的 时间、请求 ID、逐条实测秒数——那些归 commit message 和 git 历史。
• 措辞用「当前环境」,别写「本机」「部署机」这类指某一台机器的说法。

七、提交信息精简、不带署名

• 禁止任何署名或协作者 trailer(Co-Authored-By、Generated with、Signed-off-by)。
• 一行标题说清改了什么;正文最多三五行,只留判断依据。不贴时间线、不复述代码。 只有 breaking change 才允许写长,写明破坏了什么、调用方怎么改。
• 详细推导写进代码注释或文档——那里才会被下一个人读到。