Skip to content

11-batch-execution.md

Latest commit

 

History

History
145 lines (112 loc) · 7.37 KB

11-batch-execution.md

File metadata and controls

145 lines (112 loc) · 7.37 KB
Raw

11 · 批量执行与参数模板

澄清点 2 的落地：技能结晶后，根据其变量 schema 自动生成可下载的参数模板（CSV/XLSX）；用户填好导入，底座把每一行当作一次 0 Token 确定性回放批量执行（如"搜索一批不同类型、不同价位的商品"）。

1. 端到端流程

flowchart LR
    SKILL["已发布技能<br/>(io.inputs schema, 见 07)"] --> GEN["① 生成参数模板<br/>CSV/XLSX(含表头/示例/校验规则)"]
    GEN --> DL["② 用户下载模板"]
    DL --> FILL["③ 用户填写多行参数"]
    FILL --> IMP["④ 导入 → 校验(类型/必填/枚举)"]
    IMP -->|有错| REPORT["返回逐行错误报告"]
    IMP -->|通过| QUEUE["⑤ 入工作队列<br/>每行=1 个 batch item"]
    QUEUE --> RUN["⑥ 并行 0 Token 回放<br/>(身份分片 + 速率护栏)"]
    RUN --> AGG["⑦ 结果汇聚(统一 schema)"]
    AGG --> EXP["⑧ 导出(CSV/XLSX/JSON)<br/>含每行状态/结果/失败原因"]
Loading

关键定位：

  • 模板生成、校验、回放全 0 Token（I-4/I-6）：批量只是"同一技能 × 多行输入"的确定性回放，不触发认知（除非某行触发自愈，见 §6）。
  • 对齐 07 变量模型：模板列直接来自技能包 io.inputs 与 output_schema（07）。
  • 对齐 05 工作队列：每行是一个 queue item，复用 05 的幂等/退避/身份分片（05）。

2. 模板自动生成（从 schema → 表格）

技能包 io.inputs 决定模板列。示例技能 search-and-compare@ecom-x 的输入：query:string(必填)、topN:int=10、max_price:number(可选)。

生成的模板（CSV，首两行为表头 + 类型/规则注释行）：

query,topN,max_price
# string(required),int(default=10,range=1..50),number(optional)
无线降噪耳机,10,1500
机械键盘,20,800
人体工学椅,5,
  • 表头行：变量名（稳定键，与技能包一致）。
  • 规则注释行（以 # 开头，导入时忽略）：类型、必填、默认值、取值范围/枚举——让用户"看着填"。
  • 示例数据行：结晶时用探索输入 + 若干合成样例预填，用户可删改。
  • XLSX 增强：用数据校验（下拉枚举、数值范围）、列注释、非法值高亮；隐藏一张 _schema 元数据 sheet 供回传时精确解析。
  • 机密列的处理：技能若含 %vault:...%，模板不出机密列；改为一列"身份/凭据别名"，指向 Vault 中的账户（I-5），绝不让用户把密码填进表格。
flowchart TD
    IOSCHEMA["io.inputs + output_schema"] --> COLS["列定义: 名称/类型/必填/默认/枚举/范围"]
    COLS --> CSVGEN["CSV: 表头 + #规则注释 + 示例行"]
    COLS --> XLSXGEN["XLSX: 数据校验 + 注释 + 隐藏 _schema sheet"]
    SECRETS["含机密?"] -->|是| ALIAS["以‘身份别名’列替代，指向 Vault"]
Loading

3. 导入与校验

flowchart TD
    UP["上传 CSV/XLSX"] --> PARSE["解析(忽略 #注释行, 读 _schema)"]
    PARSE --> VAL{"逐行校验"}
    VAL -->|类型错/缺必填/越界/枚举外| ERRROW["标记该行 + 原因"]
    VAL -->|通过| OKROW["规范化(去空格/类型转换/默认值填充)"]
    ERRROW --> RPT["错误报告(行号+列+原因, 可下载)"]
    OKROW --> DEDUP["按业务键去重(可选)"]
    DEDUP --> BATCH["生成 Batch(N 个 item)"]
Loading
  • 严格校验：类型、必填、范围、枚举；不合法的行不入队，产出可下载的逐行错误报告，用户修正后可增量重传。
  • 业务键去重：可指定某列组合为业务键，避免重复执行（尤其涉及写动作/下单）。
  • 干跑（dry-run）：可选先跑 1–3 行验证技能仍有效，再放开全量（降低"技能已漂移却批量全败"的浪费）。

4. 批量调度（身份分片 + 护栏）

flowchart LR
    BATCH["Batch(N items)"] --> SCHED["批量调度器"]
    SCHED --> S1["身份A 会话(串行若干行)"]
    SCHED --> S2["身份B 会话"]
    SCHED --> S3["身份C 会话"]
    S1 & S2 & S3 --> RATE["按域速率/并发护栏(05/03)"]
    RATE --> COLL["结果收集器"]
Loading
  • 身份分片：多身份 Profile 并行消费，天然分散风控压力（与 03 T3 轮换协同）；每身份内部按人类节奏串行若干行，避免"同一身份瞬间百次"的异常。
  • 速率/并发护栏：按域限制，遵守 Site Policy（05）。
  • 断点续跑：Batch 落检查点，中断后从未完成 item 续跑（与 04 崩溃恢复一致）。

5. 结果汇聚与导出

  • 统一 schema：每行产出与技能 output_schema 一致；汇聚为表格，附加列：_row_id、_status(success/failed/skipped)、_heal(是否发生自愈)、_error、_run_id、_duration。
  • 导出格式：CSV / XLSX / JSON；失败行保留原因，便于重跑。
  • 部分成功：Batch 允许部分成功；失败行可一键导出为"重试模板"再次导入。

导出示例（CSV）：

_row_id,query,topN,items_count,_status,_heal,_error,_run_id
1,无线降噪耳机,10,10,success,false,,run_a1
2,机械键盘,20,20,success,true,,run_a2
3,人体工学椅,5,0,failed,false,"assertion: 结果列表为空",run_a3

6. 批量中的自愈与 Token 边界

flowchart TD
    ROW["某行回放"] --> OKQ{"定位/断言 OK?"}
    OKQ -->|是| DONE["0 Token 完成 ✅"]
    OKQ -->|否| L1["L1 本地重定位(0 Token)"]
    L1 -->|成功| HEALED["修复该行 + 回写技能(惠及后续行)"]
    L1 -->|失败| DETACH["脱离模式: 经 Cognition Port 调默认 healer(见 10)"]
    DETACH -->|成功| HEALED
    DETACH -->|失败| MARKFAIL["标记该行 failed, 继续下一行"]
    HEALED --> DONE
Loading
  • 默认 0 Token：批量正常路径不花 Token。
  • 一次自愈，全批受益：某行触发 L1/L2 修复并回写技能升版后，后续行直接用新版本回放（避免"每行都各修一遍"）。
  • 脱离模式自愈：批量通常无人在场，自愈走默认 healer Agent 驱动（子 Agent = Fable 5，见 10）；预算受 budget_tokens 限制，超预算则标记失败而非无限烧钱。
  • 失败不阻塞：单行失败不影响其余行（除非命中站点级硬风控，此时暂停整批并升级人工）。

7. Agent / 人的两种触发姿势

  • Agent 触发（inbound MCP）：Agent 调 generate_template(skill_ref) 拿模板 → 自己或让人填 → 调 run_batch(skill_ref, file)；见 06。
  • 人触发：人下载模板、填表、在本地 UI/CLI 导入运行——无需 Agent 在场（纯确定性，I-6）。

验收检查表（本篇）

  • 能从技能 io.inputs 自动生成 CSV/XLSX 模板（含表头/规则/示例/校验）。
  • 机密不进模板，改用指向 Vault 的身份别名列（I-5）。
  • 导入严格校验并产出逐行错误报告；支持去重与 dry-run。
  • 批量按身份分片 + 速率护栏 + 断点续跑，正常路径 0 Token（I-4）。
  • 结果统一 schema、支持部分成功与失败行重试导出。
  • 批量自愈走脱离模式默认 healer，受预算约束；一次修复全批受益。