Manage Tenant Member

租户成员管理 Skill

1. Scenario Description

场景：在 Dataphin 租户维度进行组织级人员管理，包括将已有用户加入租户、调整全局角色、移除成员等。

Architecture

用户请求 → 确认参数 → list-addable-users 查找可添加用户
  → add-tenant-members / add-tenant-members-by-source-user 添加
  → list-tenant-members 验证
  →（可选）update-tenant-member 更新角色
  →（可选）remove-tenant-member 移除成员

涉及 Dataphin OpenAPI

• ListAddableUsers — 查询可加入租户但尚未加入的用户
• AddTenantMembers — 按用户 ID 批量添加租户成员
• AddTenantMembersBySourceUser — 按来源用户批量添加租户成员
• ListTenantMembers — 查询当前租户成员
• ListAddableRoles — 查询可配置的全局角色
• UpdateTenantMember — 更新租户成员全局角色
• RemoveTenantMember — 移除租户成员

2. Installation

# 安装 aliyun CLI（>= 3.4.8）
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

# 安装 dataphin-public 插件
aliyun plugin install --names aliyun-cli-dataphin-public

# 验证
aliyun dataphin-public --help

详见 CLI 安装指南。

3. Environment Variables

凭证与环境变量由父 skill alibabacloud-dataphin-skills 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 仅额外要求下列变量：

独立部署（非公共云）注意：

• 凭证 profile 必须带正确的 --endpoint（如 dataphin-openapi.<your-domain>），否则请求会打到公共云 dataphin-public.<region>.aliyuncs.com 报 InvalidAccessKeyId.NotFound。
• 自签证书环境需 export DATAPHIN_INSECURE=true（推荐），或在命令末尾追加 --insecure（--insecure 非解析 flag，放在参数中间会吞掉下一个参数值）。

4. Authentication

Pre-check: Credentials Required

Security Rules:

• NEVER 读取、回显或打印凭证环境变量（禁止对 AccessKey ID / Secret 做任何输出或日志）
• NEVER 要求用户在本会话或命令行直接输入 AK/SK
• NEVER 使用 aliyun configure set 写入字面量凭证
• ONLY 使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。

如果没有有效 profile，请在此停止。

1. 从 Alibaba Cloud Console 获取凭证
2. 在会话外配置（终端执行 aliyun configure，或在 shell profile 中设置环境变量）
3. 重新运行 aliyun configure list 确认有效后再继续

Pre-check: Aliyun CLI plugin update required

[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. [MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

执行前确认 CLI 与插件版本：

aliyun version
aliyun plugin list

5. RAM Policy

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read ../../ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. Pause and wait until the user confirms that the required permissions have been granted

本 skill 最小权限见 ../../ram-policies.md。

6. IMPORTANT: Parameter Confirmation

执行任何租户成员变更命令前必须向用户确认以下参数，禁止静默提交：

7. 完整命令链

TENANT_ID=<tenant-id>
USER_AGENT="AlibabaCloud-Agent-Skills/manage-tenant-member/{session-id}"

# 1) 查找可添加用户（支持按姓名/账号搜索）
aliyun dataphin-public list-addable-users --dataphin-profile <p> --tenant-id $TENANT_ID \
  --search-text "<姓名或账号>" --page 1 --page-size 10 \
  --user-agent "$USER_AGENT" --format json \
  | jq '.PageResult.UserList[] | {Id, Name, AccountName, DisplayName, SourceType}'

# 2) 添加租户成员（按用户 ID）
#    --user-list 每个参数是一个 JSON 对象字符串，不能传 JSON 数组
aliyun dataphin-public add-tenant-members --dataphin-profile <p> --tenant-id $TENANT_ID \
  --user-list '{"Id":"<user-id-1>"}' '{"Id":"<user-id-2>"}' \
  --user-agent "$USER_AGENT" --format json

# 3) 验证已加入租户
aliyun dataphin-public list-tenant-members --dataphin-profile <p> --tenant-id $TENANT_ID \
  --search-text "<姓名或账号>" --page 1 --page-size 10 \
  --user-agent "$USER_AGENT" --format json \
  | jq '.PageResult.UserList[] | {Id, Name, AccountName, RoleList}'

# 4) 查看可配置的全局角色
#    注意：字段名是 Code / Name，不是 RoleCode / RoleName
aliyun dataphin-public list-addable-roles --dataphin-profile <p> --tenant-id $TENANT_ID \
  --user-agent "$USER_AGENT" --format json \
  | jq '.RoleList[] | {Code, Name}'

# 5) 更新成员全局角色
#    --member-list 每个成员一个 JSON 对象字符串，含 UserId + RoleList 数组
#    可选字段：MobilePhone / Mail / DingNumber
aliyun dataphin-public update-tenant-member --dataphin-profile <p> --tenant-id $TENANT_ID \
  --member-list '{"UserId":"<user-id>","RoleList":["SYSTEM_ADMIN","DATASOURCE_MANAGER"]}' \
  --user-agent "$USER_AGENT" --format json

# 6) 移除租户成员
#    --source-id 为用户来源 Id（即成员的用户 Id）
aliyun dataphin-public remove-tenant-member --dataphin-profile <p> --tenant-id $TENANT_ID \
  --source-id '<user-id>' \
  --user-agent "$USER_AGENT" --format json

8. Observability

本 Skill 属于 alibabacloud-dataphin-skills 套件，继承父 Skill alibabacloud-dataphin-skills 的 session-id，子 Skill 不再重新生成。

所有调用 Alibaba Cloud API 的 aliyun 命令必须携带：

--user-agent AlibabaCloud-Agent-Skills/manage-tenant-member/{session-id}

其中 {session-id} 替换为父 Skill 生成的 32 位小写十六进制字符串。

9. 参数要点

10. 常见报错

11. ✗ 不要做

• ✗ 静默添加/移除租户成员：必须先确认用户身份和权限
• ✗ --user-list 传 JSON 数组：CLI 把每个参数当做一个 JSON 对象解析
• ✗ update/remove 误用 --user-id / --role-list：真实参数是 --member-list / --source-id
• ✗ 未确认当前调用者角色：仅 SuperAdmin / 系统管理员可操作
• ✗ 硬编码真实 tenant-id / user-id：应通过变量或用户确认后填充
• ✗ 未带 --user-agent 调用 aliyun API 命令

12. 验证与诊断

写操作（add / update / remove）成功判据：

1. 同步返回：响应 Code: "OK" 且 HttpStatusCode: 200 表示请求被接受
2. list 反查：执行 list-tenant-members 确认成员/角色变更已生效
3. 传播延迟：成员变更可能有短暂延迟（通常 < 5s），反查为空时稍候重试

# 确认成员已加入
aliyun dataphin-public list-tenant-members --dataphin-profile <p> --tenant-id $TENANT_ID \
  --search-text "<姓名>" --page 1 --page-size 10 \
  --user-agent "$USER_AGENT" --format json \
  | jq '.PageResult.UserList[] | {Id, Name, AccountName, RoleList}'

13. Cleanup

移除通过本 skill 添加的测试成员（如验证阶段 add-tenant-members 真实加入的用户）：

aliyun dataphin-public remove-tenant-member --dataphin-profile <p> --tenant-id $TENANT_ID \
  --source-id '<user-id>' \
  --user-agent "$USER_AGENT" --format json

--source-id 为成员的用户来源 Id；建议先用 list-tenant-members --search-text "<姓名>" 反查确认后再移除。 执行前可先加 --cli-dry-run 预检请求体，确认无误后再去掉该 flag 正式执行。

14. 相关命令

• aliyun dataphin-public list-addable-users — 查询可加入租户的用户
• aliyun dataphin-public add-tenant-members — 按用户 ID 添加租户成员
• aliyun dataphin-public add-tenant-members-by-source-user — 按来源用户添加租户成员
• aliyun dataphin-public list-tenant-members — 查询当前租户成员
• aliyun dataphin-public list-addable-roles — 查询可配置的全局角色
• aliyun dataphin-public update-tenant-member — 更新租户成员角色
• aliyun dataphin-public remove-tenant-member — 移除租户成员
• manage-project-member（dataplan 模块） — 项目级别成员管理（经套件入口 alibabacloud-dataphin-skills 路由加载）

15. 最佳实践与参考链接

1. 大整数 ID 字符串传参：用户 ID / 租户 ID 为 9~19 位 snowflake，一律用引号包住，避免精度丢失（如 --source-id '1234567890123456789'）
2. 写操作先 dry-run 预检：add / update / remove 正式执行前先加 --cli-dry-run 校验请求体结构，确认无误再去掉该 flag
3. 写操作必须 HITL 确认：添加/更新/移除成员前向用户确认身份与权限，禁止静默操作
4. --user-list 传单个 JSON 对象：每个用户一个 {"Id":"xxx"}，多用户传多个参数，不能传 JSON 数组
5. update / remove 用对参数：更新用 --member-list（{"UserId":"x","RoleList":[...]}），移除用 --source-id，不是 --user-id/--role-list

Reference Links

• references/cli-installation-guide.md
• ../../ram-policies.md
• references/acceptance-criteria.md
• references/related-commands.md