面向 AI 任务助理的资源中心调度内核：把任务、执行者、工作上下文和外部协作工具接到一个可验证的状态机里。
Task Scheduler 是“小龙虾”任务助理背后的调度侧项目。它不直接替代 TickTick、DingTalk、Jira 或 OpenClaw，而是做一件更窄也更关键的事：提供一个稳定的调度内核，让 AI 助理可以用明确的命令把“谁在做什么、任务是否完成、工作上下文在哪里、什么时候该提醒”这些状态管理起来。
这个仓库目前已经落地的是 resource-centered scheduler。也就是说，系统以“资源”作为调度中心：人和智能体都可以作为资源注册进来，资源被分配任务后进入 occupied，离开任务后回到 away。任务池来自外部系统，工作上下文同步到协作工具，状态变化通过 MCP / CLI / HTTP / webhook 暴露给小龙虾和其他调用方。
日常团队协作里，很多任务不是没人会做，而是状态散落在多个地方：
- 任务计划在 TickTick、Jira 或其他任务系统里。
- 实际执行过程在聊天、文档、代码仓库或临时备注里。
- 人是否有空、任务是否被中断、上下文是否可追踪，常常靠记忆维护。
- AI 助手可以对话，但如果没有稳定状态源，它也容易只是在“聊天”，而不是可靠调度。
Task Scheduler 的定位是把这些零散状态收敛成一个小而硬的运行时：
flowchart LR
User["团队成员 / AI Agent"] --> Lobster["小龙虾<br/>OpenClaw task-planner"]
Lobster -->|MCP / CLI / HTTP| V2["SchedulerServiceV2<br/>ACK + snapshot"]
V2 --> Queue["Command Queue"]
Queue --> Core["SchedulerService<br/>XState resource machine"]
Core --> Store["File / InMemory Repositories"]
Core --> Effects["EffectExecutor"]
Effects --> TickTick["TickTick<br/>任务池 / 完成状态"]
Effects --> DingTalk["DingTalk<br/>WorkContext 待办"]
Effects --> Jira["Jira<br/>Task = WorkContext 适配"]
Effects --> Webhook["OpenClaw webhook<br/>structured events"]
Webhook --> Lobster
这个仓库的另一个重点，是探索 如何在 agent 辅助下把需求说清楚，再让 AI 可靠地写代码。后续这套方法成熟后会单独拆成方法论仓库；在当前项目里，它先作为真实工程过程运行。
这里的 AI 开发流不是“给一句话让模型自由发挥”，而是把不稳定的想法逐步压成可执行的工程输入：
flowchart LR
Discussion["discussion<br/>原始讨论与决策背景"] --> Reqs["reqs/user-stories<br/>用户场景与验收口径"]
Reqs --> Feature["features/FEAT-*<br/>能力索引与上下游链接"]
Feature --> Spec["spec/SPEC-*<br/>模块合约与不变量"]
Spec --> Plan["plans/PLAN-*<br/>一轮可执行计划"]
Plan --> Tests["tests/*<br/>TDD: Red / Green / Refactor"]
Tests --> Code["src/*<br/>实现与重构"]
Code --> Docs["docs:index / docs:spec<br/>回写文档索引"]
核心做法：
docs/discussion/在内部用于保存讨论结论和决策来源，用来记录“为什么要做”。公开展示版不发布原始 discussion 内容，只保留已经结构化后的 req / spec / plan / test / architecture。docs/reqs/user-stories/把讨论拆成用户视角的场景、期望行为和验收条件。docs/features/只做薄索引，说明一个能力是什么、从哪里来、依赖什么、当前状态如何。docs/spec/写模块合约和不变量；其中一部分由测试自动抽取，避免 spec 和代码长期漂移。docs/plans/写单轮执行计划，让 agent 拿到后可以直接实施，而不是每次重新解释背景。tests/是可执行需求。新行为优先通过 Vitest 写成失败测试，再补最小实现，再重构。docs/CONVENTIONS.md规定文档分类、编号、frontmatter 和“同一事实只写一处”的规则，减少 AI 在长上下文里反复复制、改错或过度发挥。
这套流程的目标，是让人类把“意图、边界、验收”说清楚，让 agent 在明确轨道里完成检索、编码、验证和文档同步。它也让项目能留下完整的决策链：从一次讨论，到用户故事，到模块 spec，到 plan，到测试，再到实现。
小龙虾是对话与决策入口，Task Scheduler 是状态机与副作用执行层。两者的边界很清楚：
| 角色 | 负责什么 | 不负责什么 |
|---|---|---|
| 小龙虾 / OpenClaw task-planner | 理解用户意图、查询任务池、推荐下一步、调用调度命令、把通知翻译成人话 | 直接改调度器状态文件 |
| Task Scheduler | 命令 ACK、资源状态流转、WorkContext 生命周期、外部系统同步、结构化通知 | 自然语言决策和对话编排 |
| TickTick / Jira | 任务来源或任务状态来源 | 调度资源池 |
| DingTalk | 承载执行过程中的 WorkContext / 待办链接 | 决定谁该做什么 |
小龙虾只需要掌握三个写命令：
| 命令 | 场景 | 结果 |
|---|---|---|
resource_register |
“把某个人/智能体加入资源池” | 新资源进入 away，可被调度 |
resource_assign |
“让某个资源开始做某个任务” | 资源 occupied，创建/关联 WorkContext |
resource_away |
“做完了”或“先中断” | finish 完成上下文，interrupted 暂停上下文 |
这种设计让小龙虾可以专注于“该不该推荐、怎么解释、什么时候提醒”，而不是在 prompt 里维护一堆易错的状态规则。调度器收到命令后会立即返回 ACK + snapshot，再由后台 worker 推进状态机和外部副作用。
当前状态机由两个布尔维度决定：
T：任务队列是否有待处理任务。R：资源池是否有 away 资源。
quadrantChart
title Scheduler states
x-axis "T = 0" --> "T > 0"
y-axis "R = 0" --> "R > 0"
quadrant-1 "REST<br/>有任务，也有可调度资源"
quadrant-2 "IDLE<br/>无任务，有可调度资源"
quadrant-3 "WORK<br/>无任务，全部 occupied"
quadrant-4 "BUSY<br/>有任务，但无 away 资源"
| 状态 | 条件 | 含义 |
|---|---|---|
idle |
无待处理任务，有 away 资源 | 没任务可分配 |
rest |
有待处理任务，有 away 资源 | 可以提醒/推荐任务 |
busy |
有待处理任务，无 away 资源 | 有积压但没人空闲 |
work |
无待处理任务，无 away 资源 | 所有人都在工作中 |
实现上，任务队列不存进状态机内部。每次事件都携带当前 task queue，资源状态则由 Resource / WorkContext 持久化恢复。
WorkContext 是“任务正在被执行”的上下文对象。它和 Task 不是一回事：
| 概念 | 回答的问题 | 生命周期 |
|---|---|---|
| Task | 要做的任务是什么？ | 来自 TickTick / Jira 等外部任务系统 |
| WorkContext | 谁正在做它，执行上下文在哪里？ | 分配时创建或关联，完成/取消时归档 |
| ExternalMapping | 外部系统里的 ID 是什么？ | 用于 adapter 映射 |
在 TickTick + DingTalk 路径中，Task 来自 TickTick，WorkContext 通常落到 DingTalk 待办。在 Jira 路径中，Jira issue 可以同时扮演 Task 和 WorkContext，因此 adapter 层实现了双向解析，而不需要改核心状态机。
- TypeScript 领域模型：
Task、Resource、WorkContext、ExternalMapping。 - XState v5 状态机：
idle/rest/busy/work四态。 SchedulerService：资源分配、离开、启动水合、WorkContext 生命周期。SchedulerServiceV2：ACK + snapshot、命令队列、通知缓冲、主动 tick 通知。EffectExecutor：统一执行 TickTick、DingTalk、Jira、webhook / structured event 副作用。- TickTick adapter：任务池查询、任务完成/重开映射。
- DingTalk MCP adapter：多账号连接池、待办创建/暂停/完成、WorkContext 链接同步。
- Jira adapter：把 Jira issue 同时映射为 Task / WorkContext，支持状态流转。
- 对外接口：MCP v2、CLI v2、HTTP v2。
- 文档体系：
docs/spec、docs/architecture、docs/features、docs/bugs、docs/plans。
这些是产品方向或后续能力，不应理解为当前已经完整实现：
- Qualify Score 计算。
- 探索性任务 / 事务性任务自动分流。
- 基于适配度的自动推荐算法。
- 完整的可视化看板产品形态。
- Docker 化后的生产级 workspace 隔离部署。
src/
domain/ # 中立领域模型与 XState 状态机
usecases/ # SchedulerService / SchedulerServiceV2 / EffectExecutor
adapters/ # TickTick / DingTalk / Jira / persistence / v2 notification
interfaces/ # Repository、Provider、TaskContextLink 等接口契约
mcp/ # task-scheduler-v2 MCP server
cli/ # scheduler-v2 CLI commands
web/ # HTTP API 与配置页面
clawagent/
workspace-task-planner/ # 小龙虾 task-planner 的 prompt、工具说明和工作流
workspace-worklog-narrator/
docs/
architecture/ # 架构与运行时设计
spec/ # 模块级规格
features/ # FEAT roadmap
bugs/ # 已知问题和修复跟踪
plans/ # 分阶段实施计划
reqs/ # 用户故事与验收条件
discussion/ # 内部讨论来源；公开展示版不包含原始内容
npm install
npm test
npm run build开发模式：
npm run dev
npm run dev:web常用质量检查：
npm run lint
npm run test:coverage
npm run docs:all集成类能力需要本地配置 TickTick、DingTalk MCP、Jira 或 OpenClaw gateway。真实 token 不应提交到仓库；本地配置默认通过 config.json、~/.task-scheduler 或用户侧 credentials 文件提供。
- 中立模型优先：核心 Task 不绑定 TickTick、Jira 或 DingTalk 字段。
- Adapter 隔离外部差异：外部系统差异放在 adapter 层消化。
- 状态机是资源状态唯一写入者：避免 prompt、脚本、外部工具直接改状态文件。
- ACK 优先，副作用异步：调用方先拿到 snapshot，外部同步由 worker / effect job 处理。
- 文档跟着实现走：架构、规格、feature、bug、plan 分层记录，避免把讨论稿当成最终状态。
- TDD / XP 风格演进：核心行为用 Vitest 覆盖，小步提交，回归验证。
- 让 AI 吃结构化上下文：先把需求拆进 discussion / reqs / spec / plan，再让 agent 编码和验证。
- AI 助理不是“另一个聊天入口”，而是通过 MCP 调用一个有状态、有测试、有副作用边界的调度内核。
- 人和 Agent 都被抽象为 Resource，统一走同一套状态流转。
- WorkContext 把“开始做任务之后产生的上下文”从 Task 本身拆出来，适配 TickTick、DingTalk、Jira 的不同现实。
- 小龙虾不能直接写内部状态，只能通过命令面协作；这让对话智能和系统正确性解耦。
- AI 开发流本身也被工程化：讨论、需求、spec、plan、测试和实现之间有清晰链路。
- 已经保留从单机 CLI、MCP agent 调用到 HTTP/API 化的演进路径。