AlphaDesk — Analisador de Portfólio de Investimentos
tom7523326/alphadesk-skill
Relatório diário institucional de portfólio com recomendações executáveis
Ver no GitHubMCP server que transforma screenshots de corretora, CSV ou feed MCP em relatório institucional de 9 seções com análise de regime, risk dashboard e recomendações P0/P1/P2 específicas em quantidade de ações. Inclui rastreabilidade completa via git, devil's advocate review e performance log para backtesting de decisões.
Instalação
npx convez-ai tom7523326/alphadesk-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Análise diária de portfólio com detecção de regime shifts
- Rebalanceamento de posições com recomendações específicas em quantidade
- Monitoramento de risco (concentração, alavancagem, stop-loss)
- Rastreamento de performance de recomendações anteriores
- Integração com múltiplas fontes de dados (screenshot, CSV, MCP de corretoras)
Veredito

Ferramenta robusta e bem arquitetada para investidores técnicos que precisam de análise estruturada e rastreável de portfólio. Exige disciplina do usuário (aceitar recomendações, logar decisões) mas oferece transparência total e capacidade de aprender com histórico de decisões. Recomendado para portfolios acima de 100k USD com múltiplos ativos.
README
A tradução para o português deste README ainda está na fila.
AlphaDesk — 使用说明
一句话:把你的持仓截图(或 CSV / 券商 MCP)交给 Claude,它给你一份 9 章节的专业日报 + 具体到股数的决策建议,过程透明、可追溯、可回退。
目录
1. 它能做什么
核心场景:你早上打开手机,看到富途/雪球/老虎/IB账户红了 8%,想知道——
- 这 8% 是 regime 切换还是个股事件?
- 重仓股还该拿吗?要减半吗?减多少?哪天减?
- 风控指标(集中度 / 杠杆 / 止损线)有没有触发?
- 别人(机构 / smart money)在干什么?
- 反方观点:我现在的决策有什么盲区?
把账户截图发给 Claude,说"今日日报",它给你:
▍0 算法准确率回顾 昨天那条 P0 建议执行了吗?对了还是错了?
▍1 Executive Summary 3 句话核心
▍2 Regime + 宏观 HSI/SPY/板块温度
▍3 持仓快照 每个标的 qty / 成本 / 浮亏 / 今日 ∆%
▍4 重仓股深度研究 至少 1 只重仓股 5 层研究
▍5 推荐标的研究 如果有买入信号
▍6 Smart Money 机构净流 vs 散户净流
▍7 风控仪表盘 集中度 / 杠杆 / 风险等级
▍8 P0 / P1 / P2 具体到股数的执行建议
▍9 事件日历 + 反向推演 接下来 1 周事件 + Devil's Advocate
它不做:
- 自动下单(决策永远在你手上,Claude 最多生成委托模板)
- 量化策略回测(用 vectorbt / backtrader)
- 单股深度尽调(用专门的 research skill)
2. 系统要求
必需
- Claude Code 客户端(本 skill 是 Claude 加载的,不是独立 app)
- Python 3.10+(只跑几个工具,不需要任何重型依赖)
- git(用来打 baseline tag,任何决策可回退)
- 磁盘 < 100MB(整个 skill + 一年报告 < 50MB)
可选(根据你的数据源)
- 券商 MCP(如 FUTU OpenD)— 想让 Claude 自动拉持仓时
- CSV 导出(雪球 / IBKR Flex / Robinhood Statement)— 反复用同一份数据时
- 截图— 最简单,任何券商 app 都行
Python 包
pip install jsonschema # 仅 report_gate.py 需要
就这一个。其他工具是纯标准库。
3. 5 分钟快速开始
Step 1 — 建项目目录
export ALPHADESK_ROOT="$HOME/Desktop/my-portfolio"
mkdir -p "$ALPHADESK_ROOT" && cd "$ALPHADESK_ROOT"
把这一行加到 ~/.zshrc / ~/.bashrc,以后每个 shell 都能用。
Step 2 — 复制 skill 文件
SKILL=~/Desktop/alphadesk-skill # 你解压 skill 的位置
cp -r $SKILL/templates/basic/* "$ALPHADESK_ROOT/"
cp -r $SKILL/tools "$ALPHADESK_ROOT/"
这给你最小可用版本:
my-portfolio/
├── tools/ sstate / report_gate / evidence_log / append_log
├── data/
│ ├── book_authority.json 单账户默认配置(无需修改)
│ └── report_payload.schema.json
├── CLAUDE.md Claude 每次自动读取的项目记忆
└── .gitignore
Step 3 — git baseline
git init -b main
git add -A && git commit -m "baseline: AlphaDesk installed"
git tag baseline
任何时候想回到原点:git reset --hard baseline。
Step 4 — 喂数据(选一种)
方案 A:截图(最简单)
把券商 app 的持仓页截图存到目录:
my-portfolio/screenshot-20260528.png
方案 B:CSV 导出
存为 personal-holdings.csv,至少包含这几列:
code,name,qty,avg_cost,market_value,currency
HK.01810,小米,5000,12.30,82500,HKD
US.NIO,蔚来,200,8.50,1320,USD
方案 C:券商 MCP
参考 docs/data-sources.md。一次性配置,以后 Claude 自动拉。
Step 5 — 让 Claude 跑日报
打开 Claude,说:
今日日报
或
[贴截图] 帮我分析一下今天的持仓
Claude 会:
- 读
CLAUDE.md(项目记忆) - 跑
tools/sstate.py show(看上次做到哪) - 读你的数据源(screenshot OCR / CSV / MCP)
- 构造 9 章节 payload
- 跑
tools/report_gate.py校验 - 渲染 HTML →
daily-reports/2026-MM/daily_*.html tools/append_log.py追加到performance_log.jsontools/sstate.py log记一笔
你只需要等 1-15 分钟(取决于模式)。
4. 日常使用流程
每日早晨(2 分钟)
你:晨报
Claude:[Quick mode,~10 工具调用,生成 morning HTML]
主要看:
- 隔夜美股 + 早盘亚太
- 重仓股有无 5%+ 异动
- P0 触发列表
每日收盘(5 分钟)
你:今日日报
Claude:[Standard mode,~25 工具调用,生成 evening HTML]
主要看:
- §3 持仓快照(今日 ∆%)
- §7 风控仪表盘(集中度 / 杠杆 / 止损线触发)
- §8 P0/P1/P2 决策(明天必须 24h 内执行 OR 取消)
- §9 反向推演(devil's advocate 是否有有效论点)
周末复盘(10 分钟)
你:本周复盘 + evidence log 更新
Claude:[读 5 天报告 → 提交 evidence_log 一行]
每周日跑一次 python3 tools/evidence_log.py append,4 周后看 python3 tools/evidence_log.py status 决定是否启动 SKILL 简化。
财报季 / 重大事件(15 分钟)
你:小米财报深度
Claude:[Deep mode,~40 工具调用,5 层研究]
会拉 Morningstar / smart money / 13F / 期权链 / 行业对比(如果接了 MCP)。
5. 报告章节详解
§0 算法准确率回顾
读昨天 P0 建议 → 今天实际走势 → 命中?
- 命中率 ≥60% 才算这套框架在工作
- 命中率 <40% 持续 2 周 = warn,SKILL 该改
§1 Executive Summary
3 句话:今日 regime / 重仓最大变化 / 必须做的 1 件事。
§2 Regime + 宏观仪表盘
- HSI / SPY / 纳指今日 + 5 日
- 板块温度(电车 / 互联网 / 半导体 / 新消费)
- 重要宏观:LPR / FOMC / CPI 待发
§3 持仓快照
| 排名 | Ticker | 名称 | qty | 成本 | 现价 | 浮亏 | 今日 ∆% | 集中度 |
| 1 | 01810 | 小米 | 5000 | 12.30 | 11.20 | -8.9% | -1.55% | 18.4% |
红线:每行的 qty 必须来自单一权威源(screenshot OCR / CSV / MCP),不许混合不同时间的数据。
§4 重仓股深度研究
5 层:基本面 / 技术面 / 资金面 / 情绪面 / 催化剂。 Standard 模式至少做 1 只(集中度最高的);Deep 模式做 3 只。
§5 推荐标的研究
只在有买入信号时才出现。没有就跳过 — 不许为了"完整"硬凑。
§6 Smart Money + 资金流
- 主力净流 vs 散户净流(MCP 提供)
- 异动量(均量 ×N)
- 北向资金(港股)/ ETF 申赎(美股)
§7 风控仪表盘
┌─ 总组合 ───────────────────┐
│ 总市值: HKD 5,614,398 │
│ 累计浮亏: -23.31% │
│ Top1 集中度: 18.4% │
│ Effective N: 4.2 │
│ 杠杆: 1.42x │
│ 风险等级: LEVEL 5 🟡 │
└───────────────────────────┘
§8 P0 / P1 / P2 执行策略
P0 🔴 (必须 24h 内做)
- HK.03690 美团 减半 3,274 → 1,637
理由: 集中度 22% > 风控上限 18%,催化失效
执行: 限价 132.0,数量 1,637(委托模板见下)
截止: 2026-05-29 16:00
P1 🟡 (本周内)
- HK.01810 小米 加仓评估,等 6/15 财报
P2 🟢 (持续监控)
- 美元指数突破 105 时检视 NIO 仓位
24h 闭环规则:
- 执行 →
tools/sstate.py log "P0 美团已执行 sold 1637 @ 132.5" - 取消 →
tools/sstate.py log "P0 美团 cancelled 因为消息变化" - 超时 → 次日报告 banner 标红,计入
evidence_log.csv的p0_missed
§9 事件日历 + Devil's Advocate
- 接下来 1 周 catalysts(财报 / 宏观 / 监管事件)
- Devil's Advocate — 必须列出当前主要决策的反面论点,即使你不同意。这是从私有版 6 个 P0 / 0 执行的失败里学到的:看不到反方就 = 看不到风险。
6. 三种模式怎么选
| 你想 | 用 | Claude 怎么知道 |
|---|---|---|
| 早上扫一眼 | Quick | 你说 "晨报" / "快速日报" / "给我看看" |
| 每天收盘正经看 | Standard | 你说 "今日日报" / "详细日报" / "收盘日报",或不指定 |
| 财报 / 月度 / 重大事件 | Deep | 你说 "深度日报" / "重仓深度" / "财报季" / "月度复盘" |
每种模式 token 预算不同(详见 docs/workflow.md),Claude 自动决定调用哪些工具。
7. 使用注意事项
7.1 数据真实性
- 截图必须是当日的(不是上周的!)。Claude 没法判断截图日期,建议每张截图加日期前缀:
screenshot-20260528.png - CSV 数据不要手改。如果你改了 qty 或成本,日报会和你下次刷新时的实际数据漂移
- 接 MCP 的话,确保 OpenD / brokerage gateway 在跑
7.2 P0 闭环必须做
P0 不做闭环 = 这套框架报废。24h 内:
- 真做了:
sstate.py log "P0-XXX done" - 不做了:
sstate.py log "P0-XXX cancelled" - 超时未做未取消:次日 banner 标红 + 计入
evidence_log的p0_missed
私有版的失败:8 天里 6 个 P0 / 0 执行,框架变成"持续监控"废纸。不要重复。
7.3 git tag 保命
每次重大 SKILL 改动前打 tag:
git tag pre-experiment-$(date +%Y%m%d)
后悔了:
git reset --hard pre-experiment-20260528
7.4 不要急着改 SKILL
如果你刚装好就觉得"我要加 X / 删 Y",等 4 周后再说。看 evidence_log.csv 有没有数据支撑,没有就别动。这是 docs/governance.md 的核心 — 防治理冲动膨胀。
7.5 隐私
personal-holdings.csv/screenshot*.png/performance_log.json默认在.gitignore里- 不要把这个 portfolio 项目 push 到 public repo
- skill 本身可以分享(已脱敏),数据目录不行
7.6 Claude 不会自动下单
它最多给你委托模板:
broker: FUTU HK
code: HK.03690
direction: sell
qty: 1637
price: 132.0 (limit)
你 copy 到券商 app 自己下单。即便接了 MCP,真实下单也需要你显式确认。模拟盘下单 (place_sim_order) 可以自动跑。
8. 常见问题
Q1:我没有 CSV,只有截图,Claude 真能看懂?
能。Claude 直接看截图(多模态),从中识别 ticker / qty / cost。但手动 verify 第一次:让 Claude 输出它读到的 positions list,你对一遍,有错改正后再让它存到 personal-holdings.csv。下次就有结构化数据了。
Q2:接了富途 MCP 之后,持仓是实时的吗?
是。mcp__futu__consolidated_view 拿的是实时 positions。但价格通常是延时 15 分钟(免费行情),如需 LV2 实时报价需要券商订阅。
Q3:报告 HTML 怎么看?
open daily-reports/2026-05/daily_20260528_evening.html
或者拖到浏览器。不要用 Office / VSCode 看,排版会乱。
Q4:report_gate 校验失败怎么办?
它会告诉你哪个字段错了:
REPORT_GATE_FAILED: 1 issue(s)
✗ metrics[3] 'concentration' missing 'book' field
按提示修 payload 重跑。不要绕过 gate。
Q5:performance_log.json 怎么用?
它是黑匣子:每份通过 gate 的报告都自动 append 一条 entry。命中率统计 / Phase A 进度 / 长期复盘都从这里来。不要手动改它,改了就漂移了。
Q6:我不想要 evidence_log 这套,可以吗?
可以,工具是 optional 的。但强烈建议至少跑 4 周 — 你会发现自己以为"我天天都在看"实际只看了 12 天里的 4 天,这个数据本身就值得知道。
Q7:Claude 给的 P0 我执行了亏钱了怎么办?
记录在 evidence_log.csv 里,4 周后看命中率。
- 命中率 <40% → 红线没起作用,要改(找 evidence 后改)
- 命中率 60-80% → 正常,继续
- 命中率 >80% → 也要警惕,样本太少 / 市场单边 / 你 cherry-pick 了
这个 skill 不保证盈利。它保证你有结构地决策。长期看比情绪化决策好,但单天 / 单笔不能保证。
Q8:我有 2 个券商怎么办?
不是 v1.0 默认场景,但支持。看 docs/advanced.md — 里面讲跨账户对账、代持隔离、三口径契约。如果你只有一个账户,忽略整个 advanced 文档。
Q9:这个 skill 会自己升级吗?
不会。这是设计决定 — 私有版 8 个月 11 版的失败教训就是"自动升级 = 自动膨胀"。任何升级都是手动的,且要先有 evidence 支撑。看 docs/governance.md。
Q10:我能用别的 LLM 跑吗?
理论可以,工具是纯 Python。但 9 章节模板和触发词是为 Claude 优化的,换模型(GPT-4 / Gemini)需要你自己改 SKILL.md 的 trigger 段。作者不维护非 Claude 兼容性。
9. 高级用法
9.1 多账户对账
如果你有 2+ 个券商账户:
- 读
docs/advanced.md - 用
templates/advanced/里的known_accounts.template.json+manual_broker_snapshots.template.json - 启用三口径契约(PERSONAL_BOOK / BROKER_COLLATERAL_BOOK / MARKET_DATA)
9.2 朋友代持隔离
朋友把仓位寄存在你账户里(占用你的保证金,但不属于你):见 docs/advanced.md 的 friend_book 章节。
9.3 自定义红线
在 data/book_authority.json 加你自己的:
- "Top1 不能 > 25%"
- "美元仓位不能 > 30%"
- "杠杆不能 > 1.5"
report_gate.py 会强制校验。但:必须有 ≥3 条 evidence 支撑才加,见 docs/governance.md RED-4。
9.4 接入更多数据源
- Morningstar(估值)
- 13F(机构持仓)
- 期权链(隐波 / Greeks)
每个数据源是 plugin 形式,加一个不会污染主流程。
10. 获得帮助
工具诊断
python3 tools/sstate.py show # 看 session 状态
python3 tools/sstate.py inventory # 看今天产出了什么
python3 tools/evidence_log.py status # 看 Phase A 进度
git log --oneline -20 # 看最近 20 次 commit
常见出错位置
- Claude 重复犯老错误 — 检查
CLAUDE.md是否被读取(每个 session Claude 应该自动读) - 报告里数字奇怪 — 跑
report_gate.py看 schema 校验 - HTML 乱了 — 跑
sstate.py sanity <html>检查 duplicate<h4> - session 之间记忆丢 — sstate journal 是真相源,不要靠对话上文
文件层级速查
- 报告 →
daily-reports/YYYY-MM/daily_*.html - 数据 →
data/*.json+personal-holdings.csv - 黑匣子 →
performance_log.json - session 状态 →
.alphadesk_session_state.json - 配置 →
CLAUDE.md
进一步阅读(按推荐顺序)
docs/workflow.md— 9 章节模板细节docs/governance.md— 为什么这个 skill 这么薄docs/lessons-learned.md— 私有版踩过的坑docs/architecture.md— 数据流 / 工具架构docs/data-sources.md— 截图 / CSV / MCP 接入docs/advanced.md— 多账户(可选)
版本:v1.0(2026-05-28) 许可:MIT(skill 框架);你的持仓数据归你 作者:从私有版 8 个月 11 版的失败里抽离出来的薄壳 最后一句:稳定收益的投资模型 ≠ 完美的投资模型。它 = 一个你能持续 4 周不动的模型。