公募基金升维诊断 (FundX) Skill

概述

将公募基金从传统业绩比较升维到五维一体评估（基金经理、费率、持有人、公司、合同）。排除明显有风险的产品，不预测未来业绩。

• 英文名：FundX（短标识）
• Slug：fundx（全小写，无连字符）
• 包名：fundx
• 命令示例：fundx diagnose 161005
• URL 示例：/fundx 或 fundx.diagnosis

触发条件

当用户提出以下意图时触发：

• "分析/诊断/评测某只基金"
• "看看基金XXX怎么样"
• "基金代码XXX，帮我评估一下"
• "推荐基金/选基金（需要后续需求澄清）"

完整诊断流程

Step 0: 首次运行 — 生成脚本（一次性）

Skill 包中不含 scripts/ 目录（避免 .pyc 缓存问题）。首次诊断前，按以下代码清单创建完整的 Python 脚本树：

1. 在 skill 目录下创建 scripts/ 及其子目录（参考下方目录结构），然后将完整的 Python 源代码写入各文件。

> 💡 源代码可从创建此 Skill 的原始对话中获取，或自行按 config/ 中的阈值和模块规范编写实现。

1. 验证：在 skill 目录下执行 python -c "from scripts.main import diagnose; print('OK')"，不报错即成功。

> 后续再次使用 Skill 时无需重复生成，除非要更新代码。

Step 1: 需求澄清（若输入宽泛）

若用户未提供具体基金代码（如"推荐一只ETF"、"有什么好基金"），引导用户选择：

• 基金类型：股票型/混合型/债券型/货币型/QDII/商品/FOF
• 风险偏好：激进/稳健/保守
• 持有期限：短期/中期/长期
• 偏好风格：大盘价值/大盘成长/小盘/无偏好

使用 AskUserQuestion 工具收集偏好。

Step 2: 准备基金数据

通过以下方式之一获取基金数据：

方式A：使用 neodata-financial-search Skill 查询

1. 加载 Skill("neodata-financial-search") 或 Skill("westock-data")
2. 使用金融数据搜索技能获取基金净值、基准、规模、持仓、费率等数据

方式B：手动构建基金数据对象（数据有限时）

构建符合以下结构的 dict：

fund_data = {
    "basic": {"fund_code", "fund_name", "fund_type_l1", "fund_type_l2", "found_years", "fund_size", ...},
    "nav_series": [{"date", "acc_nav"}, ...],
    "benchmark_series": [{"date", "value"}, ...],
    "return_history": {"2023": {"fund_return", "bench_return", "excess", "rank_percentile"}, ...},
    "quarterly_excess": [{"quarter", "excess"}, ...],
    "fee_structure": {...},
    "holder_structure_history": {...},
    "style_box_history": [...],
    "manager_history": {...},
    "company_info": {...},
    "contract": {...},
    ...
}

数据缺失处理：所有缺失字段必须按标准化降级规则处理（参见 config/missing_handlers.yaml），不得导致程序异常。

Step 3: 运行诊断（脚本生成后）

确保 scripts/ 目录已生成（见 Step 0），然后执行：

# 使用主入口
from scripts.main import diagnose

report_markdown = diagnose(fund_code="000001", fund_data=None, output_format="markdown")
report_json = diagnose(fund_code="000001", fund_data=None, output_format="json")

若已有 fund_data 对象：

report = diagnose(fund_data=fund_data, output_format="markdown")

Step 4: 呈现报告

• Markdown格式：调用 preview_url 或 open_result_view 呈现
• JSON格式：通过 deliver_attachments 交付给用户
• 报告中的预警标签按优先级排列：🔴 > 🟡 > 🟢 > ℹ️

模块化架构

Skill 包中仅包含配置文件和引用文档，Python 脚本由 Step 0 首次运行时生成：

fundx/
├── SKILL.md                  # 本入口文件（含完整脚本代码清单）
├── config/                   # 配置文件（YAML）
│   ├── fund_types.yaml       # 基金类型层级及模块启用
│   ├── thresholds.yaml       # 各指标阈值
│   ├── style_switch_years.yaml # 风格切换年列表
│   └── missing_handlers.yaml # 缺失数据降级规则
└── references/
    └── beginner-guide.md     # 新手使用指南

扩展指南

脚本生成后即可修改。所有修改均在 scripts/ 目录下进行：

新增模块

1. 在 scripts/modules/ 下创建 module_{id}_{name}.py
2. 实现 run(fund_data) -> dict 接口（返回 {"score", "tags", "details"}）
3. 在文件末尾调用 register_module(id, name, run, is_tag_only)
4. 在 scripts/main.py 顶部 import 该模块

新增基金类型

1. 在 config/fund_types.yaml 中添加一级/二级分类
2. 在 config/thresholds.yaml 中添加该类型的阈值
3. 在 scripts/scoring/weights.py 中配置权重
4. 在对应二级分类的 enabled_modules 列表中配置启用模块

修改评分规则

• 权重调整：修改 scripts/scoring/weights.py 中的 DEFAULT_WEIGHTS
• 阈值调整：修改 config/thresholds.yaml
• 模块内部逻辑：直接修改对应 scripts/modules/module_{id}.py

新手引导

当用户表现出以下迹象时，将 references/beginner-guide.md 作为用户指南提供参考：

• 首次使用该工具或询问"怎么用"
• 询问报告中的某个颜色/等级的含义
• 说不清自己的需求或不知道基金代码
• 对"推荐/谨慎/拒绝"等级或"🔴/🟡/🟢"标签的含义有疑问
• 问"为什么评分会变""未披露是什么意思"等 FAQ 问题

指南中的三原则应直接传达给用户：

1. 🔴 红色标签一票否决 → 直接跳过
2. ❌ 拒绝等级不买 → 哪怕是朋友推荐的也不买
3. ⚠️ 评分只是参考 → 边界的分数要结合明细看

注意事项

• 数据依赖：所有缺失数据必须走标准化降级逻辑（config/missing_handlers.yaml），不得抛出异常
• 同类比较：所有与"同类"比较均基于三级分类池（level1 → level2 → style）
• 一票否决：硬性初筛（模块0.5）不通过或利益绑定（模块2）触发强制淘汰时，直接输出拒绝报告
• 报告时效：报告数据截止日期为生成日的最新公开信息（季报延迟15-90天）
• 核心原则：先人后费率、交叉验证、数据驱动