asc-whats-new-writer

asc 新内容文案撰写器

根据灵活的输入生成引人入胜的本地化版本说明。还可选择配合促销文案更新。

前提条件

• 已通过 asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata" 将元数据拉取到本地规范文件中。或者：用户手动提供关键词。
• 已配置上传身份验证（asc auth login 或 ASC_* 环境变量）。
• 除非用户另有指定，主要区域设置为 en-US。

开始之前

1. 阅读 references/release_notes_guidelines.md，了解语气、结构和示例。
2. 找出 metadata/version/ 下最新的版本目录（semver 最高）。所有元数据读取都使用此目录。
3. 列出该版本目录中的 JSON 文件，枚举现有区域设置。

阶段 1：收集输入

接受以下三种输入模式之一（自动检测）：

Git 日志

解析自上一个标签以来的提交：

# Find latest tag
git describe --tags --abbrev=0

# List commits since that tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges

过滤噪声：合并提交、依赖项升级、CI 更改、仅格式调整的提交。提取面向用户的更改。

项目符号列表

用户提供简要要点，例如：

• “改进了搜索”
• “修复了启动时崩溃的问题”
• “新增了睡眠计时器”

自由文本

用户以对话方式描述更改：

“我们加快了搜索速度，修复了打开应用时那个烦人的崩溃问题，还新增了睡眠计时器功能”

该技能会从文本中提取并整理更改。

未提供输入

提示用户：“此版本有哪些更改？您可以粘贴 git log 输出、项目符号列表，或者直接描述这些更改。”

阶段 2：撰写说明（主要区域设置）

步骤 1：归类更改

根据指南将更改分组到各个部分：

• 新增 — 新功能或能力
• 改进 — 对现有功能的增强
• 修复 — 用户会注意到的错误修复

省略空白部分。如果所有更改都是修复，则只显示“修复”。

步骤 2：撰写突出收益的文案

遵循 references/release_notes_guidelines.md 中的语气规则：

• 描述对用户的影响，而非实现细节
• 直接称呼用户，并使用行动动词
• 具体明确——提及实际改进

步骤 3：开篇突出重点

前约 170 个字符是在“更多”之前唯一可见的部分。用一个完整且引人入胜的句子开篇，介绍影响最大的更改。

步骤 4：融入关键词以提升转化率

1. 从 metadata/version/{latest}/{primary-locale}.json 中读取 keywords
   • asc metadata keywords ... 也会读取和写入这些规范文件。
2. 如果该字段为空或不存在，则跳过此步骤
3. 找出与所述更改相关的关键词
4. 自然地将关键词融入说明中——切勿生硬堆砌

步骤 5：遵守字符数限制

• 主要区域设置的总长度保持在 500-1500 个字符之间
• 这样可以为本地化扩展留出空间（某些语言会扩展 30-40%）
• 硬性上限：4,000 个字符

步骤 6：可选撰写促销文案

如果用户需要，可撰写一条 170 字符的促销文案，要求：

• 用一句有力的话概括更新主题
• 可以提及季节性活动
• 无需提交新版本即可更新

呈现草稿

向用户展示草稿及字符数。等待批准后再进行本地化。

阶段 3：本地化

将已批准的说明翻译成所有现有区域设置。

翻译规则

• 使用正式语体和正式的“您”称谓（俄语：вы，德语：Sie，法语：vous，西班牙语：usted，荷兰语：u，意大利语：Lei）
• 根据当地市场调整语气——轻松活泼的英语表达在正式市场中可能需要调整（ja、de-DE）
• 不要直译习语——应改用当地对应的表达方式
• 英语中轻松活泼的语气在其他文化中可能需要更加尊重或正式

区域设置专属关键词融入

对于每个区域设置：

1. 从 metadata/version/{latest}/{locale}.json 中读取 keywords
2. 在翻译后的说明中自然融入该区域设置专属关键词
3. 如果 keywords 字段为空，则跳过该区域设置的关键词融入

验证

• 所有翻译不得超过 4,000 个字符
• 每种语言的宣传文案不得超过 170 个字符
• 如果翻译超出限制，请缩短内容，切勿截断句子

第 4 阶段：审核并上传

第 1 步：呈现摘要

显示包含所有语言及其备注和字符数的表格：

| 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   |
| ...    | ...                           | ...   | ...        | ...   |

第 2 步：等待批准

未经用户确认，不得上传。

第 3 步：上传

通过 asc 上传（使用 asc --help 确认准确语法）：

# Individual locale direct update
asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "en-US" --whats-new "Your release notes here"

# Bulk canonical-metadata push after writing ./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 相同的元数据解析约定

备注

• App Store 搜索不会索引“更新内容”——面向用户撰写，而非算法。
• 宣传文案是唯一无需重新提交即可更新的元数据字段。
• 170 个字符的可见窗口是发布说明中最重要的部分。
• 每次更新应用都会触发算法重新评估——更新这一行为本身很重要，即使文本不会影响排名。
• 理想的更新频率：每 2–4 周一次。
• 如需翻译完整元数据（所有字段），请改用 asc-localize-metadata。
• 如需研究和优化关键词，请先使用 asc-aso-audit。
• 如果撰写文案前本地关键词字段已过时，请使用 asc metadata pull 刷新，或使用 asc metadata keywords diff 检查计划中的关键词变更。