# 自动化任务定义 (/docs/automation/task-definition)



一条提示词不是自动化任务定义。只有输入、触发、成功条件、失败出口和责任人都清楚，任务才适合长期运行。

## 自动化前的三个门槛 [#自动化前的三个门槛]

1. 同一方法已手动运行至少三次，结果结构基本稳定；
2. 触发条件、输入来源、输出和验收标准清楚；
3. 有负责人、告警接收人和明确的停用方法。

## 定义模板 [#定义模板]

```text
任务名称：[清晰、可搜索的名称]
业务目标：[为什么运行，支持哪项工作]
负责人：[业务 owner]
处理模式：[小样验证、历史回填或持续增量]
契约版本：[输入、证据和输出字段采用的版本]
触发方式：[不重复、间隔、每小时、每天、每周、每月，或当前端支持的自然语言计划]
时区与计划：[时间、工作日、结束条件]

输入来源：[文档、表格、消息或授权数据]
时间范围：[本次应读取的数据窗口]
批次边界：[文件清单、唯一编号、分组与单批上限]
变更识别：[新增、修改、删除和迟到数据如何判断]
前置检查：[权限、格式、最少来源数量]

处理规则：[筛选、去重、计算和事实规则]
证据要求：[结论怎样定位到文件、记录或版本]
质量门禁：[通过、警告、阻断条件]
输出结构：[标题、字段、文件和命名]
写入目标：[钉钉文档、AI 表格或消息]

幂等键：[用于防止重复执行的唯一标识]
重试策略：[哪些错误重试、次数和间隔]
降级方式：[部分失败时交付什么]
告警规则：[何时通知谁，告警需要哪些信息]
停用方式：[如何暂停和恢复]
资源上限：[时间、数量、积分、Token 或调用次数]
```

## 不要混写三种处理模式 [#不要混写三种处理模式]

| 模式   | 目标               | 输入边界           | 完成标志            |
| ---- | ---------------- | -------------- | --------------- |
| 小样验证 | 发现字段、步骤和失败路径是否可靠 | 少量标准、边界、失败样本   | 契约通过人工验收并形成失败清单 |
| 历史回填 | 把固定契约应用到一批已存在输入  | 冻结清单、唯一编号和有限批次 | 清单全部完成或进入明确失败队列 |
| 持续增量 | 只处理新增、修改或迟到输入    | 水位、版本、内容指纹和时间窗 | 本轮变更完成且水位安全推进   |

同一个业务可以依次经历三种模式，但任务配置、批次 ID 和告警必须分开。小样失败不能被批处理重试掩盖，历史回填也不能与每天的增量任务争用同一状态。

## 质量状态 [#质量状态]

| 状态      | 含义           | 动作          |
| ------- | ------------ | ----------- |
| Pass    | 数据与质量满足要求    | 正常写入或推送     |
| Warning | 部分来源缺失但结果仍有用 | 显著标注缺失后交付   |
| Blocked | 无法保证最低质量或安全  | 不写入正文，只发送告警 |

## 示例：每周项目汇总 [#示例每周项目汇总]

```text
任务名称：项目周报汇总
触发：每周五 16:00，Asia/Shanghai
输入：本周项目任务、会议行动项和风险表
质量门禁：至少包含任务与风险两类来源；负责人缺失时 Warning
输出：进展、风险、待办、负责人和下周计划
写入：指定钉钉周报草稿，不自动对外发布
幂等键：project-weekly-{project}-{week}
告警：全部来源不可用或写入失败时通知项目经理
```

<Callout title="先定义，再配置" type="warning">
  不要一边创建定时任务一边发明规则。先由业务负责人确认任务定义，再在产品中配置和测试。
</Callout>

还没有稳定契约时先阅读[建立可复用工作流](./reusable-workflow)；需要设计回填、增量和扩量门禁时继续阅读[可靠自动化设计](./reliable-automation)。