stock-analysis-plugin 0.2.2__tar.gz → 0.2.4__tar.gz

{stock_analysis_plugin-0.2.2 → stock_analysis_plugin-0.2.4}/.github/workflows/autofix.yml

@@ -18,7 +18,8 @@ jobs:
           cache: pip
 
       - name: Install ruff
-        run: pip install "ruff>=0.4.0"
+        # Pinned — must match ci.yml and requirements-dev.txt.
+        run: pip install "ruff==0.15.20"
 
       - name: Ruff auto-fix (lint)
         run: ruff check --fix tools/ skills/ tests/ hermes/

{stock_analysis_plugin-0.2.2 → stock_analysis_plugin-0.2.4}/.github/workflows/ci.yml

@@ -7,9 +7,15 @@ on:
     branches: [main]
   workflow_call:
 
+# One active run per branch/PR — new pushes cancel stale runs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   lint:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
 
@@ -18,7 +24,8 @@ jobs:
           python-version: "3.11"
 
       - name: Install Python lint tools
-        run: pip install ruff>=0.4.0
+        # Pinned — must match requirements-dev.txt and autofix.yml.
+        run: pip install ruff==0.15.20
 
       - name: Ruff check
         run: ruff check tools/ skills/ tests/ hermes/
@@ -29,21 +36,30 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
+          cache: "npm"
 
+      # --ignore-scripts: tsc doesn't need the postinstall-built Python venv.
       - name: Install Node dependencies
-        run: npm install
+        run: npm ci --ignore-scripts
 
       - name: TypeScript type check
         run: npx tsc --noEmit
 
   test:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.10 leg guards the declared floor — verified: full dep set installs
+        # and the suite passes on cpython 3.10.19.
+        python-version: ["3.11", "3.10"]
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: ${{ matrix.python-version }}
           cache: pip
 
       - name: Install dependencies
@@ -57,7 +73,11 @@ jobs:
   network:
     # Real provider calls (akshare/yfinance) — flaky upstreams by nature, so
     # gated to same-repo PRs and pushes (forks skip it, like e2e-llm).
+    # continue-on-error: see publish.yml — a flaky upstream must not block the
+    # release path; failures still surface as annotations on the run.
+    continue-on-error: true
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     if: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }}
     steps:
       - uses: actions/checkout@v4
@@ -82,6 +102,7 @@ jobs:
     # structurally cannot see. Deterministic by design: no LLM, no secrets, and
     # the 4 round-trip tools are the non-network set (see tests/e2e/*.ts).
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
@@ -96,16 +117,20 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
+          cache: "npm"
+
+      - name: Python setup failure check
+        run: node tests/test_setup_python.mjs
 
       # tests/conftest.py imports numpy/pandas at module load, so any pytest run
-      # needs the tools' runtime deps in system python. npm install's postinstall
+      # needs the tools' runtime deps in system python. npm ci's postinstall
       # separately builds .venv (full requirements) — that's the python the
       # host↔python round-trips spawn.
       - name: Install dependencies
         run: |
           pip install -r tools/requirements.txt
           pip install -r requirements-dev.txt
-          npm install
+          npm ci
 
       - name: TypeScript type check
         run: npx tsc --noEmit
@@ -119,6 +144,9 @@ jobs:
       - name: dsh plugin registration
         run: npx tsx tests/test_dsh_integration.ts
 
+      - name: dsh current SDK compatibility
+        run: npx tsx tests/test_dsh_sdk_compat.ts
+
       - name: Hermes plugin registration
         run: pytest tests/test_hermes_integration.py -v
 
@@ -135,9 +163,13 @@ jobs:
         run: npx tsx tests/e2e/test_dsh_e2e.ts
 
   e2e-llm:
-    # Real DeepSeek call. Only runs when DEEPSEEK_API_KEY secret is present
+    # Real OpenAI-compatible call. API key is a secret; URL/model can also be variables.
     # (skipped on forks to prevent secret exposure).
+    # continue-on-error: like `network` — non-deterministic output must not
+    # block the release path (see publish.yml).
+    continue-on-error: true
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     if: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }}
     steps:
       - uses: actions/checkout@v4
@@ -150,33 +182,43 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
+          cache: "npm"
+
+      - name: Resolve model endpoint on runner
+        env:
+          OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL || vars.OPENAI_BASE_URL }}
+        run: node scripts/ci-resolve-llm-host.mjs
 
       - name: Install Python dependencies
         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.
       - name: Install Node dependencies
-        run: npm install
+        run: npm ci
 
       - name: E2E — Hermes LLM flow
         env:
-          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
-          DEEPSEEK_MODEL: ${{ vars.DEEPSEEK_MODEL || 'deepseek-v4-flash' }}
+          OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL || vars.OPENAI_BASE_URL }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_MODEL: ${{ secrets.OPENAI_MODEL || vars.OPENAI_MODEL }}
         run: |
-          if [ -z "$DEEPSEEK_API_KEY" ]; then
-            echo "DEEPSEEK_API_KEY not configured — skipping LLM e2e"
+          if [ -z "$OPENAI_BASE_URL" ] || [ -z "$OPENAI_API_KEY" ] || [ -z "$OPENAI_MODEL" ]; then
+            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
 
       - name: E2E — Pi LLM flow
         env:
-          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
-          DEEPSEEK_MODEL: ${{ vars.DEEPSEEK_MODEL || 'deepseek-v4-flash' }}
+          OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL || vars.OPENAI_BASE_URL }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_MODEL: ${{ secrets.OPENAI_MODEL || vars.OPENAI_MODEL }}
         run: |
-          if [ -z "$DEEPSEEK_API_KEY" ]; then
-            echo "DEEPSEEK_API_KEY not configured — skipping LLM e2e"
+          if [ -z "$OPENAI_BASE_URL" ] || [ -z "$OPENAI_API_KEY" ] || [ -z "$OPENAI_MODEL" ]; then
+            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
@@ -201,39 +243,42 @@ jobs:
           python-version: "3.11"
 
       - uses: actions/setup-node@v4
-        # Node 24: openclaw requires >= 22.19, and pi 0.83's undici breaks on 20.x
-        # (dsh also requires ^22.19 || >=24)
+        # OpenClaw 2026.9.6 requires Node >=24.16.
         with:
-          node-version: "24"
+          node-version: "24.16.0"
+          cache: "npm"
+
+      - name: Resolve model endpoint on runner
+        env:
+          OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL || vars.OPENAI_BASE_URL }}
+        run: node scripts/ci-resolve-llm-host.mjs
 
       - name: Install Node dependencies (also builds repo .venv via postinstall)
-        run: npm install
+        run: npm ci
 
       - name: Install host CLIs
-        # Pinned: pi latest and openclaw latest (slim repack) drifted from the
-        # validated CLIs — openclaw@latest installed no working bin, and pi's
-        # `list` flags changed between releases. dsh is a developer preview
-        # (rc line), so pin it too. `dsh plugin` forwards to pnpm.
+        # Pin the current host releases so failures are reproducible.
         run: |
-          npm i -g @earendil-works/pi-coding-agent@0.83.0
-          npm i -g openclaw@2026.6.33
-          npm i -g @deepseek-ai/dsh@0.1.0-rc.7
+          npm i -g @earendil-works/pi-coding-agent@0.99.0
+          npm i -g openclaw@2026.9.6
+          npm i -g @deepseek-ai/dsh@0.2.0-rc.2
           npm i -g pnpm@10
 
       - name: Real-host smoke QA (${{ matrix.host }})
         env:
-          SMOKE_LLM_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
-          SMOKE_LLM_BASE_URL: https://api.deepseek.com
-          SMOKE_LLM_MODEL: ${{ vars.DEEPSEEK_MODEL || 'deepseek-v4-flash' }}
+          OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL || vars.OPENAI_BASE_URL }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_MODEL: ${{ secrets.OPENAI_MODEL || vars.OPENAI_MODEL }}
         run: |
-          if [ -z "$SMOKE_LLM_API_KEY" ]; then
-            echo "SMOKE_LLM_API_KEY not configured — failing (this check is blocking by design)"
+          if [ -z "$OPENAI_BASE_URL" ] || [ -z "$OPENAI_API_KEY" ] || [ -z "$OPENAI_MODEL" ]; then
+            echo "OPENAI_BASE_URL, OPENAI_API_KEY, and OPENAI_MODEL are required (blocking check)"
             exit 1
           fi
           node tests/e2e/host_smoke.mjs ${{ matrix.host }}
 
   build:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     needs: [lint, test, compat]
     steps:
       - uses: actions/checkout@v4
@@ -241,9 +286,19 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
+          cache: "npm"
 
+      # --ignore-scripts: packing/bundling doesn't need the Python venv
+      # (esbuild's binary arrives via optionalDependencies, not postinstall).
       - name: Install Node dependencies
-        run: npm install
+        run: npm ci --ignore-scripts
+
+      # Bundle both compiled hosts here so esbuild breakage surfaces in CI
+      # instead of at tag-publish time.
+      - name: Build host bundles
+        run: |
+          npm run build:openclaw
+          npm run build:dsh
 
       - name: Verify pack contents
         run: npm pack --dry-run

{stock_analysis_plugin-0.2.2 → stock_analysis_plugin-0.2.4}/.github/workflows/publish.yml

@@ -6,6 +6,9 @@ on:
       - "v*"
 
 jobs:
+  # ci is a whole-workflow reusable call — a caller cannot `needs` individual
+  # jobs inside it, so the flaky jobs (network, e2e-llm) carry job-level
+  # `continue-on-error: true` in ci.yml to keep them off the release path.
   ci:
     uses: ./.github/workflows/ci.yml
     secrets: inherit
@@ -29,8 +32,9 @@ jobs:
       - name: Sync version from tag
         run: bash scripts/sync-version.sh
 
+      # --ignore-scripts: publishing only packs and uploads — no Python venv.
       - name: Install dependencies
-        run: npm install
+        run: npm ci --ignore-scripts
 
       - name: Build and verify
         run: npm pack --dry-run
@@ -95,8 +99,9 @@ jobs:
       - name: Sync version from tag
         run: bash scripts/sync-version.sh
 
+      # --ignore-scripts: publishing only packs and uploads — no Python venv.
       - name: Install dependencies
-        run: npm install
+        run: npm ci --ignore-scripts
 
       - name: Build compiled plugin entry (dist/index.js)
         run: npm run build:openclaw
@@ -111,6 +116,7 @@ jobs:
             fi
           done
           rm -f openclaw/scripts/sync-version.sh
+          cp LICENSE openclaw/LICENSE
 
       # Guard against regression of the issue behind
       # https://github.com/Weaxs/stock-analysis-plugin/issues/3 — a TS entry
@@ -124,11 +130,14 @@ jobs:
           npm pack --dry-run 2>&1 | tee pack-dry-run.txt
           grep -q "dist/index.js" pack-dry-run.txt \
             || { echo "::error::dist/index.js missing from openclaw npm tarball — build ran but files whitelist excludes dist/"; exit 1; }
+          grep -q "LICENSE" pack-dry-run.txt \
+            || { echo "::error::LICENSE missing from openclaw npm tarball"; exit 1; }
           test -f dist/index.js \
             || { echo "::error::openclaw/dist/index.js missing on disk — clawhub publish would ship no compiled entry"; exit 1; }
 
       - name: Install clawhub CLI
-        run: npm i -g clawhub
+        # Pinned — an unpinned clawhub@latest broke a release before; bump deliberately.
+        run: npm i -g clawhub@0.23.3
 
       - name: npm publish
         working-directory: openclaw
@@ -142,10 +151,10 @@ jobs:
           CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
 
       - name: Publish to ClawHub (dry-run)
-        run: clawhub package publish ./openclaw --dry-run
+        run: clawhub package publish ./openclaw --family bundle-plugin --dry-run
 
       - name: Publish to ClawHub
-        run: clawhub package publish ./openclaw
+        run: clawhub package publish ./openclaw --family bundle-plugin
 
       - name: Publish unscoped variant to npm
         # Same payload under the unscoped name. Runs after ClawHub so the
@@ -174,8 +183,9 @@ jobs:
       - name: Sync version from tag
         run: bash scripts/sync-version.sh
 
+      # --ignore-scripts: publishing only packs and uploads — no Python venv.
       - name: Install dependencies
-        run: npm install
+        run: npm ci --ignore-scripts
 
       - name: Build compiled plugin entry (dist/index.js)
         run: npm run build:dsh
@@ -190,6 +200,7 @@ jobs:
             fi
           done
           rm -f dsh/scripts/sync-version.sh
+          cp LICENSE dsh/LICENSE
 
       # Same regression guard as the OpenClaw job: the dsh profile loader
       # imports built JS, so dist must survive the `files` whitelist, and the
@@ -202,6 +213,8 @@ jobs:
             || { echo "::error::dist/index.js missing from dsh npm tarball — build ran but files whitelist excludes dist/"; exit 1; }
           grep -q "cordis.patch.yml" pack-dry-run.txt \
             || { echo "::error::cordis.patch.yml missing from dsh npm tarball — dsh bundle manifest would dangle"; exit 1; }
+          grep -q "LICENSE" pack-dry-run.txt \
+            || { echo "::error::LICENSE missing from dsh npm tarball"; exit 1; }
 
       - name: npm publish
         working-directory: dsh

{stock_analysis_plugin-0.2.2 → stock_analysis_plugin-0.2.4}/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` ×48, each spawns a `tools/*.py` CLI.
+- `pi/index.ts` — Pi extension. `pi.registerTool` ×51, 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` ×48). Bundled with esbuild.
-- `dsh/` — dsh bundle (`package.json` `dsh.bundle` + `cordis.patch.yml` + `index.ts` cordis `apply(ctx)` with `defineTool` ×48 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` ×51). Bundled with esbuild.
+- `dsh/` — dsh bundle (`package.json` `dsh.bundle` + `cordis.patch.yml` + `index.ts` cordis `apply(ctx)` with `defineTool` ×51 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* 48 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* 51 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.
 
 ---
 
@@ -132,7 +132,7 @@ This is the #1 regression surface (issues #2 / #7; the `compat` CI job exists sp
 - **Output is JSON on stdout, always.** Host adapters parse `result.stdout`. Human-readable prose goes to stderr, never stdout.
 - **Errors are data**: print a JSON object with an `error` key (and exit non-zero) rather than an uncaught traceback, so adapters can surface a clean message.
 - **argparse CLI per script**, subcommands per capability (`stock_data.py kline|quote|news|...`). See the README "独立 CLI 使用" section for the established shape.
-- **Keep `tools/` py3.9-compatible** (`ruff.toml` targets `py39`; OpenClaw hosts only guarantee Python ≥ 3.9) even though the Hermes wheel declares `requires-python >= 3.10`. No 3.10+-only syntax in `tools/`.
+- **Keep `tools/` py3.10-compatible** (`ruff.toml` targets `py310`; the Python floor is 3.10 everywhere — Hermes wheel `requires-python >= 3.10`, OpenClaw hosts). PEP 604 annotations (`X | None`) and other 3.10 syntax are allowed; nothing 3.11+-only.
 - **Line length 120**, ruff rules `E,F,W,I,UP,B,SIM` (E501 ignored).
 - Adding a runtime dependency means adding it to `tools/requirements.txt` (the postinstall-built `.venv`) **and** considering the Hermes wheel's `dependencies` in `pyproject.toml`. Follow ponytail rung 5 — don't add a dependency for a one-call problem.
 
@@ -222,7 +222,7 @@ Versions live in **five** manifests that must stay in lockstep: `pyproject.toml`
 
 ## Adding a New Tool
 
-1. Implement the CLI in the appropriate `tools/*.py` (argparse subcommand, JSON stdout, py3.9-compatible).
+1. Implement the CLI in the appropriate `tools/*.py` (argparse subcommand, JSON stdout, py3.10-compatible).
 2. Add a failing pytest first (`tests/test_<module>.py`), then make it pass (see `tdd`).
 3. Register it in all four adapters: `pi/index.ts`, `openclaw/index.ts`, `dsh/index.ts`, `hermes/tools.py` + `hermes/schemas.py` — same name, same params.
 4. Wire it into the relevant `skills/*/SKILL.md` workflow if an agent should call it.

stock_analysis_plugin-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weaxs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{stock_analysis_plugin-0.2.2 → stock_analysis_plugin-0.2.4}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.5
 Name: stock-analysis-plugin
-Version: 0.2.2
+Version: 0.2.4
 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
 Project-URL: Issues, https://github.com/Weaxs/stock-analysis-plugin/issues
 License-Expression: MIT
+License-File: LICENSE
 Keywords: a-shares,ai-agent,akshare,algorithmic-trading,backtest,backtesting,factor-investing,hermes-agent,hermes-plugin,hk-stocks,quantitative-finance,quantitative-trading,stock,stock-analysis,stock-market,stock-screener,technical-analysis,tushare,us-stocks,yfinance
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -20,11 +21,13 @@ Classifier: Topic :: Office/Business :: Financial :: Investment
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Requires-Python: >=3.10
-Requires-Dist: akshare>=1.12.0
+Requires-Dist: akshare>=1.14.0; python_version < '3.11'
+Requires-Dist: akshare>=1.18.97; python_version >= '3.11'
 Requires-Dist: exchange-calendars>=4.5.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: numpy>=1.24.0
 Requires-Dist: pandas>=2.0.0
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.28.0
 Description-Content-Type: text/markdown
 
@@ -54,6 +57,7 @@ A 股 / 港股 / 美股 / 日股 / 韩股 / 台股综合分析、多因子选股
 - [策略回测 DSL](#策略回测-dsl)
 - [市场路由规则](#市场路由规则)
 - [独立 CLI 使用](#独立-cli-使用)
+- [CI 真实宿主测试](#ci-真实宿主测试)
 - [项目结构](#项目结构)
 - [致谢](#致谢)
 - [常见问题](#常见问题)
@@ -61,7 +65,7 @@ A 股 / 港股 / 美股 / 日股 / 韩股 / 台股综合分析、多因子选股
 
 ## 功能概览
 
-- **48 个工具** — 行情数据、技术分析、K 线形态、资金流向、财务指标、新闻舆情、风险筛查、市场状态等
+- **51 个工具** — 行情数据、技术分析、K 线形态、资金流向、财务指标、新闻舆情、风险筛查、市场状态等
 - **20 个 Skills** — 综合分析、全市场选股、策略回测 + 17 个策略方法论（缠论、波浪、龙头、情绪周期等）
 - **策略回测引擎** — YAML DSL 定义策略，参数化条件组合，自动诊断，按需进行有限轮参数优化
 - **多数据源 Failover** — 11 个数据源自动容灾切换（akshare / tushare / efinance / 腾讯行情 / 新浪行情 / pytdx / baostock / yfinance / finnhub / longbridge / alphavantage），A 股链路带粘性优选（最近成功的数据源下次优先尝试）
@@ -122,7 +126,7 @@ register(ctx)
 openclaw plugins install clawhub:@weaxs/openclaw-stock-analysis
 ```
 
-OpenClaw Gateway 启动后自动加载并注册 48 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖（前提：本机有 `python3 >= 3.9`）。
+OpenClaw Gateway 启动后自动加载并注册 51 个 tool。安装时 postinstall 会自动建 `.venv` 并装好 Python 依赖（前提：本机有 `python3 >= 3.10`）。
 
 详见 [OpenClaw 接入指南](docs/openclaw-integration.md)，或 plugin 自身说明 [`openclaw/README.md`](openclaw/README.md)。
 
@@ -133,7 +137,7 @@ dsh plugin --profile <你的profile> add @weaxs/dsh-stock-analysis
 dsh --profile <你的profile>
 ```
 
-作为 dsh bundle 安装：`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合，注册 48 个 tool + 20 个 skill。postinstall 自动建 `.venv`（pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`，否则回退系统 `python3`）。
+作为 dsh bundle 安装：`dsh plugin add` 会把 `cordis.patch.yml` 叠加进 profile 组合，注册 51 个 tool + 20 个 skill。postinstall 自动建 `.venv`（pnpm 需在 profile 的 `pnpm-workspace.yaml` 里给本包配 `allowBuilds`，否则回退系统 `python3`）。
 
 详见 [`dsh/README.md`](dsh/README.md)。
 
@@ -266,7 +270,7 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
 | 工具 | 说明 |
 |------|------|
 | `get_kline` | K 线数据（OHLCV），支持日/周/月线 |
-| `get_quote` | 实时行情快照（非交易时段返回最近交易日收盘价并以 as_of/stale 标注） |
+| `get_quote` | 实时行情快照（非交易时段返回最近交易日收盘价并以 as_of/stale 标注；ETF 的 premium_discount_rate 为正=溢价、负=折价） |
 | `get_capital_flow` | 资金流向（仅 A 股） |
 | `get_news` | 个股相关新闻 |
 | `get_financials` | 财务指标 |
@@ -279,14 +283,16 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
 | `get_market_stats` | 市场统计（涨跌家数、涨停等） |
 | `get_limit_up_pool` | 涨停池/涨停板复盘（连板数、封板资金、炸板次数等，仅 A 股；非交易日自动回退到最近交易日并以 requested_date/stale 标注） |
 | `get_dragon_tiger` | 龙虎榜（净买额/上榜原因/解读，仅 A 股；非交易日自动回退到最近交易日并以 requested_date/stale 标注） |
-| `get_hot_stocks` | 全市场人气热搜榜（东财→雪球→百度，仅 A 股） |
+| `get_hot_stocks` | 全市场人气热搜榜（东财→百度，仅 A 股） |
+| `get_margin_trading` | 个股融资融券明细（融资余额/融资买入额/融券余量等，沪深交易所官方数据，仅 A 股两融标的；金额单位为元，short_*_shares 单位为股） |
+| `get_northbound_flow` | 北向资金市场级净买入序列（东财沪深港通历史数据；2024-08-16 起交易所停止披露日度净买额，仅 2024-08 之前历史数据可查，仅 A 股） |
 | `get_fundamental_context` | 基本面综合上下文 |
 
 ### 分析计算
 
 | 工具 | 说明 |
 |------|------|
-| `get_technical_analysis` | 全面技术指标分析（MA/MACD/RSI/BOLL/KDJ） |
+| `get_technical_analysis` | 全面技术指标分析（MA/MACD/RSI/BOLL/KDJ；多周期共振时 resonance.direction ∈ aligned_bullish/aligned_bearish/divergent） |
 | `analyze_pattern` | K 线形态识别 |
 | `calculate_ma` | 多周期均线计算 |
 | `get_volume_analysis` | 量价分析 |
@@ -302,6 +308,7 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
 | `run_backtest` | YAML 策略回测 |
 | `detect_market_regime` | 市场状态检测（牛/熊/震荡） |
 | `get_market_review` | 市场日度复盘数据 |
+| `get_review_history` | 复盘归档历史（最近 N 条，最新在前，用于纵向对比） |
 | `run_watchlist_analysis` | 批量自选股分析 |
 
 ### 搜索与舆情
@@ -337,7 +344,7 @@ Agent 会自动调用行情 → 技术面 → 基本面 → 资金面 → 消息
 | `evaluate_signals` | 评估到期信号（target_hit/stop_hit/timeout 结算） |
 | `get_signal_summary` | 信号胜率汇总（按 source/symbol/status 过滤） |
 | `render_stock_report` | 将结构化个股报告渲染为 Markdown |
-| `render_market_report` | 将结构化市场复盘渲染为 Markdown |
+| `render_market_report` | 将结构化市场复盘渲染为 Markdown（save=true 时归档到本地 JSONL） |
 
 ## 策略回测 DSL
 
@@ -381,6 +388,12 @@ position:
   max_positions: 1
 ```
 
+其他可用键：
+
+- `exit.trailing_stop`：移动止损，价格自持仓期间最高收盘价回撤达到该比例即卖出（如 `0.08` = 峰值回撤 8% 触发）；与 `stop_loss` 同时设置时先判固定止损。
+- `benchmark`（顶层）：基准对比标的代码（如 `"sh000300"` 沪深300；指数代码必须带 sh/sz 交易所前缀，裸 6 位数字会被当作个股），设置后回测结果附带 `benchmark` 块（基准买入持有收益与 `excess_return` 超额收益）。
+- `simulation`（顶层）：交易成本。`slippage`（滑点，买卖双边，默认 0.001）、`commission`（佣金，买卖双边，默认 0.0015）、`stamp_tax`（印花税，仅卖出收取，默认 0；A股为 0.0005，各市场税率不同且会调整，按当下实际费率填写）。费率均须在 [0, 1) 区间，越界报错。回测结果附带 `costs` 块（实际生效费率与实付费用合计 `commission_paid`/`stamp_tax_paid`）。
+
 ### 可用指标
 
 | 指标 | 说明 | 需要 period |
@@ -457,25 +470,37 @@ python tools/risk_screening.py screen 600519
 python tools/market_regime.py detect A
 ```
 
+## CI 真实宿主测试
+
+GitHub Actions 的 `e2e-host` 使用 Pi、Hermes、OpenClaw、dsh 的真实运行时执行工具调用。在仓库 **Settings → Secrets and variables → Actions** 中配置以下三项，所有 E2E 共用：
+
+| 名称 | 存放位置 | 内容 |
+|---|---|---|
+| `OPENAI_BASE_URL` | Variable 或 Secret | OpenAI 兼容的 API base URL，包含服务商要求的路径（例如 `/v1`） |
+| `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。
+
 ## 项目结构
 
 ```
 stock-analysis/
 ├── pi/                              # Pi Agent Extension
-│   └── index.ts                     #   注册 48 个工具 + 20 个 skill
+│   └── index.ts                     #   注册 51 个工具 + 20 个 skill
 ├── hermes/                          # Hermes Agent Plugin
 │   ├── plugin.yaml                  #   插件清单
 │   ├── __init__.py                  #   register(ctx) 入口
 │   ├── schemas.py                   #   工具 JSON Schema 定义
-│   └── tools.py                     #   48 个 handler → subprocess 调 CLI
+│   └── tools.py                     #   51 个 handler → subprocess 调 CLI
 ├── openclaw/                        # OpenClaw Plugin
 │   ├── openclaw.plugin.json         #   manifest（contracts.tools）
 │   ├── package.json                 #   含 openclaw 块（pluginApi/SDK 版本）
-│   └── index.ts                     #   definePluginEntry + registerTool ×48
+│   └── index.ts                     #   definePluginEntry + registerTool ×51
 ├── dsh/                             # DeepSeek Harness (dsh) Plugin
 │   ├── cordis.patch.yml             #   bundle patch（insert 插件入口）
 │   ├── package.json                 #   含 dsh.bundle 块（bundle manifest）
-│   └── index.ts                     #   cordis apply(ctx) + defineTool ×48
+│   └── index.ts                     #   cordis apply(ctx) + defineTool ×51
 │
 ├── tools/                           # 共享 Python CLI 工具（23 个脚本）
 │   ├── stock_data.py                #   行情 / 资金流 / 新闻 / 财务 / 短线情绪