1. Android 本地 PDF 掃描到底難在哪Android 獲取手機(jī)本地所有 PDF 文件本質(zhì)上是兩件事一是用 MediaStore 把散落在各目錄的 PDF 索引出來(lái)二是把這份文件清單交給 AI 工具做后續(xù)處理摘要、分類(lèi)、問(wèn)答。第一件事網(wǎng)上教程很多第二件事才是真正卡人的地方——你本地跑通了掃描結(jié)果要接大模型時(shí)發(fā)現(xiàn)每個(gè)工具都要單獨(dú)填 Key、單獨(dú)配 Base URLCline 一套、Claude Code 一套、腳本里又一套改一次配置要翻五個(gè)文件。這篇就按「掃描 PDF → 拿到路徑列表 → 用 TaoToken 統(tǒng)一 Key 接入 AI 工具」這條鏈路走一遍。適合兩類(lèi)人正在做 Android 文件管理類(lèi) App、需要把本地文檔喂給模型的開(kāi)發(fā)者以及想用 Cline、Claude Code 這類(lèi)編碼工具批量處理本地 PDF 資料的人。核心檢索詞就三個(gè)Android 本地 PDF 掃描、MediaStore 查詢(xún)、TaoToken 統(tǒng)一 Key 接入。先說(shuō)結(jié)論掃描部分用MediaStore.Files配合 MIME 過(guò)濾是最穩(wěn)的路徑Android 10 之后分區(qū)存儲(chǔ)Scoped Storage讓直接讀絕對(duì)路徑變得不可靠所以我會(huì)同時(shí)給「拿 Uri」和「拿可讀路徑」兩種寫(xiě)法。AI 接入部分TaoToken 提供的是 OpenAI 兼容的統(tǒng)一通道一個(gè) Key 可以給多個(gè)工具復(fù)用省掉到處填配置的麻煩。下面從權(quán)限開(kāi)始一步步給可復(fù)制的代碼和配置。2. TaoToken 前置統(tǒng)一 Key 與通道準(zhǔn)備在寫(xiě)掃描代碼之前先把 AI 側(cè)的通道準(zhǔn)備好這樣掃描出結(jié)果后能立刻驗(yàn)證「文件清單 → 模型調(diào)用」這條鏈路是通的。TaoToken 的定位是一個(gè)統(tǒng)一 Key/API 通道官網(wǎng)在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 這個(gè)地址不加 UTM 參數(shù)配置里直接填它。你需要做的準(zhǔn)備動(dòng)作只有三步。第一步進(jìn)控制臺(tái)創(chuàng)建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 創(chuàng)建后在密鑰管理頁(yè)復(fù)制出來(lái)形如sk-開(kāi)頭的一串。第二步確認(rèn)你要用的模型名模型對(duì)話頁(yè) https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 里能看到當(dāng)前可用的模型列表記下你打算調(diào)用的那個(gè)。第三步如果你打算長(zhǎng)期用編碼類(lèi)工具Cline、Claude Code 等批量處理 PDF建議直接看 Coding Plan地址 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它比按量計(jì)費(fèi)更適合高頻調(diào)用場(chǎng)景。注意API Key 只存在本地配置文件或環(huán)境變量里不要硬編碼進(jìn) Android 工程提交到 Git。下面所有配置示例里的sk-xxxx都請(qǐng)?zhí)鎿Q成你自己的 Key。這里有個(gè)容易混淆的點(diǎn)TaoToken 的 API 地址是https://taotoken.net/api在 OpenAI 兼容的客戶(hù)端里Base URL 通常填這個(gè)然后客戶(hù)端會(huì)自動(dòng)拼/v1/chat/completions。如果你用的工具要求填完整 endpoint那就填https://taotoken.net/api/v1/chat/completions。兩種寫(xiě)法取決于工具下面配置骨架里我會(huì)標(biāo)注清楚。3. 可復(fù)制配置掃描代碼 工具接入骨架3.1 Android 側(cè)MediaStore 掃描 PDF 的完整實(shí)現(xiàn)先在AndroidManifest.xml里聲明權(quán)限。Android 13API 33之后讀媒體文件要用細(xì)分權(quán)限所以新舊版本都要覆蓋uses-permission android:nameandroid.permission.READ_EXTERNAL_STORAGE android:maxSdkVersion32 / uses-permission android:nameandroid.permission.READ_MEDIA_IMAGES / uses-permission android:nameandroid.permission.READ_MEDIA_VIDEO / uses-permission android:nameandroid.permission.READ_MEDIA_AUDIO /PDF 不屬于圖片/視頻/音頻這三類(lèi)細(xì)分媒體在 Android 13 上通過(guò)MediaStore.Files查詢(xún)application/pdf仍然可行但部分機(jī)型需要走M(jìn)ANAGE_EXTERNAL_STORAGE或 SAF存儲(chǔ)訪問(wèn)框架才能拿到全部文件。實(shí)測(cè)下來(lái)用MediaStore.Files查 MIME 是最省事的路徑先跑通它遇到權(quán)限不足再降級(jí)到 SAF。下面是 Kotlin 掃描函數(shù)返回文件名和內(nèi)容 Uri 的配對(duì)列表data class PdfItem(val name: String, val uri: Uri, val size: Long) fun scanLocalPdfs(context: Context): ListPdfItem { val result mutableListOfPdfItem() val collection MediaStore.Files.getContentUri(external) val projection arrayOf( MediaStore.Files.FileColumns.DISPLAY_NAME, MediaStore.Files.FileColumns.SIZE, MediaStore.Files.FileColumns._ID ) val selection ${MediaStore.Files.FileColumns.MIME_TYPE} ? val selectionArgs arrayOf(application/pdf) val sortOrder ${MediaStore.Files.FileColumns.DATE_ADDED} DESC context.contentResolver.query( collection, projection, selection, selectionArgs, sortOrder )?.use { cursor - val nameIdx cursor.getColumnIndexOrThrow(MediaStore.Files.FileColumns.DISPLAY_NAME) val sizeIdx cursor.getColumnIndexOrThrow(MediaStore.Files.FileColumns.SIZE) val idIdx cursor.getColumnIndexOrThrow(MediaStore.Files.FileColumns._ID) while (cursor.moveToNext()) { val id cursor.getLong(idIdx) val uri ContentUris.withAppendedId(collection, id) result.add( PdfItem( name cursor.getString(nameIdx), uri uri, size cursor.getLong(sizeIdx) ) ) } } return result }關(guān)鍵點(diǎn)說(shuō)明MediaStore.Files.getContentUri(external)拿到外部存儲(chǔ)的文件集合selection用 MIME 類(lèi)型過(guò)濾比按擴(kuò)展名.pdf匹配更準(zhǔn)因?yàn)橛行┪募U(kuò)展名和實(shí)際類(lèi)型不一致ContentUris.withAppendedId把_ID拼成可直接讀取的content://UriAndroid 10 用這個(gè) Uri 打開(kāi)文件流最穩(wěn)不要再去拼/storage/emulated/0/...這種絕對(duì)路徑。如果你確實(shí)需要絕對(duì)路徑比如傳給某些只認(rèn)路徑的庫(kù)可以額外查MediaStore.Files.FileColumns.DATA列但要清楚這個(gè)列在 Android 10 上可能返回空或不可讀屬于兼容性寫(xiě)法不推薦作為主路徑。3.2 Cline 接入配置骨架Cline 是 VS Code 里的編碼 Agent配置走 OpenAI Compatible 模式。在設(shè)置里選 Provider 為「OpenAI Compatible」然后填{ provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: sk-xxxx, model: 你的模型名, temperature: 0.2 }baseUrl填https://taotoken.net/apiCline 會(huì)自動(dòng)補(bǔ)/v1/chat/completions。model填你在模型列表里看到的名稱(chēng)。溫度調(diào)低一點(diǎn)0.2 左右是因?yàn)樘幚砦募鍐芜@類(lèi)任務(wù)需要穩(wěn)定輸出不要讓它自由發(fā)揮。3.3 Claude Code 接入配置骨架Claude Code 通過(guò)環(huán)境變量讀取通道配置在 shell 的~/.zshrc或~/.bashrc里加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-xxxx改完執(zhí)行source ~/.zshrc生效。Claude Code 的詳細(xì)接入說(shuō)明在文檔頁(yè) https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有不同操作系統(tǒng)的完整步驟。如果你用的是 Claude Code 的 Anthropic 原生通道參考 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 這個(gè)頁(yè)面它專(zhuān)門(mén)講 Anthropic 協(xié)議下的配置差異。3.4 config.toml 通用骨架有些工具比如某些 CLI Agent用 TOML 配置骨架如下[provider] name taotoken base_url https://taotoken.net/api api_key sk-xxxx model 你的模型名 [request] timeout 60 max_retries 3timeout給 60 秒因?yàn)?PDF 內(nèi)容如果較長(zhǎng)模型響應(yīng)會(huì)慢一些max_retries給 3 次網(wǎng)絡(luò)抖動(dòng)時(shí)自動(dòng)重試。4. 驗(yàn)證請(qǐng)求從掃描結(jié)果到模型調(diào)用掃描代碼寫(xiě)完后先驗(yàn)證文件清單是否正確。在 Activity 里調(diào)用并打印val pdfs scanLocalPdfs(this) Log.d(PDFScan, 共找到 ${pdfs.size} 個(gè) PDF) pdfs.take(5).forEach { Log.d(PDFScan, ${it.name} | ${it.size} bytes | ${it.uri}) }跑起來(lái)看 Logcat如果數(shù)量為 0先檢查權(quán)限是否授予、模擬器里是否真的存了 PDF 文件。確認(rèn)清單沒(méi)問(wèn)題后驗(yàn)證 AI 通道。用 curl 發(fā)一個(gè)最小請(qǐng)求curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-xxxx \ -d { model: 你的模型名, messages: [ {role: user, content: 回復(fù) OK 兩個(gè)字母即可} ] }返回里能看到choices[0].message.content是OK說(shuō)明通道通了。這一步很關(guān)鍵很多人配置完直接上復(fù)雜任務(wù)報(bào)錯(cuò)了分不清是通道問(wèn)題還是業(yè)務(wù)問(wèn)題先用最小請(qǐng)求把通道驗(yàn)證掉。通道通了之后把掃描結(jié)果和模型調(diào)用串起來(lái)。思路是把 PDF 文件名列表拼成一段文本發(fā)給模型做分類(lèi)或摘要。比如val names pdfs.joinToString(\n) { it.name } val prompt 以下是本地 PDF 文件清單請(qǐng)按主題分類(lèi)\n$names // 把 prompt 通過(guò)你的 HTTP 客戶(hù)端發(fā)到 https://taotoken.net/api/v1/chat/completions如果你要讀 PDF 正文內(nèi)容需要先把content://Uri 轉(zhuǎn)成字節(jié)流再用 PDF 解析庫(kù)如 PdfBox-Android提取文本然后把文本作為 message 內(nèi)容發(fā)出去。注意單次請(qǐng)求的 token 上限長(zhǎng) PDF 要分段。5. 本篇常見(jiàn)錯(cuò)排查掃描結(jié)果為 0最常見(jiàn)原因是權(quán)限沒(méi)授予。Android 13 上READ_EXTERNAL_STORAGE已失效要?jiǎng)討B(tài)申請(qǐng)READ_MEDIA_*系列或者引導(dǎo)用戶(hù)去系統(tǒng)設(shè)置里開(kāi)「所有文件訪問(wèn)權(quán)限」。另一個(gè)原因是模擬器里根本沒(méi)存 PDF用adb push推一個(gè)進(jìn)去再測(cè)。Uri 能拿到但打不開(kāi)Android 10 分區(qū)存儲(chǔ)下直接拼絕對(duì)路徑會(huì)失敗。用ContentUris.withAppendedId生成的content://Uri 配合contentResolver.openInputStream(uri)讀取不要用File(path)。Cline 報(bào) 401Key 填錯(cuò)或沒(méi)帶Bearer前綴。檢查apiKey字段是不是完整的sk-開(kāi)頭字符串有沒(méi)有多余空格。Claude Code 報(bào)連接失敗環(huán)境變量沒(méi)生效。確認(rèn)ANTHROPIC_BASE_URL拼寫(xiě)正確改完配置文件后重新開(kāi)一個(gè)終端窗口或者source一下。如果還是不行去文檔頁(yè)對(duì)照你的系統(tǒng)版本檢查。請(qǐng)求超時(shí)PDF 內(nèi)容太長(zhǎng)導(dǎo)致模型處理慢。把timeout調(diào)到 120 秒或者把 PDF 分段發(fā)送。另外確認(rèn)baseUrl沒(méi)有多寫(xiě)或少寫(xiě)/v1不同工具對(duì)路徑的處理不一樣。模型名報(bào)錯(cuò)填的模型名不在可用列表里。去模型對(duì)話頁(yè)確認(rèn)當(dāng)前可用的模型名稱(chēng)復(fù)制粘貼不要手打。6. 后續(xù)怎么用把鏈路固定下來(lái)掃描 接入跑通后建議把配置固化成模板。Android 側(cè)把scanLocalPdfs封裝成工具類(lèi)AI 側(cè)把 Key 和 Base URL 放到local.properties或環(huán)境變量里不要散落在代碼各處。長(zhǎng)期做編碼類(lèi)任務(wù)的話Coding Plan 比按量計(jì)費(fèi)更劃算地址在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。需要新建或輪換 Key 時(shí)去 API Keys 頁(yè)面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入細(xì)節(jié)查文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先試試模型效果直接去模型對(duì)話頁(yè) https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 發(fā)一條消息就能驗(yàn)證。最后留一個(gè)我踩過(guò)的坑MediaStore 的查詢(xún)結(jié)果有緩存新推入的 PDF 文件可能不會(huì)立刻出現(xiàn)在列表里。測(cè)試時(shí)如果發(fā)現(xiàn)文件「消失」了用contentResolver.notifyChange觸發(fā)一次刷新或者重啟 App 再查。這個(gè)細(xì)節(jié)教程里很少提但調(diào)試時(shí)能省不少時(shí)間。