MoviePilot项目中消息通知特殊字符处理技巧

问题背景

在使用MoviePilot项目进行资源下载通知时，许多用户发现当通知消息中包含星号(*)等特殊字符时，消息API会返回400错误，提示"can't parse entities"。这是因为消息平台的Markdown解析器将这些字符识别为格式化标记，但未正确闭合导致的解析错误。

技术原理分析

消息平台的API支持Markdown风格的文本格式化，使用特定符号来标记文本样式。例如：

• 星号(*)表示粗体
• 下划线(_)表示斜体
• 反引号(`)表示等宽字体

当消息中包含这些符号但没有正确配对时，解析器无法确定格式化文本的范围，从而抛出400错误。这在MoviePilot发送资源描述信息时尤为常见，因为资源描述中经常包含各种特殊符号。

解决方案

1. 字符替换法

最直接的解决方案是将可能引起问题的特殊字符替换为视觉相似的Unicode符号。例如：

• 将*替换为✧或✦
• 将_替换为ˍ
• 将`替换为ˋ

在MoviePilot的通知模板中，可以通过Jinja2模板引擎的宏功能实现自动替换：

{% macro safe_text(text) %}
    {{ text | replace('*', '✧') | replace('_', 'ˍ') | replace('`', 'ˋ') }}
{% endmacro %}

2. 完整实现方案

在MoviePilot的通知模板配置中，可以这样实现：

{
    "macro": "{% macro safe_text(text) %}{{ text | replace('*', '✧') | replace('_', 'ˍ') | replace('`', 'ˋ') }}{% endmacro %}",
    "title": "📥 开始下载\n{{ title_year }}",
    "text": "{% if download_episodes %}\n📦 季集： {{ season_fmt }} {{ download_episodes }}{% else %}\n📦 季集： {{ season_episode }} {% endif %}"
            "{% if pubdate %}\n🕒 时间： {{ pubdate }}{% endif %}"
            "{% if category %}\n🎭 类别： {{ category }}{% endif %}"
            "{% if site_name %}\n🌐 站点： {{ site_name }}{% endif %}"
            "{% if resource_term %}\n🌟 质量：{{ resource_term }}{% endif %}"
            "{% if size %}\n💾 大小： {{ size }}{% endif %}"
            "{% if seeders %}\n🌱 做种： {{ seeders }}{% endif %}"
            "{% if labels %}\n️🏷 标签： {{ labels }}{% endif %}"
            "{% if original_name %}\n📛 名称： \n{{ original_name }}{% endif %}"
            "{% if description %}\n\n📝 描述： {{ safe_text(description) }}{% endif %}"
}

3. 进阶技巧

对于更复杂的需求，可以考虑以下优化：

1. 选择性替换：只替换未配对的特殊字符，保留有效的格式化标记
2. 转义处理：在特殊字符前添加反斜杠进行转义
3. HTML模式：使用HTML解析模式，可以更精确地控制文本格式

最佳实践建议

1. 全面测试：修改模板后，应测试各种边界情况，确保所有特殊字符都被正确处理
2. 保持可读性：选择替换字符时，尽量选择视觉相似的符号，保持消息的可读性
3. 模板维护：将常用的文本处理函数集中定义，便于统一维护和更新
4. 错误处理：在MoviePilot配置中启用详细日志，便于及时发现和处理类似问题

总结

MoviePilot项目与消息通知集成时，正确处理特殊字符是确保消息可靠传递的关键。通过Jinja2模板引擎的文本处理功能，我们可以优雅地解决这一问题，既保持了消息的完整性，又避免了API错误。这种解决方案不仅适用于星号(*)问题，也可以扩展到其他可能引起解析问题的特殊字符处理上。