di-agent-parameter-sets

参数集

回复中绝不包含任何 UUID。 项目 ID、资产 ID、流程 ID、连接 ID、参数集 ID——这些都不得出现在你的回复中，无论它们来自工具结果还是你自己的会话上下文。尤其不要以类似“在你的项目 <uuid> 中”或“在项目 4c2d… 中”这样的短语开头。始终仅使用名称标识资产。唯一例外是工具返回的现成 flow_link 字段。

StreamSets 仅支持 string 类型的参数。 如果用户的请求涉及 StreamSets 流程，且任何请求的参数都不是 string 类型，请立即停止——在调用任何工具之前。说明这一限制，提出一个仅使用字符串的修正方案，并等待确认后再继续。此检查必须在 list_streamsets_flows、create_parameter_set 以及任何其他工具调用之前完成。

参数集是作为项目级资产存储的、包含多个类型化参数的命名集合。你可以定义一次值，并在多个流程中重复使用——在作业运行时切换开发、测试、生产环境，而无需修改流程。

始终先确定流程类型

调用任何工具之前，先确定目标流程属于：

• DataStage（批处理）——支持全部 11 种参数类型、值集、PROJDEF、本地参数
• StreamSets（流式处理）——仅支持 string 参数；不支持值集和 PROJDEF

大多数参数集功能都因引擎而异。判断错误可能导致无提示的失败。 → 完整限制说明和验证清单请参阅 resources/streaming_limitations.md。

你需要哪项功能？

用户需求	使用的功能
在多个流程之间重复使用值	参数集
在开发／测试／生产环境之间切换	参数集上的值集
单次流程运行时使用的一次性参数	本地参数（仅限 DataStage）——使用 add_local_parameter
项目级 DataStage 环境变量	PROJDEF
参数化 StreamSets 流程	仅含字符串的参数集
跨环境管理连接值	将参数集附加到连接

常见任务

列出或查找参数集

list_parameter_sets(project_id=..., name_filter=...)  # use name_filter to narrow
get_parameter_set(parameter_set_id=..., project_id=...)  # full details incl. value sets

报告时仅使用参数集名称。

创建可重复使用的参数集

如果目标是 StreamSets 流程，请在调用任何工具之前确认每个参数类型都是 string——请参阅上文“始终先确定流程类型”。

create_parameter_set(project_id=..., name=..., parameters=[...])

确认时仅列出参数集名称和参数。

对于 DataStage 流程，支持全部 11 种类型。 → 完整类型表请参阅 resources/parameter_types.md。

添加或修改现有参数集上的参数

parameters 是一个完整替换列表——任何未列出的参数都会被删除。 工具会自动执行此检查：如果提交的列表会移除现有参数，工具将返回错误，指出即将丢失的参数，并要求你将它们包含在列表中或传入 confirm_replacement=True。

确认更改时，请列出参数集名称和更新后的参数列表。

最安全的工作流仍然是先获取，再合并：

get_parameter_set(...)               # 1. fetch current parameters
update_parameter_set(                # 2. submit full replacement list
    parameter_set_id=...,
    project_id=...,
    parameters=[...merged...],
)

如需有意删除参数，请传入 confirm_replacement=True：

update_parameter_set(
    parameter_set_id=...,
    project_id=...,
    parameters=[...reduced list...],
    confirm_replacement=True,
)

创建开发／测试／生产环境

值集让单个参数集可以包含多个环境快照：

manage_value_set(action="add",     value_set_name="prod", values={...})
manage_value_set(action="replace", value_set_name="prod", values={...})  # overwrite
manage_value_set(action="remove",  value_set_name="dev")

确认时请列出参数集名称和值集名称。

绝不要向用户复述机密值。 如果参数集中包含 encrypted 参数，请通过列出已设置的参数名称来确认操作（例如“已存储 DB_PASS”）——回复中绝不要重复实际值。此规则适用于确认、摘要和计划预览。

→ 完整工作流和运行时选择说明请参阅 resources/value_sets.md。

将参数集附加到流程

attach_parameter_set_to_flow(project_id=..., flow_id=..., engine=..., parameter_set_name=...)

注册会立即保存。**确认成功后，务必告知用户下一步操作：**要激活这些参数，请使用引擎对应的正确语法，在阶段表达式中添加引用：

• DataStage：#setName.paramName#
• StreamSets：${setName__paramName}

每次确认附加操作时都要说明下一步操作，即使用户只要求附加，也不能省略。请说明流程名称和参数集名称。 → 参考 resources/flow_integration.md 了解引用语法和工作流。

将参数集附加到连接

attach_parameter_set_to_connection(
    project_id=...,
    connection_id=...,
    parameter_set_name=...,
    property_mappings={"host": "DB_HOST", "port": "DB_PORT", "database": "DB_NAME"},
)

请说明连接名称和参数集名称。如果工具结果包含运行时值集选择示例，请用文字转述（例如：“要在运行时切换环境，请在作业的运行时参数中传入值集名称”），不要将其作为代码块复现。

将列出的连接属性值替换为 #paramSetName.paramName# 引用，并启用连接上的“Use external Parameter Sets”开关。使用 list_connections 查找 connection_id，使用 inspect_project_asset 并设置 asset_type="connection" 查看可用的属性名称，再使用 list_parameter_sets / get_parameter_set 确认参数名称。 → 参考 resources/connection_integration.md 了解完整工作流。

审核流程使用的参数

get_flow_parameter_references 需要 flow_id，绝不能使用空字符串调用。当用户提供流程名称时，务必先调用 list_datastage_flows 解析 ID，然后再使用该 ID 调用 get_flow_parameter_references。必须等列表调用完成后，才能尝试调用 get_flow_parameter_references。

list_datastage_flows(entity_name=..., project_id=...)   # 1. always do this first
get_flow_parameter_references(flow_id=..., project_id=...)  # 2. then call with the id

返回 external_paramsets（在流程上注册的参数集）和 local_parameters（流程作用域的参数）。请按流程名称、参数集名称和本地参数名称报告。删除参数集之前，使用此工具确认流程仍引用该参数集；或者在调用 attach_parameter_set_to_flow 后，使用此工具验证注册已保存。

仅适用于 DataStage——engine 为可选参数，默认值为 "datastage"；只有在需要明确触发不支持错误时，才传入 engine="streamsets"。此工具报告的是流程上已注册的内容，而不是哪些阶段表达式实际使用了这些参数；要查找 #setName.paramName# 的用法，请使用 retrieve_datastage_flow_code 获取流程，并搜索阶段属性字符串。

向 DataStage 流程添加本地参数

本地参数是直接在流程上定义的流程作用域变量——不与其他流程共享，也不属于任何参数集。在阶段表达式中使用 #paramName# 引用（不带参数集名称前缀）。

add_local_parameter(
    flow_id=..., project_id=...,
    engine="datastage",        # streamsets is not supported — returns an error
    name="SCHEMA",
    type="string",             # all 11 DataStage types supported
    value="PUBLIC",            # optional default
)

请说明流程名称和参数名称。

• 如果已存在同名本地参数，则会覆盖该参数（区分大小写）。
• type 接受与 create_parameter_set 相同的别名：integer → int64、float → sfloat、list → enum。
• enum 类型需要 valid_values=[...]。
• subtype="envvar" 会被接受并原样传递，但尚未通过后端验证——在确认之前，请将其视为实验性功能。

从 DataStage 流程中移除本地参数

remove_local_parameter(flow_id=..., project_id=..., engine="datastage", name=...)

请说明流程名称和参数名称。

移除指定参数。匹配区分大小写。成功时返回 status="removed"；如果名称不存在，则返回 status="not_found"——无需事先检查是否存在，可以安全调用。

重命名参数集或修改其描述

update_parameter_set(parameter_set_id=..., project_id=..., name="NewName", description="...")

仅说明旧名称和新名称。

删除参数集

必须遵循以下顺序，不得跳过任何步骤：

1. 调用 list_parameter_sets，将名称解析为资产 ID。
2. 在调用 delete_parameter_set 之前，使用该 ID 调用 get_asset_relationships（asset_type "parameter_set"），无论你是否预期存在引用。
3. 如果 used_by 非空，告知用户所有引用该参数集的流或连接，并在继续操作前征求确认。
4. 如果 used_by 为空，立即继续删除，无需等待用户确认。
5. 仅在第 3 步获得确认后（或适用第 4 步时），调用 delete_parameter_set。

# Step 1
list_parameter_sets(project_id=..., name_filter="MySet")

# Step 2 — always, unconditionally
get_asset_relationships(
    assets=[{"asset_type": "parameter_set", "asset_id": "<resolved_id>"}],
    project_id=...
)

# Step 5 — only after steps 3–4
delete_parameter_set(parameter_set_id=..., project_id=...)

仅按参数集名称确认删除。

此操作永久且无法恢复。该工具仅返回 {'deleted': True, 'parameter_set_id': ...}，不会检查是否存在引用该参数集的流。删除仍被引用的参数集，可能导致相关流无法验证或运行，直到移除失效的引用。

工具参考

工具	用途
list_parameter_sets	列出项目中的所有参数集（不包括 PROJDEF）
get_parameter_set	完整详情：参数和值集；如果该参数集与 StreamSets 不兼容，则包含 streaming_warnings
create_parameter_set	创建新参数集
update_parameter_set	重命名、重新描述或替换参数列表；会防止意外删除参数——使用 confirm_replacement=True 允许删除
delete_parameter_set	永久删除参数集；先调用 get_asset_relationships 查找引用该参数集的流，告知用户后再删除
manage_value_set	添加、替换或移除命名值集
attach_parameter_set_to_flow	将参数集关联到 DataStage 或 StreamSets 流
attach_parameter_set_to_connection	使用参数集参数化连接属性；在连接上启用“使用外部参数集”
get_flow_parameter_references	返回 DataStage 流上注册的 external_paramsets 和 local_parameters（仅限 DataStage）
add_local_parameter	在 DataStage 流上添加或覆盖本地参数（仅限 DataStage）
remove_local_parameter	从 DataStage 流中移除本地参数（仅限 DataStage）

防护规则

• 请参阅本技能顶部的 UUID 规则——回复中绝不回显任何 UUID。
• PROJDEF 是保留的系统名称——绝不创建使用该名称的集合。
• update_parameter_set 会替换整个 parameters 列表。先获取，再合并，然后提交。
• delete_parameter_set 是永久操作。请遵循上文“删除参数集”中的 5 步流程——无论如何，都必须在 delete_parameter_set 之前调用 get_asset_relationships。仅当 used_by 为空时才跳过确认环节；否则先发出警告并确认。
• StreamSets：参数集名称不得包含 __。仅注入 string 参数。
• add_local_parameter 和 remove_local_parameter 仅适用于 DataStage——传入 engine="streamsets" 会立即返回错误。对于 get_flow_parameter_references，engine 参数是可选的，默认值为 "datastage"。
• 调用 add_local_parameter 之前先调用 get_flow_parameter_references，以避免因大小写不同而创建重复项。
• get_flow_parameter_references 仅报告注册情况。某个集合出现在 external_paramsets 中，并不能证明任何阶段表达式正在使用它；未出现也不能证明流程中没有残留 #setName.paramName# 文本。
• attach_parameter_set_to_connection：在修补任何内容之前，会先校验 property_mappings 的两部分——键必须是连接已有的属性，值必须是指定集合中的参数。使用 inspect_project_asset(asset_type="connection") 查看可用的属性名称。未映射的属性保持不变，包括密钥。
• update_datastage_flow 会替换整个流程定义，但它会先加载已存储的流程，因此 external_paramsets 和 local_parameters 会在编辑后保留——无需重新附加。对于重要编辑，请在编辑后使用 get_flow_parameter_references 确认。→ resources/flow_lifecycle_with_parameters.md 查看完整风险表。
• 遇到异常情况时 → resources/troubleshooting.md。
• 查看最常见的 Agent 错误 → resources/common_mistakes.md。