stock-analysis-plugin 0.2.4 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -48,9 +48,9 @@
48
48
  "type": "object",
49
49
  "description": "风险筛查结果(来自 screen_risk)",
50
50
  "properties": {
51
- "risk_level": { "type": "string", "enum": ["low", "medium", "high"] },
52
- "risk_score": { "type": "integer", "minimum": 0, "maximum": 100 },
53
- "veto_buy": { "type": "boolean" },
51
+ "risk_level": { "type": "string", "enum": ["low", "medium", "high", "unknown"] },
52
+ "risk_score": { "type": ["integer", "null"], "minimum": 0, "maximum": 100 },
53
+ "veto_buy": { "type": ["boolean", "null"] },
54
54
  "flags": {
55
55
  "type": "array",
56
56
  "items": {
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { execSync } from "node:child_process";
2
+ import { execFileSync } from "node:child_process";
3
3
  import { existsSync } from "node:fs";
4
4
  import { join } from "node:path";
5
5
  import { fileURLToPath } from "node:url";
@@ -14,14 +14,14 @@ const venvDir = join(pkgDir, ".venv");
14
14
  const venvPython = venvPythonPath(pkgDir);
15
15
  const requirements = join(pkgDir, "tools", "requirements.txt");
16
16
 
17
- function run(cmd) {
18
- execSync(cmd, { stdio: "inherit", timeout: 1_800_000 });
17
+ function run(bin, args) {
18
+ execFileSync(bin, args, { stdio: "inherit", timeout: 1_800_000 });
19
19
  }
20
20
 
21
21
  function findPython() {
22
22
  for (const name of ["python3", "python"]) {
23
23
  try {
24
- const ver = execSync(`${name} --version`, { stdio: "pipe" }).toString().trim();
24
+ const ver = execFileSync(name, ["--version"], { stdio: "pipe" }).toString().trim();
25
25
  const match = ver.match(/(\d+)\.(\d+)/);
26
26
  if (match && (parseInt(match[1]) > 3 || (parseInt(match[1]) === 3 && parseInt(match[2]) >= 10))) {
27
27
  return name;
@@ -42,10 +42,10 @@ try {
42
42
  }
43
43
 
44
44
  if (!existsSync(venvDir)) {
45
- run(`${python} -m venv "${venvDir}"`);
45
+ run(python, ["-m", "venv", venvDir]);
46
46
  }
47
47
 
48
- run(`"${venvPython}" -m pip install -q -r "${requirements}"`);
48
+ run(venvPython, ["-m", "pip", "install", "-q", "-r", requirements]);
49
49
  } catch (err) {
50
50
  console.warn(
51
51
  `\n[pi-stock-analysis] Python setup failed: ${err.message}\n` +
@@ -1,24 +1,30 @@
1
1
  ---
2
2
  name: bull-trend
3
- description: 趋势追踪分析:识别中长期趋势、所处阶段和离场条件。用于多头排列、上升通道或持有趋势股。
3
+ description: 趋势交易:识别中长期趋势,制定入场、持仓和退出规则。用于趋势股持有、规则化趋势策略或肥尾收益分析。
4
4
  ---
5
5
 
6
6
  # 趋势追踪分析
7
7
 
8
8
  ## 核心理念
9
9
 
10
- 趋势追踪的核心是"顺势而为"——在确认趋势形成后入场,在趋势转弱时离场。不预测顶底,只跟随趋势。
10
+ 趋势追踪用可执行的规则参与趋势,通过控制试错损失、保留盈利空间捕获少数大行情。肥尾描述收益分布,趋势描述价格路径;肥尾指标不是趋势启动或延续信号。
11
+
12
+ 用户询问塔勒布、肥尾计算、极端行情或策略是否依赖少数大盈利时,先读取 [肥尾度量与趋势收益诊断](references/fat-tails.md)。概念问题直接解释方法;需要具体统计结果时,按参考中的数据口径准备输入并调用 `scripts/tail_analysis.py`。普通趋势判断无需加载这份参考。
13
+
14
+ 仅解释肥尾概念时,到此完成;下述流程用于具体标的的趋势分析。
11
15
 
12
16
  ## 执行流程
13
17
 
14
18
  ### 1. 采集数据
15
19
 
16
- 运行数据采集脚本获取 120 根日K线及技术指标:
20
+ 运行数据采集脚本获取 120 根日K线及技术指标(相对本 skill 目录执行):
17
21
 
18
22
  ```bash
19
23
  python3 scripts/gather.py <symbol>
20
24
  ```
21
25
 
26
+ 确认数据日期、周期和复权口径;120 根日K线用于近期趋势判断。肥尾分支按参考文件另取历史收益,报告实际取得的区间和样本量。
27
+
22
28
  ### 2. 趋势确认
23
29
 
24
30
  **多头趋势确认条件**:
@@ -32,26 +38,44 @@ python3 scripts/gather.py <symbol>
32
38
  - MACD 在零轴之下运行
33
39
  - 价格沿下降通道运行
34
40
 
41
+ 报告哪些条件已满足、哪些尚未满足,并给出对应数值或价格位置。空头趋势对仅能做多的股票账户意味着退出或观望;做空建议须有对应市场和账户能力。
42
+
35
43
  ### 3. 趋势阶段判断
36
44
 
37
45
  | 阶段 | 特征 | 操作 |
38
46
  |------|------|------|
39
- | 启动期 | 均线粘合后向上发散,放量突破 | 建仓 |
40
- | 加速期 | 价格加速上涨,远离均线 | 持有,注意高位风险 |
41
- | 成熟期 | 涨幅放缓,量能递减 | 逐步减仓 |
42
- | 衰退期 | 跌破 MA20 或趋势线 | 清仓 |
47
+ | 启动期 | 均线粘合后向上发散,放量突破 | 检查入场触发和初始风险 |
48
+ | 加速期 | 价格加速上涨,远离均线 | 按持仓规则跟踪,更新保护位 |
49
+ | 成熟期 | 涨幅放缓,量能递减 | 检查退出条件,阶段标签本身不触发减仓 |
50
+ | 衰退期 | 跌破预先选定的均线或趋势支撑 | 按退出规则执行 |
43
51
 
44
52
  ### 4. 关键指标
45
53
 
46
54
  - **ADX 替代**:用 MA 斜率和排列程度衡量趋势强度
47
55
  - **趋势线**:连接近期低点作为上升趋势线
48
- - **回调幅度**:健康回调通常不超过前一波涨幅的 38.2%-50%
56
+ - **回调幅度**:描述相对前一波涨幅的回撤及是否破坏支撑;斐波那契比例只作为观察位置,不能单独证明回调健康。
57
+
58
+ ### 5. 形成交易规则
59
+
60
+ 先读取 [短线交易决策框架](../stock-analysis/references/short-term-trading.md)的风险单位和市场成交约束,再形成同一套入场、持仓和退出规则:
61
+
62
+ - **入场**:指定周期、触发条件、判断时点和成交假设。例如收盘突破此前 20 根K线最高价,阈值排除当前K线;历史检验使用信号产生后可成交的价格。
63
+ - **初始风险**:给出初始止损、单笔风险预算和仓位。按预算 / 入场到止损的每股损失估算数量,并受资金、交易单位和组合风险限制;跳空和无法成交可能使实际亏损超过预算。
64
+ - **持仓**:趋势条件持续满足时保留盈利空间。保护位随有利走势更新,做多止损只上移;涨幅大或收益处于高分位本身不构成退出条件。
65
+ - **退出**:明确采用均线失效、通道破位或移动止损中的哪一种、如何触发。固定止盈属于可选策略约束,要说明它可能截断大盈利;参数是待检验假设,不归为塔勒布公式。
66
+
67
+ 规则完成标准:每项都有可核验的触发条件,说明下一次观察时点,以及触发后动作。用户已有规则时按其规则评价,调整另列为建议。
68
+
69
+ ### 6. 按需检验
70
+
71
+ 用户要求历史验证时使用 [策略回测](../strategy-backtest/SKILL.md)。先核对现有 DSL 能否表达规则,无法表达的条件标为未验证;不以近似规则冒充原策略。趋势收益的利润集中度诊断按肥尾参考文件执行。
49
72
 
50
73
  ## 输出要求
51
74
 
52
75
  分析完成后输出:
53
76
  1. 当前趋势方向和阶段
54
- 2. 趋势强度评分(1-10)
77
+ 2. 趋势证据和未满足条件
55
78
  3. 关键趋势支撑/压力位
56
79
  4. 入场/持有/离场建议
57
- 5. 止损位建议
80
+ 5. 初始风险、保护位和退出触发条件
81
+ 6. 数据或成交限制;肥尾分支附计算口径和不确定性
@@ -0,0 +1,91 @@
1
+ # 肥尾度量与趋势收益诊断
2
+
3
+ 本参考供趋势 skill 和趋势策略回测按需读取。数值由本 skill 的 [计算脚本](../scripts/tail_analysis.py) 执行,无需独立工具注册。保留输入、运行参数和输出;没有执行环境或数据时只解释方法,数值标为未计算。
4
+
5
+ ## 调用脚本
6
+
7
+ 从插件根目录使用安装了现有 numpy 依赖的 Python 运行(POSIX 通常为 `.venv/bin/python3`,Windows 为 `.venv/Scripts/python.exe`):
8
+
9
+ ```bash
10
+ python skills/bull-trend/scripts/tail_analysis.py returns historical-returns.json --n 2 10 30 --draws 20000 --seed 42
11
+ python skills/bull-trend/scripts/tail_analysis.py returns historical-returns.json --current 0.05
12
+ python skills/bull-trend/scripts/tail_analysis.py trades backtest-result.json
13
+ ```
14
+
15
+ `returns` 输入是同周期历史对数收益的 JSON 数组,如 `[0.01, -0.02, 0.005]`,以小数表示;`--current` 的当前收益另传,必须从历史输入中排除。脚本不转换价格、不抓行情、不识别日期,因此先按下文校验并记录数据口径。`trades` 输入是含完整 `trades` 数组的回测 JSON。脚本 stdout 输出 JSON,失败返回 `error` 并以非零状态退出。
16
+
17
+ κ 默认 n0 = 1,以固定种子做 iid 经验重抽样,输出每个 n 的 κ 和平均绝对偏差;换种子重复运行检查 Monte Carlo 波动,换历史窗口检查数据敏感性。输出没有总体置信区间。`sample_count` 是历史收益数量,`draws` 是模拟轮数,两者不能混称样本量。`current_event.percentile` 为 0..1,`upper_exceedances` / `lower_exceedances` 是历史严格超过 / 低于当前收益的次数。
18
+
19
+ ## 先确定分析对象
20
+
21
+ | 用户问题 | 分析对象 | 可交付结论 |
22
+ |---|---|---|
23
+ | 收益分布有多肥尾 | 固定周期的历史收益 | 样本尾部特征、κ 的条件性估计 |
24
+ | 当前涨跌是否极端 | 当前收益与此前同周期收益 | 历史分位或阈值超越,不能推导后续方向 |
25
+ | 趋势系统是否靠大赢家 | 策略平仓盈亏 | 盈利集中度及移除大赢家后的敏感性 |
26
+
27
+ 市场收益的厚尾、策略收益的正偏和趋势延续是不同性质。塔勒布的度量回答统计稳定性问题;下文的分位和盈利贡献是本项目的诊断方法,不称为塔勒布交易信号。
28
+
29
+ ## 数据口径
30
+
31
+ 使用 `get_kline` 或现有 `stock_data.py kline`,核对实际返回的日期范围、周期、数量和复权标记。股票历史价格保持一致复权口径,指数保持原始点位;先处理乱序、重复日期和无效价格,说明停牌或缺失导致的时间间隔,保留真实极端收益。
32
+
33
+ 默认分析对数收益 `r_t = log(P_t / P_{t-1})`,仅使用正价格。日、周收益分别计算;周收益从周末价格或同一周日对数收益之和取得,避免把重叠多日收益当作独立样本。策略盈利贡献使用货币盈亏,不混用价格收益。
34
+
35
+ 申请多年的同口径历史,报告实际样本量;120 根日K线只能给出短窗口描述。不存在通用的“够用样本数”;长历史也可能混合不同制度或波动阶段,按分段结果检查稳定性。
36
+
37
+ ## 当前事件的历史分位
38
+
39
+ 以当前事件之前的同周期收益 `r_1,...,r_N` 为参考,对当前收益 `r_*` 计算经验分位:
40
+
41
+ ```text
42
+ F_hat(r_*) = count(r_i <= r_*) / N
43
+ ```
44
+
45
+ 报告单侧方向、参考区间、N 和超越次数。例如当前上涨高于历史样本的 99% 分位,仅说明它相对该样本少见。样本之外的事件频率不可由零超越次数认定为零;回测每个时点只使用此前数据计算阈值。
46
+
47
+ ## 塔勒布的 κ:有限样本聚合速度
48
+
49
+ 来源:[Taleb, How Much Data Do You Need? A Pre-asymptotic Metric for Fat-tailedness](https://arxiv.org/html/1802.05495),Definition 1、Equation (1) 和 III-B。
50
+
51
+ 设 `X_i` 独立同分布且具有有限绝对一阶矩:
52
+
53
+ ```text
54
+ S_n = sum(X_i, i=1..n)
55
+ M(n) = E[abs(S_n - E[S_n])]
56
+ kappa(n0, n) = 2 - log(n/n0) / log(M(n)/M(n0)), n > n0 >= 1
57
+ ```
58
+
59
+ `M(n)` 是 n 项之和相对其均值的平均绝对偏差,不是中位数绝对偏差,也不是 n 项均值的偏差。高斯分布满足 `M(n)/M(n0) = sqrt(n/n0)`,因此 κ = 0。在论文适用的分布中,较高 κ 表示增加样本带来的均值稳定性改善较慢;κ 与 n0、n 有关。
60
+
61
+ 脚本计算的是**基于历史经验分布的条件性估计**:用历史均值中心化后计算 `M_hat(1)`,有放回独立抽样 n 项相加,以绝对和值的模拟均值估计 `M_hat(n)`,代入 n0 = 1 的公式。
62
+
63
+ 零离散度或零对数分母时,脚本返回 `kappa: null` 和 `unavailable_reason`。估计超出预期范围时报告原值并检查假设和数值稳定性,不强行裁剪到 [0,1]。
64
+
65
+ 股价收益可能具有自相关、波动聚集和制度变化,独立抽样会抹去时间结构。按真实连续时间聚合或使用块抽样时,应将结果标为包含时间依赖的描述性统计,与原论文的 iid κ 区分。仅重抽历史不能创造尚未出现的极端事件,也不能证明总体尾部已被充分观测。
66
+
67
+ κ 不能区分获利方向,不能预测趋势启动。论文中 κ > 0.15 是对正态近似可靠性的启发式提醒,不是入场、止盈或“已到肥尾”的通用阈值。
68
+
69
+ ## 趋势策略的盈利集中度
70
+
71
+ 来源:[CFM, Making fat right tails fatter with trend following… most of the time](https://www.cfm.com/making-fat-right-tails-fatter-with-trend-following-most-of-the-time/)。趋势追踪的凸性和正偏依赖策略与时间尺度;单次跳空或快速反转未必能被系统捕获。
72
+
73
+ 使用 `run_backtest` 返回的 `trades`,仅取 `type == "sell"` 的平仓记录,以 `pnl` 的货币金额计算;`pnl_pct` 是小数比例,不能当百分数或与货币盈亏相加。先确认返回结果是否完整、是否存在未平仓头寸以及费用覆盖口径。
74
+
75
+ ```text
76
+ G = sum(max(pnl_i, 0))
77
+ L = sum(min(pnl_i, 0))
78
+ T = G + L
79
+ C_k = 最大 k 笔正盈利之和 / G
80
+ T_without_k = T - 最大 k 笔正盈利之和
81
+ ```
82
+
83
+ 默认报告最大 1 笔和最大 3 笔,正盈利笔数不足时使用实际数量并注明。G = 0 时集中度不可计算;同时报告交易笔数、G、L、最差单笔及回测已有的最大回撤。使用 G 作分母,避免总净利润接近零时比率失真。
84
+
85
+ `T_without_k` 是已实现盈亏的删除敏感性分析,保留其余交易金额不变;它不是删除交易后重新模拟的资金曲线或收益率。未平仓盈亏另列,不能把 T 当作账户总收益。少数赢家贡献高符合某些趋势系统的结构,但不能单凭这一点证明策略有效或失效;结合成本、回撤、不同区间和样本外表现评价。
86
+
87
+ 现有回测有固定止盈默认值;省略 `take_profit` 不会关闭止盈。验证保留右尾的退出规则前,检查实际引擎和 DSL 的支持情况,将无法表达的规则明确列为未验证。
88
+
89
+ ## 完成标准
90
+
91
+ 报告指出分析对象、数据来源及区间、周期、复权口径、样本量、公式与估计方法、实际数值或未计算原因。κ 结果还需注明 n0、n、抽样假设和敏感性;盈利集中度需注明平仓与未平仓口径。交易建议依据趋势和风险规则,统计结果仅提供其能支持的证据。
@@ -0,0 +1,132 @@
1
+ #!/usr/bin/env python3
2
+ """Skill-local tail diagnostics from historical returns or backtest JSON."""
3
+
4
+ import argparse
5
+ import json
6
+ import math
7
+ import sys
8
+ from pathlib import Path
9
+
10
+ import numpy as np
11
+
12
+
13
+ class Parser(argparse.ArgumentParser):
14
+ def error(self, message):
15
+ raise ValueError(message)
16
+
17
+
18
+ def finite_number(value):
19
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
20
+ raise ValueError("Input values must be finite JSON numbers")
21
+ return float(value)
22
+
23
+
24
+ def analyze_returns(data, args):
25
+ if not isinstance(data, list) or len(data) < 2:
26
+ raise ValueError("Expected a JSON array of at least two historical returns")
27
+ values = np.array([finite_number(value) for value in data])
28
+ if not 100 <= args.draws <= 1000000 or args.seed < 0 or any(n < 2 or n > 10000 for n in args.n):
29
+ raise ValueError("Require draws in 100..1000000, seed >= 0, and n in 2..10000")
30
+ centered = values - values.mean()
31
+ mad = float(np.abs(centered).mean())
32
+ rng = np.random.default_rng(args.seed)
33
+ rows = []
34
+ for n in args.n:
35
+ total = 0.0
36
+ if mad > 0:
37
+ # Bound temporary arrays when either summands or draws is large.
38
+ batch_size = max(1, 1000000 // n)
39
+ for start in range(0, args.draws, batch_size):
40
+ batch = min(batch_size, args.draws - start)
41
+ sums = rng.choice(centered, size=(batch, n)).sum(axis=1)
42
+ total += float(np.abs(sums).sum())
43
+ summed_mad = total / args.draws
44
+ denominator = math.log(summed_mad / mad) if mad > 0 and summed_mad > 0 else 0
45
+ rows.append(
46
+ {
47
+ "n0": 1,
48
+ "n": n,
49
+ "mean_absolute_deviation_sum": summed_mad,
50
+ "kappa": 2 - math.log(n) / denominator if denominator else None,
51
+ "unavailable_reason": None if denominator else "Zero dispersion or degenerate aggregation",
52
+ }
53
+ )
54
+ event = None
55
+ if args.current is not None:
56
+ current = finite_number(args.current)
57
+ event = {
58
+ "return": current,
59
+ "percentile": float(np.mean(values <= current)),
60
+ "upper_exceedances": int(np.sum(values > current)),
61
+ "lower_exceedances": int(np.sum(values < current)),
62
+ }
63
+ return {
64
+ "sample_count": len(values),
65
+ "draws": args.draws,
66
+ "seed": args.seed,
67
+ "mean_absolute_deviation": mad,
68
+ "kappa": rows,
69
+ "current_event": event,
70
+ "method": "iid resampling of centered empirical returns; not a population tail estimate or trading signal",
71
+ }
72
+
73
+
74
+ def analyze_trades(data):
75
+ if not isinstance(data, dict) or not isinstance(data.get("trades"), list):
76
+ raise ValueError("Expected a backtest JSON object with a trades array")
77
+ if any(not isinstance(trade, dict) or trade.get("type") not in {"buy", "sell"} for trade in data["trades"]):
78
+ raise ValueError("Each trade must have type buy or sell")
79
+ pnl = [finite_number(trade.get("pnl")) for trade in data["trades"] if trade["type"] == "sell"]
80
+ winners = sorted((value for value in pnl if value > 0), reverse=True)
81
+ gross_profit = math.fsum(winners)
82
+ gross_loss = math.fsum(value for value in pnl if value < 0)
83
+ net = math.fsum(pnl)
84
+ return {
85
+ "closed_trades": len(pnl),
86
+ "winning_trades": len(winners),
87
+ "gross_profit": gross_profit,
88
+ "gross_loss": gross_loss,
89
+ "realized_net_pnl": net,
90
+ "worst_trade_pnl": min(pnl) if pnl else None,
91
+ "winner_contribution": [
92
+ {
93
+ "requested_k": k,
94
+ "actual_k": min(k, len(winners)),
95
+ "share_of_gross_profit": math.fsum(winners[:k]) / gross_profit if gross_profit else None,
96
+ "realized_pnl_without_top_k": net - math.fsum(winners[:k]),
97
+ }
98
+ for k in (1, 3)
99
+ ],
100
+ "method": "closed monetary pnl only; deletion sensitivity is not an equity-curve rerun",
101
+ }
102
+
103
+
104
+ def main():
105
+ try:
106
+ parser = Parser(description=__doc__)
107
+ sub = parser.add_subparsers(dest="command", required=True, parser_class=Parser)
108
+ returns = sub.add_parser("returns", help="Analyze a JSON array of historical log returns")
109
+ returns.add_argument("input", type=Path)
110
+ returns.add_argument("--n", nargs="+", type=int, default=[2, 10, 30])
111
+ returns.add_argument("--draws", type=int, default=20000)
112
+ returns.add_argument("--seed", type=int, default=42)
113
+ returns.add_argument("--current", type=float, help="Separate current return, excluded from historical input")
114
+ trades = sub.add_parser("trades", help="Analyze a complete run_backtest JSON result")
115
+ trades.add_argument("input", type=Path)
116
+ args = parser.parse_args()
117
+ data = json.loads(args.input.read_text(encoding="utf-8"))
118
+ result = analyze_returns(data, args) if args.command == "returns" else analyze_trades(data)
119
+ print(json.dumps(result, ensure_ascii=True, allow_nan=False))
120
+ return 0
121
+ except OSError:
122
+ error = "Cannot read input JSON file"
123
+ except (ValueError, OverflowError) as exc:
124
+ error = "Invalid JSON input" if isinstance(exc, json.JSONDecodeError) else str(exc)
125
+ except Exception:
126
+ error = "Tail analysis failed unexpectedly"
127
+ print(json.dumps({"error": error}, ensure_ascii=True))
128
+ return 1
129
+
130
+
131
+ if __name__ == "__main__":
132
+ sys.exit(main())
@@ -22,6 +22,8 @@ gather 工具返回:
22
22
  - `stock_info` — 公司基本信息
23
23
  - `sector_rankings` — 板块排名
24
24
 
25
+ A 股事件原文先调用 `get_announcements`:业绩预告用 `forecast`、快报用 `express`、减持用 `reduction`、增发用 `issuance`、问询及回复用 `inquiry`、分红用 `dividend`,指定 `start_date/end_date`。返回 PDF 链接而非正文;读取原文后再量化,`truncated=true` 时缩小日期范围。
26
+
25
27
  新闻摘要只用于发现事件。金额、期限、合同对手、业绩变化或政策原文必须由公告/原文确认;只有摘要时不做精确量化。
26
28
 
27
29
  制定短线计划时读取[短线交易决策框架](../stock-analysis/references/short-term-trading.md),用状态机、相对强弱和风险单位约束事件交易。
@@ -87,3 +89,9 @@ gather 工具返回:
87
89
  5. 触发、失效、时间止损、潜在收益/R 与风险提示
88
90
 
89
91
  完成标准:区分“已确认事实”“推断的影响路径”和“待验证项”,并为交易计划给出可观察的失效条件。
92
+
93
+ 财报季排期使用 `get_earnings_calendar(report_date="YYYY-MM-DD", symbol=...)`:最新预约/修订日期是计划,实际披露日期是实绩时间,业绩预告是已公告预估。除息事件用 `get_dividends(mode="calendar", symbol=...)`;不补造未公告日期或把分红预案计入已支付现金。
94
+
95
+ ### 补充数据覆盖
96
+
97
+ get_earnings_calendar 查询 A 股仍需 report_date;HK 提供 symbol,可选财政期末 report_date;优先 HKEX 已公告业绩审批董事会排期 confirmation=official_board_meeting_notice、date_kind=scheduled_board_meeting,不能称实际披露日。供应商备选日期为 provider_only,未知期次在请求特定报告期时另列 unverified_schedules,不能强行匹配。
@@ -22,6 +22,8 @@ gather 工具返回:
22
22
  - `stock_info` — 公司基本信息(行业、板块)
23
23
  - `sector_rankings` — 板块排名
24
24
 
25
+ 需要财务趋势时调用 `get_financials(symbol, annual=true, periods=10)`。港股配置 `LIXINGER_TOKEN` 后优先理杏仁非金融公司财报,按真实 `report_type` 判断年报,保留实际财年末、披露日期、币种;历史 ROE/毛利率/净利率为百分数,顶层 `roe/profit_margin` 延续小数比例。读取 `available_periods/warnings`,缺期不补造。有效 Yahoo 顶层快照与历史行分开读:`currency` 为快照财报币种、`market_cap_currency` 为市值币种,历史币种在 `periods` 每行,`snapshot_source` 标记快照来源;null 不用历史值补成跨期或跨币种数字;顶层 `report_date` 未知时读取 `periods` 的历史日期,不当作当前快照报告期。
26
+
25
27
  `financials` 通常只是单期摘要。多期趋势、经营现金流、应收账款或同业估值未返回时,把对应维度标为“数据不足”,不推断趋势、不计分。
26
28
 
27
29
  ## 分析框架(4 步法)
@@ -77,3 +79,9 @@ gather 工具返回:
77
79
  5. 投资建议与关注风险点
78
80
 
79
81
  只有收入、利润、现金流和 ROE 均有可比多期数据时,才可给出“优质”结论;否则完成标准是给出已验证项、缺失项和最小补证建议。
82
+
83
+ 用户要求长期质量、五到十年财报或 ROE/利润率趋势时,补充 `get_financials(symbol, periods=10, annual=true)`;逐年比较同口径年报,实际可得年份不足时明确标注,不以最近十个季度代替十年。结合 `get_valuation_history` 检查估值分位,分位窗口以实际返回数据为准。
84
+
85
+ ### 补充数据覆盖
86
+
87
+ 指数估值可用 get_index_valuation;中证补充多年滚动 PE,配置 LIXINGER_TOKEN 可补理杏仁 mcw 历史 PB。每个指标按其来源/口径使用,不把缺失 PB 或近期 PE1 当长期数据。
@@ -5,6 +5,10 @@ description: 综合股票分析:联合技术、基本面、资金、消息和
5
5
 
6
6
  # 综合股票分析
7
7
 
8
+ 美股机构研究调用 `get_us_holdings(cik, mode=auto)`:有当前或已检索历史 13F 时返回机构组合,否则按发行人 CIK 反查机构;也可显式选 `manager/issuer`,如 Berkshire `0001067983` 查组合、Apple `0000320193` 用 `issuer` 查机构。发行人映射仅使用核对 CIK 的官方 13D/G CUSIP,不做名称猜测;无映射直接报缺失。首次下载约 100 MB,后续缓存,Hermes 查询预算 300 秒。读取 `report_date/filing_window_end/cusip_evidence`,区分持仓日期与披露窗口;修订重述替换、新增补充,缺基础版或未知修订时总量 null,并计入 `unresolved_manager_count`。`mapping_complete=false` 表示不能保证涵盖所有类别或变更,`complete_for_mapped_cusips` 只表示已映射证券在公开数据窗口的申报链完整性,不能称实时全部股东。期权/本金在 `positions` 单列,不能把跨机构持股简单合计成去重比例。机构组合查询仍返回最新已知报告期的原始 13F 与修订链接,缺少对应原始版时明确报错;`history_truncated=true` 时不能将旧记录当作已完整检索。存在修订先读原文,不能自动推断变化。
9
+
10
+ 美股内部人研究调用 `get_insider_trades(symbol, days=90, top=10)`,需设置含真实联系邮箱的 `SEC_USER_AGENT`。`days` 按申报日期过滤,`top` 限制文件数;只将代码 P/S 视作买卖信号,授予、行权、赠与等保留原始代码和脚注,衍生品单列。Form 4/A 与原申报勿重复计算,检查截断和失败提示;`screen_risk` 仍仅支持 A 股。
11
+
8
12
  ## 意图路由表
9
13
 
10
14
  快速问答先判断意图,按下表走最短调用链;完整综合研判走下方执行流程(gather 采集管线),不受此表限制。单工具可答的问题按各工具描述中的适用场景选择,本表不再重复。
@@ -22,16 +26,18 @@ description: 综合股票分析:联合技术、基本面、资金、消息和
22
26
 
23
27
  ### 第一步:采集数据
24
28
 
25
- 运行数据采集脚本(并行获取 quote/kline/technical/financials/capital_flow/news/risk/regime 共 8 项数据):
29
+ 运行数据采集脚本(并行采集行情、K 线、财务、资金、筹码、新闻、舆情、风险和大盘状态;技术指标复用本次 K 线计算):
26
30
 
27
31
  ```bash
28
32
  python3 scripts/gather.py <symbol>
29
33
  ```
30
34
 
31
- 解析返回的 JSON 数据。如果某个字段为 `null`,表示该数据获取失败,基于可用数据继续分析。
35
+ 解析返回的 JSON 数据。如果某个字段为 `null` 或包含 `error`,表示该数据不可用,基于可用数据继续分析。大盘状态按股票所属市场查询;日/韩/台市场暂不支持,标明缺失,不能套用 A 股状态。
32
36
 
33
37
  解读实时行情前先调 `get_trading_phase` 确认该市场当前盘中阶段(盘前/早盘/午间休市/午盘/交易中/盘后/休市),避免把休市时的静态快照当作盘中信号解读。
34
38
 
39
+ 港股 `get_quote` 自动按 yfinance → 腾讯 → finnhub → longbridge 容灾,腾讯无需 API key,使用 `r_hk` 实时报价通道(`hk` 通道延迟约 15 分钟)。腾讯港股成交量为股,成交额及市值为港元;PB、换手率、量比为 null 时按缺失处理。该备用源只覆盖报价,K 线仍走原链路。
40
+
35
41
  ### 第二步:综合研判
36
42
 
37
43
  根据获取的数据进行多维度分析:
@@ -60,7 +66,7 @@ python3 scripts/gather.py <symbol>
60
66
 
61
67
  **风险筛查**:
62
68
  - 7维度风险标记(估值极端/技术预警/解禁到期/内部人减持/业绩预警/监管处罚/行业政策)
63
- - 风险评级(low/medium/high)和一票否决(veto_buy)
69
+ - 风险评级(low/medium/high/unknown)和一票否决(veto_buy);查看 data_complete、warnings,unknown 或 null 表示缺少数据,不能据此判定低风险或已通过检查
64
70
  - 如果 veto_buy=true,必须在报告中醒目提示
65
71
 
66
72
  ### 第三步:渲染研报
@@ -77,6 +83,7 @@ python3 scripts/gather.py <symbol>
77
83
  - 信号持久化在本地 JSONL(`$STOCK_SIGNAL_STORE` 或 `~/.stock-analysis/signals.jsonl`);是否记录由宿主 Agent 决定,不阻塞报告输出。
78
84
 
79
85
  ## 注意事项
86
+ - `get_kline` 的 A 股股票/ETF 数据为前复权,每条记录 `adjusted="qfq"`;显式指数 `sh000xxx` / `sz399xxx` 为原始点位,`adjusted="none"`。复权数据源全部失败时说明数据缺失,不用未复权价格补算指标或信号。
80
87
  - 始终提供风险提示
81
88
  - 不做绝对化的涨跌预测
82
89
  - 建议用户结合自身风险偏好做决策
@@ -84,3 +91,24 @@ python3 scripts/gather.py <symbol>
84
91
  - 如果风险筛查返回 veto_buy=true,必须醒目标注并建议谨慎
85
92
 
86
93
  完成标准:每个买卖建议都对应可观察的触发条件和失效条件,且所有缺失数据及其影响已说明。
94
+
95
+ ## 低频价投数据
96
+
97
+ 按用户问题选择数据,完整说明口径、采样覆盖和缺失项:
98
+
99
+ - 判断估值贵贱:`get_valuation_history(symbol, years=5)` 的 PE-TTM/PB 历史正值分位与 Band;亏损 PE 不计算分位,实际采样不足五年必须说明。
100
+ - 读多年财报:`get_financials(symbol, periods=10, annual=true)`;A 股按年报筛选,港股按源实际可得年度数返回。财报期不等于公告日,年报历史不能用于假定当时已知信息的回测。
101
+ - 财报季排期:`get_earnings_calendar(report_date="YYYY-MM-DD", symbol=...)`,区分最新预约日期、实际披露日期和已公告业绩预告,不把预告当业绩实绩。
102
+ - 股东变化:`get_shareholder_structure`。A 股北向值是财报十大流通股东中的 HKSCC 名义持股,缺席不等于零,不能当成日度北向买卖;港股南向值按港交所披露日期使用。
103
+ - 大盘估值:`get_index_valuation(symbol="000300", years=5)`;中证近期 PE1 不冒充 PE-TTM、PB 或多年分位。
104
+ - ETF:`get_etf_details(symbol="510300", benchmark="sh000300")`。折溢价须看净值/行情日期;披露持仓不是完整实时申赎篮子,指数成分与基金持仓分别呈现。跟踪误差必须给出用户认可的基准。
105
+ - 股息:`get_dividends` 区分历史、未来已公布除息日历和 A 股报告期排行;预案不计入已实现 TTM 股息。名义每股现金未重算送转股口径,遇送转股时不得据此精确比较持有收益。
106
+ - 两融:`get_margin_trading(include_ratio=true)` 的 `margin_buy_ratio_pct` 只使用同日成交额;null 表示不可计算。
107
+
108
+ 慢变数据存于 `~/.stock-analysis/cache`:财报、基本信息及新历史数据按天,板块映射按周;行情仍实时查询。输出中的报告期/数据日期决定能否用于判断,缓存命中不代表数据已更新。
109
+
110
+ ### 补充数据覆盖
111
+
112
+ get_shareholder_structure 的 northbound 优先使用沪深官方季度总量;northbound_nominee 只是十大股东推断,不能混同。get_etf_details 的 basket 是完整已发布 PCF,对价数量/现金替代规则不是基金实际持仓或NAV权重。HK 股息排行使用 get_dividends(mode=ranking, market=HK),年度口径不能称 TTM。
113
+
114
+ 实际披露股票持仓可用 get_etf_details(include_full_holdings=true) 获取半年度/年度表;按 as_of 解释,数量为股、市值为人民币元。默认不取大量明细;不是实时全资产组合,不与 PCF 对价数量混同。
@@ -5,6 +5,8 @@ description: 全市场股票筛选:按市场、估值、成长、趋势或自
5
5
 
6
6
  # 全市场股票筛选
7
7
 
8
+ 显式筛选条件缺少数据时工具返回 `error`,不能把该条件当作已通过。`filters_applied` 只包含实际执行的条件,基于返回的覆盖情况说明候选范围。
9
+
8
10
  ## 执行流程
9
11
 
10
12
  ### 第一步:确定筛选条件
@@ -73,3 +75,21 @@ python3 tools/screener.py screen --market A --top 20
73
75
  - **成长型**:中等PE + 高营收增长 + 高换手率
74
76
  - **趋势型**:放量突破 + 均线多头 + 高量比
75
77
  - **低估反转**:超跌 + 低PB + 资金净流入
78
+
79
+ ## 股息因子(A股,可选)
80
+
81
+ 配置 `filters.dividend_yield_min` / `dividend_yield_max` 或 `sort_by: dividend_score` / `dividend_yield` 时才拉取股息数据。`dividend_report_date` 可指定报告期,默认上一年年末。这里使用已实施方案的**报告期股息率**(百分数),不是滚动十二个月股息率;缺失为未知,使用股息阈值时排除。启用后 value 分项加入股息横截面评分,未启用时不增加股息请求。
82
+
83
+ ```yaml
84
+ filters:
85
+ dividend_yield_min: 3
86
+ sort_by: dividend_score
87
+ sort_order: desc
88
+ dividend_report_date: "2025-12-31"
89
+ ```
90
+
91
+ 筛选结果仍需用 `get_dividends(mode="history", symbol=...)` 核查已实施现金分红、连续支付年数与除息时间,不能把高股息直接解释为低风险。
92
+
93
+ ### 补充数据覆盖
94
+
95
+ 股息筛选支持 A/HK:A 股为报告期已实施方案股息率,HK 为 HKEX/LSEG 年度股息率。两者都不是当前价 TTM;使用结果的 yield_basis 和 report_date,缺失不当零。
@@ -7,6 +7,8 @@ description: 策略回测:定义或读取 AlphaEvo YAML 策略,回测收益
7
7
 
8
8
  开始前读取[短线交易决策框架](../stock-analysis/references/short-term-trading.md)的风险单位和回测约束。回测用于反证策略,不把样本内收益包装成预测。
9
9
 
10
+ 解读回测时,`period` 是实际取得的数据期间,`requested_period` 保留用户请求,`warnings` 提示两者差异。年化收益按实际期间计算;覆盖不完整时明确说明,不能声称完成了完整请求期间的验证。买入预算包含佣金,`position.size` 为 0..1 的资金比例。
11
+
10
12
  ## 工作流程
11
13
 
12
14
  ### 第一步:策略定义
@@ -55,6 +57,8 @@ position:
55
57
 
56
58
  ### 第二步:运行回测
57
59
 
60
+ A 股股票/ETF 回测统一使用前复权 K 线(每条记录 `adjusted="qfq"`),显式指数使用原始点位(`adjusted="none"`)。复权源不可用时停止本次回测并说明缺失,不混用未复权历史价格。
61
+
58
62
  运行回测脚本:
59
63
 
60
64
  ```bash
@@ -75,6 +79,8 @@ python3 tools/backtest.py run <path.yaml> <symbol> --start <date> --end <date>
75
79
  - 使用用户指定的互斥日期区间分别运行样本内和样本外回测。
76
80
  - 成本假设引用结果中的 `costs` 字段(实际生效的佣金/滑点/印花税费率与实付费用合计),未模拟的费用与成交约束列入限制。
77
81
 
82
+ 趋势策略或用户要求肥尾收益诊断时,读取 [肥尾度量与趋势收益诊断](../bull-trend/references/fat-tails.md)的盈利集中度部分,基于平仓 `pnl` 计算大赢家贡献和删除敏感性。只有用户询问市场收益分布时才进入 κ 分支。
83
+
78
84
  未模拟的结算、涨跌停、复权或特定市场费用列入限制,结论限定为该模拟条件下的历史表现。
79
85
 
80
86
  ### 第四步:诊断
@@ -7,6 +7,8 @@ description: 智堡投研检索:查找机构研报、财报公告、电话会
7
7
 
8
8
  智堡 MCP 涵盖海外投行研报、国内券商研究、资管报告、央行/政府文献、电话会纪要和财报公告。首先检查这些 MCP 工具是否可用;不可用时直接改用 `search_comprehensive_intel`。
9
9
 
10
+ 港股估值功课调用 `get_valuation_history(symbol, years=10)`;配置 `LIXINGER_TOKEN` 时优先理杏仁非金融公司每日 PE-TTM/PB,失败回退百度。以返回的实际窗口和正值样本计算分位及 Band,不混接同一指标的不同来源,不将缺失解释为低估。
11
+
10
12
  ## 可用工具
11
13
 
12
14
  智堡 MCP 提供以下工具(通过 `mcp__wisburg-mcp-server__` 前缀调用):
@@ -7,11 +7,14 @@
7
7
  {% if risk_screening and risk_screening.veto_buy %}
8
8
  ⚠️ **一票否决** — 风险筛查触发,建议谨慎。
9
9
  {% endif %}
10
+ {% if risk_screening and (risk_screening.data_complete is sameas false or risk_screening.risk_level == 'unknown') %}
11
+ ⚠️ **数据不完整** — 当前风险筛查不能判定为低风险。
12
+ {% endif %}
10
13
 
11
14
  {% set dp = data_perspective or {} -%}
12
15
  {% set pp = dp.price_position or {} -%}
13
16
  {% set ts = dp.trend_status or {} -%}
14
- - 📈 **趋势:** {{ ts.ma_alignment or '-' }}{% if ts.is_bullish is not none %}({{ '看多' if ts.is_bullish else '看空' }}){% endif %}
17
+ - 📈 **趋势:** {{ ts.ma_alignment or '-' }}{% if ts.is_bullish is boolean %}({{ '看多' if ts.is_bullish else '看空' }}){% endif %}
15
18
  - 💰 **价位:** 现价 {{ m.fmt_num(pp.current_price) }} | 支撑 {{ m.fmt_num(pp.support_level) }} | 压力 {{ m.fmt_num(pp.resistance_level) }}
16
19
 
17
20
  {% set bp = battle_plan or {} -%}
@@ -26,12 +26,15 @@
26
26
  ## 风险筛查
27
27
 
28
28
  {% if risk_screening -%}
29
- - **风险等级:** {{ m.risk_emoji(risk_screening.risk_level) }} {{ risk_screening.risk_level or '-' }} | **风险分:** {{ risk_screening.risk_score }}/100
29
+ - **风险等级:** {{ m.risk_emoji(risk_screening.risk_level) }} {{ risk_screening.risk_level or '-' }} | **风险分:** {{ m.fmt_num(risk_screening.risk_score, 0) }}/100
30
+ {% if risk_screening.data_complete is sameas false or risk_screening.risk_level == 'unknown' -%}
31
+ - **数据不完整:** {{ risk_screening.warnings | join(';') }},当前结果不能判定为低风险。
32
+ {% endif %}
30
33
  {% if risk_screening.flags -%}
31
34
  - **风险标记:**
32
35
  {% for f in risk_screening.flags %} - [{{ f.severity }}] {{ f.category }}:{{ f.description }}
33
36
  {% endfor %}
34
- {%- else -%}
37
+ {%- elif risk_screening.data_complete is not sameas false and risk_screening.risk_level != 'unknown' -%}
35
38
  - **风险标记:** 无显著风险标记
36
39
  {%- endif %}
37
40
  {%- else -%}
@@ -45,7 +48,7 @@
45
48
  {% set pp = dp.price_position or {} -%}
46
49
  {% set vol = dp.volume_analysis or {} -%}
47
50
  {% set chip = dp.chip_structure or {} -%}
48
- - **趋势:** {{ ts.ma_alignment or '-' }}{% if ts.is_bullish is not none %}({{ '看多' if ts.is_bullish else '看空' }}){% endif %}{% if ts.trend_score is not none %} 趋势分 {{ m.fmt_num(ts.trend_score) }}{% endif %}
51
+ - **趋势:** {{ ts.ma_alignment or '-' }}{% if ts.is_bullish is boolean %}({{ '看多' if ts.is_bullish else '看空' }}){% endif %}{% if ts.trend_score is not none %} 趋势分 {{ m.fmt_num(ts.trend_score) }}{% endif %}
49
52
  - **价格结构:** 现价 {{ m.fmt_num(pp.current_price) }} | 偏离 MA5 {{ m.change_pct(pp.bias_ma5) }} | 支撑 {{ m.fmt_num(pp.support_level) }} | 压力 {{ m.fmt_num(pp.resistance_level) }}
50
53
  - **量价:** 量比 {{ m.fmt_num(vol.volume_ratio) }}{% if vol.volume_status %}({{ vol.volume_status }}){% endif %}{% if vol.turnover_rate is not none %} | 换手率 {{ m.change_pct(vol.turnover_rate) }}{% endif %}
51
54
  {% if chip and (chip.profit_ratio is not none or chip.avg_cost is not none) -%}