1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
# vkit
用 Rust + [ratatui](https://ratatui.rs) 重写的 `vkit` CLI 快速伴生工具（二进制与命令均为 `vkit`，源码仓库为 [`vkit-rs`](https://github.com/stekovinbranturry/vkit-rs)）。目标：把「唤起 → 交互 → 退出」的秒级命令做到极致启动速度（Node + Ink 冷启动约 80–150ms，Rust 二进制约几 ms）。
独立于 [`vkit`](https://github.com/stekovinbranturry/vkit) 主仓的实验 / 学习项目，与其并存、互不干扰。
## 命令
| 命令 | 说明 | 平台 |
| --- | --- | --- |
| `vkit` | 无参数进入入口菜单（dashboard），选择要用的工具 | 跨平台 |
| `vkit port` | 列出正在监听的 Node 端口及进程，多选一键关闭 | 仅 macOS |
| `vkit run` | 扫描当前目录及子包的 `package.json`，过滤 + 多选批量运行 scripts（须在 git 仓库内） | 跨平台 |
| `vkit worktree`（别名 `wt`） | TUI 管理 worktree；另有 `wt switch` / `wt shell-init` | 跨平台 |
| `vkit vsix` | 从 Marketplace 下载 VSIX 并安装到 Cursor / VS Code | 跨平台 |
| `vkit sync` | 把 VS Code 已装扩展批量同步到 Cursor | 跨平台 |
| `vkit preview` | 一屏预览所有主题色与组件样式（校色用） | 跨平台 |
| `vkit update` | 从 GitHub Releases 下载最新二进制并原地替换 | 跨平台 |
dashboard 键位：`↑/↓` 选择 · `Enter` 进入 · `1-9` 直达 · `?` 帮助（列出子命令）· `q` 退出。
所有选择列表均支持**环形移动**：在第一项按 `↑` 跳到最后一项，在最后一项按 `↓` 回到第一项。
配色为 Everforest 风格低饱和主题：绿色作主强调（标题 / logo / 按键 / 聚焦边框），黄色表示勾选 / 选中，橙色表示光标行，绿色另用于成功状态（如状态 ✓）；边框统一走弱化色。启动时按终端背景**自动切换深/浅色**（探测失败默认深色）。所有选择列表的未选中标题、描述、勾选样式与光标高亮均统一。
## 安装
```sh
# 从 crates.io 安装（需要 Rust 工具链）
cargo install vkit
```
或从 [Releases](https://github.com/stekovinbranturry/vkit-rs/releases) 下载对应平台的预编译二进制（macOS / Linux），解压后把 `vkit` 放进 PATH。
### 从源码安装
需要 [Rust 工具链](https://rustup.rs)。
```sh
# 从源码安装到 ~/.cargo/bin
cargo install --path .
# 或直接构建后自行软链
cargo build --release
ln -sf "$(pwd)/target/release/vkit" /usr/local/bin/vkit
```
## 开发
```sh
cargo run -- port # 运行
cargo test # 单测（纯逻辑：解析 / 过滤 / 截断 / 选择状态）
cargo clippy # lint
```
## `port` 键位
- `↑ / ↓`：移动光标
- `/`：进入搜索模式（端口号 / 进程名 / 完整命令；`Enter` 回列表，`Esc` 清空）
- `Space`：勾选 / 取消当前行
- `A`：全选 / 全不选（当前搜索范围）
- `Enter`：关闭选中项（未勾选时关闭当前行）——弹出二次确认（`Y` 确认 / `n` 取消 / `Esc` 返回）
- `R`：重新扫描刷新
- `q` / `Esc`：退出；`Ctrl+C` 退出
表格的 **DIR 列**显示每行服务的**启动目录**（进程 cwd，即启动该服务时所在的目录，home 前缀缩写为 `~`），方便区分是哪个项目起的服务。搜索也会匹配该目录。
关闭进程：确认后在后台线程执行并显示 loading（spinner），先 `SIGTERM` 优雅退出，3 秒未退再 `SIGKILL` 强制，完成后就地刷新。
## `run` 键位
双栏主从布局：左栏包列表，右栏当前包的 scripts。
**包栏（左）**
- `↑ / ↓`：切换包
- `→` / `l` / `Tab`：进入右侧 scripts
- `1-9`：跳到第 N 个包并进入其 scripts
**Scripts 栏（右）**
- `↑ / ↓`：移动光标（光标行显示 `→ 命令`）
- `←` / `h`：回到包栏
- `Space`：勾选 / 取消当前 script
- `A`：全选 / 全不选本包 scripts
**通用**
- `Enter`：运行——有勾选则跨包批量顺序运行，否则运行光标所在 script
- `/`：进入搜索模式（包名 / script / 命令；`Enter` 回列表，`Esc` 清空）
- `R`：重新扫描刷新
- `q` / `Esc`：退出；`Ctrl+C` 退出
发现范围：须位于 git 仓库内（自当前目录向上找 `.git`），再从当前目录递归扫描所有 `package.json`（尊重 `.gitignore`，跳过 `node_modules`/`dist`/`target` 等），当前目录所属包排在最前并标 `*`，包名后括号内为已勾选数。嵌套子包显示为 `父包 -> 子包`。包管理器按 `packageManager` 字段 → lock 文件逐级向上探测（默认 `npm`）。运行时会临时挂起 TUI，把终端完整交给子进程（继承 stdio，适配 `dev` 这类长驻进程），结束后回到界面并显示退出码。
## `worktree` / `wt`
管理当前仓库的 Main Worktree 与约定 Placement 下的附加 Worktree（In-repo：`.worktrees/`；Global：默认 `~/worktrees/<repo>/`，可在 `~/.config/vkit/config.toml` 的 `[worktree] global_root` 覆盖）。其它路径上的 worktree 不展示。
### 快速切换（学自 Worktrunk）
```sh
# 一次性启用 shell 集成（定义 vkit-wt / 别名 vwt，不抢占 worktrunk 的 wt）
eval "$(vkit wt shell-init zsh)" # 可写入 ~/.zshrc
vwt switch feat # 进入该分支的 worktree（自动 cd）
vwt switch - # 上一个 worktree
vwt switch ^ # Main
vwt switch -c feat/x # 新建分支 + worktree 并进入
vwt switch mr:126 # 按 GitLab MR 进入（必要时创建 worktree）
vwt switch feat -x cursor # 进入后打开 cursor
```
无 shell 集成时，`vkit wt switch` 仍会打印路径，但不会改父 shell 的 cwd。
### TUI
`vkit wt` / `vkit worktree` 进入表格界面。若已 `eval` shell-init，在 TUI 里按 `Enter` 会写 CD 指令并退出，由 `vwt` 包装层自动 cd。
列表为表格：BRANCH / PATH / WHERE / STATUS（相对 Main：绿 `↑` 领先、红 `↓` 落后、`=` 齐平、黄 `*` 脏）/ MR（`!N` 打开 · `!N✓` 已合并 · `!N×` 已关闭）。
**列表键位**
- `↑ / ↓`：移动
- `Enter`：进入（有 shell 集成则 cd；否则开子 shell）
- `o`：用 `cursor` 打开
- `m`：浏览器打开 MR
- `n`：新建
- `d`：Remove（保留分支）
- `p`：Purge（连分支删）
- `r`：刷新
- `q` / `Esc`：退出
## `vsix` 键位
两步流程：输入扩展 → 下载 → 选编辑器安装。
- **输入**：键入扩展 id（`publisher.name`）或 Marketplace 链接；`Enter` 查询最新版本并下载到 `~/Downloads`；`Esc` 退出。
- **选编辑器**（下载完成后自动进入，若检测到 `cursor` / `code`）：`↑/↓` 移动 · `Space` 选择 · `A` 全选 · `Enter` 安装 · `Esc` 跳过。
下载走 Marketplace 的 `extensionquery`（查最新版本）+ `vspackage`（带 gzip 自动解压），安装用 `<editor> --install-extension`。`Ctrl+C` 随时退出。
## `sync` 键位
把 VS Code 已装扩展批量同步到 Cursor（方向固定 `VS Code → Cursor`）。
- 进入后自动读取两个编辑器的 `--list-extensions`，算出 Cursor 尚缺的插件。
- **选择**：左右双栏布局——左栏「待安装」展示 Cursor 尚缺、可多选的插件（checkbox + 光标高亮，焦点常驻），右栏「已安装」只读展示已在 Cursor 里的插件（弱化样式、前缀 ✓）。键位：`↑/↓` 移动 · `Space` 选择 · `A` 全选 · `Enter` 下一步 · `Esc` 退出（默认全选缺失项）。
- **确认**：`Enter` 开始 · `Esc` 返回修改。
- **同步中**：逐个下载 vsix 到临时目录并安装，实时显示进度与每项状态；完成后展示成功/失败汇总，`Enter`/`q` 返回。
前置：需要 `code` 与 `cursor` 两个命令都在 PATH（在各自编辑器里执行「Shell Command: Install 'xxx' command in PATH」）。