# 运行批量任务

> 用一套任务配置并发处理多个独立目录，集中观察状态、校验产物并局部重试。

Canonical page: /product/batch-tasks



<Takeaways>
  <li>
    每个目录必须能独立验收
  </li>

  <li>
    先用一个目录验证，再提高并发
  </li>

  <li>
    产物规则比模型回复更可靠
  </li>
</Takeaways>

批量任务把一个已经跑通的方法应用到多个目录。它不是把一个复杂任务自动拆成多个步骤，而是为每个目标目录创建独立子任务和会话，再按并发上限执行。

<MediaFrame>
  <img src="/images/product/batch-tasks.webp" alt="Astravia 批量任务看板，显示运行中和等待中的多个目录任务" width="1536" height="1152" />

  <figcaption>
    一份配置扇出为多个独立任务；看板负责全局状态，会话保留单次执行细节。
  </figcaption>
</MediaFrame>

## 先判断是否适合批量 [#先判断是否适合批量]

<Fork>
  <ForkYes title="使用批量任务">
    <li>
      同一规则检查多个仓库
    </li>

    <li>
      为多个目录生成相同类型产物
    </li>

    <li>
      批量迁移相似配置
    </li>

    <li>
      对多份资料执行独立整理
    </li>
  </ForkYes>

  <ForkNo title="改用其他方式">
    <li>
      子任务之间有严格先后依赖
    </li>

    <li>
      所有目录必须共享实时中间状态
    </li>

    <li>
      目标只有一个，且需要频繁交互决策
    </li>

    <li>
      任务无法在单个目录内独立验收
    </li>
  </ForkNo>
</Fork>

批量任务的关键不变量是：任意一个子任务单独执行，也能得到可判断成功或失败的结果。

## 示例：检查多个项目的发布准备度 [#示例检查多个项目的发布准备度]

<Plate no="01" title="目标目录">
  ```text
  C:\work\api-service
  C:\work\desktop-client
  C:\work\admin-console
  C:\work\docs-site
  ```
</Plate>

<Plate no="02" title="共享提示词">
  ```text
  检查当前项目是否具备可执行的发布前流程。

  要求：
  1. 阅读 package.json、README 和现有发布配置；
  2. 只生成 release-readiness.md，不修改源码或配置；
  3. 列出构建、测试、版本和发布入口的实际状态；
  4. 不确定的项目标记为“需人工确认”，不要猜测；
  5. 完成后确认 release-readiness.md 已生成。
  ```
</Plate>

产物校验填写 `release-readiness.md`。这样即使模型回复正常但没有写出文件，子任务也不会被误判为完成。

## 创建批量项目 [#创建批量项目]

入口：侧栏 **更多 → 批量任务**。点击 **新建项目**，填写：

<Panel>
  <PanelGroup title="任务定义">
    <PanelItem title="项目名称">
      列表和推送中显示的名称
    </PanelItem>

    <PanelItem title="提示词">
      应用于每个目录的同一任务说明，可用 

      `/`

       唤出技能或场景
    </PanelItem>

    <PanelItem title="模型">
      所有子任务使用的模型
    </PanelItem>

    <PanelItem title="文件夹列表">
      每行或每次选择一个目录，每个目录生成一个子任务
    </PanelItem>
  </PanelGroup>

  <PanelGroup title="执行约束">
    <PanelItem title="并发数">
      同时处于运行中的子任务上限
    </PanelItem>

    <PanelItem title="超时">
      单次运行硬超时；暂停后恢复会重新计时
    </PanelItem>

    <PanelItem title="沙盒状态">
      跟随默认、完全访问或使用沙盒
    </PanelItem>

    <PanelItem title="产物校验">
      子任务目录顶层必须全部匹配的文件名或 glob
    </PanelItem>

    <PanelItem title="消息推送">
      子任务完成和项目全部完成时通知已配置 Webhook
    </PanelItem>
  </PanelGroup>
</Panel>

## 先用一个目录验证 [#先用一个目录验证]

<Steps>
  <Step>
    ### 只添加一个代表性目录 [#只添加一个代表性目录]

    选择结构最常见、风险较低的目标，并发设置为 1。
  </Step>

  <Step>
    ### 执行并进入会话 [#执行并进入会话]

    检查 Agent 是否读取正确文件、遵守修改范围，并实际产生预期输出。
  </Step>

  <Step>
    ### 调整提示和产物规则 [#调整提示和产物规则]

    先消除模糊要求和误报条件，再追加其余目录并提高并发。
  </Step>
</Steps>

## 理解队列和状态 [#理解队列和状态]

<BatchFlow aria-label="批量任务队列和并发状态">
  <div>
    <span>共享配置</span>

    <strong>Prompt · 模型 · 并发 2 · 产物规则</strong>
  </div>

  <BatchTasks>
    <span className="border-t-[#3f9f70]">
      目录 A

      <br />

      <small>完成</small>
    </span>

    <span className="border-t-astravia-coral">
      目录 B

      <br />

      <small>运行中</small>
    </span>

    <span className="border-t-astravia-coral">
      目录 C

      <br />

      <small>运行中</small>
    </span>

    <span className="border-t-[#c59a37]">
      目录 D

      <br />

      <small>等待中</small>
    </span>

    <span className="border-t-[#c95454]">
      目录 E

      <br />

      <small>失败</small>
    </span>
  </BatchTasks>
</BatchFlow>

<Beats>
  <li>
    **开始**

    ：按并发数把未执行或可恢复的任务加入队列。
  </li>

  <li>
    **停止**

    ：中断运行中任务，并清空除已完成外的会话、产物和状态后重置；确认框会说明具体影响。
  </li>

  <li>
    **重置失败**

    ：只清理失败任务并重新入队，不必重跑全部目录。
  </li>

  <li>
    单任务支持执行、继续、重试、重新运行、删除和跳转到会话。
  </li>
</Beats>

活动面板中的 **执行进度** 用于看整体；进入单任务会话检查工具、消息和具体失败原因。

## 验收整个批次 [#验收整个批次]

<Checklist title="批次完成前">
  <li>
    总数等于预期目录数，没有遗漏或重复路径。
  </li>

  <li>
    所有完成项都满足产物规则，而不是只有成功回复。
  </li>

  <li>
    随机抽查至少一个普通目录和一个边界目录的实际内容。
  </li>

  <li>
    失败项进入对应会话定位后局部重试。
  </li>

  <li>
    Webhook 只作为通知，不作为最终验收证据。
  </li>
</Checklist>

<Callout type="warn" title="停止不是暂停">
  停止会重置未完成任务的会话、产物和状态，并且不可撤回。只想临时降低负载时，优先处理单任务或等待当前任务结束。
</Callout>

需要一份可以直接试跑的完整配置，参见[批量审计多个项目](/examples/batch-project-audit/)；需要按时间周期执行一个任务时使用[自动化](/product/automation/)；需要多个步骤共享中间状态时使用普通会话分阶段完成。