feat: 发布智能体版

.agents/skills/ulthon-permission-cli/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: "ulthon-permission-cli"
+description: "解释并指导 RBAC 权限体系与相关 CLI 命令（admin:role:* / admin:user:role:* / admin:permission:*）。用于查看节点、管理角色权限、给用户分配角色、排查权限问题。"
+---
+
+# 权限与角色管理（RBAC CLI）
+
+## 何时调用
+
+- 需要查看系统当前有哪些权限节点。
+- 需要创建/查看/删除角色，或查看角色详情。
+- 需要为角色分配/撤回权限节点。
+- 需要给指定用户分配/撤回角色。
+- 需要排查“有菜单但无权限 / 有权限但仍被拦截 / 节点名称不一致”等权限问题。
+
+## 概念速览
+
+- 权限节点：基于控制器/方法注解生成的权限标识（用于授权与鉴权）。
+- 角色：权限节点的集合（`SystemAuth`）。
+- 用户：后台用户（`SystemAdmin`），通过 `auth_ids`（逗号分隔）绑定角色 ID 列表。
+- 角色-节点：`SystemAuthNode` 记录 `auth_id + node` 的多对多关系。
+- 鉴权入口：后台请求进入后会根据“当前节点”进行权限检查（未授权则拦截）。
+- 输出说明：权限相关命令默认以文本输出为主；如命令涉及交互确认，可使用 `--force-force` 或 `-ff` 跳过确认。
+
+## 常用命令
+
+### 1) 查看权限节点
+
+```bash
+php think admin:permission:nodes
+```
+
+常用参数（如需）：
+- `--module=<模块>`：按模块过滤
+- `--level=1|2`：按级别过滤（1=控制器，2=方法）
+
+### 2) 角色管理
+
+```bash
+php think admin:role:list
+php think admin:role:info --role-id=12
+php think admin:role:create --title="测试角色" --remark="测试用"
+php think admin:role:delete --role-id=12
+```
+
+要点：
+- 删除角色会检查该角色是否仍被用户分配；若仍有用户绑定，则删除会失败。
+
+### 3) 角色权限管理
+
+```bash
+php think admin:role:permission:list --role-id=12
+php think admin:role:permission:assign --role-id=12 --nodes="system.admin/index,system.admin/add"
+php think admin:role:permission:revoke --role-id=12 --nodes="system.admin/add"
+```
+
+要点：
+- `--nodes` 支持逗号分隔批量操作。
+- 建议先用 `admin:permission:nodes` 确认节点名称完全一致后再分配到角色。
+
+### 4) 用户角色管理
+
+```bash
+php think admin:user:role:list --user-id=1
+php think admin:user:role:assign --user-id=1 --role-ids="12,13"
+php think admin:user:role:revoke --user-id=1 --role-ids="13"
+```
+
+### 5) 透视查询用户当前权限
+
+```bash
+php think admin:permission:user --user-id=1
+```
+
+## 典型工作流
+
+### 工作流 A：新增/调整注解后，核对节点并授权
+
+1. 在控制器/方法上新增或调整权限注解（节点名称、标题、模块等）。
+2. 执行 `admin:permission:nodes`，确认节点列表中已出现新节点且名称符合预期。
+3. 确定要使用的角色（可通过 `admin:role:list` / `admin:role:info` 查看；没有合适角色就用 `admin:role:create` 新建）。
+4. 执行 `admin:role:permission:assign` 将新节点分配给角色。
+5. 执行 `admin:user:role:assign` 将角色分配给用户。
+6. 执行 `admin:permission:user` 透视确认该用户已拥有节点。
+
+### 工作流 B：排查“明明有权限但仍被拦截”
+
+1. 执行 `admin:permission:user --user-id=<id>`，确认用户是否真的拥有当前节点。
+2. 执行 `admin:permission:nodes`，确认“当前被拦截节点名”是否存在、是否有大小写/分隔符差异。
+3. 如果用户通过角色获得权限，执行 `admin:role:permission:list --role-id=<roleId>` 核对角色是否包含该节点。
+4. 检查后台配置中是否存在免鉴权规则（例如 no_login/no_auth 的控制器/节点白名单）。
+
+## 变更说明（重要）
+
+- 旧命令 `admin:permission:assign` / `admin:permission:revoke` 已移除。
+- “按用户直接增删节点”的需求，应通过“角色”承接：
+  - 只影响单个用户：创建专用角色 → 给该角色分配节点 → 将角色分配给该用户。
+  - 影响一批用户：维护共享角色 → 给该角色增删节点 → 所有拥有该角色的用户一起生效。
+
+## 常见坑位
+
+- 节点名不一致：注解里写的节点名与实际鉴权使用的当前节点不一致，导致分配了权限但无法命中。
+- 只改了菜单没改权限：菜单能看到不代表有权限访问，权限检查以节点为准。
+- 缓存/环境差异：在不同环境中节点生成来源不一致时，先以 `admin:permission:nodes` 的输出为准核对。
+- 修改共享角色影响面过大：撤回/新增角色节点会影响所有拥有该角色的用户。
+- 删除角色失败：仍有用户绑定该角色，先用 `admin:user:role:revoke` 撤回后再删除。