v587d/capital-generation

Capital Generation

[!IMPORTANT] 愿大家的财富数字就像“text generation”一样，不断增长，永不停止。

Slogan

Next-Gen AI-Driven Capital Generation.

What

面向中国股市小散户的金融投资智能体

Why

• 聪明的中国散户急需AI辅助投资决策。
• 绝大多数AI智能体并未将智能带入金融场景。
• coding agent的设计思路对financial Agent并非有效。
• financial agent != model + harness + skills/MCP/tools/prompt…
• 因为financial agent更强调有机结合。恰逢 DeepSeek Harness 问世，我们一起做一些新鲜的尝试。

BYOK

[!WARNING] 本项目不提供第三方 API Key，需你自行申请。仓库内不保存任何密钥。

申请 Key

• Wind：免费获取 API Key，每天送 1000 积分（有效期 1 天），初始 2000 积分。→ 访问官网申请
• 同花顺：免费获取 API Key，免费使用，对高频请求有限制。→ 访问官网申请
• AKShare：无需 Key，作为免费兜底源直接可用。

配置方法

拿到 Key 后，任选以下一种方式配置，推荐使用 credentials 文件：

1. 将 Key 写入 ~/.dsh/.credentials.yaml（权限建议 0600）：

   ths_api_key: "你的同花顺 API Key"
   wind_api_key: "你的 Wind API Key"
   

2. 或者通过环境变量注入：

   export THS_API_KEY="你的同花顺 API Key"
   export WIND_API_KEY="你的 Wind API Key"
   

3. 重启 DSH / 重新启动 MCP server 后生效。未配置的源会给出 warning 并自动降级到可用兜底源，不会阻断启动。

[!TIP] 如果你通过 DSH 接入，且选择环境变量方式，请确认 cordis.patch.yml 的 env 中显式透传了 THS_API_KEY / WIND_API_KEY；否则 DSH 的 MCP 子进程可能拿不到 Key。

能力一览（v0.3.1）

统一金融数据访问入口：11 个 fin_data__* MCP 工具，一个入口覆盖 A 股行情 / K线 / 财务 / 日历 / 特色数据 / 公告 / 宏观 EDB / 双源对账 / 基金 / 指数。

每个结果携带溯源信封：source（同花顺/Wind/AKShare）+ tier（free/quota/paid）+ ts + warnings[]。降级从不静默；分钟线/公告/指数基本面无降级源，明确告知。

设计哲学

• 三源架构，不是三源平权：同花顺（免费官方 REST）为行情主干，AKShare（免费）兜底，万得 Wind（权威）负责财务/分钟线/公告/EDB 等独家域。
• 上下文预算优先（v0.3.1 实测，真实 KEY）：结果侧 -72.2%、工具面 -9.2%/轮。公告全文截断（truncated 显式标注 + url 兜底）、K线表头外提（meta+rows）、schema 去冗余 title——全部在”工具 schema 冻结 + 降级可观测”红线上完成。
• 契约纪律：工具名与参数 schema 一经发布即冻结，任何变更走 docs/DESIGN_REVIEW.md 评审记录；数据模型 L1 身份 / L2 语义 / L3 标注分层，vendor 字段只标注、不转换。
• BYOK：所有 Key 由使用者自备（同花顺/Wind），存在 ~/.dsh/.credentials.yaml，仓库零密钥。

快速开始

# 1. 环境: Python 3.12+ / uv
uv sync

# 2. 配置 Key (env 或 DSH credentials 文件)
#    THS_API_KEY=sk-...   WIND_API_KEY=ak-...
#    或写入 ~/.dsh/.credentials.yaml (0600)

# 3. DSH 接入: cordis.patch.yml 增加一行
- insert:
    - id: finance-unified
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: fin
        transport: stdio
        command: uv
        args: ['run', '--directory', '/path/to/capital-generation', '-m', 'servers.mcp_data']
        failOnStartupError: true

# 4. 本地验证
uv run python scripts/ci.py        # ruff + pytest + 双源契约
uv run pytest tests -q             # 205 passed + 10 skipped

数据湖（离线资产）

官方同花顺 marketdb CLI（MIT）整体集成：全市场 10 年日K + 复权因子 + 近 10 交易日增量，四层表 raw/calc/dim/stg + 8 项质量校验。纯离线，不进 LLM（用户裁定）：全市场扫描类需求走 scripts/lake.py CLI，工具面明示不支持。

项目结构

core/       # 纯 Python 数据域: domain (L1/L2/L3 模型) + adapters (THS/Wind/AKShare)
servers/    # MCP 薄壳 (FastMCP): 只注册 fin_data__* 工具, 渲染层含上下文压缩
config/     # 数据即配置: chains.yaml / error_map.yaml / render.yaml / symbols.json
scripts/    # ci.py / lake.py / live-probe.py / measure_tokens.py (token 基线)
tests/      # 离线单测 + fixtures (三源可比性)
assets/     # 效果图

文档

• docs/DESIGN_REVIEW.md — 设计决策与 schema 评审记录（改设计前先读）
• docs/DEGRADATION.md — 降级链与错误分类（降级可观测红线）
• docs/DATA_MODEL.md — L1/L2/L3 数据模型契约
• docs/LESSONS.md — 契约事实与坑（THS/Wind 实测）
• docs/DESIGN_CONTEXT_BUDGET.md — 上下文 token 预算方案与实测
• docs/CONTEXT_BUDGET_RESULTS.md — v0.3.1 优化前后正式对比数据

路线图

License

Apache-2.0（含 NOTICE）。同花顺/万得 API 为第三方商业服务，其条款独立于本仓库；Key 由使用者自备（BYOK）。