@yottameta/yotta-logs 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 更新日志
 
+## v0.2.1 (2026-08-27)
+
+文档中英双版（老张拍板「英文门面 + 中文全档」）：
+
+- **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 开发校验全流程）。
+- **新增 README.zh-CN.md**：原中文完整主文档整体平移，继续服务中文用户，顶部加语言切换链接。
+- **package.json**：description 改英文；files 加 README.zh-CN.md；版本 0.2.0 → 0.2.1。
+- 版本四处对齐：package.json / SKILL frontmatter / 引擎 VERSION / 文档。
+- 边界（B 方案）：references / CHANGELOG / 测试注释不翻译；SKILL 触发描述保持中文。
+
+## 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

@@ -1,12 +1,14 @@
+<p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
+
 <p align="center">
   <img src="assets/banner.png" alt="yotta-logs banner" width="100%" />
 </p>
 
-<h1 align="center">yotta-logs · 元史</h1>
+<h1 align="center">yotta-logs · 元史 (Yuanshi)</h1>
 
-<p align="center">YottaMeta 自有的历史会话日志检索技能：<b>零依赖检索 / 分析会话 JSONL 记录</b>，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。适用于查以前说过的结论、定位某段决策、回顾某次讨论。</p>
-<p align="center">用户引用先前聊过的内容 / 父会话 / 历史上下文时自动激活——<b>不依赖 jq / rg，纯标准库确定性检索</b>。</p>
-<p align="center">纯 Python 3.8+ 标准库实现，零外部依赖；Windows + Linux + macOS 通用；只读本地日志，默认脱敏，不联网上传。</p>
+<p align="center">YottaMeta's skill for retrieving and analyzing <b>historical session / memory logs across AI agents</b>: zero-dependency search over JSONL, JSON, SQLite and Markdown records to recall past conversations and parent-session context with original-log evidence.</p>
+<p align="center">Activates when the user references previous content / a parent session / historical context — <b>no jq / rg needed; pure standard-library deterministic retrieval</b>.</p>
+<p align="center">Pure Python 3.8+ standard library, zero external dependencies; Windows + Linux + macOS; read-only local logs, redacted by default, never uploaded.</p>
 
 <p align="center">
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
@@ -17,104 +19,115 @@
   <a href="https://github.com/YottaMeta/yotta-logs"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
 </p>
 
-## 这是什么
+## What it is
 
-智能体每天产生大量会话日志（JSONL），跨会话追溯时最缺的不是「记得发生过」，而是「原文在哪、谁说的、什么时候说的」。元史把这些日志做成**确定性检索引擎**：定位会话日志目录 → 按关键词 / 正则 / 日期 / 会话 / 角色检索 → 提取会话原文 → 统计消息、token、成本与工具调用。
+Agents generate a steady stream of session and memory records (JSONL / single-file JSON / SQLite / Markdown…). When tracing across sessions, the hard part is rarely "remembering that something happened" — it is finding *where the original text is, who said it, and when*. Yuanshi turns those records into a **deterministic retrieval engine**: discover every log and memory source → search by keyword / regex / date / session / role / source / kind / format → extract raw conversation → summarize messages, tokens, cost and tool usage.
 
-它不是某个平台的专属功能，而是一份与智能体无关的工具包：装进任何支持 Agent Skills 的智能体即可按需调用。全程零依赖、只读本地、不联网；输出默认脱敏，避免把日志里的密钥 / token 带到上下文。
+It is not tied to any single platform: it is an agent-agnostic toolkit that works in any agent supporting Agent Skills. Zero dependencies, read-only local access, no network; output is redacted by default so secrets and tokens in logs never leak into context.
 
-## 核心价值
+## Core value
 
-- **零依赖检索**：Python 3.8+ 标准库，不依赖 jq / rg / ripgrep 等外部工具，Windows + Linux + macOS 开箱即用。
-- **容错解析**：JSONL 字段形态差异（message.content 为列表或字符串、role 在顶层或 message 内、toolResult / toolCall 命名差异）均可容忍；坏行自动跳过并计数，不中断检索。
-- **默认脱敏**：输出自动打码疑似密钥 / token / 口令（sk-、ghp_、AKIA、JWT、Bearer、URL 口令、key=value 赋值、超长 token），--no-redact 关闭。
-- **多维度过滤**：关键词（不区分大小写）/ 正则 / 日期 / 会话 ID / sessions.json 别名 / 角色（user / assistant / tool / system）。
-- **结构化输出**：--json 输出纯净 JSON，含会话 ID、行号、时间戳、角色，适合程序化核对出处。
-- **只读安全**：只读本地日志，不修改、不删除、不联网上传，与元忆（语义记忆）互补分工。
+- **Zero-dependency retrieval** — Python 3.8+ standard library; no jq / rg / ripgrep; works out of the box on Windows + Linux + macOS.
+- **Multi-format (v0.2.0)** — not JSONL-only anymore: JSONL / single-file JSON / SQLite (opencode, Cursor state.vscdb…) / Markdown (memory + free notes) / binary (title-only) via "format family × field-alias normalization + config fallback", on a unified Record model.
+- **Full source discovery** — `locate` / discover finds common local log and memory sources (Codex / Claude Code / Clawdbot / opencode / Gemini / yotta-memory / Codex notes…), filtered by the default search scope.
+- **Fault-tolerant parsing** — bad lines and fields are skipped and counted, never aborting a search; binary / encrypted files degrade to titles.
+- **Redacted by default** — output masks likely secrets / tokens / credentials (sk-, ghp_, AKIA, JWT, Bearer, URL passwords, key=value assignments, over-long tokens); disable with --no-redact.
+- **Multi-dimensional filtering** — keyword (case-insensitive) / regex / date / session ID / sessions.json alias / role (user / assistant / tool / system / developer) / source (--source) / kind (--kind) / format (--format).
+- **Structured output** — --json emits clean JSON with source, session ID, line number, timestamp and role, ideal for programmatic provenance checks.
+- **Read-only & safe** — reads local logs and memory files only; never modifies, deletes or uploads; complements yotta-memory (semantic memory).
 
-## 核心优势
+## Why use it
 
-| 优势 | 说明 |
+| Advantage | Description |
 |---|---|
-| **零依赖** | Python 3.8+ 标准库，无模型、无数据库、无外部服务；Windows + Linux + macOS 通用 |
-| **确定性** | 检索逻辑可复现、可解释；命中即原文片段 + 行号，不靠模型猜测 |
-| **默认脱敏** | 疑似密钥 / token / 口令自动打码，降低日志原文外泄风险 |
-| **容错** | 不同智能体的 JSONL 形态差异可容忍，坏行跳过不中断 |
-| **定位准确** | 命中结果带会话 ID / 行号 / 时间戳 / 角色，可精确回溯出处 |
-| **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
-
-## 功能体系
-
-| 命令 | 说明 |
+| **Zero dependency** | Python 3.8+ standard library; no model, database or external service; Windows + Linux + macOS |
+| **Multi-format** | JSONL / JSON / SQLite / Markdown / binary; field-alias normalization + config fallback |
+| **Deterministic** | Reproducible, explainable logic; hits return original fragments + line numbers, no model guessing |
+| **Redacted by default** | Likely secrets / tokens / credentials masked automatically |
+| **Default scope** | Session + structured memory sources on by default; free notes / binary logs off unless explicitly enabled |
+| **Fault-tolerant** | Tolerates storage differences across agents; bad lines skipped without aborting; encrypted files fall back to titles |
+| **Pinpoint provenance** | Hits carry source / session ID / line / timestamp / role for exact tracing |
+| **Ecosystem distribution** | GitHub + npm + ClawHub synced; install via npx / install.sh / manual copy |
+
+## Commands
+
+| Command | Description |
 |---|---|
-| locate | 自动发现本机常见的会话日志目录（Codex / Claude Code / Clawdbot 等） |
-| scan | 列出目录下所有会话：ID / 日期 / 消息数 / 大小 / sessions.json 别名 |
-| search | 跨会话检索：关键词 / 正则 + 日期 / 会话 / 角色过滤，输出时间线命中（--json 结构化） |
-| session | 提取单个会话原文：时间线 + 角色 + 文本，--role 过滤，--tools 标注工具调用 |
-| stats | 会话统计：消息 / 角色分布 / token / 成本 / 时间范围 / 每日汇总（--daily） |
-| tools | 工具调用次数排行 |
-| version | 打印版本 |
+| locate | Discover all local log / memory sources (source / format / kind / default on-off) |
+| scan | List all sessions across sources (source / session ID / date / message count / size / alias) |
+| search | Cross-source search: keyword / regex + date / session / role / source / kind / format filters; timeline hits (--json structured) |
+| session | Extract one session's raw text (timeline + role + text); --role filter, --tools annotate tool calls |
+| stats | Session statistics: messages / role distribution / token / cost / time range / per-source (--daily daily rollup) |
+| tools | Tool-call frequency ranking |
+| version | Print version |
 
-## 快速使用
+## Quick start
 
-Windows 用 python，Linux/macOS 用 python3。
+On Windows use `python`; on Linux/macOS use `python3`.
 
 ```bash
-# 自动发现本机常见会话日志目录
+# Discover all local log / memory sources
 python3 scripts/yotta_logs.py locate
 
-# 列出目录下所有会话
+# Cross-source keyword search (default scope = session + structured memory; free notes off)
+python3 scripts/yotta_logs.py search "deployment plan"
+
+# Target a directory / file (format family auto-sniffed)
 python3 scripts/yotta_logs.py scan --dir ~/.clawdbot/agents/<agentId>/sessions
 
-# 跨会话检索关键词（时间线命中，默认脱敏）
-python3 scripts/yotta_logs.py search "部署方案" --dir /path/to/sessions
+# Regex + date + session filters
+python3 scripts/yotta_logs.py search "CI failed" --regex --date 2026-08-26 --dir /path/to/sessions
 
-# 正则 + 日期 + 会话过滤
-python3 scripts/yotta_logs.py search "CI 失败" --regex --date 2026-08-26 --dir /path/to/sessions
+# Filter by source / kind / format (source names from locate)
+python3 scripts/yotta_logs.py search "remember" --kind memory
+python3 scripts/yotta_logs.py search "XSS" --source opencode-db
+python3 scripts/yotta_logs.py search "deploy" --format sqlite
 
-# 提取单个会话原文
+# Explicitly enable free notes (off by default)
+python3 scripts/yotta_logs.py search "push gate" --kind note
+
+# Extract a single session's raw text
 python3 scripts/yotta_logs.py session abc123 --dir /path/to/sessions
 
-# 统计（消息 / token / 成本 / 每日汇总）
+# Statistics (messages / tokens / cost / daily rollup)
 python3 scripts/yotta_logs.py stats --dir /path/to/sessions --daily
 
-# 工具调用排行
+# Tool-call ranking
 python3 scripts/yotta_logs.py tools --dir /path/to/sessions
 
-# JSON 结构化输出（适合程序化核对）
-python3 scripts/yotta_logs.py search "部署方案" --dir /path/to/sessions --json
+# JSON structured output (for programmatic checks)
+python3 scripts/yotta_logs.py search "deployment plan" --dir /path/to/sessions --json
 ```
 
-退出码语义（与元安 / 元审 / 元盾 / 元真家族一致）：0 = 成功；1 = 无匹配 / 空结果集；4 = 用法错误 / 致命异常。
+Exit codes (consistent with the YottaMeta family): 0 = success; 1 = no match / empty result; 4 = usage error / fatal exception.
 
-未指定 --dir 时，依次尝试环境变量 YOTTA_LOGS_DIR → 自动定位首个已知日志目录；找不到则退出码 4 并提示。
+When --dir is omitted, the engine tries $YOTTA_LOGS_DIR, then full source discovery (locate logic) filtered by the default scope; if nothing is found it exits 4 with a hint.
 
-## 安装
+## Installation
 
-三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
+Three options — skill files always come from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
 
-### 方式一：npm（推荐，一行安装）
+### Option 1: npm (recommended, one-liner)
 ```bash
-# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
 npx -y @yottameta/yotta-logs -g
-npx -y @yottameta/yotta-logs --dir <你的技能目录>   # 任意智能体：指定目录安装
+npx -y @yottameta/yotta-logs --dir /path/to/skills   # any agent: install to a specific directory
 ```
-> 智能体不在预置列表里？用 --dir 指定它的 skills 目录，或手动复制（方式三）。--list 可查看各智能体对应的默认目录。想手动拿文件也可 npm pack @yottameta/yotta-logs 解包后按方式二/三安装。
+> Agent not in the preset list? Point --dir at its skills directory, or copy manually (Option 3). --list shows each agent's default directory. You can also `npm pack @yottameta/yotta-logs` and unpack the tarball.
 
-### 方式二：install.sh 一键安装
-获取技能文件夹后（npm pack 解包或 git clone），进入技能文件夹：
+### Option 2: install.sh one-liner
+From inside the skill folder (npm pack or git clone):
 ```bash
-bash install.sh -g    # 用户级；bash install.sh --list 查看全部目录
-bash install.sh --agent codex   # 指定智能体（--list 可查看可用项）
-bash install.sh       # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
+bash install.sh -g    # user-level; bash install.sh --list shows all directories
+bash install.sh --agent codex   # specific agent (--list shows available entries)
+bash install.sh       # project-level: auto-detect existing .claude/.cursor/.codex skills dirs
 bash install.sh --dir /path/to/skills
 ```
-> 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
+> Covers 17 agents including Trae / Qwen / Comate / CodeBuddy / Kimi. On Windows, Git Bash is sufficient; otherwise use Option 3.
 
-### 方式三：手动复制
-把整个 yotta-logs 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 %USERPROFILE%，Linux/macOS 用 ~）：
+### Option 3: manual copy
+Copy the whole `yotta-logs` folder into the target agent's skills directory. Common locations (user-level; %USERPROFILE% on Windows, ~ on Linux/macOS):
 
-| 智能体 | 用户级目录 | 项目级目录 |
+| Agent | User-level dir | Project-level dir |
 |---|---|---|
 | Codex | %USERPROFILE%\.codex\skills\yotta-logs\ | .codex\skills\ |
 | Claude Code | %USERPROFILE%\.claude\skills\yotta-logs\ | .claude\skills\ |
@@ -127,37 +140,43 @@ bash install.sh --dir /path/to/skills
 | Kiro | %USERPROFILE%\.kiro\skills\yotta-logs\ | .kiro\skills\ |
 | WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-logs\ | .workbuddy\skills\ |
 | Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-logs\ | .traecli\skills\ |
-| Trae IDE（国内） | %USERPROFILE%\.trae-cn\skills\yotta-logs\ | .trae\skills\ |
+| Trae IDE (CN) | %USERPROFILE%\.trae-cn\skills\yotta-logs\ | .trae\skills\ |
 | Qwen Code | %USERPROFILE%\.qwen\skills\yotta-logs\ | .qwen\skills\ |
 | Comate | %USERPROFILE%\.comate\skills\yotta-logs\ | .comate\skills\ |
 | CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-logs\ | .codebuddy\skills\ |
 | Kimi | %USERPROFILE%\.kimi\skills\yotta-logs\ | .kimi\skills\ |
-| 通用 AGENTS.md | %USERPROFILE%\.agents\skills\yotta-logs\ | .agents\skills\ |
+| Generic AGENTS.md | %USERPROFILE%\.agents\skills\yotta-logs\ | .agents\skills\ |
 
-> Codex 默认目录若设置了环境变量 CODEX_HOME，以该变量为准；opencode 若设置 XDG_CONFIG_HOME 同理。.agents\skills 并非通用目录，仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等会读取，Claude Code 与 Codex 默认不读。不确定时用 --dir 指定，或让该智能体自行安装。
+> If CODEX_HOME is set, Codex's default directory follows it; same for XDG_CONFIG_HOME with opencode. Note that .agents\skills is not universal — only OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot etc. read it; Claude Code and Codex do not by default. When in doubt, use --dir or let the agent install itself.
 
-## 使用示例（AI 智能体）
+## Usage with an AI agent
 
-1. 将本仓库的 SKILL.md 接入任意 AI 智能体的技能/规则系统（见上方安装）。
-2. 用户问「上次说的部署方案是什么」时，先定位并检索：
+1. Wire this repo's SKILL.md into any agent's skills / rules system (see Installation above).
+2. When the user asks "what was that deployment plan we discussed?", locate and search:
    ```bash
    python3 scripts/yotta_logs.py locate
-   python3 scripts/yotta_logs.py search "部署方案" --dir <日志目录>
+   python3 scripts/yotta_logs.py search "deployment plan"
    ```
-   得到命中时间线（会话 / 时间 / 角色 / 原文片段）。
-3. 需要完整上下文时提取对应会话：
+   You get a timeline of hits (source / session / time / role / raw fragment).
+3. For full context, extract the session:
    ```bash
-   python3 scripts/yotta_logs.py session <会话ID> --dir <日志目录>
+   python3 scripts/yotta_logs.py session <sessionId> --dir <logs directory>
    ```
-4. 需要精确出处时用 --json 拿会话 ID / 行号 / 时间戳，回答时给出依据。
-5. 需要回顾某次会话成本或工具使用分布时用 stats / tools。
+4. For exact provenance, use --json to get source / session ID / line number / timestamp and cite it in your answer.
+5. To review a session's cost or tool-use distribution, use stats / tools.
+
+## Development & validation
+
+- Tests: `python scripts/test_yotta_logs.py` (139 cases: 75 v0.1.0 regression + 64 v0.2.0 generalization)
+- Basic validation: `python tools/validate-skill.py yotta-logs` (run from the repository root)
+- Format registry: references/agent-formats.md; unified format: references/format.md; CLI protocol: references/cli.md; security boundary: references/security.md
 
-## 开发与校验
+## Changelog
 
-- 测试：python scripts/test_yotta_logs.py（75 项）
-- 基础校验：python tools/validate-skill.py yotta-logs（在仓库根目录运行）
-- CLI 协议：references/cli.md；日志格式：references/format.md；安全边界：references/security.md
+- v0.2.1 (2026-08-27): Bilingual documentation — English README as the GitHub / npm / ClawHub homepage, full Chinese doc moved to README.zh-CN.md, English npm description.
+- v0.2.0 (2026-08-27): Multi-format generalization — JSONL / single-file JSON / SQLite (opencode etc.) / Markdown (memory + free notes) / binary; unified Record + field-alias normalization + config fallback; discover; new --source / --kind / --format filters and default search scope (session + structured memory on, free notes / binary logs off). See CHANGELOG.md.
+- v0.1.0 (2026-08-27): Initial release — zero-dependency JSONL session log search engine (locate / scan / search / session / stats / tools / version + default redaction + sessions.json alias + read-only).
 
-## 许可证
+## License
 
-MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。
+MIT © YottaMeta — see [LICENSE](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,182 @@
+<p align="center"><b>语言 / Language</b>：中文（本文件）· <a href="./README.md">English</a></p>
+
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-logs banner" width="100%" />
+</p>
+
+<h1 align="center">yotta-logs · 元史</h1>
+
+<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>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
+  <a href="https://www.npmjs.com/package/@yottameta/yotta-logs"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-logs" /></a>
+  <a href="https://github.com/YottaMeta/yotta-logs"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-logs" /></a>
+  <a href="https://github.com/YottaMeta/yotta-logs/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-logs" /></a>
+  <a href="https://github.com/YottaMeta/yotta-logs"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
+</p>
+
+## 这是什么
+
+智能体每天产生大量会话与记忆记录（JSONL / 单文件 JSON / SQLite / Markdown…），跨会话追溯时最缺的不是「记得发生过」，而是「原文在哪、谁说的、什么时候说的」。元史把这些记录做成**确定性检索引擎**：全源登记日志与记忆位置 → 按关键词 / 正则 / 日期 / 会话 / 角色 / 来源 / 类型 / 格式检索 → 提取会话原文 → 统计消息、token、成本与工具调用。
+
+它不是某个平台的专属功能，而是一份与智能体无关的工具包：装进任何支持 Agent Skills 的智能体即可按需调用。全程零依赖、只读本地、不联网；输出默认脱敏，避免把日志里的密钥 / token 带到上下文。
+
+## 核心价值
+
+- **零依赖检索**：Python 3.8+ 标准库，不依赖 jq / rg / ripgrep 等外部工具，Windows + Linux + macOS 开箱即用。
+- **多格式通用（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 / developer）/ 来源（--source）/ 类型（--kind）/ 格式（--format）。
+- **结构化输出**：--json 输出纯净 JSON，含来源、会话 ID、行号、时间戳、角色，适合程序化核对出处。
+- **只读安全**：只读本地日志与记忆文件，不修改、不删除、不联网上传，与元忆（语义记忆）互补分工。
+
+## 核心优势
+
+| 优势 | 说明 |
+|---|---|
+| **零依赖** | Python 3.8+ 标准库，无模型、无数据库、无外部服务；Windows + Linux + macOS 通用 |
+| **多格式** | JSONL / JSON / SQLite / Markdown / 二进制五大格式族，字段别名归一 + 配置兜底 |
+| **确定性** | 检索逻辑可复现、可解释；命中即原文片段 + 行号，不靠模型猜测 |
+| **默认脱敏** | 疑似密钥 / token / 口令自动打码，降低日志原文外泄风险 |
+| **默认范围** | 会话源 + 结构化记忆源默认开；自由笔记 / 二进制日志默认关，可显式开 |
+| **容错** | 不同智能体的存储形态差异可容忍，坏行跳过不中断，加密文件只回退标题 |
+| **定位准确** | 命中结果带来源 / 会话 ID / 行号 / 时间戳 / 角色，可精确回溯出处 |
+| **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
+
+## 功能体系
+
+| 命令 | 说明 |
+|---|---|
+| locate | 全源登记：发现本机所有日志 / 记忆源（来源 / 格式 / 类型 / 默认开关） |
+| scan | 列出所有会话（跨源）：来源 / 会话 ID / 日期 / 消息数 / 大小 / 别名 |
+| search | 跨源检索：关键词 / 正则 + 日期 / 会话 / 角色 / 来源 / 类型 / 格式过滤，输出时间线命中（--json 结构化） |
+| session | 提取单个会话原文：时间线 + 角色 + 文本，--role 过滤，--tools 标注工具调用 |
+| stats | 会话统计：消息 / 角色分布 / token / 成本 / 时间范围 / 分源（--daily 每日汇总） |
+| tools | 工具调用次数排行 |
+| version | 打印版本 |
+
+## 快速使用
+
+Windows 用 python，Linux/macOS 用 python3。
+
+```bash
+# 全源登记：发现本机所有日志 / 记忆源
+python3 scripts/yotta_logs.py locate
+
+# 跨源检索关键词（默认范围 = 会话 + 结构化记忆；自由笔记默认关）
+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/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
+
+# 统计（消息 / token / 成本 / 每日汇总）
+python3 scripts/yotta_logs.py stats --dir /path/to/sessions --daily
+
+# 工具调用排行
+python3 scripts/yotta_logs.py tools --dir /path/to/sessions
+
+# JSON 结构化输出（适合程序化核对）
+python3 scripts/yotta_logs.py search "部署方案" --dir /path/to/sessions --json
+```
+
+退出码语义（与元安 / 元审 / 元盾 / 元真家族一致）：0 = 成功；1 = 无匹配 / 空结果集；4 = 用法错误 / 致命异常。
+
+未指定 --dir 时，依次尝试环境变量 YOTTA_LOGS_DIR → discover 全源登记（locate 逻辑）并按默认检索范围过滤；找不到则退出码 4 并提示。
+
+## 安装
+
+三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
+
+### 方式一：npm（推荐，一行安装）
+```bash
+# 国内加速（可选）：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-logs -g
+npx -y @yottameta/yotta-logs --dir <你的技能目录>   # 任意智能体：指定目录安装
+```
+> 智能体不在预置列表里？用 --dir 指定它的 skills 目录，或手动复制（方式三）。--list 可查看各智能体对应的默认目录。想手动拿文件也可 npm pack @yottameta/yotta-logs 解包后按方式二/三安装。
+
+### 方式二：install.sh 一键安装
+获取技能文件夹后（npm pack 解包或 git clone），进入技能文件夹：
+```bash
+bash install.sh -g    # 用户级；bash install.sh --list 查看全部目录
+bash install.sh --agent codex   # 指定智能体（--list 可查看可用项）
+bash install.sh       # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
+bash install.sh --dir /path/to/skills
+```
+> 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
+
+### 方式三：手动复制
+把整个 yotta-logs 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 %USERPROFILE%，Linux/macOS 用 ~）：
+
+| 智能体 | 用户级目录 | 项目级目录 |
+|---|---|---|
+| Codex | %USERPROFILE%\.codex\skills\yotta-logs\ | .codex\skills\ |
+| Claude Code | %USERPROFILE%\.claude\skills\yotta-logs\ | .claude\skills\ |
+| Cursor | %USERPROFILE%\.cursor\skills\yotta-logs\ | .cursor\skills\ |
+| Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-logs\ | .windsurf\skills\ |
+| opencode | %USERPROFILE%\.config\opencode\skills\yotta-logs\ | .opencode\skills\ |
+| Gemini | %USERPROFILE%\.gemini\skills\yotta-logs\ | .gemini\skills\ |
+| Goose | %USERPROFILE%\.config\goose\skills\yotta-logs\ | .goose\skills\ |
+| Amp | %USERPROFILE%\.config\agents\skills\yotta-logs\ | .agents\skills\ |
+| Kiro | %USERPROFILE%\.kiro\skills\yotta-logs\ | .kiro\skills\ |
+| WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-logs\ | .workbuddy\skills\ |
+| Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-logs\ | .traecli\skills\ |
+| Trae IDE（国内） | %USERPROFILE%\.trae-cn\skills\yotta-logs\ | .trae\skills\ |
+| Qwen Code | %USERPROFILE%\.qwen\skills\yotta-logs\ | .qwen\skills\ |
+| Comate | %USERPROFILE%\.comate\skills\yotta-logs\ | .comate\skills\ |
+| CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-logs\ | .codebuddy\skills\ |
+| Kimi | %USERPROFILE%\.kimi\skills\yotta-logs\ | .kimi\skills\ |
+| 通用 AGENTS.md | %USERPROFILE%\.agents\skills\yotta-logs\ | .agents\skills\ |
+
+> Codex 默认目录若设置了环境变量 CODEX_HOME，以该变量为准；opencode 若设置 XDG_CONFIG_HOME 同理。.agents\skills 并非通用目录，仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等会读取，Claude Code 与 Codex 默认不读。不确定时用 --dir 指定，或让该智能体自行安装。
+
+## 使用示例（AI 智能体）
+
+1. 将本仓库的 SKILL.md 接入任意 AI 智能体的技能/规则系统（见上方安装）。
+2. 用户问「上次说的部署方案是什么」时，先定位并检索：
+   ```bash
+   python3 scripts/yotta_logs.py locate
+   python3 scripts/yotta_logs.py search "部署方案"
+   ```
+   得到命中时间线（来源 / 会话 / 时间 / 角色 / 原文片段）。
+3. 需要完整上下文时提取对应会话：
+   ```bash
+   python3 scripts/yotta_logs.py session <会话ID> --dir <日志目录>
+   ```
+4. 需要精确出处时用 --json 拿来源 / 会话 ID / 行号 / 时间戳，回答时给出依据。
+5. 需要回顾某次会话成本或工具使用分布时用 stats / tools。
+
+## 开发与校验
+
+- 测试：python scripts/test_yotta_logs.py（139 项，含 75 项 v0.1.0 回归 + 64 项 v0.2.0 通用化用例）
+- 基础校验：python tools/validate-skill.py yotta-logs（在仓库根目录运行）
+- 格式普查：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 别名 + 只读）。
+
+## 许可证
+
+MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。

package/SKILL.md

@@ -1,80 +1,90 @@
 ---
 name: yotta-logs
-version: 0.1.0
-description: 元史 —— 跨智能体的历史会话日志检索技能：零依赖检索 / 分析会话 JSONL 记录，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。触发：用户问起先前聊过的内容 / 父会话 / 历史上下文、要查以前说过的结论、跨会话回溯某次讨论、需要从会话日志定位某段决策时。边界：仅读取本机自己的会话日志文件；不修改、不删除会话记录；只查本地日志不联网上传；与元忆（语义记忆）互补，本技能只做原始日志检索。
+version: 0.2.1
+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 — 安全边界 / 脱敏规则 / 与元忆的差异化
 
 ## 责任声明
 
-本技能只做本地会话日志的只读检索；输出原文片段可能包含隐私，默认脱敏且仅用于本机回溯，请勿将检索结果外传。
+本技能只做本地会话日志 / 记忆文件的只读检索；输出原文片段可能包含隐私，默认脱敏且仅用于本机回溯，请勿将检索结果外传。