wpsnote-beautifier

WPS Notes Intelligent Beautification

Overview

Intelligently beautify WPS Notes, including: structure hierarchy optimization, highlight blocks/columns to emphasize key points, color scheme application, rich text style writing. Complete all read and write operations through the WPS Notes MCP tool (user-wpsnote).

General principle of restrained color use (highest priority)

The core goal of beautification isimprove readability, not "make the document colorful". The following constraints must be observed:

Use only 1 main color tone throughout the document — after selecting one color system from the color scheme, headings, bold keywords, highlight block-key points, and columns-positive content all use that color system, without mixing in other color systems
At most 1 auxiliary color — only used for "tip/note" type highlight blocks (such as yellow tones), and this type should not exceed 1-2 places in the entire document
Use warning colors as needed — red tones are used only when the document truly contains risk/warning content; if not, do not add them
Control the total number of highlight blocks — the entire document should have no more than 3-5 highlight blocks (1-2 for short documents), and no more than 2 types
Control the total number of columns — the entire document should have no more than 2-3 columns, and the background color should use a light shade of the same color system
Extremely restrained inline highlighting — the entire document should have no more than 5-8 inline highlights, with a unified color of 1 type
Do not color body text — ordinary paragraph text remains default black; never add color to an entire paragraph of text
Prefer less over more — when unsure whether color/highlighting is needed, choose not to add it

Workflow

Phase 1: Analyze the current state of the document

The following steps must be performed first; do not skip them:

Call get_note_outline to get the note outline (including block_id, type, text preview)
Call read_note to read the full XML
Call read_file to read this Skill's XML reference file (on first beautification)

Analysis points:

Whether the current heading hierarchy is reasonable (whether it is all <p> with no headings, heading level jumps, etc.)
Whether there are large blocks of plain text lacking visual separation
Whether there is key content suitable for emphasis with highlight blocks (conclusions, core viewpoints, warnings, tips)
Whether there is content suitable for display with columns for comparison (comparisons, parallel relationships, pros and cons)
The usage of existing formatting elements (bold, color, etc.)

Phase 2: Design the beautification plan

Based on the analysis results, formulate a specific beautification plan. Briefly show the plan to the user and confirm before executing.

The plan should include:

Structure adjustment plan — which content needs to be promoted/demoted in heading level, and where separators need to be added
Emphasis element plan — Which content uses highlight blocks and which uses columns (strictly control the quantity, refer to the "General Principle of Color Restraint")
Color scheme selection — Choose 1 primary color system from the preset schemes (see reference/color-schemes.md), use this color system consistently throughout the entire document, do not mix multiple schemes
Color usage budget — Clearly list: X highlight blocks, X columns, approximately X inline highlights, to ensure the total amount is restrained
Estimated number of operations — Give the user an expectation of the scope of changes

Phase 3: Execute beautification

The outline must be refreshed before execution: Call get_note_outline before each write to get the latest block_id.

Prefer using batch_edit for batch execution to reduce the number of calls. The execution order is fixed as: delete → replace → update_attrs → insert.

When executing in batches, re-fetch the outline after each batch is completed before continuing.

Phase 4: Verify results

Call read_note to check the final effect
Confirm that the hierarchy is correct, the colors are consistent, and there is no formatting disorder
Report the completion status to the user

Structural hierarchy design rules

Heading hierarchy specifications

Level	Purpose	Description
`<h1>`	Document main title	Only one in the entire document, located at the beginning
`<h2>`	First-level section	The main section divisions of the document
`<h3>`	Second-level section	Subtopics within a section
`<h4>`	Third-level section	Detailed content, used as needed
`<h5>`/`<h6>`	Rarely used	Only when the hierarchy truly requires it

Structure adjustment strategy

Flat document (all paragraphs with no headings):

Identify semantic boundary points (where topics change)
Promote the leading paragraph to <h2> or <h3>
Generate summary headings for sections without headings

Hierarchy jump repair (such as h1 directly to h4):

Fill in the intermediate levels, or promote deep-level headings upward

Flattening of overly deep hierarchy (more than 4 levels):

Merge the content of <h5>/<h6> into the parent level or convert it to bold paragraphs

Highlight block usage rules

Applicable scenarios and color schemes

Scenario	Background color	Border color	Recommended emoji
Core conclusions/key points	`#E8F5E9`	`#4CAF50`	✅ or 💡
Important tips/notes	`#FFF3E0`	`#FF9800`	⚠️ or 📌
Warnings/risks	`#FFEBEE`	`#F44336`	❗ or 🚨
Quotes/summaries	`#E3F2FD`	`#2196F3`	📖 or 💬
Definitions/terms	`#F3E5F5`	`#9C27B0`	📝 or 🔍
Best practices	`#E0F7FA`	`#00BCD4`	⭐ or 🎯

Highlight block XML syntax

<highlightBlock emoji="💡" highlightBlockBackgroundColor="#E8F5E9" highlightBlockBorderColor="#4CAF50">
  <p><strong>核心结论</strong></p>
  <p>这里是需要强调的重点内容。</p>
</highlightBlock>

Usage principles

Total limit for the entire document: 1-2 for short documents (<20 blocks), 2-3 for medium documents (20-50 blocks), at most 5 for long documents (>50 blocks)
No more than 1 highlight block within a section, to avoid visual fatigue
Keep paragraphs within highlight blocks concise (1-3 paragraphs), do not stuff large blocks of text into them
Within the same document, use no more than 2 types of highlight blocks (e.g., only "Key Points" + "Tips"), avoiding the appearance of 3 or more highlight blocks with different color schemes
Prioritize "Key Points" highlight blocks that match the primary color scheme; use "Tips/Warnings" highlight blocks only when truly needed

Column Usage Rules

Applicable Scenarios

Scenario	Number of Columns	Description
Pros and Cons Comparison	2 Columns	Pros on the left, cons on the right, with different background colors
Solution Comparison	2-3 Columns	Display solution key points side by side
Concept Juxtaposition	2-3 Columns	Related but independent concepts side by side
Data Summary	2-4 Columns	Display key metrics side by side

Column XML Syntax

<columns>
  <column columnBackgroundColor="#E8F5E9">
    <p><strong><span fontColor="#2E7D32">优势</span></strong></p>
    <p>第一个优点说明</p>
    <p>第二个优点说明</p>
  </column>
  <column columnBackgroundColor="#FFEBEE">
    <p><strong><span fontColor="#C62828">劣势</span></strong></p>
    <p>第一个缺点说明</p>
    <p>第二个缺点说明</p>
  </column>
</columns>

Usage Principles

Keep the content volume of each column roughly balanced, avoiding one column being extremely long and another extremely short
Distinguish column titles with bold + color, choosing colors from the primary color scheme (do not introduce a new color scheme)
Use no more than 2-3 column layouts in the entire document, and only use them when the content truly has a comparative or parallel relationship
Use the same background color combination for multiple column layouts as much as possible to maintain visual consistency

Color Application Rules

Title Color

Wrap the title text with <span fontColor="..."> :

<h2><span fontColor="#1565C0">章节标题</span></h2>

Title colors should be consistent throughout the document: headings at the same level use the same color.

Bold Text Color

Use bold + color for key terms and important words:

<p>这是一段文字，其中<strong><span fontColor="#D84315">关键概念</span></strong>被突出显示。</p>

Inline Highlight

Use background highlighting for a small number of keywords:

<p>使用 <span fontHighlightColor="#FFF9C4">核心方法</span> 实现目标。</p>

Color Usage Principles

Keep body text in the default black, and never apply color to ordinary paragraphs
Use only 1 primary color throughout the document(title color = bold color = highlight block primary color = column primary color, all belonging to the same color scheme)
Use the same color for the same semantic role (such as all h2), and only vary the shade for headings at different levels
Use 1 consistent color for inline highlights (fontHighlightColor) throughout the document, and use them no more than 5-8 times
Avoid using highly saturated colors over large areas; prioritize soft tones
When unsure whether color is needed, choose not to add it
For color scheme details, see reference/color-schemes.md, and once selected, keep it consistent throughout the document without mixing multiple schemes

Common XML Writing Templates

For detailed XML templates, see reference/xml-patterns.md。

Special Scenario Handling

Long Documents (>50 blocks)

Process in sections: beautify section by section according to <h2> chapters
Use read_section to read a single chapter
Validate after completing each chapter to avoid large-scale rollbacks

Documents with Existing Formatting

Preserve formatting already set by the user, and only add formatting where there is none
If the user requests "re-beautification", first analyze the existing color scheme and then unify it

Plain Text Documents

Prioritize structuring (adding titles, paragraphs)
Then beautify (adding colors, highlight blocks, columns)
This type of document involves the largest changes, so the plan must be confirmed with the user in advance

Table-Intensive Documents

Do not add extra colors to the tables themselves (maintain readability)
Use highlighted blocks before and after the table for summaries/notes
The table must be replaced as a whole; carefully confirm before operating

Key constraints

block_id may change at any time — before each write, you must refresh via get_note_outline Refresh
batch_edit execution order is fixed — delete → replace → update_attrs → insert (independent of array order)
anchor_id only accepts top-level block IDs — paragraph ids inside containers (highlighted blocks, columns, tables) cannot be used for writing
The table must be replaced as a whole — calling on a table block edit_block(op="replace")
Read-only tags cannot be created — <img/>、<embed/>、<imageColumn/>、<tag> cannot be created via XML
New blocks do not need an id — the system assigns it automatically