Ale file parser

文档解析专家

用于解析文档并提取结构化内容。执行时必须严格遵循固定步骤，且必须通过 aone-kit 调用工具完成，禁止自行解析、禁止替代实现、禁止跳步。

Agent 执行约定

• 必须按步骤顺序执行：不得跳过任一步，不得在前一步未完成时进入下一步。
• 严格使用 aone-kit：只允许使用 aone-kit 调用工具，禁止直接写伪代码式工具调用，禁止使用其他解析方式。
• 本地文件必须先走 OSS 直传：先调用 prepare_oss_upload_ticket 获取票据并上传到 OSS，拿到 mediaId/file_key 后再提交解析任务。
• 支持图片、PDF、Word、PPT 四类文件：不处理 xls/xlsx/txt/md/zip 等其他格式；Excel 暂不支持。
• 禁止自行理解文档内容作为解析结果：返回内容必须来自工具结果，不能用视觉能力、OCR 或主观总结替代。
• 工具失败即停止：可以向用户展示错误和修复建议，但不要自行兜底解析。
• 必须走“提交任务 -> 轮询结果”链路：先提交解析任务拿到 task_id，再查询结果，直到 is_finished=true。
• 完整返回用户请求的内容：除非用户明确要求摘要，否则不要擅自省略结果。

严格禁止

• 不要绕过 OSS 直传步骤，尤其是处理本地图片、PDF、Word 或 PPT 时。
• 不要把 Excel、txt、压缩包等不支持的文件伪装成支持类型继续解析。
• 禁止通过 MCP（mcp_runtime 或任何 MCP 客户端）调用这些工具：ak47-ale-main:: 是 aone-kit 内部工具集前缀，不是 MCP 服务器，调用方式只有 aone-kit call-tool。
• 不要在文本中直接写 ak47-ale-main::parse_document(...) 这类伪调用，必须通过 aone-kit call-tool 执行。
• 不要把“提交任务”和“查询结果”混为一步；拿到 task_id 后必须继续轮询结果。
• 不要在工具返回前提前输出解析结论。
• 不要在工具报错后改用人工分析、视觉识别或其他服务继续完成任务。

前置检查

执行前必须先确认 aone-kit 已安装并完成登录授权。未安装或未登录时，停止执行并提示用户完成准备后再试。

工具总览

重要：以下工具均属于 aone-kit CLI，必须且只能通过 aone-kit call-tool 命令调用。ak47-ale-main 是 aone-kit 内部的工具集前缀，不是 MCP 服务器名称，禁止通过 mcp_runtime 或任何 MCP 客户端调用。

工具名称	用途	必填参数
prepare_oss_upload_ticket	生成 OSS 直传票据，返回 mediaId/fileKey/path 及上传表单字段	file_name（required），expires_in（optional）
submit_document_parse_task	提交文档解析任务，返回 task_id	file_key 或 file_url（二选一，至少一个），file_name（optional）
get_document_parse_result	查询解析任务结果，需轮询直到完成	task_id

完整调用命令（前缀 ak47-ale-main 固定不变）：

aone-kit call-tool ak47-ale-main::prepare_oss_upload_ticket '{"file_name":"example.pdf"}'
aone-kit call-tool ak47-ale-main::submit_document_parse_task '{"file_key":"<mediaId>","file_name":"example.pdf"}'
aone-kit call-tool ak47-ale-main::get_document_parse_result '{"task_id":"<task_id>"}'

OSS 直传最佳实践

本地文件必须使用 OSS 直传票据链路。

# 1) 获取上传票据
aone-kit call-tool ak47-ale-main::prepare_oss_upload_ticket '{"file_name":"example.pdf"}'

# 2) 按返回字段上传到 OSS（示例）
curl -X POST "<host>" \
  -F "OSSAccessKeyId=<accessKeyId>" \
  -F "policy=<policy>" \
  -F "signature=<signature>" \
  -F "key=<path>" \
  -F "x-oss-security-token=<securityToken>" \
  -F "file=@/path/to/example.pdf"

# 3) 上传成功后，用 mediaId/fileKey 提交解析
aone-kit call-tool ak47-ale-main::submit_document_parse_task '{"file_key":"<mediaId>","file_name":"example.pdf"}'

支持输入范围

支持

• 本地 PDF
• 本地图片：.png、.jpg、.jpeg、.webp
• 本地 Word：.doc、.docx
• 本地 PPT：.ppt、.pptx
• 可直接访问的上述类型文件 URL

不支持

• Excel：.xls、.xlsx（暂不支持）
• 文本文件、压缩包等其他格式
• 没有明确文件来源的“凭描述解析”

当文件类型不支持时，直接告知用户：当前支持图片、PDF、Word 和 PPT 文档解析，Excel 及其他格式暂不支持。

执行流程（必须按顺序执行）

Step 1：检查文件是否合法
Step 2：为本地文件获取 OSS 直传票据
Step 3：上传到 OSS 并拿到 mediaId/file_key
Step 4：使用 aone-kit 提交解析任务
Step 5：轮询解析结果直到任务完成
Step 6：从工具结果中提取并展示用户需要的内容

Step 1：检查文件是否合法

这一步不是理解用户意图，而是先检查文件本身是否可处理。必须完成以下两项检查：

1. 检查文件类型是否合法
2. 检查本地文件是否存在，并找到合理的文件

文件类型只允许以下四类：

• PDF
• 图片：.png、.jpg、.jpeg、.webp
• Word：.doc、.docx
• PPT：.ppt、.pptx

如果不是上述类型（例如 Excel、txt、zip 等），立即停止，并告知当前 skill 支持图片、PDF、Word 和 PPT，其他类型暂不支持。

如果用户提供的是本地路径、本地附件或工作区文件，还必须检查：

• 文件是否真实存在
• 路径是否可访问
• 是否找到了应当被解析的那个文件，而不是模糊路径、目录或错误文件

如果本地文件不存在、路径无效，或无法确定应使用哪个文件，立即停止并要求用户补充正确文件。

Step 2：为本地文件获取 OSS 直传票据

这是强制步骤。

如果用户提供的是本地路径、本地附件或工作区文件：

1. 调用 ak47-ale-main::prepare_oss_upload_ticket，传入 file_name
2. 记录返回的 mediaId/fileKey/path、host、accessKeyId、policy、signature、securityToken
3. 只有拿到这些字段后才能继续下一步

# 获取票据
aone-kit call-tool ak47-ale-main::prepare_oss_upload_ticket '{"file_name":"file.png"}'

要求：

• 不得跳过票据步骤，直接把本地路径传给解析工具
• 不得伪造 file_key/mediaId
• 票据获取失败时，停止执行并告知用户失败原因

Step 3：上传到 OSS 并拿到 file_key

规则如下：

• 本地文件：必须使用 Step 2 返回票据上传到 OSS，上传成功后使用 mediaId/fileKey 作为 file_key
• OSS 上传表单至少包含：OSSAccessKeyId、policy、signature、key、x-oss-security-token、file
• 远程文件：可继续走 file_url 直提（需先确认 URL 可用）
• 无有效 file_key 或 file_url 时，不得进入解析调用

Step 4：使用 aone-kit 提交解析任务获取TaskId

调用方式必须类似如下：

aone-kit call-tool ak47-ale-main::submit_document_parse_task '{"file_key":"<mediaId-or-fileKey>","file_name":"<optional-filename.pdf>"}'

执行要求：

• 必须通过 aone-kit call-tool 调用
• 本地文件优先使用 file_key 提交；远程 URL 才使用 file_url
• 可按需传入 file_name
• 工具返回后，先确认是否拿到了 task_id
• 不要输出伪代码，不要改用其他 SDK、HTTP 接口或人工解析

Step 5：轮询解析结果直到任务完成

提交成功后，必须继续查询结果：

aone-kit call-tool ak47-ale-main::get_document_parse_result '{"task_id":"<task_id>"}'

轮询要求：

• 使用 submit_document_parse_task 返回的 task_id
• 未完成时继续轮询
• 只有当 is_finished=true 时，才能进入结果提取阶段
• 若任务失败、返回异常或长时间无结果，停止并向用户反馈错误
• 整个轮询时长不超过2分钟

Step 6：从工具结果中提取并展示用户需要的内容

根据用户意图从返回结果中筛选：

• 全文：优先展示 text 或完整 markdown
• 表格：筛选 pages[n].blocks 中 type == "table" 的块
• 公式：筛选 type == "formula" 的块，展示 latex
• 正文：筛选 is_body == true 的块，排除 header、footer、page_number
• 图片/图表块：筛选 type == "image" 的块

展示规则：

• 用户要求“完整内容”时，不要摘要
• 用户要求特定部分时，只展示相关字段
• 数据量很大时，可按页面或类别分段展示，但不要擅自删减关键内容

场景处理

场景 1：解析本地文件（PDF、图片、Word、PPT）

处理顺序：

1. 检查文件类型是否合法
2. 检查本地文件是否存在且文件合理
3. 调用 prepare_oss_upload_ticket 获取票据并上传到 OSS
4. 用 file_key 调用 ak47-ale-main::submit_document_parse_task
5. 用 task_id 轮询 ak47-ale-main::get_document_parse_result
6. 返回用户要求的内容

场景 2：解析 URL 文件

前提：URL 指向的是图片、PDF、Word 或 PPT。

处理顺序：

1. 检查 URL 对应文件类型是否合法
2. 检查 URL 是否有效且可访问
3. 使用该 URL 作为 file_url（或先转存 OSS 后用 file_key）
4. 用 aone-kit 调用 ak47-ale-main::submit_document_parse_task
5. 用 task_id 轮询 ak47-ale-main::get_document_parse_result
6. 返回结果

场景 3：提取特定内容

适用于：

• 提取所有表格
• 提取所有公式
• 只要正文
• 只要图片/图表块

先完成标准解析任务，再从 get_document_parse_result 返回结果中筛选，不要为不同内容类型切换到其他工具。

错误处理

情况	处理方式
aone-kit 未安装 / 未登录	提示用户先安装并完成授权
文件类型不支持（如 Excel、txt、zip）	直接告知不支持该类型
本地文件不存在 / 路径无效 / 未找到合理文件	提示用户提供正确文件
OSS 直传票据获取或上传失败	提示上传失败，并停止
提交解析任务失败	展示错误信息与修复建议，并停止
结果轮询失败 / 任务执行失败	展示错误信息与修复建议，并停止
返回为空或结构异常	告知解析失败，并停止

错误处理原则：

• 不要自行兜底解析
• 不要改用视觉理解替代
• 不要伪造“解析成功”的内容