Understanding the auto_phrase Feature for User Phrases in RIME Wanxiang

The auto_phrase feature automatically records confirmed Chinese and English text into user dictionaries without manual "add-word" commands, leveraging the lua/auto_phrase.lua pipeline to build personalized vocabularies on-the-fly.

The auto_phrase feature is an automatic phrase creation mechanism implemented in the amzxyz/rime_wanxiang input method schema. It captures committed text at runtime and persists it to user-specific dictionaries, eliminating manual editing while adapting the input experience to individual typing patterns through two complementary pipelines.

How auto_phrase Works

The implementation distinguishes between Chinese and English input through separate validation logic in lua/auto_phrase.lua. Both pipelines trigger when you confirm a candidate (typically by pressing Space or Enter), but they differ in their conditions and storage targets.

Chinese auto_phrase Pipeline

When committing Chinese text, the feature activates only when three configuration switches and content validations pass simultaneously. According to the source in lua/auto_phrase.lua, the AP.commit_handler function checks:

• add_user_dict/enable_auto_phrase is set to true
• add_user_dict/enable_user_dict is set to true
• The commit text contains only Chinese characters (validated via AP.is_chinese_only using Unicode range checks)
• All segments have selected candidates carrying non-empty comments (auxiliary codes)

If these conditions pass, the handler collects auxiliary codes from the comment cache, assembles a custom_code string, and calls Memory:update_userdict to insert a DictEntry into the add_user_dict user dictionary.

English auto_phrase Pipeline

English auto_phrase operates under different constraints. The wanxiang_english user dictionary remains active regardless of the enable_user_dict setting. The trigger conditions in AP.commit_handler require:

• Raw input ending with a backslash (\)
• Commit text qualifying as an ASCII word (detected by is_ascii_word)

When triggered, the system stores the commit text together with the code derived from the raw input (excluding trailing backslashes) into wanxiang_english. It also creates a lowercase variant to ensure case-insensitive matching.

Configuration and Setup

Enable the feature through your custom configuration file. The schema declares the switches in wanxiang.schema.yaml, but you typically activate them in custom/wanxiang.custom.yaml or custom/wanxiang_pro.custom.yaml:

add_user_dict/enable_user_dict: true
add_user_dict/enable_auto_phrase: true

The first switch activates the generic user dictionary infrastructure required for Chinese auto_phrase, while the second specifically enables the automatic phrase creation logic.

Core Implementation Details

The lua/auto_phrase.lua file contains three critical components that orchestrate the feature.

The Comment Cache Mechanism

During input processing, the AP.func iterator populates a comment_cache table mapping candidate text to auxiliary code comments. This cache is essential for Chinese auto_phrase because the comments supply the encoding information needed to construct the custom_code field:

-- Simplified illustration from lua/auto_phrase.lua
local comment_cache = {}
-- During iteration:
comment_cache[candidate.text] = candidate.comment

Commit Handler Logic

The AP.commit_handler serves as the central dispatcher registered in AP.init as both a commit and delete notifier. It validates the input context, determines which pipeline to execute, constructs the DictEntry object, and persists it via env.memory:update_userdict(entry, 1, "").

Helper functions support this logic:

• AP.is_chinese_only(str): Validates that input contains only Chinese Unicode characters
• is_ascii_word(str): Detects pure ASCII words for English validation

Practical Usage Examples

Adding Chinese Phrases

Type the phrase "万象方案" and select the candidate. If auxiliary codes appear in the comments (e.g., "wj", "xx", "fa"), pressing Space triggers the handler to build the code "wj xx fa ..." and write the entry 万象方案 1 wj xx fa ... into add_user_dict. Subsequent typing of the same phrase retrieves it directly from your user dictionary.

Adding English Words

Type hello\ (including the trailing backslash) and press Space. The system detects the backslash suffix and ASCII content, storing both hello and HELLO entries in wanxiang_english with the code hello. Future typing of "hello" will prioritize this user-defined entry.

Programmatic Entry Creation

While normally handled automatically, the underlying API usage follows this pattern from lua/auto_phrase.lua:

local Memory = require('librime').Memory
local env = {engine = rime_engine}
env.memory = Memory(rime_engine, rime_engine.schema, "add_user_dict")

local entry = DictEntry()
entry.text = "万象"
entry.weight = 1
entry.custom_code = "wx "  -- Assembled from comment cache
env.memory:update_userdict(entry, 1, "")

Summary

• auto_phrase provides automatic user dictionary population without manual add-word commands in amzxyz/rime_wanxiang.
• Chinese pipeline requires enable_auto_phrase, enable_user_dict, pure Chinese content, and auxiliary code comments to build entries in add_user_dict.
• English pipeline activates on trailing backslash (\) input, storing ASCII words in wanxiang_english with case-insensitive variants.
• Core logic resides in lua/auto_phrase.lua, utilizing AP.commit_handler, comment_cache, and Memory:update_userdict for persistence.
• Configuration occurs via add_user_dict/enable_auto_phrase and add_user_dict/enable_user_dict in custom YAML files.

Frequently Asked Questions

How do I enable the auto_phrase feature?

Set add_user_dict/enable_user_dict: true and add_user_dict/enable_auto_phrase: true in your custom/wanxiang.custom.yaml file. Both switches must be active for Chinese auto_phrase to function, while English auto_phrase only requires the user dictionary infrastructure to be present.

Why isn't my Chinese phrase being saved to the user dictionary?

Verify that the commit text contains only Chinese characters (validated by AP.is_chinese_only), all segments have selected candidates with non-empty comments (auxiliary codes), and both configuration switches are enabled. The feature explicitly skips entries lacking auxiliary encoding information.

What is the difference between the Chinese and English auto_phrase pipelines?

The Chinese pipeline requires explicit enabling via enable_auto_phrase, validates Unicode Chinese content, and stores entries in add_user_dict using assembled auxiliary codes. The English pipeline triggers automatically on backslash-terminated input, requires ASCII word content, and persists to wanxiang_english regardless of the auto_phrase toggle.

Where are auto_phrase entries physically stored?

Chinese entries write to the add_user_dict user dictionary file, while English entries populate wanxiang_english. Both are standard RIME dictionary files that persist across sessions and can be backed up or version-controlled like other RIME configuration files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}