AugmentLog_Extractor

一个纯 Python 的 VS Code Augment 会话提取工具。它会从 VS Code 的本地数据目录中自动发现并恢复历史对话，修复常见中文乱码问题，去重并输出为结构化的 Markdown 文件，便于归档与检索。

主要特性

• 纯 Python、零外部二进制依赖（无需 plyvel/leveldb 等）
• 自动发现数据源（state.vscdb、webview/IndexedDB 快照等）
• 多策略恢复：优先结构化数据，其次对 webview 存储做启发式扫描
• 中文乱码修复：
  • 保留全部 Unicode（只移除 ASCII 控制字符）
  • latin1→utf8 整串回转与“分段回转”并用，修复混合乱码
  • 标题与正文统一修复
• 全局稳定去重：以 (role, content, timestamp) 为键，保留首个出现
• 清晰的 Markdown 输出样式，附带 INDEX.md 索引
• 运行时关键日志：来源发现、汇总统计、每会话写出摘要

快速开始

环境要求：Python 3.9+

可选创建虚拟环境（推荐）：

python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate

运行示例（macOS）：

./.venv/bin/python scripts/extract_full_dialogues.py \
  --data-root "/Users/<你>/Library/Application Support/Code" \
  --out-dir output/full_conversations

运行示例（Windows）：

.\.venv\Scripts\python.exe scripts\extract_full_dialogues.py `
  --data-root "$Env:APPDATA\Code" `
  --out-dir output\full_conversations

运行示例（Linux）：

./.venv/bin/python scripts/extract_full_dialogues.py \
  --data-root "$HOME/.config/Code" \
  --out-dir output/full_conversations

也支持对离线快照目录/示例数据运行（目录中包含 state.vscdb、workspaceStorage 等子目录时效果最佳）：

./.venv/bin/python scripts/extract_full_dialogues.py \
  --data-root example_data \
  --out-dir output/full_conversations-example

命令行参数

• --data-root（必需）
  • VS Code 的数据根目录。
  • 常见路径：
    • macOS: /Users/<你>/Library/Application Support/Code
    • Windows: %APPDATA%\Code
    • Linux: ~/.config/Code
  • 如果你有特定 snapshot/备份目录，也可直接指向该目录。
• --out-dir（可选，默认 output/full_conversations）
  • 导出的 Markdown 目录。
• --kv-dir（可选）
  • 覆盖自动发现的 augment-kv-store 位置；通常不需要手动指定。
• --state-db（可选）
  • 覆盖 state.vscdb 的具体路径；通常不需要手动指定。

输出结构

• 每个会话一份 Markdown 文件，默认输出到 --out-dir 指定的目录
• 顶层会按项目名分文件夹归档（基于 workspace.json 的 folder 信息推断）
• 伴随生成 INDEX.md 索引文件（列出“会话名称 → 文件路径”）
• 文件名规则：
  • {project_name}-{timestamp_slug}-{conversation_name}-{uuid}.md
  • 示例：
    • chmsee-20250914-155150-VSCodeProject-6ce840ab-2723-4a4f-95be-8a06aa36a8f1.md

Markdown 内容样式（示例）：

# 请分析example_data下的内容

- [2025-10-21T11:31:48.401Z] user:

    请分析example_data下的内容

- [2025-10-21T11:32:01.381Z] tool:

    tool_use: view (path=example_data/...)

日志说明（运行时）

• [Start] data_root=... | out_dir=...
  • 启动参数确认
• [Webview] conversations meta: N
  • Webview 元数据中发现的会话数量（若为 0，可能走启发式扫描）
• [Discovery] kv-store candidates: N 以及 sample: [...]
  • 自动发现到的 kv-store 候选路径数量与样例
• Recovered messages by ...
  • 显示采用的恢复策略（如 Webview 广域扫描）
• [Summary] conversations recovered: X | total messages: Y
  • 写文件前的总体统计
• WROTE: | msgs: A -> unique: B (removed C); title_src=meta/first_user
  • 单个会话写出摘要：原始消息数、去重后唯一数、剔除重复数、标题来源

乱码与去重策略

• 乱码修复
  • 保留所有 Unicode，仅移除 ASCII 控制字符（< 0x20，保留 \t/\r/\n）与 DEL(0x7F)
  • 若检测到“Ã/Â/ä/å/æ/ç/è/é/ï/¼/½/¾”等典型字符，尝试 latin1→utf8 回转
  • 对混合字符串进行“分段回转”：仅对连续 Latin-1 片段尝试回转，中文等非 Latin-1 区段保持不变
  • 标题与正文均走统一修复流程
• 去重
  • 以 (timestamp_iso, role, content) 为键做“全局稳定去重”，保留首个出现
  • 如需改为“仅去相邻重复”或允许“相同时间戳的重复”请告知，我可以调整策略

性能与范围控制

• 首次运行会扫描 data-root 下的多个存储位置，大量工作区/历史会话时，运行耗时会较长
• 你可以：
  • 将 --data-root 指向更具体的 workspaceStorage 子目录以缩小扫描范围
  • 或先在小目录测试验证，再对全量目录运行

隐私与安全

• 工具仅在本地读取 VS Code 数据，不会联网上传
• 输出结果中可能包含敏感信息，请在受控/私有环境使用与归档

故障排查

• 仍有中文不正常
  • 请把“文件路径 + 小段内容”发给我，我会基于样例进一步优化修复规则
• 文件名出现异常字符/过长
  • conversation_name 已做基本清理，若你的文件系统仍不友好，可告知我加强清理/截断规则
• 去重过强/过弱
  • 当前是“全局稳定去重”，如果希望更保守或更激进，请说明你的偏好

开发者笔记

• 入口脚本：scripts/extract_full_dialogues.py
• 关键函数：
  • safe_text（中文乱码修复）
  • sort_messages（统一排序）
  • _dedup_stable（全局稳定去重）
  • render_markdown（写出 Markdown 与 INDEX）
• 模式：PYTHON_ONLY = True（强制纯 Python 模式，不依赖外部二进制）