# alpha-desk

Adopt this skill: https://proskills.md/skills/other/jinghao-leon-dsh-alpha-desk-skill

Page: https://proskills.md/skills/other/jinghao-leon-dsh-alpha-desk-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skill/SKILL.md
size: 9672
sha: 0a80c3e8c7a76777ade35764a7e80b7cdc0aa5a3
upstream: https://github.com/jinghao-leon/dsh-alpha-desk/blob/main/skill/SKILL.md

````text
---
name: alpha-desk
description: AI 投研工作台——在 deepseek-harness 里编排 virattt/ai-hedge-fund（美股多策略 AI 基金，支持回测）、iFinD 权威数据源（经 plugins/ifind 访问，财报/公告/股东/预测/选股，A股港股美股）与本地 A股/港股技术分析技能，配合 risk-gate 风控钩子、定时盯盘与投资记忆，完成"分析→回测→解读→复盘"的完整投研闭环。当用户要求分析美股、运行 AI 基金、回测策略、比较投资大师观点、生成投研报告、定时盯盘、复盘投资假设，或查询财报/财务报表/公告/股东户数/业绩预测/智能选股/iFinD/同花顺数据时使用。触发词：AI 基金、对冲基金、回测、巴菲特、格雷厄姆、投研、美股分析、盯盘、复盘、iFinD、同花顺、股东户数、财务报表、公告、业绩预测。
---

# Alpha Desk — AI 投研工作台

把 dsh 会话变成一个投研交易台：底层引擎是 [virattt/ai-hedge-fund](https://github.com/virattt/ai-hedge-fund)（MIT，CLI 名 `aihf`），上层由 dsh 的 skill / hook / cron / memory 扩展点编排。

**硬性合规线（每次回复都要遵守）：**
- 本技能输出的是**研究与教育内容**，不是投资建议；每次给出结论时附上免责声明："本内容仅供学习研究，不构成投资建议。"
- **暂不执行真实交易**。risk-gate 插件会拦截实盘命令，但即使插件未安装，也不得运行任何券商下单、资金划转命令。用户要求实盘时，明确拒绝并说明原因。
- aihf 内部对 LLM 信号的调用本身会消耗用户的 LLM API 额度，运行前先告知。

## 前置条件检查（每次会话首次使用前执行）

```bash
command -v aihf && aihf --help | head -5
```

未安装则：`pipx install aihf`（或 `uv tool install aihf`）。

运行需要两类 key（导出在 shell 环境，或写入 `~/.hedge-fund/.env`）：
- `FINANCIAL_DATASETS_API_KEY` — 行情与基本面数据（financialdatasets.ai，有免费档）
- 一个 LLM key：`DEEPSEEK_API_KEY`（推荐，与 dsh 同栈）或 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GOOGLE_API_KEY` / `XAI_API_KEY` / `KIMI_API_KEY`

aihf 默认推理模型是 `claude-sonnet-5`（走 Anthropic）。用 DeepSeek 时，任选其一：
- `export HEDGE_FUND_LLM_MODEL=deepseek-v4-pro`（全局默认）
- 或在命令里加 `--model deepseek-v4-pro`（单次覆盖）

缺 key 时**停下来让用户提供**，不要伪造数据、不要编造回测结果。所有数字必须来自 aihf 的真实输出。

## 核心概念：mandate（基金委托书）

mandate 是一个 YAML，描述"交易台"本身——策略、投资大师模型、风控、资金、再平衡频率——**不含股票代码**；标的是运行时通过 `--tickers` 传入的。本仓库 `mandates/` 目录自带三份：

| 文件 | 风格 | 再平衡 | 适用场景 |
|---|---|---|---|
| `deep-value-weekly.yaml` | 格雷厄姆×2 + 巴菲特 + 芒格，70% 价值 + 30% 财报漂移量化 | weekly | 默认首选，稳健演示 |
| `fundamental-ls-market-neutral.yaml` | 五位大师投票的多空市场中性 | monthly | 展示多空推理 |
| `inflections-daily.yaml` | 德鲁肯米勒 + 林奇的宏观拐点 | daily | 压力测试风控 |

可用的 alpha 模型（`models[].name`）：`graham`、`buffett`、`munger`、`lynch`、`druckenmiller`（LLM 驱动）；`pead`（财报漂移，量化，不消耗 LLM 额度）。用户想自定义组合时，复制一份 mandate 改写即可。

## 工作流一：单次投研周期（"今天这只基金怎么看这几只票"）

```bash
aihf mandates/deep-value-weekly.yaml --tickers AAPL,MSFT,NVDA --out records/cycle-$(date +%F).json
```

- stdout 是纯 JSON（CycleRecord），人类摘要走 stderr；始终用 `--out` 落盘到 `records/` 供复盘。
- CycleRecord 关键字段：`strategies[].signals[]`（每个模型的 `value` ∈ [-1,1] 看多/看空强度 + `reasoning` 文字理由）、`positions`（成交后持股）、`equity_before`、`skipped`（数据缺失的票及原因）。
- 解读时：**先念各模型的 reasoning 原文要点，再给综合仓位变化**——"巴菲特为什么看多、格雷厄姆为什么反对"是用户最想看的。分歧要明确指出，不要和稀泥。

## 工作流二：回测（"这套策略过去一年表现如何"）

```bash
aihf mandates/deep-value-weekly.yaml --tickers AAPL,MSFT,NVDA --backtest --start 2025-08-01 --out records/backtest-$(date +%F).json
```

- 回测从 `--start` 到 `--date`（默认今天）按 mandate 的再平衡频率逐周期运行，输出含净值曲线与基准（mandate 里的 `benchmark`）对比指标。
- 解读必给：累计收益 vs 基准、最大回撤、胜率，以及**哪几次调仓贡献/拖累最大**（从逐周期记录里定位）。
- 回测耗 LLM 额度 = 周期数 × 模型数 × 标的数，运行前估算并告知用户（例：weekly × 52 周 × 3 个 LLM 模型 × 3 只票 ≈ 468 次调用）。想省钱就先缩短区间或减少模型。
- 明确提醒：历史回测不代表未来收益。

## 工作流三：A股/港股联动

aihf 只覆盖美股。用户问 A股/港股时，改用 `stock-technical-indicators` 技能（如已安装）。两边结果可以同框对比（例："同一套价值逻辑在美股和 A股各自选出什么"），但要讲清两边引擎和数据源不同，结论不可直接互换。

## 工作流三·五：iFinD 权威数据（plugins/ifind，免 iFinD 账号）

需要**权威基本面/公告/股东/预测数据**时（财务报表、业务分部、股东户数、业绩预告、智能选股），用本仓库 `plugins/ifind/ifind_tool.py`——它经 Kimi agent-gw 访问同花顺 iFinD，凭证由脚本自行解析（plugins/ifind/.env 或本机 Kimi 桌面端配置），不需要用户提供任何账号，也不依赖环境变量注入。

```bash
# 1. 先读 API 目录(9 个 API 的参数、ticker 格式、覆盖范围约定)
terminal/.venv/bin/python plugins/ifind/ifind_tool.py describe

# 2. 按目录的参数约定调用(必须用 terminal/.venv/bin/python,它有 agent-gw SDK)
terminal/.venv/bin/python plugins/ifind/ifind_tool.py call ifind_get_financial_statements \
  --params-json '{"ticker": "600519.SH", ...}'
```

规则：
- **必须先 describe 再 call**，参数严格按返回的目录构造（ticker 格式：A股 `600519.SH`、港股 `0001.HK`、美股 `AAPL.O`）。
- 公告与业绩预测仅覆盖 A 股；调用失败时如实报告错误，禁止编造财务数字。
- 引用数据时带上报告期/币种/数据口径限定语。
- 与 gtimg 行情的分工：盘中报价/K线走行情网关，基本面与公告走 ifind。

## 工作流四：定时盯盘（cron）

用户要求"每天盘前/盘后自动跑"时，用 dsh 的定时任务能力注册调度，例如：

- 美东盘前（北京时间 21:30 前）：跑工作流一，输出当日信号摘要
- 每周五收盘后：跑回测增量更新 + 本周假设复盘

定时任务产出的记录同样落盘 `records/`。

## 工作流五·五：公开预测台账（ledger/，对外可验证）

每次给出**可结算的方向性观点**（某标的在某时间窗内看多/看空/横盘）时，除了写进记忆，还要入台账：

```bash
python3 tools/ledger.py new --symbol <代码> --market cn|hk|us --direction long|short|neutral \
  --confidence <0~1> --horizon <YYYY-MM-DD> --rationale "<理由，必填>" \
  --source "workflow:<来源>" [--invalidate-if "<失效条件>"]
```

规则：
- `rationale` 必填且要具体（依据什么数据/逻辑）——没有理由的观点不入台账。
- `confidence` 是自评置信度，事后会做校准统计（声明 0.7 的预测是否 70% 命中），**不要拍脑袋给 0.9**。
- `new` 会自动 git commit；**尽快 push**（公开时间戳才成立）。commit 后不可改写已入库的预测。
- 到期后（或用户要求复盘时）：`python3 tools/ledger.py settle`，然后 `python3 tools/ledger.py report --write` 更新 stats.md，并把结果 commit + push。
- 结算是机械的（收盘价 + 死区 + 方向），**禁止人工改判定结果**；数据缺失会记 void 不计分。
- 台账战绩从零累积、拒绝回填：如实展示 miss 与低胜率，这比虚假战绩值钱。

## 工作流六：投资记忆与复盘

- 每次给出一个观点时，把"假设"写进记忆：标的、方向、理由、预期时间窗、失效条件。
- 复盘时取出历史假设，对照 `records/` 里的实际信号与走势，逐条判定对错，并总结哪类假设胜率高。
- 这是本工作台区别于一次性问答的核心：**观点要被记录、被检验、被追责**。

## 失败处理

- `skipped` 非空 → 告知用户哪些票数据缺失（常见于新股、退市、数据源未覆盖），不要静默忽略。
- 报 `ANTHROPIC_API_KEY not found` 之类错误 → 说明用户没配 LLM key 或没指定模型；提示配 `DEEPSEEK_API_KEY` 并加 `--model deepseek-v4-pro`，不要擅自换成别的 provider。
- 网络/额度错误 → 原样报告 stderr，不要重试超过两次。
- 用户给的 mandate 路径不存在 → 先用 `ls mandates/` 列出可用的，让用户选。

## 安全红线（risk-gate 插件已装时由其强制执行，未装时自律）

- 禁止：任何券商 API/CLI 下单命令（ibkr、alpaca、tda、富途、老虎等）、向券商域名发写请求、`--live` 类参数。
- 禁止：修改 `~/.hedge-fund/.env` 之外的任何凭证文件。
- 允许：aihf 的全部只读/回测用法、数据查询、报告生成。
````

## File: README.md
upstream: https://github.com/jinghao-leon/dsh-alpha-desk/blob/main/README.md

````text
<div align="center">

# Alpha Desk

**把 deepseek-harness（dsh）会话变成合规、可复现、可追责的 AI 投研工作台**

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-339933?logo=python&logoColor=white)](terminal/backend/requirements.txt)
[![dsh Skill Pack](https://img.shields.io/badge/deepseek--harness-skill_pack-4D6BFF)](https://github.com/deepseek-ai/deepseek-harness)
[![Engine: ai-hedge-fund](https://img.shields.io/badge/Engine-ai--hedge--fund-black)](https://github.com/virattt/ai-hedge-fund)
[![Terminal: React · klinecharts · FastAPI](https://img.shields.io/badge/Terminal-React_·_klinecharts_·_FastAPI-61DAFB?logo=react&logoColor=black)](terminal/README.md)
[![演示视频](https://img.shields.io/badge/演示视频-90s_demo-blueviolet)](terminal/demo/alpha-desk-terminal-demo.mp4)

[English](README.en.md) | 中文

</div>

> [!WARNING]
> **本项目仅供学习研究，不构成投资建议，暂不执行真实交易。** risk-gate 在架构层拒绝一切实盘下单 / 券商 API / 凭证访问。

> 把 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）会话变成一个投研交易台：
> 多策略 AI 基金回测 + A股/港股技术分析 + 风控合规门禁 + 定时盯盘 + 投资记忆复盘。
> 本仓库是一个可直接安装的 dsh **skill 包**（AI 投研 / AI hedge fund / 量化回测 / Agent 风控），也是 dsh 微内核扩展点（skill / hook / cron / memory）的完整示范。

![alpha-desk 量化终端](terminal/screenshot.png)

## 它解决什么问题

通用 agent 框架能"聊天"，但做投研缺四样东西：

1. **可复现的引擎** —— 结论不能是模型即兴编的，必须来自真实数据与真实计算
2. **合规边界** —— agent 权限越来越大，"永远碰不到真钱"要是架构保证，不是提示词约定
3. **持续性** —— 投资观点要被记录、被定时检验、被事后追责
4. **多市场** —— 美股、A股、港股各一套数据与逻辑

Alpha Desk 用 dsh 的扩展点各解决一个问题：

| 问题 | dsh 扩展点 | 本仓库实现 |
|---|---|---|
| 可复现引擎 | skill（`section` + `inject()`） | [`skill/SKILL.md`](skill/SKILL.md)：编排 [virattt/ai-hedge-fund](https://github.com/virattt/ai-hedge-fund) CLI，stdout 纯 JSON，全部落盘 |
| 合规边界 | hook（`tools/pre-execute` waterfall） | [`plugins/risk-gate`](plugins/risk-gate/index.ts)：实盘下单/券商 API/凭证访问在分发前被单调拒绝 |
| 持续性 | cron + memory | SKILL.md 工作流四/五/六：盘前扫描、公开预测台账、假设复盘 |
| 多市场 | skill 组合 | 美股走 aihf；A股/港股联动 `stock-technical-indicators` 技能 |
| 权威数据 | agent 工具链 | [`plugins/ifind`](plugins/ifind/README.md)：iFinD 数据源（财报/公告/股东/预测/选股），经 Kimi agent-gw，免 iFinD 账号，凭证自解析 |

## 架构

```
用户（自然语言）
   │
   ▼
deepseek-harness agent ── inject ──► skill/SKILL.md（本仓库）
   │                                   │
   │   tools/pre-execute               ▼
   │ ◄── risk-gate 插件（拒绝实盘）   aihf CLI（ai-hedge-fund 引擎）
   │                                   │  stdout: CycleRecord / BacktestResult JSON
   │                                   ▼
   │                              records/*.json（落盘，供复盘）
   │
   ├── cron：盘前/周末定时触发投研工作流
   └── memory：投资假设台账，到期对照 records 复盘
```

底层引擎 [ai-hedge-fund](https://github.com/virattt/ai-hedge-fund)（MIT）把"基金"做成声明式 mandate：策略 pod、投资大师 alpha 模型（格雷厄姆/巴菲特/芒格/林奇/德鲁肯米勒 + 量化 PEAD）、风控限额、再平衡频率都是 YAML 数据；标的在运行时通过 `--tickers` 传入。aihf 原生支持 **DeepSeek 作为推理 LLM**——DeepSeek 模型跑在 DeepSeek harness 里驱动 AI 基金，全栈同构。

## 量化终端（terminal/）

把上面的 agent 能力装进一个同花顺风格的 Web 终端——A股自选实时报价（红涨绿跌）、K线、专家团信号面板、右栏明细，中间是对话区，所有回复都过 risk-gate 并附带逐步运行轨迹（reasoning / tool-call / token 计量）。数据层用 **vnpy** 的 BarData/TickData 对象模型与 Gateway 语义封装腾讯免费行情（分钟级延迟），未来换 CTP/SimNow 是 drop-in 替换；agent 走 `dsh --profile headless` + risk-gate patch。**只读研究终端，没有下单路径。**

📺 [90 秒演示视频](terminal/demo/alpha-desk-terminal-demo.mp4) · 安装与 API 详见 [terminal/README.md](terminal/README.md)

## 公开预测台账（ledger/）

第三方"AI 预测竞技场"类平台的共同代价是数据许可：你的预测和推理文本被永久授权、可进入他人训练集。本仓库自带替代方案——**公开预测台账**：观点在给出的瞬间落盘为结构化 JSON 并 git commit，到期日用真实收盘价**机械结算**（规则固定、无人工裁量），胜率与置信度校准由脚本汇总进 [ledger/stats.md](ledger/stats.md)。

- **可验证性靠 git**：预测先于结果入库，commit 序列即时间戳证据；诚实边界见 [ledger/README.md](ledger/README.md)（本机时间可改，尽早 push 才构成公开证据）
- **结算规则透明**：基线 = `as_of` 后首个交易日收盘，终值 = `horizon_end` 当日（或之前最近交易日）收盘，±0.5% 死区外按方向判 hit/miss，数据缺失记 `void` 不计分
- **数据源免费无 key**：腾讯 gtimg 日K，A股（前复权）/港股/美股三市场
- **从零开始，拒绝回填**：台账 2026-09-23 起运行，战绩只能来自真实结算累积——一条过程全公开的空白台账，比任何无法审计的"历史胜率"值钱

```bash
python3 tools/ledger.py new --symbol 600519 --market cn --direction long \
  --confidence 0.6 --horizon 2026-10-23 --rationale "……"
python3 tools/ledger.py settle              # 结算所有到期预测
python3 tools/ledger.py report --write      # 重新生成 ledger/stats.md
```

结算引擎已用真实行情验证（演练命令可复现）：`LEDGER_DIR` 指向临时目录后，对茅台 2026-09-01→09-18 的演练做多（基线 1299.56 → 1257.12，-3.27%，miss）、AAPL 同窗口演练做空（325.13 → 336.13，+3.38%，miss），两条均被如实记为 miss——机制不粉饰亏损。单元测试：`python3 tests/test_ledger.py`（20 项，离线）。

## 快速开始

```bash
# 1. 安装引擎（pipx 隔离安装）
pipx install aihf

# 2. 配置 key（二选一：shell 环境变量，或写入 ~/.hedge-fund/.env）
export FINANCIAL_DATASETS_API_KEY=...   # 行情与基本面，financialdatasets.ai 有免费档
export DEEPSEEK_API_KEY=...             # alpha 模型的推理 LLM

# 3. 手动验证引擎
aihf mandates/deep-value-weekly.yaml --tickers AAPL,MSFT,NVDA --backtest

# 4. 把 skill 装进 dsh（按你的 dsh 安装方式，将 skill/ 目录加入技能搜索路径，
#    例如软链到 ~/.agents/skills/alpha-desk）
ln -s "$PWD/skill" ~/.agents/skills/alpha-desk

# 5. （可选但推荐）启用 risk-gate 插件，见 plugins/risk-gate/
```

然后在 dsh 里直接说人话：

- 「用深度价值基金回测一下苹果、微软、英伟达过去一年」
- 「巴菲特和格雷厄姆对 NVDA 的看法有什么分歧？」
- 「每个交易日盘前帮我跑一遍持仓信号」
- 「上周你建议关注的几只票，现在复盘一下对错」

## 仓库结构

```
dsh-alpha-desk/
├── skill/SKILL.md                        # dsh 技能本体（触发条件、工作流、合规红线）
├── mandates/                             # 三份开箱即用的基金委托书
│   ├── deep-value-weekly.yaml            #   深度价值（格雷厄姆×2+巴菲特+芒格）周频
│   ├── fundamental-ls-market-neutral.yaml #  五大师多空市场中性，月频
│   └── inflections-daily.yaml            #   宏观拐点（德鲁肯米勒+林奇）日频
├── plugins/risk-gate/                    # dsh 风控钩子插件（tools/pre-execute）
├── plugins/ifind/                        # iFinD 数据源（经 Kimi agent-gw，免 iFinD 账号）
├── ledger/                               # 公开预测台账（预测 JSON + 结算记录 + stats.md）
├── tools/ledger.py                       # 台账 CLI：登记 / 机械结算 / 战绩汇总（仅标准库）
├── tests/test_ledger.py                  # 结算规则离线测试
├── terminal/                             # 同花顺风格量化终端（vnpy 数据层 + FastAPI + React）
│   ├── backend/app/gateway_gtimg.py      #   腾讯行情 → vnpy BarData/TickData
│   ├── backend/app/fundamentals.py       #   iFinD 基本面（agent-gw 直调 + 7 天缓存）
│   ├── backend/app/agent_bridge.py       #   dsh headless 桥（risk-gate 已挂载）
│   └── web/                              #   React + klinecharts 终端 UI
├── records/                              # 运行记录落盘目录（git 忽略）
└── LICENSE                               # MIT
```

## 与主流 agent 框架的对比

| 能力 | Alpha Desk (dsh) | 裸 LangChain/CrewAI 编排 | 通用编码 agent + 提示词 |
|---|---|---|---|
| 合规边界 | 架构级：hook 在工具分发前单调拒绝 | 需自己包一层执行器 | 仅靠提示词，模型可绕过 |
| 投研引擎 | 成熟开源基金引擎，JSON 可复现 | 自行拼装 | 模型即兴生成，不可复现 |
| 定时盯盘 | dsh cron 扩展点，声明式 | 需外部调度器 | 无 |
| 观点追责 | memory + 落盘记录，到期自动复盘；公开预测台账（git 时间戳 + 机械结算 + 校准曲线） | 自行实现状态层 | 无 |
| 热重载/生态 | dsh 插件 HMR，MCP/skill 生态复用 | — | — |

## FAQ

**Q：Alpha Desk 能帮我实盘下单吗？**

不能，而且是架构保证而非提示词约定：[risk-gate](plugins/risk-gate/index.ts) 挂在 dsh 的 `tools/pre-execute` 瀑布上，对实盘下单、券商 API、凭证文件访问做单调拒绝，工具调用在分发前就被拦截。"永远碰不到真钱"是本仓库的设计目标。

**Q：不装 dsh 能用吗？**

部分能。`mandates/*.yaml` 是标准 aihf 委托书，`aihf mandates/deep-value-weekly.yaml --tickers AAPL,MSFT --backtest` 单独即可跑通回测；skill 编排、cron 定时盯盘、投资记忆台账这三层需要 deepseek-harness。

**Q：支持 A股/港股回测吗？**

美股走 aihf 引擎（数据源 Financial Datasets）。A股/港股目前是行情报价 + 技术分析（腾讯行情 + `stock-technical-indicators` 技能）+ iFinD 基本面查询（[plugins/ifind](plugins/ifind/README.md)），暂无 A/H 股基本面回测——受免费数据源限制。

**Q：数据是实时的吗？**

腾讯免费行情，分钟级延迟；iFinD 基本面经 Kimi agent-gw 直调并做 7 天磁盘缓存以保护月度额度。都不是付费 Level-1/Level-2 行情通道。

**Q：回测结果可以直接当投资依据吗？**

不可以。回测来自真实数据与真实计算、全部落盘可复现，但历史表现不构成未来收益保证；本仓库所有输出仅供学习研究。

## 局限与边界（Limitations）

- **无实盘路径**：risk-gate 拒绝实盘/券商/凭证访问，本项目暂不执行真实交易——这是设计目标，不是待办事项
- **数据源偏美股**：aihf 引擎的 Financial Datasets 主要覆盖美股；A股/港股缺基本面回测
- **行情分钟级延迟**：腾讯免费接口无 SLA，不保证可用性
- **iFinD 非官方直连**：经 Kimi agent-gw 中转，受额度与稳定性约束
- **回测 ≠ 未来收益**：所有策略输出仅供学习研究

## 致谢

- 引擎：[virattt/ai-hedge-fund](https://github.com/virattt/ai-hedge-fund)（MIT），本项目只做编排层，不 fork 其代码
- 运行时：[deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)

## License

[MIT](LICENSE) © 2026 JingHao-Leon
````
