docs(permission): 统一校准权限节点措辞，消除更新节点误解

admin:permission:nodes 是查看型命令（实时扫描注解、不写库、改注解即生效），但文档/注释多处用一键更新/自动更新/生成等动作词描述，导致开发者系统性误以为它是更新权限节点命令。本次校准 8 个文件 10 处误导措辞，并在命令输出末尾追加机制提示。@NodeAnotation 拼写保持不变（框架故意少一个 t）。
2026-08-30 12:45:32 +08:00 · 2026-08-08 18:21:25 +08:00
parent 7341268ceb
commit ad96755ff5
8 changed files with 11 additions and 8 deletions
--- a/.agents/skills/ulthon-admin-table/SKILL.md
+++ b/.agents/skills/ulthon-admin-table/SKILL.md
@@ -604,7 +604,7 @@ CURD 生成时会将关联模型的全部字段（如 `systemAdmin.*`）输出
 1. 检查 HTML 是否声明了对应的 `data-auth-X`（用浏览器开发者工具看 table 元素）
 2. 检查 `{:auth('xxx/yyy')}` 的返回值是否为 1（用超管账号测试排除权限问题）
 3. 检查 JS 里 `auth: 'X'` 的 X 与 HTML `data-auth-X` 是否完全一致（大小写）
-4. 检查权限节点是否已生成：`php think admin:permission:nodes`
+4. 查看权限节点列表：`php think admin:permission:nodes`

 **"搜索不生效"排查步骤**：

--- a/.agents/skills/ulthon-permission-cli/SKILL.md
+++ b/.agents/skills/ulthon-permission-cli/SKILL.md
@@ -15,6 +15,8 @@ description: "解释并指导 RBAC 权限体系与相关 CLI 命令（admin:role

 ## 概念速览

+> **机制声明**：权限节点由框架动态扫描控制器 @NodeAnotation 注解实时生成，**不持久化到数据库**，修改注解后立即生效。不存在"更新/刷新节点"的命令，`admin:permission:nodes` 仅用于查看核对。
+
 - 权限节点：基于控制器/方法注解生成的权限标识（用于授权与鉴权）。
 - 角色：权限节点的集合（`SystemAuth`）。
 - 用户：后台用户（`SystemAdmin`），通过 `auth_ids`（逗号分隔）绑定角色 ID 列表。
--- a/.agents/skills/ulthon-scheme-curd-workflow/SKILL.md
+++ b/.agents/skills/ulthon-scheme-curd-workflow/SKILL.md
@@ -168,7 +168,7 @@ php think tools:http:call --url="/admin/<模块路径>/delete" --method=POST --d
 ### 功能配套

 - **菜单**：用 `admin:menu:*` 新增/调整菜单，与页面路径/节点保持一致。详见 [ulthon-admin-menu-cli](./ulthon-admin-menu-cli/SKILL.md)。
- **权限**：用 `admin:permission:nodes` 生成/核对节点，为角色分配节点并为用户分配角色。详见 [ulthon-permission-cli](./ulthon-permission-cli/SKILL.md)。
+- **权限**：用 `admin:permission:nodes` 核对节点（节点由注解动态生成，命令仅查看），为角色分配节点并为用户分配角色。详见 [ulthon-permission-cli](./ulthon-permission-cli/SKILL.md)。
 - **数据库排错**：必要时用 `tools:db:*` 做只读检查，详见 [ulthon-db-tools-debug](./ulthon-db-tools-debug/SKILL.md)。

 ### 交付检查
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -49,7 +49,7 @@

 - 数据库：表结构优先 Scheme（`app/admin/scheme/`）；避免 ENUM；tools:db 用于调试，不用于"设计表结构"
 - 前端：视图与脚本同名配对（`*.html` + 同名 `*.js`），并按模块维护 `_common.js`
- 权限：基于 `auth` 注解生成节点与鉴权；以角色为中心管理（角色、角色权限、用户角色）；命令行使用见技能：[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md)
+- 权限：基于 `auth` 注解动态扫描节点与鉴权；以角色为中心管理（角色、角色权限、用户角色）；命令行使用见技能：[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md)
 - 临时文件：智能体在任务中产生的临时文件（脚本、日志、缓存、产物等）统一输出到 `runtime/agents/`（可按智能体/任务再分子目录），不要放在仓库根目录；除非任务明确要求或框架约定位置属于根目录
 - 调试与验证：优先使用框架内置命令行工具（tools:http:call、tools:db:*、tools:log:*、admin:menu:*、admin:permission:*），不需要借助外部数据库 MCP 或临时脚本

@@ -65,7 +65,7 @@
 | 4. 生成 CURD 代码 | `curd -t {table}`；后续字段变更可安全重新生成（`-r` 临时目录对比合并，不覆盖已改造的业务代码） | [ulthon-scheme-curd-workflow](./.agents/skills/ulthon-scheme-curd-workflow/SKILL.md) |
 | 5. 业务定制 | 仅改 `app/`；逐页调整按钮/字段/表单/交互；接口需求用页面接口同体机制 | [ulthon-page-api-dual-mode](./.agents/skills/ulthon-page-api-dual-mode/SKILL.md) |
 | 6. 功能验证 | `tools:http:call` 模拟请求跑通增删改查；`tools:log:*` 排查异常 | [ulthon-tools-http-call](./.agents/skills/ulthon-tools-http-call/SKILL.md) |
-| 7. 功能配套 | 菜单（`admin:menu:*`）、权限节点（`admin:permission:nodes`）、角色分配 | [ulthon-admin-menu-cli](./.agents/skills/ulthon-admin-menu-cli/SKILL.md)、[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) |
+| 7. 功能配套 | 菜单（`admin:menu:*`）、核对权限节点（`admin:permission:nodes` 仅查看）、角色分配 | [ulthon-admin-menu-cli](./.agents/skills/ulthon-admin-menu-cli/SKILL.md)、[ulthon-permission-cli](./.agents/skills/ulthon-permission-cli/SKILL.md) |
 | 8. 最终检查 | 页面路径可用、命令行验证通过、代码规范自查 | - |

 ## 规则维护机制
@@ -162,6 +162,6 @@ ulthon_admin/
 | 模拟 HTTP 请求       | `php think tools:http:call`             |
 | 查看日志             | `php think tools:log:show`              |
 | 数据库查询            | `php think tools:db:query "SELECT ..."` |
-| 权限节点生成           | `php think admin:permission:nodes`      |
+| 查看权限节点           | `php think admin:permission:nodes`      |
 | 菜单管理             | `php think admin:menu:*`                |
 | 框架更新             | `php think admin:update`                |
--- a/README.md
+++ b/README.md
@@ -131,7 +131,7 @@ php think admin:update
    * 支持生成**模型字段的属性声明**
 * 基于`auth`的权限管理系统
    * 通过`注解方式`来实现`auth`权限节点管理
-    * 具备一键更新`auth`权限节点，无需手动输入管理
+     * 基于`auth`注解动态扫描生成权限节点，修改注解即生效，无需手动同步
    * 完善的后端权限验证以及前面页面按钮显示、隐藏控制
 * 完善的菜单管理
    * 分模块管理
--- a/extend/base/admin/service/adminUpdateCodeData/v2.4.0.php
+++ b/extend/base/admin/service/adminUpdateCodeData/v2.4.0.php
@@ -24,7 +24,7 @@
 *   - 幂等 check-then-insert（先查询存在性，不存在才插入）
 *   - 不分配超管权限：AuthServiceBase::isSuperAdmin() 对 admin_id=1 直接返回 true，
 *     为 auth_id=1 植入 system_auth_node 是冗余且无效
- *   - 不直接植入权限节点：节点由 admin:permission:nodes 扫描控制器 @NodeAnotation 注解生成
+ *   - 不直接植入权限节点：节点由注解动态扫描生成（admin:permission:nodes 仅用于查看核对）
 *
 * 注意：此文件属于框架内核，业务开发者不应修改
 */
--- a/extend/base/common/command/admin/permission/AdminPermissionNodesBase.php
+++ b/extend/base/common/command/admin/permission/AdminPermissionNodesBase.php
@@ -90,6 +90,7 @@ class AdminPermissionNodesBase extends Command
            }

            $output->info('总计: ' . count($filteredNodes) . ' 个权限节点');
+            $output->writeln('提示：权限节点由框架动态扫描注解生成，修改 @NodeAnotation 注解后立即生效，无需手动更新。');

        } catch (\Exception $e) {
            $output->error('获取权限节点失败: ' . $e->getMessage());
--- a/route/welcome.php
+++ b/route/welcome.php
@@ -46,7 +46,7 @@ Route::view('/', 'welcome', [
    'feature' => [
        [
            'name'        => '内置权限管理',
-            'description' => '内置基于auth的权限系统，使用注解方式自动更新权限节点，无需手动维护。',
+            'description' => '内置基于auth的权限系统，动态扫描注解生成权限节点，修改注解即生效，无需手动维护。',
        ],
        [
            'name'        => '表格&表单的二次封装',