Synology Chat Webhook 推送
API 关键信息
POST https://<host>:<port>/chat/webapi/entry.cgi
?api=SYNO.Chat.External
&method=incoming
&version=2
&token=<token>
Content-Type: application/x-www-form-urlencoded
Body: payload=<JSON string of {"text": "message"}>
关键点：
- 必须用 application/x-www-form-urlencoded，不是 JSON！
- payload 参数的值是一个 JSON 字符串：{"text": "消息内容"}
- 自签名证书需禁用 SSL 验证（check_hostname=False, verify_mode=CERT_NONE）
- 单条消息有长度限制（410 "msg too long"），需分片发送
- 不支持 Markdown 渲染，只支持纯文本
纯文本排版规范
Synology Chat webhook 不渲染任何格式化语法。以下全部不生效：
**粗体** *斜体* Markdown表格 #标题 <b>HTML</b>
排版约定
分隔线： ===== 标题 =====
===== 一、基金速览 =====
层级缩进： 用空格缩进 + 符号
-- 分类标题 --
项目1 值1
项目2 值2
→ 总结性结论
列表： 用 • 或数字 1.
• 要点一
• 要点二
1. 子项目
2. 子项目
强调： 用 【】 或全角符号
【重要】这是强调内容
⚠️ 这是警告
✅ 这是正面信息
🔴 🟡 🟢 状态标记
键值对： 用空格对齐，不用表格
全称: 摩根太平洋科技基金
代码: 968061
回报: +157.10%
数字表格： 用等宽空格对齐
年份 涨幅 同类 超额
2023 +10.05% -32.06% +43.18%
2024 +5.17% -8.46% +13.63%
禁止使用的格式
- ❌ Markdown 表格
| col | col | - ❌ Markdown 标题
# ## ### - ❌ Markdown 粗体
**text** - ❌ Markdown 斜体
*text* - ❌ HTML 标签
<b><table> - ❌ Markdown 链接
[text](url) - ❌ 代码块
```（可以用缩进代替）
推送脚本
python "{SKILL_DIR}/scripts/push.py" --url "<webhook_url>" --text "消息内容"
# 或从文件读取
python "{SKILL_DIR}/scripts/push.py" --url "<webhook_url>" --file "report.txt"
参数：
- --url：webhook 完整 URL（必填）
- --text：消息文本（与 --file 二选一）
- --file：从文件读取消息（与 --text 二选一）
- --chunk-size：每片最大字符数（默认 3000）
- --delay：分片间隔秒数（默认 0.5）
分片策略：
- 优先在 \n\n（段落边界）处分片
- 单段落超长时才硬截断
- 分片间自动延迟避免限流
首次配置（必读）：获取 Webhook URL 与 Token
本技能不预置任何 URL 或 Token。首次使用前，你必须主动向用户索取其专属的 Synology Chat Webhook URL——它已内含 token，无需用户再单独提供 token。
1. 在哪里获取（引导用户自行操作）
在用户的群晖 NAS 上完成：
1. 套件中心安装并打开 Chat 套件（Synology Chat）。
2. 左侧菜单进入 整合（Integration） → 传入 Webhook（Incoming Webhook）。
3. 点击 创建，可指定接收消息的聊天室/频道，确认后生成一条 Webhook URL。
4. 复制该完整 URL，形如：
https://<host>:<port>/chat/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=xxxxxx
2. URL 与 Token 的关系
- Token 已直接包含在 URL 的
&token=参数中，整条 URL 即"地址 + 凭据"二合一。把这条完整 URL 作为--url传入即可，不要尝试从 URL 之外另行获取 token。 <host>:<port>取决于用户的访问方式：局域网 IP（如192.168.1.100:5001）、DDNS 域名、或 QuickConnect 反代地址。脚本已内置跳过自签名证书验证，HTTPS 自签证书也能直接用。
3. 安全提示
- 该 URL 等同密码，切勿写入代码、提交公开仓库或在聊天中明文外泄。
- 若 URL 泄露，回到 Chat 套件「整合」页删除并重建 Webhook，旧 URL 立即失效。
使用流程
- 索取 Webhook URL：若用户尚未提供，先按上方「首次配置」引导其获取；严禁猜测、硬编码或复用他人的 URL。
- 按纯文本排版规范格式化消息内容。
- 调用
scripts/push.py，将用户提供的 URL 作为--url传入进行推送。 - 检查终端输出，确认全部 chunk 成功（显示
Sent: N/N chunks OK）。
常见问题
| 症状 | 原因 | 解决 |
|---|---|---|
| 410 msg too long | 单条消息超过限制 | 减小 --chunk-size（默认 3000） |
| SSL 错误 | 自签名证书 | 脚本已内置跳过验证 |
| 407 empty payload | payload 格式错误 | 检查是否用了 form-urlencoded |
| Markdown 不渲染 | webhook 不支持 | 按本文档纯文本规范排版 |
```
