lesson-book

中文说明

lesson-book 是本地优先、可复现的交易经验记录工具，也可以用于 A 股研究 和模拟交易流程。它记录错误、代价和标签，并在相似情境再次出现时给出提醒。 匹配规则是固定的，不调用大模型、不上传云端，也不提供买卖建议；它的作用是 让过去的经验在行动前被看见。

Tuition memory for traders. A local-first, deterministic mistake ledger: record what each mistake cost you, tag it, and lb match reminds you of it the next time the same situation shows up —before you act. Python 3.11+, zero dependencies, Windows / Linux / macOS. No LLM, no cloud, no statistics: the reminder is reproducible and auditable.

Status: v0.1.1 alpha, published on PyPI. The matching logic is distilled from a production trading system's lesson-matching module; this standalone package is new.

Why this exists

Your trading system has a memory problem: it forgets. The mistake you paid 1,200 for last month looks like a fresh opportunity today, because nothing stood between the idea and the order. Trading journals solve the recording half —they are ledgers of what happened. lesson-book solves the retrieval half: it keeps the tuition in a form that can speak up when the same situation appears again.

Two design commitments make it different from journaling apps and LLM "memory" systems:

1. Deterministic, not statistical. Scoring is a fixed weighted formula (code +3, industry +2, market cap +1, volatility proximity bonus, tag overlap bonus). Same situation, same reminder, every time —the opposite of an LLM memory that improvises.
2. Local-first and verifiable. The book is a plain append-only JSONL file in your repo. git log on it is your audit trail; nothing ever leaves your machine.

Philosophy

Tuition is capital —the system does not forget what you paid for, and it reminds you before you pay again.

This is the checklist culture of aviation and medicine, applied to trading: Gawande's The Checklist Manifesto is the canonical argument that simple checklists reduce catastrophic error rates by an order of magnitude. And it is the premortem in reverse: Klein (2007), "Performing a Project Premortem" asks you to imagine, before acting, that you already failed and explain why. lb match is the automated premortem: it surfaces the historical answers to "why will this fail?" without you having to ask.

The IOM (1999), To Err Is Human framing applies directly: errors are a system problem, not a character flaw. The book exists to improve the system —classification, review and retrieval —never to punish the person. That is why records carry cost (a number, not a shame) and why the tool classifies but never enforces: rules, positions and limits stay with you.

Quick start

# install the published package from PyPI
pip install lesson-book

# or run without installing anything:
#   PYTHONPATH=src python -m lesson_book --help

python examples/demo.py   # record, match, review on a scratch book

Your own book:

# record a mistake —classification happens via the rule table
lb add --book book.jsonl \
  --title "bought into the open gap" \
  --issue execution_failed --error-category price_limit \
  --date 2026-08-01 --code 600000 --industry banking \
  --volatility 0.03 --tags gap,limit-up --cost 1200 \
  --lesson "never chase the open gap; wait for the retest"

# before acting tomorrow: ask the book
lb match --book book.jsonl --industry banking --volatility 0.03 \
  --code 600000 --tags gap
# -> the 2026-08-01 record, score 8.0, lesson: "never chase the open gap..."

# import an existing ##-style markdown knowledge base
lb import-lessons --from LESSONS.md --book book.jsonl

# daily review of what the day cost
lb review --book book.jsonl --day 2026-08-01 --out reviews/

Commands

The book

book.jsonl —append-only, one JSON record per line:

{"schema_version": "lesson_book.lesson.v1", "record_id": "...",
 "title": "bought into the open gap", "date": "2026-08-01",
 "code": "600000", "industry": "banking", "volatility": 0.03,
 "market_cap": "large", "tags": ["gap", "limit-up"],
 "category": "price_limit_rejected", "priority": "P1",
 "cost": 1200.0, "lesson": "never chase the open gap",
 "situation": "", "recorded_at": "..."}

Matching score (deterministic):

A primary match (code / industry / market cap) is required for a non-zero score —the book never speaks up about situations it has no grounds to compare.

Classification rules

add classifies issue + error_category through a plain rule table (category, priority, action), fully overridable in code. Defaults:

Unclassified records are P2 with "review manually and extend the rule table" —the taxonomy grows with you, never silently.

Development

python -m pip install -e . pytest
python -m pytest

CI runs the full test suite on Ubuntu, Windows and macOS with Python 3.11 and 3.12. Issues are handled on weekends; pull requests are welcome.

Related work

• Klein (2007), Performing a Project Premortem (HBR) —imagine the failure before it happens
• Gawande (2009), The Checklist Manifesto —checklists as error-rate reduction
• IOM (1999), To Err Is Human —errors as system problems

Project family

Part of Holdout — a toolchain against self-deception in quantitative research:

• pit-adjuster — PIT back-adjustment with static forward-adjustment drift detection
• falsification-ledger — pre-registration and falsification ledger
• factor-qc — fail-closed backtest quality gate
• lesson-book — tuition memory for traders
• lookahead-free — verifiable look-ahead-freedom checks
• ashare-data-immunity — data immunity for A-share daily bars

Sister org: Metabolism Tools — workspace-metabolism, policy-driven file lifecycle management for agentic workspaces.

License

MIT