Byted Las Document Parse

LAS-AI Document Parsing

Powerful Parser for PDF & Images: Extract structured text, tables, and data from PDF documents and IMAGES (especially extremely long screenshots and scanned files), converting them seamlessly to structured Markdown format. Powered by Bytedance LAS-AI.

设计模式

本 skill 主要采用：

• Pipeline：多步骤工作流（确认模式 → 提交 → 轮询 → 结果）
• Tool Wrapper：封装 LAS API，提供按需知识
• Inversion：在关键决策点（解析模式）先收集用户偏好

Gotchas

• 必须配置 LAS_API_KEY 环境变量，获取方式
• 本地上传文件需要配置 TOS_ACCESS_KEY 和 TOS_SECRET_KEY，获取方式
• env.sh 自动加载（无需手动 source）：自动发现 skill 目录 / 当前目录的 env.sh，仅补充缺失变量；--env-file 显式指定则强制覆盖已有值
• 如果用户报告认证失败（401），优先建议加上 --env-file 参数以确保使用最新凭证
• 长图（宽高比 < 0.334）处理耗时更长，会自动分页
• API 并发限制为 1 QPM，过快调用可能触发限流
• 断点恢复：如果会话中断，用户稍后回来提供 task_id，直接使用 check-and-notify --task-id {task_id} --output /tmp/las_parse_{task_id} --poll 即可恢复所有本地图片下载和 ZIP 打包流程。

工作流

复制此清单并跟踪进度：

解析进度：
- [ ] 步骤 0：确认解析模式
- [ ] 步骤 1：确认虚拟环境就绪
- [ ] 步骤 2：提交任务
- [ ] 步骤 3：立即回复用户
- [ ] 步骤 4：后台异步轮询

第 0 步：确认解析模式（必须先执行）

在提交任务前，必须先让用户确认解析模式。向用户展示以下信息并询问：

请选择 PDF 解析模式：

| 模式 | 说明 | 价格 |
|------|------|------|
| normal | 默认模式，不进行深度思考，速度更快，适用于绝大多数文档 | 0.02 元/页 |
| detail | 深度分析模式，精度更高但处理时间更长 | 0.04 元/页 |

推荐：如果文档结构简单、以文字为主，选择 normal；如果文档包含复杂表格、图表或需要高精度识别，选择 detail。

行为约束：

• 如果用户明确指定了模式，直接使用用户指定的模式
• 如果用户未明确指定，默认使用 normal 模式
• 确认模式后，继续执行第 1 步

第 1 步：确认虚拟环境就绪（仅首次）

首次执行命令前，将环境初始化与 submit chain 在一起，一次工具调用完成：

cd {skill_directory} && (test -d .venv || (python3 -m venv .venv && .venv/bin/pip install -r requirements.txt)) && .venv/bin/python3 scripts/skill.py [--env-file /path/to/env.sh] submit --url "{文件路径或URL}" --parse-mode {normal|detail}

如果上述命令执行成功（未报错），说明虚拟环境已就绪。后续命令无需再重复环境检查，直接使用 .venv/bin/python3 即可。

第 2 步：提交任务

首次用上方 chain 命令完成环境检查 + submit。

• 输入类型自动识别（本地PDF / 本地图片 / HTTP URL / TOS路径）
• stdout 输出一行 JSON：{"task_id": "xxx", "eta": "40秒~2分钟", "input_type": "local_image", "pages": 4}
  • 若返回了 tos_bucket / tos_prefix，须在第 4 步透传给 check-and-notify
• 建议输出目录: /tmp/las_parse_{task_id}/

第 3 步：立即回复用户（submit 成功后必须先执行此步）

submit 命令返回后，必须先回复用户再做任何其他操作（包括启动轮询）。用户在等待反馈——如果跳过此步直接进入轮询，用户会长时间看不到任何响应。

解析 stdout JSON，立刻回复：

✅ PDF 解析任务已提交
📋 任务ID: {task_id}
⏳ 预计 {eta} 完成，完成后会自动通知您，您可以继续其他操作。

回复后，在同一个响应中继续第 4 步。

第 4 步：后台异步轮询

在回复用户的同一个响应中，根据当前运行环境，选择以下第一个匹配的方案执行：

环境检测方法：

• 支持后台子代理（可 spawn subagent） → 方案 A（后台子代理轮询）
• 不支持后台子代理 → 方案 B（降级：当前对话轮询）

方案 A：后台子代理轮询（首选）

使用后台子代理执行轮询。子代理在独立上下文中运行，不阻塞主对话，完成后结果自动返回主会话。

调用后台子代理，使用如下参数：

• description: PDF解析结果轮询 ({task_id})
• prompt:

你是一个后台轮询 Agent，任务是检查 PDF 解析任务状态并返回结果。

执行以下命令（一次调用即可，脚本内部会自动进行智能动态退避轮询，无需你手动循环）:
cd {skill_directory} && .venv/bin/python3 scripts/skill.py check-and-notify --task-id {task_id} --poll [--tos-bucket {tos_bucket}]

命令会阻塞直到任务完成/失败/超时，然后输出一行 JSON 到 stdout。

根据退出码向用户报告:
- exit 0 (成功): 读取 stdout JSON，按"结果回复模板"格式向用户报告
- exit 1 (失败): 读取 stdout JSON 中的 error_msg，报告错误
- exit 3 (超时): 报告任务耗时较长，提供 task_id 供手动查询

结果回复模板（exit 0 成功时）：

  ✅ PDF 解析完成
  📄 页数: {page_count} | 表格: {table_count} | 图片: {image_count}（已下载 {image_downloaded} 张）
  📝 内容预览: {preview}
  📂 本地路径: {output_dir}/
     ├── result.md（图片已替换为本地路径）
     ├── result.full.json（完整 API 响应）
     └── images/（{image_downloaded} 张图片）
  ☁️ 打包下载: {download_link_markdown}

  - 仅当 `has_download_url` 为 true 时显示下载行
  - 若 `has_download_url` 为 false，展示 `download_url_missing_reasons` 中的原因代替下载行
  - 直接原样输出 JSON 中 `download_link_markdown` 字段的值，不要自行拼接或截断

行为约束（主 Agent 侧）：

• 调用后台子代理后，不要等待子代理完成，继续响应用户
• 子代理完成后结果会自动回传，不要主动轮询子代理状态
• 如果后台子代理不可用或调用失败，降级到方案 B

方案 B：当前对话轮询（后台子代理不可用时）

直接在当前对话中执行带 --poll 的命令，脚本内部会自动进行智能动态退避轮询：

cd {skill_directory} && .venv/bin/python3 scripts/skill.py check-and-notify --task-id {task_id} --poll [--tos-bucket {tos_bucket}]

命令会阻塞直到出结果（成功/失败/超时），一次调用即可，不要手动循环。

结果回复模板（exit 0 成功时）

✅ PDF 解析完成
📄 页数: {page_count} | 表格: {table_count} | 图片: {image_count}（已下载 {image_downloaded} 张）
📝 内容预览: {preview}
📂 本地路径: {output_dir}/
   ├── result.md（图片已替换为本地路径）
   ├── result.full.json（完整 API 响应）
   └── images/（{image_downloaded} 张图片）
☁️ 打包下载: {download_link_markdown}

• 仅当 has_download_url 为 true 时显示下载行
• 若 has_download_url 为 false，展示 download_url_missing_reasons 中的原因代替下载行
• 直接原样输出 JSON 中 download_link_markdown 字段的值，不要自行拼接或截断

下载链接展示（重要）

返回 JSON 中包含 download_link_markdown 字段，值是已拼好的完整 Markdown 链接（如 [点击下载ZIP（24小时有效）](https://...)）。

直接原样输出 download_link_markdown 的值，不要自行拼接或改写。预签名 URL 包含签名参数（?X-Tos-Algorithm=...&X-Tos-Signature=...），任何截断都会导致 403 下载失败。

作为兜底，下载链接也写入了 {output_dir}/download_url.txt。如果输出时链接被截断，引导用户从该文件获取完整链接：

cat {output_dir}/download_url.txt

不要使用 tos_internal_path 字段——它是 tos:// 内部路径，无法作为 HTTP 链接。

输出目录结构

/tmp/las_parse_{task_id}/
├── result.md              # Markdown 正文（图片 URL 已替换为本地相对路径）
├── result.full.json       # 完整 API 响应（含 detail / text_blocks / 位置信息）
├── images/                # 下载到本地的所有图片
├── images.json            # 图片清单（含原始 URL、本地路径、下载状态）
└── download_url.txt       # 完整下载链接（兜底，防止 LLM 输出截断）

配置了 --tos-bucket 时，结果会打包为 zip 上传到 TOS 并生成预签名下载 URL（默认 24 小时有效）。

更多参考

• 命令参数详解
• 使用示例 & 代码集成
• 配置说明 & 依赖安装
• API 参数说明
• 常见问题 FAQ