name

alpha-research-recorder

description

Alpha 研究日志记录器 - 作为研究流程的数据持久化层。核心功能： 1. 根据记录类型（session_meta/round/final_summary）引用对应的模板文件 2. 接收结构化数据并验证必填字段 3. 创建/更新 YAML 或 Markdown 日志文件使用方式： - 调用时指定 record_type 和 session_id - 查看模板文件了解完整字段结构：templates/{record_type}.template - 传入数据合并到模板，生成最终文件

Alpha 研究记录器 Skill

技能定位

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

在研究流程中的地位

研究流程：
┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│ 知识检索/输入    │ ───▶ │  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
识别 [必填] 字段
传入数据

文件结构

{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	详细使用指南

查看方式：

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

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

数据流向

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