Metadata-Version: 2.4
Name: cloudreve-tools
Version: 0.1.1
Summary: Small Cloudreve V4 upload helpers for note_server-backed sessions.
Author: luke
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31

# cloudreve-tools

`cloudreve-tools` 是给自建 Cloudreve V4 用的小工具包，重点是从
`note_server` 读取 `login_hub` 保存的 Cloudreve 登录态，然后上传本地文件。

## 安装

```bash
pip install cloudreve-tools
```

本仓库开发态安装：

```bash
python3 -m pip install -e .
```

## 凭据

不要把 token、cookie、密码写进命令或文件。工具默认从环境变量读取：

```bash
export NOTE_SERVER_TOKEN='<note_server 普通 token>'
export NOTE_SERVER_URL='https://note.luke9012.cn'
export CLOUDREVE_BASE_URL='https://cloud.luke9012.cn'
```

`NOTE_SERVER_URL` 和 `CLOUDREVE_BASE_URL` 可省略，默认就是上面两个地址。

## 上传文件

`login_hub` 在 `note_server` 里的完整 key 是：

```text
login:{platform}:{account}:session
```

CLI 支持短 key：

- `cloudreve` -> `login:cloudreve:main:session`
- `cloudreve:main` -> `login:cloudreve:main:session`

上传命令：

```bash
cloudreve-tools upload cloudreve:main /我的软件/recon_reader/1.0.0 \
  "/Users/luke/Desktop/recon_reader/recon_reader 1.0.0.apk" \
  "/Users/luke/Desktop/recon_reader/recon_reader mac 1.0.0.zip"
```

输出 JSON：

```bash
cloudreve-tools upload --json cloudreve:main /我的软件/demo ./demo.zip
```

## 发布 App Release

`release` 命令会把 release 文件上传到：

```text
/我的软件/<app>/<version>/
```

同时生成并上传：

```text
/我的软件/<app>/latest.json
```

示例：

```bash
cloudreve-tools release mptext_reader 1.0.3 \
  --build-number 4 \
  --android "/Users/luke/Desktop/mptext_reader/mptext_reader 1.0.3.apk" \
  --macos "/Users/luke/Desktop/mptext_reader/mptext_reader mac 1.0.3.zip" \
  --notes "更新说明" \
  --json
```

同名远端文件默认会覆盖，便于同版本修正包和重复发布。如果希望严格禁止覆盖，可加：

```bash
--no-overwrite
```

`latest.json` 结构：

```json
{
  "app": "mptext_reader",
  "version": "1.0.3",
  "build_number": 4,
  "published_at": "2026-06-19T00:00:00Z",
  "android": {
    "url": "https://cloud.luke9012.cn/...",
    "sha256": "...",
    "size": 12345678
  },
  "macos": {
    "url": "https://cloud.luke9012.cn/...",
    "sha256": "...",
    "size": 12345678
  },
  "notes": "更新说明"
}
```

命令最后会输出 `manifest_url`，这个地址就是客户端后续做更新检查时要读取的公开 manifest URL。release 文件和 `latest.json` 的 Cloudreve 公开 URL 来自 Cloudreve V4 的 source link 接口，域名保持 `https://cloud.luke9012.cn`。

Cloudreve source link 绑定文件 entity，不适合作为客户端长期内置的更新地址。没有稳定 manifest 入口时，命令会把 Cloudreve source link 回退为 `manifest_url`，同时在 `warnings` 中提示它不稳定；调试用的 Cloudreve 地址单独输出为 `cloudreve_manifest_url`。

如果已经有匿名可读、会被外部流程同步的稳定 manifest 入口，可显式声明：

```bash
cloudreve-tools release mptext_reader 1.0.3 \
  --build-number 4 \
  --android "/Users/luke/Desktop/mptext_reader/mptext_reader 1.0.3.apk" \
  --macos "/Users/luke/Desktop/mptext_reader/mptext_reader mac 1.0.3.zip" \
  --stable-manifest-url "https://note.luke9012.cn/public/releases/mptext_reader/latest.json" \
  --json
```

此时 `manifest_url` 会输出这个稳定入口，`cloudreve_manifest_url` 仍保留 Cloudreve 的 `latest.json` source link。

## 直链与自动更新域名

Cloudreve 直链、发布清单和 App 自动更新下载地址统一使用
`https://cloud.luke9012.cn`。不要把链接改写成 `img.luke9012.cn`。

release / direct-link 命令默认也应保留 `cloud.luke9012.cn` 作为公开下载域名。

## Python 用法

```python
from cloudreve_tools import CloudreveClient, CloudreveSession, NoteServerClient

bundle = NoteServerClient().load_session_bundle("cloudreve:main")
client = CloudreveClient(CloudreveSession.from_bundle(bundle))
result = client.upload("./demo.zip", "/我的软件/demo")
print(result.uri)
```
