chore: release v0.5.21

CHANGELOG.md

@@ -6,6 +6,89 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 Breaking changes within the 0.x line are called out explicitly.
 
+## [0.5.21] — 2026-10-11
+
+### 修复：资产负债表 / 利润表 / 现金流量表此前一直是空表（#116，#117 by @ontheway06）
+
+新浪财报接口的结果在 `data.report_list{报告期: {publish_date, update_time, …, data: [{item_title, item_value}]}}`
+里，而 v0.2.5（2026-05-17）去掉 akshare 时写的解析只认 `data.<fzb|lrb|llb>` 行列表，
+三个取数函数于是一直返回「No … data found」这样的正常字符串——不报错，基本面分析师
+会把「该股没有财报」当成事实写进报告。近 5 个月里基本面分析拿不到三张表。
+
+- 两种结构都认（行列表的写法保留兼容），以后结构再变也先在这里报空表而不是崩（#117）。
+- 同名科目不再互相覆盖：利润表里营业总收入下、财务费用下各有一个「利息收入」，后一个
+  记作「财务费用-利息收入」。
+- 实测 600519：三张表从 44~51 字符的「No data」变成 6~10k 字符的完整报表；
+  深市（000001）、北交所（920819）同样能取到。
+
+### 修复：回看历史日期时提前看到还没公布的财报（随上一条一起修）
+
+原来按「报告期 ≤ 分析日」筛选：分析日 07-15 会拿到 8 月才公布的半年报。三张表以前是
+空表，所以这个口子一直没暴露；表一恢复就会变成未来函数。现在一份财报满足下面任一条
+才算分析日当天已公布（都是严格早于分析日）：
+
+- 新浪给的公告日早于分析日；
+- 新浪的入库时间（北京时间）早于分析日当天——多数是公布前一晚入库；
+- 两个日期都晚于报告期一年以上（或接口根本没给），说明原始日期已被后来的报表改写丢失，
+  这时才按法定披露截止日判断：一季报、三季报为报告期结束后 1 个月，半年报 2 个月，
+  年报 4 个月；非标准报告期保守按 4 个月。
+- 新浪 2020-03-13 给全市场做过一次批量入库，之前的各期共用这一个入库时间（茅台利润表
+  76 期）。这一天被 3 期及以上共用的入库时间认定为批量入库：它仍能证明这些期那时已公布，
+  但不当原始入库时间，这些期按截止日判断（否则茅台 2019 年前三季要到 2020-03-14 才看得到）。
+  只认这一天：别的日期多期共用，可能是逾期公司一次补发几期，照旧等入库时间才放行。
+- 公告日不晚于报告期的（上市前的数据有写成报告期当天的）当作没有。
+
+这两个日期都可能被后来的报表改写成更晚的日期（公告日会变成次年同期报表、或下一期报表把它
+当对比数再刊出的日期），但不会早于实际公布，所以只用来放行。逾期披露的公司两个日期都还在
+一年内，不会走截止日这条——例：300630 的 2023 年报和 2024 一季报都在 2024-07-05 才发，
+分析日 2024-05-15 看不到，07-06 起才看得到。两个日期列不放进返回给分析师的表。
+
+另外：
+
+- 三张财报表工具的 `curr_date` 改为必填，传空字符串直接要求重传，基本面分析师的提示词也
+  写明要传——原来可选，模型漏传就整段不筛。
+- 回看越早的日期取的期数越多（接口按最新在前返回，原来固定 20 期只覆盖最近 5 年，分析
+  2016 年会得到空表）；返回前按报告期从新到旧排序，不依赖接口顺序。
+- 「缺数据重试」里升级前记下的财报调用没有 `curr_date`（或是空值），重试时按该任务的分析日
+  补上，不会因为参数变成必填而一直失败，也不会不筛就记成已解决。
+
+已知限制：
+
+- 入库时间也被后来的改数改写过的报告期，会比实际公布晚才放行（例：600519 的 2021 年三季报
+  2021 年 10 月下旬已公布，两个日期都被改写到 2022 年 10 月，要过了截止日 10-31 才放行）。
+- 2020-03-13 批量入库之前的报告期只能按截止日或批量入库时间放行：比截止日早公布的会晚
+  看到（例：平安银行 2019 年报 2020 年 2 月就已公布，要到 2020-03-14 才放行），当年逾期
+  披露的则可能提前看到。之后的逾期披露公司，如果两个日期后来都在一年以后被改写，也只能
+  按截止日放行。这是接口不保留原始公布日的限制。
+- 较早报告期的数值可能是次年报表里重述后的对比数，不一定是当时公布的原值。
+
+### 修复：Web 侧栏选「Custom model ID」时把 `custom` 当模型名发给 API（#120 by @ontheway06）
+
+DeepSeek、通义千问、GLM、MiniMax 的模型下拉里有一条「Custom model ID」，CLI 会追问填写，
+Web 侧栏却把 `custom` 直接发了出去，用户拿到「you passed custom」这种和界面对不上的 400。
+现在选中它会出现输入框，填过的 ID 会被记住；没填就拦在发起分析之前并提示。校验挂在
+`start_analysis` 的唯一消费点，侧栏开始分析、未完成任务续跑、报告页重新分析、错误页继续
+这 4 条入口都覆盖。
+
+### 测试
+
+新增 51 条（`tests/test_sina_financial_report_shape.py` 29 条，`tests/test_lookahead_guard.py`
+4 条，`tests/test_missing_data_tasks.py` 4 条，`tests/test_web_model_selection.py` 14 条）。
+全量 562 passed / 14 skipped / 0 failed（Python 3.12；跳过的都是没装的可选依赖）。
+
+- 公布时间筛选、批量入库识别、科目去重、排序、取数期数、工具必填、重试补日期共做了 28 处
+  变异检查（去掉入库时间放行、公告日当天放行、截止日不看原始日期是否丢失、入库时间不换
+  北京时间、两期共用就算批量、批量不限日期、批量入库时间不再放行、去掉排序、工具收空日期等），
+  全部变红。
+- 补丁做了三次独立只读复核（Opus 5.5）：第一次指出逾期披露会漏、工具日期可选；第二次指出
+  批量入库让 2019 年报表晚放行近一年、升级前的重试任务会一直失败、上市前的公告日不可信；
+  第三次指出批量认定没限定日期（逾期公司一次补发三期会提前露出）、空字符串日期不筛。都已修。
+- 实测 600519：分析日 2026-07-15 最新一期是 2026-03-31，2026-08-20 是 2026-06-30；
+  2025-04-10 能看到 2024 年报（2025-04-02 晚入库）；现金流量表 2026-04-16 看不到、
+  04-17 看得到 2025 年报；2019-05-15 / 09-15 / 11-15 分别看到 2019 年一季报 / 半年报 / 三季报。
+  平安银行 2020-03-14 看得到 2019 年报。300630 的逾期年报如上。分析日 2016-06-01 能取到
+  2016 一季报。
+
 ## [0.5.20] — 2026-09-21
 
 ### 修复：`claude_agent_sdk` 订阅主路径此前完全没有超时（补上 v0.5.19 自己记下的那个缺口）

CLAUDE.md

@@ -6,7 +6,7 @@
 - **仓库**: https://github.com/simonlin1212/TradingAgents-astock
 - **协议**: Apache 2.0
 - **Python**: >=3.10
-- **当前版本**: 0.5.20（2026-09-21）
+- **当前版本**: 0.5.21（2026-10-11）
   ⚠️ 改版本号时**三处要一起改**：`pyproject.toml` / `CHANGELOG.md` / 这一行。漏了这行会让后续 agent 和发版流程读到旧版本（`tests/test_version_consistency.py` 会拦）。
 
 ## 架构
@@ -61,6 +61,15 @@ curr_date 过滤历史行、复盘时整段不取实时分钟数据）；数据
 （腾讯实时估值、同花顺当前一致预期）就在正文顶部**明确告警**并指示模型不得当作当天
 事实。**新增任何收 `curr_date` 的接口，必须处理这两种情况之一，不能收了不用。**
 
+财报三表（v0.5.21）按「已公布」截断，不按报告期，都是严格早于分析日：新浪公告日早于分析日；
+或入库时间 `update_time`（转北京时间）早于分析日当天；或两个日期都晚于报告期一年以上 / 缺失
+（原始日期已丢）时，才按法定披露截止日（`_report_deadline`）判断；同一入库时间被 3 期及以上
+共用、且在 2020-03-13（`_SINA_BATCH_IMPORT_DAY`，新浪全市场批量入库）的只能放行、不算原始日期——
+别的日期多期共用可能是逾期公司补发，**别放宽成不限日期**。⚠️ **别改成只按公告日筛**——
+公告日会被次年同期报表、下一期报表的对比数改写成更晚的日期，回看时会把早已公布的财报整批丢掉。
+⚠️ **也别退回「截止日或公告日」**——逾期披露的公司（300630 的 2023 年报 2024-07-05 才发）截止日
+一过就提前露出来。两个日期列只在内部用，不放进返回表；三张表工具的 `curr_date` 是必填。
+
 ### 非 A 股代码防护（v0.5.3 新增，v0.5.5 补全）
 `_normalize_ticker()` 会拒绝港股（4~5 位数字 / `.HK`）与美股代码。**新增任何 vendor
 方法都必须走它，不要直接调 `safe_ticker_component`**——后者只做路径安全校验，不认市场。
@@ -99,7 +108,7 @@ deepseek-v4-flash 等模型在 tool call 时可能返回中文股票名而非 6
 
 ### 测试
 **干净 clone（`pip install -e .` 不带 `[agentsdk]`）跑 `pytest tests/` 应当是
-512 passed / 13 skipped / **0 failed**（v0.5.20 实测，Python 3.13）。出现 failed 就是真回归。**
+562 passed / 14 skipped / **0 failed**（v0.5.21 实测，Python 3.12；跳过的都是没装的可选依赖 claude-agent-sdk / langchain-google-genai）。出现 failed 就是真回归。**
 需要可选依赖的用例用 `requires_sdk` 标记跳过——⚠️ **占位类型绝不要用 `Exception`
 基类**：`ClaudeSDKError` 曾被占位成 `Exception`，进 `_FALLBACK_ERRORS` 后让"订阅凭据
 失效不得降级到计费 provider"这条护栏彻底失效（v0.5.4 修）。

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tradingagents-astock"
-version = "0.5.20"
+version = "0.5.21"
 description = "A股多Agent投研框架 — 基于 TradingAgents 深度特化"
 readme = "README.md"
 requires-python = ">=3.10"