name: skill-document-converter description: 文档转换路由，支持双重调用 allowed-tools: Task

文档转换技能

薄包装器，将文档转换委托给 document-converter-agent 子代理。

上下文指针

参考（不要急切加载）：

路径: .opencode/context/core/formats/subagent-return.md
目的: 返回验证
加载时机: 仅子代理执行时

注意：此技能是一个薄包装器。上下文由委托的代理加载，而非此技能。

触发条件

此技能在以下情况激活：

直接调用

用户明确运行 /convert 命令
用户在对话中请求文件格式转换

隐式调用（在任务实现期间）

当实现代理遇到以下任何模式时：

计划步骤语言模式：

“从 [file].pdf 提取文本”
“从 [file] 提取内容”
“将 [file] 转换为 markdown”
“将 [file] 转换为 PDF”
“从 [documentation/file] 生成 PDF”
“从 [file].docx 读取内容”
“创建 [file] 的 PDF 版本”
“解析 [file].pdf 以获取内容”
“导入 [file] 内容”

文件扩展名检测：

源文件具有扩展名: .pdf, .docx, .xlsx, .pptx, .html
目标提及: “markdown”, “.md”, “PDF”, “.pdf”

任务描述关键词：

“文档转换”
“格式转换”
“从 PDF 提取”
“生成 PDF”

何时不触发

不要为以下情况调用：

读取源代码文件 (.py, .js, .lean, 等)
查看图像而不提取
不涉及格式转换的操作
文件已在目标格式中

执行

1. 输入验证

验证必需输入：

source_path - 必须提供且文件必须存在
output_path - 可选，默认为源目录并带有适当扩展名

# 验证源文件存在
if [ ! -f "$source_path" ]; then
  return error "源文件未找到: $source_path"
fi

# 如果未提供输出路径，则确定输出路径
if [ -z "$output_path" ]; then
  source_dir=$(dirname "$source_path")
  source_base=$(basename "$source_path" | sed 's/\.[^.]*$//')
  source_ext="${source_path##*.}"

  # 推断目标扩展名
  case "$source_ext" in
    pdf|docx|xlsx|pptx|html) output_path="${source_dir}/${source_base}.md" ;;
    md) output_path="${source_dir}/${source_base}.pdf" ;;
    *) return error "无法为 .$source_ext 推断输出格式" ;;
  esac
fi

2. 上下文准备

准备委托上下文：

{
  "source_path": "/absolute/path/to/source.pdf",
  "output_path": "/absolute/path/to/output.md",
  "metadata": {
    "session_id": "sess_{timestamp}_{random}",
    "delegation_depth": 1,
    "delegation_path": ["orchestrator", "convert", "skill-document-converter"]
  }
}

3. 调用子代理

关键: 您必须使用 Task 工具来生成子代理。

此技能前端元数据中的 agent 字段指定目标: document-converter-agent

必需的工具调用:

Tool: Task (NOT Skill)
Parameters:
  - subagent_type: "document-converter-agent"
  - prompt: [Include source_path, output_path, metadata]
  - description: "Convert {source_path} to {output_path}"

不要使用 Skill(document-converter-agent) - 这将失败。代理位于 .opencode/agents/, 而非 .opencode/skills/。 Skill 工具只能从 .opencode/skills/ 调用技能。

子代理将：

检测可用的转换工具
从文件扩展名确定转换方向
使用适当工具执行转换
验证输出存在且非空
返回标准化的 JSON 结果

4. 返回验证

验证返回是否匹配 subagent-return.md 模式：

状态是以下之一: converted, extracted, partial, failed
摘要非空且 <100 个令牌
存在包含输出文件路径的工件数组
元数据包含 session_id, agent_type, 委托信息

5. 返回传播

将验证后的结果返回给调用者，不做修改。

返回格式

参见 .opencode/context/core/formats/subagent-return.md 获取完整规范。

预期的成功返回:

{
  "status": "converted",
  "summary": "Successfully converted document.pdf to document.md using markitdown",
  "artifacts": [
    {
      "type": "implementation",
      "path": "/absolute/path/to/document.md",
      "summary": "Converted markdown document"
    }
  ],
  "metadata": {
    "session_id": "sess_...",
    "agent_type": "document-converter-agent",
    "delegation_depth": 1,
    "delegation_path": ["orchestrator", "convert", "skill-document-converter", "document-converter-agent"],
    "tool_used": "markitdown"
  },
  "next_steps": "Review converted document"
}

错误处理

输入验证错误

如果源文件未找到，立即返回失败状态。

不支持格式

返回失败状态并附带关于支持格式的清晰消息。

子代理错误

直接传递子代理的错误返回。

工具不可用

返回失败状态并附带安装说明。