1实现原理 · 为什么它能做到
功能载体是 6 个本地 Python CLI（list_local_history / read_claude_session / extract_user_messages / analyze_sessions / history_index / recover_content），各自对应 inventory、精确会话重建、人工输入导出、关键词检索、混合召回、triage、文件恢复；agent 按 SKILL 路由表调用，明确禁止恢复旧进程。
daymade-claude-code/read-claude-code-history/SKILL.md
| Recent Claude Code sessions, titles, dates, or IDs | `scripts/list_local_history.py --source claude` |
SKILL.md 把『用户想要什么结果』映射到具体脚本+参数；guardrails 同时写死 'Do not run `claude --resume` or `claude --continue`'，保证这是只读证据层，读取完把证据交给 continue-claude-code-work 才能动手。
『找不到』是昂贵答案：跨多 home 全量发现是正确性根基。homes.py 枚举 CLAUDE_CONFIG_DIR、~/.claude、~/.claude-profiles/* 与 ~/.claude-* 兄弟 home；sources.py 再并入 ~/.claude/history-sources.json 注册的归档；按 Session ID 去重、以记录内时间戳而非 mtime 排序。
daymade-claude-code/read-claude-code-history/scripts/_core/homes.py
# CLAUDE_CONFIG_DIR wins first when set, then the default home.
模块 docstring 点出动机：'A tool that only looks at ~/.claude silently misses every conversation held under a profile, which is the #1 reason a real session is wrongly reported as not found'——即多 home 发现直接决定『没找到』这个结论是否可信。
对 Claude 记录做语义而非字面处理：storage label（type: user）不等于作者；忙碌期间的排队指令藏在 attachment.queued_command.prompt（origin.kind: human），只读 user 记录会丢修正。
daymade-claude-code/read-claude-code-history/SKILL.md
Treat Claude's record labels as storage metadata, not authorship proof.
SKILL 用整段约束：顶层 type: user 记录可能装命令信封/hook 样板/整段粘贴文档/agent 口吻文本/系统占位；配套 references/session_file_format.md 讲 schema、sidechain、附件、compaction、file-history 快照。
可选『混合召回』路径（history_index.py recall）：中文分词 FTS5（wangfenjin/simple libsimple，固定版本 v0.7.1 + SHA256 校验下载）+ Qwen3 嵌入向量（Apple Silicon MLX），BM25/向量融合，解决『措辞变了』的语义召回；不属于默认只读路径。
daymade-claude-code/read-claude-code-history/scripts/history_index.py
EMBEDDING_MODEL_ID = "Qwen/Qwen3-Embedding-0.6B"
同文件 SIMPLE_VERSION = v0.7.1；引用文档 hybrid_history_recall.md 明确分工：'You remember the meaning but not the wording | `history_index.py recall` | Ranked candidate sessions'，精确取证仍走 analyze_sessions.py search。安装/下载在 SKILL 里被描述为一次性 setup。
文件恢复（recover_content.py）走『报告-批准-写入』三段门禁：先对精确 Session 文件出恢复报告，人工审阅每个目标路径后才写；且禁止直接覆盖当前项目树。
daymade-claude-code/read-claude-code-history/SKILL.md
First run the recovery report against the exact Session file, review every proposed destination, then write only after the user asked to recover content. Never restore directly over the current project tree.
恢复的是 Claude file-history 记录里保存的被删/被覆写文件；把『写盘』从常规读取中隔离出来单独立规矩。
Kimi CLI 历史是该 skill 的活表面：inventory 走 list_local_history.py --source kimi，全文检索走 analyze_sessions.py search --kimi，解析 ~/.kimi-code 下的 state.json/wire JSONL（home 优先级 --kimi-home > KIMI_HOME > ~/.kimi-code）。
daymade-claude-code/read-claude-code-history/scripts/_core/kimi.py
Kimi CLI (kimi-code) stores conversations under ``~/.kimi-code/`` (override with ``KIMI_HOME``).
SKILL.md：'Kimi CLI is a live surface of this Skill, not a legacy one. It has no reader of its own'——若用 Claude 数据回答 Kimi 问题会产出假的 never happened；shared _core 说明该包是跨 read-*-history 技能捆绑复制的单一实现（SSOT 在 _conversation_core/）。
2核心能力
01跨所有 Claude home/归档的最近会话清单（含 profile 隔离会话、子代理标记、来源诊断）
02按 Session ID 精确重建时间线证据简报（compaction 边界、user/assistant 交替、排队指令、end reason、未决调用、subagent 状态、文件/记忆/工作区）
03全事件关键词检索（消息/思考/工具入出/压缩摘要/附件/队列/文件快照），默认排除 agent prompt 与当前会话自匹配
04人工输入导出为 Markdown/HTML：剥离存储污染、保留排队 prompt、去重保序不擅自主题分类
05措辞变化时的语义混合召回（可选 libsimple FTS5 + Qwen3 向量）
06triage：按时间窗/项目归类会话如何结束（interrupted/net-error/stuck-on-tool/done）
07从 file-history 快照恢复被删/被覆写文件（先报告、批准后写入）
08Kimi CLI 清单与全文检索（仓库内唯一活表面）
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | git |
| cli | rg/grep（可选路径预过滤） |
| network | github.com 发布物下载（wangfenjin/simple libsimple，固定版本+SHA256 校验，仅混合索引 setup） |
| network | Hugging Face 模型（Qwen/Qwen3-Embedding-0.6B，仅 --download-model 经 mlx_embeddings.load） |
| package | 可选 Python 依赖 chonkie/transformers（分块）与 mlx-embeddings/mlx（Apple Silicon 向量） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: python3 运行 6 个自带脚本（默认纯 stdlib）
- 网络端点: 声明外部网络访问: urllib.urlopen 下载 https://github.com/wangfenjin/simple/releases/download/v0
- 本地工作目录: 文件读写与工件输出: extract_user_messages.py 向用户给定输出基址写 Markdown/HTML
审计说明： 。默认读取路径零外发、纯本地只读（JSONL 只读、sqlite mode=ro），按准则属 blue 面；取黄色的依据是存在真实的网络外发代码路径（非默认触发）：history_index.py setup 从 github.com/wangfenjin/simple releases 下载原生 libsimple（版本固定 v0.7.1、sha256 校验、zip-slip 防护）并在进程内作为 FTS5 扩展加载，--download-model 时再经 mlx_embeddings 下载 HF 模型 Qwen/Qwen3-Embedding-0.6B；外发对象可预期（公开源）、不碰凭证、需用户显式触发，故 yellow 而非更高档。数据面为可能含凭据的本地全量会话历史，SKILL 自带分享门禁。
5第二遍独立确认
- [ok] libsimple 下载（github.com/wangfenjin/simple）调用点 — history_index.py url 构造 + urlopen；sha256 校验与 _safe_extract_zip 穿越防护真实存在。
- [ok] 无其他网络调用（排除 requests/curl/wget/其他 urlopen） — 全目录扫描仅 history_index.py 引入 urllib.request；其余脚本零网络 import。
- [ok] Kimi 表面真实存在且只读 — list_local_history.py argparse choices 含 kimi；analyze_sessions.py search 有 --kimi/--kimi-home；_core/kimi.py 只解析 state.json/wire.jsonl，无 kimi CLI 调用。
- [ok] read-only 承诺与写盘面核对 — SKILL guardrails 禁止 resume/continue；写盘仅 extract_user_messages（用户给输出基址）、recover_content（报告后批准）、history_index（可选索引库）。
- [unlocatable] Qwen 嵌入模型网络端点 — 静态证据止于 EMBEDDING_MODEL_ID + mlx_embeddings.load(...) 与 ~/.cache/huggingface 路径；HF 实际网络端点由 mlx-embeddings 库行为决定，源码未直写，未运行验证。
- [ok] 能力声明夸大检查（exact timelines/verbatim input/full-event search） — read_claude_session.py 严格解析含 compaction 前记录、extract_user_messages 去噪逻辑（NOISE_USER_PATTERNS/IMG_TOKEN_RE）、analyze_sessions 预算超时显式失败——均有代码与测试佐证。
6结论
适合： 适合需要『证明 Claude 会话里到底说过/做过什么』的场景：找回 Session ID、逐字人工输入、被删文件恢复、跨 profile/归档的完整检索；适合作为继续工作前的证据层（与 continue-claude-code-work 配对），以及把『本地历史可信检索』当基础设施的深度用户。
不适合： 不适合需要恢复旧进程继续干活或改动旧项目的请求（那是 continue-claude-code-work）；不适合无本地 Claude Code 历史的环境；不需要语义级『忘了措辞』召回的用户不必启用 history_index（省去下载与 MLX 依赖）；Kimi/Codex 问题请走对应表面，本 skill 不替代。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload read-claude-code-history.tar.gz
sha256:
Option B · Copy Guide for Agent646d5ca94bdfe86a…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.