uipath-coded-apps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UiPath Coded Apps

Build, debug, and deploy UiPath Coded Web Applications and Coded Action Apps using the

uip codedapp

CLI and

@uipath/uipath-typescript

SDK.

使用

uip codedapp

CLI和

@uipath/uipath-typescript

SDK构建、调试和部署UiPath编码Web应用与编码动作应用。

When to Use This Skill

何时使用该技能

User wants to build, debug, or deploy a UiPath Coded Web App or Coded Action App

User asks about

uip codedapp

commands,

.uipath/

directory,

app.config.json

, or

action-schema.json

User wants to scaffold a new React/Vue frontend for UiPath Cloud or an Action Center form
User asks for app UI that a prebuilt UiPath widget covers: review/correct Document Understanding extraction results (Validation Station), chat with a conversational agent, browse/edit a Data Fabric entity in a grid, upload files to a storage bucket, display a PDF, or sign in with an external IdP (Google/SAML)
User wants to push/pull source between local and Studio Web
User wants to use the
```
@uipath/uipath-typescript
```
SDK from a coded app
User wants to run the full pipeline (build → pack → publish → deploy)
User wants to generate an agent-monitoring / analytics dashboard from a natural-language description — e.g. "show agent health, error rates, invocation volume, latency, active agents, KPIs, governance metrics, or consumption trends"
User says "build/create/generate a dashboard", describes metrics to visualize, or asks for an agent observability, operations, or cost view

用户想要构建、调试或部署UiPath编码Web应用或编码动作应用

用户询问

uip codedapp

命令、

.uipath/

目录、

app.config.json

或

action-schema.json

App Types

应用类型

Type	Description	Key Difference
Coded Web App	React/Vue/other frontend hosted on UiPath CDN	User-facing app accessed via a URL
Coded Action App	React form wired to UiPath Action Center	Rendered inside human task reviews in Maestro/Agent workflows

Two lifecycles, two scaffolding entry points.
Standalone coded app: scaffold with
npx create-vite@latest
(see create-web-app.md / create-action-app.md). No
project.uiproj
/
webAppManifest.json
— those are solution-membership artefacts and standalone apps don't need them. Deploy via
uip codedapp pack
→
uip codedapp publish
(
-t Action
for action apps) →
uip codedapp deploy
. This is the classic single-app lifecycle covered by the rest of this skill.
In-solution coded app: run
uip codedapp init
from inside a
.uipx
solution. Init writes
project.uiproj
(
ProjectType: "AppV2"
) +
webAppManifest.json
, nests runtime + build artefacts under
source/dist/
, auto-registers the project as
Type: "AppV2"
in the
.uipx
, and emits
resources/solution_folder/app/{Coded,CodedAction}/
. From then on the app is part of the solution —
uip solution pack
bundles its
.nupkg
and
uip solution deploy run
provisions it in the deployment folder. Do not run
uip codedapp pack
/
publish
/
deploy
on a coded app that's already registered in
.uipx
— that bypasses the solution's deploy config (external client ID, routing name, action schema) and double-registers the package.
uip solution projects add
/
uip solution projects import
register existing AppV2 folders too, reading
webAppManifest.config.isActionApp
to pick the
Coded
/
CodedAction
subType. For the solution-side lifecycle see /uipath:uipath-solution.
uip codedapp init
is for solutions only. It is not the scaffolding entry point for a standalone coded app — use
create-vite
for that.

类型	描述	核心差异
编码Web应用（Coded Web App）	托管在UiPath CDN上的React/Vue或其他前端应用	用户可通过URL访问的面向用户的应用
编码动作应用（Coded Action App）	与UiPath Action Center关联的React表单	在Maestro/代理工作流的人工任务审核中渲染

两种生命周期，两种搭建入口。
独立编码应用：使用
npx create-vite@latest
搭建（详见create-web-app.md / create-action-app.md）。无需
project.uiproj
/
webAppManifest.json
— 这些是解决方案成员的产物，独立应用不需要它们。通过
uip codedapp pack
→
uip codedapp publish
（动作应用需加
-t Action
） →
uip codedapp deploy
进行部署。这是本技能涵盖的经典单应用生命周期。
解决方案内编码应用：在
.uipx
解决方案内运行
uip codedapp 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、路由名称、动作 schema）并导致包重复注册。
uip solution projects add
/
uip solution projects import
也可注册现有AppV2文件夹，它会读取
webAppManifest.config.isActionApp
来选择
Coded
/
CodedAction
子类型。解决方案端生命周期详见/uipath:uipath-solution。
**
uip codedapp init
仅适用于解决方案。**它不是独立编码应用的搭建入口 — 请使用
create-vite
进行搭建。

Critical Rules

关键规则

Identify the app type before doing anything else. Ask as a structured choice (Rule 18): Coded Web App — custom frontend deployed to UiPath Cloud · Coded Action App — form for Action Center human task reviews. The two paths diverge on scaffolding, redirect URI, and publish flag — do not guess.
Always check login status first. Run
```
uip login status --output json
```
before any cloud command. If not logged in, run
```
uip login
```
.
Never skip the build step. Run
```
npm run build
```
after scaffolding (to verify the scaffold compiles) and again before
```
pack
```
or
```
push
```
(to produce the deployable
```
dist/
```
). Verify
```
dist/
```
exists each time.
Pack → Publish → Deploy order is required. Each step depends on the previous one producing its output.
Bump the version for re-publish. If the same version already exists in Orchestrator, publish will fail.
Action apps require
-t Action
on publish. Run
```
uip codedapp publish -t Action
```
(not the default
```
Web
```
type).
Never handle access tokens manually. Do not pass, print, parse, source, or set cached access tokens. Use
```
uip login
```
and supported
```
uip codedapp
```
commands; the CLI manages authentication.
Base URL must use the API subdomain.
```
https://api.uipath.com
```
not
```
https://cloud.uipath.com
```
. See the table below.
vite.config.ts
must always set
base: './'
. The platform handles URL routing — apps must use relative asset paths. Do not use a routing name or a sub-path here. Import static assets through the bundler (
```
import logo from './assets/logo.png'
```
) so Vite fingerprints and base-rewrites them. Do NOT place them in
```
public/
```
or reference them by a hardcoded
```
/
```
-rooted path — those bypass base rewriting and 404 after deploy under the non-root mount.
Use
getAppBase()
from
@uipath/uipath-typescript
for any absolute URL constructed at runtime — router basename, image
```
src
```
,
```
fetch
```
paths. Deployed apps mount at a non-root prefix;
```
/
```
-rooted paths work locally but 404 after deploy. Vite's
```
base: './'
```
only fixes import-time references.
uip codedapp deploy
must run non-interactively. Pass the folder key as
```
--folder-key <GUID>
```
(or as
```
UIPATH_FOLDER_KEY=<GUID>
```
env-var prefix — either works). The interactive folder picker fails in non-TTY contexts (CI, agent shells). If the user provides a folder name, resolve it with the server-side filter
```
uip or folders list --all --name "<name>" --output json
```
and pick the row whose
```
Name
```
exactly equals the target, then read its
```
Key
```
(the plain list is paginated 50/page and
```
--name
```
is a contains match requiring
```
--all
```
, so never just take the first row). A personal workspace is not in
```
--all
```
— resolve it from the default
```
uip or folders list --output json
```
where
```
Type == "Personal"
```
. To deploy into a new folder, create it first with
```
uip or folders create "<NAME>" --output json
```
and read
```
Data.Key
```
. The
```
uip or ...
```
commands require the Orchestrator tool — install once via
```
uip tools install @uipath/orchestrator-tool
```
(check first with
```
uip tools list
```
).
Guard against text overflow in every UI. See patterns.md "Preventing Text Overflow".
Inspect the DF schema before writing analytics, filters, or seeds. Run
```
uip df entities get <ENTITY_ID> --output json
```
to inspect fields and types. At runtime, use
```
entities.getById(<id>)
```
from the app's authenticated session. DF doesn't behave like a typical RDBMS; see sdk/data-fabric.md "Anti-shapes & gotchas".
Every list call returns ONE page — even with no options. There is no "give me everything" path. Applies to
```
getAll
```
,
```
getAllRecords
```
,
```
queryRecordsById
```
,
```
getFileMetaData
```
, etc.
```
getAll()
```
with no options does NOT return all rows; the SDK sends no
```
pageSize
```
and the server applies its own cap, wrapped in a misleadingly-named
```
NonPaginatedResponse
```
. To list every row from a source that may exceed the cap, you MUST loop the cursor:
```
while (page.hasNextPage) { page = await getAll({ cursor: page.nextCursor }) }
```
and accumulate
```
items
```
. Reading
```
result.items.length
```
after a single call is almost always a bug. See sdk/pagination.md.
Tables of dynamic data must paginate, not dump all rows in one scroll. Page size 25–50 with next/prev/page-number controls and a "Showing X–Y of Z" summary. Top-N + "see all" is acceptable for explicitly summary panels (e.g., "Top 10 oldest"). Infinite-scroll-of-N-rows is unusable for operational dashboards. Applies to any table backed by any service (DF entities, Tasks, Jobs, Conversations, Process Instances, etc.). See patterns.md "Tabular Data".
When adding any new SDK method call, verify the configured OAuth scope already includes the required scope — both dashboards and web apps read the
```
scope
```
key from
```
uipath.json
```
. Write operations, action methods (
```
Jobs.stop
```
,
```
Tasks.complete
```
,
```
ProcessInstances.cancel
```
, etc.), or first use of a new service typically need broader scopes than read-only flows. Mismatched scopes fail silently with
```
401
```
/
```
403
```
on the first call. See oauth-scopes.md for scope bundles and the per-method lookup protocol (the per-method table ships inside the SDK package at
```
node_modules/@uipath/uipath-typescript/docs/oauth-scopes.md
```
).
Never call
sdk.initialize()
in an action app. That is web-app-only — it starts a PKCE OAuth redirect. Action apps run in Action Center's iframe with a host-injected session: construct
```
new UiPath()
```
(no args) and use it directly. See create-action-app.md
```
src/uipath.ts
```
.
Never make the user type magic phrases. Whenever you ask the user to pick between known options (app type, build/edit/deploy intent, OAuth setup, deploy pinning), present a structured choice via the host coding agent's native question tool (selectable options) when one exists. Mechanics: one option per choice with a short bold label + one-line description of what picking it does; put the recommended option first and suffix its label "(Recommended)"; keep to at most 4 options (reserve one slot for an escape option like Make changes / Cancel when applicable). If there are 5+ candidates, or the host agent has no question tool, render a plain numbered list instead and accept the number or the option label as the answer. A free-text reply must always remain valid (e.g. a plan-change request) and takes precedence over the options. Exception — never put a question in the same response as a long output: plan-approval gates are free-text by design (the plan ends with "confirm or tell me what to change"); structured questions fire only on later, short turns. See
```
references/dashboards/plugins/build/impl.md
```
.
Never guess SDK method signatures — read the installed types. The authoritative reference for method names, parameters, return types, and usage examples is
```
node_modules/@uipath/uipath-typescript/dist/<subpath>/index.d.ts
```
(full JSDoc; matches the installed SDK version exactly). Before calling a service you have not used in this session, Read its
```
.d.ts
```
. If
```
node_modules
```
is absent, run the install step first — the app cannot build without it. The
```
references/sdk/*.md
```
files deliberately do NOT list signatures; they cover only scopes, calling conventions, and traps the types cannot express. See references/sdk/imports.md for the missing-capability protocol. Boundary: read the
.d.ts
, never the compiled bundle.
```
dist/*.mjs
```
/
```
*.js
```
is minified implementation, not API — reading it dead-ends. A grep with no output confirms absence; treat a genuine gap as unsupported (use the documented alternative) rather than escalating the search into the bundle.

首先确定应用类型。以结构化选项的方式询问（规则18）：编码Web应用 — 部署至UiPath Cloud的自定义前端 · 编码动作应用 — 用于Action Center人工任务审核的表单。这两种路径在搭建、重定向URI和发布标志上有所不同，请勿猜测。
始终先检查登录状态。执行任何云命令前，运行
```
uip login status --output json
```
。若未登录，运行
```
uip login
```
。
绝不要跳过构建步骤。搭建完成后运行
```
npm run build
```
（验证搭建的项目可编译），在
```
pack
```
或
```
push
```
前再次运行（生成可部署的
```
dist/
```
目录）。每次都要确认
```
dist/
```
目录存在。
必须遵循打包→发布→部署的顺序。每个步骤都依赖前一步生成的输出。
重新发布需更新版本号。如果相同版本已存在于Orchestrator中，发布将失败。
动作应用发布时必须添加
-t Action
参数。运行
```
uip codedapp publish -t Action
```
（而非默认的
```
Web
```
类型）。
绝不要手动处理访问令牌。请勿传递、打印、解析、获取或设置缓存的访问令牌。使用
```
uip login
```
和受支持的
```
uip codedapp
```
命令；CLI会管理认证。
基础URL必须使用API子域名。使用
```
https://api.uipath.com
```
而非
```
https://cloud.uipath.com
```
。详见下表。
vite.config.ts
必须始终设置
base: './'
。平台会处理URL路由 — 应用必须使用相对资源路径。此处请勿使用路由名称或子路径。通过打包工具导入静态资源（
```
import logo from './assets/logo.png'
```
），以便Vite为资源添加指纹并重写基础路径。请勿将资源放在
```
public/
```
目录或通过硬编码的根路径
```
/
```
引用 — 这些会绕过基础路径重写，部署后在非根挂载路径下会出现404错误。
运行时构造任何绝对URL都必须使用
@uipath/uipath-typescript
中的
getAppBase()
— 包括路由器基准名称、图片
```
src
```
、
```
fetch
```
路径。部署后的应用挂载在非根前缀下；根路径
```
/
```
在本地可正常工作，但部署后会出现404错误。Vite的
```
base: './'
```
仅能修复导入时的引用。
uip codedapp deploy
必须以非交互模式运行。通过
```
--folder-key <GUID>
```
（或
```
UIPATH_FOLDER_KEY=<GUID>
```
环境变量前缀，两种方式均可）传递文件夹密钥。交互式文件夹选择器在非TTY环境（CI、代理Shell）中会失败。如果用户提供文件夹名称，通过服务器端过滤器
```
uip or folders list --all --name "<name>" --output json
```
解析，选择
```
Name
```
与目标完全匹配的行，然后读取其
```
Key
```
（普通列表每页分页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 install @uipath/orchestrator-tool
```
安装一次（安装前先用
```
uip tools list
```
检查）。
每个UI都要防止文本溢出。详见patterns.md中的“防止文本溢出”部分。
编写分析、过滤器或种子数据前，先检查DF schema。运行
```
uip df entities get <ENTITY_ID> --output json
```
检查字段和类型。运行时，使用应用已认证会话中的
```
entities.getById(<id>)
```
。DF的行为与典型关系型数据库不同；详见sdk/data-fabric.md中的“反模式与注意事项”。
所有列表调用仅返回一页结果 — 即使没有选项。没有“获取全部数据”的路径。适用于
```
getAll
```
、
```
getAllRecords
```
、
```
queryRecordsById
```
、
```
getFileMetaData
```
等方法。不带选项的
```
getAll()
```
不会返回所有行；SDK不发送
```
pageSize
```
，服务器会应用自身的限制，并封装在名称易混淆的
```
NonPaginatedResponse
```
中。要从可能超过限制的源获取所有行，必须循环游标：
```
while (page.hasNextPage) { page = await getAll({ cursor: page.nextCursor }) }
```
并累加
```
items
```
。单次调用后读取
```
result.items.length
```
几乎总是错误的。详见sdk/pagination.md。
动态数据表格必须分页，不要一次性加载所有行。每页显示25–50条数据，提供下一页/上一页/页码控制，以及“显示第X–Y条，共Z条”的摘要。对于明确的摘要面板（例如“最久的10条”），显示前N条+“查看全部”是可接受的。无限滚动加载N行数据的方式不适用于运维仪表盘。适用于任何由服务（DF实体、任务、作业、对话、流程实例等）支持的表格。详见patterns.md中的“表格数据”部分。
添加任何新的SDK方法调用时，验证已配置的OAuth scope是否包含所需权限 — 仪表盘和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
```
中）。
绝不要在动作应用中调用
sdk.initialize()
。该方法仅适用于Web应用 — 它会启动PKCE OAuth重定向。动作应用在Action Center的iframe中运行，宿主会注入会话：直接构造
```
new UiPath()
```
（无参数）并使用即可。详见create-action-app.md中的
```
src/uipath.ts
```
。
绝不要让用户输入魔法短语。每当需要用户在已知选项中选择时（应用类型、构建/编辑/部署意图、OAuth设置、部署固定），如果宿主编码代理有原生的问题工具（可选选项），请通过该工具呈现结构化选项。规则：每个选项包含简短的粗体标签+一行描述选择该选项的作用；将推荐选项放在第一位并在标签后添加“（推荐）”后缀；最多保留4个选项（必要时预留一个退出选项，如修改 / 取消）。如果有5个及以上候选选项，或宿主代理没有问题工具，则改为显示普通编号列表，并接受数字或选项标签作为答案。自由文本回复必须始终有效（例如更改计划的请求），且优先级高于选项。例外 — 不要在长输出的同一条回复中提出问题：计划审批门设计为自由文本（计划结尾为“确认或告知我需要修改的内容”）；结构化问题仅在后续简短对话中触发。详见
```
references/dashboards/plugins/build/impl.md
```
。
绝不要猜测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无输出确认功能不存在；将真正的功能缺口视为不支持（使用文档中提到的替代方案），而不要深入包中搜索。

Disambiguation — Apps vs Dashboards

歧义消除 — 应用 vs 仪表盘

Route directly to Apps workflow (sections below) when you see:

web app

action app

codedapp

app.config.json

action-schema.json

scaffold app

deploy app

pack

publish

push

pull

debug app

Route directly to references/dashboards/CAPABILITY.md when you see:

dashboard

analytics

KPI

metrics

Insights

observability

admin console

report

chart

trend

governance report

agent metrics

When intent is ambiguous — ask "Which fits your goal?" as a structured choice (Rule 18):

Option	Description
Build or modify a Web App / Action App	Scaffold a UI, form, or app that deploys to Automation Cloud
Generate a dashboard	Analytics or admin view from a natural-language description

当看到以下关键词时，直接路由到应用工作流（以下章节）：

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应用/动作应用	搭建可部署至Automation Cloud的UI、表单或应用
生成仪表盘	根据自然语言描述生成分析或管理视图

Task Navigation

任务导航

I want to...	Read this
Create a new Coded Web App	references/create-web-app.md
Create a new Coded Action App	references/create-action-app.md
Debug auth or config issues	references/debug.md
Push/pull code to Studio Web	references/file-sync.md
Package and deploy	references/pack-publish-deploy.md
Full CLI command reference	references/commands-reference.md
Embed the DU Validation Station widget	references/widgets/validation-station.md
Embed the Conversational Agent chat widget	references/widgets/conversational-agent-chat.md
Embed the Data Fabric DataTable widget	references/widgets/datatable.md
Embed the multi-file bucket upload widget	references/widgets/multi-file-upload.md
Embed the PDF viewer widget	references/widgets/pdf-viewer.md
Add external IdP sign-in buttons (Google/SAML)	references/widgets/external-auth.md
OAuth scopes for SDK services	references/oauth-scopes.md
SDK: Import paths & subpath exports	references/sdk/imports.md
SDK: Assets, Queues, Buckets, Processes, Jobs, Attachments	references/sdk/orchestrator.md
SDK: Data Fabric (Entities, ChoiceSets)	references/sdk/data-fabric.md
SDK: Maestro (Processes, Cases)	references/sdk/maestro.md
SDK: Action Center (Tasks)	references/sdk/action-center.md
SDK: Conversational Agent	references/sdk/conversational-agent.md
SDK: Agent Feedback	references/sdk/feedback.md
SDK: Pagination	references/sdk/pagination.md
SDK: Agents & Agent Memory (Insights RTM)	references/sdk/agents.md
SDK: Agent Traces (Insights RTM)	references/sdk/traces.md
SDK: Governance — policy evaluations (Insights API)	references/sdk/governance.md
SDK: Agent Governance Decisions — runtime compliance (Insights RTM)	references/sdk/governance-traces.md
UI Patterns (polling, BPMN, HITL, text overflow, table pagination)	references/patterns.md
Generate an admin dashboard from NLP	references/dashboards/CAPABILITY.md

我想要...	查看此文档
创建新的编码Web应用	references/create-web-app.md
创建新的编码动作应用	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
嵌入对话代理聊天组件	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
添加外部身份提供商登录按钮（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（实体、选择集）	references/sdk/data-fabric.md
SDK：Maestro（流程、案例）	references/sdk/maestro.md
SDK：Action Center（任务）	references/sdk/action-center.md
SDK：对话代理	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、人工在环、文本溢出、表格分页）	references/patterns.md
从自然语言生成管理仪表盘	references/dashboards/CAPABILITY.md

CLI Setup

CLI设置

bash

undefined

bash

undefined

Install the UiPath CLI (run once)

安装UiPath CLI（运行一次）

npm install -g @uipath/cli

Install the coded apps tool

安装编码应用工具

uip tools install @uipath/codedapp-tool

Install the Orchestrator tool (needed to resolve folder name → key for deploy)

安装Orchestrator工具（部署时需将文件夹名称解析为密钥）

uip tools install @uipath/orchestrator-tool

Verify both are installed

验证两者均已安装

uip tools list

Resolve uip if not on PATH

如果uip不在PATH中，解析其路径

UIP=$(command -v uip 2>/dev/null || npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip $UIP --version


Authenticate before any cloud command:

```bash
uip login status --output json         # check if logged in
uip login                              # interactive OAuth (opens browser)
uip login --authority https://alpha.uipath.com   # non-production environments

UIP=$(command -v uip 2>/dev/null || npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip $UIP --version


执行任何云命令前先认证：

```bash
uip login status --output json         # 检查是否已登录
uip login                              # 交互式OAuth（打开浏览器）
uip login --authority https://alpha.uipath.com   # 非生产环境

Client-credentials (headless/CI) — scope MUST name one Orchestrator scope AND

客户端凭证（无头/CI环境） — 权限必须包含一个Orchestrator权限和

the two Apps-service scopes. Neither set covers the other:

两个应用服务权限。两组权限互不覆盖：

OR.Default → Orchestrator

Apps.Read Apps.Write → Apps-service registration in

uip codedapp publish

Apps.Read Apps.Write →

uip codedapp publish

中的应用服务注册

Do NOT substitute granular Orchestrator scopes (OR.Folders/OR.Execution/

请勿用细粒度的Orchestrator权限（OR.Folders/OR.Execution/

OR.Administration) for OR.Default.

OR.Administration）替代OR.Default。

uip login
--client-id <id>
--client-secret <secret>
--organization <org>
--tenant <tenant>
--scope "OR.Default Apps.Read Apps.Write"
--authority https://alpha.uipath.com # omit --authority for production


> **The `uip login` session scope is separate from the app's runtime OAuth scopes.** The scopes in `uipath.json` are what the *deployed app* requests at runtime (see [oauth-scopes.md](references/oauth-scopes.md)). The `--scope` on `uip login` above is what the *CLI session* needs to call the Apps registration API during `uip codedapp publish`. `uip codedapp publish` does two things: uploads the package (needs `OR.Default`) **and** registers the coded app (needs `Apps.Read Apps.Write`). For what each failure looks like, see [debug.md](references/debug.md#publish--deploy-fails-under-a-client-credentials-login).


> **`uip login`会话权限与应用运行时OAuth权限是分开的。**`uipath.json`中的权限是**已部署应用**在运行时请求的权限（详见[oauth-scopes.md](references/oauth-scopes.md)）。上述`uip login`中的`--scope`是**CLI会话**在`uip codedapp publish`期间调用应用注册API所需的权限。`uip codedapp publish`会执行两项操作：上传包（需要`OR.Default`）**以及**注册编码应用（需要`Apps.Read Apps.Write`）。每种失败的表现详见[debug.md](references/debug.md#publish--deploy-fails-under-a-client-credentials-login)。

SDK Config (web app)

SDK配置（Web应用）

The web app initializes the SDK with

new UiPath()

(no config). At runtime the SDK reads

clientId

scope

orgName

tenantName

baseUrl

, and

redirectUri

from

<meta name="uipath:*">

tags. During local dev

@uipath/coded-apps-dev

injects those tags from

uipath.json

(committed) — the single config source, holding

clientId

scope

orgName

tenantName

baseUrl

, and

redirectUri

(the Vite dev URL for local). In production the UiPath platform injects the same tags directly.

To change any of these values, edit

uipath.json

Web应用使用

new UiPath()

（无配置）初始化SDK。运行时，SDK会从

<meta name="uipath:*">

标签读取

clientId

、

scope

、

orgName

、

tenantName

、

baseUrl

和

redirectUri

。本地开发时，

@uipath/coded-apps-dev

会从

uipath.json

（已提交）注入这些标签 — 这是唯一的配置源，包含

clientId

、

scope

、

orgName

、

tenantName

、

baseUrl

和

redirectUri

（本地Vite开发URL）。生产环境中，UiPath平台会直接注入相同的标签。

要更改这些值，请编辑

uipath.json

。

CLI Environment Variables

CLI环境变量

Variable	Used By	Description
`UIPATH_PROJECT_ID`	`uip codedapp push` / `uip codedapp pull`	Studio Web project ID

Base URL by environment:

Environment	Correct Base URL
Production (cloud)	`https://api.uipath.com`
Staging	`https://staging.api.uipath.com`
Alpha	`https://alpha.api.uipath.com`

变量	使用者	描述
`UIPATH_PROJECT_ID`	`uip codedapp push` / `uip codedapp pull`	Studio Web项目ID

各环境对应的基础URL：

环境	正确的基础URL
生产环境（cloud）	`https://api.uipath.com`
预发布环境	`https://staging.api.uipath.com`
Alpha环境	`https://alpha.api.uipath.com`

Quick Deploy (Full Pipeline)

快速部署（完整流程）

Do NOT pause between steps to ask "should I continue?" — execute the full pipeline. Only stop if you need auth credentials or an app name.

Auth —
```
uip login status --output json
```
. If not logged in, ask the user for their environment and run
```
uip login
```
. With client credentials (headless/CI), use
```
--scope "OR.Default Apps.Read Apps.Write"
```
— all three names are required:
```
OR.Default
```
for Orchestrator,
```
Apps.Read
```
and
```
Apps.Write
```
for the Apps-service registration in
```
uip codedapp publish
```
. The External Application itself needs only
```
Apps.Read
```
and
```
Apps.Write
```
;
```
OR.Default
```
is auto-granted and not portal-selectable, so name it in
```
--scope
```
. If publish or deploy then fails, see debug.md.
Build —
```
npm run build
```
. Verify
```
ls dist/
```
.

Pack —

uip codedapp pack dist -n <name> --version <version>

. Produces

.uipath/<name>.<version>.nupkg

. Bump version if previously published.

Publish —

uip codedapp publish

(add

-t Action

for action apps). Verify

cat .uipath/app.config.json

Deploy —
```
uip codedapp deploy -n <name> --folder-key <GUID>
```
. Resolve the GUID from the chosen folder: a personal workspace (
```
Type == "Personal"
```
), a named existing folder, or a freshly
```
uip or folders create
```
d one — via
```
uip or folders list --output json
```
. Dashboards additionally choose a deploy mode (standalone / governance-pinned / governance) that sets
```
--tags
```
; see dashboards deploy impl. Never let the command go interactive. Share the app URL with the user.

步骤间请勿暂停询问“是否继续？” — 执行完整流程。仅在需要认证凭证或应用名称时停止。

认证 — 运行
```
uip login status --output json
```
。若未登录，询问用户环境并运行
```
uip login
```
。使用客户端凭证（无头/CI环境）时，需使用
```
--scope "OR.Default Apps.Read Apps.Write"
```
— 三个权限名称均为必填：
```
OR.Default
```
用于Orchestrator，
```
Apps.Read
```
和
```
Apps.Write
```
用于
```
uip codedapp publish
```
中的应用服务注册。外部应用本身仅需要
```
Apps.Read
```
和
```
Apps.Write
```
；
```
OR.Default
```
是自动授予的，无法在门户中选择，因此需在
```
--scope
```
中指定。如果发布或部署失败，详见debug.md。
构建 — 运行
```
npm run build
```
。验证
```
ls dist/
```
。

打包 — 运行

uip codedapp pack dist -n <name> --version <version>

。生成

.uipath/<name>.<version>.nupkg

。如果之前已发布过，需更新版本号。

发布 — 运行

uip codedapp publish

（动作应用需添加

-t Action

）。验证

cat .uipath/app.config.json

。

部署 — 运行
```
uip codedapp deploy -n <name> --folder-key <GUID>
```
。从所选文件夹解析GUID：个人工作区（
```
Type == "Personal"
```
）、已命名的现有文件夹或新创建的文件夹（通过
```
uip or folders create
```
创建） — 使用
```
uip or folders list --output json
```
。仪表盘还需选择部署模式（独立/治理固定/治理）来设置
```
--tags
```
；详见仪表盘部署实现。绝不要让命令进入交互模式。将应用URL分享给用户。

SDK Module Imports

SDK模块导入

See references/sdk/imports.md for the lookup protocol (subpaths and classes are discovered from the installed package —

ls node_modules/@uipath/uipath-typescript/dist/

), type import conventions, and anti-pattern examples. Core rules are listed under Anti-patterns below.

导入协议（子路径和类从已安装的包中发现 —

ls node_modules/@uipath/uipath-typescript/dist/

）、类型导入约定和反模式示例详见references/sdk/imports.md。核心规则列在下方的反模式部分。

Key Concepts

核心概念

App Config (

.uipath/app.config.json

)

应用配置（

.uipath/app.config.json

）

Created by

publish

, consumed by

deploy

. Contains

appName

systemName

appType

deploymentId

appUrl

. Do not delete

.uipath/

between publish and deploy.

由

publish

命令创建，供

deploy

命令使用。包含

appName

、

systemName

、

appType

、

deploymentId

、

appUrl

。发布与部署之间请勿删除

.uipath/

目录。

Action Schema (

action-schema.json

)

动作Schema（

action-schema.json

）

Action apps define a data contract between the form and the Maestro/Agent workflow. It has four sections:

inputs

(read-only data from automation),

outputs

(user-filled fields),

inOuts

(pre-populated but editable), and

outcomes

(submission buttons like Approve/Reject).

动作应用定义了表单与Maestro/代理工作流之间的数据契约。它包含四个部分：

inputs

（来自自动化的只读数据）、

outputs

（用户填写的字段）、

inOuts

（预填充但可编辑的字段）、

outcomes

（提交按钮，如批准/拒绝）。

Troubleshooting

故障排除

See references/debug.md for detailed diagnosis steps.

Error	Cause	Fix
`Not authenticated`	No valid session	Run `uip login`
`dist/ not found`	App not built	Run `npm run build`
`Published app with package name '<name>' and version '<version>' already exists`	Same name+version already published (registration rejects duplicates)	Bump `--version` and re-publish
`Folder key required` / deploy hangs on prompt	Missing folder for CLI deploy	Resolve folder name → key via `uip or folders list --output json` (match on `Name` , read `Key` ), then run `uip codedapp deploy --folder-key <GUID> ...` . See pack-publish-deploy.md.
`No packages found`	No `.nupkg` in `.uipath/`	Run `pack` first
Login fails / redirect error	OAuth misconfiguration	See debug.md
API calls fail with 401/CORS	Wrong base URL	Use `https://api.uipath.com` not `cloud.uipath.com`

Folder identifier names differ across CLI and SDK. The CLI uses
UIPATH_FOLDER_KEY
/
--folder-key
(string) and applies only to
uip codedapp deploy
. SDK methods use different parameters: Maestro services (
MaestroProcesses
,
ProcessInstances
,
Cases
) take
folderKey
(string GUID), Orchestrator services (
Assets
,
Queues
,
Buckets
,
Processes
) take
folderId
(number). Do not pass the CLI env var into SDK calls. To bridge from a Maestro
folderKey
to an Orchestrator
folderId
, see sdk/maestro.md — and never
parseInt(folderKey)
, the GUID is not numeric.

详细诊断步骤详见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。
`No packages found`	`.uipath/` 中无 `.nupkg` 文件	先运行 `pack` 命令
登录失败/重定向错误	OAuth配置错误	详见debug.md
API调用返回401/CORS错误	基础URL错误	使用 `https://api.uipath.com` 而非 `cloud.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 — 且绝不要
parseInt(folderKey)
，因为GUID不是数字。

Completion Output

完成输出

When you finish a task, report only what's applicable to the work actually done:

What was done — files created, edited, or deleted (list paths); CLI commands run
Stage reached — one of: scaffolded / built / packed / published / deployed
Artifacts produced (report only the ones that actually exist):
- ```
dist/
```
  — if
```
npm run build
```
  was run
- ```
.uipath/<name>.<version>.nupkg
```
  — if
```
pack
```
  was run
- ```
.uipath/app.config.json
```
  with
```
deploymentId
```
  — if
```
publish
```
  was run
- Live deployment URL (
```
appUrl
```
  from
```
app.config.json
```
  ) — if
```
deploy
```
  was run
- External Application client ID — if one was created this session
Next steps, depending on where the task stopped:
- Scaffolded only:
```
cd <app-name> && npm run dev
```
  to run locally
- Built but not packed: ready to
```
uip codedapp pack
```
  when the user wants to deploy
- Published but not deployed: run
```
uip codedapp deploy
```
  to go live
- Deployed (Web): open/share the deployment URL; verify sign-in flow
- Deployed (Action): the app will render in Action Center human tasks triggered by Maestro/Agent workflows matching the routing name
Open issues — any auth failures, scope mismatches, missing folder key, skipped steps, or errors left unresolved

If a later stage was requested but skipped (e.g., user asked to deploy but only

publish

succeeded), call it out explicitly in the next-steps section.

完成任务后，仅报告与实际完成工作相关的内容：

已完成的工作 — 创建、编辑或删除的文件（列出路径）；运行的CLI命令
当前阶段 — 以下之一：已搭建 / 已构建 / 已打包 / 已发布 / 已部署
生成的产物（仅报告实际存在的产物）：
- ```
dist/
```
  — 如果运行了
```
npm run build
```
- ```
.uipath/<name>.<version>.nupkg
```
  — 如果运行了
```
pack
```
- 包含
```
deploymentId
```
  的
```
.uipath/app.config.json
```
  — 如果运行了
```
publish
```
- 实时部署URL（来自
```
app.config.json
```
  的
```
appUrl
```
  ） — 如果运行了
```
deploy
```
- 外部应用客户端ID — 如果本次会话创建了一个
下一步操作，取决于任务停止的阶段：
- 仅完成搭建：运行
```
cd <app-name> && npm run dev
```
  在本地运行
- 已构建但未打包：准备好后运行
```
uip codedapp pack
```
  进行部署
- 已发布但未部署：运行
```
uip codedapp deploy
```
  上线
- 已部署（Web应用）：打开/分享部署URL；验证登录流程
- 已部署（动作应用）：该应用会在Maestro/代理工作流触发的Action Center人工任务中渲染，匹配路由名称
未解决问题 — 任何认证失败、权限不匹配、缺少文件夹密钥、跳过的步骤或未解决的错误

如果用户请求了后续阶段但未完成（例如用户要求部署但仅完成了

publish

），请在下一步操作部分明确指出。

Anti-patterns

反模式

These pitfalls are not already covered by the Critical Rules. For rules stated as positive requirements, see the Critical Rules section at the top.

Don't import service classes from the package root — use the subpath (e.g.,
```
@uipath/uipath-typescript/assets
```
).
Don't use the deprecated dot-chain
sdk.entities.getAll()
— use constructor DI:
```
new Entities(sdk)
```
.

Don't delete
.uipath/
between
publish
and
deploy
—

deploy

reads

app.config.json

written by

publish

这些陷阱未在关键规则中涵盖。如需查看正面要求的规则，请参阅顶部的关键规则部分。

不要从包根目录导入服务类 — 使用子路径（例如
```
@uipath/uipath-typescript/assets
```
）。
不要使用已弃用的链式调用
sdk.entities.getAll()
— 使用构造函数依赖注入：
```
new Entities(sdk)
```
。
不要在
publish
与
deploy
之间删除
.uipath/
目录 —
```
deploy
```
会读取
```
publish
```
生成的
```
app.config.json
```
。

uipath-coded-apps

Original

Translation

UiPath Coded Apps

UiPath Coded Apps

When to Use This Skill

何时使用该技能

App Types

应用类型

Critical Rules

关键规则

Disambiguation — Apps vs Dashboards

歧义消除 — 应用 vs 仪表盘

Task Navigation

任务导航

CLI Setup

CLI设置

Install the UiPath CLI (run once)

安装UiPath CLI（运行一次）

Install the coded apps tool

安装编码应用工具

Install the Orchestrator tool (needed to resolve folder name → key for deploy)

安装Orchestrator工具（部署时需将文件夹名称解析为密钥）

Verify both are installed

验证两者均已安装

Resolve uip if not on PATH

如果uip不在PATH中，解析其路径

Client-credentials (headless/CI) — scope MUST name one Orchestrator scope AND

客户端凭证（无头/CI环境） — 权限必须包含一个Orchestrator权限和

the two Apps-service scopes. Neither set covers the other:

两个应用服务权限。两组权限互不覆盖：

OR.Default → Orchestrator

OR.Default → Orchestrator

Apps.Read Apps.Write → Apps-service registration in uip codedapp publish

Apps.Read Apps.Write → uip codedapp publish中的应用服务注册

Do NOT substitute granular Orchestrator scopes (OR.Folders/OR.Execution/

请勿用细粒度的Orchestrator权限（OR.Folders/OR.Execution/

OR.Administration) for OR.Default.

OR.Administration）替代OR.Default。

SDK Config (web app)

SDK配置（Web应用）

CLI Environment Variables

CLI环境变量

Quick Deploy (Full Pipeline)

快速部署（完整流程）

SDK Module Imports

SDK模块导入

Key Concepts

核心概念

App Config (.uipath/app.config.json)

应用配置（.uipath/app.config.json）

Action Schema (action-schema.json)

动作Schema（action-schema.json）

Troubleshooting

故障排除

Completion Output

完成输出

Anti-patterns

反模式

Apps.Read Apps.Write → Apps-service registration in
`uip codedapp publish`

Apps.Read Apps.Write →
`uip codedapp publish`
中的应用服务注册

App Config (
`.uipath/app.config.json`
)

应用配置（
`.uipath/app.config.json`
）

Action Schema (
`action-schema.json`
)

动作Schema（
`action-schema.json`
）