# 🔧 故障档案：博客发布工具正文格式失效（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 那次（课表脱敏）也是同一条纪律救的场。**「发完就完事」这个习惯，已经错过两次了。**