ru-text：为AI编码助手注入专业俄语文本质量引擎

1. 项目概述：为AI编码助手注入俄语文本质量之魂

如果你是一名在俄语环境中工作的开发者、产品经理或内容创作者，并且正在使用诸如 Claude Code、GitBrains 或 Cursor 这类AI编码助手，那么你很可能面临一个共同的痛点：当助手用俄语生成代码注释、文档、UI文案甚至商务邮件时，其文本质量往往一言难尽。错误的引号（是 «кавычки-ёлочки» 还是 “лапки”？）、混乱的破折号（短横线还是长破折号？）、充满官僚腔调的冗长句子，这些细节问题不仅影响专业形象，更会降低信息的传达效率。

ru-text 正是为解决这一问题而生。它不是一个独立的校对软件，而是一个专为AI助手设计的“技能”或“插件”。其核心使命是让AI在产出俄语文本时，能像一位经验丰富的编辑或文案一样思考。它基于超过1040条独立制定的规则，涵盖了从排版、信息风格到UX写作和商务沟通的七大领域。当你的AI助手安装了ru-text后，它会在处理俄语文本时自动激活，即时应用排版规则，并根据上下文按需加载特定领域的知识库。这意味着，你无需再在每次生成文本后手动进行繁琐的校对，AI的俄语输出从一开始就具备了专业水准。

这个项目适合所有需要高质量俄语文本的从业者：为俄语市场开发应用的软件工程师、撰写技术文档的技术写作者、需要与俄语区客户沟通的产品经理，以及任何希望提升AI生成内容专业度的个人用户。它的价值在于将那些散落在各种手册、博客和书籍中的俄语写作最佳实践，系统化地“教”给了AI，使其成为你工作中一个无声却强大的协作者。

2. 核心设计思路：规则引擎与上下文感知的融合

ru-text 的设计哲学并非简单地构建一个“俄语语法检查器”，而是打造一个深度理解俄语文本质量维度的“认知框架”。其设计思路可以拆解为三个核心层面：规则的系统化组织、智能的上下文感知触发机制，以及对用户意图的绝对尊重。

2.1 规则体系的构建：从千条规则到七大领域

项目的基石是那约1040条规则。这些规则并非凭空想象，而是作者 Arseniy Kamyshev 基于16个权威俄语资料源（如阿尔乔姆·戈尔布诺夫的排版指南、马克西姆·伊利亚霍夫的“信息风格”理论、Tinkoff Journal的编辑规范等），经过多年专业实践和理解后，独立提炼和重新表述的。为了避免版权问题，所有表述均为原创，未直接引用原文，但完整列出了参考来源以示尊重和溯源。

这千余条规则被精心组织成七个逻辑清晰的领域，每个领域解决一类特定的文本质量问题：

1. 排版：包含96条规则，处理的是文本的“视觉语法”。例如，确保使用正确的角形引号（« »）而非直引号（“ ”），区分连接号（-）与破折号（—），在度量单位和数字间插入不换行空格以防止糟糕的断行，规范数字分组（1 000 000）和缩写格式。
2. 信息风格：包含197条规则，核心是“为读者而写”。它致力于消除“水词”（如“众所周知”、“实际上”、“在某种程度上”等97个常见填充词），优化文本结构（采用倒金字塔原则），强调事实而非空洞的形容词，并统一语体。
3. 编辑：标点：包含88条规则，专注于复杂句子的可读性。特别包含了57个“逗号陷阱”结构——那些容易用错逗号的典型句式，以及引导词、分号的使用规范。
4. 编辑：语法：包含171条规则，涵盖大小写、一致性、50多种冗余表达（如“免费礼物”中的“免费”就是冗余）、列表格式化以及简洁语言原则。
5. UX写作：包含217条规则，这是面向产品界面的微观文案指南。它规定了51种按钮标签的优选措辞（例如，“取消”应用“Отмена”而非“Нет”），构建了错误信息的标准结构（发生了什么 + 用户该如何做），指导了占位符文本、空状态描述、表单标签、通知和对话框文案的撰写。
6. 商务写作：包含128条规则，优化商务沟通。它重构电子邮件结构（主题、首句、行动号召），提供43种清晰短语模式来替代官僚用语（如用“сообщаю”替代“довожу до вашего сведения”），并规范即时通讯礼仪和会议纪要的撰写。
7. 反模式：包含139条规则，以“错误→正确”对照表的形式，按严重程度组织，专门针对官僚语言、被动语态滥用和文本臃肿等问题。

这种领域划分使得ru-text能够进行“渐进式披露”。AI助手无需在会话开始时加载全部规则，而是根据当前任务（例如，正在编写错误提示）动态加载“UX写作”领域的相关规则集，这大大提升了响应效率和针对性。

2.2 自动激活与按需加载：实现无缝集成

一个优秀工具的关键在于其可用性。ru-text 被设计为“隐形”的助手。其主要工作模式是自动激活。当AI助手检测到正在生成或编辑俄语文本时，ru-text 的核心引擎便会介入。这意味着开发者无需记住要输入某个特定的命令来开启校对功能，它就在后台默默工作，确保输出的俄语文本从源头就是规范的。

同时，其按需加载的架构避免了性能开销。9个参考文件（对应不同领域或细分规则）不会在插件初始化时全部读入内存，只有在相关领域被触发时才会加载。例如，当AI在编写代码注释时，可能主要应用“排版”和“信息风格”规则；而当它被要求起草一封客户邮件时，“商务写作”和“反模式”领域的规则文件才会被加载进来。这种设计保证了插件在各类AI助手平台（从轻量级CLI到功能完整的IDE插件）上都能流畅运行。

2.3 风格优先级：用户至上，规则为辅

ru-text 明确树立了“用户意图高于一切”的原则。插件提供的是一套高质量的、基于最佳实践的默认规则集，但它绝非不可逾越的教条。在提示词中，如果你明确要求了某种特定风格——例如，“用轻松的口语化风格写”、“采用学术论文的正式语体”、“为SEO优化这段文字”甚至“模仿契科夫的文学风格”——那么你的明确指令将完全覆盖ru-text的默认规则。

这种设计非常关键，它赋予了用户最终的控制权。工具是来辅助和提升基线质量的，而不是束缚创造力的枷锁。ru-text 确保的是，当用户没有特殊要求时，文本能达到专业、清晰的标准；而当用户有特定需求时，它又能灵活地退居二线。

3. 多平台部署实操指南

ru-text 的强大之处在于其广泛的平台兼容性。它遵循 Anthropic 的 Claude Code 插件规范进行构建，并以此为基础，通过适配或利用通用的技能框架，扩展到了十余个主流AI编码和写作平台。下面我将详细拆解在几个关键平台上的安装与配置步骤，并分享一些实操中的注意事项。

3.1 Claude Code：原生支持与核心体验

作为原生平台，Claude Code 提供了最丝滑的集成体验。

安装步骤：

1. 添加社区市场（一次性设置）：在 Claude Code 的聊天界面中，输入命令/plugin marketplace add anthropics/claude-plugins-community。这会为你的插件列表添加一个丰富的第三方插件库。
2. 安装 ru-text：随后，输入/plugin install ru-text@claude-community。Claude Code 会自动从社区市场获取并安装最新版本的 ru-text 插件。

安装完成后，无需任何额外配置。当你用俄语与 Claude Code 交流，或要求它生成俄语文档、注释时，ru-text 会自动生效。你会在助手的回复中立刻看到变化：引号变得规整，破折号长度正确，句子也更简洁有力。

实操心得：在 Claude Code Web 版或桌面应用中，安装插件后建议重启一下会话（或刷新页面），以确保插件完全加载。有时新安装的插件在现有会话中不会立即被识别。

3.2 GitHub Copilot 与 Windsurf：利用通用技能框架

对于 GitHub Copilot 和 Windsurf 这类支持“技能”框架的助手，ru-text 通过npx skills add命令提供了一种统一的安装方式。

通用安装命令：

npx skills add talkstream/ru-text

这条命令会从 GitHub 仓库下载 ru-text 技能包，并放置到当前项目或全局技能目录中。对于 Copilot，它通常位于.github/skills/目录下；对于 Windsurf，则在.windsurf/skills/目录下。

手动部署方案：如果网络或权限问题导致npx命令失败，可以采用经典的 Git 克隆方式：

git clone https://github.com/talkstream/ru-text.git # 对于 Copilot cp -r ru-text/skills/ru-text .github/skills/ru-text # 对于 Windsurf cp -r ru-text/skills/ru-text .windsurf/skills/ru-text

平台特定激活：

• GitHub Copilot：安装后，Copilot 会在支持俄语的上下文中自动应用规则。在 VS Code 或 JetBrains IDE 中编写俄语注释或字符串时，Copilot 的补全建议就会符合 ru-text 规范。
• Windsurf：安装后，你可以在 Cascade 聊天中通过@ru-text来显式调用该技能。也可以在 Cascade 面板的 “Customizations” > “Skills” 中查看和管理已安装的技能。

注意事项：使用npx命令通常需要项目目录下已有相应的技能目录结构。如果命令执行后技能未生效，请检查是否正确生成了skills/ru-text文件夹，并确认你的 IDE 或编辑器已正确加载了 Copilot 或 Windsurf 扩展的最新版本。

3.3 Cursor 与 JetBrains (Junie)：手动集成的细节

对于 Cursor 和 JetBrains 的 AI 助手 Junie，虽然它们也支持技能，但市场集成度可能稍逊一筹，手动复制是更可靠的方法。

Cursor 安装：

1. 克隆仓库：git clone https://github.com/talkstream/ru-text.git
2. 将技能文件夹复制到 Cursor 的技能目录：
   • macOS/Linux:cp -r ru-text/skills/ru-text ~/.cursor/skills/ru-text
   • Windows (PowerShell):Copy-Item -Recurse ru-text\skills\ru-text "$env:USERPROFILE\.cursor\skills\ru-text"
3. 重启 Cursor。之后，在 Cursor Agent 的聊天中，俄语回复将应用 ru-text 规则。

JetBrains IDE (通过 Junie) 安装：

1. 在项目根目录下运行：npx skills add talkstream/ru-text。这会在项目内创建.junie/skills/ru-text目录。
2. 或者手动复制：cp -r ru-text/skills/ru-text .junie/skills/ru-text
3. 确保你的 JetBrains IDE (IntelliJ IDEA, PyCharm等) 已安装并启用了 Junie 插件。在编写俄语文本时，Junie 的建议将遵循 ru-text 规范。

踩坑记录：在 JetBrains 系列 IDE 中，有时技能目录的路径或权限可能引发问题。如果手动复制后技能不生效，可以尝试关闭 IDE，删除.junie目录，重新打开 IDE 让 Junie 插件重建目录，然后再复制 ru-text 技能文件夹进去。

3.4 命令行工具集成：Codex CLI 与 Gemini CLI

对于喜欢在终端工作的开发者，ru-text 同样提供了支持。

Codex CLI：在 Codex 会话中，直接输入/plugins命令，会启动交互式插件浏览器。搜索 “ru-text” 并安装即可。这是一种非常直观的图形化安装方式。

Gemini CLI：通过扩展安装命令直接集成：

gemini extensions install https://github.com/talkstream/ru-text

安装后，在使用 Gemini CLI 进行任何涉及俄语文本生成的交互时，ru-text 的规则会自动生效。

3.5 Notion 集成：双路径选择

ru-text 为 Notion 提供了两种集成思路，适应不同用户的需求和订阅计划。

路径一：Notion AI 自定义技能（适用于 Business/Enterprise 计划）

1. 将项目中的 模板页面 内容复制到一个新的 Notion 页面。
2. 将该页面指定为 AI 技能（在页面设置中操作）。
3. 之后，在 Notion 中选中任意俄语文本，从 AI 菜单中选择 “ru-text” 技能，即可对其应用排版和风格检查。

路径二：通过 MCP 服务器与 Claude Code 联动（适用于任何 Notion 计划）

1. 首先在 Claude Code 中安装 ru-text 插件。
2. 按照 Notion 官方指南，设置并连接 Notion MCP 服务器 。这相当于在 Claude Code 和你的 Notion 工作区之间建立了桥梁。
3. 连接成功后，你可以直接要求 Claude Code：“请读取我的 Notion 页面 ‘项目计划’，并用 ru-text 规则检查并改进其中的俄语文案。” Claude Code 会通过 MCP 获取页面内容，应用 ru-text 规则修改，并建议更新。

个人体会：对于重度 Notion 用户，第二种方式（MCP+Claude Code）功能更强大，因为它结合了 Claude 的理解能力和 ru-text 的文本专精。而第一种方式更像一个内置的快捷校对工具。选择哪种，取决于你的工作流是更倾向于在 Notion 内部闭环，还是愿意在 Claude Code 中进行集中化的内容处理。

4. 核心功能与命令深度解析

ru-text 的功能远不止于被动的自动校正。它提供了一系列主动命令，让用户能够进行深度文本分析和质量评估。理解这些命令的用途和输出，能帮助你最大化利用这个工具。

4.1 自动激活：无声的守护者

如前所述，这是 ru-text 的主要工作模式。一旦安装成功，每当你的AI助手开始输出俄语文本时——无论是生成一小段注释、编写一个完整的 README 文件、起草邮件还是创作 UI 文案——ru-text 都会在后台运行。你看到的结果，已经是经过初步排版和风格优化的版本。这个过程是实时的、无缝的，你几乎感觉不到它的存在，但它确实在持续提升你文本输出的专业底线。

4.2/ru-text:ru-check：全面质量诊断

当你对一段已有的文本（无论是AI生成的还是自己写的）心存疑虑，或者想进行深度审查时，可以使用此命令。

使用方法：在AI助手的聊天框中，输入/ru-text:ru-check，然后粘贴或引用你想要检查的文本。或者，如果助手刚刚生成了一段文本，你可以直接对它说：“对上面这段文字执行/ru-text:ru-check。”

输出解析：该命令会返回一份详细的诊断报告。报告不会简单地标记“正确”或“错误”，而是会指出具体问题并提供改进建议。例如：

• 排版问题：“此处应使用长破折号 (—) 而非短横线 (-)。”
• 信息风格问题：“‘众所周知’属于填充词，建议删除以使陈述更直接。”
• 语法问题：“此处的形容词与名词在性、数、格上不一致。”
• UX建议：“错误信息应包含‘发生了什么’和‘用户该如何做’两部分，当前缺少解决方案。”

这个功能相当于请来一位专业的俄语编辑，对你的文本进行逐行审阅，非常适合用于最终发布前的终审，或者用于教育团队了解高质量的俄语文本标准。

4.3/ru-text:ru-score：量化文本质量

这是 ru-text 最具特色的功能之一。它不止于定性检查，更能给出一个量化的分数，让你对文本质量有一个直观的把握。

使用方法：与ru-check类似，输入/ru-text:ru-score后跟上待评估的文本。

输出解析：该命令会从五个维度对文本进行评分，每个维度得分在 0.0 到 10.0 之间，并给出一个综合得分：

1. 排版：评估标点符号、空格、引号、数字格式等是否正确。
2. 清晰度：评估句子是否简洁、逻辑是否清晰、是否避免了冗余和模糊表述。
3. 语法：评估语法结构、词形变化、一致性和拼写。
4. 结构：评估段落组织、信息流和整体可读性。
5. 读者精准度：评估文本是否针对目标读者，语气和术语是否恰当。

最终，它会生成一个类似“综合得分：7.8/10”的结果，并附上每个维度的得分和简短评语。例如，“排版：9.5/10（优秀），清晰度：6.0/10（存在较多填充词和复杂句式）”。

实操心得：ru-score是一个强大的内部沟通工具。当与文案或翻译团队协作时，你可以用这个分数作为客观的质量基准，减少主观争论。例如，可以要求所有对外发布的俄语文案必须达到ru-score7.0 以上。这为质量管控提供了一个可衡量的标准。

5. 领域规则详解与实战案例

要真正用好 ru-text，不能只知其然，更要知其所以然。了解其背后各个领域规则的精髓，能帮助你在即使没有AI助手的情况下，也能提升自己的俄语写作水平。下面我将结合具体案例，深入剖析几个核心领域。

5.1 排版领域：细节决定专业度

俄语排版有其独特且严格的规定，这些细节是区分业余与专业文本的第一道门槛。

• 引号：俄语中标准的中性引号是角形引号 «ёлочки»。在角形引号内部需要再使用引号时，则使用 “лапки”。ru-text 会强制将直引号（" "）转换为正确的俄语引号。错误示例：Он сказал: "Привет, мир!"正确示例：Он сказал: «Привет, мир!»如果内部还有引用：Он сказал: «Слово „привет“ мне нравится»。
• 破折号与连接号：这是最常见的错误之一。连接号（-）用于复合词（интернет-магазин）和数字范围（стр. 10-15）。长破折号（—）用于句子中的停顿、说明或对话。ru-text 会根据上下文自动区分。例如，Москва — столица России。（破折号），而UX-дизайнер（连接号）。
• 不换行空格：在数字和单位之间（100 км）、 initials之间（А. С. Пушкин）以及某些介词后，应使用不换行空格，以防止在行末产生难看的断行。ru-text 会自动插入这些空格（在HTML/Unicode中为 或\u00A0）。

避坑技巧：许多西文排版习惯会潜移默化地影响我们。在编写 Markdown 或纯文本时，ru-text 的自动修正能帮你守住俄语排版的底线。对于开发者而言，在编写面向俄语用户的UI界面字符串时，这一点尤为重要，一个错误的引号会立刻让产品显得“不地道”。

5.2 信息风格与反模式：向“水词”和官僚腔宣战

这是 ru-text 提升文本清晰度和力度的核心战场，其理念直接源于马克西姆·伊利亚霍夫的“信息风格”。

• 清除填充词：ru-text 的词典包含了97个常见的“水词”，如конечно же（当然）、на самом деле（实际上）、в принципе（原则上）、как бы（好像）、достаточно（足够地）等。这些词不增加信息量，只会削弱陈述的力度。规则会建议删除或替换它们。
  • 修改前：На самом деле, этот подход является достаточно эффективным.
  • 修改后：Этот подход эффективен.
• 对抗名词化：官僚语言喜欢把动词变成抽象名词，让句子变得冗长晦涩。ru-text 会识别并建议“动词化”。
  • 修改前：Произвести анализ данных（进行数据分析）。
  • 修改后：Проанализировать данные（分析数据）。
• 使用主动语态：被动语态常与官僚文体相伴，且会模糊责任主体。
  • 修改前：Было принято решение о запуске проекта（已做出启动项目的决定）。
  • 修改后：Мы решили запустить проект（我们决定启动项目）。

实战案例：修改一段蹩脚的产品更新公告

• 原始文本：В рамках дальнейшего совершенствования пользовательского опыта нами было осуществлено внедрение ряда функциональных возможностей, направленных на оптимизацию процесса взаимодействия с интерфейсом.
• ru-text 优化后：Мы добавили новые функции, чтобы вам было проще работать с интерфейсом.可以看到，优化后的句子主语明确（“我们”），动词有力（“添加了”），直接说明了目的（“为了让您更轻松地工作”），完全去除了空洞的官僚套话。

5.3 UX写作领域：打造用户友好的界面

对于产品开发者和设计师，这个领域的规则价值连城。它提供了微观文案的完整解决方案。

• 按钮文案：规则库提供了51种常见场景的优选按钮标签。例如，“取消”操作永远使用Отмена，而不是模糊的Нет或Закрыть。“提交”表单使用Отправить，而保存草稿可能用Сохранить черновик。这确保了整个产品界面用语的一致性。
• 错误信息结构：一条好的错误信息应包含两部分：1)问题：清晰说明什么出错了（“Не удалось загрузить файл”）；2)解决方案：告诉用户下一步该怎么做（“Проверьте подключение к интернету и попробуйте снова”）。ru-text 会检查生成的信息是否遵循这个结构。
• 占位符文本：占位符应该是示例，而非指令。Например, Иван Иванов比Введите ваше имя更好。前者展示了格式，后者是多余的指令（输入框本身已暗示需要输入）。

个人体会：在跨国团队中，俄语UI文案常常是事后由非母语者或机器翻译草草完成，质量堪忧。集成 ru-text 后，AI助手在生成界面文案草稿时就能遵循最佳实践，这为俄语本地化质量设立了一个很高的起点，节省了大量后期校对和返工的时间。

6. 常见问题与排查技巧实录

在实际部署和使用 ru-text 的过程中，你可能会遇到一些典型问题。以下是我根据经验整理的排查指南和技巧。

6.1 插件未生效或规则未应用

这是最常见的问题。请按以下步骤排查：

1. 确认安装路径：首先检查 ru-text 技能文件是否被放置在了正确的目录下。不同平台路径不同（如.github/skills/,.cursor/skills/, 项目根目录等）。一个快速的检查方法是查看对应目录下是否存在SKILL.md和一系列.json参考文件。
2. 重启会话/IDE：许多AI助手插件和技能是在会话初始化时加载的。安装 ru-text 后，请务必关闭当前聊天会话并新建一个，或者重启你的IDE/编辑器。这能确保新技能被正确识别和加载。
3. 检查语言检测：ru-text 的自动激活依赖于AI助手对俄语文本的检测。请确保你输入的提示词或上下文明确包含了俄语。你可以尝试用纯俄语提问，例如：“Напиши комментарий к этой функции на русском.”（用俄语为这个函数写注释。）
4. 手动触发：尝试使用显式命令/ru-text或/ru-text:ru-check来测试。如果手动命令有效，但自动激活无效，可能是平台的语言检测逻辑与插件配合存在延迟或问题。

6.2 规则与自定义风格冲突

有时，你希望AI生成特定风格（如诗意化、非常口语化）的文本，但 ru-text 的默认规则会将其“规范化”。

• 解决方案：牢记“风格优先级”原则。在你的提示词中明确声明你想要的风格。例如：“Напиши поэтичное описание заката, игнорируя стандартные правила делового стиля.”（写一段日落的诗意描述，忽略标准的商务风格规则。）或者 “Используй максимально разговорный, даже сленговый язык.”（使用极其口语化，甚至带俚语的语言。）你的明确指令会覆盖 ru-text 的默认规则。

6.3 在非文本生成任务中误触发

极少数情况下，当AI在处理包含俄语字符的代码、配置或数据时，ru-text 可能会被不必要地触发，导致一些非文本内容被意外修改（虽然概率很低）。

• 解决方案：如果发生这种情况，最直接的方法是在当前会话中暂时禁用插件。在 Claude Code 中，你可以使用/plugin disable ru-text命令。完成相关任务后，再用/plugin enable ru-text重新启用。对于其他平台，如果无法动态禁用，可以考虑在处理非自然语言任务时，使用一个未安装 ru-text 的独立会话或项目。

6.4 对复杂或专业术语的处理

ru-text 的规则基于通用和商业俄语的最佳实践。对于非常小众的专业领域（如特定法律条文、高度技术性的科学论文）或新兴的网络俚语，其建议可能不完全适用。

• 应对策略：将其视为一个“基线编辑器”。它确保了文本在排版、基础语法和清晰度上的正确性。对于领域特定的术语和风格，你仍然需要发挥专业判断。你可以利用ru-check的报告作为参考，但不必盲从所有建议，特别是当它不理解某个专业术语的正确用法时。

6.5 性能与响应速度

由于 ru-text 包含超过千条规则，有人可能会担心它影响AI助手的响应速度。

• 实际情况：得益于“按需加载”的架构，实际性能影响微乎其微。只有在处理俄语文本时，相关的规则子集才会被加载到内存中。在我的实际使用中，在 Claude Code 和 Cursor 中，几乎感觉不到任何延迟。与获得的文本质量提升相比，这点潜在的开销完全可以忽略不计。

最后，这个项目本身是开源的，如果你在使用中发现某个平台的集成有特殊问题，或者对某些规则有改进建议，最好的方式是去其 GitHub 仓库的 Issues 页面进行反馈。一个活跃的社区是这类工具持续进化的生命线。