prospective-release-notes

预期发行说明

选择某个时间范围的两个锚点分支，然后交由 Release Notes SOP 处理。 锚点选择范围仅限应用的默认应用组——明确排除 Service Pack 热修复组，以免周中热修复影响比较结果。

执行方式

此技能专为在非交互环境中按计划无人值守运行而设计。运行过程中没有调用方可供询问。每个遇到歧义、缺少输入或工具错误的步骤，都必须在 Agent 的输出中明确失败，并提供清晰、可自我说明的消息——操作员事后查看调度器日志，并使用更正后的输入重新运行。

不要猜测。不要选择“第一个匹配项”。要明确报错。

在交互模式下调用时（用户输入“为 生成每周发行说明”），遇到歧义时仍应遵循相同原则——但此时用户就在你面前，因此应输出错误并请他们消除歧义。

依赖项

• release-notes-generator 技能——在步骤 3 确认两个锚点都存在后，使用解析出的两个分支 ID 调用。

前提条件

• 组织名称和应用定义名称——两者都是必填项。应用名称仅在组织内唯一，因此即使组织显而易见，也不能省略组织名称。
• 时间范围： range_start（包含）和 range_end（包含）。如果未指定，默认为用户本地时区的上周一 00:00 → 上周日 23:59:59。

已发布的发行版位于 Datex Studio 市场中。它们与部署无关——“已发布”表示可供任何环境使用，并不意味着任何环境当前都在运行该版本。此技能读取市场元数据，不需要部署目标。

工作流

[Step 1: Resolve org / repo / defaultApplicationGroup]
dxs --output json organization search "<ORG_NAME>"
  → <ORG_ID> (fail hard on 0 or >1 match)
dxs --output json organization app list --org <ORG_ID>
  → find entry where name == <APP_NAME>
  → <REPO_ID>, <defaultApplicationGroupId>
  (fail hard on 0 matches)
        |
[Step 2: Collect release branches in the Default group]
dxs --output json source branch list \
  --repo <REPO_ID> --default-group --status published -n 0
        |
[Step 3: Pick the two anchors]
Sort filtered releases by releaseDate descending.
  last_before   = largest releaseDate strictly less than range_start
  last_in_range = largest releaseDate in [range_start, range_end]
        |
        +--- Outcome 1: no last_in_range     → emit "No releases …" and stop
        |
        +--- Outcome 2: last_in_range but no last_before
                                             → emit Initial Release note and stop
        |
        +--- Outcome 3: both exist           → Step 4
        |
[Step 4: Delegate]
Invoke release-notes-generator with --from=<last_before.id> --to=<last_in_range.id>
(Use `dxs source release-notes --enrich-workitems --output json` as the source call
 if the target skill wants structured data; otherwise pass the branch IDs and let
 release-notes-generator drive its own workflow.)
        |
[Step 5: Return]
Return the Technical + Customer notes as the agent's response. No persistence
to KB / file / chat — the caller decides downstream delivery.

步骤详情

步骤 1：解析 (orgId, repoId, defaultApplicationGroupId)

# 1a. Organization name → organization ID
dxs --output json organization search "<ORG_NAME>"

# 1b. Apps in that org
dxs --output json organization app list --org <ORG_ID>

从应用列表中，选择 name == <APP_NAME> 的条目，并记录其 id（即 <REPO_ID>）和 defaultApplicationGroupId。

必须失败的情况（不要猜测或选择第一个匹配项）：

• 缺少任一输入（组织名称或应用名称）。
• 组织搜索返回零个或多个匹配项。
• 在组织内查找应用时返回零个匹配项。

每条失败消息都必须包含搜索内容、返回结果以及调用方需要提供什么才能修正问题。例如：

“对 'Datex' 的组织搜索返回了 3 个匹配项：[1 Datex，47 Datex Demo， 88 Datex Partners]。请使用更具体的组织名称重新运行，或直接传入 组织 ID。”

步骤 1 结束时必须获得： <REPO_ID>（在步骤 2 中用作 --repo） 和 <defaultApplicationGroupId>（在步骤 2 中用作客户端安全检查）。

步骤 2：收集默认组中的发行分支

dxs --output json source branch list \
  --repo <REPO_ID> --default-group --status published -n 0

• --default-group 将范围限定为仓库的 Default 应用组（排除 Service Pack 组）。
• --status published 限定为 applicationStatusId=3 的分支。 较早的发行版不会降级——它们仍保持 PublishedMain 状态，并通过 releaseDate 和 isLatest 区分。
• -n 0 禁用分页，以便返回所有发行版。

每个发行版需要关注的字段：id、releaseDate、versionName、 marketplaceApplicationVersionId、isLatest。

无需在客户端筛选组——CLI 会在每个分支上标注已知组 ID，因此结果是确定的。（步骤 1 中记录的 defaultApplicationGroupId 仅作为安全检查保留，以防 CLI 未来发生变化。）

步骤 3：选择两个锚点分支

按 releaseDate 降序排列筛选后的版本。选择：

• last_before — releaseDate 严格小于 range_start 的条目中，releaseDate 最大的条目。
• last_in_range — releaseDate 满足 range_start ≤ releaseDate ≤ range_end 的条目中，releaseDate 最大的条目。

明确处理以下三种情况：

1. 没有 last_in_range — 该时间范围内没有发布版本。输出一行摘要：

   “ 在 <range_start> 和 <range_end> 之间没有发布版本。”

   停止。不要调用 release-notes-generator。

2. 存在 last_in_range，但没有 last_before — 首次发布。输出简短的初始版本说明，总结 last_in_range.versionName、releaseDate，以及分支记录中的任何 releaseNotes 文本。停止。不要调用 release-notes-generator——没有可供比较的基线。

3. 两者都存在 — 继续执行步骤 4。

步骤 4：委托给 release-notes-generator

调用 release-notes-generator 技能，并传入：

• --from = last_before.id
• --to = last_in_range.id

release-notes-generator 技能负责处理 比较 → 工作项 → 差异 → 依赖项 → 编写 流程，生成技术版和客户版，并应用强制要求的工作项链接、业务背景和作者要求。不要在此重复这些指导——交叉引用现有技能而不是重复内容，可以确保随着标准操作流程（SOP）的演进，两者保持同步。

如果操作人员希望为目标技能提供单个预先补充信息的结构化载荷，可以使用命令 dxs source release-notes --from <…> --to <…> --enrich-workitems --output json 获取——该命令在 dxs ≥ 0.5.4 时可用；低于此版本时，该载荷会静默地完全不报告依赖项更新。否则，只传入分支 ID 并让 release-notes-generator 运行自己的命令也可以，这是默认方式。

步骤 5：返回说明

将技术版和客户版说明作为 Agent 的回复返回。此技能不会将输出保存到知识节点、文件或消息渠道——由调用方（调度程序、用户、下游自动化）决定如何交付。

提示

1. 时区。 releaseDate 为带偏移量的 ISO 8601 格式。在比较之前，将它与 range_start/range_end 转换为相同的时区（UTC 最稳妥）。时区不一致可能导致某个版本被错误地纳入或排除在范围之外。
2. 服务包造成的干扰。 不使用 --default-group 时，dxs source branch list --repo <id> 会返回所有组中的分支，包括服务包。周中发布的服务包热修复可能会被选为 last_in_range，导致比较结果偏离。--default-group 可避免这种情况。
3. createdDate 与 releaseDate。 对于发布分支，两者只相差几毫秒，但此技能使用 releaseDate，因为它是语义上正确的字段，并且未来架构调整时也能保持稳定。
4. 幂等性。 对相同的 (app, range_start, range_end) 重复运行，会得到相同的锚点对，因为已发布的版本不可变。可以安全地重新运行。
5. 调度由外部负责。 Windows 任务计划程序、cron、Azure Functions 或手动调用，都会以相同方式触发此技能。调度不在此技能的范围内；此技能只说明被调用后要执行的工作。
6. 空白周很常见。 对于发布频率较低的项目，大多数周都会在步骤 3 中进入情况 1。“本周没有发布版本”是有效且预期的结果，并非失败。

示例会话

# Range: 2026-04-13 00:00 UTC → 2026-04-19 23:59:59 UTC
# Application: "thedevapp" in organization "Datex"

# Step 1
dxs --output json organization search "Datex"
# → id: 1 (Datex)

dxs --output json organization app list --org 1
# → name=="thedevapp": id=1, defaultApplicationGroupId=1

# Step 2
dxs --output json source branch list --repo 1 --default-group --status published -n 0
# → branches:
#     id=60  releaseDate=2026-01-06  isLatest=true
#     id=3   releaseDate=2025-10-23  isLatest=false

# Step 3 — anchors for [2026-04-13, 2026-04-19]
# last_before   = branch 60   (largest releaseDate strictly before range_start)
# last_in_range = none          (no release inside the range)
# → Outcome 1: emit "No releases between 2026-04-13 and 2026-04-19 for thedevapp" and stop.

# If last_in_range had existed, Step 4 would run:
#   invoke release-notes-generator with --from=60 --to=<last_in_range.id>

常见错误

错误	修复方法
静默选择第一个匹配的组织 / 应用	匹配项为 0 个或多于 1 个时直接报错；打印候选项及后续操作说明
未指定 --default-group	Service Pack 分支会混入列表，导致锚点偏移
使用 createdDate 而非 releaseDate 排序	使用 releaseDate——这是语义字段
缺少 last_in_range 时调用 release-notes-generator	结果 1：输出单行摘要后停止
忘记“首次发布”的情况	结果 2：输出 Initial Release 说明；不要与空内容进行差异比较
将输出保存在技能中	此技能仅返回文本；交付由调用方处理
范围比较时使用的时区不一致	比较前将所有时间转换为 UTC