INN666

Appearance

AI 文章發佈流程 ​

本文件是 INN666 技術部落格的 AI 文章發佈標準流程。

  • AI 助手收到「發佈文章」或同義要求時，必須先閱讀本文件。
  • 本文件只規範發佈流程；文章內容仍以使用者指示與原始草稿為準。
  • commit、push 與正式部署不屬於自動發佈範圍，除非使用者另外明確要求。

1. 確認發佈來源 ​

  • 確認使用者指定的繁中草稿路徑；沒有明確指定時，以目前作用中的草稿為準。
  • 檢查 Git 狀態，保留使用者既有變更，不覆寫無關檔案。
  • 草稿必須位於 draft/，且不能已在 draft/published/。
  • 從草稿 frontmatter 取得：
    • category
    • translationKey
    • 標題、摘要、日期、Tag 與作者資訊
  • translationKey 必須是小寫 kebab-case，並作為中英文正式文章的共同 slug。

2. 校訂繁中完成稿 ​

  • 保留作者原本的中文語氣、例子、節奏與直接口吻。
  • 修正錯字、標點、過長句子、重複內容與不清楚的段落順序。
  • 一篇文章維持一個主要論點，不讓附帶主題搶走主軸。
  • 對技術與事實性敘述進行必要查證；無法確認的專案特定資訊必須保留不確定性。
  • 不自行加入原稿沒有的背景、動機、結論、反思或行銷式文字。
  • 補齊正式 frontmatter：
    • title
    • description
    • author
    • date
    • updated
    • tags
    • lang: zh-TW
    • translationKey
    • draft: false
  • 正式文章不重複填寫 category；分類由來源目錄決定。
  • 標題後加入 <ArticleMeta />。
  • 將完成稿放到 zh/articles/{category}/{translationKey}.md。

3. 建立英文正式稿 ​

  • 英文版必須忠實翻譯已完成的繁中正式稿。
  • 保留相近的直接語氣，不新增繁中版沒有的論點、解釋或結論。
  • 中英文使用相同的：
    • translationKey
    • slug
    • 發布日期與更新日期
    • Tag
    • 章節結構
  • 英文 frontmatter 使用 lang: en-US 與 draft: false。
  • 標題後加入 <ArticleMeta />。
  • 文末固定加入：English translation provided by Codex.
  • 將英文稿放到 en/articles/{category}/{translationKey}.md。

4. 處理公開素材 ​

  • 只有文章實際使用且確認可公開的圖片才可搬入 public/。
  • 正式圖片放到 public/assets/{category}/{translationKey}/。
  • 中英文共用圖片時只保存一份；含文字的語系圖片使用清楚的語言後綴。
  • 不得公開草稿素材、私人資料、公司機密或未取得公開許可的內容。
  • 確認所有站內連結與圖片路徑指向實際存在的檔案或頁面。

5. 執行自動發佈驗證 ​

在專案根目錄執行：

powershell
pnpm run article:publish "draft/草稿檔名.md"

發佈工具會依序：

  • 驗證草稿的分類與 translationKey。
  • 找出對應的繁中與英文正式稿。
  • 驗證必要 frontmatter、語言、日期、Tag、slug、draft 狀態與 <ArticleMeta />。
  • 驗證英文翻譯聲明與雙語配對。
  • 檢查同語言內是否有重複 slug。
  • 執行 pnpm run docs:build。
  • 驗證正式頁面、canonical、hreflang、BlogPosting JSON-LD 與索引狀態。
  • 驗證文章列表、Tag 頁、搜尋輸出與 sitemap。
  • 檢查建置後的站內連結與圖片是否存在。
  • 所有檢查成功後，才將原始草稿移入 draft/published/。

6. 失敗處理 ​

  • 任一檢查失敗時，不得手動封存或刪除原始草稿。
  • 依終端機錯誤訊息修正正式稿、素材或設定，再重新執行發佈指令。
  • 不以停用檢查、刪除測試或硬編碼例外的方式繞過錯誤。
  • 若錯誤來自發佈工具本身，先執行：
powershell
pnpm run article:publish:test

7. 發佈後確認 ​

  • 確認原始草稿已完整移入 draft/published/。
  • 檢查 Git diff，只包含本次文章、素材與必要設定變更。
  • 純文字文章以自動建置驗證為主；若修改主題、版面或互動元件，必須另外進行瀏覽器預覽。
  • 向使用者回報：
    • 中英文正式稿位置
    • 公開網址
    • 草稿封存位置
    • 測試與建置結果
    • 尚未執行的 commit、push 或部署動作