@v587d/capital-generation 0.0.0-stage → 2.6.0

package/preset/capital-generation/skills/capital-visualization-protocol/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: capital-visualization-protocol
+description: Use immediately after data_junior profile completion to run the mandatory visualization gate, dispatch chart-worthy tasks to visualization_specialist, choose bounded chart views and fields, prepare a chart_source_ref, or document a real skip/block/failure.
+---
+
+# Capital 可视化编排协议
+
+本 skill 同时服务 data_junior 和 visualization_specialist，但两者职责不同：
+
+```text
+data_junior
+  └─ 读取 profile，判断是否值得可视化，签发 chart_source_ref，等待 specialist
+
+visualization_specialist
+  └─ 读取有限 profile 事实，选择视图，调用 render_chart，返回 chart_ref
+```
+
+图表是呈现，不是分析。任何数值结论必须来自 data_junior 的 profile/query 或
+data_collector 的结构化回传，不能通过观察图形推断。
+
+## 1. 可视化决策 gate
+
+profile 完成后只能选择以下四种状态之一：
+
+```text
+not_needed
+recommended
+blocked
+failed
+```
+
+### 1.1 `not_needed`
+
+以下情况通常不需要图表：
+
+- 单个标量或少量 KPI；
+- 只有一两行的简单结果；
+- 没有趋势、比较、分布或集中度关系的数据；
+- 文字表格已经比图表更清楚；
+- 纯文本公告或资料摘要。
+
+必须在回传中给出简短原因，不要为了满足“主动出图”而生成装饰性图表。
+
+### 1.2 `recommended`
+
+以下信号满足一个或多个，并且图表能明显改善理解时，可以可视化：
+
+- 存在有足够点数的时间序列；
+- 存在多期比较；
+- 存在多个可比较的数值序列；
+- 存在 OHLC 与 volume 组合；
+- 存在类别排名、集中度或分布关系；
+- 文字统计难以表达趋势、结构或相对变化。
+
+推荐不是“看到时间字段就必画”。需要同时考虑点数、字段质量、缺失值和用户问题。
+
+### 1.3 `blocked`
+
+以下情况不得强行出图：
+
+- profile 没有足够字段；
+- 数据是文档型 Dataset，没有可呈现的行集合；
+- 没有可用的时间、类别或数值字段；
+- 用户问题要求的视图无法由现有字段表达；
+- chart source token 无法安全签发。
+
+### 1.4 `failed`
+
+只有已经尝试了合法流程但工具或产物失败时使用：
+
+- `prepare_chart_source` 失败；
+- `render_chart` 返回明确错误；
+- workspace 不可写；
+- 图表旁路登记失败且无法提供可用产物。
+
+不能把“懒得判断”或“没有加载 skill”写成 failed。
+
+### 1.5 硬 gate 覆盖规则
+
+以下情况不得选择 `not_needed`：用户明确要求图表，或 profile 已确认存在时间序列、OHLC+volume、多期比较或多个可比数值序列。此时必须选择 `recommended`，完成 `prepare_chart_source → subagent_visualization_specialist → one-shot barrier`；只有字段/数据实际不足才可 `blocked`，只有合法工具已经失败才可 `failed`。不要把“本 Agent 没有 render_chart”当作跳过理由，render_chart 属于 specialist 的受控工具。
+
+`recommended` 回答的是“这份数据该不该被画出来”，不是“这次委派要不要出图”。委派 prompt 显式限定范围（如「只到 profile」「不要图」）时，仍按上面的判据给出 `recommended`，但**停在结论不出图**，并在回传里写明未执行是**委派收窄**——它既不是 `blocked`（字段不足）也不是 `failed`（工具失败），三者混淆会让主 Agent 把范围决定误读成能力结论。范围下一轮放开时无需重新 profile，按同一结论直接走 `prepare_chart_source` 即可。
+
+
+### 2.1 描述后判断
+
+data_junior 必须先完成：
+
+```text
+describe_dataset（默认：一次完成 inspect + profile + 可选 queries）
+必要时用 inspect_dataset / profile_dataset / query_dataset 做单点复核
+```
+
+然后形成最小决策记录：
+
+```text
+decision
+reasons
+candidate_views
+```
+
+candidate views 只记录视图意图，例如：
+
+```text
+trend
+comparison
+volume
+distribution
+ranking
+ohlc
+```
+
+不要在 profile 阶段生成 raw rows 或完整 chart payload。
+
+### 2.2 推荐出图时签发 token
+
+对每个当前 task/dataset：
+
+```text
+prepare_chart_source({ dataset_id, task_id })
+```
+
+只使用工具返回的 `chart_source_ref`。不要自己构造 token、路径或 `raw.json` 地址。
+
+**一张图一个 token，且 token 有 15 分钟 TTL**：先定好要出哪几张图、每张用哪份 Dataset，
+再一次性签发；**不要**因为改了视图方案就为同一个 dataset 重签（实测代价：多花 8.3K 字符思考，
+还把剩下的窗口压得更短）。
+
+传给 visualization_specialist 的内容只能包括：
+
+- `task_id`；
+- `profile_ref`；
+- 有界 profile 事实；
+- `chart_source_ref`；
+- 用户问题和 candidate view；
+- 输出要求。
+
+禁止传递：
+
+- 原始 rows；
+- series 数组；
+- 绝对路径；
+- 任意脚本或 HTML；
+- 未经 profile 允许的其他 Dataset。
+
+**分工硬规则：spec 由 specialist 组装，data_junior 只交"要什么视图"。** `kind` / `x` / `series` /
+`markers` / `title` 的取值由 specialist 读 `capital-chart-protocol` 决定；data_junior 的 prompt 只写
+视图角色（主视图/辅助视图）、目标窗口与关心的字段名。实测偏离这条要付两笔账：一次 8.3K 字符的
+思考（在替 specialist 算 spec 与标记位置），以及为同一个 dataset 重签 token。
+
+**协议排除的视图要记为 limitation，不要改方案重签。** 需要"归一化对比 / 多源叠加"（例如个股与
+指数同图）时：当前能力不支持，按"图表跟着 Dataset 一对一"拆成各自独立的单源图，并在回传的
+`warnings` 里写明「归一化叠加对比不支持，已拆为 N 张单源图」。不要为此重新 `prepare_chart_source`，
+也不要自造归一化序列。
+
+## 3. visualization_specialist 选图规则
+
+### 3.1 视图选择
+
+| 目标 | 首选 kind | 典型字段 |
+|---|---|---|
+| 时间趋势 | `line` / `area` | 时间字段 + 一个或多个数值字段 |
+| 多期逐期比较 | `column` | 期间/类别字段 + 数值字段 |
+| OHLC 行情 | `candlestick` | 真实时间字段 + open/high/low/close |
+| OHLC 柱 | `bar` | 真实时间字段 + open/high/low/close |
+| 成交量辅助 | `volume` | 与 OHLC 同行的成交量字段 |
+| 类别排名 | `column` / `bar` | 类别 + 已受控聚合的数值 |
+| 分布 | `column` | 先由 data_junior 提供区间计数，再绘制 |
+
+`bar` 不是普通单值柱状图；普通单值柱状图使用 `column`。
+
+没有经过受控聚合的原始高基数类别不要直接画成拥挤图表。
+
+### 3.2 字段选择
+
+- 字段名必须来自 profile 或工具错误中的可用字段；
+- 不根据中文语义猜不存在的字段；
+- `candlestick` / `bar` 必须拥有完整 OHLC 和真实时间字段；
+- 同一图最多选择 6 条数值序列；
+- 多序列只有在单位和比较意义相近时才放在一张图；
+- 单位不同或量级差异过大时拆成多个 chart plan；
+- volume 只有在数据语义确实是成交量时才使用，不要把任意数量字段标成 volume。
+
+### 3.3 图表数量
+
+第一版每个 profile 最多生成 4 张图，并优先选择信息增益最高的视图：
+
+1. 用户问题直接要求的主视图；
+2. 能解释主视图的辅助视图；
+3. 风险或异常视图；
+4. 只有确实有必要时才增加第四张。
+
+不要为了达到数量上限而重复绘制同一信息。
+
+## 4. 调用 render_chart
+
+第一次调用前加载：
+
+```text
+skill capital-chart-protocol
+```
+
+使用 `chart_source_ref` 和当前 `task_id`：
+
+```jsonc
+{
+  "chart_source_ref": "cs_01J...",
+  "task_id": "task_01J...",
+  "spec": {
+    "kind": "line",
+    "x": "trade_date",
+    "series": [
+      { "field": "close", "label": "收盘价" }
+    ],
+    "title": "近一年收盘价走势"
+  }
+}
+```
+
+不要把 chart source token 改写成 `dataset_id` 或 workspace path。
+
+成功后只保留：
+
+```text
+chart_ref
+chart_id
+kind / axis
+points / original_points / downsampled
+warnings
+必要的标题和视图角色
+```
+
+不要转发：
+
+```text
+series.json
+raw rows
+chart.html 内容
+绝对路径
+```
+
+如果收到 `chart_source_expired` 或 `chart_source_scope_mismatch`，不要猜 token，
+应把当前 specialist 标为 failed，由 data_junior 如实汇总。
+
+如果收到 `chart_spec_invalid` 或 `chart_field_not_found`，只根据错误中的 allowed/available
+信息修正一次；第二次仍失败则回传 failed，不要循环试错。
+
+## 5. one-shot barrier 与回传
+
+visualization_specialist 是前台 one-shot：
+
+- 不调用 `send_message`；
+- 不创建下游 Agent；
+- 不启动 background Job；
+- 最终结果直接返回给 data_junior。
+
+data_junior 必须等本批次所有 specialist 都有终态：
+
+```text
+rendered
+skipped
+failed
+```
+
+之后才向主 Agent发送一次结构化汇总，至少包括：
+
+```text
+task_id
+dataset_id
+profile_ref
+visualization.decision
+visualization.pending = 0
+charts[].chart_ref
+warnings / failures
+```
+
+图表成功后，data_junior 回传 `chart_ref`；图表失败、blocked 或 not_needed 也必须回传明确的终态、warnings/failures 和 task_id，不能让主 Agent把“无图表”误解为流程未完成。
+
+**呈现由宿主完成，不需要任何 Agent 再做什么**：`render_chart` 成功时宿主会把这张图登记为
+**本轮交付物**（官方 `deliverables/presented`），用户在收尾的「本轮文件改动 / 交付」行点开
+`chart.html`，右侧即渲染可交互图表。因此 data_junior 与 specialist **都不得**在回传里罗列图表文件、
+路径或 HTML，主 Agent 也不在正文里重复这些内容。
+
+**图表跟着 Dataset 一对一，宁多勿叠**：一个 `chart_source_ref` 对应一张图；需要多个视图就出多张
+（各自独立的 `render_chart`）。不要试图把多个来源、多种单位或需要归一化的序列叠进一张图 ——
+当前能力也不支持（无多源合并、无归一化字段），叠出来的图用户只会更晕。
+
+## 6. 安全与来源
+
+- 图表只展示已授权 Dataset；
+- 不使用图表替代 profile/query 数值事实；
+- 不把网页数字伪装成 Dataset 事实；
+- 不在回传或正文里罗列图表文件路径、HTML 或 series；
+- 不索取凭据；
+- 不自动下单；
+- 不输出收益、胜率或准确率承诺。

package/preset/capital-generation/skills/capital-web-protocol/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: capital-web-protocol
+description: Use in Capital mode when retrieving or presenting external material — the anysearch / wind_docs source boundary and the rule to pick a source before searching, the search-convergence heuristic and how to read provider_tally / recent_retrievals, the three mandatory Wind query elements, the wind-to-anysearch fallback, the automatic local-fetch fallback and its via / local-http provenance labeling, the numbered evidence reply format, and the official-domain verification checklist for securities sources. Required reading for the web_retriever child before its first retrieval.
+---
+
+# Capital 检索协议（完整版）
+
+`web_retriever` 子 Agent 的工作细则；主 Agent 呈现检索结论时同样按第 5 节的回传格式保留来源标注。
+persona 只保留硬规则（先定来源再动手、只用这十四个工具、一次一个 URL、无来源不作证据）；
+本文件是其余细节。
+
+## 1. 来源边界（两个 search_engine_provider + 九个具名来源工具 + 文档解析）
+
+**三类工作面，别混**：`search` / `fetch` 是**检索**（先发现候选，再按 URL 取正文）；
+下面九个工具是**来源查询**（具名来源 + 业务参数 → 确定、有序、可翻页、同参可复现的结果集）；
+`ocr` 是**文档解析**（PDF / 图片 → markdown 正文，见第 8 节——它是这批工具里**唯一要 token** 的）。
+
+| 来源 | 工具 | 性格 | 用途 |
+|---|---|---|---|
+| `wind_docs` | `wind_docs_announcements` / `wind_docs_news` | 精准（`public_document`） | 官方正式文件（公告/年报/招股书）与权威新闻的**默认第一选择** |
+| `anysearch` | `anysearch_search` / `web_retriever_fetch` | 广度 | 候选探索与线索、官方页面归属核验、Wind 覆盖之外的内容（监管政策原文、境外或非上市主体、市场传闻） |
+| `cls` | `cls_telegraph` | 来源查询（媒体） | 财联社 7×24 全市场快讯 |
+| `wscn` | `wscn_lives` | 来源查询（媒体） | 华尔街见闻 7×24 快讯，按 `channel` + `cursor` 翻页 |
+| `eastmoney` | `eastmoney_724` / `eastmoney_stock_news` / `eastmoney_reports` | 来源查询（媒体 / 券商研报） | 东财 7×24 快讯、个股新闻、个股研报列表 |
+| `sina` | `sina_reports` | 来源查询（研报第二来源） | 新浪研报列表（**不含评级与目标价**） |
+| `ths` | `ths_eps_forecast` | 来源查询（一致预期） | 同花顺机构一致预期 EPS（逐年：机构数 / 最小 / **均值** / 最大 / 行业平均） |
+| `cninfo_irm` | `cninfo_irm` | 来源查询（巨潮，**深市**） | 互动易投资者问答：公司怎么回应某传闻/关切 |
+| `sseinfo` | `sseinfo_qa` | 来源查询（上交所平台，**沪市**） | 上证e互动问答；不传 `code` 可看全市场 |
+
+**互为备份的成对来源**：三个快讯来源（`cls_telegraph` / `wscn_lives` / `eastmoney_724`）三条不同源、
+不同风控面，一条不可用另一条仍在——但东财会把它聚合到的财联社内容一并返回，**同一事件可能重复，
+按标题去重**，不要当成两条独立证据。两个研报来源（`eastmoney_reports` / `sina_reports`）同理。
+
+**三个来源有硬边界，不要越过**：
+
+- `eastmoney_reports` / `sina_reports` 的列表**不含正文**（只有标题 / 机构 / 研究员 / 日期 / 评级）。
+  东财的每条还直接给出 `pdf_url`（该篇研报 PDF 直链）与 `attach_pages`——**这不是死路：把那条
+  `pdf_url` 原样交 `ocr` 解析**（第 8 节），不要自己去拼或改链接。`ocr` 也拿不到时如实说明这个
+  边界，**不要用标题当结论**。
+- `ths_eps_forecast` 是**一致预期**（观点聚合），不是官方事实、也不是已实现业绩。
+  `institutions`（预测机构数）< 3 时参考价值有限，回传时必须把机构数一并向用户披露。
+- `sina_reports` **不含评级与目标价**；需要这些改用 `eastmoney_reports`。
+
+- **先定来源再动手**：不要等 anysearch 空转后才想起 wind_docs；拿不准时先试 `wind_docs`，
+  失败再降级 `anysearch`，不要反过来。
+- `verified_official` 只能来自 `web_retriever_fetch` 的官方域名核验路径。九个具名来源都是
+  **媒体或互动平台**，其内容只能作旁证（媒体转述 / 投资者问答），**不得标 `verified_official`**。
+- 不调用官方名称为 `web_search` 或 `web_fetch` 的其他工具。
+
+### 1.1 来源查询的纪律（与检索不同）
+
+- **结果集是确定的**：`该翻页就翻到没有`。回执带 `count`；`wscn_lives` 翻页把 `next_cursor`
+  原样传回 `cursor`。不要因为一次返回条数少就换来源重搜。
+- **空结果是真事实**：`cninfo_irm` 返回 0 条说明该公司近一个月确实没有问答；平台只开放近期
+  问答（公司维度约近 1 个月）。**不要把"没有问答"写成"无法确认"**。
+- **深沪不可互换**：互动易只覆盖深市（沪市实测返回 0 条），沪市问答必须用 `sseinfo_qa`；
+  **北交所两个平台都没有**。传错市场会拿到空表，那不是数据缺口。
+- **`status` 字段是事实不是缺口**：`answered` = 公司已回复（`answer` 有正文）；
+  `unanswered` = 尚未回复（`answer` 为空）。未回复本身就是要回传的信息。
+- **回执 `note` 必须读**：它写明上游口径、覆盖范围与被丢弃的条目（如上游把别的公司数据混进来
+  时按条过滤的条数），据此判断结果可信度。
+- **单条正文有长度上限**（约 1200 字符，超出以 `…` 结尾）：需要完整原文时用回执里的 `url`
+  走 `web_retriever_fetch`，不要凭截断片段下结论。少数条目的 `url` 会被**整段丢掉**（链接不成话：
+  非 http(s) 协议、含控制符、`https://真域名@假域名/` 这类凭据伪装、超长）——条目本身仍是证据，
+  照常回传来源与媒体名，不要因为缺链接就丢弃这条。
+- **一次调用有总输出预算**（约 6 千字符）：`count` 等于**真放进回执的条数**，被省略的条数写在
+  `note`（"省略其后 N 条"）。要更多就调小 `limit` 或按 `next_cursor` / `page` 翻页继续取——
+  **不要把"这次只回了 17 条"读成"上游一共只有 17 条"**。
+- **代码写法随意**：`600519` / `SH600519` / `600519.SH` 归一化成同一个查询（上游只认纯 6 位），
+  格式写错不会静默变成空结果。
+- **`sseinfo_qa` 的 `code=TIMEOUT` 是上游慢**（按公司定位要串行翻 10+ 页），不是这一轮被取消：
+  稍后重试，或先用不带 `code` 的调用取全市场问答再按代码筛。
+- 这九个工具的失败是**工具错误**（`isError`），不是"正常返回的失败信封"；`code` 取值见回执
+  （`UPSTREAM` 上游报错 / `INVALID_RESPONSE` 上游结构变了 / `NOT_FOUND` 标的不存在 /
+  `NETWORK` 网络失败 / `TIMEOUT` 上游慢到超过总时限）。**结构变更类错误不要重试**，如实回传。
+
+### 1.2 遇到结构化数值诉求就停手
+
+网页这一侧只能给出"某篇文章里的数字"：单位、缺失值含义、时间口径都没人承诺，上游改版就是静默变样。
+委派消息要的是**可比对的数值序列或表格**（行情、财务、宏观指标、持股与榜单）时，立即回告主 Agent
+"这份该走 `data_collector`"，不要用网页数字凑一张表，也不要抓取后自行解析、补齐成结构化数据冒充取数结果。
+叙事材料（公告、研报、新闻正文）留在本角色，那正是内容本身；已经取到的行里带一个标题字段，不算叙事。
+
+Wind 结构化查询同样是**花积分的**：先看 `data_collector` 的免费能力能不能覆盖"看趋势"这一步，
+只有需要 Wind 口径或研报级准确度时才用积分。
+
+## 2. 搜索收敛（经验法则，不是硬性配额）
+
+- 一次任务对同一个 `search_engine_provider` 的全部检索调用——anysearch 的
+  `anysearch_search`、wind_docs 的 `wind_docs_announcements` / `wind_docs_news` 都算——
+  **一般 5 次以内就该收敛**。
+- 动手前先想清楚要回答什么，规划少数几个高质量查询；每次变换查询条件前先自问"这次变化
+  是否真的可能带来新来源"。
+- 当新一轮检索的候选与已收集材料高度重叠，或已足以挑出完成任务所需的页面时，停止检索，
+  转入逐个 fetch 与整理回传。
+- 多标的、多主题的任务可以适度多搜，但每换一次条件前先盘点 `recent_retrievals`（已检索记录）
+  与 `provider_tally`（各来源累计次数）：接近 5 次就该收敛收手。
+- **偶尔超过 5 次不是错误**，要避免的是无收益的重复搜索。
+
+## 3. Wind 查询要素
+
+`wind_docs` 的 `query` 必须一次带齐三要素：
+
+1. 公司实体（股票代码或公司全称，以主 Agent 委派消息为准）；
+2. **文件类型或主题**；
+3. **时间范围**。
+
+禁止"公告 2026年9月"这类**无主体泛查询**。委派消息缺标的或代码时先回告主 Agent 补充，
+不得自行猜测或省略实体。Wind 检索消耗积分：按需少量调用，不做批量撒网；`top_k` 按需给值，
+不确定时保持默认。
+
+## 4. 双来源纪律与降级
+
+- `wind_docs` 返回内容视为"来源：万得 Wind 金融数据服务"的官方文档库检索结果，标注来源与
+  时间口径后即可作为证据使用，不必再走官网核验。
+- 同一份文件不得两边都取原文；两边都取必须是明说的交叉核验，且一份对一份。
+- **Wind 失败降级**：`wind_docs` 返回 AUTH / RATE_LIMIT 等错误信封时**不得重试 wind**，
+  直接转 `anysearch_search` 发现公告线索并逐个 `web_retriever_fetch` 官方披露页，
+  回传注明"Wind 不可用/未覆盖，来源为官网抓取"。
+- 反向 fallback：anysearch 多轮探索仍找不到权威原文而 Wind 可用时，转 `wind_docs` 少走弯路。
+- 换 provider 前先看 `recent_retrievals` / `provider_tally`：该诉求是否已被回答、已有材料是否
+  覆盖、目标来源还剩多少余量；切换原因写进回传。检索收敛法则按 provider 各自计。
+
+## 5. 回传格式（每条证据都要有来源）
+
+- 回传的证据/情报逐条编号（情报1、情报2……），编号后紧跟来源标注。
+- 有网页链接的用 markdown 链接：方括号里列出**全部来源**（检索 provider 与具体媒体/机构名
+  都写上），**链接只放一条最权威的**即可，不必逐个贴链接。示例：
+  `情报1：公司今日召开临时股东会审议借款议案。[AnySearch, 新浪财经, 证券之星](https://…)`
+- 没有具体网页链接的证据（如 `wind_docs` 返回的公告/新闻正文），只标注来源与时间口径。示例：
+  `情报2：公司2024年年报披露净利润同比下降。（来源：万得 Wind 金融数据服务，2026-09-11）`
+  `wind_docs` 返回体内自带链接字段时可用那个链接；**不得编造链接**。
+- 来源标注要区分：候选来源（搜索摘要，未点开）、已获取正文（fetch 过）、wind_docs 官方文档
+  （来源：Wind）。**无来源的信息不得作为证据回传**；不编造来源。
+- 失败项与未核验项同样编号列出并注明原因，不与已证实证据混排；同一来源服务多条情报时逐条
+  重复标注，不要用"同上"。
+- 主 Agent 向用户呈现时保留这些来源标注；网页数字只能标"媒体转述旁证"。
+- `via: 'local-http'`（本机直连抓取）取得的正文，来源标注用「官网直抓」措辞
+  （例如「AnySearch 受限，来源为本机直抓官网页面」），链接仍只放一条最权威的。
+
+## 6. 官方证券来源域名核验
+
+当任务涉及股票、证券、基金、监管机构、交易所、清算机构、上市公司或发行人的可信来源时，
+只核验官方网址和域名。
+
+- 仅使用 `web_retriever_fetch` 访问官方监管机构、交易所、清算机构、发行人、基金管理人、
+  官方披露系统或官方数据接口页面。
+- 不得使用搜索摘要、财经媒体、聚合网站、百科、论坛、社交媒体、域名评级网站或模型记忆作为
+  证据；不得调用 `anysearch_search` 替代 `web_retriever_fetch`。
+- 不得仅凭机构名称、域名后缀、网页外观或搜索结果判断官方归属。必须通过 fetch 页面确认机构
+  名称、域名归属和具体业务用途。
+- 主域名、子域名、API 域名、披露系统域名和下载域名必须**分别核验**；官方页面跳转或链接到
+  第三方域名，不代表该域名自动属于官方。
+- 只有官方页面能够直接证明归属和用途时，才能标记为 `verified_official`；否则标记为
+  `unverified` 或 `not_verified`，不得猜测或列入白名单。
+- 每个已核验域名输出：机构、司法辖区、机构类型、规范化域名、官方网址、核验用途、可信原因、
+  核验状态、证据网址、抓取时间和使用限制。
+- 将"已核验官方白名单"和"候选/未核验域名"分开；没有充分证据时明确写"未核验"，不得为了
+  完整性补全域名。
+- 域名属于官方机构，不等于该域名下所有数据都适合作为最终证券研究证据；实际使用不得超出已
+  核验的业务范围。
+- 本机直抓**不改变** `verified_official` 的授予条件（仍只属于官方域名核验路径）；但核验记录里
+  要写明该页面是经 AnySearch 清洗还是本机直抓取得的（看回执 `via` 字段）。
+
+## 7. 抓取与失败处置
+
+- 网页抓取成功后回传 URL、标题、正文和抓取结果；正文过长时按工具返回内容为准，不自行补全。
+- **自动本机回退（不是你的第二次调用）**：`web_retriever_fetch` 在 AnySearch 明确失败且"值得换路"、
+  **且本机直连回退已启用**（设置卡片开关「允许启动本地提取网页内容」，默认开启）时，会**自动**改由
+  本机直连抓取该页面；你不需要、也不应该为此再调用一次工具。未启用时 AnySearch 失败即回传失败，
+  照常按失败处置，不要为此改用其他抓取途径。回执里的 `via` 标明正文来源：
+  `via: 'anysearch'` = AnySearch 清洗正文；`via: 'local-http'` = 本机直连抓取。
+- **来源标注义务**：`local-http` ⇒ 来源标注用「官网直抓」措辞（必须写明
+  「AnySearch 受限，来源为本机直抓官网页面」），并保留 `fallback.code` 作为 AnySearch 失败原因；
+  `via: 'anysearch'` 时按第 5 节现状标注。
+- **本机直抓的能力边界**（不要以为它万能）：只处理公开可访问的文本页面（HTML / 文本 / JSON / XML）；
+  PDF 与二进制、需登录页面、内网地址仍会失败。正文超长时是**截断**（回执 `truncated: true`），不是失败。
+- **失败是工具错误，不是"正常返回"**：抓取失败时 `web_retriever_fetch` 以**工具错误**（`isError`）返回，
+  错误正文就是一份 JSON 回执（`ok: false` + `error` + `code` + `local_error` + `fallback` + 检索回声）。
+  **不要把它当成抓取成功**——先读 `local_error.code` / `code` 判明原因，再如实回传；不得编造标题或正文。
+- **与"最多重试一次"的关系**：自动回退**不算**你的第二次重试。模型层面的"重试一次"只适用于两条路
+  都失败之后的显式重试；网络或服务错误**最多重试一次**，仍失败则如实回传，并与其他已证实证据分开编号。
+- 搜索摘要只能用于发现候选来源，不能作为证券事实证据；报告中区分候选来源、已获取正文、
+  未核验内容和失败原因，不编造缺失信息。
+
+### 7.1 WAF 挑战型站点：如实报错，改走 Wind
+
+有些站点（政府网站尤其多）挂在 **WAF 的 JavaScript 挑战**后面。识别特征：
+
+- 回执 `local_error.code = 'HTTP'` 且消息是 **HTTP 521**（也可能是 403 / 503）；
+- 响应头带 `X-Via-Jsl`（加速乐 / Jiasule）、`Set-Cookie: __jsluid_h=...`；
+- 正文不是文章，而是一段**裸 `<script>`**（内容是 `document.cookie=...__jsl_clearance...`）。
+
+**原理**：服务器要求客户端**执行 JavaScript** 算出通行证 cookie 再重新请求。浏览器会自动完成这一步，
+而本机直抓是纯 HTTP 客户端，**不执行脚本**，所以永远拿不到正文。它**不是**超时、不是缺响应头、
+也不是重定向问题——**重试无用**（第二次只会拿到 20KB 以上的混淆脚本，需要 `window` / `document` 才能跑）。
+
+**处置（硬规则）**：
+
+1. **不重试、不尝试绕过**：不分析混淆脚本、不猜 cookie、不靠换 UA 碰运气。
+2. 如实回传：该 URL **未取得正文**，与其他已证实证据分开编号，域名核验状态写「未核验」。
+3. **改走 Wind**：同一份官方文件或权威新闻优先用 `wind_docs_announcements` / `wind_docs_news` 取
+   （`public_document`），标注「来源：万得 Wind 金融数据服务」与时间口径后即可作为证据。
+   Wind 也查不到时，再试同一内容的**其他官方入口**（中国政府网、部委主站镜像等），
+   并在回传里注明替代来源与原 URL 的关系。
+4. 不要因为一条被墙就放弃整个任务：把这一条标为「来源不可达」，其余结论照常给出。
+
+## 8. 文档解析（`ocr`：PDF / 图片 → 正文）
+
+第 1 节那三个"硬边界"里唯一被拆掉的就是**研报 / 公告正文拿不到**：现在有一条明确的通路，
+但它**要 token、按整篇计费**，所以用法比别的工具讲究。
+
+- **什么时候动它**：你手上有一条 `.pdf` 直链（`eastmoney_reports` 条目里的 `pdf_url`，或公告 /
+  招股书原文的直链），或委派消息给了一个工作目录内的本地文档路径（用户以 `@xxx.pdf` 推给
+  主 Agent 的那种）。`web_retriever_fetch` 拿到 PDF 是**能力边界**不是故障——不要重试 fetch，
+  改调 `ocr`。
+- **四种调用形态，一次只走一种**：`url`（外部 PDF 直链）/ `file`（工作目录相对路径的本地
+  pdf 或图片）/ `job_id` + `doc_id`（**续查**上一次没跑完的作业）/ `doc_id` + `pages` \| `query`
+  （**纯本地读已落盘正文**，不出网、不花钱）。同时给两种输入会被直接拒绝，不会替你选边。
+- **`pages` 不省钱**：一次作业总是解析**整篇**（上游口径最多 100 页），`pages` 只决定这次
+  给你读哪几页。想省钱靠**第二次起用 `doc_id`**，而不是靠少写几页。
+- **`status: 'pending'` 不是失败**：作业还在跑。回执带 `job_id` 与 `doc_id`，**再调一次只传
+  这两个**继续等；⛔ 不要重传 `url`——那是提交第二个作业、再花一次钱。
+- **`doc_id` 是 opaque 引用**：形如 `ocr_1a2b3c4d5e6f`，从回执里原样取用，不要猜、不要拼路径、
+  不要试图从它读出文档内容。同一份文档再次请求会**直接回读缓存**（不再出网），只有
+  `refresh: true` 才重跑；重跑**不是独立验证**（上游对同一份 PDF 给过 18% 与 19% 两种数字）。
+- **回执装不下整篇**：超出输出预算时只给**页索引**（每页 `chars` 与首个标题）+ 首页。
+  先按索引判断需要哪几页，再用 `pages`（`"1-3"` / `"2-4,9"`，一次最多 8 页）或 `query`
+  （关键词定位，回命中片段与页号）取回。**一律整页进整页出**——没有"半页正文"这种东西。
+- **表格与图片**：上游的表格已归一化成 markdown 管道表（回执里的 `style_chars_removed`
+  说明剥掉的是排版噪音，不是内容）；`images` 只给**数量**，图链是上游的临时地址，本工具
+  **不下载、不内联**——不得声称"看到了图里的内容"，图表数字只认 markdown 里的那份。
+- **来源标注**：正文来自 OCR，标注写「（来源：〈机构/媒体〉研报 PDF 正文，OCR 解析
+  `doc_id=…`，第 N 页）」并**标页号**；⛔ **不得把那条 PDF 链接本身当成"已读到正文"的证据**，
+  链接只是文件所在。`verified_official` 的授予条件不变（第 6 节）：OCR 解析不改变域名核验结论，
+  但官方域名下的 PDF（如巨潮、交易所披露页给出的直链）其正文可按官方文档对待。
+- **失败处置**：`NO_CREDENTIAL` ⇒ token 未配置，如实回传"需要用户在 设置 → 插件 → 插件配置 →
+  Capital 模式 填写 PaddleOCR Token"，**绝不**用标题或摘要补一篇正文出来；`UPSTREAM` /
+  `JOB_FAILED` / `TOO_MANY_PAGES` ⇒ 最多重试一次，仍失败就按边界如实回传。
+  `ocr` 在检索回声（`recent_retrievals` / `provider_tally`）里**记一次**，与 fetch 同口径。