持仓结构自查（A 股）
这个技能做什么、不做什么
- 做：把用户自己的持仓文件变成一份仓位结构报告——钱压在几只票上（CR1/CR3、HHI、有效持仓数）、最大一只有没有超过用户自己定的上限、仓位在沪主板/深主板/创业板/科创板/北交所/ETF 之间怎么分、浮亏的票合计占多大份量、现金还剩多少比例；结尾只给一个关于仓位结构的下一步动作。
- 不做：不联网，不取任何外部数据；不评价任何一只股票的好坏，不预测涨跌，不给买入、卖出、换股建议，不提供股价数据。用户问「XX 能不能买」「该卖哪只」时，明确说这不在本技能范围内，把话题拉回「按你自己定的规则，现在的结构是什么样」。
- 所有数字都来自用户上传的持仓文件与用户自己写的规则（
rules.json）。持仓文件里的「最新价/市值」就是券商导出那一刻的数，技能不去更新它。
使用流程
- 拿到持仓文件：请用户在券商 App/PC 端的「持仓」或「股票资产」页面导出文件（CSV 或 xlsx）。东方财富、同花顺、通达信系、华泰、中信、国泰君安、平安等常见格式的列名会自动识别（对照表见
references/broker-columns.md）。
- 至少要有「证券代码」+「持仓数量」（或「市值」）两列；有「成本价」「最新价/市价」「市值」「浮动盈亏」越多越准。
- 识别不了时脚本会打印第一行表头并退出：把表头给用户看，请用户指认哪一列是代码、哪一列是数量，别猜。
- xlsx 需要本机装了openpyxl；没有的话请用户在 Excel/WPS 里「另存为 CSV」再来。老式.xls同样请另存。 - 规则文件（可选，但建议第一次就写）：问用户这几件事，写成
rules.json（模板assets/rules.example.json）：
- 账户总资产（元）——给了才算现金比例、占总资产比例；也可以用参数--total-assets临时给。有的券商导出在表头上方写了「总资产」，脚本会自动读取并在报告里注明来源。
- 单票占比上限max_single_pct（默认 0.30）、前三只合计上限max_top3_pct（默认 0.70）
- 各板块占比上限board_limits（例如创业板 ≤ 25%）、现金比例下限min_cash_pct
用户没回答的项用默认值，报告里会写明「以下规则用的是模板默认值」。 - 跑自查：
python {baseDir}/scripts/check.py --positions <持仓文件> --rules <rules.json> --out report.md
没有规则文件时去掉 --rules；只想临时给总资产：
python {baseDir}/scripts/check.py --positions <持仓文件> --total-assets 500000 --out report.md
输出 Markdown 报告 report.md 与同名 report.json（结构化数据，含 checks 规则对照与 next_action）。把报告原样展示给用户，再用一两句话说最突出的那一条结构问题。
4. 样例试跑：用户想先看看效果时，用自带样例：
python {baseDir}/scripts/check.py --positions {baseDir}/assets/sample_positions.csv --rules {baseDir}/assets/rules.example.json --out report.md
- 定期复查：用户每次调仓后重新导出持仓、重跑第 3 步，对比有效持仓数、最大一只占比、现金比例的变化。
报告怎么说话
- 先一句总览：几只持仓、最大一只占多少、前三只占多少、有效持仓数、现金比例、对照规则有几条超线。
- 超线用「你的规则说 X，现在是 Y」的格式，带代码、名称、百分比和超出的金额，不加形容词，不说「危险」「太重」这类判断。
- 对任何一只股票只说它在你仓位里的份量和你自己的成本对比（占比、浮盈浮亏），不说它好不好、贵不贵、会不会涨。
- 结尾只给一个下一步动作，只谈仓位结构，例如「最大一只占 45%，超过你自己定的 30%」。不列清单，不说买什么、卖什么。
- 报告末尾保留免责声明：以上只是你自己持仓文件的结构统计，不评价任何股票，不构成投资建议。
指标定义（脚本实现，见 scripts/check.py）
| 指标 | 算法 | 需要 |
|---|---|---|
| 市值 | 优先用文件里的「市值」列；没有就 数量×最新价；再没有就 数量×成本价（报告注明） | 持仓文件 |
| 占持仓 | 单只市值 ÷ 股票市值合计 | 持仓文件 |
| 规则口径占比 | 给了总资产用「占总资产」，否则用「占股票市值合计」，报告的「口径」列写明 | 持仓文件 + 规则 |
| CR1 / CR3 | 最大一只 / 前三只合计的占持仓比例 | 持仓文件 |
| HHI | 各只占比平方和，×10000 展示（满分 10000 = 全仓一只） | 持仓文件 |
| 有效持仓数 | 1 ÷ HHI，相当于「平均分到几只」 | 持仓文件 |
| 板块 | 只按代码前缀：600/601/603/605 沪主板；000–003 深主板；300/301 创业板；688/689 科创板；43/83/87/88/920 北交所；51/52/56/58/15/16/18/50 ETF/基金 | 持仓文件 |
| 浮盈浮亏 | 优先 (最新价 − 成本价) × 数量；没有则用文件「盈亏」列；比例按成本算 | 持仓文件 |
| 浮亏分布 | 浮亏票只数与合计占比、浮亏金额最大与比例最大的一只、6 档盈亏区间占比 | 持仓文件 |
| 现金比例 | (总资产 − 股票市值) ÷ 总资产 | 持仓文件 + 总资产 |
规则对照：max_single_pct、max_top3_pct（持仓 ≥ 3 只时）、board_limits 各项、min_cash_pct、max_losing_weight（可选）。都没超线时，下一步动作指出最接近上限的那一条（达到上限 80% 以上时），否则提示调仓后再跑。
边界
- 零联网：脚本只用 Python 标准库（读 xlsx 时用 openpyxl），不发任何网络请求，不读取文件以外的数据。持仓文件里的价格是多久以前的，报告就反映多久以前的结构。
- 只统计 A 股沪深北（含 ETF、LOF）；「交易市场」列标明港股通的行会跳过；可转债、逆回购等按代码归到「债券/逆回购」单列，不混进股票板块。跳过的行在报告「数据说明」里逐条列出原因（合计行、已清仓、港股通、代码不合法等）。
- 代码被 Excel 当成数字吃掉前导零（如
858、1.0、="000333"、600519.SH）会自动还原成 6 位并在报告注明条数。 - 同一代码在多个股东账户各有一行时自动合并。
- 总资产小于股票市值（融资买入或数字没更新）时不算现金比例，报告里说明原因。
- 板块只按代码前缀划分，不做行业分类，不判断 ST 或任何公司属性。
- 文件编码依次尝试 utf-8-sig、gbk、gb18030、utf-16；逗号、制表符、分号分隔都可以。
