obsidian-session-export — 跨 Agent 会话逐字导出到 Obsidian

版本：以 git 提交为准（main 最新：12c40f3，2026-08-16） · 状态：维护中 核心特点：任意 Agent 的会话记录本地逐字导出为 Obsidian 笔记，日志与总结骨架 不经过 LLM；自动扫描 Obsidian 库，无需手填路径。

本技能是原 obsidian-harness-export 的跨 Agent 通用升级版：从 Codex / Claude Code / pi / Hanako / OpenCode / Hermes / Z Code 等本地会话记录中提取 「用户消息 + 每轮最终回复」，逐字生成 Obsidian 笔记。两种模式：模式一（日志） 产出逐字日志 + 总结骨架 + 可选代码引用；模式二（内容）产出单文件内容版。 部署后以 obsidian-harness-export 技能名被 Codex 发现，旧命令（--rollout） 保持兼容。

一、架构 / 核心概念速览

模块	职责
SKILL.md	技能说明：触发词、两种模式、命令与验证
scripts/export_session.py	核心脚本：多格式提取 → 范围选择 → 渲染笔记
scripts/export_to_obsidian.py	兼容旧入口：--rollout → --session 映射
references/agent-formats.md	各 Agent 会话存储位置、格式与限制速查

关键流程：定位会话（--agent auto / --session）→ 提取事件（本地，无 LLM） → 选择范围（--preview / 轮次 / 时间 / 关键词）→ 定位 Obsidian 库 （--out / 自动扫描 / --vault）→ 渲染（日志 / 内容 / 总结骨架）。

二、目录结构与文件职责

obsidian-session-export/
├── SKILL.md                     # 技能主文档（触发与用法）
├── agents/
│   └── openai.yaml              # Codex UI 元数据
├── references/
│   └── agent-formats.md         # 各 Agent 会话格式与限制
└── scripts/
    ├── export_session.py        # 核心导出脚本（跨 Agent、双模式、选择导出）
    └── export_to_obsidian.py    # 旧命令兼容入口（--rollout）

三、快速开始

# 校验技能结构
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py .

# 直接使用（自动找最新会话 + 自动扫描 Obsidian 库）
python3 scripts/export_session.py --agent auto --date 2026-08-16 --title "我的会话"

# 导出指定会话的最近 5 轮（日志模式，进 <库>/会话日志/）
python3 scripts/export_session.py --agent codex --session <rollout路径> \
  --last 5 --date 2026-08-16 --title "最近5轮"

# 部署到 Codex 安装目录（技能名保持 obsidian-harness-export）
cp -R . ~/.codex/skills/obsidian-harness-export/

四、配置说明

• 无需 API key / 环境变量；仅需 Python 3。
• 会话来源：各 Agent 本地默认位置（见 references/agent-formats.md）。
• Obsidian 库：自动扫描 iCloud Obsidian、~/Documents、家目录（以 .obsidian 为标识）；多个 / 找不到时用 --vault 或 --out 指定；--list-vaults 查看。
• 输出默认：内容模式 → <库>/会话内容/；日志模式 → <库>/会话日志/。

五、文档导航

• SKILL.md：用法与命令（主文档）
• references/agent-formats.md：各 Agent 会话位置与限制
• 本 README：项目定位与结构导航

六、边界与已知限制

• 不做：不归纳 / 改写正文（仅总结骨架由 Agent 补写）；不推送任何仓库。
• 已知限制：
  • Cline / Kilo Code / Grok Build 无标准本地 JSONL，需应用导出后用 generic 兜底；
  • Z Code 为 model-io 最佳努力解析；
  • file:// 可点击链接（--keep-links）的打开行为取决于系统 / Obsidian 版本；
  • 导出进行中的会话时，最后一轮回复可能尚未落盘（属正常）。

七、常见问题 / 故障排查

• 找不到 Obsidian 库 → 用 --list-vaults 检查；--vault <库路径> 或 --out 指定。
• 提取为空 → 确认 --agent / --session（SQLite 用 --list-sessions 查 ID）。
• 不知道导出哪几轮 → 先 --preview 看轮次编号，再 --from/--to。
• 只要某段内容 → --since/--until 或 --from-match/--to-match。

八、许可

本项目基于 MIT License 开源 · © 2026 jifeng15 · 无致谢。