Stock CYQ Analyzer Pro · A股筹码分布增强分析引擎
把 A 股交易者最在意的「筹码视角」做成可复用、可批处理、可审计的 Agent 级特征引擎——轻、透、不忽悠。本版（v2.0.0）在 @user_b806c584/stock-cyq-analyzer v1.1.0 核心框架上做功能增强，不改变「只产出特征、不代替买卖决策」的定位。
一、核心能力（继承自 v1.1.0）
- 算法透明可复现：典型价
(O+H+L+C)/4；分布假设三角分布（低/高/典型价为参数）；历史衰减按换手率线性衰减(1 - turnover)，越近交易权重越大；价格步长 0.1 元，默认回溯约 180 个交易日。 - 输出可落地指标（非漂亮话）：获利盘比例、平均成本、筹码峰值、90% 筹码集中度、主力成本区、图表路径。
- 零数据成本：akshare 免费行情 + 本地缓存，无需 API Key。
- Agent 原生：自然语言说「看下某某筹码结构」即触发，脚本自动执行，结果结构化。
二、增强点（v2.0.0 vs v1.1.0）
| 维度 | v1.1.0 | v2.0.0 增强 |
|---|---|---|
| 分布模型 | 仅三角分布 | 三角分布（默认，保兼容）+ 高斯 KDE（成交量加权，可选） |
| 数据源 | 仅 akshare（单点风险） | akshare → baostock → eastmoney 多源 fallback + SQLite 持久化 + 源健康探测 |
| 参数 | 写死（180天/0.1步长/三角） | CLI 全参数 + config.yaml 预设（短线/长线/主力追踪）+ 插件接口 |
| 修正层 | 无 | 插件化修正层（大宗交易/龙虎榜/股东人数，默认关闭，标注【待核实】）+ 对倒/锁仓启发式降噪 |
| 鲁棒性 | 缺失败分支 | 显式 if-then 失败模式表 + 🔴 检查点 + 数据校验层 |
| 合规 | 非结构化 | 补齐 frontmatter 触发词、反例黑名单、runtime 中立 |
三、触发场景
- 用户问「某只股票的筹码结构 / 获利盘 / 套牢盘 / 平均成本 / 主力成本区」
- 用户说「分析 600519 的筹码分布」「帮我看下 XX 的 CYQ」
- 批量筛票：「按 90% 集中度 + 主力成本区给池子排序」
- 写研报：「附平均成本 / 筹码峰值作为技术面佐证」
- 量化特征工程：「把 CYQ 分布喂给我的选股/策略脚本」
四、工作流（线性、每步明确输入→输出）
> 执行前先确认 cyq_analyzer.py 与依赖可用（见第十三节）。所有路径用正斜杠。
- 解析请求 — 输入：用户自然语言。输出：标的代码
code、模式（auto/短线/长线/主力）、分布模型、输出路径。 - 加载配置 — 输入：
config.yaml（可选）。输出：生效参数（lookback / price_step / decay / distribution / sources）。 - 取数 + 缓存 — 输入：
code、日期区间。输出：OHLCV DataFrame（含换手率）。
- 先查 SQLite 本地库；缺失/过期则按sources顺序联网拉取并回写。 - 数据校验 🔴 — 输入：OHLCV。输出：通过 / 中止。见第八节失败模式。
- 选择分布模型 — 输入：参数。输出：三角或 KDE 的筹码分布数组。
- （可选）修正层 — 输入：大宗/龙虎榜/股东人数（若开启）。输出：叠加修正权重，标注【待核实】。
- 计算指标 — 输入：分布数组 + 现价。输出：JSON 指标（见第十节）。
- 绘图 — 输入：分布数组。输出：PNG 路径（matplotlib 可用时）或 ASCII 直方图（降级）。
- 返回 — 输出：标准 JSON + 图表路径，由 Agent 整合成自然语言回复。
五、🔴 检查点（强制，不得跳过）
- 🔴 CP-1 数据质量：若标的最新交易日距今天数 > 5 个交易日，或任意日
volume<=0/close缺失，暂停并提示「数据可能不齐，是否继续？」，不得静默计算。 - 🔴 CP-2 停牌/退市：若
volume连续 20 日 = 0，判定疑似停牌，中止并说明，不强行出数。 - 🔴 CP-3 决策边界：若用户要求「该买还是该卖 / 给个买卖点」，必须明确拒绝并回指「本工具只产出特征，不构成投资建议」，不得生成买卖结论。
- 🔴 CP-4 修正层开启确认：首次开启大宗/龙虎榜修正层时，提示「修正因子为估算、标注【待核实】，仅供研究」，确认后再纳入。
六、失败模式编码（if-then，dim3）
| 触发条件 | 一线修复 | 仍失败兜底 |
|---|---|---|
| 主数据源 akshare 拉取异常/超时 | 按 sources 切下一个源（baostock→eastmoney） |
全部失败 → 报错 DataSourceError，提示检查网络/代理，不返回空结果 |
| 缺换手率字段 | 用「当日成交量 / 近 60 日均量」估算并标注【待核实】 | 仍无 → 降级为常量衰减 decay=0.03 并标注【待核实】 |
| 复权数据异常（价格断层） | 改用后复权重新拉取 | 仍异常 → 中止并提示「复权质量存疑，请人工核对」 |
| SQLite 写入失败 | 降级为仅内存计算，跳过缓存 | 内存计算成功仍返回结果，日志记 cache=skip |
| matplotlib 不可用 | 输出 ASCII 直方图写入 JSON 的 ascii_hist 字段 |
不影响数值指标返回 |
| 标的不存在/代码错误 | 校验代码格式（6 位数字），提示用户核对 | 终止并报 InvalidCode |
七、参数与预设（config.yaml，dim5）
default:
lookback: 180 # 回溯交易日
price_step: 0.1 # 价格步长(元)
decay_model: turnover # turnover(按换手率) | constant
decay_factor: 0.03 # 仅 constant 模式生效
distribution: triangular # triangular | kde
kde_bandwidth: 0.3 # 仅 kde 模式；支持 auto(Scott) / silverman 自适应带宽
sources: [akshare, baostock] # eastmoney 可作为自定义源扩展
cache_db: .stock_cache/cyq.db
presets:
short_term: { lookback: 60, decay_factor: 0.03, distribution: kde } # 短线：衰减放缓(0.03)更"长记忆"
long_term: { lookback: 250, decay_factor: 0.02, distribution: triangular }
main_force: { lookback: 120, distribution: kde, corrections: [block_trade, dragon_tiger] }
kde_bandwidth三种取值：数值(固定,如 0.3) /auto(Scott's rule: std·n^(-1/5)) /silverman(Silverman's rule: 0.9·min(std,IQR/1.349)·n^(-1/5))。自适应带宽让 KDE 随样本量/波动自动调整平滑度，无需手调。short_term预设的decay_factor由 0.05 调低至 0.03，衰减更慢，避免对短线博弈"过于健忘"；该预设默认继承全局decay_model: turnover（换手率驱动）。
CLI 覆盖示例：
python cyq_analyzer.py --code 600519 --preset long_term --distribution kde --kde_bandwidth auto --output out.json
八、输出格式（JSON Schema）
{
"code": "600519",
"date": "2026-10-23",
"current_price": 1500.00,
"metrics": {
"profit_ratio": 0.62, // 现价以下筹码占比
"average_cost": 1480.35, // 平均成本
"chip_peak": 1450.00, // 最密集价位
"concentration_90": 0.18, // 90%筹码集中度(区间宽度/中值)
"concentration_90_range": [1390.00, 1560.00],
"main_force_zone": [1430.00, 1500.00], // 最密20%区间
"locked_ratio": 0.05 // 锁仓/大宗标记占比(仅开启修正层时)
},
"distribution": {"1450.0": 0.012, ...}, // 价:权重(可省，量大时)
"chart_path": "out.png",
"ascii_hist": "...", // matplotlib不可用时
"data_source": "akshare",
"data_freshness": "2026-10-23", // 数据覆盖的最新交易日(Agent据此判断时效性)
"cache_age_minutes": 15, // 仅本地缓存命中时有值；csv/在线取数为 null
"warnings": ["decay=constant【待核实】"]
}
九、反例黑名单（dim9 · 不要做什么）
- ❌ 不要直接给买卖点：本工具只产出特征，任何「该买/该卖/目标价」均属越界，必须拒绝（见 CP-3）。
- ❌ 不要对停牌/退市股强行计算：触发 CP-2 即中止。
- ❌ 不要伪造换手率：缺失时只能估算并标注【待核实】，不得编造为真实值。
- ❌ 不要绕过失败模式静默返回：任一数据源失败必须走第六节 fallback，不得返回空/假数据。
- ❌ 不要宣称还原真实持仓：筹码分布是基于历史量价的估算模型，非交易所级透视；对倒/锁仓/大宗仅能修正、不能穿透。
- ❌ 不要把修正层结论当事实：大宗/龙虎榜/股东人数修正因子默认关闭，开启即标【待核实】。
十、边界与免责（继承并强化）
- 基于历史量价的估算模型，不是真实持仓透视；只能辅助判断支撑/压力与成本结构，不能单独作为买卖依据，不构成投资建议。
- 对停牌、复权、大宗转让、对倒等场景还原有限；三角分布为近似，与通达信/同花顺原生 CYQ 有细微差异。
- KDE 与修正层进一步提升还原度，但仍是估算；标注【待核实】的字段仅供研究参考。
十一、插件化修正层（高阶，默认关闭）
修正层为 cyq_corrections/ 包（目录形态，便于扩展）：
- cyq_corrections/__init__.py：内置 block_trade（大宗交易锁定期慢衰减）、dragon_tiger（龙虎榜均价高置信锚点）、shareholder_count（股东人数变化调节集中度速度）三个插件，均为估算、标注【待核实】。
- cyq_corrections/example_block_trade.py：最小可用示例范本。从本地 CSV（block_trades.csv，可用 EXAMPLE_BLOCK_TRADE_CSV 环境变量改路径；列：date,code,price,volume,discount_rate）读取大宗记录，在对应价格 bin 叠加"锁定期慢衰减权重"并标记成本区间，无任何外部接口依赖，供用户照此改写自定义修正层。
- 自定义扩展：在 cyq_corrections/ 下新增 *.py 实现同签名函数 (code, centers, dist) -> (dist, warnings)，并在 cyq_analyzer.py 的 apply_corrections 中注册名称即可通过 --corrections <name> 调用。
启用示例：
python cyq_analyzer.py --code 600519 --corrections example_block_trade
十二、Runtime 中立说明
本 skill 为纯 Python 脚本（cyq_analyzer.py）+ 标准 YAML 配置，不依赖任何单一 Agent 运行时。可在 Claude Code、Codex、Cursor、OpenClaw、Hermes、Gemini CLI、OpenCode 等任意 skills-compatible runtime 中使用。无「在 Claude Code 里」等单运行时措辞。
十三、依赖与安装
pip install -r requirements.txt # numpy/pandas 可选加速；akshare/baostock 取数；matplotlib 绘图；pyyaml 读配置
- 核心计算为纯 Python 实现，无 numpy 亦可运行（KDE 自动降级为纯 Python 高斯平滑）。
- 离线可用：提供
--from-csv path.csv直接读本地 OHLCV（列：date,open,high,low,close,volume,turnover）。 - 不替代模型下买卖结论，只产出特征。
