@yottameta/yotta-logs 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## v0.3.0 (2026-09-08)
+
+**评测驱动完善**：新增 FAQ，安装器错误处理与测试补齐。
+
+- 新增 references/faq.md，覆盖格式、范围、脱敏、只读边界与安装排障。
+- 安装器支持 --help、参数校验、统一退出码与人话错误提示。
+
 # 更新日志
 
 ## v0.2.2 (2026-08-29)
@@ -8,7 +15,7 @@
 
 ## v0.2.1 (2026-08-27)
 
-文档中英双版（老张拍板「英文门面 + 中文全档」）：
+文档中英双版：
 
 - **README.md 改为英文**：作为 GitHub / npm / ClawHub 首页的英文门面（翻译 + 精简，覆盖定位 / 核心价值 / 命令 / 快速使用 / 安装 / 使用示例 / 开发校验全流程）。
 - **新增 README.zh-CN.md**：原中文完整主文档整体平移，继续服务中文用户，顶部加语言切换链接。
@@ -18,7 +25,7 @@
 
 ## v0.2.0 (2026-08-27)
 
-多格式通用化：不再只认 JSONL，按「格式族 × 字段别名归一 + 配置兜底」适配一切格式（老张拍板三点：方向认可 / 版本 v0.2.0 / 默认检索范围动作工时定）：
+多格式通用化：不再只认 JSONL，按「格式族 × 字段别名归一 + 配置兜底」适配一切格式：
 
 - **五大格式族 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 字符串解包。
@@ -30,9 +37,9 @@
 
 ## v0.1.0 (2026-08-27)
 
-YottaMeta 自有实现首版（历史会话日志检索方向参考开源社区 session-logs 类技能思路，已完全重写，无上游代码）：
+YottaMeta 自有实现首版（历史会话日志检索方向参考开源社区 session-logs 类技能思路，已完全重写）：
 
 - 元史（yotta-logs）—— 零依赖跨智能体会话日志检索引擎（Python 3.8+ 标准库）。
 - 能力：locate / scan / search / session / stats / tools / version；关键词 / 正则 / 日期 / 会话 ID / 别名 / 角色过滤；默认脱敏（--no-redact 关闭）；--json 结构化输出；只读安全；容错 JSONL 解析（含 sessions.json 索引别名）。
 - 测试：scripts/test_yotta_logs.py 75 项全绿。
-- 版权：YottaMeta 纯自有 MIT + NOTICE 品牌声明；README 一行上游致谢。
+- 版权：YottaMeta 纯自有 MIT + NOTICE 品牌声明。

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 YottaMeta
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -162,12 +162,18 @@ bash install.sh --list           # list agents -> default directories
 
 ## Changelog
 
+- v0.3.0 (2026-09-08): Evaluation-driven refinement — added FAQ, hardened installer error handling and exit codes, and added installer tests.
+
 - v0.2.2 (2026-08-29): Install docs alignment — unified four install methods (npx -y @yottameta/yotta-logs --agent/--dir, git clone, GitHub Download ZIP, install.sh --agent/--dir/--list), removed the legacy GitHub-clone installer and global-install (-g) recommendations; bilingual README install section synced to 发布规范 §3.3.1. No functional change.
 
 - 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).
 
+## References
+
+- references/faq.md
+
 ## License
 
 MIT © YottaMeta — see [LICENSE](./LICENSE).

package/README.zh-CN.md

@@ -162,11 +162,17 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 
 ## 更新日志
 
+- v0.3.0（2026-09-08）：评测驱动完善——新增常见问题，安装器错误处理与退出码加固，并补齐安装器测试。
+
 - v0.2.2（2026-08-29）：安装方式统一为四方式（对齐发布规范 §3.3.1）——方式一 npx -y @yottameta/yotta-logs --agent / --dir（推荐，走 npm 源）；方式二 git clone；方式三 GitHub Download ZIP；方式四 bash install.sh --agent/--dir/--list。移除旧式 GitHub 克隆安装器与全局安装（-g）推荐；中英 README 安装节同步。无功能变更。
 
 - 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 别名 + 只读）。
 
+## 参考文档
+
+- references/faq.md
+
 ## 许可证
 
 MIT © YottaMeta —— 详见 [LICENSE](./LICENSE)。

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yotta-logs
-version: 0.2.2
+version: 0.3.0
 description: 元史 —— 跨智能体的历史会话 / 记忆日志检索技能：零依赖检索 / 分析 JSONL、JSON、SQLite、Markdown 多格式会话与记忆文件，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。触发：用户问起先前聊过的内容 / 父会话 / 历史上下文、要查以前说过的结论、跨会话回溯某次讨论、需要从会话日志或记忆文件定位某段决策时。边界：仅读取本机自己的会话日志 / 记忆文件；不修改、不删除；只查本地不联网上传。
 license: MIT
 ---
@@ -84,6 +84,7 @@ python3 scripts/yotta_logs.py tools --dir /path/to/logs --format sqlite
 - references/format.md — 统一 Record 模型与各格式族读取规则
 - references/cli.md — CLI 子命令 / 参数 / 退出码 / JSON schema / 配置详解
 - references/security.md — 安全边界 / 脱敏规则 / 与元忆的差异化
+- references/faq.md — 常见问题与安装排障
 
 ## 责任声明
 

package/bin/install.js

@@ -1,163 +1,245 @@
-#!/usr/bin/env node
-/**
- * yotta-logs 跨平台安装器（YottaSkills）
- * 用法:
- *   npx -y @yottameta/yotta-logs --agent <name>  # 按智能体默认用户级目录安装（推荐）
- *   npx -y @yottameta/yotta-logs --dir PATH      # 装到指定目录（用户改了目录的智能体）
- *   npx -y @yottameta/yotta-logs -g              # 安装到全部已知智能体用户级目录
- *   npx -y @yottameta/yotta-logs                 # 安装到检测到的项目级目录
- *   npx -y @yottameta/yotta-logs --list          # 列出智能体 -> 默认目录
- */
-'use strict';
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const SKILL_NAME = 'yotta-logs';
-const PKG_ROOT = path.join(__dirname, '..');
-
-// 智能体 -> 用户级默认技能目录（dirs 按优先级排列；--agent 装到第一个）
-// 依据官方文档：.agents/skills 并非通用目录，被 OpenCode / Cursor / Cline / Amp /
-// Kimi / Gemini CLI / GitHub Copilot 等读取；Claude Code 与 Codex 默认不读 .agents。
-const AGENT_DIRS = {
-  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
-  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
-  codex:     { label: 'Codex',            dirs: ['.codex/skills'] }, // 特判：$CODEX_HOME/skills
-  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
-  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
-  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
-  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] }, // 特判：$XDG_CONFIG_HOME
-  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
-  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
-  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
-  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
-  'trae-cn': { label: 'Trae IDE（国内）',  dirs: ['.trae-cn/skills'] },
-  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
-  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/skills'] },
-  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
-  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
-  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
-};
-
-// Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/skills
-function codexUserDir() {
-  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  return path.join(base, 'skills');
-}
-
-// OpenCode 用户级目录特判：优先 $XDG_CONFIG_HOME/opencode/skills，否则 ~/.config/opencode/skills
-function opencodeUserDir() {
-  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-  return path.join(base, 'opencode', 'skills');
-}
-
-function resolveUserDir(rel) {
-  if (rel === '.codex/skills') return codexUserDir();
-  if (rel === '.config/opencode/skills') return opencodeUserDir();
-  return path.join(os.homedir(), rel);
-}
-
-function installTo(dest) {
-  const target = path.join(dest, SKILL_NAME);
-  fs.mkdirSync(target, { recursive: true });
-  copyDir(PKG_ROOT, target, new Set(['package.json', 'bin', 'node_modules', '.git']));
-  console.log('installed -> ' + target);
-}
-
-function copyDir(src, dst, skip) {
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    if (skip.has(entry.name)) continue;
-    const s = path.join(src, entry.name);
-    const d = path.join(dst, entry.name);
-    if (entry.isDirectory()) {
-      fs.mkdirSync(d, { recursive: true });
-      copyDir(s, d, skip);
-    } else if (entry.isFile()) {
-      fs.copyFileSync(s, d);
-    }
-  }
-}
-
-function displayDir(rel) {
-  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
-  return '~/' + rel;
-}
-
-function main() {
-  const args = process.argv.slice(2);
-  const isGlobal = args.includes('-g') || args.includes('--global');
-  const list = args.includes('--list') || args.includes('-l');
-  let explicitDir = null;
-  const di = args.indexOf('--dir');
-  if (di !== -1 && args[di + 1]) explicitDir = args[di + 1];
-  let agent = null;
-  const ai = args.indexOf('--agent');
-  if (ai !== -1 && args[ai + 1]) agent = String(args[ai + 1]).toLowerCase();
-
-  if (list) {
-    console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
-    for (const [key, v] of Object.entries(AGENT_DIRS)) {
-      const resolved = v.dirs.map(displayDir);
-      console.log('  ' + key.padEnd(10) + v.label.padEnd(18) + resolved.join('、'));
-    }
-    console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
-    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
-    return;
-  }
-
-  if (explicitDir) { installTo(explicitDir); return; }
-
-  if (agent) {
-    const info = AGENT_DIRS[agent];
-    if (!info) {
-      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
-      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
-      return;
-    }
-    installTo(resolveUserDir(info.dirs[0]));
-    console.log('完成。');
-    return;
-  }
-
-  if (isGlobal) {
-    const seen = new Set();
-    for (const v of Object.values(AGENT_DIRS)) {
-      for (const d of v.dirs) {
-        if (seen.has(d)) continue;
-        seen.add(d);
-        installTo(resolveUserDir(d));
-      }
-    }
-    console.log('完成。');
-    return;
-  }
-
-  const PROJECT_DIRS = [
-    '.claude/skills',
-    '.cursor/skills',
-    '.codex/skills',
-    '.config/goose/skills',
-    '.config/agents/skills',
-    '.opencode/skills',
-    '.codeium/windsurf/skills',
-    '.workbuddy/skills',
-    '.kiro/skills',
-    '.traecli/skills',
-    '.gemini/skills',
-    '.trae-cn/skills',
-    '.qwen/skills',
-    '.comate/skills',
-    '.codebuddy/skills',
-    '.kimi/skills',
-    '.agents/skills',
-  ];
-  let installedAny = false;
-  for (const d of PROJECT_DIRS) {
-    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
-  }
-  if (!installedAny) {
-    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
-  }
-}
-
-main();
+#!/usr/bin/env node
+/**
+ * @yottameta/yotta-logs cross-platform installer.
+ *
+ * Usage:
+ *   npx -y @yottameta/yotta-logs --agent <name>
+ *   npx -y @yottameta/yotta-logs --dir <path>
+ *   npx -y @yottameta/yotta-logs -g
+ *   npx -y @yottameta/yotta-logs
+ *   npx -y @yottameta/yotta-logs --list
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'yotta-logs';
+const PKG_ROOT = path.join(__dirname, '..');
+const COPY_SKIP = new Set(['package.json', 'bin', 'node_modules', '.git', '.github', 'test']);
+
+const AGENT_DIRS = {
+  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
+  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
+  codex:     { label: 'Codex',            dirs: ['.codex/skills'] },
+  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
+  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
+  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
+  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] },
+  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
+  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
+  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
+  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
+  'trae-cn': { label: 'Trae IDE',         dirs: ['.trae-cn/skills'] },
+  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
+  comate:    { label: 'Comate',           dirs: ['.comate/skills'] },
+  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
+  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
+  agents:    { label: 'Generic AGENTS.md', dirs: ['.agents/skills'] },
+};
+
+class UsageError extends Error {}
+class TargetError extends Error {}
+class InstallError extends Error {}
+
+function usage() {
+  console.log('yotta-logs installer');
+  console.log('');
+  console.log('Usage:');
+  console.log('  npx -y @yottameta/yotta-logs --agent <name>  Install to an agent default directory');
+  console.log('  npx -y @yottameta/yotta-logs --dir <path>     Install to a custom directory');
+  console.log('  npx -y @yottameta/yotta-logs -g               Install to all known agent directories');
+  console.log('  npx -y @yottameta/yotta-logs                  Auto-detect project-level directories');
+  console.log('  npx -y @yottameta/yotta-logs --list           List supported agent directories');
+  console.log('');
+  console.log('Options:');
+  console.log('  --agent <name>  Agent key, see --list');
+  console.log('  --dir <path>    Custom skills directory');
+  console.log('  -g, --global    Install to all known user-level directories');
+  console.log('  --list, -l      List supported agents');
+  console.log('  -h, --help      Show this help');
+}
+
+function parseArgs(argv) {
+  const opts = { help: false, list: false, global: false, dir: null, agent: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--list' || arg === '-l') opts.list = true;
+    else if (arg === '--global' || arg === '-g') opts.global = true;
+    else if (arg === '--dir') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--dir requires a non-empty path');
+      opts.dir = value;
+    } else if (arg === '--agent') {
+      const value = argv[++i];
+      if (!value) throw new UsageError('--agent requires a non-empty name');
+      opts.agent = value.toLowerCase();
+    } else {
+      throw new UsageError('Unknown argument: ' + arg);
+    }
+  }
+  if (!opts.help) {
+    const selected = [opts.dir, opts.agent, opts.global].filter(Boolean).length;
+    if (selected > 1) throw new UsageError('Use only one of --dir, --agent, or -g');
+  }
+  return opts;
+}
+
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+function opencodeUserDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'opencode', 'skills');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function printList() {
+  console.log('Agent -> default skill directory:');
+  for (const [key, value] of Object.entries(AGENT_DIRS)) {
+    console.log('  ' + key.padEnd(12) + value.label.padEnd(20) + value.dirs.map(displayDir).join(', '));
+  }
+  console.log('');
+  console.log('Use --dir <path> for agents not listed. CODEX_HOME and XDG_CONFIG_HOME are respected.');
+}
+
+function assertSafeTarget(target) {
+  const rel = path.relative(PKG_ROOT, target);
+  if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) {
+    throw new UsageError('Target directory must be outside the skill source directory');
+  }
+}
+
+function copyDir(src, dst, skip) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name)) continue;
+    const from = path.join(src, entry.name);
+    const to = path.join(dst, entry.name);
+    try {
+      if (entry.isDirectory()) {
+        fs.mkdirSync(to, { recursive: true });
+        copyDir(from, to, skip);
+      } else if (entry.isFile()) {
+        fs.copyFileSync(from, to);
+      }
+    } catch (err) {
+      throw new InstallError('Failed to copy ' + from + ' -> ' + to + ': ' + err.message);
+    }
+  }
+}
+
+function installTo(dest) {
+  if (!dest || typeof dest !== 'string') throw new UsageError('Destination directory is required');
+  const target = path.resolve(dest, SKILL_NAME);
+  assertSafeTarget(target);
+  try {
+    fs.mkdirSync(target, { recursive: true });
+    copyDir(PKG_ROOT, target, COPY_SKIP);
+    if (!fs.existsSync(path.join(target, 'SKILL.md'))) {
+      throw new InstallError('Installed directory is missing SKILL.md');
+    }
+  } catch (err) {
+    if (err instanceof UsageError || err instanceof InstallError) throw err;
+    throw new InstallError('Cannot install to ' + target + ': ' + err.message);
+  }
+  console.log('installed -> ' + target);
+  return target;
+}
+
+function projectDirs() {
+  return [
+    '.claude/skills',
+    '.cursor/skills',
+    '.codex/skills',
+    '.config/goose/skills',
+    '.config/agents/skills',
+    '.opencode/skills',
+    '.codeium/windsurf/skills',
+    '.workbuddy/skills',
+    '.kiro/skills',
+    '.traecli/skills',
+    '.gemini/skills',
+    '.trae-cn/skills',
+    '.qwen/skills',
+    '.comate/skills',
+    '.codebuddy/skills',
+    '.kimi/skills',
+    '.agents/skills',
+  ].filter((dir) => fs.existsSync(dir));
+}
+
+function run() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) { usage(); return; }
+  if (opts.list) { printList(); return; }
+
+  if (opts.dir) { installTo(opts.dir); return; }
+
+  if (opts.agent) {
+    const info = AGENT_DIRS[opts.agent];
+    if (!info) {
+      throw new UsageError('Unknown agent: ' + opts.agent + '. Available: ' + Object.keys(AGENT_DIRS).join(', ') + '. Use --dir for a custom directory.');
+    }
+    installTo(resolveUserDir(info.dirs[0]));
+    return;
+  }
+
+  if (opts.global) {
+    const seen = new Set();
+    let count = 0;
+    for (const value of Object.values(AGENT_DIRS)) {
+      for (const dir of value.dirs) {
+        if (seen.has(dir)) continue;
+        seen.add(dir);
+        installTo(resolveUserDir(dir));
+        count++;
+      }
+    }
+    console.log('Installed to ' + count + ' directories.');
+    return;
+  }
+
+  const dirs = projectDirs();
+  if (!dirs.length) {
+    throw new TargetError('No project-level agent directory detected. Use --agent <name> or --dir <path>.');
+  }
+  for (const dir of dirs) installTo(dir);
+}
+
+function main() {
+  try {
+    run();
+  } catch (err) {
+    if (err instanceof UsageError) {
+      console.error('Usage error: ' + err.message);
+      usage();
+      process.exitCode = 2;
+    } else if (err instanceof TargetError) {
+      console.error('Target error: ' + err.message);
+      process.exitCode = 4;
+    } else if (err instanceof InstallError) {
+      console.error('Install failed: ' + err.message);
+      console.error('Fix: check directory permissions and free space, then retry. Use --dir to choose another directory.');
+      process.exitCode = 1;
+    } else {
+      console.error('Unexpected error: ' + (err && err.message ? err.message : String(err)));
+      process.exitCode = 1;
+    }
+  }
+}
+
+main();

package/install.sh

@@ -1,132 +1,132 @@
-#!/usr/bin/env bash
-# yotta-logs 多智能体安装脚本（YottaSkills 模板）
-# 用法:
-#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
-#   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
-#   bash install.sh -g              # 装到全部已知智能体用户级目录
-#   bash install.sh                  # 检测并安装到已存在的项目级目录
-#   bash install.sh --list          # 列出智能体 -> 默认目录
-set -euo pipefail
-
-SKILL_NAME="yotta-logs"
-SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-case "$(uname -s)" in
-  MINGW*|MSYS*)
-    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
-    ;;
-esac
-
-# 智能体 -> 用户级默认目录（--agent 装到第一个）
-# .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
-# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
-_IS_WINDOWS=0
-case "$(uname -s)" in
-  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
-esac
-dirs_for() {
-  case "$1" in
-    claude)     echo ".claude/skills" ;;
-    cursor)     echo ".cursor/skills .agents/skills" ;;
-    codex)      echo "__CODEX__" ;;
-    gemini)     echo ".gemini/skills .agents/skills" ;;
-    goose)      echo ".config/goose/skills .agents/skills" ;;
-    amp)        echo ".config/agents/skills .agents/skills" ;;
-    opencode)   echo "__OPENCODE__" ;;
-    windsurf)   echo ".codeium/windsurf/skills" ;;
-    workbuddy)  echo ".workbuddy/skills" ;;
-    kiro)       echo ".kiro/skills" ;;
-    trae)       echo ".traecli/skills" ;;
-    trae-cn)    echo ".trae-cn/skills" ;;
-    qwen)       echo ".qwen/skills" ;;
-    comate)     echo ".comate/skills" ;;
-    codebuddy)  echo ".codebuddy/skills" ;;
-    kimi)       echo ".kimi/skills" ;;
-    agents)     echo ".agents/skills" ;;
-    *)          return 1 ;;
-  esac
-}
-
-codex_dir() {
-  if [ -n "${CODEX_HOME:-}" ]; then printf '%s' "$CODEX_HOME/skills"; else printf '%s' "$HOME/.codex/skills"; fi
-}
-opencode_dir() {
-  if [ -n "${XDG_CONFIG_HOME:-}" ]; then printf '%s' "$XDG_CONFIG_HOME/opencode/skills"; else printf '%s' "$HOME/.config/opencode/skills"; fi
-}
-resolve_user() {
-  case "$1" in
-    __CODEX__)    codex_dir ;;
-    __OPENCODE__) opencode_dir ;;
-    *)            printf '%s' "$HOME/$1" ;;
-  esac
-}
-
-install_to() {
-  mkdir -p "$1/$SKILL_NAME"
-  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
-  rm -rf "$1/$SKILL_NAME/.git"
-  echo "installed -> $1/$SKILL_NAME"
-}
-
-list() {
-  echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
-  for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
-    local dirs first
-    dirs="$(dirs_for "$a")"
-    first="${dirs%% *}"
-    case "$first" in
-      __CODEX__)    first=".codex/skills" ;;
-      __OPENCODE__) first=".config/opencode/skills" ;;
-    esac
-    if [ "$_IS_WINDOWS" = "1" ]; then
-      first="%USERPROFILE%\\${first//\//\\}"
-    else
-      first="~/$first"
-    fi
-    printf '  %-10s %s\n' "$a" "$first"
-  done
-  echo '说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。'
-  echo '改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。'
-}
-
-main() {
-  local agent="" dir="" global=0 show_list=0
-  while [ $# -gt 0 ]; do
-    case "$1" in
-      --agent) shift; agent="${1:-}" ;;
-      --dir)   shift; dir="${1:-}" ;;
-      -g|--global) global=1 ;;
-      --list|-l) show_list=1 ;;
-      *) echo "未知参数: $1" >&2; exit 2 ;;
-    esac
-    shift
-  done
-
-  if [ "$show_list" = "1" ]; then list; return; fi
-  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
-  if [ -n "$agent" ]; then
-    local dirs first
-    if ! dirs="$(dirs_for "$agent")"; then
-      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
-    fi
-    first="${dirs%% *}"
-    install_to "$(resolve_user "$first")"; echo "完成。"; return
-  fi
-  if [ "$global" = "1" ]; then
-    echo "安装到全部已知智能体用户级目录..."
-    local dirs rel
-    for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
-      dirs="$(dirs_for "$a")"
-      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
-    done
-    echo "完成。"; return
-  fi
-  local installed=0 d
-  for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
-    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
-  done
-  if [ "$installed" = "0" ]; then
-    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
-  fi
-}
-
+#!/usr/bin/env bash
+# yotta-logs 多智能体安装脚本（YottaSkills 模板）
+# 用法:
+#   bash install.sh --agent <name>  # 按智能体默认用户级目录安装
+#   bash install.sh --dir <path>    # 装到指定目录（用户改过目录的智能体）
+#   bash install.sh -g              # 装到全部已知智能体用户级目录
+#   bash install.sh                  # 检测并安装到已存在的项目级目录
+#   bash install.sh --list          # 列出智能体 -> 默认目录
+set -euo pipefail
+
+SKILL_NAME="yotta-logs"
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "$(uname -s)" in
+  MINGW*|MSYS*)
+    SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)"
+    ;;
+esac
+
+# 智能体 -> 用户级默认目录（--agent 装到第一个）
+# .agents/skills 并非通用目录：OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 读取。
+# 判断当前环境：Windows Git Bash 用 %USERPROFILE%，Unix 用 ~
+_IS_WINDOWS=0
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*) _IS_WINDOWS=1 ;;
+esac
+dirs_for() {
+  case "$1" in
+    claude)     echo ".claude/skills" ;;
+    cursor)     echo ".cursor/skills .agents/skills" ;;
+    codex)      echo "__CODEX__" ;;
+    gemini)     echo ".gemini/skills .agents/skills" ;;
+    goose)      echo ".config/goose/skills .agents/skills" ;;
+    amp)        echo ".config/agents/skills .agents/skills" ;;
+    opencode)   echo "__OPENCODE__" ;;
+    windsurf)   echo ".codeium/windsurf/skills" ;;
+    workbuddy)  echo ".workbuddy/skills" ;;
+    kiro)       echo ".kiro/skills" ;;
+    trae)       echo ".traecli/skills" ;;
+    trae-cn)    echo ".trae-cn/skills" ;;
+    qwen)       echo ".qwen/skills" ;;
+    comate)     echo ".comate/skills" ;;
+    codebuddy)  echo ".codebuddy/skills" ;;
+    kimi)       echo ".kimi/skills" ;;
+    agents)     echo ".agents/skills" ;;
+    *)          return 1 ;;
+  esac
+}
+
+codex_dir() {
+  if [ -n "${CODEX_HOME:-}" ]; then printf '%s' "$CODEX_HOME/skills"; else printf '%s' "$HOME/.codex/skills"; fi
+}
+opencode_dir() {
+  if [ -n "${XDG_CONFIG_HOME:-}" ]; then printf '%s' "$XDG_CONFIG_HOME/opencode/skills"; else printf '%s' "$HOME/.config/opencode/skills"; fi
+}
+resolve_user() {
+  case "$1" in
+    __CODEX__)    codex_dir ;;
+    __OPENCODE__) opencode_dir ;;
+    *)            printf '%s' "$HOME/$1" ;;
+  esac
+}
+
+install_to() {
+  mkdir -p "$1/$SKILL_NAME"
+  cp -r "$SOURCE_DIR/." "$1/$SKILL_NAME/"
+  rm -rf "$1/$SKILL_NAME/.git"
+  echo "installed -> $1/$SKILL_NAME"
+}
+
+list() {
+  echo "智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:"
+  for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+    local dirs first
+    dirs="$(dirs_for "$a")"
+    first="${dirs%% *}"
+    case "$first" in
+      __CODEX__)    first=".codex/skills" ;;
+      __OPENCODE__) first=".config/opencode/skills" ;;
+    esac
+    if [ "$_IS_WINDOWS" = "1" ]; then
+      first="%USERPROFILE%\\${first//\//\\}"
+    else
+      first="~/$first"
+    fi
+    printf '  %-10s %s\n' "$a" "$first"
+  done
+  echo '说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。'
+  echo '改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。'
+}
+
+main() {
+  local agent="" dir="" global=0 show_list=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --agent) shift; agent="${1:-}" ;;
+      --dir)   shift; dir="${1:-}" ;;
+      -g|--global) global=1 ;;
+      --list|-l) show_list=1 ;;
+      *) echo "未知参数: $1" >&2; exit 2 ;;
+    esac
+    shift
+  done
+
+  if [ "$show_list" = "1" ]; then list; return; fi
+  if [ -n "$dir" ]; then install_to "$dir"; echo "完成。"; return; fi
+  if [ -n "$agent" ]; then
+    local dirs first
+    if ! dirs="$(dirs_for "$agent")"; then
+      echo "未收录智能体: $agent。请用 --dir <路径> 指定技能目录。" >&2; exit 2
+    fi
+    first="${dirs%% *}"
+    install_to "$(resolve_user "$first")"; echo "完成。"; return
+  fi
+  if [ "$global" = "1" ]; then
+    echo "安装到全部已知智能体用户级目录..."
+    local dirs rel
+    for a in claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents; do
+      dirs="$(dirs_for "$a")"
+      for rel in $dirs; do install_to "$(resolve_user "$rel")"; done
+    done
+    echo "完成。"; return
+  fi
+  local installed=0 d
+  for d in .claude/skills .cursor/skills .codex/skills .config/goose/skills .config/agents/skills .opencode/skills .codeium/windsurf/skills .workbuddy/skills .kiro/skills .traecli/skills .gemini/skills .trae-cn/skills .qwen/skills .comate/skills .codebuddy/skills .kimi/skills .agents/skills; do
+    if [ -d "$d" ]; then install_to "$d"; installed=1; fi
+  done
+  if [ "$installed" = "0" ]; then
+    echo "未检测到项目级智能体目录。可用 --agent <name> / -g 装到用户级，或 --dir 指定。"
+  fi
+}
+
 main "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-logs",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Yuanshi — a skill for retrieving historical session / memory logs across AI agents: zero-dependency search and analysis of JSONL, JSON, SQLite and Markdown session & memory files (unified Record + field-alias normalization + config fallback), with full source discovery to recall past conversations and parent-session context. Triggers when the user asks about previously discussed content / a parent session / historical context, wants to look up an earlier conclusion, traces a past discussion across sessions, or needs to locate a decision in session logs or memory files. Boundaries: reads only the local agent's own session logs / memory files; never modifies or deletes records; local-only, never uploaded.",
   "license": "MIT",
   "keywords": [
@@ -18,7 +18,10 @@
     "bin",
     "NOTICE",
     "CHANGELOG.md",
-    "README.zh-CN.md"
+    "README.zh-CN.md",
+    "!scripts/__pycache__",
+    "!**/__pycache__",
+    "!**/*.pyc"
   ],
   "repository": {
     "type": "git",
@@ -29,5 +32,8 @@
   },
   "bin": {
     "yotta-logs": "bin/install.js"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\" && python scripts/test_yotta_logs.py"
   }
 }

package/references/agent-formats.md

@@ -120,7 +120,7 @@
 
 引擎零改动即可接入怪格式（个别 agent 私有 schema 用列映射接入）。
 
-## 六、默认检索范围（2026-08-27 老张拍板）
+## 六、默认检索范围
 
 - 会话源（kind=session）+ 结构化记忆源（kind=memory）**默认开**；
 - 自由笔记（kind=note）与二进制日志（kind=log）**默认关**，可 `--kind note` / `--kind log` 显式开；

package/references/faq.md

@@ -0,0 +1,54 @@
+# 元史常见问题
+
+## 速查索引
+
+- **格式**：支持哪些格式 · SQLite 要装依赖吗
+- **范围**：默认扫哪里 · 自由笔记怎么开
+- **检索**：查不到怎么办 · 如何精确到某个会话
+- **安全**：会修改日志吗 · 如何脱敏
+
+---
+
+## 1. 支持哪些格式？
+
+JSONL、单文件 JSON、SQLite、Markdown（结构化记忆与自由笔记）、部分二进制文件的标题回退。
+
+## 2. SQLite 需要额外依赖吗？
+
+不需要，使用 Python 标准库 `sqlite3`，只读打开。
+
+## 3. 默认扫描范围是什么？
+
+会话源与结构化记忆源默认开启；自由笔记和二进制日志默认关闭，可显式开启。
+
+## 4. 如何只查某个目录？
+
+用 `--dir <path>` 指定目录或文件；目录会自动嗅探格式族。
+
+## 5. 自由笔记怎么开启？
+
+用 `--kind note` 或在配置中调整默认范围。
+
+## 6. 查不到怎么办？
+
+先 `locate` 确认源是否存在，再 `scan` 查看可检索内容；确认关键词、日期、会话过滤是否过窄。
+
+## 7. 如何精确提取某个会话？
+
+先 `search` 获取会话 ID，再 `session <sid>` 提取原文。
+
+## 8. 会修改或删除日志吗？
+
+不会。所有操作只读。
+
+## 9. 输出会泄露敏感信息吗？
+
+默认自动脱敏疑似密钥、token、口令；如需原文可用 `--no-redact`，但请谨慎外传。
+
+## 10. JSON 输出有什么用？
+
+包含来源、会话 ID、行号、时间戳、角色等结构化字段，便于程序核对和自动化处理。
+
+## 11. 安装失败怎么办？
+
+确认智能体目录是否正确；未收录智能体用 `--dir` 指定路径；权限问题请检查目标目录写权限。

package/scripts/yotta_logs.py

@@ -64,7 +64,7 @@ try:
 except Exception:
     pass
 
-VERSION = "0.2.2"
+VERSION = "0.3.0"
 TOOL_NAME = "yotta-logs"
 TOOL_CN = "元史"
 DEFAULT_LIMIT = 50