不靠猜测的批量导入："未确认"也是一种结果，恢复就是重跑

语言： English | 简体中文

发布日期：2026-11-08

FLH 的 capture CLI 以前一次只导入一个 learning_capture_v1 文件。我加入了最多 100 个文件的批量模式，以及一个不发送任何请求的预览。设计的核心是一个问题：响应没有回来时，报告应该怎么写？

我的工程贡献：定义结果类别和退出码，选择”重跑”而非自动重试，并规定报告的隐私规则。

复用单文件路径

-batch FILE... 先规划文件（1–100 个，按路径字节序，拒绝通过路径或文件身份重复列出的文件），再对每个文件调用未改动的单文件 Import。没有新增路由、schema、迁移或前端改动。单文件和 stdin 的输出逐字节不变，只有一个有意的例外：以前没有 -batch 时多余的位置参数会被静默忽略，现在以退出码 2 拒绝。

-batch -preview 只做本地检查。验收中经日志代理确认 0 个请求。

说清楚”不知道”

每个文件只有一个结果：

回应	结果
`201`	`created`
`200`	`replayed`
`409`	`conflict`：已存储的 capture 不变
`400`、`422` 或本地文件无效	`invalid`
响应丢失或无法读取、超时、中断	`unconfirmed`：可能已存储，也可能没有
无法连接，或批次已停止	`not_attempted`

关键是 unconfirmed。客户端无法知道服务器是否已提交，所以报告不假装知道。连续三个文件都没有服务器响应，或者收到中断后，剩下的文件标记为 not_attempted，而不是继续累积未知结果。

退出码 0 表示全部 created 或 replayed；1 表示有冲突或无效文件；3 表示用同样的文件再跑一次。

恢复是重跑，不是重试

CLI 从不自动重试。服务器本来就为每个 capture_id 保存带指纹的回执，所以重跑同样的文件时由服务器判断：已提交的会 replay，新的会创建。

验收在真实服务二进制前放了一个代理，在服务器返回 201 之后丢掉一个响应。第一次批量以 3 退出，该文件为 unconfirmed；重跑后它显示为 replayed，数据库仍然只有 4 条记录，没有重复。批量中途发送真实 SIGINT、服务器不可达时，都以 3 退出，记录不变。总计 46 通过、0 失败。

报告只包含标识符

报告列出路径、可移植的 capture_id 标签、HTTP 状态和记录 ID，从不包含学习者原文或请求体；服务器消息如果复述了请求内容，也会被隐去。验收在所有报告中搜索合成学习文本的标记，没有找到。

局限

预览和正式运行之间被编辑的文件，CLI 不会发现；对已存储的 capture_id，服务器指纹会把它变成 conflict。
超过 100 个文件需要手动拆分。
临时副本中没有运行 make verify，因为没有前端改动；Go 部分完整运行。

实现由 Claude Code 和 Codex 在我的指导、任务定义和审查下完成。

验证报告 · 实现 PR #128 · 关于我