不知道你是不是也有这种经历：项目上线前代码 review 了三轮，方案评审时大家一致觉得“稳了”，结果上线第二天，线上监控弹出一条告警，顺着日志一层层扒下去，最后发现是半年前拍脑袋定下的一个数据格式约定出了问题。那一刻脑子里只剩一个词——hindsight。“后见之明”这词在英语里带点自嘲，说的是事后什么都看得清楚。但今天我想分享的，恰恰是一个专门把这种“事后想明白的道理”沉淀下来的个人项目，名字就叫hindsight。
它不是那种激进的新框架，也不是什么炫酷的 AI 能力，而是一套老老实实的经验库：每次踩坑、每次误判、每次“早知道就……”的懊恼，全部结构化记录下来，然后在做新决策的时候自动翻出来提醒你。简单说，hindsight 的目标是让后见之明变成下一次的前见之明。项目用 Python 写的，数据存 SQLite，跑在命令行里，不需要额外部署服务，一个人用完全足够。适合所有想认真做复盘的技术人、产品经理，乃至带项目的人。内容偏实操，后面我会把每个模块的设计原因、表结构、核心代码、踩过的坑全部写清楚。
先提醒一句：这篇文章不是讲什么“冥想复盘”“六顶思考帽”这类偏玄的方法论，而是落地的工程方案。你会看到一个真正能跑起来的项目是怎么一步步从模糊想法变成日常使用的工具。
1. 项目整体设计与思路拆解
1.1 为什么需要“再回头看一步”的能力
人脑对失败的记忆天然会美化。这周线上出过一次故障，痛定思痛，当时恨不得把根因贴满工位。过两周，新的需求压过来，排期一紧，当初的教训就被挤到记忆的犄角旮旯。再过两个月，同类问题换个马甲重现，你甚至会觉得“这次情况跟上次不一样啊”，直到再次推倒重来。
我一开始也写过复盘文档，存在 Confluence 的角落里，结果就是典型的“写了等于没写”。文档一旦沉淀下来，和你的日常工作流是完全断开的。没人会主动去翻，搜索引擎也基本覆盖不了你那些口语化的反思。
于是有了 hindsight 的第一个设计原则：记录成本和读取成本都必须低到可以忽略。记录时敲一行命令就好，读取时它会在恰当的时机主动跳出来。
1.2 设计哲学：让“后见之明”变成“下次的前见”
hindsight 的核心思路听起来简单：建一个结构化的经验数据库，每个经验都带标签、场景、情绪权重、适用条件。每当开始一个新任务、新项目或写技术方案时，你先花十秒钟调用一次 hindsight 检索，它会返回一批和你当前场景有关的历史教训。
这里的关键不是“搜索”，而是关联。同一个坑，在不同项目里可能有完全不同的表述。比如“缓存穿透问题”，有人记成“数据库被打爆”，有人记成“空值缓存”，还有人记成“恶意请求刷接口”。如果只靠关键词匹配，这些根本不会撞到一起。所以我在设计时做了一层很轻的标签体系，让记录者在写入时用统一的词根。
另一个设计哲学是：这个工具不追求“对错”，只追求“相关”。它的本质不是知识库，不是博客，不是 wiki，而是给曾经的自己“递纸条”。工具不会主动判断你的方案对错，它只是把过去的你把过的脉、开过的药方递给你。
1.3 整体架构：采集 → 沉淀 → 检索 → 提醒
整个项目由四个模块组成，各管一摊：
- 采集模块：命令行工具
hs record，接收文本、标签、场景、项目名，写入 SQLite。 - 沉淀模块：定期对记录做清洗和聚合，比如标记“已解决”“已规避”“已过时”，避免经验库越来越水。
- 检索模块：
hs search，支持关键词 + 标签 + 时间窗组合筛选，返回按相关度排序的经验条目。 - 提醒模块：
hs remind，启动新项目时自动拉取和当前场景匹配的高权重教训，打印成清单。
这四块虽然功能各异，但都围绕同一个核心数据结构展开。后面我会细讲每一块的实现和设计依据。先说说数据模型，因为这是整个项目的地基。
2. 核心机制解析与实操要点
2.1 数据采集：三层来源
hindsight 的采集通道分三层。首选是git 提交信息钩子，我写了一个 pre-commit 小脚本，检测到提交信息里有#lesson标记时，自动把提交信息同步到 hindsight 的 pending 表。这样做的好处是，你写提交信息的时候往往是刚刚修复完一个 bug、刚刚想明白一个逻辑，记录的“新鲜度”最高，不用专门停下来开个新终端敲命令。
第二层是命令行主动记录。我习惯在每天下班前花两分钟过一下当天的工作流，把真正有信息量的事记下来。命令很简单：
hs record "千万别在 nginx location 里用 if 做复杂判断，规则优先级会坑人" \ --scene backend/config \ --tags nginx,配置,优先级 \ --project gateway第三层是周报聚合。每周五我用一个脚本把这一周的 git log 和 commit message 拉出来，跑一遍关键词打分，找出和已有标签相似度高的提交，生成一个“疑似值得沉淀条目”清单，我只负责勾选，不用从零手写。
这里最容易被忽略的是“情绪状态”。人只有在情绪波动时才会真正记住教训，所以我加了一个--emotion参数，取值是-2到+2，表示这件事当时让我多难受。这个值在后续排序时权重很高，因为事实证明，让你难受过的坑远比让你顺利通过的经验更值得在下次避免。
2.2 数据模型设计：怎么写才能搜得到
hindsight 的数据库设计起初很简单，一张表存记录，一个字段存标签，后来开始出现数据膨胀、检索失准的问题，才被迫做成了下面这个三表结构：
-- 经验主表 CREATE TABLE lessons ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, created_at TEXT NOT NULL DEFAULT (datetime('now', 'localtime')), updated_at TEXT, scene TEXT, -- 场景分类，如 backend/config, frontend/performance project TEXT, -- 关联项目名 emotion INTEGER DEFAULT 0, -- -2 ~ +2 resolved INTEGER DEFAULT 0, -- 1=已解决/已规避 outdated INTEGER DEFAULT 0, -- 1=已过时，不再推荐 times_hit INTEGER DEFAULT 1 -- 这条经验命中过几次 ); -- 标签表 CREATE TABLE tags ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT UNIQUE NOT NULL ); -- 多对多关联表，一经验多标签，一标签多经验 CREATE TABLE lesson_tags ( lesson_id INTEGER NOT NULL REFERENCES lessons(id), tag_id INTEGER NOT NULL REFERENCES tags(id) );为什么不用 JSON 字段存标签数组？第一版确实这么干过，用tags LIKE '%nginx%'查询，数据两百条后查询速度就肉眼可见变慢了。更坑的是标签重名和拼写问题，nginx和Nginx、nginx/直接分裂成两个标签，统计完全失真。多对多关联表虽然写起来烦一点，但保证了标签的唯一性，还能做标签聚合计数。
内容字段我用的是 TEXT 而不是 VARCHAR，不加长度限制，因为有时候记一条完整的上下文比只记结论重要得多。你回头翻时才看得懂当时的处境。但我也做了限制：记录时必须先经过去噪脚本，比如去掉“感觉”“好像”“可能”这类模糊词汇的前缀，强迫自己用确定性强的口吻记录。这样检索时匹配的质量会高很多。
2.3 检索与推荐：用最简单的办法检索教训
检索模块的排序算法，我斟酌了很久。一开始想用 TF-IDF，后来又考虑过用 embedding 向量库。但考虑到一个跑在自己笔记本上的工具要轻、要快、要离线可用，杀鸡用牛刀没有必要。最终选了一种加权关键词 + 标签扩召 + 时间衰减的混合方案。
具体逻辑是这样的：
- 用户输入检索词，比如“缓存 穿透”，先拆成关键词列表，每个关键词也映射到标签表。
- 对每条经验计算相关度分数：
score = 0.4 * 关键词命中数权重 + 0.3 * 标签扩召命中数权重 + 0.2 * emotion 权重（取值归一化到 0~1） - 0.1 * 时间衰减（超过180天开始扣分，每30天扣0.05） + 0.1 * times_hit 归一化值这种手写规则的好处是完全可解释。比如某条经验标签是“缓存、穿透、空值”，你搜“缓存穿透”时，标签关联表会把“空值”这条也带出来。用 embedding 可能语义更准，但也会把“缓存雪崩”“缓存更新”这类内容带进来，反而噪音更大。
同理，“时间衰减”也很重要。技术世界的经验保质期很短。一年前关于某个老框架的教训，在新版本里可能已经被框架修复了。所以我会定期跑一个hs stale命令去检查超过一年且未被命中的条目，手动确认是否标记 outdated。
3. 实操过程与核心环节实现
3.1 环境准备与初始化
整个项目我是在 Python 3.11 环境下开发的，依赖库只有两个：click用于命令行参数解析，rich用于终端输出美化。没有用 ORM，直接写 SQL 操作 SQLite，因为这种内聚的小项目用 ORM 反而增加一层抽象负担。
初始化步骤：
mkdir hindsight && cd hindsight python3 -m venv .venv && source .venv/bin/activate pip install click rich touch hindsight.py数据库文件默认放在~/.hindsight.db，环境变量HINDSIGHT_DB可以覆盖路径。我这个项目在很多台机器上用过，有时候临时在服务器上想查一条经验，所以支持环境变量是比较实用的妥协。
3.2 数据库建表与初始化脚本
第一次运行时会自动建表和索引，关键是给scene和tags加上索引，否则数据量到几千条后，每次查询都全表扫描会变得很痛苦。
import sqlite3, os, click, time from rich.console import Console console = Console() DB_PATH = os.getenv("HINDSIGHT_DB", os.path.expanduser("~/.hindsight.db")) def init_db(): conn = sqlite3.connect(DB_PATH) cur = conn.cursor() cur.executescript(""" CREATE TABLE IF NOT EXISTS lessons ( id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT NOT NULL, created_at TEXT NOT NULL DEFAULT (datetime('now','localtime')), updated_at TEXT, scene TEXT, project TEXT, emotion INTEGER DEFAULT 0, resolved INTEGER DEFAULT 0, outdated INTEGER DEFAULT 0, times_hit INTEGER DEFAULT 1 ); CREATE TABLE IF NOT EXISTS tags (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT UNIQUE NOT NULL); CREATE TABLE IF NOT EXISTS lesson_tags ( lesson_id INTEGER NOT NULL REFERENCES lessons(id), tag_id INTEGER NOT NULL REFERENCES tags(id) ); CREATE INDEX IF NOT EXISTS idx_lesson_scene ON lessons(scene); CREATE INDEX IF NOT EXISTS idx_lesson_created ON lessons(created_at); CREATE INDEX IF NOT EXISTS idx_lesson_resolved ON lessons(resolved); CREATE INDEX IF NOT EXISTS idx_tag_name ON tags(name); """) conn.commit() conn.close()3.3 命令行采集工具实现
我做得比较顺手的是record子命令。它接收多行文本，拆分成句子，然后逐条插入数据库。因为经验往往不是一句话能说清的，比如“这次问题出在连接池初始化顺序，幸好通过线程堆栈抓到了，下次记得先确认静态变量的初始化时机”，这是一条完整记录，但也可以拆成两条独立经验。
@click.command() @click.argument("content") @click.option("--scene", default="general", help="场景分类，如 backend/config") @click.option("--tags", default="", help="逗号分隔的标签") @click.option("--project", default="", help="关联项目名") @click.option("--emotion", default=0, type=click.IntRange(-2, 2), help="情绪强度 -2~2") def record(content, scene, tags, project, emotion): """记录一条经验到 hindsight 数据库。""" init_db() conn = sqlite3.connect(DB_PATH) cur = conn.cursor() # 把整段内容按句号分句，每句作为独立经验存储 sentences = [s.strip() for s in content.replace("。", ".\n").split("\n") if len(s.strip()) > 8] for sentence in sentences: cur.execute( "INSERT INTO lessons (content, scene, project, emotion) VALUES (?, ?, ?, ?)", (sentence, scene, project, emotion) ) lesson_id = cur.lastrowid for tag in [t.strip() for t in tags.split(",") if t.strip()]: cur.execute("INSERT OR IGNORE INTO tags (name) VALUES (?)", (tag,)) cur.execute("SELECT id FROM tags WHERE name = ?", (tag,)) tag_id = cur.fetchone()[0] cur.execute( "INSERT OR IGNORE INTO lesson_tags (lesson_id, tag_id) VALUES (?, ?)", (lesson_id, tag_id) ) conn.commit() conn.close() console.print(f"[green]已记录 {len(sentences)} 条经验[/green]")这里有个细节：为什么按句号分句？因为实际使用中，我复制的报错信息或者聊天记录往往是长长的一段，不分句直接塞进去会浪费整条记录，检索时还会因为一句话包含太多主题导致匹配混乱。
3.4 周报聚合与“昨日重现”模块
周报聚合是我觉得最“回本”的模块。每周五跑一次，它会扫描 git log 里带#lesson的提交，提取出 commit message 主体部分，然后和已有记录做文本重叠度匹配。重叠度高于 0.6 的就不重复入库，只把times_hit加一；低于 0.6 的列出一个候选清单，等我来决定收不收。这样经验库里没有大量重复内容，质量也保持得住。
“昨日重现”是 hindsight 最有仪式感的功能。每周一早上运行hs flashback，它会随机抽取 3 条一个月前的教训，加上当时的场景和情绪值，以卡片形式打印出来。这个设计借鉴了记忆里的间隔重复机制：如果不主动回看，教训会在几个月后彻底淡化。每周花 10 秒看三张卡片，远比出事之后花三小时查日志划算。
4. 常见问题与排查技巧实录
4.1 数据全是噪声怎么办
这是第一个星期几乎一定会遇到的问题。新鲜感过去以后，你开始什么都想记录，于是库里塞满了“今天改了一个配置”“这个接口返回格式要注意”这类低信息量条目，真正关键的教训反而被淹没。我的解法是加了一个resolved字段，hs prune命令列出所有times_hit < 2且emotion < 1的条目，直接批量标为“不推荐”。说白了就是给经验库做瘦身，不然检索结果会被平庸的条目稀释。
4.2 标签体系失控了怎么办
标签一旦随手打，很快就出现几十种细微变体：nginx/配置、nginx-config、nginx 配置、Nginx配置。这个问题其实无解，因为人在输入时不会严格考虑规范。我后来放弃了让标签完全规范化的幻想，改为在检索时做一层标签同义词归一化：把所有标签转小写、去空格、去斜杠、去掉“配置”这类高频通用词。这样至少能拦截大部分重复。
4.3 时区问题真的会让你怀疑人生
数据库里datetime('now','localtime')在桌面上跑没问题，但如果通过 SSH 连服务器执行hs record，SQLite 的localtime是根据服务器时区来的。我曾经在凌晨记录一条经验，时间戳写的是 UTC 时间，早上回看时它跑到了“未来”。排查了很久才发现是数据库的时间混用了。现在所有程序内操作统一用datetime.now().astimezone().isoformat()写入，不依赖 SQLite 内置函数。
4.4 检索跑偏或者“关键词打架”
两条经验本来毫不相关，但因为共用了一个标签词，检索时就会互相干扰。比如“数据库连接超时”和“连接池配置错误”都带着“连接”这个标签，你搜“连接池配置”时，超时那条也会被拉出来。这时候我在打分函数里加了“场景权重”的概念：如果检索词里包含“数据库”，那么scene为backend/database的经验分数乘以 1.5，其他场景的分数乘以 0.8。效果立竿见影，跨场景的误报明显减少。
5. 工具选型与扩展方向
5.1 为什么选 SQLite 而不是 JSON 文件或 MySQL
很多人会问，一个单人用的工具，直接写 JSON 文件不是更简单吗？第一版确实是 JSON，存成~/.hindsight.json，每条记录按时间追加。但当我试图按标签筛选时，要遍历整个数组；当我想统计“哪些标签被我命中次数最多”时，又要遍历整个数组。做了两次这样的操作之后，我果断换成了 SQLite。它是单文件数据库，不需要独立服务进程，但对 SQL 的支持非常完整，索引、事务、关联查询，该有的都有。对个人工具来说，SQLite 几乎是最优解。
MySQL 则完全没必要。一个人用的工具，引入 MySQL 意味着要管理服务、账号权限、备份策略，这些运维成本远远超过数据本身带来的收益。除非未来做到多设备同步，否则 SQLite 的形态足够。
5.2 下一步扩展：联动提醒与自动生成复盘报告
当前版本已经稳定用了三个月，下一个迭代我要加两个功能。一个是hs watch长驻模式，监听 git 提交和本地错误日志，实时识别出常见错误模式并弹出提醒；另一个是复盘报告生成器，每季度跑一次，汇总这个季度被命中次数最多的 10 条经验，自动生成一页纸的分享文档，直接发给团队成员。
第二点尤其适合团队场景。单独一个人的 hindsight 是个人的后见之明，但如果是十个人的团队复用同一个经验库，那它的价值就几何级放大了。为此我还计划把 SQLite 升级成基于文件同步的方案，比如通过 Git 仓库直接分发经验库镜像，这样不需要架设中心服务器，也能做到多人共用一套经验数据。
最后分享一个真实的个人体验。我刚开始用 hindsight 的那两周其实一直处于“记了又不想看”的状态，直到某次排查线上性能问题，因为一条三个月前记录的“这个接口的 N+1 查询曾经导致过 CPU 飙高”被检索出来，帮我省掉了至少半天盲目排查的时间。那一刻我才真正意识到，工具本身不能让你变聪明，但它能让你每一次犯过的错都不白犯。
后来我又养成了一个习惯：每次在 hindsight 里记完一条经验，都会顺手补一句“如果回到当时，我会怎么做”。这句话往往比经验本身更有价值，因为它逼着我把模糊的懊恼转化成具体的行动指令。
如果你也想动手做一个类似的东西，不需要照搬我的设计，但有一点建议值得参考：别一开始就追求功能完整，先跑起来，然后让记录习惯决定工具的进化方向。现在的 hindsight 依然很朴素，命令行、黑白终端、没有图表和仪表盘，但它承担着最原始也最实用的任务——留住不让时间冲走的教训。