Feishu Cli Perm

# perm add 输入检查清单

执行 `perm add` 前，逐项确认以下内容：

## 1. TOKEN 与 doc-type 匹配

| Token 前缀 | 应使用的 doc-type |
|------------|------------------|
| `docx_` | docx |
| `doccn` | doc |
| `sht_` | sheet |
| `bascn` | bitable |
| `wikicn` | wiki |
| `fldcn` | folder |

如果 Token 无前缀或前缀不明确，需用户手动确认文档类型。

## 2. member-type 与 member-id 一致

| member-type | member-id 格式 |
|-------------|---------------|
| email | user@example.com |
| openid | `ou_` 前缀 |
| userid | 纯数字或自定义 ID |
| unionid | `on_` 前缀 |
| openchat | `oc_` 前缀 |
| opendepartmentid | `od_` 前缀 |
| groupid | `gc_` 前缀 |
| wikispaceid | `ws_` 前缀 |

## 3. 是否需要通知对方

- 添加 `--notification` 会向被授权者发送飞书通知
- 批量添加时建议开启，单个添加可按需选择

## 4. 权限级别选择

- `view`：只读分享（外部人员、大范围分享）
- `edit`：日常协作（团队成员）
- `full_access`：管理员（需要管理协作者或文档设置的场景）


---
name: feishu-cli-perm
description: >-
  飞书云文档权限管理。支持添加/更新/删除/查看协作者、公开权限管理、分享密码、批量添加、
  权限检查、转移所有权。当用户请求"添加权限"、"权限管理"、"共享文档"、"授权"、
  "协作者"、"full_access"、"转移所有权"时使用。
argument-hint: <doc_token> --perm <view|edit|full_access>
user-invocable: true
allowed-tools: Bash(feishu-cli perm:*), Read
---

# 飞书权限管理技能

飞书云文档权限管理：添加/更新/删除/查看协作者、公开权限管理、分享密码、批量添加、权限检查、转移所有权。

## 适用场景

- 给飞书文档添加/更新/删除协作者权限
- 查看文档协作者列表
- 管理文档公开权限（外部访问、链接分享）
- 设置/刷新/删除分享密码
- 批量添加协作者
- 检查用户对文档的权限
- 转移文档所有权

## 前置条件

### 安装与认证

- **feishu-cli**：如尚未安装，请前往 [riba2534/feishu-cli](https://github.com/riba2534/feishu-cli) 获取安装方式
- **认证**：使用 **App Token（应用身份）**，需配置 App ID 和 App Secret（环境变量或 `~/.feishu-cli/config.yaml`）。无需 `auth login`（User Token 不适用于权限管理 API）。

### 所需权限 scope

| scope | 说明 |
|-------|------|
| `docs:permission.member:create` | 添加协作者 |
| `docs:permission.member:retrieve` | 查看协作者列表 |
| `docs:permission.member:update` | 更新协作者权限 |
| `docs:permission.member:delete` | 删除协作者 |
| `docs:permission.member:transfer` | 转移所有权 |
| `docs:permission.member:auth` | 检查用户权限 |
| `docs:permission.setting:read` / `docs:permission.setting:readonly` | 读取公开权限设置 |
| `docs:permission.setting:write_only` | 更新公开权限、密码管理 |

## 快速开始

```bash
# 给用户添加编辑权限（最常用操作）
feishu-cli perm add <TOKEN> --doc-type docx --member-type email --member-id user@example.com --perm edit --notification

# 查看文档协作者列表
feishu-cli perm list <TOKEN> --doc-type docx

# 删除指定协作者
feishu-cli perm delete <TOKEN> --doc-type docx --member-type email --member-id user@example.com
```

## 命令总览

### 一、基础操作

| 命令 | 说明 |
|------|------|
| `perm add` | 添加协作者权限 |
| `perm update` | 更新已有协作者的权限级别 |
| `perm list` | 查看协作者列表 |
| `perm delete` | 删除协作者 |

### 二、高级操作

| 命令 | 说明 |
|------|------|
| `perm batch-add` | 从 JSON 文件批量添加协作者 |
| `perm transfer-owner` | 转移文档所有权 |
| `perm auth` | 检查当前用户对文档的权限 |

### 三、公开设置

| 命令 | 说明 |
|------|------|
| `perm public-get` | 查看文档公开权限设置 |
| `perm public-update` | 更新公开权限（外部访问、链接分享等） |
| `perm password create` | 创建分享密码 |
| `perm password update` | 刷新分享密码 |
| `perm password delete` | 删除分享密码 |

## 命令详情

### 添加权限

```bash
feishu-cli perm add <TOKEN> \
  --doc-type <DOC_TYPE> \
  --member-type <MEMBER_TYPE> \
  --member-id <MEMBER_ID> \
  --perm <PERM> \
  [--notification]
```

### 更新权限

```bash
feishu-cli perm update <TOKEN> \
  --doc-type <DOC_TYPE> \
  --member-type <MEMBER_TYPE> \
  --member-id <MEMBER_ID> \
  --perm <PERM>
```

### 查看协作者列表

```bash
feishu-cli perm list <TOKEN> --doc-type <DOC_TYPE>
```

### 删除协作者

```bash
feishu-cli perm delete <TOKEN> \
  --doc-type <DOC_TYPE> \
  --member-type <MEMBER_TYPE> \
  --member-id <MEMBER_ID>
```

### 批量添加协作者

```bash
feishu-cli perm batch-add <TOKEN> \
  --doc-type <DOC_TYPE> \
  --members-file <members.json> \
  [--notification]
```

`--doc-type` 默认 `docx`，非 docx 文档（sheet / bitable / file / wiki / slides 等）必须显式指定，否则会按 docx 处理导致 API 报错。

members.json 格式（顶层为 JSON 数组）：
```json
[
  {"member_type": "email", "member_id": "user1@example.com", "perm": "edit"},
  {"member_type": "email", "member_id": "user2@example.com", "perm": "view"}
]
```

### 转移所有权

```bash
feishu-cli perm transfer-owner <TOKEN> \
  --member-type <MEMBER_TYPE> \
  --member-id <MEMBER_ID> \
  [--notification] \
  [--remove-old-owner] \
  [--stay-pu