uipath-admin

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UiPath Admin

Administrative operations on UiPath via

uip admin

— Identity Server, Authorization, OMS, IP Restriction, Audit. Per-area workflows, command references, and procedures are in the linked files below — this file is the entry contract.

通过

uip admin

对UiPath执行管理操作 —— 涵盖Identity Server、授权管理、OMS、IP限制、审计功能。各领域的工作流、命令参考和操作流程见下方链接文件，本文档为入口约定。

When to Use This Skill

何时使用本技能

Identity

身份管理

Manage identity users — list, create, invite, update, delete
Manage groups — CRUD + add/remove members
Manage robot accounts — create, update, delete unattended robot identities
Manage external apps — OAuth2 clients, secrets, federated credentials
Manage personal access tokens (PATs) — create, list, revoke, regenerate
Configure SMTP — get, update, test, delete email settings
Browse OAuth2 scopes — list available scopes for external apps and PATs
Onboard human user — invite, assign to groups
Onboard robot account — create account, assign to groups

管理身份用户 —— 列出、创建、邀请、更新、删除用户
管理群组 —— 增删改查（CRUD）以及添加/移除成员
管理机器人账号 —— 创建、更新、删除无人值守机器人身份
管理外部应用 —— OAuth2客户端、密钥、联合凭证
管理个人访问令牌（PAT） —— 创建、列出、撤销、重新生成
配置SMTP —— 获取、更新、测试、删除邮件设置
浏览OAuth2权限范围 —— 列出外部应用和PAT可用的权限范围
导入人工用户 —— 邀请用户并分配至群组
导入机器人账号 —— 创建账号并分配至群组

Authz

授权管理

Manage custom roles — CRUD on Authorization service role definitions (scope shapes:
```
Organization
```
,
```
TenantGlobal
```
,
```
Tenant
```
,
```
Project
```
)
Manage role assignments — assign roles to users/groups/robot accounts at
```
Organization
```
,
```
Tenant
```
,
```
TenantGlobal
```
,
```
Project
```
,
```
Folder
```
, or
```
App
```
scope
List permission definitions — read-only catalog of permissions across services
Check effective access — compute what a principal can actually do at a given scope (Policy Decision Point)
Grant permission(s) to a principal — ad-hoc "grant me X" / "give <user> Y, Z" requests resolved via the scope/service intersection flow

管理自定义角色 —— 对授权服务角色定义执行增删改查（范围类型：
```
Organization
```
、
```
TenantGlobal
```
、
```
Tenant
```
、
```
Project
```
）
管理角色分配 —— 在
```
Organization
```
、
```
Tenant
```
、
```
TenantGlobal
```
、
```
Project
```
、
```
Folder
```
或
```
App
```
层级，为用户/群组/机器人账号分配角色
列出权限定义 —— 跨服务的只读权限目录
查询有效权限 —— 计算主体在指定层级实际可执行的操作（策略决策点PDP）
为主体授予权限 —— 通过范围/服务交叉流程，处理临时的“授予我权限X”或“为<用户>分配权限Y、Z”请求

OMS

OMS管理

Inspect / update the current organization —
```
uip admin organizations
```
(read + update only; no CLI create/delete)
Manage tenant lifecycle — create, enable, disable, delete tenants in the caller's org
Provision org-level or tenant-level services —
```
services list
```
,
```
list-available
```
,
```
add
```
,
```
enable
```
,
```
disable
```
,
```
remove
```
Poll async OMS operations —
```
tenants
```
mutations return
```
operationId
```
; poll via
```
organizations operation get <id>
```
(the canonical poll endpoint)
List available regions — discover provisioning regions before
```
tenants create
```

查看/更新当前组织 —— 使用
```
uip admin organizations
```
（仅支持读取和更新；CLI不支持创建/删除）
管理租户生命周期 —— 在调用者所属组织中创建、启用、禁用、删除租户
配置组织级或租户级服务 —— 使用
```
services list
```
、
```
list-available
```
、
```
add
```
、
```
enable
```
、
```
disable
```
、
```
remove
```
命令
轮询异步OMS操作 ——
```
tenants
```
变更操作返回
```
operationId
```
；通过
```
organizations operation get <id>
```
进行轮询（标准轮询端点）
列出可用区域 —— 在创建租户前，先查询可配置的区域

IP Restriction

IP限制

Manage IP allowlisting — add / update / delete CIDR entries that gate inbound access
Toggle IP-restriction enforcement — turn the org-wide allowlist switch on or off (with lockout safety)
Manage bypass rules — URL-pattern exceptions to IP allowlisting
Look up the caller's public IP — answer "what's my IP?" / "what public IP does the platform see for me?" directly with
```
ip-restriction my-ip
```
; also the safety pre-flight before enabling enforcement

管理IP白名单 —— 添加/更新/删除控制入站访问的CIDR条目
切换IP限制启用状态 —— 开启或关闭组织级白名单开关（含锁定安全机制）
管理绕过规则 —— IP白名单的URL模式例外规则
查询调用者的公网IP —— 通过
```
ip-restriction my-ip
```
直接回答“我的IP是什么？”或“平台识别到我的公网IP是多少？”；同时也是启用IP限制前的安全预检步骤

Audit

审计功能

Activate on both explicit audit requests and natural-language investigation intent — users rarely say "audit events" by name.

Surface boundary — this is
uip admin audit
, not
uip or audit-logs
. Every org/tenant audit ask below — including bare "audit logs", "audit history", "export the audit trail", "login history", "who did what" — is served by
uip admin audit <scope>
. Do not fall back to
uip or audit-logs
(Orchestrator-operational audit, a different schema; that's the
uipath-platform
skill), even when the user's wording is generic. When the user asks what audit events / sources are available or visible, answer by running
uip admin audit <scope> sources
— discover live, never describe from memory or the docs.

Explicit —
```
uip admin audit
```
commands; list sources / targets / types; query, filter, paginate, or export events; CSV or per-day-JSON dump of audit history for a window.
Query audit events — list event sources, filter events by source / target / type / user / status / time window at org or tenant scope
Export audit events — chunked download from the long-term store (one call per UTC day, atomic abort on any chunk failure) as a folder of day-wise JSON files (default) or a single merged CSV via
```
--file-format csv
```
Membership / license phrasings — "who joined / left the organization", "who was made an admin", "license changes", "cross-tenant audit"
Sign-in / authentication phrasings — "failed/successful logins", "login history for user X", "who's been signing in"
Tenant-activity phrasings — "what happened on tenant X", "asset/queue/folder edits", "queue items processed", "job failures", "Action Center task changes", "Apps / AgentHub / Document Understanding / Integration Service / Test Manager activity"
Cross-scope phrasings — "everything everywhere" (run the flow once per scope and present combined)
Investigation intent (full-sentence form) — "Who deleted the X folder last Tuesday?", "Show me failed logins for user Y this month.", "What changed on tenant Z between Jan 1 and Feb 1?", "Give me the audit log for the last 30 days.", "Was the API key rotated by someone in our org?", "Export everything for compliance for Q4."

Scope routing (which phrasing →
org
vs
tenant
, and why) lives in audit-workflow-guide.md → Audit scope disambiguation. Critical Rule 23 governs the stop-and-ask requirement when scope is ambiguous.

针对明确的审计请求和自然语言表述的调查需求均可触发——用户很少直接提及“审计事件”。

边界说明 —— 本技能使用
uip admin audit
，而非
uip or audit-logs
。以下所有组织/租户相关的审计需求——包括“审计日志”“审计历史”“导出审计追踪”“登录历史”“操作溯源”——均通过
uip admin audit <scope>
处理。即使用户表述宽泛，也不要使用
uip or audit-logs
（属于Orchestrator操作审计，架构不同，归
uipath-platform
技能负责）。当用户询问有哪些可用的审计事件/源时，需执行
uip admin audit <scope> sources
命令获取实时信息，切勿凭记忆或文档描述作答。

明确命令 —— 使用
```
uip admin audit
```
命令；列出事件源/目标/类型；查询、筛选、分页或导出事件；按时间窗口导出审计历史为按天划分的JSON文件夹（默认）或单CSV文件。
查询审计事件 —— 在组织或租户层级，按事件源/目标/类型/用户/状态/时间窗口筛选事件
导出审计事件 —— 从长期存储中分批下载（按UTC日期分批调用，任意批次失败则终止），默认导出为按天划分的JSON文件夹，可通过
```
--file-format csv
```
参数导出为合并后的单CSV文件
成员/许可相关表述 —— “谁加入/离开组织”“谁被设为管理员”“许可变更”“跨租户审计”
登录/认证相关表述 —— “登录失败/成功记录”“用户X的登录历史”“谁登录过系统”
租户活动相关表述 —— “租户X上发生了什么”“资产/队列/文件夹编辑记录”“队列项处理情况”“任务失败记录”“Action Center任务变更”“Apps / AgentHub / Document Understanding / Integration Service / Test Manager活动记录”
跨层级表述 —— “所有操作记录”（在每个层级各执行一次流程，合并结果展示）
调查需求（完整语句形式） —— “上周二谁删除了X文件夹？”“展示本月用户Y的登录失败记录。”“租户Z在1月1日至2月1日之间有哪些变更？”“给我最近30天的审计日志。”“我们组织里有人轮换过API密钥吗？”“导出第四季度所有合规记录。”

层级路由（哪些表述对应
org
或
tenant
层级及原因）详见audit-workflow-guide.md → 审计层级消歧义。规则23规定，当层级不明确时，必须先询问用户确认。

Troubleshoot

故障排查

Activate on access/auth/identity troubleshooting — users report symptoms, not audit verbs.

Diagnose access denied — "user can't access X", "403 on API", "new hire has no permissions" → resolve principal, check-access, inspect role assignments. Playbook: identity-troubleshoot-guide.md → Playbook 1
Investigate login failures — "failed login attempts", "account compromised?", "suspicious sign-ins" → org-scoped audit login-history investigation. Playbook: identity-troubleshoot-guide.md → Playbook 2
Diagnose role misconfiguration — "custom role doesn't work", "user has role but can't do X" → inspect role actions, verify scope alignment. Playbook: identity-troubleshoot-guide.md → Playbook 3
Diagnose IP restriction lockout — "can't access platform from new office", "all users blocked" → my-ip + ip-ranges list + enforcement get. Playbook: identity-troubleshoot-guide.md → Playbook 4
Diagnose PAT / external app failures — "API returns 401", "PAT stopped working", "external app can't authenticate" → check expiry, scopes, audit for revocation. Playbook: identity-troubleshoot-guide.md → Playbook 5
Diagnose SMTP email delivery failures — "invitations not sending", "SMTP broken" → smtp get + smtp test
Investigate stuck tenant operations — "tenant create not completing", "operation stuck" → poll operation status
Identify service provisioning no-ops — "service still enabled after remove" → platform-pinned services
Triage robot account authentication issues — "robot not authenticating" → identity vs credential model confusion

Structured diagnose capability index with failure-mode lookup and diagnostic priority ladder: diagnose/CAPABILITY.md. Quick investigation playbooks: identity-troubleshoot-guide.md.

针对访问/认证/身份相关故障排查触发——用户通常描述症状，而非使用审计术语。

诊断访问拒绝问题 —— “用户无法访问X”“API返回403”“新员工无权限” → 确认主体身份、查询有效权限、检查角色分配。操作手册：identity-troubleshoot-guide.md → 手册1
调查登录失败 —— “登录尝试失败”“账号是否被盗？”“异常登录行为” → 在组织层级审计登录历史。操作手册：identity-troubleshoot-guide.md → 手册2
诊断角色配置错误 —— “自定义角色无法生效”“用户拥有角色但无法执行操作X” → 检查角色权限、验证层级匹配。操作手册：identity-troubleshoot-guide.md → 手册3
诊断IP限制锁定问题 —— “无法从新办公室访问平台”“所有用户被阻断” → 查询自身IP + IP范围列表 + 限制启用状态。操作手册：identity-troubleshoot-guide.md → 手册4
诊断PAT/外部应用认证失败 —— “API返回401”“PAT失效”“外部应用无法认证” → 检查有效期、权限范围、审计撤销记录。操作手册：identity-troubleshoot-guide.md → 手册5
诊断SMTP邮件发送失败 —— “邀请邮件未发送”“SMTP故障” → 获取SMTP配置 + 测试SMTP连接
调查停滞的租户操作 —— “租户创建未完成”“操作停滞” → 轮询操作状态
识别服务配置无响应问题 —— “移除服务后仍显示启用” → 平台固定服务相关问题
排查机器人账号认证问题 —— “机器人无法认证” → 区分身份模型与凭证模型的混淆

结构化诊断能力索引，含故障模式查询和诊断优先级顺序：diagnose/CAPABILITY.md。快速调查手册：identity-troubleshoot-guide.md。

Critical Rules

核心规则

Each rule is the agent contract. Per-area detail is in the linked reference files.

每条规则均为Agent执行约定。各领域详细说明见链接的参考文件。

Universal

通用规则

Route Orchestrator-specific role/permission requests to
uip or roles
(
```
uipath-platform
```
skill).
```
uip admin authorization
```
does NOT own Orchestrator's role catalog. Conversely, all organization/tenant audit is owned HERE and served by
uip admin audit <scope>
(
sources
/
events
/
export
) — NEVER use
uip or audit-logs
for audit events, audit history, audit export, login history, compliance dumps, or "who did what/where" requests.
```
uip or audit-logs
```
is a different surface (Orchestrator-operational audit —
```
Component,User,Action,Operation,Time
```
columns,
```
--export
```
returns a CSV; the
```
uipath-platform
```
skill). If you reach for
```
uip or audit-logs
```
on any org/tenant audit ask, stop and switch to
```
uip admin audit
```
.
Verify login first.
```
uip login status --output json
```
. If not logged in, stop and ask the user to run
```
uip login
```
— it opens an interactive browser flow, so never launch it yourself in an automated or non-interactive session (sessions authenticated via env vars are already logged in). Org id is resolved from the active session.
Use
--output json
on every command. Parse programmatically; present conversationally.
Stop on error. Show the error verbatim. Never retry auth failures — ask the user to
```
uip login
```
.
Resolve every named principal before high-risk ops. Any command that touches a named user / group / robot account / external app —
```
roles assignments create/delete
```
,
```
users delete
```
,
```
groups delete
```
,
```
groups members add/revoke
```
,
```
robot-accounts delete
```
,
```
external-apps delete
```
,
```
external-apps generate-secret
```
— MUST first search the directory and echo
```
Principal: <displayName> (<userName>) — <id>
```
back before the mutation runs. Zero matches → stop and ask; never fall back to the current login user. Multiple matches → numbered list, wait for a digit. Procedure: role-assignment-management.md → Resolving Principal IDs.

将Orchestrator特定的角色/权限请求路由至
uip or roles
（
```
uipath-platform
```
技能）。
```
uip admin authorization
```
不负责Orchestrator的角色目录。反之，所有组织/租户审计均由本技能负责，通过
uip admin audit <scope>
（
sources
/
events
/
export
命令）处理——绝不要使用
uip or audit-logs
处理审计事件、审计历史、审计导出、登录历史、合规导出或“操作溯源”请求。
```
uip or audit-logs
```
是独立模块（Orchestrator操作审计——包含
```
Component,User,Action,Operation,Time
```
列，
```
--export
```
返回CSV文件；归
```
uipath-platform
```
技能负责）。若你在处理组织/租户审计请求时想调用
```
uip or audit-logs
```
，请立即切换为
```
uip admin audit
```
。
先验证登录状态。执行
```
uip login status --output json
```
。若未登录，暂停操作并提示用户执行
```
uip login
```
——该命令会打开交互式浏览器流程，因此切勿在自动化或非交互式会话中自动执行（通过环境变量认证的会话已处于登录状态）。组织ID从当前活跃会话中获取。
所有命令均使用
--output json
参数。以编程方式解析结果，以自然语言形式展示给用户。
遇到错误立即停止。原样展示错误信息。认证失败切勿重试——提示用户执行
```
uip login
```
。
执行高风险操作前，先确认所有指定主体。任何涉及指定用户/群组/机器人账号/外部应用的命令——
```
roles assignments create/delete
```
、
```
users delete
```
、
```
groups delete
```
、
```
groups members add/revoke
```
、
```
robot-accounts delete
```
、
```
external-apps delete
```
、
```
external-apps generate-secret
```
——必须先查询目录并返回
```
Principal: <displayName> (<userName>) — <id>
```
，再执行变更操作。无匹配结果→停止并询问；切勿默认使用当前登录用户。多个匹配结果→列出编号选项，等待用户选择数字。操作流程：role-assignment-management.md → 解析主体ID。

Identity

身份管理规则

Discover before creating.
```
list
```
before
```
create
```
to avoid duplicates (robot accounts, groups, external apps —
```
users invite
```
excepted).
Secrets shown only once on external-app create and
```
generate-secret
```
— warn the user to save immediately.
External apps require scopes at creation —
```
--app-scope
```
or
```
--user-scope
```
is required (e.g.,
```
--app-scope "OR.Folders"
```
).
Group membership uses user IDs. Resolve via
```
users list
```
per Rule 5, then
```
groups members add/revoke
```
.
Confirm before delete on users / groups / robot accounts / external apps — after resolving the named target per Rule 5.

创建前先查询。执行
```
list
```
命令后再执行
```
create
```
，避免重复创建（机器人账号、群组、外部应用——
```
users invite
```
除外）。
密钥仅显示一次——在创建外部应用和执行
```
generate-secret
```
命令时，提示用户立即保存密钥。
创建外部应用时必须指定权限范围——需传入
```
--app-scope
```
或
```
--user-scope
```
参数（例如
```
--app-scope "OR.Folders"
```
）。
群组成员管理使用用户ID。按照规则5通过
```
users list
```
解析用户ID，再执行
```
groups members add/revoke
```
命令。
删除用户/群组/机器人账号/外部应用前需确认——按照规则5解析目标主体后，再执行删除操作。

Authz

授权管理规则

Built-in roles are read-only. Only
```
Custom
```
roles can be created / updated / deleted. CLI also rejects authoring against service-managed and platform-level services. Service lists: role-management.md → Services That Manage Their Own Roles.
roles create
/
roles update
are PUT-style upserts. Body is assembled from inline flags +
```
--file ./actions.json
```
. Always
```
roles get
```
first before updating — omitted flags overwrite that field.
--service
infers scope (e.g.,
```
--service studio
```
→
```
Tenant
```
;
```
--service apps
```
→
```
Organization
```
). Combine with
```
--scope
```
only to override. Never guess a
serviceName
— the valid values and the command that re-derives them:
permission-catalog.md →
```
--service
```
serviceNames
.
Listing works for every service; authoring is what's blocked.
```
roles list --service <svc>
```
and
```
roles assignments list --service <svc>
```
accept every service. For effective access on a principal use
```
check-access
```
(PDP).

Scope vocab differs across verbs.

roles create --scope

Organization|TenantGlobal|Tenant|Project

roles assignments create --scope

: those +

Folder|App

roles assignments list --scope

: excludes

TenantGlobal

check-access --scope

: only

Tenant|Folder

roles assignments create/delete
MUST resolve the principal first per Rule 5 —
```
--identity-id
```
is a raw UUID the CLI does not name-check.
roles assignments create
MUST match the role's
ownerServiceName
to the scope-path service segment.
```
CentralizedAccess
```
→ no service segment (
```
/
```
or
```
/tenant/<tid>
```
); anything else → path must include
```
lowercase(ownerServiceName)
```
. Display-name mapping (e.g.,
```
Reinfer
```
→ "IXP") + full procedure: role-assignment-management.md → Validate Role's Owning Service.

内置角色为只读。仅
```
Custom
```
角色可创建/更新/删除。CLI也拒绝修改服务托管和平台级服务的角色。服务列表：role-management.md → 自行管理角色的服务。
roles create
/
roles update
为PUT风格的更新操作。请求体由命令行参数 +
```
--file ./actions.json
```
组合而成。更新前必须先执行
```
roles get
```
——未传入的参数会覆盖对应字段。
--service
参数推断层级（例如
```
--service studio
```
→
```
Tenant
```
；
```
--service apps
```
→
```
Organization
```
）。仅需在覆盖默认层级时搭配
```
--scope
```
参数。切勿猜测
serviceName
——有效值及重新获取命令：
permission-catalog.md →
```
--service
```
服务名称
。
所有服务均支持查询；仅部分服务支持编辑。
```
roles list --service <svc>
```
和
```
roles assignments list --service <svc>
```
支持所有服务。查询主体有效权限使用
```
check-access
```
（PDP）。

不同命令的层级术语不同。

roles create --scope

的可选值：

Organization|TenantGlobal|Tenant|Project

。

roles assignments create --scope

的可选值：上述值 +

Folder|App

。

roles assignments list --scope

的可选值：排除

TenantGlobal

。

check-access --scope

的可选值：仅

Tenant|Folder

。

roles assignments create/delete
必须先按照规则5解析主体——
```
--identity-id
```
为原始UUID，CLI不会自动验证名称。
roles assignments create
必须确保角色的
ownerServiceName
与层级路径的服务段匹配。
```
CentralizedAccess
```
→无服务段（
```
/
```
或
```
/tenant/<tid>
```
）；其他角色→路径必须包含小写的
```
ownerServiceName
```
。显示名称映射（例如
```
Reinfer
```
→"IXP"）+完整流程：role-assignment-management.md → 验证角色所属服务。

OMS

OMS管理规则

Async lifecycle: auto-poll, then hand off.
```
tenants create/update/delete/enable/disable
```
return
```
operationId
```
. Auto-poll
```
organizations operation get <OP_ID>
```
3× at 5 s; on terminal status stop and report; still in-progress after 3 polls → numbered menu, never indefinite loop. organizations create
and
organizations delete
are not exposed by the CLI — Portal / support flow only. Procedure: organization-management.md → Polling procedure.
tenants delete
is soft-only. No hard-delete flag; restoration is via support.
Tenant commands default to the login tenant. Always pass an explicit
```
<TENANT_ID>
```
for destructive ops (
```
tenants delete
```
,
```
tenants disable
```
,
```
tenants services remove
```
).
Resolve region before tenant create.
```
--region
```
is required on
```
tenants create
```
— run
```
organizations regions list
```
first. Tenant service catalog is region-aware.
services disable
/
remove
may no-op despite Success on certain services. Always re-list after mutating. Gap list: tenants-commands.md → Concepts.

异步生命周期：自动轮询，然后移交用户。
```
tenants create/update/delete/enable/disable
```
返回
```
operationId
```
。自动轮询
```
organizations operation get <OP_ID>
```
3次，每次间隔5秒；若返回终端状态则停止并报告；3次轮询后仍未完成→列出编号选项，切勿无限循环。organizations create
和
organizations delete
未在CLI中开放——仅支持通过门户/支持流程操作。操作流程：organization-management.md → 轮询流程。
tenants delete
仅为软删除。无硬删除参数；恢复需通过支持流程。
租户命令默认使用当前登录租户。执行破坏性操作（
```
tenants delete
```
、
```
tenants disable
```
、
```
tenants services remove
```
）时，必须传入明确的
```
<TENANT_ID>
```
。
创建租户前先解析区域。
```
tenants create
```
必须传入
```
--region
```
参数——先执行
```
organizations regions list
```
。租户服务目录与区域相关。
针对部分服务，
services disable
/
remove
可能返回成功但无实际效果。执行变更操作后需重新查询确认。问题列表：tenants-commands.md → 概念。

Audit

审计规则

Disambiguate
org
vs
tenant
scope before querying. If the prompt is vague AND no prior turn fixed the scope, stop and ask once (a single clarifying question — use AskUserQuestion when available) — never silently default to
```
tenant
```
or any single scope. If you genuinely cannot get an answer (non-interactive run) and must proceed, query both scopes and combine the results rather than guessing one — silently picking a single scope is the failure mode. Scope is a positional subgroup, NOT a flag: write
```
uip admin audit org sources
```
/
```
uip admin audit tenant events
```
— there is no
```
--scope
```
option (
```
audit sources --scope organization
```
is invalid). Routing table (user-phrasing → scope + why it lives where) and investigation playbooks: audit-workflow-guide.md → Audit scope disambiguation.
audit <scope> events
returns an object, not a bare array. Shape is
```
{auditEvents, next, previous}
```
. Do not index
```
Data[0]
```
; read
```
Data.auditEvents[]
```
. Cursor semantics are chronological:
```
next
```
= newer events,
```
previous
```
= older events. The default newest-backward walk follows
```
previous
```
.
--limit
paginates internally — never loop on
--from-date
/
--to-date
to "paginate". The server clamps
```
maxCount
```
to
```
[10, 200]
```
per request; when the user wants more than 200, the CLI fetches
```
ceil(N/200)
```
pages under the hood. Pass
```
--limit 500
```
(or larger, up to the 10000 maximum) — do NOT re-implement pagination in the agent.
```
--limit
```
must be in
```
[1, 10000]
```
; a bigger value is rejected up front with
```
Result: "ValidationError"
```
, so never pass an arbitrarily huge number to mean "everything" — for that, omit
```
--limit
```
or stay within the range.
Discover via
audit <scope> sources
first — never invent source / target / type GUIDs. The catalog response gives the GUIDs you pass to
```
events --source / --target / --type
```
. This is also the answer to "what audit events / sources can I see?" — run
audit <scope> sources
and report the live catalog; do not answer conceptually from memory or the reference docs.
Bound the time window, ISO 8601 in UTC. Don't call
```
audit <scope> events
```
without
```
--from-date
```
and
```
--to-date
```
on a noisy tenant. Accepted formats: date-only (
```
2026-04-01
```
) or with time (
```
2026-04-01T14:30:00Z
```
). --to-date
is inclusive of the exact instant — to capture a full final day, pass the start of the next day or
```
T23:59:59.999Z
```
. This next-day trick is for
```
events
```
only —
```
export
```
bounds are whole days (Rule 30). Resolve relative phrases ("yesterday", "last 7 days") against the actual current UTC date (e.g.
```
date -u
```
) — never guess dates — and echo the resolved window in your reply. 27b. "No matching event" is a complete answer — never name an actor the evidence does not support. An audit trail is evidence, so attributing an action to the wrong person is worse than returning nothing. If the targeted query comes back empty, say so plainly, state what you searched (scope, source/target/type, window), and offer a next step (widen the window, try the other scope, check the resource ever existed). Never promote an actor from an adjacent event — a different resource, a different event type, or a broad
```
--search
```
hit — into the answer, and do not keep loosening filters until something returns and then present that as the culprit. Only name an actor when the cited event matches both the resource and the verb asked about, quoting
```
createdOn
```
plus the identifying
```
eventDetails
```
field so the user can verify it. Detail: audit-workflow-guide.md → Step 5.
--tenant-id
is silently ignored on
org
-scoped audit commands. If you find yourself reaching for it on
```
audit org events
```
, switch to
```
audit tenant
```
instead.
On 401 from audit, do NOT retry. The token is missing the
```
Audit.Read
```
scope; tell the user to
```
uip logout && uip login
```
. 29b. On a 5xx from audit, DO retry — the envelope tells you so.
```
ErrorCode: server_error
```
/
```
Retry: RetryLater
```
(e.g.
```
HTTP 503: no healthy upstream
```
,
```
HTTP 504
```
) is a transient, not a bad request. Re-run the same query up to two more times with a few seconds of backoff before reporting failure — changing
```
--limit
```
or the window between attempts is not a fix and only obscures the cause. Retry immediately-and-once is usually not enough; wait between attempts. Never write or present an error envelope as if it were the result — if the user asked you to save the JSON, saving
```
{"Result":"Failure",...}
```
to that file is a failed retrieval, not a result. Report the failure explicitly instead.
audit <scope> export
writes into a base directory (
--output-path
): a uniquely-named folder of day-wise JSON files (default) or a single merged CSV.
```
--from-date
```
,
```
--to-date
```
, and
```
--output-path
```
are all required. Export dates are whole UTC days, inclusive on both ends (the server truncates times to the calendar day):
```
--from-date 2026-01-01 --to-date 2026-01-31
```
exports all of January; a single day is
```
--from-date X --to-date X
```
with the same date. Do not apply the
```
events
```
next-day trick here — a next-day
```
--to-date
```
exports an extra full day.
```
--output-path
```
is a base directory (created if missing) — pass a directory only, never a filename or extension; the CLI creates a uniquely-named
```
audit_<from>_<to>_<generated-at>
```
output inside it (folder for
```
json
```
,
```
.csv
```
for
```
csv
```
), so repeated exports of the same window never collide. Do not hand-craft the per-export name. --file-format <json|csv>
selects the shape:
```
json
```
(default) = a folder of
```
<YYYY-MM-DD>.json
```
files;
```
csv
```
= one merged CSV — pick
```
csv
```
for a flat spreadsheet/Excel-friendly dump,
```
json
```
for per-day files. If the user named a destination folder, pass it verbatim as
```
--output-path
```
— no confirmation needed; confirm first only when you had to pick a default (e.g.
```
./audit-exports
```
) yourself. Then report the generated
```
Path
```
(and
```
GeneratedAt
```
) from the result.

查询前先明确
org
或
tenant
层级。若提示模糊且之前未确定层级，必须询问用户一次（仅一个澄清问题——使用AskUserQuestion功能）——切勿默认使用
```
tenant
```
或其他单一层级。若确实无法获取答案（非交互式运行）且必须继续，则查询两个层级并合并结果，而非猜测单一层级——默认选择单一层级属于错误操作。层级为位置参数，而非标志位：正确写法为
```
uip admin audit org sources
```
/
```
uip admin audit tenant events
```
——无
```
--scope
```
参数（
```
audit sources --scope organization
```
无效）。路由表（用户表述→层级及原因）和调查手册：audit-workflow-guide.md → 审计层级消歧义。
audit <scope> events
返回对象，而非纯数组。结构为
```
{auditEvents, next, previous}
```
。切勿直接索引
```
Data[0]
```
；需读取
```
Data.auditEvents[]
```
。游标语义按时间顺序：
```
next
```
=更新的事件，
```
previous
```
=更早的事件。默认从最新事件开始遍历，需使用
```
previous
```
游标。
--limit
参数内部处理分页——切勿通过循环
--from-date
/
--to-date
实现“分页”。服务器限制每次请求的
```
maxCount
```
为
```
[10, 200]
```
；当用户需要超过200条记录时，CLI会自动获取
```
ceil(N/200)
```
页数据。传入
```
--limit 500
```
（或更大值，最大为10000）——切勿在Agent中重新实现分页逻辑。
```
--limit
```
必须在
```
[1, 10000]
```
范围内；超出范围会直接返回
```
Result: "ValidationError"
```
，因此切勿传入极大值表示“所有记录”——若需获取所有记录，可省略
```
--limit
```
或保持在范围内。
先通过
audit <scope> sources
查询——切勿自行编造事件源/目标/类型的GUID。目录响应会返回可传入
```
events --source / --target / --type
```
的GUID。这也是回答“我能查看哪些审计事件/源？”的方式——执行
audit <scope> sources
并报告实时目录；切勿凭记忆或参考文档进行概念性回答。
限制时间窗口，使用UTC时区的ISO 8601格式。对于活跃租户，调用
```
audit <scope> events
```
时必须传入
```
--from-date
```
和
```
--to-date
```
。支持格式：仅日期（
```
2026-04-01
```
）或带时间（
```
2026-04-01T14:30:00Z
```
）。--to-date
包含指定时刻——若需包含完整的最后一天，传入次日起始时间或
```
T23:59:59.999Z
```
。此技巧仅适用于
```
events
```
命令——
```
export
```
命令的时间范围为完整日期（规则30）。解析相对表述（“昨天”“最近7天”）需基于当前UTC日期（例如
```
date -u
```
）——切勿猜测日期——并在回复中明确解析后的时间窗口。 27b. “无匹配事件”为有效答案——切勿在无证据的情况下指定操作者。审计追踪为证据，错误归因比返回空结果更严重。若目标查询无结果，直接告知用户，说明搜索范围（层级、事件源/目标/类型、时间窗口），并提供下一步建议（扩大时间窗口、尝试另一层级、检查资源是否存在）。切勿从相邻事件（不同资源、不同事件类型或宽泛
```
--search
```
结果）中提取操作者作为答案，也不要不断放宽筛选条件直到返回结果并将其作为问题原因。仅当事件同时匹配查询的资源和操作时，才可指定操作者，并引用
```
createdOn
```
和识别性
```
eventDetails
```
字段供用户验证。详细说明：audit-workflow-guide.md → 步骤5。
org
层级审计命令会忽略
--tenant-id
参数。若你在执行
```
audit org events
```
时想传入该参数，请切换为
```
audit tenant
```
命令。
审计命令返回401时，切勿重试。令牌缺少
```
Audit.Read
```
权限；提示用户执行
```
uip logout && uip login
```
。 29b. 审计命令返回5xx时，需重试——响应信息会提示。
```
ErrorCode: server_error
```
/
```
Retry: RetryLater
```
（例如
```
HTTP 503: no healthy upstream
```
、
```
HTTP 504
```
）为临时错误，而非请求错误。使用相同查询最多重试两次，每次间隔几秒；若仍失败则报告错误——重试时修改
```
--limit
```
或时间窗口无法解决问题，只会掩盖原因。仅立即重试一次通常不足；需等待间隔后重试。切勿将错误响应作为结果展示——若用户要求保存JSON，将
```
{"Result":"Failure",...}
```
保存至文件属于获取失败，而非有效结果。需明确报告失败情况。
audit <scope> export
将内容写入基础目录（
--output-path
）：默认生成按天划分的JSON文件的唯一命名文件夹，或合并后的单CSV文件。
```
--from-date
```
、
```
--to-date
```
和
```
--output-path
```
均为必填参数。导出日期为完整UTC日期，两端均包含（服务器会截断时间至日历日）：
```
--from-date 2026-01-01 --to-date 2026-01-31
```
导出整个1月的数据；单天导出需传入
```
--from-date X --to-date X
```
。切勿对
```
export
```
命令使用
```
events
```
的次日技巧——传入次日
```
--to-date
```
会多导出一整天的数据。
```
--output-path
```
为基础目录（不存在则自动创建）——仅传入目录，切勿传入文件名或扩展名；CLI会在该目录下创建唯一命名的
```
audit_<from>_<to>_<generated-at>
```
输出（
```
json
```
格式为文件夹，
```
csv
```
格式为
```
.csv
```
文件），因此同一时间窗口的重复导出不会冲突。切勿手动指定导出文件名。**
```
--file-format <json|csv>
```
**选择输出格式：
```
json
```
（默认）=按天划分的
```
<YYYY-MM-DD>.json
```
文件；
```
csv
```
=合并后的单CSV文件——如需扁平表格/Excel友好格式选择
```
csv
```
，如需按天文件选择
```
json
```
。若用户指定了目标目录，直接传入
```
--output-path
```
无需确认；仅当你自行选择默认目录（例如
```
./audit-exports
```
）时需先确认。然后报告结果中的
```
Path
```
（和
```
GeneratedAt
```
）。

IP Restriction

IP限制规则

enforcement enable
is lockout-sensitive — prompt + impact statement required. Run
```
ip-restriction my-ip
```
and verify the caller's IP is covered by an entry in
```
ip-ranges list
```
. Then prompt the user with the impact before flipping: "After enabling IP restriction, any caller (Portal, CLI, robot, external app) whose source IP is not in
ip-ranges list
will be blocked from this org. Misconfiguration locks you out and requires platform-side recovery. Proceed?"
```
--confirm
```
is required;
```
ip-ranges delete
```
while enforcement is on also requires
```
--confirm
```
. Procedure: enforcement-management.md.
Recovery from IP lockout requires platform-side action. No CLI bypass — either access from an in-allowlist IP and
```
enforcement disable
```
, or use the Portal recovery flow.
"APMS" is internal — never expose to the user. "APMS" (Access Policy Management Service) is the platform's internal name for IP Restriction. Use "IP Restriction" in every user-facing surface.

enforcement enable
涉及锁定风险——需提示+影响说明。执行
```
ip-restriction my-ip
```
并验证调用者IP在
```
ip-ranges list
```
的条目内。然后向用户提示影响，再执行启用操作：“启用IP限制后，任何源IP不在
ip-ranges list
中的调用者（门户、CLI、机器人、外部应用）将无法访问本组织。配置错误会导致锁定，需平台端恢复。是否继续？” 必须传入
```
--confirm
```
参数；在启用限制状态下执行
```
ip-ranges delete
```
也需传入
```
--confirm
```
。操作流程：enforcement-management.md。
IP锁定恢复需平台端操作。无CLI绕过方式——要么从白名单IP访问并执行
```
enforcement disable
```
，要么使用门户恢复流程。
“APMS”为内部术语——切勿向用户暴露。“APMS”（Access Policy Management Service）是IP限制的平台内部名称。用户交互中统一使用“IP限制”。

What NOT to Do

禁止操作

Never delete built-in groups.
```
type: "BuiltIn"
```
groups cannot be deleted. Only custom groups.
Never pass IDs as flags. Resource IDs and names are positional arguments:
```
groups members add <GROUP_ID> --user-ids ...
```
, NOT
```
--group-id <GROUP_ID>
```
. Same for all
```
get
```
,
```
update
```
,
```
delete
```
,
```
create
```
subcommands.
Do NOT assume audit
events
returns a bare array. It's
```
{auditEvents, next, previous}
```
.
Do NOT loop on
--from-date
/
--to-date
to "paginate". Bump
```
--limit
```
and the CLI handles cursor pagination internally.
Do NOT silently default audit scope to
```
tenant
```
or
```
org
```
when the prompt is ambiguous. Ask once, then proceed.
Do NOT invent audit source/target/type GUIDs. Always discover via
```
sources
```
first.
Do NOT call audit
events
with no time bound on a noisy tenant — default to a bounded window.
Do NOT pass
--tenant-id
to
org
-scoped audit commands — it's silently ignored.
Do NOT retry on 401 auth errors. The token is missing the required scope (
```
Audit.Read
```
for audit). Tell the user to
```
uip logout && uip login
```
. 9a. Do NOT save or report an audit error envelope as data. A
```
{"Result":"Failure"|"ValidationError", ...}
```
payload is a failed call — retry a 5xx (Rule 29b), fix a
```
ValidationError
```
, and never leave it in a file the user asked you to fill with results. 9b. Do NOT name a culprit an audit query did not return. If the targeted search is empty, report "no matching event found" — never borrow an actor from an adjacent or broader-search event (Rule 27b).
Do NOT call
roles update
with only the flag you want to change. Re-fetch first; the upsert body overwrites omitted fields (Rule 12).
Do NOT present authz results without provenance — role name,
```
scopeType
```
,
```
ownerServiceName
```
, tenant-binding (names not UUIDs). Detail: authorization-commands.md → Provenance contract.
Do NOT conflate provisioned services with the available catalog.
```
services list
```
returns provisioned with status;
```
services list-available
```
is the catalog. Present them as separate sections.
Do NOT run an OMS mutation without naming the target. Echo org name / tenant name + UUID / service type + region before running.
Do NOT pass the next day as
--to-date
on audit
export
to "include the final day" — export bounds are already whole-day inclusive (Rule 30); the next-day trick is for
```
events
```
only and would export an extra day.

切勿删除内置群组。
```
type: "BuiltIn"
```
的群组无法删除。仅可删除自定义群组。
切勿将ID作为标志位参数传入。资源ID和名称为位置参数：例如
```
groups members add <GROUP_ID> --user-ids ...
```
，而非
```
--group-id <GROUP_ID>
```
。所有
```
get
```
、
```
update
```
、
```
delete
```
、
```
create
```
子命令均遵循此规则。
切勿假设
audit events
返回纯数组。返回结构为
```
{auditEvents, next, previous}
```
。
切勿通过循环
--from-date
/
--to-date
实现“分页”。增大
```
--limit
```
参数，CLI会自动处理游标分页。
当提示模糊时，切勿默认审计层级为
```
tenant
```
或
```
org
```
。先询问用户，再继续操作。
切勿自行编造审计事件源/目标/类型的GUID。必须先通过
```
sources
```
查询获取。
对于活跃租户，切勿无时间限制调用
audit events
——默认使用有限时间窗口。
切勿向
org
层级审计命令传入
--tenant-id
参数——该参数会被忽略。
认证错误返回401时，切勿重试。令牌缺少所需权限（审计需
```
Audit.Read
```
）。提示用户执行
```
uip logout && uip login
```
。 9a. 切勿将审计错误响应保存或报告为数据。
```
{"Result":"Failure"|"ValidationError", ...}
```
为调用失败——5xx错误需重试（规则29b），
```
ValidationError
```
需修正请求，切勿将其保存至用户要求填充结果的文件中。 9b. 切勿在审计查询无结果的情况下指定操作者。若目标搜索无结果，报告“未找到匹配事件”——切勿从相邻或宽泛搜索结果中提取操作者（规则27b）。
切勿仅传入需修改的参数执行
roles update
。先重新获取角色信息；更新操作会覆盖未传入的字段（规则12）。
切勿展示无来源信息的授权结果——需包含角色名称、
```
scopeType
```
、
```
ownerServiceName
```
、租户绑定（名称而非UUID）。详细说明：authorization-commands.md → 来源约定。
切勿混淆已配置服务与可用目录。
```
services list
```
返回已配置服务及状态；
```
services list-available
```
返回可用目录。需分开展示。
执行OMS变更操作前，必须明确目标。执行前需回显组织名称/租户名称+UUID/服务类型/区域。
切勿对
audit export
传入次日作为
--to-date
以“包含最后一天”——导出范围已为完整日期（规则30）；次日技巧仅适用于
```
events
```
命令，会导致多导出一天数据。

Quick Start

快速入门

One row per common goal. Per-area workflows are in the reference files.

Goal	Entry command(s)
Invite a user → assign to group	user-management.md + group-management.md
Create a custom role	`uip admin authorization roles create --scope <Organization\|TenantGlobal\|Tenant\|Project> --name "<NAME>" --file ./actions.json --output json` (actions.json = `["STUDIO.X.Y", ...]` )
Grant permission(s) to a principal ("grant me X", "give alice Y, Z")	grant-permissions.md — intersection-and-menu flow
Assign a role to a principal	(1) Resolve principal per Rule 5. (2) `roles get <ROLE_ID>` → echo `ownerServiceName` + verify scope-path service segment matches (Rule 17). (3) `roles assignments create --role-id <ROLE_ID> --identity-id <ID> --identity-type <User\|Group\|Robot\|ExternalApplication> --output json`
See what a principal can do	`uip admin authorization check-access <USER_GUID_OR_EMAIL> --scope <Tenant\|Folder> --output json` (Rule 15)
Create a tenant	tenant-management.md — region + default-services resolution, file-body shape, operation polling (Rule 18)
Add a tenant service	`tenants services list-available --region <R>` → `tenants services add --tenant-id <TID> --service <SVC>` (verify post-state per Rule 22)
Look up my public IP ("what's my IP?", "what public IP does the platform see for me?")	`ip-restriction my-ip --output json` → return `Data.ipAddress` . Standalone — no enforcement context required
Enable IP allowlist enforcement	`ip-restriction my-ip` → verify covered by `ip-ranges list` → `ip-restriction enforcement enable --confirm` (Rule 31)
Query audit events / export	audit-workflow-guide.md — scope disambiguation + 4 investigation playbooks (who-did-X, login history, date-range dump, overview)

每行对应一个常见目标。各领域工作流见参考文件。

目标	入口命令
邀请用户并分配至群组	user-management.md + group-management.md
创建自定义角色	`uip admin authorization roles create --scope <Organization\|TenantGlobal\|Tenant\|Project> --name "<名称>" --file ./actions.json --output json` （actions.json = `["STUDIO.X.Y", ...]` ）
为主体授予权限（“授予我权限X”“为Alice分配权限Y、Z”）	grant-permissions.md —— 交叉流程及菜单选择
为主体分配角色	(1) 按照规则5解析主体。(2) `roles get <ROLE_ID>` → 回显 `ownerServiceName` 并验证层级路径服务段匹配（规则17）。(3) `roles assignments create --role-id <ROLE_ID> --identity-id <ID> --identity-type <User\|Group\|Robot\|ExternalApplication> --output json`
查看主体可执行的操作	`uip admin authorization check-access <用户GUID或邮箱> --scope <Tenant\|Folder> --output json` （规则15）
创建租户	tenant-management.md —— 区域+默认服务解析、文件结构、操作轮询（规则18）
添加租户服务	`tenants services list-available --region <区域>` → `tenants services add --tenant-id <租户ID> --service <服务>` （按照规则22验证后续状态）
查询我的公网IP（“我的IP是什么？”“平台识别到我的公网IP是多少？”）	`ip-restriction my-ip --output json` → 返回 `Data.ipAddress` 。独立操作——无需限制上下文
启用IP白名单限制	`ip-restriction my-ip` → 验证IP在 `ip-ranges list` 中 → `ip-restriction enforcement enable --confirm` （规则31）
查询审计事件/导出	audit-workflow-guide.md —— 层级消歧义+4个调查手册（操作溯源、登录历史、日期范围导出、概览）

Key Concepts

核心概念

Organization hierarchy

组织层级

Organization (org)
  └── Partition (= org in most cases)
        ├── Users           ← human identities
        ├── Groups          ← role containers (BuiltIn + Custom)
        ├── Robot Accounts  ← unattended automation identities
        └── External Apps   ← OAuth2 clients (Client ID + Secret)

Organization (组织)
  └── Partition（多数情况下等同于组织）
        ├── Users           ← 人工身份
        ├── Groups          ← 角色容器（内置+自定义）
        ├── Robot Accounts  ← 无人值守自动化身份
        └── External Apps   ← OAuth2客户端（客户端ID+密钥）

Robot accounts vs external apps

机器人账号 vs 外部应用

Concept	Purpose	Managed by
Robot account	Identity — who the robot is	Identity Server ( `uip admin` )
Robot credentials	Per-robot Client ID + Secret for machine auth	Orchestrator (machine connection)
External app	OAuth2 client for API integrations, CI/CD	Identity Server ( `uip admin` )

Robot credentials are provisioned automatically by Orchestrator on machine connect — not by creating external apps.

概念	用途	管理方
机器人账号	身份标识——机器人的身份	Identity Server（ `uip admin` ）
机器人凭证	每台机器人的客户端ID+密钥，用于机器认证	Orchestrator（机器连接）
外部应用	用于API集成、CI/CD的OAuth2客户端	Identity Server（ `uip admin` ）

机器人凭证由Orchestrator在机器连接时自动配置——无需创建外部应用。

Output Etiquette

输出规范

What to surface after each verb. Per-area detail in the reference files; this is the contract.

Area	Always surface
Identity mutations	Result + new resource id; for external-app create / `generate-secret` , highlight the secret + warn to save; offer a next step (assign to group, generate another secret, etc.).
Authz reads + mutations	Provenance: role name, `scopeType` , `ownerServiceName` (read directly from response — translate to display name per Rule 17, e.g., `Reinfer` →"IXP"), tenant binding (resolve UUID → name). `check-access` : label each row as `direct` or `inherited from <Group name>` by inspecting the nested `roleAssignments[].securityPrincipalType` . Full contract: authorization-commands.md → Provenance contract.
OMS reads	Separate provisioned (with status) from available catalog (no status). Lead with `Organization: <ORG_NAME>` (and tenant name + UUID + lifecycle status for tenant reads).
OMS mutations	Echo the resolved target before running (Anti-pattern 13). Async: auto-poll 3× at 5 s, then numbered menu (Rule 18). Sync services: re-list to verify post-state (Rule 22).
Audit queries	Disambiguate `org` vs `tenant` first (Rule 23). Discover via `sources` (Rule 26). Bound the window (Rule 27). Operation summary (count, scope, time window, filters, cursor state). Wait for the user's next-step choice; do not chain mutations. Investigation playbooks: audit-workflow-guide.md.
IP Restriction mutations	Before `enforcement enable` : state the impact, require explicit user confirmation (Rule 31). After: confirm caller's IP is still covered (re-run `my-ip` + `ip-ranges list` ). Never use the internal name "APMS" in user-facing output.

For per-area full checklists, follow the table's inline links: Identity → identity-commands.md; Authz → authorization-commands.md; Audit → audit-workflow-guide.md.

每个操作后需展示的内容。各领域详细说明见参考文件，此为执行约定。

领域	必须展示的内容
身份管理变更操作	结果+新资源ID；创建外部应用或执行 `generate-secret` 时，高亮显示密钥并提示用户保存；提供下一步建议（分配至群组、重新生成密钥等）。
授权管理查询+变更操作	来源信息：角色名称、 `scopeType` 、 `ownerServiceName` （直接从响应读取——按照规则17转换为显示名称，例如 `Reinfer` →"IXP"）、租户绑定（解析UUID→名称）。`check-access` ：通过嵌套的 `roleAssignments[].securityPrincipalType` ，将每行标记为 `direct` 或 `inherited from <群组名称>` 。完整约定：authorization-commands.md → 来源约定。
OMS查询操作	区分已配置服务（含状态）与可用目录（无状态）。开头展示 `Organization: <组织名称>` （租户查询需展示租户名称+UUID+生命周期状态）。
OMS变更操作	执行前回显解析后的目标（反模式13）。异步操作：自动轮询3次，每次间隔5秒，然后提供编号菜单（规则18）。同步服务：重新查询验证后续状态（规则22）。
审计查询操作	先明确 `org` 或 `tenant` 层级（规则23）。通过 `sources` 查询（规则26）。限制时间窗口（规则27）。操作摘要（数量、层级、时间窗口、筛选条件、游标状态）。等待用户下一步选择；切勿链式执行变更操作。调查手册：audit-workflow-guide.md。
IP限制变更操作	执行 `enforcement enable` 前：说明影响，要求用户明确确认（规则31）。执行后：验证调用者IP仍在白名单中（重新执行 `my-ip` + `ip-ranges list` ）。用户交互中切勿使用内部名称“APMS”。

各领域完整检查清单，见表格内联链接：身份管理→identity-commands.md；授权管理→authorization-commands.md；审计→audit-workflow-guide.md。

Task Navigation

任务导航

I need to...	Read first
Identity CLI reference	references/identity-commands.md
Manage users (list / create / invite / update / delete)	references/user-management.md
Manage groups (CRUD + membership)	references/group-management.md
Manage robot accounts	references/robot-account-management.md
Manage external apps (OAuth2 + secrets + federated credentials)	references/external-app-management.md
Manage personal access tokens (PATs)	references/pat-management.md
Configure SMTP email settings	references/smtp-management.md
Authorization CLI reference	references/authorization/authorization-commands.md
Manage custom roles	references/authorization/role-management.md
Grant permission(s) to a principal — scope/service intersection flow	references/authorization/grant-permissions.md
Manage role assignments (incl. role-service vs scope-path validation, Rule 17)	references/authorization/role-assignment-management.md
List permission definitions	references/authorization/permission-catalog.md
Check effective access for a principal	references/authorization/check-access.md
Organizations CLI reference	references/organizations-commands.md
Tenants CLI reference	references/tenants-commands.md
Manage the organization (read + update, polling, regions, org services read-only)	references/organization-management.md
Manage tenants (CRUD, enable/disable, tenant services)	references/tenant-management.md
IP-restriction CLI reference	references/ip-restriction/ip-restriction-commands.md
Manage IP allowlist entries	references/ip-restriction/ip-range-management.md
Toggle enforcement (+ `my-ip` safety check)	references/ip-restriction/enforcement-management.md
Manage bypass rules	references/ip-restriction/bypass-rule-management.md
Audit CLI reference	references/audit-commands.md
Audit investigation workflows (scope disambiguation, who-did-X, login history, date-range dump, overview)	references/audit-workflow-guide.md
Paginate audit events beyond 200	references/audit-commands.md + Rule 25
Troubleshoot access denied, login failures, role misconfig, IP lockout, PAT/app auth	references/identity-troubleshoot-guide.md
Diagnose capability index (structured)	references/diagnose/CAPABILITY.md
Failure mode lookup (12 named patterns)	references/diagnose/references/failure-modes.md
Diagnostic priority ladder (sequential triage)	references/diagnose/references/troubleshooting-guide.md

我需要...	先阅读
身份管理CLI参考	references/identity-commands.md
管理用户（列出/创建/邀请/更新/删除）	references/user-management.md
管理群组（增删改查+成员）	references/group-management.md
管理机器人账号	references/robot-account-management.md
管理外部应用（OAuth2+密钥+联合凭证）	references/external-app-management.md
管理个人访问令牌（PAT）	references/pat-management.md
配置SMTP邮件设置	references/smtp-management.md
授权管理CLI参考	references/authorization/authorization-commands.md
管理自定义角色	references/authorization/role-management.md
为主体授予权限——范围/服务交叉流程	references/authorization/grant-permissions.md
管理角色分配（含角色服务与层级路径验证，规则17）	references/authorization/role-assignment-management.md
列出权限定义	references/authorization/permission-catalog.md
查询主体有效权限	references/authorization/check-access.md
组织管理CLI参考	references/organizations-commands.md
租户管理CLI参考	references/tenants-commands.md
管理组织（读取+更新、轮询、区域、组织服务只读）	references/organization-management.md
管理租户（增删改查、启用/禁用、租户服务）	references/tenant-management.md
IP限制CLI参考	references/ip-restriction/ip-restriction-commands.md
管理IP白名单条目	references/ip-restriction/ip-range-management.md
切换限制启用状态（含 `my-ip` 安全检查）	references/ip-restriction/enforcement-management.md
管理绕过规则	references/ip-restriction/bypass-rule-management.md
审计CLI参考	references/audit-commands.md
审计调查工作流（层级消歧义、操作溯源、登录历史、日期范围导出、概览）	references/audit-workflow-guide.md
分页查询超过200条审计事件	references/audit-commands.md + 规则25
排查访问拒绝、登录失败、角色配置错误、IP锁定、PAT/应用认证问题	references/identity-troubleshoot-guide.md
结构化诊断能力索引	references/diagnose/CAPABILITY.md
故障模式查询（12种命名模式）	references/diagnose/references/failure-modes.md
诊断优先级顺序（顺序排查）	references/diagnose/references/troubleshooting-guide.md