FRED Navigator

目的

提供一套可靠的流程，用于浏览 FRED 的分类（categories）与序列（series），支持以下三种方式：

1. 直接指定 category_id
2. 直接指定 series_id
3. 使用自然语言 query → 意图识别 → 双重验证

输入参数

• category_id：FRED 分类 ID
• series_id：FRED 序列 ID
• query：自然语言请求
• limit：返回候选结果的数量（默认为 5）
• api_key：仅从环境变量 FRED_API_KEY 中读取

必需资源

• references/fred_categories_tree.json
• references/fred_categories_flat.json
• 可选：references/category_paths.json（预计算路径）
• 可选：references/synonyms.json
• 辅助脚本：scripts/fred_query.py
• 路径构建器：scripts/build_paths.py

可选资源结构说明

• references/category_paths.json 格式：
  • { "category_id": { "id": , "name": "", "path": "" }, ... }
• references/synonyms.json 格式：
  • { "concept": ["alias1", "alias2", ...], ... }

工作流

1. 分类探索

1. 加载 fred_categories_tree.json 以支持层级化浏览。
2. 若用户提供 category_id，需验证其是否存在。
3. 若用户提供 category_name，则在 flat 名称列表中进行模糊匹配，并返回候选结果。

2. 序列发现

1. 调用 search_by_category(category_id) 列出该分类下所有可用的序列。
2. 推荐统一使用 scripts/fred_query.py category 获取一致格式的输出。
3. 返回关键字段：
   • id、title、frequency、units、seasonal_adjustment、last_updated

3. 序列获取

1. 调用 get_series(series_id) 获取时间序列数据。
2. 调用 get_series_info(series_id) 获取元数据信息。
3. 推荐分别使用 scripts/fred_query.py series 和 scripts/fred_query.py series-info 。
4. 应提供以下内容：
   • 数据首尾若干行（head/tail）
   • 缺失值统计（missing counts）
   • 最新数值及其对应日期（latest value and date）

4. 自然语言查询

4.1 意图识别（Top-K）

1. 使用 IDE agent（Codex）解析自然语言查询的意图。
2. 从中选出最匹配的单一分类。
3. 若置信度较低，则需向用户确认所选分类后，再继续后续流程。
4. 如有可用，可将 references/category_paths.json 和 references/synonyms.json 作为上下文辅助判断。

4.2 双重验证

结构验证

• 候选分类必须存在于 fred_categories_tree.json 中。
• 满足以下任一条件即视为通过：
  • children 字段非空
  • search_by_category(id) 返回至少 1 个序列
  • 推荐使用 scripts/fred_query.py check-category 快速校验

语义验证（由 agent 执行）

• 将 query 与候选分类的 name 或 path 进行比对。
• 返回 pass/fail 或一个数值型相关性得分（relevance score）。

4.3 决策逻辑

• 若结构验证与语义验证均通过 → 接受该分类。
• 否则：
  • 返回 Top-5 候选分类
  • 明确提示用户从中选择一个

异常处理

• 在任何不确定情形下，始终提供 Top-5 候选结果。
• 若分类验证失败，则禁止进入序列获取阶段。

注意事项

• 切勿硬编码 API 密钥（API keys）。
• 将体积较大的参考数据保留在 references/ 目录中，而非本文件内。
• 执行 Python 查询函数时，须在 sandbox 环境中运行。

维护指南

• 更新工作流或约束条件：编辑 SKILL.md。
• 更新分类数据：替换 references/ 目录下的对应文件。
• 优化自然语言匹配能力：增补或修改 references/synonyms.json（键为概念名，值为相关术语列表）。
• 重新生成预计算路径（可选）：运行 scripts/build_paths.py。
• 新增辅助脚本（可选）：置于 scripts/ 目录下，并在此处补充说明其用途。