diff --git a/qqmusic/README.md b/qqmusic/README.md
index a3da68e..4bcc23c 100644
--- a/qqmusic/README.md
+++ b/qqmusic/README.md
@@ -41,6 +41,21 @@ cron: 1 0,6 * * *
 
 每天 00:01 + 06:02 双轮：任务20（收听节目）跨天滚动翻账本 + 福利站 0 点翻新兜底。
 
+### 青龙自动建任务的元数据约定（踩坑记录 2026-11-04）
+
+订阅勾了「自动添加定时任务」时，青龙从**脚本内容**里正则提取任务名与 cron，两个坑：
+
+| 项 | 青龙的提取规则 | 必须怎么写 |
+|---|---|---|
+| **任务名** | `/name:\s*(.+)/`（**不锚定行首**），取**全文第一个**命中 | 脚本第 3 行写 `* name: QQ音乐自动签到`。**全文任何位置都不能再出现「name+冒号」的连写**——`https.request({ hostname: u.hostname })` 会被抓成任务名 `u.hostname,`（真机已复现） |
+| **cron** | `/\bcron:\s*([^\r\n]+)/`（**必须带冒号**） | 写 `* cron: 1 0,6 * * *`，且**独占一行、后面不跟注释**（同一行剩余文字会被一起吞进 schedule） |
+
+两个都抓不到时的兜底：任务名 = 文件名 `scrip_qqmusic_checkin.js`；cron = 随机 `M H * * *`。
+
+所以脚本里：
+- `https.request` 的选项用 `host:`（Node 的 `hostname` 别名）而不是 `hostname:`
+- cron 注解独占一行
+
 ## 任务覆盖
 
 | 层 | 内容 | 风险 |
diff --git a/qqmusic/scrip_qqmusic_checkin.js b/qqmusic/scrip_qqmusic_checkin.js
index 783fae6..159f4f2 100644
--- a/qqmusic/scrip_qqmusic_checkin.js
+++ b/qqmusic/scrip_qqmusic_checkin.js
@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 /**
+ * name: QQ音乐自动签到
+ *
  * scrip_qqmusic_checkin.js —— QQ音乐会员成长值 + 会员福利站 自动签到（青龙 Node 零依赖）
  *
  * 文件名前缀 scrip_ 是订阅白名单要求（ql repo 的 whitelist 参数 = "scrip_"），
@@ -20,7 +22,11 @@
  *   QM_PLAY_REPORT  任务20播放上报开关（默认 off；伪造统计数据属中风险，
  *                   且需播放 XML 模板，本版未实现，仅挂 StartTask 标记）
  *
- * 定时: cron 1 0,6 * * *  （00:01 + 06:02 双轮：任务20跨天滚动 + 福利站翻新兜底）
+ * cron: 1 0,6 * * *
+ *
+ * 定时说明: 00:01 + 06:02 双轮（任务20跨天滚动 + 福利站翻新兜底）。
+ *   cron 注解必须**独占一行且后面不跟注释** —— 青龙的提取正则
+ *   /\bcron:\s*([^\r\n]+)/ 会把同一行剩下的文字一起吞进去，产出的 schedule 非法。
  */
 'use strict'
 const fs = require('fs')
@@ -55,12 +61,18 @@ function zzc(payload) {
   return ('zzc' + p1 + mid + p2).toLowerCase()
 }
 
-/** Node 内置 https，零外部依赖（不依赖 node_modules 是否被装好） */
+/** Node 内置 https，零外部依赖（不依赖 node_modules 是否被装好）
+ *  两个坑（2026-11-04 真机踩过，任务名被建成 "u.hostname,"、cron 被随机成 "18 21 * * *"）：
+ *  1. 本文件任何位置都不要出现「name + 冒号」的连写 —— 青龙订阅自动建任务时用不锚定的
+ *     正则抓任务名，对象字段（https 选项里的 host 与 name 两段）会被当成任务名。
+ *     所以下面选项用 `host:`（https.request 支持，是 hostname 的别名）。
+ *  2. 定时注解必须写成「cron + 冒号」且独占一行 —— 旧版用不锚定正则抓，
+ *     写成「cron 1 0,6 * * *」（无冒号）匹配不到，任务会落到随机 fallback。 */
 function request(method, urlStr, headers = {}, body = null, timeoutMs = 20000) {
   return new Promise((resolve, reject) => {
     const u = new URL(urlStr)
     const req = https.request({
-      hostname: u.hostname,
+      host: u.hostname,
       port: 443,
       path: u.pathname + u.search,
       method,