myagents-task-automation

# MyAgents Task 与自动化 ## 先建立 Task 产品心智模型 Task 是 MyAgents 对“需要在当前对话之后继续存在、在未来被执行和追踪的工作”的统一承载。它不是一条临时提醒，也不是一段 Cron 表达式；它把用户的行动目标保存成有身份、有状态、有执行记录、可暂停和可恢复的工作项，并在合适的时机把工作交给 AI。 一个自动化 Task 由五个彼此独立的决策组成： ```text Task = action（AI 被激活后做什么，权威内容在 task.md） + schedule（何时产生一次执行机会） + activation（机会出现时是否真的唤醒 AI） + Session routing（在哪段上下文中工作） + end conditions（何时不再继续） ``` schedule 只负责产生执行机会，不等于 AI 已经运行；activation 再决定这个机会是直接进入 AI Turn，还是先由程序筛选。这样，普通定时任务与“持续检查、命中才处理”共享同一个 Task 生命周期，而不需要两套产品实体。 Task 解决四类问题： - **意图持久化**：工作不依赖当前聊天回合继续存在，之后仍可查到目标、配置和状态。 - **未来触发**：支持指定时间一次、固定间隔和 Cron 墙钟计划。 - **按需唤醒**：既能每次到点都运行 AI，也能先做低成本确定性检查，避免无意义的模型调用。 - **治理与追踪**：统一管理 Session 去向、运行历史、暂停/恢复、结束条件和失败健康状态。 ### 与相邻能力的边界 | 用户真正需要的是什么 | 正确承载 | |----------------------|----------| | 现在就在当前回合完成一件事 | 直接执行，不创建 Task | | 先保存一条文字或音频记录，暂时不执行 | Record | | 一项已经明确、需要未来触发或持续追踪的工作 | Task | | 当前 Session 围绕同一目标连续多轮自主推进 | Goal Mode，不用循环 Task 模拟 | | App 完全退出后仍必须由 OS 常驻执行 | 不属于 MyAgents Task；不要伪装成已部署成功 | Cron 只是已发布的兼容命令面，不是另一种资源；Sensor 也不是独立产品实体。`TaskStore` 是唯一权威，新 Agent 工作流统一使用 `myagents task ...`。 ### 生命周期应怎样理解 创建 Task 只是把它持久化为 `Todo`；首次 `run` 后，时间型 Task 进入 `Running`，表示 scheduler 已启用，不表示 AI 此刻正在执行。每个 tick 经 activation 后才可能产生 AI Turn。首次 tick 由 schedule 决定：固定 interval 默认在 `run` 后约 2 秒产生第一次机会（要延后就显式设置 `--startAt`），Cron 等到下一个墙钟点，scheduled 等到 `dispatchAt`。`stop` 暂停未来调度并停止活跃执行；`start` 按保留的 schedule anchor 恢复，anchor 已过期时下一次机会可能接近当前时间，应以回执里的 `nextExecutionAt` 为准。`rerun` 重新派发终态 Task；`run-now` 是一次绕过 Detector 的人工执行，不改变 schedule 或 checkpoint。 MyAgents App 必须在线才会产生 tick 或执行检查。Task 可以在 App 后台驻留时运行，但完全退出或 OS 休眠期间不会运行，也不会逐个补跑错过的 tick。 正常创建和列表会自动继承当前 MyAgents workspace，不需要先查 ID。只有明确跨 workspace 操作时才同时传 `--workspaceId` / `--workspacePath`；若要诊断当前身份，使用 `myagents agent current --json`。命令语法有疑问时运行 `myagents task readme` 获取当前紧凑契约；精确参数以对应命令的 leaf help 为准。 ## 选择激活方式 | 方式 | 每个 schedule tick 的效果 | 适用情况 | Task 配置 | |------|---------------------------|----------|-----------| | `always` | 直接派发普通 Task AI Turn；没有前置程序判断 | 每次到点都值得让 AI 行动，例如提醒、日报、定期总结；或是否行动只能由模型理解 | 省略 `--trigger-file` | | `command Detector` | MyAgents harness 先运行本地命令；`quiet` 不创建 Session、不唤醒 AI，`activate` 才把事件证据交给普通 Task AI Turn | 外部条件能由廉价、确定的程序判断，而且大多数检查应该保持静默 | 验证后传 `--trigger-file` | 默认选择 `always`。只有“程序可以可靠判断是否命中”“运行程序明显比唤醒 AI 更便宜”“未命中时不需要 AI 参与”同时成立，才使用 `command Detector`。不要创建一个脚本，再让脚本无条件输出 `activate`；那与 `always` 等价，只增加故障点。 一旦选择 `command Detector`，在编写脚本或 Trigger 前完整读取 `references/command-detector.md`。该 reference 是命令结构、stdin/stdout 协议、checkpoint、fixture 测试、安全边界和 failure 行为的详细契约；普通 `always` Task 不需要加载它。 ## 决策顺序 1. **行动**：命中时 AI 具体做什么。把它写进 `task.md`；Detector 的输出只能提供事件证据，不能代替行动目标。 2. **时间**：选择未来某时执行一次、固定间隔或 Cron 表达式。墙钟时间默认使用本机 IANA 时区；用户指定其他时区时显式保存。 3. **激活策略**：按上表选择 `always` 或 `command Detector`。只向用户澄清实际效果，不要求用户理解这两个内部名称。 4. **Session**：延续当前/已有上下文用 `single-session`；每次需要隔离上下文用 `new-session`。 5. **结束**：一次性任务自然结束；循环任务根据用户意图选择最大 AI 执行次数、截止时间、允许 AI 主动退出，或持续到用户暂停。Detector 的 quiet 检查不计入 AI 执行次数。 只澄清会改变这些选择的缺失信息。普通的明确创建请求在信息齐全后连续完成准备、验证、创建、回读和启动，不逐步索要批准；删除仍遵守 `/myagents-cli` 的确认规则。若本轮来自 `<TASK_DISCUSSION>`，则由 `myagents-task-alignment` 负责候选文档与创建前确认，必须等用户明确确认后才 mutation。 ## `always`：到点直接激活 先用标准文件工具写 `task-action.md`，再创建 Task。长文本不要拼进 shell command。 未来某时执行一次： ```bash myagents task create-direct --name "send release reminder" \ --taskMdFile task-action.md --executionMode scheduled \ --dispatchAt 2026-08-04T09:00:00+08:00 \ --runMode single-session --preselectedSessionId current --json ``` 周期执行： ```bash myagents task create-direct --name "daily report" \ --taskMdFile task-action.md --executionMode recurring \ --cronExpression "0 9 * * *" --cronTimezone Asia/Shanghai \ --runMode new-session --json ``` 固定间隔使用 `--intervalMinutes <n>`（最小 5 分钟）。默认首次 tick 在 `run` 后约 2 秒；如果用户希望“从一个 interval 之后才第一次检查”，同时传带时区的 `--startAt <ISO-8601>`。普通 Task 省略 `--trigger-file`，其有效激活策略就是 `always`。 ## `command Detector`：命中才激活 只有在上面的三个条件都成立后才进入本节。完整读取 `references/command-detector.md`，再编写脚本、隔离测试输入并部署；不要凭本文件的摘要猜协议。 条件 Task 与普通 Task 只有一个创建差异：验证通过后在 `create-direct` 加入生产用 `--trigger-file`。例如： ```bash myagents task create-direct --name "watch CI failure" \ --taskMdFile task-action.md --executionMode recurring --intervalMinutes 5 \ --runMode single-session --preselectedSessionId current \ --maxExecutions 1 --trigger-file trigger.production.json --json ``` 这里的 `--maxExecutions 1` 表示首次 activate 并完成 AI Turn 后结束；之前任意数量的 quiet 检查不消耗次数。需要持续观察后续事件时省略它。 ## 结束条件 创建 ordinary scheduled/recurring Task 时可组合： ```text --deadline <ISO-8601-with-offset> 到达该时刻后不再开始新 AI Turn --maxExecutions <positive-int> 限制已结算的 AI 执行次数 --aiCanExit true|false 是否允许任务内 AI 主动结束 ``` 当 `--aiCanExit true` 且行动已经完成、继续运行无意义时，Task 内的 AI 可以调用： ```bash myagents task exit --reason "goal achieved: ..." ``` 它不是临时失败的逃生按钮。瞬时错误应按 `task.md` 的处理策略重试或报告；不要擅自结束用户仍需要的周期任务。 ## 创建后的确定性流程 创建命令始终加 `--json`，从结果解析权威 `taskId`，然后回读并启用： ```bash myagents task get <taskId> --json myagents task run <taskId> --json ``` 创建、`get`、`run`、`rerun` 的 JSON 结果都提供固定的 `data.receipt`：从这里读取 `taskId`、`status`、`statusMeaning`、`changed`、`nextExecutionAt`、瞬时 `executionState` 和 `resultAccess`，不要猜测不同命令的旧字段层级。`Running` 只表示 scheduler enabled；重复或并发 `task run` 已经 Running 的 Task 会成功返回 `changed: false`，不会创建第二次派发，也不应重试。`start`、`stop` 的既有回执仍包含权威状态与 `nextExecutionAt`。首次从 Todo 启用用 `task run`；暂停后恢复用 `task start`；终态重新派发用 `task rerun`。不要通过目录时间或猜测名称寻找刚创建的 Task。 `resultAccess` 只解释现有结果通道：`single-session` 的结果留在绑定 Session；`new-session` 的结果留在各次执行 Session 和 `task runs` 历史。系统不会把执行结果自动推回创建 Task 的 Session，也不会把普通 assistant 输出自动复制为 Task 评论；需要沉淀到本地时间线时由 Agent 显式调用 `task comment`。 ## 治理 ```bash myagents task get <taskId> --json # 权威配置、状态、Detector health/checkpoint myagents task runs <taskId> --limit 5 --full --json # 最近 AI 执行历史与结果正文 myagents task check-now <taskId> # 真实 Detector 检查；提交状态，命中会激活 AI myagents task run-now <taskId> # 绕过 Detector，直接执行 AI myagents task stop <taskId> # 暂停 schedule，保留 checkpoint myagents task start <taskId> # 按原 anchor 恢复；查看回执 nextExecutionAt myagents task reset-checkpoint <taskId> # 只清平台 checkpoint myagents task update <taskId> --clear-trigger # 改回 always myagents task archive <taskId> # 用户专属的长期可恢复归档 myagents task delete <taskId> # 确认后不可恢复地删除；不删除工作区脚本 ``` `check-now` 会提交真实 MyAgents 状态；部署前不提交 MyAgents 状态的验证使用 `trigger test`（脚本自身副作用仍真实发生）。`run-now` 不改变 schedule anchor 或 Detector checkpoint。 归档和删除不是同一种“软删除”：`archive` 是长期可恢复的产品状态；`delete` 会立即停止调度、移除平台 Trigger state/pending activation，并从正常产品使用中不可恢复地移除 Task。TaskStore 只保留防止旧 Cron 重新迁移所需的内部 tombstone 与审计；没有 30 天恢复承诺，也没有 undelete 命令。两者都不会越权清理工作区脚本、脚本数据库或外部状态。 ## 本地 Task 评论 Task 可以作为跨 Session 的本地协作中枢。需要回看时间线时用 `myagents task comments <taskId> --json`。只有当结果、风险、经验或待用户决策的信息确实值得沉淀到 Task 时，Agent 才显式调用： ```bash myagents task comment <taskId> --body-file result.md --json ``` 在 Task 自身触发的执行 turn 内可省略 `<taskId>`；在用户评论注入的后续 turn 中，必须使用隐藏提醒提供的显式 Task ID。 回复某条评论时增加 `--reply-to <commentId>`。长文本始终先写文件，不把多行正文拼进 shell。普通 assistant 回复不会自动登记为 Task 评论；从本地 Task 评论收到的 query 应服从该轮 `TASK_COMMENT` reminder，而从 Space Issue Delivery 收到的 query 继续使用 Cloud Issue 的回复命令，二者不得默认双写。 ## 给用户的部署回执 部署成功后一次说明： - Task 名称与 ID - 何时执行或检查，包括时区 - 到点直接激活，还是满足什么程序条件才激活 - 激活后的 AI 动作 - 目标 Session 策略 - 结束条件或“持续到手动停止” - App 在线限制和 Task Center 治理入口 quiet 检查保持静默。activate 后由目标 Session 中的 AI 正常交付工作结果；Detector failure 只进入 Task health/backoff，不伪装成业务判断，也不再创建一个 AI Task 去监控 Detector。