| name | baklib-data-import |
| description | 指导使用 Baklib 开源导入工具（路径清单 → Excel → Open API）将本机、NAS 或挂载盘上的文件按目录层级迁入 Baklib 资源库（DAM），并可选择同步创建 CMS 站点资源页。在用户提到批量导入、本地文件进 Baklib、DAM 迁移、importer、 Excel 导入、路径清单预处理时使用。 |
Baklib 数据导入（本地磁盘 → Baklib）
官方工具仓库：https://github.com/baklib-tools/importer
核心流程：生成 UTF-8 路径清单（每行一个绝对路径）→ 离线预处理生成 Excel → 在表中可选填写「打标签」「新目录」→ 配置 Open API → 执行导入脚本。
前置条件
- Python 3.8+（建议 3.10+）
- 克隆或下载 importer 仓库，在仓库根目录安装依赖：
pip install -r requirements.txt
- Baklib Open API 的
access_key、secret_key、目标 site_id 及正确的 api.base_url（见控制台 / 文档）
四步操作（仓库根目录下执行）
1. 路径清单
在 macOS / Linux 上可用 find 导出文件列表（详见仓库 docs/02-file-list-mac-linux.md）：
find /你的根目录 -type f > file_list.txt
清单需为 UTF-8，每行一个绝对路径。
2. 预处理 → Excel
python3 preprocessing/extract-file-paths.py ./file_list.txt --split 10000 --format excel
预处理不访问网络。--split 可按行数拆成多个表；输出目录中的 .xlsx 供下一步编辑。
长时间导入期间的增量文件：若从开始清单到导入完成相隔很久，客户可能在原磁盘继续写入新文件。导入结束后可再扫一遍磁盘，用清单差集只挑出新增路径：
python3 preprocessing/compare_file_lists.py \
--baseline ./file_list_at_import_start.txt \
--current ./file_list_rescan.txt \
-o ./new_files_only.txt
得到 new_files_only.txt 后，可再执行本技能第 2 步 extract-file-paths.py 生成 Excel 并走导入。详见 importer 仓库 preprocessing/README.md。
3. 编辑 Excel（可选但常用）
按 docs/03-excel-guide.md 理解各列；可批量填写 打标签、新目录，覆盖或补充仅由路径推导的结果。
4. 配置并导入
将 config.example.json 复制为仓库根目录的 config.json，填写密钥与导入段参数（示例字段名以仓库内文件为准）：
site_id、api.base_url、api.access_key、api.secret_keyimport.path_prefix：去掉盘符/共享根等前缀后，用于对齐 Baklib 中 DAM 目录层级；过深时受 import.max_depth 等限制import.skip_directories：可选，跳过指定相对路径子树- NAS / 路径映射：Excel 中为服务器路径、本机从挂载点读文件时，使用仓库文档中的
**excel_path_prefix + local_path_root**（见官方 README 与 docs/）
仅导入资源库（DAM）：
python3 baklib_import/import_files_to_dam.py --excel ./your.xlsx --config config.json
DAM + CMS 站点资源页（Wiki 类站点请仅用 DAM 脚本）：
python3 baklib_import/import_files_to_site.py --excel ./your.xlsx --config config.json
首次运行强烈建议：--dry-run 和/或 --max-rows 10 试跑；更多参数见 docs/05-import-runbook.md。
安全与仓库卫生
- 不要将真实
config.json、含内部路径的 Excel 或敏感日志提交到 Git。
- 官方仓库已
.gitignore 本地 config.json；用户自己的副本需自行保管。
文档索引（importer 仓库内）
| 路径 | 用途 |
|---|
docs/00-index.md | 总入口与阅读顺序 |
docs/01-workflow-sop.md | 端到端 SOP |
docs/04-import-quickstart.md | API 导入快速开始 |
docs/05-import-runbook.md | 命令行参数与行为 |
代理协助用户时：若涉及具体列名、Windows 排障或高级参数，应引导阅读上述文档或打开仓库中对应文件，避免臆造未在文档中出现的 API 字段。
