Document Conversion zh CN

文档转换

语言： English · 简体中文

LWC 可以把 Microsoft MarkItDown 或 Firecrawl Anydoc 接入一项受控本地转换流程，将一份经过授权的非 Markdown 文件转换成新的、可审核的 UTF-8 Markdown。

转换能力可选、默认关闭，并且与知识整合相互独立。转换结果只有经过显式 Source 加入与整合后，才会进入 Wiki 记忆。

什么时候使用

任务需要把本地 PDF、Office 文档、EPUB 或所选 adapter 支持的其他格式变成可审核 Markdown 时，可以使用转换。

以下情况应跳过：

• 输入已经是 Markdown 或纯文本；
• 无需派生文件也能安全审核来源；
• 普通召回已经足以回答问题；
• adapter 无法保留当前决策需要的信息。

格式支持由所选 adapter 及其已安装 extras 决定。LWC 不承诺每种格式都能无损转换。

选择一个可选 Adapter

先检查有效配置：

lwc --scope project config show

说明本地文件访问影响并取得授权后，只安装和选择一个 adapter。

Firecrawl Anydoc：

npm install --global @firecrawl/anydoc
lwc --scope project config set --trans anydoc

Microsoft MarkItDown 及全部可选格式 extras：

python3 -m pip install 'markitdown[all]'
lwc --scope project config set --trans markitdown

LWC 不会安装任何 adapter，不会静默切换引擎，也不会在两者之间自动回退。所选可执行文件必须能够从 PATH 找到。

超时与 Adapter 参数

默认超时为 120 秒，允许范围为 1–900 秒。配置可以替换所选引擎的参数列表：

lwc --scope project config set \
  --trans markitdown \
  --trans-timeout 300 \
  --trans-arg --keep-data-uris

LWC 会在执行时再次应用对应引擎的参数白名单。额外位置输入、输出参数、-- 注入和不受支持的选项都会被拒绝，配置无法取代 LWC 控制的输入或输出路径。

凭证不得进入 --trans-arg、配置文件、日志或生成的 Markdown。Adapter 功能确实需要凭证时，应使用其官方环境变量机制，并确保凭证不进入持久输出。

转换一份文件

lwc --scope project trans docs/report.docx --output converted/report.md

输入必须是现有普通文件，且不得超过 64 MiB。在项目作用域中，项目根之外的路径需要为本次调用显式确认：

lwc --scope project trans ../shared/report.pdf \
  --output converted/report.md \
  --allow-external-source

只有确认准确外部文件属于当前授权任务后才能使用该参数。符号链接解析不能绕过项目边界。

安全发布输出

输出路径必须：

• 指向一个新文件；
• 与输入不同；
• 具有可用的真实父目录；
• 不超过 64 MiB；
• 包含非空、有效的 UTF-8。

LWC 先把 adapter 输出写入私密临时文件，对整个进程树执行配置超时，再校验并以 create-new 语义发布。它不会覆盖现有目标；并发创建了同一路径时会报告冲突，而不是替换文件。

转换回执包含：

• 选中的引擎；
• 规范化输入路径；
• 输出路径；
• 输出字节数；
• 输出 SHA-256 摘要。

回执只能证明最终发布了哪些字节，不能证明转换完整，也不能证明来源已经进入 Wiki。

整合前先审核

完整检查 Markdown 中是否存在：

• 丢失页面、工作表、幻灯片、图片、表格或脚注；
• 被破坏的标题层级或阅读顺序；
• OCR 错误和字符丢失；
• 意外出现的凭证或隐私数据；
• 会改变含义的 adapter 警告。

确认派生文档确实应进入持久记忆后，再开始独立的正常整合流程：

lwc source add converted/report.md

该命令会建立自己的不可变 Source 回执、ingest 任务、引用和审核义务。单纯转换不会创建这些内容，也不会写入 LWC operation log。

Agent Readiness

生命周期 readiness 会报告：

• 有效 md_trans 设置及其来源；
• PATH 中检测到的 adapter；
• 所选可执行文件是否可用；
• 每个受支持 adapter 的配置命令。

只有任务确实需要转换时，Hook 才应说明 adapter 尚未选择或缺失；它绝不能自动安装或启用 adapter。

完成证据

转换只有满足以下条件才算完成：

• 配置明确一个 adapter、超时和经过审核的参数；
• 准确输入路径已经获得授权；
• 新的项目范围内 UTF-8 Markdown 已发布，且没有覆盖现有文件；
• 输出字节数和 SHA-256 回执与文件一致；
• 完整 Markdown 已通过内容与敏感信息审核；
• 需要整合时，另有独立 Source 与引用生命周期。

下一篇：MCP 服务与 lwc_explore