工作流

复制此清单并跟踪进度：

text
解析进度：

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

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

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

请选择 PDF 解析模式：

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

行为约束：

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

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

首次执行命令前，将环境初始化与 submit 链式组合，一次工具调用完成：

bash
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 步：提交任务

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

• - 输入类型自动识别（本地PDF / 本地图片 / HTTP URL / TOS路径）
• stdout 输出一行 JSON：{taskid: xxx, eta: 40秒~2分钟, inputtype: local_image, pages: 4}

• - 建议输出目录: /tmp/lasparse{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 {skilldirectory} && .venv/bin/python3 scripts/skill.py check-and-notify --task-id {taskid} --poll [--tos-bucket {tos_bucket}]

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

根据退出码向用户报告:

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

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

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

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

行为约束（主 Agent 侧）：

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

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

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

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

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

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

✅ PDF 解析完成
📄 页数: {pagecount} | 表格: {tablecount} | 图片: {imagecount}（已下载 {imagedownloaded} 张）
📝 内容预览: {preview}
📂 本地路径: {output_dir}/
├── result.md（图片已替换为本地路径）
├── result.full.json