> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 自动化任务
> 让 Waker 按计划、事件或 API 请求在后台执行固定任务，适合日报、巡检、仓库事件分析、外部工单处理等重复工作。
自动任务让一个 Waker 按计划、事件或 API 请求在后台执行固定任务。它适合日报、巡检、仓库事件分析、外部工单处理等重复工作。
**操作路径：** 准备 Waker 和工作空间 → 创建任务 → 选择定时、事件或 API 触发 → 立即运行并验收。
创建前，请确认已有执行任务的 Waker 和可用工作空间。使用本地目录时，本机 QoderWake 需保持运行；调用外部系统时，还需提前安装并验证对应 Skill 或连接器。需要中途人工确认的任务应改用 WakerFlow。
## 创建自动任务
**操作步骤：**
1. 从「Waker 管理」打开目标 Waker，进入「自动任务」。
2. 点击「新建」，填写名称并选择本地目录或项目。
3. 在任务描述中写清输入范围、处理要求、输出格式和禁止事项。
4. 选择模型并配置至少一种触发方式。
5. 按需设置最大运行次数或截止日期，点击「保存」。
名称建议采用"对象 + 动作 + 频率"，例如"主仓库每日风险巡检"。任务描述应包含检查范围、处理步骤、输出位置、成功标准和禁止操作；API 触发时可使用 `{{field}}` 引用请求字段。
**完成判断：**
* 列表中出现新任务，名称、工作空间、模型和触发方式正确。
* 状态为"已启用"，并显示下一次运行时间或 API/事件信息。
## 配置定时触发
定时触发适合日报、周报、固定巡检和周期性汇总。
1. 选择「定时」，设置一次性或周期性规则。
2. 检查页面计算的「下次执行」时间和系统时区。
3. 按需设置最大运行次数和截止日期，保存任务。
4. 首次先设为几分钟后运行，验证成功后再改为正式周期。
使用本地目录时，计划时间内电脑、QoderWake 和目标目录必须可用；定时运行可能出现数分钟调度延迟。
### 场景示例：使用 DWS MCP 创建每日群聊总结
先进入 Waker 详情 →「连接器」→「系统」完成 DWS 授权，并在普通对话中验证读取和发送能力。首次使用测试群，任务描述中写清目标群、时间范围、总结格式和发送时间。
1. 打开新任务，核对启用状态、下次运行时间、目标群、时间范围和发送对象。
2. 点击「立即运行」，检查运行历史和测试群中的总结。
3. 确认只发送一条正确消息后，再切换到正式群和正式周期。
若发送到错误群，应立即暂停任务，并在测试群重新验证。任务未触发时检查时间和启用状态；消息调用失败时检查 DWS 授权和连接状态。
## 配置事件触发
事件触发适合 GitHub Issue、Pull Request、评论变化，或当前页面提供的其他插件事件。
1. 选择「事件」和事件来源，按页面完成授权。
2. 设置关注对象、变化类型及仓库、分支或标签等过滤条件。
3. 保存并启用任务；页面提供「测试检查」时先执行一次。
4. 在外部系统创建一条测试事件，再到「事件活动」和「运行历史」检查结果。
Webhook 地址必须复制当前页面生成的值，不要手工拼接。状态显示"未分配"或"同步中"时，等待片刻再刷新。
**完成判断：** 外部测试事件出现在「事件活动」中，运行历史新增一条来源正确的记录，并且会话详情中的输入与测试事件一致。
事件发生但任务未运行时，检查授权、过滤条件和任务启用状态。
## 配置 API 触发
API 触发适合工单平台、CI/CD 或业务系统主动调用 Waker。
1. 添加「API」触发方式并保存任务。
2. 在详情页复制系统生成的 POST 地址、认证方式和请求体，不要自行拼接。
3. 从调用方发送测试请求。
4. 在运行历史中确认来源为 API，并打开会话详情检查结果。
Qoder 公网 API 使用个人访问令牌（PAT）进行 Bearer 认证。可在 Qoder 控制台「个人设置」→「服务集成」创建令牌；令牌只显示一次，应保存在调用系统的受保护凭据中。示例：
```bash theme={null}
curl -X POST 'https://api.qoder.com/v1/qoderwake/automation/invoke/' \
--header 'Authorization: Bearer pt-your-token-here' \
--header 'Content-Type: application/json' \
--data '{
"prompt": "your appended prompt here"
}'
```
替换调用 Key 和 PAT 占位值，并以当前详情页的请求示例为准。任务描述可用 `{{field}}` 引用 Payload 字段，字段名区分大小写。需要复用同一业务会话时，可传入 `wakeSessionUniqueId`；它不是幂等键，不同客户或项目不得共用。
**完成判断：** 运行历史出现来源为 API 的新记录，会话收到正确输入，最终产物符合任务描述。API 请求成功不代表业务已经执行完成，仍需查看运行历史和会话详情。
**安全提示：** 真实 PAT 不得写入仓库、任务描述、截图或日志；泄露后应立即撤销并重新创建。
## 管理任务和查看运行结果
在任务卡片的更多菜单中可暂停、恢复、编辑、复制、删除或立即运行。删除前确认不再需要历史记录；暂停任务通常需先恢复后才能立即运行。
进入任务详情后，重点查看：
| 区域 | 用途 |
| ----------- | ------------ |
| 任务描述和工作空间 | 确认实际任务和目录 |
| 触发方式 / 下次运行 | 确认触发配置和启用状态 |
| 事件活动 | 确认外部事件是否被接收 |
| 运行历史 / 会话详情 | 查看来源、状态和交付内容 |
**完成判断：** 运行状态成功，工作空间和输入正确，产物或外部动作符合任务描述，测试内容未进入生产目录或真实外部对象。
## 自动任务失败排查
| 现象 | 检查顺序 |
| ------------ | ------------------------------------------------ |
| 到时间没有运行 | 任务是否启用 → 下次运行时间和时区 → 最大次数 / 截止日期 → 本机是否在线 |
| 事件没有触发 | 来源授权 → 仓库或对象 → 变化类型和过滤条件 → 事件活动中是否收到记录 |
| API 调用失败 | 使用页面最新端点 → 认证 → Content-Type 和 JSON → 网关是否同步完成 |
| 任务启动后立即失败 | 工作空间是否存在 → 模型是否可用 → Waker 是否在线 → Skill / 连接器是否就绪 |
| Payload 没有注入 | 占位符路径和大小写 → 请求体字段 |
| 业务上下文混乱 | 检查 `wakeSessionUniqueId` 是否被无关业务复用 |
| 成功但无预期产物 | 检查任务描述中的输出位置、格式和成功标准 |
排查时先使用「立即运行」隔离触发问题：手动运行成功而自动触发失败，重点检查触发配置；手动运行也失败，重点检查任务描述、工作空间、模型、能力和权限。