uipath-coded-apps

UiPath Coded Apps

uip codedapp CLI と @uipath/uipath-typescript SDK を使用して、UiPath Coded Web Applications と Coded Action Apps を構築、デバッグ、デプロイします。

このスキルを使用する場面

• UiPath Coded Web App または Coded Action App を構築、デバッグ、デプロイしたい場合
• uip codedapp コマンド、.uipath/ ディレクトリ、app.config.json、action-schema.json について質問がある場合
• UiPath Cloud または Action Center フォーム用の新しい React/Vue フロントエンドをスキャフォールドしたい場合
• UiPath のプリビルトウィジェットで対応できるアプリ UI について質問がある場合：Document Understanding の抽出結果をレビュー／修正する（Validation Station）、会話型エージェントとチャットする、Data Fabric エンティティをグリッドで表示／編集する、ストレージバケットにファイルをアップロードする、PDF を表示する、外部 IdP（Google/SAML）でサインインする
• ローカルと Studio Web 間でソースをプッシュ／プルしたい場合
• コーデッドアプリから @uipath/uipath-typescript SDK を使用したい場合
• パイプライン全体（ビルド → パック → 公開 → デプロイ）を実行したい場合
• 自然言語による説明からエージェント監視／分析ダッシュボードを生成したい場合。例：「エージェントの健全性、エラー率、呼び出し量、レイテンシ、アクティブなエージェント、KPI、ガバナンス指標、消費傾向を表示」
• 「ダッシュボードを構築／作成／生成して」と言う、可視化する指標を説明する、またはエージェントのオブザーバビリティ、運用、コストビューを求める場合

アプリのJS/TS 関数バックエンド（アプリが呼び出す defineFunction エンドポイントの作成、トークン、CORS、ローカルでの 2 サーバー開発ループ）については、→ uipath-functions を参照してください。

アプリの種類

種類	説明	主な違い
Coded Web App	UiPath CDN でホストされる React/Vue/その他のフロントエンド	URL 経由でアクセスするユーザー向けアプリ
Coded Action App	UiPath Action Center に接続された React フォーム	Maestro／Agent ワークフローの人間によるタスクレビュー内にレンダリングされる

ライフサイクルは 2 種類、スキャフォールディングの開始点も 2 種類です。

• スタンドアロンのコーデッドアプリ：create-vite でスキャフォールドします。create-web-app.md／create-action-app.md（重要なルール 20）に記載された正確なコマンドをコピーしてください。project.uiproj／webAppManifest.json はありません。これらはソリューションへの所属に関する成果物であり、スタンドアロンアプリには不要です。uip codedapp pack → uip codedapp publish（アクションアプリの場合は -t Action）→ uip codedapp deploy でデプロイします。これは、このスキルの残りの部分で説明する従来の単一アプリのライフサイクルです。
• ソリューション内のコーデッドアプリ：.uipx ソリューションの内部で uip codedapp init を実行します。init は project.uiproj（ProjectType: "AppV2"）と webAppManifest.json を書き込み、ランタイムとビルド成果物を source/dist/ の下に格納し、プロジェクトを .uipx 内に Type: "AppV2" として自動登録し、resources/solution_folder/app/{Coded,CodedAction}/ を生成します。以降、アプリはソリューションの一部となり、uip solution pack がその .nupkg をバンドルし、uip solution deploy run がデプロイフォルダーにプロビジョニングします。すでに .uipx に登録されているコーデッドアプリに対して、uip codedapp pack／publish／deploy を実行しないでください。ソリューションのデプロイ設定（外部クライアント ID、ルーティング名、アクションスキーマ）が迂回され、パッケージが二重登録されます。uip solution projects add／uip solution projects import でも既存の AppV2 フォルダーを登録でき、webAppManifest.config.isActionApp を読み取って Coded／CodedAction サブタイプを選択します。ソリューション側のライフサイクルについては、/uipath:uipath-solution を参照してください。

uip codedapp init は React プロジェクトをスキャフォールドしません。 静的な dist/index.html と 3 つのメタデータファイルを書き込むだけで、ソースプロジェクトは生成しません。そのため、スタンドアロンのコーデッドアプリのスキャフォールディング開始点ではありません。スタンドアロンアプリには、create-web-app.md（重要なルール 20）に記載された create-vite コマンドを使用してください。

重要なルール

1. まず最初に、アプリの種類を特定してください。 構造化された選択肢として質問してください（ルール 18）：Coded Web App — UiPath Cloud にデプロイするカスタムフロントエンド · Coded Action App — Action Center の人によるタスクレビュー用フォーム。2 つの手順では、スキャフォールディング、リダイレクト URI、公開フラグが異なります。推測してはいけません。
2. 必ず最初にログイン状態を確認してください。 クラウドコマンドを実行する前に uip login status --output json を実行してください。未ログインの場合は、uip login を実行してください。
3. ビルド手順を省略してはいけません。 スキャフォールディングの後に npm run build を実行し（スキャフォールドがコンパイルされることを確認）、さらに pack または push の前にも実行して、デプロイ可能な dist/ を生成してください。毎回 dist/ の存在を確認してください。
4. Pack → Publish → Deploy の順序は必須です。 各手順は、前の手順で出力が生成されることを前提としています。
5. 再公開時はバージョンを上げてください。 同じバージョンがすでに Orchestrator に存在する場合、公開は失敗します。
6. Action アプリの公開には -t Action が必要です。 uip codedapp publish -t Action を実行してください（デフォルトの Web タイプではなく）。
7. アクセストークンを手動で扱ってはいけません。 キャッシュされたアクセストークンを渡したり、出力、解析、読み込み、設定したりしてはいけません。uip login とサポート対象の uip codedapp コマンドを使用してください。認証は CLI が管理します。
8. ベース URL には API サブドメインを使用する必要があります。 https://cloud.uipath.com ではなく https://api.uipath.com を使用してください。以下の表を参照してください。
9. vite.config.ts では、必ず base: './' を設定してください。 URL ルーティングはプラットフォームが処理するため、アプリでは相対アセットパスを使用する必要があります。ここでルーティング名やサブパスを使用してはいけません。静的アセットはバンドラー経由でインポートしてください（import logo from './assets/logo.png'）。そうすることで、Vite がフィンガープリントを付与し、ベースパスを書き換えます。public/ に配置したり、/ をルートとするハードコードされたパスで参照したりしてはいけません。これらはベースパスの書き換えを回避するため、ルート以外にマウントされた状態でデプロイすると 404 になります。
10. 実行時に絶対 URL を構築する場合は、必ず @uipath/uipath-typescript の getAppBase() を使用してください — ルーターのベース名、画像の src、fetch のパスなどが該当します。デプロイされたアプリはルート以外のプレフィックスにマウントされます。/ をルートとするパスはローカルでは動作しますが、デプロイ後は 404 になります。Vite の base: './' で修正できるのは、インポート時の参照のみです。
11. uip codedapp deploy は非対話モードで実行する必要があります。 フォルダーキーを --folder-key <GUID> として渡してください（または UIPATH_FOLDER_KEY=<GUID> を環境変数のプレフィックスとして指定してください。どちらでも動作します）。対話型フォルダーピッカーは、非 TTY コンテキスト（CI、エージェントシェル）では失敗します。uip or folders list --all --name "<name>" でフォルダーが返されるのに、deploy がキーを not found among folders accessible to your account として拒否する場合は、--folder-key を指定せずに UIPATH_FOLDER_KEY=<GUID> uip codedapp deploy … として1 回だけ再実行してください。フォルダー数が非常に多いアカウントでは、フラグの事前チェックがアカウントのフォルダー一覧の不完全なコピーを参照するため、キー自体に問題はありません。同じ呼び出しを待ったり再試行したりしても解決しません。pack-publish-deploy.md を参照してください。ユーザーがフォルダーの名前を指定した場合は、サーバー側フィルター uip or folders list --all --name "<name>" --output json で解決し、Name が対象と完全一致する行を選んでから、その Key を読み取ってください。通常の一覧は 1 ページあたり 50 件でページ分割され、--name は --all が必要な「部分一致」検索であるため、最初の行をそのまま選んではいけません。パーソナルワークスペースは --all の対象外です。デフォルトの uip or folders list --output json から Type == "Personal" の行を特定してください。新しいフォルダーにデプロイするには、先に uip or folders create "<NAME>" --output json で作成し、Data.Key を読み取ってください。uip or ... コマンドには Orchestrator ツールが必要です。uip tools list で確認してから、uip tools install @uipath/orchestrator-tool で一度インストールしてください。
12. すべての UI でテキストのオーバーフローを防いでください。 patterns.md の「Preventing Text Overflow」を参照してください。
13. 分析、フィルター、シードデータを作成する前に、DF スキーマを調べてください。 uip df entities get <ENTITY_ID> --output json を実行して、フィールドと型を確認してください。実行時には、アプリの認証済みセッションから entities.getById(<id>) を使用してください。DF は一般的な RDBMS のようには動作しません。sdk/data-fabric.md の「Anti-shapes & gotchas」を参照してください。
14. 一覧取得の呼び出しはすべて、オプションがなくても 1 ページだけを返します。「すべて取得」する方法はありません。 getAll、getAllRecords、queryRecordsById、getFileMetaData などが対象です。オプションなしの getAll() はすべての行を返しません。SDK は pageSize を送信せず、サーバーが独自の上限を適用した応答を、誤解を招く名前の NonPaginatedResponse でラップします。上限を超える可能性があるデータソースからすべての行を一覧取得するには、カーソルをループする必要があります：while (page.hasNextPage) { page = await getAll({ cursor: page.nextCursor }) } として、items に蓄積してください。1 回の呼び出し後に result.items.length を読み取るのは、ほぼ常にバグです。sdk/pagination.md を参照してください。
15. 動的データのテーブルでは、すべての行をスクロール領域に一度に表示するのではなく、ページネーションを使用してください。 ページサイズは 25～50 とし、次へ／前へ／ページ番号のコントロールと、「X～Y 件目／全 Z 件」の概要を表示してください。概要パネルで明示的に使う場合（例：「最も古い 10 件」）は、上位 N 件と「すべて表示」の組み合わせでもかまいません。運用ダッシュボードで N 件分を無限スクロールする設計は使いものになりません。DF エンティティ、タスク、ジョブ、会話、プロセスインスタンスなど、あらゆるサービスをデータソースとするテーブルが対象です。patterns.md の「Tabular Data」を参照してください。
16. 新しい SDK メソッド呼び出しを追加する場合は、設定済みの OAuth スコープに必要なスコープが含まれていることを確認してください — ダッシュボードと Web アプリのどちらも、uipath.json から scope キーを読み取ります。書き込み操作、アクションメソッド（Jobs.stop、Tasks.complete、ProcessInstances.cancel など）、または新しいサービスを初めて使用する場合は、通常、読み取り専用の処理より広いスコープが必要です。スコープが一致しない場合、最初の呼び出しで 401／403 が発生し、明確なエラーが表示されないことがあります。スコープの組み合わせとメソッドごとの参照手順については、oauth-scopes.md を参照してください（メソッドごとの表は SDK パッケージ内の node_modules/@uipath/uipath-typescript/docs/oauth-scopes.md に含まれています）。
17. アクションアプリでは、sdk.initialize() を呼び出してはいけません。 これは Web アプリ専用です。完了できない iframe 内で、対話型 PKCE リダイレクトを開始します。アクションアプリは、Action Center が注入する設定からサイレントに認証します。引数なしで new UiPath() を構築し、そのまま使用してください。create-action-app.md の src/uipath.ts を参照してください。
18. ユーザーに定型の決まり文句を入力させてはいけません。 既知の選択肢（アプリの種類、ビルド／編集／デプロイの意図、OAuth の設定、デプロイの固定方法）から選ぶようユーザーに求める場合は、選択可能なオプションを提供するホストのコーディングエージェントにネイティブな質問ツールがあれば、構造化された選択肢として提示してください。手順：選択肢ごとに、短い太字のラベルと、選択した場合に実行される内容を 1 行で説明します。推奨する選択肢を最初に置き、ラベルの末尾に「（推奨）」を付けてください。選択肢は最大 4 つにしてください（該当する場合は、変更する／キャンセル などの中止用選択肢に 1 つ分の枠を確保します）。候補が 5 つ以上ある場合、またはホストエージェントに質問ツールがない場合は、番号付きのリストを表示し、番号または選択肢ラベルで回答できるようにしてください。自由記述の返信も常に有効な回答として扱ってください（例：計画変更の依頼）。その場合は選択肢よりも自由記述を優先します。例外 — 長い出力と同じ応答で質問してはいけません： 計画承認の確認は意図的に自由記述とし（計画の最後に「承認するか、変更内容をお知らせください」と記載します）、構造化された質問はその後の短いターンでのみ行います。references/dashboards/plugins/build/impl.md を参照してください。
19. SDK メソッドのシグネチャを推測してはいけません。インストール済みの型定義を確認してください。 メソッド名、パラメーター、戻り値の型、使用例に関する信頼できる参照先は、node_modules/@uipath/uipath-typescript/dist/<subpath>/index.d.ts です（JSDoc 全文を含み、インストール済み SDK のバージョンと正確に一致します）。このセッションで使用していないサービスを呼び出す前に、その .d.ts を読んでください。node_modules が存在しない場合は、まずインストール手順を実行してください。インストールしないとアプリをビルドできません。references/sdk/*.md ファイルには、意図的にシグネチャを記載していません。スコープ、呼び出し規約、型では表現できない落とし穴のみを説明しています。必要な機能が見つからない場合の手順については、references/sdk/imports.md を参照してください。境界：読むのは .d.ts のみで、コンパイル済みバンドルは読まないでください。 dist/*.mjs／*.js は圧縮された実装であり、API ではありません。読んでも行き詰まるだけです。grep の結果が何も出力されない場合は、対象が存在しないことの確認とみなしてください。本当に機能がない場合は、検索をバンドルにまで広げず、ドキュメントに記載された代替手段を使用してください。
20. src/main.tsx が存在するまでは、スキャフォールドが React だと判断してはいけません。何かをインストールする前に存在を確認してください。 どちらの種類のアプリも、create-web-app.md のステップ 3.2 または create-action-app.md に記載された 1 つの create-vite コマンドをコピーしてスキャフォールディングしてください。このコマンドには --no-interactive が渡されています。これがないと、create-vite はリンターのプロンプトで停止します。また、回答する人がいない場合は何も作成せずに終了コード 0 を返します。コマンドの末尾には SCAFFOLD_OK を出力する node チェックがあります。npm create vite 形式を使ってはいけません。npm create でフラグを渡すには、単独の -- 区切りが必要です。区切りが欠落または破損すると、npm が --template を取り込んでしまい、create-vite は気付かれないまま vanilla TypeScript テンプレートをスキャフォールディングします。終了コードや出力だけを見てスキャフォールドを判断してはいけません。テンプレートの解析に失敗した場合、表示できなかったリンターのプロンプトが出た場合、または空でない対象ディレクトリで Operation cancelled になった場合も、create-vite は終了コード 0 を返します。このスキルでは react を明示的にインストールしないため、間違ったテンプレートを使うと、数分後に無関係に見えるビルドエラーとして表面化します。失敗した場合は --overwrite を指定して再度スキャフォールディングしてください。vanilla のスキャフォールドを手作業で React に変換してはいけません。

曖昧さの解消 — Apps と Dashboards

次の項目が見つかった場合は、Apps のワークフローに直接進んでください（以下のセクション）。 web app、action app、codedapp、app.config.json、action-schema.json、 scaffold app、deploy app、pack、publish、push、pull、debug app

次の項目が見つかった場合は、references/dashboards/CAPABILITY.md に直接進んでください。 dashboard、analytics、KPI、metrics、Insights、observability、 admin console、report、chart、trend、governance report、agent metrics

意図が曖昧な場合 — 構造化された選択肢として「どちらが目的に合っていますか？」と尋ねてください（ルール 18）。

選択肢	説明
Web App／Action App を作成または変更する	Automation Cloud にデプロイする UI、フォーム、またはアプリをスキャフォールドします
ダッシュボードを生成する	自然言語による説明から分析ビューまたは管理ビューを作成します

タスクのナビゲーション

次の操作...	参照先
新しい Coded Web App を作成する	references/create-web-app.md
新しい Coded Action App を作成する	references/create-action-app.md
認証または設定の問題をデバッグする	references/debug.md
Studio Web にコードをプッシュ／プルする	references/file-sync.md
パッケージ化してデプロイする	references/pack-publish-deploy.md
CLI コマンドの完全なリファレンス	references/commands-reference.md
DU Validation Station ウィジェットを埋め込む	references/widgets/validation-station.md
Conversational Agent チャットウィジェットを埋め込む	references/widgets/conversational-agent-chat.md
Data Fabric DataTable ウィジェットを埋め込む	references/widgets/datatable.md
複数ファイルのバケットアップロードウィジェットを埋め込む	references/widgets/multi-file-upload.md
PDF ビューアーウィジェットを埋め込む	references/widgets/pdf-viewer.md
外部 IdP のサインインボタン（Google/SAML）を追加する	references/widgets/external-auth.md
SDK サービスの OAuth スコープ	references/oauth-scopes.md
SDK：インポートパスとサブパスエクスポート	references/sdk/imports.md
SDK：アセット、キュー、バケット、プロセス、ジョブ、添付ファイル	references/sdk/orchestrator.md
SDK：Data Fabric（エンティティ、ChoiceSets）	references/sdk/data-fabric.md
SDK：Maestro（プロセス、ケース）	references/sdk/maestro.md
SDK：Action Center（タスク）	references/sdk/action-center.md
SDK：Conversational Agent	references/sdk/conversational-agent.md
SDK：エージェントのフィードバック	references/sdk/feedback.md
SDK：ページネーション	references/sdk/pagination.md
SDK：エージェントとエージェントメモリ（Insights RTM）	references/sdk/agents.md
SDK：エージェントのトレース（Insights RTM）	references/sdk/traces.md
SDK：ガバナンス — ポリシー評価（Insights API）	references/sdk/governance.md
SDK：エージェントのガバナンス判断 — ランタイムコンプライアンス（Insights RTM）	references/sdk/governance-traces.md
UI パターン（ポーリング、BPMN、HITL、テキストのオーバーフロー、テーブルのページネーション）	references/patterns.md
NLP から管理ダッシュボードを生成する	references/dashboards/CAPABILITY.md

CLI のセットアップ

# Fresh macOS/Linux machine: installs Node.js >= 20, uip, agent skills, .NET SDK 8.0, and Python 3.11-3.14
curl -fsSL https://download.uipath.com/uipath-cli/install.sh | bash

# Resolve the CLI binary before using it
UIP=$(command -v uip 2>/dev/null || true)
if [ -z "$UIP" ] && command -v npm >/dev/null 2>&1; then
  UIP="$(npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip"
fi
if [ -z "$UIP" ] || [ ! -x "$UIP" ]; then
  echo "UiPath CLI not found after bootstrap. Update PATH for this host, then rerun this step." >&2
  exit 2
fi
$UIP --version

# Install the coded apps tool
$UIP tools install @uipath/codedapp-tool

# Install the Orchestrator tool (needed to resolve folder name → key for deploy)
$UIP tools install @uipath/orchestrator-tool

# Verify both are installed
$UIP tools list

Windows PowerShell を使った新しいマシンでのセットアップ：

irm https://download.uipath.com/uipath-cli/install.ps1 | iex

クラウドコマンドを実行する前に認証してください：

uip login status --output json         # check if logged in
uip login                              # interactive OAuth (opens browser)
uip login --authority "<AUTHORITY_URL>"   # non-default host (Automation Suite, dedicated)

# Client-credentials (headless/CI) — scope MUST name one Orchestrator scope AND
# the two Apps-service scopes. Neither set covers the other:
#   OR.Default            → Orchestrator
#   Apps.Read Apps.Write  → Apps-service registration in `uip codedapp publish`
# Do NOT substitute granular Orchestrator scopes (OR.Folders/OR.Execution/
# OR.Administration) for OR.Default.
# Credentials come from env vars via the CLI's env.<NAME> syntax — never inline.
uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --organization <org> \
  --tenant <tenant> \
  --scope "OR.Default Apps.Read Apps.Write" \
  --authority "<AUTHORITY_URL>"   # omit --authority for cloud.uipath.com

クライアントシークレットを会話内で扱わないでください。 ユーザーにチャットへの貼り付けを求めたり、コマンドラインやファイルに書き込んだり、表示したりしないでください。UIPATH_CLIENT_ID / UIPATH_CLIENT_SECRET が設定されていない場合は、ユーザー自身のシェルでエクスポートするよう依頼してから、上記のコマンドを実行してください。

uip login のセッションスコープは、アプリの実行時 OAuth スコープとは別です。 uipath.json のスコープは、デプロイされたアプリが実行時に要求するものです（oauth-scopes.md を参照）。上記の uip login に指定する --scope は、uip codedapp publish の実行中に Apps 登録 API を呼び出すために、CLI セッションが必要とするものです。uip codedapp publish は、パッケージのアップロード（OR.Default が必要）とコード化アプリの登録（Apps.Read Apps.Write が必要）の 2 つを行います。それぞれの失敗時の状況については、debug.md を参照してください。

SDK の設定（Web アプリ）

Web アプリは new UiPath()（設定なし）で SDK を初期化します。実行時に SDK は <meta name="uipath:*"> タグから clientId、scope、orgName、tenantName、baseUrl、redirectUri を読み取ります。ローカル開発時は、@uipath/coded-apps-dev がコミット済みの uipath.json からこれらのタグを挿入します。uipath.json は単一の設定ソースであり、clientId、scope、orgName、tenantName、baseUrl、redirectUri（ローカル用の Vite 開発 URL）を保持します。本番環境では、UiPath プラットフォームが同じタグを直接挿入します。

これらの値を変更するには、uipath.json を編集してください。

CLI 環境変数

変数	使用元	説明
UIPATH_PROJECT_ID	uip codedapp push / uip codedapp pull	Studio Web プロジェクト ID

環境ごとの Base URL — ユーザーがサインインしたポータルのホストから導き出します（uip login status --output json → Data.BaseUrl）：

ポータルのホスト	正しい Base URL
https://cloud.uipath.com（デフォルト）	https://api.uipath.com
https://<PREFIX>.uipath.com（その他の UiPath ホストのポータル）	https://<PREFIX>.api.uipath.com
その他のホスト（Automation Suite、カスタム）	ユーザーが指定する API URL をそのまま使用します

クイックデプロイ（フルパイプライン）

手順の途中で「続けてもよいですか？」と尋ねて停止しないでください。パイプライン全体を実行してください。認証情報またはアプリ名が必要な場合に限り、停止してください。

1. 認証 — uip login status --output json。ログインしていない場合は、ユーザーに環境を尋ねて uip login を実行してください。クライアント認証情報（ヘッドレス／CI）の場合は、--scope "OR.Default Apps.Read Apps.Write" を使用してください。3つすべての名前が必要です。OR.Default は Orchestrator 用、Apps.Read と Apps.Write は uip codedapp publish での Apps サービスの登録用です。External Application 自体に必要なのは Apps.Read と Apps.Write のみです。OR.Default は自動的に付与され、ポータルでは選択できないため、--scope に名前を指定してください。その後、publish または deploy が失敗した場合は、debug.md を参照してください。
2. ビルド — npm run build。ls dist/ で確認してください。
3. パック — uip codedapp pack dist -n <name> --version <version>。.uipath/<name>.<version>.nupkg が生成されます。以前に publish している場合は、バージョンを上げてください。
4. Publish — uip codedapp publish（アクションアプリの場合は -t Action を追加）。cat .uipath/app.config.json で確認してください。
5. Deploy — uip codedapp deploy -n <name> --folder-key <GUID>。選択したフォルダー（Type == "Personal" の個人用ワークスペース、名前を指定した既存のフォルダー、または新たに uip or folders create で作成したフォルダー）から、uip or folders list --output json を使って GUID を解決します。ダッシュボードではさらに デプロイモード（スタンドアロン／ガバナンス固定／ガバナンス）を選択し、--tags を設定してください。ダッシュボードのデプロイ実装 を参照してください。コマンドを対話形式で実行させないでください。uip or folders list --all --name が返すキーに対して、deploy が not found among folders accessible to your account と応答した場合は、待機やループをせず、--folder-key の代わりに UIPATH_FOLDER_KEY=<GUID> プレフィックスを付けて一度だけ再実行してください（ルール 11）。アプリの URL をユーザーに共有してください。**CLI が成功を報告した時点で Deploy は完了です。確認のためにアプリの URL をポーリングしたり、curl でアクセスしたりしないでください。**有効化にはデプロイ後数分かかるため、新しい URL が 404／503 を返すのは想定内であり、何も証明しません。待機しても時間を浪費するだけです。

SDK モジュールのインポート

ルックアップ手順（サブパスとクラスは、インストール済みパッケージの ls node_modules/@uipath/uipath-typescript/dist/ から確認）、型のインポート規約、アンチパターンの例については、references/sdk/imports.md を参照してください。主なルールは、以下の アンチパターン に記載されています。

主要な概念

アプリ設定（.uipath/app.config.json）

publish で作成され、deploy で使用されます。appName、systemName、appType、deploymentId、appUrl が含まれます。publish と deploy の間に .uipath/ を削除しないでください。

アクションスキーマ（action-schema.json）

アクションアプリでは、フォームと Maestro／Agent ワークフローの間のデータ契約を定義します。4 つのセクションがあります。inputs（自動化からの読み取り専用データ）、outputs（ユーザーが入力するフィールド）、inOuts（事前入力済みだが編集可能なフィールド）、outcomes（承認／却下などの送信ボタン）です。

トラブルシューティング

詳しい診断手順については、references/debug.md を参照してください。

エラー	原因	解決方法
Not authenticated	有効なセッションがありません	uip login を実行します
dist/ not found	アプリがビルドされていません	npm run build を実行します
Published app with package name '<name>' and version '<version>' already exists	同じ名前とバージョンのアプリがすでに公開されています（登録時に重複が拒否されます）	--version を更新して再公開します
Folder key required / プロンプトでデプロイが停止する	CLI でのデプロイに必要なフォルダーがありません	フォルダー名をキーに解決します。uip or folders list --output json を実行し、Name を照合して Key を確認してから、uip codedapp deploy --folder-key <GUID> ... を実行します。pack-publish-deploy.md を参照してください。
Folder key '<GUID>' was not found among folders accessible to your account（フォルダーは存在する）	--folder-key の事前チェックでは、アカウントのフォルダー一覧の不完全なコピーが使われます	--folder-key を指定せず、UIPATH_FOLDER_KEY=<GUID> uip codedapp deploy ... として再実行します。待機してから再試行してはいけません（ルール 11）。pack-publish-deploy.md を参照してください。
No packages found	.uipath/ に .nupkg がありません	先に pack を実行します
ログインに失敗する／リダイレクトエラー	OAuth の設定ミス	debug.md を参照してください
API 呼び出しが 401/CORS で失敗する	ベース URL が間違っています	cloud.uipath.com ではなく https://api.uipath.com を使用します

フォルダー識別子の名前は CLI と SDK で異なります。 CLI では UIPATH_FOLDER_KEY / --folder-key（文字列）を使用し、適用されるのは uip codedapp deploy のみです。SDK メソッドでは別のパラメーターを使用します。Maestro サービス（MaestroProcesses、ProcessInstances、Cases）は folderKey（GUID 文字列）を受け取り、Orchestrator サービス（Assets、Queues、Buckets、Processes）は folderId（数値）を受け取ります。CLI の環境変数を SDK の呼び出しに渡してはいけません。Maestro の folderKey を Orchestrator の folderId に変換する方法については、sdk/maestro.md を参照してください。また、GUID は数値ではないため、決して parseInt(folderKey) を使用しないでください。

完了時の出力

タスクが完了したら、実際に行った作業に該当する項目だけを報告してください。

1. 実施内容 — 作成、編集、削除したファイル（パスを列挙）；実行した CLI コマンド
2. 到達したステージ — 次のいずれか：scaffolded / built / packed / published / deployed
3. 生成された成果物（実際に存在するものだけを報告）：
   • dist/ — npm run build を実行した場合
   • .uipath/<name>.<version>.nupkg — pack を実行した場合
   • deploymentId を含む .uipath/app.config.json — publish を実行した場合
   • ライブデプロイ URL（app.config.json の appUrl）— deploy を実行した場合
   • 外部アプリケーションのクライアント ID — 今回のセッションで作成した場合
4. 次のステップ — タスクを停止した段階に応じて：
   • scaffolded のみ： ローカルで実行するには cd <app-name> && npm run dev
   • built だが packed されていない： ユーザーがデプロイを希望したら uip codedapp pack を実行できます
   • published だが deployed されていない： 公開状態にするには uip codedapp deploy を実行します
   • Deployed（Web）： デプロイ URL を開く／共有し、サインインのフローを確認します
   • Deployed（Action）： ルーティング名に一致する Maestro/Agent ワークフローによってトリガーされた Action Center のヒューマンタスクに、アプリが表示されます
5. 未解決の問題 — 認証の失敗、スコープの不一致、フォルダーキーの不足、スキップした手順、未解決のエラー

後続のステージが依頼されていたにもかかわらずスキップされた場合（例：デプロイを依頼されたが publish のみ成功した場合）は、次のステップのセクションで明示してください。

アンチパターン

以下の落とし穴は、重要なルールですでに取り上げられているものではありません。肯定的な要件として示されているルールについては、先頭の重要なルールセクションを参照してください。

• パッケージのルートからサービスクラスをインポートしないでください — サブパスを使用してください（例：@uipath/uipath-typescript/assets）。
• 非推奨のドットチェーン sdk.entities.getAll() を使用しないでください — コンストラクターインジェクションを使用してください：new Entities(sdk)。
• publish と deploy の間に .uipath/ を削除しないでください — deploy は publish によって書き込まれた app.config.json を読み取ります。