docs: 更新 v-permission 指令 API 文档，添加导出和规则结构说明

Author: SeasonsChange422

docs/directives/permission.md

@@ -152,6 +152,104 @@ createPermissionDirective({
 - `replace`：仅对宿主元素内部带标识属性的子元素设置 `textContent`
 - `allow`：不处理并恢复原始状态
 
+## API
+
+### 导出
+
+```ts
+import { createPermissionDirective, DEFAULT_PERMISSION_REPLACE_ATTR } from 'tml-ui'
+
+import type {
+  CreatePermissionDirectiveOptions,
+  PermissionBehavior,
+  PermissionKey,
+  PermissionLevel,
+  PermissionMode,
+  PermissionRule,
+  PermissionRules,
+  PermissionReplaceOptions,
+  ResolvePermission,
+  ResolvePermissionResult
+} from 'tml-ui'
+```
+
+### `createPermissionDirective`
+
+```ts
+function createPermissionDirective<Level extends PermissionLevel = string>(
+  options: CreatePermissionDirectiveOptions<Level>
+): import('vue').Directive<HTMLElement, string>
+```
+
+- 指令名：`permission`（模板中使用 `v-permission`）
+- 绑定值：`string`，作为权限 key（会 `trim()`；空字符串视为未配置，恢复原始状态）
+- 参数/修饰符：当前版本不使用
+
+### `CreatePermissionDirectiveOptions`
+
+```ts
+export interface CreatePermissionDirectiveOptions<Level extends PermissionLevel = string> {
+  rules: PermissionRules
+  resolvePermission: ResolvePermission<Level>
+  replace?: PermissionReplaceOptions
+}
+```
+
+- `rules`：权限规则表（key -> rule）
+- `resolvePermission`：权限解析函数，返回 `boolean` 或“等级”
+- `replace.targetAttr`：自定义替换目标属性名（默认 `DEFAULT_PERMISSION_REPLACE_ATTR`）
+
+### `ResolvePermission`
+
+```ts
+export type ResolvePermissionResult<Level extends PermissionLevel = string> = boolean | Level
+
+export type ResolvePermission<Level extends PermissionLevel = string> = (
+  key: PermissionKey
+) => ResolvePermissionResult<Level>
+```
+
+- 返回 `true`：允许（不处理，恢复原始状态）
+- 返回 `false`：按 `whenDenied` 执行
+- 返回 `Level`：仅当规则配置了 `byLevel` 时生效；否则默认不处理（恢复原始状态）
+
+### 规则结构
+
+```ts
+export type PermissionMode = 'allow' | 'hide' | 'disable' | 'replace'
+
+export interface PermissionBehavior {
+  mode: PermissionMode
+  replaceText?: string
+}
+
+export type PermissionByLevelConfig = Partial<Record<string, PermissionBehavior>>
+
+export type PermissionRule =
+  | { whenDenied: PermissionBehavior }
+  | { byLevel: PermissionByLevelConfig }
+  | ({ whenDenied: PermissionBehavior } & { byLevel: PermissionByLevelConfig })
+
+export type PermissionRules = Record<PermissionKey, PermissionRule>
+```
+
+规则匹配优先级（按实现逻辑）：
+
+- `resolvePermission(key)` 返回 `boolean`
+  - `true`：允许
+  - `false`：若配置 `whenDenied` 则使用 `whenDenied`，否则不处理
+- `resolvePermission(key)` 返回 `Level`
+  - 若配置 `byLevel`：使用 `byLevel[String(level)]`
+  - 未配置 `byLevel`：不处理
+
+### `DEFAULT_PERMISSION_REPLACE_ATTR`
+
+```ts
+export const DEFAULT_PERMISSION_REPLACE_ATTR = 'data-permission-replace'
+```
+
+- `replace` 模式默认会查找宿主元素内部所有带该属性的子元素，并替换其 `textContent`
+
 ## 安全说明
 
 `replace` 默认使用 `textContent` 写入替换文案，不渲染 HTML，以避免引入 XSS 风险。