Skywork Document

Doc — 专业文档生成器

调用 Skywork Office Doc API，生成专业、格式精美的文档。

---

前置条件

配置 API 密钥（必需，优先完成）

此技能需要在 OpenClaw 中配置 SKYWORK_API_KEY。

如果你还没有 API 密钥，请访问： https://skywork.ai

详细设置说明请参阅： references/apikey-fetch.md

---

隐私与远程调用（使用前请阅读）

• 远程上传与处理：此技能会上传用户提供的文件，并将完整、未经删改的用户请求发送至 Skywork 服务。除非你信任该远程服务及其数据处理政策，否则请避免提交敏感或机密内容。
• 网络搜索：此技能中提及的任何网络搜索，均由 Skywork Doc API 在服务端执行，而非由这些脚本在本地执行。

---

工作流

步骤 0：意图识别（至关重要 — 请先完成此步骤）

调用任何脚本之前，先分析用户的请求并确定：

1. 用户是否提供了参考文件，或暗示需要某些文件才能继续完成写作任务？

   • 查找文件路径、附件，或“基于此 PDF”“使用上传的文档”等说法。如果你事先收集了有助于完成写作任务的信息（例如通过网络搜索或其他工具），请将其保存为文件，并在步骤 1 中将其作为参考文件传入。
   • 如果是：查找／提取文件路径 → 继续执行步骤 1
   • 如果否：跳到步骤 2

2. 输出内容应使用哪种语言？

   • 分析用户请求所用的语言或明确要求的语言。如果未指定，请根据用户使用的语言或上传文件的语言推断。
   • 设置 --language 参数：English、中文简体 等。
   • 默认值：English

3. 用户需要哪种格式？

   • 查找关键词：“Word 文档” → docx，“PDF” → pdf，“HTML” → html，“Markdown” → md
   • 如果未指定，默认格式：docx
   • 支持的格式：docx、pdf、html、md

4. 如何编写内容提示词？

   • --content 参数类似于改写查询
   • 综合用户的要求（可能来自多轮对话）
   • 具体描述结构、章节、语气和要点。避免过于冗长或偏离用户的原始要求；应贴合用户意图，确保准确性。

步骤 1：解析参考文件（用户提供文件时）

重要：

• parse_file.py 每次只处理一个文件。如果有多个文件，请多次调用。
• 如果文件路径包含空格，请用引号括起，以便正确传递参数。
• 将用户写作任务所需的所有参考材料作为文件解析。如果本次会话中已解析过某个文件，请勿重复解析，并重用其 file_id。

单个文件：

python3 <skill-dir>/scripts/parse_file.py /path/to/reference.pdf

多个文件（每个文件调用一次脚本；可并行运行以加快处理速度）：

# Parse file 1
python3 <skill-dir>/scripts/parse_file.py /path/to/file1.pdf

# Parse file 2
python3 <skill-dir>/scripts/parse_file.py /path/to/file2.xlsx

# Parse file 3
python3 <skill-dir>/scripts/parse_file.py "/path/to/file3 with blank in it.docx"

每次脚本调用的输出：

[parse] File: reference.pdf (2,458,123 bytes)
...
[success] File parsed!
  File ID:    2032146192467681280
  ...
PARSED_FILE: {"file_id":"2032146192467681280","filename":"reference.pdf","url":""}

提取所有 PARSED_FILE 输出，并将其收集到 JSON 数组中：

[
  {"file_id":"2032146192467681280","filename":"file1.pdf","url":""},
  {"file_id":"2032146192467681281","filename":"file2.xlsx","url":""},
  {"file_id":"2032146192467681282","filename":"file3.docx","url":""}
]

此数组将通过下方的 --files 参数传递给 create_doc.py。

步骤 2：创建文档

不使用参考文件：

python3 <skill-dir>/scripts/create_doc.py \
  --title "Document_Title" \
  --content "Detailed content prompt based on user requirements..." \
  --language English \
  --format docx

使用参考文件（使用从步骤 1 收集的 file_ids）：

python3 <skill-dir>/scripts/create_doc.py \
  --title "Analysis_Report" \
  --content "Based on the uploaded reference files, create a comprehensive analysis report..." \
  --files '[{"file_id":"id1","filename":"file1.pdf","url":""},{"file_id":"id2","filename":"file2.xlsx","url":""}]' \
  --language English \
  --format docx

title 字段不得包含空格。

输出：

[doc] Creating document: "Analysis Report"
...
[success] Document created!
  File ID:   abc-123
  Path:      /output/doc/some_file.html
  URL:       https://...
  Time:      15.2s

第 3 步：交付结果

create_doc.py 运行完成后，解析最终的 JSON 输出。其中包含用户访问文档的两种方式——必须同时提供：

• file_url — 远程下载链接（云端 URL）。请将其设为可点击的超链接，方便用户在浏览器中打开或分享。
• file_path — 文件自动下载到用户设备上的本地绝对路径。请明确告知此路径，方便用户立即找到文件，无需手动下载。

回复示例（根据用户使用的语言调整措辞）：

文档已就绪！

• 下载链接：巴西电网行业及充电桩市场调研报告.docx
• 本地文件：/Users/alice/Downloads/巴西电网行业及充电桩市场调研报告.docx

如果 file_path 为空（下载失败），仍需提供 file_url，并告知用户可以手动下载。

---

脚本参数

parse_file.py

• file - 参考文件路径（必填）
• --json - 以 JSON 格式输出完整结果（可选）

关键输出：PARSED_FILE: <json> — 提取此内容以用于第 2 步

create_doc.py

• --title - 文档标题（必填）
• --content - 内容提示词，描述要撰写的内容（必填）
  • 类似于改写请求——综合整理用户的要求
  • 具体说明结构、章节、语气和要点
• --files - 来自 parse_file.py 的文件对象 JSON 数组（可选）
  • 格式：[{"file_id":"xxx","filename":"yyy","url":""}]
• --language - 输出语言（可选，默认值：English）
  • 示例：English、中文简体、中文繁體、日本語、한국어、Français、Deutsch、Español，……
• --format - 输出格式（可选，默认值：docx）
  • 支持的格式：docx、pdf、html、md

---

重要说明

1. 首先识别意图 - 调用脚本前，始终先分析用户的请求。
2. 内置网页搜索 - Doc API 会根据需要自动执行网页搜索，为文档创作收集相关内容。是否预先从外部搜索资料完全由你决定——两种方式都可行。
3. 文件 ID 是桥梁 - parse_file.py 会输出 file_id → 通过 --files 传递给 create_doc.py。
4. 服务器会获取内容 - 无需手动粘贴 parsed_content；服务器会通过 file_id 获取内容。
5. 内容是改写请求 - 将用户的要求综合整理为清晰、详细的提示词。即使用户的指示很长或很复杂，也要涵盖所有要求，不要遗漏。
6. 生成需要时间 - 文档生成通常需要 5-10 分钟，复杂文档有时需要更久。
7. 脚本会自动等待 - create_doc.py 使用 SSE（服务器发送事件）保持长连接，并接收实时进度更新。脚本会自动等待最多 3~10 分钟，直至任务完成。无需手动轮询——只需等待脚本运行结束，它便会输出结果。
8. 进度显示 - 生成期间，脚本会显示实时进度条。AI Agent 应将此信息传达给用户，让用户了解预计所需时间。
9. 最终文档交付 - 重要：create_doc.py 成功执行后，输出的 JSON 中包含 file_url（远程下载链接）和 file_path（文件自动保存到本地的位置）。必须主动将两者都提供给用户：提供可点击的 file_url，让用户分享或在线打开；同时提供 file_path，让用户能立即在设备上找到文件。如果 file_path 为空，请告知用户，并提供 file_url 供其手动下载。

---

错误处理

错误	解决方案
NO_TOKEN / INVALID_TOKEN / 401	身份验证失败（在回复中保留错误代码 / 原始消息）。确认 OpenClaw 中已设置 SKYWORK_API_KEY，或更换为有效密钥（参见 references/apikey-fetch.md）。不要建议升级会员。
Cannot reach server	检查网络连接
JSON parse error	在 --files JSON 中使用双引号
权益不足	脚本或日志可能会显示类似 Insufficient benefit. Please upgrade your account at {url} 的信息——见下文

权益不足时的回复方式

检测到上述情况时，请使用用户当前使用的语言回复——不要复述英文消息。按以下模式回复：

• 传达：“抱歉，文档生成失败。使用此技能需要升级您的 Skywork 会员。”然后附上一个行动号召链接。
• 格式：用用户的语言写一句简短的话 + 一个类似 [立即升级 →](url) 的链接，或使用该语言的对应表达。
• URL：从日志 / 脚本输出中提取升级 URL（例如 at https://... 部分）。

技术说明

• 生成需要 5-10 分钟，请设置足够的超时时间。因为 create_doc.py 可能需要较长时间才能运行。随着 SSE 事件到达，向用户显示每个阶段，让用户在生成过程中了解进度。