知返 AhaDiff 用户使用指南 · v1.3.8

知返 AhaDiff 用户使用指南

AhaDiff 把一次 git diff 变成带代码证据的课程、明确的 claim 状态、测验、复习卡、概念图谱和质量棘轮。它默认 local-first：每个仓库自己的 AhaDiff 状态都存在 .ahadiff/ 下。

视频教程： 英文讲解（YouTube）； 中文讲解（B 站）。两个视频分别使用对应语言界面和烧录字幕；中间字幕源文件不随公开文档树发布。安装以 pip install ahadiff 为准（现在推荐用 pipx 隔离安装，见下方安装说明）；英文讲解已是最新，中文 B 站视频正在同步更新。
上手

1. 快速开始

从 PyPI 安装已发布的 CLI，推荐用 pipx 隔离安装。只有参与 AhaDiff 开发时，才需要从源码 checkout 运行。

安装

推荐用 pipx 隔离安装 CLI 和内置 WebUI（无需 git clone）。uv tool install ahadiff 同样可用；在 venv/conda 里 pip install ahadiff 也可以。在 Homebrew/系统自带 Python 上直接 pip install 会触发 externally-managed-environment（PEP 668），改用 pipx 或 uv tool install ahadiff 即可。

pipx install ahadiff ahadiff --version

从源码开发（贡献者）

同步锁定的开发环境，再确认模块能正常运行。

uv sync --locked --dev uv run python -m ahadiff --version uv run python -m ahadiff doctor

第一次在仓库中使用

第一次在某个仓库里用 AhaDiff 时，先初始化它并确认环境。

cd /path/to/your/repo ahadiff init ahadiff doctor ahadiff config show --resolved

运行产物和复习状态留在这个仓库里。Provider 配置可以放在仓库级，也可以放在全局级。

存储门禁接受这些 SQLite 版本

3.51.3+ 3.50.4+（backport） 3.44.6+（backport）

uv tool 在 Python 3.11.14 上自带 SQLite 3.50.4。已被接受。

第一次生成课程前，先跑 ahadiff doctor 确认你的 SQLite 版本达标；它会报告检测到的版本和所需门槛，版本过低时 fail-closed 报错。版本号更高不代表自动被接受。门禁要求 SQLite 3.51.3 及以上，或回填补丁的 3.50.4+ / 3.44.6+ 版本，所以 3.51.0-3.51.2 低于门槛、不会被接受。如果 ahadiff doctor 提示你的版本不行，换一个自带 SQLite 满足门槛的 Python，例如 uv tool、python.org 安装包、Homebrew 或 conda。

欢迎页：主标语、简介段落和首次运行的快速上手。
欢迎页：打开 WebUI 后的第一屏。
  1. 衬线主标题 Ship with AI. Learn it back.
  2. 首字下沉的简介段落介绍 AhaDiff。
  3. 查看最新课程 CTA 与 uv run learn 命令片段。
  4. 右侧卡片预览最新已完成运行的课程大纲。
配置

2. 配置 Provider

配置一个 LLM provider 是 ahadiff learn 之前唯一的准备步骤。有两条路径。在 CLI 上，密钥放在环境变量里，你只把变量名交给 AhaDiff。在 WebUI Settings 里，你直接粘贴明文密钥，由 AhaDiff 替你存储（见下文「WebUI 如何存储你的密钥」）。无论哪种方式，密钥都不会进入 Git、README、manifest 或纳管的脚本。

provider test 做了什么

用一个小请求探测模型。
成功后把 provider 保存到 .ahadiff/config.toml。
密钥环境变量未设置时 fail closed。

仓库配置里接受的密钥环境变量名称：

AHADIFF_PROVIDER_API_KEY OPENAI_API_KEY ANTHROPIC_API_KEY GEMINI_API_KEY AZURE_OPENAI_API_KEY

名称

--api-key-env 是变量的名称。当变量未设置时，标识符形态的值会 fail closed，所以名称不会被误当作 bearer token 发出去。

密钥

在这条 CLI 路径上，真正的密钥留在你的 shell 环境里，从不进入命令行参数。WebUI 路径不同：它会把明文密钥写入 .ahadiff/.env（见下文）。两种方式都不会让密钥进入 Git。

配置 provider

运行 ahadiff serve 在 Settings 里添加 provider（卡片会在保存前预览模型限额，不发远程请求、不读取密钥），或在下面对应的标签里运行一次 provider test。

导出密钥和 provider base URL，然后运行一次探测。

export OPENAI_API_KEY="<your-provider-api-key>" export AHADIFF_PROVIDER_BASE_URL="<provider-base-url>" ahadiff provider test \ --name default \ --provider-class openai \ --base-url "$AHADIFF_PROVIDER_BASE_URL" \ --api-key-env OPENAI_API_KEY

不回显地读入密钥，再探测一个 Responses/API provider 示例。在 macOS / Linux 上：

export AHADIFF_PROVIDER_BASE_URL="<provider-base-url>" read -rsp "Provider API key: " AHADIFF_PROVIDER_API_KEY; export AHADIFF_PROVIDER_API_KEY; printf '\n' ahadiff provider test \ --name gpt55 \ --provider-class openai_responses \ --base-url "$AHADIFF_PROVIDER_BASE_URL" \ --model gpt-5.5 \ --api-key-env AHADIFF_PROVIDER_API_KEY \ --privacy-mode explicit_remote

在 Windows PowerShell 上，用 Read-Host -AsSecureString 读入：

$env:AHADIFF_PROVIDER_BASE_URL="<provider-base-url>" $secure = Read-Host "Provider API key" -AsSecureString $env:AHADIFF_PROVIDER_API_KEY = [System.Net.NetworkCredential]::new("", $secure).Password ahadiff provider test ` --name gpt55 ` --provider-class openai_responses ` --base-url $env:AHADIFF_PROVIDER_BASE_URL ` --model gpt-5.5 ` --api-key-env AHADIFF_PROVIDER_API_KEY ` --privacy-mode explicit_remote

官方 DeepSeek API 请使用 openai_compat，这样结构化输出会走 JSON object mode。Settings preview 确认支持后，DeepSeek v4 flash/pro 也会显示 Thinking Level 控件；无 会关闭思考，低、中、高 都会映射为 API 的 high effort。全局级 DeepSeek provider 可直接用于 Settings 保存、learn 和 improve preflight，不需要复制进每个仓库。

export DEEPSEEK_API_KEY="<your-deepseek-api-key>" ahadiff provider test \ --name deepseek \ --provider-class openai_compat \ --base-url https://api.deepseek.com \ --model deepseek-v4-flash \ --api-key-env DEEPSEEK_API_KEY \ --privacy-mode explicit_remote

指向一个本地的 OpenAI 兼容服务。Ollama 和 LM Studio 各自暴露自己的 base URL。

ahadiff provider test \ --name local \ --provider-class lmstudio \ --base-url "$LOCAL_PROVIDER_BASE_URL" \ --api-key-env AHADIFF_PROVIDER_API_KEY
设置：provider、隐私、审计、偏好和项目级 AI 工具指引。
设置：配置与诊断。
  1. 左侧设置栏：Account、Provider、Capture、Privacy、Audit。
  2. 隐私控制：隐私模式、本地模式、脱敏门、审计日志。
  3. Server 区块含 serve 端口输入框与 Save 按钮。

WebUI 如何存储你的密钥

在 Settings 里，你把明文密钥直接粘贴进 API Key 输入框；你不在那里填变量名。随后 AhaDiff 会：

  • 生成一个形如 AHADIFF_<ALIAS>_KEY 的唯一引用名。唯一性会避开你系统环境里已有的变量名，以及 .ahadiff/.env 里已有的名；冲突时加数字后缀（例如 AHADIFF_DEMO_2_KEY）。
  • 只把明文密钥写入仓库内的 .ahadiff/.env 文件。在 POSIX 上权限为 chmod 0600；在 Windows 上 chmod 不等价于 POSIX owner-only ACL，只是尽力限制（best-effort），并非强隔离。
  • 会确保这些 secret 模式（.env、.env.*、audit.private.jsonl、*.lock、*.log）被 Git 忽略：.ahadiff/.gitignore 不存在时会创建它，已存在时只追加缺失的 secret 行（你已有的行会保留）。如果这个 .gitignore 是 symlink、hardlink、reparse point，或无法安全打开，保存会被拒绝，不会写入 key。无论哪种情况，key 文件都会被正常的 git add 忽略（强制 git add -f 仍可能覆盖）。
  • 在 config.toml 里只存引用名（api_key_env 等于 AHADIFF_<ALIAS>_KEY）；明文绝不写入 config.toml。
  • 当你在字段里填了 API key 再保存时，会探测 provider 以验证连通性。这是 best-effort：探测失败不阻塞保存，UI 会显示验证结果。更新已有 provider 时如果 key 字段留空，会沿用当前 key 并跳过探测（验证结果为空）。

启动时，serve 和 CLI 都会把 .ahadiff/.env 加载进进程环境变量。如果系统环境里已存在同名变量，系统值优先、不会被覆盖。

删除 provider 时会清理它在 .ahadiff/.env 里的条目，但仅限使用 AhaDiff 保留前缀 AHADIFF_ 且没有被其它 provider 引用的条目。系统或共享的 env 名（如 OPENAI_API_KEY），以及仍被引用的名，都不会被改动。清理依据是 AHADIFF_ 前缀和引用计数，并不记录某行是否由 AhaDiff 写入，所以请把该前缀留给 AhaDiff，不要在 .ahadiff/.env 里自定义 AHADIFF_ 开头的变量。

CLI 路径未变：ahadiff provider test --api-key-env NAME 仍然使用环境变量名，现在也能解析 .ahadiff/.env 里的引用名。标识符形态、但并非已设置环境变量的值会 fail closed（不会被当作字面 key 发出）；含连字符（dash）的值则按字面 key 使用。

Windows 说明：本地 .ahadiff/.env 由 NTFS 文件夹权限保护，而非 POSIX 0600。想要更严格，可把 api_key_env 指向一个真实的 OS 环境变量（它优先生效，且绝不会被写入 .ahadiff/.env）。静态加密请使用全盘加密，如 BitLocker（macOS 上为 FileVault）。

Registry 上下文示例

openai

≈400k
普通 openai 访问的上下文预算
vs

openai_responses / API

≈1.05M
Responses / API 访问的上下文预算

对于 gpt-5.5，内置 registry 保留这两种上下文 profile。当端点报告真实的总上下文时，可信的实时探测可以覆盖任一 profile。

配置好后，你唯一的仓库级或全局级 provider（或你在 Settings 里选的生成 provider/model）会被 ahadiff learn 自动使用。同名时仓库 provider 覆盖全局 provider。只有想覆盖单次运行时才传 --provider / --model。

ahadiff learn --last

保存的 max_output_tokens 如何处理

留空 → Auto

不填值表示由 AhaDiff 为你确定输出限额。

可信硬上限

已知且可信的上限会在保存时被 clamp，并返回一条 warning。

未知 / 低置信度 / route-specific / local-runtime

这些只作为 warning。不会被当成硬性保证。

本地服务报告了错误的 JSON 能力？

只在 .ahadiff/config.toml 里设置已知的布尔 override。NewAPI 默认 supports_native_json_schema=false；如果你的网关支持原生 JSON schema，就加上 override。

[providers.local.capability_overrides] supports_native_json_schema = false
工作流

3. 生成课程

选一个 diff 来源

AhaDiff 有 10 种捕获模式。选与你改动相符的那个磁贴。发布验证会分开记录捕获覆盖和 live LLM 课程生成；v1.3.8 审计记录了全局 provider 保存回归和一次 live DeepSeek run。

生成课程和 claim 状态

AhaDiff 捕获 diff、扫描安全问题，产出 claim、课程、测验、分数和其他产物。

打开 WebUI 学习

读 Lesson 看解释，跳到 Diff 看证据，做 Quiz 检验理解，用 Review 做间隔重复。

运行与你改动相符的来源。仪表盘的 New Run 对话框对应这同一组分类。

快速（工作树）
Last commit最近一次 commit。ahadiff learn --last
Staged已暂存、准备下次提交的内容。先用 git add 暂存。ahadiff learn --staged
Unstaged尚未暂存的改动；可加未跟踪文件。ahadiff learn --unstaged --include-untracked
Git 进阶
时间窗口某个时间点以来的 commit。ahadiff learn --since "2 hours ago"
修订范围明确的 commit 范围。ahadiff learn HEAD~1..HEAD
Patch
Patch 文件磁盘上的 unified diff。ahadiff learn --patch change.diff
Patch stdin从其他工具管道传入的 diff。ahadiff learn --patch -
Patch URL远程的 unified diff。ahadiff learn --patch-url URL
文件对比
对比文件两个文件版本，不用 git。ahadiff learn --compare old.py new.py
对比目录两个目录树，不用 git。ahadiff learn --compare-dir old/ new/
10 种模式 → 捕获覆盖 v1.3.8 live DeepSeek 全局 provider run 已记录 路径范围：仅工作树模式 · 仓库相对路径
给上面任意一种加 --against-spec SPEC.md 即可把 diff 与 spec 对照；加 --spec-semantic-review 走语义检查。

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

--since

一个多 commit 的时间窗口。窗口内每个 commit 都会被捕获。
vs

--since --author

恰好一个匹配的 commit。它会跳过窗口内其他作者的 commit。

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

无符号索引 → claim 可能偏弱（课程仍会生成） 远程 URL：同样的安全检查 · 拒绝环回 / 内网 compare-dir：仅 POSIX · 其他平台 fail closed

WebUI 的 patch 字段接受粘贴的 unified diff 文本，上限 65536 字节；patch 文件、stdin 或更大的 patch 请用 CLI。CLI 的 patch 文件在仓库根目录内解析；外部生成的 patch 传 --patch -。

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

界面

4. 使用 WebUI

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

ahadiff serve ahadiff serve --port 8765 --no-browser ahadiff serve --watch # 文件监听，默认已包含

工作流一览

Diff捕获代码改动
Claims绑定 file:line 证据
Lesson生成解释
Quiz/Review用 SRS 检验记忆
Ratchet分数历史、improve 预览与导出

页面地图

页面用途
/仪表盘：最新运行、KPI、棘轮趋势和复习活动。
/run/:runId运行详情：Overview、Score、Judge、Artifacts。可选的 LLM judge 失败时，Judge 标签显示脱敏的失败面板，而非原始 provider 输出。
/run/:runId/lesson课程正文、claim 摘要、证据和知识笔记。
/run/:runId/diffUnified/Split diff、claim 圆点和 ClaimInspector。
/run/:runId/quizGuided / Recall / Transfer 题目。模式徽章标明当前题目是一次性的苏格拉底测验还是 SRS 复习卡。
/reviewFSRS 复习队列，含 Again / Hard / Good / Easy 评分。
/concepts概念账本、概念图谱和 Graphify 源。
/ratchet结果历史、benchmark 摘要、improve 预览和导出入口。
/settingsprovider、capture、隐私、审计、偏好和项目级 AI 工具指引。AI Tool Guidance 把目标分为 CLI / IDE / CI，显示使用提示，并内置一个无需 provider 的演示。
/guide日常命令和 15 个项目 AI 工具指引目标。它显示分类过滤、使用提示，以及每个目标在你应用改动前会写入什么；写入和移除仍在 Settings → AI Tool Guidance 里完成。
大约十几个 AI 工具目标会写入各工具原生的文件。Settings → AI Tool Guidance 列出全部目标并在写入前预览每个文件；除非你提交，否则它们都留在本地。例如：
  • .claude/skills/ahadiff/SKILL.md
  • .agents/skills/ahadiff/SKILL.md
  • .gemini/skills/ahadiff/SKILL.md
  • .agents/skills/ahadiff-antigravity/SKILL.md
  • .agents/skills/ahadiff-antigravity-cli/SKILL.md
  • .agents/rules/ahadiff.md
  • .github/instructions/ahadiff.instructions.md
  • .opencode/agents/ahadiff.md
  • .clinerules/ahadiff.md
  • .continue/rules/ahadiff.md
  • .cursor/rules/ahadiff.mdc
  • .roo/rules/ahadiff.md
  • .windsurf/rules/ahadiff.md
仓库级指引段落仍写在用户自管的文件里，例如 CLAUDE.md、AGENTS.md、GEMINI.md 和 .github/copilot-instructions.md。本仓库忽略生成的 .agents/ 安装，所以本地 Codex / Antigravity 的 skill 产出默认不会被提交。hooks 目标与 MCP 注册见常用命令一节。
仪表盘：最近运行、分数、通过率、棘轮趋势和复习活动。
仪表盘：一览运行、棘轮与学习信号。
  1. 顶部统计卡：总运行数、平均分、通过率、概念数、LLM 调用。
  2. Spec alignment 区块含分数、趋势、评估次数。
  3. 棘轮轨迹折线图，区分 kept 与 discarded 分数。
  4. 右侧复习活动热力日历。

Claim 与 diff

每条 claim 都链到 file:line 证据，并带五种徽章之一。glyph 和语义是产品里真实的；色调是映射到本页配色的。

✓ verified verified file:line 处有证据支撑该 claim
◆ weak weak 部分或间接证据
○ not_proven not_proven 两边都没找到证据
✕ contradicted contradicted 证据与 claim 冲突
⊘ rejected rejected claim 被丢弃
课程：claim 状态、claim 摘要、知识笔记和证据侧栏。
课程：由 diff 生成的带证据学习笔记。
  1. 顶栏含 PASS 分数、查看评分详情、标记为已学习。
  2. 右上 Compact / Hint / Full 详细程度切换。
  3. 左侧大纲栏：TL;DR、改了什么、Claims、概念。
  4. 右侧 Claims 摘要：verified / weak / not proven 计数。
Diff：diff 内容、ClaimInspector 和对应的证据行。
Diff：代码改动与行内 claim 证据联动。
  1. 中部代码 diff，红/绿标记新增与删除行。
  2. diff 上方文件标签与 Unified / Split 视图切换。
  3. 右侧 Claim Inspector 面板逐条列出 claim 卡片。
  4. claim 状态徽章把解释链回到代码行。

测验与复习

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

Again忘了；很快再见
Hard费力才想起
Good顺利想起
Easy很简单；往后推
测验：回忆与迁移题、证据揭示和常见误区。
测验：基于 claim 状态的主动回忆题。
  1. 单道选择题，含 A/B/C/D 选项。
  2. Guided / Recall / Transfer 模式标签与进度计数。
  3. 右侧证据面板，答题后才解锁。
  4. 右侧 Progress 列出每题状态（pending）。
复习：FSRS 队列，含 Again / Hard / Good / Easy 评分。
复习：按遗忘曲线排序的间隔重复队列。
  1. 顶部计数：到期卡片、FSRS、高风险概念。
  2. 复习概览活动热力图与概念掌握度列表。
  3. Needs Practice 列表含各概念 stability 值。
  4. 右侧 New Concepts 列表标记为 New。

概念

概念账本：可排序表格中的全部已学概念。
概念账本：可排序表格中的全部已学概念。
  1. Ledger / Graph 标签与健康状态过滤计数。
  2. 表格列：概念、运行、文件、claims。
  3. 每行健康标签，如 Orphan 与 Contradicted。
  4. 每个概念行的运行与文件链接。
概念图谱：Graphify 源、概念节点和图控件。
概念图谱：导入的知识图谱视图。
  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、管理本地数据。

日常循环

学习与验证

生成一次运行，然后检查、评分、改进。

ahadiff learn --last ahadiff quiz RUN_ID ahadiff review ahadiff claims RUN_ID ahadiff verify RUN_ID ahadiff score RUN_ID ahadiff improve-run RUN_ID

Serve

打开本地 WebUI。--watch 会附带工作区改动自动 learn。

ahadiff serve ahadiff serve --port 8765 --no-browser ahadiff serve --watch # 文件监听，默认已包含

Watch

工作区变更自动 learn。ahadiff serve --watch 用的是同一个监听，只是多带一个 WebUI。

ahadiff watch ahadiff watch --debounce 2.0 --cooldown 30.0 ahadiff watch --dry-run

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

维护分组

Database

对 review.sqlite 跑 SQLite 完整性门禁。

ahadiff db check

Graph

查看并重新导入 Graphify 产物。

ahadiff graph status ahadiff graph import ahadiff graph refresh

Concepts

列出、验证并 lint 概念账本。

ahadiff concepts list ahadiff concepts verify ahadiff concepts lint

Export

把结果写到磁盘以便分享（见导出和分享）。

ahadiff export-results ahadiff export preview RUN_ID

Challenge

需要 opt-in。从一次运行构建 challenge，再查看状态。

ahadiff challenge build RUN_ID ahadiff challenge status

MCP

AhaDiff 自带只读 MCP server，提供 7 个工具：runs、run 摘要、到期卡片、搜索、概念、统计、lesson 问答。每个仓库注册一次：

# Claude Code claude mcp add ahadiff -- ahadiff mcp-server --repo-root <path> # Codex CLI codex mcp add ahadiff -- ahadiff mcp-server --repo-root <path>

Git hooks

ahadiff install hooks 写入仅提醒的 git hooks：每次 commit 后，post-commit hook 打印一行提示（运行 ahadiff learn HEAD~1..HEAD 学回这次提交）；push 前 pre-push hook 打印 verify 提醒。这些 hooks 不会运行 learn，不会阻塞 commit，自身失败也会被吞掉。加 --auto-learn 进入免操作模式：post-commit hook 在后台运行 ahadiff learn --last，输出追加到 .ahadiff/hooks.log。GUI 客户端提交也能用：hook 会回退到安装时记录的 ahadiff 路径；实在找不到时只在日志里追加一条跳过记录，不会卡住 commit。learnability gate 照常生效，琐碎提交在调用 LLM 前就会跳过。两次 commit 间隔过近时，per-repo 写锁会让第二个 learn 直接失败并写入日志；查看日志或自己重跑 ahadiff learn --last。带或不带该 flag 重跑 ahadiff install hooks 即可原地切换模式。仅支持 macOS/Linux。

ahadiff install hooks ahadiff install hooks --auto-learn

Refresh vs learn：谁会动 Graphify

graph refresh / WebUI refresh

只导入已有产物。它不运行 graphify update。
vs

learn run

存在 Graphify CLI 时先运行 graphify update，再导入。
Refresh 超时 600s
输出

6. 导出和分享

WebUI 里的 Ratchet / Export 入口提供四种格式。CLI 覆盖同样的范围。

ahadiff export-results ahadiff export preview RUN_ID --out .ahadiff/export-preview

静态预览

一个 strict-local 静态包，带确定性 zip。没有任何东西离开本机。

TSV

结果以制表符分隔，供表格软件使用。

JSON

结果以 JSON 输出，供脚本和工具使用。

Anki .apkg

把活跃复习卡导出为 Anki 牌组。

默认

无需额外安装。

APKG 导出在标准安装下默认即可用，因为已内置 genanki。
能力

7. 能力说明：默认、opt-in 与依赖

能力徽章区分默认行为、opt-in 流程和依赖支撑的导出。点开任意卡片的 Details 看确切行为。

默认 安装即可用

Lesson / Claims / Quiz / Score

默认流水线，在 ahadiff learn 之后产出。

Details

会生成哪些产物取决于 diff 及其 learnability。缺少符号级证明时，仅 patch 的捕获可以使用偏弱的 diff 锚定 claim。S1 语义蕴含仍是私有 shadow-only 测量，不是语义证明。在 Quiz 里，源证据在你答题前一直锁定。

可选 LLM judge

仅供参考；确定性分数仍是主判据。

Details

judge 成功运行会写 judge.json。失败会写一份有界、脱敏的 judge_failure.json，含 provider、model、错误类型和一条安全消息。缺失的 judge 产物返回 404，而不是让 API 崩溃。

测验题量

默认固定为 3；自适应需 opt-in。

Details

固定模式接受 1-30 题。在 Settings 里，或用 --quiz-mode auto，AhaDiff 会用 diff 统计选一个有界题量；自适应默认范围是 3-12。

结构化 JSON 输出

JSON object 模式，带一次 validation retry。

Details

公开产物保持不变。只有 provider 能力报告支持时才用原生 schema。不支持的模式会降级；截断或畸形的 fallback JSON 会被重试，而非接受。

自适应捕获限额

全新配置走 Auto；你定制某个限额后转 Manual。

Details

Auto 模式从五个输入确定捕获限额：

provider 探测 model registry 输出预留 安全预留 CJK 密度

编辑其中任意一项都会把仓库迁移到 Manual 模式：

capture.max_files capture.hard_limit capture.max_patch_bytes
patch 上限 50 MiB

Provider 智能配置

在 Settings 里保存前预览草稿模型限额。

Details

provider 卡片按草稿 provider class、model、base URL 和可选的 limits profile 预览限额，而不会在每次编辑都做远程探测。它显示是否支持 thinking、低置信度 warning、建议的最大输出，以及保存 API 返回的任何 clamp。只有检测到官方 DeepSeek API 路由时，DeepSeek v4 flash/pro 才会显示 Thinking Level；无 会关闭思考，低、中、高 会映射为 API 的 high effort。普通 OpenAI-compatible 路由仍以后端 metadata 为准。生成与评判限额分开展示。

WebUI

Welcome、Dashboard、Diff 和 Review 用 ahadiff serve 打开。

Details

Welcome 的 Before/After 演示会把过长的原始 diff 折叠到课程高度，并显示可见 / 总行数。短或空的 diff 没有折叠控件。

AI Tool Guidance

Settings 负责写文件；Guide 只读。

Details

Settings 为 15 个安装目标显示：

  • CLI / IDE / CI 分组
  • 本地化的快速上手步骤
  • 示例 prompt 与预期行为
  • 平台说明
  • 一个无需 provider 的本地演示

Settings

用受保护的原子替换写文件。

Guide

对同样的提示和文件写入只读预览；没有写入 / 移除按钮。

在平台支持处，回滚会恢复内容和权限模式

Opt-in 默认关闭，开了才用

Challenge

默认关闭；通过 config 启用。

Details

CLI 暴露 build / status；完整进阶通过 WebUI / API 进行。

Spec alignment

仅在带 --against-spec 时运行。

Details

加 --spec-semantic-review 走语义检查。没有 spec 的运行会把该维度渲染为 N/A。

依赖 需要 extra 或外部产物

LLM Provider（自带 BYOK）

知返用你自己配置的 LLM Provider 运行：9 种格式任选，模型自己定，不限定具体型号。在『配置 Provider』里设置。

Details

使用前设置好 provider、base URL、model 和 API 密钥环境变量。DeepSeek BYOK 使用 openai_compat 和 https://api.deepseek.com；AhaDiff 在这条 route 上使用 JSON object mode，而不是 native JSON schema。

APKG 导出

默认即可用；已内置 genanki。

Details

APKG 导出在标准安装下默认即可用，因为已内置 genanki。当前活跃复习卡无需额外安装即可导出。

Serve --watch（serve + 自动 learn）

默认即可用；文件监听已内置。

Details

文件监听默认已包含，ahadiff serve --watch 开箱即用：一边提供 WebUI，一边在工作区改动时自动 learn——和 ahadiff watch 是同一套监听。你也可以手动运行 ahadiff learn。

Watch（自动 learn）

监听工作区变更并自动 learn。

Details

ahadiff watch 监听工作区（未暂存 + 未跟踪文件），变更后自动运行 learn。默认 debounce 2.0s、cooldown 30.0s。--dry-run 只捕获 diff 不生成 lesson；--force-learn 跳过 learnability gate。可在任意目录运行。日志文件请放在仓库之外：写进被监听目录会再次触发 watcher。

Graphify refresh

导入已有产物；上限 50000 个节点。

Details

它把 graphify-out/graph.json 重新导入 AhaDiff 缓存，不运行 graphify update。上限是 graph.max_nodes_import（默认 50000）；超限的 refresh 返回 GRAPH_NODE_LIMIT。

一次运行如何评分

八个维度，100 分。分数门禁、contradicted claims、证据覆盖或安全门禁都可能让运行失败。

accuracy20 分门禁 ≥14
evidence18 分门禁 ≥12
diff_coverage14 分
learnability14 分
quiz_transfer10 分
spec_alignment10 分
conciseness8 分
safety_privacy6 分
当一道硬门禁触发，或 critical_safety_findings 命中时，一个运行即使分数很高也会 FAIL。
运行详情概览：单次 learn 运行的结果与元数据。
运行详情概览：单次 learn 运行的结果与元数据。
  1. Overview / Score / Judge / Artifacts 标签栏。
  2. FAIL 横幅含分数与未通过门禁原因。
  3. 元数据行：base ref、语言、来源类型、prompt 版本。
  4. Graphify Signoff 卡：passed、新鲜度、节点与边数。
运行详情评分：8 维评估明细。
运行详情评分：8 维评估明细。
  1. FAIL 徽章、总分、未通过门禁数。
  2. 八个维度评分卡片，各带进度条。
  3. Hard Gates 行，critical safety findings 红色未通过。
  4. Spec Alignment 区块说明本次运行无相关产物。
帮助

8. 常见问题

为什么没有 Lesson / Diff / Quiz？

这些页面需要一个具体的 run_id。先至少运行一次 ahadiff learn，再从仪表盘或命令输出里打开对应的运行。

provider 失败了怎么办？

跑诊断并重新测试 provider。在 Windows PowerShell 上，用 $env: 形式设置变量并传 --base-url $env:AHADIFF_PROVIDER_BASE_URL，如配置 Provider所示。

ahadiff doctor ahadiff config show --resolved

然后重新运行配置 Provider里的对应 provider 命令。

课程被跳过了怎么办？

可能 diff 太小、learnability 太低，或没有足够可用的 claim 状态。如果你确定这就是要学的改动，用 --force-learn 重跑。

怎么改测验题量？

用 Settings → Preferences。固定模式总是问配置好的题数，从 1 到 30。自适应模式用捕获到的 diff 统计；它的默认范围是 3-12，没有这些统计的旧运行会回退到固定题数。

捕获限额是怎么选的？

新仓库走 Auto 捕获，按一条优先级阶梯确定限额：

实时 provider 探测数据。
内置的 model registry。
保守默认值。
生成与评判限额分别解析。输出预留只从输入预算里扣减一次。只有像 Gemini 这样显式 split-envelope 的行，才会把输入加输出当成总上下文。

Manual 模式保留你在 config 或 Settings 里设的数值。Settings 的 provider 表单按未保存的草稿预览这些限额，不做远程探测。

LLM judge 决定最终判定吗？

不。最终判定来自确定性的 score.json 和硬门禁。judge.json 仅供参考；它帮助解释模型反馈，但不会覆盖确定性判定。当某个维度不适用，例如无 spec 运行上的 spec_alignment，Score 和 Judge 会把它渲染为 N/A / 0/0。

Accuracy / Evidence 门禁为什么会变？

基线阈值不变：

Accuracy 14/20 Evidence 12/18

大 diff 可以用一个由可见文件、hunk 和改动行得出的自适应阈值，ratio、regime 和 basis 会写入 hard_gates.*.policy。这绝不会放过坏证据。出现以下情况时运行仍会失败：

rejected claim 占比过高 存在 contradicted claim 安全问题 证据确实缺失
Diff Coverage 怎么判定？

Diff Coverage 只用持久化的 line_map.json 里可见的文件和 hunk：

仅可见文件作分母 按改动行加权 hunk 数下限 自适应锚定阈值

被省略的文件不进入分母。hunk 数下限让微小 hunk 仍被计入。硬门禁把它的 ratio、regime 和可见 basis 写进门禁详情。

哪些安全发现会让运行失败？

一个未缓解的 Critical 安全发现会让运行失败。只有当本地捕获记录显示完整的脱敏形态（含 rule、hash、source、line 和 column），一个 Critical 密钥发现才会被视为已缓解。

能保证没有 bug 吗？

不能。AhaDiff 通过保持数据本地、把课程 claim 链到 diff 证据、暴露确定性分数和硬门禁详情来降低风险。你仍应在依赖某个改动前审阅生成的课程并跑你常规的测试套件。发布状态请看当前的 GitHub Actions 和 release notes，而非这份静态指南。

说明

9. 关于本文档

本指南里的截图仅为示例。它们不含任何真实 provider 凭证、仓库内容或用户数据。

平台支持

macOS 是 v1.3.8 的本地验证平台；Windows 路径和全局配置行为由目标单测覆盖，真实 Windows runtime 状态以 release workflow 为准。Antigravity 在真实检查跑通前仍为 Unknown/blocked。两个功能仅限 POSIX。

功能macOS · LinuxWindows
核心 CLI✓✓
serve + WebUI✓✓
--compare-dir✓✗
hooks 安装目标✓✗
安装回滚✓部分
--compare-dir 需要仅在 macOS / Linux 上可用的安全目录文件描述符，其他平台 fail closed。hooks 目标使用 POSIX shell 钩子。hooks 默认仅提醒；--auto-learn 变体见 Git hooks 卡片。回滚在 POSIX 上于原子替换前恢复权限模式，并在缺少 fchmod 的平台于替换后尽力恢复权限模式。

验证快照

当前文档快照记录的本地检查。v1.3.8 本地 gate 覆盖后端 unit/integration/eval、ruff/format/pyright、viewer typecheck/Vitest/build、i18n parity、真实 serve 保存复现和一次 live DeepSeek learn。发布和 CI 状态以 GitHub Actions 为准。

已验证

后端 unit ruff / format / pyright viewer Vitest + build i18n parity macOS 本地 v1.3.8 gate 已记录 live DeepSeek 全局 provider run Antigravity Unknown/blocked
本指南里的 10 种 learn 口径指捕获覆盖；只有验证审计逐项列出 command、run_id、exit code 和 lesson/claims/quiz/cards 产物时，才可写成 live LLM 课程生成覆盖。v1.3.8 审计把 DeepSeek 全局 provider 回归与旧 10-mode 矩阵分开记录；GitHub Release 和 PyPI publish 由 release workflow 与 release notes 记录。