stock-analysis-plugin 0.2.6__tar.gz → 0.2.7__tar.gz

{stock_analysis_plugin-0.2.6 → stock_analysis_plugin-0.2.7}/.github/workflows/ci.yml

@@ -147,6 +147,12 @@ jobs:
       - name: dsh current SDK compatibility
         run: npx tsx tests/test_dsh_sdk_compat.ts
 
+      - name: LLM host adapters (offline)
+        run: npx tsx tests/test_llm_hosts.ts
+
+      - name: Large JSON input transport and cleanup
+        run: npx tsx tests/test_json_input.ts
+
       - name: Hermes plugin registration
         run: pytest tests/test_hermes_integration.py -v
 
@@ -154,7 +160,7 @@ jobs:
         run: pytest tests/e2e/test_host_to_python.py -v
 
       - name: Signal store and analysis regressions
-        run: pytest tests/test_signal_tracker.py tests/test_gather.py tests/test_watchlist.py tests/test_watchlist_context.py -q
+        run: pytest tests/test_signal_tracker.py tests/test_gather.py tests/test_watchlist.py tests/test_watchlist_context.py tests/test_stateless_analysis.py -q
 
       - name: Pi host real subprocess round-trip
         run: npx tsx tests/e2e/test_pi_e2e.ts
@@ -172,6 +178,10 @@ jobs:
     # block the release path (see publish.yml).
     continue-on-error: true
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        host: [hermes, pi, openclaw, dsh]
     timeout-minutes: 20
     if: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }}
     steps:
@@ -193,16 +203,18 @@ jobs:
         run: node scripts/ci-resolve-llm-host.mjs
 
       - name: Install Python dependencies
+        if: matrix.host == 'hermes'
         run: |
           pip install -r tools/requirements.txt
           pip install -r requirements-dev.txt
 
-      # Full npm ci (postinstall builds .venv) — the Pi LLM flow spawns tools
-      # through it.
+      # Full npm ci builds .venv for the TypeScript host adapters.
       - name: Install Node dependencies
+        if: matrix.host != 'hermes'
         run: npm ci
 
       - name: E2E — Hermes LLM flow
+        if: matrix.host == 'hermes'
         env:
           OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL || vars.OPENAI_BASE_URL }}
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
@@ -212,9 +224,10 @@ jobs:
             echo "OPENAI_BASE_URL, OPENAI_API_KEY, and OPENAI_MODEL are required — skipping LLM e2e"
             exit 0
           fi
-          pytest tests/e2e/test_hermes_llm.py -m integration_llm -v
+          pytest tests/e2e/test_hermes_llm.py tests/e2e/test_analysis_quality.py -m integration_llm -v
 
-      - name: E2E — Pi LLM flow
+      - name: E2E — ${{ matrix.host }} LLM flow
+        if: matrix.host != 'hermes'
         env:
           OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL || vars.OPENAI_BASE_URL }}
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
@@ -224,7 +237,7 @@ jobs:
             echo "OPENAI_BASE_URL, OPENAI_API_KEY, and OPENAI_MODEL are required — skipping LLM e2e"
             exit 0
           fi
-          npx tsx tests/e2e/test_pi_llm.ts
+          npx tsx tests/e2e/test_host_llm.ts ${{ matrix.host }}
 
   e2e-host:
     # Real-host smoke: install the plugin into the actual pi / openclaw /

{stock_analysis_plugin-0.2.6 → stock_analysis_plugin-0.2.7}/.gitignore

@@ -26,6 +26,9 @@ node_modules/
 !package-lock.json
 !tsconfig.json
 !schemas/**/*.json
+!tools/cli_budgets.json
+!tests/fixtures/analysis_quality.json
+!tests/fixtures/stateless_analysis.json
 !openclaw/openclaw.plugin.json
 !strategies/**/*.yaml
 

{stock_analysis_plugin-0.2.6 → stock_analysis_plugin-0.2.7}/AGENTS.md

@@ -7,13 +7,13 @@ A multi-host agent plugin for stock analysis, screening, and strategy backtestin
 The architecture is **one Python core, four thin host adapters**:
 
 - `tools/*.py` — the shared CLI tools. **This is the single source of truth** for all behavior. Every tool prints JSON to stdout.
-- `pi/index.ts` — Pi extension. `pi.registerTool` ×60, each spawns a `tools/*.py` CLI.
+- `pi/index.ts` — Pi extension. `pi.registerTool` ×67, each spawns a `tools/*.py` CLI.
 - `hermes/` — Hermes plugin (`plugin.yaml` + `register(ctx)` in `__init__.py`; `tools.py` handlers → subprocess to the same CLIs). Discovered via the `hermes_agent.plugins` entry point.
-- `openclaw/` — OpenClaw plugin (`openclaw.plugin.json` manifest + `index.ts` `definePluginEntry` + `registerTool` ×60). Bundled with esbuild.
-- `dsh/` — dsh bundle (`package.json` `dsh.bundle` + `cordis.patch.yml` + `index.ts` cordis `apply(ctx)` with `defineTool` ×60 via `@deepseek-ai/dsh-tools`; skills via `ctx.skills.register`). Bundled with esbuild, `@deepseek-ai/*` external (peer deps).
+- `openclaw/` — OpenClaw plugin (`openclaw.plugin.json` manifest + `index.ts` `definePluginEntry` + `registerTool` ×67). Bundled with esbuild.
+- `dsh/` — dsh bundle (`package.json` `dsh.bundle` + `cordis.patch.yml` + `index.ts` cordis `apply(ctx)` with `defineTool` ×67 via `@deepseek-ai/dsh-tools`; skills via `ctx.skills.register`). Bundled with esbuild, `@deepseek-ai/*` external (peer deps).
 - `skills/*/SKILL.md` — 20 workflow / strategy-methodology skills shared by all four hosts.
 
-> **The invariant that matters most:** the four adapters expose the *same* 60 tools over the *same* Python CLIs. A change to a tool's name, parameters, or JSON output shape must be applied to **all four adapters and the relevant SKILL.md together** — never just one.
+> **The invariant that matters most:** the four adapters expose the *same* 67 tools over the *same* Python CLIs. A change to a tool's name, parameters, or JSON output shape must be applied to **all four adapters and the relevant SKILL.md together** — never just one.
 
 ---
 

{stock_analysis_plugin-0.2.6 → stock_analysis_plugin-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stock-analysis-plugin
-Version: 0.2.6
+Version: 0.2.7
 Summary: Hermes plugin for stock analysis, screening, and strategy backtesting across A/HK/US/JP/KR/TW markets
 Project-URL: Homepage, https://github.com/Weaxs/stock-analysis-plugin
 Project-URL: Repository, https://github.com/Weaxs/stock-analysis-plugin
@@ -73,7 +73,7 @@ A 股 / 港股 / 美股 / 日股 / 韩股 / 台股综合分析、多因子选股
 
 ## 功能概览
 
-- **60 个工具** — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
+- **67 个工具** — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
 - **20 个 Skills** — 综合分析、全市场选股、策略回测 + 17 个策略方法论（缠论、波浪、龙头、情绪周期等）
 - **策略回测引擎** — YAML DSL 定义策略，参数化条件组合，自动诊断，按需进行有限轮参数优化
 - **多数据源 Failover** — 11 个数据源自动容灾切换（akshare / tushare / efinance / 腾讯行情 / 新浪行情 / pytdx / baostock / yfinance / finnhub / longbridge / alphavantage），A 股链路带粘性优选（最近成功的数据源下次优先尝试）
@@ -111,6 +111,8 @@ npm install @weaxs/stock-analysis-plugin
 
 Pi 启动后自动加载，输入 `/skills` 确认。详见 [Pi Agent 接入指南](docs/pi-integration.md)（[English](docs/pi-integration.en.md)）。
 
+新版 Pi（已核验 1.2.0）提供原生 `tool_search` 时，插件自动启用按需工具发现，67 项能力保留注册，仅命中工具加载完整定义。缺少原生发现接口的旧版 Pi 或 SDK 宿主保持全量暴露。检索使用英文关键词或工具名，例如 `get_quote`、`get_financials`。
+
 ### Hermes Agent Plugin
 
 ```bash
@@ -134,7 +136,7 @@ register(ctx)
 openclaw plugins install clawhub:@weaxs/openclaw-stock-analysis
 ```
 
-OpenClaw Gateway 启动后自动加载并注册 60 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖（前提：本机有 `python3 >= 3.10`）。
+OpenClaw Gateway 启动后自动加载并注册 67 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖（前提：本机有 `python3 >= 3.10`）。
 
 详见 [OpenClaw 接入指南](docs/openclaw-integration.md)，或 plugin 自身说明 [`openclaw/README.md`](openclaw/README.md)。
 
@@ -145,7 +147,9 @@ dsh plugin --profile <你的profile> add @weaxs/dsh-stock-analysis
 dsh --profile <你的profile>
 ```
 
-作为 dsh bundle 安装：`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合，注册 60 个 tool + 20 个 skill。postinstall 自动建 `.venv`（pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`，否则回退系统 `python3`）。
+作为 dsh bundle 安装：`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合，注册 67 个 tool + 20 个 skill。postinstall 自动建 `.venv`（pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`，否则回退系统 `python3`）。
+
+新版 dsh 的原生函数调用模式默认通过 `stock_tool_search` 按 Agent 搜索、加载所需工具，支持中文关键词或工具名；旧接口、搜索入口不可用时保留全量暴露。可设置 `toolDiscovery: false` 关闭，配置与 PTC 模式边界见下方接入文档。
 
 详见 [`dsh/README.md`](dsh/README.md)。
 
@@ -322,9 +326,9 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
 
 | 工具 | 说明 |
 |------|------|
-| `screen_stocks` | 全市场多因子筛选（市场情绪调节，可选 L2 量化增强） |
+| `screen_stocks` | 全市场多因子筛选（可选 L2；factor_coverage 展示缺失因子、覆盖度、实际权重及 L2 effective_scores） |
 | `screen_risk` | 风险因子筛查 |
-| `run_backtest` | YAML 策略回测 |
+| `run_backtest` | YAML 策略回测，默认收盘信号于次日开盘成交，execution 返回模型与限制 |
 | `detect_market_regime` | 市场状态检测（牛/熊/震荡） |
 | `get_market_review` | 市场日度复盘数据 |
 | `get_review_history` | 复盘归档历史（最近 N 条，最新在前，用于纵向对比） |
@@ -361,8 +365,8 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
 | `check_alert_rules` | 无状态检查价格、涨跌幅、异动和风险规则 |
 | `record_signal` | 记录 AI 分析建议信号（本地 JSONL 持久化） |
 | `evaluate_signals` | 评估到期信号（target_hit/stop_hit/timeout 结算） |
-| `get_signal_summary` | 信号胜率汇总（按 source/symbol/status 过滤） |
-| `render_stock_report` | 将结构化个股报告渲染为 Markdown |
+| `get_signal_summary` | 信号胜率及分来源平均收益、有效收益样本数与小样本提示（按 source/symbol/status 过滤） |
+| `render_stock_report` | 将结构化个股报告渲染为 Markdown，展示 evidence 与 data_quality 限制 |
 | `render_market_report` | 将结构化市场复盘渲染为 Markdown（save=true 时归档到本地 JSONL） |
 
 批量自选股分析和摘要的 `success` 表示至少获取了有效行情价格、K 线收盘价或技术评分；全部关键数据失败时计入 `failed`，部分结果仍保留。采集脚本复用返回的 K 线计算技术指标，并按股票所属市场查询大盘状态；日/韩/台市场状态暂不可用，非 A 股板块榜单也暂不可用，均会明确返回错误。
@@ -373,6 +377,43 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
 
 选股的 `filters_applied` 只列实际执行的条件，显式条件缺少数据时报错。回测的 `period` 是实际数据期间，`requested_period` 保留请求期间，`warnings` 提示覆盖差异；买入预算包含佣金，年化收益和回撤按实际数据及初始资金计算。
 
+### 无状态研究与风险计算
+
+| 工具 | 说明 |
+|------|------|
+| `compare_stocks` | 比较显式输入的同行指标；检查单位、期间和口径，仅对可比数值排序 |
+| `analyze_disclosure_changes` | 比较新旧公告正文与财务指标，返回来源、变更行号和增长率限制 |
+| `analyze_portfolio_risk` | 一次性持仓的集中度、行业/币种敞口、价格盈亏、止损情景与可选相关性 |
+| `calculate_position_size` | 按现金、风险预算、费用、滑点和交易单位计算本次可买数量 |
+| `analyze_event_study` | 事件前一交易日收盘至各窗口的股票/基准收益差，标明缺失和重叠样本 |
+| `validate_backtest` | 复用现有引擎，滚动训练选候选、样本外验证，比较参数及多个标的 |
+| `compare_analysis_snapshots` | 比较调用方传入的快照，区分新增、删除、变化、数据失效和恢复 |
+
+这些工具不保存自选股、账户或分析历史，也不提供调度/通知。现有数据工具采集行情和财务，宿主传入本次持仓、正文或快照；[完整输入约定与解读工作流](skills/stock-analysis/references/stateless-analysis.md)供四个宿主共用。
+
+大输入经权限受限的临时 JSON 文件传给 Python，调用结束后清理，避免 Windows 命令行长度限制；CLI 也支持 stdin 和 `--input` 文件。公告正文由宿主读取：PDF/OCR 不包含在本次扩展中，只有标题或链接不能声称已读全文。
+
+例如仓位预算（所有金额同币种，lot_size 由用户或交易规则确认）：
+
+```json
+{
+  "equity": 100000, "cash": 20000,
+  "entry_price": 100, "stop_price": 95,
+  "risk_fraction": 0.01, "lot_size": 100,
+  "fee_rate": 0.001, "slippage_rate": 0.001
+}
+```
+
+将上述 JSON 保存为 `input.json` 后运行：
+
+```bash
+python tools/stateless_analysis.py position_size --input input.json
+```
+
+对应宿主工具是 `calculate_position_size`。其余 CLI 子命令依次为 `peers/disclosure/portfolio/event_study/robustness/snapshot`。事件研究可直接传 `symbol/benchmark/start_date/end_date/event_dates`；回测验证可传 `symbols/start_date/end_date/strategies`，由 Python 复用行情接口，避免模型重新抄写历史 K 线。显式价格/datasets 模式仍支持离线计算，两种模式互斥。
+
+跨币种组合必须提供显式汇率；价格盈亏不含历史汇兑损益。稳健性工具仅支持 next_open、每窗口重新从现金开始，样本内敏感性不等于样本外表现。
+
 ## 策略回测 DSL
 
 策略以 YAML 格式定义，支持参数化和条件组合：
@@ -415,10 +456,13 @@ position:
   max_positions: 1
 ```
 
+行情 JSON 保留原有数组/字典形状，添加 `source`、UTC `fetched_at` 和 `data_as_of`。采集时间不是报价时间，提供方未给时间时为 null；仅提供交易日时保留 YYYY-MM-DD，不补造具体时刻；K 线 data_as_of 是该条的日期标签，周/月线标签不是实际末次成交时间；`as_of_basis=trading_calendar` 表示交易日历推断。A 股复权口径延续 qfq/none；其他市场按来源标为 total_return/qfq/unknown，不把 unknown 当已验证复权。
+
 其他可用键：
 
 - `exit.trailing_stop`：移动止损，价格自持仓期间最高收盘价回撤达到该比例即卖出（如 `0.08` = 峰值回撤 8% 触发）；与 `stop_loss` 同时设置时先判固定止损。
 - `benchmark`（顶层）：基准对比标的代码（如 `"sh000300"` 沪深300；指数代码必须带 sh/sz 交易所前缀，裸 6 位数字会被当作个股），设置后回测结果附带 `benchmark` 块（基准买入持有收益与 `excess_return` 超额收益）。
+- `simulation.execution`：默认 `next_open`，前日收盘信号、次日开盘加滑点成交；显式 `same_close` 复现旧收盘成交假设。交易同时返回 signal_date/date。零成交量阻止成交；一字板限制只在输入提供同口径历史 limit_up/limit_down 时执行。`execution` 列出阻止成交次数、未成交订单及限制；止损是收盘信号，未模拟盘口排队、部分成交、结算和市场冲击。
 - `simulation`（顶层）：交易成本。`slippage`（滑点，买卖双边，默认 0.001）、`commission`（佣金，买卖双边，默认 0.0015）、`stamp_tax`（印花税，仅卖出收取，默认 0；A股为 0.0005，各市场税率不同且会调整，按当下实际费率填写）。费率均须在 [0, 1) 区间，越界报错。回测结果附带 `costs` 块（实际生效费率与实付费用合计 `commission_paid`/`stamp_tax_paid`）。
 
 ### 可用指标
@@ -542,27 +586,27 @@ GitHub Actions 的 `e2e-host` 使用 Pi、Hermes、OpenClaw、dsh 的真实运
 | `OPENAI_API_KEY` | Secret | 对应的 API key |
 | `OPENAI_MODEL` | Variable 或 Secret | 支持 tool calling 的模型 ID |
 
-`e2e-llm` 也使用这三项配置；同仓库 PR 和主分支推送会运行，fork PR 不读取 API key。`e2e-host` 缺少任一项时会失败。URL 和 model 同时存在于 Variable 与 Secret 时，优先使用 Secret。
+`e2e-llm` 也使用这三项配置，Hermes（含报告质量评测）、Pi、OpenClaw 和 dsh 通过四个 matrix 作业并行运行，互不因失败而取消；同仓库 PR 和主分支推送会运行，fork PR 不读取 API key。`e2e-host` 缺少任一项时会失败。URL 和 model 同时存在于 Variable 与 Secret 时，优先使用 Secret。
 
 ## 项目结构
 
 ```
 stock-analysis/
 ├── pi/                              # Pi Agent Extension
-│   └── index.ts                     #   注册 60 个工具 + 20 个 skill
+│   └── index.ts                     #   注册 67 个工具 + 20 个 skill
 ├── hermes/                          # Hermes Agent Plugin
 │   ├── plugin.yaml                  #   插件清单
 │   ├── __init__.py                  #   register(ctx) 入口
 │   ├── schemas.py                   #   工具 JSON Schema 定义
-│   └── tools.py                     #   60 个 handler → subprocess 调 CLI
+│   └── tools.py                     #   67 个 handler → subprocess 调 CLI
 ├── openclaw/                        # OpenClaw Plugin
 │   ├── openclaw.plugin.json         #   manifest（contracts.tools）
 │   ├── package.json                 #   含 openclaw 块（pluginApi/SDK 版本）
-│   └── index.ts                     #   definePluginEntry + registerTool ×60
+│   └── index.ts                     #   definePluginEntry + registerTool ×67
 ├── dsh/                             # DeepSeek Harness (dsh) Plugin
 │   ├── cordis.patch.yml             #   bundle patch（insert 插件入口）
 │   ├── package.json                 #   含 dsh.bundle 块（bundle manifest）
-│   └── index.ts                     #   cordis apply(ctx) + defineTool ×60
+│   └── index.ts                     #   cordis apply(ctx) + defineTool ×67
 │
 ├── tools/                           # 共享 Python CLI 工具
 │   ├── stock_data.py                #   行情 / 资金流 / 新闻 / 财务 / 短线情绪
@@ -696,6 +740,24 @@ python3 tools/sec_edgar.py holdings 0001067983 --mode manager
 
 首次下载当前 SEC 包约 100 MB；ZIP 按周缓存，CUSIP 反查结果按天缓存，流式扫描不解压整个持仓表、不增加数据库依赖。返回 `report_date`（持仓日期）、`filing_window_end`（公开申报窗口截止）、`cusip_evidence`（原文映射依据），不把文件披露窗口当作持仓日期。`mapping_complete=false` 表示最近十份结构化 13D/G 可能未覆盖所有证券类别或 CUSIP 变更；缺映射直接报错，不做名称模糊匹配。`complete_for_mapped_cusips` 仅在该报告期没有未解决申报链时为 true，不代表实时全部股东。期权与本金持仓在 `positions` 保留，`shares` 合计只计无 PUT/CALL 的 SH 股票。不能将跨机构合计当作已去重的全市场持股。
 
-来源格式与实測依据见 [#51 数据研究](docs/research/issue-51-reverse-holdings.md)。
+13F CLI 预算为 300 秒，宿主另留 30 秒接收输出；其他命令按共享预算表执行。机构查询优先寻找最新已知报告期的原始 13F：较新修订对应的原始版未找到时明确报错，历史分片仍未完全检索时返回 `history_truncated` 与警告。发行人 CUSIP 查询会跳过不可访问/无效 XML，继续核对后续原文；没有任何可验证映射时才报缺失。
+
+## 分析可靠性验证
+
+命令预算集中于 `tools/cli_budgets.json`：通用采集默认 120 秒、市场快照 240 秒、选股 top 须为正整数，预算按候选数及 6 个 worker 的批次计算（默认 20 个候选为 1830 秒）、13F 300 秒；技术分析、市场状态、回测和风险筛查按实际嵌套调用另留预算；四个宿主额外留 30 秒接收 CLI 输出。综合采集保留安全 JSON 错误及 error_code（timeout/empty_output/invalid_json/process_failed/tool_error），不会把失败当成有效空数据。
+
+最终报告的固定证据案例覆盖完整、缺失、过期、同口径冲突及样本不足：
+
+```bash
+.venv/bin/python -m pytest tests/test_analysis_quality.py -q
+# 需要 OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL；只调用模型，数据源使用固定夹具
+.venv/bin/python -m pytest tests/e2e/test_analysis_quality.py -m integration_llm -v
+```
+
+真实模型评测同时要求结构化证据检查与独立上下文的结论审稿通过：审稿检查正文事实、限制说明是否诚实，以及是否过度外推。未运行审稿、结果缺失或模糊都不能算通过；报告自行声明通过不被采信。另有人工核对的正确报告及两类反例用于验证审稿器（正确引用但正文捏造现价、3笔交易却保证长期胜率）。空回答也失败。离线渲染和规则检查不代表真实模型通过，也不证明策略未来有效。信号建议可沿用 source 标识策略版本，按来源复盘胜率、平均收益和样本量；未扣成本、未匹配基准的观察记录不能当作策略回测。
+
+信号结算仅在价格口径可核实时进行：原始价格可直接比较；复权日线需记录日 adjustment_factor（复权价/原始价），当前日线 Tushare、Alpha Vantage 可提供。缺失系数或口径未知时返回 skipped_price_basis，保持未结算，不猜测除权比例。换算后的 exit_price 是记录时价格单位的等价值，实际市场价可不同，evaluation_price_basis 保留依据。evaluate_signals 的 CLI 预算为 300 秒，内部提前结束采集并保存已完成结果，complete/deferred/warnings 指示需要重试的记录；预算耗尽后调整未结算记录的处理顺序，下轮优先处理尚未尝试的记录，避免慢请求长期阻塞后续信号。
+
+市场复盘数据不足时温度/姿态为 null，信号 unknown，data_quality.limitations 说明限制。自选股异动采集失败时 anomaly_status=unavailable、anomaly_count=null，保留警告并计入 summary.partial，不能当成无异常。
 
-Hermes 的 `get_us_holdings` 子进程预算为 300 秒，允许首次下载批量包；其他 CLI 仍为 120 秒。机构查询优先寻找最新已知报告期的原始 13F：较新修订对应的原始版未找到时明确报错，历史分片仍未完全检索时返回 `history_truncated` 与警告。发行人 CUSIP 查询会跳过不可访问/无效 XML，继续核对后续原文；没有任何可验证映射时才报缺失。
+L1 与 L2 综合分均在排序前按可用因子重新归一化；缺失或非有限因子不作零分处理，因子组内部也仅平均有效输入。factor_coverage.ratio 保留原始权重覆盖率，effective_weights 是实际归一化后的权重，高分仍需结合覆盖率判断。

{stock_analysis_plugin-0.2.6 → stock_analysis_plugin-0.2.7}/README.md

@@ -32,7 +32,7 @@ A 股 / 港股 / 美股 / 日股 / 韩股 / 台股综合分析、多因子选股
 
 ## 功能概览
 
-- **60 个工具** — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
+- **67 个工具** — 行情数据、技术分析、K 线形态、资金流向、估值历史、财报日历、股东/ETF/股息、新闻舆情、风险筛查、市场状态等
 - **20 个 Skills** — 综合分析、全市场选股、策略回测 + 17 个策略方法论（缠论、波浪、龙头、情绪周期等）
 - **策略回测引擎** — YAML DSL 定义策略，参数化条件组合，自动诊断，按需进行有限轮参数优化
 - **多数据源 Failover** — 11 个数据源自动容灾切换（akshare / tushare / efinance / 腾讯行情 / 新浪行情 / pytdx / baostock / yfinance / finnhub / longbridge / alphavantage），A 股链路带粘性优选（最近成功的数据源下次优先尝试）
@@ -70,6 +70,8 @@ npm install @weaxs/stock-analysis-plugin
 
 Pi 启动后自动加载，输入 `/skills` 确认。详见 [Pi Agent 接入指南](docs/pi-integration.md)（[English](docs/pi-integration.en.md)）。
 
+新版 Pi（已核验 1.2.0）提供原生 `tool_search` 时，插件自动启用按需工具发现，67 项能力保留注册，仅命中工具加载完整定义。缺少原生发现接口的旧版 Pi 或 SDK 宿主保持全量暴露。检索使用英文关键词或工具名，例如 `get_quote`、`get_financials`。
+
 ### Hermes Agent Plugin
 
 ```bash
@@ -93,7 +95,7 @@ register(ctx)
 openclaw plugins install clawhub:@weaxs/openclaw-stock-analysis
 ```
 
-OpenClaw Gateway 启动后自动加载并注册 60 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖（前提：本机有 `python3 >= 3.10`）。
+OpenClaw Gateway 启动后自动加载并注册 67 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖（前提：本机有 `python3 >= 3.10`）。
 
 详见 [OpenClaw 接入指南](docs/openclaw-integration.md)，或 plugin 自身说明 [`openclaw/README.md`](openclaw/README.md)。
 
@@ -104,7 +106,9 @@ dsh plugin --profile <你的profile> add @weaxs/dsh-stock-analysis
 dsh --profile <你的profile>
 ```
 
-作为 dsh bundle 安装：`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合，注册 60 个 tool + 20 个 skill。postinstall 自动建 `.venv`（pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`，否则回退系统 `python3`）。
+作为 dsh bundle 安装：`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合，注册 67 个 tool + 20 个 skill。postinstall 自动建 `.venv`（pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`，否则回退系统 `python3`）。
+
+新版 dsh 的原生函数调用模式默认通过 `stock_tool_search` 按 Agent 搜索、加载所需工具，支持中文关键词或工具名；旧接口、搜索入口不可用时保留全量暴露。可设置 `toolDiscovery: false` 关闭，配置与 PTC 模式边界见下方接入文档。
 
 详见 [`dsh/README.md`](dsh/README.md)。
 
@@ -281,9 +285,9 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
 
 | 工具 | 说明 |
 |------|------|
-| `screen_stocks` | 全市场多因子筛选（市场情绪调节，可选 L2 量化增强） |
+| `screen_stocks` | 全市场多因子筛选（可选 L2；factor_coverage 展示缺失因子、覆盖度、实际权重及 L2 effective_scores） |
 | `screen_risk` | 风险因子筛查 |
-| `run_backtest` | YAML 策略回测 |
+| `run_backtest` | YAML 策略回测，默认收盘信号于次日开盘成交，execution 返回模型与限制 |
 | `detect_market_regime` | 市场状态检测（牛/熊/震荡） |
 | `get_market_review` | 市场日度复盘数据 |
 | `get_review_history` | 复盘归档历史（最近 N 条，最新在前，用于纵向对比） |
@@ -320,8 +324,8 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
 | `check_alert_rules` | 无状态检查价格、涨跌幅、异动和风险规则 |
 | `record_signal` | 记录 AI 分析建议信号（本地 JSONL 持久化） |
 | `evaluate_signals` | 评估到期信号（target_hit/stop_hit/timeout 结算） |
-| `get_signal_summary` | 信号胜率汇总（按 source/symbol/status 过滤） |
-| `render_stock_report` | 将结构化个股报告渲染为 Markdown |
+| `get_signal_summary` | 信号胜率及分来源平均收益、有效收益样本数与小样本提示（按 source/symbol/status 过滤） |
+| `render_stock_report` | 将结构化个股报告渲染为 Markdown，展示 evidence 与 data_quality 限制 |
 | `render_market_report` | 将结构化市场复盘渲染为 Markdown（save=true 时归档到本地 JSONL） |
 
 批量自选股分析和摘要的 `success` 表示至少获取了有效行情价格、K 线收盘价或技术评分；全部关键数据失败时计入 `failed`，部分结果仍保留。采集脚本复用返回的 K 线计算技术指标，并按股票所属市场查询大盘状态；日/韩/台市场状态暂不可用，非 A 股板块榜单也暂不可用，均会明确返回错误。
@@ -332,6 +336,43 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
 
 选股的 `filters_applied` 只列实际执行的条件，显式条件缺少数据时报错。回测的 `period` 是实际数据期间，`requested_period` 保留请求期间，`warnings` 提示覆盖差异；买入预算包含佣金，年化收益和回撤按实际数据及初始资金计算。
 
+### 无状态研究与风险计算
+
+| 工具 | 说明 |
+|------|------|
+| `compare_stocks` | 比较显式输入的同行指标；检查单位、期间和口径，仅对可比数值排序 |
+| `analyze_disclosure_changes` | 比较新旧公告正文与财务指标，返回来源、变更行号和增长率限制 |
+| `analyze_portfolio_risk` | 一次性持仓的集中度、行业/币种敞口、价格盈亏、止损情景与可选相关性 |
+| `calculate_position_size` | 按现金、风险预算、费用、滑点和交易单位计算本次可买数量 |
+| `analyze_event_study` | 事件前一交易日收盘至各窗口的股票/基准收益差，标明缺失和重叠样本 |
+| `validate_backtest` | 复用现有引擎，滚动训练选候选、样本外验证，比较参数及多个标的 |
+| `compare_analysis_snapshots` | 比较调用方传入的快照，区分新增、删除、变化、数据失效和恢复 |
+
+这些工具不保存自选股、账户或分析历史，也不提供调度/通知。现有数据工具采集行情和财务，宿主传入本次持仓、正文或快照；[完整输入约定与解读工作流](skills/stock-analysis/references/stateless-analysis.md)供四个宿主共用。
+
+大输入经权限受限的临时 JSON 文件传给 Python，调用结束后清理，避免 Windows 命令行长度限制；CLI 也支持 stdin 和 `--input` 文件。公告正文由宿主读取：PDF/OCR 不包含在本次扩展中，只有标题或链接不能声称已读全文。
+
+例如仓位预算（所有金额同币种，lot_size 由用户或交易规则确认）：
+
+```json
+{
+  "equity": 100000, "cash": 20000,
+  "entry_price": 100, "stop_price": 95,
+  "risk_fraction": 0.01, "lot_size": 100,
+  "fee_rate": 0.001, "slippage_rate": 0.001
+}
+```
+
+将上述 JSON 保存为 `input.json` 后运行：
+
+```bash
+python tools/stateless_analysis.py position_size --input input.json
+```
+
+对应宿主工具是 `calculate_position_size`。其余 CLI 子命令依次为 `peers/disclosure/portfolio/event_study/robustness/snapshot`。事件研究可直接传 `symbol/benchmark/start_date/end_date/event_dates`；回测验证可传 `symbols/start_date/end_date/strategies`，由 Python 复用行情接口，避免模型重新抄写历史 K 线。显式价格/datasets 模式仍支持离线计算，两种模式互斥。
+
+跨币种组合必须提供显式汇率；价格盈亏不含历史汇兑损益。稳健性工具仅支持 next_open、每窗口重新从现金开始，样本内敏感性不等于样本外表现。
+
 ## 策略回测 DSL
 
 策略以 YAML 格式定义，支持参数化和条件组合：
@@ -374,10 +415,13 @@ position:
   max_positions: 1
 ```
 
+行情 JSON 保留原有数组/字典形状，添加 `source`、UTC `fetched_at` 和 `data_as_of`。采集时间不是报价时间，提供方未给时间时为 null；仅提供交易日时保留 YYYY-MM-DD，不补造具体时刻；K 线 data_as_of 是该条的日期标签，周/月线标签不是实际末次成交时间；`as_of_basis=trading_calendar` 表示交易日历推断。A 股复权口径延续 qfq/none；其他市场按来源标为 total_return/qfq/unknown，不把 unknown 当已验证复权。
+
 其他可用键：
 
 - `exit.trailing_stop`：移动止损，价格自持仓期间最高收盘价回撤达到该比例即卖出（如 `0.08` = 峰值回撤 8% 触发）；与 `stop_loss` 同时设置时先判固定止损。
 - `benchmark`（顶层）：基准对比标的代码（如 `"sh000300"` 沪深300；指数代码必须带 sh/sz 交易所前缀，裸 6 位数字会被当作个股），设置后回测结果附带 `benchmark` 块（基准买入持有收益与 `excess_return` 超额收益）。
+- `simulation.execution`：默认 `next_open`，前日收盘信号、次日开盘加滑点成交；显式 `same_close` 复现旧收盘成交假设。交易同时返回 signal_date/date。零成交量阻止成交；一字板限制只在输入提供同口径历史 limit_up/limit_down 时执行。`execution` 列出阻止成交次数、未成交订单及限制；止损是收盘信号，未模拟盘口排队、部分成交、结算和市场冲击。
 - `simulation`（顶层）：交易成本。`slippage`（滑点，买卖双边，默认 0.001）、`commission`（佣金，买卖双边，默认 0.0015）、`stamp_tax`（印花税，仅卖出收取，默认 0；A股为 0.0005，各市场税率不同且会调整，按当下实际费率填写）。费率均须在 [0, 1) 区间，越界报错。回测结果附带 `costs` 块（实际生效费率与实付费用合计 `commission_paid`/`stamp_tax_paid`）。
 
 ### 可用指标
@@ -501,27 +545,27 @@ GitHub Actions 的 `e2e-host` 使用 Pi、Hermes、OpenClaw、dsh 的真实运
 | `OPENAI_API_KEY` | Secret | 对应的 API key |
 | `OPENAI_MODEL` | Variable 或 Secret | 支持 tool calling 的模型 ID |
 
-`e2e-llm` 也使用这三项配置；同仓库 PR 和主分支推送会运行，fork PR 不读取 API key。`e2e-host` 缺少任一项时会失败。URL 和 model 同时存在于 Variable 与 Secret 时，优先使用 Secret。
+`e2e-llm` 也使用这三项配置，Hermes（含报告质量评测）、Pi、OpenClaw 和 dsh 通过四个 matrix 作业并行运行，互不因失败而取消；同仓库 PR 和主分支推送会运行，fork PR 不读取 API key。`e2e-host` 缺少任一项时会失败。URL 和 model 同时存在于 Variable 与 Secret 时，优先使用 Secret。
 
 ## 项目结构
 
 ```
 stock-analysis/
 ├── pi/                              # Pi Agent Extension
-│   └── index.ts                     #   注册 60 个工具 + 20 个 skill
+│   └── index.ts                     #   注册 67 个工具 + 20 个 skill
 ├── hermes/                          # Hermes Agent Plugin
 │   ├── plugin.yaml                  #   插件清单
 │   ├── __init__.py                  #   register(ctx) 入口
 │   ├── schemas.py                   #   工具 JSON Schema 定义
-│   └── tools.py                     #   60 个 handler → subprocess 调 CLI
+│   └── tools.py                     #   67 个 handler → subprocess 调 CLI
 ├── openclaw/                        # OpenClaw Plugin
 │   ├── openclaw.plugin.json         #   manifest（contracts.tools）
 │   ├── package.json                 #   含 openclaw 块（pluginApi/SDK 版本）
-│   └── index.ts                     #   definePluginEntry + registerTool ×60
+│   └── index.ts                     #   definePluginEntry + registerTool ×67
 ├── dsh/                             # DeepSeek Harness (dsh) Plugin
 │   ├── cordis.patch.yml             #   bundle patch（insert 插件入口）
 │   ├── package.json                 #   含 dsh.bundle 块（bundle manifest）
-│   └── index.ts                     #   cordis apply(ctx) + defineTool ×60
+│   └── index.ts                     #   cordis apply(ctx) + defineTool ×67
 │
 ├── tools/                           # 共享 Python CLI 工具
 │   ├── stock_data.py                #   行情 / 资金流 / 新闻 / 财务 / 短线情绪
@@ -655,6 +699,24 @@ python3 tools/sec_edgar.py holdings 0001067983 --mode manager
 
 首次下载当前 SEC 包约 100 MB；ZIP 按周缓存，CUSIP 反查结果按天缓存，流式扫描不解压整个持仓表、不增加数据库依赖。返回 `report_date`（持仓日期）、`filing_window_end`（公开申报窗口截止）、`cusip_evidence`（原文映射依据），不把文件披露窗口当作持仓日期。`mapping_complete=false` 表示最近十份结构化 13D/G 可能未覆盖所有证券类别或 CUSIP 变更；缺映射直接报错，不做名称模糊匹配。`complete_for_mapped_cusips` 仅在该报告期没有未解决申报链时为 true，不代表实时全部股东。期权与本金持仓在 `positions` 保留，`shares` 合计只计无 PUT/CALL 的 SH 股票。不能将跨机构合计当作已去重的全市场持股。
 
-来源格式与实測依据见 [#51 数据研究](docs/research/issue-51-reverse-holdings.md)。
+13F CLI 预算为 300 秒，宿主另留 30 秒接收输出；其他命令按共享预算表执行。机构查询优先寻找最新已知报告期的原始 13F：较新修订对应的原始版未找到时明确报错，历史分片仍未完全检索时返回 `history_truncated` 与警告。发行人 CUSIP 查询会跳过不可访问/无效 XML，继续核对后续原文；没有任何可验证映射时才报缺失。
+
+## 分析可靠性验证
+
+命令预算集中于 `tools/cli_budgets.json`：通用采集默认 120 秒、市场快照 240 秒、选股 top 须为正整数，预算按候选数及 6 个 worker 的批次计算（默认 20 个候选为 1830 秒）、13F 300 秒；技术分析、市场状态、回测和风险筛查按实际嵌套调用另留预算；四个宿主额外留 30 秒接收 CLI 输出。综合采集保留安全 JSON 错误及 error_code（timeout/empty_output/invalid_json/process_failed/tool_error），不会把失败当成有效空数据。
+
+最终报告的固定证据案例覆盖完整、缺失、过期、同口径冲突及样本不足：
+
+```bash
+.venv/bin/python -m pytest tests/test_analysis_quality.py -q
+# 需要 OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL；只调用模型，数据源使用固定夹具
+.venv/bin/python -m pytest tests/e2e/test_analysis_quality.py -m integration_llm -v
+```
+
+真实模型评测同时要求结构化证据检查与独立上下文的结论审稿通过：审稿检查正文事实、限制说明是否诚实，以及是否过度外推。未运行审稿、结果缺失或模糊都不能算通过；报告自行声明通过不被采信。另有人工核对的正确报告及两类反例用于验证审稿器（正确引用但正文捏造现价、3笔交易却保证长期胜率）。空回答也失败。离线渲染和规则检查不代表真实模型通过，也不证明策略未来有效。信号建议可沿用 source 标识策略版本，按来源复盘胜率、平均收益和样本量；未扣成本、未匹配基准的观察记录不能当作策略回测。
+
+信号结算仅在价格口径可核实时进行：原始价格可直接比较；复权日线需记录日 adjustment_factor（复权价/原始价），当前日线 Tushare、Alpha Vantage 可提供。缺失系数或口径未知时返回 skipped_price_basis，保持未结算，不猜测除权比例。换算后的 exit_price 是记录时价格单位的等价值，实际市场价可不同，evaluation_price_basis 保留依据。evaluate_signals 的 CLI 预算为 300 秒，内部提前结束采集并保存已完成结果，complete/deferred/warnings 指示需要重试的记录；预算耗尽后调整未结算记录的处理顺序，下轮优先处理尚未尝试的记录，避免慢请求长期阻塞后续信号。
+
+市场复盘数据不足时温度/姿态为 null，信号 unknown，data_quality.limitations 说明限制。自选股异动采集失败时 anomaly_status=unavailable、anomaly_count=null，保留警告并计入 summary.partial，不能当成无异常。
 
-Hermes 的 `get_us_holdings` 子进程预算为 300 秒，允许首次下载批量包；其他 CLI 仍为 120 秒。机构查询优先寻找最新已知报告期的原始 13F：较新修订对应的原始版未找到时明确报错，历史分片仍未完全检索时返回 `history_truncated` 与警告。发行人 CUSIP 查询会跳过不可访问/无效 XML，继续核对后续原文；没有任何可验证映射时才报缺失。
+L1 与 L2 综合分均在排序前按可用因子重新归一化；缺失或非有限因子不作零分处理，因子组内部也仅平均有效输入。factor_coverage.ratio 保留原始权重覆盖率，effective_weights 是实际归一化后的权重，高分仍需结合覆盖率判断。

{stock_analysis_plugin-0.2.6 → stock_analysis_plugin-0.2.7}/docs/hermes-integration.en.md

@@ -61,121 +61,6 @@ services.hermes-agent = {
 
 After starting Hermes Agent, use `/plugins` to view loaded plugins — you should see `stock-analysis`.
 
-You can also verify programmatically:
-
-```python
-from hermes import register
-
-class MockCtx:
-    def __init__(self):
-        self.tools = []
-        self.skills = []
-
-    def register_tool(self, name, toolset, schema, handler):
-        self.tools.append(name)
-
-    def register_skill(self, name, path):
-        self.skills.append(name)
-
-ctx = MockCtx()
-register(ctx)
-print(f"Tools: {len(ctx.tools)}")   # Should print 48
-print(f"Skills: {len(ctx.skills)}") # Should print 20
-```
-
-## How It Works
-
-### Plugin Discovery
-
-Hermes discovers this plugin through two mechanisms:
-
-1. **pip entry point**: `pyproject.toml` declares the `hermes_agent.plugins` entry point:
-
-```toml
-[project.entry-points."hermes_agent.plugins"]
-stock-analysis = "hermes"
-```
-
-> Note: the entry point must reference the **module** (`hermes`), not `hermes:register` — Hermes 0.19's loader calls `ep.load()` and then `getattr(module, "register")`. Pointing at the function makes `ep.load()` return the function itself, and the loader reports "no register() function" and silently skips tool registration.
-
-2. **Directory discovery**: `hermes/plugin.yaml` serves as the plugin manifest for Hermes CLI installs.
-
-### Tool Registration
-
-`hermes/__init__.py` exports a `register(ctx)` function that receives the Hermes PluginContext:
-
-```python
-from pathlib import Path
-from . import schemas, tools
-
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
-SKILLS_DIR = PROJECT_ROOT / "skills"
-
-def register(ctx):
-    for schema in schemas.TOOL_SCHEMAS:
-        name = schema["name"]
-        handler = _HANDLER_MAP[name]
-        ctx.register_tool(
-            name=name,
-            toolset="stock-analysis",
-            schema=schema,
-            handler=handler,
-        )
-
-    for child in sorted(SKILLS_DIR.iterdir()):
-        skill_md = child / "SKILL.md"
-        if child.is_dir() and skill_md.exists():
-            ctx.register_skill(child.name, str(skill_md))
-```
-
-### Tool Definitions (Schema)
-
-`hermes/schemas.py` defines the JSON Schema for all 51 tools, each containing `name`, `description`, and `parameters`:
-
-```python
-TOOL_SCHEMAS = [
-    {
-        "name": "get_kline",
-        "description": "Fetch stock OHLCV candlestick data...",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "symbol": {"type": "string", "description": "Stock symbol"},
-                "period": {"type": "string", "enum": ["daily", "weekly", "monthly"]},
-                "count": {"type": "number", "description": "Number of data points"},
-            },
-            "required": ["symbol"],
-        },
-    },
-    # ... 30 more
-]
-```
-
-### Tool Handlers
-
-`hermes/tools.py` implements 48 handler functions, each calling the corresponding Python CLI script via `subprocess`:
-
-```python
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
-TOOLS_DIR = PROJECT_ROOT / "tools"
-
-def _find_python():
-    venv_python = PROJECT_ROOT / ".venv" / "bin" / "python3"
-    if venv_python.exists():
-        return str(venv_python)
-    return "python3"
-
-def _run(script, args):
-    python = _find_python()
-    cmd = f"{python} {TOOLS_DIR / script} {args}"
-    result = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=120)
-    return result.stdout
-```
-
-### Path Resolution
-
-The plugin locates the project root via `Path(__file__).resolve().parent.parent`. When installed via pip, both `hermes/` and `tools/` are installed as top-level packages in site-packages, maintaining the expected relative path structure.
-
 ## Environment Variables
 
 Environment variables are grouped by function — configure as needed:
@@ -298,7 +183,7 @@ stock-analysis-plugin (wheel)
 ├── hermes/
 │   ├── __init__.py       # register(ctx) entry point
 │   ├── plugin.yaml       # Plugin manifest
-│   ├── schemas.py        # JSON Schema definitions for 51 tools
+│   ├── schemas.py        # JSON Schema definitions for 67 tools
 │   └── tools.py          # 51 handlers calling CLI via subprocess
 └── tools/                # Python CLI tools
 ```