@yottameta/yotta-logs 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 更新日志
 
+## v0.2.0 (2026-08-27)
+
+多格式通用化：不再只认 JSONL，按「格式族 × 字段别名归一 + 配置兜底」适配一切格式（老张拍板三点：方向认可 / 版本 v0.2.0 / 默认检索范围动作工时定）：
+
+- **五大格式族 reader**：JSONL（支持嵌套子目录与 Codex rollout payload 形态）/ 单文件 JSON（数组、dict-of-lists）/ SQLite（opencode schema 实测 + 通用列映射兜底，只读 mode=ro）/ Markdown（YAML frontmatter 结构化记忆 + 自由笔记）/ 二进制（只降级读标题不崩）。
+- **统一 Record 模型**：{source, format, kind, session, time, role, text, path, meta}；字段别名归一（time / role / text / session / title），秒 / 毫秒自动推断，JSON 字符串解包。
+- **discover 全源登记**：locate 遍历所有 reader 的 discover()，登记 Codex / Claude Code / Clawdbot / opencode（XDG_DATA_HOME / OPENCODE_DATA / 默认路径）/ VS Code·Cursor state.vscdb / Continue / yotta-memory（memory_home 配置）/ Codex 笔记 / Aider / Windsurf 等已知根。
+- **配置兜底**：~/.config/yotta-logs/config.json（$YOTTA_LOGS_CONFIG 覆盖），sources[] 自定义源（table / col_time / col_role / col_text / col_session / col_title），引擎零改动接入怪格式。
+- **过滤与默认范围**：新增 --source / --kind / --format；默认检索范围 = 会话源 + 结构化记忆源开，自由笔记 / 二进制日志关（可显式开）。
+- 测试：139 项全绿（75 项 v0.1.0 回归 + 64 项 v0.2.0 通用化用例）；py_compile / validate-skill / 元安 / 元审全过。
+- 文档：新增 references/agent-formats.md 普查登记表；format.md / cli.md / security.md / SKILL.md / README.md 同步；版本 0.1.0→0.2.0 四件对齐（package.json / SKILL frontmatter / 引擎 VERSION / 文档）。
+
 ## v0.1.0 (2026-08-27)
 
 YottaMeta 自有实现首版（历史会话日志检索方向参考开源社区 session-logs 类技能思路，已完全重写，无上游代码）：

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">yotta-logs · 元史</h1>
 
-<p align="center">YottaMeta 自有的历史会话日志检索技能：<b>零依赖检索 / 分析会话 JSONL 记录</b>，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。适用于查以前说过的结论、定位某段决策、回顾某次讨论。</p>
+<p align="center">YottaMeta 自有的历史会话 / 记忆日志检索技能：<b>零依赖检索 / 分析 JSONL、JSON、SQLite、Markdown 多格式记录</b>，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。适用于查以前说过的结论、定位某段决策、回顾某次讨论。</p>
 <p align="center">用户引用先前聊过的内容 / 父会话 / 历史上下文时自动激活——<b>不依赖 jq / rg，纯标准库确定性检索</b>。</p>
 <p align="center">纯 Python 3.8+ 标准库实现，零外部依赖；Windows + Linux + macOS 通用；只读本地日志，默认脱敏，不联网上传。</p>
 
@@ -19,39 +19,43 @@
 
 ## 这是什么
 
-智能体每天产生大量会话日志（JSONL），跨会话追溯时最缺的不是「记得发生过」，而是「原文在哪、谁说的、什么时候说的」。元史把这些日志做成**确定性检索引擎**：定位会话日志目录 → 按关键词 / 正则 / 日期 / 会话 / 角色检索 → 提取会话原文 → 统计消息、token、成本与工具调用。
+智能体每天产生大量会话与记忆记录（JSONL / 单文件 JSON / SQLite / Markdown…），跨会话追溯时最缺的不是「记得发生过」，而是「原文在哪、谁说的、什么时候说的」。元史把这些记录做成**确定性检索引擎**：全源登记日志与记忆位置 → 按关键词 / 正则 / 日期 / 会话 / 角色 / 来源 / 类型 / 格式检索 → 提取会话原文 → 统计消息、token、成本与工具调用。
 
 它不是某个平台的专属功能，而是一份与智能体无关的工具包：装进任何支持 Agent Skills 的智能体即可按需调用。全程零依赖、只读本地、不联网；输出默认脱敏，避免把日志里的密钥 / token 带到上下文。
 
 ## 核心价值
 
 - **零依赖检索**：Python 3.8+ 标准库，不依赖 jq / rg / ripgrep 等外部工具，Windows + Linux + macOS 开箱即用。
-- **容错解析**：JSONL 字段形态差异（message.content 为列表或字符串、role 在顶层或 message 内、toolResult / toolCall 命名差异）均可容忍；坏行自动跳过并计数，不中断检索。
+- **多格式通用（v0.2.0）**：不再只认 JSONL——按「格式族 × 字段别名归一 + 配置兜底」适配 JSONL / 单文件 JSON / SQLite（opencode、Cursor state.vscdb 等）/ Markdown（记忆 md + 自由笔记）/ 二进制（只读标题），统一 Record 模型，引擎零改动接入怪格式。
+- **全源登记**：`locate` / discover 自动发现本机常见日志与记忆源（Codex / Claude Code / Clawdbot / opencode / Gemini / yotta-memory / Codex 笔记…），按默认检索范围过滤。
+- **容错解析**：坏行 / 坏字段自动跳过并计数，不中断检索；二进制 / 加密文件只回退标题不崩。
 - **默认脱敏**：输出自动打码疑似密钥 / token / 口令（sk-、ghp_、AKIA、JWT、Bearer、URL 口令、key=value 赋值、超长 token），--no-redact 关闭。
-- **多维度过滤**：关键词（不区分大小写）/ 正则 / 日期 / 会话 ID / sessions.json 别名 / 角色（user / assistant / tool / system）。
-- **结构化输出**：--json 输出纯净 JSON，含会话 ID、行号、时间戳、角色，适合程序化核对出处。
-- **只读安全**：只读本地日志，不修改、不删除、不联网上传，与元忆（语义记忆）互补分工。
+- **多维度过滤**：关键词（不区分大小写）/ 正则 / 日期 / 会话 ID / sessions.json 别名 / 角色（user / assistant / tool / system / developer）/ 来源（--source）/ 类型（--kind）/ 格式（--format）。
+- **结构化输出**：--json 输出纯净 JSON，含来源、会话 ID、行号、时间戳、角色，适合程序化核对出处。
+- **只读安全**：只读本地日志与记忆文件，不修改、不删除、不联网上传，与元忆（语义记忆）互补分工。
 
 ## 核心优势
 
 | 优势 | 说明 |
 |---|---|
 | **零依赖** | Python 3.8+ 标准库，无模型、无数据库、无外部服务；Windows + Linux + macOS 通用 |
+| **多格式** | JSONL / JSON / SQLite / Markdown / 二进制五大格式族，字段别名归一 + 配置兜底 |
 | **确定性** | 检索逻辑可复现、可解释；命中即原文片段 + 行号，不靠模型猜测 |
 | **默认脱敏** | 疑似密钥 / token / 口令自动打码，降低日志原文外泄风险 |
-| **容错** | 不同智能体的 JSONL 形态差异可容忍，坏行跳过不中断 |
-| **定位准确** | 命中结果带会话 ID / 行号 / 时间戳 / 角色，可精确回溯出处 |
+| **默认范围** | 会话源 + 结构化记忆源默认开；自由笔记 / 二进制日志默认关，可显式开 |
+| **容错** | 不同智能体的存储形态差异可容忍，坏行跳过不中断，加密文件只回退标题 |
+| **定位准确** | 命中结果带来源 / 会话 ID / 行号 / 时间戳 / 角色，可精确回溯出处 |
 | **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
 
 ## 功能体系
 
 | 命令 | 说明 |
 |---|---|
-| locate | 自动发现本机常见的会话日志目录（Codex / Claude Code / Clawdbot 等） |
-| scan | 列出目录下所有会话：ID / 日期 / 消息数 / 大小 / sessions.json 别名 |
-| search | 跨会话检索：关键词 / 正则 + 日期 / 会话 / 角色过滤，输出时间线命中（--json 结构化） |
+| locate | 全源登记：发现本机所有日志 / 记忆源（来源 / 格式 / 类型 / 默认开关） |
+| scan | 列出所有会话（跨源）：来源 / 会话 ID / 日期 / 消息数 / 大小 / 别名 |
+| search | 跨源检索：关键词 / 正则 + 日期 / 会话 / 角色 / 来源 / 类型 / 格式过滤，输出时间线命中（--json 结构化） |
 | session | 提取单个会话原文：时间线 + 角色 + 文本，--role 过滤，--tools 标注工具调用 |
-| stats | 会话统计：消息 / 角色分布 / token / 成本 / 时间范围 / 每日汇总（--daily） |
+| stats | 会话统计：消息 / 角色分布 / token / 成本 / 时间范围 / 分源（--daily 每日汇总） |
 | tools | 工具调用次数排行 |
 | version | 打印版本 |
 
@@ -60,18 +64,26 @@
 Windows 用 python，Linux/macOS 用 python3。
 
 ```bash
-# 自动发现本机常见会话日志目录
+# 全源登记：发现本机所有日志 / 记忆源
 python3 scripts/yotta_logs.py locate
 
-# 列出目录下所有会话
-python3 scripts/yotta_logs.py scan --dir ~/.clawdbot/agents/<agentId>/sessions
+# 跨源检索关键词（默认范围 = 会话 + 结构化记忆；自由笔记默认关）
+python3 scripts/yotta_logs.py search "部署方案"
 
-# 跨会话检索关键词（时间线命中，默认脱敏）
-python3 scripts/yotta_logs.py search "部署方案" --dir /path/to/sessions
+# 指定目录 / 文件（目录自动嗅探格式族）
+python3 scripts/yotta_logs.py scan --dir ~/.clawdbot/agents/<agentId>/sessions
 
 # 正则 + 日期 + 会话过滤
 python3 scripts/yotta_logs.py search "CI 失败" --regex --date 2026-08-26 --dir /path/to/sessions
 
+# 按来源 / 类型 / 格式过滤（来源名见 locate）
+python3 scripts/yotta_logs.py search "记住" --kind memory
+python3 scripts/yotta_logs.py search "XSS" --source opencode-db
+python3 scripts/yotta_logs.py search "部署" --format sqlite
+
+# 自由笔记显式开（默认关）
+python3 scripts/yotta_logs.py search "推送闸门" --kind note
+
 # 提取单个会话原文
 python3 scripts/yotta_logs.py session abc123 --dir /path/to/sessions
 
@@ -87,7 +99,7 @@ python3 scripts/yotta_logs.py search "部署方案" --dir /path/to/sessions --js
 
 退出码语义（与元安 / 元审 / 元盾 / 元真家族一致）：0 = 成功；1 = 无匹配 / 空结果集；4 = 用法错误 / 致命异常。
 
-未指定 --dir 时，依次尝试环境变量 YOTTA_LOGS_DIR → 自动定位首个已知日志目录；找不到则退出码 4 并提示。
+未指定 --dir 时，依次尝试环境变量 YOTTA_LOGS_DIR → discover 全源登记（locate 逻辑）并按默认检索范围过滤；找不到则退出码 4 并提示。
 
 ## 安装
 
@@ -142,21 +154,26 @@ bash install.sh --dir /path/to/skills
 2. 用户问「上次说的部署方案是什么」时，先定位并检索：
    ```bash
    python3 scripts/yotta_logs.py locate
-   python3 scripts/yotta_logs.py search "部署方案" --dir <日志目录>
+   python3 scripts/yotta_logs.py search "部署方案"
    ```
-   得到命中时间线（会话 / 时间 / 角色 / 原文片段）。
+   得到命中时间线（来源 / 会话 / 时间 / 角色 / 原文片段）。
 3. 需要完整上下文时提取对应会话：
    ```bash
    python3 scripts/yotta_logs.py session <会话ID> --dir <日志目录>
    ```
-4. 需要精确出处时用 --json 拿会话 ID / 行号 / 时间戳，回答时给出依据。
+4. 需要精确出处时用 --json 拿来源 / 会话 ID / 行号 / 时间戳，回答时给出依据。
 5. 需要回顾某次会话成本或工具使用分布时用 stats / tools。
 
 ## 开发与校验
 
-- 测试：python scripts/test_yotta_logs.py（75 项）
+- 测试：python scripts/test_yotta_logs.py（139 项，含 75 项 v0.1.0 回归 + 64 项 v0.2.0 通用化用例）
 - 基础校验：python tools/validate-skill.py yotta-logs（在仓库根目录运行）
-- CLI 协议：references/cli.md；日志格式：references/format.md；安全边界：references/security.md
+- 格式普查：references/agent-formats.md；统一格式：references/format.md；CLI 协议：references/cli.md；安全边界：references/security.md
+
+## 更新日志
+
+- v0.2.0（2026-08-27）：多格式通用化——JSONL / 单文件 JSON / SQLite（opencode 等）/ Markdown（记忆 + 自由笔记）/ 二进制五大格式族，统一 Record + 字段别名归一 + 配置兜底，discover 全源登记，新增 --source / --kind / --format 过滤与默认检索范围（会话 + 结构化记忆开、自由笔记 / 二进制日志关）。详见 CHANGELOG.md。
+- v0.1.0（2026-08-27）：首版——零依赖 JSONL 会话日志检索引擎（locate / scan / search / session / stats / tools / version + 默认脱敏 + sessions.json 别名 + 只读）。
 
 ## 许可证
 

package/SKILL.md

@@ -1,80 +1,90 @@
 ---
 name: yotta-logs
-version: 0.1.0
-description: 元史 —— 跨智能体的历史会话日志检索技能：零依赖检索 / 分析会话 JSONL 记录，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。触发：用户问起先前聊过的内容 / 父会话 / 历史上下文、要查以前说过的结论、跨会话回溯某次讨论、需要从会话日志定位某段决策时。边界：仅读取本机自己的会话日志文件；不修改、不删除会话记录；只查本地日志不联网上传；与元忆（语义记忆）互补，本技能只做原始日志检索。
+version: 0.2.0
+description: 元史 —— 跨智能体的历史会话 / 记忆日志检索技能：零依赖检索 / 分析 JSONL、JSON、SQLite、Markdown 多格式会话与记忆文件，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。触发：用户问起先前聊过的内容 / 父会话 / 历史上下文、要查以前说过的结论、跨会话回溯某次讨论、需要从会话日志或记忆文件定位某段决策时。边界：仅读取本机自己的会话日志 / 记忆文件；不修改、不删除；只查本地不联网上传。
 license: MIT
 ---
 
 # 元史（yotta-logs）
 
-跨智能体的历史会话日志检索技能：**零依赖检索 / 分析会话 JSONL 记录**，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。
+跨智能体的历史会话 / 记忆日志检索技能：**零依赖检索 / 分析多格式日志记录**（JSONL / 单文件 JSON / SQLite / Markdown / 二进制），回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。
 
-零依赖（Python 3.8+ 标准库），Windows + Linux + macOS 通用；Claude Code / Cursor / Codex / 通用 Agent 均可调用。
+零依赖（Python 3.8+ 标准库），Windows + Linux + macOS 通用；Claude Code / Cursor / Codex / opencode / 通用 Agent 均可调用。
 
 ## 何时使用
 
 - 用户引用先前聊过的内容 / 父会话 / 历史上下文；
-- 要查以前说过的结论、决策、命令或结果；
+- 要查以前说过的结论、决策、命令或结果（无论存在 JSONL 会话、SQLite（如 opencode）还是记忆 md）；
 - 需要从会话日志定位某段讨论发生在哪个会话、什么时间、谁说的。
 
 **Do NOT trigger**：
 
-- 只读：不修改、不删除任何会话记录；
+- 只读：不修改、不删除任何会话 / 记忆记录；
 - 只查本地日志，不联网上传；
-- 语义记忆 / 长期知识请用元忆（yotta-memory）；本技能只管原始会话日志检索，二者互补。
+- 语义记忆 / 长期知识请用元忆（yotta-memory）；本技能只管原始日志 / 记忆文件检索，二者互补。
 
 ## 快速使用
 
 Windows 用 python，Linux/macOS 用 python3。
 
 ```bash
-# 自动发现本机常见会话日志目录
+# 全源登记：发现本机所有日志 / 记忆源（来源 / 格式 / 类型 / 默认开关）
 python3 scripts/yotta_logs.py locate
 
-# 列出目录下所有会话（ID / 日期 / 消息数 / 大小）
+# 跨源检索关键词（默认范围 = 会话源 + 结构化记忆源；自由笔记默认关）
+python3 scripts/yotta_logs.py search "部署方案"
+
+# 指定目录 / 文件（目录自动嗅探格式族）
 python3 scripts/yotta_logs.py scan --dir ~/.clawdbot/agents/<agentId>/sessions
+python3 scripts/yotta_logs.py search "CI 失败" --regex --date 2026-08-26 --dir /path/to/logs
 
-# 跨会话检索关键词（时间线命中，默认脱敏）
-python3 scripts/yotta_logs.py search "部署方案" --dir /path/to/sessions
+# 按来源 / 类型 / 格式过滤
+python3 scripts/yotta_logs.py search "记住" --kind memory
+python3 scripts/yotta_logs.py search "XSS" --source opencode-db
+python3 scripts/yotta_logs.py search "部署" --format sqlite
 
-# 正则 + 日期 + 会话过滤
-python3 scripts/yotta_logs.py search "CI 失败" --regex --date 2026-08-26 --dir /path/to/sessions
+# 自由笔记显式开（默认关）
+python3 scripts/yotta_logs.py search "推送闸门" --kind note
 
 # 提取单个会话原文
 python3 scripts/yotta_logs.py session abc123 --dir /path/to/sessions
 
-# 统计（消息 / token / 成本 / 每日汇总）
+# 统计（消息 / token / 成本 / 每日汇总 / 分源）
 python3 scripts/yotta_logs.py stats --dir /path/to/sessions --daily
 
 # 工具调用排行
-python3 scripts/yotta_logs.py tools --dir /path/to/sessions
+python3 scripts/yotta_logs.py tools --dir /path/to/logs --format sqlite
 ```
 
 退出码（与元安 / 元审 / 元盾 / 元真家族一致）：0 = 成功；1 = 无匹配 / 空结果集；4 = 用法错误 / 致命异常。
 
 ## 工作流程（AI 智能体回溯历史时）
 
-1. **定位**：locate 或 scan 找到会话日志目录与会话 ID；
-2. **检索**：search 按关键词 / 正则跨会话命中，先看时间线片段；
+1. **定位**：locate 全源登记或 scan 列出会话（跨源，含来源 / 格式）；
+2. **检索**：search 按关键词 / 正则跨源命中，先看时间线片段；
 3. **提取**：命中后 session <sid> 提取该会话原文；
-4. **核对**：需要精确出处时用 --json 拿结构化结果（会话 ID / 行号 / 时间戳 / 角色）；
+4. **核对**：需要精确出处时用 --json 拿结构化结果（来源 / 会话 ID / 行号 / 时间戳 / 角色）；
 5. **统计**：需要成本 / token / 工具使用回顾时用 stats / tools。
 
 ## 能力
 
 - **零依赖检索**：Python 3.8+ 标准库，不依赖 jq / rg 等外部工具；
-- **容错解析**：字段缺失 / 坏行自动跳过并计数，可容忍不同智能体的 JSONL 形态差异；
+- **多格式通用**：JSONL / 单文件 JSON / SQLite（opencode 等）/ Markdown（记忆 md + 自由笔记）/ 二进制（只读标题），统一 Record 模型 + 字段别名归一 + 配置兜底；
+- **全源登记**：locate / discover 自动发现本机常见日志与记忆源（Codex / Claude Code / Clawdbot / opencode / Gemini / yotta-memory / Codex 笔记…）；
+- **默认检索范围**：会话源 + 结构化记忆源默认开，自由笔记默认关可显式开（--kind note / --kind log / 配置 default_scope）；
+- **容错解析**：坏行 / 坏字段自动跳过并计数；二进制 / 加密文件只回退标题不崩；
 - **默认脱敏**：输出自动打码疑似密钥 / token / 口令（--no-redact 关闭）；
-- **多维度过滤**：关键词 / 正则 / 日期 / 会话 ID / 别名 / 角色；
-- **结构化输出**：--json 输出纯净 JSON（含行号 / 时间戳 / 角色）；
-- **只读安全**：只读本地日志，不修改、不删除、不联网。
+- **多维度过滤**：关键词 / 正则 / 日期 / 会话 ID / 别名 / 角色 / 来源 / 类型 / 格式；
+- **结构化输出**：--json 输出纯净 JSON（含来源 / 行号 / 时间戳 / 角色）；
+- **只读安全**：只读本地日志与记忆文件，不修改、不删除、不联网。
 
 ## 参考文档
 
-- references/format.md — 会话日志 JSONL 格式与 sessions.json 索引说明
-- references/cli.md — CLI 子命令 / 参数 / 退出码 / JSON schema 详解
+- references/agent-formats.md — 6 大格式族普查登记表 + 字段别名映射 + 已知根 + 配置兜底
+- references/format.md — 统一 Record 模型与各格式族读取规则
+- references/cli.md — CLI 子命令 / 参数 / 退出码 / JSON schema / 配置详解
 - references/security.md — 安全边界 / 脱敏规则 / 与元忆的差异化
 
 ## 责任声明
 
-本技能只做本地会话日志的只读检索；输出原文片段可能包含隐私，默认脱敏且仅用于本机回溯，请勿将检索结果外传。
+本技能只做本地会话日志 / 记忆文件的只读检索；输出原文片段可能包含隐私，默认脱敏且仅用于本机回溯，请勿将检索结果外传。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yottameta/yotta-logs",
-  "version": "0.1.0",
-  "description": "元史 —— 跨智能体的历史会话日志检索技能：零依赖检索 / 分析会话 JSONL 记录，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。触发：用户问起先前聊过的内容 / 父会话 / 历史上下文、要查以前说过的结论、跨会话回溯某次讨论、需要从会话日志定位某段决策时。边界：仅读取本机自己的会话日志文件；不修改、不删除会话记录；只查本地日志不联网上传。",
+  "version": "0.2.0",
+  "description": "元史 —— 跨智能体的历史会话 / 记忆日志检索技能：零依赖检索 / 分析 JSONL、JSON、SQLite、Markdown 多格式会话与记忆文件（统一 Record + 字段别名归一 + 配置兜底），discover 全源登记，回溯旧对话与父会话上下文。触发：用户问起先前聊过的内容 / 父会话 / 历史上下文、要查以前说过的结论、跨会话回溯某次讨论、需要从会话日志或记忆文件定位某段决策时。边界：仅读取本机自己的会话日志 / 记忆文件；不修改、不删除会话记录；只查本地日志不联网上传。",
   "license": "MIT",
   "keywords": [
     "agent-skills",

package/references/agent-formats.md

@@ -0,0 +1,127 @@
+# AI 智能体会话 / 记忆存储格式普查登记表（agent-formats）
+
+> v0.2.0 通用化依据：元史（yotta-logs）不再只认 JSONL，按「格式族 × 字段别名归一 + 配置兜底」适配一切格式。
+> 本表是普查结论：6 大格式族、统一记录模型、字段别名映射、已知根与配置兜底。引擎行为见 `cli.md` / `format.md`。
+
+## 一、总览：6 大格式族
+
+| # | 格式族 | format | 代表智能体 / 存储 | 特征 |
+|---|---|---|---|---|
+| 1 | JSONL | jsonl | Claude Code / Codex CLI / Gemini 新版 / Copilot / Qwen / 多数会话 | 每行一个 JSON 对象，追加写入 |
+| 2 | 单文件 JSON | json | Cline / Roo / Continue / Gemini 旧版 | 一个文件存整个会话 / 会话集（数组或对象） |
+| 3 | SQLite | sqlite | opencode / Cursor state.vscdb / Trae / Copilot CLI session-store / CodeBuddy | 关系表存会话 / 消息 / 片段，字段多为 JSON 字符串 |
+| 4 | Markdown | markdown | Aider .aider.chat.history.md / 各类自由笔记 | # 标题 + 正文 |
+| 5 | 结构化 Markdown（YAML frontmatter） | markdown | yotta-memory / agent-code / opencode-agent-memory | --- frontmatter 元数据 + 正文 |
+| 6 | 二进制 / 专有 / 加密 | binary | Windsurf pbtxt / Cascade / JetBrains Nitrite | 只降级读标题，不崩 |
+
+## 二、统一记录模型 Record
+
+所有 reader 产同构记录：`{source, format, kind, session, time, role, text, path, meta}`。
+
+| 字段 | 说明 | 字段别名（按序取首个命中） |
+|---|---|---|
+| source | 来源名（如 codex-sessions / opencode-db / yottamemory-facts / codex-notes） | 来源登记名 |
+| format | jsonl / json / sqlite / markdown / binary | 文件嗅探 / 配置 |
+| kind | session / memory / note / log | 来源登记或逐记录判定 |
+| session | 会话 ID / 文件名主干 / 相对路径 | session_id / thread_id / sessionId / session / conversation_id / threadId；缺省取文件主干 |
+| time | 归一化 ISO 时间戳（秒 / 毫秒自动推断） | timestamp / time_created / created / time / ts / date / created_at / mtime / updated |
+| role | user / assistant / tool / system / developer；结构化 md 的 type=FACT/PREF/BOUND/COMMIT → role | role / type / kind（message 内或 payload 内均可） |
+| text | 人类可读文本 | text / content / body / message / statement；content 列表取 type=text / input_text / output_text |
+| path | 绝对路径 | 文件路径 |
+| meta | 额外字段（title / tags / tools / cost / tokens…） | title←title / subject / name / # 一级标题 |
+
+## 三、各格式族详情
+
+### 3.1 JSONL（jsonl）
+
+- 代表：Claude Code（~/.claude/projects/*）、Codex CLI（~/.codex/sessions，CODEX_HOME 可覆盖；嵌套子目录）、Clawdbot（~/.clawdbot/agents/*/sessions）、opencode sessions 目录、Gemini 新版、Copilot、Qwen。
+- 每行一个 JSON 对象：`type=session/message`；`message.role`；`message.content` 字符串或列表（type=text/toolCall/toolResult）；`message.usage`。
+- Codex rollout 形态（本机实测 2026-08-27）：`{timestamp, type, payload:{type, role, content, usage}}`——`payload.type=message` 取 role / content；`payload.type=function_call / function_call_output / local_shell_call` 归一为 tool 并提取工具名；reasoning / event_msg 不进文本。
+- 可选 `sessions.json` 索引（别名 → 会话 ID）。
+- 容错：坏行跳过并计数，不中断。
+
+### 3.2 单文件 JSON（json）
+
+- 代表：Cline / Roo / Continue（~/.continue/sessions/*.json）、Gemini 旧版。
+- 形态：JSON 数组（每条一个消息）；对象 {会话ID: [消息...]}；对象 {会话ID: 单消息}。
+- 归一：数组逐条；对象遍历值。
+
+### 3.3 SQLite（sqlite）
+
+- 代表：opencode（~/.local/share/opencode/opencode.db；本机实测 D:\AI_WorkDir\.OpenCodeData\data\opencode\opencode.db，走 XDG_DATA_HOME / OPENCODE_DATA）、Cursor state.vscdb、Trae、Copilot CLI session-store、CodeBuddy。
+- opencode 实测 schema（2026-08-27，D:\AI_WorkDir\.OpenCodeData\data\opencode\opencode.db）：
+  - `session(id, project_id, title, cost, tokens_input, tokens_output, time_created[毫秒], ...)`
+  - `message(id, session_id, time_created[毫秒], data[JSON: role, time, agent, model, ...])`
+  - `part(id, message_id, session_id, time_created[毫秒], data[JSON: type=text/tool/reasoning/step-start...])`——text 部分取 `text` 字段；tool 部分取 `tool` 字段为工具名。
+- 只读连接：`sqlite3.connect("file:<path>?mode=ro", uri=True)`，绝不写库。
+- 通用兜底：配置指定 `table / col_time / col_role / col_text / col_session / col_title`；未指定则按字段别名嗅探「消息类」表。
+
+### 3.4 Markdown（markdown）
+
+- 代表：Aider（repo 下 *.aider.chat.history.md）、各类自由笔记（Codex memories）。
+- 无 frontmatter：`# 一级标题` → title，正文 → text，文件 mtime → time，kind=note。
+
+### 3.5 结构化 Markdown（markdown + YAML frontmatter）
+
+- 代表：yotta-memory（记忆库 facts / private / archive 下的 *.md）、agent-code、opencode-agent-memory。
+- frontmatter：`type`（FACT/PREF/BOUND/COMMIT → role）、`subject` → title、`statement` → text、`created / updated / date` → time、`tags / confidence / scope / owner / immutable` → meta。
+- 本机实测样本（2026-08-27）：D:\AI_WorkDir\.yottamemory\facts\2026-08-25-0002.md（记忆库位置由 ~/.yottamemory/config.json 的 `memory_home` 决定）。
+- frontmatter 解析为零依赖 YAML 子集（key: value / key: [a, b] / 引号），非完整 YAML。
+
+### 3.6 二进制 / 专有 / 加密（binary）
+
+- 代表：Windsurf pbtxt（~/.codeium/windsurf/**/*.pbtxt）、Cascade、JetBrains Nitrite。
+- 只降级读 title（文件名 / 首个可读片段），不崩；kind=log，默认关。
+
+## 四、已知根（discover 全源登记）
+
+| 来源名 | 根路径 | format | kind | 默认范围 |
+|---|---|---|---|---|
+| codex-sessions | ~/.codex/sessions（CODEX_HOME 覆盖，支持嵌套子目录） | jsonl | session | 开 |
+| claude-projects | ~/.claude/projects/* | jsonl | session | 开 |
+| clawdbot-sessions | ~/.clawdbot/agents/*/sessions | jsonl | session | 开 |
+| opencode-sessions | ~/.config/opencode/sessions | jsonl | session | 开 |
+| gemini-sessions | ~/.gemini/sessions | jsonl | session | 开 |
+| agents-sessions | ~/.agents/sessions | jsonl | session | 开 |
+| opencode-db | ~/.local/share/opencode/opencode.db；$XDG_DATA_HOME/opencode/opencode.db；$OPENCODE_DATA；~/.OpenCodeData/data/opencode/opencode.db | sqlite | session | 开 |
+| cursor-state / code-state | VS Code / Cursor globalStorage 下 state.vscdb（Windows / Linux / macOS） | sqlite | session | 开 |
+| continue-sessions | ~/.continue/sessions、~/.config/continue/sessions | json | session | 开 |
+| yottamemory-facts | 记忆库 facts（memory_home 配置） | markdown | memory | 开 |
+| yottamemory-private | 记忆库 private（memory_home 配置） | markdown | memory | 开 |
+| yottamemory-archive | 记忆库 archive（memory_home 配置） | markdown | memory | 开 |
+| codex-notes | $CODEX_HOME/memories、~/.CodexData/memories | markdown | note | 关（显式开） |
+| aider-history | 当前目录 *.aider.*.md | markdown | session | 开 |
+| windsurf-conv | ~/.codeium/windsurf、~/.windsurf 下 *.pbtxt | binary | log | 关 |
+| 自定义 sources | 配置 sources[]（见下） | 任意 | 任意 | 配置 default_scope |
+
+## 五、配置兜底（config.json）
+
+路径：`$YOTTA_LOGS_CONFIG` 或 `~/.config/yotta-logs/config.json`。
+
+```json
+{
+  "default_scope": ["session", "memory"],
+  "sources": [
+    {
+      "name": "myapp",
+      "path": "/path/to/logs",
+      "format": "sqlite",
+      "kind": "session",
+      "table": "messages",
+      "col_time": "created_at",
+      "col_role": "role",
+      "col_text": "content",
+      "col_session": "session_id",
+      "col_title": "title"
+    }
+  ]
+}
+```
+
+引擎零改动即可接入怪格式（个别 agent 私有 schema 用列映射接入）。
+
+## 六、默认检索范围（2026-08-27 老张拍板）
+
+- 会话源（kind=session）+ 结构化记忆源（kind=memory）**默认开**；
+- 自由笔记（kind=note）与二进制日志（kind=log）**默认关**，可 `--kind note` / `--kind log` 显式开；
+- 显式指定 `--dir / --source / --format / --kind` 时以显式条件为准。

package/references/cli.md

@@ -6,45 +6,50 @@
 
 | 选项 | 说明 |
 |---|---|
-| --dir PATH | 会话日志目录；缺省读环境变量 YOTTA_LOGS_DIR，再自动定位首个已知目录 |
+| --dir PATH | 日志 / 记忆目录或文件；目录自动嗅探格式族（jsonl / json / sqlite / markdown），也支持单文件（含 .db / .md / .jsonl） |
+| --source NAME | 只检索指定来源（可多次；名称见 locate 登记，如 codex-sessions / opencode-db / yottamemory-facts / codex-notes） |
+| --kind KIND | 只检索指定类型：session / memory / note / log |
+| --format FMT | 只检索指定格式：jsonl / json / sqlite / markdown / binary |
 | --json | 输出纯净 JSON（stdout 无其它噪音） |
 | --no-redact | 关闭默认脱敏 |
 | --limit N | 最多返回 N 条（默认 50） |
 | --version | 打印版本 |
 
+未指定 --dir 时：依次尝试 YOTTA_LOGS_DIR → discover 全源登记（locate 逻辑），并按默认检索范围（会话 + 结构化记忆开、自由笔记 / 二进制日志关）过滤；显式 --source / --kind / --format 可覆盖默认范围。
+
 ## 子命令
 
 ### locate
-自动发现本机常见会话日志目录（`~/.clawdbot/agents/*/sessions`、`~/.codex/sessions`、`~/.claude/projects/*`、`~/.config/opencode/sessions`、`~/.gemini/sessions`、`~/.agents/sessions`），只返回存在且含 `*.jsonl` 的目录。
+全源登记：遍历所有 reader 的 discover()，登记本机存在的日志 / 记忆源（来源 / 格式 / 类型 / 路径 / 默认开关）。`--json` 输出 `{tool, version, default_scope, sources[]}`。无源退出码 1。
 
 ### scan
-列出目录下所有会话：ID / 日期（首条消息）/ 消息数 / 大小 / sessions.json 别名。支持 `--limit`、`--json`。空目录退出码 1。
+列出所有会话（跨源）：来源 / 会话 ID / 日期（首条消息）/ 消息数 / 大小 / 别名。支持 `--source/--kind/--format`、`--limit`（全局截断）、`--json`。空结果退出码 1。
 
 ### search <query>
-跨会话检索，输出时间线命中（会话 / 时间 / 角色 / 原文片段）。
+跨源检索，输出时间线命中（来源 / 会话 / 时间 / 角色 / 原文片段）。
 
 | 选项 | 说明 |
 |---|---|
 | --regex | 把 query 当正则（默认不区分大小写） |
 | --date YYYY-MM-DD | 只检索指定日期（也支持 YYYY-MM） |
 | -s / --session SID | 只检索指定会话 ID / 别名（可多次） |
-| --role ROLE | user / assistant / tool / system |
+| --role ROLE | user / assistant / tool / system / developer |
 | --context N | 命中上下文半径字符数（默认 40） |
 | --limit N | 最多返回 N 条（默认 50） |
 
---json 输出：`{command, tool, version, query, regex, dir, total_matches, sessions_hit, truncated, matches[]}`，每条命中含 `session / timestamp / role / line / match / text`。
+--json 输出：`{command, tool, version, query, regex, sources[], total_matches, sessions_hit, truncated, matches[]}`，每条命中含 `source / format / kind / session / timestamp / role / line / match / text`。
 
 ### session <sid>
-提取单个会话原文（时间线 + 角色 + 文本）。`--role` 过滤、`--tools` 标注工具调用、`--limit`、`--json`。未知会话退出码 4。
+提取单个会话原文（时间线 + 角色 + 文本）。`--role` 过滤、`--tools` 标注工具调用、`--source/--kind/--format`、`--limit`、`--json`。未知会话退出码 4。跨源同名会话取第一个，可用 `--source` 消歧。
 
 ### stats
-会话统计：消息 / 角色分布 / token / 成本 / 时间范围；`--daily` 输出每日汇总；`-s/--session` 限定单会话。空目录退出码 1。
+会话统计（跨源）：会话 / 消息 / 角色分布 / token / 成本 / 时间范围 / 分源（by_source）；`--daily` 输出每日汇总；`-s/--session` 限定单会话。空结果退出码 1。
 
 ### tools
-工具调用次数排行（`toolCall` / `toolResult` 的工具名计数），`-s/--session` 限定单会话。
+工具调用次数排行（toolCall / toolResult / payload function_call 的工具名计数），`-s/--session` 限定单会话。
 
 ### version
-打印 `yotta-logs 0.1.0`。
+打印 `yotta-logs 0.2.0`。
 
 ## 退出码
 
@@ -52,9 +57,16 @@
 |---|---|
 | 0 | 成功（检索到结果 / 操作完成） |
 | 1 | 无匹配 / 空结果集 |
-| 4 | 用法错误 / 目录不存在 / 未知会话 / 致命异常 |
+| 4 | 用法错误 / 路径不存在 / 未知会话 / 致命异常 |
 
 ## JSON 输出约定
 
 - stdout 只输出 JSON，进度 / 提示走 stderr；
 - `ensure_ascii=False`，中文原样输出；stdout 已重配 UTF-8（GBK 控制台不炸）。
+
+## 配置（配置兜底）
+
+- 配置文件：`$YOTTA_LOGS_CONFIG` 或 `~/.config/yotta-logs/config.json`；
+- `default_scope`：默认检索范围（默认 `["session", "memory"]`）；
+- `sources[]`：自定义源（path / format / kind / name / table / col_time / col_role / col_text / col_session / col_title），引擎零改动接入怪格式。
+- 示例见 `agent-formats.md` 第五节。

package/references/format.md

@@ -1,40 +1,75 @@
-# 会话日志格式（format）
+# 日志 / 记忆格式（format）
 
-元史按「目录 = 会话集」工作：一个目录下有若干 `*.jsonl` 会话文件，可选一个 `sessions.json` 索引。目录由 `--dir` 指定（缺省读环境变量 `YOTTA_LOGS_DIR`，再自动定位首个已知目录）。
+元史 v0.2.0 起按「格式族 × 字段别名归一 + 配置兜底」适配一切格式，统一产出 Record。
+格式普查与各智能体存储位置见 `agent-formats.md`。
 
-## 会话文件（*.jsonl）
+## 统一记录模型 Record
 
-每行一个 JSON 对象，追加写入。常见字段：
+所有 reader 产同构记录：
 
 | 字段 | 说明 |
 |---|---|
-| type | `session`（会话元数据）或 `message`（消息） |
-| timestamp | ISO 时间戳（如 `2026-08-26T03:00:01+08:00`） |
-| message.role | `user` / `assistant` / `toolResult`（归一为 `tool`） |
-| message.content | 文本或列表；列表项 `type=text` 取文本，`type=toolCall` / `toolResult` 取工具名 |
-| message.usage.cost.total | 单条成本 |
-| message.usage.input_tokens / output_tokens | token 数 |
+| source | 来源名（codex-sessions / opencode-db / yottamemory-facts / codex-notes …） |
+| format | jsonl / json / sqlite / markdown / binary |
+| kind | session / memory / note / log |
+| session | 会话 ID / 文件名主干 |
+| time | 归一化 ISO 时间戳（秒 / 毫秒自动推断，Z 转 +00:00） |
+| role | user / assistant / tool / system / developer；结构化 md 为 FACT/PREF/BOUND/COMMIT |
+| text | 人类可读文本 |
+| path | 绝对路径 |
+| meta | 额外字段（title / tags / tools / cost / tokens_in / tokens_out / line …） |
 
-会话 ID = 文件名主干（去掉 `.jsonl`）。文件只被读取，绝不写入 / 修改 / 删除。
+## 字段别名归一（适配一切关键字段）
 
-## 索引文件（sessions.json）
+| 语义 | 别名（按序取首个命中） |
+|---|---|
+| time | timestamp / time_created / created / time / ts / date / created_at / mtime / updated |
+| role | role / type / kind（message 内或 payload 内均可） |
+| text | text / content / body / message / statement / text_content |
+| session | session_id / thread_id / sessionId / session / conversation_id / threadId |
+| title | title / subject / name / heading；md 无 frontmatter 时取 # 一级标题 |
+
+- content 为列表时取 `type=text / input_text / output_text` 项；
+- JSON 字符串字段自动解包一层；
+- 秒 / 毫秒时间戳自动推断（13 位及以上按毫秒）。
+
+## 各格式族读取规则
+
+### JSONL（jsonl）
+
+- 目录 = 会话集（支持嵌套子目录，如 Codex `sessions/2026/08/27/xxx.jsonl`）；可选 `sessions.json` 索引（别名 → 会话 ID）。
+- 每行一个 JSON 对象；`message` / `payload` 内取 role / content / usage。
+- Codex rollout 形态：`payload.type=message` 取 role / content；`function_call / function_call_output / local_shell_call` 归一为 tool 并提取工具名；reasoning / event_msg 不进文本。
+- 坏行跳过并计入 invalid。
+
+### 单文件 JSON（json）
+
+- 数组 = 一条条消息；对象 = {会话ID: [消息...]} 或 {会话ID: 单消息}。
+
+### SQLite（sqlite）
+
+- 只读连接 `file:<path>?mode=ro`（uri=True），绝不写库。
+- opencode schema 实测：session(id, title, cost, tokens_input, tokens_output, time_created[毫秒]) + message(id, session_id, data[JSON role]) + part(message_id, data[JSON type=text/tool/reasoning])。text 部分取 text 字段；tool 部分取 tool 字段为工具名；reasoning 不进文本。
+- 通用兜底：配置指定 table / col_time / col_role / col_text / col_session / col_title；未指定则按字段别名嗅探消息类表。
+
+### Markdown（markdown）
+
+- 有 YAML frontmatter（`---` 开头）：type→role、subject→title、statement→text、created/updated/date→time、tags/confidence/scope/owner/immutable→meta；kind=memory。
+- 无 frontmatter：# 一级标题→title，正文→text，mtime→time；kind=note。
+- frontmatter 解析为零依赖 YAML 子集（key: value / key: [a, b] / 引号包裹）。
 
-可选，把别名映射到会话 ID。两种形态均可：
+### 二进制 / 专有 / 加密（binary）
 
-```json
-{ "微信-部署": "a1", "ci-排查": "b2" }
-```
+- 只降级读 title（文件名 / 首个可读片段），不崩；kind=log。
 
-```json
-[ { "key": "微信-部署", "sessionId": "a1" } ]
-```
+## 会话 ID 规则
 
-search / session / stats / tools 的 `--session` / `-s` 参数同时接受会话 ID 与别名。
+- JSONL / Markdown / Binary：文件名主干（去掉扩展名）；
+- 单文件 JSON 数组：文件主干；对象：键名（会话 ID）；
+- SQLite：session 表 id（opencode）或 col_session 列值；无会话列时取文件主干。
 
 ## 容错规则
 
-- content 为字符串时直接作为文本；为列表时只取 `type=text` 项；
-- role 可在 message 内或顶层；`toolResult` / `tool_result` 统一归一为 `tool`；
-- usage 可在 message 内或顶层；
-- 坏行（非法 JSON / 非对象）跳过并计入 `invalid`，不中断检索；
-- 非 `.jsonl` 文件（如 `sessions.json`、`notes.txt`）不会被当作会话。
+- 坏行 / 坏 JSON 字段跳过并计数（invalid），不中断检索；
+- 二进制 / 加密文件只回退标题，不抛错；
+- 所有读取均为只读，绝不修改 / 删除 / 写入。