myquant/docs/agent-guide.md

Agent 工作指南

cc-cursor — Mac Mini 单机量化研究平台。全链路：Data → Factor → Backtest → Optimize → ML → Sentiment → Agent。

速查索引

模块	详情文件	核心入口
数据层 + 数据库	data-layer.md	from data.data_manager import DataManager
因子引擎 + 情绪	factors.md	from factors.registry import get_factor
回测 + 优化	backtest.md	from backtest.vectorbt.engine import VectorBTEngine
ML 模型	ml-models.md	from models.lightgbm.model import LightGBMModel
Agent 系统 + CLI	agents.md	python finance/cli/agent_cli.py daily

工作区布局

目录	内容
finance/	核心量化引擎（代码实际位置）。代码内 import 用顶层名 data.*/factors.* 等 — 由 CLI 把 finance/ 加入 sys.path；文件路径为 finance/data/xxx.py 等
djapi/	Django API 子项目，有独立 djapi/CLAUDE.md
shared/script/	autossh.sh — MariaDB SSH 隧道
docs/	项目文档目录，包含使用指南、架构说明、API 参考等；新建 md 一律放这里
finance/strategy portfolio execution scheduler/	空壳占位（仅 __init__.py），逻辑未落地，别误以为有实现
finance/reports/	日报输出 daily_YYYYMMDD.{md,html}

环境

conda activate quant          # Python 3.11.13
bash shared/script/autossh.sh # DB SSH 隧道 (本地 13306 → 远程 3306)

# 环境变量在 finance/.env（示例见 finance/.env.example）：QWEN / TUSHARE / DB / 情绪范围

任务→文档路由

任务类型	先读取
数据源/数据库/cache 相关	data-layer.md
因子/情绪/新闻相关	factors.md + reference.md
回测/优化/策略相关	backtest.md
ML 模型/特征工程相关	ml-models.md
Agent/CLI/报告相关	agents.md
第三方库 API/参数	查官方文档
因子名/类名/表结构速查	reference.md

多步任务规则

复杂任务（涉及 3+ 文件或 2+ 模块）执行前：

1. 输出执行计划清单（步骤 + 每步验证方法）
2. 每步完成后验证通过才继续
3. 遇到失败先定位根因，不跳过

核心设计约束（必须遵守）

• 数据流：Data → Factor → Model → Strategy → Backtest → Report
• 策略层禁止直接访问 AkShare/Tushare → 全部通过 DataManager
• 模型层禁止直接访问数据库 → 全部通过 DataManager
• 指数代码规则：.SH=指数, .SZ 开头非 399=个股
• 数据源优先级：Tushare → AkShare (fallback)
• 当日数据未缓存 → 先 dm.sync_daily；增量同步只更新已缓存股票
• 修改多文件前先说明：文件清单、原因、影响；优先小范围修改

CLI 常用命令

python finance/cli/agent_cli.py daily              # 5步完整流程
python finance/cli/agent_cli.py picks 15           # 选股
python finance/cli/agent_cli.py risk               # 风险评估
python finance/cli/agent_cli.py research           # 因子研究
python finance/cli/agent_cli.py report 20260603    # 生成日报
python finance/cli/agent_cli.py warmup 50          # 首次预热缓存

python finance/cli/demo_data_manager.py --ts_code 600519.SH
python finance/cli/demo_factor_engine.py --ts_code 300750.SZ
python finance/cli/demo_backtest.py --ts_code 000001.SZ
python finance/cli/demo_optimizer.py --ts_code 000001.SZ --trials 100
python finance/cli/demo_ml.py --ts_code 000001.SZ --lookahead 5
python finance/cli/demo_sentiment.py --ts_code 600519.SH
python finance/cli/demo_sentiment_detail.py --ts_code 600519.SH --date 20260603

技术栈

组件	技术	环境
数据获取	AkShare + Tushare (双源)	conda quant
数据库	MariaDB (SSH 隧道)	mac_ 前缀表
因子/特征	pandas / numpy / sklearn	conda quant
回测	VectorBT 1.0	conda quant
优化	Optuna 4.9	conda quant
ML	LightGBM 4.6 + CatBoost 1.2	conda quant
NLP	Qwen (DashScope / Ollama)	.env 配置
Agent	自研编排器	finance/agents/
API	Django 5.2 + uWSGI	djapi/

安全规范

禁止提交

• .env（含真实 key）
• API Key（sk-*、TUSHARE_TOKEN 等）
• Cookie / Session
• Token / 密钥
• 个人隐私数据（手机号、身份证、密码）

必须提供

• .env.example — 仅含占位符的示例配置，如：

  TUSHARE_TOKEN=your_token_here
  QWEN_API_KEY=sk-your-key-here
  MAC_DB_PASSWORD=your_password_here
  

提交前检查

grep -r "sk-\|token\|_H(lU\|password" --include="*.py" --include="*.md" --include="*.yaml" | grep -v ".example\|your_token\|your_password"