package-cascade

Package Cascade

将已发布的包变更沿依赖图向上传播：对每个引用该包的包（ComponentModule）重新固定版本并重新发布，递归执行，直到应用为止（应用会报告为过时，但绝不会自动发布）。此技能基于 dxs source cascade 命令，提供轻量的交互式编排。

必要背景

• ../datex-studio-shared/branch-setup.md — 分支与连接选择
• references/cascade-workflow.md — 包含精确 dxs 命令的分阶段操作手册
• references/plan-schema.md — 级联计划的 JSON 结构
• references/interaction-patterns.md — 树形呈现、选择／缩减提示、进度说明
• references/troubleshooting.md — 发布失败、锁、冲突、恢复

何时使用／不使用

当源包已经发布且你想更新它的使用方时使用。用户自行修改、提交并发布源包；此技能从已发布的版本开始接手。

不适用于：编写包变更本身（使用 component-creator skills）、分析单分支调用方（使用 impact-analysis），或检查正向依赖（dxs source deps）。

职责划分（不可越界）

CLI 负责所有确定性工作：图遍历、拓扑排序、传递引用重建，以及冲突／环检测，都由 dxs source cascade plan 和 dxs source reference set 完成。此技能负责交互：呈现计划，询问全部执行还是仅执行子集（包括从 --select 中取消选择某个包时，沿计划自身的 updates 边移除其依赖方——CLI 会严格按你的选择执行，否则会在运行中途报错），驱动执行并汇报。绝不要手动编辑 AppConfig JSON，绝不要自行计算更新顺序，也不要用文字推理传递闭包——应交由 dxs 处理。如果你想对 appConfig 使用 jq，请停下：这项工作应由 dxs source reference set 完成。

工作流

Phase 0  Establish origin+org  — user names the package; resolve its uniqueIdentifier (dxs marketplace
         search "<name>" --type componentmodule, or marketplace list --type componentmodule to browse) and
         pass the RESOLVED uid to -p, never the display name the user typed (see safety gates); take the
         newest published version from the user; pick the target org (auto only when the user sees exactly
         one AND didn't name a different one — if they name an org you're not logged into, confirm + switch
         identity via dxs auth login, see references); CONFIRM (a wrong version poisons every pin, a wrong
         org syncs the wrong tenant).
Phase 1  Plan                  — dxs -O json source cascade plan -p <uid> -v <version> --org <orgId>
Phase 2  Present & select      — render the tree; ask ALL / subset / review-only (see
         references/interaction-patterns.md); a cycle or conflict = hard stop.
Phase 3  Execute bottom-up     — dxs source cascade run --plan plan.json [--select …];
         narrate each republish (n of N).
Phase 4  Report                — republished packages (+ new versions) and stale applications
         to update separately.

每个阶段的精确命令请遵循 references/cascade-workflow.md。

相关技能

• datex-studio-shared — 分支与连接设置（参见上文“必要背景”）。
• release-notes-generator — 起草你在第 3 阶段传给 --release-notes "<notes>" 的文本；请记住，该文本会在本次运行中原样应用于每个重新发布的节点，而非按节点分别应用。
• commit-message-generator — cascade run 始终写入固定的提交信息（chore(deps): cascade update <uid>），且没有 --commit-message 标志，因此只有当你跳过 cascade run，手动调用各节点原语（branch commit）以自定义信息时，才需要使用此相关技能——这是当前的限制，并非默认路径。手动方式需要使用 -f 跳过 branch commit 的确认提示（dxs ≥ 0.4.19），并使用 --dry-run 进行预览；请参阅 references/cascade-workflow.md。

安全门禁

• 在制定计划（Phase 0）之前，确认源包、版本和目标组织。 版本错误会导致所有固定版本都出错；组织错误则会同步到错误的租户。
• -p 必须使用解析后的 uniqueIdentifier，不能使用显示名称。 uniqueIdentifier 会从名称中去除空格和下划线（显示名称 pkg_cascade_mid → uid pkgcascademid），而 cascade plan 会通过精确匹配来查找，因此显示名称即使看起来已经是 ID 格式（例如 pkg_cascade_leaf），也不会匹配到任何包，并会返回一个看似“无需处理”的空计划。请传入 marketplace search 返回的确切字符串；使用 dxs source referenced-from <uid> --org <id> 检查确认。
• Cascade 是单租户的——Phase 1 会传入 --org <id>，因此只会规划目标组织中的包。其他租户中的使用方会被排除（而且也无法重新发布；发布权限仅限所属组织）。
• 目标组织可能不是当前登录的组织。 organization list 只会显示当前身份的租户，而 cascade plan 会以只读方式跨租户遍历，因此即使你无法向某个组织发布，也可能成功为其生成计划——直到执行 run 时才会失败（mainApplicationId 返回 404）。如果用户指定的组织不可见，不要默默回退到可见组织，也不要先生成计划再失败：确认目标组织，确认切换操作，然后运行 dxs auth login --tenant-id <tenantId> 登录该租户。 在 dxs ≥ 0.5.0 中，如果已有该租户的身份缓存，登录会立即返回；否则会打开浏览器供用户完成登录——只有在无头模式下，或传入 --use-device-code / --no-browser 时，才会输出设备代码。请参阅 references/cascade-workflow.md 的 Phase 0 第 3a 步，以及 references/interaction-patterns.md →“目标组织不是当前登录的组织”。
• 绝不要假设分支或仓库 ID——计划会包含每个节点的 Main 分支 ID；应将其展示出来，不要猜测。
• 出现循环或版本冲突时必须停止。 cascade plan 会设置 cycleDetected；reference set 遇到冲突会中止。请报告问题，不要强行继续。
• 展示计划后，必须明确确认是否继续——用户作出选择之前，不会进行任何变更（Phase 2）。
• 应用永远不会自动发布——它们只会出现在 staleApplications 中。
• 保留失败记录以供检查——节点失败时，保留其功能分支，报告失败，并提供使用剩余节点的 --select 恢复执行。
• 发布权限——如果用户没有包发布权限，首次发布会失败；请提前说明。