Stock Analytics Agent - 股市投资分析助手

🚀 V3.1 升级 - 2026年11月

• 数据地基：FullQuote（PE/PB/52 周/换手/量比）+ 市场总览 + 持仓快照
• 计算层：区间收益 / 回撤 / 波动 / 相关性 / beta 由工具计算，不靠心算
• 调用治理：单轮 ≤8 次、同参去重、递归上限
• 报告输出：--out 落盘 + 结构检查 + 合规词表
• 双模式：harness 直读（模式1）+ LangChain.js 独立 CLI Agent（模式2）
• 25 个投资 skill，口径统一、可核验、含空方论点

项目简介

Stock Analytics Agent 是一个基于大语言模型（LLM）的股市投资分析智能体，专为个人投资者设计。它通过模块化 Skill 架构 + 本地数据获取工具 + AI Agent 双模式，帮助投资者进行市场分析、资产配置和投资决策。

核心特点

• 🤖 双模式运行：既可作为 harness 技能集被 IDE Agent 直读，也可作为独立 CLI Agent 对话
• 📊 多维度分析：覆盖 A股、港股、美股、债券、ETF、基金等多个投资品种
• 🎯 智能持仓管理：读取 position.md 自动调用对应分析技能
• 🧮 计算层：收益、回撤、波动、相关性与 beta 由工具计算，回答不靠心算
• 🔍 口径可核验：估值分位/股息率/回撤统一口径标注，回答附「溯源清单」防幻觉
• ⚖️ 客观中立：强制空方论点、估值陷阱检查，不给收益承诺
• 🛠 本地数据获取：A股/港股/美股/基金实时行情、净值、股息与 K 线
• 📤 报告输出：--out 写入 Markdown，自动做结构检查并提示交付审查
• 📈 长期投资导向：专注长期稳健复利，不鼓励短期炒作

两种使用方式

按场景选择，可随时切换。两者共享同一套 skill 与数据层，逻辑零分叉。

模式 2 用法：

# 单次提问
bun run main.ts --ask "帮我分析一下招商银行的基本面"

# 单次提问并写报告（自动做结构检查）
bun run main.ts --ask "生成今日持仓日报" --out reports/daily_report_20261103.md

# 多轮对话（REPL，输入 exit 退出）
bun run main.ts --agent

系统架构

graph TB
    subgraph Agent["🤖 Agent 层 · 两种使用模式"]
        direction LR
        M1["模式 1 · harness 直读Trae/Cursor/Codex读 AGENTS.md + skills + position.md"]
        M2["模式 2 · 独立 CLI--ask / --agentLangChain.js + .env LLM"]
    end

    subgraph Skill["📚 Skill 层 · .agents/"]
        S1["25 个投资 skillstock-deep-analysis 等"]
        S2["3 个 business skillhtml-report / report-reviewskill-quality-review"]
        S3["3 个 dev skillbelos-street / bun / grill-me"]
    end

    subgraph Data["⚙️ 数据层 · src/"]
        CLI["main.tscli / data / agent / format"]
        STATS["stats.ts收益 / 回撤 / 波动 / corr / beta"]
        SDK["行情 / 基金 / K线 / 股息"]
    end

    Market["东方财富 / 天天基金A股 · 港股 · 美股 · 基金"]

    M1 -->|"load_skill + 调 CLI"| Skill
    M2 -->|"10 个 tools + load_skill"| Skill
    M1 --> Data
    M2 --> Data
    CLI --> STATS
    CLI --> SDK
    SDK --> Market

分层说明：

• Agent 层：决定「怎么用」——harness 直读 or LangChain.js 对话
• Skill 层：投资方法论（口径纪律、空方论点、估值框架），渐进式加载不爆上下文
• 数据层：main.ts → src/ → 行情/基金/K线/股息，两种模式共享；计算层负责收益、回撤、波动与相关性

Agent 工具（10 个）

所有工具返回统一信封 { ok, data, meta }，meta 带 source / asOf / unit；失败返回 { ok: false, error }，不抛异常、不编造缺失字段。

投资理念

投资理念与风险偏好由 position.md 按每位投资者自定义，工具不预设立场——长期复利、成长、价值、红利、量化等不同风格均可适配。

Skill 技能清单

投资分析 skill（25 个 · .agents/skills/）

市场分析类（8）

ETF / 基金类（8）

个股 / 估值类（9）

业务技能（.agents/business/）

开发技能（.agents/dev/）

技能路由：投资问题搜 skills/；交付报告搜 business/；代码工程搜 dev/。详见 AGENTS.md。

使用场景

快速开始

1. 环境自检与安装

# 安装 Bun 运行时（已有则跳过）
curl -fsSL https://bun.sh/install | bash
bun --version

# 安装依赖
bun install

2. 配置持仓

cp position.example.md position.md
# 编辑 position.md 填入你的持仓标的、目标占比、配置规则

position.md 是个人持仓配置，已加入 .gitignore 不会提交。

3. 配置模型（仅模式 2 需要）

cp .env.example .env
# 编辑 .env 填入 LLM 配置

.env 内容（OpenAI 兼容端点均可）：

OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://api.deepseek.com   # DeepSeek / MoonShot 等
DEFAULT_MODEL=deepseek-flash                 # 模型名因供应商而异
# OPENAI_APPEND_V1=false                    # Azure/网关需保留原 URL 时关闭补 /v1

模式 1（harness）无需 .env，由 IDE Agent 自带 LLM。

4. 冒烟测试与自检

bun run main.ts -s sh600519 --pretty   # 返回贵州茅台行情即环境就绪
bun run check                          # 类型检查 + 单测 + golden + lint

5. 开始使用

• 模式 1：把 AGENTS.md 交给 IDE Agent（或作为 system prompt），直接对话
• 模式 2：bun run main.ts --ask "今天A股表现怎么样？" 或 --agent 进多轮对话

CLI 工具

基本用法

bun run main.ts [options]

参数说明

stdout 只输出数据，标题/提示走 stderr，可直接管道给 JSON 解析工具。

输出格式

JSON（默认）：

[
  {
    "name": "贵州茅台",
    "code": "600519",
    "price": 1212.72,
    "change": -19.28,
    "change_percent": -1.57,
    "update_time": "2026/10/21"
  }
]

Table：

名称        代码     价格      涨跌    涨跌幅
贵州茅台    600519   1212.72   -19.28  -1.57%

支持的市场

• A股：sh600519（贵州茅台）、sh600036（招商银行）等
• 港股：00700（腾讯控股）、01810（小米集团）等
• 美股：AAPL（苹果）、MSFT（微软）等
• 基金：006493、006961（南方中债）等
• ETF：sh515450（红利低波50ETF）等

使用示例

# 查询行情
bun run main.ts -s sh600941,sh600036 --pretty

# 查询股息率（含 yield_basis 口径标注）
bun run main.ts --dividend sh600941

# AI 助手单次提问（模式2）
bun run main.ts --ask "用巴菲特理念分析一下贵州茅台"

用户：今天我的持仓表现怎么样？
Agent：
1. 读取 position.md 了解持仓配置
2. 调 CLI 获取各持仓标的数据
3. 逐一加载对应 Skill 分析（含空方论点、口径标注）
4. 调 asset-allocation-rebalancing 给出再平衡建议
5. 输出报告 + 「📎 本次回答依据」溯源清单

项目结构

stock-analytics-agent/
├── main.ts                  # 薄入口：解析参数 → 分发
├── src/
│   ├── cli/                 # program/query/render（CLI 编排、渲染、spinner）
│   ├── data/                # sdk/dividend/stats（行情、净值、股息、K线、统计）
│   ├── agent/               # config/index/run/skills/tools/position/trace/envelope/compliance
│   ├── format.ts            # 输出格式化
│   ├── types.ts             # 集中类型定义
│   └── index.ts             # 统一导出
├── test/                    # bun test 用例 + golden fixture
├── .agents/
│   ├── skills/              # 25 个投资 skill
│   ├── business/            # html-report / report-review / skill-quality-review
│   ├── dev/                 # belos-street / bun / grill-me
│   ├── rules/               # project_rules / memory / agent_brief
│   └── memory/decisions.md  # 决策日志
├── upgrade/v3.0/            # 3.0 升级归档
├── upgrade/v3.1/            # 3.1 方案、评审与基线说明
├── AGENTS.md                # Agent 配置（skill 路由、场景映射）
├── position.example.md      # 持仓配置模板
├── .env.example             # LLM 配置模板（模式2）
├── package.json
└── README.md

致谢

扩展开发

添加新 skill：

1. 在 .agents/skills/ 下建目录，写 SKILL.md
2. 在 AGENTS.md 添加场景映射

添加新数据源：

1. 在 src/data/ 建模块（参考 sdk.ts）
2. 在 src/cli/program.ts 加参数，src/index.ts 导出

注意事项

⚠️ 法律声明

• 仅供个人学习和技术研究，禁止商业用途
• 数据来自公开第三方接口，归属权归各平台所有
• 不存储用户数据，不涉及账户登录

⚠️ 风险提示

• 仅供学习参考，不构成投资建议
• 投资有风险，入市需谨慎
• 回答附「溯源清单」供核验，量化口径以文档标注为准

许可证

MIT License