命名格式¶
KToolBox v1 的命名设置属于当前项目。CLI 与 WebUI 共同读取 ktoolbox.toml 中的 [naming]；命名字段不再作为全局 dotenv 配置编辑。
设置目录结构¶
在 WebUI 打开**命名格式**，可以设置：
- 作者、作品、修订、年份和月份目录模板；
- 主文件（封面）与附件文件模板；
- 作品内部的附件、修订、正文和外链名称；
- 年月分组、混合作品和附件顺序命名。
附件顺序命名默认开启，因为 Pawchive 经常返回不可读的存储文件名。只有原始文件名有意义且需要保留时才建议关闭。
模板只能使用字段旁列出的变量 Chip，例如 {creator_name}、{creator_id}、{service}、{title}、{post_id}、{revision_id}、{year} 和 {month}。路径分隔符、父目录跳转、未知变量和不安全名称会在扫描前被拒绝。
“目录结构”和“命名模板”分别提供保存按钮。保存后会立即影响未来下载；仅保存命名设置绝不会移动旧文件。
“默认下载位置”也属于项目配置，默认值为 downloads，相对路径以项目根目录解析，也可以填写项目外的主机绝对路径。创建任务时依次使用：任务显式输出目录、自动同步计划显式输出目录、项目默认下载位置。任务创建后会固化解析出的绝对路径，后续修改项目默认值不会悄然移动既有任务。
将附件保存在作品目录¶
在“目录结构”中将附件目录设为 . 或 ./，即可把附件直接保存在作品封面和元数据旁。此规则仅适用于附件目录；正文、外链文件和修订目录仍需填写名称。
使用以下 v0 配置下载的旧文件，可以通过“旧下载目录转换 → 粘贴配置”进行转换：
KTOOLBOX_JOB__POST_STRUCTURE__ATTACHMENTS=./
请同时粘贴在 v0 中修改过的其他命名设置，省略的 ENV 字段会按 v0 默认值补齐。转换目标始终是当前项目格式。确认前先查看扫描预览：转换器依据 post.json 或作者索引逐个移动附件，包括可识别修订中的附件；封面和元数据不会被当作附件搬走，无法识别的文件保留在作品目录内原有的相对位置。目标文件已存在或路径不安全时会阻止转换，不会覆盖文件。
转换旧下载位置¶
只有在以前下载的内容需要采用已保存命名格式时，才需要打开独立的“旧下载目录转换”标签页。添加一个或多个旧位置，再点击“扫描旧下载位置”。这些位置只是转换扫描来源，不是未来任务的下载目录设置。
转换器可随时使用，并提供两种来源模式。“项目历史”允许多选已保存的命名版本，适合一个下载位置中混有多代目录结构的情况。“粘贴配置”支持旧 .env 命名键、完整 ktoolbox.toml、单独的 [naming] 表或无表头命名片段。带高亮的编辑器提供样例和字段级错误定位；粘贴原文仅在内存中解析，不会写入浏览器存储、日志、事件或转换历史。两种模式都始终把当前项目命名版本作为只读目标，绝不会覆盖项目配置。
每个已保存布局也会冻结当时的发布时间策略。修复前的项目版本会标记为“直接使用 Pawchive 原值”；粘贴 v0 .env 默认采用“Kemono UTC”，粘贴 TOML 可选择 Kemono UTC、Pawchive 原值或自定义 Service 时区。例如 Fanbox 的 2025-12-21T00:35:43 会先按 Asia/Tokyo 解释，UTC 目标下得到 2025-12-20T15:35:43+00:00，因此使用 {published} 的路径会从 2025-12-21 转换到 2025-12-20。post.json 中仍保留 Pawchive 原始值。
扫描直接读取文件系统，而非仅依赖任务历史，也不会访问 Pawchive。KToolBox 通过作者目录身份、creator-indices.ktoolbox 与 post.json 识别内容，并拒绝跟随越出所选位置的符号链接。
预览会显示每位作者的新旧路径、作品数、文件数、总大小、跳过项和冲突。所有可安全转换的作者默认选中，也可逐项取消。
KToolBox 不会覆盖或合并目标目录。扫描结果过期、配置变化、相关任务处于活动状态、目标重复或文件系统变化时，都必须重新扫描。
转换与恢复¶
KToolBox 会以持久后台作业执行选中的移动。“暂停”会等待当前原子文件操作完成并保留已移动内容；“继续”前会重新校验配置、文件指纹、目标冲突和可用空间。“取消”含义不同，会按相反顺序回滚已完成移动；写入失败或进程中断也会安全回滚。已保存的命名格式继续用于未来下载。
转换进度和历史保存在 .ktoolbox/webui.sqlite3。成功后会清理临时操作日志，完成记录会保留到用户手动删除。转换会删除已空的旧来源目录，但不会删除无关文件。
首次启动迁移¶
只有检测到 .env 或 prod.env 中存在旧命名键时，才会显示迁移向导。启动阶段只检测并在终端警告，不会提前修改任何文件。登录后，向导会：
- 显示每个来源、旧值与当前项目值；
- 默认选中旧值，并允许逐项保留项目当前值；
- 预览将修改的项目配置和将删除的 dotenv 键；
- 用户确认后备份到
.ktoolbox/migrations/project-naming-v2/，再原子写入ktoolbox.toml并移除旧键； - 配置迁移成功后，再进入独立的旧目录转换步骤。
关闭或点击“忽略”只会关闭本次弹窗。只要旧键仍然存在，刷新或重新登录后仍会显示。配置迁移与目录转换彼此独立：配置迁移成功后，先核对一个或多个旧位置，再显式点击“扫描旧下载位置”；仅打开转换工具不会自动扫描或移动文件。
CLI 同样使用项目命名设置。旧项目尚未完成迁移时，请启动该项目的 WebUI 并确认带备份的原子迁移。仅存在于进程环境中的旧值无法由 KToolBox 删除；项目命名会忽略这些值，并持续警告用户从启动环境中移除。