soia-team soia-pkm-clip-drive
clip 家族的云盘成员：把网盘 / 本地的存量资料（PDF、DOCX 等）导入 vault。区别于抓网页，它处理本地 / 云盘文件。
客户可读说明
这个技能可以做什么
把云盘/本地的存量资料（PDF/Word/表格/演示文稿/文档）批量导入 Obsidian vault。提取文本、生成资料笔记，归入资料库或文章摘抄，再交给 organize 整理。图片不能仅凭文件名当作正文，需用户明确要求并具备 OCR 后端。
| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 完成本技能覆盖的工作 | 读取用户请求、必要上下文和本技能正文流程，执行最小可靠步骤 | 客户会看到 Obsidian/vault 文件变更、终端日志、生成产物路径和最终回执。 |
| 缺少依赖、权限、配置或 key | 停止需要外部状态的动作，明确指出缺什么 | 安装命令、申请地址、配置路径或需要客户确认的问题 |
| 执行完成 | 汇总成功、跳过、失败、文件变更和验证结果 | 一段可复制进工单/日志的完成回执 |
客户如何使用
- 用自然语言说明目标，并提供必要输入：文件、URL、repo、workspace、proposal、vault 或平台账号状态。
- 能 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、original_path、source_sha256、extraction_method；然后由soia-pkm-query-vault搜索提取稿，不直接解析二进制正文。 - 大批量：目录批处理，每个文件 → 一篇笔记。
- URL 批量下载：使用
scripts/archive_pdf.py，它会校验 HTTP(S) URL、限制响应大小、检查%PDF-魔数、原子落盘并返回 SHA-256；--extract时调用pdftotext -layout生成-extracted.txt。加--deep可从 arXivabs或论文 HTML 页发现 PDF（citation_pdf_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、original_path、captured_at、topics:[]。 - 导入后必走
organize：单文件归入文章库时用rebuild_moc.py --article <path>增量同步；批量导入也应逐篇增量，不能把无门禁的全量清空当作收尾捷径。确需全量重建时，先运行--full-rebuild --dry-run并解决 unknown-topic 报告，再经明确授权执行。只要新建了 20 区文件，必须按soia-pkm-maintain-vault-health/references/index-sync-contract.md重建OB知识库地图.md，并用vault_index_verify.py验证相关 Base；附件正文提取不等于索引已更新。 - URL 论文清单的链接归档与“全文归档”分开标记：非 PDF 页面可先进入 canonical 参考索引；只有实际下载并通过魔数、哈希和（可用时）
pdfinfo校验的文件，才标记为 PDF 已归档。不要把 arXivabs页面或 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 citation_pdf_url 发现；见仓库 tests/test_archive_pdf.py。
闭环位置
★clip-drive(收) → organize（云盘资料尤其依赖整理） → distill → …。
完成后回执
交付顺序：先把文件落盘，再输出下面的回执，不得反过来；不确定的元数据（如原文档来源信息缺失）在回执里显式标注"未核实"，不编造。
回执包含：
- 做了什么 — 一句话总结完成的工作。
- 文件变更 — 列出新建 / 修改 / 移动的文件（完整路径）；未改动文件则说明"未改动文件"。
- 下一步 — 可选的后续建议（如衔接的下一个 skill）。
- 索引同步 — 若写入 20 区，列出地图
updated、文件/目录统计、Base 根路径验证；没有 Base 时明确记录未配置。