Alpha 研究记录器 Skill

技能定位

本技能是 Alpha 研究流程中的数据持久化层，负责将研究过程的结构化数据保存为可追溯的日志文件。

在研究流程中的地位

code

研究流程：
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│ 知识检索/输入    │ ───▶ │  Alpha 生成/回测 │ ───▶ │   因子评估       │
│ (其他技能)       │      │  (其他技能)      │      │  (其他技能)      │
└────────┬────────┘      └────────┬────────┘      └────────┬────────┘
         │                        │                        │
         └────────────────────────┼────────────────────────┘
                                  ▼
                    ┌─────────────────────────┐
                    │  alpha-research-recorder │ ◀── 本技能
                    │  (数据持久化 + 文件管理)  │
                    └─────────────────────────┘
                                  │
                    ┌─────────────┴─────────────┐
                    ▼                           ▼
              session_metadata.yml        round_NNNN.yml
              (会话配置)                  (轮次记录)
                    │                           │
                    └─────────────┬─────────────┘
                                  ▼
                          final_summary.md
                         (最终总结报告)

记录类型

本技能支持三种独立的记录类型，按需调用，无固定顺序：

记录类型	文件格式	使用场景	输出文件	模板文件
session_meta	YAML	研究开始时记录配置和约束	`session_metadata.yml`	`templates/session_metadata.yml.template`
round	YAML	单轮研究结束后记录完整过程	`round_NNNN.yml`	`templates/round_NNNN.yml.template`
final_summary	Markdown	研究完成后生成总结报告	`final_summary.md`	`templates/final_summary.md.template`

调用方式：

•✅ 可以只调用 session_meta，不创建 round
•✅ 可以创建多个 round，延迟创建 final_summary
•✅ 可以中途补充或修改任何记录
•❌ 禁止跳过 session_meta 直接创建 round

参数规范

通用参数（所有记录类型共用）

参数	类型	必填	默认值	说明
`record_type`	`string`	是	-	记录类型：`"session_meta"` / `"round"` / `"final_summary"`
`root_dir`	`string`	否	`"logs/"`	研究日志根目录
`session_id`	`string`	是	-	会话唯一标识，格式：`YYYYMMDD_<主题>_<LLM>`

数据参数（根据 record_type 引用对应模板）

每种记录类型的完整字段定义请查看对应的模板文件：

记录类型	模板文件路径	查看方式
session_meta	`./templates/session_metadata.yml.template`	包含注释说明哪些是必填字段
round	`./templates/round_NNNN.yml.template`	包含注释说明哪些是必填字段
final_summary	`./templates/final_summary.md.template`	包含注释说明哪些是必填字段

典型场景

场景 1：研究开始时快速创建 session_meta

技能操作：

•读取 templates/session_metadata.yml.template
•将传入数据合并到模板
•保留未填写的可选字段为空或注释
•创建 {root_dir}/{session_id}/session_metadata.yml

场景 2：研究进行中补充 session_meta

技能操作：

•读取已存在的 session_metadata.yml
•合并新数据到已有字段
•不覆盖已填写的内容
•更新文件

场景 3：创建 round 记录

步骤：

•查看 templates/round_NNNN.yml.template
•识别 [必填] 字段
•传入数据

文件结构

code

{root_dir}/                        # 默认: logs/
└── {session_id}/                  # 例如: 20260108_analyst_sonnet/
    ├── session_metadata.yml       # 会话配置（可逐步完善）
    ├── round_0001.yml             # 第1轮（可逐步完善）
    ├── round_0002.yml             # 第2轮（可逐步完善）
    ├── ...                        # 更多轮次
    └── final_summary.md           # 最终总结（可选）

核心原则

1. 经济学分析优先 ⭐⭐⭐⭐⭐

以下字段在任何阶段都应优先填写（在模板中标注为 ⭐）：

•economic_analysis.hypothesis（经济学假设）
•economic_interpretation（经济学解释）
•economic_insights（经济学洞察）

2. 结构化优先

•✅ 使用 YAML 确保数据可解析
•✅ 避免自由文本，便于程序化提取
•✅ 标准化字段命名

成功标准

维度	标准	验证方法
可追溯性	每个决策都有明确记录	检查 `rationale`、`hypothesis` 字段
渐进性	支持分阶段填写	验证可选字段可后续补充
经济学深度	核心经济学字段完整	检查 3 个 `economic_*` 字段
可解析性	YAML 可被程序提取	使用 `yaml.safe_load()` 验证
灵活性	支持按需调用	验证可单独创建任意记录类型

模板文件

模板文件索引

模板文件	记录类型	格式	行数	说明
`session_metadata.yml.template`	session_meta	YAML	~60	会话配置完整模板
`round_NNNN.yml.template`	round	YAML	~90	轮次记录完整模板
`final_summary.md.template`	final_summary	Markdown	~406	最终总结完整模板
`README.md`	使用文档	Markdown	~447	详细使用指南

查看方式：

bash

# 查看特定模板
cat templates/session_metadata.yml.template

# 或在 IDE 中打开
open templates/round_NNNN.yml.template

数据流向

code

其他技能 ──────▶ alpha-research-recorder ──────▶ YAML/MD 文件
(生成数据)         (引用模板 + 数据合并)            (持久化存储)
                       │
                       ▼
                  查看模板文件
             templates/{type}.template