分析一个解决多项目频繁找目录打开终端和编辑器的工具

用户70505050600
0 阅读6分钟

pisces：在终端里一键打开项目和 AI Agent / 编辑器

一个基于 Ink + React 构建的终端 TUI 启动器（binary pis，npm 包 @lysun001/pisces）。配置一次，敲几个键，就能在指定目录打开终端、启动 AI Agent 或用编辑器打开项目。

一、它解决什么问题

作为一名开发者，你的一天可能是这样的：

  • 在好几个项目目录之间来回切换，反复 cd；
  • 每个项目都要手动启动对应的 AI 编程代理（claude、opencode、crush……）；
  • 想用 VS Code / IDEA 打开某个目录，还得手动去点；
  • 目录层级深、路径长，找起来费劲。

pisces 把「项目目录」和「启动方式」集中到一个可搜索的面板里。你只需要输入几个字母，按回车，就能：

  • 在某个项目目录打开一个新终端；
  • 在某个项目目录启动指定的 AI Agent；
  • 用 VS Code / PyCharm / IntelliJ IDEA / Qoder / Cursor / Trae 打开某个目录；
  • 浏览某个目录下的子目录并直接打开。

全程无需离开终端。

二、核心特性

  • 按键优先搜索：输入 locationKey + agentKey 做前缀匹配，不是模糊搜索，结果精准可预期。
  • Agent 组合：一个项目目录 + 一个 AI Agent CLI，一键组合启动。
  • 编辑器启动：把任意位置（或当前目录）在 VS Code 或其他配置的编辑器/IDE 中打开，不经过终端。
  • 子目录浏览：输入 locationKey + / 或 \ 钻进某个位置下的子目录。
  • 默认启动：Ctrl+D 一键打开固定的路径和命令。
  • 最近打开：Ctrl+R 列出最近 10 次启动（带时间），一键重新打开。
  • 首次运行自动检测：自动扫描已安装的 Agent 和编辑器并写入初始配置，无需手动选择。
  • 配置热加载：改了配置文件保存即生效，无需重启。
  • 自我更新：pis self-update 一键升级到 npm 最新版本。

三、安装

需要 Node.js 22 或更高版本。

npm install -g @lysun001/pisces

安装完成后直接运行：

pis

搜索面板会立即打开。首次运行会自动检测你机器上已安装的 Agent 和编辑器，并生成初始配置。

四、配置

所有配置都在一个文件里：

~/.pisces/settings.json

（Windows 上为 %USERPROFILE%\.pisces\settings.json。）

该文件在首次运行时自动创建，并且 pisces 会热加载它——编辑保存即可，无需重启。

4.1 一个完整示例

{
  "locations": [
    {
      "name": "cloud-admin",
      "path": "C:\\Users\\You\\Desktop\\code\\cloud-admin",
      "key": ["b", "beta"]
    }
  ],
  "agents": [
    { "name": "opencode", "command": "opencode", "key": ["oc", "open"] },
    {
      "name": "claude",
      "command": "claude",
      "key": "cl",
      "args": ["--model", "sonnet"]
    }
  ],
  "editors": [
    { "name": "VS Code", "command": "code", "key": "vscode" }
  ],
  "default": {
    "path": "C:\\Users\\You\\Desktop\\code\\cloud-admin",
    "command": "claude"
  }
}

4.2 各字段说明

locations（项目目录）

字段类型必填说明
namestring是显示名称（1–50 字符，任意字符，含中日韩文字）
pathstring是目录的绝对路径
keystring | string[]是一个或多个搜索键（每个 1–20 字符，仅限 a-z0-9-）

agents（AI 代理 CLI）

字段类型必填说明
namestring是显示名称
commandstring是要执行的 shell 命令
keystring | string[]是一个或多个搜索键
argsstring[]否附加在命令后的参数（默认 []）

editors（GUI 编辑器 / IDE）

字段类型必填说明
namestring是显示名称
commandstring是PATH 上的启动命令（如 code）或可执行文件绝对路径
keystring | string[]是一个或多个搜索键
argsstring[]否附加在目录参数之前的参数（默认 []）

关于 editors 的 command：它是编辑器的启动命令，可以是 PATH 上的命令名（如 code、pycharm、idea），也可以是可执行文件的绝对路径。手动添加时通常填 PATH 命令即可，只有编辑器不在 PATH 上时才需要填绝对路径。

default（默认启动，可选）

字段类型必填说明
pathstring否要打开的绝对路径（不设置则禁用）
commandstring否打开后执行的 shell 命令

4.3 禁用代理或编辑器

默认显示全部。若只想用代理、不想用编辑器（或反之），可以设置：

{
  "agentsDisabled": false,
  "editorsDisabled": true
}

这两个字段可选，默认 false（启用），初始生成的配置里不会包含它们，需要时自行添加。

五、首次运行会自动检测什么

pisces 首次运行时，会自动扫描并写入初始配置，无需手动选择。

  • 自动检测的 Agent（13 个）：claude、codex、opencode、kimi、crush、cline、kilo、pi、qoder、grok、gemini、omp、reasonix。检测方式是命令在 PATH 上，或存在对应的配置目录。

  • 自动检测的编辑器（6 个）：VS Code、PyCharm、IntelliJ IDEA、Qoder、Cursor、Trae。

如果某个工具没被检测到（或不在上面的列表里），在 settings.json 里按上面的字段手动加一条即可。

六、搜索规则（前缀匹配）

输入被解释为 locationKey + agentKey（或 locationKey + editorKey），按前缀匹配：

  1. 找到能作为输入前缀的最长位置键；
  2. 剩余字符作为前缀，同时匹配 agent 键和 editor 键；
  3. 如果没有位置键匹配，则整个输入只与 agent 键和 editor 键匹配（在当前目录启动）。

假设有一个位置键 b，代理键 oc（opencode）、cs（crush），编辑器键 vscode：

输入结果
（空）所有目录、仅代理、仅编辑器条目（组合隐藏）
bb 目录及其所有代理 / 编辑器组合
bob 下代理键以 o 开头的组合
boc唯一的 b + opencode 组合
bvscode在 VS Code 中打开 b 目录
oc仅代理的 opencode 条目（当前目录）
vscode仅编辑器的 VS Code 条目（当前目录）
xyz无匹配

七、键盘快捷键

操作按键
向上导航↑ 或 Ctrl+K
向下导航↓ 或 Ctrl+J
选择 / 启动Enter
默认启动Ctrl+D（或 Cmd+D）
最近打开Ctrl+R（或 Cmd+R）
退出Esc 或 Ctrl+C

八、几个实用的玩法

8.1 用编辑器打开项目

输入 bvscode，在 VS Code 中打开 b 对应的目录。选中编辑器条目时，目录会在编辑器自己的窗口中打开，不经过终端。

8.2 钻进子目录

输入 b/，面板会切换为该位置下的子目录列表，继续输入按前缀过滤，回车在选中的子目录打开终端。隐藏目录（以 . 开头）会被排除。

8.3 一键默认启动

配置好 default 后，Ctrl+D 直接打开固定路径并运行固定命令。

8.4 最近打开

Ctrl+R 打开最近打开弹窗，列出最近 10 次启动（代理、编辑器和目录）及其打开时间，Enter 一键重新打开。

九、自我更新

随时运行内置更新器：

pis self-update

等价写法：pis --update 或 pis -u。已是最新则提示，有新版本则自动执行 npm install -g @lysun001/pisces@latest。

十、相关链接

结语

如果你也厌倦了在终端里反复 cd、手动启动各种 Agent 和编辑器，不妨试试 pisces：配置一次项目目录和启动命令，之后用几个按键就能打开它们。它体积小、无图形界面依赖、配置即热加载，很适合日常高频的项目切换场景。

avatar
文章
阅读
粉丝