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 Code | 含义 | 处理 |
|---|
| 0 | 成功 | 读取 stdout JSON，按下方"结果回复模板"格式报告结果 |
| 1 | 失败 | 读取 stdout JSON 中的 error_msg，报告错误 |
| 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 字段的值，不要自行拼接或截断
下载链接展示（重要）
返回 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 小时有效）。
更多参考
