[//]: # (cross-linked bilingual sibling — English version: README.en.md)
仓瞰把你自己导出的基金持仓文件变成一份中文风险体检报告：确定性计算重仓集中度、重复持仓、隐性费率、风格漂移与最大回撤，再把每个数字翻译成白话。持仓数据不出本地，不荐股，不预测——只帮你看懂你已经买了什么。
Important
仓瞰不构成任何投资建议：它只解读已持有资产的风险指标，不做买卖、申赎或调仓推荐，不预测收益。
定投两三年后，多数人的支付宝里有十几只基金。账户绿了会点开看一眼，但没人回答得了这些问题：
- 这 12 只基金里，有几只重仓着同一批股票？（名字不一样，跌起来一模一样）
- 每年被管理费、托管费隐性吃掉多少收益？
- 我的组合到底是"大盘成长"还是"小盘价值"？
- 这套持仓在过去的行情里最大回撤是多少？
App 内置诊断只给一句黑盒评分——看不到口径、不能导出、更不会告诉你"费率太高"（代销平台没有动力劝你注意它赚钱的费率）。把持仓导出成 CSV 之后，没有任何工具能读它。仓瞰补的就是这一层：输入是你自己的持仓，输出是一份每个数字都能复算的体检报告。
# 安装（任选其一）
pipx install cangkan
# 或
uvx cangkan --help
# 1. 生成手动模板（零依赖路径：任何渠道的持仓都能手填）
cangkan template --out 持仓.csv
# 2. 填好『基金代码』和『份额』两列（示例见 docs/sample_portfolio.csv）
# 3. 体检
cangkan check --file 持仓.csv跑完你会看到：持仓清单与基础统计，外加四张确定性指标表 —— 重仓重叠（哪几只基金重仓同一批股票）、组合集中度、隐性费率合计（年化吃掉多少）、回撤波动（最大回撤 / 年化波动率 / 与沪深300 相关系数）。
公开基金数据（净值、季报重仓股、运作费率、沪深300 指数）经 akshare 拉取并在本地缓存 24 小时；你的持仓明细永远不离开本机。任何一项取数失败都会在对应表里明示"数据不足"，不会用行业均值补齐。
该录屏录制于 v0.1.0（当时只交付 m1：清单与基础统计）。v0.2.0 起的四张指标表见下方"能力与边界"。
录制日的完整输入输出与版本记录见 docs/demo-results.json。
你的持仓 CSV ──► 导入器（模板/支付宝，只读文件，无平台自动化）
│
▼
数据层（akshare · 本地缓存 · 失败明示跳过）
│
▼
指标层（纯函数：重叠/费率/风格/回撤，可单测可复算）
│
▼
报告层（Markdown 体检报告 + 免责声明）
└─► 解读层（国产大模型，只引用已算出的数字，禁止建议语气）
cangkan template --out 持仓.csv 生成手动持仓模板
cangkan check --file 持仓.csv 体检：清单 + 基础统计 + 四张风险指标表
cangkan --version 查看版本
导入器自动识别两种表头：手动模板（基金代码,份额，中英文列名皆可）与支付宝导出（尽力解析 基金代码/持有份额 等已知列名；官方格式若变化会明确提示转用模板，绝不猜数据）。支付宝导出里的「持有金额」是市值、不是买入成本，所以只取代码与份额。
取数失败的基金会明示跳过并标注原因，不会静默计入统计；--report / --explain 属 m3 里程碑，尚未实现，请求它们会以退出码 3 明确失败（不会假装生成了一份报告）。
| 能力（v0.2） | 状态 | 说明 |
|---|---|---|
| 持仓导入（模板/支付宝） | ✅ | 只读用户手动导出的文件 |
| 持仓清单 + 基础统计 | ✅ | 只数、取数状态、估算市值 |
| 公开数据本地缓存 | ✅ | SQLite，24h TTL，有界重试（最坏 1.5s/次调用） |
| 重仓重叠 + 组合集中度 | ✅ | 季报前十大重仓股 Jaccard + 按市值加权的个股合计占比 |
| 隐性费率合计 | ✅ | 管理费+托管费+销售服务费，按市值加权年化（来源：天天基金运作费用） |
| 风格透视 | 四象限口径已实现；个股快照接口不可达时明示"数据不足"，不猜市值/估值 | |
| 回撤波动 | ✅ | 组合合成净值的最大回撤、年化波动率、与沪深300 相关系数 |
| 白话解读 + Markdown 报告 | 🚧 m3 | 接口契约已就位（cangkan/llm/、report/） |
| 买卖/调仓建议 | ❌ 永远不做 | 产品红线 |
| 平台账号登录/自动抓取 | ❌ 永远不做 | 只读手动导出的文件 |
风格透视的口径（公开在代码与单测里）：总市值 ≥ 500 亿元为大盘、否则小盘；动态市盈率 ≥ 30 为成长、0 < 市盈率 < 30 为价值；市盈率缺失或为负（亏损股）记入"未分类"——既不猜市值也不猜风格。它依赖 akshare 的全市场快照接口，该接口在受限网络下可能不可达，此时本表会明示"数据不足"而不是给一个编出来的比例。
CLI 与本地 Markdown 报告永久免费开源。规划中的付费面是 v0.3 的精排 PDF 体检报告（深度排版 + 历史对比页，按份 ¥9.9），开源功能不会收费——先看大家是否真需要可打印的精排版，再动手做支付页。
- v0.1：持仓导入 + 清单与基础统计 + 本地缓存
- v0.2（当前）：m2 四大确定性指标引擎（重仓重叠 / 费率合计 / 风格透视 / 回撤波动）直接渲染在终端
- v0.3：m3 白话解读层 + Markdown 体检报告 + 精排 PDF（付费）
- v0.4+：历史对比（"上季度 vs 本季度"）、渠道合并盘点
这算投资建议吗？ 不算，也不打算算。仓瞰只解读已持有资产的风险指标，所有指标口径公开在代码与测试里，报告页脚带免责声明。
我的持仓数据安全吗？ CSV 在你本地解析、指标在本地计算；只有公开的净值/季报重仓股/费率/指数数据经 akshare 拉取并缓存。可选的解读层调用你自己配置的模型 API key，不经过任何第三方服务器。
为什么费率表里有的基金显示"未取到"？ 因为运作费率确实没取到。仓瞰不会用行业均值替它补齐——那会把"不知道"变成"看起来很低"，低估你的真实成本。合计只在费率已知的市值上加权，标题里会写明覆盖了多少市值。
和 App 内置诊断有什么区别？ 口径透明（每张表怎么算的都能查）、可导出、可跨渠道合并——以及没有"劝你少交费率"的利益冲突。
git clone https://github.com/SuperMarioYL/cangkan && cd cangkan
pip install -e . pytest
python -m pytest -q # 48 项离线单测，不依赖网络MIT © 2026 SuperMarioYL