SkillStrata

无感蒸馏可复用工具库。 从 Claude Code 代理的真实执行轨迹中，自动发现、验证、合并、沉淀程序类可复用能力，以 MCP 工具形式回灌给后续任务——让"上次写过的那个转换脚本"下次自动出现，不再重搓。

当前阶段：团队版去风险原型 → 个人通用版 file-transform MVP（L1）。纯 Python，覆盖文档转换 + 通用文件转换（CSV↔JSON、text↔md 等），含 domain adapter、artifact store、API judge、safety gate、episode builder、hook+daemon 七阶段全链路。测试随里程碑增长（python -m pytest -q 看当前数，当前 >400）。

快照

distiller init                    # 初始化数据仓库（一次性）
# 此后你在 Claude Code 里干活 —— 无感采集
# daemon 空闲时蒸馏出可复用工具
distiller ls                      # 看库里有什么
distiller show doc-to-markdown    # 看工具详情 + 分支 + 质量分
distiller usage doc-to-markdown   # 被复用了几次 / 成功还是失败
distiller pending                 # 待审的候选（ambiguous / 高价值）

怎么运行的（三进程，无感）

Claude Code（你干活）
  │ PostToolUse hook（<5ms，静默，只追加一行事件）
  ▼
traces/  ← 事件流（JSONL）
  │
  ▼ daemon（独立进程，空闲触发，低优先级，不抢资源）
  ├─ 候选发现   把碎片拼成候选，认出"这好像是 pdf→md"
  ├─ Gate 0      确定性探测 + 系统依赖检测（有 LibreOffice？→ 标搁置不静默丢）
  ├─ Replay      沙箱重放（uv venv + temp 目录，不碰工作区）
  ├─ Output Gate 属性验证（守恒 oracle：输入里可量化的内容有没有活进输出）
  ├─ 契约抽取    I/O 契约 + 行为指纹 = 合并 key
  ├─ 目的判同    这是"同一个工具的新分支"还是"另一个工具"？
  ├─ 三选一      新工具 / 新分支 / 已有分支的就地迭代
  ├─ Composer    挂分支、切 active、保留 fallback
  └─ skills/     沉淀为带 manifest + branches + fixtures + lineage 的能力

skills/ ──MCP server──> Claude Code（下次直接复用，工具出现在工具箱里）

三个关键原则：

• 无感 — daemon 在带外跑，沙箱在临时目录，采集 hook <5ms。人不被打断。
• 渐进披露 — 回灌时只给工具的元数据（名称/用途/签名/质量分），模型想用再展开。
• 价值靠复用确认 — "工具好不好"不是上来打分，而是看它被几个项目复用了、成功了几次。

安装

git clone [email protected]:mirabilitum/SkillStrata.git
cd SkillStrata
python -m pip install -e ".[dev]"
distiller init

配置（零配置默认跑）

daemon 的凭证与行为通过三项覆盖：

Judge（目的判同）默认用 Claude Haiku，复用 CC 凭证；无 key 时优雅退化为 offline 规则引擎（不阻塞主链）。 见 src/distiller/config.py 的解析链。

项目结构

src/distiller/
  contracts.py        # 冻结接口——所有模块共享
  capture.py          # M1 采集：hook 极轻事件
  enrich.py           # M1 daemon 补全（hash/media_type/确定性信号）
  discovery.py        # M2 候选发现：关联→形状过滤→提名（委托给 domain）
  gate0.py            # M2 确定性探测 + 系统二进制检测（显式搁置，不静默丢）
  safety.py           # 安全门：静态源码扫描 + 文件变更审计（免危险脚本 promoted）
  replay.py           # M3 沙箱重放（uv venv + temp 隔离）
  output_gate.py      # M3 属性验证（守恒 oracle）+ behavior_signature
  contract_extract.py # M4 契约抽取（I/O 锚 + 代码佐证 + 目的嵌入）
  classify.py         # M4+M5：目的判同 + 三选一（新工具/新分支/迭代）
  composer.py         # M5 沉淀（内存）：分支/active/retained/共享后处理
  persist.py          # 落库写路径：SkillManifest/Branch/Candidate → SQLite
  artifact_store.py   # 实现快照：promoted skill 的 impl+fixture 复制到 data-dir
  pipeline.py         # orchestrator：把各阶段焊成一条线 + 三选一驱动 composer
  judge.py            # Judge（Rule + LLM 双实现）：改善命名/归类/解释
  episode.py          # Episode Builder：长链条任务识别最终可复用能力
  mcp_server.py       # M6 MCP 暴露（promoted≠exposed）
  warmstart.py        # M6 回灌 + R_miss 检查
  observe.py          # M7a 只读观测（pull）：ls/show/usage/failures
  review.py           # M7b 审查 + 质量门控自动升级
  hook.py             # CC PostToolUse hook：极轻事件写入（<5ms，append-only）
  daemon.py           # 异步 daemon：读 traces→enrich→pipeline→落库（断点续跑）
  cli.py              # init + ls/show/usage/pending 子命令
  config.py           # 配置链：CLI flag > env > config 文件 > 默认

  domains/            # Domain Adapter 层（可插拔能力域）
    base.py               # CapabilityDomain 协议（收窄版）
    document_to_markdown.py  # 文档→MD 域（doc/docx/pdf/html→markdown）
    generic_file_transform.py  # 通用文件转换域（CSV↔JSON, text↔md 等）

参考实现 examples/doc2md.py（设计的"尺子"，不属包、不接 pipeline，见 examples/README.md）。

开发

python -m pytest -q           # 跑全部测试（数量随里程碑增长，不写死）
python -m pytest --tb=short   # 失败时看详情
git branch                    # mvp/m0-scaffold

环境陷阱：某些 Windows 运行时的系统临时目录有权限限制，会导致 pytest 在收尾清理 tmp 时报错。若遇到，把临时目录指向工作区内再跑：

$env:TEMP=(Resolve-Path '.').Path; $env:TMP=$env:TEMP; $env:TMPDIR=$env:TEMP
python -m pytest -q

工程纪律： 每个里程碑连测试一起交，运行时数据（.distiller-data/）与密钥绝不入库。去重用到的归一化（ast-grep 归一掉变量名等）只用于检测重复，入库永远是原始实现（带所有边缘处理/年轮）。