diff --git a/AGENTS.md b/AGENTS.md index ebd6313..e67c916 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,7 +57,7 @@ data → universe → factors(特征) → alpha(合成/预测) → portfolio(+ri ## 开发约定 - **交流中文**;代码/注释/commit message 用**英文**。 -- **Git**:feature 分支 + PR。**PR #1(P0+P1)、#2(P2-1)、#3(P2-2)、#4(进度文档)、#5(P2-3)、#6(进度文档)、#7(P2-4)、#8(进度文档)、#9(P3-1)、#10(进度文档)、#11(P3-2)、#12(P3-3)、#13(进度文档)、#14(P3-4)、#15(进度文档)、#16(P3-5)、#17(进度文档)、#18(P3-6)、#19(P3-7)、#20(进度文档)、#21(P3-8)、#22(进度文档)、#23(P4-1)、#24(进度文档)、#25(P4-2)、#28(tushare 权限/限频探测 + capability registry)、#29(I1–I4 分钟级 intraday pipeline,4 commit 一 PR)、#30(进度文档)、#31(P4-3 因子支撑端点缓存 + 21:00 data updater,2 commit 一 PR)、#33(P-I5a 事件驱动回测架构重构 + opt-in 分钟尾盘 event model,4 commit 一 PR)、#35(P-I5b 分钟尾盘执行期 raw stk_limit 涨跌停可行性,4 commit 一 PR)、#37(P-I5c MMP 分钟因子端到端 opt-in alpha)、#39(P-I5d MMP 五分位分组回测 standalone,含 I5c plumbing)、#41(数据层 D1 契约文档 + token 解析去重)、#43(数据层 D2 TushareCache specs/parsers 拆分)、#45(数据层 D3 report-only 数据质量层)均已 merge 到 `main`**。commit 用 conventional 格式,**无 attribution**(不加 Co-Authored-By)。 +- **Git**:feature 分支 + PR。**PR #1(P0+P1)、#2(P2-1)、#3(P2-2)、#4(进度文档)、#5(P2-3)、#6(进度文档)、#7(P2-4)、#8(进度文档)、#9(P3-1)、#10(进度文档)、#11(P3-2)、#12(P3-3)、#13(进度文档)、#14(P3-4)、#15(进度文档)、#16(P3-5)、#17(进度文档)、#18(P3-6)、#19(P3-7)、#20(进度文档)、#21(P3-8)、#22(进度文档)、#23(P4-1)、#24(进度文档)、#25(P4-2)、#28(tushare 权限/限频探测 + capability registry)、#29(I1–I4 分钟级 intraday pipeline,4 commit 一 PR)、#30(进度文档)、#31(P4-3 因子支撑端点缓存 + 21:00 data updater,2 commit 一 PR)、#33(P-I5a 事件驱动回测架构重构 + opt-in 分钟尾盘 event model,4 commit 一 PR)、#35(P-I5b 分钟尾盘执行期 raw stk_limit 涨跌停可行性,4 commit 一 PR)、#37(P-I5c MMP 分钟因子端到端 opt-in alpha)、#39(P-I5d MMP 五分位分组回测 standalone,含 I5c plumbing)、#41(数据层 D1 契约文档 + token 解析去重)、#43(数据层 D2 TushareCache specs/parsers 拆分)、#45(数据层 D3 report-only 数据质量层)、#47(数据层 D3b default-off `data-update` 质量报告钩子)均已 merge 到 `main`**。commit 用 conventional 格式,**无 attribution**(不加 Co-Authored-By)。 - **不过度设计**:按路线图 MVP 先打通一条端到端链路,再加层(architecture.html §11,Phase 0→3)。 - **secrets** 一律走外部 `.config.json`;repo `.gitignore` 已排除数据产物(`*.parquet`等)、缓存、`tmp/`(仅留架构文档)。 - 文件小而专(<800 行),immutable 优先。 @@ -223,7 +223,13 @@ data → universe → factors(特征) → alpha(合成/预测) → portfolio(+ri - ✅ **数据层 D3 — report-only 数据质量层**(**PR #45 已 merge 到 `main`**,含 review 一修复;纯库 + 测试,**report-only 非 cleaning**):新增独立 `data/quality/` 包,在接入处附近**只报告**可疑上游数据,**绝不**过滤行/修复值/改 qfq/改 cache coverage/动 feed·factor·alpha·portfolio·runtime。 - **包**(纯函数,输入 DataFrame→findings,输入永不被改):`report.py`(`QualityFinding` + `make_finding`(样本限 5、清洗)+ `findings_to_frame`(稳定确定序)+ `render_report`(确定性 Markdown,clean→"No findings")+ secret redaction);`market.py`(日频:dup(date,symbol)/非正 OHLC/high 目的:把 **`cache`(缓存)** 与 **`store`(面板存储)** 的边界写成可提交的契约, > 让后续改动有明确不变量可守。本文件只描述 **当前已实现** 的行为,不预告未实现的阶段。 -已实现:**D1**(边界文档化 + 低风险 token 解析去重)、**D2**(`TushareCache` endpoint specs/parsers 拆分,公开缓存行为不变)、**D3**(report-only `data/quality/` 数据质量层)。**D4–D6 尚未实现**,本文件不声称其存在。 +已实现:**D1**(边界文档化 + 低风险 token 解析去重)、**D2**(`TushareCache` endpoint specs/parsers 拆分,公开缓存行为不变)、**D3**(report-only `data/quality/` 数据质量层)、**D3b**(默认关闭的 `data-update` 质量报告钩子,report-only)。**D4–D6 尚未实现**,本文件不声称其存在。 --- @@ -42,7 +42,7 @@ - 它 **不跑 factor / alpha / portfolio / backtest,不写 `PanelStore`**。 - 真实回测仍各自走 read-through,按需补自己的缺口;`data-update` 只是把常用 endpoint 提前填好。 -## 4. D1 / D2 / D3 已做什么;D4+ 范围(未实现) +## 4. D1 / D2 / D3 / D3b 已做什么;D4+ 范围(未实现) **D1**(行为零改动)做两件低风险事:**把上述边界写成本契约文档**,以及 **把 `TushareFeed` / `IndexConstituentsFeed` 里重复的 token 解析收敛到共享的 `data/feed/secret.py::read_token`** @@ -57,8 +57,16 @@ endpoint 常量/specs → `data/cache/tushare_specs.py`、raw endpoint 解析器 **D3**(report-only 数据质量层,库 + 测试)新增独立的 `data/quality/` 包,在接入处附近**只报告**可疑的上游 日频行情 / `adj_factor` / 1min 分钟数据,**绝不**过滤行、修复值、改 qfq、改 cache coverage、或动 feed/factor/ alpha/portfolio/runtime。纯函数:输入 DataFrame → findings(含 dataset/check 元数据 + bounded 样本),输入永不被 -改;findings/渲染报告携带 redaction guard,不含 token/secret 路径/无界 dump。可选的 `data-update` 集成**推迟到 D3b** -(本阶段仅库 + 测试,零 config/命令行为变更)。 +改;findings/渲染报告携带 redaction guard,不含 token/secret 路径/无界 dump。 + +**D3b**(默认关闭的 `data-update` 质量报告钩子)把 D3 质量层接入运维:新增严格的 `data_update.quality` +配置(`enabled` 默认 **false**,所以所有现存配置行为不变)。开启后,`data-update` 在它 **已经暖好的**帧 +(market bars + 1min 分钟,**不额外打 API**)上跑 D3 的**结构**检查,并把确定性 Markdown 报告写到 +`output.report_dir`(clean 也写)。可检查端点仅限 updater 以帧形式加载的结构面:`market_daily` / `adj_factor` +/ `stk_mins_1min`;报告只含 bounded/redacted findings + 窗口/符号**数量**,不含 secret 路径/token/无界 symbol +dump。**report-only**:不过滤/修复/改数据,不让 job 失败,不改 cache coverage / 每端点请求 summary,不动 +feed/factor/alpha/portfolio/runtime/backtest 语义(日频 close-to-close 不漂移)。不合成交易日历(仅结构检查; +缺日期/缺分钟的 D3 检查在 D3b 关闭)。 以下明确 **仍未实现**(D4+,本文件 **不声称已实现**):