soia-pkm-clip-drive

clip 家族的云盘成员：把网盘 / 本地的存量资料（PDF、DOCX 等）导入 vault。区别于抓网页，它处理本地 / 云盘文件。

客户可读说明

这个技能可以做什么

把云盘/本地的存量资料（PDF/Word/表格/演示文稿/文档）批量导入 Obsidian vault。提取文本、生成资料笔记，归入资料库或文章摘抄，再交给 organize 整理。图片不能仅凭文件名当作正文，需用户明确要求并具备 OCR 后端。

客户如何使用

1. 用自然语言说明目标，并提供必要输入：文件、URL、repo、workspace、proposal、vault 或平台账号状态。
2. 能 dry-run 或预览的动作先给预览；涉及删除、覆盖、发送、发布、写远端状态时先征求客户确认。

依赖与安装

安装（推荐：装整个领域插件，一次装好本仓全部技能）：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-clip-drive -y

配置约定：

~/.config/soia-skills/soia-pkm-clip-drive/config.yml
SOIA_PKM_CLIP_DRIVE_CONFIG_FILE=<custom-config-path>

• 如果本技能不需要私有配置，可以不创建 config.yml。
• 如果需要 API key、cookie、session、provider home 或本机路径，只能放进私有 config.yml、进程环境或 provider 自己的登录态里，不能写进仓库、vault 正文或日志。
• 第三方 skill 只能声明依赖和安装方式，不直接修改第三方 skill 文件。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

日志与完成回执

捕获只是五段入库合同的 captured 阶段；单文件默认继续交给 soia-pkm-manage-vault-lifecycle 完成 organized → MOC/导航 → map → Base，并在回执中逐项给出 pass 或 not_applicable。合同详见生命周期技能的 references/knowledge-intake-five-stage-contract.md。

每次执行都要让客户看见过程和结果。最低回执格式：

完成：<一句话说明本次完成了什么>。

日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的检查、命令或人工核对点>

问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>

处理

• 输入：文件路径 / 目录（PDF、DOC/DOCX、PPT/PPTX、XLS/XLSX、TXT、Markdown；图片需显式 OCR）
• 提取：PDF 用 pypdf/pdfplumber 或等价工具，DOCX 用 python-docx 或等价工具，Office 旧格式先转换；原文件留到 _附件/。图片 OCR 结果必须标记 ocr、工具和人工核对状态。
• 输出给查询技能：提取稿保留 source、originalpath、sourcesha256、extraction_method；然后由 soia-pkm-query-vault 搜索提取稿，不直接解析二进制正文。
• 大批量：目录批处理，每个文件 → 一篇笔记。
• URL 批量下载：使用 scripts/archivepdf.py，它会校验 HTTP(S) URL、限制响应大小、检查 %PDF- 魔数、原子落盘并返回 SHA-256；--extract 时调用 pdftotext -layout 生成 -extracted.txt。加 --deep 可从 arXiv abs 或论文 HTML 页发现 PDF（citationpdf_url、link[rel=alternate]、PDF 锚点），但最终仍以魔数和哈希校验为准。

python3 scripts/archive_pdf.py \
  --url-file <url-file> \
  --output-dir <vault-relative-attachment-dir> \
  --text-dir <vault-relative-extracted-text-dir> \
  --deep --extract --dry-run --json

--url-file 每行一个 URL，也可用 URL<TAB>filename 指定稳定文件名；先 dry-run 检查冲突和响应，再去掉 --dry-run 写入。脚本默认拒绝覆盖，只有明确传 --force 才替换目标。失败项以逐条 status/error 返回，不把下载失败包装成完整归档。--deep 是来源无关能力：X、公众号、网页或手工论文清单都可以把 URL 交给它。

落地

• 资料 / 参考类 → <vault-resources-dir>/<主题>/；文章类 → <vault-articles-dir>/（由配置或 CLI 参数决定）。落到 20_资料库/ 时，目标语义目录必须带唯一编号，不能把新资料直接堆在根目录；不确定分类先停在 Inbox 或交生命周期技能生成 manifest。
• frontmatter：tags:[资料] 或 [文章摘抄]、source: 云盘/pdf、originalpath、capturedat、topics:[]。
• 导入后必走 organize：单文件归入文章库时用 rebuildmoc.py --article <path> 增量同步；批量导入也应逐篇增量，不能把无门禁的全量清空当作收尾捷径。确需全量重建时，先运行 --full-rebuild --dry-run 并解决 unknown-topic 报告，再经明确授权执行。只要新建了 20 区文件，必须按 soia-pkm-maintain-vault-health/references/index-sync-contract.md 重建 OB知识库地图.md，并用 vaultindex_verify.py 验证相关 Base；附件正文提取不等于索引已更新。
• URL 论文清单的链接归档与“全文归档”分开标记：非 PDF 页面可先进入 canonical 参考索引；只有实际下载并通过魔数、哈希和（可用时）pdfinfo 校验的文件，才标记为 PDF 已归档。不要把 arXiv abs 页面或 DOI 页面自动写成已经下载的 PDF。

验证

python3 -m unittest discover -s tests -p 'test_archive_pdf.py'
python3 skills/soia-pkm-clip-drive/scripts/archive_pdf.py --help

离线 fixture 与 realistic forward test 使用本地 HTTP server 模拟 PDF 响应，覆盖下载、魔数、哈希、dry-run、arXiv abs 解析和 HTML citationpdfurl 发现；见仓库 tests/testarchivepdf.py。

闭环位置

★clip-drive(收) → organize（云盘资料尤其依赖整理） → distill → …。

完成后回执

交付顺序：先把文件落盘，再输出下面的回执，不得反过来；不确定的元数据（如原文档来源信息缺失）在回执里显式标注"未核实"，不编造。

回执包含：

1. 做了什么 — 一句话总结完成的工作。
2. 文件变更 — 列出新建 / 修改 / 移动的文件（完整路径）；未改动文件则说明"未改动文件"。
3. 下一步 — 可选的后续建议（如衔接的下一个 skill）。
4. 索引同步 — 若写入 20 区，列出地图 updated、文件/目录统计、Base 根路径验证；没有 Base 时明确记录未配置。