feishu-operator 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. feishu_operator-0.1.0/.gitignore +31 -0
  2. feishu_operator-0.1.0/PKG-INFO +150 -0
  3. feishu_operator-0.1.0/README.md +128 -0
  4. feishu_operator-0.1.0/pyproject.toml +52 -0
  5. feishu_operator-0.1.0/src/feishu_operator/__init__.py +17 -0
  6. feishu_operator-0.1.0/src/feishu_operator/_cli.py +791 -0
  7. feishu_operator-0.1.0/src/feishu_operator/_client.py +26 -0
  8. feishu_operator-0.1.0/src/feishu_operator/_credentials.py +82 -0
  9. feishu_operator-0.1.0/src/feishu_operator/_scopes.py +43 -0
  10. feishu_operator-0.1.0/src/feishu_operator/auth.py +143 -0
  11. feishu_operator-0.1.0/src/feishu_operator/bitable.py +320 -0
  12. feishu_operator-0.1.0/src/feishu_operator/calendar.py +217 -0
  13. feishu_operator-0.1.0/src/feishu_operator/contact.py +205 -0
  14. feishu_operator-0.1.0/src/feishu_operator/document.py +226 -0
  15. feishu_operator-0.1.0/src/feishu_operator/drive.py +207 -0
  16. feishu_operator-0.1.0/src/feishu_operator/mail.py +139 -0
  17. feishu_operator-0.1.0/src/feishu_operator/message.py +234 -0
  18. feishu_operator-0.1.0/src/feishu_operator/minutes.py +71 -0
  19. feishu_operator-0.1.0/src/feishu_operator/task.py +210 -0
feishu_operator-0.1.0/.gitignore ADDED
@@ -0,0 +1,31 @@
1
+ # Build artifacts
2
+ dist/
3
+ dist2/
4
+ dist_test/
5
+ *.egg-info/
6
+ *.egg
7
+ *.whl
8
+ *.tar.gz
9
+
10
+ # Virtual environment
11
+ .venv/
12
+ venv/
13
+ env/
14
+
15
+ # IDE
16
+ .idea/
17
+ .vscode/
18
+ *.swp
19
+ *.swo
20
+
21
+ # OS
22
+ .DS_Store
23
+ Thumbs.db
24
+
25
+ # Python
26
+ __pycache__/
27
+ *.py[cod]
28
+ *$py.class
29
+ .pytest_cache/
30
+ .coverage
31
+ htmlcov/
feishu_operator-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,150 @@
1
+ Metadata-Version: 2.4
2
+ Name: feishu-operator
3
+ Version: 0.1.0
4
+ Summary: 以个人身份操作飞书消息、文档、多维表格、通讯录的 Python 工具库
5
+ Project-URL: Homepage, https://github.com/xykong/ChatGPT
6
+ Author-email: "xy.kong" <xy.kong@gmail.com>
7
+ License: MIT
8
+ Keywords: feishu,lark,operator,sdk
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Topic :: Communications
16
+ Classifier: Topic :: Utilities
17
+ Requires-Python: >=3.10
18
+ Requires-Dist: click>=8.0.0
19
+ Requires-Dist: lark-oapi>=1.4.23
20
+ Requires-Dist: requests>=2.28.0
21
+ Description-Content-Type: text/markdown
22
+
23
+ # feishu-operator
24
+
25
+ 以 **个人身份** （`user_access_token`）操作飞书的 Python 工具库与 CLI。
26
+
27
+ 支持：消息收发、文档与 Wiki、多维表格、通讯录、云盘、日历、妙记、任务、邮箱。
28
+
29
+ ---
30
+
31
+ ## 安装
32
+
33
+ ```bash
34
+ pip install feishu-operator
35
+ # 或使用 uv
36
+ uv add feishu-operator
37
+ ```
38
+
39
+ ---
40
+
41
+ ## 快速开始
42
+
43
+ ```bash
44
+ # 首次授权（打开浏览器完成飞书 OAuth）
45
+ feishu-operator auth login
46
+
47
+ # 查看授权状态
48
+ feishu-operator auth status
49
+
50
+ # 发送私信
51
+ feishu-operator message send --to ou_xxx --text "Hello!"
52
+
53
+ # 查看收件箱
54
+ feishu-operator mail list
55
+ ```
56
+
57
+ ---
58
+
59
+ ## 环境变量
60
+
61
+ | 变量 | 说明 | 默认值 |
62
+ |---|---|---|
63
+ | `FEISHU_SERVICE_URL` | ChatGPT 服务端地址 | `https://it.kxxxl.com` |
64
+ | `FEISHU_TOKEN_DIR` | token 缓存目录 | `~/.config/feishu-operator` |
65
+ | `FEISHU_USER_TOKEN` | 直接传入 token，跳过本地缓存 | — |
66
+
67
+ > `FEISHU_APP_ID` / `FEISHU_APP_SECRET` **不在客户端配置** 。所有飞书 OAuth 凭证由服务端持有和管理，客户端零凭证。
68
+
69
+ ---
70
+
71
+ ## 认证流程
72
+
73
+ ```mermaid
74
+ sequenceDiagram
75
+ participant C as "客户端 (feishu-operator)"
76
+ participant S as "服务端 (ChatGPT)"
77
+ participant F as "飞书 OAuth"
78
+
79
+ C->>S: POST /webhook/auth/session
80
+ S-->>C: session_id + auth_url
81
+ C->>F: 打开浏览器，用户授权
82
+ F->>S: 回调 /webhook/oauth?code=xxx
83
+ S->>F: 换取 user_access_token
84
+ S-->>S: 存入 session（含 scopes）
85
+ loop "轮询"
86
+ C->>S: GET /webhook/auth/session/{id}
87
+ S-->>C: status=done, token, scopes
88
+ end
89
+ C-->>C: 缓存至 credentials.json
90
+ ```
91
+
92
+ token 缓存在本地 `~/.config/feishu-operator/credentials.json`（权限 0600）。临近过期自动刷新，无需重复授权。
93
+
94
+ ---
95
+
96
+ ## 功能一览
97
+
98
+ | 模块 | 已实现功能 | 所需权限 |
99
+ |---|---|---|
100
+ | **消息** | 发送、回复、撤回、获取单条、群聊历史 | `im:message` |
101
+ | **文档** | 创建、获取元信息、读取正文 | `docx:document` |
102
+ | **Wiki** | 列出空间、列出节点、获取节点、创建节点、移动文档 | `wiki:wiki` |
103
+ | **多维表格** | 创建应用、获取应用、列出表格、记录增删改查 | `bitable:app` |
104
+ | **通讯录** | 获取用户信息、获取部门成员 | `contact:user.base:readonly` |
105
+ | **云盘** | 列目录、上传、下载、移动、复制、删除、创建文件夹 | `drive:drive` `drive:file` |
106
+ | **日历** | 获取主日历、列出日程、创建/更新/删除日程 | `calendar:calendar:readonly` |
107
+ | **妙记** | 获取详情、获取转写文字、获取统计信息（只读） | `minutes:minutes:readonly` |
108
+ | **任务** | 列出清单、列出任务、创建/获取/更新/完成/删除任务 | `task:task:read` `task:task:write` |
109
+ | **邮箱** | 列出邮件、获取邮件、发送邮件 | `mail:user_mailbox.message:readonly` `mail:user_mailbox.message:send` |
110
+
111
+ ---
112
+
113
+ ## 已知限制
114
+
115
+ | 限制 | 原因 |
116
+ |---|---|
117
+ | 无法列出私聊（p2p）历史消息 | 飞书 API 不支持 user token 读取 p2p 消息列表 |
118
+ | 无法按姓名搜索用户 | `search/v1/user` 不支持 user token |
119
+ | 无法获取无权限的部门列表 | 需要管理员权限 |
120
+ | 妙记为只读 | 飞书不提供 user token 写入妙记的接口 |
121
+ | 日历为只读 | 应用后台仅开通 `calendar:calendar:readonly` |
122
+
123
+ ---
124
+
125
+ ## 模块结构
126
+
127
+ ```
128
+ src/feishu_operator/
129
+ ├── __init__.py # 公开 API
130
+ ├── _client.py # lark.Client 单例
131
+ ├── _credentials.py # token 本地持久化
132
+ ├── _scopes.py # 权限定义与 InsufficientScopeError
133
+ ├── _cli.py # Click CLI 入口
134
+ ├── auth.py # OAuth 2.0 + PKCE 认证 & token 管理
135
+ ├── message.py # 消息操作
136
+ ├── document.py # 文档 & Wiki 操作
137
+ ├── bitable.py # 多维表格操作
138
+ ├── contact.py # 通讯录操作
139
+ ├── drive.py # 云盘文件管理
140
+ ├── calendar.py # 日历 & 日程
141
+ ├── minutes.py # 妙记（只读）
142
+ ├── task.py # 任务 v2
143
+ └── mail.py # 个人邮箱收发
144
+ ```
145
+
146
+ ---
147
+
148
+ ## License
149
+
150
+ MIT
feishu_operator-0.1.0/README.md ADDED
@@ -0,0 +1,128 @@
1
+ # feishu-operator
2
+
3
+ 以 **个人身份** （`user_access_token`）操作飞书的 Python 工具库与 CLI。
4
+
5
+ 支持：消息收发、文档与 Wiki、多维表格、通讯录、云盘、日历、妙记、任务、邮箱。
6
+
7
+ ---
8
+
9
+ ## 安装
10
+
11
+ ```bash
12
+ pip install feishu-operator
13
+ # 或使用 uv
14
+ uv add feishu-operator
15
+ ```
16
+
17
+ ---
18
+
19
+ ## 快速开始
20
+
21
+ ```bash
22
+ # 首次授权（打开浏览器完成飞书 OAuth）
23
+ feishu-operator auth login
24
+
25
+ # 查看授权状态
26
+ feishu-operator auth status
27
+
28
+ # 发送私信
29
+ feishu-operator message send --to ou_xxx --text "Hello!"
30
+
31
+ # 查看收件箱
32
+ feishu-operator mail list
33
+ ```
34
+
35
+ ---
36
+
37
+ ## 环境变量
38
+
39
+ | 变量 | 说明 | 默认值 |
40
+ |---|---|---|
41
+ | `FEISHU_SERVICE_URL` | ChatGPT 服务端地址 | `https://it.kxxxl.com` |
42
+ | `FEISHU_TOKEN_DIR` | token 缓存目录 | `~/.config/feishu-operator` |
43
+ | `FEISHU_USER_TOKEN` | 直接传入 token，跳过本地缓存 | — |
44
+
45
+ > `FEISHU_APP_ID` / `FEISHU_APP_SECRET` **不在客户端配置** 。所有飞书 OAuth 凭证由服务端持有和管理，客户端零凭证。
46
+
47
+ ---
48
+
49
+ ## 认证流程
50
+
51
+ ```mermaid
52
+ sequenceDiagram
53
+ participant C as "客户端 (feishu-operator)"
54
+ participant S as "服务端 (ChatGPT)"
55
+ participant F as "飞书 OAuth"
56
+
57
+ C->>S: POST /webhook/auth/session
58
+ S-->>C: session_id + auth_url
59
+ C->>F: 打开浏览器，用户授权
60
+ F->>S: 回调 /webhook/oauth?code=xxx
61
+ S->>F: 换取 user_access_token
62
+ S-->>S: 存入 session（含 scopes）
63
+ loop "轮询"
64
+ C->>S: GET /webhook/auth/session/{id}
65
+ S-->>C: status=done, token, scopes
66
+ end
67
+ C-->>C: 缓存至 credentials.json
68
+ ```
69
+
70
+ token 缓存在本地 `~/.config/feishu-operator/credentials.json`（权限 0600）。临近过期自动刷新，无需重复授权。
71
+
72
+ ---
73
+
74
+ ## 功能一览
75
+
76
+ | 模块 | 已实现功能 | 所需权限 |
77
+ |---|---|---|
78
+ | **消息** | 发送、回复、撤回、获取单条、群聊历史 | `im:message` |
79
+ | **文档** | 创建、获取元信息、读取正文 | `docx:document` |
80
+ | **Wiki** | 列出空间、列出节点、获取节点、创建节点、移动文档 | `wiki:wiki` |
81
+ | **多维表格** | 创建应用、获取应用、列出表格、记录增删改查 | `bitable:app` |
82
+ | **通讯录** | 获取用户信息、获取部门成员 | `contact:user.base:readonly` |
83
+ | **云盘** | 列目录、上传、下载、移动、复制、删除、创建文件夹 | `drive:drive` `drive:file` |
84
+ | **日历** | 获取主日历、列出日程、创建/更新/删除日程 | `calendar:calendar:readonly` |
85
+ | **妙记** | 获取详情、获取转写文字、获取统计信息（只读） | `minutes:minutes:readonly` |
86
+ | **任务** | 列出清单、列出任务、创建/获取/更新/完成/删除任务 | `task:task:read` `task:task:write` |
87
+ | **邮箱** | 列出邮件、获取邮件、发送邮件 | `mail:user_mailbox.message:readonly` `mail:user_mailbox.message:send` |
88
+
89
+ ---
90
+
91
+ ## 已知限制
92
+
93
+ | 限制 | 原因 |
94
+ |---|---|
95
+ | 无法列出私聊（p2p）历史消息 | 飞书 API 不支持 user token 读取 p2p 消息列表 |
96
+ | 无法按姓名搜索用户 | `search/v1/user` 不支持 user token |
97
+ | 无法获取无权限的部门列表 | 需要管理员权限 |
98
+ | 妙记为只读 | 飞书不提供 user token 写入妙记的接口 |
99
+ | 日历为只读 | 应用后台仅开通 `calendar:calendar:readonly` |
100
+
101
+ ---
102
+
103
+ ## 模块结构
104
+
105
+ ```
106
+ src/feishu_operator/
107
+ ├── __init__.py # 公开 API
108
+ ├── _client.py # lark.Client 单例
109
+ ├── _credentials.py # token 本地持久化
110
+ ├── _scopes.py # 权限定义与 InsufficientScopeError
111
+ ├── _cli.py # Click CLI 入口
112
+ ├── auth.py # OAuth 2.0 + PKCE 认证 & token 管理
113
+ ├── message.py # 消息操作
114
+ ├── document.py # 文档 & Wiki 操作
115
+ ├── bitable.py # 多维表格操作
116
+ ├── contact.py # 通讯录操作
117
+ ├── drive.py # 云盘文件管理
118
+ ├── calendar.py # 日历 & 日程
119
+ ├── minutes.py # 妙记（只读）
120
+ ├── task.py # 任务 v2
121
+ └── mail.py # 个人邮箱收发
122
+ ```
123
+
124
+ ---
125
+
126
+ ## License
127
+
128
+ MIT
feishu_operator-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,52 @@
1
+ [project]
2
+ name = "feishu-operator"
3
+ version = "0.1.0"
4
+ description = "以个人身份操作飞书消息、文档、多维表格、通讯录的 Python 工具库"
5
+ authors = [{ name = "xy.kong", email = "xy.kong@gmail.com" }]
6
+ requires-python = ">=3.10"
7
+ readme = "README.md"
8
+ license = { text = "MIT" }
9
+ keywords = ["feishu", "lark", "operator", "sdk"]
10
+ classifiers = [
11
+ "Programming Language :: Python :: 3",
12
+ "Programming Language :: Python :: 3.10",
13
+ "Programming Language :: Python :: 3.11",
14
+ "Programming Language :: Python :: 3.12",
15
+ "License :: OSI Approved :: MIT License",
16
+ "Operating System :: OS Independent",
17
+ "Topic :: Communications",
18
+ "Topic :: Utilities",
19
+ ]
20
+ dependencies = [
21
+ "lark-oapi>=1.4.23",
22
+ "requests>=2.28.0",
23
+ "click>=8.0.0",
24
+ ]
25
+
26
+ [project.urls]
27
+ Homepage = "https://github.com/xykong/ChatGPT"
28
+
29
+ [project.scripts]
30
+ feishu-operator = "feishu_operator._cli:main"
31
+
32
+ [build-system]
33
+ requires = ["hatchling"]
34
+ build-backend = "hatchling.build"
35
+
36
+ [tool.hatch.build.targets.wheel]
37
+ packages = ["src/feishu_operator"]
38
+
39
+ [tool.hatch.build.targets.sdist]
40
+ include = [
41
+ "src/",
42
+ "README.md",
43
+ "pyproject.toml",
44
+ ]
45
+
46
+ [tool.hatch.build]
47
+ ignore-vcs = true
48
+
49
+
50
+
51
+ [tool.uv]
52
+ package = true
feishu_operator-0.1.0/src/feishu_operator/__init__.py ADDED
@@ -0,0 +1,17 @@
1
+ from . import auth, bitable, calendar, contact, document, drive, mail, message, minutes, task
2
+ from ._scopes import InsufficientScopeError, scopes_for
3
+
4
+ __all__ = [
5
+ "auth",
6
+ "message",
7
+ "document",
8
+ "bitable",
9
+ "contact",
10
+ "drive",
11
+ "calendar",
12
+ "minutes",
13
+ "task",
14
+ "mail",
15
+ "InsufficientScopeError",
16
+ "scopes_for",
17
+ ]