xparse-parse

xparse-parse

使用已安装的 xparse-cli 作为唯一的解析、身份验证、配额和文档导航执行内核。不要在 Skill 中复现其 HTTP、OAuth、配额、PDF 拆分或结果合并逻辑。

任务上下文

对于每个新的用户请求，在首次执行 xParse 命令之前，创建一个私有的 0600 JSON 文件：

{
  "schema_version": "xparse_task_context.v1",
  "user_intent": "the user's original request, in its original language",
  "tool_call_reason": "the document information needed to complete this task"
}

• 保留用户的措辞，并简要说明操作原因。
• 切勿包含隐藏推理、凭据、文档内容或最终答案。
• 仅在该请求的首次 xParse 调用中传递 --task-context <FILE>。
• 在该次调用后删除临时文件。后续命令会继承任务。
• 不要通过 shell 参数、echo 或 heredoc 传递内联 JSON。

命令完整性与结构化错误关卡

每次操作性 xparse-cli 调用都必须作为独立的 shell 命令运行。不要将其通过管道传给 head、tail、grep 或其他命令，也不要追加可能替换其退出状态的清理、打印、文件读取或其他 shell 命令。请在单独的 shell 调用中清理任务上下文。

对于每条失败的命令，解析其标准错误中的最后一个 schema_version 为 xparse_error.v1 的对象。即使 shell 包装器报告退出代码为 0，也将该对象视为失败。在执行下一条 xParse 命令之前，应用以下关卡：

• retryable=false 表示不要重试或重新解释同一逻辑操作。仅遵循声明的 next_action。对于 CONTACT_SUPPORT，报告错误和保留的标识符，然后不得再为当前请求执行 xParse 命令。
• retryable=true 允许在 Agent 层对同一逻辑操作最多重试一次。保留相同的 Task、Run、Resource，以及存在时的 operation_id。
• 更改标志、身份验证选项、选择器形式、Resource 标识符、时间，或在 task read 和 task export 之间切换，不会产生新的逻辑操作，也不会重置其重试次数。
• 除非 Task 状态或 next_action 明确要求，否则不要运行诊断性 xParse 命令。完成目标的压力不是恢复信号；正确报告失败即可完成 Agent 操作。

发生不可重试的失败后，只有在用户确认已进行外部修复或明确请求新操作后，才允许再次尝试。复用保留的 Task 和 Run 标识符；绝不要重新创建已完成的服务器端工作。

免费、免费套餐和付费路由

默认使用 --api auto。CLI 会在解析前查询服务配额，并以当前服务响应为准，而不依赖 Skill 快照。

模式	CLI 行为	适用场景
--api auto	优先使用每日免费 API 额度。当配额报告显示存在通过 AppKey 认证的免费套餐，且 free_remain_count 充足时，可通过现有的认证路由使用该套餐。	适用于受支持的 PDF 和图像处理，且为默认模式。
--api free	强制使用免费端点，不使用经过认证的免费套餐路由。	用户明确要求仅使用免费端点时。
--api paid	强制使用付费端点，并遵循服务现有的套餐／余额计费方式。	用户明确批准付费使用，或得知该格式需要付费 API 后予以批准时。

身份认证不等于获得消费许可。切勿仅因为存在 OAuth 或 AppKey 凭据就选择 --api paid。

在用户询问配额、需要解释路由失败，或准备建议付费重试之前，运行 xparse-cli quota --output json。读取所有返回的信息：

• 每日剩余免费解析页数及重置时间；
• 如有返回，则读取独立的 extraction_quota 每日限额、已用页数、剩余页数及重置时间；
• 请求是否经过身份认证；
• 如有返回，则读取认证免费套餐的总量、历史已用量及当前 free_remain_count（路由仅使用 free_remain_count）；
• 每个请求的最大页数和文件大小。

不要在 Skill 中缓存或计算可用额度。parse --api auto 会自行预检配额；如果配额在查询和执行之间发生变化，应以解析响应为准。Skill 不得承诺超出现有服务保障范围的计费保证。

设备 OAuth 和 AppKey 对应不同身份。如果配额返回 authenticated=false 或未包含 free_package，不要根据 OAuth 登录标记推断可以使用套餐。仅将当前配额响应中的字段视为可用信息。

经过身份认证的默认配额响应仍可能不包含 extraction_quota。应说明服务未返回提取额度；不要声称企业 OAuth 本身无法查询该额度，也不要用解析额度代替。仅缺少配额数据并不能证明提取功能不可用；应根据实际的提取 Task 响应判断。如果 authenticated=false，请先恢复预期的登录状态。

区分以下三种路径：

• 不带参数的 quota 会报告解析额度，并且仅在服务返回时报告结构化提取（open_kie_vlm_engine）的 extraction_quota。
• quota --service manipulation_detection 仅报告操作检测器的免费套餐。这不是提取额度，也不是提取能力检查。
• task run --task-type extract 会创建结构化提取 Task。应根据该 Task 的实际响应判断其可用性和结果，切勿根据操作检测配额响应作出判断。缺少提取配额或提取失败时，不要改用 detect-manipulation。

免费端点支持 PDF 和图像。Office、HTML、OFD 及其他格式可能需要使用 --api paid；切换模式前应说明这一点并征得用户批准。如果所有报告的免费额度来源都不足，应停止并说明当前配额，不要默默改用付费模式重试。

篡改检测（仅限国内服务）

当用户询问受支持的图像或 PDF 是否被篡改或由 AI 生成时，使用 xparse-cli detect-manipulation <FILE|URL>。这是独立于解析的服务。要查看当前套餐，请运行 xparse-cli quota --service manipulation_detection --output json，并且仅在 authenticated=true 且返回的服务为 manipulation_detection 时读取 free_package.free_remain_count。缺少 free_package 表示未知，而不是零；切勿根据未指定服务的 xparse-cli quota 命令中的 pdf_to_markdown 额度推断此套餐。如果已安装的 CLI 不识别 --service，请更新它，而不是将默认额度作为替代。CLI 会通过额度端点预先检查当前的 manipulation_detection 免费套餐。如果有免费额度，就会在不带付费标记的情况下执行一次检测。如果免费额度已用尽或无法确认，CLI 会在检测前停止；请先征求用户同意进行一次可能产生费用的调用，然后再使用 --approve-paid 重复运行命令。这只是预检查，并非费用预留或保证。后续调用中不要沿用付费批准。

如果 CLI 报告 quota service mismatch，说明所选端点未返回篡改检测额度。停止此次检测尝试，并报告响应不兼容；不要将其解读为提取服务已启用或有提取额度，也不要因此尝试其他操作。

--tamper-threshold 和 --aigc-threshold 是 [0,1] 范围内的可选 API 输入；仅在用户提出要求或为满足已商定的检测标准所需时传入。省略这些参数时，CLI 会保留服务默认值。结果默认保存到 ./xparse-results/，也可以通过 --output <DIR> 指定目录，并存放在唯一的运行文件夹中。CLI 会保存 result.json，并在服务返回 JPEG 热力图时一并保存；终端输出包含绝对路径，而非内嵌的 Base64。将服务的风险结论和风险类型作为检测信号报告，而非来源证明。不要将此仅限国内服务的请求发送到全球端点，也不要悄悄替换为其他检测器。如果已安装的 CLI 可能早于此命令，请查看 detect-manipulation --help。

选择工作流

根据输入形式和持久性需求选择，而不是根据是否已经完成身份验证来选择：

工作流选择和计费方式选择是独立的决定。根据请求的输入形式和持久性需求选择 Task 或 parse；auto、free 和 paid 只用于选择计费路径。配额、资格、授权、资金或格式方面的结果，绝不能将已接受的多文档 Task 改为逐个调用 parse。只有用户明确要求将原始范围缩小为一个真正全新的单文档操作时，才可将其视为新的 parse 操作。

• 当用户需要即时结果、转换或本地大纲／搜索导航时，对单个文档或 URL 使用 parse。
• 结构化提取是例外：首先判断新文件是属于当前对话中的提取 Task，还是一个真正全新的提取请求。对于同一目标的后续请求，即使没有使用“追加”一词，也可以视为追加。选择下面支持的来源路径；并非每次追加都必须新建 Parse Task。遵循下面的语义提取部分，而不是将解析后的内容读入 Host。
• 对于两个或更多本地文档，或用户明确需要持久化 Task ID、后续状态检查、选择性读取结果、导出、调试或继续处理时，使用持久化的 Task Runtime。因此，即使请求只有一个文件，只要明确要求持久性，也仍可使用 Task。
• Task Runtime 控制平面路由和 OAuth 身份验证在国内和海外环境中均可用。优先使用免费计费的 Task 是另一项独立能力：如果所选环境返回 TASK_FREE_MODE_UNAVAILABLE，请停止并说明原因。绝不要将 Task 替换为串行 parse 调用，也不要静默切换为付费执行。

持久化多文档 Task 运行时

对于本地文件，启动一个由服务端持久化的 Task，而不是启动多个 parse 命令：

xparse-cli task run --files '<GLOB>' --api auto

--api auto 优先使用免费服务，并在无法使用时直接失败：不会静默创建付费 Task。只有在用户明确批准付费服务行为后，才使用 --api paid。属于同一个 Task 的输入，不要并行执行各自的 parse 命令。

task run 会在服务端接受 Run 后返回。启用结构化进度时，stderr 会输出 xparse_event.v1 JSONL 流：run_accepted 会立即提供已接受的 Task/Run 标识， 而 run_status 仅在状态发生变化时发出。 Stdout 仅包含一个最终提交 JSON。保留 operation_id、task_id 和 run_id。如果提交失败或 进程丢失了响应，使用已观察到的 operation_id 和 --operation-id 重试；对于同一次逻辑提交，切勿另造一个 ID。

让 Agent 工作流保持默认的提交后返回路径。不要自动添加 --wait 或较短的固定 --timeout。当用户明确要求前台等待或等待并导出时，--wait 会轮询同一个 Run；其本地超时会返回当前已接受的标识，并带有 wait_timed_out: true 和 next_action: POLL_STATUS。它不会取消或 重新创建 Run。继续使用 task status 查询该确切的 Task 和 Run。

waiting_paid_authorization 和 waiting_funds 是已接受的 Task 状态，不是 CLI 传输失败。提交/状态 JSON 及其 next_action 是唯一依据。它们表示用户请求尚未完成：立即停止，不要再发出任何 xParse 命令——包括配额、状态、读取、导出、调试、 另一个 task run 或 parse——直到用户确认所需的外部操作。之后仅针对确切的 Task 和 Run 调用一次 task resume。

使用 task status <TASK_ID> --run-id <RUN_ID> 进行有限次数的进度检查。先等待 2 秒，然后依次延长至 5、10、20 和 30 秒；单个 Agent 轮次中的轮询时间不要超过约 两分钟。如果工作仍在运行，返回控制权并提供 ID 和当前状态。切勿仅因 Run 仍处于 scheduled 或 running 状态就启动重复的 Task。 只需一个结果时优先使用 task read；用户需要完整结果集时使用 task export。部分失败时，先运行 task debug，再选择恢复操作。仅当该已接受 Run 的 调试结果指出现有 Resource 的原始 Parse 错误代码 40423 时，才使用 task continue。 通过重复指定 --password 提供每个文件的密码；涉及多个 Resource 时，将每个值绑定为 <SELECTOR>=<PASSWORD>。这只会重新运行选定的失败 Resource，不会重新处理成功的文件。

Task 标识和状态只会向前推进：

no identifiers -> task run once
operation_id + PASSWORD_INPUT_REQUIRED -> ask for the named passwords, then replay the originating task run or task rerun --mode new-files once with that ID and the returned selectors
operation_id only after an ambiguous submission -> retry task run once with that ID
task_id + run_id -> task status for that exact Run
waiting_paid_authorization -> stop; after user approval, resume that exact Run
waiting_funds -> stop; after confirmed funding, resume that exact Run
completed -> task read or task export for that exact Run
non-retryable result-access failure -> report and stop

PASSWORD_INPUT_REQUIRED 仅允许对发起命令进行一次有文档记录的更正后重试，并使用相同的 operation_id。对于初始提交，该命令是 task run；对于现有 Task 中的新文件，该命令是 task rerun --mode new-files，且错误中可以合理地包含现有的 task_id。CLI 会透明地复用已就绪的上传内容；Agent 不得跟踪 File Asset ID，也不得决定要上传哪些文件。另一次存在歧义的提交后，如果有 operation_id，但没有 Task/Run ID，则允许进行一次不作更改的重试。一旦某次逻辑提交已接受新的 task_id 或 run_id，就绝不能再为其返回 task run。task read 或 task export 失败时，不得回退到新建 Task、串行执行 parse、使用缓存结果、改用其他选择器或切换到不同的 Run。仅在状态为 partial_failed/failed 时使用 task debug，不要用它调查结果访问返回不可重试错误的已完成 Run。

在启动、检查或恢复持久化 Task 之前，请阅读 task-runtime.md。

从 File Asset 提取语义的 Task

首先判断新文件是延续现有的提取目标，还是开始新的目标。追加时，使用用户明确提供的提取 Task ID；若用户未提供，则使用当前对话中与该目标明确相关且已被接受的唯一提取 Task。即使用户只说“再处理这份”或“还有这些文件”，没有说“追加”，也要将后续提供的文件视为追加。保留创建 Task 或上次追加时返回的提取 task_id。仅凭处于同一对话并不足以判定为追加：明确提出新的或独立的提取请求时，应开始新的 Task。如果目标或对象不明确，或有多个提取 Task 可能匹配，请在提交工作前询问。不要选择最近的 Task，也不要把 Parse Task ID 与提取 Task ID 混淆。追加失败或资源版本冲突时，绝不要改为创建替代 Task。 使用 task status <EXTRACTION_TASK_ID> 验证目标及其类型。

仅对于新的提取请求，在服务上创建一个持久化的提取 Task。不要将 Parse 结果读入 Host，也不要在本地生成最终字段值。将用户的提取请求原样保留为 instruction；不要替换为固定架构或添加字段定义。

如果已有可信的、来自 xParse 的已解析 File Asset ID，则跳过解析。使用 task add --file-id 将它们追加到现有 Task；对于新的提取请求，直接创建 Task。创建新的提取 Task 时，也可以使用刚上传且已就绪的 File Asset ID：后端只会为没有可复用解析结果的文件启动付费托管解析。不要擅自产生解析费用；如果用户尚未授权付费解析，请先征得同意。task add --file-id 仍要求资源已解析。按源文件顺序重复使用 --file-id：

xparse-cli task run --task-type extract \
  --instruction '<USER_REQUEST>' \
  --file-id <FILE_ASSET_ID>

如果用户需要独立上传，或希望保留 ID 以供日后使用，请使用 xparse-cli upload <FILE> --operation-id <OPERATION_ID>。其 JSON 会返回原始 file_id，不会解析文件。上传中断时保留 operation_id；CLI 会在复用就绪资源前检查本地 SHA-256。将返回的 ID 用作新建提取 Task 的 --file-id。如果现有解析结果可复用，后端不会为新的解析收费；否则，Task 会先进入付费托管解析流程。初始 document_count 仅统计已附加的提取资源，可能为零；submitted_file_count 则报告 CLI 提交的 ID 数量。检查 task status 以确认是否存在导入失败；绝不要根据创建响应或某一个已完成的文件推断 complete=true。

追加时，如果已安装的 CLI 支持提取功能的 task add --history-id，可以直接使用现有历史记录 ID；如果已安装的 CLI 支持托管式本地文件导入，则可以直接使用 task add <EXTRACTION_TASK_ID> <FILE>。请检查已安装 CLI 的 task add --help，确认是否支持 --history-id 或 --uploaded-file-id 和 --reconcile 等托管导入标志，不要假定某个特定的 Connector 版本支持这些选项。这两种方式都不需要新的 Parse Task。如果本地导入不可用，请通过下方的 Parse Task 流程获取已解析的 File Asset ID，并仍追加到原有提取 Task。如果只有历史记录 ID，而已安装的 CLI 无法使用它，请索要受支持的来源或 Connector 更新；不要假装 Parse Task 可以使用该 ID。绝不要创建替代提取 Task。

对于没有已解析 File Asset ID 的本地文件（包括单个文件），如果是在创建新的提取 Task，或已安装的 CLI 无法直接导入这些文件来追加，则仍应采用免费优先路径，创建持久化的 Parse Task。上方独立的 upload 路径适用于明确需要原始资源 ID 的情况；从原始 ID 创建提取任务前，必须先获得付费解析授权。追加时，分别保留 Parse Task 已接受的 task_id 和第一个 run_id，并与 <EXTRACTION_TASK_ID> 区分：

xparse-cli task run <FILE> --api auto

对所有本地源文件使用一次 task run。仅使用 task status <TASK_ID> --run-id <FIRST_RUN_ID> 轮询该首次 Run，并遵循上文定义的有界退避策略。不要使用旧 Task、重新运行的 Run 或后续 Run 作为隐式提取来源。如果首次 Run 在轮询预算用尽后仍为 scheduled 或 running，请返回其标识符和当前状态，而不是创建提取 Task。

首次 Run 状态变为 completed 后，获取稳定的 Task 资源：

xparse-cli task status <TASK_ID> --details

仅当详情响应满足以下所有不变量时，才使用此 Parse Task 的 File Asset ID 创建或追加内容：

• run.run_id 等于 <FIRST_RUN_ID>，且 run.status 为 completed；
• run.failed_count 为 0；
• run.completed_count 等于 run.total_count；
• run.total_count 等于 resources 的数量；
• 每个资源都有非空的 file_id。

按资源顺序将每个 resources[].file_id 作为重复的 --file-id 参数传入。不要调用 task export、task read 或其他会返回内容的命令来获取 File Asset ID。必须在提取前停止处理 partial_failed 和 failed 状态。等待状态需保留同一个 Task 和首次 Run，并在继续轮询前执行文档规定的用户操作。

• 仅在重放同一次结果不明确的提取创建尝试时，保持 --operation-id 不变；新建提取请求时不要复用它。
• 命令会返回 task_id、status 和 result_page_url。使用 task status <TASK_ID> 查看进度；不要猜测提取 Run ID。
• 结果 URL 的片段中包含一个短期有效的授权凭据。请原样保留返回的 URL。不要重构、持久化或打印该授权凭据，也不要将其发送到其他 API。请让有能力的 Host 直接打开此 URL；如果 Host 无法打开，请将其作为可点击链接返回。
• 创建提取 Task 会提交异步工作。适当时打开或返回结果页面，并使用 task status <TASK_ID> 查看进度。应用上述有界轮询退避策略；当需要用户操作或轮询预算用尽时，停止轮询。
• task status <TASK_ID> 会返回服务端摘要：status、stage、 total_count、completed_count、failed_count、pending_count、terminal、 needs_user_action、complete 和 issues。不要根据终止状态推断成功：只有 complete=true 才表示完整结果已就绪。如果 Task 因结果不完整而停止，请报告缺失或失败的文档。当 needs_user_action=true 时，停止轮询并引导用户前往现有结果页面；只有在文档说明的恢复路径要求时，才使用 task status <TASK_ID> --details。打开页面不能代替查询状态。
• 如果提取返回 FILE_NOT_FOUND 和 CHECK_FILE_ACCESS，请核对提供的 File Asset ID 和已登录账户；不要自动重试相同请求。如果返回 EXTRACTION_SOURCE_NOT_PARSED 和 PARSE_FILE，请先在当前账户中完成该文件的解析，再进行提取。
• 汇总计数是文档数量。失败的文档在文档级别有一个问题，其中包含可用时的 error_code 和 error_message；应报告该原因，而不是额外报告一个字段缺失错误。对于 insufficient_balance，请说明必须先补充资金或套餐额度，才能在现有 Task 上重试。已完成但未找到的字段是正常的 null 结果，不属于问题。结果分页仅适用于 items；summary 仍涵盖整个 Task。
• 保持默认的异步提交和有界状态轮询。当用户明确要求前台等待时，提取创建和 task add 可接受 --wait，并可选用正数时长设置 --timeout 和 --poll-interval。这些时长必须与 --wait 一起使用。等待时会读取 Task 的当前摘要，包括并发添加或编辑的内容；它不会固定某个 Run 或提交时的快照。当 terminal=true 或 needs_user_action=true 时，等待即停止。
• 等待后返回的响应会保留原始提交标识符、计数、resource_version 和 result_page_url，并在获取到最新 summary 时一并包含。顶层的 status 反映该摘要。请遵循 next_action：POLL_STATUS 查询同一个 Task，READ_RESULTS 读取或导出结果，INSPECT_TASK 报告问题并检查现有 Task，OPEN_RESULT_PAGE 则在现有页面上请求用户操作。
• wait_timed_out=true 只会结束本地等待，包括正在进行的状态请求；请继续使用 task status <TASK_ID>。切勿因等待超时而重新提交创建请求或追加请求。轮询出错或被取消时，会返回已接受的提交，并带有 wait_interrupted=true，以及包含相同 task_id 和 details.submission_accepted=true 的结构化错误。执行任何后续命令前，请遵循结构化错误处理门控；其 next_action 优先级最高。如果首次查询失败，最新摘要可能不存在。请保留已接受的 Task，切勿将等待错误视为提交失败。
• 要读取纯结果，请使用 task result <TASK_ID> --limit 50。使用 --offset <NEXT_OFFSET> --snapshot <SNAPSHOT> 跟进 next_offset；发生快照冲突时，请从第一页重新开始，不要合并不同 Task 版本的结果。
• 要导出，请使用 task export <TASK_ID> --format json --output <DIRECTORY>（或 csv）。提取会写入 results.json 或 results.csv；标准输出包含完成摘要和输出路径。只会导出已就绪的文档；请始终根据摘要报告省略内容和审核警告。切勿声称部分结果已完整。
• JSON 包含 file_name 和业务 result 值，不包含证据或 Agent 内部信息。缺失值为 null，标识符保持为字符串，对象和数组值保持其结构。CSV 会将对象和数组单元格序列化为 JSON 文本。
• 创建提取时不要传入仅用于解析的标志（--api、--config、--password 或自动 --output）。为兼容起见，task run 默认执行解析；提取必须显式指定 --task-type extract。
• task add <TASK_ID> 使用服务端的任务类型：解析时传入本地路径，已解析文件传入 --file-id，历史记录传入 --history-id，提取时传入本地路径。本地提取追加使用现有的托管导入流程，而不是新建提取 Task。请保留返回的 uploaded_file_ids 和 operation_id；上传中断后，请使用相同的操作标识，或通过 --uploaded-file-id 导入已知资源。task add TASK --reconcile 会刷新待处理的导入。解析追加会请求一个新文件 Run，并保留 --operation-id 恢复机制；绑定后发生故障并不意味着文件未添加。请保留标识符并遵循返回的恢复说明。 现有的 task rerun --mode new-files 仍受支持。

提取工作区操作（需要包含这些命令的 CLI 版本）

区域可用性以此页面为准：列表、字段规范设置／澄清、整个任务或指定范围的重新运行、预览和版本历史仅限国内地区。服务器会拒绝在全球地区执行这些工作区操作；请勿绕过此限制。

• 使用 task retry <TASK_ID> 明确重新运行当前提取 Task 的全部内容。这是在同一 Task 中开启新一轮提取，而不是恢复某个失败文件，也不是 task resume。绝不要根据状态查询请求推断需要完整重新运行。
• 使用 task retry <TASK_ID> --scope selected --resource-id <RESOURCE_ID> --field-id <FIELD_ID> 选择文件／字段。根据需要重复指定选择器；文件和字段选择器取交集。--only-outdated 会保留当前值／手动值。不指定任何选择器时，将选择所有活动字段和所有文件。
• 旧版 task retry TASK --resource-id RESOURCE 保留单文件恢复功能。添加 --scope selected 可明确重新提取该文件。--pending-result-id 仅用于结算，不能与重新运行选择器组合使用。
• 使用 task spec get TASK 读取字段及其版本。使用 task spec set TASK --input <JSON_FILE> 提交完整且已审核的字段定义：expected_version、task_rules、fields、apply_to_existing，以及可选的 restore_field_ids 和 resource_ids。省略现有活动字段会将其删除；绝不要将部分列表作为完整定义发送。task spec clarify TASK --input <JSON_FILE> 会根据 expected_version、name 和 description 请求建议。
• 使用 task field set|confirm TASK RESOURCE FIELD --input <JSON_FILE> 更正或确认结果。保留 base_result_version、expected_spec_version、request_id、后端 value 封装，以及可选的 review。不要在未告知的情况下启用 review.apply_to_future。使用 task status TASK --details 读取准确的当前值／版本／依据；使用 task history TASK RESOURCE 读取历史记录，使用 task preview TASK RESOURCE 查看源文件预览。
• task copilot show TASK 会读取当前草稿／问题；task copilot steps TASK --after N 会读取对话／执行历史。task copilot send TASK --text '<REQUEST>' 会发送新的用户指令。对于回答、确认、编辑后的确认或取消操作，请使用 --input <JSON_FILE>，并按适用情况保留准确的 kind、client_message_id、expected_version、reply_to、draft_id、draft_revision 和 edited_fields。确认前先向用户展示草稿；不要在未告知的情况下将仅确认更改为确认并重新运行。
• task list 支持 --search、--status、--file-id、--offset、--limit。task memory list TASK 会读取任务记忆；task memory revoke TASK MEMORY 仅撤销明确选中的更正记忆。
• task page TASK 会获取由服务器新签发的 result_page_url，不会添加文件或运行提取。需要后端支持页面链接查询。遵循主机的链接打开约定；绝不要重构或泄露授权信息。
• 遇到冲突或失败结果不明确时，保留请求／版本标识。不要刷新版本并自动重新发送变更，不要循环重试整个任务，也不要创建替代任务。遵守服务器的区域可用性限制并尊重能力错误。成功提交不代表提取已完成。
• 这些工作区命令需要 CLI 2.4.4-beta.7 或更高版本的匹配发行版。不要假定较早安装的 beta 版本包含这些命令。请先查看 CLI 帮助。

提取计费与恢复

• 提取每天为每位用户提供 100 个免费页面，之后按正常价格计费。 从 xparse-cli quota --output json 中读取 extraction_quota.daily_pages_remaining 和 extraction_quota.reset_at。 这些是服务器端事实，而非本地估算。如果不存在 extraction_quota，则提取额度未知； 不要推断还剩 100 个页面，也不要用解析额度代替。 缺少 extraction_quota 表示额度未知（包括未认证的调用方、较旧的服务器或暂时不可用的提取账本）；绝不能将其替换为 0 或 100。现有的 free_package 属于 pdf_to_markdown，不属于提取。 解析额度不等于提取额度。服务器会根据剩余免费页面和付费资金检查整个 文件；资金不足时会拒绝该文件，不会部分扣费。成功结算按用户、Task 和文件 计费一次；同一文件可能会因新 Task 而再次收费。 绝不要创建替代 Task 来恢复失败任务。
• 创建时会返回 operation_id，提交状态不明确时也会在结构化错误详情中返回。 仅使用同一个 --operation-id 重放；不要生成另一个 ID，也不要从缺失的响应中推断出新 Task。若要在 CLI 进程中断后恢复，请在提交前提供并保留该 ID。
• 使用 task status <TASK_ID> --details 检查确切的 resource_id、 error_code、billing_status、pending_result_id 和 agent_activity。
• 如果 billing_status 为 pending_settlement，则生成的结果已私下保存，但尚未交付。充值后，使用 task retry <TASK_ID> --resource-id <RESOURCE_ID> --pending-result-id <PENDING_RESULT_ID>。 对响应不明确的情况，保留这两个 ID，并重放同一个请求。 这只会结算并发布已保存的结果：不会调用模型，也不会消耗额外的模型预算。 重复成功结算会返回相同的结果。 过期的候选结果会返回冲突；绝不要悄悄用重新运行的结果替换。
• 结算后 Task 仍处于挂起状态。交付的文件可通过 task result / task export 获取；请说明剩余工作仍未完成。
• 没有待处理结果的失败文件，可以使用 task retry <TASK_ID> --resource-id <RESOURCE_ID> 显式重新提取。此操作不保证可幂等重放。如果响应不明确，请检查状态； 不要自动重新发送。依次重试多个失败文件，等待当前一轮终止，并在下一轮开始前检查状态。
• 收到用户明确指示后，要继续挂起的 Agent，请使用 task resume <TASK_ID>，不要使用解析用的 --run-id 或 --after-funding 标志。 这会继续其他工作，并增加由服务器控制的执行预算。 保留返回的 command_id 和 checkpoint_version，包括失败时返回的值，并使用 --command-id <COMMAND_ID> --checkpoint-version <VERSION> 重放。 即使状态此后已更改，精确重放仍使用原始的一对值。先结算待处理结果。 绝不要自动循环恢复，也不要增加预算。

对于追加请求，只将新提供的文件发送到同一个 提取 Task。使用已安装 CLI 支持的来源路径：已解析的 File Asset ID、历史记录 ID 或托管式本地文件导入。不要在同一命令中混用托管式导入 与已解析/历史记录来源。不要执行 task run --task-type extract，也不要重新发送旧文件。保留现有的提取指令和字段； 不要将追加请求变成新的 --instruction。不接受提取 Run ID：

xparse-cli task add <EXTRACTION_TASK_ID> \
  --file-id <NEW_FILE_ASSET_ID>
# If supported, for a history file instead:
xparse-cli task add <EXTRACTION_TASK_ID> --history-id <HISTORY_ID>
# If supported, for a local file instead:
xparse-cli task add <EXTRACTION_TASK_ID> <NEW_LOCAL_FILE>

检查返回的 task_id 是否为原始 <EXTRACTION_TASK_ID>，然后轮询同一个 Task。直接添加 File Asset/历史记录时可能会返回 result_page_url；只有在实际返回时才能使用。托管式本地文件导入会返回 operation_id、uploaded_file_ids 和导入状态，而不是页面 URL：保留这些标识，遵循其导入恢复/状态说明；仅在功能支持且需要页面时，才使用 task page <EXTRACTION_TASK_ID> 请求服务器签发的新链接。绝不要编造 URL。如果追加失败，请按照错误中的恢复说明在同一个 Task 上处理；绝不要退而新建另一个 extraction Task。

当 MCP 工具可用时，对应的契约为 create_extraction_task(file_ids, instruction, operation_id) 和 add_extraction_task_files(task_id, file_ids)。使用 file_ids；不要编造 Parse Job、Parse Task Run 或 source-pointer 参数。

完整文档或转换

使用一条 parse 命令：

xparse-cli parse <INPUT> --api auto

对于 PDF，请传入输出目录，避免较长的 Markdown 在终端输出中被截断。如果目录不存在，CLI 会创建该目录：

xparse-cli parse report.pdf --api auto --output <DIR>

请求更多详细信息前，请先阅读已保存的结果。只有当任务需要结构化元素、坐标、表格、页码或标题层级时，才添加 --view json。

服务器生成的文档导出

当用户明确要求将一份文档导出为 DOCX、PDF 或 XLSX 时，请说明这需要付费的 parse 端点，并在运行命令前取得付费授权。只请求用户需要的格式：

xparse-cli parse <INPUT> --api paid --export docx,pdf,xlsx --output <DIR>

• --export 接受 docx、pdf 和 xlsx；请传入逗号分隔的列表，或重复使用该标志。CLI 会移除重复项，且 XLSX 会自动使用表格导出范围。
• 使用 --export 时，必须指定 --api paid 和 --output <DIR>。下载前，CLI 会立即重新解析所选 AppKey 或 OAuth 身份，以便在耗时较长的解析过程中刷新已过期的 OAuth 令牌。随后，它会下载每个成功的导出文件并验证已保存文件的大小。
• 输出目录包含常规解析结果，以及 <basename>.docx、<basename>.pdf 和/或 <basename>.xlsx。请将这些本地文件作为任务结果读取或返回。如果文件名会覆盖输入文件，CLI 会使用 <basename>.export.<format>。不要向用户公开后端下载 URL、file_id 值或授权详情。
• 此单文档功能与 task export 不同；后者导出持久多文档 Task 的 Markdown 结果。

定向阅读、搜索或提取

对于本地文档，请使用：

get_doc_info -> parse the complete document -> navigate -> extract

1. 运行 get_doc_info <FILE> 并保留其确切的 doc_id。
2. 运行 parse <FILE> --api auto，不要使用 --page-range。成功完成的本地完整解析会自动写入导航缓存。
3. 使用 get_outline、search_text 或 read_pages 定位相关内容。
4. 导航完成后，批量调用所需的 read_content。

没有单独的缓存准备命令。成功完成本地完整 parse 是唯一的准备步骤。

指定页码范围的解析不会替换完整文档导航缓存。URL 解析没有稳定的本地 doc_id，因此应直接使用其解析输出，而不要使用本地导航命令。

执行定向导航或提取前，请阅读 navigation.md。

效率与回退规则

• 在阅读各个章节前规划好所有导航；每项任务的 read_content 调用次数不超过 8 次，并将相互独立的读取请求一起发出。
• 对于名称、日期、金额和百分比，优先使用 search_text。只有在需要查看上下文说明或表格结构时，才阅读完整章节。
• 如果大纲被截断，使用 --parent-id 深入查看；不要猜测 ID。
• 对于互不相关的单文档解析，按顺序执行。对于多文档批处理，使用一个持久化 Task，而不是并行运行 parse 命令。
• 仅当结构化错误指出 retryable=true 时，才最多重试一次暂时性服务故障。遇到不可重试的服务故障时立即停止。绝不要悄悄跳过故障。
• 对于本地文档，在使用 Python、PyMuPDF、pdfplumber、qpdf、OCR 工具、图像转换或自定义脚本之前，先尝试此 Skill。
• 如果文档已加密或缺少必需的输入，请询问用户，而不是尝试其他工具。
• 只有在 xparse-cli 明确无法完成任务后，才使用备用方案，并说明原因。

快速参考

目标	命令
使用自动免费路由解析	xparse-cli parse <FILE> --api auto
仅强制使用免费端点	xparse-cli parse <FILE> --api free
显式使用付费解析	xparse-cli parse <FILE> --api paid --auth-method oauth
保存为 Markdown	xparse-cli parse <FILE> --api auto --output <DIR>
保存为 JSON	xparse-cli parse <FILE> --api auto --view json --output <DIR>
将单份文档导出为 DOCX/PDF/XLSX	xparse-cli parse <FILE> --api paid --export docx,pdf,xlsx --output <DIR>
仅解析指定页面	xparse-cli parse <FILE> --api auto --page-range 1-5
加密文档	xparse-cli parse <FILE> --api auto --password <PWD>
字符详情	xparse-cli parse <FILE> --api auto --view json --output <DIR> --include-char-details
显示当前配额	xparse-cli quota --output json
显示篡改检测配额	xparse-cli quota --service manipulation_detection --output json
检测篡改或 AIGC 风险	xparse-cli detect-manipulation <FILE_OR_URL> --view json
为本地文件运行持久化 Task	xparse-cli task run --files '<GLOB>' --api auto
上传单个文件但不解析	xparse-cli upload <FILE> --operation-id <OPERATION_ID>
从就绪的 File Asset 创建提取任务	xparse-cli task run --task-type extract --instruction '<REQUEST>' --file-id <FILE_ASSET_ID>
检查稳定的 Task 资源	xparse-cli task status <TASK_ID> --details
将新解析的 File Asset 追加到提取 Task	xparse-cli task add <TASK_ID> --file-id <FILE_ASSET_ID>
在支持时追加现有历史文件	xparse-cli task add <TASK_ID> --history-id <HISTORY_ID>
在支持时通过托管导入追加本地文件	xparse-cli task add <TASK_ID> <LOCAL_FILE>
重新运行 Task 下的所有 Resource	xparse-cli task rerun <TASK_ID> --mode all
添加文件并创建新的 Run	xparse-cli task rerun <TASK_ID> --mode new-files --files '<GLOB>'
重新运行选定的 Resource	xparse-cli task rerun <TASK_ID> --mode selected-files --resource-id <RESOURCE_ID>
检查指定的 Task Run	xparse-cli task status <TASK_ID> --run-id <RUN_ID>
读取单个 Task 结果	xparse-cli task read <TASK_ID> <FILE_OR_RESOURCE> --run-id <RUN_ID>
导出所有已完成的结果	xparse-cli task export <TASK_ID> --run-id <RUN_ID> --output <DIR>
检查各文件的失败情况	xparse-cli task debug <TASK_ID> --run-id <RUN_ID>
Run 错误 40423 后继续单个现有 Resource	xparse-cli task continue <TASK_ID> --password <PASSWORD>
Run 错误 40423 后继续多个现有 Resource	xparse-cli task continue <TASK_ID> --password <SELECTOR>=<PASSWORD> --password <SELECTOR>=<PASSWORD>
付费审批后恢复运行	xparse-cli task resume <TASK_ID> --run-id <RUN_ID> --approve-paid
资金到位后恢复运行	xparse-cli task resume <TASK_ID> --run-id <RUN_ID> --after-funding
启动本地导航	xparse-cli get_doc_info <FILE>
显示缓存的大纲	xparse-cli get_outline <DOC_ID>
搜索缓存的文本	xparse-cli search_text <DOC_ID> <PATTERN>

--output 接受目录，而非输出文件名。CLI 会创建不存在的目录， 并在其中写入 <basename>.md 或 <basename>.json。

身份验证边界

• CLI 支持 AppKey、Device OAuth 和浏览器 PKCE，详情见 authentication.md。
• 处理身份验证时，切勿打印凭据文件或使用 --verbose。
• 显式选择的身份验证方法必须按该方法失败；不要静默改用其他凭据类型。

设置和命令发现

使用 xparse-cli version 检查安装情况。该软件包需要 Node.js 18 或更高版本，可通过以下命令安装：

npm i -g xparse-cli

中国用户请使用 npmmirror registry：

npm i -g xparse-cli --registry=https://registry.npmmirror.com

请将此 Skill 及其参考文档用作命令索引。需要实时发现命令时，请先阅读完整的 xparse-cli --help，再阅读对应命令的完整帮助信息。请勿使用 head、tail 或固定范围的 sed 截断帮助输出。

遇到不支持或损坏的文件、无效凭据、配额耗尽、缺少付费审批、任何不可重试的服务故障，或单次允许的 Agent 层重试后仍未解决的瞬时故障时，请停止。

参考文档

• navigation.md：定向大纲、搜索、页面和内容工作流。
• task-runtime.md：持久化多文件路由、状态、结果获取和恢复。
• authentication.md：AppKey、Device OAuth 和浏览器身份验证。
• cli-guidance.md：模式、输出、参数和限制。
• api-reference.md：响应字段和服务错误代码。
• error-handling.md：重试、停止和付费审批决策。
• textin-key-setup.md：独立的旧版 AppKey 设置。