find-my-session

find-my-session

🌐 中文说明

面向编码 Agent 的本地只读会话查找与交接工具，提供两种形式，共用一个 fms_lib 核心：

• find-my-session-skill — 一个 Agent 技能（fms CLI），可跨不同运行框架查找合适的会话，并输出低 token 消耗的交接摘要，而非完整对话记录。
• find-my-session-ui — 面向用户的浏览器面板，可查看相同的存储数据。

当运行框架的额度用完时，你通常记得自己在做什么，却不记得会话在哪里。fms 用一条简洁的命令帮你找到它。

截图使用的是合成测试数据。

向你的 Agent 提问

安装技能后，只需使用自然语言与 Agent 对话，无需提供 fms 参数：

• /find-my-session 找到 claude-code 最近的一个会话，继续那个任务
• /find-my-session find the most recent claude-code session and continue that task
• /find-my-session 额度用完了，在 claude-code 里找昨天关于鉴权的那次会话并接力
• /find-my-session search my claude-code sessions about token refresh and show the handoff digest
• /find-my-session 列出这个项目最近一次 claude-code 会话里我提过的所有需求

Agent 会确定运行框架，执行 search / latest / show / prompts，然后继续工作。

支持的运行框架

目前已有 21 个适配器，另有 2 个计划中。已验证的版本、运行环境和注意事项见兼容性矩阵；各运行框架的存储详情见 references/。

运行框架	引用前缀	存储位置
Qoder CN	qoder-cn	~/.qoder-cn
Qoder（国际版）	qoder	~/.qoder
Kimi Code	kimi-code	~/.kimi-code
ZCode	zcode	~/.zcode
CodeArts Agent	codearts-agent	~/.codeartsdoer
ChatGPT Codex	codex	~/.codex
DeepSeek Harness	deepseek	~/.dsh
Claude Code	claude-code	~/.claude
Cline	cline	~/.cline
Grok Build	grok-build	~/.grok
WorkBuddy AI	workbuddy	~/.workbuddy-ai
WorkBuddy（国内版）	workbuddy-cn	~/.workbuddy
Antigravity	antigravity	~/.gemini/antigravity
Antigravity CLI	antigravity-cli	~/.gemini/antigravity-cli
MiniMax Code	minimax-code	~/.minimax/v2
Cursor	cursor	~/.cursor/projects
OpenCode	opencode	~/.local/share/opencode
Gemini CLI	gemini-cli	~/.gemini
Qwen Code	qwen	~/.qwen
Pi	pi	~/.pi/agent/sessions
Oh My Pi	omp	~/.omp/agent/sessions
CodeBuddy	codebuddy（计划中）	~/.codebuddy
Cline（VS Code 扩展）	cline-vscode（计划中）	VS Code globalStorage

要求

• Python 3.9 或更高版本；macOS 或 Linux。Python 3.9 已停止上游维护，计划在 0.2 版本中要求 Python 3.10+（见 ROADMAP.md）。
• 无需第三方 Python 软件包
• 压缩存储（codex .jsonl.zst、deepseek .zstd）需要 zstd 解码器：Python 3.14+ 或 zstd CLI；否则将跳过这些会话
• Windows 由一个实验性的非阻塞 CI 作业进行测试，但目前尚不支持；见 ROADMAP.md

安装

CLI 和 UI 命令

pipx install find-my-session 会从 PyPI 安装 fms 和 fms-ui 命令。若要运行尚未发布的提交，请改为从 Git 安装：pipx install git+https://github.com/SomeNoneAI/find-my-session.git。使用 pipx upgrade find-my-session 升级，或使用 pipx uninstall find-my-session 卸载。使用 uv 时，uvx --from find-my-session fms ... 可运行 PyPI 发行版，无需永久安装。

面向 Agent：技能

1. 发行版 ZIP。 每个 GitHub Release 都会发布 find-my-session-skill.zip。从最新发行版下载，然后将其安装到你的运行环境中（例如，将其解压到 Claude Code 的 ~/.claude/skills，或将目录链接到运行环境的技能文件夹）。

2. 源代码检出。

   git clone https://github.com/SomeNoneAI/find-my-session.git
   cd find-my-session
   ln -s "$PWD/skills/find-my-session" ~/.claude/skills/find-my-session   # Claude Code; adapt the path for your harness
   

   从检出目录中，你也可以直接运行 CLI：python3 skills/find-my-session/scripts/fms，或者运行 python3 tools/build_artifacts.py 来自行构建 dist/find-my-session-skill.zip。若要移除已链接的技能，请从运行环境的技能文件夹中删除其符号链接。

面向用户：UI 面板

1. 发行版 ZIP。 从最新发行版下载 find-my-session-ui.zip，解压后在解压目录中运行 python3 fms-ui（如果解压工具保留了可执行权限，也可以运行 ./fms-ui）。替换该目录即可升级，删除该目录即可卸载。
2. pipx。 上述 pipx 安装方式也会提供 fms-ui 命令。
3. 源代码检出。 运行 fms_ui/fms-ui（使用 --no-browser --port 8765 可指定端口且不打开浏览器）。

面板会在 127.0.0.1 上启动一个只读服务，提供关键词和元数据筛选、会话概览、分页显示的用户提示词、最近轮次以及可复制的引用。静态前端仅使用同源 JSON API，不依赖 Node.js 或外部资源。界面语言跟随本地系统设置，也可以明确切换 zh/en。界面还会跟随系统的浅色／深色偏好，提供手动切换功能，并采用非纯黑的深色调色板。前端使用 Vue 3 + TypeScript + Vite 构建；仅在从 fms_ui/frontend/ 目录开发时需要 Node.js，运行面板则不需要。

快速开始

fms harnesses                                     # list ready and planned harnesses
fms search "quota handoff" --harness claude-code  # find sessions by keywords
fms latest --harness claude-code --cwd .          # most recent session in this repo
fms show claude-code:c1a0de01                     # low-token handoff digest
fms prompts claude-code:c1a0de01 --count          # count human prompts, then page with --limit/--offset
fms resume claude-code:e1a2b3c4 --exec            # jump straight back into a session
fms stats --since 7d                              # token/cost totals across harnesses

搜索时优先使用明确指定的 --harness；省略查询即可列出最近的会话。除非传入 --include-archived，否则 search／latest 不会包含已归档的会话。show 始终为只读操作，并会打印原始源文件路径，以便在摘要信息不足时让 Agent 搜索原文件。

命令

命令	用途
fms harnesses	列出已就绪和计划中的运行环境、变体及存储位置。
fms search [query ...]	按关键词搜索会话元数据；省略查询即可列出最近的会话。
fms latest	返回最近的匹配会话。
fms show <ref>	打印单个会话的交接摘要。
fms prompts <ref>	列出单个会话中的所有用户提示词；可统计数量、分页和排序。
fms mcp	通过 stdio 运行 Model Context Protocol 服务：为原生支持 MCP 的宿主提供只读 MCP 工具，包括 search/show/prompts/stats/doctor。参见 docs/mcp.md。
fms stats [--harness] [--since] [--json]	汇总各运行环境自行记录的 token／成本用量；未记录用量的运行环境显示 -。
fms resume <ref> [--exec]	打印（或运行）重新打开会话的运行环境命令；未验证恢复命令时，会回退为交接摘要。
fms doctor [--harness] [--json] [--fingerprint]	检查本地环境和存储位置（解码器可用性、根目录可读性、各运行环境的健康状况）；--fingerprint 会为漂移报告添加不含内容的结构摘要。

常用选项

选项	适用于	含义
--harness NAME[,NAME]	search、latest、show、prompts、doctor	将查找范围限制在某个 harness。建议使用，以提升速度和准确性。
--cwd PATH	search、latest	匹配工作目录包含 PATH 或被 PATH 包含的会话。
--since 7d / --since 2026-10-01	search、latest	按最后更新时间筛选。
--limit N	search、latest、prompts	限制结果或提示词数量；0 表示不限制。
--offset N	prompts	跳过前 N 个提示词。
--order oldest/newest	prompts	分页顺序；保留原始索引。
--count	prompts	仅打印提示词总数。
--deep	search、latest	同时扫描完整对话记录。速度较慢；仍只打印元数据。
--include-archived	search、latest	包含已归档的会话。默认关闭。
--verbose	search、latest	在 stderr 上警告已跳过的会话，不改变 stdout。
--messages N / --chars N / --summary-chars N	show	限制轮次数、每条消息的字符数和摘要字符数。
--json	harnesses、search、latest、prompts、doctor	输出机器可读内容；对于 show，使用 --format json。字段规范请参阅 docs/json-output.md。

会话引用使用 harness:session-prefix 格式（例如 claude-code:c1a0de01）；也可以使用受支持存储中的原始对话记录路径。

使用 fzf 进行选择

所有列表均为纯 TSV 格式，因此只需通过管道即可进行交互式选择：

fms search --limit 0 | fzf | cut -f1 | xargs -I{} fms show {}
fms search --limit 0 --include-archived | fzf --with-nth=2,4 | cut -f1 | xargs -I{} fms resume {}

第二个示例会在所选会话所属的 harness 中恢复该会话，前提是该 harness 有经过验证的恢复命令（参见 fms resume --help）。共用同一存储的桌面端／命令行界面共用一个引用空间——哪些界面已通过验证，请参阅兼容性矩阵。

隐私与安全

• 所有操作均在本地运行；CLI 不会发起网络请求。
• CLI 只读取会话文件和数据库，以只读方式打开 SQLite 存储；绝不会编辑或删除会话内容。
• 搜索输出仅包含元数据；show 和 prompts 可以打印对话内容，因此请像对待原始对话记录一样谨慎处理其输出。

开发与文档

• CONTRIBUTING.md — 环境设置、测试，以及如何添加或验证 harness。
• docs/compatibility.md — 各 harness 的详细兼容性矩阵。
• docs/json-output.md — --json 字段规范和 1.0 之前的稳定性政策。
• docs/faq.md — 5 分钟教程，以及最常见的“我的会话在哪里”问题解答。
• ROADMAP.md — 近期计划。
• SECURITY.md — 支持的版本和私密漏洞报告方式。
• skills/find-my-session/references/ — 各 harness 的存储架构和验证示例；如需添加 harness，请先阅读 extending.md。

python3 -m unittest discover -s tests -v
python3 -m compileall -q core fms_ui skills/find-my-session/scripts tools tests
python3 tools/build_artifacts.py   # rebuild dist/find-my-session-skill(.zip) and dist/find-my-session-ui(.zip)

许可证

MIT。请参阅 LICENSE。