proxycast/docs/aiprompts/task-agent-taxonomy.md

Task / Agent taxonomy 主链

这份文档回答什么

本文件定义 Lime 当前 Task / Agent / Coordinator 的唯一 taxonomy，主要回答：

• 哪些对象才算当前一等执行实体
• agent turn、subagent turn、automation job、scheduler tick、execution run 分别是什么关系
• execution tracker / scheduler / subagent / automation 各自属于哪一层，而不是继续互相抢“主入口”
• 哪些旧文档、旧术语、旧路径只能当专项说明或兼容壳，不能再反向定义当前主链

它是 长时执行与协作编排的 current 事实源，不是执行追踪专项计划，也不是单个服务的实现说明。

什么时候先读

遇到以下任一情况时，先读本文件：

• 调整 agent_runtime_spawn_subagent、send_input、wait_agent、resume_agent、close_agent
• 调整自动化任务的创建、调度、执行、投递或运行历史
• 调整 ExecutionTracker、agent_runs、执行状态聚合或 run 级读模型
• 调整 SchedulerService、scheduled_tasks、cron.run 或任何“后台轮询 / 心跳执行”逻辑
• 讨论“这是任务、子代理、自动化还是调度器”的边界归属

如果一个需求同时碰到“子代理 + 自动化”“调度 + 执行追踪”“会话回合 + 长时后台任务”里的两项以上，默认属于本主链。

固定 taxonomy

当前 Lime 只承认下面三类一等执行实体：

1. agent turn 前台会话回合。统一走 agent_runtime_submit_turn -> runtime_turn -> Query Loop 主链。

2. subagent turn 父会话派生出的 child session / teammate 回合。它是 agent turn 的协作变体，不是另一套执行引擎。

3. automation job 可持久化、可延时、可周期触发的后台任务。它是 durable coordinator，统一由自动化服务承接。

下面两类不是一等执行实体：

• scheduler tick 只是“发现到期任务并触发执行”的兼容触发器，不单独代表一个任务分类。

• execution run 只是跨入口的执行摘要与生命周期记录，不是 coordinator。本层统一由 ExecutionTracker 与 agent_runs 承载。

固定规则只有一句：

后续新增长时执行能力时，只允许落成 agent turn、subagent turn 或 automation job 三类之一；不允许再造第四类 runtime taxonomy。

固定心智模型

当前主链统一按下面这张图理解：

agent turn -> subagent turn / automation job -> ExecutionTracker(agent_runs) -> thread/session/evidence 读模型

这条主链意味着：

1. agent turn 是前台交互入口，主事实源仍然是 query-loop.md
2. subagent turn 是 child session 的协作入口，复用当前 agent runtime 与会话事实，不单独发明另一套 task 状态机
3. automation job 是唯一 durable 后台任务入口，可以触发 agent turn，但不应该自己再发明第二套 run 摘要系统
4. ExecutionTracker 只负责“这次执行怎么开始、怎么结束、归因到哪里”，不负责调度、分工或 parent/child 编排
5. scheduler tick 只负责触发 due job，不负责定义产品层 task taxonomy

代码入口地图

1. agent turn

• docs/aiprompts/query-loop.md
• src-tauri/src/commands/aster_agent_cmd/command_api/runtime_api.rs
• src-tauri/src/commands/aster_agent_cmd/runtime_turn.rs

固定规则：

• 前台回合只有一条 Query Loop 主链
• 子代理回合如果进入模型执行，仍然复用这条主链
• 不允许为长时任务再造第二套“聊天执行入口”

2. subagent turn

• src-tauri/src/commands/aster_agent_cmd/subagent_runtime.rs
• src-tauri/src/commands/aster_agent_cmd/command_api/subagent_api.rs
• src-tauri/src/commands/aster_agent_cmd/tool_runtime/subagent_tools.rs

当前这里负责：

1. spawn child session / teammate
2. 写入父子会话与 team membership
3. 将 child turn 放入后台执行
4. 处理 send_input / wait / resume / close
5. 发出 runtime stream/status 事件，维持父子状态投影

固定规则：

• subagent turn 当前不是新的 RunSource
• 在执行摘要层，它继续复用 chat 会话型 run 与 session_id / parent-child context / evidence 关联
• 需要新增子代理能力时，优先扩展这里，而不是绕去 scheduler 或自动化任务

3. automation job

• src-tauri/src/services/automation_service/mod.rs
• src-tauri/src/commands/automation_cmd.rs
• src/lib/api/automation.ts

当前这里负责：

1. automation_jobs 的创建、更新、删除与启停
2. 后台轮询和到期任务执行
3. run_job_now 手动触发
4. 输出投递、健康聚合与运行历史
5. 与 ExecutionTracker 的 RunSource::Automation 对接

固定规则：

• durable 后台任务统一走自动化服务
• 如果一个需求需要“稍后执行 / 周期执行 / 无前台会话也能继续跑”，默认先落 automation job
• 自动化任务可以触发 agent turn，但不允许自己再维护第二份 run 历史真相

4. execution run

• src-tauri/src/services/execution_tracker_service.rs
• src-tauri/crates/core/src/database/dao/agent_run.rs
• src-tauri/src/commands/execution_run_cmd.rs

当前这里负责：

1. 为 chat / skill / automation 记录统一生命周期摘要
2. 暴露 agent_runs 只读查询
3. 统一终态与错误归一化

固定规则：

• ExecutionTracker 是观测层，不是 coordinator
• RunSource::Chat 覆盖前台与子代理会话型回合
• RunSource::Skill 代表独立 skill 执行摘要，不是新的 task taxonomy
• RunSource::Automation 代表后台任务执行摘要

5. scheduler tick

• src-tauri/src/app/scheduler_service.rs
• src-tauri/crates/scheduler/*
• docs/develop/scheduler-task-governance-p1.md

当前这里负责：

1. 轮询 scheduled_tasks
2. 发现 due task
3. 执行并标记完成 / 失败

固定规则：

• 它当前是 compat 触发壳，不再是主 taxonomy
• 后续允许做治理减法、冷却恢复、兼容委托
• 不允许继续在这里长新的产品级任务语义、统一状态页或第二套编排模型

current / compat / deprecated / dead

current

• docs/aiprompts/task-agent-taxonomy.md
• docs/aiprompts/query-loop.md
• src-tauri/src/commands/aster_agent_cmd/subagent_runtime.rs
• src-tauri/src/services/automation_service/*
• src-tauri/src/services/execution_tracker_service.rs
• agent_runs
• automation_jobs

这些路径共同构成当前唯一 taxonomy：

• 前台执行看 agent turn
• 协作执行看 subagent turn
• 后台 durable 执行看 automation job
• 执行摘要看 ExecutionTracker

compat

• src-tauri/src/app/scheduler_service.rs
• src-tauri/crates/scheduler/*
• scheduled_tasks
• docs/develop/scheduler-task-governance-p1.md

保留原因：

• 仓库里仍存在到期任务轮询与 cron.run 兼容链路
• 这些路径目前仍承接“发现任务并执行”的历史职责

退出条件：

• 后续如果 scheduler 继续留存，也必须明确只做“触发器 / 兼容壳”
• 若有新的后台任务能力，一律先判断能否落到 automation job
• 不再允许把 scheduler 写成新的 coordinator 事实源

deprecated

• docs/develop/execution-tracker-technical-plan.md
• docs/develop/execution-tracker-deprecation-plan.md
• docs/develop/execution-tracker-p1-p2-roadmap.md
• 任何新增的 heartbeat_executions 写路径或读取依赖
• 任何把 heartbeat 当成与 chat / skill / automation 并列 run source 的新设计
• 任何把 scheduler tick / cron / 心跳任务 当成独立 task taxonomy 的新设计

这些路径仍可作为历史实现说明或退场清单，但不再承担 current taxonomy 定义权。

dead

• automation_jobs.payload.browser_session

当前自动化服务已在启动与执行阶段主动停用这类任务；它只能迁移或删除，不能继续创建、更新或恢复为 current 能力。

最低验证要求

如果本轮改动涉及本主链，至少按边界选择最贴近的验证：

• 纯文档 / 分类回写：npm run harness:doc-freshness
• 改 ExecutionTracker 或 agent_runs：相关定向 Rust 测试
• 改子代理 runtime：subagent_runtime.rs 或 runtime_turn 的定向测试
• 改自动化命令 / 服务：自动化服务定向测试，必要时补 test:contracts
• 改 scheduler / cron 命令：scheduler 或 websocket RPC 定向测试

这一步如何服务主线

M2 的目标不是把所有长时执行代码一次性重写，而是先把 taxonomy 收成唯一事实源。

从现在开始：

• 解释前台协作执行时，回到 agent turn / subagent turn
• 解释后台 durable 执行时，回到 automation job
• 解释执行摘要时，回到 ExecutionTracker
• 解释 scheduler 时，默认把它视为 compat 触发壳

这样后续的 M3 Remote runtime、M4 Memory / Compaction、M5 State / History / Telemetry 才不会继续被长时任务边界反复打断。