一个轻量的旁路观察工具：你用 Claude Code 或 Codex 编程时它照常工作，任务结束后运行一条命令， airecap 读取本次会话记录，提炼你接触到的技能点，生成一份由内部证据校验的个性化学习复盘（小白 / 专家两种模式）， 并把学习信号写入本地库、按日期归档 markdown。
核心理念：让你知道「AI 刚才做了什么、为什么这么做、我能从中学到什么」。
四层管道，数据来自 Claude Code / Codex 本地会话（公开消息、操作轨迹、报错、token 成本）：
① 捕获 Capture 自动发现 Claude ~/.claude/projects/ 或 Codex ~/.codex/sessions/
↓
② 结构化 Structure 归约成任务轨迹：请求 / 文件变更 / 命令 / 探索(Read/Grep/Glob/Web) /
子代理任务 / 报错 / 可观察决策证据
↓
③ 提炼 Extract 在推理+命令+探索+文件片段里匹配技能，只挑 0-3 个强证据技术
↓
④ 复盘+写入 Recap 当前 Codex/Claude 宿主模型生成（默认）→ 本地校验 + markdown 归档 + 写学习信号
「AI 的计划方案」扫描整段对话，只归并同时拥有成功实施与成功验证证据的最终方案；
某次 Plan Mode 文本、建议、失败补丁或未验证修改都不能单独进入该栏目。
每个核心结论在后台引用 E1、E2 等证据编号并经过校验，但编号、证据索引和
质量报告不会进入公开输出。成功复盘提炼出的决策与技术复用方法会写入本地长期记忆。
复盘公开内容固定为五类，目标约 4000–8000 字。每个判断先回到本次真实文件、函数、 命令、错误或用户要求，再只向邻近场景泛化一层；证据不足时宁可少写，不填充空话。 主标题由模型扫描整段对话后生成，用一句话概括核心目标和最终完成结果，不再照搬会话首条消息。 归档文件名仍使用会话编号，避免标题中的特殊字符影响跨平台打开。
| 区块 | 内容 |
|---|---|
| 这次做成了什么 | 3–4 个短段落说明目标、具体成果、验证结果和仍存在的边界；总计不超过 1000 字，单段约 250 字以内 |
| 关键决策是怎么定的 | 2–4 个高影响选择：局面、选择依据、权衡与结果 |
| AI 的计划方案 | 按目标归并整段对话中已实施且已验证的方案：目标、最终方案、实施步骤、验证和结果 |
| 你的 Prompt 写得怎么样 | 宁缺毋滥筛选 0-3 条真正有价值或确实导致误解的 Prompt，并给可复制版本 |
| 用到的技术：如何复用与底层原理 | 精选 0–3 项技术，说明本次用法、底层机制、复用步骤和适用边界；若 AI 确实写入了关键代码，再附 1–3 段“核心代码 Review” |
“核心代码 Review”只会展示成功写入真实代码文件、且值得学习的新增代码。airecap 会先脱敏， 再要求模型逐字引用变更证据中的连续片段，并解释它解决了什么、调用或数据如何流动、容易在哪出错。 配置文件、删除内容、失败补丁和普通样板代码不会被拿来凑数；本次没有合格代码时不会显示该小节。
复盘由两个正交维度塑形——mode 决定语言深度，focus 决定内容重心：
| 小白模式 | 专家模式 | |
|---|---|---|
| 语言 | 通俗、比喻、无缩写 | 术语精确、讲底层原理 |
| 计划方案 | 用人话解释方案如何真正落地 | 讲清跨模块实施、验证边界与最终结果 |
| 技术原理 | 先解释术语，再给可操作步骤 | 增加失效场景、性能与安全权衡 |
切换到小白模式：
# 设为默认模式。Codex 的 $airecap、Claude Code 的 /airecap 和自动复盘都会读取它
airecap config -m beginner
# 查看当前配置，确认“模式 mode”为 beginner
airecap config
# 需要切回专家模式时
airecap config -m expert如果使用独立终端的 API Provider，只想让本次复盘采用小白模式，可以在 recap 命令中
临时传入 -m beginner，不会修改默认配置：
airecap recap -m beginner -p anthropic --source codex小白模式只改变解释方式：首次出现的术语会用通俗语言说明，实施步骤会写得更容易照着操作； 证据校验、隐私脱敏、五个公开栏目和 4000–8000 字的总篇幅规则都不会改变。
想学通用解决问题能力，还是 AI 用到的具体技术？focus 决定各区块的详略与顺序，
五类内容不变，focus 只调整计划方案和技术部分的深度与先后：
| focus | 领先/加厚的区块 | 压缩的区块 | 适合 |
|---|---|---|---|
application（应用层） |
计划方案详细讲跨多轮实施与验证 | 技术只留最相关的 0–2 项 | 学方案如何落地 |
technical（底层） |
技术提前，深入机制与失效条件 | 计划方案保持完整但精炼 | 学 AI 用到的技术 |
balanced（均衡，默认） |
计划方案和技术都给到位 | — | 两边都想学 |
focus 与 mode 自由组合（2×3）。用 -f/--focus 临时切，或 airecap config -f application 永久设。
需要 Python 3.10–3.13。建议先创建虚拟环境。
cd ai-help-study
py -m pip install -e .
airecap init --yes
airecap doctorcd ai-help-study
python3 -m pip install -e .
airecap init --yes
airecap doctor默认 provider=host，在 Codex/Claude 对话里使用当前模型，不需要 API Key。只有在后台、CI
或独立终端使用 anthropic/openai/deepseek 时才复制 .env.example 并填写对应 Key。
不想每次手动敲命令？让 airecap 在每轮对话结束时自动复盘：
airecap install # 同时安装 Claude Code + Codex 集成
airecap install --target codex # 只安装 Codex Stop hook + $airecap Skill
airecap uninstall --target codex # 只移除 Codex 集成- Claude Code 触发点：每轮回答完、控制权交回你时（Stop hook）。
- Codex CLI/IDE 触发点：每个 turn 停止时运行原生
Stophook。 - 直接用宿主模型：
provider=host时 hook 让当前 Codex/Claude 额外继续一轮，调用 airecap Skill 生成复盘；Python 进程不调用模型 API，也不检查 API Key。 - 不刷屏：Claude 与 Codex 都默认冷却 30 分钟；结果写进
~/.airecap/archive/，用airecap history查看。 - 手动触发：Claude Code 输入
/airecap；Codex 输入$airecap。手动复盘不受自动冷却限制。 - 宿主不可用不降级：普通终端直接运行默认的
airecap recap会提示你回到 Codex/Claude 对话，不会静默切换成某个 API Provider。
自动 hook 使用独立的 hook.provider / codex_hook.provider，默认都是 host，不会被项目
.env 中用于 CLI/CI 的 AIRECAP_PROVIDER 偷偷改成 API。只有你在用户配置中明确把 hook
provider 改成 anthropic/openai/deepseek，才会启用后台 API worker。
install 把 hook 写进 ~/.claude/settings.json（幂等，保留你已有的 hooks/权限配置），
命令串用当前 Python 解释器的绝对路径，规避 Windows PATH/shell 差异。整体开关见
settings.yaml 的 hook.enabled。
安装器把同一份 Skill 分别复制到 ~/.claude/skills/airecap/ 和
~/.codex/skills/airecap/，并保留用户已有 hooks。Codex CLI 用户重启后输入 /hooks
审核并信任新增 hook；未信任前自动复盘会被跳过。
Codex Desktop 当前没有公开、稳定的 Stop 生命周期入口，provider=host 因此不启动 rollout
watcher，也不会偷偷改用 API；桌面端请手动输入 $airecap。如果你显式配置 API Provider，
原有 watcher/后台 worker 仍可用于无人值守场景。
# 在 Codex / Claude Code 对话中（默认 host，不需要 API Key）：
$airecap # Codex 手动复盘
/airecap # Claude Code 手动复盘
# 会话发现和隐私预览仍是普通 CLI 命令：
airecap sources # 查看当前项目发现了哪些会话
airecap preview # 预览脱敏后的宿主任务材料，不调用模型
airecap config # 查看当前配置
airecap config -m beginner # 永久切换到小白模式（Codex/Claude Skill 也读取此配置）
airecap config -m expert # 永久切换到专家模式
airecap config -f application # 永久侧重应用层
airecap history # 查看历史复盘 + 技能画像
airecap retry <session_id> # 重试失败的后台复盘
airecap doctor # 检查环境、配置、会话来源与隐私告知
# 后台、CI、独立终端：必须显式选择 API Provider
airecap recap -p anthropic --source codex
airecap recap -p deepseek # 用 DeepSeek
airecap recap -p deepseek --model deepseek-reasoner
airecap recap --base-url https://your-relay.com/v1 # 走中转站端点支持四种 provider。host 是默认值；其它三种才是直接 API 调用：
| provider | 协议 | 默认模型 | 默认端点 | 用途 |
|---|---|---|---|---|
host |
Codex/Claude Skill 两阶段桥接 | 当前对话模型 | — | 对话内手动/自动复盘；不需要 API Key，不允许静默降级 |
anthropic |
Anthropic 原生 tool_use | claude-sonnet-5 |
官方 | 官方 Anthropic，或 Anthropic 协议中转站（配 base_url） |
deepseek |
OpenAI function calling | deepseek-chat |
https://api.deepseek.com |
DeepSeek |
openai |
OpenAI function calling | gpt-4o |
官方 | 官方 OpenAI，或 OpenAI 协议中转站（配 base_url） |
配置方式（优先级：CLI 参数 > 环境变量 > ~/.airecap/settings.yaml > 内置默认）：
# 方式一：命令行临时指定 API Provider
airecap recap -p deepseek
# 方式二：永久写入用户配置
airecap config -p deepseek
airecap config --base-url https://your-relay.example.com/v1
# 方式三：环境变量 / .env
AIRECAP_PROVIDER=deepseek
AIRECAP_MODEL=deepseek-chat # 覆盖模型（留空用 provider 默认）
AIRECAP_BASE_URL=https://relay/v1 # 中转站端点（通用）host 不读取 API Key。API Provider 可用专用变量（ANTHROPIC_API_KEY / DEEPSEEK_API_KEY / OPENAI_API_KEY），
或通用的 AIRECAP_API_KEY（省得记专用名，且优先级更高）。中转站：一般给中转站的 Key + 端点，
Anthropic 协议站用 provider=anthropic，OpenAI 协议站用 provider=openai（大多数中转站是 OpenAI 协议）。
复盘里用到 emoji、项目符号 • 等装饰符号，在非 UTF-8 终端（Windows GBK/cp936）下不可编码。
airecap 在渲染层自动把这些符号降级为 ASCII 近似（•→-、🔑→[key]、✅→[x]），
终端面板边框同时切换为 ASCII 画框，中文本身在 GBK 下可编码、保持原样。这套逻辑与 shell 无关，PowerShell / cmd / Git Bash 一视同仁，
无需改 .bashrc 或 PowerShell profile。每次降级都会记进 ~/.airecap/airecap.log（含符号与位置），
便于判断是否要进一步优化渲染。
想看完整 Unicode（emoji、原样符号）？把终端切到 UTF-8 即可（可选增强，非必需）：
# PowerShell（当前会话）
chcp 65001
$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new()推荐直接用 Windows Terminal，默认 UTF-8，开箱即完整显示。
长期数据写入 ~/.airecap/：
~/.airecap/
settings.yaml # 你的配置覆盖（可选）
airecap.db # SQLite：学习信号、任务状态、长期决策记忆
archive/YYYY-MM-DD/xxxx.md # 按日期归档的复盘
host_jobs/ # 宿主两阶段任务快照；成功后自动清理
宿主 Skill 生成时会在当前项目短暂创建 .airecap-host/<job>.json 结果模板；commit
成功或 abort 后自动删除。中断后遗留的模板不应提交到 Git。
- 默认在交给宿主或 API 模型前遮盖常见密钥、认证头、密码、URL 凭据和本机用户目录。
- 来源中真实存在的推理摘要可以参与归纳；成品只展示决策摘要，不直接展开原始内部思维。
- 第一次运行
init或install会显示外发说明；自动 hook 不会每次弹窗。 airecap preview展示相同的脱敏摘要；host 任务快照也只保存脱敏后的数据。- 可在
~/.airecap/settings.yaml设置privacy.mode: strict|balanced|off。 - 完整说明见 PRIVACY.md。
不做简单计数，而是记录学习信号用于画像：
ai_did_it_silently—— AI 用了某技能，但你全程没追问（被动暴露）user_asked_about_it—— 你在会话中追问了该技能（主动学习信号，画像里权重更高）
user_did_it_themselves（你自己写对的）需要观测非 AI 的文件变更，纯 transcript 拿不到，属于 Phase 2。
airecap/settings.yaml 是内置默认，可在 ~/.airecap/settings.yaml 覆盖任意字段。
优先级：CLI 参数 > ~/.airecap/settings.yaml > 内置默认。
pip install -e ".[dev]" # 装上 pytest
pytest # 跑回归测试回归测试固化了几处关键行为：LLM 输出（skill_point / thinking_step）偏离形态的
结构化修正（tests/test_recap_schema.py）、cp936 终端下装饰符号的 ASCII 降级
（tests/test_terminal.py）、终端面板在 UTF-8 与 GBK 流下的渲染
（tests/test_render.py）、Claude Code 工具归类与「思考→行动」配对
（tests/test_timeline.py）、Stop hook 的冷却限流与防递归
（tests/test_hook.py）、全局 hook 的幂等合并与精确移除（tests/test_install.py）。
- Phase 1（MVP）：手动
airecap recap，transcript 捕获，SQLite 信号，双模式复盘，markdown 归档 - Phase 2（部分完成）：✅ Claude Code Stop hook 自动触发（
airecap install，冷却限流 + 后台 detached）； 待办：文件监听补user_did_it_themselves信号；skill 表升级 embedding 检索；记忆后端可切 mem0 - Phase 3：学习信号接入主动教学闭环（观察 → 画像 → 主动引导）