Elsa 发布公告写作规范：Discord / LinkedIn / X 多渠道公告包的风格指南与发布工作流

• 后端
• 工作流自动化
• 流程编排
• 低代码

导读

本文基于 .agents/skills/elsa-release-announcements/references/style.md 及其配套的发布脚本、配置与测试，系统讲解 Elsa 项目（The Workflow Engine for .NET）发布新版本时如何撰写并发布多平台公告。你将掌握：公告包的固定结构与各章节职责、Discord / LinkedIn / X 三套渠道的差异化文案风格、稳定版与预览版 / RC 公告的措辞边界，以及公告发布前的验证前置条件与发布后的回执校验流程，可直接用于 Elsa 版本发布后的标准公告撰写与投递。

公告包结构：一份草稿，五个章节

style.md 规定公告应以Announcement Pack（公告包）的形式产出，即一个统一的 Markdown 草稿文件，按固定顺序包含以下五个章节：

# Elsa <version> Announcement Pack ## Facts ## Discord ## LinkedIn ## X single-post option ## X thread option ## Links

其中：

• Facts：记录本次发布的客观事实，如产品名、版本号、发布类型（stable / preview / rc）、发布链接，供人工核稿与后续流程引用。
• Discord / LinkedIn / X：三套针对具体渠道定制的文案。同一份事实基础，按渠道习惯重新组织语气、信息密度与结构。
• X single-post option 与 X thread option：同时给出"单帖"与"多帖串"两种备选形态，由发布时按信息量决定使用哪一种。
• Links：集中列出发布链接、包 / feed 链接与文档 / 迁移链接，方便各渠道引用。

配套的生成脚本 .agents/skills/elsa-release-announcements/scripts/announcement_pack.py 会自动把上述章节拼装成一份完整草稿：它读取一份经过整理的 release notes Markdown，从中提取 "Highlights" 小节下的-列表项（最多 5 条）作为亮点，并依据--release-kind（stable/preview/rc）自动渲染各渠道的可用性措辞。脚本支持如下参数：

从源码看，extract_highlights通过正则^##\s+.*Highlights\s*$定位 Highlights 小节并把每条-列表项中的 Markdown 链接与反引号清洗成纯文本，这正是"先机器生成、后人工精修"流水线的一环——脚本生成的草稿末尾还带有一行注释<!-- Review, tighten, and approve before publishing. -->，提醒发布前必须人工审核。

渠道风格指导：同样的发布，不同的说法

style.md 针对三个渠道给出了明确的风格差异要求：

• Discord：可以直接、有庆祝感、讲实用信息——发布内容、重点变更、包可用性与链接。表情符号优先使用 Discord 短码（如:rocket:、:point_right:、:sparkles:、:tools:、:test_tube:）而不是原始 Unicode emoji，以保证跨客户端渲染一致。
• LinkedIn：从"开发者价值"与"项目进展"角度解释本次发布，弱化实现细节，更强调它带给构建者的意义。
• X（Twitter）：追求极简；当有效信息点超过两个时，使用帖子串（thread）而不是单帖硬塞。

此外，style.md 规定了与发布状态强相关的三条边界：

1. 稳定版只有在确认 NuGet 发布成功后，才可以说"包已可用"；
2. 预览版 / RC必须明确说明自己是 preview / RC，面向测试与验证，不得暗示生产稳定性；
3. Discord 公告应抑制链接预览——通过 webhook 的SUPPRESS_EMBEDS消息标志实现，且链接要用尖括号包裹（如<release-url>），避免预览卡片抢占版面。

这些约束在源码中得到了一致落实：announcement_pack.py 的availability_text()对三种发布类型分别输出："Packages are available on the configured feeds."（仅 stable 且已提供包链接时）、"This is a preview release intended for early validation."（preview）、"This is a release candidate intended for final validation before stable release."（rc）。render_validation_note()则对 stable 输出 "Feedback welcome" 并向用户征集升级问题与回归报告，对 preview/RC 输出 "Please test it" 并明确其仅用于测试验证。

Discord 模板：一套可落地的标准文案骨架

style.md 给出了 Discord 草稿的标准形状，发布时按实际版本填充细节：

:rocket: **Elsa Workflows 3.7.0 is here!** We've published the stable **Elsa 3.7.0** release across **Elsa Core** and **Elsa Studio**. :point_right: Core: <core-release-url> :point_right: Studio: <studio-release-url> This release brings a solid set of improvements around **authentication**, **workflow diagnostics**, **Studio extensibility**, and the **modular server runtime**. ### :sparkles: Highlights :closed_lock_with_key: **Modern authentication support in Elsa Studio** Summarize the high-value change in one or two practical sentences. :compass: **Improved workflow instance diagnostics** Summarize the most user-visible diagnostics improvements. :jigsaw: **Modular server runtime improvements** Summarize the Core/runtime changes. ### :tools: Upgrade notes Call out compatibility or dependency changes users should validate. ### :raised_hands: Feedback welcome Ask users to report upgrade issues, regressions, and bugs.

模板的核心要素可以拆解为五块，这也是任何一篇 Discord 公告都必须回答的问题：

1. 标题行：<版本号> is here!，是公告的锚点；
2. 引言：说明已发布稳定版（或预览 / RC）及覆盖的产品范围（Elsa Core 与 Elsa Studio）；
3. 定位句：一句话概括本次发布的主题领域（示例中的 authentication、diagnostics、Studio extensibility、modular server runtime 仅是占位，实际应替换为真实发布主题）；
4. Highlights 小节：每条亮点用一行加粗主题词 + 一两句务实说明，前置一个语义相关的 Discord 表情短码；
5. Upgrade notes 与 Feedback welcome 小节：承担风险提示与反馈征集职责。

源码层面，announcement_pack.py 的render_discord()完整实现了这一骨架，并为亮点自动轮换分配表情短码：:closed_lock_with_key:、:compass:、:art:、:jigsaw:、:zap:、:bug:（见render_discord_highlights()的图标列表）。discord_heading()/discord_intro()则根据发布类型自动切换措辞：stable 用 "is here!" + "We've published the stable ..."，preview 用 "preview is here!" + "for early testing and feedback"，rc 用 "RC is here!" + "release candidate"。

发布前置条件：先验证，后宣布

公告写作不是发布流程的起点，而是终点。.agents/skills/elsa-release-announcements/SKILL.md 明确要求：必须基于 release train 的 manifests / 报告与真实发布状态来核实公开版本、确切版本号与所需的包 / feed 结果，绝不可以在只有上传任务或未合并的 PR 时就宣布可用。任何稳定版公告中声称的"包已上线"，其前提都是 NuGet 发布任务确实成功；预览 / RC 公告则必须明确标注自身性质，且只能宣称最终发布范围所支持的功能特性。

发布渠道的默认配置记录在 .agents/skills/elsa-release/references/elsa-profile.json 的announcements小节：

SKILL.md 规定发布前必须解析真实渠道：Discord 默认目标是 "releases" 公告频道，LinkedIn 是 Elsa Workflows，X 是 sfmskywalker，均通过配置的 Buffer 组织 Valence Works 投递；需要读取发布 profile 或显式覆盖，并自行发现频道 ID 与访问权限，禁止猜测私有 connector ID 或暴露凭据。

Discord 发布与安全恢复：幂等投递与跨频道发布

Discord 公告通过 .agents/skills/elsa-release-announcements/scripts/post_discord.py 投递。该脚本支持两种模式：

• Bot 模式：以--channel-id指定频道，默认从环境变量DISCORD_BOT_TOKEN_SUPPORT（可用--bot-token-env覆盖）读取 Bot Token；
• Webhook 模式：读取DISCORD_RELEASE_WEBHOOK_URL环境变量，省略--channel-id。

两种模式互斥，同时提供会直接报错。典型用法（先试跑、后执行）：

# 试跑：只打印将要发送的载荷，不发送 python3 <announcement-skill>/scripts/post_discord.py \ --message-file <run>/discord.md --channel-id <verified-channel-ID> \ --state-file <run>/discord-state.json --crosspost # 审核载荷后，在既有授权下正式执行 python3 <announcement-skill>/scripts/post_discord.py \ --message-file <run>/discord.md --channel-id <verified-channel-ID> \ --state-file <run>/discord-state.json --crosspost --execute

从源码看，这个脚本在"安全投递"上做了四层加固，这正是其可复用的价值所在：

1. 载荷合规：MAX_CONTENT_LENGTH = 2000（Discord 单条消息上限），超长直接拒绝；固定设置allowed_mentions: {"parse": []}禁用一切提及，flags: SUPPRESS_EMBEDS抑制链接预览。
2. 幂等去重：每次投递基于"模式 + 目标 + 是否 crosspost + 内容哈希"计算operation_nonce（格式elsa-release-<sha256 前 32 位>），随请求携带enforce_nonce: true；同一载荷重试不会产生重复消息。
3. 崩溃安全的状态机：--execute必须带--state-file。脚本先落盘intent状态再发请求，创建成功立即写回messageId与channelId（此写盘必须在任何 crosspost 请求之前），全程通过fcntl文件锁防并发。状态取值intent → created → crossposted → verified，异常路径落failed或ambiguous。
4. 歧义恢复与终局校验：若创建请求因 5xx 或连接中断而结果未知（HTTP 500+ 或网络层异常被视为"可能已创建"），脚本不会盲目重发——Bot 模式会按 nonce 拉取频道最近消息做对账，校验内容哈希与目标频道后复用已记录的消息 ID；webhook 模式没有可靠去重键，必须人工核查频道后再决定。最终verify_message()会 GET 回消息并逐项校验：内容完全一致、目标频道匹配、SUPPRESS_EMBEDS标志存在，若要求 crosspost 还必须确认CROSSPOSTED标志置位。

对于 Announcement Channel 的跨频道发布（crosspost），脚本调用 Discord 的/crosspost端点，且要求提供 Bot Token；跨帖成功后状态推进到crossposted，最终稳定在verified。

LinkedIn 与 X：经 Buffer 的意图持久化与回执验证

LinkedIn 与 X 的公告走 Buffer connector，由 .agents/skills/elsa-release-announcements/scripts/buffer_receipt.py 管理"意图"与"回执"，该辅助脚本本身从不发帖，只负责状态编排。流程为：

# 1. 写入精选文案，并持久化发布意图 python3 <announcement-skill>/scripts/buffer_receipt.py begin \ --state-file <run>/linkedin-state.json --platform linkedin \ --channel-id <discovered-ID> --message-file <run>/linkedin.txt # 2. 调用 connector 的 create_post（mode: shareNow，schedulingType: automatic）， # 立即捕获返回的 post ID，并用 get_post 获取该 ID 的完整结果 # 3. 校验并归一化回执 python3 <announcement-skill>/scripts/buffer_receipt.py record \ --state-file <run>/linkedin-state.json \ --response-file <run>/linkedin-get-post.json \ --receipt-file <run>/linkedin-receipt.json

record的校验非常严格：connector 返回必须是status: sent、无error、含非空externalLink、sentAt与id，且channelId与内容 SHA-256 哈希必须与意图完全一致，否则拒绝生成回执。生成的 receipt 形如{"id": ..., "url": ..., "text": ..., "status": "sent", "error": null, "sent_at": ..., "platform": "linkedin"}，随后可交给release_train.py record-announcement记录到 release checkpoint。

针对中断或不确定的 Buffer 调用，begin对已存在的 pending 意图一律返回reconcile而绝不返回publish：先用已知 post ID 调get_post；若响应丢失，则用list_posts按精确频道与创建时间窗口完整翻页，逐条比对文本哈希。只有当 connector 以新鲜、完整的查询证据证明确实没有创建任何帖子时，才允许以--absence-evidence <run>/absence.json授权再次创建。absence 证据文件的结构为：

{ "observed_at": "<ISO-8601 timestamp with timezone>", "pages": [{ "request": {"channelIds": ["<verified channel>"], "createdAt": {"start": "<intent time or earlier>"}}, "response": {"edges": [], "pageInfo": {"hasNextPage": false, "endCursor": null}} }] }

其校验规则（见validate_absence()）包括：observed_at距今必须 ≤ 300 秒、必须覆盖意图时间至当前时刻的完整窗口、不允许按 status / tag / 排期过滤、翻页必须完整（hasNextPage: true时必须携带有效的endCursor继续）、一旦发现匹配帖子立即拒绝。换句话说，认证失败、观测超时、本地输出缺失都不是"未创建"的证据；任何 connector 故障都不构成公告已完成的理由，剩余动作必须留在 checkpoint 中并如实报告访问失败。

测试印证：脚本行为的自动化保障

仓库为上述两个发布脚本提供了对应测试，验证了核心安全语义：

• .agents/skills/elsa-release-announcements/tests/test_post_discord.py 用内置 HTTP 服务器模拟 Discord API（/api/v10/channels/123/messages等端点），覆盖创建、列表、crosspost 计数与"仅歧义一次"等场景，印证 nonce 对账与状态机在模拟网络故障下仍能正确恢复。
• .agents/skills/elsa-release-announcements/tests/test_buffer_receipt.py 覆盖了恢复语义的三个关键断言：begin对 pending 意图返回reconcile且已知 post ID 不可被 absence 清除；完整翻页且无匹配的 absence 证据才允许重新发布，但目标频道变更会被拒绝；分页不完整（hasNextPage: true且无后续页）或发现匹配帖子都会阻止二次创建。

从测试可以推断，这套发布体系的设计目标不是"发出去"，而是**"可证明地发出去且不重复发"**：每个渠道都要求终态回执（Discord 的 verified + CROSSPOSTED 标志、Buffer 的 sent + public link），任何不确定的中间状态都必须先对账、再行动。

结语：把公告当作可验证的交付物

综合 style.md、SKILL.md、publishing.md 与配套脚本，Elsa 的发布公告是一条完整的工程链路而非随意发挥：先由 release train 核实版本与包的真实状态，再由 announcement_pack.py 按标准骨架生成三渠道草稿，人工按 style.md 的渠道风格精修后，分别经 post_discord.py（幂等 + crosspost + 终局校验）与 buffer_receipt.py（意图持久化 + 回执验证）投递，并将回执记入 release checkpoint。对社区维护者而言，这套规范最值得借鉴的是它的措辞纪律（稳定版与预览 / RC 的表述边界）与投递安全机制（nonce 幂等、状态机、absence 证据），它们让"发布公告"这个看似琐碎的动作具备了可审计、可恢复、不重发的工程品质。

如需进一步了解发布链路的上游（版本、构建、包门禁），可阅读 .agents/skills/elsa-release/SKILL.md 与 .agents/skills/elsa-release/references/runbook.md。

• 后端
• 工作流自动化
• 流程编排
• 低代码