DV-02 · 发布说明与迁移指南起草

① 场景引入

一、这件事现在是什么样

研发与开发者文档 · 真实业务触发

v2.1 正式版发布在即：DV-01 巡检出的 9 处客户在用漂移需要随版说明；其中 `/settlement/reconcile` 的返回结构变更属Breaking——集成方需要迁移指南；技术负责人要求发布包三件套齐备：面向客户的产品更新说明、面向开发者的迁移指南、面向内部客服的支持简报——三份材料三个受众，一个版本一次交付。

二、痛点 · 每条都有来源

1「发布 changelog 条目和更新参考文档是两件不同的事——团队普遍做了第一件就当完成了」依据 · Changelog 最佳实践：「发布 changelog 条目和更新参考文档是两件不同的事——团队普遍做了第一件就当完成了」2Breaking change标准管理：迁移期最低 6-12 个月（Stripe 用 12 个月）、Sunset/Deprecation 响应头做机器可读通告——而多数团队的迁移期是「发完就算」依据 · Breaking change 标准管理动作：迁移期最低 6-12 个月（Stripe 用 12 个月，Twilio 提前一整年通知）；用 RFC 8594 的 Sunset/Deprecation 响应头做机器可读通告；下线前监控旧端点流量3「没有 changelog 的API 在向开发者广播：我们随时可能弄坏你、我们不追踪自己的变更」——发布说明的欠账直接变成集成方的信任折损依据 · Changelog 的信任功能：「没有 changelog 的 API 在向开发者广播：我们随时可能弄坏你、我们不追踪自己的变更」；规范模板含 Deprecated/Added/Changed/Fixed/Security 分节4金融 API 里错误示例会转错钱且不可撤销——迁移指南里的示例代码质量是运营事故级风险依据 · 错误代码示例的后果分级：社交 API 里错误示例发错图只是尴尬，金融 API 里错误示例会转错钱且不可撤销——示例质量是运营事故级风险5一半开发者每周损失约 10 小时寻找基本信息——过时文档的代价由使用方和被咨询方双向支付依据 · Atlassian 2025 State of DevEx：一半开发者每周损失约 10 小时只为寻找干活所需的基本信息

三、换个做法之后

变化不在「快」，在「参与的角色」和「覆盖的范围」

✕ 现在的做法

• 「发布 changelog 条目和更新参考文档是两件不同的事——团队普遍做了第一件就当完成了」Breakingchange 标准管理：迁移期最低 6-12 个月（Stripe 用 12 个月）、Sunset/Deprecation 响应头做机器可读通告——而多数团队的迁移期是「发完就算」「没有 changelog 的 API 在向开发者广播：我们随时可能弄坏你、我们不追踪自己的变更」——发布说明的欠账直接变成集成方的信任折损金融 API 里错误示例会转错钱且不可撤销——迁移指南里的示例代码质量是运营事故级风险

✓ 交给 Agent 之后

• 多来源文件一次读入，先做口径与完整性校验，再开始算
• 每条结论绑定来源文件、字段或条号，可以被审
• 产出是企业真会流转的正式件（带签批栏），不是一张展示用的表
• 该拦的地方给出「现在还不能提交」，并给不用干等的替代方案

四、场景闭环

5 步 · 每一步的产出都是下一步的输入

1. 变更分类登记本版全部变更按 Added/Changed/Deprecated/Fixed/Security 五分节归类
2. Breaking 判定与影响挂接逐条判定是否 Breaking；是则挂受影响集成方与端点级 diff
3. 迁移指南起草端点级变更说明 + 迁移示例（逐条验证）+ 弃用时间表建议
4. 三受众分别成稿客户版/开发者版/客服支持简报——同一事实三种讲法
5. 发布包汇编与签发流转三件套 + 通知范围建议，签发栏留空

要准备什么：DV-01 巡检报告（本期漂移台账）9 处客户在用漂移——发布说明的事实骨架本版合并记录与发版清单

Added/Changed/Deprecated/Fixed 的原始事实受影响集成方清单（联调工单+集成登记表）谁需要收到哪份材料——通知范围依据上一版发布说明（历史欠账对照）哪些「上次说要做」的这次真做了——口径连续性检查

为什么这个场景值得做

优先级评分：痛感 5 × AI 适配 3 ÷ 落地难度 2 = 7.5

最大差异点：发布包三件套面向三个受众分别成稿，不是一份文档改三遍格式：客户版讲「对你的影响」（无技术术语）；开发者版讲「怎么迁」（端点级 diff + 验证过的迁移示例 + 弃用时间表）；客服版讲「客户会来问什么」（预判问题清单 + 应答口径）。原料直接来自 DV-01 的漂移台账与合并记录，不重新考古。

评分口径：痛感看「这事没做好谁会生气、生气到什么程度」；

AI 适配看「输入是否非结构化、是否要跨部门取数、错了能不能当场看出来」；

落地难度是分母 —— 需要客户先做数据治理的场景，分数会被压得很低。

五、会产出什么

判断标准只有一个：这份东西能不能直接进企业的流程

• 正式件本体：发布包三件套.docx 正式件 · 客户版/开发者版/客服版 · 含弃用时间表建议与签发栏
• 可派发清单：迁移示例验证记录.xlsx 11 个示例 · 验证状态/验证日期/失败原因 · 未验证不进指南
• 可派发清单：受影响集成方通知范围表.xlsx 集成方 × 应收材料版本 × 建议发送时点 · 客户成功确认

这套东西不承诺什么：迁移指南的代码示例必须逐条经过可运行验证，未验证示例标注「草稿」；弃用时间表只起草建议（对照行业惯例给区间），正式承诺由产品与技术负责人签发；客户通知的发送范围与时间由客户成功确认，本场景只出材料不出发送动作。

② Live Demo（演示逐步）

演示模式 · 可视化预演 本页展示的是「应该怎么跑、每一步看什么、交付什么」，用的是真实业务格式的脱敏构造数据， 不宣称已接入客户生产系统，也不承诺任何效率提升百分比。

案例设定：明衡软件研发部。v2.2 发版在即：本版变更 39 项（Added 8 + Changed 12 + Deprecated 3 + Fixed 15 +

Security 1），其中 Breaking 1 项（/export/legacy v1 关停）；迁移示例 11 个验证中，集成方 6 家需通知。

输入文件4 份本版变更39 项 · 五分节Breaking1 项 · 弃期建议稿发版窗口下周二 · 三受众材料齐

输入软件公司手上能拿到的东西

不需要整理格式、不需要改文件名 · 直接拖进对话框

• 01_变更合并记录_v2.2.xlsx v2.2 版本全部合并记录归集——发布说明五分节的唯一数据源研发部导出 · 发版前冻结
• 02_API文档漂移台账_本周.xlsx DV-01 本周巡检产出——迁移示例与修复说明的素材来源（上游材料）研发部 · 本周巡检
• 03_迁移示例集_11个.xlsx 多币种与导出相关的 11 个迁移示例——每个都要过验证关研发部编写 · 发版前验证
• 04_集成方与材料版本.xlsx 受影响集成方清单——应收材料与版本要求（与 DV-01 在用清单同源）客户成功部维护 · 每月更新

注意标橙色那一份 —— 01_变更合并记录_v2.2.xlsx。它研发部导出 · 发版前冻结，平时压根不在核对范围里。这个场景的价值，很大一部分就来自把它读进来。

提示词就说这么几句

没有模板、没有表单 · 专业规则由 Skill 兜底

v2.1 正式版要发了。这是 DV-01 的巡检报告（9 处客户在用的漂移），这是本版全部合并记录，这是受影响的集成方清单，还有上一版的发布说明。 帮我出发布包三件套：

1. 客户版更新说明——只讲「对你的影响」，别堆技术术语。
2. 开发者版迁移指南——`/settlement/reconcile` 的返回结构变更是 Breaking 级，端点级 diff、迁移示例、弃用时间表都要有。示例逐条跑一遍，跑不通的标出来给我。
3. 客服支持简报——客户最可能来问的十个问题和应答口径。 上一版说了要上但这次还没合并的功能，别写进来。弃用时间表给建议稿，正式承诺那栏留空，我们自己定。复制五分节结构、Breaking 判定、三受众改写规则在能力包里；原料是 DV-01 台账与合并记录——发布说明从此是漂移台账的下游，不是又一次考古。 触发v2.2 发版在即 · 39 项变更要拆成三份材料发给三种人 发了 changelog 不等于更新了文档——这是两件事 客户看的是「这次多了什么」、开发者看的是「接口怎么迁」、客服看的是「明天会接到什么电话」——同一版变更，三份材料三个口径，原料都是同一份合并记录。 1变更五分节归集 · 39 项一项不落 发布说明的分节与行业通行惯例对齐——客户见过这种格式 分节数量客户可见度Added8客户版高亮Changed12开发者版逐条Deprecated3三受众都发 · 含弃期表Fixed15客户版摘要Security1客户版高亮 · 单独说明合计39—该拦的边界 · changelog 与文档更新分开对待最省事的做法是发一份 changelog 就当文档更新完了——changelog 记录「这一版改了什么」，文档站记录「现在是什么样」，两个问题两种答案。发版清单里文档更新是独立一项（DV-01 台账里的 9 处修复随本版进文档站），不靠 changelog 顶替。 2Breaking 1 项 · /export/legacy v1 关停的弃期建议稿 弃期承诺有依据、可签发、可追踪——但只出建议稿 接口处置弃期建议依据/export/legacy v1本版关停 · Breaking6 个月过渡期对照行业惯例 6-12 个月 · 使用方仅华驿 1家/report/legacy v1保留12 个月使用方珠江医药 · 改造成本高/fx/manual v0保留3 个月无集成方在用从历史里想起的「口头弃期」上一版关停 /export/batch 旧端点时，弃期是客户成功在群里口头说的「大概半年后关」——半年后客户炸群，翻遍文档站找不到书面依据。这次的弃期表进发布包、白纸黑字，建议稿给依据和区间，正式承诺由人签发——这条边界是信任的护城河。 3迁移示例 11 个 · 9 个已过验证，2 个待修正不进指南 金融级接口的示例质量第一次有了硬关卡 示例编号对应接口验证状态处理EX-01 ~ EX-08/settlement · /fx · /report 各端点通过 · 8 个进指南EX-09/export/legacy 迁移到 v2待修正修正并复验后补入EX-10/export/legacy 迁移到 v2待修正修正并复验后补入EX-11/report/legacy替代方案通过进指南合计11 个示例通过 9 · 修正 2—可以排除的「先发再修」「示例先随版发布、后面再补」可以排除——待修正的 2 个对应DV-01 台账里客户在用的示例失效项，错示例进指南等于把漂移从文档站搬进客户代码里。未验证示例不进指南，这条没有例外。 4三受众材料分发 · 客户版 / 开发者版 / 客服版

6 家集成方按影响分三档，客服拿到预判问题清单

受众材料要点发送时点客户版发布说明 · 客户摘要Added 8 高亮 + Security 单独说明发版当天开发者版迁移指南 + 变更明细Breaking 弃期表 + 9 个已验示例发版前 2 天客服版预判问题清单多币种咨询预案 + 弃期答疑口径发版前 1 天把发布日翻译成钱客服拿到预判清单，发布日的咨询洪峰第一次有预案而不是临时抓人——6 家集成方里强相关 3 家先收开发者版（含华驿的迁移时间表），常规 3 家收客户版即可。分档通知省下的不是邮费，是每一家「收到看不懂的材料」之后打进来的那通电话。

IO成稿 · 发布包三件套 + 验证记录 + 通知范围表

发布说明从此是漂移台账的下游，不是又一次考古

交付物格式状态发布包三件套docx客户版 / 开发者版 / 客服版 · 含签发栏迁移示例验证记录xlsx11 个 · 未验证不进指南受影响集成方通知范围表xlsx6 家 · 建议发送时点

弃用时间表只出建议稿 · 正式承诺由人签发这份发布包现在还不能直接签发：Breaking 项的 6 个月弃期是建议稿，写进客户通知的那一刻起集成方会按它排自己的年度规划——正式承诺由人签发。方案一：下周二发版按全套走——周五 6 家集成方先收通知（强相关 3 家带迁移时间表），EX-09/10 两个示例修正复验后补入指南，内部零新增投入。方案二：若把 2 个待修正示例直接随版发布——华驿按错示例写完迁移代码，返工加上联调窗口的占用，代价远超等两天修正复验；「先发再修」省下的两天，是用客户对文档站残存的信任付的账。

之后这一次跑完，公司多了什么

不讲省了多久：讲少了几个隐患、沉淀了什么

• ✓ 发布说明从「发完就算」变成三受众三份材料，changelog 与文档更新这两件事第一次被分开对待
• ✓ Breaking 变更拿到对照行业惯例的迁移期建议稿——弃期承诺有依据、可签发、可追踪
• ✓ 迁移示例 100% 过验证关——金融级接口的示例质量第一次有了硬关卡
• ✓ 客服拿到预判问题清单——发布日的咨询洪峰第一次有了预案而不是临时抓人

追问现场可能被问到的

答不上来的问题，比答得漂亮的问题更能决定这场演示的结果

• 发版频率高，每版都这么干会不会太重？ 三件套的重量是弹性的：无 Breaking 的常规版，客户版与客服版可以合并成一页；有 Breaking 的版本才走全套——分级本身就是这套流程的一部分。
• 弃用时间表为什么只出建议稿？ 因为它是承诺。写进客户通知的那一刻起，集成方会按它排自己的年度规划——建议稿给依据和区间，正式承诺由人签发，这条边界是信任的护城河而不是效率的负担。

③ 能力沉淀（Skill / 提示词 / 预期输出 / 人工边界）

1. Skill 能力包

导入之后，同类任务会自动按这套规则走 —— 提示词才能写得那么短

发布说明与迁移指南起草 —— 发了 changelog 不等于更新了文档，这是两件事 · Skill

SKILL.md 主本 + references（输出骨架 / 判据 / 渲染脚本）· 符合 WorkBuddy Skill 规范

版本 v1.0

release-notes-and-migration-guide.zip

在 WorkBuddy 里直接上传这个 zip 即可导入

包内结构

• SKILL.md 主本 —— YAML 元信息 + 执行流程 + 硬规则 + 人工边界
• references/output_template.md 输出骨架（sheet 名 / 分区顺序 / 列头）+ 可直接运行的渲染脚本
• references/judgement_rules.md 判据与口径 —— 什么情况算异常、什么情况必须拦住

references 不会一次性全读进来 —— Agent 按需取用。所以 Skill 可以写得很细，不会拖慢每次对话。

2. 原始素材

这些就是软件公司手上真实能拿到的东西 —— 格式不统一是常态，不是问题

📁DV-02 · 演示素材

脱敏构造数据 · 真实业务格式 · 埋点可核验

共 4 份

• 01_变更合并记录_v2.2.xlsx v2.2 版本全部合并记录归集——发布说明五分节的唯一数据源
• 02_API文档漂移台账_本周.xlsx DV-01 本周巡检产出——迁移示例与修复说明的素材来源（上游材料）
• 03_迁移示例集_11个.xlsx 多币种与导出相关的 11 个迁移示例——每个都要过验证关
• 04_集成方与材料版本.xlsx 受影响集成方清单——应收材料与版本要求（与 DV-01 在用清单同源）

怎么用

• 把素材全部拖进 WorkBuddy 对话框（不需要整理格式、不需要改文件名）
• 粘贴下方提示词发送
• 拿到正式件初稿 —— 签批栏留空，推荐意见留空，由你填

3. 提示词卡片

v2.1 正式版要发了。这是 DV-01 的巡检报告（9 处客户在用的漂移），这是本版全部合并记录，这是受影响的集成方清单，还有上一版的发布说明。 帮我出发布包三件套：

1. 客户版更新说明——只讲「对你的影响」，别堆技术术语。
2. 开发者版迁移指南——`/settlement/reconcile` 的返回结构变更是 Breaking 级，端点级 diff、迁移示例、弃用时间表都要有。示例逐条跑一遍，跑不通的标出来给我。
3. 客服支持简报——客户最可能来问的十个问题和应答口径。 上一版说了要上但这次还没合并的功能，别写进来。弃用时间表给建议稿，正式承诺那栏留空，我们自己定。复制为什么这么短就够了 · 五分节结构、Breaking 判定、三受众改写规则在能力包里；原料是 DV-01 台账与合并记录——发布说明从此是漂移台账的下游，不是又一次考古。

换成你自己的业务：把素材换成你手上的真实文件即可。导入 Skill 之后，

该走几步、什么口径、什么情况必须拦住，Agent 自己知道 —— 你只需要说清这是什么事。

自己组织输入的三步法

• 用自然语言说清核心需求 —— 就按平时跟同事交代活的方式说：什么事、什么文件、什么要求。不用讲究格式。
• 调用 Skill 补齐专业规则 —— 导入本页 Skill 后，流程、口径、硬规则 Agent 自己知道。
• 用「增强提示词」补全遗漏 —— 输入框旁边有增强按钮，把随口说的话补成更完整的表述。

分工：自然语言负责「这是什么事」，Skill 负责「该怎么做」，增强提示词负责「别漏了什么」。

4. 预期输出

不方便现场跑的时候可以直接拿这份给客户看 · 与实跑结果同结构

📋正式交付物

带签批栏 / 冻结首行 / 开筛选 —— 判断标准是「能不能直接进企业的流程」

共 3 份

• DV-02_发布包三件套.docx 正式件 · 客户版/开发者版/客服版 · 含弃用时间表建议与签发栏
• DV-02_迁移示例验证记录.xlsx 11 个示例 · 验证状态/验证日期/失败原因 · 未验证不进指南
• DV-02_受影响集成方通知范围表.xlsx 集成方 × 应收材料版本 × 建议发送时点 · 客户成功确认

Skill 里固化了什么：`/settlement/reconcile` 拿到了 12 个月迁移期建议迁移示例第一次全部跑过一遍排除性结论把技术动作翻译成钱

输入清单：DV-01 巡检报告（本期漂移台账）9 处客户在用漂移——发布说明的事实骨架本版合并记录与发版清单Added/Changed/Deprecated/Fixed 的原始事实受影响集成方清单（联调工单+集成登记表）谁需要收到哪份材料——通知范围依据上一版发布说明（历史欠账对照）哪些「上次说要做」的这次真做了——口径连续性检查

人工边界：迁移指南的代码示例必须逐条经过可运行验证，未验证示例标注「草稿」；弃用时间表只起草建议（对照行业惯例给区间），正式承诺由产品与技术负责人签发；客户通知的发送范围与时间由客户成功确认，本场景只出材料不出发送动作。

升为客户真实案例还缺什么：客户当前真实输入文件（不要整理过的）岗位现行 SOP 与审批链（金额分档、谁签字）至少一次真实出过问题的案例客户当前正在用的正式输出模板客户确认的阈值口径（多少天算临期、多少金额算大额）

5. 同一角色下的其他场景

研发与开发者文档 · 产出即下一步输入

• DV-01 · API 文档与代码同步巡检：75% 的生产 API 和它们的规范对不上

上下游串起来就是完整链路。每一步的产出都是下一步的输入，不用在不同工具之间来回复制粘贴。

场景内容基于 WorkBuddy 产品能力整理，演示中的企业、人物与数据均为虚构，不代表任何客户的实际成效；痛点引用的公开来源已做脱敏处理。网页版由原资料转换，部分演示表格以原文形式展示。