@yottameta/yotta-logs 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +31 -40
  3. package/README.zh-CN.md +31 -41
  4. package/SKILL.md +1 -1
  5. package/package.json +1 -1
  6. package/scripts/yotta_logs.py +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # 更新日志
2
2
 
3
+ ## v0.2.2 (2026-08-29)
4
+
5
+ - 安装方式统一为四方式（对齐发布规范 §3.3.1）：方式一 `npx -y @yottameta/yotta-logs --agent <name>` / `--dir <dir>`（推荐，走 npm 源）；方式二 `git clone https://github.com/YottaMeta/yotta-logs.git`；方式三 GitHub Download ZIP；方式四 `bash install.sh --agent/--dir/--list`。移除 `npx skills` 与 `-g` 推荐；中英双 README 安装节同步。
6
+ - 版本对齐：package.json / SKILL.md / CHANGELOG / 引擎 VERSION / 测试断言 / README 锚点 = 0.2.2。
7
+ - 无功能变更（仅文档与版本同步）。
8
+
3
9
  ## v0.2.1 (2026-08-27)
4
10
 
5
11
  文档中英双版（老张拍板「英文门面 + 中文全档」）：
package/README.md CHANGED
@@ -47,7 +47,7 @@ It is not tied to any single platform: it is an agent-agnostic toolkit that work
47
47
  | **Default scope** | Session + structured memory sources on by default; free notes / binary logs off unless explicitly enabled |
48
48
  | **Fault-tolerant** | Tolerates storage differences across agents; bad lines skipped without aborting; encrypted files fall back to titles |
49
49
  | **Pinpoint provenance** | Hits carry source / session ID / line / timestamp / role for exact tracing |
50
- | **Ecosystem distribution** | GitHub + npm + ClawHub synced; install via npx / install.sh / manual copy |
50
+ | **Ecosystem distribution** | GitHub + npm + ClawHub synced; four install methods (npx / git clone / Download ZIP / install.sh) |
51
51
 
52
52
  ## Commands
53
53
 
@@ -105,50 +105,39 @@ When --dir is omitted, the engine tries $YOTTA_LOGS_DIR, then full source discov
105
105
 
106
106
  ## Installation
107
107
 
108
- Three options — skill files always come from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
108
+ Pick any of the four methods below; the order is the recommended priority. Skill files always come from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
109
109
 
110
- ### Option 1: npm (recommended, one-liner)
111
- ```bash
112
- npx -y @yottameta/yotta-logs -g
113
- npx -y @yottameta/yotta-logs --dir /path/to/skills # any agent: install to a specific directory
110
+ ### Method 1: npm one-liner (recommended)
111
+
112
+ ```text
113
+ # Optional China mirror: npm config set registry https://registry.npmmirror.com
114
+ npx -y @yottameta/yotta-logs --agent <agent-name> # install to the agent's default user-level skills dir
115
+ npx -y @yottameta/yotta-logs --dir <your-skills-dir> # point to the skills dir itself (e.g. ~/.codex/skills)
114
116
  ```
115
- > 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.
116
117
 
117
- ### Option 2: install.sh one-liner
118
- From inside the skill folder (npm pack or git clone):
119
- ```bash
120
- bash install.sh -g # user-level; bash install.sh --list shows all directories
121
- bash install.sh --agent codex # specific agent (--list shows available entries)
122
- bash install.sh # project-level: auto-detect existing .claude/.cursor/.codex skills dirs
123
- bash install.sh --dir /path/to/skills
118
+ - `--agent <name>` installs to that agent's default user-level directory; `--list` shows each agent's default directory.
119
+ - `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir` at their skills directory.
120
+ - If the mirror has not synced the new package (404): add `--registry=https://registry.npmjs.org/` (a proxy may be needed in China), or wait for the mirror cache.
121
+
122
+ ### Method 2: git clone (developers / git available)
123
+
124
+ ```text
125
+ git clone https://github.com/YottaMeta/yotta-logs.git <your-skills-dir>/yotta-logs
124
126
  ```
125
- > Covers 17 agents including Trae / Qwen / Comate / CodeBuddy / Kimi. On Windows, Git Bash is sufficient; otherwise use Option 3.
126
-
127
- ### Option 3: manual copy
128
- Copy the whole `yotta-logs` folder into the target agent's skills directory. Common locations (user-level; %USERPROFILE% on Windows, ~ on Linux/macOS):
129
-
130
- | Agent | User-level dir | Project-level dir |
131
- |---|---|---|
132
- | Codex | %USERPROFILE%\.codex\skills\yotta-logs\ | .codex\skills\ |
133
- | Claude Code | %USERPROFILE%\.claude\skills\yotta-logs\ | .claude\skills\ |
134
- | Cursor | %USERPROFILE%\.cursor\skills\yotta-logs\ | .cursor\skills\ |
135
- | Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-logs\ | .windsurf\skills\ |
136
- | opencode | %USERPROFILE%\.config\opencode\skills\yotta-logs\ | .opencode\skills\ |
137
- | Gemini | %USERPROFILE%\.gemini\skills\yotta-logs\ | .gemini\skills\ |
138
- | Goose | %USERPROFILE%\.config\goose\skills\yotta-logs\ | .goose\skills\ |
139
- | Amp | %USERPROFILE%\.config\agents\skills\yotta-logs\ | .agents\skills\ |
140
- | Kiro | %USERPROFILE%\.kiro\skills\yotta-logs\ | .kiro\skills\ |
141
- | WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-logs\ | .workbuddy\skills\ |
142
- | Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-logs\ | .traecli\skills\ |
143
- | Trae IDE (CN) | %USERPROFILE%\.trae-cn\skills\yotta-logs\ | .trae\skills\ |
144
- | Qwen Code | %USERPROFILE%\.qwen\skills\yotta-logs\ | .qwen\skills\ |
145
- | Comate | %USERPROFILE%\.comate\skills\yotta-logs\ | .comate\skills\ |
146
- | CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-logs\ | .codebuddy\skills\ |
147
- | Kimi | %USERPROFILE%\.kimi\skills\yotta-logs\ | .kimi\skills\ |
148
- | Generic AGENTS.md | %USERPROFILE%\.agents\skills\yotta-logs\ | .agents\skills\ |
149
-
150
- > 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.
151
127
 
128
+ ### Method 3: GitHub Download ZIP (manual / no git)
129
+
130
+ On the GitHub repository `YottaMeta/yotta-logs`, click **Code → Download ZIP**, unzip it and put the `yotta-logs` folder into the agent's skills directory.
131
+
132
+ ### Method 4: install.sh (multi-agent one-liner script)
133
+
134
+ ```text
135
+ bash install.sh --agent <name> # install to the agent's default user-level directory
136
+ bash install.sh --dir <path> # install to the given directory
137
+ bash install.sh --list # list agents -> default directories
138
+ ```
139
+
140
+ > Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.
152
141
  ## Usage with an AI agent
153
142
 
154
143
  1. Wire this repo's SKILL.md into any agent's skills / rules system (see Installation above).
@@ -173,6 +162,8 @@ Copy the whole `yotta-logs` folder into the target agent's skills directory. Com
173
162
 
174
163
  ## Changelog
175
164
 
165
+ - 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.
166
+
176
167
  - 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.
177
168
  - 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.
178
169
  - 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).
package/README.zh-CN.md CHANGED
@@ -47,7 +47,7 @@
47
47
  | **默认范围** | 会话源 + 结构化记忆源默认开；自由笔记 / 二进制日志默认关，可显式开 |
48
48
  | **容错** | 不同智能体的存储形态差异可容忍，坏行跳过不中断，加密文件只回退标题 |
49
49
  | **定位准确** | 命中结果带来源 / 会话 ID / 行号 / 时间戳 / 角色，可精确回溯出处 |
50
- | **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / install.sh / 手动复制三种安装方式 |
50
+ | **生态分发** | GitHub + npm + ClawHub 三源同步发布；npx / git clone / Download ZIP / install.sh 四种安装方式 |
51
51
 
52
52
  ## 功能体系
53
53
 
@@ -105,51 +105,39 @@ python3 scripts/yotta_logs.py search "部署方案" --dir /path/to/sessions --js
105
105
 
106
106
  ## 安装
107
107
 
108
- 三种方式任选其一，技能文件统一从 **npm** 获取（GitHub 无代理时较慢，npm 可配国内镜像加速）。
108
+ 以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
109
109
 
110
- ### 方式一：npm（推荐，一行安装）
111
- ```bash
112
- # 国内加速（可选）：npm config set registry https://registry.npmmirror.com
113
- npx -y @yottameta/yotta-logs -g
114
- npx -y @yottameta/yotta-logs --dir <你的技能目录> # 任意智能体：指定目录安装
110
+ ### 方式一：npm 一行装（推荐）
111
+
112
+ ```text
113
+ # 可选国内加速：npm config set registry https://registry.npmmirror.com
114
+ npx -y @yottameta/yotta-logs --agent <智能体名称> # 装到指定智能体默认用户级技能目录
115
+ npx -y @yottameta/yotta-logs --dir <智能体的技能目录> # 指到技能目录本身（如 ~/.codex/skills）
115
116
  ```
116
- > 智能体不在预置列表里？用 --dir 指定它的 skills 目录，或手动复制（方式三）。--list 可查看各智能体对应的默认目录。想手动拿文件也可 npm pack @yottameta/yotta-logs 解包后按方式二/三安装。
117
117
 
118
- ### 方式二：install.sh 一键安装
119
- 获取技能文件夹后（npm pack 解包或 git clone），进入技能文件夹：
120
- ```bash
121
- bash install.sh -g # 用户级；bash install.sh --list 查看全部目录
122
- bash install.sh --agent codex # 指定智能体（--list 可查看可用项）
123
- bash install.sh # 项目级：自动检测已存在的 .claude/.cursor/.codex 等 skills 目录
124
- bash install.sh --dir /path/to/skills
118
+ - `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。
119
+ - `--dir <路径>` 装到指定的技能目录；未收录的智能体用 `--dir` 指到它的技能目录。
120
+ - npmmirror 未同步新包（404）：加 `--registry=https://registry.npmjs.org/`（国内需代理），或稍等镜像缓存。
121
+
122
+ ### 方式二：git clone（开发者 / 有 git 环境）
123
+
124
+ ```text
125
+ git clone https://github.com/YottaMeta/yotta-logs.git <智能体的技能目录>/yotta-logs
125
126
  ```
126
- > 覆盖 17 类智能体，含国内 Trae / Qwen / Comate / CodeBuddy / Kimi。Windows 用户：装有 Git Bash 即可用；否则用方式三手动复制。
127
-
128
- ### 方式三：手动复制
129
- 把整个 yotta-logs 文件夹复制到目标智能体的 skills 目录。常见位置（用户级；Windows 用 %USERPROFILE%，Linux/macOS 用 ~）：
130
-
131
- | 智能体 | 用户级目录 | 项目级目录 |
132
- |---|---|---|
133
- | Codex | %USERPROFILE%\.codex\skills\yotta-logs\ | .codex\skills\ |
134
- | Claude Code | %USERPROFILE%\.claude\skills\yotta-logs\ | .claude\skills\ |
135
- | Cursor | %USERPROFILE%\.cursor\skills\yotta-logs\ | .cursor\skills\ |
136
- | Windsurf | %USERPROFILE%\.codeium\windsurf\skills\yotta-logs\ | .windsurf\skills\ |
137
- | opencode | %USERPROFILE%\.config\opencode\skills\yotta-logs\ | .opencode\skills\ |
138
- | Gemini | %USERPROFILE%\.gemini\skills\yotta-logs\ | .gemini\skills\ |
139
- | Goose | %USERPROFILE%\.config\goose\skills\yotta-logs\ | .goose\skills\ |
140
- | Amp | %USERPROFILE%\.config\agents\skills\yotta-logs\ | .agents\skills\ |
141
- | Kiro | %USERPROFILE%\.kiro\skills\yotta-logs\ | .kiro\skills\ |
142
- | WorkBuddy | %USERPROFILE%\.workbuddy\skills\yotta-logs\ | .workbuddy\skills\ |
143
- | Trae Code CLI | %USERPROFILE%\.traecli\skills\yotta-logs\ | .traecli\skills\ |
144
- | Trae IDE（国内） | %USERPROFILE%\.trae-cn\skills\yotta-logs\ | .trae\skills\ |
145
- | Qwen Code | %USERPROFILE%\.qwen\skills\yotta-logs\ | .qwen\skills\ |
146
- | Comate | %USERPROFILE%\.comate\skills\yotta-logs\ | .comate\skills\ |
147
- | CodeBuddy | %USERPROFILE%\.codebuddy\skills\yotta-logs\ | .codebuddy\skills\ |
148
- | Kimi | %USERPROFILE%\.kimi\skills\yotta-logs\ | .kimi\skills\ |
149
- | 通用 AGENTS.md | %USERPROFILE%\.agents\skills\yotta-logs\ | .agents\skills\ |
150
-
151
- > Codex 默认目录若设置了环境变量 CODEX_HOME，以该变量为准；opencode 若设置 XDG_CONFIG_HOME 同理。.agents\skills 并非通用目录，仅 OpenCode / Cursor / Cline / Amp / Kimi / Gemini CLI / GitHub Copilot 等会读取，Claude Code 与 Codex 默认不读。不确定时用 --dir 指定，或让该智能体自行安装。
152
127
 
128
+ ### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
129
+
130
+ 在 GitHub 仓库 `YottaMeta/yotta-logs` 点 **Code → Download ZIP**，解压后把 `yotta-logs` 文件夹放进智能体技能目录。
131
+
132
+ ### 方式四：install.sh（多智能体一键脚本）
133
+
134
+ ```text
135
+ bash install.sh --agent <name> # 装到指定智能体默认用户级目录
136
+ bash install.sh --dir <path> # 装到指定目录
137
+ bash install.sh --list # 列出智能体 -> 默认目录
138
+ ```
139
+
140
+ > 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
153
141
  ## 使用示例（AI 智能体）
154
142
 
155
143
  1. 将本仓库的 SKILL.md 接入任意 AI 智能体的技能/规则系统（见上方安装）。
@@ -174,6 +162,8 @@ bash install.sh --dir /path/to/skills
174
162
 
175
163
  ## 更新日志
176
164
 
165
+ - 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 安装节同步。无功能变更。
166
+
177
167
  - v0.2.0（2026-08-27）：多格式通用化——JSONL / 单文件 JSON / SQLite（opencode 等）/ Markdown（记忆 + 自由笔记）/ 二进制五大格式族，统一 Record + 字段别名归一 + 配置兜底，discover 全源登记，新增 --source / --kind / --format 过滤与默认检索范围（会话 + 结构化记忆开、自由笔记 / 二进制日志关）。详见 CHANGELOG.md。
178
168
  - v0.1.0（2026-08-27）：首版——零依赖 JSONL 会话日志检索引擎（locate / scan / search / session / stats / tools / version + 默认脱敏 + sessions.json 别名 + 只读）。
179
169
 
package/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: yotta-logs
3
- version: 0.2.1
3
+ version: 0.2.2
4
4
  description: 元史 —— 跨智能体的历史会话 / 记忆日志检索技能：零依赖检索 / 分析 JSONL、JSON、SQLite、Markdown 多格式会话与记忆文件，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。触发：用户问起先前聊过的内容 / 父会话 / 历史上下文、要查以前说过的结论、跨会话回溯某次讨论、需要从会话日志或记忆文件定位某段决策时。边界：仅读取本机自己的会话日志 / 记忆文件；不修改、不删除；只查本地不联网上传。
5
5
  license: MIT
6
6
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yottameta/yotta-logs",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "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.",
5
5
  "license": "MIT",
6
6
  "keywords": [
package/scripts/yotta_logs.py CHANGED
@@ -64,7 +64,7 @@ try:
64
64
  except Exception:
65
65
  pass
66
66
 
67
- VERSION = "0.2.1"
67
+ VERSION = "0.2.2"
68
68
  TOOL_NAME = "yotta-logs"
69
69
  TOOL_CN = "元史"
70
70
  DEFAULT_LIMIT = 50