Cherry Studio 本地文档转 Markdown 完全指南mcp__cherry-tools__to_markdown 工具的用法、边界与原理【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 通过内置 MCP 服务器向 Agent 注入了一组第一方工具其中mcp__cherry-tools__to_markdown负责把受支持的本地文档Word、PPT、Excel、OpenDocument、PDF 等转换为 Markdown。本文以官方技能参考 documents.md 为骨架结合仓库源码与测试用例系统讲解该工具的路由定位、调用契约、路径授权边界、输出管理、恢复策略与底层实现帮助读者以及阅读本文的 Agent/LLM在会话中安全、准确地使用这一能力。一、工具定位与知识库、Shell 的边界to_markdown解决的是**读取一份本地文档的结构化内容**问题——当普通文本读取工具无法处理 Office/PDF 等二进制格式时由它来接管。官方路由表SKILL.md明确区分了三条路径本地文档读取/转换→mcp__cherry-tools__to_markdown然后按需读取返回的临时 Markdown 文件知识库问答→mcp__cherry-tools__kb_list→kb_search→kb_read这些工具检索的是已被 Cherry 索引过的文档而非任意本地文件Shell 执行→ 项目捆绑的bun/uv/uvx/rg运行时用于跑脚本、执行一次性工具、搜索代码。三者互不替代to_markdown不检索知识库也不是通用 Shell 替代品。从源码看该工具由独立的领域提供器CherryDocumentTools实现并由CherryBuiltinToolsServer聚合进名为cherry-tools的 MCP server见 cherryBuiltinTools.ts与其他领域工具CherryKnowledgeTools、CherryAutonomyTools、CherryCliTools并列注册。二、工作流一次完整的文档转换官方参考文档给出了标准调用序列结合源码 cherryDocumentTools.ts 可以还原完整流程传入路径调用工具时传入一个path参数——可以是相对会话工作区的路径也可以是绝对路径须属于本会话授权范围见下文路径授权一节路径解析与鉴权工具先尝试把路径解析到会话工作区内失败后再尝试 agent 数据目录与会话附件等可信根。任何越权路径都会在转换开始前被拒绝格式识别加载firecrawl/anydoc转换库通过formatFromExtension(path.extname(...))取扩展名对应的格式再调用toMarkdownBytes完成转换该库也会从文件内容识别格式扩展名仅作兜底写入临时文件转换结果被整体写入 agent 私有的临时 Markdown 文件位于agentDataPath/tmp/to-markdown/uuid.md以wx标志创建返回结果工具结果只包含该临时文件的绝对路径和字符数不会把整篇文档塞进模型上下文后续读取Agent 用普通文件工具对返回路径做切片读取、搜索或按用户要求复制到最终路径。关键设计结果不注入上下文。工具故意只回传{ path, chars }避免大文档撑爆上下文窗口。这一点由输出 Schema 强制约束见 builtinTools.ts测试 cherryDocumentTools.test.ts 也验证了转换结果不包含在工具返回值中这一行为。三、支持的输入格式官方参考文档给出的支持矩阵如下类别扩展名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定义并内嵌进工具描述与参数说明中见 builtinTools.ts。值得注意的格式识别细节内容优先、扩展名兜底转换器会从文件内容识别可辨识的格式识别失败时回退到扩展名判断CSV 无文件签名CSV 没有内容特征可用于识别因此必须使用.csv扩展名才能被正确路由单参数约束工具目前只接受path一个必填参数不接受输出路径、格式覆盖、页码范围、密码或 OCR 选项——格式判断完全交由转换器自主决定。四、参数与返回契约path参数的 Schema 约束见 builtinTools.ts字符串类型调用前会trim()最小长度 1非空最大长度 4096 字符语义相对路径从会话工作区解析绝对路径必须是本会话已公布的附件或位于 agent 数据目录之下。返回值 SchematoMarkdownOutputSchema{ path: 绝对路径转换出的临时 Markdown 文件需要时按切片读取, chars: 写入 Markdown 文件的字符数非负整数 }chars对应源码中markdown.length即转换结果去除首尾空白后的字符数可用于让 Agent 判断文件规模、决定切片读取策略。五、路径授权与安全边界该工具无需审批auto-approved因此越权路径必须在转换发生前被拦截。源码中的授权逻辑cherryDocumentTools.ts 的resolveDocumentSource定义了三个可信根会话工作区相对路径或落在工作区内的绝对路径通过 WorkspaceFileGuard.ts 的resolveWorkspaceFile解析——它先用realpath规范化目标路径再校验其是否仍位于工作区根之内从而挫败..相对遍历与符号链接逃逸Agent 数据目录Agent 自己下载或生成的文档所在目录agentDataPath通过isSameOrInside做包含性校验见 path.ts本会话附件仅限本会话公布的托管文件——授权采用精确物理路径匹配而不是父目录匹配。测试用例验证了与已授权附件共享父目录的兄弟文件不会被授权这一边界见 cherryDocumentTools.test.ts。除路径外还有两道硬约束常规文件源必须是可读的常规文件lstat校验目录等特殊文件被拒绝大小限制源文件不得超过工具的字节上限。源码中MAX_FILE_SIZE_BYTES 100 * MB见 downloadAsBase64.ts且在读取前stat与读取后实际字节数双重校验防止文件在读取间隙被替换/增长绕过限制见 localFileResolver.ts。六、临时输出管理agent 私有目录与 24 小时清理转换结果统一写入agentDataPath/tmp/to-markdown/目录文件名是随机 UUID避免与其他会话产物冲突wx创建标志保证不覆盖已存在文件。源码中的cleanupStaleOutputs会在每次转换时清理超过 24 小时OUTPUT_MAX_AGE_MS 24 * 60 * 60 * 1000未修改的.md临时文件只清理该目录内的 Markdown 文件、不影响近期产物。测试用例removes stale Markdown outputs while preserving recent files用 25 小时前的旧文件验证了这一行为。对 Agent 的实操含义临时文件是私有且会过期的需要长期保留的内容应复制到用户要求的最终路径读取时应按切片进行而不是一次性载入全文。七、恢复策略与已知限制官方参考文档给出了明确的故障处理矩阵每一条都对应可验证的源码行为情况处理方式工具不可用本会话的文档转换能力不可用不要在用户不知情的情况下安装或调用替代转换器不支持或不可读的文件报告转换器错误不要通过npm、bun x、npx、直接mise、远程安装器或手动下载的二进制重试空输出报告未产生任何文本绝不能将其包装成一次成功的转换——源码中空结果会抛出Document conversion produced no text且不会落盘测试用例已覆盖扫描版/纯图片 PDF需要 OCR而本工具不提供OCR应如实告知用户另行选择具备 OCR 的路径Windows ARM64上游firecrawl/anydoc目前未发布该平台的原生绑定因此转换在该平台不可用仓库中亦有对应注释佐证见 fileExtensions.ts此外工具错误会以Error: message文本形式返回并标记isErrorAgent 应当读取报错信息修正调用而不是盲目重试相同参数转换过程也尊重 AbortSignal可被会话取消。八、实战示例总结一份 PPT官方参考文档给出了最典型的使用场景——Summarizereports/q3-review.pptx。完整执行序列如下调用mcp__cherry-tools__to_markdown参数path: reports/q3-review.pptx相对会话工作区的路径拿到返回的临时 Markdown 绝对路径与字符数用普通文件工具对返回路径按切片读取或搜索相关章节基于切片内容完成总结并回复用户。过程中不要安装独立的文档转换 CLI也不要把完整 Markdown 一次性加载进模型上下文——前者违反不绕行安装原则后者会无谓消耗上下文窗口。九、源码级调用链与验证从工具名到最终落盘完整调用链为mcp__cherry-tools__to_markdown → CherryBuiltinToolsServerMCP 分发见 cherryBuiltinTools.ts → CherryDocumentTools.call参数校验、路径鉴权见 cherryDocumentTools.ts → resolveWorkspaceFile / resolveLocalFilerealpath 防逃逸 大小校验 → firecrawl/anydoc 的 formatFromExtension toMarkdownBytes格式识别与转换 → 写入 agentDataPath/tmp/to-markdown/uuid.md → 返回 { path, chars }针对该工具的单元测试cherryDocumentTools.test.ts系统验证了以下行为结果不含文档内容、工作区外绝对路径被拒、../遍历与符号链接逃逸被拒、本会话附件可转换、非本会话附件被拒、agent 数据目录内文件可转换、超限文件被拒、空输出报错且不落盘、24 小时过期清理。这些测试即是最佳的行为契约文档。十、与知识库文件处理的区别避免混淆仓库中还存在另一条文档转 Markdown路径——知识库的文件处理流程如 localDocument 处理器它面向已入库的 PDF 文件且仅路由 PDFknowledgeFileProcessingExts [.pdf]见 fileExtensions.ts包含本地 OCR 回退PaddleOCR等更重的处理能力。但这条路径属于知识库索引侧不暴露为本文所述的 MCP 工具to_markdown面向的是会话内任意受支持的本地文档两者是不同入口、不同授权模型切勿混用。结语mcp__cherry-tools__to_markdown是 Cherry Studio Agent 会话中处理本地办公文档的标准入口单参数、格式自动识别、结果落盘而非注入上下文、三类可信根严格鉴权、24 小时临时文件治理配合明确的恢复策略构成一套安全、克制、可预测的文档转换能力。结合本文的源码佐证与测试契约Agent 与开发者都可以放心地在会话工作流中编排这一工具而不会触及知识库索引或 Shell 执行等相邻边界。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio 本地文档转 Markdown 完全指南：mcp__cherry-tools__to_markdown 工具的用法、边界与原理
Cherry Studio 本地文档转 Markdown 完全指南mcp__cherry-tools__to_markdown 工具的用法、边界与原理【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 通过内置 MCP 服务器向 Agent 注入了一组第一方工具其中mcp__cherry-tools__to_markdown负责把受支持的本地文档Word、PPT、Excel、OpenDocument、PDF 等转换为 Markdown。本文以官方技能参考 documents.md 为骨架结合仓库源码与测试用例系统讲解该工具的路由定位、调用契约、路径授权边界、输出管理、恢复策略与底层实现帮助读者以及阅读本文的 Agent/LLM在会话中安全、准确地使用这一能力。一、工具定位与知识库、Shell 的边界to_markdown解决的是**读取一份本地文档的结构化内容**问题——当普通文本读取工具无法处理 Office/PDF 等二进制格式时由它来接管。官方路由表SKILL.md明确区分了三条路径本地文档读取/转换→mcp__cherry-tools__to_markdown然后按需读取返回的临时 Markdown 文件知识库问答→mcp__cherry-tools__kb_list→kb_search→kb_read这些工具检索的是已被 Cherry 索引过的文档而非任意本地文件Shell 执行→ 项目捆绑的bun/uv/uvx/rg运行时用于跑脚本、执行一次性工具、搜索代码。三者互不替代to_markdown不检索知识库也不是通用 Shell 替代品。从源码看该工具由独立的领域提供器CherryDocumentTools实现并由CherryBuiltinToolsServer聚合进名为cherry-tools的 MCP server见 cherryBuiltinTools.ts与其他领域工具CherryKnowledgeTools、CherryAutonomyTools、CherryCliTools并列注册。二、工作流一次完整的文档转换官方参考文档给出了标准调用序列结合源码 cherryDocumentTools.ts 可以还原完整流程传入路径调用工具时传入一个path参数——可以是相对会话工作区的路径也可以是绝对路径须属于本会话授权范围见下文路径授权一节路径解析与鉴权工具先尝试把路径解析到会话工作区内失败后再尝试 agent 数据目录与会话附件等可信根。任何越权路径都会在转换开始前被拒绝格式识别加载firecrawl/anydoc转换库通过formatFromExtension(path.extname(...))取扩展名对应的格式再调用toMarkdownBytes完成转换该库也会从文件内容识别格式扩展名仅作兜底写入临时文件转换结果被整体写入 agent 私有的临时 Markdown 文件位于agentDataPath/tmp/to-markdown/uuid.md以wx标志创建返回结果工具结果只包含该临时文件的绝对路径和字符数不会把整篇文档塞进模型上下文后续读取Agent 用普通文件工具对返回路径做切片读取、搜索或按用户要求复制到最终路径。关键设计结果不注入上下文。工具故意只回传{ path, chars }避免大文档撑爆上下文窗口。这一点由输出 Schema 强制约束见 builtinTools.ts测试 cherryDocumentTools.test.ts 也验证了转换结果不包含在工具返回值中这一行为。三、支持的输入格式官方参考文档给出的支持矩阵如下类别扩展名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定义并内嵌进工具描述与参数说明中见 builtinTools.ts。值得注意的格式识别细节内容优先、扩展名兜底转换器会从文件内容识别可辨识的格式识别失败时回退到扩展名判断CSV 无文件签名CSV 没有内容特征可用于识别因此必须使用.csv扩展名才能被正确路由单参数约束工具目前只接受path一个必填参数不接受输出路径、格式覆盖、页码范围、密码或 OCR 选项——格式判断完全交由转换器自主决定。四、参数与返回契约path参数的 Schema 约束见 builtinTools.ts字符串类型调用前会trim()最小长度 1非空最大长度 4096 字符语义相对路径从会话工作区解析绝对路径必须是本会话已公布的附件或位于 agent 数据目录之下。返回值 SchematoMarkdownOutputSchema{ path: 绝对路径转换出的临时 Markdown 文件需要时按切片读取, chars: 写入 Markdown 文件的字符数非负整数 }chars对应源码中markdown.length即转换结果去除首尾空白后的字符数可用于让 Agent 判断文件规模、决定切片读取策略。五、路径授权与安全边界该工具无需审批auto-approved因此越权路径必须在转换发生前被拦截。源码中的授权逻辑cherryDocumentTools.ts 的resolveDocumentSource定义了三个可信根会话工作区相对路径或落在工作区内的绝对路径通过 WorkspaceFileGuard.ts 的resolveWorkspaceFile解析——它先用realpath规范化目标路径再校验其是否仍位于工作区根之内从而挫败..相对遍历与符号链接逃逸Agent 数据目录Agent 自己下载或生成的文档所在目录agentDataPath通过isSameOrInside做包含性校验见 path.ts本会话附件仅限本会话公布的托管文件——授权采用精确物理路径匹配而不是父目录匹配。测试用例验证了与已授权附件共享父目录的兄弟文件不会被授权这一边界见 cherryDocumentTools.test.ts。除路径外还有两道硬约束常规文件源必须是可读的常规文件lstat校验目录等特殊文件被拒绝大小限制源文件不得超过工具的字节上限。源码中MAX_FILE_SIZE_BYTES 100 * MB见 downloadAsBase64.ts且在读取前stat与读取后实际字节数双重校验防止文件在读取间隙被替换/增长绕过限制见 localFileResolver.ts。六、临时输出管理agent 私有目录与 24 小时清理转换结果统一写入agentDataPath/tmp/to-markdown/目录文件名是随机 UUID避免与其他会话产物冲突wx创建标志保证不覆盖已存在文件。源码中的cleanupStaleOutputs会在每次转换时清理超过 24 小时OUTPUT_MAX_AGE_MS 24 * 60 * 60 * 1000未修改的.md临时文件只清理该目录内的 Markdown 文件、不影响近期产物。测试用例removes stale Markdown outputs while preserving recent files用 25 小时前的旧文件验证了这一行为。对 Agent 的实操含义临时文件是私有且会过期的需要长期保留的内容应复制到用户要求的最终路径读取时应按切片进行而不是一次性载入全文。七、恢复策略与已知限制官方参考文档给出了明确的故障处理矩阵每一条都对应可验证的源码行为情况处理方式工具不可用本会话的文档转换能力不可用不要在用户不知情的情况下安装或调用替代转换器不支持或不可读的文件报告转换器错误不要通过npm、bun x、npx、直接mise、远程安装器或手动下载的二进制重试空输出报告未产生任何文本绝不能将其包装成一次成功的转换——源码中空结果会抛出Document conversion produced no text且不会落盘测试用例已覆盖扫描版/纯图片 PDF需要 OCR而本工具不提供OCR应如实告知用户另行选择具备 OCR 的路径Windows ARM64上游firecrawl/anydoc目前未发布该平台的原生绑定因此转换在该平台不可用仓库中亦有对应注释佐证见 fileExtensions.ts此外工具错误会以Error: message文本形式返回并标记isErrorAgent 应当读取报错信息修正调用而不是盲目重试相同参数转换过程也尊重 AbortSignal可被会话取消。八、实战示例总结一份 PPT官方参考文档给出了最典型的使用场景——Summarizereports/q3-review.pptx。完整执行序列如下调用mcp__cherry-tools__to_markdown参数path: reports/q3-review.pptx相对会话工作区的路径拿到返回的临时 Markdown 绝对路径与字符数用普通文件工具对返回路径按切片读取或搜索相关章节基于切片内容完成总结并回复用户。过程中不要安装独立的文档转换 CLI也不要把完整 Markdown 一次性加载进模型上下文——前者违反不绕行安装原则后者会无谓消耗上下文窗口。九、源码级调用链与验证从工具名到最终落盘完整调用链为mcp__cherry-tools__to_markdown → CherryBuiltinToolsServerMCP 分发见 cherryBuiltinTools.ts → CherryDocumentTools.call参数校验、路径鉴权见 cherryDocumentTools.ts → resolveWorkspaceFile / resolveLocalFilerealpath 防逃逸 大小校验 → firecrawl/anydoc 的 formatFromExtension toMarkdownBytes格式识别与转换 → 写入 agentDataPath/tmp/to-markdown/uuid.md → 返回 { path, chars }针对该工具的单元测试cherryDocumentTools.test.ts系统验证了以下行为结果不含文档内容、工作区外绝对路径被拒、../遍历与符号链接逃逸被拒、本会话附件可转换、非本会话附件被拒、agent 数据目录内文件可转换、超限文件被拒、空输出报错且不落盘、24 小时过期清理。这些测试即是最佳的行为契约文档。十、与知识库文件处理的区别避免混淆仓库中还存在另一条文档转 Markdown路径——知识库的文件处理流程如 localDocument 处理器它面向已入库的 PDF 文件且仅路由 PDFknowledgeFileProcessingExts [.pdf]见 fileExtensions.ts包含本地 OCR 回退PaddleOCR等更重的处理能力。但这条路径属于知识库索引侧不暴露为本文所述的 MCP 工具to_markdown面向的是会话内任意受支持的本地文档两者是不同入口、不同授权模型切勿混用。结语mcp__cherry-tools__to_markdown是 Cherry Studio Agent 会话中处理本地办公文档的标准入口单参数、格式自动识别、结果落盘而非注入上下文、三类可信根严格鉴权、24 小时临时文件治理配合明确的恢复策略构成一套安全、克制、可预测的文档转换能力。结合本文的源码佐证与测试契约Agent 与开发者都可以放心地在会话工作流中编排这一工具而不会触及知识库索引或 Shell 执行等相邻边界。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考