 Markdown 完全指南：mcp__cherry-tools__to_markdown 工具的用法、邊界與原理)
Cherry Studio 本地文檔轉(zhuǎn) Markdown 完全指南mcp__cherry-tools__to_markdown 工具的用法、邊界與原理【免費(fèi)下載鏈接】cherry-studio Cherry Studio 是一款支持多個(gè) LLM 提供商的桌面客戶端項(xiàng)目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 通過內(nèi)置 MCP 服務(wù)器向 Agent 注入了一組第一方工具其中mcp__cherry-tools__to_markdown負(fù)責(zé)把受支持的本地文檔Word、PPT、Excel、OpenDocument、PDF 等轉(zhuǎn)換為 Markdown。本文以官方技能參考 documents.md 為骨架結(jié)合倉(cāng)庫(kù)源碼與測(cè)試用例系統(tǒng)講解該工具的路由定位、調(diào)用契約、路徑授權(quán)邊界、輸出管理、恢復(fù)策略與底層實(shí)現(xiàn)幫助讀者以及閱讀本文的 Agent/LLM在會(huì)話中安全、準(zhǔn)確地使用這一能力。一、工具定位與知識(shí)庫(kù)、Shell 的邊界to_markdown解決的是**讀取一份本地文檔的結(jié)構(gòu)化內(nèi)容**問題——當(dāng)普通文本讀取工具無法處理 Office/PDF 等二進(jìn)制格式時(shí)由它來接管。官方路由表SKILL.md明確區(qū)分了三條路徑本地文檔讀取/轉(zhuǎn)換→mcp__cherry-tools__to_markdown然后按需讀取返回的臨時(shí) Markdown 文件知識(shí)庫(kù)問答→mcp__cherry-tools__kb_list→kb_search→kb_read這些工具檢索的是已被 Cherry 索引過的文檔而非任意本地文件Shell 執(zhí)行→ 項(xiàng)目捆綁的bun/uv/uvx/rg運(yùn)行時(shí)用于跑腳本、執(zhí)行一次性工具、搜索代碼。三者互不替代to_markdown不檢索知識(shí)庫(kù)也不是通用 Shell 替代品。從源碼看該工具由獨(dú)立的領(lǐng)域提供器CherryDocumentTools實(shí)現(xiàn)并由CherryBuiltinToolsServer聚合進(jìn)名為cherry-tools的 MCP server見 cherryBuiltinTools.ts與其他領(lǐng)域工具CherryKnowledgeTools、CherryAutonomyTools、CherryCliTools并列注冊(cè)。二、工作流一次完整的文檔轉(zhuǎn)換官方參考文檔給出了標(biāo)準(zhǔn)調(diào)用序列結(jié)合源碼 cherryDocumentTools.ts 可以還原完整流程傳入路徑調(diào)用工具時(shí)傳入一個(gè)path參數(shù)——可以是相對(duì)會(huì)話工作區(qū)的路徑也可以是絕對(duì)路徑須屬于本會(huì)話授權(quán)范圍見下文路徑授權(quán)一節(jié)路徑解析與鑒權(quán)工具先嘗試把路徑解析到會(huì)話工作區(qū)內(nèi)失敗后再嘗試 agent 數(shù)據(jù)目錄與會(huì)話附件等可信根。任何越權(quán)路徑都會(huì)在轉(zhuǎn)換開始前被拒絕格式識(shí)別加載firecrawl/anydoc轉(zhuǎn)換庫(kù)通過formatFromExtension(path.extname(...))取擴(kuò)展名對(duì)應(yīng)的格式再調(diào)用toMarkdownBytes完成轉(zhuǎn)換該庫(kù)也會(huì)從文件內(nèi)容識(shí)別格式擴(kuò)展名僅作兜底寫入臨時(shí)文件轉(zhuǎn)換結(jié)果被整體寫入 agent 私有的臨時(shí) Markdown 文件位于agentDataPath/tmp/to-markdown/uuid.md以wx標(biāo)志創(chuàng)建返回結(jié)果工具結(jié)果只包含該臨時(shí)文件的絕對(duì)路徑和字符數(shù)不會(huì)把整篇文檔塞進(jìn)模型上下文后續(xù)讀取Agent 用普通文件工具對(duì)返回路徑做切片讀取、搜索或按用戶要求復(fù)制到最終路徑。關(guān)鍵設(shè)計(jì)結(jié)果不注入上下文。工具故意只回傳{ path, chars }避免大文檔撐爆上下文窗口。這一點(diǎn)由輸出 Schema 強(qiáng)制約束見 builtinTools.ts測(cè)試 cherryDocumentTools.test.ts 也驗(yàn)證了轉(zhuǎn)換結(jié)果不包含在工具返回值中這一行為。三、支持的輸入格式官方參考文檔給出的支持矩陣如下類別擴(kuò)展名Word.doc、.docx、.docmPowerPoint.ppt、.pps、.pot、.pptx、.pptm、.ppsx、.ppsmExcel.xls、.xlsx、.xlsm、.xlsbOpenDocument.odt、.ods、.odp其他.rtf、.epub、.csv、.pdf同一份清單在源碼中以常量TO_MARKDOWN_SUPPORTED_EXTENSIONS定義并內(nèi)嵌進(jìn)工具描述與參數(shù)說明中見 builtinTools.ts。值得注意的格式識(shí)別細(xì)節(jié)內(nèi)容優(yōu)先、擴(kuò)展名兜底轉(zhuǎn)換器會(huì)從文件內(nèi)容識(shí)別可辨識(shí)的格式識(shí)別失敗時(shí)回退到擴(kuò)展名判斷CSV 無文件簽名CSV 沒有內(nèi)容特征可用于識(shí)別因此必須使用.csv擴(kuò)展名才能被正確路由單參數(shù)約束工具目前只接受path一個(gè)必填參數(shù)不接受輸出路徑、格式覆蓋、頁(yè)碼范圍、密碼或 OCR 選項(xiàng)——格式判斷完全交由轉(zhuǎn)換器自主決定。四、參數(shù)與返回契約path參數(shù)的 Schema 約束見 builtinTools.ts字符串類型調(diào)用前會(huì)trim()最小長(zhǎng)度 1非空最大長(zhǎng)度 4096 字符語(yǔ)義相對(duì)路徑從會(huì)話工作區(qū)解析絕對(duì)路徑必須是本會(huì)話已公布的附件或位于 agent 數(shù)據(jù)目錄之下。返回值 SchematoMarkdownOutputSchema{ path: 絕對(duì)路徑轉(zhuǎn)換出的臨時(shí) Markdown 文件需要時(shí)按切片讀取, chars: 寫入 Markdown 文件的字符數(shù)非負(fù)整數(shù) }chars對(duì)應(yīng)源碼中markdown.length即轉(zhuǎn)換結(jié)果去除首尾空白后的字符數(shù)可用于讓 Agent 判斷文件規(guī)模、決定切片讀取策略。五、路徑授權(quán)與安全邊界該工具無需審批auto-approved因此越權(quán)路徑必須在轉(zhuǎn)換發(fā)生前被攔截。源碼中的授權(quán)邏輯cherryDocumentTools.ts 的resolveDocumentSource定義了三個(gè)可信根會(huì)話工作區(qū)相對(duì)路徑或落在工作區(qū)內(nèi)的絕對(duì)路徑通過 WorkspaceFileGuard.ts 的resolveWorkspaceFile解析——它先用realpath規(guī)范化目標(biāo)路徑再校驗(yàn)其是否仍位于工作區(qū)根之內(nèi)從而挫敗..相對(duì)遍歷與符號(hào)鏈接逃逸Agent 數(shù)據(jù)目錄Agent 自己下載或生成的文檔所在目錄agentDataPath通過isSameOrInside做包含性校驗(yàn)見 path.ts本會(huì)話附件僅限本會(huì)話公布的托管文件——授權(quán)采用精確物理路徑匹配而不是父目錄匹配。測(cè)試用例驗(yàn)證了與已授權(quán)附件共享父目錄的兄弟文件不會(huì)被授權(quán)這一邊界見 cherryDocumentTools.test.ts。除路徑外還有兩道硬約束常規(guī)文件源必須是可讀的常規(guī)文件lstat校驗(yàn)?zāi)夸浀忍厥馕募痪芙^大小限制源文件不得超過工具的字節(jié)上限。源碼中MAX_FILE_SIZE_BYTES 100 * MB見 downloadAsBase64.ts且在讀取前stat與讀取后實(shí)際字節(jié)數(shù)雙重校驗(yàn)防止文件在讀取間隙被替換/增長(zhǎng)繞過限制見 localFileResolver.ts。六、臨時(shí)輸出管理agent 私有目錄與 24 小時(shí)清理轉(zhuǎn)換結(jié)果統(tǒng)一寫入agentDataPath/tmp/to-markdown/目錄文件名是隨機(jī) UUID避免與其他會(huì)話產(chǎn)物沖突wx創(chuàng)建標(biāo)志保證不覆蓋已存在文件。源碼中的cleanupStaleOutputs會(huì)在每次轉(zhuǎn)換時(shí)清理超過 24 小時(shí)OUTPUT_MAX_AGE_MS 24 * 60 * 60 * 1000未修改的.md臨時(shí)文件只清理該目錄內(nèi)的 Markdown 文件、不影響近期產(chǎn)物。測(cè)試用例removes stale Markdown outputs while preserving recent files用 25 小時(shí)前的舊文件驗(yàn)證了這一行為。對(duì) Agent 的實(shí)操含義臨時(shí)文件是私有且會(huì)過期的需要長(zhǎng)期保留的內(nèi)容應(yīng)復(fù)制到用戶要求的最終路徑讀取時(shí)應(yīng)按切片進(jìn)行而不是一次性載入全文。七、恢復(fù)策略與已知限制官方參考文檔給出了明確的故障處理矩陣每一條都對(duì)應(yīng)可驗(yàn)證的源碼行為情況處理方式工具不可用本會(huì)話的文檔轉(zhuǎn)換能力不可用不要在用戶不知情的情況下安裝或調(diào)用替代轉(zhuǎn)換器不支持或不可讀的文件報(bào)告轉(zhuǎn)換器錯(cuò)誤不要通過npm、bun x、npx、直接mise、遠(yuǎn)程安裝器或手動(dòng)下載的二進(jìn)制重試空輸出報(bào)告未產(chǎn)生任何文本絕不能將其包裝成一次成功的轉(zhuǎn)換——源碼中空結(jié)果會(huì)拋出Document conversion produced no text且不會(huì)落盤測(cè)試用例已覆蓋掃描版/純圖片 PDF需要 OCR而本工具不提供OCR應(yīng)如實(shí)告知用戶另行選擇具備 OCR 的路徑Windows ARM64上游firecrawl/anydoc目前未發(fā)布該平臺(tái)的原生綁定因此轉(zhuǎn)換在該平臺(tái)不可用倉(cāng)庫(kù)中亦有對(duì)應(yīng)注釋佐證見 fileExtensions.ts此外工具錯(cuò)誤會(huì)以Error: message文本形式返回并標(biāo)記isErrorAgent 應(yīng)當(dāng)讀取報(bào)錯(cuò)信息修正調(diào)用而不是盲目重試相同參數(shù)轉(zhuǎn)換過程也尊重 AbortSignal可被會(huì)話取消。八、實(shí)戰(zhàn)示例總結(jié)一份 PPT官方參考文檔給出了最典型的使用場(chǎng)景——Summarizereports/q3-review.pptx。完整執(zhí)行序列如下調(diào)用mcp__cherry-tools__to_markdown參數(shù)path: reports/q3-review.pptx相對(duì)會(huì)話工作區(qū)的路徑拿到返回的臨時(shí) Markdown 絕對(duì)路徑與字符數(shù)用普通文件工具對(duì)返回路徑按切片讀取或搜索相關(guān)章節(jié)基于切片內(nèi)容完成總結(jié)并回復(fù)用戶。過程中不要安裝獨(dú)立的文檔轉(zhuǎn)換 CLI也不要把完整 Markdown 一次性加載進(jìn)模型上下文——前者違反不繞行安裝原則后者會(huì)無謂消耗上下文窗口。九、源碼級(jí)調(diào)用鏈與驗(yàn)證從工具名到最終落盤完整調(diào)用鏈為mcp__cherry-tools__to_markdown → CherryBuiltinToolsServerMCP 分發(fā)見 cherryBuiltinTools.ts → CherryDocumentTools.call參數(shù)校驗(yàn)、路徑鑒權(quán)見 cherryDocumentTools.ts → resolveWorkspaceFile / resolveLocalFilerealpath 防逃逸 大小校驗(yàn) → firecrawl/anydoc 的 formatFromExtension toMarkdownBytes格式識(shí)別與轉(zhuǎn)換 → 寫入 agentDataPath/tmp/to-markdown/uuid.md → 返回 { path, chars }針對(duì)該工具的單元測(cè)試cherryDocumentTools.test.ts系統(tǒng)驗(yàn)證了以下行為結(jié)果不含文檔內(nèi)容、工作區(qū)外絕對(duì)路徑被拒、../遍歷與符號(hào)鏈接逃逸被拒、本會(huì)話附件可轉(zhuǎn)換、非本會(huì)話附件被拒、agent 數(shù)據(jù)目錄內(nèi)文件可轉(zhuǎn)換、超限文件被拒、空輸出報(bào)錯(cuò)且不落盤、24 小時(shí)過期清理。這些測(cè)試即是最佳的行為契約文檔。十、與知識(shí)庫(kù)文件處理的區(qū)別避免混淆倉(cāng)庫(kù)中還存在另一條文檔轉(zhuǎn) Markdown路徑——知識(shí)庫(kù)的文件處理流程如 localDocument 處理器它面向已入庫(kù)的 PDF 文件且僅路由 PDFknowledgeFileProcessingExts [.pdf]見 fileExtensions.ts包含本地 OCR 回退PaddleOCR等更重的處理能力。但這條路徑屬于知識(shí)庫(kù)索引側(cè)不暴露為本文所述的 MCP 工具to_markdown面向的是會(huì)話內(nèi)任意受支持的本地文檔兩者是不同入口、不同授權(quán)模型切勿混用。結(jié)語(yǔ)mcp__cherry-tools__to_markdown是 Cherry Studio Agent 會(huì)話中處理本地辦公文檔的標(biāo)準(zhǔn)入口單參數(shù)、格式自動(dòng)識(shí)別、結(jié)果落盤而非注入上下文、三類可信根嚴(yán)格鑒權(quán)、24 小時(shí)臨時(shí)文件治理配合明確的恢復(fù)策略構(gòu)成一套安全、克制、可預(yù)測(cè)的文檔轉(zhuǎn)換能力。結(jié)合本文的源碼佐證與測(cè)試契約Agent 與開發(fā)者都可以放心地在會(huì)話工作流中編排這一工具而不會(huì)觸及知識(shí)庫(kù)索引或 Shell 執(zhí)行等相鄰邊界?！久赓M(fèi)下載鏈接】cherry-studio Cherry Studio 是一款支持多個(gè) LLM 提供商的桌面客戶端項(xiàng)目地址: https://gitcode.com/CherryHQ/cherry-studio創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Cherry Studio 本地文檔轉(zhuǎn) Markdown 完全指南：mcp__cherry-tools__to_markdown 工具的用法、邊界與原理
Cherry Studio 本地文檔轉(zhuǎn) Markdown 完全指南mcp__cherry-tools__to_markdown 工具的用法、邊界與原理【免費(fèi)下載鏈接】cherry-studio Cherry Studio 是一款支持多個(gè) LLM 提供商的桌面客戶端項(xiàng)目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 通過內(nèi)置 MCP 服務(wù)器向 Agent 注入了一組第一方工具其中mcp__cherry-tools__to_markdown負(fù)責(zé)把受支持的本地文檔Word、PPT、Excel、OpenDocument、PDF 等轉(zhuǎn)換為 Markdown。本文以官方技能參考 documents.md 為骨架結(jié)合倉(cāng)庫(kù)源碼與測(cè)試用例系統(tǒng)講解該工具的路由定位、調(diào)用契約、路徑授權(quán)邊界、輸出管理、恢復(fù)策略與底層實(shí)現(xiàn)幫助讀者以及閱讀本文的 Agent/LLM在會(huì)話中安全、準(zhǔn)確地使用這一能力。一、工具定位與知識(shí)庫(kù)、Shell 的邊界to_markdown解決的是**讀取一份本地文檔的結(jié)構(gòu)化內(nèi)容**問題——當(dāng)普通文本讀取工具無法處理 Office/PDF 等二進(jìn)制格式時(shí)由它來接管。官方路由表SKILL.md明確區(qū)分了三條路徑本地文檔讀取/轉(zhuǎn)換→mcp__cherry-tools__to_markdown然后按需讀取返回的臨時(shí) Markdown 文件知識(shí)庫(kù)問答→mcp__cherry-tools__kb_list→kb_search→kb_read這些工具檢索的是已被 Cherry 索引過的文檔而非任意本地文件Shell 執(zhí)行→ 項(xiàng)目捆綁的bun/uv/uvx/rg運(yùn)行時(shí)用于跑腳本、執(zhí)行一次性工具、搜索代碼。三者互不替代to_markdown不檢索知識(shí)庫(kù)也不是通用 Shell 替代品。從源碼看該工具由獨(dú)立的領(lǐng)域提供器CherryDocumentTools實(shí)現(xiàn)并由CherryBuiltinToolsServer聚合進(jìn)名為cherry-tools的 MCP server見 cherryBuiltinTools.ts與其他領(lǐng)域工具CherryKnowledgeTools、CherryAutonomyTools、CherryCliTools并列注冊(cè)。二、工作流一次完整的文檔轉(zhuǎn)換官方參考文檔給出了標(biāo)準(zhǔn)調(diào)用序列結(jié)合源碼 cherryDocumentTools.ts 可以還原完整流程傳入路徑調(diào)用工具時(shí)傳入一個(gè)path參數(shù)——可以是相對(duì)會(huì)話工作區(qū)的路徑也可以是絕對(duì)路徑須屬于本會(huì)話授權(quán)范圍見下文路徑授權(quán)一節(jié)路徑解析與鑒權(quán)工具先嘗試把路徑解析到會(huì)話工作區(qū)內(nèi)失敗后再嘗試 agent 數(shù)據(jù)目錄與會(huì)話附件等可信根。任何越權(quán)路徑都會(huì)在轉(zhuǎn)換開始前被拒絕格式識(shí)別加載firecrawl/anydoc轉(zhuǎn)換庫(kù)通過formatFromExtension(path.extname(...))取擴(kuò)展名對(duì)應(yīng)的格式再調(diào)用toMarkdownBytes完成轉(zhuǎn)換該庫(kù)也會(huì)從文件內(nèi)容識(shí)別格式擴(kuò)展名僅作兜底寫入臨時(shí)文件轉(zhuǎn)換結(jié)果被整體寫入 agent 私有的臨時(shí) Markdown 文件位于agentDataPath/tmp/to-markdown/uuid.md以wx標(biāo)志創(chuàng)建返回結(jié)果工具結(jié)果只包含該臨時(shí)文件的絕對(duì)路徑和字符數(shù)不會(huì)把整篇文檔塞進(jìn)模型上下文后續(xù)讀取Agent 用普通文件工具對(duì)返回路徑做切片讀取、搜索或按用戶要求復(fù)制到最終路徑。關(guān)鍵設(shè)計(jì)結(jié)果不注入上下文。工具故意只回傳{ path, chars }避免大文檔撐爆上下文窗口。這一點(diǎn)由輸出 Schema 強(qiáng)制約束見 builtinTools.ts測(cè)試 cherryDocumentTools.test.ts 也驗(yàn)證了轉(zhuǎn)換結(jié)果不包含在工具返回值中這一行為。三、支持的輸入格式官方參考文檔給出的支持矩陣如下類別擴(kuò)展名Word.doc、.docx、.docmPowerPoint.ppt、.pps、.pot、.pptx、.pptm、.ppsx、.ppsmExcel.xls、.xlsx、.xlsm、.xlsbOpenDocument.odt、.ods、.odp其他.rtf、.epub、.csv、.pdf同一份清單在源碼中以常量TO_MARKDOWN_SUPPORTED_EXTENSIONS定義并內(nèi)嵌進(jìn)工具描述與參數(shù)說明中見 builtinTools.ts。值得注意的格式識(shí)別細(xì)節(jié)內(nèi)容優(yōu)先、擴(kuò)展名兜底轉(zhuǎn)換器會(huì)從文件內(nèi)容識(shí)別可辨識(shí)的格式識(shí)別失敗時(shí)回退到擴(kuò)展名判斷CSV 無文件簽名CSV 沒有內(nèi)容特征可用于識(shí)別因此必須使用.csv擴(kuò)展名才能被正確路由單參數(shù)約束工具目前只接受path一個(gè)必填參數(shù)不接受輸出路徑、格式覆蓋、頁(yè)碼范圍、密碼或 OCR 選項(xiàng)——格式判斷完全交由轉(zhuǎn)換器自主決定。四、參數(shù)與返回契約path參數(shù)的 Schema 約束見 builtinTools.ts字符串類型調(diào)用前會(huì)trim()最小長(zhǎng)度 1非空最大長(zhǎng)度 4096 字符語(yǔ)義相對(duì)路徑從會(huì)話工作區(qū)解析絕對(duì)路徑必須是本會(huì)話已公布的附件或位于 agent 數(shù)據(jù)目錄之下。返回值 SchematoMarkdownOutputSchema{ path: 絕對(duì)路徑轉(zhuǎn)換出的臨時(shí) Markdown 文件需要時(shí)按切片讀取, chars: 寫入 Markdown 文件的字符數(shù)非負(fù)整數(shù) }chars對(duì)應(yīng)源碼中markdown.length即轉(zhuǎn)換結(jié)果去除首尾空白后的字符數(shù)可用于讓 Agent 判斷文件規(guī)模、決定切片讀取策略。五、路徑授權(quán)與安全邊界該工具無需審批auto-approved因此越權(quán)路徑必須在轉(zhuǎn)換發(fā)生前被攔截。源碼中的授權(quán)邏輯cherryDocumentTools.ts 的resolveDocumentSource定義了三個(gè)可信根會(huì)話工作區(qū)相對(duì)路徑或落在工作區(qū)內(nèi)的絕對(duì)路徑通過 WorkspaceFileGuard.ts 的resolveWorkspaceFile解析——它先用realpath規(guī)范化目標(biāo)路徑再校驗(yàn)其是否仍位于工作區(qū)根之內(nèi)從而挫敗..相對(duì)遍歷與符號(hào)鏈接逃逸Agent 數(shù)據(jù)目錄Agent 自己下載或生成的文檔所在目錄agentDataPath通過isSameOrInside做包含性校驗(yàn)見 path.ts本會(huì)話附件僅限本會(huì)話公布的托管文件——授權(quán)采用精確物理路徑匹配而不是父目錄匹配。測(cè)試用例驗(yàn)證了與已授權(quán)附件共享父目錄的兄弟文件不會(huì)被授權(quán)這一邊界見 cherryDocumentTools.test.ts。除路徑外還有兩道硬約束常規(guī)文件源必須是可讀的常規(guī)文件lstat校驗(yàn)?zāi)夸浀忍厥馕募痪芙^大小限制源文件不得超過工具的字節(jié)上限。源碼中MAX_FILE_SIZE_BYTES 100 * MB見 downloadAsBase64.ts且在讀取前stat與讀取后實(shí)際字節(jié)數(shù)雙重校驗(yàn)防止文件在讀取間隙被替換/增長(zhǎng)繞過限制見 localFileResolver.ts。六、臨時(shí)輸出管理agent 私有目錄與 24 小時(shí)清理轉(zhuǎn)換結(jié)果統(tǒng)一寫入agentDataPath/tmp/to-markdown/目錄文件名是隨機(jī) UUID避免與其他會(huì)話產(chǎn)物沖突wx創(chuàng)建標(biāo)志保證不覆蓋已存在文件。源碼中的cleanupStaleOutputs會(huì)在每次轉(zhuǎn)換時(shí)清理超過 24 小時(shí)OUTPUT_MAX_AGE_MS 24 * 60 * 60 * 1000未修改的.md臨時(shí)文件只清理該目錄內(nèi)的 Markdown 文件、不影響近期產(chǎn)物。測(cè)試用例removes stale Markdown outputs while preserving recent files用 25 小時(shí)前的舊文件驗(yàn)證了這一行為。對(duì) Agent 的實(shí)操含義臨時(shí)文件是私有且會(huì)過期的需要長(zhǎng)期保留的內(nèi)容應(yīng)復(fù)制到用戶要求的最終路徑讀取時(shí)應(yīng)按切片進(jìn)行而不是一次性載入全文。七、恢復(fù)策略與已知限制官方參考文檔給出了明確的故障處理矩陣每一條都對(duì)應(yīng)可驗(yàn)證的源碼行為情況處理方式工具不可用本會(huì)話的文檔轉(zhuǎn)換能力不可用不要在用戶不知情的情況下安裝或調(diào)用替代轉(zhuǎn)換器不支持或不可讀的文件報(bào)告轉(zhuǎn)換器錯(cuò)誤不要通過npm、bun x、npx、直接mise、遠(yuǎn)程安裝器或手動(dòng)下載的二進(jìn)制重試空輸出報(bào)告未產(chǎn)生任何文本絕不能將其包裝成一次成功的轉(zhuǎn)換——源碼中空結(jié)果會(huì)拋出Document conversion produced no text且不會(huì)落盤測(cè)試用例已覆蓋掃描版/純圖片 PDF需要 OCR而本工具不提供OCR應(yīng)如實(shí)告知用戶另行選擇具備 OCR 的路徑Windows ARM64上游firecrawl/anydoc目前未發(fā)布該平臺(tái)的原生綁定因此轉(zhuǎn)換在該平臺(tái)不可用倉(cāng)庫(kù)中亦有對(duì)應(yīng)注釋佐證見 fileExtensions.ts此外工具錯(cuò)誤會(huì)以Error: message文本形式返回并標(biāo)記isErrorAgent 應(yīng)當(dāng)讀取報(bào)錯(cuò)信息修正調(diào)用而不是盲目重試相同參數(shù)轉(zhuǎn)換過程也尊重 AbortSignal可被會(huì)話取消。八、實(shí)戰(zhàn)示例總結(jié)一份 PPT官方參考文檔給出了最典型的使用場(chǎng)景——Summarizereports/q3-review.pptx。完整執(zhí)行序列如下調(diào)用mcp__cherry-tools__to_markdown參數(shù)path: reports/q3-review.pptx相對(duì)會(huì)話工作區(qū)的路徑拿到返回的臨時(shí) Markdown 絕對(duì)路徑與字符數(shù)用普通文件工具對(duì)返回路徑按切片讀取或搜索相關(guān)章節(jié)基于切片內(nèi)容完成總結(jié)并回復(fù)用戶。過程中不要安裝獨(dú)立的文檔轉(zhuǎn)換 CLI也不要把完整 Markdown 一次性加載進(jìn)模型上下文——前者違反不繞行安裝原則后者會(huì)無謂消耗上下文窗口。九、源碼級(jí)調(diào)用鏈與驗(yàn)證從工具名到最終落盤完整調(diào)用鏈為mcp__cherry-tools__to_markdown → CherryBuiltinToolsServerMCP 分發(fā)見 cherryBuiltinTools.ts → CherryDocumentTools.call參數(shù)校驗(yàn)、路徑鑒權(quán)見 cherryDocumentTools.ts → resolveWorkspaceFile / resolveLocalFilerealpath 防逃逸 大小校驗(yàn) → firecrawl/anydoc 的 formatFromExtension toMarkdownBytes格式識(shí)別與轉(zhuǎn)換 → 寫入 agentDataPath/tmp/to-markdown/uuid.md → 返回 { path, chars }針對(duì)該工具的單元測(cè)試cherryDocumentTools.test.ts系統(tǒng)驗(yàn)證了以下行為結(jié)果不含文檔內(nèi)容、工作區(qū)外絕對(duì)路徑被拒、../遍歷與符號(hào)鏈接逃逸被拒、本會(huì)話附件可轉(zhuǎn)換、非本會(huì)話附件被拒、agent 數(shù)據(jù)目錄內(nèi)文件可轉(zhuǎn)換、超限文件被拒、空輸出報(bào)錯(cuò)且不落盤、24 小時(shí)過期清理。這些測(cè)試即是最佳的行為契約文檔。十、與知識(shí)庫(kù)文件處理的區(qū)別避免混淆倉(cāng)庫(kù)中還存在另一條文檔轉(zhuǎn) Markdown路徑——知識(shí)庫(kù)的文件處理流程如 localDocument 處理器它面向已入庫(kù)的 PDF 文件且僅路由 PDFknowledgeFileProcessingExts [.pdf]見 fileExtensions.ts包含本地 OCR 回退PaddleOCR等更重的處理能力。但這條路徑屬于知識(shí)庫(kù)索引側(cè)不暴露為本文所述的 MCP 工具to_markdown面向的是會(huì)話內(nèi)任意受支持的本地文檔兩者是不同入口、不同授權(quán)模型切勿混用。結(jié)語(yǔ)mcp__cherry-tools__to_markdown是 Cherry Studio Agent 會(huì)話中處理本地辦公文檔的標(biāo)準(zhǔn)入口單參數(shù)、格式自動(dòng)識(shí)別、結(jié)果落盤而非注入上下文、三類可信根嚴(yán)格鑒權(quán)、24 小時(shí)臨時(shí)文件治理配合明確的恢復(fù)策略構(gòu)成一套安全、克制、可預(yù)測(cè)的文檔轉(zhuǎn)換能力。結(jié)合本文的源碼佐證與測(cè)試契約Agent 與開發(fā)者都可以放心地在會(huì)話工作流中編排這一工具而不會(huì)觸及知識(shí)庫(kù)索引或 Shell 執(zhí)行等相鄰邊界?！久赓M(fèi)下載鏈接】cherry-studio Cherry Studio 是一款支持多個(gè) LLM 提供商的桌面客戶端項(xiàng)目地址: https://gitcode.com/CherryHQ/cherry-studio創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考