session-trail 0.2.0__tar.gz

session_trail-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fwt11
+
+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.

session_trail-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include README.en.md
+recursive-include src/agent_trail/static *
+recursive-include src/agent_trail/tray *.png *.template

session_trail-0.2.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: session-trail
+Version: 0.2.0
+Summary: Local cross-agent work timeline: discover, browse and resume coding-agent sessions on your machine
+Author: fwt11
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/fwt11/agent_trail
+Project-URL: Repository, https://github.com/fwt11/agent_trail
+Project-URL: Issues, https://github.com/fwt11/agent_trail/issues
+Keywords: ai-agents,coding-agent,timeline,session-management,local-first,tray,systray
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Agent 足迹（agent-trail）
+
+中文 | [English](README.en.md)
+
+跨 Agent 的本地工作记忆：自动发现你机器上各种编码 Agent 留下的会话记录，汇成一条按日期分组的时间线，帮你回答"昨天那个东西我到底是用哪个工具、在哪个目录做的"，并尽量一键回到原会话继续工作。
+
+![时间线截图](docs/screenshot.png)
+
+如果你在多个编码 Agent（Kimi Code、CodeBuddy、ZCode、OpenCode……）之间来回切换，大概也经历过这种时刻：只记得"昨天做过某个东西"，却想不起用了哪个工具、在哪个目录。这个工具做的就是缩短"模糊回忆 → 找到工作现场 → 继续工作"的路径。
+
+## 特性
+
+- **自动发现**：只读扫描各 Agent 已保存的本机会话（JSONL / JSON / SQLite），不改变任何现有使用习惯
+- **统一时间线**：按本地日期分组、按最后活动时间倒序；支持今天/昨天/最近 7 天、Agent、项目目录和标题/目录文本筛选
+- **实时更新**：Linux 下用 inotify 监控源文件变化，秒级反映新会话（不可用时自动回退到定时轮询）
+- **工作段折叠**：同一 Agent、同一目录、相邻间隔 ≤45 分钟的会话可折叠为一段，展开仍能定位每个原会话
+- **回到原会话**：对真实验证过恢复路径的工具，在原工作目录起一个新终端执行对应恢复命令
+- **隐私优先**：本地索引只存元数据（标题、目录、时间、统计），不存任何消息正文、代码、diff 或凭据；HTTP 服务只绑定 127.0.0.1，每次启动生成高熵访问令牌
+- **诚实降级**：没有原生标题就显示"未命名会话"，恢复路径没验证过就不显示恢复按钮，绝不伪造
+
+## 支持的 Agent
+
+| Agent | 时间线 | 回到原会话 | 说明 |
+| --- | :-: | :-: | --- |
+| Kimi Code | ✅ | ✅ | `kimi --session <id>`，真机验证 |
+| CodeBuddy | ✅ | ✅ | `codebuddy --resume <id>`，真机验证 |
+| MiniMax Code | ✅ | ✅ | `mcode --session <id>`，主会话真机验证；子代理会话只读 |
+| OpenCode | ✅ | ✅ | `opencode --session <id>`，真机验证 |
+| ZCode | ✅ | ➖ | 深链路由未验证，只读展示 |
+| DeepSeek Harness | ✅ | ➖ | 恢复未通过真机验证，只读展示 |
+| Pi | ✅ | ➖ | 恢复未通过真机验证，只读展示 |
+| Codex | ✅ | ➖ | 恢复需要目录信任决策，未授权验证，只读展示 |
+| Claude Code | ⚠️ | ➖ | 实验性检测，本机无数据时不产生虚假记录 |
+
+## 安装
+
+要求：Python ≥ 3.10，Linux（inotify 实时监控为 Linux 特性，其余平台自动退化为轮询）。**零第三方运行时依赖**，纯标准库。
+
+```bash
+pip install session-trail
+```
+
+或从源码安装：
+
+```bash
+git clone https://github.com/fwt11/agent_trail.git
+cd agent_trail
+pip install .
+```
+
+## 使用
+
+```bash
+agent-trail scan      # 扫描一次，输出各来源状态与记录数
+agent-trail list      # 以 JSON Lines 输出全部会话元数据
+agent-trail serve     # 启动本地控制台（默认自动打开浏览器）
+agent-trail tray      # 系统托盘形态（Linux，见下）
+```
+
+`serve` 常用选项：
+
+```bash
+agent-trail serve --port 8731        # 固定端口（默认随机）
+agent-trail serve --no-browser       # 不自动打开浏览器
+agent-trail serve --no-watch         # 禁用 inotify，只用定时轮询
+agent-trail serve --interval 30      # 轮询间隔（watch 健康时自动降为 5 分钟安全网）
+```
+
+启动后控制台 URL 带一次性高熵访问令牌（如 `http://127.0.0.1:8731/?key=…`）；令牌保存在浏览器 sessionStorage，后续请求通过请求头携带，所有 API 都会校验。手动刷新按钮立即触发一次扫描。
+
+## 桌面托盘（Linux）
+
+`serve` 之外还有系统托盘形态，已整合为子命令：内嵌窗口展示控制台，托盘菜单提供打开控制台、立即刷新、启动/停止服务、开机自启和退出。
+
+```bash
+agent-trail tray             # 启动托盘（自动拉起 agent-trail serve）
+agent-trail tray --show      # 启动同时打开控制台窗口
+agent-trail tray --install   # 写入应用菜单入口；--uninstall 反向清理
+```
+
+托盘壳本身不依赖任何第三方 pip 包，但需要 GTK 的 GI 绑定（系统 Python 通常自带）。`agent-trail tray` 在当前解释器缺 GI 绑定时会自动改用带绑定的系统 Python 重执行（例如 pip 装在 venv 里、托盘跑在系统 Python），无需任何手动操作；实在找不到时按提示安装：
+
+```bash
+# Debian/Ubuntu/deepin 系
+sudo apt install python3-gi gir1.2-webkit2-4.1
+```
+
+托盘以子进程方式管理 `agent-trail serve`（可用环境变量 `AGENT_TRAIL_BIN` 覆盖可执行文件路径），服务异常退出自动重启（退避重试，连续失败后停在可手动启动的状态）。窗口直接关闭只是隐藏，退出走托盘菜单；flock 单实例锁防止重复启动。
+
+托盘图标走原生 StatusNotifierItem/DBusMenu 协议（`agent_trail/tray/sni.py`，Gio 实现——libayatana 在 Deepin 23 的托盘守护上不工作，详见源码注释）。内嵌 WebView 默认使用软件合成（`WEBKIT_DISABLE_DMABUF_RENDERER` / `WEBKIT_DISABLE_COMPOSITING_MODE`，可用同名环境变量覆盖），避免在无 DRM 权限的会话里出现空白窗口。`serve` 的所有命令行形态保持不变，无托盘环境（SSH/无桌面）不受影响。
+
+## 工作原理
+
+```
+各 Agent 本地数据                本工具                        呈现
+─────────────────      ─────────────────────────      ─────────────────
+JSONL / JSON / SQLite ─▶ 适配器（9 种，只读） ─▶ 元数据索引    ─▶ 本地网页时间线
+  ~/.kimi-code/…          规范化为统一模型      (SQLite)      127.0.0.1 + 令牌
+  ~/.zcode/…              指纹增量去重                        筛选 / 详情 / 恢复
+  ~/.codex/…              inotify 事件触发重扫
+```
+
+- **适配器契约**：每个 Agent 一个适配器，实现发现（discover）、扫描（scan）、状态（status）、恢复计划（resume_plan）四个边界；数据源格式变化时报告不兼容而不是猜测
+- **增量扫描**：以源路径、大小、mtime 和适配器版本计算指纹，未变化的来源毫秒级跳过
+- **实时监控**：`watcher.py` 用 ctypes 直接调 libc inotify（保持零依赖），目录级 watch 覆盖原子替换与 WAL sidecar 变化；去抖 + 最小间隔合并高频写入
+- **恢复安全**：恢复命令来自适配器白名单参数数组，不经过 shell；API 只接受会话标识，服务端重新查库生成计划，调用者无法注入命令或目录
+- **源数据只读**：SQLite 源以 `mode=ro` 打开，禁止任何写事务；源记录删除后保留最后元数据并标记"源已缺失"、禁用恢复
+
+## 隐私与安全
+
+- 明确不读取各工具的 credentials、auth、token、密钥类文件
+- 本地索引与日志不保存消息正文、代码、命令、diff、附件或凭据
+- HTTP 仅绑定回环地址；刷新与恢复使用 POST 并校验 Origin，防止外部网页诱导本机服务执行动作
+- 网页不加载任何第三方脚本、字体或统计
+
+## 已知限制
+
+- 元数据优先：部分会话只有"未命名会话"，以目录和时间辅助识别；不读取首条用户消息补标题
+- 适配器基于当前各工具的本机数据格式，工具升级后可能需要更新
+- "回到工作现场"指原 Agent 会话与目录，不保证恢复未保存的文件或桌面布局
+
+## 开发文档
+
+- [设计文档](docs/design.md)
+- [实施计划](docs/implementation-plan.md)
+
+## 许可证
+
+[MIT](LICENSE)

session_trail-0.2.0/README.en.md

@@ -0,0 +1,128 @@
+# Agent Trail (Agent 足迹)
+
+[中文](README.md) | English
+
+A local-first work memory for people who use multiple coding agents: it discovers the sessions your agents already saved on this machine, lines them up on one dated timeline, and — where verified — drops you back into the original session with one click. Answers the "I did something yesterday… with which tool, in which directory?" problem.
+
+![Timeline screenshot](docs/screenshot.png)
+
+## Features
+
+- **Automatic discovery**: read-only scanning of the sessions each agent already stores locally (JSONL / JSON / SQLite); nothing about your existing habits changes
+- **One timeline**: grouped by local date, newest first; filter by today/yesterday/last 7 days, agent, project directory, and title/directory text
+- **Live updates**: on Linux, inotify watches the source files and reflects new sessions within seconds (falls back to interval polling automatically)
+- **Work segments**: sessions from the same tool, same directory, within 45 minutes fold into one segment — expandable down to every original session
+- **Resume original session**: for tools whose resume path is verified, opens a new terminal in the original working directory
+- **Privacy first**: the local index stores metadata only (titles, directories, timestamps, stats) — never message bodies, code, diffs or credentials; the HTTP console binds to 127.0.0.1 with a per-start high-entropy access token
+- **Honest degradation**: no native title → "Unnamed session"; unverified resume paths → no resume button. It never fakes capabilities
+- **i18n**: the console UI and tray menu ship in Simplified Chinese and English; the console follows your browser language (`?lang=en` / `?lang=zh-CN` to override), the tray follows `LANG` (`AGENT_TRAIL_LANG` overrides)
+
+## Supported agents
+
+| Agent | Timeline | Resume | Notes |
+| --- | :-: | :-: | --- |
+| Kimi Code | ✅ | ✅ | `kimi --session <id>`, verified on a real machine |
+| CodeBuddy | ✅ | ✅ | `codebuddy --resume <id>`, verified |
+| MiniMax Code | ✅ | ✅ | `mcode --session <id>`, verified for main sessions; subagent sessions are view-only |
+| OpenCode | ✅ | ✅ | `opencode --session <id>`, verified |
+| ZCode | ✅ | ➖ | deep-link route unverified; view-only |
+| DeepSeek Harness | ✅ | ➖ | resume failed verification; view-only |
+| Pi | ✅ | ➖ | resume failed verification; view-only |
+| Codex | ✅ | ➖ | resume needs an interactive directory-trust decision; view-only |
+| Claude Code | ⚠️ | ➖ | experimental detection; no fake records without real data |
+
+## Install
+
+Requires Python ≥ 3.10 and Linux for the inotify live updates (other platforms degrade to polling). **Zero third-party runtime dependencies** — standard library only.
+
+```bash
+pip install session-trail
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/fwt11/agent_trail.git
+cd agent_trail
+pip install .
+```
+
+## Usage
+
+```bash
+agent-trail scan      # scan once, print per-source status and record counts
+agent-trail list      # print all session metadata as JSON Lines
+agent-trail serve     # start the local console (opens the browser by default)
+agent-trail tray      # system tray app (Linux, see below)
+```
+
+Common `serve` options:
+
+```bash
+agent-trail serve --port 8731        # fixed port (random by default)
+agent-trail serve --no-browser       # do not open the browser
+agent-trail serve --no-watch         # disable inotify, poll on an interval
+agent-trail serve --interval 30      # poll interval (drops to a 5-minute safety net while watching)
+```
+
+The console URL carries a one-time high-entropy token (`http://127.0.0.1:8731/?key=…`); the token lives in the browser's sessionStorage and every API call is checked. The refresh button triggers a scan immediately.
+
+## Desktop tray (Linux)
+
+Beyond `serve`, a tray application embeds the console in a native window and adds a tray menu: open console, refresh, start/stop service, launch at login, quit.
+
+```bash
+agent-trail tray             # start the tray (spawns agent-trail serve)
+agent-trail tray --show      # also open the console window
+agent-trail tray --install   # add an applications-menu entry; --uninstall reverts
+```
+
+The tray needs GTK GI bindings (preinstalled on most distros as the system Python). If the interpreter running agent-trail lacks them — e.g. the package lives in a venv — `agent-trail tray` automatically re-executes itself with a system Python that has GI; no manual steps. If none is found, install:
+
+```bash
+# Debian/Ubuntu/deepin
+sudo apt install python3-gi gir1.2-webkit2-4.1
+```
+
+The tray manages `agent-trail serve` as a subprocess (override with `AGENT_TRAIL_BIN`) and restarts it automatically with backoff if it dies. Closing the window only hides it; quit lives in the tray menu. A flock single-instance lock prevents duplicates.
+
+The tray icon speaks the native StatusNotifierItem/DBusMenu protocol (`agent_trail/tray/sni.py`, implemented with Gio — libayatana does not work against Deepin 23's tray daemon; see source comments). The embedded WebView defaults to software compositing (`WEBKIT_DISABLE_DMABUF_RENDERER` / `WEBKIT_DISABLE_COMPOSITING_MODE`, overridable via env), avoiding blank windows on sessions without DRM access. All `serve`/CLI forms keep working without a desktop.
+
+## How it works
+
+```
+Agent session data               this tool                       presentation
+──────────────────      ─────────────────────────      ─────────────────
+JSONL / JSON / SQLite  ─▶  9 read-only adapters  ─▶  metadata index  ─▶  local web console
+  ~/.kimi-code/…           normalized model         (SQLite)        127.0.0.1 + token
+  ~/.zcode/…               fingerprinted deltas                     filters / details / resume
+  ~/.codex/…               inotify-triggered rescans
+```
+
+- **Adapter contract**: one adapter per agent implementing discover / scan / status / resume_plan; incompatible formats are reported, never guessed
+- **Incremental scans**: a fingerprint over source paths, sizes, mtimes and adapter version; unchanged sources skip in milliseconds
+- **Live watching**: `watcher.py` calls libc inotify via ctypes (staying dependency-free); directory-level watches cover atomic renames and WAL sidecars; debounce + minimum spacing merge write bursts
+- **Resume safety**: resume commands come from an adapter whitelist and run as argument arrays — never through a shell; the API only accepts session identifiers and regenerates the plan server-side
+- **Source data is read-only**: SQLite sources open with `mode=ro`; deleted source records keep their last metadata, flagged missing with resume disabled
+
+## Privacy & security
+
+- Never reads credentials, auth, token, or key files of any agent
+- The local index and logs contain no message bodies, code, commands, diffs, attachments or credentials
+- HTTP binds to the loopback interface only; refresh and resume are POST with Origin checks, so foreign web pages cannot drive the local service
+- The web console loads no third-party scripts, fonts or analytics
+
+## Known limitations
+
+- Metadata-first: some sessions appear as "Unnamed session", identified by directory and time; first user messages are never read to fabricate titles
+- Adapters target current on-disk formats; tool upgrades may require adapter updates
+- "Back to the work site" means the original agent session and directory — unsaved files or desktop layout are not restored
+
+## Development docs
+
+- [Design document](docs/design.md) (Chinese)
+- [Implementation plan](docs/implementation-plan.md) (Chinese)
+
+## License
+
+[MIT](LICENSE)

session_trail-0.2.0/README.md

@@ -0,0 +1,129 @@
+# Agent 足迹（agent-trail）
+
+中文 | [English](README.en.md)
+
+跨 Agent 的本地工作记忆：自动发现你机器上各种编码 Agent 留下的会话记录，汇成一条按日期分组的时间线，帮你回答"昨天那个东西我到底是用哪个工具、在哪个目录做的"，并尽量一键回到原会话继续工作。
+
+![时间线截图](docs/screenshot.png)
+
+如果你在多个编码 Agent（Kimi Code、CodeBuddy、ZCode、OpenCode……）之间来回切换，大概也经历过这种时刻：只记得"昨天做过某个东西"，却想不起用了哪个工具、在哪个目录。这个工具做的就是缩短"模糊回忆 → 找到工作现场 → 继续工作"的路径。
+
+## 特性
+
+- **自动发现**：只读扫描各 Agent 已保存的本机会话（JSONL / JSON / SQLite），不改变任何现有使用习惯
+- **统一时间线**：按本地日期分组、按最后活动时间倒序；支持今天/昨天/最近 7 天、Agent、项目目录和标题/目录文本筛选
+- **实时更新**：Linux 下用 inotify 监控源文件变化，秒级反映新会话（不可用时自动回退到定时轮询）
+- **工作段折叠**：同一 Agent、同一目录、相邻间隔 ≤45 分钟的会话可折叠为一段，展开仍能定位每个原会话
+- **回到原会话**：对真实验证过恢复路径的工具，在原工作目录起一个新终端执行对应恢复命令
+- **隐私优先**：本地索引只存元数据（标题、目录、时间、统计），不存任何消息正文、代码、diff 或凭据；HTTP 服务只绑定 127.0.0.1，每次启动生成高熵访问令牌
+- **诚实降级**：没有原生标题就显示"未命名会话"，恢复路径没验证过就不显示恢复按钮，绝不伪造
+
+## 支持的 Agent
+
+| Agent | 时间线 | 回到原会话 | 说明 |
+| --- | :-: | :-: | --- |
+| Kimi Code | ✅ | ✅ | `kimi --session <id>`，真机验证 |
+| CodeBuddy | ✅ | ✅ | `codebuddy --resume <id>`，真机验证 |
+| MiniMax Code | ✅ | ✅ | `mcode --session <id>`，主会话真机验证；子代理会话只读 |
+| OpenCode | ✅ | ✅ | `opencode --session <id>`，真机验证 |
+| ZCode | ✅ | ➖ | 深链路由未验证，只读展示 |
+| DeepSeek Harness | ✅ | ➖ | 恢复未通过真机验证，只读展示 |
+| Pi | ✅ | ➖ | 恢复未通过真机验证，只读展示 |
+| Codex | ✅ | ➖ | 恢复需要目录信任决策，未授权验证，只读展示 |
+| Claude Code | ⚠️ | ➖ | 实验性检测，本机无数据时不产生虚假记录 |
+
+## 安装
+
+要求：Python ≥ 3.10，Linux（inotify 实时监控为 Linux 特性，其余平台自动退化为轮询）。**零第三方运行时依赖**，纯标准库。
+
+```bash
+pip install session-trail
+```
+
+或从源码安装：
+
+```bash
+git clone https://github.com/fwt11/agent_trail.git
+cd agent_trail
+pip install .
+```
+
+## 使用
+
+```bash
+agent-trail scan      # 扫描一次，输出各来源状态与记录数
+agent-trail list      # 以 JSON Lines 输出全部会话元数据
+agent-trail serve     # 启动本地控制台（默认自动打开浏览器）
+agent-trail tray      # 系统托盘形态（Linux，见下）
+```
+
+`serve` 常用选项：
+
+```bash
+agent-trail serve --port 8731        # 固定端口（默认随机）
+agent-trail serve --no-browser       # 不自动打开浏览器
+agent-trail serve --no-watch         # 禁用 inotify，只用定时轮询
+agent-trail serve --interval 30      # 轮询间隔（watch 健康时自动降为 5 分钟安全网）
+```
+
+启动后控制台 URL 带一次性高熵访问令牌（如 `http://127.0.0.1:8731/?key=…`）；令牌保存在浏览器 sessionStorage，后续请求通过请求头携带，所有 API 都会校验。手动刷新按钮立即触发一次扫描。
+
+## 桌面托盘（Linux）
+
+`serve` 之外还有系统托盘形态，已整合为子命令：内嵌窗口展示控制台，托盘菜单提供打开控制台、立即刷新、启动/停止服务、开机自启和退出。
+
+```bash
+agent-trail tray             # 启动托盘（自动拉起 agent-trail serve）
+agent-trail tray --show      # 启动同时打开控制台窗口
+agent-trail tray --install   # 写入应用菜单入口；--uninstall 反向清理
+```
+
+托盘壳本身不依赖任何第三方 pip 包，但需要 GTK 的 GI 绑定（系统 Python 通常自带）。`agent-trail tray` 在当前解释器缺 GI 绑定时会自动改用带绑定的系统 Python 重执行（例如 pip 装在 venv 里、托盘跑在系统 Python），无需任何手动操作；实在找不到时按提示安装：
+
+```bash
+# Debian/Ubuntu/deepin 系
+sudo apt install python3-gi gir1.2-webkit2-4.1
+```
+
+托盘以子进程方式管理 `agent-trail serve`（可用环境变量 `AGENT_TRAIL_BIN` 覆盖可执行文件路径），服务异常退出自动重启（退避重试，连续失败后停在可手动启动的状态）。窗口直接关闭只是隐藏，退出走托盘菜单；flock 单实例锁防止重复启动。
+
+托盘图标走原生 StatusNotifierItem/DBusMenu 协议（`agent_trail/tray/sni.py`，Gio 实现——libayatana 在 Deepin 23 的托盘守护上不工作，详见源码注释）。内嵌 WebView 默认使用软件合成（`WEBKIT_DISABLE_DMABUF_RENDERER` / `WEBKIT_DISABLE_COMPOSITING_MODE`，可用同名环境变量覆盖），避免在无 DRM 权限的会话里出现空白窗口。`serve` 的所有命令行形态保持不变，无托盘环境（SSH/无桌面）不受影响。
+
+## 工作原理
+
+```
+各 Agent 本地数据                本工具                        呈现
+─────────────────      ─────────────────────────      ─────────────────
+JSONL / JSON / SQLite ─▶ 适配器（9 种，只读） ─▶ 元数据索引    ─▶ 本地网页时间线
+  ~/.kimi-code/…          规范化为统一模型      (SQLite)      127.0.0.1 + 令牌
+  ~/.zcode/…              指纹增量去重                        筛选 / 详情 / 恢复
+  ~/.codex/…              inotify 事件触发重扫
+```
+
+- **适配器契约**：每个 Agent 一个适配器，实现发现（discover）、扫描（scan）、状态（status）、恢复计划（resume_plan）四个边界；数据源格式变化时报告不兼容而不是猜测
+- **增量扫描**：以源路径、大小、mtime 和适配器版本计算指纹，未变化的来源毫秒级跳过
+- **实时监控**：`watcher.py` 用 ctypes 直接调 libc inotify（保持零依赖），目录级 watch 覆盖原子替换与 WAL sidecar 变化；去抖 + 最小间隔合并高频写入
+- **恢复安全**：恢复命令来自适配器白名单参数数组，不经过 shell；API 只接受会话标识，服务端重新查库生成计划，调用者无法注入命令或目录
+- **源数据只读**：SQLite 源以 `mode=ro` 打开，禁止任何写事务；源记录删除后保留最后元数据并标记"源已缺失"、禁用恢复
+
+## 隐私与安全
+
+- 明确不读取各工具的 credentials、auth、token、密钥类文件
+- 本地索引与日志不保存消息正文、代码、命令、diff、附件或凭据
+- HTTP 仅绑定回环地址；刷新与恢复使用 POST 并校验 Origin，防止外部网页诱导本机服务执行动作
+- 网页不加载任何第三方脚本、字体或统计
+
+## 已知限制
+
+- 元数据优先：部分会话只有"未命名会话"，以目录和时间辅助识别；不读取首条用户消息补标题
+- 适配器基于当前各工具的本机数据格式，工具升级后可能需要更新
+- "回到工作现场"指原 Agent 会话与目录，不保证恢复未保存的文件或桌面布局
+
+## 开发文档
+
+- [设计文档](docs/design.md)
+- [实施计划](docs/implementation-plan.md)
+
+## 许可证
+
+[MIT](LICENSE)

session_trail-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "session-trail"
+version = "0.2.0"
+description = "Local cross-agent work timeline: discover, browse and resume coding-agent sessions on your machine"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "fwt11" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["ai-agents", "coding-agent", "timeline", "session-management", "local-first", "tray", "systray"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Environment :: X11 Applications",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+]
+
+[project.urls]
+Homepage = "https://github.com/fwt11/agent_trail"
+Repository = "https://github.com/fwt11/agent_trail"
+Issues = "https://github.com/fwt11/agent_trail/issues"
+
+[project.scripts]
+agent-trail = "agent_trail.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+agent_trail = ["static/*", "tray/*.png", "tray/*.template"]

session_trail-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

session_trail-0.2.0/src/agent_trail/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

session_trail-0.2.0/src/agent_trail/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

session_trail-0.2.0/src/agent_trail/adapters/__init__.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+from .base import BaseAdapter
+from .claude_code import ClaudeCodeAdapter
+from .codebuddy import CodeBuddyAdapter
+from .codex import CodexAdapter
+from .deepseek_harness import DeepSeekHarnessAdapter
+from .kimi_code import KimiCodeAdapter
+from .minimax_code import MiniMaxCodeAdapter
+from .opencode import OpenCodeAdapter
+from .pi import PiAdapter
+from .zcode import ZCodeAdapter
+
+
+def default_adapters(home: Path) -> list[BaseAdapter]:
+    return [
+        KimiCodeAdapter(home),
+        CodeBuddyAdapter(home),
+        PiAdapter(home),
+        DeepSeekHarnessAdapter(home),
+        MiniMaxCodeAdapter(home),
+        ZCodeAdapter(home),
+        OpenCodeAdapter(home),
+        CodexAdapter(home),
+        ClaudeCodeAdapter(home),
+    ]

session_trail-0.2.0/src/agent_trail/adapters/base.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from pathlib import Path
+
+from ..models import ActivitySession, AdapterStatus, ResumePlan, ScanResult
+
+
+class BaseAdapter(ABC):
+    source: str
+    adapter_version: int = 1
+
+    def __init__(self, home: Path) -> None:
+        self.home = home
+        self._status = AdapterStatus(source=self.source, kind="unavailable")
+
+    @abstractmethod
+    def discover(self) -> AdapterStatus:
+        raise NotImplementedError
+
+    def status(self) -> AdapterStatus:
+        return self._status
+
+    def watch_roots(self) -> list[tuple[Path, bool]]:
+        """Directories to watch for change notifications as (path, recursive).
+
+        Defaults to no watching; adapters that read files should return the
+        directories that contain their sources so misses degrade to polling.
+        """
+        return []
+
+    @abstractmethod
+    def scan(self, previous_fingerprint: str | None, now: datetime) -> ScanResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def resume_plan(self, session: ActivitySession) -> ResumePlan:
+        raise NotImplementedError

session_trail-0.2.0/src/agent_trail/adapters/claude_code.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from ..models import ActivitySession, AdapterStatus, ResumePlan, ScanResult
+from .base import BaseAdapter
+from .jsonl_utils import fingerprint_paths
+
+
+class ClaudeCodeAdapter(BaseAdapter):
+    source = "claude-code"
+    adapter_version = 1
+
+    @property
+    def root(self) -> Path:
+        return self.home / ".claude" / "projects"
+
+    def discover(self) -> AdapterStatus:
+        if not self.root.is_dir():
+            return AdapterStatus(source=self.source, kind="unavailable")
+        return AdapterStatus(
+            source=self.source,
+            kind="experimental",
+            message="session metadata format has not been verified",
+        )
+
+    def scan(self, previous_fingerprint: str | None, now: datetime) -> ScanResult:
+        discovery = self.discover()
+        if discovery.kind == "unavailable":
+            return ScanResult(discovery, None, [], True)
+        fingerprint = fingerprint_paths([], self.adapter_version)
+        return ScanResult(discovery, fingerprint, [], fingerprint != previous_fingerprint)
+
+    def resume_plan(self, session: ActivitySession) -> ResumePlan:
+        return ResumePlan(
+            kind="none",
+            workdir=session.workdir,
+            reason="Claude Code resume has not been verified",
+        )