知返 AhaDiff 使用指南

1. 快速开始

安装 AhaDiff，在工作目录打开本地 WebUI，再添加提供商。两份文件、本地快照或单份 Markdown 都能开始学习，无需 Git 仓库或 AI 工具集成。

打开你的工作目录

在准备存放学习记录的文件夹打开终端。普通文件夹就可以；文件、patch、快照和文档输入无需 Git 仓库。下面的命令在 macOS/Linux 终端和 Windows PowerShell 中都可使用：

AhaDiff 会打开 http://127.0.0.1:8765，并按需创建本地状态。到设置添加本地或远端 provider；使用远端模型前需明确选择远端隐私模式。配置 provider 时可能发送小探测请求，文件变化预览不会调用 LLM。

选择你要学习的材料

同一次运行会把这些页面连接起来。修改前可显式保存快照；单份 Markdown 可直接生成文档课程。快照需要手动保存。暂不支持 PDF 或网页抓取。AI 工具集成是可选项。

运行产物和复习状态留在所选工作区。Provider 配置可以放在工作区内，也可以放在全局级。

存储门禁接受这些 SQLite 版本

需要 Python 3.11+ 和达标的 SQLite 运行时。SQLite 版本取决于 AhaDiff 实际使用的 Python 构建，不能仅凭安装器名称判断。

第一次生成课程前，先查看快速上手里的诊断。在 Git 仓库内也可以运行 ahadiff doctor 确认 SQLite 版本达标；它会报告检测到的版本和所需门槛，版本过低时 fail-closed 报错。版本号更高不代表自动被接受。门禁要求 SQLite 3.51.3 及以上，或回填补丁的 3.50.4+ / 3.44.6+ 版本，所以 3.51.0-3.51.2 低于门槛、不会被接受。如果诊断提示版本不达标，请改用包含兼容 SQLite 的 Python 构建并重新检查。安装器名称或 Windows 上的 Python 版本本身都不能证明 SQLite 兼容。

1. 衬线主标题 Ship with AI. Learn it back.
2. 首字下沉的简介段落介绍 AhaDiff。
3. 查看最新课程与首次学习入口。
4. 右侧卡片预览最新已完成运行的课程大纲。

2. 配置模型提供商

打开 设置，添加本地或远程提供商。填写接口协议、基础 URL，以及你的账号或本地服务可用的模型。选择生成提供商和模型；可选的评判可以使用另一组配置。保存成功不代表连接成功，开始学习前请查看测试结果。

模型限制预览只读取本地配置和注册表，不联系提供商。测试提供商会发送小型真实请求，可能产生费用。远程生成需要 redacted_remote 或 explicit_remote；默认为 strict_local。

通过终端配置

下方示例会测试提供商，并在成功后保存配置。请将基础 URL 和模型占位符替换为你的服务提供的值。--api-key-env 接受环境变量名。后续 CLI 调用仍需该变量中的密钥，也可以通过设置页保存密钥。

模型限制与思考设置

• 模型默认 由提供商决定思考行为。只有受支持的模型和接口才提供 关闭。其他模型可能提供思考等级、开关，或不提供思考控件。
• 输出上限留空即为自动。超过已知上限时，知返会下调数值并提示。未知或部署专属的限制仍是估计；云端限制不能代表本地服务的容量。
• 生成与评判的限制分别计算。只有与所用接口匹配时才选择对应限制配置。切换模型后，保存前请重新检查已指定的思考设置。
• 多个工作目录可以共用全局提供商配置。同名时，工作目录提供商优先。模型列表只能确认名称，不能确认账号调用权限。

密钥保存在哪里

在设置页的 API Key 字段中填写密钥本身。知返将其写入所选范围的 .env，在 config.toml 中只保存引用。工作目录提供商使用 .ahadiff/.env；全局提供商使用下表目录。全局配置需要与学习记录分开备份。工作目录的忽略规则会让普通 git add 排除密钥文件；分享压缩包时也请排除它。同名系统环境变量优先。

编辑已有提供商时，密钥字段留空会保留原密钥。保存新密钥时可以测试连接，但测试失败不会撤销保存，请查看结果。移除提供商时，会清理使用保留前缀 AHADIFF_ 且不再被引用的密钥；不要在本地密钥文件中为无关变量使用该前缀。

macOS/Linux 上的密钥文件仅限所有者访问。Windows 上请用 NTFS 权限保护目录。需要由操作系统管理凭证时，可用 api_key_env 指定环境变量，无需粘贴密钥。

3. 生成课程

习惯终端时，可使用以下已有 CLI 模式，它们共用同一条学习链路。文件和 patch 路径必须在工作区内，Git 模式需要仓库。想学习很小的练习改动时可加 --force-learn。

--since 单用 vs --since --author

Patch 和 URL 捕获带有注意事项：

文件输入、预览与证据边界

浏览器接受 UTF-8 文本文件，每份最多 256 KiB，两份合计最多 512 KiB。快照文件和单篇 Markdown 在 CLI 与 WebUI 中都保持 256 KiB 上限。点选文件时，草稿只留在页面内存中，不会改写原文件。两份 .ipynb 保留按单元格比较的来源信息，AhaDiff 不会执行单元格。Markdown 和结构化格式在成功解析时增加专用锚点，SQL 和不支持的结构保留明确的行级证据；支持不足时仍标为 weak 或未证明。

预览变化只把输入发给本机服务，不调用 LLM。预览最多显示 64 KiB，部分展示会明确标注；这与捕获限额提示不同，后者才代表输入本身未完整捕获。点击开始学习后，生成遵循你选定的本地或远端隐私模式，并把常规运行产物保存在 .ahadiff/。

粘贴的统一 diff 上限为 64 KiB。浏览器请求序列化后上限为 1 MiB，转义字符很多时可能先达到请求上限；较大的比较输入可用 CLI，快照和文档上限仍然固定。CLI 的 patch 和对比文件在工作区根目录内解析；外部生成的 patch 可传 --patch -。

保存并复用本地基准

1. 打开本地快照，选择修改前文件，填写最多 80 字符的可移植名称。
2. 点击保存本地基准。列表展示时间、大小与就绪状态；过滤可能改变保存内容。
3. 下次打开时点击使用此基准，再选择修改后文件。预览比较结果，随后开始学习。
4. 删除时点击删除快照并确认具体名称。已有课程和源文件会保留。

从列表复制 SNAPSHOT_ID 和 content_hash；learn 的可选 hash 绑定精确比较内容。删除使用另一字段 record_hash，并会交互确认：

--yes 只跳过该具体 ID/hash 的交互提示。WebUI 始终确认具体一份再删除。损坏或不支持版本的记录不能用于比较；无法安全读取的记录没有可用删除哈希。

学习单份 Markdown 文档

选择单份 Markdown，点选一份最多 256 KiB 的 UTF-8 .md 或 .markdown 文件，预览过滤后的原文，然后开始学习。

独立 document 来源保存 document.md 及章节/段落锚点。证据页展示原文行，不添加增删标记；课程、测验、复习仍连接同一 run。该模式不支持 diff 的 spec alignment。Diff Coverage 与改动新颖度 Learnability 显示 N/A / 0/0，不计入总分；文档课程按正文中的证据检查覆盖；只有文档没有正文、全是标题时才使用标题。含正文的文档不能只靠引用标题通过检查。此模式接受单份本地 Markdown，不接受 PDF、URL 或多文档集合。

补充人工 review 说明

选择改动来源后可填写人工 review 说明，CLI 用户可选择本地文本文件：

说明最多为 8 KiB UTF-8 文本，按不可信输入过滤，并独立标成辅助上下文。它不能产生证据位置或替代代码反证。运行记录是否使用与内容哈希；草稿不进入任务重试摘要，编辑说明会使旧预览失效。请勿包含凭证。

阅读格式专用证据

格式专用索引上限为 4,096 个锚点。较大 diff 可能显示部分索引提示，但既有 hunk 证据仍可使用；超过此结构限额的单份文档会被拒绝，不会把部分文档冒充完整证据分母。

展开 claim 的源锚点，可查看前后侧、位置、引文和哈希。不同内容在移动或重命名后不会获得相同的证据身份。只有 hunk 证据的旧运行继续可读；声明了新来源产物却缺失、损坏或不一致时，会拒绝读取，不冒充已验证文本。

长时间运行的 CLI 命令会在运行中显示 Rich 状态。把它当作终端反馈，而不是机器可读的输出契约。

4. 使用 WebUI

运行下面任意一条打开本地 React SPA。serve 默认会打开浏览器；加 --no-browser 保持无头，或加 --watch 在 Git 工作区文件改动时自动 learn。

工作流一览

页面地图

1. 顶部统计卡：总运行数、平均分、通过率、概念数、LLM 调用。
2. Spec alignment 区块含分数、趋势、评估次数。
3. 棘轮轨迹折线图，区分 kept 与 discarded 分数。
4. 右侧复习活动热力日历。

Claim 与 diff

打开声明可查看来源位置和证据状态。下面五种状态说明知返从已捕获材料中确认了什么。

1. 顶栏含 PASS 分数、查看评分详情、标记为已学习。
2. 右上 Compact / Hint / Full 详细程度切换。
3. 左侧大纲栏：TL;DR、改了什么、Claims、概念。
4. 右侧 Claims 摘要：verified / weak / not proven 计数。

1. 中部代码 diff，红/绿标记新增与删除行。
2. diff 上方文件标签与 Unified / Split 视图切换。
3. 右侧 Claim Inspector 面板逐条列出 claim 卡片。
4. claim 状态徽章把解释链回到代码行。

先尝试主动迁移练习

在新建学习对话框中，明确勾选此来源的更多选项 → 主动迁移练习。默认关闭，普通运行仍按 guided/recall/transfer 混合分配。开启后只生成开放式 transfer 题，题数至少为 3 时覆盖全部三种形式。修改开关会使预览失效；切换来源或关闭对话框会重置开关。

regenerate 会替换本次运行的测验和卡片，重新评分，并清除旧的评判结果，不会重新调用评判模型。不传练习开关时沿用原模式；--mixed-practice 可生成混合测验。请选择打算修改的运行。生成过程使用已配置的提供商和隐私模式。

Transfer 复用现有 Quiz 与 SRS：预测下一步、补全相似例子、解释错误原因。先写尝试，再揭示参考答案；作答前不下发参考答案、解释和证据，也不会执行代码。

对照参考含义后选择独立完成、需要帮助或尚未完成。必要时标明困难属于概念回忆、应用、推理还是证据边界。等价表述也可能正确。选择题核对是机械判断，开放练习反馈是语义自评。

WebUI 作答正文保留在页面内存，仅保存受限自评、错误类别和时间信息。复习会带回同一卡片；距上次记录尝试至少 24 小时才计入延迟回忆，只有明确标记新场景的首次尝试才计为未见变式。

Dashboard 分别展示首次练习、延迟回忆、未见变式的自报完成情况、样本数与错误类别。分母为空时显示未测量，不当成零成功率。既有 SRS 评分改善占比与这些练习指标分开呈现。

测验与复习

复习给每张卡片评分；评分驱动下一次到期日。

1. 单道选择题，含 A/B/C/D 选项。
2. Guided / Recall / Transfer 模式标签与进度计数。
3. 右侧证据面板，答题后才解锁。
4. 右侧 Progress 列出每题状态（pending）。

1. 顶部计数：到期卡片、FSRS、高风险概念。
2. 复习概览活动热力图与概念掌握度列表。
3. Needs Practice 列表含各概念 stability 值。
4. 右侧 New Concepts 列表标记为 New。

概念

1. Ledger / Graph 标签与健康状态过滤计数。
2. 表格列：概念、运行、文件、claims。
3. 每行健康标签，如 Orphan 与 Contradicted。
4. 每个概念行的运行与文件链接。

1. Ledger / Graph 标签与 Refresh Graph 按钮。
2. Graphify 源卡：节点/边数、FRESH 徽章、sha256。
3. 社区过滤 chip 与 All / code / rationale 过滤器。
4. 下方图节点画布，含 Export JSON、Fit to view。

5. 常用命令

日常工作走 learn、quiz、review。下面的分组覆盖其余一切：启动 UI、管理本地数据。

日常循环

improve-run RUN_ID 会重新生成一篇课程，只有确定性评分确实更高时才保留新副本，并作为独立的运行写入、原来那次保持不变。用 --candidates N（默认 3，范围 1-10）控制尝试多少个重生候选；值越大越可能拿到更高分，但更费 token 和时间。任何安装方式都能用，包括 pip。另一个 improve 命令调整的是 AhaDiff 自身的生成 prompt，只能在 AhaDiff 源码 checkout 里运行。

维护分组

Refresh vs learn：谁会动 Graphify

6. 导出和分享

WebUI 提供静态预览、TSV/JSON 结果和 Anki 卡片。CLI 可用 export-results 导出 TSV，用 export preview 导出本地预览：

静态预览保留 document/diff 来源、结构锚点与单独标识的 review 说明；只读 MCP 暴露来源/锚点 provenance 与受限辅助摘录。分享或处理这些输出时应保留相应区分。扁平化引文或 review 评论不能变成运行证明。静态预览与 APKG 含答案，分享前应先检查内容。

7. 可选功能与评分

选择每次运行的内容

可选工具与自动化

• 标准安装包含 Anki 导出与文件监听。自动学习可能反复调用提供商；在 Git 工作目录启用 ahadiff watch 或 ahadiff serve --watch 前，请检查隐私和预算设置。
• FSRS 参数优化需要可选的 optimizer 扩展，并会安装 torch。基础卡片复习和排程无需此扩展。
• 仓库图谱叠加需要 Graphify 图文件。ahadiff graph refresh 导入已有图谱，不运行 Graphify。
• AI 工具指引是可选项。设置页在写入、更新或移除前预览具体项目文件；使用指南展示相同工具并说明用法。

理解一次运行的评分

确定性评分检查课程和证据。排除不适用的维度前，各维度满分如下：

未提供规范时，规范对齐显示 N/A。文档运行的 Diff 覆盖度和变更新颖度可学习性也显示 N/A。这些维度不会拉低总分；文档证据使用独立的覆盖检查。

80 分起为 PASS，60 分至不足 80 分为 CAUTION，低于 60 分为 FAIL。即使分数高，必需检查失败仍会让运行判为 FAIL。打开 运行详情 → 评分 可查看失败项和原因。

可选的 LLM 评判补充反馈，不覆盖该结论。评判失败时，运行详情会显示失败信息，并保留确定性分数。两种分数都不衡量你能否独立完成类似修改；请通过自己的作答和后续回忆来评估。

8. 常见问题

9. 平台与发布信息

核心 CLI 与 WebUI 面向 macOS、Linux 和 Windows。Python 的 SQLite 运行时需满足“快速开始”中的要求。以下功能有明确的平台限制。

已测试平台、已知问题和下载见 v1.4.0 发布说明。PyPI 安装包包含 WebUI。

截图和视频用于展示流程，部分细节来自早期界面。1.4.0 的操作与标签请以本指南正文为准。