How to Configure Custom Patches in custom.yaml Files for Rime Wanxiang

To configure custom patches in custom.yaml files for the Rime Wanxiang input method, create a file under the custom/ directory, add a top-level patch: key, and define specific configuration overrides or extensions using the __patch syntax for tables and direct key assignments for scalar values.

The custom.yaml files in the amzxyz/rime_wanxiang repository serve as user-level extension points for the 万象拼音 (Wanxiang Pinyin) Rime schema. These files allow you to modify spelling algebra, page sizes, and module behaviors without editing core schema files. When Rime loads a schema, it merges three configuration layers—upstream defaults, schema defaults, and your custom patches—to produce the final runtime configuration.

Understanding the Three-Layer Configuration Merge

The Wanxiang schema implements a hierarchical configuration system that processes files in strict order:

1. Built-in defaults – default.yaml contains generic Rime settings including menu size and key bindings.
2. Schema defaults – wanxiang.schema.yaml defines the core Wanxiang configuration, including spellers, translators, and filters.
3. User customizations – Any custom/*.custom.yaml file placed in the schema directory applies final overrides.

The merge is performed by Rime's native patch mechanism. According to the source code in amzxyz/rime_wanxiang, only keys explicitly listed in your custom file are modified; all other settings inherit from lower layers unchanged.

Patch Syntax Strategies

Depending on your goal, you will use one of two syntax patterns: the __patch directive for extending tables or direct assignment for replacing values.

Extending Tables with __patch

When you need to append, prepend, or selectively modify entries in an existing list (such as spelling algebra rules), use the __patch sub-key. In custom/wanxiang.custom.yaml, this appears as:

speller/algebra:
  __patch:
    - wanxiang_algebra:/base/全拼   # Appends full-pinyin algebra to existing rules

This syntax preserves the base schema's existing algebra entries while adding your specified module from wanxiang_algebra.

Overriding Values Directly

To replace a scalar value or an entire configuration block, omit __patch and assign the new value directly. For example, to enforce a maximum candidate page size of 6 (as required by the schema):

menu/page_size: 6

Similarly, to completely replace the super replacer configuration rather than extend it:

super_replacer:
  db_name: lua/replacer
  delimiter: "|"
  types:
    - option: emoji
      mode: append

Configuring Specific Modules

The Wanxiang schema exposes several modular components through the patch system.

Enabling Super Comments

To activate the comment module and set its display length, override the super_comment block. As implemented in the reference configuration:

super_comment:
  candidate_length: 2
  corrector_type: "〔comment〕"

Customizing Character Sets

Define whitelist or blacklist filters by patching the charset section. This controls which characters appear in your candidate list based on frequency or category filters referenced in the lua/ directory.

Disabling Specific Tips

Turn off unwanted tip categories using the tips configuration:

tips:
  disabled_types: []

Step-by-Step Implementation Workflow

Follow this sequence to apply custom patches safely:

1. Create the patch file – Navigate to the custom/ directory in your Rime user folder and create or edit wanxiang.custom.yaml.

2. Add the required patch key – Every custom file must begin with the patch: top-level key to trigger Rime's patch mechanism.

3. Define your overrides – Insert your specific configuration changes using the syntax patterns described above.

4. Deploy the changes – Save the file and reload the input method using either the command line or hotkey:

   rime_deployer --reload

   On Windows, press Ctrl+` in the Rime status bar. On macOS, use ⌃+⌥+⌘+R.

Why Use Patches Instead of Editing Core Files?

Maintaining separate custom.yaml files provides three critical advantages:

• Upgrade safety – Updates to wanxiang.schema.yaml or upstream defaults won't overwrite your personal settings because they reside in isolated files.
• Granular control – Enable or disable individual modules like super_comment or super_replacer without navigating large monolithic configuration files.
• Portability – Copy your entire custom/ directory to another Rime installation to reproduce your exact configuration instantly.

Summary

• amzxyz/rime_wanxiang uses a three-layer merge system: default.yaml → wanxiang.schema.yaml → custom/*.custom.yaml.
• Use __patch to append or modify existing tables like speller/algebra without replacing the entire list.
• Use direct key assignment to override scalar values like menu/page_size or replace entire module configurations.
• Always wrap custom configurations under the top-level patch: key in files located in the custom/ directory.
• Reload Rime using rime_deployer --reload or system-specific hotkeys to apply changes.

Frequently Asked Questions

What is the difference between __patch and direct assignment in custom.yaml?

The __patch directive appends or modifies entries within an existing table defined in lower configuration layers, preserving the base schema's defaults. Direct assignment completely replaces the target key's value with your new definition. Use __patch when extending spelling algebra or adding replacer rules; use direct assignment when changing page sizes or replacing entire module configurations like super_replacer.

Where should I place my custom.yaml file for Wanxiang?

Place your file in the custom/ subdirectory of your Rime configuration folder, naming it wanxiang.custom.yaml for the main schema or wanxiang_reverse.custom.yaml for reverse lookup patches. The repository structure at amzxyz/rime_wanxiang/wanxiang/custom/ provides the reference location for these user-level extensions.

Do I need to restart my computer after editing custom.yaml?

No. Rime applies patches dynamically using the deployer. After saving your changes, run rime_deployer --reload from the command line, or use the reload hotkey (Ctrl+` on Windows, ⌃+⌥+⌘+R on macOS). The schema will merge your new patches immediately without requiring a system restart.

Can I use multiple custom.yaml files for different Wanxiang variants?

Yes. The patch mechanism supports multiple files targeting different schemas or variants. For example, you can maintain separate wanxiang.custom.yaml for full-pinyin input and wanxiang_reverse.custom.yaml for reverse lookup configurations. Each file operates independently, allowing granular control over different input modes while sharing the same underlying wanxiang.schema.yaml base.

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