常见问题¶

为什么没有账号收藏功能？¶

KToolBox v1 实现 Pawchive 中无需登录的 14 个操作。OpenAPI 中受 cookieAuth 保护的 5 个操作明确排除，因此 API 客户端不会接受或发送账号会话。

作品标记是独立的公开操作，已经实现。请有意识地调用：成功标记会改变服务端状态，重复标记可能抛出 PawchiveConflictError。

API 调用失败时怎么办？¶

CLI 会报告类型化的 Pawchive 错误，不会返回只解析了一部分的响应。常见类型包括传输、HTTP、认证、未找到、冲突和响应校验错误。

检查 URL 或 service、作者 ID、作品 ID 是否正确。
网络较慢时增大 KTOOLBOX_API__TIMEOUT。
对临时传输错误、429 或 5xx，调整 KTOOLBOX_API__RETRY_TIMES 与 KTOOLBOX_API__RETRY_INTERVAL。
不要向 API 配置添加账号 Cookie；API 请求不会使用它。

重定向、普通 4xx、冲突和非法响应数据不会重试。

文件下载为什么返回 403？¶

若文件主机要求特定资源携带会话，可设置只属于下载器的密钥：

KTOOLBOX_DOWNLOADER__SESSION_KEY=xxxxx

该 Cookie 仅用于文件下载请求，不会发送到 Pawchive API。请将 .env 和 prod.env 视作可能包含密钥的本地文件，不要提交。

如何继续中断的下载？¶

重新运行相同命令即可。KToolBox 会跳过完整的目标文件。如果存在带 downloader.temp_suffix 的未完成文件，且服务器支持范围请求，下载器会请求剩余字节并校验合并后的大小。

如何禁用封面或附件？¶

# 只下载附件。
KTOOLBOX_JOB__DOWNLOAD_FILE=False
KTOOLBOX_JOB__DOWNLOAD_ATTACHMENTS=True

# 只下载封面。
#KTOOLBOX_JOB__DOWNLOAD_FILE=True
#KTOOLBOX_JOB__DOWNLOAD_ATTACHMENTS=False

download_file 指作品主文件，通常为封面。两个选项默认均为 True。

能否把附件直接放进作品目录？¶

可以。在“命名格式 → 目录结构”中，将附件目录设为 . 或 ./。对应的项目配置为：

[naming.post_structure]
attachments = "."

请确保附件文件名不与主文件（封面）、post.json 或其他元数据重名。转换旧 KTOOLBOX_JOB__POST_STRUCTURE__ATTACHMENTS=./ 配置下载的文件时，使用“旧下载目录转换 → 粘贴配置”，按命名指南预览后转换。其他内部路径仍需使用安全且非空的相对名称。

如何避免文件名过长？¶

在项目 [naming] 中使用顺序命名或格式精度限制：

[naming]
sequential_filename = true
post_dirname_format = "[{published}]{post_id}_{title:.30}"
filename_format = "{title:.30}_{}"

转换已有下载前请先阅读命名格式指南。

如何配置代理？¶

HTTPX 会读取标准代理环境变量：

export HTTPS_PROXY=http://127.0.0.1:7897
export HTTP_PROXY=http://127.0.0.1:7897
export ALL_PROXY=socks5://127.0.0.1:7897

PowerShell：

$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:HTTPS_PROXY="http://127.0.0.1:7897"

为什么配置编辑器无法打开？¶

安装可选的终端 UI 依赖：

pip install "ktoolbox[urwid]"
# 或
pipx install "ktoolbox[urwid]" --force

如何定期同步很多作者？¶

将每位作者加入项目清单，可选设置短别名，然后执行无目标 sync：

ktoolbox creator add fanbox:123 --alias studio-a
ktoolbox creator add patreon:456 --alias studio-b
ktoolbox sync

使用 creator disable 可保留作者但不加入无目标同步；仍可显式同步已禁用别名。作者准备与文件传输使用不同并发限制，因此大型作者不会长期占据全部已就绪下载。

如何为不同作者排除不同主题？¶

在 ktoolbox.toml 中添加不同 [[blockers]]。所有作者共享的规则使用 scope.mode = "global"；特定作者规则使用 scope.mode = "creators" 并填写精确 service:id。忽略规则按文件顺序求值，第一个命中后停止。

长时间同步前先校验正则与作用域：

ktoolbox config validate

为什么重定向日志中的进度显示不同？¶

Rich 实时进度仅用于交互终端。界面会显示每个活动文件的速度与预计剩余时间，并在 Files 总体行显示所有活动下载的速度总和。管道、CI、NO_COLOR 与 --plain 使用稳定逐行输出，日志不会破坏 ANSI 实时区域。需要无颜色交互布局时使用 --no-color，完全隐藏进度与普通日志时使用 --quiet。

为什么 WebUI 拒绝启动？¶

请安装 ktoolbox[webui] 并传入项目目录。账户配置可留空，此时终端会输出本次运行使用的 admin 用户名和随机密码。显式配置的密码哈希仍必须是有效的 Argon2 值。若缺少 ktoolbox.toml，程序会在终端警告后自动创建；同一项目已经运行另一个 WebUI 时，项目锁仍会拒绝启动。

可以安全地把 WebUI 暴露到网络吗？¶

默认服务是明文 HTTP，因此只应在可信局域网使用 0.0.0.0。本机使用请绑定 127.0.0.1，远程访问则应置于 HTTPS 反向代理之后。认证、CSRF、严格 Cookie、速率限制和安全响应头能保护应用本身，但无法加密 HTTP 网络链路。

WebUI 任务在服务重启后会怎样？¶

排队任务仍保持排队。原本正在运行的任务会标记为 interrupted，不会静默自动重启，因为配置与远端状态可能已经变化；请检查后手动恢复。已完成文件与可续传临时文件会保留。

删除 WebUI 任务会误删无关文件吗？¶

普通删除只移除任务历史。删除输出必须先预览并再次确认，随后会核对任务的输出归属记录和文件元数据；既存、已修改、共享、非普通文件和符号链接路径都会跳过。

如何确认同步失败的真正原因？¶

打开失败任务并查看“任务失败原因”。KToolBox 会指出对应作者或文件、失败阶段、重试是否可能有效以及建议操作。若提示响应格式不兼容，通常表示 Pawchive 改变了某个字段的数据形状；请先更新 KToolBox，再提交面板中显示的安全操作名与字段路径。网络、超时和限流错误可稍后重试。诊断报告经过脱敏，不会包含上游响应正文、作品标题、Cookie 或完整下载 URL。

uvloop 或 winloop 是必需的吗？¶

不是。它们只是可选的事件循环优化。Linux/macOS 使用 ktoolbox[uvloop]，Windows 使用 ktoolbox[winloop]。两者都未安装时，KToolBox 会继续使用 Python 标准 asyncio 循环。

为什么杀毒软件可能标记打包后的可执行文件？¶

部分启发式扫描会标记 PyInstaller 包或下载管理器。发布包通过仓库中公开的自动化流程构建；也可以改用 pipx 安装，或审查源码后自行构建。