hub-editor

Hub 编辑器

修改 Datex Studio hub 配置，以添加工具栏按钮、连接点击流程，并将报表或其他操作集成到 hub UI 中。

另请参阅： hub-creator——从头创建新 hub（此技能用于修改现有 hub）。

参考资料

• ../datex-studio-shared/branch-setup.md — 分支选择（各技能共用）
• ../datex-studio-shared/configuration-roundtrip.md — 规范的 dxs configuration get → extract .json → edit → upsert 往返流程，以及该流程可避免的静默清空错误
• ../datex-studio-shared/flow-code-patterns.md — $utils.isDefined()、日期默认值、$shell.Reports.open{ref}()
• references/hub-config-api.md — 基于规范往返流程的 hub 专属说明（以及 dxs api --raw / -D / -O 后备方案）
• references/toolbar-and-click-flows.md — toolbar[] 和 flows[] JSON 结构、clickFlowConfig 参考及常见模式

依赖项

• requirements-gathering 技能 — 如果尚无需求简报，则调用此技能生成
• function-creator 技能 — 如果点击流程尚未创建为 Datex Studio 函数，则调用此技能

CLI 状态

Hub 编辑通过 dxs configuration 完成——它是适用于所有平台配置类型（hub、grid、form、flow、footprintquerymanager、appconfig 等）的通用 CRUD 基元；运行 dxs configuration types 可列出全部类型。往返流程是 ../datex-studio-shared/configuration-roundtrip.md 中的规范做法。get -O 会写入完整的服务器信封；在执行 upsert 之前，必须提取其中的 .json 正文，否则推送会静默清空配置（此错误最初是在 hub 上发现的）：

dxs configuration get hub <configId> -b <branchId> -O envelope.json   # fetch (full envelope)
jq .json envelope.json > body.json                                    # extract inner body — REQUIRED
# edit body.json locally (toolbar[], flows[], …)
dxs configuration upsert hub -b <branchId> -D body.json               # push inner body

分支是事实来源；envelope.json / body.json 是一次性临时文件。没有 dxs hub 子命令，也不支持字段级补丁——你需要获取整个文档、编辑 JSON，再将整个文档推送回去。规范往返流程请参阅 ../datex-studio-shared/configuration-roundtrip.md，hub 专属详情请参阅 references/hub-config-api.md。

命名说明：dxs configuration 用于操作分支上的平台配置（hub、grid 等）。dxs config（也可用别名 dxs settings）用于操作存储在 ~/.datex/config.yaml 中的本地 CLI 设置。在同时讨论 dxs configuration 的上下文中，优先使用 dxs settings，以避免容易产生的混淆。

工作流

[Phase 1: Setup]
Follow branch-setup.md for branch selection
        |
[requirements brief in context?]
  +-----+-----+
  |            |
 YES          NO → invoke requirements-gathering
  |            |
  +-----+------+
        |
[Phase 2: Locate the hub]
Identify hub by reference name (e.g., inventory_hub)
        |
dxs source explore config <hub_ref> --branch <id>
  → extract: hub config ID
        |
[Phase 3: Fetch current hub configuration]
dxs configuration get hub <configId> -b <branchId> -O envelope.json
jq .json envelope.json > body.json          ← extract inner body (REQUIRED)
cp body.json body.json.orig                 ← save for diff
        |
[Phase 4: Plan the change]
What's changing?
  +------+------+------+
  |      |      |      |
 ADD   MODIFY REMOVE  RENAME
  toolbar       button       click flow
        |
[Phase 5: Click-flow prerequisite (if adding/changing a button)]
Does the target click flow function exist?
  +-----+-----+
  |           |
 YES         NO
  |           |
 use it    invoke function-creator
  |        (writes the .ts code,
  |         upserts the function,
  |         returns reference name)
  +-----+-----+
        |
[Phase 6: Edit body.json]
Modify toolbar[] and flows[] arrays per references/toolbar-and-click-flows.md
        |
[Phase 7: Validate locally]
python -m json.tool body.json > /dev/null   ← syntactic check
diff -u body.json.orig body.json            ← review the change
        |
[Phase 8: Push updated config]
dxs configuration upsert hub -b <branchId> -D body.json
        |
[Phase 9: Verify]
Reload the hub in the running app (or re-fetch and diff)
to confirm the change took effect

阶段详情

阶段 1：设置

按照 ../datex-studio-shared/branch-setup.md 操作。每条 dxs configuration 命令都需要分支 ID（-b/--branch）——在技能示例中明确传入；不要依赖隐式作用域。

阶段 2：定位 hub

你需要 hub 配置 ID（configId）。最简单的方式：

dxs source explore config <hub_reference_name> --branch <branch_id>

这会返回 hub 配置元数据，其中包括其 id。如果你不知道引用名称，可以按 hub 类型筛选配置列表：

dxs source explore configs --branch <branch_id> | grep -i hub

Hub 配置使用的 configurationTypeId 与数据源（6）和函数（9）不同。查看 dxs source explore configs 的输出，了解分支上正在使用的类型 ID。

阶段 3：获取当前 hub 配置

dxs configuration get hub <configId> -b <branch_id> -O envelope.json
jq .json envelope.json > body.json    # extract the inner body — see configuration-roundtrip.md
cp body.json body.json.orig           # diff target for Phase 7

get -O 会写入完整的服务器信封；upsert -D 只接受其中的 .json 正文。跳过提取步骤会将信封推回，并静默清空配置——请参阅 ../datex-studio-shared/configuration-roundtrip.md。务必从最新获取的配置开始操作，切勿编辑过时副本。hub 专属详情请参阅 references/hub-config-api.md。

阶段 4：规划更改

Hub 配置包含两个相互关联的数组：

数组	用途
toolbar[]	Hub 工具栏中显示的 UI 按钮——每个按钮都有一个 clickFlowConfig
flows[]	Hub 知道的 Datex Studio 流函数引用——每个从 clickFlowConfig 引用的流都必须列在这里

典型的“添加一个用于启动报告的工具栏按钮”更改会涉及两个数组：在 toolbar[] 中添加一个新条目，并在 flows[] 中添加点击流引用。JSON 结构和常见模式请参见 references/toolbar-and-click-flows.md。

阶段 5：点击流前提条件

Hub 工具栏按钮会将 Datex Studio 函数作为点击处理程序执行。如果目标点击流函数尚不存在，请先调用 function-creator。点击流代码通常会：

1. 从 $flow.inParams 读取 Hub 的日期范围／上下文输入
2. 为缺失值应用默认值——使用 $utils.isDefined() 设置日期默认值的标准模式，请参见 ../datex-studio-shared/flow-code-patterns.md
3. 使用已解析的参数调用 $shell.Reports.open{ref}()（或其他 shell 操作）

编写点击流时，请参考 ../datex-studio-shared/flow-code-patterns.md，以确保 function-creator 生成的代码使用 $utils.isDefined()（而不是 != null），并采用文档中所述的日期默认值代码块。

阶段 6：编辑 body.json

使用 JSON 编辑器或 jq 添加／修改条目。请遵循以下两条安全规则：

• 保留所有未修改的内容。 Hub 配置包含 UI 状态、版本标记以及与此次编辑无关的属性。dxs configuration upsert 会替换整个对象；缺失字段将被删除。
• 确保 toolbar[] 和 flows[] 保持一致。 toolbar[] 中的每个 clickFlowConfig.reference 都必须在 flows[] 中有对应条目，反之亦然。

阶段 7：在本地验证

python -m json.tool body.json > /dev/null      # JSON-parses?
diff -u body.json.orig body.json                # review actual changes

body.json.orig 已在阶段 3 中提取后立即保存——diff 是推送前唯一的结构审查手段。

阶段 8：推送更新后的配置

dxs configuration upsert hub -b <branch_id> -D body.json

推送提取出的内部 body（body.json），切勿推送原始的 envelope.json。-D/--data-file 标志会从文件读取 body，完全绕过 shell 转义，因此 JSON 中的 \r\n 序列和嵌入引号不再需要担心。

阶段 9：验证

重新获取配置并比较内部 body：

dxs configuration get hub <configId> -b <branch_id> -O envelope-after.json
jq .json envelope-after.json > body-after.json
diff -u body.json body-after.json

diff 应为空（或仅包含 updatedDateTime 等服务器端字段）。在运行中的应用里重新加载 Hub，确认新的工具栏按钮已显示，并且点击流可以正确触发。

常见操作

操作	更改内容
添加一个打开报告的工具栏按钮	在 toolbar[] 中添加一个新条目；在 flows[] 中添加点击流引用；可能需要创建点击流函数
更改按钮打开的报告	点击流函数代码（$shell.Reports.open{newRef}(...)）——如果流引用保持不变，则无需更改 Hub 配置
重命名／更改按钮标签	toolbar[].label（或等效的显示字段）——无需更改流
移除按钮	从 toolbar[] 中移除该条目，并从 flows[] 中移除对应的（现已孤立的）引用
重新排列按钮	重新排列 toolbar[] 条目

关键规则

• 在 upsert 前提取内层 .json 正文。 get -O 会写入完整封套；使用 jq .json envelope.json > body.json。推送原始封套会悄无声息地清空配置——参见 ../datex-studio-shared/configuration-roundtrip.md。
• 切勿编辑过时的 body.json。 编辑前务必使用 dxs configuration get hub 重新获取——其他用户或版本可能已经修改了 hub。
• dxs configuration upsert 会替换整个配置。 不要省略任何你并非有意更改的字段。
• toolbar[] 和 flows[] 必须保持同步。 工具栏按钮若没有对应的 flow 条目就不会触发；孤立的 flow 条目无害，但应清理掉。
• 点击 flow 代码必须使用 $utils.isDefined()——参见 ../datex-studio-shared/flow-code-patterns.md。原生 null 检查不适用于 Datex Studio 的值模型。
• $shell.Reports.open{ref}() 的参数键区分大小写，且必须与报表的 ReportParameters[].Name 完全一致。
• 提取后保存 body.json.orig。 这是推送前唯一的差异比较目标。

常见错误

错误	修正方法
将 get -O 得到的原始 envelope.json 直接推送给 upsert -D	会悄无声息地清空 hub（toolbar/flows/onInitFlowConfig 重置为 null）。先提取：jq .json envelope.json > body.json，再运行 upsert -D body.json。参见 configuration-roundtrip.md
尝试使用 dxs hub get / dxs hub update	这些命令不存在。请使用 dxs configuration get hub / dxs configuration upsert hub
使用 dxs config get <id> 获取 hub	dxs config（别名 dxs settings）用于操作本地 CLI 设置，而非平台配置。请使用 dxs configuration get hub <id> -b <branchId>
阅读 endpoints.py 手动拼接 URL	dxs configuration 涵盖 KNOWN_TYPES 中的所有类型——不再需要 URL 模式。对于 dxs configuration 未涵盖的端点，请使用 dxs api
尝试使用 dxs api --save	该标志从未存在过。请在 dxs api 中使用 -O/--output-file（写入原始 JSON），或使用 dxs configuration get ... -O
对于较大的正文，改用 Python httpx.put() 辅助程序	不再需要。dxs configuration upsert -D <file> 和 dxs api PUT -D <file> 都会从文件读取正文，避免 shell 转义问题
使用 `dxs api GET ...	tail -n +2` 去除前导文本
忘记在 dxs configuration 命令中添加 -b/--branch	此标志为必填项。请在每个示例中显式传入
在 toolbar[] 中添加按钮，却未在 flows[] 中添加对应条目	按钮会显示，但不会触发。两个数组都必须引用该点击 flow
在点击 flow 代码中使用 != null 或 !startDate	请使用 $utils.isDefined(startDate)——Datex Studio 的值模型无法与字面量 null/undefined 进行可靠比较
$shell.Reports.open{ref}() 中的参数键不匹配	键区分大小写，且必须与报表参数的 Name 值完全一致。键不匹配时，参数会被悄无声息地留空
推送缺少原始配置字段的已编辑配置	upsert 会替换整个对象；省略的字段会被删除。务必从最新的 get 结果开始，只修改你确实要更改的内容

---

编辑完成后，请调用 post-edit-verification，以发现描述/JSON/架构违规。最终审核时，请调用 component-validator。