Script Registry

用 SQLite + FTS5 管理 AI 编程助手（Claude Code / Codex 等）生成的脚本和文件。

核心理念：以用户意图为中心。 不只记录"生成了什么文件"，更记录"你当时对 AI 说了什么"。这样你可以用自然语言找回任何脚本——搜"把学习率调小的那个版本"而不是翻文件名。

解决什么问题

使用 AI 编程助手一段时间后，你会积累大量生成的脚本、配置文件、报告。问题是：

• 找不到：记得让 AI 做过某件事，但不记得脚本叫什么、放在哪
• 分不清：train_v37.py、train_v38.py、train_v39.py 到底哪个是哪个？
• 断了线：脚本和产生它的对话之间没有关联，丢失了上下文

Script Registry 自动追踪每次 AI 生成的文件，记录：

1. 你说了什么（用户意图原文）
2. 生成了什么（文件路径 + 完整代码快照）
3. 在哪个对话里（session ID，可回溯）
4. 和其他文件的关系（自动检测相似文件，计算 diff）

快速开始

安装

git clone https://github.com/<your-username>/script-registry.git
cd script-registry

# 无需安装依赖，纯 Python 标准库
python3 sr.py stats

可选：创建全局命令

ln -sf $(pwd)/sr.py ~/.local/bin/sr

配置（可选）

通过环境变量自定义路径：

# 数据库位置（默认：sr.py 同目录下的 registry.db）
export SR_DB=/path/to/registry.db

# Claude Code session log 目录（默认：自动检测 ~/.claude/projects/ 下最近活跃的项目）
export SR_SESSION_DIR=~/.claude/projects/-Users-you-YourProject

导入历史对话中的文件

如果你使用 Claude Code，可以一键导入所有历史 session 中生成的文件：

sr import-history

这会扫描 ~/.claude/projects/ 下的 session log，提取每次 Write 操作及其关联的用户消息。

搜索

# 自然语言搜索——搜意图、文件名、代码内容
sr search "训练脚本"
sr search "learning rate"
sr search "数据清洗"

# 查看详情
sr show 42
sr show train_v39.py
sr show 42 --code          # 含完整代码快照

# 对比两个文件：意图差异 + 代码 diff
sr diff 148 149

手动注册

sr register script.py --intent "用户的原始请求" --purpose "一句话用途"

其他命令

sr list                    # 列出最近的文件
sr list -n 50 --lang python
sr check                   # 检查哪些文件已被删除/移动
sr stats                   # 统计信息

自动注册（Claude Code Hook）

配置 PostToolUse Hook 后，每次 AI Write/Edit 文件时自动注册，无需手动操作：

// ~/.claude/settings.json → hooks.PostToolUse
{
  "matcher": "Edit|Write",
  "hooks": [
    {
      "type": "command",
      "command": "/path/to/script-registry/hooks/post-tool-register.sh"
    }
  ]
}

Hook 会自动从当前 session 提取最近的用户消息作为意图。

搜索效果示例

$ sr search "训练"

找到 3 个匹配:

  [148] ✓ step12_train.py  (python)
      路径: /my-project/scripts/train.py
      时间: 2026-03-27T22:05:24
      意图: 开始写训练脚本 作为step12
      会话: 69d5438c...
      相似: train_v2.py (65%)

  [149] ✓ train.py  (python)
      路径: /my-project/scripts/train.py
      时间: 2026-03-27T22:10:02
      意图: 看看远程电脑的配置 能并行的话可以并行 注意给cpu留20%余量
      会话: 69d5438c...

  [86] ✗ monitor.sh  (bash)
      路径: /tmp/monitor.sh
      时间: 2026-03-26T09:31:53
      意图: 帮我搞个窗口方便监控训练进度
      会话: 0435a60b...

对比两个版本：

$ sr diff 148 149

=== 对比 ===
  A: [148] train.py  (2026-03-27)
  B: [149] train.py  (2026-03-27)

── 意图对比 ──
  A 意图: 开始写训练脚本
  B 意图: 能并行的话可以并行 注意给cpu留20%余量

── 代码相似度: 82% ──
  - max_workers = 1
  + max_workers = 10
  + # 并行配置：48 核 × 80% = 38 可用核

一眼就知道：B 版本是加了并行配置，因为你说了"能并行的话可以并行"。

支持的文件类型

类别	后缀
脚本	.py .sh .js .ts .jsx .tsx
文档	.html .md .css .json .yaml .yml .toml .xml .svg .sql

技术细节

• 存储: SQLite 单文件，含 FTS5 全文索引（trigram tokenizer，支持中英文搜索）
• 搜索: FTS5 trigram（≥3字符子串匹配）+ LIKE 兜底（短词），自动中文 bigram 分词
• 相似度: difflib SequenceMatcher，文件名权重 30% + 内容权重 70%
• 代码快照: 每次注册保存完整代码，即使原文件被删除也可恢复
• 去重: 同路径同 SHA256 hash 不重复注册
• 版本谱系: 同路径文件自动建立 parent→child 关系
• 无外部依赖: 纯 Python 3 标准库

数据库 Schema

scripts (主表)        ← intents (意图，一对多)
  ↕                      ↑ session_id → Claude session log
script_diffs (相似对)
script_lineage (版本链)
scripts_fts (全文索引)

存储开销

实测 867 个文件占 16 MB。预估 1000 个文件约 20 MB，完全不是问题。

作为 Claude Code Skill 使用

将 SKILL.md 放到项目的 .claude/commands/ 目录下，或在 CLAUDE.md 中引用，Claude 就会在合适时机自动使用搜索和注册功能。

License

MIT