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 スキルを呼び出します。これにより、コードに触れる前に、エージェントが関数で実行すべき内容（新規作成の場合）または必要な変更（変更の場合）を把握できます。
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 に対してコンテキストを実行し、実際のコードを書く前に型システムを取得します。

変更の場合： dxs function get で取得した設定 JSON をファイルに保存し、コンテキストコマンドで直接使用できます。

取得：

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

defaultContext.imports を読み取り、実際に使用可能な $ シンボルを確認してください。appContext.vars にあるすべてのシンボルがバックエンド関数コードで使えるわけではありません。インポートされたシンボルについてのみ、appContext.text で型定義を調べてください。global_context には、アンビエントユーティリティ（$utils、列挙型）が用意されています。

フェーズ 3：シグネチャの安全性（変更のみ）

入力または出力パラメーターを変更する場合：

1. 関数の参照名を指定して、impact-analysis スキルを呼び出します
2. 呼び出し元が存在する場合はそれらを提示し、続行するかユーザーに確認します
3. 続行する場合、エージェントは関数の変更後、影響を受けるすべての呼び出し元を更新する必要があります

フェーズ 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）。他のスキルから 「validate はエラーを明確に通知する」と学習したエージェントは、このコマンドの成功終了コードを問題なしと判断し、 壊れた関数をアップロードしてしまいます。終了ステータスではなく、必ず出力を確認してください。終了コードの全一覧： ../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 を参照してください。
$entity の代わりに $item を使用する	Datex Studio では、式の変数は $entity です
コードファイルが 512 KB を超える	ロジックを複数の関数に分割するか、ヘルパーを切り出してください
validate が成功するにもかかわらず、新しいフローの保存が失敗する（DXS-API-500 / DbUpdateException）	まず description の長さを確認してください。256 文字を超えると、すべての設定タイプでまさにこのエラーが発生し、validate では検出されません（2026-08-13 に二分探索で確認。configuration-roundtrip.md を参照）。description が上限以内の場合は、2026-08-11 に確認された幅広いシグネチャのバグを確認してください（PrintManager、約19個の inParams + 8個の outParams + 1つの本体にコード）：単一の作成／更新処理は 500 エラーになりますが、どの部分集合も問題なく保存できます。さらに、保存に失敗するとブランチからフローが削除されます。回避策：段階的に構成します。最小限の本体（referenceName + プレースホルダーコード、パラメーターなし）を upsert し、次に inParams とコードを追加し、その後 outParams を少しずつ追加して各段階で再度 upsert します。最後に、新たに get を実行してブランチの状態を確認してください。

---

編集後は post-edit-verification を実行し、description／JSON／スキーマの違反を確認してください。最終レビューには component-validator を実行してください。