skill 范本：scheduled-task

「定时任务」（adr-020）配套的技能手册：教 agent 什么时候建任务、 怎么把一件事写成自包含的任务提示词。技能库仍是用户自管的（<dataDir>/skills/），把下面的 内容存成 <dataDir>/skills/scheduled-task/SKILL.md（默认 ~/.acpp/skills/…）与 references/ 下的两个范本，再去「技能」页启用。

SKILL.md

---
name: scheduled-task
description: "把一件事固化成 Discord 频道的定时任务：每天 / 每周 / 每隔 N 小时自动跑，成果发到频道。用于：用户说「以后每天早上 10 点出一份发到这个频道」「每两小时巡检一次，有错误再发」「定时 / 到点 / 固定时间」；改或删已有的定时任务；或对话里出现 mcp__acpp-cron 工具。核心方法：先在当前对话把事做一次并对齐口径，再把实际走过的步骤写成自包含的任务提示词——到点它在全新会话里跑，没有这次对话的任何记忆。触发词：每天、每周、每隔、定时、到点、固定时间、日报、周报、巡检、自动发、以后都、cron。"
---

# scheduled-task

工具是 `mcp__acpp-cron__cron_add` / `cron_list` / `cron_update` / `cron_remove`。
它们只在 Discord 子区会话里挂着；清单里没有就不是这个场景，正常回话。

## 先知道它是怎么跑的

- 到点后 bot 在**当前频道**发一条起始消息、以它开一个子区，在**全新会话**里执行任务提示词。
  工具面与你现在这条会话一样（库、机器都锁在频道绑定上，html-report / send_file 都在）。
- 跑完起始消息会编辑成一行状态与摘要（取回复的第一行），子区里是完整成果，用户可以在子区里追问。
- 没有人在线：提问会被自动取消；需要审批的命令卡会 @ 建任务的人，没人点就超时失败。
- 巡检类任务无事时整条回复只写 `NO_REPORT`，起始消息变成「无需汇报」，子区归档。

所以任务提示词是**你写给未来的、没有记忆的自己的一封信**——它要能让一个刚打开的会话不问任何问题就干完。

## 三步：做一次 → 固化 → 复述

1. **先做一次**。用户第一次提「每天发一份 xx」时，如果这件事还没在当前对话里做过，
   先按正常流程做出来（db-query 查库 / server-inspect 看日志 / html-report 出报告 / send_file 交付），
   把口径跟用户对齐：哪些表、什么时间窗、哪些指标、报告长什么样。
   跳过这一步直接写提示词，第一次运行多半跑歪。
2. **固化**。把**刚才实际走过的步骤**写成提示词，调 `cron_add`。写完对照下面的清单逐项核对。
3. **复述**。建完用一句话向用户确认：「每天 10:00（Asia/Shanghai）跑《用户七日行为日报》，
   查 pp-game/prod 过去 7 天的 …，出 HTML 报告发到本频道」。任务卡已在子区里，上面有立即运行 / 停用 / 删除。
   多久一次要说清——每次运行都是一整条会话，用户心里要有数。

## 提示词自包含清单（每条都要有）

| 要写什么 | 反例 | 正例 |
| --- | --- | --- |
| 数据来源 | 「像刚才那样查」 | 「按 db-query 技能查数据源 `pp-game/prod` 的 `user_login`、`orders` 表」 |
| 时间窗 | 「最近的数据」 | 「以运行时刻为准，取过去 7 天（不含当天）」 |
| 口径 | 「活跃用户」 | 「DAU = 当天有登录记录的去重 user_id；付费 = orders.status='paid'」 |
| 输出结构 | 「写个报告」 | 「先一行结论（含关键数字与环比），再要点；按 html-report 写成单文件报告并 `report_open`，报告首屏放统计卡」 |
| 交付形态 | （不写） | 「报告经 report_open 打开即可；CSV 用 send_file as=file」 |
| 静默条件 | （不写） | 「巡检类：没有错误级别的发现，整条回复只写 NO_REPORT」 |
| 失败时 | （不写） | 「查询超时或连不上机器要如实说明，不算无事」 |
| 步骤纪律 | （不写） | 「先 COUNT 再取明细；grep 必须给 include 与 maxMatches」 |

不要写「同上」「参考上次」「按之前的口径」——新会话没有上次。
长配方（几十行 SQL、日志路径清单）可以先用 Write 存成工作目录里 `.acpp-cron/<任务名>/` 下的文件，
提示词里写明「读 `.acpp-cron/daily/queries.sql` 里的语句」；工作目录是持久的，下次运行读得到。

## 时间怎么表达

`cron` 是 5 段（分 时 日 月 周），按 `tz` 的墙钟解释，`tz` 缺省本机时区：

| 用户说 | cron |
| --- | --- |
| 每天早上 10 点 | `0 10 * * *` |
| 每个工作日 18:30 | `30 18 * * 1-5` |
| 每周一 9 点 | `0 9 * * 1` |
| 每两小时 | `0 */2 * * *` |
| 每月 1 号 8 点 | `0 8 1 * *` |
| 2 小时后 / 40 分钟后跑一次 | `in: "2h"` / `in: "40m"`（服务端按当前时刻换算，别自己算 at） |
| 明天这个时候再看一眼 | `in: "1d"` |
| 明天早上 9 点看一眼（只一次） | `at: "2026-09-04T09:00:00+08:00"`（具体钟点才用 at；「今天」是几号以工具描述里的「现在是」为准） |

用户说的时间是他所在时区的墙钟，不要换算成 UTC 再填。相对时间一律用 `in`：你没有钟表，自己算绝对时刻会错。

## 巡检类任务（日志 / 慢查询 / 健康检查）

- 时间窗用「自上次运行以来」：开场注入里有上次运行时间，提示词写「只看上次运行之后的新增」。
- 分级：错误 / 警告 / 提示。提示词里写清**只有错误级才值得发**，无事回 `NO_REPORT`。
- 工具失败不是无事：连不上机器、日志读不到、查询超时，都要如实汇报。
- 成本纪律照 server-inspect / db-query：先 tail 再 read、grep 必须限定文件与条数、COUNT 先于明细。

范本：[references/log-patrol.md](references/log-patrol.md)（日志与慢查询巡检）、
[references/daily-report.md](references/daily-report.md)（用户行为日报）。

## 改与删

- 「改成每天 9 点」「先停掉」「周报加上 xx」→ `cron_update`（改 prompt 传完整新版，不是补丁）。
- 「不用了 / 删掉」→ `cron_remove`；只是暂时不跑用 `cron_update` 的 `enabled:false`。
- 手上没 id 先 `cron_list`；用户问「上次跑成功了吗」也用它。

## 三个反例

- ❌ 用 sleep 循环、反复轮询、或让用户「到点再来叫我」冒充定时——只有 cron_add 才是定时。
- ❌ 没做过一次就凭想象写提示词——第一次运行就会在「表叫什么」上卡住。
- ❌ 提示词里写「像刚才那样」——新会话里没有刚才。

references/daily-report.md

# 范本：用户七日行为日报

场景：用户先让你分析了近七天用户行为并出了报告，然后说「以后每天早上 10 点这样出一份发到这个频道」。

```
cron_add
  name: 用户七日行为日报
  cron: 0 10 * * *
  tz: Asia/Shanghai
  prompt: |
    按 db-query 技能查数据源 pp-game/prod（本频道锁定的库），出一份《用户七日行为日报》。

    时间窗：以运行时刻为准，取过去 7 天（不含当天），按天分组；环比对象是再往前 7 天。
    指标与口径：
    - DAU：user_login 表当天有记录的去重 user_id
    - 新增用户：users.created_at 落在当天
    - 付费用户 / 付费金额：orders.status = 'paid'，金额取 amount 求和（单位分，报告里换成元）
    - 次日留存：第 N 天新增用户中第 N+1 天有登录记录的比例
    查询纪律：先 COUNT 确认规模，聚合让数据库算（GROUP BY），不拉明细；单条查询超 30 秒改收窄条件。

    输出：
    1. 回复第一行写一句结论（含 DAU、付费金额与环比，如「DAU 12.3k ↓2%，付费 ¥8.1k ↑5%」）；
    2. 按 html-report 技能写成单文件报告 tmp/用户行为日报-<日期>.html：首屏一排统计卡（DAU / 新增 / 付费 / 留存，带环比），
       七日折线图（内联 SVG，数据点手写），异常波动列表（环比超 ±15% 的天），最后一段「值得关注」；
    3. 调 mcp__acpp-report__report_open 打开报告；不要再另外 send_file。
    没查到的数字不要编，报告里留空并注明。
```

references/log-patrol.md

# 范本：服务器错误日志与慢查询巡检

场景：频道锁定了一台服务器与一个库，用户说「每两小时巡检一次，有错误再发」。

```
cron_add
  name: 线上巡检
  cron: 0 */2 * * *
  tz: Asia/Shanghai
  prompt: |
    按 server-inspect 技能巡检本频道锁定的服务器，按 db-query 技能查本频道锁定的库，只汇报错误级别的发现。

    时间窗：只看**上次运行之后**的新增（开场注入里有上次运行时间；第一次运行看最近 2 小时）。
    步骤：
    1. 先读工作目录里的 docker-compose*.yml 推容器名与日志挂载路径，不要猜；
    2. docker_ps 看各容器状态与重启次数（重启次数在涨就是错误级）；
    3. docker_logs 用 since 限定时间窗，grep 参数取 "ERROR|panic|fatal"，tail 不超过 500；
       挂载出来的文件日志用 server_grep，必须给 include（*.log）与 maxMatches（50）；
    4. 慢查询：db_query 查 mysql.slow_log（或 performance_schema.events_statements_summary_by_digest），
       取时间窗内耗时 > 5 秒的语句，按 digest 聚合出现次数与最大耗时，只取前 10；
    5. 磁盘：server_info 里任一挂载点用量 > 90% 算错误级。
    分级：容器异常重启 / ERROR 或 panic / 慢查询 > 5s / 磁盘 > 90% 为错误级；WARN 与偶发超时为警告级，不单独发。

    输出：
    - 没有错误级发现：整条回复只写 NO_REPORT。
    - 有：第一行一句总结（如「3 条 ERROR · 2 条慢查询 >5s · 磁盘 82%」），然后按「容器 / 日志 / 慢查询 / 资源」分段，
      每段给出证据（日志行摘录、SQL digest 与耗时）与建议的下一步；错误日志超过 20 行的按 html-report 出报告并 report_open。
    - 连不上机器、日志读不到、查询超时：如实写出来，这不是无事。
```