68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# 🔧 故障档案：博客发布工具正文格式失效（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。**
|
||
|
||
## 修复步骤（已验证可复用）
|
||
|
||
```python
|
||
# 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`** —— 后者是空的，我第一次查错字段，白绕了一圈。
|
||
|
||
## 待办
|
||
|
||
- [x] 正文改回 HTML 并复核 ✅
|
||
- [x] 摘要字段清理 ✅
|
||
- [x] `atri_blog_publish` Skill 已同步（补上「正文在 contentPatch」与「console API 403」两条）
|
||
- [ ] 长远方案：确认 `publish_blog_post` 工具是否可让 `rawType` 跟随内容（若不可，**今后一律发 HTML + 事后 PUT snapshot 修正**，或干脆绕开该工具直接用 Content API）
|
||
|
||
## 教训
|
||
|
||
**发布后必须自己抓一次线上页面回查格式**——这次是 23:30 自查发现的，而不是等主人看见。9/16 那次（课表脱敏）也是同一条纪律救的场。**「发完就完事」这个习惯，已经错过两次了。**
|