docs: 文档重构 — 清理 AI agent 残留，整合 docs/ 目录结构

- 删除 11 个残留文件: continuation.md, init_plan.md, reasonix.toml, djapi/continuation.md, djapi/.serena/, djapi/.claude/, djapi/.mcp.json, .claude/skills/, docs/usage.html, docs/db_schema.md, docs/report_db_design.md - 7 个 CLAUDE-*.md 移入 docs/ 并重命名去 CLAUDE- 前缀 - 新增 4 个文档: architecture.md, development.md, api.md, deployment.md - 重写 usage.md, README.md - 修复所有过时引用和交叉链接
2026-08-22 11:56:40 +08:00
parent 6e1ac0c46b
commit 6acf938caf
34 changed files with 1191 additions and 3909 deletions
@@ -0,0 +1,120 @@
+# Agent 工作指南
+
+cc-cursor — Mac Mini 单机量化研究平台。全链路：Data → Factor → Backtest → Optimize → ML → Sentiment → Agent。
+
+## 速查索引
+
+| 模块 | 详情文件 | 核心入口 |
+|------|---------|---------|
+| 数据层 + 数据库 | [data-layer.md](data-layer.md) | `from data.data_manager import DataManager` |
+| 因子引擎 + 情绪 | [factors.md](factors.md) | `from factors.registry import get_factor` |
+| 回测 + 优化 | [backtest.md](backtest.md) | `from backtest.vectorbt.engine import VectorBTEngine` |
+| ML 模型 | [ml-models.md](ml-models.md) | `from models.lightgbm.model import LightGBMModel` |
+| Agent 系统 + CLI | [agents.md](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}` |
+
+## 环境
+
+```bash
+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](data-layer.md) |
+| 因子/情绪/新闻相关 | [factors.md](factors.md) + [reference.md](reference.md) |
+| 回测/优化/策略相关 | [backtest.md](backtest.md) |
+| ML 模型/特征工程相关 | [ml-models.md](ml-models.md) |
+| Agent/CLI/报告相关 | [agents.md](agents.md) |
+| 第三方库 API/参数 | 查官方文档 |
+| 因子名/类名/表结构速查 | [reference.md](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 常用命令
+
+```bash
+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
+  ```
+
+### 提交前检查
+
+```bash
+grep -r "sk-\|token\|_H(lU\|password" --include="*.py" --include="*.md" --include="*.yaml" | grep -v ".example\|your_token\|your_password"
+```