根据 `./metadata` 目录下的标准元数据，从 git log、要点列表或自由文本中提取信息，生成吸引人且已本地化的 App Store 更新日志（What's New）。还可同步生成或更新宣传文本（Promotional Text）。
asc What's New Writer
灵活接收多种输入，生成吸引人且已本地化的 App Store 更新日志。可选同步撰写宣传文本（Promotional Text）。
前提条件
- 已通过
asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata"将元数据拉取到本地标准文件中；或者用户手动提供了关键词。 - 已配置上传所需身份认证（通过
asc auth login或设置ASC_*环境变量）。 - 除非用户另行指定，默认**主语言环境（Primary locale）**为
en-US。
开始之前
- 阅读
references/release_notes_guidelines.md，了解语气风格、规范结构和参考示例。 - 识别
metadata/version/下的最新版本目录（最高 semver 版本号）。后续所有元数据读取均以此目录为准。 - 通过列出该版本目录下的 JSON 文件，梳理出现有语言环境（Locales）列表。
阶段 1：收集输入
支持以下三种输入模式（系统自动检测）：
Git Log
解析自上一 tag 标记以来的 commit 记录：
# 查找最新 tag
git describe --tags --abbrev=0
# 列出该 tag 之后的所有 commit
git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges
过滤无关信息：排除 merge commit、依赖更新、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 会自动从文本中提取并结构化整理变更内容。
未提供输入
主动询问用户：“本次版本更新了哪些内容？您可以直接粘贴 git log 输出、提供更新要点，或者用自然语言描述。”
阶段 2：撰写草稿（主语言环境）
步骤 1：变更分类
根据规范将变更划分到不同分组：
- 新增（New） — 新功能或新能力
- 优化（Improved） — 对现有功能的改进
- 修复（Fixed） — 用户感知的 Bug 修复
隐藏空分组。若全部变更均为修复类，则仅展示“修复”。
步骤 2：撰写以用户价值为核心的文案
遵循 references/release_notes_guidelines.md 中的语气规范：
- 描述对用户的具体影响，而非技术实现细节
- 使用第二人称（“您/你”）与祈使动词/行动词
- 保持具体 — 明确指出具体提升了什么
步骤 3：把最吸睛的钩子前置
在用户点击“更多”之前，仅前 ~170 个字符可见。务必用一句完整且极具吸引力的话，放在开头突出最重要的单项更新。
步骤 4：植入关键词提升转化率 (Echo Keywords)
- 从
metadata/version/{latest}/{primary-locale}.json中读取keywords字段- 这里的标准文件也是
asc metadata keywords ...命令读写的目标。
- 这里的标准文件也是
- 若该字段为空或不存在，跳过此步骤
- 找出与当前变更相关的关键词
- 将关键词自然融入文案中 — 绝不硬塞或堆砌
步骤 5：遵循字符限制
- 主语言环境下的总长度控制在 500–1500 个字符之间
- 预留出翻译膨胀空间（部分语言翻译后篇幅会增加 30%–40%）
- 硬性上限：4,000 个字符
步骤 6：可选撰写宣传文本（Promotional Text）
若用户需要，撰写一段 170 字符以内的宣传文本：
- 用一句干练的话概括本次更新主题
- 可结合节日/季节性活动
- 无需提交新版本审核即可随时更新
展示草稿
向用户展示包含字符统计的草稿，获得确认后再进行本地化翻译。
阶段 3：本地化翻译
将已获批的草稿翻译为所有现存语言版本。
翻译规范
- 使用正式语域和尊称称谓（如俄语：вы，德语：Sie，法语：vous，西班牙语：usted，荷兰语：u，意大利语：Lei）
- 针对本地市场调整语气 — 英语中俏皮诙谐的语气在讲究正式的语言环境（如日文 ja、德文 de-DE）下可能需要适当收敛
- 切勿机械直译谚语/俗语 — 改用当地地道表达替换
- 英语中较为轻松休闲的基调，在其他文化背景下可能需要转变为更具敬意或规范的形式
各语言特定关键词融入
针对每种语言环境：
- 从
metadata/version/{latest}/{locale}.json中读取keywords - 将对应语言的关键词自然融入翻译后的文案中
- 若关键词字段为空，跳过该语言的植入步骤
校验
- 所有翻译版本均不得超过 4,000 个字符
- 宣传文本在各个语言下均不得超过 170 个字符
- 若翻译超长，请进行精简削减 — 绝不能在句子中间硬截断
阶段 4：审核与上传
步骤 1：展示汇总表
向用户展示包含所有语言版本、更新内容摘要及字符统计的表格：
| Locale | What's New (前 80 字...) | 字符数 | Promo Text | 字符数 |
|--------|-------------------------------|-------|------------|-------|
| en-US | Search just got faster — ... | 847 | New sleep… | 142 |
| ar-SA | البحث أصبح أسرع — ... | 923 | نوم جديد… | 138 |
| ... | ... | ... | ... | ... |
步骤 2：等待用户确认
未经用户明确确认，不得擅自上传。
步骤 3：上传
使用 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 后批量推送标准元数据
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 文件中。
步骤 4：失败处理
若发生部分语言上传失败：
- 明确报告哪些语言环境上传成功、哪些失败
- 提供重试失败语言环境的选项
元数据文件路径规范
- 关键词：
metadata/version/{latest-version}/{locale}.json→keywords字段 - 当前更新日志：
metadata/version/{latest-version}/{locale}.json→whatsNew字段 - 最新版本：
metadata/version/目录下 semver 版本号最高的文件夹 ./metadata标准目录树是asc metadata pull、asc metadata push以及asc metadata keywords ...的指定作用对象- 遵循与
asc-aso-audit相同的元数据解析约定
注意事项
- What's New 内容不会被计入 App Store 搜索索引 — 请面向真实用户写作，而非面向搜索算法。
- 宣传文本（Promotional Text）是唯一无需随应用新版本提交审核即可随时更新的元数据字段。
- 展开“更多”前可见的前 170 个字符是更新日志中最重要的黄金位置。
- 每次发布 App 更新都会触发 App Store 算法重新评估 — 即使更新文本本身不直接影响排名，更新这一行为本身就很重要。
- 推荐更新频率：每 2–4 周更新一次。
- 如需进行全量元数据翻译（包含所有字段），请改用
asc-localize-metadata。 - 如需进行关键词调研与优化，请先使用
asc-aso-audit。 - 若起草前本地关键词字段陈旧，可通过
asc metadata pull刷新，或使用asc metadata keywords diff查看预期的关键词变更。
