Suvadu

让终端记忆一切。为你的 AI Agent 共享记忆。

Suvadu 用 SQLite 支持的存储取代你的 Shell 历史记录。每条命令都会附带结构化上下文——退出代码、耗时、目录、执行器和会话。AI Agent 可以通过 MCP 查询。100% 本地运行。

• 用数据衡量，而非空口断言——在一台 M4 Max 上测试 100,000 条记录：记录命令的 p95 耗时为 207 µs，对完整历史记录执行评测搜索的 p95 耗时为 0.05–15 ms。仅在一台机器上运行了一次——测试工具、数据集以及尚未测量的内容详见 BENCHMARKS.md
• AI Agent 跟踪——完整捕获 Claude Code、Codex、OpenCode 和 Cursor 的会话（Cursor 不包含 Token 用量）；记录 pi.dev 的命令和提示词；记录 Antigravity Agent 的命令；仅为 Windsurf、Aider、Continue 和 Copilot 添加命令标签（各层级具体提供的内容）
• 提示词探索器——追溯每条已记录的命令，查看触发它的提示词
• MCP 服务——**22 个只读工具、8 个资源和 6 个提示词，默认全部只读。**两个写入工具需启用后才能使用。支持 Agent 会话发现、项目上下文、失败经验学习、风险评估、共享技能库和已收藏的命令模板。可通过 suv settings 配置
• 100% 本地运行——无云服务、无遥测、无需账号。Suvadu 唯一主动发起的请求是每天检查一次是否有新版本，你可以关闭此功能。采用 MIT 许可证。

网站与文档： suvadu.sh · CLI 参考： suvadu.sh/cli · 博客： suvadu.sh/blog · 更新内容： CHANGELOG

---

安装

# Homebrew (macOS & Linux)
brew tap AppachiTech/suvadu && brew install suvadu

# Install script (macOS & Linux)
curl -fsSL https://downloads.appachi.tech/suvadu/install.sh | bash

# Install script, into ~/.local/bin without sudo
curl -fsSL https://downloads.appachi.tech/suvadu/install.sh | bash -s -- --user

# Cargo (Rust 1.95 or newer)
cargo install suvadu

安装脚本会将 suv 安装到 /usr/local/bin，只有该目录不可写时才会使用 sudo；--user 或 --dir DIR（或 SUVADU_INSTALL_DIR）可指定其他位置。重新运行脚本时，它会更新原位置由脚本安装的 suv——这类安装可通过脚本在其旁边创建的 suvadu 链接识别；如果没有任何变化，脚本不会下载任何内容，但仍会修复该链接。如果 PATH 中的 suv 来自 Homebrew 或 Cargo，脚本会停止并指出相应包管理器的更新命令；其他并非由它安装的 suv 则会保留不动，而使用 --user 或 --dir 会有意安装一个独立副本。 在终端中运行时，脚本会询问是否将下面的 shell 钩子添加到 ~/.zshrc（Linux 上为 ~/.bashrc）：它会先显示要添加的行，只有输入 y 才会写入，不会写入其他内容，会将文件副本保存为 .suvadu-backup，并且绝不会重复添加钩子。使用 --no-modify-rc 可关闭此提示。

然后添加 shell 钩子：

# Zsh
echo 'eval "$(suv init zsh)"' >> ~/.zshrc && source ~/.zshrc

# Bash
echo 'eval "$(suv init bash)"' >> ~/.bashrc && source ~/.bashrc

验证：suv status

每条命令都会记录其所在目录；如果位于 git 仓库中，还会记录命令开始时所在的分支（若 HEAD 分离，则记录短提交哈希）。分支信息直接从仓库文件中读取——不会在提示符处运行 git——并显示在 recall 的详情窗格中。更改目录的命令（例如 cd ../other）会归入输入该命令时所在的分支；切换分支的命令则会归入切换后的分支。可在 suv settings 中通过 Record Git Branch 关闭此功能，或设置 [shell] capture_git_branch = false。

保持更新。 Suvadu 每天会在后台查询最新的发行版本号（与 suv update 读取的 version.txt 相同）；如果有更新版本，会在你于终端运行命令前用一行提示，并显示与你安装方式对应的更新命令（brew upgrade suvadu、cargo install suvadu 或 suv update）。不会发送任何关于你或你的历史记录的信息。此功能不会在 shell 钩子、recall、脚本、管道或 CI 中运行。可在 suv settings 中通过 Check for Updates 关闭此功能，在 config.toml 中设置 [update] check = false，或设置 SUVADU_NO_UPDATE_CHECK=1。

上箭头键回溯

在 zsh 中，加载钩子后，按上箭头键和下箭头键即可回溯 Suvadu 中的命令，无需其他设置。上箭头键会先调出以当前输入内容开头的最新命令，然后按从新到旧的顺序调出更早的命令——只有在同一毫秒记录的命令之间，当前目录才会用于区分——下箭头键则会逐步返回到你输入的内容。回溯时只会显示你输入过的命令；按 Alt+A 也可显示该 shell 中 AI Agent 输入的命令。

• 关闭此功能： 在 suv settings 的 Shell 选项卡中关闭 Enable Arrow Key Navigation，或在 config.toml 中设置 [shell] enable_arrow_navigation = false。该设置会在新 shell 中生效（或运行 exec zsh 后生效）；此后，上下箭头键会使用 zsh 自带的功能，而 Alt+A 不受影响。
• Bash 暂不支持。 Bash 钩子只绑定 Ctrl+R；上下箭头键仍使用 Bash 自带的历史记录功能。
• 检查： bindkey '^[[A' 应输出 "^[[A" suvadu-up-arrow，而 bindkey '^[OA'（许多终端发送的序列）应输出 "^[OA" suvadu-up-arrow。
• 如果按上箭头键时由其他功能响应， 说明在 eval "$(suv init zsh)" 之后加载的插件重新绑定了该按键——oh-my-zsh 的按键绑定、zsh-history-substring-search、zsh-vi-mode、fzf 的按键绑定、atuin 和 mcfly 都会绑定上箭头键。请将 eval "$(suv init zsh)" 放在 ~/.zshrc 的最后，也就是插件管理器和插件之后，然后运行 exec zsh；诸如 ZSH_AUTOSUGGEST_STRATEGY 这样的普通设置仍可放在它后面。zsh-vi-mode 会在首次显示提示符时才绑定按键，因此还需在加载它之前设置 ZVM_INIT_MODE=sourcing。
• suv doctor 会报告此问题。 每个 zsh 会在首次显示提示符时检查一次——此时 ~/.zshrc 已全部运行完毕——钩子会检查上箭头键是否仍由 Suvadu 绑定，并记录接管该按键的内容；doctor 的 Up-arrow 行会指出对应的 widget 和修复方法。如果后续启动的 zsh 发现上箭头键再次由 Suvadu 绑定，则会移除该记录。此检查不会输出任何内容，每次启动 shell 的耗时约为 0.8 ms（见 BENCHMARKS.md）；关闭箭头键导航时则会跳过。

zsh-autosuggestions。 zsh 钩子提供了适用于 zsh-autosuggestions 的策略，可根据 上箭头键会回溯的命令提供建议——也就是以你输入内容开头的最新命令；除非按 Alt+A 将 AI Agent 命令显示出来，否则这些命令会被隐藏。在 ~/.zshrc 中启用该策略；如果 Suvadu 中没有匹配项，则回退到 zsh 自带的历史记录：

ZSH_AUTOSUGGEST_STRATEGY=(suvadu history)

每条建议都会进行一次 suv get 查询，与上箭头键执行的查询相同（耗时见 BENCHMARKS.md）。zsh-autosuggestions 0.7 默认会异步获取建议，因此输入时无需等待。

---

故障排除

no such file or directory 指向旧路径（例如 suv:8: no such file or directory: /opt/homebrew/bin/suv）——shell 钩子会在会话启动时记录 suv 二进制文件的绝对路径。如果你移动了该二进制文件——例如更换包管理器（如从 Homebrew 切换到 Cargo）、运行 brew unlink suvadu，或卸载后在其他位置重新安装——已经打开的 shell 仍会指向旧的、现已删除的路径。重新加载 shell 以获取新位置：

exec zsh    # or: exec bash

（或者直接打开一个新终端）。还要确保新位置（例如 ~/.cargo/bin）已加入 PATH。

按上箭头键显示的是 zsh 自带的历史记录，而不是 Suvadu 的记录——检查：运行 bindkey '^[[A' 或 bindkey '^[OA'，如果输出的 widget 不是 suvadu-up-arrow（例如 up-line-or-beginning-search 或 history-substring-search-up），且 suv doctor 的 Up-arrow 行说明了接管该按键的内容，就属于这种情况。原因：在钩子之后加载的插件重新绑定了该按键、箭头键导航已关闭（在 suv settings 中关闭了 Enable Arrow Key Navigation），或者当前 shell 是 Bash，其上箭头键会使用 Bash 自带的历史记录功能。修复方法：将 eval "$(suv init zsh)" 移到 ~/.zshrc 末尾并运行 exec zsh，或重新开启该设置。请参阅上箭头键回溯。

更多信息见 suvadu.sh/cli/shell-integration。

---

快速开始

suv                         # Home: find any feature by what you want to do (also suv home)
suv search                  # Interactive search TUI (also Ctrl+R)
suv history                 # Print last 25 commands (pipeable)
suv history --json -n 100   # Last 100 commands as JSONL
suv stats                   # Stats dashboard with heatmap
suv replay --after today    # Timeline of today's commands
suv sessions                # Browse shell and AI sessions together
suv doctor                  # Check installation health
suv agent dashboard         # Monitor AI agent activity
suv agent prompts           # Browse prompts and their commands
suv agent sessions          # List captured Codex/Claude sessions and reported tokens
suv skills                  # Interactive skills management (browse, add, edit, sync, review)
suv skills add my-skill     # Add a skill any MCP-capable agent can read
suv skills sync             # Materialize skills into Claude Code/Cursor/Codex
suv skills trust            # Trust this repo's .suvadu/skills/*.md so sync writes them
suv bookmarks get box --set host=db1   # Print a bookmark with its {{placeholders}} filled

仓库中的团队技能

将技能与代码放在一起提交，每个技能使用一个 Markdown 文件，存放在 .suvadu/skills/ 中：

---
name: release            # optional; defaults to the file name (release.md)
description: How we cut a release
triggers: [release, tag]
targets: [claude-code, codex]   # optional; default: every agent
---

1. Bump the version in Cargo.toml.
2. Tag, then push the tag.

每个克隆仓库的人都会获得这些技能，因此在你阅读之前，Suvadu 会将它们视为不可信：

suv skills list                 # repo skills show origin 'repo' and 'untrusted'
suv skills show release         # read one (its file path, trust, body)
suv skills trust --dry-run      # list this repository's skills and their state
suv skills trust                # trust them (or: suv skills trust release)
suv skills sync                 # from the repository root: writes them like project skills

• 项目是从你当前所在位置向上查找时，最近的包含 .suvadu/skills/ 文件夹的目录，但不会超出 Git 仓库的根目录。 仓库技能会从该目录同步到其中的 .claude/skills/、 .cursor/rules/ 和 AGENTS.md，位置与项目技能完全相同。
• 信任状态按文件记录，并通过内容哈希校验（为另一个检出目录执行 suv skills trust --repo PATH）。文件发生更改时——例如拉取更新之后——它会被标记为自信任后已更改：下次同步会停止写入该文件，并移除之前写入的副本，直到你再次信任它。suv skills untrust 会撤销信任，下次同步时会移除这些副本。
• Suvadu 从不编辑、移动或删除仓库技能文件：请直接编辑文件。在 suv skills 中，这些文件为只读并显示其路径；edit、rm 和 disable 会拒绝操作，并告知你要修改哪个文件。
• 受信任的仓库技能会取代同一项目中同名的库技能（也会在该项目中覆盖全局技能），同步时会说明这一点。不受信任的技能不会产生任何影响。
• 删除文件后，下次同步会移除其同步副本——仅限由 Suvadu 写入且此后未被任何人编辑的副本。
• 通过 MCP，list_skills、get_skill 和 search_skills 会包含 Agent 指定项目（scope）或服务运行所在项目中的仓库技能，并提供 source repo、文件路径和信任状态。对于不受信任或已更改的技能，只会列出名称和路径：在你信任它之前，不会提供其描述和正文。
• 如果文件名包含非字母、数字、- 和 _ 的字符、文件是符号链接、文件超过 256 KB、文件不是 UTF-8 编码、没有正文，或其 targets 指定了未知 Agent，则会跳过该文件并发出包含文件名的警告。

带占位符的书签

书签可以是模板：

suv bookmarks add "ssh {{user:root}}@{{host}} -p {{port:22}}" -l box
suv bookmarks                       # pick it: a popup asks for user, host, port
suv bookmarks get box --set host=db1   # prints: ssh root@db1 -p 22

• {{name}} 是占位符；{{name:default}} 会为其指定默认值（第一个 : 之后的所有内容都会原样保留）。名称必须以字母或 _ 开头，后续可包含字母、数字、_ 或 -；{{ name }} 也有效。
• 同一占位符出现多次时，只会询问一次，并在所有位置填入相同内容。
• \{{ 表示字面上的 {{。双大括号中的其他内容若不是占位符——例如 docker inspect -f 中的 {{.State.Status}}，或缺少 }} 的 {{——都会按原样保留。
• 值会原样插入：你输入的是 shell 语法，因此包含空格或 $ 的值需要按照 shell 的要求加引号。
• 在选择器弹窗中，按 Tab/Enter 移至下一个值；在最后一个值上按 Enter 会将填好的命令放到提示符中（不会执行）；按 Esc 返回列表。若有占位符未提供值或默认值，suv bookmarks get 会失败并显示这些占位符的名称。
• 填入的值不会保存。
• MCP list_snippets 工具会以只读方式列出你的书签及各书签的占位符和默认值，因此 Agent 可以使用 suv bookmarks get … --set … 填入占位符，而不必重新输入整个命令。

---

查找功能：suv

单独运行 suv（或运行 suv home）即可打开首页：这里按任务分类展示 Suvadu 的功能，并支持搜索： 查找命令、查看会话、整理命令、了解你的活动、查看 AI 活动、连接工具以及管理 Suvadu。输入内容即可搜索功能，而不是搜索历史记录；可以使用 failed、 backup、prompts 或 atuin 等词。每项功能都会说明其用途，以及对应的实际命令。

按 Enter 键会打开当前选中项，但绝不会在 Shell 中运行任何内容：

• 界面（设置、会话、统计信息、Agent 仪表板等）会像从 Shell 中打开时那样显示；按 Esc 键可返回原处。
• 选择器（搜索、书签）会显示你选中的命令，并提供 复制命令 按钮。命令不会运行；在 Shell 中按 Ctrl+R 仍然是将命令放入提示符的方式。
• 报告（状态、doctor、版本、历史记录、标签、Agent 报告）会在首页内显示。
• 任何会更改数据或 Shell 的操作——导入、删除、更新、暂停、Shell 设置——都会打开包含可复制示例的说明。

F1 会列出按键，F2 会打开命令参考，其中包含 suv --help 输出的概览以及每条命令各自的帮助。

如果希望直接运行 suv 时显示经典命令概览，请在 suv settings 中将 启动界面 设为 help，或在 config.toml 中进行设置：

[home]
startup = "help"   # or "home" (the default)
icons = "ascii"    # or "unicode" for the category markers

此设置仅读取你自己的配置文件——项目的 .suvadu.toml 无法更改它。脚本、管道和 TERM=dumb 始终会在标准错误输出中显示概览，退出状态码为 2，与之前相同，因此任何以非交互方式运行裸 suv 的操作都不会改变。无论设置为何，运行 suv home 都会打开首页，而 suv --help 始终会显示概览。

---

匹配与排序如何运作

匹配决定哪些命令符合条件，范围决定要在哪里查找，而排序只决定顺序。这是三个彼此独立的控制项，更改其中一项绝不会影响其他项的作用。

匹配——--match，或在搜索界面中按 ^X：

模式	规则
terms（默认）	每个以空格分隔的词都必须作为子字符串出现，顺序不限；如果没有结果，则忽略分隔符后再用相同的词进行匹配（见下文）
literal	整个查询必须与输入内容完全一致，包括空格和标点
prefix	命令必须以查询内容开头
fuzzy	查询中的字母必须按顺序出现在命令中，字母之间可有间隔（gco 可找到 git checkout）

多个词按 AND 关系组合，绝不按 OR 关系组合。没有引号语法，也绝不会删除标点，因此 git-push 是一个词。匹配不区分大小写。 terms 和 fuzzy 也会折叠 Unicode 大小写：ÉCHO 可找到 écho，σ 可找到 ΟΔΟΣ，而 straße 可找到 STRASSE。在 terms 模式下，这适用于包含非 ASCII 字母的词；以纯 ASCII 输入的词会在搜索索引中查找，而该索引只折叠 ASCII 大小写，因此 STRASSE 找不到 straße。fuzzy 会折叠所有查询内容的大小写。literal 和 prefix 通过 SQLite 的 LIKE 进行匹配，该操作只折叠 ASCII 大小写。没有针对特定语言的规则：土耳其语的 İ 会折叠为 i 加组合点，而无点的 ı 仍是独立字母。所有模式都会在数据库中缩小搜索范围，因此匹配项有多旧绝不会影响能否找到它。 分隔符——唯一的回退方式。 当 terms 查询在当前范围和筛选条件下毫无匹配结果时，系统会忽略分隔符后再次查询——从你的词语和命令中移除空格、-、_、.、/ 和 :。这样，hiveagent 就能找到 hive-agent、hive_agent、hive.agent、hive/agent 和 hive:agent，而 hive-agent 也能找到 hiveagent。每个词仍必须出现。结果标题会显示 ignoring punctuation (-_./:)，状态行会显示 Match terms (loose)，匹配到的文本（包括其中的分隔符）也会像往常一样标记。它绝不会与精确匹配混在一起：只要有任何内容与输入完全匹配，就只显示这些结果，因此计数和每一页的结果都遵循同一规则。literal、prefix 和 fuzzy 没有回退方式。MCP search_commands 工具也会对整个查询以相同方式回退，其响应会注明 no exact matches; showing matches ignoring punctuation (-_./:)。

范围——--scope、^P 循环切换、^R 重置：

范围	搜索内容
all（默认）	所有记录
directory	在恰好当前目录中运行的命令——不包括其子目录。--here 与此相同
workspace	在最近的上级 Git 仓库下任何位置运行的命令。关联工作树是独立的工作区；嵌套仓库优先于其父级
session	当前 shell 会话中的命令

无法在当前环境中应用的范围（没有仓库、没有会话）会在 stderr 上说明原因，并明确回退；绝不会静默扩大范围。

排序——terms 和 fuzzy 会按匹配程度排列结果：完整查询前缀优先，其次是连续子串，再其次是按查询顺序出现的各个词，最后是按任意顺序出现的各个词。匹配层级始终优先：任何后续因素都不会让命令排在文本匹配更接近的命令之前。 在同一层级内，由一个分数决定排序。该分数是模糊匹配分数，并根据命令长度以及命令是由你而非 Agent 输入进行调整；在智能排序中（^S、search.context_boost，默认开启），还会乘以：

• 当前目录：命令是否恰好在当前目录中运行过 （search.cwd_boost_percent）；
• 频次与近期性：你运行过该确切命令的次数，以及最近一次运行的时间。第一次运行后的首小时内，每次计 16；当天计 8；三天内计 4；一周内计 1；一个月内计 0.5；此后计 0.25。加成是 1 加上总和的四次方根，因此，两天前运行过二十次（×3.0）的命令会排在五分钟前运行过一次（×2.0）的命令之前，但不会让后者难以找到。MCP suggest_next 工具也按相同定义排序；
• 运行结果：如果一条命令通常会失败——至少运行过三次且已知退出状态的记录中，失败次数超过一半——其分数就会降低；如果它从未成功过，分数会降至四分之一。多次成功中夹杂一次失败不会造成影响，而通过 Ctrl+C 停止的运行（退出码 130）不算失败；
• 序列：在当前 shell 中运行完刚才那条命令后，你通常会接着运行什么。Recall 会查看历史中最近 500 次运行该命令的记录，并对每条记录检查同一会话中 10 分钟内记录的下一条命令。某条命令在其中至少出现两次，就会获得最高 ×3 的加成；加成幅度取决于它成为下一条命令的频率——因此，在 git add -A 之后，git commit 会排在你更常运行的 git status 之前。此功能需要 shell 会话（由 shell hook 设置的 $SUVADU_SESSION_ID），并且可通过 search.sequence_boost = false（suv settings 中的 Sequence Boost）单独关闭此加成。

频次与近期性、运行结果和序列都会计入历史中该确切文本的每次运行，而不只是匹配到的运行；只有在显示 Agent 命令时，Agent 的运行记录才会计入。平分时，优先选择由用户交互输入的命令，然后选择最新的命令（Executions）或运行次数最多的命令（Commands）。近期排序（再次按 ^S）不计入这四项加成：同一层级内只看模糊匹配分数和人工输入加成，然后使用相同的平分规则。literal、prefix 和空查询完全不会重新排序：这些结果始终按最新优先返回。 最多会对 5,000 条匹配结果进行排序。这限制的是排序处理量，而不是搜索的历史记录量，也不限制你可以访问的结果：匹配和计数都在数据库中完成，因此结果数量是实际匹配数，而且每一页都可以打开。超过排序窗口的页面会按时间倒序显示——只根据部分结果集计算出的相关性顺序，在那里将毫无依据。

输入时绝不会等待搜索。 每次查询都会在后台线程中运行，并使用独立的只读连接。按键改变查询时，仍在运行的搜索会被放弃——SQLite 会在扫描过程中将其停止——而针对旧查询返回的结果会被丢弃。Enter、方向键以及所有其他会对结果执行操作的按键，都会先等待当前输入内容对应的结果，因此你接受的内容始终与屏幕上的查询相符；在结果到达之前，结果标题会显示 searching…。

浏览列表。 查询匹配的字符会在每一行中加上下划线并突出显示，覆盖常规语法颜色，让你一眼看出命令为何匹配。Recall 默认打开 Commands 视图，相同的命令会合并为一行，显示命令最近一次运行的时间以及匹配的运行次数，因此运行过五十次的命令不会把其他候选项都挤出屏幕。^U 可切换到 Executions 视图——显示每次记录的运行及其时间、目录和结果——并可切换回来；结果标题会标明当前视图以及对应单位的计数，切换视图时仍会选中原先的命令。如要默认打开 Executions 视图，请设置 search.show_unique_by_default = false（或在 suv settings 中关闭 Start in Commands View）。对于列表中太长而无法完整显示的行，末尾会显示 …；选中行则会自动换行，以便完整显示。

只有文本完全相同的命令才会归为一组，因此原本不可见的空白也会显示出来：· 表示开头或结尾的空格，↵ 和 ⇥ 分别表示换行和制表符。如果命令中含有无法从屏幕上直接看出的内容——例如制表符、零宽空格、方向覆盖字符——详情窗格会额外显示其转义后的 Raw 形式。按 ^V 可打开任意命令的原始视图，无论内容多长都能滚动查看：每个空格都显示为 ·，每个隐藏字符都会转义，每个换行符都会单独占一行，并显示精确长度。

按 Enter 会将命令放到提示符处（在 suv search 中则会打印出来）——绝不会运行任何内容。页脚仅显示最常用的按键；按 ? 可查看所有快捷键。

向上/向下方向键召回是另一种更简单的方式：前缀匹配、按时间倒序、不去重；对于同一毫秒内记录的命令，仅在排序相同的情况下才使用当前目录进行区分——请参阅方向键向上召回。

suv search --compact 会将相同的界面以内嵌形式显示在提示符下方，而不是占满整个屏幕，因此你正在阅读的输出仍会保留在屏幕上。

让选择成为默认设置。 search.match_mode、search.scope 和 search.compact 可为每次召回设置默认选项。你可以在 suv settings 的 Search 选项卡中设置（Default Match Mode、Starting Scope、Compact Recall），也可以在 config.toml 的 [search] 部分中设置；该文件位于数据存储中列出的配置目录下。从 suv settings 保存时，文件中的其他所有键都会保留，包括无法识别的键。这三项的默认行为均与早期版本一致。

---

导入你已有的历史记录

suv import --from bash-history --dry-run ~/.bash_history   # preview counts, writes nothing
suv import --from bash-history ~/.bash_history             # import
suv import --from zsh-history ~/.zsh_history               # zsh equivalent

输入文件只会被读取，绝不会被修改；重复运行同一导入不会添加任何内容，而文件中确实重复执行的命令都会保留。 两个导入器都会像实时记录一样，严格应用你的脱敏和排除模式，并报告排除和脱敏的数量，不会回显任何命令文本。两者都不会预先备份你的 Suvadu 数据库——只有 Atuin 导入器会这样做；如果需要备份，请自行运行 suv backup。

Bash 历史文件能提供和无法提供的信息：

字段	是否导入
命令文本	是——会像实时记录一样应用脱敏和你的排除模式
时间戳	仅当运行命令时设置了 HISTTIMEFORMAT（#<epoch> 行）才会导入。否则会明确使用合成的 1970-01-01 占位时间——绝不会编造时间
多行命令	在带时间戳的文件中重建（#<epoch> 行是记录边界）。普通文件没有边界，因此每行都会作为单独的命令导入
目录、退出代码、持续时间、执行者	文件中不包含——会存储为未知，绝不会猜测，也绝不会记录为成功退出

从 Atuin 导入

suv import --from atuin-db --dry-run ~/.local/share/atuin/history.db   # preview, writes nothing
suv import --from atuin-db ~/.local/share/atuin/history.db             # import

Atuin 数据库以只读方式打开——Suvadu 绝不会写入该数据库，也绝不会绕过 SQLite 复制文件；它会在一个事务中读取完整历史记录，因此运行中的 Atuin 可以继续记录。写入前，Suvadu 会为自己的数据库创建一致性备份，并打印用于还原的 cp 命令；写入后会验证 Atuin 文件是否逐字节保持不变，以及声称已写入的条目是否确实存在。重复运行导入不会添加任何内容。

已针对 Atuin 18.0.0 – 18.23.0 进行测试（历史记录架构 20210422143411 – 20260818000000）；测试 18.23.0 时，导入的是由真正的 Atuin 18.23.0 二进制文件写入的数据库，测试脚本为 scripts/test-atuin-import.sh。如果数据库包含本版本尚未测试过的迁移，则会报告迁移 ID 并拒绝导入，而不会猜测——请运行 suv update 后重试。

Atuin 字段	导入为
command	命令文本，原样保留（保留多行内容和 Unicode）。会像实时记录一样应用脱敏和你的排除模式——根据 Atuin 记录该行时所在的目录解析，因此项目中的 .suvadu.toml 也会影响导入的历史记录
timestamp（纳秒）	started_at，截断到毫秒，仅此而已。同一毫秒内的两次运行会保留相同的 started_at，并作为独立条目保留：一行由其 Atuin id 标识，绝不会由时间标识
duration（纳秒）	duration_ms / ended_at，截断到毫秒。Atuin 的 -1（“从未完成”）会存储为未知，而不是零耗时
exit	exit_code。Atuin 的 -1 会变为 NULL——绝不会伪造成功
cwd	目录。空值或 Atuin 的字面值 "unknown" 会变为未知
session	每个 Atuin 会话对应一个 Suvadu 会话，ID 为 atuin-<session>
hostname（host:user）	会话主机名，以及条目上下文中的 atuin_user
author、author_kind	executor 和 executor_type（1→human，2→agent）。未声明类型时保持为 unknown：Atuin 会根据已知的作者名称猜测“agent”，而 Suvadu 只记录明确声明的内容
id、intent、shell	保留在条目的 context 中（atuin_id、atuin_intent、atuin_shell）——Suvadu 没有对应列。atuin_id 也用于确保重新导入时不执行任何操作。自由文本字段会像命令一样应用脱敏和排除规则；被排除规则匹配的字段会被隐藏，并列入 context.withheld_fields
deleted_at	跳过并统计你在 Atuin 中删除的行，绝不会恢复
—	亚毫秒精度会丢失（行会保留；仅丢失同一毫秒内的排序精度）。Atuin 没有可供迁移的标签、备注或命令输出；Suvadu 不会保留任何 Atuin 同步或记录存储状态

---

AI Agent 设置

suv init claude-code    # Claude Code — commands, sessions, tokens + MCP
suv init codex          # Codex — commands, sessions, tokens + MCP
suv init cursor         # Cursor — commands, sessions (no tokens) + MCP
suv init opencode       # OpenCode — plugin + full session capture (commands, sessions, tokens)
suv init pi             # pi.dev — extension + prompt capture
suv init antigravity    # Antigravity — agent commands (via ~/.zshenv)

设置完成后，请重新启动已配置的 Agent。对于任一 VS Code 扩展，请完全退出并重新打开 VS Code。Codex 还要求在出现提示时审核并信任 Suvadu hooks（或通过 /hooks 操作）。两个安装程序都会保留无关的 hooks，并配置 Suvadu MCP 服务；Codex 会在修改现有 hooks.json 前先备份，并在设置了 CODEX_HOME 时使用它。

各 Agent 实际提供的功能

有三种不同的功能都被称为“AI Agent 支持”。你获得的是以下哪一种：

Agent	suv init	命令	提示词	原生会话时间线	测试环境
Claude Code	claude-code	是（hooks）	是	是	未固定版本 — 请参阅下方注意事项
Codex	codex	是（hooks）	是	是	CLI 0.153.4
OpenCode	opencode	是（插件）	是	是	CLI 1.18.30
Cursor	cursor	是（hooks）	是	是 — 提示词、最终回复和轮次结束；不含 token 用量	未固定版本
pi.dev	pi	是（扩展）	是（扩展将其限制为 500 个字符）	否	未固定版本
Antigravity	antigravity	是（~/.zshenv 捕获脚本）	否	否	使用 zsh 5.9 的 Antigravity IDE 2.5.5
Windsurf、Aider、Continue、Copilot	—	通过 shell hook	否	否	—

最后一行是命令标记，而非集成：shell hook 会识别这些工具设置的环境变量，并为命令标注正确的执行器。无需安装任何内容，也不会捕获提示词。

Antigravity 的 Agent 会从其语言服务器启动每条命令，执行方式为 zsh -c '<command>'。该 shell 不会读取 ~/.zshrc，因此 shell hook 无法检测到它。suv init antigravity 会将捕获脚本写入 ~/.config/suvadu/hooks/antigravity-zsh.sh，并在 ~/.zshenv（若设置了 $ZDOTDIR，则为 $ZDOTDIR/.zshenv）中添加带标记的代码块，同时将原文件备份为 .zshenv.suvadu-backup-<id>。只有在非交互式 zsh 中运行 -c 命令且设置了 $ANTIGRAVITY_AGENT 时，该代码块才会引入脚本；其他所有 shell 都会跳过它。每条 Agent 命令都会在其 shell 退出时记录，包含退出代码、耗时和目录，并按每次 Antigravity 运行创建一个会话（antigravity-<pid>）。此功能仅适用于 zsh。Antigravity 通过 exec 启动的命令，或被信号终止的命令，不会被记录。为让 shell 等待命令结束并记录命令，该脚本会设置一个无操作的 EXIT trap；但在这些 shell 中，这会替换此前在 ~/.zshenv 中设置的 EXIT trap。suv uninstall 会移除该代码块。

上文只有 Codex 和 OpenCode 的版本是 Suvadu 实际测试过的版本；运行时不会强制检查这些版本，Atuin 导入除外，因为 Atuin 导入确实会检查架构。如果某个 Agent 更改了其 hook 或插件契约，捕获功能可能会无声地退化 — suv doctor 会按 Agent 报告是否检测到其进程、是否安装了集成，以及是否检测到命令、原生会话和 MCP 注册。

失败原因：失败输出（可选启用）

启用 [capture] failure_output = true（suv settings 中的 保留失败输出；默认关闭）后，失败的命令会保留其输出的最后 4 KB —— 前提是 Suvadu 已有该输出：

路径	保留的输出
Claude Code	PostToolUseFailure 错误文本，不含其 Exit code N 行
Cursor	afterShellExecution 的 output
Codex	PostToolUse 响应的 output、aggregated_output 或 stdout/stderr 文本，但响应中也必须包含退出代码
OpenCode	由插件发送的 bash 工具输出（重新运行 suv init opencode）
suv wrap -- cmd	命令的 stderr，运行时原样传递到你的终端
zsh 和 Bash hooks	不保留任何内容 —— 捕获终端输出意味着要介于程序和终端之间，这会破坏交互式程序

Recall 的详情面板会在失败的命令下方显示这些内容（较长内容可按 Shift+Tab 滚动）；MCP 的 what_failed、command_status 和 learn_from_failures 工具，以及 failures/recent 资源，会显示其最后三行（设置 detail=true 时会显示全部内容），并标记为命令自身的文本，而非指令；如果没有这些内容，它们会明确说明未知命令失败的原因。

转义码和进度重绘内容会被剔除，机密信息会按照与命令相同的规则和目录级策略进行脱敏（在截取文本之前）；被排除的命令不会保留任何内容；项目的 .suvadu.toml 可以关闭此功能，但不能启用它。使用 suv wrap 时，命令的 stderr 是管道，因此只在终端上启用颜色或动画的程序会以纯文本形式输出；该命令启动并遗留在后台运行的进程，则会在 suv wrap 退出后失去 stderr。删除命令时，输出会随命令一并通过 suv delete 删除；它也会包含在 JSON 和 JSONL 导出文件中；suv gc --failure-output 会删除所有失败输出，但保留命令。

“上次失败时，你用……修复了它”

对于失败的命令，Recall 的详情面板会显示之前修复它的方法 —— 上次失败时，你用这个修复了它：git status（3×） —— MCP 的 what_failed 和 learn_from_failures 工具则会添加一行 fixed before (inferred)。不会为此记录任何新内容：需要时会从你的历史记录中推断，数据范围是该命令最近 50 次失败（退出状态不为 0，或 Ctrl+C 的退出状态为 130）。每次失败后，Suvadu 会检查同一会话接下来的 20 条命令，这些命令必须在 15 分钟内启动，且位于同一目录；其他失败命令会被跳过：

• 与失败命令相似的成功命令就是修复方法 —— 相同程序且第一个非标记参数相同（cargo build → cargo build --release），或对命令行做了小幅修改（gti status → git status，每八个字符最多修改一处）；
• 如果随后再次运行原失败命令且未作修改，那么此前通过的设置步骤就是修复方法 —— 相同程序（npm test 之前运行的 npm install），或安装软件包（you fixed it with: npm install, then reran it）；如果没有设置步骤，则表示原样重新运行后成功；
• 中间用于查看情况的命令（cd、ls、cat、git status/diff/log/show、编辑器）会被跳过；其他任何成功命令都会终止搜索，且不记录修复方法。

修复方法会在这些失败记录中累计计数，并显示最常见的一种。这是根据后续运行的命令推断出来的，并非观察到的原因。在包含 100,000 条命令的历史记录中，每次查找耗时不到一毫秒（BENCHMARKS.md）；Recall 会对每条选中的失败命令查找一次。

有哪些变化：Agent Git 快照

当 Claude Code、Codex、OpenCode 或 Cursor 会话在 Git 仓库中工作时，Suvadu 会在会话的第一个提示词发出时，以及每轮结束时获取一次 Git 快照（Claude Code 和 Codex 的 UserPromptSubmit 与 Stop/SessionEnd；OpenCode 的提示词发出时和 session.idle）：记录检出的提交和分支，以及 git status 报告为已暂存、未暂存、未跟踪、已重命名、已删除或存在冲突的路径。**仅记录路径，不记录文件内容，也不记录差异。**保留第一份快照；每轮结束时替换最后一份，因此一个会话最多保留两份。

• git 仅在这些时刻运行，不会针对每条命令运行；运行的命令为 git --no-optional-locks status --porcelain=v2 --branch -z，并关闭 core.fsmonitor，因此不会在 Agent 使用索引时锁定索引，仓库自身的配置也无法让它运行程序。超时时间为 2 秒；如果运行较慢、PATH 中找不到 git，或目录不属于任何仓库，则不会记录任何内容，Agent 的钩子会继续运行。在仓库之外，不会启动 git 进程。在包含 10,000 个文件的仓库中，快照会让获取快照的钩子额外耗时约 30–35 毫秒，几乎全部用于 git status（Apple M4 Max；参见 BENCHMARKS.md）；后续提示词额外耗时不到 1 毫秒。
• 与 exclusions 匹配的路径会被排除（并计数）；其余路径和分支名会像命令文本一样经过脱敏，最多保留 500 条路径——如果变更更多，快照会注明。
• 可在 suv settings 中通过 Record Agent Git Snapshots 关闭此功能，或设置 [agent] record_git_snapshots = false；项目的 .suvadu.toml 可以关闭此功能，但不能重新开启。暂停捕获时不会记录任何快照。
• 在 suv agent delete-session 中删除会话时，其快照也会一并删除；suv gc 会删除那些已满一天、且所属会话没有其他记录的快照。快照不会导出，就像它们所属的 Agent 会话一样。

Cursor 会话也会获取快照，时机为 beforeSubmitPrompt 和 stop。

MCP what_changed 工具会读取这些快照。给定 session_id 后，它会比较该会话的两份快照，并报告其间 Git 状态发生变化的路径（标记为 provenance: observed），以及两个 HEAD 之间的提交；它会在此时向仓库查询这些提交（使用 git rev-list、git log、git diff --name-only，同样有 2 秒的超时限制），因此会话期间创建的提交会连同其主题和涉及的文件一并列出。这些提交主题和路径不会被存储，在显示前会应用仓库自身的排除规则和脱敏处理；如果仓库或提交已不存在，则只会提供两个 HEAD。如果仓库中的路径发生了变化，不一定是 Agent 导致的；如果某路径在开始时已显示变更，且结束时仍显示相同变更，即使期间再次发生变化，也不会列出。如果缺少任一快照，工具会改为读取会话命令，推测其可能产生的影响，并标记为推断结果且说明原因。如果查询的是某个目录和时间范围，它会先列出该目录中有快照的会话，然后再按惯例分析命令文本。

在 suv sessions 中，终端宽度至少为 100 列时，AI 会话的时间线标题会显示其快照观察到的内容，例如 Changed: 3 files, 1 commit；交接框架（h）会在 Changed-file evidence 下列出提交和变更路径，并注明依据的是这两份快照。

永远不会捕获的内容

• 命令输出和文件内容。 Suvadu 会记录命令是否运行、运行结果、耗时以及运行位置，但不会记录命令输出的内容或更改的内容——上文提到的选择加入式失败输出除外，即失败的 Agent 或 suv wrap 命令输出的末尾部分。Agent Git 快照会记录更改过的路径，但不会记录其内容。
• 原生转录记录中的内容： 思考块、附件、图像、文件内容和原始工具结果。Codex 的评论和推理、注入的 AGENTS／环境上下文以及开发者指令也不记录。
• 非 shell 工具调用和文件编辑，以及从某个会话启动的子会话——每个会话标题都会标注为 capture.unverifiable。
• 大小限制： 钩子输入最多读取 16 MiB，且只保留 Suvadu 会记录的字段，因此大型工具输出不会增加命令开销；超过 16 MiB 时，如果命令在截断前到达，仍会记录该命令，否则钩子会返回带名称的错误。单条原生转录记录上限为 16 MiB；超出上限的记录会被拒绝，并返回带名称的错误，而不会静默截断。提示词文本的上限为 agent.prompt_capture_max_chars（默认为 4000）。
• 不同 Agent 的计时和退出代码可信度不尽相同。 Codex 和 Claude Code 钩子的时间戳表示接收时间，而非执行时间（Codex 记录 timing_source = hook_received）。如果 Codex 未提供结构化退出代码，退出代码会保持未知；Claude Code 和 Cursor 会根据成功钩子推断为 0；pi.dev 的 bash 工具不提供退出代码，因此其扩展程序会进行推测。

因此，会话标题会将 Suvadu 已知的遗漏项（known_missing：暂停的窗口、关闭了记录功能的目录、无法跟踪的令牌计数器）与其从未观察到的内容分开报告。complete 表示未记录到缺口——绝不表示此处包含 Agent 执行的所有操作。

suv history --executor openai-codex
suv agent prompts --executor openai-codex

Codex shell 命令会链接到同一轮对话中的提示词。未记录命令的提示词不会出现在提示词浏览器中。记录遵循 Suvadu 的记录和脱敏设置。钩子时间戳反映接收时间；如果 Codex 未提供结构化退出代码，退出状态会保持未知。这需要支持 UserPromptSubmit 和 PostToolUse 钩子的 Codex 版本（已使用 CLI 0.153.4 测试）。Stop 和 SessionEnd 钩子还会增量导入 Codex 的原生转录记录，包括提示词、助手的最终回答以及提供方报告的令牌用量，此过程独立于 shell 命令（每条记录上限为 16 MiB）——这部分还需要支持 Stop／SessionEnd 钩子的 Codex 版本。

Claude Code 命令会在转录记录对齐后链接到对应的原生提示词轮次。Stop 和 SessionEnd 钩子会增量导入本地转录记录中的提示词、助手文本、模型和提供方报告的令牌用量。Suvadu 不会存储思考块、附件、图像、文件内容和原始工具结果。 suv init opencode 会在 ~/.opencode/plugins/suvadu.js 安装一个插件，并将该目录注册到 ~/.config/opencode/opencode.jsonc 的 plugin 数组中——OpenCode 无法可靠地仅从该目录自动加载插件。如果你的 opencode.jsonc 已包含 JSONC 风格的注释（此步骤无法在不冒损坏其余配置风险的情况下安全地解析并重写这些注释），它会打印出需要你自行添加的确切行。OpenCode 执行的 Bash 命令会立即记录；提示词、助手回复、模型和令牌用量会在会话空闲时通过 OpenCode 自身的 session.messages API 捕获。插件只会将 Suvadu 存储的内容交给它——每条消息的文本、模型和令牌计数，不包括工具输出或推理——并且只交付尚未导入的消息，因此长会话每次空闲时只需处理新增消息。升级 Suvadu 或 OpenCode 后，请重新运行 suv init opencode，然后彻底退出并重新启动 OpenCode，让更新后的插件和配置生效。已针对 OpenCode CLI 1.18.30 测试；如果升级 OpenCode 后它报告插件加载错误，可能是其插件接口又发生了变化，需要相应更新 suv init opencode。

suv init cursor 会在 ~/.cursor/hooks.json 中注册四个钩子，并保留你已有的钩子：afterShellExecution（命令）、beforeSubmitPrompt（提示词），以及 afterAgentResponse 和 stop（每轮的最终回复及其结束方式）。每个 Cursor 对话都会成为一个会话，即 cursor-<conversation_id>，对话中的命令会关联到执行它们的回合（Cursor 的生成 ID）。相关限制来自 Cursor：它的钩子不会报告令牌用量，因此 Cursor 会话的令牌用量是不可用的，而不是零；其捕获状态也会注明这一点；钩子不携带时间戳，因此事件时间以钩子接收到事件的时间为准；Cursor 只发送每轮的最终回复文本，因此不会捕获中间的助手消息、思考过程（未安装 afterAgentThought）以及除 shell 命令以外的工具调用；并且只有当 Cursor 指定了工作区时，才会捕获事件，该工作区的 .suvadu.toml 决定脱敏和排除规则。升级 Suvadu 后，请重新运行 suv init cursor 并重启 Cursor。

对于配置了 MCP 的 Agent，可以询问：“这个项目最近有哪些命令执行失败？”

提示词浏览器还是会话时间线？

两者都展示“Agent 做了什么”，但来自两个不同的数据存储，彼此不能替代。

• 提示词浏览器（suv agent prompts）基于记录的 shell 命令构建。它会按命令执行时生效的提示词对命令进行分组，并报告该轮的命令数、成功数、失败数和总用时。没有产生已记录命令的提示词不会显示——因为没有可供分组的命令。它适用于所有能捕获提示词的 Agent，包括没有会话时间线的 pi.dev；还可以按时间范围和执行器筛选，浏览多个会话。
• 会话时间线（suv sessions，非交互式视图则使用 suv agent sessions）基于 Agent 自身的对话记录逐步导入构建。它们会显示提示词、助手回复、中断的回合、所有已观察到的模型和提供方报告的令牌总数——包括完全没有执行命令的会话——以及捕获完整性、已保存的摘要（s）和交接框架（h）。只有 Claude Code、Codex、OpenCode 和 Cursor 支持会话时间线。

MCP：默认只读

该服务提供 22 个只读工具、8 个资源和 6 个提示词。 它们全部用于读取。恰好有两个写入工具，只有在你启用相应选项后才会生效：

写入工具	启用选项	功能
save_session_summary	mcp.allow_session_summaries	在你提出请求时，存储调用它的 Agent 生成的摘要
propose_skill	mcp.allow_skill_proposals	提交技能提案，始终处于待审核状态；只有你在 suv skills（Ctrl+P）中批准后才会启用

要启用某个选项：运行 suv settings，转到 MCP 选项卡（按 Tab 切换），然后在 Writes 下选中相应行并按 Enter。按 Ctrl+S 保存，然后重启 MCP 客户端——服务只会在启动时读取一次配置，因此正在运行的客户端会继续使用旧设置，直到重新连接。 然后提出请求：“总结并保存当前会话。”

同一选项卡会列出每个工具和资源的实际状态。写入工具会显示其关闭的原因——是因为对应选项已关闭、你关闭了该工具，还是两者兼有——避免出现两个开关状态不一致的情况。关闭某个选项会阻止新的写入；已保存的摘要会保留。

服务读取的配置。 工具和资源的可用性、两个写入选项、mcp.exclude_dirs 以及 MCP 默认设置，仅来自全局 config.toml——项目中的 .suvadu.toml 覆盖配置不会改变启用的 MCP 功能。脱敏、排除项和自定义风险规则会通过覆盖配置解析，但只会在 MCP 服务进程启动时，根据其启动目录解析一次。这也是更改后需要重启客户端的原因。

每个响应都遵循统一约定，方便调用方评估可信度： RFC 3339 时间戳、将 unknown 作为唯一的缺失值标记、百分比始终附带其分数值、使用 limit/offset 和 next_offset、明确显示截断信息、每一行都带有稳定的 command-<id>，以及标明 observed（Suvadu 存储的记录）、inferred（由这些记录推导出的内容）或 caller-reported（Agent 编写的文本）的 provenance: 行。 任何推断内容也会重复说明：Suvadu 记录命令、退出代码和耗时——绝不记录文件内容；命令输出只会在启用相应选项时，作为 Agent 或 suv wrap 命令失败时的末尾信息记录。

已保存的摘要是 Agent 自己编写并存回的文本。Suvadu 不会调用模型，也不会生成任何文字。编写摘要的 Agent 和模型会被记录为由调用方声明的元数据，而非经验证的身份；同时会检查摘要引用的证据 ID 是否存在于该会话中。Suvadu 会准确解析当前的 Codex、Claude Code 或 OpenCode 会话，不会猜测：没有工作目录时不会解析，匹配项多于一个时则始终由你选择。后续请求会从已保存的事件和命令偏移量扩展仅追加的检查点；如果其依据的证据发生变化，Agent 会根据完整会话重新生成摘要。

请参阅完整集成指南和 MCP 服务文档。

要手动将 MCP 服务添加到其他客户端，请将 suvadu mcp-serve（或 suv mcp-serve）作为 stdio 服务运行。

• MCP Registry 名称：mcp-name: io.github.AppachiTech/suvadu

---

主要功能

功能	详情
首页	直接运行 suv（或 suv home）——按任务搜索 Suvadu 的功能，查看每项功能背后的实际命令，打开屏幕、选择器和报告，或阅读可复制的数据变更操作说明；在 suv settings 中选择 Startup Screen 可恢复经典概览
搜索	全历史搜索 TUI，提供四种匹配模式（^X）和四种范围（^P），在每行高亮匹配内容；按最后使用时间和运行次数（^U）对每次运行或相同命令分组；默认显示你自己的命令（Ctrl+A 显示 Agent 命令，Ctrl+E 仅显示失败项）；支持筛选器、Smart 排序、详情窗格、查看精确文本的原始检查器（^V）、书签，以及 --compact 行内召回
历史记录	非交互式 suv history，支持筛选器和 --json，可通过管道传递给其他工具
Agent 仪表板	时间线、风险评估、按 Agent 划分的分析、可导出的报告；使用 suv agent report --fail-on <low|medium|high|critical> 在本地 CI／git 钩子中设置门禁
MCP 服务	22 个只读工具、8 个资源和 6 个提示词，另有两个默认关闭的可选写入工具——Agent 会话回放和增量式跨 Agent 摘要检查点；提供项目上下文和失败经验学习；采用统一的响应约定，并明确标注来源
技能库	suv skills——交互式 TUI，可浏览、添加、编辑、删除、同步和审核共享技能，任何支持 MCP 的 Agent 都可读取，无需每个工具各自维护副本。sync --dry-run 会对比每个生成文件中由工具管理的区域；在 Suvadu 之外编辑的区域会被报告为冲突并跳过，而不会被覆盖（--force 可覆盖此行为），已移除或禁用技能的文件会被删除。信任后即可同步提交在 .suvadu/skills/*.md 中的团队技能——参见仓库中的团队技能。add/list/show/edit/rm/disable/enable/sync/cleanup/trust/untrust 也可用作可编写脚本的子命令
提示词浏览器	suv agent prompts 按触发命令的提示词对已记录的命令分组，并显示该轮的成功、失败和耗时。没有运行任何已记录命令的提示词不会显示——要查看 Agent 自己的转录内容，请使用会话时间线
统一会话	suv sessions 可同时浏览人工和 AI 会话，其中 Capture 列仅根据记录的间隔报告 full 或 gaps: N，绝不根据退出码推断。原生 Codex、Claude Code 和 OpenCode 会话会显示提示词、响应、命令、所有观测到的模型以及提供方报告的令牌总数；按 s 打开已保存的摘要（标记为 CURRENT / NEW ACTIVITY / EVIDENCE CHANGED；按 Tab 切换渲染视图／原始视图，按 Ctrl+Y 复制），按 h 仅根据捕获的记录生成交接框架
统计信息	热力图、按小时分布、常用命令、执行器细分；--human（或在 TUI 中按 Ctrl+H）可排除 AI Agent 活动
诊断	suv doctor 会区分阻止 shell 历史记录捕获的因素和可选集成，为每项检查提供单独的修复方法，报告存储数据实际能证明的内容，并按类别列出存储数据及会影响它们的保留规则
整理	标签、书签（suv bookmarks 会打开交互式选择器，将书签召回到提示词中；带有 {{name}}／{{name:default}} 占位符的书签会先询问每个值；运行 suv bookmarks get <label> --set name=value 会输出填入值后的内容——参见带占位符的书签）、备注，以及 suv aliases——用于管理 shell 别名（添加／编辑／删除）的交互式管理器，还会提供常用长命令的建议
隐私与安全	空格前缀排除、正则表达式模式、密钥脱敏（通过 redaction.extra_patterns 扩展）、仅限本地——适用于所有数据采集路径，也包括导入和已保存的摘要。suv backup、任何 suv delete 操作前自动创建快照，以及用于查看匹配命令和删除后剩余内容的 suv delete --dry-run。参见 SECURITY.md。
方向键	按最近使用优先的上／下键召回——优先显示最新命令，按前缀匹配；仅当命令记录在同一毫秒内时才使用当前目录来区分命令。默认隐藏 Agent 命令；使用 Alt+A（按 shell 设置）或 --include-agents 显示。仅支持 Zsh（Bash 保留自己的上／下键行为）；如果后加载的插件接管了上键，suv doctor 会发出警告——参见上箭头召回。同一查询也支持 zsh-autosuggestions 策略：ZSH_AUTOSUGGEST_STRATEGY=(suvadu history)。
Git 分支	在 git 仓库中记录的每条命令都会保留其启动时所在的分支；信息直接从 .git 读取，不会启动 git 进程，并显示在召回详情窗格和详细 MCP 行中。支持 worktree 和子模块；分离的 HEAD 会以其短哈希保存。
Vim 键位	搜索 TUI 中可选的 Vim 风格 j／k／Ctrl+U／Ctrl+D 导航
完整功能文档请参阅 suvadu.sh/cli。

---

更多演示

使用虚构数据，在 Suvadu 0.5.0 中录制。上方的搜索演示展示了 Ctrl+R 调取历史记录；下方的演示涵盖功能发现和 AI 会话。AI 示例使用预先准备的记录，并非实时运行 Agent。

发现功能 — 运行 suv，按任务搜索并打开工具

AI 活动 — 在同一时间线中查看提示词、命令、退出状态和响应

观看视频版本，或阅读 Home 指南和 会话指南。

---

开发

git clone https://github.com/AppachiTech/suvadu.git
cd suvadu
make dev      # Run the app
make test     # Run tests
make lint     # Run clippy + format check

请参阅 CONTRIBUTING.md，了解贡献指南和发布检查清单；请参阅 BENCHMARKS.md，了解搜索的测量方式。

安全

请参阅 SECURITY.md，了解漏洞报告、数据存储设计和隐私详情。

许可证

MIT