1. Android 本地 PDF 掃描到底難在哪Android 獲取手機(jī)本地所有 PDF 文件本質(zhì)上是兩件事一是用 MediaStore 把散落在各目錄的 PDF 索引出來二是把這份文件清單交給 AI 工具做后續(xù)處理摘要、分類、問答。第一件事網(wǎng)上教程很多第二件事才是真正卡人的地方——你本地跑通了掃描結(jié)果要接大模型時(shí)發(fā)現(xiàn)每個(gè)工具都要單獨(dú)填 Key、單獨(dú)配 Base URLCline 一套、Claude Code 一套、腳本里又一套改一次配置要翻五個(gè)文件。這篇就按「掃描 PDF → 拿到路徑列表 → 用 TaoToken 統(tǒng)一 Key 接入 AI 工具」這條鏈路走一遍。適合兩類人正在做 Android 文件管理類 App、需要把本地文檔喂給模型的開發(fā)者以及想用 Cline、Claude Code 這類編碼工具批量處理本地 PDF 資料的人。核心檢索詞就三個(gè)Android 本地 PDF 掃描、MediaStore 查詢、TaoToken 統(tǒng)一 Key 接入。先說結(jié)論掃描部分用MediaStore.Files配合 MIME 過濾是最穩(wěn)的路徑Android 10 之后分區(qū)存儲(chǔ)Scoped Storage讓直接讀絕對(duì)路徑變得不可靠所以我會(huì)同時(shí)給「拿 Uri」和「拿可讀路徑」兩種寫法。AI 接入部分TaoToken 提供的是 OpenAI 兼容的統(tǒng)一通道一個(gè) Key 可以給多個(gè)工具復(fù)用省掉到處填配置的麻煩。下面從權(quán)限開始一步步給可復(fù)制的代碼和配置。2. TaoToken 前置統(tǒng)一 Key 與通道準(zhǔn)備在寫掃描代碼之前先把 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)建后在密鑰管理頁復(fù)制出來形如sk-開頭的一串。第二步確認(rèn)你要用的模型名模型對(duì)話頁 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 里能看到當(dāng)前可用的模型列表記下你打算調(diào)用的那個(gè)。第三步如果你打算長期用編碼類工具Cline、Claude Code 等批量處理 PDF建議直接看 Coding Plan地址 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它比按量計(jì)費(fèi)更適合高頻調(diào)用場景。注意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 兼容的客戶端里Base URL 通常填這個(gè)然后客戶端會(huì)自動(dòng)拼/v1/chat/completions。如果你用的工具要求填完整 endpoint那就填https://taotoken.net/api/v1/chat/completions。兩種寫法取決于工具下面配置骨架里我會(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 不屬于圖片/視頻/音頻這三類細(xì)分媒體在 Android 13 上通過MediaStore.Files查詢application/pdf仍然可行但部分機(jī)型需要走M(jìn)ANAGE_EXTERNAL_STORAGE或 SAF存儲(chǔ)訪問框架才能拿到全部文件。實(shí)測下來用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)說明MediaStore.Files.getContentUri(external)拿到外部存儲(chǔ)的文件集合selection用 MIME 類型過濾比按擴(kuò)展名.pdf匹配更準(zhǔn)因?yàn)橛行┪募U(kuò)展名和實(shí)際類型不一致ContentUris.withAppendedId把_ID拼成可直接讀取的content://UriAndroid 10 用這個(gè) Uri 打開文件流最穩(wěn)不要再去拼/storage/emulated/0/...這種絕對(duì)路徑。如果你確實(shí)需要絕對(duì)路徑比如傳給某些只認(rèn)路徑的庫可以額外查MediaStore.Files.FileColumns.DATA列但要清楚這個(gè)列在 Android 10 上可能返回空或不可讀屬于兼容性寫法不推薦作為主路徑。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填你在模型列表里看到的名稱。溫度調(diào)低一點(diǎn)0.2 左右是因?yàn)樘幚砦募鍐芜@類任務(wù)需要穩(wěn)定輸出不要讓它自由發(fā)揮。3.3 Claude Code 接入配置骨架Claude Code 通過環(huán)境變量讀取通道配置在 shell 的~/.zshrc或~/.bashrc里加export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-xxxx改完執(zhí)行source ~/.zshrc生效。Claude Code 的詳細(xì)接入說明在文檔頁 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è)頁面它專門講 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)容如果較長模型響應(yīng)會(huì)慢一些max_retries給 3 次網(wǎng)絡(luò)抖動(dòng)時(shí)自動(dòng)重試。4. 驗(yàn)證請(qǐng)求從掃描結(jié)果到模型調(diào)用掃描代碼寫完后先驗(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}) }跑起來看 Logcat如果數(shù)量為 0先檢查權(quán)限是否授予、模擬器里是否真的存了 PDF 文件。確認(rè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說明通道通了。這一步很關(guān)鍵很多人配置完直接上復(fù)雜任務(wù)報(bào)錯(cuò)了分不清是通道問題還是業(yè)務(wù)問題先用最小請(qǐng)求把通道驗(yàn)證掉。通道通了之后把掃描結(jié)果和模型調(diào)用串起來。思路是把 PDF 文件名列表拼成一段文本發(fā)給模型做分類或摘要。比如val names pdfs.joinToString(\n) { it.name } val prompt 以下是本地 PDF 文件清單請(qǐng)按主題分類\n$names // 把 prompt 通過你的 HTTP 客戶端發(fā)到 https://taotoken.net/api/v1/chat/completions如果你要讀 PDF 正文內(nèi)容需要先把content://Uri 轉(zhuǎn)成字節(jié)流再用 PDF 解析庫如 PdfBox-Android提取文本然后把文本作為 message 內(nèi)容發(fā)出去。注意單次請(qǐng)求的 token 上限長 PDF 要分段。5. 本篇常見錯(cuò)排查掃描結(jié)果為 0最常見原因是權(quán)限沒授予。Android 13 上READ_EXTERNAL_STORAGE已失效要?jiǎng)討B(tài)申請(qǐng)READ_MEDIA_*系列或者引導(dǎo)用戶去系統(tǒng)設(shè)置里開「所有文件訪問權(quán)限」。另一個(gè)原因是模擬器里根本沒存 PDF用adb push推一個(gè)進(jìn)去再測。Uri 能拿到但打不開Android 10 分區(qū)存儲(chǔ)下直接拼絕對(duì)路徑會(huì)失敗。用ContentUris.withAppendedId生成的content://Uri 配合contentResolver.openInputStream(uri)讀取不要用File(path)。Cline 報(bào) 401Key 填錯(cuò)或沒帶Bearer前綴。檢查apiKey字段是不是完整的sk-開頭字符串有沒有多余空格。Claude Code 報(bào)連接失敗環(huán)境變量沒生效。確認(rèn)ANTHROPIC_BASE_URL拼寫正確改完配置文件后重新開一個(gè)終端窗口或者source一下。如果還是不行去文檔頁對(duì)照你的系統(tǒng)版本檢查。請(qǐng)求超時(shí)PDF 內(nèi)容太長導(dǎo)致模型處理慢。把timeout調(diào)到 120 秒或者把 PDF 分段發(fā)送。另外確認(rèn)baseUrl沒有多寫或少寫/v1不同工具對(duì)路徑的處理不一樣。模型名報(bào)錯(cuò)填的模型名不在可用列表里。去模型對(duì)話頁確認(rèn)當(dāng)前可用的模型名稱復(fù)制粘貼不要手打。6. 后續(xù)怎么用把鏈路固定下來掃描 接入跑通后建議把配置固化成模板。Android 側(cè)把scanLocalPdfs封裝成工具類AI 側(cè)把 Key 和 Base URL 放到local.properties或環(huán)境變量里不要散落在代碼各處。長期做編碼類任務(wù)的話Coding Plan 比按量計(jì)費(fèi)更劃算地址在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。需要新建或輪換 Key 時(shí)去 API Keys 頁面 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ì)話頁 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 發(fā)一條消息就能驗(yàn)證。最后留一個(gè)我踩過的坑MediaStore 的查詢結(jié)果有緩存新推入的 PDF 文件可能不會(huì)立刻出現(xiàn)在列表里。測試時(shí)如果發(fā)現(xiàn)文件「消失」了用contentResolver.notifyChange觸發(fā)一次刷新或者重啟 App 再查。這個(gè)細(xì)節(jié)教程里很少提但調(diào)試時(shí)能省不少時(shí)間。