程序化执行

按对象准备输入，确认执行授权，再提交、查询和下载。

公共执行流程

准备输入 → 校验或预检 → 确认费用 → 提交 → 保存运行标识 → 查询 → 下载。输入变化后重新检查，预检不代表执行授权。

官方模板：读取结构后提交

先读取 schema。本例使用 text-v1，把下面的一行保存为 rows.jsonl：

{"text_prompts":"把参考文本整理成三点摘要","writing_requirements":"中文，每点一句话，不补充原文没有的信息","reference_text":"Emma 整理正文，Alex 核对产品规则，周五前完成第一版。"}

字段已对照当前官方 schema；这是讲解输入，提交前仍需校验和预检。该模板当前的参考输入是单元格文本；上传文件须选择支持 Artifact 输入的模板，不能照抄旧说明把文件标识作为文本。

显式使用程序化输入时，按当前字段结构准备 JSON 或 JSONL：

loomloom template schema <template-id>
loomloom run validate <template-id> -f ./rows.jsonl
loomloom run precheck <template-id> -f ./rows.jsonl

展示当前预估并确认后，再执行：

loomloom run execute <template-id> -f ./rows.jsonl --client-request-id <本次请求标识>

私有模板：指定版本并预检

常见单入口流程支持每行一个扁平字符串对象。例如，仅当所选版本声明 meetingText 输入时，可使用：

{"meetingText":"Emma 整理正文，Alex 核对规则，周五前完成第一版。"}

实际键必须来自该版本定义。复杂多步骤输入需采用该版本支持的映射，不能猜测步骤标识。

JSONL 执行输入通过专门的行数据上传入口处理：

loomloom orchestration-input upload ./rows.jsonl
loomloom template-spec precheck <template-id> --version-id <version-id> --input-file-id <返回的输入标识>

确认费用后，用同一模板、版本和输入创建运行：

loomloom template-spec run <template-id> --version-id <version-id> --input-file-id <返回的输入标识> --client-request-id <本次请求标识>

市场 SkillApp：通过 Listing 执行

request.json 使用公开 inputRows。仅当详情的公开输入键为 prompt 时，下面结构才适用：

{
  "inputRows": [
    {"prompt": "把这段已核对的会议内容整理成三点摘要"}
  ]
}

以 fields[].key 提交键，按公开类型、必填项与允许值准备内容。这是格式示例，不是任何 Listing 都可直接使用的请求。

先查看公开输入，再准备请求，不推断作者内部步骤：

loomloom market show <listing-id>
loomloom market quote <listing-id> --input-file ./request.json

确认后再运行：

loomloom market run <listing-id> --input-file ./request.json --confirm --client-request-id <本次请求标识>

市场标识来自实际列表，输入键来自公开结构。创建订单时使用当前可售快照。

文件素材与行数据

input-asset 上传可复用原始素材；orchestration-input 上传私有模板执行行数据。两者返回的标识不能随意互换。

文件类型要与目标输入匹配，不能把文件标识当普通提示词文本。

输入格式来自对应 schema，不能用私有模板定义绕过市场调用。完整 JSON 请求样例需按实际公开字段补齐，接口见 API 概览。

可靠性：幂等、超时、终态与重试

提交超时后先查运行和交易，不立即创建重复任务。未拿到运行标识时，按提交时间、执行对象、输入记录及原请求标识核对；无法排除任务已创建时，保留记录进一步核实，不改用新请求标识再次提交。只有完全相同的已确认请求重试才复用原请求标识；新输入重新校验、报价、确认并生成新标识。

loomloom run get <run-id>
loomloom run watch <run-id>
loomloom run result-workbook <run-id>

自动化集成需要明确自己的费用授权与限额，不能把预检视为执行授权。

轮询只在当前状态确认为终态后结束；终态集合以当前返回和接口约定为准。部分失败时保留已成功结果，先检查失败行与交易，再准备新任务。

人工使用在报价后明确确认；无人值守集成需事先明确费用授权、限额和异常处理。授权不清楚时不要把一次预检当成持续付费许可。