整理代码到 GitHub Repo — 求职作品集

日期: 2026-08-05 方向: Phase 3 / GitHub repo 阶段: Phase 3: 实盘+规模化+迁移 标签: #GitHub #OpenSource #Portfolio #README #JobSearch #PersonalBranding #DevOps

---

今日目标

---

一、为什么 Day 88 要做这件事

走到 Phase 3 Week 12，前 87 天的产出散落在三个地方：

本地仓库     → 能跑、能改、但只有我一个人看见
Mirror 文章 → 思考过程公开了，但代码细节藏起来了
IBKR 账户   → 真金白银的 fills，但隐私不可公开

作品集 = 把「能跑的代码 + 思考过程 + 可验证的结果」用一种陌生人能在 5 分钟内 grok 的形式摆出来。这不是「装修」，是 把过去 87 天的隐性资产显性化。

对求职而言，三件事的边际价值排序：

关键认知：履历能编，文章能写得好看，但 代码不能装。10 年金融 PM 转量化 / DeFi 工程，最高效的「能力证明」就是把 repo 摆出来。

---

二、Repo 结构：90 天混乱代码 → 工业级布局

2.1 目标结构

personal-trading-90-days/
├── README.md                  # 项目门面
├── LICENSE                    # MIT
├── .gitignore                 # 排除 .env / *.csv / logs/
├── .env.example               # 配置模板（不含 secrets）
├── pyproject.toml             # 依赖 + lint + test 配置
├── requirements.txt           # 兼容 pip 用户
├── .github/
│   └── workflows/
│       ├── ci.yml             # pytest + ruff + mypy
│       └── pages.yml          # 部署 GitHub Pages
│
├── docs/                      # 精选 10 篇笔记（中英双语）
│   ├── 01-why-ibkr.md
│   ├── 02-wheel-strategy.md
│   ├── 03-momentum-factor.md
│   ├── 04-backtest-engine.md
│   ├── 05-risk-management.md
│   ├── 06-live-trading-lessons.md
│   ├── 07-tax-on-options.md
│   ├── 08-90-days-review.md
│   ├── architecture.md         # C4 图 + 数据流
│   └── images/                 # 截图 / equity curve / PnL chart
│
├── src/
│   ├── data/                   # 数据 layer
│   │   ├── ibkr_client.py      # ib_insync 封装 + 重连
│   │   ├── yahoo_loader.py     # 历史数据 fallback
│   │   ├── cache.py            # parquet 缓存
│   │   └── corp_actions.py     # 拆股/分红调整
│   ├── factors/                # 因子计算
│   │   ├── momentum.py
│   │   ├── value.py
│   │   ├── quality.py
│   │   └── volatility.py
│   ├── backtest/               # 回测引擎
│   │   ├── engine.py           # 事件驱动核心
│   │   ├── portfolio.py
│   │   ├── slippage.py         # 含 size-aware 滑点模型
│   │   └── metrics.py          # Sharpe/Sortino/MaxDD/Calmar
│   ├── strategies/             # 策略
│   │   ├── wheel.py            # CSP → 接货 → CC
│   │   ├── momentum_long.py
│   │   ├── earnings_iron_condor.py
│   │   └── pairs_trading.py
│   ├── risk/                   # 风控
│   │   ├── position_sizing.py  # Kelly / vol-target
│   │   ├── drawdown_guard.py   # max DD 熔断
│   │   ├── correlation_check.py
│   │   └── circuit_breaker.py
│   ├── execution/              # 执行
│   │   ├── order_router.py
│   │   ├── twap.py             # 拆单
│   │   ├── safety.py           # read-only 护栏 + 误下单防护
│   │   └── reconcile.py        # 对账
│   ├── monitoring/             # 监控
│   │   ├── alerts.py           # Telegram/Email
│   │   ├── healthcheck.py
│   │   └── dashboard.py        # Streamlit
│   └── reporting/              # 报告生成
│       ├── daily_pnl.py
│       ├── weekly_summary.py
│       └── tax_lots.py
│
├── tests/                      # 单元测试
│   ├── test_factors.py
│   ├── test_backtest.py
│   ├── test_risk.py
│   └── test_execution.py
│
├── notebooks/                  # Jupyter 复盘
│   ├── 01_data_exploration.ipynb
│   ├── 02_momentum_research.ipynb
│   ├── 03_wheel_backtest.ipynb
│   └── 04_live_results_review.ipynb
│
└── scripts/                    # 命令行入口
    ├── run_backtest.py
    ├── run_paper.py
    └── generate_report.py

2.2 这套结构背后的设计意图

反面案例：很多个人量化项目把所有东西堆在 main.py + utils.py，看起来「能跑」但任何人都看得出来这是「学完一遍 tutorial 之后的产物」，对资深工程师 / 量化招聘方而言是负分。

2.3 我的现状 → 目标的 diff

---

三、README 工程学：90% 的人在这里翻车

招聘方看 GitHub repo 的真实路径：

点开 repo
  ↓ 第一秒：看 README 顶部 banner + 一句话描述
  ↓ 第二秒：往下滚动看截图 / equity curve / 性能数字
  ↓ 第三秒：看安装步骤是不是「一行 pip install」
  ↓ 决定：要不要往 src/ 里点

90% 的工程师在前两秒就关掉了 README 写得差的 repo。哪怕代码再好。

3.1 README 模板（我会照搬这个）

<div align="center">

# Personal Trading: 90 Days from Zero to Live

> A documented, reproducible journey from $5,000 paper account to a
> live multi-strategy trading system on Interactive Brokers.

[![CI](https://github.com/<me>/personal-trading-90-days/actions/workflows/ci.yml/badge.svg)](https://...)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](...)

</div>

![Equity Curve](docs/images/equity_curve.png)

## What is this

A personal quantitative trading system built over 90 days while keeping
a day job. Combines:

- 🎯 **Options Wheel** on SPY / QQQ / IWM (CSP → assigned → CC)
- 📈 **Cross-sectional momentum** on liquid US equities
- 🎲 **Earnings volatility** harvesting (iron condors)
- 🛡️ A real risk module that I actually used in production

The interesting part is **not** the strategies themselves
(none are novel) — it's the engineering discipline around them:
backtest reproducibility, execution safety, tax-aware reporting.

## Headline numbers (paper + small live, 90 days)

| Metric | Value |
|--------|-------|
| Strategies running | 3 |
| Backtest coverage | 2014-2025 |
| Max live drawdown | -4.2% |
| Sharpe (live, annualized) | 1.3 |
| Trades executed | 187 |
| Lines of code | ~6,400 |
| Test coverage | 58% |

> Live numbers are from a deliberately small ($5k) account.
> They prove the **plumbing works**, not that the strategy will scale.
> See [`docs/08-90-days-review.md`](...) for an honest postmortem.

## Tech stack

- **Python 3.11** — core language
- **ib_insync** — IBKR API
- **pandas / numpy / polars** — data
- **scikit-learn** — feature engineering for factor models
- **Streamlit** — live dashboard
- **pytest + ruff + mypy** — quality gates
- **GitHub Actions** — CI

## Quickstart

```bash
git clone https://github.com/<me>/personal-trading-90-days.git
cd personal-trading-90-days
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env  # then fill in your IBKR paper account
pytest               # should pass
python scripts/run_backtest.py --strategy wheel --start 2020-01-01

Architecture

See docs/architecture.md for the full C4 diagram. TL;DR:

Data layer  →  Factor library  →  Strategy  →  Risk filter  →  Execution
   ↓              ↓                  ↓             ↓              ↓
 cache         backtest         signals      sizing/halt      IBKR

What I learned (and what I'd do differently)

A 90-day retrospective lives at [docs/08-90-days-review.md]. Long-form essays on Mirror:

• Why Wheel is a beginner trap that worked anyway
• Backtests are lies, but useful lies
• A risk module is the only thing keeping you alive

License

MIT. Use it however you like. This is not financial advice. I am not a registered advisor.

### 3.2 README 写作 7 条铁律

1. **顶部一句话能讲清楚**：陌生人 3 秒内知道这是什么
2. **必须有截图 / 图表**：纯文字 README = 减分。equity curve 是最有效的一张
3. **数字必须诚实**：写 "Sharpe 4.0 backtest" 但藏起 live -10% drawdown = 比不写还糟
4. **Quickstart 必须真的能跑**：在干净 VM 上验证一遍，pip 装完真的能 `pytest` 通过
5. **不要超过 2 屏**：超过的内容塞 `docs/`
6. **写「我学到了什么」**：技术招聘方看到「90 days」想问的是「你成长了多少」
7. **明确 disclaimer**：写明「不是投资建议、不是注册顾问」— 法务保护 + 显得专业

---

## 四、隐私 / Secrets cleaning：上传前必做

这一步搞砸了，repo 就废了。**已经被 commit 过的 secret，即使删除文件，git history 里仍然存在**，必须 rewrite history。

### 4.1 必须清掉的清单

| 类型 | 例子 | 风险 |
|------|------|------|
| API keys | `OPENAI_API_KEY=sk-...` | 别人盗刷你的额度 |
| IBKR account number | `U1234567` | 社工攻击起点 |
| Telegram bot token | `bot12345:AAH...` | 别人冒充你发消息 |
| RPC URLs（含 key）| `https://eth-mainnet.alchemyapi.io/v2/<key>` | 别人耗你 quota |
| `.env` 完整文件 | 任何 prod 配置 | 一锅端 |
| 真实持仓 CSV | `positions_2026.csv` | 暴露策略 / 资金量 |
| 个人 IP 日志 | `logs/*.log` 里的内网 IP | 渗透起点 |

### 4.2 清理工作流

**第一步：装 git-filter-repo（比 BFG 现代）**

```bash
pip install git-filter-repo

第二步：找出历史里所有可能的 secret

# 用 trufflehog 扫一遍
docker run --rm -v "$PWD:/repo" trufflesecurity/trufflehog:latest \
    git file:///repo --json | jq '.SourceMetadata.Data.Git.file' | sort -u

第三步：从历史里抹掉

# 抹掉特定文件
git filter-repo --path .env --invert-paths
git filter-repo --path config/secrets.yaml --invert-paths

# 抹掉特定字符串（用正则替换为 ***）
echo 'sk-[A-Za-z0-9]{32,}==>***REMOVED***' > replace.txt
echo 'U[0-9]{7,8}==>***IBKR_ACCT***' >> replace.txt
git filter-repo --replace-text replace.txt

第四步：force push 到新 repo

不要 push 到老 repo —— 真的有人会从 fork / cache 里翻出来。重建新 repo，把清洗后的代码作为 initial commit。

4.3 .gitignore 黄金模板

# secrets
.env
.env.*
!.env.example
*.pem
*.key
secrets/
config/local.yaml

# data
data/raw/
data/processed/
*.csv
*.parquet
!tests/fixtures/*.csv  # but allow test fixtures

# logs / outputs
logs/
*.log
outputs/
reports/*.pdf

# Python
__pycache__/
*.pyc
.pytest_cache/
.mypy_cache/
.ruff_cache/
.venv/
*.egg-info/

# editors
.vscode/
.idea/
*.swp
.DS_Store

# Jupyter
.ipynb_checkpoints/
notebooks/scratch/

4.4 .env.example 工程学

# ─────────────────────────────────────────────────────────────
# Personal Trading — Environment Variables
# Copy this to `.env` and fill in real values. Never commit `.env`.
# ─────────────────────────────────────────────────────────────

# IBKR connection
IBKR_HOST=127.0.0.1
IBKR_PORT=7497            # 7497=Paper TWS, 4002=Paper Gateway, 4001=Live
IBKR_CLIENT_ID=1
IBKR_ACCOUNT=DU1234567    # use DU... for paper

# Safety
TRADING_MODE=paper        # paper | live   <-- LIVE requires explicit override
MAX_POSITION_USD=1000     # hard cap per position
MAX_DAILY_LOSS_USD=200    # circuit breaker

# Data
YFINANCE_CACHE_DIR=./data/cache

# Alerts
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

关键设计：TRADING_MODE=paper 默认值 + 代码里 assert os.getenv("TRADING_MODE") == "live" 才允许下实盘 — 显式护栏比文档好用 1000 倍。

---

五、代码质量提升：60% test coverage 比 100% README 重要

5.1 必装的 4 个 gate

pyproject.toml 模板：

[project]
name = "personal-trading-90-days"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "ib_insync==0.9.86",
    "pandas>=2.0",
    "numpy>=1.24",
    "scikit-learn>=1.3",
    "streamlit>=1.30",
    "python-dotenv",
]

[project.optional-dependencies]
dev = ["pytest>=8", "pytest-cov", "ruff", "mypy", "pre-commit"]

[tool.ruff]
line-length = 100
target-version = "py311"
select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]

[tool.mypy]
python_version = "3.11"
strict = true
ignore_missing_imports = true   # ib_insync 没 stub

[tool.pytest.ini_options]
addopts = "--cov=src --cov-report=term --cov-fail-under=50"
testpaths = ["tests"]

5.2 哪些模块必须有测试

最低门槛：factors + risk + metrics + safety 四块 → 自动覆盖率约 50-60%。

5.3 GitHub Actions CI（.github/workflows/ci.yml）

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
      - run: pip install -e ".[dev]"
      - run: ruff check .
      - run: mypy src/
      - run: pytest

绿色 badge 的心理价值：陌生人点开看到 README 顶端三个绿勾 → 「这人不是玩票的」。

---

六、License 选择：90 秒决策

我的选择：MIT。原因：

1. 招聘方 / 客户友好 — 没人想用 GPL 代码再考虑法务
2. 个人作品集的目的是被看、被复用，不是限制别人
3. 一句话 license，简单到不会出错

MIT License
Copyright (c) 2026 <my name>
Permission is hereby granted, free of charge, ...

---

七、Repo 名字：SEO + 第一印象的复利游戏

候选名字对比：

我的选择：personal-trading-90-days。理由：

1. 「90 days」叙事钩子：招聘方读到立刻好奇
2. 「personal」标明非商业：避免被误解为推销产品
3. SEO 上：site:github.com "personal trading 90 days" 几乎独占
4. 可演进：未来 Phase 4 可以加 personal-trading-365-days

---

八、「公开 vs 私有」决策：作品集 ≠ 把全部底牌掀开

核心原则：公开「方法 + 工程」，私有「资金 + alpha + 隐私」。

招聘方想看的是「你怎么思考、怎么 ship」，不是「你这周赚了多少」。

8.1 公开的边际收益模型

公开 = 求职信号 × 触达概率 - 隐私风险 - 维护成本

求职信号 高    （技术招聘方真的会看）
触达概率 中    （主动投+被搜到）
隐私风险 低    （只要 cleaning 做好）
维护成本 低    （写完基本不动）

净 ROI = 高 + 中 - 低 - 低 = 正且大

现在公开正是 ROI 最高的时机：

1. Phase 1-3 全跑完，故事完整
2. 还没找下家，作品集就是面试通行证
3. 90 天叙事 + 真实 live 经验 = 稀缺 narrative

---

九、GitHub Pages 个人主页：把零散资产串成一站

9.1 为什么需要

招聘方 / 猎头第一次接触你的入口可能是 LinkedIn、Twitter、Mirror、Reddit、HN 任何一个。他们不会去翻 5 个平台，他们会想「这人有没有一个主页能让我快速 grok」。

GitHub Pages = 免费、不挂、URL 体面（<myname>.github.io）、可以放任何静态内容。

9.2 个人主页的极简结构

<myname>.github.io/
├── index.html              # 一页式
├── style.css               # 自己写 / Tailwind CDN
└── assets/
    ├── headshot.jpg
    └── equity_curve.png

index.html 内容拆段：

[Header]
  <myname> — Quant-curious PM with 10 yrs in finance/retail.
  Currently looking for: senior PM / architect roles in fintech / DeFi.
  [Email] [LinkedIn] [Twitter] [GitHub]

[Projects — 3 cards]
  Card 1: Personal Trading 90 Days → link to repo
  Card 2: <Web3 portfolio site, e.g., momoweb3>
  Card 3: <Architecture 270-day project portfolio>

[Writing — 5 highlighted posts]
  - Mirror: Why Wheel is a beginner trap...
  - Mirror: Backtests are lies, but useful lies
  - Substack: ...

[Background — 1 short paragraph]
  10 yrs finance/retail PM, ...

[Footer]
  © 2026 <myname>. Built with HTML + brutal honesty.

9.3 部署

# 在 GitHub 上创建 repo: <myname>.github.io
git clone ...
# 把 index.html 放进去
git push
# 5 分钟后 https://<myname>.github.io 上线

配置自定义域名（可选）：买 <myname>.dev（Google domains $12/yr）→ DNS 指 CNAME → GitHub Pages settings 填入。从此简历最后一行写 <myname>.dev 而不是 github.com/<myname> —— 第一印象差别巨大。

---

十、预期影响：管理预期，不要被 vanity metrics 误导

10.1 真实数据范围（参考其他个人量化 repo）

10.2 不要把 stars 当 KPI

stars 是 vanity metric。真正有价值的是：

1. 面试官能在打开 repo 30 秒内决定要不要聊你 → 这件事发生 = ROI 兑现
2. 写在简历最显眼的位置后，对方有理由继续读 → ROI 兑现
3. 自己 6 个月后回头看代码不觉得羞耻 → 工程能力可视化的副作用

衡量「ROI 兑现」的真正信号：

• 邮件 / LinkedIn message 提到 "I saw your trading repo..."
• 面试官在面试中引用你 README 里的某句话
• 别人 fork 后开 PR / Issue（哪怕只有 1 个，价值已经超过 100 个 stars）

10.3 长尾价值

公开 repo 的长尾价值在 3-5 年后：

• 转岗时不用重做作品集
• 下次写 blog / 演讲时有现成材料链接
• 在 conf / meetup 自我介绍时有 "show, don't tell" 的依据
• 维持 GitHub 活跃度的「锚定项目」

这是个长期资产，跟单次投递简历的 ROI 模型完全不一样。

---

十一、PM 视角：作品集与「open source contribution」同构

10 年金融 PM 的人通常会想：「我又不是工程师，做什么 open source？」

但仔细想这个映射：

结论：公开作品集 = PM 能力的代码化展示。它证明你不只会做 deck，还能把一个真实系统从 0 push 到 live。

对 Web3 / DeFi PM 岗位而言，这一点尤其重要 — Web3 工程师对「不会代码的 PM」有结构性不信任。用 repo 击穿这层不信任成本最低。

11.1 三个迁移性思考

1. 作品集 = 长期资产：跟投简历（一次性消耗）和 LinkedIn（被动展示）不同，作品集是自带复利的。每多一颗 star / 一次 fork / 一次引用都在背后默默工作。

2. 公开 = 强制保持质量：本地的 spaghetti 代码可以放任，但 push 到公开 repo 那一刻你会自动 refactor、写测试、补文档。「想象有人在看」是最便宜的质量提升机制。

3. 诚实 > 漂亮：写 "live drawdown -10%" 比写 "Sharpe 4.0 backtest" 重要 10 倍。资深从业者 30 秒就能识别哪个是装的、哪个是真的。诚实本身就是稀缺信号。

---

十二、Day 88 实际执行 Checklist

按这个顺序做（预计 6 小时）：

• (0) 拍照当前 repo 结构：tree -L 3 > before.txt，留作前后对比
• (1) 创建新 repo：personal-trading-90-days on GitHub，不要 import 老 history
• (2) 本地新建目录结构：按第二节布局 mkdir -p src/{data,factors,backtest,strategies,risk,execution,monitoring,reporting} tests notebooks docs scripts
• (3) 按职责搬代码：47 个老 .py → 新 src/<module>/<file>.py，保留 git history（git mv）
• (4) 统一 backtest API：所有策略改成调 backtest.Engine
• (5) Secrets 扫描：trufflehog git file://. --json 确认无残留
• (6) 写 .gitignore + .env.example：用第四节模板
• (7) 写 pyproject.toml：用第五节模板
• (8) 加测试：factors + risk + metrics + safety 四块，coverage ≥ 50%
• (9) 写 README.md：用第三节模板，截图放 docs/images/
• (10) 加 LICENSE：MIT
• (11) 加 CI：.github/workflows/ci.yml，确认绿
• (12) 精选 docs：把 Day 1-87 里 10 篇核心笔记 copy 到 docs/，去掉个人信息
• (13) 部署 GitHub Pages：建 <myname>.github.io，写 index.html
• (14) 更新 LinkedIn / 简历：加 repo 链接 + 个人主页
• (15) 更新 docs/daily/TR_PROGRESS.md：Day 88 ✅
• (16) 记录踩坑：本笔记最后加「实际执行记录」段

---

十三、明日预告

Day 89: 90 天回顾文章 — Mirror 长文 + Twitter thread + LinkedIn post

• 把 87 天浓缩成「3 个最惊讶的发现」+「5 个最贵的教训」
• 写一篇 3000 字 Mirror 长文 → 引流到 GitHub repo + 个人主页
• 拆 10 条 Twitter thread → 触达不同时区受众
• 写 LinkedIn post（更克制的版本）→ 触达招聘方
• 内容 disclaimer + 不是投资建议条款
• 文章节奏：钩子 → 数字 → 故事 → 教训 → CTA

---

实际执行记录

启动一项填一项，时间戳 + 卡点。

• [hh:mm] 新 repo 创建 — ...
• [hh:mm] 目录骨架建好 — ...
• [hh:mm] 代码搬迁完成 — ...
• [hh:mm] secrets 扫描清洁 — ...
• [hh:mm] 测试 coverage 通过 — ...
• [hh:mm] README 上线 — ...
• [hh:mm] CI 绿 — ...
• [hh:mm] GitHub Pages 部署 — ...
• 卡点 / 学到的：

---

总字数：约 5,900 字 今日完成度：方法论 ✓ / 模板 ✓ / 执行 checklist ✓ / 实操（你自己执行）