function-creator

函数创建器

在 Datex Studio 分支上创建新的 Datex Studio 函数或修改现有函数。

另请参阅： db-query — 面向从 *-storage.json 组件读取或写入数据的流程代码，介绍 $db 谓词 DSL 和存储访问模式。function-creator 负责函数生命周期（dxs function generate / validate / dxs configuration upsert flow）；db-query 负责 $db 谓词机制。

参考资料

• ../datex-studio-shared/branch-setup.md -- 分支和连接选择（各技能共用）
• references/command-syntax.md -- 所有 dxs function 命令及示例
• references/flag-guide.md -- 各标志的使用时机、原因和方法
• references/code-patterns.md -- 常见的函数代码模式
• references/functions.md -- 函数平台参考：用途、文件结构、configurationTypeId=9、参数描述符样板代码、UI→操作桥接、运行时全局变量、调用约定
• ../datex-studio-shared/context-navigation.md -- 如何检索和浏览设计器上下文响应

依赖项

• requirements-gathering 技能 — 如果当前对话上下文中尚无需求简报，则调用该技能生成一份
• impact-analysis 技能 — 修改现有函数的输入/输出参数时调用

工作流

[Phase 1: Setup + Requirements]
Follow branch-setup.md for branch/connection selection
        |
[requirements brief in context?]
  +-----+-----+
  |            |
 YES          NO
  |            |
 use it    invoke `requirements-gathering` skill
  |            |
  +-----+------+
        |
[determine intent: create or modify?]
        |
  +-----+-----+
  |             |
CREATE        MODIFY
  |             |
 determine    dxs function get <ref> --branch <id>
 ref name     extract code from nodes[0].stepConfig.executeCodeConfig.code
 + params     write to temp .ts file
  |             |
  +------+------+
         |
[Phase 2: Intellisense]
dxs function context <config.json> --branch <id>
         |
[Phase 3: Signature Safety -- modify only]
If input/output params are changing:
  invoke impact-analysis skill
  only continue if no callers or user approves
         |
[Phase 4: Code]
Write or update TypeScript code in temp .ts file
         |
[Phase 5: Generate + Validate + Upload]
dxs function generate ... --code-file <file.ts> -o <config.json>
dxs function validate <config.json> --branch <id>   # exits 0 even on errors — READ the output
dxs configuration upsert flow -D <config.json> --branch <id>

阶段详情

阶段 1：设置和需求

1. 按照 branch-setup.md 选择分支和连接
2. 检查当前对话上下文中是否已有需求简报（由 requirements-gathering 或其他调用技能生成）
   • 已有需求简报 — 使用该简报。简报会说明意图、预期输入/输出和业务规则。
   • 没有需求简报 — 先调用 requirements-gathering 技能。这样可以确保 Agent 在动手编写代码前，了解函数应执行的操作（创建时）或所需的更改（修改时）。
3. 确定意图：创建新函数还是修改现有函数？

创建流程（续）： 4. 确定引用名称（有效的 JS 标识符 — 必须以 _flow 后缀结尾，例如 sum_flow、process_order_flow） 5. 根据需求简报确定输入/输出参数

修改流程（续）： 4. 获取现有函数：dxs function get <ref_name> --branch <id> 5. 从响应 JSON 的 nodes[0].stepConfig.executeCodeConfig.code 中提取当前代码 6. 将代码写入临时 .ts 文件以便编辑 7. 记录当前输入/输出参数，以便检测签名变更

阶段 2：智能感知

完整的上下文响应检索和读取指南（包括后端与前端符号筛选规则），请参阅 context-navigation.md。若要快速确认 $types.<Package>.* 自定义类型或枚举成员是否存在（例如，在流程代码中引用 $types.Utilities.e_awi_scopes.Cartonization 之前），而不解析完整的上下文数据块，请使用其中介绍的 nomenclature 注册表。

创建时： 使用占位代码文件（例如，只包含 // placeholder）运行 dxs function generate --code-file <placeholder.ts> -r <name> -t "<title>" -d "<desc>" --in-param <params> --out-param <params> -o <config.json>，然后对生成的 JSON 运行 context，以在编写实际代码前获取类型系统。

修改时： 可以将通过 dxs function get 获取的配置 JSON 保存到文件，并直接用于 context 命令。

检索：

dxs -O json function context <config.json> --branch <id>

读取 defaultContext.imports，以确定实际可用的 $ 符号——并非 appContext.vars 中的每个符号都能在后端函数代码中使用。仅查询已导入符号在 appContext.text 中的类型定义。global_context 提供环境实用工具（$utils、枚举）。

阶段 3：签名安全性（仅限修改）

如果修改会更改输入或输出参数：

1. 使用函数的引用名称调用 impact-analysis 技能
2. 如果存在调用方，列出它们并询问用户是否继续
3. 如果继续，Agent 必须在修改函数后更新所有受影响的调用方

阶段 4：代码

在临时 .ts 文件中编写或更新 TypeScript 代码。使用阶段 2 的智能感知数据来：

• 以正确的类型引用其他函数、数据源、报表等
• 正确使用 $flow.inParams.* 和 $flow.outParams.*
• 访问运行时服务（$utils、$services 等）

常见模式请参阅 code-patterns.md。

阶段 5：生成、验证、上传

# Generate the config (local file operation — does not take --branch)
dxs function generate \
  --code-file <file.ts> \
  -r <reference_name> \
  -t "<title>" \
  -d "<description>" \
  --in-param <name>:<type> \
  --out-param <name>:<type> \
  -o <config.json>

# Validate. NOTE: unlike `dxs configuration validate`, this command exits 0 even when it
# finds errors — a zero exit means "the command ran", NOT "the function is valid".
# Read the payload: proceed only on `status: "valid"`; a `validation_errors` list means stop.
dxs function validate <config.json> --branch <id>

# Upload
dxs configuration upsert flow -D <config.json> --branch <id>

dxs function validate 不会根据退出代码进行拦截。 dxs configuration validate 和 dxs datasource validate 在报告错误时会以 1 退出；dxs function validate 仍以 0 退出，并在输出中报告 validation_errors（已根据 CLI 源码 0.4.18 验证）。如果 Agent 从其他技能中了解到“验证失败会明确报错”，就可能将此命令的成功退出视为放行信号， 并上传有问题的函数。务必检查输出，不要只看退出状态。完整的退出代码对照表： ../datex-studio-shared/configuration-roundtrip.md。

命名约定

• 引用名称必须是有效的 JS 标识符（以字母、_ 或 $ 开头，不含空格或连字符）
• 必须以 _flow 后缀结尾（例如，sum_flow、validate_order_flow、boolean_array_to_mask_flow）
• 标题（-t）是面向用户的显示名称，可与引用名称不同

常见错误

错误	修正方法
使用 return 设置输出	改为赋值给 $flow.outParams.*——函数不使用返回值
$datasources 或 $flows 的作用域错误	模块代码需要模块前缀（$datasources.ModuleName.ds_name）。引用自身配置的应用代码不需要（$datasources.ds_name）。始终检查 dxs function context 中的 appContext 类型，以确定正确的路径。
更改参数时未检查调用方	修改输入／输出参数时，始终先调用影响分析技能
凭记忆猜测可用服务	始终运行 dxs -O json function context 并读取 defaultContext.imports——参见 context-navigation.md。
引用了仅供前端使用的符号（$shell、$frontendFlows）	函数仅供后端使用。如果某个符号不在 defaultContext.imports 中，就无法使用——参见 context-navigation.md。
使用 $item 而不是 $entity	在 Datex Studio 中，表达式变量是 $entity
代码文件超过 512 KB	将逻辑拆分到多个函数中，或提取辅助函数
即使 validate 通过，新建的工作流仍无法保存（DXS-API-500 / DbUpdateException）	先检查 description 的长度——超过 256 个字符时，所有配置类型都会出现此错误，而且 validate 无法检测到（已于 2026-08-13 通过二分排查确认；参见 configuration-roundtrip.md）。如果描述未超过上限，则考虑 2026-08-11 观察到的宽签名错误（PrintManager，单个主体中约有 19 个 inParams、8 个 outParams 和代码）：一次性创建／更新会返回 500，而任意子集都能正常保存——并且保存失败会从分支中删除该工作流。解决方法：逐步组合——先 upsert 最小主体（包含 referenceName 和占位代码，不含参数），然后添加 inParams 和代码，再每次少量添加 outParams，并在每一步重新 upsert；之后通过重新执行 get 来验证最终分支状态。

---

编辑后，请调用 post-edit-verification，以发现 description／JSON／schema 违规。最终审核时，请调用 component-validator。