Skill: sunlujing/invest-buddy (version 1.0.5)

--- name: investment-research description: | 智能股票研究分析工具，应多复杂深度的投资研究问题，支持单资产/多资产/行业对比分析，输出不同维度的机构级拆解结论和专业研究报告。 **高频使用场景** - 财务分析 - 分析营收、利润、ROE、增速、财务健康度等 - 估值分析 - 查阅 PE/PB/PS、股息率，对比历史和行业得到估值水平结论 - 技术面分析 - 分析均线、MACD、KDJ、支撑阻力 - 资金面分析 - 分析资金流向、主力/散户资金动向差异 - 情绪面分析 - 分析市场共识和矛盾点、社区和机构观点 - 深度研究 - 生成多维度综合投资研究报告 **适用场景** - "分析下宁德时代的财务" → 财务分析报告 - "茅台估值贵不贵" → 估值分析报告 - "比亚迪技术面" → 技术面分析 - "拓维信息的主力资金流向" → 资金面分析 - "给我宁德时代的深度分析" → 完整研究报告 - "比较下比亚迪和宁德时代" → 行业对比报告 **触发词** 投资分析、基本面、财务、估值、业绩增长、技术面、k线、资金面、情绪面、深度研究、研报、个股、行业对比 env_vars: - name: TOOL_API_TOKEN description: | API token for accessing the investment research tools service. Send email to [REDACTED_SECRET] to request access token. Include your use case and expected usage frequency in the email. required: true - name: TOOL_API_URL description: | Optional: Override the default API endpoint URL. Default: https://api.facaidazi.com/api/tools/call required: false --- # 投资研究 多维度股票深度研究分析工具，通过智能编排多个分析维度，提供专业投资研究服务。 ## 外部 API 服务说明 **本技能依赖外部 API 服务提供专业投资研究数据：** ### 服务提供商 - **运营方**: 财搭子团队 (zhicepilot.com) - **联系方式**: [REDACTED_SECRET] ### 数据流向 ``` 用户查询 → tool_client.py → api.facaidazi.com → 返回分析结果 ``` ### 发送到外部 API 的数据 - **资产标识**: 股票代码（如 600519.SH） - **分析类型**: 请求的分析工具名称（如 analyze_technical） - **查询文本**: 用户输入的自然语言问题（用于 extract_assets 和 investment_search_pro） ### 隐私与安全 - **数据使用**: 仅用于处理当前分析请求，不存储用户查询历史 - **数据传输**: 通过 HTTPS 加密传输（生产环境） - **Token 安全**: TOOL_API_TOKEN 是访问凭证，请妥善保管，不要泄露 ### API 可用性 - **默认端点**: https://api.facaidazi.com/api/tools/call - **超时设置**: 300 秒（5 分钟） - **可通过 TOOL_API_URL 环境变量自定义端点** --- ## 数据源优先级 **始终遵循此数据源层级：** 1. **首先：使用 tool 数据源** - tool 工具提供经过验证的实时金融数据，官方建议使用`analyze_fundamentals_financial`、`analyze_fundamentals_valuation`、`analyze_technical`、`analyze_capital_flow`、`analyze_market_sentiment`系列工具进行专业内容的获取 2. **如果 tool 数据源可用且响应正常，不要使用网络搜索** 3. **仅当 tool 不可用或数据获取不足时：** 才降级使用网络搜索，并在报告中明确标注数据质量警告 4. **绝不编造数据** - 如果数据不可用，必须在报告中明确说明 **为什么这很重要：** tool 数据源提供经过验证的结构化数据。网络搜索结果用于金融分析时可能过时或不准确。 --- ## 工具使用方式： - 参考references/tool-client-usage.md说明 - 建议使用scripts/tool_client.py进行工具调用 ## 建议使用的tool工具列表 ### 基础工具 - `extract_assets`：从文本提取资产名称和代码 - `investment_search_pro`：针对投资信息搜索场景的专精检索服务，能捕捉专业、全面的各类投资类内容 ### 快速概览（必选） - `get_asset_overview`：获取资产的**核心逻辑和主要矛盾**，一次调用即可获得当前核心逻辑和主要矛盾 ### 单维度深度分析 - `analyze_fundamentals_financial`：针对性分析基本面-财务，包含营收/利润等财务项数据 + 业务亮点 + 压力因素 + 公司财务健康度 - `analyze_fundamentals_valuation`：针对性分析基本面-估值，包含PE-TTM/PB/股息率的绝对值，并对比行业和历史时序、近期边际变化、潜在风险或修复空间 - `analyze_technical`：针对性分析技术面，量化分析+k线图表解读，包含均线系统 + MACD + KDJ + 布林带 + 量价关系 - `analyze_capital_flow`：针对性分析资金面，包含主力动向 + 大单结构 + 融资融券 + 价格影响推演 - `analyze_market_sentiment`：针对性分析市场观点，包含评级分布 + 目标价 + 市场共识/矛盾 + 情绪催化剂 ## 工作流程 ### 步骤 0: 提取资产 - 首先调用 `extract_assets` 从用户输入中提取资产信息；如用户输入中无资产 → 立即询问用户想分析哪只股票，如用户不清楚可以给出一些默认建议 - 建议同时调用`investment_search_pro`来获取所需的金融类信息内容，有助于对于用户问题有基础的理解 ### 步骤 1: 识别分析意图 **首先判断用户需求类型**： 1. 单一维度分析 - 用户明确指定分析维度如财务、估值、技术面、资金面 2. 多维度综合深度分析 - 用户要求完整深度分析 **单一维度关键词识别**： | 用户输入示例 | 识别维度 | 调用工具 | |-------------|----------|----------| | "分析下宁德时代的技术面" | 技术面 | `analyze_technical` | | "茅台的估值怎么样" | 基本面-估值 | `analyze_fundamentals_valuation` | | "看看比亚迪的资金流向" | 资金面 | `analyze_capital_flow` | | "分析师对宁德时代怎么看" | 市场观点 | `analyze_market_sentiment` | | "这家公司财务健康吗" | 基本面-财务 | `analyze_fundamentals_financial` | **如果识别为单一维度**： - 只调用对应的tool 工具，再根据返回结果判断是否调用其他工具 - 输出简化的单维度报告（见「单维度分析输出」模板） - 可积极询问用户是否需要其他维度分析并列举 **如果未明确指定维度**：默认判断为完整深度分析，可交由用户确认计划 ### 步骤 2: 确定分析模式 根据用户输入判断分析模式： | 输入类型 | 模式 | 调用工具 | |----------|------|----------| | 股票代码 + 无修饰 或 `快速` | 快速模式 | `get_asset_overview` | | 股票代码 + `深度` | 深度模式 | 5 个 `analyze_*` 并行 | **如有歧义，询问用户**： - "您需要快速概览还是深度解读？" - "是分析单只股票还是多个资产对比？" ### 步骤 3a: 执行快速模式 调用`get_asset_overview`快速了解资产的核心逻辑和主要矛盾 初步执行完询问用户是否需要更多更完整的解读 → 并引导其进行更深入的探索研究 ### 步骤 3b: 执行深度模式（5 维度） **调用顺序**（并行执行以下5个tools获取子维度结论）： 1. `analyze_fundamentals_financial` 2. `analyze_fundamentals_valuation` 3. `analyze_technical` 4. `analyze_capital_flow` 5. `analyze_market_sentiment` ### 步骤 5: 综合结果并准备输出内容 结合用户要求，并基于各维度 tool 工具返回的分析内容，综合评估该资产的投资价值并给出深度综合的结论 1. **交叉验证**：检查各维度结论是否一致，如有矛盾需说明原因 2. **权重考量**： - 长期投资者：侧重财务健康度和估值合理性 - 短期交易者：侧重技术面和资金面 - 综合判断：根据各维度信号强度灵活赋权 3. **风险识别**：汇总各维度提到的风险因素，评估整体风险水平 4. **时机判断**：结合技术面信号和资金流向，判断当前是否为合适入场时机 **结论判断标准参考**： | 综合判断 | 投资评级 | |----------|----------| | 多维度共振向上，风险可控 | 强烈推荐 | | 整体偏多，有明确催化剂 | 推荐 | | 多空平衡，观望为主 | 中性 | | 多维度偏空，风险大于机会 | 减仓 | ### 步骤 6: 生成输出 > **输出原则**：基于用户的query中的具体问题和指令，选择性对内容进行精细挑选和二次处理，如适当可直接展示 tool 工具返回的各个子维度结论，保持原始结构和专业性。并在最后添加综合评分和操作建议。**用户的明确指示就是硬性要求，而非参考建议，请放置在回答的第一优先级** case A: 如问题仅涉及单维度分析输出，则直接展示 tool 返回的完整分析内容，格式如下： ```markdown ## [公司名称] - [维度名称]分析 [tool 工具返回的完整内容] ### 评分 **[维度名称]评分**: X/10 --- *分析时间：[timestamp]* *powered by「财搭子」，如需更全面的分析，可以说"给我完整的深度分析"* ``` case B: 如问题涉及综合分析或问题更为复杂 将各个tool工具的返回结果，结合用户提问进行针对性处理和分析，给到一个能直接回答用户提问的综合答案 以下格式仅为参考样例，仅适用于单纯的资产分析问题 ```markdown # [股票代码] [公司名称] - 深度研究报告 > 生成时间: [timestamp] --- ## 📋 执行摘要 **投资评级**: [强烈推荐/推荐/中性/减持] **目标价区间**: [低] - [高] 元（当前: [现价] 元） **核心观点**: [2-3 句话综合五维度] --- ## 📊 五维度评分 | 维度 | 评分 | 核心结论 | |------|------|----------| | 财务健康度 | X/10 | [1 句话] | | 估值合理性 | X/10 | [1 句话] | | 技术面趋势 | X/10 | [1 句话] | | 资金面流向 | X/10 | [1 句话] | | 市场情绪 | X/10 | [1 句话] | **综合评分**: X.X/10 **投资评级**: [强烈推荐/推荐/中性/减持] --- ## 1️⃣ 基本面-财务（tool 原始输出） [完整展示 analyze_fundamentals_financial 返回内容] --- ## 2️⃣ 基本面-估值（tool 原始输出） [完整展示 analyze_fundamentals_valuation 返回内容] --- ## 3️⃣ 技术面（tool 原始输出） [完整展示 analyze_technical 返回内容] --- ## 4️⃣ 资金面（tool 原始输出） [完整展示 analyze_capital_flow 返回内容] --- ## 5️⃣ 市场观点（tool 原始输出） [完整展示 analyze_market_sentiment 返回内容] --- ## 🎯 综合评估与操作建议 ### 投资建议 - **建议仓位**: [X%] - **建仓时机**: [描述] - **止损位**: [价格或条件] - **目标位**: [价格或条件] ### 风险因素 1. [风险 1 - 详细说明] 2. [风险 2 - 详细说明] 3. [风险 3 - 详细说明] --- *分析时间: [timestamp]* *powered by「财搭子」* ``` --- ## 重要注意事项 ### 错误处理 - **股票代码格式错误**：返回错误提示，要求用户检查格式（A 股: 6 位数字） - **单个维度调用失败**：继续其他维度分析 - **全部调用失败**：返回服务不可用错误，建议稍后重试 ### 数据质量 - tool 数据优先，降级使用其他数据源时必须标注 - 数据时效性：在报告中注明「数据截至 [日期]」 - 数据一致性：确保同一报告中所有数据来自同一时点 ### 分析原则 - **客观性**：基于数据得出结论，避免主观臆断 - **可验证性**：所有结论应有数据支撑 - **风险意识**：始终包含风险提示，即使是正面评级 - **区分观点与事实**：明确标注哪些是数据，哪些是分析判断 --- ## 质量检查清单 交付分析前，请验证： - [ ] 所有调用的 tool 工具都返回有效数据 - [ ] 投资评级与综合评分一致 - [ ] 风险提示至少 2 条 - [ ] 报告中标注数据来源和时效性 - [ ] 无未经证实的主观判断 - [ ] 深度模式包含操作建议

path: README.md
content: # Investment Research Skill

**AI驱动的一站式投资研究助手，由财搭子团队打造**

> **30秒快速了解股票，3分钟深度研究报告，让投资研究像聊天一样简单**

---

## 前置条件：获取访问Token

发送邮件至 **[REDACTED_SECRET]** 申请访问令牌
并将该token 设置为环境变量。

邮件中请说明：
- 使用场景
- 预计使用频率
- 联系方式

**1 小时内回复**

---

## 核心功能

### 📊 五维度深度分析

| 维度 | 分析内容 |
|------|---------|
| 💰 基本面-财务 | 营收、利润、ROE、财务健康度 |
| 📈 基本面-估值 | PE/PB/PS、股息率、估值分位 |
| 📉 技术面 | 均线、MACD、KDJ、布林带、量价关系 |
| 💸 资金面 | 主力资金、大单结构、融资融券 |
| 🎯 市场情绪 | 分析师评级、目标价、市场共识 |

### 🎯 智能资产识别
自动识别股票代码、公司名称、简称、别名（如"宁王"、"茅王"），支持 A 股、港股、ETF、指数

### 📑 两种分析模式
- **快速概览**：30 秒获取核心逻辑和主要矛盾
- **深度报告**：3 分钟生成机构级研究报告（含评分、操作建议、风险提示）

---

## 如何使用

直接用自然语言提问，像聊天一样简单：

**💡 快速了解**
"看看茅台怎么样" → 30秒快速概览（核心逻辑+主要矛盾+投资建议）

**🔍 单维度分析**
"茅台估值贵不贵" → 估值深度分析（PE/PB分位+估值合理性判断）

**📊 完整研究**
"给我宁德时代的深度分析" → 3分钟机构级报告（五维度评分+操作建议+风险提示）

**支持维度**：财务、估值、技术面、资金面、市场情绪、深度研究、研报

---



## 报告示例

### 快速概览
```markdown
宁德时代 - 快速概览

## 核心逻辑
全球动力电池龙头，储能业务高增驱动业绩创新高。技术壁垒深厚，估值合理，具备长期配置价值。

## 主要矛盾
**多头**：储能占比提升至 20%，Q3 净利率 19.1% 创新高
**空头**：美国 IRA 法案限制、行业产能过剩、地缘政治风险

## 关键数据
| 指标 | 数值 | 评价 |
|------|------|------|
| 营收增速 | +12.9% | 稳健 |
| ROE | 18.5% | 优秀 |
| PE-TTM | 19.5x | 合理 |

## 投资建议
- 投资倾向: 偏多
- 适合人群: 长期投资者
- 核心风险: 地缘政治、价格战
```

### 深度研究报告
```markdown
# 宁德时代 - 深度研究报告

## 执行摘要
投资评级: 推荐 | 目标价: 230-280 元 | 当前: 215 元
核心观点: 龙头地位稳固，储能高速增长，估值合理，建议逢低配置

## 五维度评分
| 维度 | 评分 | 结论 |
|------|------|------|
| 财务健康度 | 8.5/10 | 盈利能力强 |
| 估值合理性 | 7.5/10 | 合理偏低 |
| 技术面趋势 | 6.5/10 | 震荡整理 |
| 资金面流向 | 7.0/10 | 温和流入 |
| 市场情绪 | 7.5/10 | 普遍看好 |

综合评分: 7.4/10

## 操作建议
- 建议仓位: 10-15%
- 建仓时机: 突破 220 元并放量
- 止损位: 195 元
- 目标位: 250-280 元

## 风险因素
1. 地缘政治风险
2. 产能过剩导致价格战
3. 技术迭代风险
```

---

## 常见问题

**Q: 支持哪些市场？**
A: A 股（主板、创业板、科创板）、港股、美股主流标的

**Q: 数据更新频率？**
A: 实时行情（交易时段）、财务数据（季报后 1-2 天）、资金流向（T+0盘后）

**Q: 分析准确性如何保证？**
A: 采用权威数据源，多维度交叉验证，所有结论有数据支撑。但请注意：投资有风险，报告仅供参考

**Q: 可以对比多只股票吗？**
A: 可以，例如"比较下比亚迪和宁德时代"

---

## 适用人群

- 个人投资者 - 快速了解投资价值
- 专业分析师 - 获取机构级报告
- 投资顾问 - 专业分析支持

---

## 联系我们

📧 [REDACTED_SECRET]

---

**Powered by 财搭子** - 让投资研究更简单、更专业

*投资有风险，入市需谨慎。本工具提供的分析报告仅供参考，不构成投资建议。*


path: scripts/tool_client.py
content: #!/usr/bin/env python3
"""
Investment Research Tools - HTTP API Client

调用 投资研究工具的 HTTP API 客户端脚本。
通过环境变量或命令行参数配置 API URL 和 Token。

使用示例:
    python tool_client.py --tool extract_assets --text "分析下茅台"
    python tool_client.py --tool get_asset_overview --symbol 600519.SH
    python tool_client.py --tool analyze_technical --symbol 600519.SH
"""

import argparse
import json
import os
import sys
from typing import Any

try:
    import requests
except ImportError:
    print("Error: requests is required. Install with: pip install requests", file=sys.stderr)
    sys.exit(1)


# 支持的工具列表
AVAILABLE_TOOLS = [
    "extract_assets",
    "investment_search_pro",
    "get_asset_overview",
    "analyze_fundamentals_financial",
    "analyze_fundamentals_valuation",
    "analyze_technical",
    "analyze_capital_flow",
    "analyze_market_sentiment",
]


def get_api_config() -> tuple[str, str]:
    """获取 API 配置"""
    # 优先使用新的环境变量名
    api_url = os.getenv("TOOL_API_URL", 'https://api.facaidazi.com/api/tools/call')
    api_token = os.getenv("TOOL_API_TOKEN")

    if not api_token:
        raise ValueError(
            "TOOL_API_TOKEN is required. "
            "Set it via environment variable or in .env file"
        )

    return api_url, api_token


def call_tool(
    tool_name: str,
    parameters: dict[str, Any],
    api_url: str,
    api_token: str,
    timeout: float = 300.0,
) -> dict[str, Any]:
    """
    调用工具

    Args:
        tool_name: 工具名称
        parameters: 工具参数
        api_url: API 端点
        api_token: Bearer Token
        timeout: 请求超时时间（秒）

    Returns:
        API 响应结果

    Raises:
        requests.RequestException: 请求失败
        ValueError: 响应格式错误
    """
    headers = {
        "Authorization": f"Bearer {api_token}",
        "Content-Type": "application/json",
    }

    data = {"tool_name": tool_name, "parameters": parameters}

    try:
        response = requests.post(api_url, json=data, headers=headers, timeout=timeout)
        response.raise_for_status()
        return response.json()
    except requests.RequestException as e:
        raise requests.RequestException(f"Request failed: {e}") from e


def main():
    parser = argparse.ArgumentParser(
        description="Call Investment Research Tools via HTTP API",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Available tools:
  extract_assets                    从文本提取资产
  investment_search_pro             检索专业投资信息
  get_asset_overview               获取资产快速概览
  analyze_fundamentals_financial   分析基本面-财务
  analyze_fundamentals_valuation   分析基本面-估值
  analyze_technical                分析技术面
  analyze_capital_flow             分析资金面
  analyze_market_sentiment         分析市场观点

Examples:
  # Extract assets from text
  python tool_client.py --tool extract_assets --text "分析下茅台"

  # Search for investment information
  python tool_client.py --tool investment_search_pro --query "宁德时代 2025年业绩"

  # Get asset overview
  python tool_client.py --tool get_asset_overview --symbol 600519.SH

  # Analyze technical indicators
  python tool_client.py --tool analyze_technical --symbol 600519.SH

  # Full deep analysis (bash)
  for tool in analyze_fundamentals_financial analyze_fundamentals_valuation analyze_technical analyze_capital_flow analyze_market_sentiment; do
    python tool_client.py --tool $tool --symbol 600519.SH
  done
        """,
    )

    parser.add_argument("--tool", required=True, choices=AVAILABLE_TOOLS, help="Tool name")
    parser.add_argument("--symbol", help="Stock symbol (e.g., 600519.SH,务必带上symbol后缀)")
    parser.add_argument("--text", help="Text input for extract_assets")
    parser.add_argument("--query", help="Query text for investment_search_pro")
    parser.add_argument("--timeout", type=float, default=300.0, help="Request timeout in seconds")
    parser.add_argument("--output", default="text", choices=["text", "json"], help="Output format")
    parser.add_argument("--indent", type=int, default=2, help="JSON indent level")

    args = parser.parse_args()

    try:
        api_url, api_token = get_api_config()
    except ValueError:
        parser.error("TOOL_API_TOKEN is required. Set via environment variable or in .env file")

    # 构建参数
    params = {}
    if args.tool == "extract_assets":
        if not args.text:
            parser.error("--text is required for extract_assets tool")
        params["text"] = args.text
    elif args.tool == "investment_search_pro":
        if not args.query:
            parser.error("--query is required for investment_search_pro tool")
        params["query"] = args.query
    else:
        if not args.symbol:
            parser.error("--symbol is required for analysis tools")
        params["symbol"] = args.symbol

    try:
        result = call_tool(args.tool, params, api_url, api_token, args.timeout)

        if args.output == "json":
            print(json.dumps(result, indent=args.indent, ensure_ascii=False))
        else:
            print(result.get("result", json.dumps(result)))

    except requests.RequestException as e:
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()


path: references/tool-specs.md
content: # tool 工具接口规范

本文档定义投资研究 tool 工具的接口规范。

> **重要**：所有 tool 工具都是 **LLM 工作流**，输出为结构化文本（Markdown），而非纯 JSON。

---

## 通用规范

### 工具分类

| 类别 | 工具 | 用途 |
|------|------|------|
| 基础工具 | `extract_assets` | 从文本提取资产 |
| 基础工具 | `investment_search_pro` | 检索专业投资信息 |
| 快速概览 | `get_asset_overview` | 获取资产核心逻辑和主要矛盾 |
| 单维度分析 | `analyze_*` | 深度分析单个维度 |
| 深度分析 | 5 个 `analyze_*` 并行 | 完整投资研究报告 |

### 调用方式

```python
# 工具调用示例
result = await tool.call_tool("get_asset_overview", {
    "symbol": "600519.SH"
})
```

### 返回格式

**单维度分析工具**返回 Markdown 文本，包含：

```markdown
[公司名称]

[一句话总结 + 核心数据]

[4 个带 emoji 的关键发现]
💰 发现1
🌍 发现2
📉 发现3
🔧 发现4

1. **[详细分析1]**。具体内容...
2. **[详细分析2]**。具体内容...
3. **[详细分析3]**。具体内容...
4. **[详细分析4]**。具体内容...
```

### 错误处理

| 错误类型 | 返回内容 |
|----------|----------|
| 股票代码无效 | `⚠️ 股票代码 [code] 不存在或格式错误` |
| 数据暂不可用 | `⚠️ [维度] 数据暂不可用，请稍后重试` |
| 网络错误 | `⚠️ 数据获取失败: [错误信息]` |

---

## 0. 资产提取 `extract_assets`

### 功能
从任意文本中提取金融资产名称和代码，用于识别用户意图中的分析对象。

### 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `text` | string | 是 | 用户输入的原始文本 |

### 输出结构

```json
{
  "success": true,
  "assets": [
    {
      "name": "宁德时代",
      "symbol": "300750.SZ",
      "market": "A股",
      "confidence": 0.95
    }
  ],
  "ambiguous": [],
  "suggestions": []
}
```

### 输出字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `assets` | array | 识别到的资产列表 |
| `assets[].name` | string | 资产名称（标准化） |
| `assets[].symbol` | string | 股票代码 |
| `assets[].market` | string | 市场类型：A股/港股/美股/基金 |
| `assets[].confidence` | float | 识别置信度 (0-1) |
| `ambiguous` | array | 歧义资产（需用户确认） |
| `suggestions` | array | 推荐的资产（如用户输入简称） |

### 输出示例

**输入**: "帮我分析下宁王和茅台的技术面"

```json
{
  "success": true,
  "assets": [
    {
      "name": "宁德时代",
      "symbol": "300750.SZ",
      "market": "A股",
      "confidence": 0.92,
      "alias": "宁王"
    },
    {
      "name": "贵州茅台",
      "symbol": "600519.SH",
      "market": "A股",
      "confidence": 0.98
    }
  ],
  "ambiguous": [],
  "suggestions": []
}
```

**输入**: "比亚迪怎么样"

```json
{
  "success": true,
  "assets": [
    {
      "name": "比亚迪",
      "symbol": "002594.SZ",
      "market": "A股",
      "confidence": 0.95
    }
  ],
  "ambiguous": [],
  "suggestions": [
    {
      "name": "比亚迪股份",
      "symbol": "1211.HK",
      "market": "港股",
      "note": "港股比亚迪，如需分析港股请明确"
    }
  ]
}
```

**输入**: "今天大盘怎么样"（无明确资产）

```json
{
  "success": true,
  "assets": [],
  "ambiguous": [],
  "suggestions": [],
  "hint": "未识别到具体股票，可询问用户想分析哪只股票"
}
```

### 处理逻辑

| 情况 | 处理方式 |
|------|----------|
| 无资产 | 询问用户想分析哪只股票 |
| 单资产 + 高置信度(>0.8) | 直接使用，继续分析流程 |
| 单资产 + 低置信度(<0.8) | 确认资产名称是否正确 |
| 多资产 | 询问分析哪一只，或触发行业对比模式 |
| 存在歧义资产 | 展示选项让用户确认 |

### 支持的资产类型

| 类型 | 识别模式 | 示例 |
|------|----------|------|
| A股 | 6位数字代码、公司名称、简称、别名 | 600519、贵州茅台、茅台、茅王 |
| 港股 | 数字代码+.HK、公司名称 | 00700.HK、腾讯控股 |
| 美股 | 英文代码、公司名称 | AAPL、苹果 |
| 基金 | 基金代码、基金名称 | 110022、易方达消费行业 |

---

## 1. 投资信息检索 `investment_search_pro`

### 功能
从新闻/研报/公众号等公开信息中获取专业的金融类信息内容，用于理解市场动态、公司事件、行业趋势等。

### 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `query` | string | 是 | 用于检索的文本 |

### 输出结构

```json
{
  "success": true,
  "result": [
    {
      "title": "文档标题",
      "content": "文档内容",
      "effectiveTime": "文档创建时间"
    }
  ]
}
```

### 输出字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `title` | string | 文档标题 |
| `content` | string | 文档内容 |
| `effectiveTime` | string | 文档创建的时间 |

### 输出示例

**输入**: query="宁德时代 2025年业绩"

```json
{
  "success": true,
  "result": [
    {
      "title": "宁德时代2025年Q3财报解读：储能业务爆发",
      "content": "宁德时代发布2025年第三季度财报...",
      "effectiveTime": "2025-10-30"
    },
    {
      "title": "全球动力电池市场格局分析",
      "content": "根据最新数据，宁德时代市场份额...",
      "effectiveTime": "2025-11-15"
    }
  ]
}
```

### 使用场景

| 场景 | 调用方式 |
|------|----------|
| 用户询问公司最新动态 | `investment_search_pro` → 搜索相关新闻和研报 |
| 用户询问行业趋势 | `investment_search_pro` → 搜索行业分析报告 |
| 用户询问市场事件 | `investment_search_pro` → 搜索相关事件报道 |

---

## 2. 快速资产概览 `get_asset_overview`

### 功能
获取资产的**核心逻辑和主要矛盾**，用于快速分析场景。一次性输出投资该资产最关键的信息，帮助用户快速决策是否值得深入研究。

### 输入参数

| 参数 | 类型 | 必填 |说明                |
|------|------|------|-------------------|
| `symbol` | string | 是 | 股票代码（如 600519.SH） |

### 输出结构

```markdown
[公司名称] - 快速概览

## 核心逻辑
[2-3 句话说明投资该资产的核心逻辑]

## 主要矛盾
[当前面临的主要多空因素]

## 关键数据
| 指标 | 数值 | 评价 |
|------|------|------|
| 营收增速 | X% | [评价] |
| ROE | X% | [评价] |
| PE | X | [评价] |
| 技术趋势 | [多/空/震荡] | [评价] |

## 投资建议
- **投资倾向**: [偏多/中性/偏空]
- **适合人群**: [长期投资者/短期交易者/观望]
- **核心风险**: [1-2 个主要风险]

---
*如需更详细分析，可以说"给我深度分析"*
```

### 输出示例

**输入**: symbol="300750.SZ"

```markdown
宁德时代 - 快速概览

## 核心逻辑
全球动力电池龙头，储能业务高增驱动业绩创新高。技术壁垒深厚（钠电池、587Ah电芯），全球化产能布局加速（匈牙利工厂），当前估值处于历史中枢，具备长期配置价值。

## 主要矛盾
**多头因素**：
- 储能出货占比提升至 20%，AI 数据中心需求爆发
- Q3 单季净利率 19.1% 创历史新高
- 技术领先优势持续巩固

**空头因素**：
- 美国IRA法案对海外市场拓展的限制
- 行业产能过剩导致价格竞争
- 地缘政治风险

## 关键数据
| 指标 | 数值 | 评价 |
|------|------|------|
| 营收增速 | +12.9% | 稳健增长 |
| 净利增速 | +36.2% | 超预期 |
| ROE | 18.5% | 优秀 |
| PE-TTM | 19.5x | 合理 |
| 技术趋势 | 震荡偏多 | 等待突破 |

## 投资建议
- **投资倾向**: 偏多
- **适合人群**: 长期投资者，能承受一定波动
- **核心风险**: 地缘政治、产能过剩导致的价格战

---
*如需更详细分析，可以说"给我宁德时代的深度分析"*
```

### 使用场景

| 场景 | 调用方式 |
|------|----------|
| 用户说"看看茅台" | `get_asset_overview` → 快速概览 |
| 用户说"茅台怎么样" | `get_asset_overview` → 快速概览 |
| 用户说"给我茅台的深度分析" | 5 个 `analyze_*` 并行 → 深度报告 |
| 用户明确指定维度 | 对应 `analyze_*` → 单维度报告 |

---

## 3. 基本面-财务 `analyze_fundamentals_financial`

### 功能
分析公司财务健康度，包括盈利能力、成长能力、偿债能力。

### 输入参数

| 参数 | 类型 | 必填 |说明                |
|------|------|------|-------------------|
| `symbol` | string | 是 | 股票代码（如 600519.SH） |

### 输出结构

```markdown
[公司名称]

[一句话总结营收/利润/增速 + 核心财务数据]

💰 [营收数据] **同比+X%**，归母净利 **同比+/-X%**
🌍 [业务亮点] 如出口增长、新业务进展
📉 [压力因素] 如国内销量下滑、成本上升
🔧 [应对措施] 如研发攻坚、产能扩张

1. **[营收增长但盈利承压]**。详细分析...
2. **[业务转型/扩张]**。详细分析...
3. **[财务健康度评估]**。详细分析...
4. **[未来展望]**。详细分析...
```

### 输出示例

```markdown
比亚迪

比亚迪2025年Q3营收同比增长12.75%至5662.66亿元，但归母净利润同比下降7.68%至23.33亿元，出口高增难抵国内销量下滑与技术瓶颈压力

💰 Q3营收5662.66亿元 **同比+12.75%**，归母净利23.33亿元 **同比-7.68%**，累计净利润同比下滑7.55%
🌍 **出口强劲增长** 1-11月海外销量91.7万辆（同比+153.6%），11月单月出口13.2万辆创历史新高
📉 **国内销量承压** 王传福坦言技术领先度不及前几年，行业同质化加剧，11月本土销量同比-27%
🔧 **技术攻坚启动** 12万工程师团队聚焦低温快充等痛点，预告将发布重磅技术重塑竞争优势

1. **营收增长但盈利承压，出口成核心驱动力**。Q3营收5662.66亿元，同比增长12.75%，主要受益海外市场爆发...
2. **技术瓶颈制约国内表现**。董事长王传福在股东会直言当前技术领先度不足...
3. **高端化战略调整见效**。方程豹品牌凭借钛7车型单月销量达3.7万辆...
4. **产能国际化加速**。泰国工厂7万辆整车下线，巴西/匈牙利工厂投产在即...
```

---

## 3. 基本面-估值 `analyze_fundamentals_valuation`

### 功能
分析公司估值水平，包括 PE/PB/PS 历史分位、估值合理性判断。

### 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `symbol` | string | 是 | 股票代码（必须带市场后缀） |

### 输出结构

```markdown
[公司名称]

[一句话估值结论]

📉 PE/PB/PS历史分位数据
💰 股息率/盈利因子排名
🚀 基本面边际变化
⚖️ 前瞻估值对比

[小标题：估值核心结论]

1. **[估值位置分析]**。PE/PB/PS 历史分位详细数据...
2. **[基本面信号]**。动销/订单/业绩变化...
3. **[盈利质量评估]**。ROE/股息率/排名...
4. **[估值修复逻辑]**。均值回归空间分析...
```

### 输出示例

```markdown
五粮液

PE/PB/PS均处历史底部1%分位以下，前瞻PE稳定且春节动销超预期，估值修复空间显著

📉 PE/PB/PS历史分位均低于**2%**，处近十年估值最底部区间。
💰 股息率1.83%优于全市场67%公司，盈利因子排名全A前**1.5%**彰显护城河。
🚀 春节动销同比增**超20%**，渠道库存降至1个月健康水平，基本面边际改善。
⚖️ 前瞻PE14-15倍低于行业中枢，批价/收入比创17年新低现价值洼地。

绝对估值历史底部，动销改善催化修复

1.截至2026年3月7日，五粮液PE-TTM仅13.98倍，处于历史**1.93%**极端低位...
2.基本面出现积极信号:春节动销同比增长超20%，开瓶扫码量翻倍...
3.盈利质量坚实:盈利因子排名全A股前1.51%，ROE稳定性领先行业...
4.估值修复动力明确:当前批价780元对应人均可支配收入比值仅17%...
```

---

## 4. 技术面 `analyze_technical`

### 功能
分析股价技术形态，包括均线系统、MACD/KDJ 指标、布林带、量价关系。

### 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `symbol` | string | 是 | 股票代码（必须带市场后缀） |

### 输出结构

```markdown
[公司名称]

[日期]股价[位置描述]，[均线/指标状态]，[量能描述]，[趋势判断]

当前[公司名称]技术面呈现典型的『[形态描述]』结构，[操作建议]。具体分析如下:
- **均线系统**: [5/10/20/60日均线状态]
- **MACD指标**: [MACD/DIF/DEA状态及信号]
- **KDJ指标**: [KDJ值及超买超卖判断]
- **布林带形态**: [上下轨/中轨/带宽/突破状态]
- **量价关系**: [成交量变化及资金流向]
综合判断:[操作建议及关键位置]
```

### 输出示例

```markdown
新奥股份

3月11日股价在21.29附近企稳，5日均线向上拐头，MACD金叉动能增强，KDJ超卖区反弹，布林带收口后价格突破中轨，量能温和放大，显示短期反弹动能正在形成，但上方压力仍存。

当前新奥股份（600803.SH）技术面呈现典型的『筑底反弹+趋势修复』结构，适合择机布局。具体分析如下:
- **均线系统**:5日均线（21.43）略高于当前股价（21.29），且呈向上拐头趋势；10日均线（21.62）与20日均线（20.60）形成金叉雏形...
- **MACD指标**:MACD值0.20，DIF（0.48）与DEA（0.38）形成金叉，柱状线虽未大幅放大，但动能持续抬升...
- **KDJ指标**:当前KDJ值18.29，处于超卖区域，但近期连续三日从低位回升...
- **布林带形态**:布林带上下轨分别为23.31和17.89，当前价格位于中轨（约20.6）附近，带宽明显收窄...
- **量价关系**:近两日成交量维持在19万手以上，较前期低谷放大数倍...
综合判断:当前股价处于关键支撑位之上，技术面共振向上，建议在股价有效突破10日均线（21.62）并伴随成交量放大时，确认买入信号...
```

---

## 5. 资金面 `analyze_capital_flow`

### 功能
分析资金流向，包括主力资金、北向资金、融资融券、大单/超大单结构。

### 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `symbol` | string | 是 | 股票代码（必须带市场后缀） |

### 输出结构

```markdown
[公司名称]

[日期][公司名称]资金面呈现[主力资金状态]、[融资融券状态]、[趋势判断]

总体来看，[公司名称]当前资金面[整体判断]，[操作建议]。具体分析如下:
- **资金净流入与主力动向**: [整体资金流向及主力行为]
- **大单与超大单结构**: [大单/超大单净流入数据]
- **趋势与技术面支撑**: [股价位置与均线支撑]
- **杠杆资金风险敞口**: [融资融券数据及风险判断]
- **价格影响量化推演**: [资金对股价的预期影响]
因此，[操作建议及关键观察点]
```

### 输出示例

```markdown
联科科技

3月11日主力资金持续净流入但市场整体资金净流出，呈现'内强外弱'的结构性资金博弈格局，股价面临短期回调压力，但主力护盘意图明显，具备逢低布局潜力。

总体来看，联科科技当前资金面呈现'主力逆势吸筹、散户资金撤离'的分化结构，虽整体资金净流出7446.16万元，但主力资金净流入6312.62万元（占净流入额21.46%），超大单净流入高达6473.15万元，显示核心资金仍在积极建仓。具体分析如下:
- **资金净流入与主力动向背离**:整体资金净流出7446万，反映市场情绪偏谨慎或抛压集中；但主力净流入6312万且占比21.46%...
- **大单与超大单结构分化**:大单净流出160万，表明中小资金或散户在离场；而超大单净流入6473万...
- **趋势与技术面支撑**:当前股价位于20日均线附近，60日均线呈下行但斜率缓和...
- **杠杆资金风险敞口可控**:融资余额未提供最新值，但若维持稳定或小幅增长...
- **价格影响量化推演**:基于历史资金-股价回归模型，当前主力净流入对股价的正向驱动效应约为+1.8%...
因此，建议投资者在股价回踩至20日均线或布林带下轨（约30.5元）时择机分批布局...
```

---

## 6. 市场观点 `analyze_market_sentiment`

### 功能
汇总分析师评级、研报观点、市场舆情。

### 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `symbol` | string | 是 | 股票代码（必须带市场后缀） |

### 输出结构

```markdown
[公司名称]

[一句话市场观点总结]

📊 [分析师评级分布]
💰 [一致目标价及上涨空间]
⚠️ [核心风险提示]
🚀 [催化剂/利好因素]

[小标题：市场共识核心观点]

1. **[机构观点1]**。详细内容...
2. **[机构观点2]**。详细内容...
3. **[舆情分析]**。详细内容...
4. **[风险与机会]**。详细内容...
```

---

## 维度关键词映射

用于识别用户查询意图，调用对应的 tool 工具：

| 关键词 | 对应维度 | tool 工具 |
|--------|----------|----------|
| 财务、盈利、ROE、利润、营收、净利 | 基本面-财务 | `analyze_fundamentals_financial` |
| 估值、PE、PB、PS、贵不贵、便宜、估值分位 | 基本面-估值 | `analyze_fundamentals_valuation` |
| 技术、趋势、K线、支撑阻力、走势、均线、MACD、KDJ | 技术面 | `analyze_technical` |
| 资金、主力、北向、机构、流入流出、融资融券 | 资金面 | `analyze_capital_flow` |
| 观点、研报、分析师、舆情、评级、目标价 | 市场观点 | `analyze_market_sentiment` |

---

## 调用示例

### 单维度调用

```python
# 用户输入: "分析下宁德时代的技术面"
result = await tool.call_tool("analyze_technical", {
    "symbol": "300750.SZ"
})
```

### 多维度调用（深度分析）

```python
# 用户输入: "给我茅台的深度分析"
tools = [
    "analyze_fundamentals_financial",
    "analyze_fundamentals_valuation",
    "analyze_technical",
    "analyze_capital_flow",
    "analyze_market_sentiment",
]

results = await asyncio.gather(*[
    tool.call_tool(tool_name, {"symbol": "600519.SH"})
    for tool_name in tools
])
```


path: references/tool-client-usage.md
content: # tool Client 使用指南

本指南说明如何在 OpenClaw Agent 中使用 tool Investment Research Tools 的 HTTP API 客户端。

## 快速开始

### 1. 环境配置

确保 tool 服务正在运行，并设置 API Token：

```bash
# 方法 1: 设置环境变量
export TOOL_API_TOKEN=your_token_here
```

### 2. 可用工具

| 工具名 | 用途 | 参数 |
|--------|------|------|
| `extract_assets` | 从文本提取资产 | `--text` |
| `investment_search_pro` | 检索专业投资信息 | `--query` |
| `get_asset_overview` | 获取资产快速概览 | `--symbol` (必带后缀) |
| `analyze_fundamentals_financial` | 分析基本面-财务 | `--symbol` (必带后缀) |
| `analyze_fundamentals_valuation` | 分析基本面-估值 | `--symbol` (必带后缀) |
| `analyze_technical` | 分析技术面 | `--symbol` (必带后缀) |
| `analyze_capital_flow` | 分析资金面 | `--symbol` (必带后缀) |
| `analyze_market_sentiment` | 分析市场观点 | `--symbol` (必带后缀) |

**重要说明**：
- **symbol 必须带市场后缀**：
  - A股深交所（0/3开头）：`300750.SZ`
  - A股上交所（6开头）：`600519.SH`
  - 港股：`00700.HK`
- 调用 `extract_assets` 会返回带后缀的 symbol，可以直接使用

### 3. 基础调用示例

```bash
# 提取资产（返回带后缀的 symbol）
python scripts/tool_client.py --tool extract_assets --text "分析下茅台"

# 获取资产概览
python scripts/tool_client.py --tool get_asset_overview --symbol 600519.SH

# 分析技术面
python scripts/tool_client.py --tool analyze_technical --symbol 600519.SH

# 分析宁德时代
python scripts/tool_client.py --tool analyze_technical --symbol 300750.SZ
```

## 在 Agent 工作流中使用

### 示例 1: 资产提取

当用户输入"分析下茅台"时：

```bash
# Agent 执行
cd /Users/edy/.openclaw/workspace/skills/investment-research
python scripts/tool_client.py --tool extract_assets --text "分析下茅台"
```

**输出示例**：
```json
{
  "success": true,
  "assets": [
    {
      "name": "贵州茅台",
      "symbol": "600519.SH",
      "market": "A股",
      "confidence": 0.98
    }
  ],
  "ambiguous": [],
  "suggestions": []
}
```

### 示例 2: 单维度分析

```bash
# 用户: "看看茅台的技术面"
python scripts/tool_client.py --tool analyze_technical --symbol 600519.SH
```

**输出**：Markdown 格式的技术面分析

### 示例 3: 深度分析（5 维度并行）

使用 bash 并行调用多个工具：

```bash
cd /Users/edy/.openclaw/workspace/skills/investment-research

# 并行调用 5 个分析工具
tools=(
  "analyze_fundamentals_financial"
  "analyze_fundamentals_valuation"
  "analyze_technical"
  "analyze_capital_flow"
  "analyze_market_sentiment"
)

for tool in "${tools[@]}"; do
  python scripts/tool_client.py --tool "$tool" --symbol 600519.SH &
done

wait
```

## 输出格式

tool 工具返回的格式为：

```json
{
  "success": true,
  "result": "Markdown 格式的分析内容",
  "metadata": {
    "tool": "analyze_technical",
    "symbol": "600519.SH",
    "timestamp": "2024-03-15T12:00:00Z"
  }
}
```

其中 `result` 字段包含 Markdown 格式的分析内容，可以直接在报告中使用。

## 错误处理

### 常见错误

| 错误 | 原因 | 解决方法 |
|------|------|----------|
| `tool_API_TOKEN is required` | 未设置 API Token | 设置环境变量或在 .env 文件中配置 |
| `HTTP 401 Unauthorized` | Token 无效 | 检查 Token 是否正确 |
| `HTTP 404 Not Found` | API URL 错误 | 检查 tool 服务是否运行 |
| `Request timeout` | 服务响应超时 | 增加 `--timeout` 参数或检查服务状态 |
| `HTTP 500 Internal Server Error` | 服务端错误 | 检查 tool 服务日志 |

### 在 Agent 中的错误处理

Agent 在调用脚本后应检查返回值：

```bash
result=$(python scripts/tool_client.py --tool extract_assets --text "分析下茅台" 2>&1)

if echo "$result" | grep -q "Error:"; then
  # 处理错误
  echo "无法连接到 tool 服务: $result"
else
  # 处理正常结果
  echo "$result"
fi
```

## 高级用法

### 输出原始内容（非 JSON）

```bash
python scripts/tool_client.py --tool analyze_technical --symbol 600519 --output raw
```

### 自定义超时时间

```bash
python scripts/tool_client.py --tool get_asset_overview --symbol 600519 --timeout 120
```

服务默认运行在 `http://api.facaidazi.com/api/tools/call`。

## 参考资源

- **Tool 规范**: `references/tool-specs.md`
- **原客户端代码**: `../scripts/tool_client.py`


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)