function-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Function Creator

函数创建工具

Create new Wavelength functions or modify existing ones on a Datex Studio branch.

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

References

参考文档

../shared/branch-setup.md -- Branch & connection selection (shared across skills)
references/command-syntax.md -- All
```
dxs function
```
commands with examples
references/flag-guide.md -- When/why/how for each flag
references/code-patterns.md -- Common patterns for function code
../shared/context-navigation.md -- How to retrieve & navigate designer context responses

../shared/branch-setup.md -- 分支与连接选择（全技能共享）
references/command-syntax.md -- 所有
```
dxs function
```
命令及示例
references/flag-guide.md -- 各参数的使用场景、原因及方法
references/code-patterns.md -- 函数代码的常见模式
../shared/context-navigation.md -- 如何获取及导航设计器上下文响应

Dependencies

依赖技能

requirements-gathering
skill — invoked to produce a requirements brief if one doesn't already exist in the conversation context
impact-analysis
skill — invoked when modifying input/output parameters of an existing function

requirements-gathering
技能 — 若对话上下文中不存在需求概要，则调用该技能生成需求概要
impact-analysis
技能 — 修改现有函数的输入/输出参数时调用

Workflow

工作流

[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 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>
dxs function upsert <config.json> --branch <id>

[阶段1：设置 + 需求梳理]
遵循branch-setup.md进行分支/连接选择
        |
[上下文中是否有需求概要？]
  +-----+-----+
  |            |
  是          否
  |            |
 使用现有概要    调用`requirements-gathering`技能
  |            |
  +-----+------+
        |
[确定意图：创建还是修改？]
        |
  +-----+-----+
  |             |
 创建          修改
  |             |
  确定引用名称    dxs function get <ref> --branch <id>
  + 参数        从stepConfig.executeCodeConfig.code中提取代码
  |             |
  +------+------+
         |
[阶段2：智能提示]
dxs function context <config.json> --branch <id>
         |
[阶段3：签名安全性 — 仅修改场景]
若输入/输出参数发生变化：
  调用impact-analysis技能
  仅在无调用者或用户批准后继续
         |
[阶段4：代码编写]
在临时.ts文件中编写或更新TypeScript代码
         |
[阶段5：生成 + 验证 + 上传]
dxs function generate ... --code-file <file.ts> -o <config.json>
dxs function validate <config.json> --branch <id>
dxs function upsert <config.json> --branch <id>

Phase Details

阶段详情

Phase 1: Setup + Requirements

阶段1：设置 + 需求梳理

Follow branch-setup.md for branch/connection selection
Check whether a requirements brief already exists in the conversation context (produced by
```
requirements-gathering
```
or another calling skill)
- Requirements brief exists — use it. The brief provides the intent, expected inputs/outputs, and business rules.
- No requirements brief exists — invoke the
```
requirements-gathering
```
  skill first. This ensures the agent understands what the function should do (create) or what changes are needed (modify) before touching code.
Determine intent: create new or modify existing?

Create flow (continued): 4. Determine reference name (valid JS identifier — must end with

_flow

suffix, e.g.,

sum_flow

process_order_flow

) 5. Determine input/output parameters from the requirements brief

Modify flow (continued): 4. Fetch the existing function:

dxs function get <ref_name> --branch <id>

5. Extract the current code from

stepConfig.executeCodeConfig.code

in the response JSON 6. Write the code to a temporary

.ts

file for editing 7. Note the current input/output parameters for signature change detection

遵循branch-setup.md进行分支/连接选择
检查对话上下文中是否已存在需求概要（由
```
requirements-gathering
```
或其他调用技能生成）
- 存在需求概要 — 使用该概要。概要包含意图、预期输入/输出及业务规则。
- 无需求概要 — 先调用
```
requirements-gathering
```
  技能。这能确保Agent在接触代码前，理解函数应实现的功能（创建场景）或所需修改内容（修改场景）。
确定意图：创建新函数还是修改现有函数？

创建流程（续）： 4. 确定引用名称（合法的JS标识符 — 必须以

_flow

后缀结尾，例如

sum_flow

、

process_order_flow

） 5. 从需求概要中确定输入/输出参数

修改流程（续）： 4. 获取现有函数：

dxs function get <ref_name> --branch <id>

5. 从响应JSON的

stepConfig.executeCodeConfig.code

中提取当前代码 6. 将代码写入临时

.ts

文件以便编辑 7. 记录当前输入/输出参数，用于检测签名变更

Phase 2: Intellisense

阶段2：智能提示

See context-navigation.md for the full guide on retrieving and reading context responses, including the backend vs frontend symbol filtering rules.

For create: Run

dxs function generate --code-file <placeholder.ts> -r <name> -t "<title>" -d "<desc>" --in-param <params> --out-param <params> -o <config.json>

with a placeholder code file (e.g., containing just

// placeholder

), then run context on the resulting JSON to get the type system before writing actual code.

For modify: The fetched config JSON from

dxs function get

can be saved to a file and used directly with the context command.

Retrieval:

bash

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

Read

defaultContext.imports

to determine which

-symbols are actually available — not every symbol in

appContext.vars

is usable in backend function code. Look up type definitions in

appContext.text

for imported symbols only. The

global_context

provides ambient utilities (

$utils

, enums).

查看context-navigation.md获取完整的上下文响应获取与阅读指南，包括后端与前端符号过滤规则。

创建场景： 运行

dxs function generate --code-file <placeholder.ts> -r <name> -t "<title>" -d "<desc>" --in-param <params> --out-param <params> -o <config.json>

，使用占位符代码文件（例如仅包含

// placeholder

），然后对生成的JSON运行context命令，在编写实际代码前获取类型系统信息。

修改场景： 从

dxs function get

获取的配置JSON可保存到文件，直接用于context命令。

获取命令：

bash

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

查看

defaultContext.imports

确定可用的

符号 — 并非

appContext.vars

中的所有符号都可用于后端函数代码。仅查看导入符号在

appContext.text

中的类型定义。

global_context

提供环境工具（

$utils

、枚举）。

Phase 3: Signature Safety (modify only)

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

If the modification changes input or output parameters:

Invoke the impact-analysis skill with the function's reference name
If callers exist, present them and ask the user whether to proceed
If proceeding, the agent must update all affected callers after modifying the function

若修改涉及输入或输出参数变更：

使用函数的引用名称调用impact-analysis技能
若存在调用者，列出调用者并询问用户是否继续
若继续，Agent必须在修改函数后更新所有受影响的调用者

Phase 4: Code

阶段4：代码编写

Write or update the TypeScript code in a temp

.ts

file. Use the intellisense data from Phase 2 to:

Reference other functions, datasources, reports, etc. with correct types
Use
```
$flow.inParams.*
```
and
```
$flow.outParams.*
```
correctly
Access runtime services (
```
$utils
```
,
```
$services
```
, etc.)

See code-patterns.md for common patterns.

在临时

.ts

文件中编写或更新TypeScript代码。使用阶段2的智能提示数据：

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

查看code-patterns.md获取常见模式。

Phase 5: Generate, Validate, Upload

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

bash

undefined

bash

undefined

Generate the config (local file operation — does not take --branch)

生成配置（本地文件操作 — 无需--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

验证

dxs function validate <config.json> --branch <id>

Upload

上传

dxs function upsert <config.json> --branch <id>

undefined

dxs function upsert <config.json> --branch <id>

undefined

Naming Convention

命名规范

Reference names must be valid JS identifiers (start with letter/
```
_
```
/
```
$
```
, no spaces/hyphens)

Must end with

_flow

suffix (e.g.,

sum_flow

validate_order_flow

boolean_array_to_mask_flow

)

Title (
```
-t
```
) is a human-readable display name — can differ from reference name

引用名称必须是合法的JS标识符（以字母/
```
_
```
/
```
$
```
开头，无空格/连字符）

必须以

_flow

后缀结尾（例如

sum_flow

、

validate_order_flow

、

boolean_array_to_mask_flow

）

标题（
```
-t
```
）是人类可读的显示名称 — 可与引用名称不同

Common Mistakes

常见错误

Mistake	Fix
Using `return` to set output	Assign to `$flow.outParams.*` instead — functions don't use return values
Wrong scoping on `$datasources` or `$flows`	Module code requires module prefix ( `$datasources.ModuleName.ds_name` ). App code referencing its own configs does not ( `$datasources.ds_name` ). Always check the `appContext` types from `dxs function context` to determine the correct path.
Changing params without checking callers	Always invoke impact-analysis skill first when modifying input/output params
Guessing available services from memory	Always run `dxs -O json function context` and read `defaultContext.imports` — see context-navigation.md.
Referencing a frontend-only symbol ( `$shell` , `$frontendFlows` )	Functions are backend-only. If a symbol is not in `defaultContext.imports` , you cannot use it — see context-navigation.md.
Using `$item` instead of `$entity`	The expression variable is `$entity` in Wavelength
Code file exceeding 512 KB	Split logic into multiple functions or extract helpers

错误	修复方法
使用 `return` 设置输出	改为赋值给 `$flow.outParams.*` — 函数不使用返回值
`$datasources` 或 `$flows` 作用域错误	模块代码需要模块前缀（ `$datasources.ModuleName.ds_name` ）。引用自身配置的应用代码不需要前缀（ `$datasources.ds_name` ）。始终通过 `dxs function context` 获取的 `appContext` 类型确定正确路径。
修改参数前未检查调用者	修改输入/输出参数时，务必先调用impact-analysis技能
凭记忆猜测可用服务	始终运行 `dxs -O json function context` 并查看 `defaultContext.imports` — 参考context-navigation.md。
引用仅前端可用的符号（ `$shell` 、 `$frontendFlows` ）	函数仅运行于后端。若符号不在 `defaultContext.imports` 中，则无法使用 — 参考context-navigation.md。
使用 `$item` 而非 `$entity`	Wavelength中的表达式变量为 `$entity`
代码文件超过512 KB	将逻辑拆分为多个函数或提取辅助函数