保留学习者原文：版本化解释与人工纠正

语言： English | 简体中文

发布日期：2026-09-04

我为 FLH 设计了学习记录的数据边界，把原始问题、机器解释和人工纠正分开管理。Go / SQLite 工作流因此可以保留历史、接受显式纠正，并在重复导入 capture 时避免创建重复记录。

工程重点：数据建模、来源追踪与事务式导入。

FLH 最初要解决的问题很简单：法语学习中的问题不应该消失在一段段聊天里。引入机器解释后，原本的笔记问题变成了数据建模问题。

一行数据承担三种事实的陷阱

早期 Entry 除了原始输入和上下文，还包含可空的 category、explanation 和 confidence。这种直观的 schema 混合了三种不同事实：学习者写了什么、机器如何理解，以及人读完以后如何判断。

如果它们共享一行，重新分析就会覆盖旧解释，人工纠正也会抹掉机器原来的说法。系统便无法回答“上个月规则引擎怎么解释，人有没有反对”。

分离来源、解释与判断

Entry 只保存学习者原文、上下文和时间，不被机器解释改写。
Analysis 是独立且不可变的版本记录。再次分析追加版本，并记录如 rule-based:v2:fr_l2_taxonomy_v1 或 openai:<model>:fr_l2_taxonomy_v1 的来源。
Feedback 是针对某次 Analysis 的只追加人工判断：接受、纠正或拒绝，不修改原 Analysis。
Effective analysis 在读取时由分析和最新反馈推导，不另存一份状态。拒绝后不产生有效解释，更早的接受不会重新生效。

最初 migration 创建的 Entry 列仍保留在物理表中，以兼容已有数据库，但活跃领域模型和 API 不再读取它们。没有合成新值、搬移旧值或改写 migration 历史。这是一项明确的兼容性取舍。

能解释自身决定的本地分析器

默认分析器在本地运行，不需要 API key。它从根据问号和词数分支的 switch，发展为同时分析输入与上下文的具名加权规则。“how do I say”等明确信号优先，词数等弱规则仅作兜底。

这里有两个关键决定。第一，confidence 是启发式决策分数，不是校准概率，可用于排序和提醒复核。第二，规则引擎可以建议 NeedsAI，但不自行调用 provider。OpenAI 实现通过同一接口由 AI_PROVIDER 显式选择；provider 失败不落库，返回 502 或 504，也不自动重试或静默切换。

所有实现共用 fr_l2_taxonomy_v1 分类，越界输出在存储前被拒绝。

导入真实学习内容，而不必构建聊天机器人

我采用版本化 learning_capture_v1 文档，由学习者准备后提交到 POST /captures。服务在一个事务中存入普通 Entry，并可附带第一版候选 Analysis；端点不调用模型，也不读取聊天全文。

客户端选择 capture_id，服务按规范化内容指纹实现幂等：同身份、同内容返回已有记录和 200；同身份、不同内容返回 409，不覆盖。薄 CLI 原样提交文档，校验规则只由服务器拥有。

明确的功能范围

这个阶段没有自动重新分析、复习调度或新分析出现后的 staleness 标记。来源记录使以后扩展这些能力不必重写历史。

后续验证：2026 年 10 月

早期里程碑没有独立验收报告，其实现日期可从 Git 历史核对。FLH-001 在 10 月 7 日验证了带/不带候选分析的 capture、相同和冲突重放以及重启，没有观察到数据完整性失败。FLH-011 进一步确认替换容器后，capture 幂等仍然有效。

实现由我定义方向、任务和审查，结合 AI 编码工具完成。以上结果来自项目记录。