alibabacloud-csas-user-device-ops

预检查

需要 Aliyun CLI >= 3.3.3

aliyun version

如果尚未安装或版本过低，请参阅 references/cli-installation-guide.md。

插件设置（首次使用前必须运行）

aliyun configure set --auto-plugin-install true
aliyun plugin update

AI-Mode 生命周期（必须遵循）

在工作流开始时（调用任何 CLI 之前）：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-csas-user-device-ops"

在每个退出点（成功、失败、错误、取消，包括每次写入操作完成后）：

aliyun configure ai-mode disable

[必须] 即使操作成功，也要运行 ai-mode disable。这是成功流程的一部分，不只是错误流程的一部分。

凭证验证

安全规则：

• 绝不读取、回显或打印 AK/SK 值
• 绝不要求用户在对话中输入 AK/SK
• 仅使用 aliyun configure list 检查凭证状态

aliyun configure list

如果不存在有效配置文件，请停止。引导用户在本会话之外配置凭证。

RAM 策略与权限处理

所需权限列于 references/ram-policies.md。

[必须] 权限失败处理： 当任何命令因权限错误失败时（HTTP 403、"AccessDenied"、"Forbidden"、"no permission" 或类似错误）：

1. 立即停止执行。不要盲目重试。
2. 从错误消息中识别失败的 API（例如 csas:ListUserDevices、csas:UpdateUserDevicesStatus）。
3. 告知用户失败的确切 RAM Action，并提供两种方案：
   • 快捷方案： 为 RAM 用户/角色附加系统策略 AliyunCSASFullAccess（涵盖所有 CSAS 操作）。
   • 最小权限方案： 仅将特定失败的 Action 添加到自定义策略。最小权限策略模板请参阅 references/ram-policies.md。
4. 暂停并等待用户确认已授予权限。
5. 确认后，重试失败的操作。

权限错误消息模板：

"调用 csas:<ApiName> 时权限被拒绝。请授予 AliyunCSASFullAccess（涵盖所有操作的系统策略），或将 csas:<ApiName> 添加到自定义 RAM 策略。详情请参阅 references/ram-policies.md。授予权限后回复 'done'，我会重试。"

操作路由

根据用户意图选择执行路径：

用户意图	执行方式
查询/筛选设备（任意条件组合）	使用参数运行 aliyun csas list-user-devices
查询用户列表（按部门、状态、名称）	使用参数运行 aliyun csas list-users
检查用户可访问哪些应用	aliyun csas list-user-applications
获取单台设备详情	aliyun csas get-user-device
检查 IDP 身份源配置	aliyun csas get-active-idp-config
查询用户组	aliyun csas list-user-groups
分析不活跃设备	bash scripts/inactive-analysis.sh
锁定不活跃设备	bash scripts/cleanup-inactive.sh
删除用户账户或设备	不支持 — 引导用户前往 SASE 控制台

查询示例转换：

• “显示 QA 部门中运行 macOS 且禁用了 DLP 的设备” → aliyun csas list-user-devices --department QA --device-types macOS --dlp-statuses Disabled --pager
• “哪些设备是个人设备且长期离线” → aliyun csas list-user-devices --device-belong Personal --device-statuses LongTermOffline --pager
• “用户获授权访问哪些内部应用” → aliyun csas list-user-applications --sase-user-id <ID> --current-page 1 --page-size 100
• “有多少台 Windows 设备处于在线状态” → aliyun csas list-user-devices --device-types Windows --device-statuses Online --current-page 1 --page-size 1（检查 TotalNum）

直接 CLI 命令

所有查询均直接使用 aliyun csas 插件模式。使用 --pager 自动翻页获取完整结果。 完整参数详情请参阅 references/api-reference.md。

参数验证规则

[MUST] 调用 API 前验证参数，避免出现 InvalidParameter 错误：

来源：aliyun csas <command> --help

参数	约束	示例	来源
--current-page	int，1~10000	1	CLI 帮助
--page-size	int，1500（list-user-applications：1100）	100	CLI 帮助
--device-action	枚举：Locked Lost Unbound Unlocked Found	Locked	CLI 帮助
--device-statuses	枚举列表	Online LongTermOffline	CLI 帮助
--device-types	枚举列表	Windows macOS	CLI 帮助
--device-belong	枚举：Personal Company	Company	CLI 帮助
--sort-by	枚举：Username AppVersion UpdateTime	UpdateTime	CLI 帮助
--status（list-users）	枚举：Enabled Disabled	Enabled	CLI 帮助
--dlp-statuses	枚举列表：Enabled Disabled Unprovisioned Unauthorized	Disabled Unprovisioned	CLI 帮助
--pa-statuses	枚举列表：Enabled Disabled Unprovisioned	Enabled	CLI 帮助
--ia-statuses	枚举列表：Enabled Disabled Unprovisioned	Disabled	CLI 帮助
--nac-statuses	枚举列表：Enabled Disabled Unprovisioned	Unprovisioned	CLI 帮助
--sase-user-id	取自 API 响应中的 SaseUserId 字段	su_2e10e16a****0566abea4ce6	观察所得
--sase-user-ids	SaseUserId 列表	su_2e10****4ce6 su_ef48****573b	观察所得
--device-tag	取自 API 响应中的 DeviceTag 字段	480F8E02-****-5932A5FF60BC	观察所得
--device-tags	DeviceTag 列表	480F8E02-****-60BC 24BB1571-****-86EF	观察所得
--username	字符串	test001	CLI 帮助
--fuzzy-username	字符串，模糊匹配	zhang	CLI 帮助
--precise-username	字符串，精确匹配	zhangsan	CLI 帮助
--department	字符串	Engineering	CLI 帮助
--hostname	字符串	MacBook-Pro	CLI 帮助
--mac	字符串	3c:06:****:79:1b	CLI 帮助
--inner-ip	字符串	10.0.**.**	CLI 帮助
--user-group-ids	列表	usergroup-51bd****a540	观察所得
--name（list-user-applications）	字符串	CRM	CLI 帮助
--address（list-user-applications）	字符串（IPv4/CIDR/域名）	192.168.1.0/24	CLI 帮助

所有枚举值均区分大小写。列表参数的值以空格分隔（不能用逗号）。

[MUST] 用户提供的 SaseUserId 或 DeviceTag 看起来不正确时：

不要盲目调用 API。可以提出查找正确值：

• SaseUserId：使用 aliyun csas list-users --fuzzy-username <name> 查找真实 ID
• DeviceTag：使用 aliyun csas list-user-devices --username <name> 查找真实标签

list-user-devices

使用 20 多种筛选条件的任意组合查询设备：

aliyun csas list-user-devices --current-page 1 --page-size 100 [OPTIONS] [--pager]

主要筛选条件：--department、--device-types（列表）、--device-statuses（列表）、--dlp-statuses、--pa-statuses、--ia-statuses、--nac-statuses、--username、--device-belong、--hostname、--sort-by。

列表参数的值以空格分隔：--device-types Windows macOS

枚举值：

• DeviceStatuses：Online Offline LongTermOffline Locked Lost Unbound
• DeviceTypes：Windows macOS Linux Android iOS Windows_Wuying
• DlpStatuses：Enabled Disabled Unprovisioned Unauthorized
• PaStatuses/IaStatuses/NacStatuses：Enabled Disabled Unprovisioned

list-users

aliyun csas list-users --current-page 1 --page-size 100 [OPTIONS] [--pager]

主要筛选条件：--fuzzy-username、--precise-username、--department、--status（Enabled/Disabled）、--sase-user-ids（列表）。

list-user-applications

查询授权给用户的私有访问应用：

aliyun csas list-user-applications --sase-user-id <ID> --current-page 1 --page-size 100

必需参数：--sase-user-id。可选参数：--name、--address。

get-user-device

获取单台设备的完整详情：

aliyun csas get-user-device --device-tag <TAG>

get-active-idp-config

获取当前启用的身份提供商配置：

aliyun csas get-active-idp-config

list-user-groups

aliyun csas list-user-groups --current-page 1 --page-size 100 [OPTIONS] [--pager]

主要筛选条件：--name、--attribute-value、--user-group-ids（列表）、--pa-policy-id。

输出格式

向用户展示查询结果时，请遵循以下规则，避免输出过多信息：

结果数量阈值：

• ≤10 项：全部显示
• 11–50 项：显示前 20 项 + 总数
• >50 项：显示前 20 项 + 总数 + 建议缩小筛选范围

**表格格式：**使用 Markdown 表格，仅包含关键列（不显示完整 JSON）。设备示例列：#、用户、主机名、设备类型、相关状态、部门。

使用 --cli-query 在 API 层提取字段：

aliyun csas list-user-devices --dlp-statuses Disabled --current-page 1 --page-size 100 \
  --cli-query "{total: TotalNum, devices: Devices[].{user: Username, host: Hostname, type: DeviceType, dlp: DlpStatus, dept: Department}}"

显示部分结果前，务必说明总数，例如：“已找到 844 台已停用 DLP 的设备，显示前 20 台：”

基于脚本的操作

非活动分析（只读）

根据 UpdateTime 阈值识别非活动设备：

bash scripts/inactive-analysis.sh --days 30 [--max-days 180]

选项：--days N（>=1，默认 30）、--max-days M（可选，上限）、--department、--device-type、--page-size

参数语义：

• 单独使用 --days N：选择所有 UpdateTime < 今天-N 的设备（非活动 ≥ N 天）
• 使用 --days N --max-days M：选择 today-M ≤ UpdateTime < today-N 的设备（非活动 N~M 天）

常见模式：

用户表述	参数
“非活动 90 天以上”	--days 90
“非活动 90~180 天”	--days 90 --max-days 180
“非活动 180 天以上”	--days 180
“一年多未活动”	--days 365
“非活动 6 个月到 1 年”	--days 180 --max-days 365

[MUST] 用户的时间范围含糊不清时，执行前请先询问确认：

“‘非活动 90 天’是指所有 ≥90 天未活动的设备，还是仅指 90~180 天未活动的设备？”

输出：包含非活动设备列表和汇总统计信息的 JSON。不执行写入操作。

**注意：**不支持用户活动情况分析。原因：list-users API 不会返回最后活动时间戳，且当其他用户登录时，设备绑定会发生变化（每台设备仅保留最近一位用户）。因此，无法准确判断用户活动状态。 对于用户级别的分析，请参阅 SASE 控制台审计日志。

用户询问休眠账户或长期未活动的设备时，请从此处着手。

清理非活动设备（破坏性操作，可撤销）

锁定非活动 N 天的设备。遵循下文的写入操作规则。

第 1 步 — 预览：

bash scripts/cleanup-inactive.sh --days 90 --dry-run

向用户展示试运行输出：

• 扫描的设备总数、非活动设备数，以及包含详细信息的设备列表
• 遵循上述输出格式规则（≤10 项时全部显示，>10 项时显示前 20 项 + 总数）
• 在执行第 2 步前，向用户征求明确确认

第 2 步 — 执行（仅在用户确认后）：

bash scripts/cleanup-inactive.sh --days 90 --yes

分批锁定所有非活动设备（每次 API 调用 ≤100 台）。锁定操作具有幂等性，且可撤销。

第 3 步 — 验证并报告：

执行后：

1. 操作后验证 — 对每台已锁定的设备调用 aliyun csas get-user-device --device-tag <TAG>（设备较多时可抽样），确认 DeviceStatus == "Locked"。由此形成操作闭环：操作前状态（试运行）→ 执行 → 操作后状态（验证）。
2. 整理结果并报告给用户 — 不要直接输出原始脚本 JSON。将其转换为 Markdown 汇总：
   • 一句话结论，例如：“锁定完成：扫描 3 台，锁定 1 台，失败 0 台。”
   • 已锁定设备的 Markdown 表格（DeviceTag、Username、Hostname、DeviceType、新状态）
   • 恢复提示：使用 aliyun csas update-user-devices-status --device-action Unlocked --device-tags <TAGS> 撤销操作。
3. 如果存在失败 — 列出失败的 DeviceTag，并建议仅针对这些标签重试。

写入操作规则

[MUST] 所有写入操作都必须获得用户确认：

1. 说明将要执行的操作（目标设备/用户、操作、数量）
2. 请用户确认，并等待用户明确答复“是”
3. 只有在用户确认后才能执行——绝不自动执行

[MUST] 取消操作的处理： 当用户取消操作（回复“no”“cancel”“stop”或任何非明确确认的内容）时：

1. 不要执行破坏性操作
2. 不要默默结束会话——提供后续选项：

   “操作已取消。其他选项：（a）修改范围（例如，更改时间范围或筛选条件）；（b）仅查看设备列表，不锁定设备；（c）导出 DeviceTag 列表以供手动审核；（d）退出。你想选择哪一项？”

3. 等待用户选择后再继续
4. 如果用户确认退出，请妥善结束，并总结哪些操作未执行

[MUST] 幂等执行：

• 即使目标集合为空（0 台设备匹配），仍要运行命令并报告“影响 0 台”
• 即使设备已处于目标状态（例如已锁定），仍要执行——API 具有幂等性
• 绝不以“已完成”为由跳过执行——始终运行并报告实际结果

[MUST] 操作后验证（操作闭环）： 每项写入操作都必须形成闭环：pre-check → execute → post-verify。

1. 写入前：确认目标列表（试运行预览）。
2. 执行写入操作。
3. 写入后：重新查询受影响的资源（例如，get-user-device --device-tag <TAG>），并确认新状态符合预期操作。
4. 报告已验证的结果，而不只是脚本的成功标志。

[MUST] 最终结果格式： 绝不要在最终答复中向用户输出原始脚本 JSON。始终：

1. 先用一句话总结结果（例如，“✅ 锁定完成：1/1 台设备已锁定，0 台失败”）
2. 在 Markdown 表格中展示关键信息（仅包含关键列）
3. 适用时附上恢复/后续步骤提示
4. 以 AI-Mode 禁用命令结尾（见预检查）

[MUST] 安静执行： 执行多步骤操作时，尽量减少工具调用之间的说明。

• 不要宣布“现在我将启用 AI 模式”或“正在执行锁定命令”等无关紧要的步骤
• 不要回显 (no output) 或空工具结果
• 仅在以下情况向用户发言：（a）展示预览/结果；（b）请求确认；（c）报告错误
• 在到达面向用户的关键节点前，内部工具调用链应保持静默

适用于：

• bash scripts/cleanup-inactive.sh --yes（批量锁定）
• aliyun csas update-user-devices-status --device-action <ACTION> --device-tags <TAGS>（直接锁定/解锁）

确认模板：

“即将在 N 台设备上执行[锁定/解锁/标记丢失/标记找回]操作。确认吗？”

能力边界

此技能不会执行不可逆操作：

• 删除用户账号（DeleteClientUser）
• 删除终端设备（DeleteUserDevices）
• 冻结／解冻用户账号（UpdateUsersStatus）
• 分析用户活动（API 限制：无法获取用户最近活动时间）

[MUST] 用户要求删除不活跃用户／设备时，遵循以下流程：

1. 明确范围 — 此技能只分析和操作设备，不分析用户活动：

   “仅支持查询不活跃设备和锁定设备。无法分析用户活动（API 限制）。要查询不活跃 N 天以上的设备吗？”

2. 引导用户进行设备分析 — 请用户指定设备的时间范围：

   “我可以帮你：查询不活跃 N 天以上的设备；查询不活跃 N～M 天的设备；锁定这些设备（可撤销，可随时解锁）。你需要查询哪个时间范围？”

3. 说明不支持删除的原因：

   “删除操作不可逆，此技能不会执行删除。锁定效果相同（设备无法连接）。确认后，你可以通过控制台删除。”

4. 提供锁定替代方案，并说明具体影响：

   “改为锁定这 N 台设备吗？锁定后，它们将无法访问网络。你可以随时解锁。”

5. 如果用户坚持删除，引导其前往控制台：

   “前往 Alibaba Cloud Console → SASE → Terminal Management 手动删除。我可以导出 DeviceTag 列表，供你在控制台批量操作。”

6. 如果用户接受锁定，按照写入操作规则（预览 → 确认 → 执行）继续操作。

切勿默默拒绝。 始终提供替代操作方案。

错误处理

所有脚本都会输出结构化 JSON，其中包含 success: true/false。发生故障时，请检查 error 和 message 字段。

常见错误：

• ApiCallFailed — 检查网络、凭据和权限
• ValidationError — 参数无效；详情请参见错误消息
• Permission denied / HTTP 403 / AccessDenied — 按照上文“RAM 策略与权限处理”部分操作。建议使用 AliyunCSASFullAccess（快捷方案），或添加特定的 csas:<ApiName> Action（最小权限方案）。
• 文件系统错误（write_file 失败、输出路径不存在）— 检查输出目录是否存在且可写。如果无法写入该路径，则改为将报告打印到 stdout。

所有写入操作都是幂等的。部分失败后可以安全重试。即使目标为空或已处于所需状态，也要执行操作并报告结果。

脚本参考

脚本	用途
scripts/validate-cli.sh	CLI 环境验证
scripts/inactive-analysis.sh	只读的不活跃设备分析
scripts/cleanup-inactive.sh	锁定不活跃设备（具有破坏性，但可撤销）
scripts/common.sh	共享实用程序（由其他脚本加载）

完整的 API 参数参考：references/api-reference.md CLI 命令列表：references/related-commands.md