larksync 0.1.0__tar.gz

larksync-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+.venv/
+.venv-gtk/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+
+# 前端（gui/frontend/.gitignore 另外忽略 node_modules/ 和 dist/）
+gui/frontend/node_modules/
+gui/frontend/dist/
+
+# 凭证：larksync 默认存在用户配置目录，这里防止误放进仓库
+token.json
+.feishu_token.json
+
+# 测试时拉取到项目根目录的表格
+/*.csv
+/*.xlsx
+
+# 编辑器
+*~
+\#*\#
+.#*
+.idea/
+.vscode/
+.DS_Store

larksync-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 libcyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

larksync-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: larksync
+Version: 0.1.0
+Summary: 飞书电子表格 / 多维表格的拉取与按主键更新（Feishu / Lark sheets & bitable sync）
+Project-URL: Homepage, https://github.com/libcyz/larksync
+Project-URL: Documentation, https://github.com/libcyz/larksync/blob/main/docs/python.md
+Project-URL: Issues, https://github.com/libcyz/larksync/issues
+Author-email: libcyz <2840424020@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bitable,csv,feishu,lark,spreadsheet,sync,xlsx
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: platformdirs>=4
+Provides-Extra: gui
+Requires-Dist: pywebview>=6.2.1; extra == 'gui'
+Description-Content-Type: text/markdown
+
+# larksync
+
+这是一个用来同步飞书表格的项目，大多数项目的非技术人员在使用飞书在线表格进行管理的时候经常会出现大量数据需要人工核对，可能又需要去重，于是添加新的表变的非常麻烦，而整理好的csv中如果出现重复的数据，直接复制的话就gameover，当然会有用豆包更新表格的声音，如果你用豆包更新表格，那我不要和你说话。
+
+对于技术人员来讲，在pipeline搭建好之后发现跑脚本前需要拉取在线表格更新后的信息，需要折返到对应表格，下载，另存为csv，大概率还会出现XXXX表(1),XXXX表(2),然后就需要在修改脚本路径和重命名表格这两个愚蠢选项中选择一项，诸如此类，larksync应运而生。
+
+## 更新规则
+
+GUI 和 Python 代码使用同一套规则。
+
+- 补空的格子默认写入。
+- 不一致的格子默认不写入。人工确认后，才可以写入。
+- 新增的行由调用方决定是否写入。GUI 默认不勾选新增的行。
+- 本地文件中为空的格子不参与比较。larksync 不清空在线表的值。
+- larksync 不删除在线表的行。撤销时，只删除本次写入新增的行。
+- 写入前，larksync 重新读取涉及的行。预览后有人修改过这些格子时，写入整体中止。
+
+## 前提
+
+1. 创建一个飞书自建应用。
+2. 为应用开通以下权限：
+```json
+{
+  "scopes": {
+    "tenant": [
+      "bitable:app",
+      "sheets:spreadsheet",
+      "wiki:wiki:readonly"
+    ],
+    "user": [
+      "bitable:app",
+      "sheets:spreadsheet",
+      "wiki:wiki:readonly"
+    ]
+  }
+}
+```
+3. 在应用的重定向 URL 中添加 `http://localhost:8888/callback`。
+4. 发布应用版本。
+
+说明：权限修改并发布后，生效可以有几分钟的延迟;每个人必须使用自己的飞书应用,不同的人对在线表的权限不同。
+
+## GUI 使用
+
+### 首次配置
+
+1. 启动 larksync。结果：弹出「飞书应用与登录」窗口。
+2. 填写「App ID」和「App Secret」。
+3. 单击「保存并登录」。结果：浏览器打开飞书授权页。
+4. 在 180 秒内单击「授权」。结果：窗口右上角显示你的飞书用户名。
+
+登录状态保存在本机。下次启动时，不需要再登录。
+
+## 术语
+
+- **主键**：用来匹配行的字段。本地文件的行和在线表的行，主键值相同时视为同一行。
+- **联合主键**：多个字段一起作为主键。一个字段的值有重复时，使用联合主键。
+- **补空**：在线表的格子为空，本地文件有值。
+- **未匹配**：在线表有这一行，本地文件没有这一行。
+
+### 用本地文件更新在线表
+
+1. 在左侧列表中选择一张在线表。结果：顶部显示表头的前 8 个字段。
+2. 把本地文件拖入虚线框。也可以单击虚线框，选择本地文件。
+3. 在「列对应」中检查每一个 CSV 列对应的字段。同名的列自动对应。
+4. 勾选「主键」。一个字段的值有重复时，勾选多个字段。
+5. 勾选「更新」中要写入的列。表头的「更新」复选框可以全选。
+6. 单击「生成预览」。结果：显示「补空」「不一致」「新增」「未匹配」4 个页签。
+7. 在「不一致」中核对每一个格子。只勾选确认要覆盖的格子。
+8. 在「新增」中勾选确认要增加的行。
+9. 单击「写入飞书」。结果：弹出确认框。
+10. 单击「写入」。结果：显示「已写入飞书」。
+
+列对应和主键保存在表格配置中。下次拖入同样格式的本地文件时，自动恢复。
+
+
+### 其他操作
+
+- 单击「刷新」：重新读取表头。在线表增加字段后，必须刷新。
+- 单击「移除」：删除本机的表格配置。飞书上的在线表和写入记录不变。
+- 单击右上角的用户名：修改 App ID 或 App Secret，或退出登录。
+
+开发者调用详见 [docs/python.md](https://github.com/libcyz/larksync/blob/main/docs/python.md)。

larksync-0.1.0/README.md

@@ -0,0 +1,83 @@
+# larksync
+
+这是一个用来同步飞书表格的项目，大多数项目的非技术人员在使用飞书在线表格进行管理的时候经常会出现大量数据需要人工核对，可能又需要去重，于是添加新的表变的非常麻烦，而整理好的csv中如果出现重复的数据，直接复制的话就gameover，当然会有用豆包更新表格的声音，如果你用豆包更新表格，那我不要和你说话。
+
+对于技术人员来讲，在pipeline搭建好之后发现跑脚本前需要拉取在线表格更新后的信息，需要折返到对应表格，下载，另存为csv，大概率还会出现XXXX表(1),XXXX表(2),然后就需要在修改脚本路径和重命名表格这两个愚蠢选项中选择一项，诸如此类，larksync应运而生。
+
+## 更新规则
+
+GUI 和 Python 代码使用同一套规则。
+
+- 补空的格子默认写入。
+- 不一致的格子默认不写入。人工确认后，才可以写入。
+- 新增的行由调用方决定是否写入。GUI 默认不勾选新增的行。
+- 本地文件中为空的格子不参与比较。larksync 不清空在线表的值。
+- larksync 不删除在线表的行。撤销时，只删除本次写入新增的行。
+- 写入前，larksync 重新读取涉及的行。预览后有人修改过这些格子时，写入整体中止。
+
+## 前提
+
+1. 创建一个飞书自建应用。
+2. 为应用开通以下权限：
+```json
+{
+  "scopes": {
+    "tenant": [
+      "bitable:app",
+      "sheets:spreadsheet",
+      "wiki:wiki:readonly"
+    ],
+    "user": [
+      "bitable:app",
+      "sheets:spreadsheet",
+      "wiki:wiki:readonly"
+    ]
+  }
+}
+```
+3. 在应用的重定向 URL 中添加 `http://localhost:8888/callback`。
+4. 发布应用版本。
+
+说明：权限修改并发布后，生效可以有几分钟的延迟;每个人必须使用自己的飞书应用,不同的人对在线表的权限不同。
+
+## GUI 使用
+
+### 首次配置
+
+1. 启动 larksync。结果：弹出「飞书应用与登录」窗口。
+2. 填写「App ID」和「App Secret」。
+3. 单击「保存并登录」。结果：浏览器打开飞书授权页。
+4. 在 180 秒内单击「授权」。结果：窗口右上角显示你的飞书用户名。
+
+登录状态保存在本机。下次启动时，不需要再登录。
+
+## 术语
+
+- **主键**：用来匹配行的字段。本地文件的行和在线表的行，主键值相同时视为同一行。
+- **联合主键**：多个字段一起作为主键。一个字段的值有重复时，使用联合主键。
+- **补空**：在线表的格子为空，本地文件有值。
+- **未匹配**：在线表有这一行，本地文件没有这一行。
+
+### 用本地文件更新在线表
+
+1. 在左侧列表中选择一张在线表。结果：顶部显示表头的前 8 个字段。
+2. 把本地文件拖入虚线框。也可以单击虚线框，选择本地文件。
+3. 在「列对应」中检查每一个 CSV 列对应的字段。同名的列自动对应。
+4. 勾选「主键」。一个字段的值有重复时，勾选多个字段。
+5. 勾选「更新」中要写入的列。表头的「更新」复选框可以全选。
+6. 单击「生成预览」。结果：显示「补空」「不一致」「新增」「未匹配」4 个页签。
+7. 在「不一致」中核对每一个格子。只勾选确认要覆盖的格子。
+8. 在「新增」中勾选确认要增加的行。
+9. 单击「写入飞书」。结果：弹出确认框。
+10. 单击「写入」。结果：显示「已写入飞书」。
+
+列对应和主键保存在表格配置中。下次拖入同样格式的本地文件时，自动恢复。
+
+
+### 其他操作
+
+- 单击「刷新」：重新读取表头。在线表增加字段后，必须刷新。
+- 单击「移除」：删除本机的表格配置。飞书上的在线表和写入记录不变。
+- 单击右上角的用户名：修改 App ID 或 App Secret，或退出登录。
+
+开发者调用详见 [docs/python.md](https://github.com/libcyz/larksync/blob/main/docs/python.md)。

larksync-0.1.0/docs/python.md

@@ -0,0 +1,108 @@
+# Python 调用
+
+术语和更新规则见 [README](../README.md)。
+
+## 安装
+
+```bash
+pip install larksync      # 需要 Python 3.10+
+```
+
+## 快速开始
+
+```python
+import larksync
+from larksync import Table
+
+larksync.configure("cli_xxx", "app_secret")    # 每台机器运行一次
+
+t = Table("https://xxx.feishu.cn/wiki/<token>?sheet=<id>")
+
+rows = t.pull("out.csv")         # 拉取：返回 list[dict]，同时写入 CSV
+
+plan = t.diff("new.csv", key="ID")
+print(plan)                      # 补空 12 格 / 新增 3 行 / 不一致 2 格（未写入）/ 未匹配 5 行
+record_id = plan.apply()         # 写入
+
+t.undo(record_id)                # 撤销这次写入
+```
+
+首次运行时打开浏览器授权。之后 larksync 自动续期。
+
+## API
+
+| 调用 | 说明 |
+|---|---|
+| `Table(url, auth="user", tab=None)` | 打开在线表。支持 `/wiki/`、`/sheets/`、`/base/` 链接 |
+| `t.pull(path=None)` | 拉取全部行，返回 `list[dict]`。传 `path` 时同时写入 CSV |
+| `t.columns()` | 表头 |
+| `t.tabs()` | 文档中的全部在线表：`[(id, 标题)]` |
+| `t.title` | 文档标题 |
+| `t.diff(source, key, columns=None)` | 和本地数据比较，返回 `Plan` |
+| `plan.apply()` | 写入，返回写入记录 id |
+| `t.undo(record_id)` | 撤销一次写入 |
+| `t.init(source)` | 用本地文件初始化空的在线表 |
+
+- `tab`：指定在线表 id。不写时，用链接中的 `?sheet=` / `?table=`；链接也没有时，用第一张在线表。
+- `source`：CSV 或 xlsx 的路径、文件内容 `bytes`，或 `list[dict]`。CSV 可以是 UTF-8 或 GBK。
+- `key`：主键。联合主键写成列表：`key=["歌曲名", "歌手名"]`。
+- `columns`：要更新的字段。不写时，更新本地数据中全部非主键列。
+
+### Plan
+
+| 属性 | 内容 | `apply()` 时 |
+|---|---|---|
+| `plan.changed` | 补空的格子 | 写入 |
+| `plan.conflicts` | 不一致的格子 | 不写入 |
+| `plan.added` | 新增的行 | 写入 |
+| `plan.unmatched` | 未匹配的行数 | — |
+
+`apply()` 前可以修改 `plan`：
+
+```python
+plan.changed += plan.conflicts   # 确认后，覆盖不一致的格子
+plan.added = []                  # 不新增行
+plan.apply()
+```
+
+## 在服务器上运行
+
+服务器没有浏览器。用 tenant 身份，凭证放在环境变量中：
+
+```bash
+export LARKSYNC_APP_ID=cli_xxx
+export LARKSYNC_APP_SECRET=xxx
+```
+
+```python
+Table(url, auth="tenant").pull("out.csv")
+```
+
+- tenant 身份必须把应用加为在线表的协作者。
+- 要用 user 身份：在有浏览器的机器上登录一次，把配置目录中的 `config.json` 和 `token.json` 复制到服务器。
+
+## 示例：pipeline 中批量拉取
+
+```python
+from larksync import LarkError, Table
+
+URLS = {
+    "人员登记": "https://xxx.feishu.cn/wiki/<token>?sheet=<id>",
+    "组别登记": "https://xxx.feishu.cn/wiki/<token>?sheet=<id>",
+}
+
+for name, url in URLS.items():
+    try:
+        rows = Table(url, auth="tenant").pull(f"csv/{name}.csv")
+        print(f"{name}：{len(rows)} 行")
+    except LarkError as e:       # larksync 只抛出这一种异常，错误信息包含处理方法
+        print(f"{name} 拉取失败：{e}")
+```
+
+## 配置目录
+
+- Linux：`~/.config/larksync/`
+- macOS：`~/Library/Application Support/larksync/`
+- Windows：`%LOCALAPPDATA%\larksync\`
+
+目录中有 `config.json`（应用凭证）、`token.json`（登录状态）和 `history/`（写入记录）。`config.json` 和 `token.json` 不得提交到 git 仓库。

larksync-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "larksync"
+version = "0.1.0"
+description = "飞书电子表格 / 多维表格的拉取与按主键更新（Feishu / Lark sheets & bitable sync）"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "libcyz", email = "2840424020@qq.com" }]
+requires-python = ">=3.10"
+keywords = ["feishu", "lark", "bitable", "spreadsheet", "csv", "xlsx", "sync"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Natural Language :: Chinese (Simplified)",
+    "Topic :: Office/Business",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "httpx>=0.27",
+    "openpyxl>=3.1.5",
+    "platformdirs>=4",
+]
+
+[project.urls]
+Homepage = "https://github.com/libcyz/larksync"
+Documentation = "https://github.com/libcyz/larksync/blob/main/docs/python.md"
+Issues = "https://github.com/libcyz/larksync/issues"
+
+[project.optional-dependencies]
+gui = [
+    "pywebview>=6.2.1",
+]
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+# 源码包只放库本身、测试和文档；GUI 另外打安装包，不进 PyPI
+[tool.hatch.build.targets.sdist]
+include = ["src/larksync", "tests", "docs", "README.md", "LICENSE"]

larksync-0.1.0/src/larksync/__init__.py

@@ -0,0 +1,6 @@
+"""larksync：飞书电子表格 / 多维表格的拉取与按主键更新。"""
+from .auth import configure
+from .http import LarkError
+from .table import Table
+
+__all__ = ["Table", "LarkError", "configure"]

larksync-0.1.0/src/larksync/auth.py

@@ -0,0 +1,179 @@
+"""本机飞书应用配置与登录。
+
+每人用自己的飞书应用（表格权限因人而异），configure() 一次即可。
+user 身份（默认）首次登录打开浏览器，之后缓存 token、自动续期；tenant 身份无需登录。
+"""
+import json
+import os
+import sys
+import threading
+import time
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import platformdirs
+
+from .http import BASE, LarkError, call
+
+CONFIG_DIR = Path(platformdirs.user_config_dir("larksync", appauthor=False))
+CONFIG_FILE = CONFIG_DIR / "config.json"
+TOKEN_FILE = CONFIG_DIR / "token.json"
+
+SCOPES = "wiki:wiki:readonly sheets:spreadsheet bitable:app"
+_EXPIRY_MARGIN_S = 300   # 提前 5 分钟判过期，免得请求发出的瞬间失效
+_LOGIN_TIMEOUT_S = 180
+
+
+def configure(app_id, app_secret, port=8888):
+    """保存本机的飞书应用。port 要和应用后台配置的重定向地址 http://localhost:<port>/callback 一致。"""
+    write_json(CONFIG_FILE, {"app_id": app_id.strip(), "app_secret": app_secret.strip(),
+                              "port": int(port)})
+
+
+def load_config():
+    cfg = read_json(CONFIG_FILE)
+    app_id = os.environ.get("LARKSYNC_APP_ID") or cfg.get("app_id")
+    app_secret = os.environ.get("LARKSYNC_APP_SECRET") or cfg.get("app_secret")
+    if not app_id or not app_secret:
+        raise LarkError("还没配置飞书应用：先运行 larksync.configure(app_id, app_secret)，"
+                        "或设置环境变量 LARKSYNC_APP_ID / LARKSYNC_APP_SECRET")
+    return app_id, app_secret, int(cfg.get("port") or 8888)
+
+
+class Auth:
+    def __init__(self, method="user"):
+        if method not in ("user", "tenant"):
+            raise LarkError(f'auth 只能是 "user" 或 "tenant"，收到 {method!r}')
+        self.method = method
+        self.app_id, self.app_secret, self.port = load_config()
+
+    def token(self):
+        c = self._cached()
+        if c and c["expires_at"] > time.time():
+            return c["access_token"]
+        if self.method == "tenant":
+            body = call("POST", "/auth/v3/tenant_access_token/internal",
+                        json={"app_id": self.app_id, "app_secret": self.app_secret})
+            return self._save({"access_token": body["tenant_access_token"],
+                               "expires_in": body.get("expire")})
+        if c and (t := self._refresh(c.get("refresh_token"))):
+            return t
+        return self._login()
+
+    def account(self):
+        """已登录的用户名（只看本地缓存，不联网）；没登录返回 None。"""
+        c = self._cached()
+        if not c or (c["expires_at"] <= time.time() and not c.get("refresh_token")):
+            return None
+        return c.get("name") or "飞书用户"
+
+    def logout(self):
+        d = read_json(TOKEN_FILE)
+        if d.pop(self.method, None) is not None:
+            write_json(TOKEN_FILE, d)
+
+    # -- 缓存：按 app_id 隔离，换应用自动作废 --
+
+    def _cached(self):
+        d = read_json(TOKEN_FILE)
+        block = d.get(self.method) if d.get("app_id") == self.app_id else None
+        if isinstance(block, dict) and block.get("access_token"):
+            return block
+        return None
+
+    def _save(self, data):
+        token = data.get("access_token")
+        if not token:
+            raise LarkError(f"飞书没有返回 access_token：{data}")
+        d = read_json(TOKEN_FILE)
+        if d.get("app_id") != self.app_id:
+            d = {"app_id": self.app_id}
+        d[self.method] = {
+            "access_token": token,
+            "refresh_token": data.get("refresh_token", ""),
+            "expires_at": time.time() + float(data.get("expires_in") or 0) - _EXPIRY_MARGIN_S,
+            "name": data.get("name") or (d.get(self.method) or {}).get("name", ""),
+        }
+        try:
+            write_json(TOKEN_FILE, d)
+        except OSError:
+            pass   # 缓存写不下去不该让整个流程失败
+        return token
+
+    # -- user 身份：续期 -> 浏览器登录 --
+
+    def _app_token(self):
+        body = call("POST", "/auth/v3/app_access_token/internal",
+                    json={"app_id": self.app_id, "app_secret": self.app_secret})
+        return body["app_access_token"]
+
+    def _refresh(self, refresh_token):
+        if not refresh_token:
+            return None
+        try:
+            body = call("POST", "/authen/v1/refresh_access_token", token=self._app_token(),
+                        json={"grant_type": "refresh_token", "refresh_token": refresh_token})
+        except LarkError:
+            # refresh_token 每次续期都会轮换：可能是别的进程刚续过，再看一眼缓存
+            c = self._cached()
+            if c and c["expires_at"] > time.time():
+                return c["access_token"]
+            return None
+        return self._save(body.get("data") or {})
+
+    def _login(self):
+        got = {}
+        done = threading.Event()
+
+        class Callback(BaseHTTPRequestHandler):
+            def do_GET(self):
+                got["code"] = (parse_qs(urlparse(self.path).query).get("code") or [None])[0]
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write("<h3>飞书授权完成，可以关闭这个页面了。</h3>".encode())
+                done.set()
+
+            def log_message(self, *a):
+                pass
+
+        try:
+            server = HTTPServer(("localhost", self.port), Callback)
+        except OSError as e:
+            raise LarkError(f"本机端口 {self.port} 被占用：换个端口重新 configure，"
+                            f"并同步修改应用后台的重定向地址") from e
+        threading.Thread(target=server.serve_forever, daemon=True).start()
+        url = f"{BASE}/authen/v1/index?" + urlencode({
+            "app_id": self.app_id, "scope": SCOPES,
+            "redirect_uri": f"http://localhost:{self.port}/callback"})
+        print(f"请在浏览器中登录飞书并授权（没有自动打开就手动访问）：\n  {url}",
+              file=sys.stderr, flush=True)
+        webbrowser.open(url)
+        try:
+            if not done.wait(_LOGIN_TIMEOUT_S) or not got.get("code"):
+                raise LarkError(f"{_LOGIN_TIMEOUT_S} 秒内没有完成飞书授权。服务器上请改用 "
+                                f'auth="tenant"，或拷贝本机的 {TOKEN_FILE.name}')
+        finally:
+            server.shutdown()
+            server.server_close()
+        body = call("POST", "/authen/v1/access_token", token=self._app_token(),
+                    json={"grant_type": "authorization_code", "code": got["code"]})
+        return self._save(body.get("data") or {})
+
+
+def read_json(path):
+    try:
+        d = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return d if isinstance(d, dict) else {}
+
+
+def write_json(path, data):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, path)   # 原子替换，并发写入不会留下半个文件