spyc

<p align="center"> <img src="docs/assets/spyc-logo.png" alt="spyc logo" width="128"> </p> <h1 align="center">spyc</h1> <p align="center"> 为您的编码代理打造的文件指挥官。 </p> <p align="center"> 键盘驱动 · MCP 原生 · Rust · macOS 和 Linux </p> <p align="center"> <a href="https://github.com/Tripstack-Corp/spyc/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Tripstack-Corp/spyc/ci.yml?branch=main&label=CI&style=flat-square" alt="CI"></a> <a href="https://github.com/Tripstack-Corp/spyc/actions/workflows/audit.yml"><img src="https://img.shields.io/github/actions/workflow/status/Tripstack-Corp/spyc/audit.yml?label=audit&style=flat-square" alt="Audit"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-BSD--3--Clause-blue?style=flat-square" alt="License: BSD-3-Clause"></a> <img src="https://img.shields.io/badge/rust-1.96-orange?style=flat-square&logo=rust" alt="Rust 1.96"> </p> <p align="center"> <img src="docs/assets/demo.gif" alt="spyc demo: pick three docs, ask the agent about them over MCP, gf jumps to the answer" width="760"> </p> --- ## 为什么是 spyc？ 在终端中放置一个 AI 编码代理，通常会得到一个聊天窗口。你仍然需要向它描述你的工作树，复制粘贴路径，并跟踪它正在查看的内容。spyc 在 macOS 和 Linux 上运行代理在一个键盘驱动的文件指挥官旁边，并通过本地 MCP 套接字为其提供对您正在查看的内容的实时结构化访问。 代理可以询问 spyc *光标正在查看什么，什么已暂存，什么已固定，目录中有什么* —— 无需复制粘贴或路径描述。选择三个文件并提出问题；代理会看到您的选择。当它在响应中提及路径时，按 `gf` 直接跳转到那里。 文件管理器是您和代理实际工作共用的工作空间 —— 而不是一个附加在聊天窗口上的文件列表。 ## 它是什么 一个两窗格的终端程序。 - **上窗格** 是一个键盘驱动、类似 vim 的文件指挥官，带有 git 感知列表。 - **下窗格** 是一个子进程 —— 默认情况下是 Claude Code 或 codex（两者都是首选；也支持 Gemini、Antigravity 和 zot），但实际上可以是任何程序。 两个窗格通过一个 chord-prefix 系统（`^a` / screen-style）共享焦点，文件指挥官公开一个本地 Unix 域 MCP 套接字，供下窗格代理连接。 > **Shell 用户注意：** spyc 保留 `^a` 和 `^w` 作为 chord 前缀，因此在窗格内运行的 shell 将看不到它们 —— `^a`（readline `beginning-of-line`）和 `^w`（readline `unix-word-rubout`）被 spyc 拦截。如果您在窗格中运行交互式 shell，请在 `.spycrc.toml` 中重新绑定前缀（`spyc --print-config` 显示相关部分）。在 tmux 中也是如此：`^a` 是 screen 的前缀，而 `^b` 是 tmux 的默认前缀 —— 保持它们不同或在 `.tmux.conf` 中设置 `set -s escape-time 0` 以保持输入快速。 当您选择三个文件并向代理提问时，它可以调用 `get_spyc_context` 并查看您的 cwd、光标文件、选择、库存、活动过滤器和 git 分支 —— 无需复制粘贴或路径描述。 其他一切（vi 动作、标记、选择、库存、分页器、shell 集成）都是您期望从键盘驱动的文件管理器中获得的。MCP 桥是 spyc 与 Yazi、Broot、Ranger 或其他文件管理器不同的部分。 **名称。** 读作 *"spy-see"* —— 接近 *spicy*，这是辣椒的由来。它也继承了 `spy` 和键盘驱动的文件指挥官的血统，它们是在 Rust 中为编码代理时代重建的。 _{spyc 是一个独立项目，与 Side Effects Software Inc. 或 Anthropic 无关。} ## 快速开始 ### 先决条件 - **Rust** 1.88+ -- `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` - **Nerd 字体** 推荐用于 powerline 状态栏；如果您没有，请在 spyc 内按 `C` 切换到单色备用字体。使用以下命令安装：`brew install --cask font-meslo-lg-nerd-font` - **Claude Code** （可选）-- `npm install -g @anthropic-ai/claude-code` - **Linux 剪贴板帮助程序** -- yank-to-clipboard（`yf`、`yp`、`yP`、`ya`、分页 yank）需要 `wl-copy`（Wayland）或 `xclip` / `xsel`（X11）。macOS 使用内置的 `pbcopy`。有关详细信息，请参见 [INSTALL.md](INSTALL.md#clipboard-helper-linux-only)。 ### 安装 ```sh git clone https://github.com/Tripstack-Corp/spyc.git cd spyc make install # 构建 release 并复制到 ~/.local/bin（无需 sudo） ``` ### 启动 ```sh spyc # 在当前目录中打开 spyc -r # 恢复以前的会话（恢复每个窗格到其自己的对话，标识每个标签） ``` spyc 在多列列表中打开您的 cwd。使用 `hjkl` 移动，按 `Enter` 进入目录或在分页器中查看文件，按 `e` 在 `$EDITOR` 中打开。按 `?` 查看完整的帮助叠加层。 要打开 Claude 窗格，请按 **`^\`** （Ctrl+Backslash）或 **F10**。按 **`^a j`** / **`^a k`** 在文件列表和窗格之间切换焦点。 ## MCP 桥的工作原理 spyc 启动时，会自动： 1. **启动一个 MCP 服务器** 在 PID 作用域的 Unix 域套接字（`~/.local/state/spyc/mcp-<PID>.sock`） 2. **写入 `.mcp.json`**，以便 Claude Code 通过标准配置发现 spyc —— 无需额外标志 3. **保持上下文快照的更新** —— cwd、光标文件、选择、库存、过滤器、git 分支 —— 随着您的导航进行更新 多个实例可以安全共存。如果新的 spyc 打开一个目录已经被另一个正在运行的 spyc 占用，它会提示 stderr（`PID N already owns MCP here. Take over? [Y/n]`），然后在断开连接并重写 `.mcp.json` 之前。拒绝，旧实例保持所有权。企业 `managed-mcp.json` 和 `managed-settings.json` 策略受到尊重 —— 有关详细信息，请参见 [INSTALL.md](INSTALL.md#enterprise-managed-environments)。 Claude 可以在任何时候调用 `get_spyc_context` 以查看您正在查看的内容。使用 `gf` / `gF` 从 Claude 的输出跳转回文件列表。 搜索 MCP 工具（`search_paths`、`search_content`、`search_picks`、`search_inventory`）允许 Claude 运行 gitignore 感知的模糊文件名和正则表达式内容搜索，针对项目、用户当前选择的文件或持久的 yanked-file 缓存 —— 后两者是 Claude 无法通过通用文件系统工具看到的。 ## 知道哪个代理需要你 在多个标签页上运行代理，实际的问题是 *哪个代理需要我？* 每个窗格标签页都有一个实时的 **活动点** —— 代理工作时会有动态脉冲，当它 **阻塞**（等待您的输入或权限）或 **完成** 时会显示为稳定的方块。代理通过相同的 MCP/hook 通道报告状态，因此 spyc 不会根据屏幕上的内容进行猜测，并且即使代理重新绘制自己的 UI 也能保持正确。 在转换到 **阻塞** 或 **完成** 时，spyc 会触发桌面通知，显示标签页名称和简短的香料热度边框脉冲（视觉铃声）—— 这样，即使您在另一个窗口中，提示也会引起您的注意。侵入式通道（铃声、闪烁）默认情况下仅在 **阻塞** 时触发，而静默的桌面 ping 也会在 **完成** 时触发。所有这些都是在 `[notify]` 下可配置的（参见 [Configuration](#configuration)），并且 `:notify test` 按需触发所有通道。 会话在退出时自动保存，并在更改后几秒钟自动重新保存，因此崩溃或硬杀死最多会丢失该窗口，而不是整个会话。`spyc -r` 打开一个会话选择器，恢复所有窗格标签页并恢复每个代理的对话。Claude 标签页会启动一个全新的 `claude` 并输入 `/resume <sessionId>`，验证提交是否成功，如果 Claude 的异步启动消耗了它（ `--resume` CLI 标志有安装崩溃回归）。 ## 高级用法 ### 协调多个代理 在多个选项卡上运行多个代理 —— 跨选项卡或跨多个工作树垂直分割 —— 它们在合并时可能会发生冲突。spyc 通过 MCP 公开一个 **作用域注册表**，以便代理在触摸文件之前声明它们正在触摸的内容： - **`register_scope(paths, intent)`** —— 代理声明正在编辑或即将合并的文件；返回声明 ID 以及可能已经在进行的冲突合并。 - **`list_scopes`** —— 谁正在触摸什么，谁正在合并中。 - **`wait_for_scope_clear(paths)`** —— 阻止直到没有其他代理的 `merging` 声明与您的重叠，因此两个代理永远不会同时合并相同的文件。 - **`release_scope(id)`** —— 完成（自动释放时标签页关闭）。 它是建议性的，而不是一个硬锁：只是足够的协调，以保持并行代理相互之间不干扰，没有后台守护进程。使用 `:agent list` / `:agent registry` 可以实时检查它。 上述带有活动点的选项卡，以及它们涵盖了运行多个代理时出现的两个问题：跟踪哪个代理需要你，以及两个代理编辑相同的文件。完整的设计和原理：[`docs/AGENT_ORCHESTRATION.md`](docs/AGENT_ORCHESTRATION.md)。 ## 键绑定 ### 导航 | 键 | 操作 | |-----|--------| | `h` `j` `k` `l` | 移动（计数有效：`5j`、`10k`） | | `gg` / `G` | 顶部 / 底部 | | `Enter` | 进入目录或在分页器中查看文件 | | `e` / `v` | 进入目录或在 `$EDITOR` 中打开文件 | | `dd` / `Ndd` | 删除光标条目（+ N-1 个以下）到墓地（确认 `y`） | | `V` | 在顶部窗格中打开 `$EDITOR`（底部窗格保持可见） | | `D` | 在顶部窗格中打开文件（底部窗格保持可见） | | `u` / `-` | 回到父目录 | | `/` | 搜索当前列表（增量，支持通配符） | | `~` / `Home` | 跳转到主目录（`H` 是 harpoon 前缀） | | `J` | 跳转到任意路径 | | `F` | 项目范围的模糊文件名查找器（支持 gitignore） | | `:grep <pat>` | 项目范围的内容搜索（嵌入式 ripgrep 匹配器） | ### 选择 & 库存 **选择** 是每个目录的多选。**库存** 是持久的文件缓存，跨会话存活。 | 键 | 操作 | |-----|--------| | `t` | 切换选择 | | `T` | 按通配符选择 | | `yy` | 库存 yank（复制文件到缓存） | | `yp` | yank 可见的窗格输出到剪贴板 | | `yP` | yank 最后一个输入提示到剪贴板 | | `Y` | 从库存中删除光标文件 | | `p` | 将库存文件放入 cwd | | `i` | 切换库存视图 | > yank-to-clipboard 在 macOS 上使用 `pbcopy`，在 Linux 上使用 `wl-copy` / `xclip` / `xsel`（自动检测）。在 Linux 上安装其中一个 - 有关详细信息，请参见 [INSTALL.md](INSTALL.md#clipboard-helper-linux-only). ### 墓地（R-undo + 软删除恢复） 使用 **`R`** （以及从库存中删除的项目）的文件会进入用户特定的 **墓地**，作为压缩的 `tar.zst` 块（保留模式位 + mtime）。使用 `:graveyard` 或 `:undo` 恢复。当墓地超过 500MB 时，最旧的条目会级联到系统垃圾箱，因此 OS-native 恢复仍然有效。 | 键 | 操作 | |-----|--------| | `:graveyard` | 打开墓地视图（最新的在前；绑定一个键 `map KEY command graveyard`） | | `:undo` | 恢复最近删除的文件到其原始路径 | | `p`（在视图中） | 恢复光标条目到 cwd | | `P`（在视图中） | 恢复光标条目到原始路径 | | `dd` / `x`（在视图中） | 将光标条目永久删除到系统垃圾箱 | | `Z`（在视图中） | 永久删除所有条目到系统垃圾箱（确认） | ### Git 视图 内置 gix 支持的 diff / show / blame 视图（在进程中，无 `git` 子进程） - 语法高亮，边到边或统一（`|` 切换），字级行内更改高亮显示。 | 键 | 操作 | |-----|--------| | `gd` | 差异 vs HEAD 选择（暂存 + 未暂存 + 新） | | `gD` | 仅暂存差异（`git diff --cached`） | | `gu` | 未暂存差异（`git diff`）- 您暂存的内容 | | `gb` | 责备告ursor文件 | | `\|` （在视图中） | 切换侧边显示 ↔ 统一布局 | ### 分割窗格 窗格是一个真正的伪终端 - 它默认运行 `claude`，但任何命令都有效。 前缀是 `^a`（类似 screen）；`^w` 也有效。 | 键 | 操作 | |-----|--------| | `^\` / `F10` | 切换窗格 | | `F9` | 用 `claude --resume` 打开窗格 | | `^a j` / `^a k` | 切换焦点 | | `^a c` | 新标签页 | | `^a n` / `^a ]` | 下一个标签页 | | `^a p` / `^a [` | 上一个标签页 | | `^a K` / `^a x` | 关闭标签页 | | `^a 1`..`9` | 切换到标签页 N | | `^a s` | 向窗格发送选择路径 | | `^a P` | 将文件内容管道传输到窗格 | | `^a z` | 缩放活动区域 - 列表或底部窗格（全屏切换） | | `^a \|` | 垂直分割 - 循环关闭 / 仅顶部 / 全高（光标文件预览实时加载） | | `^a a` / `^a h` | 焦点左侧文件窗格（a） | | `^a b` / `^a l` | 焦点右侧文件窗格（b） | | `^a d` | 切换非活动分割列/列表的变暗 | | `^s n` | 打开第二个文件指挥官（列 b，在 `PROJECT_HOME`） | | `^s x` | 关闭第二个文件指挥官 (`^d` 退出，保持 `b` 打开以便 `-r`） | | `^a u` | 快速选择 - URL/路径/SHA 的标记选择器 | | `^a v` | 窗格滚动条在应用内分页器（搜索，跳转，视觉 yank） | | `Ctrl+J` | 窗格换行（多行输入） | | `gf` | 跳转到窗格输出中的文件路径 | | `gF` | 跳转到文件 + 在引用的行打开 | ### 分页器 按 `Enter` 在内置分页器中查看文件，支持语法高亮，搜索（`/` 向前，`?` 向后；`n` / `N` 重复），行号，十六进制转储，markdown 渲染和 ANSI 颜色支持。 在分页器中按 `H`（或 `F1`）查看其自己的帮助叠加层。 分页器不限于居中叠加层。 它也可以安装到位： - **`D`** 在顶部窗格中打开光标文件（底部窗格保持可见）。 - **`^a v`** 将窗格滚动条的冻结快照安装在底部窗格中（默认情况下启用行号，因此它按滚动条读取而不是实时读取）。 在分页器中： `/` 搜索 `n`/`N`， `:N` 跳转到行， `V` 启用视觉行模式 - 第一个 `V` 放置光标到确切的起始行， 第二个 `V` 锚定选择（`y` yank 行范围）； `^v` 进入视觉块模式进行矩形选择。 ### Shell | 键 | 操作 | |-----|--------| | `!` | 捕获命令 - 流入分页器 | | `!!` | 重复上一个命令 | | `!?` | 历史记录编辑器（vi 编辑，可搜索） | | `;` | 前台命令（顶部，vim 等） | | `$` | 放入 `$SHELL` | | `:` | 命令行（`cd`，`:sort`，`:limit`，`:grep`，`:fg`，`:task`，`:q`） | 任何命令中的 `%` 展开为当前选择。 ### 后台任务 & 缓存历史 长时间捕获的命令不应阻止您访问 spyc。 | 键 | 操作 | |-----|--------| | `^Z` | （在 `!` 分页器中）将正在运行的任务发送到后台 | | `:fg` / `:fg N` | 恢复最近的（或特定的）后台任务 | | `gB` / `:task N` | 打开 *任务查看器* - 一个无需接管的预览视图 | | `[t` / `]t` | （在分页器中，chord）循环任务查看器 prev/next by id | | `gp` | 重新打开最近关闭的分页器缓冲区 | | `:bprev` / `:bnext` | 按顺序遍历分页器缓冲区历史 | 后台任务在分割器中渲染为 `[N+]`（运行中，新输出）， `[N●]`（运行中，安静）， `[N✓]`（退出 0）， `[N✗]`（非零 / 杀死 / 崩溃），颜色与分割器选项卡不同。 当查看的任务退出时，关闭任务查看器会将其最终渲染的视图推送到缓冲区历史栈中，因此 `[b` 可以返回到它稍后。 ### 标记 & 过滤器 | 键 | 操作 | |-----|--------| | `m{a-z}` | 设置书签 | | `'{a-z}` | 跳转到书签 | | `''` | 跳转回（像 `cd -`） | | `` ` `` | 跳转到起始目录（使用 `gS` 或 `:startdir` 设置） | | `a` | 切换点文件过滤器 | | `o` | 切换构建工件过滤器 | | `=` | 临时通配符过滤器 (`=*.rs`, `=!` 选择，`=git` git, `=h` harpoon) | ### 哈鲁彭（每个工作树固定文件） 一个小型有序列表（最多 9 个槽），用于循环您选择的 文件 / 目录。 持续每个工作树（聚焦的列的仓库根，否则 `PROJECT_HOME`），因此第二个列在另一个工作树中保留其自己的列表。 | 键 | 操作 | |-----|--------| | `Ha` | 将光标文件/目录追加到 harpoon | | `Hx` | 从 harpoon 中删除光标文件/目录 | | `H1`..`H9` | 跳转到槽 N（更改目录 + 放置光标） | | `Hh` | 打开 harpoon 菜单（j/k，K/J 重新排序，dd 删除） | | `=h` | 将列表限制为 harpoon 条目（包括祖先目录） | ### 项目主页 & 会话 每个 spyc 运行都有一个 `PROJECT_HOME`（一个粘性项目根目录）和一个会话名称（一个受香料启发的标签，如 `SAFFRON_CUMIN`）。两者都出现在顶部栏中，并在 `spyc -r` 之间持续存在。 | 键 | 操作 | |-----|--------| | `Space p` | 跳转到 `PROJECT_HOME`（leader；`^a Space p` 从代理窗格） | | `gP` / `Space P` | 将 `PROJECT_HOME` 设置为当前目录 | | `gS` | 将起始目录（`` ` `` 的目标）设置为当前目录 | | `:whoami` | 在状态栏中闪烁 `user@host` | | `:project [.\|<path>\|clear]` | 管理 `PROJECT_HOME` | | `:startdir [.\|<path>]` | 管理起始目录 | | `:name <NEW>` | 重命名活动会话 | | `:whoami` | 显示 `user@host` | **leader**（`Space`，或来自代理窗格的 `^a Space`）打开一个全局/工作区菜单：`Space w l\|n\|d`（工作树列表/新建/删除），`Space p`（项目主页），`Space s`（会话信息）。按住它以查看 which-key 弹出窗口。 `PROJECT_HOME` 在启动时自动设置，如果启动目录包含 `.git`。新的窗格选项卡默认为 `PROJECT_HOME`，如果设置了 `PROJECT_HOME`（将 `[pane] new_tab_cwd = "browse_dir"` 设置为在当前列表目录中打开它们）。 ## 配置 spyc 会从 `~/.spycrc.toml`（用户） 和 `./.spycrc.toml`（项目）中读取配置文件。更改后可以立即生效，无需重启（使用 `^R` 强制刷新）。 > **完整参考：** [`CONFIGURATION.md`](CONFIGURATION.md) — 包含所有选项和示例，包括通知（`[notify]`）、按键映射 DSL 和 Lua 脚本。 > **项目配置是沙盒化的。** `./.spycrc.toml` 可以设置颜色、布局、忽略掩码和绑定按键到内置操作，但其执行绑定（`unix` shell 命令、`lua` 脚本和 `jump`）被忽略 — 只有您的 `~/.spycrc.toml` 可以绑定这些，只有在克隆仓库中打开 spyc 无法运行恶意 `.spycrc.toml` 中植入的命令。`^R` 会从您启动的目录重新加载项目文件，而不是您浏览到的目录。 要生成一个包含所有选项（默认为注释状态）的配置文件： ```sh spyc --print-config > ~/.spycrc.toml ``` 选择部分选项： ```toml # 布局：状态栏的位置。默认为 "top"，也可设置为 "bottom"。 # 在 tmux 中使用 "bottom"，以避免 spyc 的状态栏与 tmux 的状态栏重复。 [layout] status_position = "bottom" # 按键映射：将按键绑定到任意操作。按键可以是单个字符、Ctrl 组合键（`^P`）或命名键（`<F2>`）。 # `command` 绑定按键到 : 命令 — 方便不常用的功能，这些功能默认没有绑定按键。 keymap = [ "map f unix file %", "map A command activity", "map ^Y command graveyard", "map z lua mymacro", # 运行 ~/.config/spyc/lua/mymacro.lua（仅限 $HOME 配置） ] # 颜色覆盖：自定义调色板。 [colors] cursor_bg = "#ff6600" pick = "#ffcb6b" # 当 Agent 窗格状态更改时通知（“哪个 Agent 需要我”）。 # 桌面提示和视觉闪烁默认开启；响铃是可选的。 # 侵入式通道（响铃 + 闪烁）在 Blocked 时触发；非侵入式桌面提示在 Done 时也会触发。 # 可以修改通道的 *_done 设置来改变此行为。 [notify] # desktop = true # 在 Blocked / Done 时通知（默认开启） # desktop_via = "auto" # "auto"（通过 SSH 使用 OSC-9 → 您的客户端，本地使用 OS 通知）、"system"、"osc9" 或 "both" # desktop_done = false # 仅在 *blocked* 时桌面提示，而不是在每一步 # bell = true # 响铃（仅在 Blocked 时） # bell_done = true # 在 Done 时也响铃（默认仅在 Blocked 时） # visual = false # 关闭 spice-heat 渐变边框脉冲 # visual_done = true # 在 Done 时也闪烁（默认仅在 Blocked 时） # suppress_focused_tab = true # 静音当前标签页（默认关闭 → 通知） ``` 运行 **`:notify test`** 以触发所有通道（响铃 + 视觉 + 桌面提示），以验证您的设置是否正确，无需等待 Agent 状态转换。 ## 推荐设置 - **终端：** [iTerm2](https://iterm2.com/)（macOS）、WezTerm、Kitty、Ghostty 或 Alacritty - **字体：** 任意 [Nerd Font](https://www.nerdfonts.com/) 以支持状态栏。按 `C` 切换到单色模式，如果您不想安装 Nerd Font。 - **Claude Code：** `npm install -g @anthropic-ai/claude-code` - **平台：** macOS 和 Linux（x86_64，aarch64），Windows 通过 WSL。 参见 [INSTALL.md](INSTALL.md) 获取详细的设置说明。 ## 更多文档 - [FEATURES.md](FEATURES.md) — 完整的功能参考 - [CONFIGURATION.md](CONFIGURATION.md) — 配置参考：`.spycrc.toml`、通知、按键映射 DSL、Lua - [INSTALL.md](INSTALL.md) — 终端、字体、构建和交叉编译设置 - [ARCHITECTURE.md](ARCHITECTURE.md) — 并发模型、MVU 目标形状、持久化、MCP 传输 - [docs/AGENT_ORCHESTRATION.md](docs/AGENT_ORCHESTRATION.md) — 活动点、通知、会话恢复和作用域注册如何协同工作 - [DESIGN.md](DESIGN.md) — UI 设计语言：组件、界面、调色板、扩展检查清单 - [CHANGELOG.md](CHANGELOG.md) — 版本历史 - [ROADMAP.md](ROADMAP.md) — 战略、方向和决策日志 - [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献指南和 SemVer 政策 - [问题](https://github.com/Tripstack-Corp/spyc/issues) — 实时 backlog：错误、功能和想法（已标记，位于 [路线图板块](https://github.com/orgs/Tripstack-Corp/projects/1)) ## 许可证 BSD-3-Clause。徽标使用 [Twemoji](https://github.com/jdecked/twemoji) 的 Pepper Art 作品（CC-BY 4.0）。