TencentCloud ADP - 文档转 PDF (Document to PDF)

> ADP 文档转 PDF Skill | 本 Skill 提供 Word/Excel 文件转 PDF 的能力：Word (.docx) 转 PDF、Excel (.xlsx) 转 PDF。转换为异步操作，通过 MCP 协议调用，响应格式为 JSON-RPC 2.0。

概述

本技能提供文档格式转换能力，支持将 Word 和 Excel 文件转换为 PDF 格式，并尽可能保留原文件格式样式。

重要说明

1. 本 Skill 调用的是 ADP 平台的 MCP 插件，不是腾讯云 API（lke.tencentcloudapi.com），认证方式为 Bearer Token
2. 密钥通过 ADP 平台的密钥管理页面获取
3. 共 4 个工具：WordToPDF / QueryWordToPDF / ExcelToPDF / QueryExcelToPDF，均通过 MCP 协议 调用
4. 转换为异步操作：先提交任务获取 task_id，再轮询查询结果
5. 转换完成后返回的 PDF 下载链接必须先下载到本地，再按渠道投递给用户

4 个工具说明

首次激活流程

1. 检查环境变量

首次激活时，检查环境变量 ADP_API_KEY 是否已设置。

> ⚠️ 重要：/etc/environment 文件只在登录 shell 时自动加载。Agent 通过 exec 启动的 shell 通常是非登录 shell，不会自动读取该文件。因此必须两步都检查：

# 步骤 1: 检查当前 shell 环境变量
echo $ADP_API_KEY

# 步骤 2: 如果为空，检查 /etc/environment 文件（可能存在但未加载到当前 shell）
grep "ADP_API_KEY" /etc/environment 2>/dev/null

判断逻辑：

> 💡 脚本已内置 fallback：脚本会自动依次查找 MCP 配置文件 → os.environ → /etc/environment → ~/.env → .env，即使当前 shell 未加载变量，脚本也能找到密钥。但 Agent 在执行脚本前仍建议先 source /etc/environment，确保后续命令行操作也能使用该变量。

2. 引导用户获取 API 密钥

主流程

引导用户按以下步骤操作：

1. 访问 ADP 密钥管理页面
2. 点击「新建密钥」
3. 保存密钥，发送给 agent

> ⚠️ 注意：密钥最多只能创建 2 个。如果提示已达上限，需要先删除旧的密钥再新建。

> 🔒 必须展示的提示：在引导用户访问上述链接时，每次都必须同时告知用户：如果无法访问该页面，说明当前账号权限不够，请联系管理员开通权限。

兜底流程（主流程链接未正常跳转时）

如果上述链接没有正常跳转到密钥管理页面，引导用户：

1. 访问 ADP 控制台
2. 点击「产品体验」按钮
3. 使用主账号登录
4. 点击右上角头像 → 「企业管理」 → 「密钥管理」
5. 点击「新建密钥」

3. 存储密钥

用户提供密钥后，优先写入 /etc/environment（全局生效），如果没有 sudo 权限则兜底写入项目 .env 文件。

主方案：写入 /etc/environment（推荐）

# 写入 /etc/environment（需要 sudo 权限，对所有用户和 shell 生效）
echo 'ADP_API_KEY=用户提供的密钥' | sudo tee -a /etc/environment > /dev/null

写入后，重新加载使当前会话生效：

source /etc/environment

兜底方案：写入 .env 文件（无 sudo 权限时）

如果用户没有 sudo 权限，写入项目根目录的 .env 文件：

echo 'ADP_API_KEY=用户提供的密钥' >> .env

> ⚠️ 变量名必须为 ADP_API_KEY，完全一致，不可更改，否则会影响 ADP 平台上的业务逻辑。

存储完成后，告知用户密钥已保存。

触发条件

显式触发（直接命中）

用户明确表达了文档转 PDF 意图：

• "Word转PDF"、"把Word转成PDF"、"docx转PDF"
• "Excel转PDF"、"把表格转成PDF"、"xlsx转PDF"
• "文档转PDF"、"convert to PDF"、"导出PDF"
• "把这个文件转成PDF"、"生成PDF"
• "file conversion"、"format conversion"

隐式触发

当用户提供了一个 Word 或 Excel 文件（本地路径或 URL），并要求将其转换为 PDF 格式时，自动触发。

不触发

• PDF 转 Word/Excel："把 PDF 转成 Word" → 使用 tencent-pdf-to-office-document 技能 ❌
• 图片转 Word/Excel："把图片转成文档" → 使用 tencent-Image-to-office-document 技能 ❌
• 文档翻译："翻译这个文档" → 使用 tencent-document-translation 技能 ❌
• 文档阅读/理解："帮我看看这个文档写了什么"（不需要格式转换） ❌
• PDF 合并/拆分/加水印：不在本技能范围内 ❌
• 已有更合适的 Skill ❌

执行工作流

步骤 1：收集文件信息

必须获取文件

如果用户没有提供文件，提示用户：

> 请提供需要转换为 PDF 的文件（支持 Word .docx 和 Excel .xlsx 格式，支持上传本地文件或提供公网 URL）。

缺少输入时的处理

> ⚠️ 禁止在用户未提供文件时直接报错或返回空结果。必须友好地引导用户提供必要输入。

步骤 2：确定转换类型

根据用户的文件或描述，路由到对应的工具。路由表：

模糊意图 → 展示选择题

当无法从用户描述或文件名中确定文件类型时，展示以下选择题：

> 请确认要转换的文件类型：

> 1. Word 文件 (.docx/.doc) — 将 Word 文档转换为 PDF

> 2. Excel 文件 (.xlsx/.xls) — 将 Excel 表格转换为 PDF

步骤 3：处理本地文件 — 上传获取公网 URL

> ⚠️ 仅当用户提供的是本地文件路径时需要此步骤。如果用户提供的已经是公网 URL（http:// 或 https:// 开头），直接跳到步骤 4。

本地文件需要先通过 ADP 文件托管 API 上传获取公网 COS URL。核心思路：本地文件 → Base64 编码 → 调用 ADP 文件托管 API → 获取 COS URL → 传入转换 API

使用脚本上传（推荐）：

python3 <SKILL_DIR>/scripts/doc_to_pdf.py \
  --action upload \
  --file-path "/path/to/document.docx"

ADP 文件托管 API 详情：

注意事项：

1. 使用与转换 API 相同的 ADP_API_KEY 进行认证
2. FileName 必须带文件后缀（如 .docx、.xlsx）
3. 上传成功后从响应 Data.CosUrl 字段获取公网 URL
4. 上传过程对用户透明，无需用户介入

步骤 4：调用转换 API

参考 scripts/doc_to_pdf.py 中的完整代码模板。

Agent 执行时将以下占位符替换为实际值：

操作代号表

推荐调用方式：一键转换（--auto 模式）

# Word 转 PDF — 本地文件（自动上传 + 转换 + 轮询）
python3 <SKILL_DIR>/scripts/doc_to_pdf.py \
  --action word-to-pdf \
  --file-path "/path/to/document.docx" \
  --auto

# Word 转 PDF — 公网 URL（直接转换 + 轮询）
python3 <SKILL_DIR>/scripts/doc_to_pdf.py \
  --action word-to-pdf \
  --file-url "公网URL" \
  --auto

# Excel 转 PDF — 本地文件（自动上传 + 转换 + 轮询）
python3 <SKILL_DIR>/scripts/doc_to_pdf.py \
  --action excel-to-pdf \
  --file-path "/path/to/spreadsheet.xlsx" \
  --auto

# Excel 转 PDF — 公网 URL（直接转换 + 轮询）
python3 <SKILL_DIR>/scripts/doc_to_pdf.py \
  --action excel-to-pdf \
  --file-url "公网URL" \
  --auto

> 💡 --auto 模式下，脚本会自动读取环境变量 ADP_API_KEY 中的密钥。如提供 --file-path 则自动上传到 ADP 文件托管获取公网 URL，然后提交转换任务后每隔 3 秒轮询一次，最多等待 5 分钟，直到转换完成并返回文件信息（含下载 URL，需在步骤 5 中下载到本地）。

手动分步操作（仅需调试时使用）

# 步骤 A：提交任务
python3 <SKILL_DIR>/scripts/doc_to_pdf.py \
  --api-key "YOUR_KEY" \
  --action word-to-pdf \
  --file-url "URL"

# 步骤 B：查询结果
python3 <SKILL_DIR>/scripts/doc_to_pdf.py \
  --api-key "YOUR_KEY" \
  --action query-word \
  --task-id "TASK_ID"

步骤 5：呈现结果 + 投递文件

> 🔴🔴🔴 CRITICAL — 全渠道统一文件投递规则

>

> 所有渠道都必须遵守以下三步流程：

>

> 第一步：下载到本地 — 将转换完成后返回的 PDF 文件 URL 下载到工作区目录（不要用 /tmp/）

> 第二步：确认文件存在 — 检查本地文件是否下载成功、大小是否正常

> 第三步：按渠道投递本地文件 —

> - 🟢 IM 渠道（已确认支持 filePath）（飞书 / 钉钉）→ 用 message 工具的 filePath 发送本地 PDF 文件

> - 🟡 Web / API / QQ / 企业微信 / 其他 → 调用 upload_file_for_url(本地文件路径, api_key) 获得一个新的短 URL → 以 下载文案 的 Markdown 链接形式返回

> - 🔵 IDE / CLI → 告知用户本地文件路径 / 用 open_result_view

>

> ⚠️ 关于 QQ 和企业微信：这两个渠道的文件发送能力因 Bot 框架不同差异较大，不能假设一定有 filePath 参数。默认按 Web/API 处理（上传获取新链接）。如果 Agent 运行时确认当前 QQ/企微环境支持 filePath 发文件，可以按 IM 方式处理。

>

> 🔴 核心原则：永远不要把接口直接返回的 COS 签名 URL 复制给用户。签名 URL 极长、易被截断、用户体验差。所有渠道都必须先下载到本地，再通过本地文件投递。

转换结果呈现格式

转换完成后，向用户展示格式化的结果：

### 📄 文档转 PDF 结果

**原始文件**：{文件名}
**转换类型**：{Word / Excel} → PDF
**转换状态**：✅ 转换成功

**生成结果**：已保存到 `{本地文件路径}`

> ⚠️ 所有字段必须完整输出，不可省略。

全渠道统一投递流程（三步，缺一不可）

1. 下载到本地 — 从脚本输出中提取 PDF 文件 URL → requests.get(url, timeout=120) → 保存到工作区目录 converted_output.pdf
2. 确认文件存在 — 检查文件大小是否正常（PDF 不应为 0 字节）
3. 投递本地文件 —

上传接口使用方法（脚本 doc_to_pdf.py 已内置 upload_file_for_url 函数）：

import sys
sys.path.insert(0, '<SKILL_DIR>/scripts')
from doc_to_pdf import upload_file_for_url

cos_url, error = upload_file_for_url("converted_output.pdf", api_key)
if error:
    # 上传失败，兜底：告知用户本地文件路径
    print(f"上传失败: {error}，本地文件路径: converted_output.pdf")
else:
    # 上传成功，返回下载链接
    print(f"📄 [下载 PDF 文件]({cos_url})")

✅ 正确示范（IM 渠道）：

### 📄 文档转 PDF 结果

**原始文件**：report.docx
**转换类型**：Word → PDF
**转换状态**：✅ 转换成功

**生成结果**：已保存到 `converted_output.pdf`

📎 [通过 filePath 发送 converted_output.pdf 文件给用户]

✅ 正确示范（Web/API 渠道）：

### 📄 文档转 PDF 结果

**原始文件**：report.docx
**转换类型**：Word → PDF
**转换状态**：✅ 转换成功

📄 [下载 PDF 文件](https://xxx.cos.ap-xxx.myqcloud.com/upload/xxx.pdf?sign=xxx)

⚠️ 链接有效期约 1 天，请及时下载保存。

❌ 错误示范（所有渠道都禁止）：

转换完成，PDF 链接：https://xxx.cos.ap-xxx.myqcloud.com/xxx.pdf?q-sign-algorithm=sha1&q-ak=xxx...（把接口原始签名 URL 直接贴出来）

步骤 6：渠道判断标准 + 严禁行为

6.1 全渠道统一投递原则

> 🔴 核心原则：无论任何渠道，接口返回的原始 COS 签名 URL 都不允许直接展示给用户。

>

> - 飞书/钉钉 → 下载到本地 → filePath 发送文件（用户收到的是文件消息，不是链接）

> - Web/API/QQ/企微/其他 → 下载到本地 → upload_file_for_url 重新上传 → 返回新的 Markdown 链接

> - IDE/CLI → 下载到本地 → 告知路径

>

> 为什么不直接给原始 URL？

> 1. 原始 COS 签名 URL 通常超过 300 字符，模型容易截断导致链接失效

> 2. 裸 URL 用户体验极差

> 3. IM 渠道用户期望收到的是可直接打开的文件消息，不是一个链接

6.2 如何判断当前渠道

> Agent 必须根据自身运行环境判断。如果无法确定，默认按「Web/API」处理（下载 → 上传 → 给新链接）。

> ⚠️ 关于 QQ 和企业微信：这两个渠道的 Bot 框架差异大，文件发送能力不统一（QQ Bot 可能没有 filePath、企微 Bot 需要先上传获取 mediaId）。默认按 Web/API 方式处理。如果 Agent 运行时确认当前环境确实支持 filePath 发文件，可以按飞书/钉钉方式处理。

6.3 文件保存位置

• 所有渠道：下载/保存到工作区目录（项目根目录），不要用 /tmp/（IM 渠道 filePath 不支持 /tmp 路径）
• 文件命名建议：converted_output.pdf（或根据原文件名命名，如 report.pdf）

6.4 下载远程文件到本地的代码模板

当需要下载转换后的 PDF 文件到本地时：

import requests

# 从脚本输出中提取 PDF 文件下载 URL
result_url = "提取到的完整URL"
output_filename = "converted_output.pdf"

resp = requests.get(result_url, timeout=120)
with open(output_filename, "wb") as f:
    f.write(resp.content)
print(f"文件已保存: {output_filename} ({len(resp.content)} bytes)")

6.5 上传本地文件获取新链接的代码模板

Web/API 渠道需要将本地文件转为可点击的下载链接：

import sys
sys.path.insert(0, '<SKILL_DIR>/scripts')
from doc_to_pdf import upload_file_for_url

cos_url, error = upload_file_for_url("converted_output.pdf", api_key)
if error:
    print(f"上传失败: {error}")
    # 兜底：告知用户本地文件路径
else:
    # 在回复中使用: [下载文案](cos_url)
    print(f"上传成功: {cos_url}")

6.6 严禁行为 🚫

> 以下行为是绝对禁止的，违反任何一条都是严重错误：

1. 🔴 严禁把接口返回的原始 COS 签名 URL 直接展示给用户 — 无论任何渠道，原始签名 URL 都不能出现在用户可见的消息中。必须通过「下载到本地 → 投递本地文件」或「下载到本地 → 重新上传 → 返回新链接」的方式处理
2. 🔴 严禁在 IM 渠道给用户发链接而不发文件 — 飞书/钉钉渠道，用户期望收到的是可直接打开/保存的文件消息。如果只给了一个链接，用户会认为技能出了问题
3. 🔴 严禁只说"文件已保存到本地路径"而不实际投递 — Web/API 渠道用户看不到你的本地路径，IM 渠道用户也不想要一个路径
4. 🔴 严禁跳过投递步骤 — 转换完成后必须立即执行投递，不可以只打印结果就结束
5. 🔴 严禁截断 URL — 提取文件下载 URL 时，必须提取完整内容。URL 中的 &、q-signature=xxx 等都是必要的组成部分
6. 严禁把脚本内部的 AGENT DELIVERY INSTRUCTIONS 文字原样输出给用户 — 那是给 Agent 看的内部指令，用户不应看到

常见问题

配额不足处理

当接口返回 配额不足（如 Code=3000003、quota exceeded 等错误提示）时，说明当前账号的调用额度已用完。Agent 应告知用户：

> ⚠️ 当前配额已用完，无法继续调用。请前往 ADP 购买页 购买套餐或增购包后重试。

未覆盖场景

如遇到本 Skill 未覆盖的问题，建议查阅 ADP 官方文档。

API 参考

完整的接口参数说明和响应格式，参见 references/api_docs.md。

资源文件

scripts/

• doc_to_pdf.py — 调用文档转PDF MCP API 的 Python 脚本，支持 5 种操作（upload / word-to-pdf / query-word / excel-to-pdf / query-excel）、自动轮询模式、自动读取环境变量密钥

references/

• api_docs.md — 完整 API 文档，包含 4 个工具的请求/响应格式、参数说明