idsaas-skill
SKILL.md
IdSaaS 权限分配 Skill（idsaas）
本 Skill 说明如何通过仓库内 Python 脚本（idsaas-cli/scripts/）调用 IdSaaS 权限相关接口。
流程与安全（必读）
- 先确认当前操作者信息
在调用角色分配、标签分配等接口前，应先运行
**current_user_info.py** 查询当前密钥对应的用户信息，确认操作者身份后再继续；该接口信息在各环境通用，不依赖用户选择环境。 - 再确认环境
在调用角色分配、标签分配等接口前，应运行
**fetch_navigation_domains.py，根据返回的g_env_link与用户确认要使用哪一个环境；除非用户在提问时已明确说明环境，否则不要猜测。
它返回的各环境、各区域的入口url，用于推导后续业务脚本的**--base-url；脚本只需要传域名，公共 HTTP 层会自动补/idsaas。current_user_info.py与fetch_navigation_domains.py可先后任意执行，但在真正分配权限前都应完成确认。 **--base-url（IdSaaS 域名）** 不要求用户事先配置环境变量。 在用户选定环境后(可能是中文或域名地址)，由助手根据g_env_link里所选条目的url推导出 IdSaaS 域名，再作为各业务脚本的--base-url传入； （重要） 若要给多个环境下的同一人分配权限，必须在每个环境分别拉取/搜索角色与项目信息；不同环境的roleId、项目 id 等可能不同，不可复用另一环境的 id。- 超级管理员 若用户拥有 「权限管理系统-超级管理员」 角色，则理论上可为他人分配范围更大的权限；务必谨慎操作，并在对话中明确风险提示。
- 403 / 503 与权限 若接口返回 403，表示当前密钥对应用户没有相应操作权限，需要找相关业务管理员加权限，或没配置好访问密钥；若返回 503（或其它异常且服务端提示无权限），也应按权限不足排查。此时应请用户联系管理员 方健炜、李宴儒 咨询开通或代操作。
认证（参数传入，不用环境变量）
除 **fetch_navigation_domains.py** 外，其余脚本调用的业务接口均须在 HTTP Header 携带：
X-User-Api-Key: TCL_SKILL_USER_KEY密钥，可以通过以下方式获取：1.Windows 读取 %USERPROFILE%\.env\skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.cmd 脚本获取密钥； 2.Linux/macOS 读取 ~/.env/skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.sh 脚本获取密钥。如果用户没配置密钥，请提示他到https://platform-eaglelab.tcl.com/skill-page/manage/keys复制命令配置密钥
命令示例
# 0）查询当前操作者信息。
# 说明：调用 /user/user-info；信息在各环境通用，默认使用线上固定网关。
python scripts/current_user_info.py --api-key "你的密钥"
# 1）获取各环境域名 / 导航入口。
# 说明：返回各个环境的域名以及对应的中文名称
python scripts/fetch_navigation_domains.py
# 2）搜索用户。
# 说明：按姓名 / 账号模糊查询，或按工号 / 邮箱精确查询；业务脚本均需 --base-url 与 --api-key。 返回的accountName employeeId 就是用户的信息，而userId，userName是修改人信息不要使用他。
python scripts/search_users.py --base-url "https://idsaas-o.api.leiniao.com" --api-key "你的密钥" "00335673"
# 3）查询用户已拥有角色(roleId)及当前操作者可分配的角色。
# 说明：返回角色相关信息；后续添加 / 删除角色时使用其中的整数 roleId。
# 注意：返回的字段里roleIds是已有角色的id，而roles字段里面的角色是可分配的角色信息
python scripts/list_user_roles.py --base-url "https://idsaas-o.api.leiniao.com" --api-key "你的密钥" 00335673
# 4）为一个或多个用户增加同一角色。
# 说明：第一个位置参数是整数 roleId，后续为一个或多个员工号；脚本会生成 userIdList 数组。
python scripts/add_user_role.py --base-url "https://idsaas-o.api.leiniao.com" --api-key "你的密钥" 77 00335673 00335674
# 5）删除一个或多个用户的同一角色。
# 说明：第一个位置参数是整数 roleId，后续为一个或多个员工号；不要把 JSON 数组字符串当作参数传入。
python scripts/remove_user_role.py --base-url "https://idsaas-o.api.leiniao.com" --api-key "你的密钥" 12345 00335673 00335674
# 6）查询用户在权限管理系统下的标签。
# 说明：调用 list-user-label；只用于查看权限管理系统标签。
python scripts/list_user_project_labels.py --base-url "https://idsaas-o.api.leiniao.com" --api-key "你的密钥" 00335673
# 7）获取业务项目列表。
# 说明：调用脚本后，结果中的项目 path是add_user_label_by_project追加标签使用的参数(如cms-ai-partner)可用于追加权限系统标签，拥有该项目标签，则拥有该项目的角色分配权限。而返回的name是项目的名称(如：咚咚伙伴)， 在list_user_project_labels获取时可以查看用户是否已经拥有该标签
python scripts/fetch_project_list.py --base-url "https://idsaas-o.api.leiniao.com" --api-key "你的密钥"
# 8）按业务项目追加权限系统标签。
# 说明：project_path 应来自业务项目列表；追加成功后会反查 cms-idsaas 标签确认写入；不要把 cms-idsaas 当作业务项目 path 误传。
python scripts/add_user_label_by_project.py --base-url "https://idsaas-o.api.leiniao.com" --api-key "你的密钥" 00335673 "业务项目path"
接口注意点
**userIdList**：须为 JSON 数组（元素为员工号字符串）。脚本用「多个工号位置参数」生成正确 JSON；不要把整个'["a","b"]'当作单个字符串传参。**roleId**：整数主键，不是角色显示名称。**list-user-label与list-user-role：带**labels**、按**projectPath**查标签的是**POST /user/list-user-label**（脚本list_user_project_labels.py），该脚本固定传**projectPath=cms-idsaas**，只用于查看权限管理系统标签。POST /user/list-user-role只返回角色**roleIds/roles**（脚本list_user_roles.py）。**POST /user/add-user-label-by-project**：projectPath为 业务项目 path（来自fetch_project_list.py结果里面的path参数；勿把cms-idsaas当作业务项目 path 误传（与「在cms-idsaas下查询标签」是不同概念）。
内部模块
**_idsaas_http.py**：仅供上述脚本引用，无独立命令行入口。