AI Skills
asc-whats-new-writer

asc-whats-new-writer

熱門

利用 `./metadata` 下的標準 metadata，根據 git log、要點清單或自由文字，生成吸引人且符合在地化語言習慣的 App Store 版本更新說明（What's New）。可選擇同步搭配宣傳文字（Promotional Text）的更新。

948星標
50分支
更新於 2026/7/31
獲取技能源代碼

相關技能

content-creator4.6萬hud3.9萬freecad-scripts3.9萬
SKILL.md
唯讀
名稱
asc-whats-new-writer
描述

利用 `./metadata` 下的標準 metadata，根據 git log、要點清單或自由文字，生成吸引人且符合在地化語言習慣的 App Store 版本更新說明（What's New）。可選擇同步搭配宣傳文字（Promotional Text）的更新。

asc What's New Writer

根據彈性輸入來源，生成吸引人且在地化的版本更新說明。可選擇搭配宣傳文字更新。

Preconditions

  • Metadata 已透過 asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata" 下載至本地標準檔案中。或者：使用者手動提供關鍵字。
  • 身份驗證已設定完成以利上傳（透過 asc auth login 或 ASC_* 環境變數）。
  • 除非使用者另有指定，否則主要語系（primary locale）預設為 en-US。

Before You Start

  1. 閱讀 references/release_notes_guidelines.md 以了解語氣、結構與範例。
  2. 找出 metadata/version/ 下的最新版本目錄（最高 semver 版本號）。所有 metadata 讀取皆使用此目錄。
  3. 列出該版本目錄下的 JSON 檔案，以列舉現有的語系（existing locales）。

Phase 1: Gather Input

接受以下三種輸入模式之一（自動偵測）：

Git Log

解析自上次標籤（tag）以來的 commit 紀錄：

# 找出最新的 tag
git describe --tags --abbrev=0

# 列出該 tag 之後的 commit
git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges

過濾掉無關雜訊：合併 commit（merge commits）、相依性更新（dependency bumps）、CI 變動、僅格式調整的 commit。提煉出面向使用者的變更。

Bullet Points

使用者提供粗略的要點，例如：

  • "improved search"
  • "fixed crash on launch"
  • "added sleep timer"

Free Text

使用者以口語方式描述變更：

"We made search faster, fixed that annoying crash when you open the app, and added a sleep timer feature"

Skill 會從文字中擷取並結構化這些變更。

No Input Provided

提示使用者："What changed in this release? You can paste git log output, bullet points, or just describe the changes."

Phase 2: Draft Notes (Primary Locale)

Step 1: Classify Changes

依據指南將變更分組至各章節：

  • New — 全新的功能或能力
  • Improved — 對既有功能的強化
  • Fixed — 使用者會察覺到的 Bug 修復

省略空白的章節。若所有變更皆為修復，則僅顯示 "Fixed"。

Step 2: Write Benefit-Focused Copy

遵循 references/release_notes_guidelines.md 中的語氣規則：

  • 描述對使用者的實際影響，而非技術實作細節
  • 使用第二人稱直接稱呼（"您" / "你"）與行動動詞
  • 切中要害 — 提及具體的改善點

Step 3: Front-Load the Hook

前 ~170 個字元是點開 "更多" 之前唯一可見的部分。用一句完整、吸引人的句子，率先打出最具影響力的單一變更。

Step 4: Echo Keywords for Conversion

  1. 從 metadata/version/{latest}/{primary-locale}.json 讀取 keywords
    • 這些標準檔案也是 asc metadata keywords ... 讀取與寫入的對象。
  2. 若該欄位為空或不存在，跳過此步驟
  3. 識別與目前描述的變更相關的關鍵字
  4. 將關鍵字自然融進更新說明中 — 絕不硬塞或洗關鍵字

Step 5: Respect Character Limits

  • 主要語系的總字數保持在 500–1500 個字元之間
  • 這能為在地化翻譯預留擴充空間（某些語言翻譯後字數會膨脹 30-40%）
  • 上限硬性限制：4,000 個字元

Step 6: Optionally Draft Promotional Text

若使用者需要，可撰寫一段 170 字元以內的宣傳文字（Promotional Text）：

  • 用一句精練簡短的話概括本次更新的主題
  • 可引用季節性活動
  • 無需重新送審 App 即可隨時更新

Present Draft

向使用者展示草稿並附上字數統計。等待使用者確認核可後再進行在地化。

Phase 3: Localize

將核可的更新說明翻譯至所有現有的語系。

Translation Rules

  • 使用正式語氣與尊稱（俄文：вы、德文：Sie、法文：vous、西班牙文：usted、荷蘭文：u、義大利文：Lei）
  • 依當地市場調整語氣 — 英文活潑輕鬆的語氣在較正式的市場（如 ja、de-DE）可能需要調整
  • 切勿直譯成語或俗語 — 應替換為當地對等的表達方式
  • 英文中活潑輕鬆的語氣，在其他文化中可能需要更加尊重或正式

Locale-Specific Keyword Echo

針對每個語系：

  1. 從 metadata/version/{latest}/{locale}.json 讀取 keywords
  2. 在翻譯後的更新說明中自然融入該語系專屬的關鍵字
  3. 若關鍵字欄位為空，跳過該語系的關鍵字植入

Validate

  • 所有翻譯版本必須 ≤ 4,000 個字元
  • 每個語系的宣傳文字必須 ≤ 170 個字元
  • 若翻譯超出限制，請進行裁減 — 切勿在句子中途直接截斷

Phase 4: Review & Upload

Step 1: Present Summary

顯示包含所有語系及其更新說明、字數統計的表格：

| Locale | What's New (first 80 chars...) | Chars | Promo Text | Chars |
|--------|-------------------------------|-------|------------|-------|
| en-US  | Search just got faster — ...   | 847   | New sleep… | 142   |
| ar-SA  | البحث أصبح أسرع — ...           | 923   | نوم جديد…  | 138   |
| ...    | ...                           | ...   | ...        | ...   |

Step 2: Wait for Approval

未獲得使用者確認前，請勿進行上傳。

Step 3: Upload

透過 asc 上傳（使用 asc --help 確認精確語法）：

# 單一語系直接更新
asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "en-US" --whats-new "Your release notes here"

# 寫入 ./metadata/version/<version>/<locale>.json 後進行批量標準 metadata 推送
asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata" --dry-run
asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata"

若有撰寫宣傳文字，可在直接更新命令中加入 --promotional-text "..."，或在執行 asc metadata push 之前將 promotionalText 寫入標準 JSON 中。

Step 4: Handle Failures

當部分上傳失敗時：

  • 回報哪些語系上傳成功，哪些失敗
  • 提供重新嘗試失敗語系上傳的選項

Metadata File Paths

  • Keywords： metadata/version/{latest-version}/{locale}.json → keywords 欄位
  • Current What's New： metadata/version/{latest-version}/{locale}.json → whatsNew 欄位
  • Latest version： metadata/version/ 下最高 semver 版本號的目錄
  • 標準 ./metadata 目錄樹即為 asc metadata pull、asc metadata push 及 asc metadata keywords ... 操作的對象。
  • 遵循與 asc-aso-audit 相同的 metadata 解析慣例

Notes

  • What's New 不會被納入 App Store 搜尋索引 — 請為人類讀者撰寫，而非演算法。
  • 宣傳文字（Promotional Text）是唯一無需提交新版本即可更新的 metadata 欄位。
  • 點開前的 170 個字元可見視窗是更新說明中最關鍵的部分。
  • 每次 App 更新都會觸發演算法重新評估 — 更新這個動作本身就有意義，即使文字不直接影響排名。
  • 理想的更新頻率：每 2–4 週一次。
  • 如需完整 metadata 翻譯（所有欄位），請改用 asc-localize-metadata。
  • 如需進行關鍵字研究與最佳化，請先使用 asc-aso-audit。
  • 若撰寫前本地關鍵字欄位已過期，請使用 asc metadata pull 重新整理，或使用 asc metadata keywords diff 檢視預計變更的關鍵字。