wushi_band 接入 tick 行情计划 v1（2026-10-17）
性质：计划稿，只出计划、不写代码、不动仓库（plan-first 纪律）。现状部分基于 2026-10-17 经 F7 对 Mac 上
/Users/junjun/Desktop/Projects/wushi_band/的两轮只读勘察，以及本机既有 jvQuant 通道验证记录。文中量级数字均为带假设的估算，一期实测后校准。
一、现状摘要
1.1 仓库与主链
- 仓库为扁平结构：根目录 60+ 个
.py、共 119 个.py文件；唯一成型的包是wushi_control/（17 文件）；无pyproject.toml，requirements.txt仅 7 行且未钉版本（websocket-client、httpx、a2a-sdk、fastapi、uvicorn、openai、pyyaml；pandas/numpy/akshare/requests 为未声明的隐式依赖）。 - 实际主程序是
scripts/six_eye_parliament.py（议会：组装案卷 → 并行派发各"眼" → 收票 → 仲裁）；prepare_parliament_briefing.py是 Step 0 案卷生成器。无统一main入口，靠 launchd plist + 手动跑脚本启动。
1.2 行情现状：源已存在，缺的是出口、落盘与消费口
- 唯一的实时行情源在仓库之外：Mac 本机的 F18 行情服务（
f18-marketdata/server.py，launchdcom.junjun.f18-jvquant.plistKeepAlive 常驻），它维持着对 jvQuant 的 WebSocket 长连接，已支持 L1/L2/L10 订阅；另有com.junjun.f18-l2-arm.plist在工作日 09:16 一次性"武装"L2 订阅。 - 仓库内只有一个 HTTP 轮询客户端
f18_client.py：base URL 写死http://127.0.0.1:8007，每次调用新建 urllib GET、10 秒超时、无缓存、无重试，失败不抛异常而是返回{"error": ...}。对外函数为get_quote/get_quotes/get_summary/get_parliament_briefing_data等。 /quotes的返回结构已经包含十档盘口（bid_prices/bid_volumes/ask_prices/ask_volumes）和price/change_pct/volume/amount/timestamp——即 F18 服务端手里已有盘口快照流，只是仓库侧只取了标量字段在用。- tick 在仓库内是零：关键词"tick"45 处命中全部是"票据（ticket）"；"逐笔""盘口"全仓 0 命中；无 tick 落盘、无 tick 聚合、无 tick 消费方。
- 消费方式：
prepare_parliament_briefing.build_briefing()调get_parliament_briefing_data(codes)把整段 markdown 注入案卷，每次运行现拉、无缓存；six_eye_parliament.py本体不 import f18，只消费冻结文本。F12 证据层读预生成 JSON（默认 36h 时效门）。
1.3 其他数据路径（与 tick 无关、勿混用）
tushare_probe.py：一次性探针，只打印不落盘。etf_flow_mac.py：Tushare 基金份额/日线，落tushare_out/的 md。rs_signal_calc.py：AmazingData 日线（依赖 Mac Docker）。仓库外data_center/daily_collector.py工作日 15:05 拉 akshare/sina 日线落 CSV。- 存储现状：标准库 sqlite3 仅用于交易状态（
state.sqlite3、risk_ledger.sqlite3、workflow.sqlite3）；无 pyarrow/duckdb/sqlalchemy。注意.gitignore明确拒收*.parquet、*.db、.env——行情落盘文件不应进仓库目录（见 3.1）。
1.4 通道盘点（关键约束）
当前与 jvQuant 相关的连接已有两条：
| 通道 | 位置 | 形态 | 现职责 |
|---|---|---|---|
| F18 server | Mac 本机 | jvQuant WS 长连接（L1/L2/L10 可订阅），launchd 托管 | wushi_band 议会的行情证据层 |
| jv_listener | 本机 VM | jvQuant WS 监听进程（jv_listener.py，已验证 L1/L2 通道、额度记录 20050） |
投研线盘中异动等监听 |
结论：tick 接入不新开第三条通道。 逐笔流只存在于 F18 服务端的 WS 里，HTTP 轮询 /quotes 只能拿快照、拿不到逐笔——这是接入点选址的决定性事实。
二、接入点设计
2.1 选址：F18 服务端同机旁路（Mac）
在 Mac 本机、F18 服务旁挂一个独立进程的 tick 记录器（recorder），数据不出 Mac：议会、策略、F18、落盘、回放全部同机，零跨机搬运。仓库 wushi_band/ 内一期不新增任何代码，二期才加只读消费模块。
逐笔流如何从 F18 到 recorder，两条路线：
- 路线 A（推荐）：F18 服务端加旁路出口。 在
f18_adapter的 WS 消费循环里加一个可开关的旁路：把已订阅的逐笔/快照原始消息同时投递给本机 recorder（本机 socket/文件队列）。优点：单条 WS、零新增订阅与连接额度、数据与议会所见完全同源。代价：要改仓库外的 F18 服务本体（它在产、议会 Step 0 在用），改造须走 F18 自己的变更纪律，且旁路必须异步、满了就丢、绝不阻塞 WS 主循环。 - 路线 B（备选）：recorder 在 Mac 上自开一条 jvQuant WS，只订阅一期白名单标的。优点：完全不碰 F18 本体。代价：同机第二条连接、与 F18 订阅重叠，须先核清 jvQuant 的连接数/订阅数额度（现有"额度 20050"口径具体指什么、F18 与 VM jv_listener 是否共用同一账号额度池，均待核——见拍板点 1）。
VM 侧 jv_listener 不扩 tick 职责：它服务投研线监听，与 wushi_band 不同机、不同链，tick 落盘放它身上会带来跨机搬运与职责混杂。
2.2 仓库侧消费口（二期才建）
在仓库内新增一个与 f18_client.py 对偶的只读模块（暂名 tick_client.py）：只读落盘文件，对上提供"按标的+时间窗取聚合特征"的接口，输出结构对齐现有案卷习惯（dict/markdown 段）。prepare_parliament_briefing 增加一个默认关闭的开关，开启时把 tick 特征段追加进案卷；six_eye_parliament.py 本体不改（它消费冻结文本的模式天然兼容）。
三、分期步骤
一期：只读落盘（纯旁路，零侵入主链）
- 核额度与订阅清单：确认路线 A/B、jvQuant 连接与订阅额度、白名单标的（建议复用
config/annotation_ontology.json里已有的 pilot 5 只，见拍板点 2）。 - recorder 上线：订阅白名单的 L2 逐笔成交 + 十档快照（逐笔委托是否要，见拍板点 4），按 3.1 的格式落盘到仓库外目录；带断线重连、缺口日志、磁盘配额熔断。
- 每日对账脚本（只读）：落盘逐笔合成的日成交量/额与 F18
/summary及日线口径比对，输出差异报告。 - 连续跑满 5 个交易日验收（见第五节），并实测单日磁盘增量，回填本计划的量级估算。
一期红线：recorder 停止/崩溃不得影响 F18 与议会任何现有行为；不落盘白名单外标的；数据仅存 Mac 本机。
二期：喂策略（先 shadow、后入案卷）
- 聚合层：从落盘 tick 生成 1min/5min bar、VWAP、盘口失衡（十档量差）、大单净流入等特征，按标的+日落一份特征文件。
- 一致性校验：特征中的量比/涨跌口径与现有
/summary（rsi、volume_ratio 等）逐日对照，偏差成表。 - shadow 模式 ≥10 个交易日：
prepare_parliament_briefing生成"含 tick 段"的影子案卷但不送议会，只存档对照。 - 拍板后才把开关默认打开，tick 段正式进案卷（仍只是证据层，不直接触发任何交易动作——与 F18 现定位一致）。
三期：回放
- 回放器：按原始时间戳顺序把落盘 tick 喂给二期聚合层与影子案卷生成，支持倍速与断点。
- 用途：盘后复盘、聚合参数对照实验、议会案卷的离线重演（同日回放两次结果须逐字节一致，见验收）。
- 回放与实盘共用同一份聚合代码与输出格式，杜绝"回放一套、实盘一套"。
四、数据落盘格式与量级估算
3.1 位置与格式
- 位置：仓库外独立目录（建议
~/Desktop/Projects/wushi_band_data/tick/，与仓库平级），按date=YYYYMMDD/code=<代码>/分区。理由：.gitignore已拒收 parquet/db，仓库内 40+ 个.bak已显臃肿，行情数据 GB 级增长不进代码仓。 - 格式：Parquet（zstd 压缩、列存）为目标格式——需新增
pyarrow依赖（仓库当前无此依赖，列入拍板点 3）。若想一期零依赖起步，可先用 JSONL 按小时分文件落盘、二期聚合时转 Parquet，但字段 schema 一期就须定死、与 Parquet 版一致。 - 表结构（两张表）：
- 逐笔成交
trades：ts（交易所时间戳，毫秒）、recv_ts（本机接收时间）、code、price、volume、amount、bs_flag（主买/主卖，源有则存）、order_id_buy/order_id_sell（源有则存）。 - 盘口快照
books：ts、recv_ts、code、last_price，及bid_price_1..10/bid_vol_1..10/ask_price_1..10/ask_vol_1..10。 - 双时间戳（交易所 + 本机接收）必须都存：对账、延迟测量、回放保真都靠它。
3.2 量级估算（估算值，一期实测校准）
假设：一期白名单 5 只、均为活跃股；L2 逐笔成交每只日均约 5万–30万笔（取中位 15万笔计）；十档快照按约 3 秒一帧、每帧一行宽表约 200B（Parquet 压缩后）。
| 数据 | 5 只/日（估算） | 扩至 30 只/日（估算） | 备注 |
|---|---|---|---|
| 逐笔成交 | 75 万行，约 15–25 MB | 约 100–150 MB | Parquet 列存压缩后 |
| 十档快照 | 约 5 MB | 约 30 MB | 逐笔委托若全存，再 ×5–10 |
| 合计 | 约 20–30 MB/日 | 约 130–180 MB/日 | 年化（250 交易日）30 只约 35–45 GB |
保留策略建议：热存 60 个交易日，之后按周抽样/转冷归档；recorder 设目录配额上限（建议 50GB）与 80% 告警，宁可熔断停录、不可打满 Mac 系统盘。
五、风险与回滚
| 风险 | 说明 | 缓解 |
|---|---|---|
| 拖垮 F18 主链 | 路线 A 改服务端，若旁路写盘阻塞 WS 消费会丢包、殃及议会证据层 | 旁路异步队列＋满即丢弃＋独立进程隔离；上线前做开/关对照延迟测试（见验收） |
| 额度与连接数 | F18、VM jv_listener 两条 WS 已并存；jvQuant 连接/订阅额度口径（20050）未核清前，新增订阅可能挤占现有订阅 | 一期动手前先核额度（拍板点 1）；路线 A 优先正是为零新增连接 |
| 磁盘打满 | tick 量级 GB/月增长，Mac 为日常用机 | 仓库外目录＋配额熔断＋滚动保留（3.2） |
| 时钟与时效 | Mac 本机时钟漂移会污染 recv_ts 与回放 |
落盘双时间戳；recorder 启动时记录与行情源时间差 |
| 依赖面扩大 | 新增 pyarrow；仓库 requirements 未钉版本、隐式依赖已多 | 新依赖钉版本、只加在 recorder/聚合侧，不进议会主链环境 |
| 数据授权 | L2 数据来自 jvQuant 订阅，落盘仅限本机研究用途 | 不外传、不上云、不同步进任何仓库（含备份仓） |
| 口径误用 | tick 特征若被议会当作实时信号直接用，违背"证据层"定位 | 二期 shadow 先行；进案卷也只作证据段，开关默认关 |
回滚：一期为纯旁路——停掉 recorder 的 launchd 任务即完全回滚，F18 与仓库零残留（落盘目录可整目录删除）；二期回滚＝关 prepare_parliament_briefing 的 tick 开关，案卷恢复原样；三期回放为离线工具，无生产回滚概念。
六、验收标准
一期（落盘）
1. 连续 5 个交易日全程落盘，无整日缺失；断线演练：人为断开 WS，60 秒内自动恢复，缺口时段在日志中有明确记录。
2. 对账：逐笔合成的日成交量/成交额与日线口径（data_center 日线）逐只比对，误差 <0.5%，超限须给出可解释原因（如集合竞价口径差异）。
3. 无侵入：recorder 开与关两种状态下，F18 /quotes 响应延迟 p95 无显著变化（同日对照，变化 <10%）；议会 Step 0 案卷生成结果逐字一致。
4. 磁盘：实测单日增量与 3.2 估算偏差 <2 倍；配额熔断演练触发一次并正确停录+告警。
二期（喂策略）
1. 聚合特征与 /summary 既有口径（量比等）逐日对照表，偏差来源可解释。
2. shadow ≥10 个交易日，影子案卷与正式案卷的 diff 仅限新增 tick 段，其余逐字一致。
3. 开关打开后首周，议会引用 tick 段的表述可在落盘数据中逐条复核（抽 3 条）。
三期（回放） 1. 同一交易日回放两次，聚合输出逐字节一致（确定性）。 2. 回放速度 ≥10 倍速跑通全天数据不丢行（行数与落盘一致）。
七、待用户拍板点清单
- 通道与额度：确认以 Mac F18 为 tick 主通道、VM jv_listener 不扩 tick 职责；并核清 jvQuant 的连接/订阅额度口径（"20050"指什么、F18 与 VM 监听是否共用同一账号额度池）。
- 改造许可（路线 A/B）：路线 A 要改仓库外 F18 服务本体（加旁路出口），路线 B 要在 Mac 上新开一条 jvQuant WS——选哪条，或先核额度再定。
- 一期标的池：复用标注本体的 pilot 5 只，还是投研异动名单的 10 只（量级估算按 5 只做的，10 只约翻倍）？
- 订阅深度：逐笔成交＋十档快照（本计划默认），还是再加逐笔委托（量级再涨 5–10 倍、聚合价值待评估）？
- 落盘格式与依赖：Parquet 一步到位（新增 pyarrow 并钉版本），还是 JSONL 过渡、二期再转？
- 落盘位置与保留期：仓库外
wushi_band_data/（建议）＋热存 60 个交易日（建议），是否认可？ - 二期门槛：shadow ≥10 个交易日后，tick 段进正式案卷——由用户届时单独拍板，本计划不预授权。
附：本计划的现状事实来源——F7 只读勘察两轮（2026-10-17，目录/入口/配置/依赖/关键词/数据层/消费方式/F18 细节），及本机 jvQuant 通道既有验证记录（VM 侧 jv_listener 在跑、L1/L2 已验）。F18 服务端的 WS 消费循环内部结构未深挖，路线 A 的旁路挂点位置在一期动手前需再做一次针对性只读勘察。