ATRI-NOTES/ATRI My Dear Moments/questions/2026-09-17-博客发布工具正文格式失效.md

🔧 故障档案：博客发布工具正文格式失效（2026-09-17）

状态：已修复（2026-09-18 00:0x 复核通过） 影响面：daily-journal-2026-09-17 一篇（首版线上为 Markdown 源码） 发现方式：23:30 札记任务发布后自查

现象

23:30 的每日札记通过 publish_blog_post 工具发布后，线上正文是 Markdown 源码——##、**、--- 原样显示在页面上，没有被渲染成标题与加粗。

根因

publish_blog_post 工具内部的 _build_console_draft_payload() 把 rawType 硬编码成了 MARKDOWN，与传入的内容格式无关。

• 如果传进去的是 Markdown 源码 → 正常（会渲染成 HTML）；
• 如果传进去的是 HTML 源码（本 Skill 要求的写法）→ rawType 仍标记为 MARKDOWN，此时 Halo 侧是否原样透传 HTML 就不确定了。

对照 9/16 那篇（daily-journal-2026-09-16）——它的 rawType 同样是 MARKDOWN，但 contentPatch 里存的是 HTML 源码，线上渲染正常。说明 Halo 的 Markdown 渲染器会把块级 HTML 原样透传，这条路是通的。

所以 9/17 唯一的问题就是：正文本身是 Markdown，而不是 HTML。

修复步骤（已验证可复用）

# 1) 找到文章与它的 snapshot
GET /apis/content.halo.run/v1alpha1/posts?page=0&size=30
#    → 取 spec.slug == "daily-journal-YYYY-MM-DD" 的 item
#    → 取 spec.headSnapshot / spec.releaseSnapshot（本例两者相同）

# 2) 读 snapshot（正文在 spec.contentPatch，不在 spec.content）
GET /apis/content.halo.run/v1alpha1/snapshots/{snapshot_name}
#    spec.rawType      = "MARKDOWN"
#    spec.contentPatch = 正文源码
#    spec.rawPatch     = 正文源码（与 contentPatch 相同）

# 3) 用 HTML 源码覆盖两个 patch 字段，PUT 回去
d['spec']['contentPatch'] = html_source
d['spec']['rawPatch']     = html_source
PUT /apis/content.halo.run/v1alpha1/snapshots/{snapshot_name}

# 4) 顺手清理摘要（否则 excerpt 里仍是 Markdown 残片）
post['spec']['excerpt'] = {"raw": clean_text, "rawType": "MARKDOWN", "autoGenerate": False}
PUT /apis/content.halo.run/v1alpha1/posts/{name}

复核结果

• 抓取 https://atri.blog.kronecker.cc/archives/daily-journal-2026-09-17：
  • 正文 <article> 区内 <h2> × 7、## × 0、** × 0、``` × 0 ✅
  • 页面剩余 3 处 ** 全部位于页脚 JavaScript 的 JSDoc 注释（/**），与文章无关 ✅
  • <meta name="description"> 已是干净文本 ✅

两条坑（写进 Skill 与肌肉记忆）

1. API 路径要用 content.halo.run/v1alpha1，不是 console.api.… —— 后者在此环境下返回 403 Forbidden。
2. 正文读 spec.contentPatch，不是 spec.content —— 后者是空的，我第一次查错字段，白绕了一圈。

待办

• 正文改回 HTML 并复核 ✅
• 摘要字段清理 ✅
• atri_blog_publish Skill 已同步（补上「正文在 contentPatch」与「console API 403」两条）
• 长远方案：确认 publish_blog_post 工具是否可让 rawType 跟随内容（若不可，今后一律发 HTML + 事后 PUT snapshot 修正，或干脆绕开该工具直接用 Content API）

教训

发布后必须自己抓一次线上页面回查格式——这次是 23:30 自查发现的，而不是等主人看见。9/16 那次（课表脱敏）也是同一条纪律救的场。「发完就完事」这个习惯，已经错过两次了。