{"id":51025369,"url":"https://github.com/pzehrel/squirrel-auto-switch.nvim","last_synced_at":"2026-06-21T19:01:50.908Z","repository":{"id":366088871,"uuid":"1274109020","full_name":"pzehrel/squirrel-auto-switch.nvim","owner":"pzehrel","description":"一款专为 macOS 鼠须管打造的 Neovim 插件：自动在 Normal 模式切换英文，并在 Insert 模式智能记忆和恢复输入状态。异步、轻量，不阻塞编辑。","archived":false,"fork":false,"pushed_at":"2026-06-20T07:07:11.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T08:23:00.661Z","etag":null,"topics":["im-select","ime","lua","macos","neovim","neovim-plugin","squirrel"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pzehrel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-19T07:26:11.000Z","updated_at":"2026-06-20T07:10:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pzehrel/squirrel-auto-switch.nvim","commit_stats":null,"previous_names":["pzehrel/squirrel-auto-switch.nvim"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pzehrel/squirrel-auto-switch.nvim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzehrel%2Fsquirrel-auto-switch.nvim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzehrel%2Fsquirrel-auto-switch.nvim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzehrel%2Fsquirrel-auto-switch.nvim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzehrel%2Fsquirrel-auto-switch.nvim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pzehrel","download_url":"https://codeload.github.com/pzehrel/squirrel-auto-switch.nvim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzehrel%2Fsquirrel-auto-switch.nvim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34622271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["im-select","ime","lua","macos","neovim","neovim-plugin","squirrel"],"created_at":"2026-06-21T19:01:49.034Z","updated_at":"2026-06-21T19:01:50.892Z","avatar_url":"https://github.com/pzehrel.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# squirrel-auto-switch.nvim\n\n一个面向 macOS 鼠须管（Squirrel）的 Neovim 输入状态自动切换插件。\n\n它会在 Normal 模式中保证鼠须管处于 ASCII 状态，并记住用户在 Insert／Replace 模式中最后使用的是中文还是英文。再次进入编辑模式时，插件会恢复该状态。\n\n## 行为\n\n| 场景 | 行为 |\n|---|---|\n| Neovim 启动 | 切换到 ASCII |\n| 进入 Insert／Replace | 恢复上一次编辑状态 |\n| 离开 Insert／Replace | 查询并记住真实状态，然后切换到 ASCII |\n| Normal 模式重新获得焦点 | 强制同步到 ASCII |\n| Insert 模式重新获得焦点 | 只读取并记住状态，不覆盖用户选择 |\n\n插件只注册自己的自动命令和用户命令，**不会修改你的 Neovim 配置文件**。\n\n## 要求\n\n- macOS\n- Neovim 0.10+\n- 鼠须管，并且 Squirrel CLI 位于可执行路径\n\n默认路径：\n\n```text\n/Library/Input Methods/Squirrel.app/Contents/MacOS/Squirrel\n```\n\n## 安装\n\n使用 [lazy.nvim](https://github.com/folke/lazy.nvim)：\n\n```lua\n{\n  \"pzehrel/squirrel-auto-switch.nvim\",\n  config = function()\n    require(\"squirrel_auto_switch\").setup()\n  end,\n}\n```\n\n## 配置\n\n下面展示全部配置项。所有参数都可以省略，未提供时使用表格中的默认值。\n\n```lua\nrequire(\"squirrel_auto_switch\").setup({\n  executable = \"/Library/Input Methods/Squirrel.app/Contents/MacOS/Squirrel\",\n  input_source = \"im.rime.inputmethod.Squirrel.Hans\",\n  auto_activate = true,\n  default_insert_state = \"ascii\",\n  restore_on_insert_enter = true,\n  sync_on_focus = true,\n  timeout_ms = 3000,\n  notify = true,\n  debug = false,\n  error_throttle_ms = 30000,\n})\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|---|---|---|---|\n| `executable` | `string` | \u003ccode\u003e/Library/Input\u003cwbr\u003e Methods/Squirrel.app/\u003cwbr\u003eContents/MacOS/\u003cwbr\u003eSquirrel\u003c/code\u003e | Squirrel CLI 的完整路径。插件通过它执行状态查询、ASCII 切换和输入源选择；路径不存在或不可执行时，自动切换不会生效。 |\n| `input_source` | `string` | \u003ccode\u003eim.rime.\u003cwbr\u003einputmethod.\u003cwbr\u003eSquirrel.Hans\u003c/code\u003e | macOS 中的 Squirrel 输入源 ID。仅在 `auto_activate = true` 时使用；不同版本或安装方式的 ID 可能不同。 |\n| `auto_activate` | `boolean` | `true` | 每次设置 `ascii`／`nascii` 前，先确保当前 macOS 输入源是 Squirrel。选择失败时会尝试启用输入源并重试。关闭后，插件只操作 Squirrel 的 ASCII 状态，不会主动从其他输入法切到 Squirrel。 |\n| `default_insert_state` | `string` | `\"ascii\"` | 当前 Neovim 会话还没有记忆到 Insert 状态时，第一次进入 Insert／Replace 使用的状态。支持 `\"ascii\"`、`\"nascii\"`，也支持更直观的别名 `\"english\"`、`\"chinese\"`。 |\n| `restore_on_insert_enter` | `boolean` | `true` | 进入 Insert／Replace 时是否恢复上一次编辑状态。设为 `false` 后，插件仍会在离开 Insert 时记忆状态并切到 ASCII，但进入 Insert 时不主动切换。 |\n| `sync_on_focus` | `boolean` | `true` | 是否监听 Neovim 窗口焦点变化。Normal 模式重新获得焦点时会强制同步到 ASCII；Insert／Replace 重新获得焦点时只读取并记忆当前状态，不覆盖用户选择。关闭后不注册 `FocusGained` 和 `FocusLost` 自动命令。 |\n| `timeout_ms` | `integer` | `3000` | 每次 Squirrel CLI 调用的超时时间，单位为毫秒。超时会被视为本次操作失败，但不会阻塞或中断 Neovim。必须是正整数。 |\n| `notify` | `boolean` | `true` | 是否通过 `vim.notify()` 显示 CLI 不存在、查询失败、切换失败等运行时错误。关闭后插件静默降级；健康检查仍可用于排查问题。 |\n| `debug` | `boolean` | `false` | 是否输出调试通知，包括实际执行的 Squirrel CLI 命令。通常只在排查路径、输入源或切换时序问题时开启。`notify = false` 时调试通知也不会显示。 |\n| `error_throttle_ms` | `integer` | `30000` | 相同错误通知的最小间隔，单位为毫秒，用于防止模式快速切换时重复刷屏。设为 `0` 可关闭节流；必须是非负整数。 |\n\n### 输入状态的含义\n\n插件控制的是 Squirrel 内部状态，而不是两个独立的 macOS 输入法：\n\n| 配置值 | Squirrel CLI | 含义 |\n|---|---|---|\n| `\"ascii\"`／`\"english\"` | `--ascii` | 开启 Squirrel ASCII 模式，直接输入英文字符 |\n| `\"nascii\"`／`\"chinese\"` | `--nascii` | 关闭 Squirrel ASCII 模式，使用当前 Rime 方案输入 |\n\n`\"english\"` 和 `\"chinese\"` 只用于配置可读性，插件内部会分别规范化为 `\"ascii\"` 和 `\"nascii\"`。\n\n### `auto_activate` 的影响\n\n默认启用 `auto_activate` 是为了处理这样的场景：用户在其他应用中切换到了 ABC、搜狗输入法或另一个 macOS 输入源，然后返回 Neovim。此时单独执行 Squirrel 的 `--ascii` 可能无法影响当前输入窗口，因此插件会先选择配置的 Squirrel 输入源。\n\n如果你希望保留当前系统输入源，不允许插件主动切回 Squirrel，可以关闭它：\n\n```lua\nrequire(\"squirrel_auto_switch\").setup({\n  auto_activate = false,\n})\n```\n\n关闭后需要确保 Squirrel 本身已经是当前输入源，否则 `--ascii`／`--nascii` 可能不会产生预期效果。\n\n### Insert 状态如何记忆\n\n`default_insert_state` 只负责“尚无历史记录”的首次进入：\n\n1. 第一次进入 Insert 时使用 `default_insert_state`。\n2. 用户可以在 Insert 中手动切换中文或英文。\n3. 离开 Insert 时，插件查询真实状态并将其记录。\n4. 后续进入 Insert 时恢复记录值，不再使用默认值。\n\n状态按整个 Neovim 实例记忆，不区分 buffer、window 或 tab，并且不会跨 Neovim 重启持久化。\n\n## 命令\n\n| 命令 | 说明 |\n|---|---|\n| `:SquirrelAutoSwitchEnable` | 启用自动切换 |\n| `:SquirrelAutoSwitchDisable` | 禁用自动切换 |\n| `:SquirrelAutoSwitchToggle` | 切换启用状态 |\n| `:SquirrelAutoSwitchSync` | 按当前 Neovim 模式立即同步 |\n| `:SquirrelAutoSwitchStatus` | 查看内部状态 |\n\n## 健康检查\n\n```vim\n:checkhealth squirrel_auto_switch\n```\n\n健康检查会验证：\n\n- 当前操作系统；\n- `vim.system` 是否可用；\n- Squirrel CLI 是否可执行；\n- 输入源 ID；\n- 当前 `ascii`／`nascii` 状态。\n\n## 设计说明\n\n所有 Squirrel CLI 调用都通过 `vim.system()` 异步执行，不会使用 `vim.fn.system()` 阻塞 Neovim。\n\n插件把以下状态分别管理：\n\n- 最后确认的真实状态；\n- 当前目标状态；\n- 上一次 Insert 会话的状态。\n\n切换任务按顺序执行，因此快速进出 Insert 时，较旧的异步回调不会越过较新的操作。\n\n## 故障排查\n\n### 插件没有切换输入法\n\n先运行：\n\n```vim\n:checkhealth squirrel_auto_switch\n```\n\n如果 CLI 路径不正确，请覆盖 `executable`。\n\n### 使用的 Squirrel 输入源 ID 不同\n\n覆盖 `input_source`。如果不希望插件主动选择输入源：\n\n```lua\nrequire(\"squirrel_auto_switch\").setup({\n  auto_activate = false,\n})\n```\n\n### 希望第一次进入 Insert 默认中文\n\n```lua\nrequire(\"squirrel_auto_switch\").setup({\n  default_insert_state = \"chinese\",\n})\n```\n\n## 开发\n\n完整检查需要安装：\n\n- [StyLua](https://github.com/JohnnyMorganz/StyLua)\n- [Luacheck](https://github.com/lunarmodules/luacheck)\n- [actionlint](https://github.com/rhysd/actionlint)\n\n运行测试：\n\n```sh\nmake test\n```\n\n检查 Lua 格式、静态分析、GitHub Actions Workflow 和测试：\n\n```sh\nmake check\n```\n\n自动格式化 Lua：\n\n```sh\nmake format\n```\n\n测试使用隔离的最小 Neovim 配置，不会加载或修改本机配置。\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpzehrel%2Fsquirrel-auto-switch.nvim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpzehrel%2Fsquirrel-auto-switch.nvim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpzehrel%2Fsquirrel-auto-switch.nvim/lists"}