Args:
    limit: 返回最近 N 次导入记录（默认 20，最大 200）

Returns:
    {imports: [{id, broker, file_name, imported_rows, skipped_rows,
                total_rows, first_date, last_date, created_at}...]}

Args:
    start_date: 起始日期 YYYY-MM-DD（含）
    end_date: 结束日期 YYYY-MM-DD（含）
    broker: 券商标识筛选（默认全部）

Returns:
    {buy: {...}, sell: {...}, total_trades, distinct_symbols, first_date, last_date}

Args:
    file_path: 券商导出的交割单/对账单 CSV 文件绝对路径
    broker: 券商标识，可选 htsc / citic / cms / gtja / generic；
            默认 auto 自动按表头特征识别（无法确定时按 generic 处理）

Returns:
    {
      import_id, broker, file_name,
      total_rows, imported_rows, duplicated_rows, skipped_rows,
      first_date, last_date, warnings, hint
    }
    重复导入同一文件时返回 imported_rows=0 并提示已存在。

Args:
    start_date: 起始日期 YYYY-MM-DD（含）
    end_date: 结束日期 YYYY-MM-DD（含）
    symbol: 按证券代码模糊筛选（如 600519）
    side: 买卖方向筛选，可选 buy / sell / other / unknown
    broker: 券商标识筛选，可选 htsc / citic / cms / gtja / generic
    limit: 返回条数上限（默认 200，最大 2000）

Returns:
    {total: n, trades: [{id, trade_date, trade_time, side, symbol,
                         symbol_name, price, quantity, amount, fee,
                         net_amount, broker, contract_no}...]}

用于导入前确认券商格式兼容性；返回各券商典型列名与标准化字段对照。

Returns:
    {brokers: [{id, name, sample_columns}], standard_fields: {...}, note}

放弃当前进行中的 Socratic 辅导会话并归档。

Args:
    session_id: 要放弃的会话 ID

Returns:
    dict: 包含 final_summary 的归档结果

对比当前新事件与历史情景的变量结构异同。

从情景库中取出指定历史事件，用 LLM 对比分析：
- 相同点是什么
- 核心差异是什么
- 上次的教训是否适用于本次

Args:
    event: 当前新事件的描述（如"美联储降息50bp"）
    scenario_id: 要对比的历史情景 ID（从 list_coaching_scenarios 获取）

Returns:
    dict: {"status":"success", "comparison": "..."}

当用户判断错误后，更新投研规则中的变量优先级。

输入上次判断错误的变量和实际正确结果，
LLM 会分析并给出变量优先级调整建议——下次遇到类似结构，
哪个变量该调高、哪个该调低。

Args:
    wrong_variable: 未按预期变化的变量（如"黄金与美元同涨"）
    correct_result: 实际发生的正确结果（如"黄金独立上涨，美元回落"）

Returns:
    dict: {"status":"success", "iteration": "..."}

根据用户过去的交易记录，建议触发深度分析的数值阈值。

对于指定的资产类别（如"利率"、"汇率"、"商品"），
LLM 会分析多大的变动幅度应该触发深度分析，
给出具体数值阈值建议并说明理由。

Args:
    asset_class: 资产类别，如"利率"、"汇率"、"商品"、"A股"、"美股"

Returns:
    dict: {"status":"success", "suggestion": "..."}

将进行中的 Socratic 多轮辅导会话切换到简单模式。

放弃剩余的问答题，直接用已有的分析上下文走一遍
10 步标准投研模板输出，并正常归档到情景库。

Args:
    session_id: 由 start_coaching 返回的会话 ID

Returns:
    dict: simple 模式结果，含 answer 和 scenario_id

继续一个进行中的 Socratic 多轮辅导会话。

回复选项字母 (A/B/C/D) 来推进对话，或输入
「直接说」切换到简单模式、「别问了」放弃本轮。

Args:
    session_id: 由 start_coaching 返回的会话 ID
    user_input: 用户对当前问题的回答（选项字母或指令文本）

Returns:
    dict: 下一轮问题或最终结果

列出最近的学习辅导情景记录。

每次辅导结束（无论是简单模式还是复杂模式）都会自动归档到情景库，
包括触发事件、变量结构、因果链和最终结论。

Args:
    limit: 返回的记录数量，默认 20

Returns:
    dict: {"count": N, "scenarios": [...]}

启动学习辅导，分析投资问题。

自动判断问题是简单还是复杂：
- 简单问题（如"该不该买XX"）→ 直接输出 10 步标准投研分析
- 复杂问题（如"为什么XX和YY走势背离"）→ 启动 Socratic 多轮引导对话

Args:
    user_input: 用户提出的投资问题（如"茅台2000块值得买吗"）
    mode: 强制模式，"simple" 或 "complex"，留空则自动判断

Returns:
    simple 模式: {"status":"success", "mode":"simple", "answer": "...", "scenario_id":"..."}
    complex 模式: {"status":"success", "mode":"complex", "session_id":"...", "question":"...", "options":[...]}

投资大师圆桌讨论。

自动语义匹配 3-5 位最相关的投资大师，模拟结构化深度对话。
每位大师独立调用 LLM 生成观点，主持人综合交锋并生成结构化纪要。

Args:
    topic: 投资议题（如 "贵州茅台当前估值合理吗？"）

Returns:
    dict: 含 scene / masters / rounds / verdict 的结构化圆桌纪要

Get constituent stocks of an index (CSI300, etc).
Note: Simplified - returns basic info from Sina.

Args:
    index_code: Index code (e.g., "000300" for CSI 300, "000001" for Shanghai)

Returns:
    dict: Index name and current value

Get overall market sentiment indicators.
Returns Shanghai Composite as a proxy for market sentiment.

Returns:
    dict: Index value, change %, sentiment reading

Get historical K-line data for a stock.

Args:
    ticker: Stock ticker symbol (e.g., "600519")
    period: K-line period - "daily", "weekly", "monthly" (default: "daily")

Returns:
    dict: OHLCV data with date, open, high, low, close, volume

Get real-time quote for a stock ticker.

Args:
    ticker: Stock ticker symbol (e.g., "600519", "sh600519", "贵州茅台")

Returns:
    dict: Current price, change %, volume

Get valuation data for a stock.
Note: Sina provides limited fundamental data - returns price-based metrics.

Args:
    ticker: Stock ticker symbol (e.g., "600519")

Returns:
    dict: Price-based valuation info

Get identified behavior patterns from user's investment history.

Returns:
    list: Behavior patterns like "tends to buy on price drops", "stops loss too early"

Get user investment profile.

Returns:
    dict: User profile including risk preference, circle of competence, investment principles

Record an investment decision made by the user.

Args:
    data: Decision data including ticker, action (buy/sell/hold), price, reason, timestamp

Returns:
    dict: Confirmation of recorded decision

Configure a notification channel.

Args:
    channel: Notification channel name. Supported: feishu, dingtalk, bark, pushplus
    webhook_url: Webhook URL for webhook-based channels (feishu / dingtalk / bark)
    token: PushPlus token (only used when channel="pushplus")
    enabled: Whether to enable this channel (default True)
    send_test: Whether to immediately send a test message (default False)

Returns:
    dict: Current configuration status for all channels, plus test result if requested

Get the current notification configuration for all channels.

Returns:
    dict: Configuration status for all channels, e.g.:
        {"channels": {"feishu": {...}, "dingtalk": {...}, "bark": {...}, "pushplus": {...}}}

Generate a behavior pattern report in Markdown format.

Args:
    period: Report period — "weekly" (default) or "monthly"

Returns:
    dict: Report path and full Markdown content

Get cumulative summary of all detected behavior patterns.

Returns:
    dict: Pattern type -> {count, last_seen}, plus prompt_hint for
          the agent to decide whether to proactively engage the user

Run behavior pattern detection on all recorded decisions and thoughts.

Detects: 追高, 过早卖出, 情绪化交易, 原则违反.
Results are saved to the behavior_patterns table.

Returns:
    dict: Detection results with count and pattern list

Ask an investment question and get RAG-augmented answer.

Args:
    question: Investment question (e.g., "什么是护城河？")

Returns:
    dict: Answer with source citations from master knowledge base

Get a specific master's view on a topic.

Args:
    master: Master name (e.g., "巴菲特", "芒格", "段永平")
    topic: Topic to query (e.g., "护城河", "安全边际")

Returns:
    dict: Master's view on the topic with citations

返回最近入库的券商研报摘要，包含机构、股票、行业、评级、盈利预测等信息。

Args:
    query: 搜索关键词（如"宁德时代 业绩"、"保险 增长"、"半导体"）
    top_k: 返回结果数量，默认5

Returns:
    {
        "query": str,
        "count": int,
        "results": [
            {
                "info_code": str,
                "title": str,
                "org_name": str,
                "stock_name": str,
                "stock_code": str,
                "industry_name": str,
                "rating": str,
                "rating_change": str,
                "publish_date": str,
                "text": str,
                "distance": float,
            }
        ]
    }

Search the investment knowledge base.

Args:
    query: Search query (e.g., "价值投资", "周期")

Returns:
    list: Matching knowledge entries

Delete a reminder by ID.

Args:
    id: Reminder ID to delete

Returns:
    dict: Deletion confirmation

Get all active reminders.

Returns:
    list: All active reminders

Set a reminder with trigger condition.

Args:
    condition: Reminder condition, e.g.:
        - {"type": "price", "ticker": "贵州茅台", "operator": "below", "value": 1400}
        - {"type": "time", "cron": "0 9 * * 5"}  # Every Friday 9am
        - {"type": "pe_ratio", "ticker": "贵州茅台", "operator": "below", "value": 20}

Returns:
    dict: Created reminder with ID

Generate a behavior pattern report for this week or month.
Designed to be called on a schedule by the agent (e.g. every Sunday).

Args:
    range: Report range — "week" (default) or "month"

Returns:
    dict: Compact report with summary, insights, highlight, and report file path

Get all thought cards for a specific ticker/symbol.

Args:
    ticker: Stock ticker (e.g., "贵州茅台", "AAPL")

Returns:
    list: All thought cards for this ticker

Record an investment thought/idea from the user.

Args:
    text: The raw thought text from user (e.g., "茅台跌到1400可以考虑买入")

Returns:
    dict: A thought card with parsed entities and card ID

Search user's historical thoughts and memories using semantic search.

Args:
    query: Search query (e.g., "茅台", "上次关于苹果的想法")

Returns:
    list: Matching thought cards, sorted by relevance

Check if Tushare token is configured and valid.

Returns:
    dict: Token status and user info

Convert common stock ticker to Tushare format.

Args:
    ts_code_or_ticker: Either Tushare format (600519.SH) or plain number (600519)

Returns:
    str: Tushare format code

Get balance sheet data (Tushare API: balancesheet).

Args:
    ts_code: Tushare stock code (e.g., "600519.SH")
    period: Reporting period in YYYYMMDD format

Returns:
    dict: Balance sheet data

Get cash flow statement (Tushare API: cashflow).

Args:
    ts_code: Tushare stock code (e.g., "600519.SH")
    period: Reporting period in YYYYMMDD format

Returns:
    dict: Cash flow data

Get daily price data for a stock (Tushare API: daily).

Args:
    ts_code: Tushare stock code (e.g., "600519.SH" for 贵州茅台)
             Format: {code}.{exchange} (SH=Shanghai, SZ=Shenzhen)
    start_date: Start date in YYYYMMDD format (default: 30 days ago)
    end_date: End date in YYYYMMDD format (default: today)

Returns:
    dict: OHLCV data with date, open, high, low, close, volume, amount

Get financial indicators for a stock (Tushare API: fina_indicator).

Includes: PE, PB, ROE, gross margin, etc.

Args:
    ts_code: Tushare stock code (e.g., "600519.SH")

Returns:
    dict: Financial indicators

Get income statement (P&L) for a stock (Tushare API: income).

Args:
    ts_code: Tushare stock code (e.g., "600519.SH")
    period: Reporting period in YYYYMMDD format (e.g., "20250331" for Q1 2025)

Returns:
    dict: Income statement data

Get constituent stocks of an index (Tushare API: index_weight).

Args:
    index_code: Index code (e.g., "000300.SH" for CSI 300)

Returns:
    dict: List of constituent stocks with weight

Get index daily K-line data (Tushare API: index_daily).

Args:
    index_code: Index code (e.g., "000300.SH" for CSI 300, "000001.SH" for Shanghai)
    start_date: Start date in YYYYMMDD format
    end_date: End date in YYYYMMDD format

Returns:
    dict: Index OHLCV data

Get industry classification for a stock (Tushare API: stock_basic + industry).

Args:
    ts_code: Tushare stock code (e.g., "600519.SH")

Returns:
    dict: Industry info (SW industry, Shenwan classification)

Get top gainers/losers for the day (Tushare API: top_list).

Args:
    trade_date: Trading date in YYYYMMDD format (default: today)

Returns:
    dict: Top gainers, losers, and most active stocks

Get realtime quote for a stock (Tushare API:实时行情).

Args:
    ts_code: Tushare stock code (e.g., "600519.SH")

Returns:
    dict: Current price, change %, volume, etc.

Get stock pledge (股权质押) status (Tushare API: pledge_stat).

Args:
    ts_code: Tushare stock code (e.g., "600519.SH")

Returns:
    dict: Pledge ratio and status

Get PE/PB ratios for multiple stocks over time (Tushare API: daily + basic).

Args:
    stock_list: List of Tushare stock codes (e.g., ["600519.SH", "000858.SZ"])
    start_date: Start date in YYYYMMDD format
    end_date: End date in YYYYMMDD format

Returns:
    dict: Valuation data for multiple stocks

Get weekly price data for a stock (Tushare API: weekly).

Args:
    ts_code: Tushare stock code (e.g., "600519.SH")
    start_date: Start date in YYYYMMDD format
    end_date: End date in YYYYMMDD format

Returns:
    dict: Weekly OHLCV data

首次使用前必须创建，用于留存/活跃度追踪的锚点。

Args:
    nickname: 用户昵称
    risk_profile: 风险偏好，可选 conservative / moderate / aggressive
    investment_style: 投资风格，可选 value / growth / trend / mixed
    experience_years: 投资经验年限
    goals: 投资目标列表，如 ["长期复利", "跑赢沪深300"]
    settings: 附加设置（JSON 对象），如 {"currency": "CNY", "notify_channel": "feishu"}
    user_id: 用户 ID（默认 local 单用户）

Returns:
    {created: true, profile: {...}}

Args:
    user_id: 用户 ID（默认 local）
    days: 统计窗口天数，默认 30

Returns:
    {exists, stats: {total, active_days, daily_avg, by_type, last_activity_at, active_date_list}}

Args:
    user_id: 用户 ID（默认 local）

Returns:
    {exists: true/false, profile: {...}} — profile 含昵称/风险偏好/投资风格/
    经验年限/目标/设置/创建与最近活跃时间

Args:
    user_id: 用户 ID（默认 local）

Returns:
    {exists, retention: {...}}

支持 4 类来源：framework（投资框架）、journal（交易日志）、
reading_notes（读书笔记）、insight（关键洞察，默认）。

Args:
    title: 知识标题
    content: 正文内容（将用于语义搜索的 embedding）
    tags: 标签列表，如 ["framework:gold", "strategy:tactical"]
    source_type: 来源类型，可选 framework / journal / reading_notes / insight

Returns:
    {id, title, status: "added"}

Args:
    id: 知识条目 ID（如 uk_1722000000）

Returns:
    {id, status: "deleted"}

Args:
    source_type: 按来源类型过滤（framework / journal / reading_notes / insight）
    tag: 按标签过滤（如 "framework:gold"）
    limit: 返回条目数量上限，默认 50

Returns:
    {count, items: [{id, title, tags, source_type, created_at}, ...]}

基于向量相似度检索最相关的用户知识条目。

Args:
    query: 搜索查询文本
    top_k: 返回结果数量，默认 5

Returns:
    {query, results: [{id, title, snippet, tags, score, source_type, created_at}, ...]}

只传需要修改的字段，未传的字段保持不变。

Args:
    id: 知识条目 ID（如 uk_1722000000）
    content: 新正文（可选）
    title: 新标题（可选）
    tags: 新标签列表（可选）

Returns:
    {id, status: "updated", version}

供其他工具/Agent 在关键行为后调用，用于留存与活跃度统计。

Args:
    activity_type: 事件类型，如 thought / decision / reminder / pattern / search / coaching / report
    detail: 事件说明（可选，最多 500 字）
    user_id: 用户 ID（默认 local）

Returns:
    {recorded: true/false, activity_id}

Args:
    nickname / risk_profile / investment_style / experience_years / goals / settings: 需更新的字段
    user_id: 用户 ID（默认 local）

Returns:
    {updated: true/false, profile: {...}}