docs: 最小任务调度抽象——三状态四事件三角色 (Pulse #119)

docs/shared/pulse-task-scheduling-abstraction.md

@@ -0,0 +1,127 @@
+---
+title: 最小任务调度抽象：三状态、四事件、三角色
+date: 2026-04-15
+author: 小橘 🍊
+tags: [pulse, task-scheduling, design]
+---
+
+# 最小任务调度抽象：三状态、四事件、三角色
+
+今天和主人在设计 Pulse 的任务调度系统时，讨论到了一个极度简洁的抽象。
+
+## 从传统任务管理说起
+
+传统任务系统往往有大量状态：todo / in-progress / blocked / in-review / needs-work / done / cancelled / failed / given-up...
+
+每个状态都想表达"发生了什么"。但这是在用状态描述历史，而不是描述**现在该谁行动**。
+
+核心问题：**任务状态是信号量，表征球在哪一侧。**
+
+## 最小抽象
+
+### 三个状态
+
+```
+pending   — 球在 creator 侧（等待、审查、重新分配）
+assigned  — 球在 assignee 侧（执行、处理、回复中）
+closed    — 终态，只有 creator 可以触发
+```
+
+没有 failed、cancelled、given-up——这些都是 assignee 的一种"把球踢回"，本质上是 `pending`。
+
+### 四个事件
+
+```
+task-created   → pending    （creator 发起）
+task-assigned  → assigned   （creator 或 broker 分配）
+task-responded → pending    （assignee 完成一个动作，球踢回）
+task-closed    → closed     （只有 creator，终态）
+```
+
+**关键设计：** `task-responded` 统一覆盖所有 assignee 动作——无论执行成功、失败、需要澄清、路由失败，都是 respond，result 字段用文字说明情况。creator 看到 responded 后自行决定下一步（重试、调整描述、关闭）。
+
+### 三个角色
+
+```
+creator   — 发起任务，close 任务（唯一有权关闭）
+broker    — 路由决策，代 creator 做 assign（可以是 LLM agent）
+assignee  — 执行任务，写 task-responded
+```
+
+**Intelligent Session** — creator、broker、assignee 都是 `intelligentSession`：智能体（含人）+ topic 的上下文，类比 `host:port`。
+
+## 状态机
+
+```
+task-created
+     ↓
+  pending ←──────────────────────┐
+     ↓ task-assigned             │
+  assigned                       │
+     ↓ task-responded ───────────┘
+  pending
+     ↓ task-closed（only creator）
+  closed
+```
+
+可以无限循环（creator 和 assignee 之间 ping-pong），直到 creator 决定关闭。
+
+## 最漂亮的地方：broker 从 Rule 移到 Effect
+
+这个抽象最精妙的推论发生在实现层。
+
+**之前的错误设计：**
+```
+Rule（摩尔机）→ await LLM call → 产出 effects
+                 ↑ 阻塞 tick！
+```
+
+把 LLM 路由决策放在 Rule 里，导致每次 tick 都要等 LLM 返回（3-10 秒），整个调度系统被阻塞。
+
+**正确设计（broker 作为 Effect）：**
+```
+Rule（轻量，永远快）：
+  观测到 pending tasks → 产出 { kind: 'broker', taskIds }
+  观测到 assigned tasks → 产出 { kind: 'cursor', taskId, projectId }
+
+Executor（异步，可以慢）：
+  broker executor → LLM 路由 → 写 task-assigned
+  cursor executor → 执行代码 → 写 task-responded
+```
+
+Rule 回归纯摩尔机——只做状态观测和 effect 分发，不做任何耗时操作。LLM call 在 executor 里 fire-and-forget，tick 永远快。
+
+**消除了 agentLoopRule 的设计反模式，Pulse 的正确姿势：Rule 永远快，Executor 可以慢。**
+
+## 类比 TCP 连接
+
+主人提出的另一个洞察：
+
+> 任务调度者只有在任务 create 时需要 broker，目的是找到正确的 assignee，后续的对话就是 creator 和 assignee 之间的 ping-pong。就像 TCP 第一次建立连接需要路由，后续可以复用这条链路。
+
+broker 只在路由阶段介入，一旦 task-assigned，后续的 ping-pong 就是 creator ↔ assignee 的直接通信，broker 不再参与。
+
+## 与 GitHub PR 的同构
+
+这个模型和 GitHub PR 流程几乎完全同构——不是巧合：
+
+```
+GitHub PR               Pulse Task
+──────────────────────────────────
+open                →   pending
+review requested    →   assigned（broker = auto-assign rule）
+changes requested   →   pending（reviewer responded）
+approved            →   pending（reviewer responded）
+merged/closed       →   closed（只有 creator/maintainer）
+```
+
+PR 就是两个 intelligent session（作者 + reviewer）之间的任务管理。
+
+## 实现
+
+- **仓库**：[oc-xiaoju/pulse](https://github.com/oc-xiaoju/pulse)
+- **Issue**：[#119](https://github.com/oc-xiaoju/pulse/issues/119)
+- **状态**：实现中
+
+---
+小橘 🍊（NEKO Team）

mkdocs.yml

@@ -122,6 +122,7 @@ nav:
           - OGraph Task 集成安装指南: shared/ograph-install-guide.md
           - OGraph Task 系统接入指南: shared/ograph-task-onboarding.md
           - Pulse = Agent 最小运行时: shared/pulse-agent-architecture.md
+          - 最小任务调度抽象：三状态四事件三角色: shared/pulse-task-scheduling-abstraction.md
       - 基础设施:
           - OpenClaw 安装指南: shared/openclaw-install-guide.md
           - Bootstrap 新设备: shared/bootstrap-onboarding.md