知键 · Rime Studio

一个把 Rime 配置修改器、使用指南和方案探索 放在一起的本地 Web 工作台。

希望改变候选窗口，不必记 YAML 路径；忘了外国人名中间的 · 怎么输入，可以按描述查按键；想理解输入法为什么这样工作，可以查看方案组件与拼写规则。

日常管理和输入不使用 AI、不调用云端 API、不依赖 CDN。用户主动下载或更新方案时通过 Git 连接上游仓库。面向 macOS 鼠须管（Squirrel），目前是可运行的早期版本。

快速开始

需要：

• macOS，已经安装并使用鼠须管。
• 已存在的 Rime 用户目录 ~/Library/Rime。
• Node.js 22 或以上；目前验证使用 Node.js 26。
• npm。首次安装依赖需要联网，运行后使用本机服务。

git clone https://github.com/codepiano/rime-studio.git
cd rime-studio
npm ci
npm start

打开 http://127.0.0.1:4312。

也可以双击根目录的 启动知键.command。启动器会检查已有服务，必要时安装依赖、启动服务并打开浏览器。首次打开 .command 若被系统拦截，可以使用终端启动。

服务只监听 127.0.0.1。启动时先检查系统鼠须管安装，再检查当前用户的安装与配置目录。主目录来自当前操作系统用户，不包含固定用户名。默认候选位置：

用户配置：~/Library/Rime
内置配置：/Library/Input Methods/Squirrel.app/Contents/SharedSupport

首次打开先进入“连接设置”。请通过鼠须管菜单打开用户文件夹，核对并确认实际使用的目录；没有找到目录时，仍可在页面中手动指定。手动设置保存在本机 .data/settings.json，下次启动会记住。

改变控件会加入待应用清单，不会立即写入配置。请先生成文件差异预览，再保存，最后重新部署。

生命周期脚本

./scripts/init.sh          # 检查 Node 版本、创建本地目录
./scripts/install.sh       # 安装依赖，不启动服务
./scripts/start.sh         # 后台启动；重复运行不会创建第二个进程
./scripts/status.sh        # JSON 状态：运行 0、停止/失败 1、未知 3
./scripts/restart.sh       # 停止后启动
./scripts/open-entry.sh    # 启动并打开浏览器
./scripts/stop.sh          # 仅停止脚本记录并验证的进程
./scripts/uninstall.sh     # 停止并清理运行日志，保留依赖、设置和备份

清单为 control-panel.json，服务严格监听 127.0.0.1:4312，端口占用时直接失败。PID、进程启动时间及命令保存在 .runtime/，日志为 .runtime/server.log。手动 npm start 启动的进程不会被脚本接管；请在原终端停止后再使用后台脚本。

GET /control-panel/metrics 返回服务自身的状态、时间、PID、运行时长和 Node 内存数据。项目没有自有 SQLite 数据库；.data/ 保存工作台设置及配置备份。

可以做什么

入口	用途
输入诊断	核对启用／部署、字母表和词库挂载，用本机引擎隔离试输并显示真实候选
统一搜索	功能、操作卡、符号、个人词条、快捷短语和已加载的学习记录，按来源跳转
方案与词库	雾凇／白霜下载安装与更新、plum 配方准备与安装、独立词库导入／启停／卸载、个人词条与快捷短语、学习记录查询／删除／清空／恢复、更新冲突对比与合并、可取消及重试的下载任务
查词与文字工具	查询本机 macOS 系统词典、8 种 OpenCC 繁简／地域用词转换、复制结果与转入快捷短语
调整我的输入	候选数、排列、字体、配色、Shift 行为、菜单按键、方案默认状态、词库学习、应用语言规则、半角标点、方案启停与排序
随用随查	26 张操作卡，按问题组织，支持搜索、收藏、跳转设置与教学练习
找符号	用“外国人名”“圆点”“省略号”等描述，或粘贴字符，查询所选方案已部署的真实按键映射
备份浏览与迁移	在“修改记录”中分页搜索全部备份、按类型／状态筛选、查看差异与恢复；导出／检查／预览导入设置、个人词条和短语迁移包
看懂输入方案	查看真实方案的按键处理、分段、候选生成、过滤组件及拼写规则；目前只读

修改之前，看清文件差异

待应用清单连接真实配置文件。文件差异使用本机加载的 jsdiff / diff2html，支持并排、逐行、行号、增删统计、行内高亮与新增文件提示。

忘了符号的输入方法，就按描述查

“找符号”读取所选方案已有的编译配置，区分直接输出、候选选择与配对引号，并优先推荐简单的输入方式。不同方案、标点模式和键盘布局可能不同。

保存、部署与恢复

1. 调整控件，修改进入待应用清单。
2. 生成预览，核对真实文件差异。
3. 保存修改；系统自动保存修改前的完整配置文本。
4. 请求鼠须管重新部署，再在真实输入框里确认效果。

设置控件只修改 default.custom.yaml、squirrel.custom.yaml 和已安装方案的 .custom.yaml。方案安装还会写入预览中的上游数据文件；个人扩展词库与短语另存为独立文本文件。所有保存均进入备份记录，学习记录通过鼠须管官方工具标记删除，修改前在原生锁下备份数据库；占用时只读取同步快照。

备份在 .data/backups/，不同用户配置目录分开保存。切换目录会使旧预览失效，待应用清单也按目录区分。恢复之前检查文件是否又被修改，避免直接覆盖后续修改。首次创建的文件可以恢复为不存在。

手动选择配置副本不会改变鼠须管的配置位置，也不会对副本请求系统输入法重载。部署入口仅对检测到的安装及其原生目录开放。

“保存成功”“部署请求已发送”“编译产物已更新”是不同状态。后台重载通知可能延迟；未能确认时，请从系统输入法菜单手动重新部署。编译时间检查不等于运行时行为验收。

当前范围

• 目前只支持 macOS 鼠须管，未支持 Windows 小狼毫和 Linux 客户端。
• 常见根级继承和补丁路径可读写，不能替代完整 Rime 配置编译器。无法安全合并的高级补丁会拒绝修改。
• 候选外观预览使用示例数据，只近似呈现外观；原生配色和真实窗口以鼠须管为准。
• 教学练习不运行 Rime 引擎，也不操作真实词库。“输入诊断”另行使用本机引擎和临时配置；不载入真实学习数据库，不替代真实输入框验收。需要 clang 和 macOS sandbox-exec，特殊 Lua／二进制插件不保证兼容。
• 专门适配支持雾凇和白霜，也可通过 plum 准备官方或第三方 GitHub 配方；尚未支持任意终端命令、外部 packages.conf、任意底层学习数据库编辑、搜狗等二进制词库转换、模糊音规则编辑、插件安装或源码构建。
• 完整安装可能覆盖已有同名上游文件，预览会列出全部变化。后续更新默认保留已修改的本地文件、个人短语和自定义配置；可逐项对比并选择使用上游或合并文本，不自动删除上游移除的文件。基线存在时提供三方合并建议，冲突标记必须处理后才能生成保存预览。
• plum 使用固定版本的官方安装器，在 macOS 受限暂存环境运行；文件预览和保存仍由知键负责。配方可能修改自定义配置。高级配方、插件及特殊数据文件不保证兼容。
• “学会的词”支持多词典查询、批量删除、单词典清空、导出与恢复；被占用时只读同步快照，快照不允许删除。首次操作需 macOS 命令行工具（clang），用于编译一个小型原生锁辅助程序。
• 独立 .dict.yaml 可导入并接入当前方案，限 20 MB。主词库不可直接停用；共享目录只读；仍有已知引用时不能卸载用户词库。
• 词条编辑支持文字、编码、权重三列；特殊列结构拒绝自动接入。大型词库和二进制模型显示大小与哈希摘要。下载需要 Git。
• 默认语言、字形设置对应新会话；已有状态还可能受到 save_options 等机制影响。
• 社区讨论与配方是探索线索，不代表已在本机安装、验证。

开发与验证

npm ci
npm test
npm start

目前 136 项自动化测试，覆盖配置读写、差异预览、恢复、外部变更、补丁冲突、词库与短语管理、系统词典接口、OpenCC 转换、符号反查、请求乱序、部署资源核对、统一搜索与原生隔离试输、更新合并、任务中断／取消／重试、完整备份浏览及迁移后的真实候选。

已在 macOS / Squirrel 1.1.2 / Rime 1.16.0 环境完成首轮验证，并在隔离配置副本中用本机 rime_deployer 核对生成的候选数、语言状态、字形与标点配置。完整边界和证据见验收记录。

环境变量	用途
PORT	本机服务端口，默认 4312
RIME_USER_DIR	显式启动覆盖：Rime 用户配置目录，优先于页面设置
RIME_SHARED_DIR	显式启动覆盖：内置配置目录，优先于页面设置
RIME_SOURCE_DIR	可选源码仓库父目录；内置快照优先
RIME_STUDIO_DATA_DIR	工作台自身的设置与备份目录，默认项目下 .data/
RIME_DISABLE_DEPLOY=1	禁止调用真实鼠须管部署，用于隔离开发

生命周期脚本和启动器使用 control-panel.json 中的保留端口；PORT 仅用于终端前台调试。

文档

• 使用指南：按具体目的操作，理解配置层级与恢复。
• 开发说明：项目结构、接口与验证方法。
• 上游资料及许可证说明：公开调研材料的来源与授权范围。
• 验收记录：已验证内容及未验证范围。

数据与访问范围

个人配置、备份、日志、依赖目录不进入 Git。服务使用本机地址、来源检查、写入令牌、字段白名单和预览版本检查；不要把它通过代理公开到公网。

本项目不是 Rime 官方工具。感谢 Rime、Squirrel、librime、plum、jsdiff 和 diff2html 的作者与贡献者。