Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

22.4 KB
Raw Blame
export type ScheduleKind = 'cron';
export type AgentKind = 'claude-code' | 'codex' | 'pi';
export type ScheduleStatus = 'active' | 'paused' | 'expired';
export type ScheduleWorkspaceKind = 'project' | 'dialogue';
export type ScheduleExecutionMode = 'agent' | 'script';
export type ScriptCapability = 'jira.read' | 'jira.comment' | 'sessions.dispatch' | 'feishu.read';

/**
 * Host-owned session context key for the scheduler run currently dispatched
 * through a session. It is not exposed in the agent prompt; scheduler MCP
 * tools use it to recover the authoritative run during auto-resume.
 */
export const SCHEDULER_RUN_ID_VENDOR_OPTION = '__cindySchedulerRunId';

/** 一次调度执行由自动到点触发,还是由用户显式 runNow 触发。 */
export type ScheduleFireSource = 'automatic' | 'run-now';

/**
 * Scheduler 内部执行阶段。阶段只用于运行期诊断,不持久化到 schedule_runs。
 * 它覆盖从抢占排期到终态落库的整个槽位生命周期。
 *
 * 'queued' 是**纯等待**阶段:runner 已把本轮 prompt 排进目标会话的队列,正在等
 * 会话空闲后被派发 —— 此时没有 agent 子进程、没有 MCP 注册、不烧 token。它刻意
 * 不计入并发闸门(见 Scheduler.tick 的槽位计算):并发上限防的是"同时跑太多
 * agent",纯等待占着配额会让整个调度器被卡住的会话拖死(2026-07-29 实事故:
 * 4 个排队心跳占满全部槽位,其余任务停摆 3.5 小时)。
 */
export type ScheduleRunPhase =
  | 'loading'
  | 'claiming'
  | 'persisting'
  | 'running'
  | 'queued'
  /**
   * 排队者已决定**本轮不再执行**(endQueueWait(false):撤项 / 失败 / abort),正在走
   * 自己的收口。既不算纯等待(卡死守卫要看得住它),也不该占并发槽(它明确不会执行)——
   * 复位成 'running' 会让 slotsInUse 临时超过 maxConcurrentRuns,UI 上冒出 9/8
   * (review #944 第十五轮)。
   */
  | 'cancelling'
  | 'finalizing';

/** 当前 Scheduler 实例中的一条结构化 in-flight 记录。 */
export interface SchedulerInflightRun {
  scheduleId: string;
  scheduleName?: string;
  runId: string;
  source: ScheduleFireSource;
  executionMode?: ScheduleExecutionMode;
  startedAt: number;
  /** 自动任务从到期到真正获得槽位的等待时间;runNow 没有此字段。 */
  slotWaitMs?: number;
  phase: ScheduleRunPhase;
  /**
   * 最近一次收到执行进展信号的时刻(runner 经 FireContext.onProgress 打点,
   * 每个会话事件一次)。卡死判定用"多久没有新反馈"而不是总执行时长 —— 后者会
   * 误砍真在干活的长任务。没收到过任何事件时等于 startedAt。
   */
  lastProgressAt: number;
}

/** 因自动并发闸门而尚未获得槽位的到期任务。 */
export interface SchedulerWaitingSchedule {
  scheduleId: string;
  scheduleName: string;
  /** 任务原定到期时间;当前等待时长可由 now - waitingSince 计算。 */
  waitingSince: number;
}

/**
 * Scheduler 的瞬时运行快照。通过 IPC 查询并在变化时推送给 renderer;不写数据库。
 */
export interface SchedulerRuntimeSnapshot {
  schedulerInstanceId: string;
  processId?: number;
  /** in-flight 记录总数(含 'queued' 纯等待与 'cancelling' 收口中的项)。 */
  inFlight: number;
  /**
   * 真正占用并发槽的 run 数(判据以 Scheduler.countSlotsInUse 为准:排除 'queued'
   * 纯等待与 'cancelling' 已决定本轮不执行的收口项)。UI 显示"N/max"要用本字段:
   * inFlight 含这两类不占槽的记录,直接拿它显示会出现"满负荷"却没有任务在跑的错觉。
   */
  slotsInUse: number;
  maxConcurrentRuns: number;
  inFlightRuns: SchedulerInflightRun[];
  waitingSchedules: SchedulerWaitingSchedule[];
}

/**
 * 一条 in-flight run 的展示 / 通知策略快照。给 renderer 在事件丢失或 hook 晚挂时
 * 重建 silenced / schedulerOwned 标记。sessionId 在绑定之前可能为空。
 */
export interface SchedulerInflightRunPolicy {
  runId: string;
  sessionId?: string;
  silenced: boolean;
}

/**
 * script 模式可授予的全量能力目录(单一来源):引擎校验白名单与 UI 能力选择器
 * 都从这里枚举——host 侧新增能力时只改这一处,选择器自动出现新项。
 */
export const SCRIPT_CAPABILITIES: readonly ScriptCapability[] = [
  'jira.read',
  'jira.comment',
  'sessions.dispatch',
  'feishu.read',
];

/**
 * Host-executed script task. The command is selected by the user and runs in
 * the schedule workspace; capabilities are default-deny grants for host RPC.
 */
export interface ScriptExecutionConfig {
  command: string;
  timeoutMs?: number;
  capabilities: ScriptCapability[];
}
/**
 * 'aborted': 用户暂停/删除计划,或调度器 stop(切账号/退出)主动中断。
 * 视为终态;落库时自带 readAt(不是用户要处理的失败,不产生未读红点)。
 * 'interrupted': app 关闭/崩溃时残留为 'running' 的 run,下次启动时由
 * Scheduler.start() 统一改写为本状态,区别于用户主动 abort。视为终态。
 * 'skipped': 前置检查脚本(preRunHook)exit 2 拦截,本轮未启动 agent。
 * 视为终态;落库时自带 readAt(生而已读,不产生未读红点)。
 */
export type RunStatus = 'running' | 'success' | 'failed' | 'aborted' | 'interrupted' | 'skipped';
/**
 * Release-compat tombstone — issue-triage 子模式已下线(见 0028/0029 migration),
 * 新代码不再创建 'issue-triage' 任务,但类型与 DB 列保留,允许老 release 版本继续
 * 读写老数据,避免跨版本运行时崩溃。新流程恒为 'prompt'。
 */
export type JobType = 'prompt' | 'issue-triage';

export interface ScheduleNotifyConfig {
  desktop: boolean;
  feishu: boolean;
  wecomGroup?: boolean;
}

/**
 * 前置检查脚本(Pre-run Hook)配置。任务触发时 runner 先执行该脚本再决定是否
 * 真正启动 agent(不启动 = 零 token 消耗)。协议对齐 Claude Code hooks:
 *   - exit 0 → 放行本轮
 *   - exit 2 → 跳过本轮(run 记 'skipped',照常重排下一次触发)
 *   - 其它退出码 / 超时 / 脚本不存在 → fail-closed:阻止本轮并记录失败结果
 * 脚本语言无关:command 是一条经系统 shell 执行的命令字符串,cwd = 本轮工作目录,
 * stdin 收到 JSON 上下文(scheduleId / name / firedAt / workingDir 等)。
 * Windows 下 shebang 不生效,command 应写显式解释器(`node x.mjs` / `python x.py`)。
 */
export interface PreRunHookConfig {
  /** 经系统 shell 执行的命令字符串。 */
  command: string;
  /** 超时毫秒;超时会阻止本轮执行。未配置 = 不限时(无默认超时)。 */
  timeoutMs?: number;
}

/** 前置检查一次执行的最终状态。 */
export type PreRunHookRunStatus = 'passed' | 'skipped' | 'failed' | 'timed_out' | 'aborted';

/** 前置检查对本轮任务的最终判定。 */
export type PreRunHookDecision = 'run' | 'skip' | 'block';

/**
 * 单轮前置检查的结构化结果。它独立于 agent 的 resultText:检查可能在创建 session
 * 之前就失败,也可能通过后继续得到正常的 agent 结果。
 */
export interface PreRunHookRunResult {
  /** Explicit successful check, including a healthy no-work skip. Optional for old hooks. */
  checkSucceeded?: true;
  status: PreRunHookRunStatus;
  decision: PreRunHookDecision;
  exitCode: number | null;
  durationMs: number;
  stdout: string;
  stderr: string;
  stdoutTruncated: boolean;
  stderrTruncated: boolean;
  /** 兼容现有执行/测试调用点的显式状态位。 */
  timedOut: boolean;
  aborted: boolean;
  spawnError?: string;
  /** spawn 失败或未形成有效退出结果时的诊断信息。 */
  error?: string;
}

export interface Schedule {
  id: string;
  name: string;
  prompt: string;
  /** Release-compat tombstone(见 JobType 注释)。新建恒为 'prompt'。 */
  jobType?: JobType;
  /** Release-compat tombstone:老 issue-triage 的 JSON 配置;新代码不读不写。 */
  jobConfig?: string;
  source?: 'user' | 'project' | 'bot';
  projectConfigId?: string;
  kind: ScheduleKind;
  cronExpr: string;
  timezone: string;
  recurring: boolean;
  /**
   * 手动触发模式:true 表示这条 schedule 不参与 cron 自动调度,
   * 永远只能通过 `runNow()` 触发。`cronExpr` 仍然保留(创建时仍要求合法)但不会被
   * 引擎读来计算 nextFireAt — 视作占位。`runNow` 不受影响。
   */
  manual: boolean;
  /**
   * Interval-mode 间隔毫秒。设了就走"上次完成 + intervalMs"语义(不再按 cron 槽位),
   * 引擎在 fireOne / start / resume / create 里都会优先检查本字段。
   *   - 首次触发:createdAt + intervalMs
   *   - 周期触发:finishedAt + intervalMs
   *   - 冷启动 / resume:now + intervalMs(不补发漏掉的,重新起 N 倒计时)
   * 没设(undefined)→ 维持 cron 槽位语义;`cronExpr` 在 interval 模式下仍保留为
   * 兼容/显式切回 Cron 时的表达式,但 UI 回显与引擎执行都必须以 intervalMs 为准。
   */
  intervalMs?: number;
  agentKind: AgentKind;
  /** Explicit model-picker Harness. Absent on legacy schedules: bound tasks keep their live Harness. */
  modelAgentKind?: AgentKind;
  /** Agent location for an explicit model choice: absent = inherit the bound task; '' = task host. */
  modelAgentDeviceId?: string;
  model?: string;
  /**
   * 显式选定的供应商(来源)id。undefined / 空 → 回落该 agent 原生默认来源
   * (no-break,与未升级行为字节级一致);非空才按 catalog RoutingDescriptor 路由。
   * 语义与 desktop `session-provider-store` 的 null 对齐。
   */
  providerId?: string;
  /**
   * 新建任务时 Agent 运行在哪台电脑(同账号另一台电脑或分享来的供应商)。undefined = 本机。
   * 设了时 providerId / model 属于那台电脑的已授权目录。绑定的任务仍存在时不使用:
   * 运行位置跟随被绑定的任务。
   */
  agentDeviceId?: string;
  effort?: string;
  /**
   * Fast 模式:仅 Codex 有意义(agent capability `hasFastMode` 为 true)。
   * true → runner fire 时透传给 codex agent,落到 app-server 的 ServiceTier.Fast,
   * 输出更快。Claude agent 忽略此字段。undefined/false → 标准 tier。
   */
  fastMode?: boolean | 'ultrafast';
  /**
   * New-session workspace semantics.
   * - project: workingDir is a user-selected project directory.
   * - dialogue: runner allocates an app-managed dialogue cwd per fire.
   *
   * Heartbeat schedules ignore this and use the target session's existing cwd.
   */
  workspaceKind: ScheduleWorkspaceKind;
  workingDir?: string;
  useWorktree: boolean;
  /** Script mode: lifecycle owner and sole dispatch target; no agent turn is started by the runner. */
  targetSessionId?: string;
  /**
   * 持续会话模式:true → runner 在第一次 fire 成功创建 session 后自动把 sessionId
   * 回写到本字段 `targetSessionId`,后续 fire 都走 heartbeat resume 同一 session,
   * 拥有完整上下文。false(默认) → 每次 fire 新建 session(旧行为)。
   *
   * 与 MCP 显式指定 `targetSessionId` 的"手绑 session"模式正交:显式绑定本身已经
   * 达到等效效果,`persistentSession=true` 在那种 schedule 上是 no-op;
   * 绑定的普通任务被归档时,自动输入与用户发送一样恢复原任务,完成后不重新归档。
   * 仅当任务被删除或不存在时:persistentSession=true → runner 清空
   * targetSessionId 并走新建分支;persistentSession=false → pause 整条 schedule。
   */
  persistentSession?: boolean;
  /**
   * 静默运行:true → 成功 run 默认不发通知、不产生未读小红点;任务 prompt 可自行说明
   * 哪些业务条件值得提醒,agent 在满足时调用 schedule_notify_current_run 主动上报。
   * 失败/异常仍然通知。未明确分类的新任务默认 false;检查入口显式设 true。
   * 存量已存选择保持不变。
   */
  silentWhenIdle?: boolean;
  /** Execution mode; omitted/legacy schedules run an agent. */
  executionMode?: ScheduleExecutionMode;
  /** Required when executionMode is 'script'. */
  scriptConfig?: ScriptExecutionConfig;
  /**
   * 前置检查脚本。undefined = 未配置,完全走原有流程(零行为变化)。
   * 详见 PreRunHookConfig。
   */
  preRunHook?: PreRunHookConfig;
  notify: ScheduleNotifyConfig;
  status: ScheduleStatus;
  createdAt: number;
  updatedAt: number;
  lastFiredAt?: number;
  /** 上一次终态完成(success/failed/aborted)的时间戳。从未跑完过 = undefined。 */
  lastFinishedAt?: number;
  nextFireAt?: number;
  expireAt?: number;
}

export interface ScheduleRun {
  id: string;
  scheduleId: string;
  sessionId?: string;
  firedAt: number;
  finishedAt?: number;
  status: RunStatus;
  errorMsg?: string;
  /** 本次 run 产生的真实 API 账单费用。 */
  costUsd?: number;
  /** 本次 run 的订阅 token 估算价值,不计入真实账单。 */
  estimatedValueUsd?: number;
  /** 新版区域真实费用;旧 costUsd 仅作历史 USD 兼容。 */
  costMoney?: ScheduleRunMoney;
  /** 新版区域订阅价值估算;不代表实际账单。 */
  estimatedValueMoney?: ScheduleRunMoney;
  /** 本次 run 关联 assistant 消息的 Token 用量总和,供无法可靠计价时展示。 */
  totalTokens?: number;
  /**
   * exact = 已确认费用(可能是实际账单,也可能是 estimate-only);direct = 费用仅来自
   * 无法挂载消息的直接账本;mixed = 快照同时包含直接账本和消息账本;zero = 已确认零费用;
   * unavailable = agent run 尚无可靠计价;legacy = 历史数据无法精确拆到单次 run。
   */
  costAttribution?: 'exact' | 'direct' | 'mixed' | 'zero' | 'unavailable' | 'legacy';
  /**
   * Agent 这一轮 turn 的最终文本(与飞书正常对话气泡显示内容同源 — 按 isFinal
   * 替换、否则追加 delta,done 时定格)。仅 prompt 类 run 在 success 时填,
   * 失败 run 留 undefined。供通知渲染 / 历史回顾用。
   */
  resultText?: string;
  /** 本轮实际执行过前置检查时的结构化结果。 */
  preRunHookResult?: PreRunHookRunResult;
  /** 用户已读时间戳(毫秒);NULL 表示未读。仅对终态 run 有意义。 */
  readAt?: number;
  /**
   * In-flight 心跳时间戳(毫秒)——跨实例的"这条 run 仍有活实例在跑"租约信号。
   * 执行实例在 run 期间周期性续期;僵尸清理(markRunningAsInterrupted)只回收
   * 心跳过期的 'running' 行,不会误标另一个活实例正在执行的 run。
   * 仅 'running' 期间有意义;老版本写入的行可能为 NULL(按 firedAt 兜底判停滞)。
   */
  heartbeatAt?: number;
}

export interface ScheduleRunMoney {
  amount: number;
  currency: 'CNY' | 'USD';
  approximate: boolean;
  kind: 'actual-cost' | 'value-estimate';
  estimateReasons?: Array<
    'fixed-fx' | 'legacy-usd' | 'subscription-value' | 'reference-price' | 'inferred-currency'
  >;
}

export interface CreateScheduleInput {
  name: string;
  prompt: string;
  /** Release-compat tombstone(见 JobType 注释)。新建恒为 'prompt',可省略。 */
  jobType?: JobType;
  /** Release-compat tombstone:老 issue-triage 的 JSON 配置;新代码不读不写。 */
  jobConfig?: string;
  kind: ScheduleKind;
  cronExpr: string;
  timezone: string;
  recurring: boolean;
  /** 默认 false。true → 永不自动触发,只能 runNow。详见 Schedule.manual。 */
  manual?: boolean;
  /** Interval 语义间隔(毫秒)。详见 Schedule.intervalMs。 */
  intervalMs?: number;
  agentKind: AgentKind;
  /** Explicit model-picker Harness. Absent on legacy schedules: bound tasks keep their live Harness. */
  modelAgentKind?: AgentKind;
  /** Agent location for an explicit model choice: absent = inherit the bound task; '' = task host. */
  modelAgentDeviceId?: string;
  model?: string;
  /**
   * 显式选定的供应商(来源)id。undefined / 空 → 回落该 agent 原生默认来源
   * (no-break,与未升级行为字节级一致);非空才按 catalog RoutingDescriptor 路由。
   * 语义与 desktop `session-provider-store` 的 null 对齐。
   */
  providerId?: string;
  /** Agent 运行位置。详见 Schedule.agentDeviceId。 */
  agentDeviceId?: string;
  effort?: string;
  /** Codex Fast 模式开关,仅 Codex 有意义。详见 Schedule.fastMode。 */
  fastMode?: boolean | 'ultrafast';
  /** Defaults to 'project' for backwards compatibility. */
  workspaceKind?: ScheduleWorkspaceKind;
  workingDir?: string;
  useWorktree: boolean;
  targetSessionId?: string;
  /** 默认 false。详见 Schedule.persistentSession。 */
  persistentSession?: boolean;
  /** 仅明确判定为检查型的创建入口显式设 true;未分类 agent 与 script 缺省 false。存量与显式选择保持不变。 */
  silentWhenIdle?: boolean;
  /** Execution mode; defaults to agent for legacy schedules. */
  executionMode?: ScheduleExecutionMode;
  /** Required when executionMode is 'script'. */
  scriptConfig?: ScriptExecutionConfig | null;
  /**
   * 前置检查脚本;undefined = 不启用。详见 PreRunHookConfig。
   * update patch 里允许显式传 null = 关闭并清空(跨 JSON 边界的调用方——MCP /
   * device-link——无法用“带 key 的 undefined”表达清列,null 是等价通道;
   * create 时 null 与 undefined 同义,引擎归一成 undefined)。
   */
  preRunHook?: PreRunHookConfig | null;
  notify: ScheduleNotifyConfig;
  expireAt?: number;
}

export type UpdateScheduleInput = Partial<CreateScheduleInput>;

export interface ListFilter {
  status?: ScheduleStatus;
}

export type SchedulerEvent =
  | { type: 'fired'; scheduleId: string; runId: string; silent?: boolean }
  | { type: 'completed'; scheduleId: string; runId: string; sessionId: string; silenced?: boolean }
  | { type: 'failed'; scheduleId: string; runId: string; error: string; sessionId?: string }
  /**
   * In-flight run 已被标记静默。该事件早于后续 agent done/completed 收口,
   * 消费方用它抑制普通 session completion attention;completed.silenced
   * 仍作为最终兜底清理信号。
   */
  | { type: 'silenced'; scheduleId: string; runId: string; sessionId: string }
  /**
   * 静默运行中的 agent 已主动声明本轮需要提醒用户。消费方用它恢复普通完成
   * attention / 音效路径。
   */
  | { type: 'notified'; scheduleId: string; runId: string; sessionId: string }
  /**
   * 本次 fire 被顺延(撞忙礼让):预插的 running run 已被撤销、不留可见记录,因此**不发**
   * 'completed' / 'failed'。但 'fired' 已先发出去,消费方(renderer useSchedules 的
   * ephemeral runningById)需要据此清掉"运行中"态,否则 chip 会卡在 running 直到下一次
   * 真 run 完成。携带 runId 让消费方精确匹配它当初因 'fired' 记下的那一条。
   */
  | { type: 'deferred'; scheduleId: string; runId: string }
  /**
   * 本次 fire 被前置检查脚本(preRunHook exit 2)拦截跳过:未启动 agent、零 token。
   * 与 'deferred' 的区别:run 记录**保留**(status='skipped',生而已读),照常按
   * recurring 语义重排下一次触发(不是短延重试)。消费方需像 'deferred' 一样清掉
   * ephemeral running 态;不发通知、不亮红点。sessionId 为跳过留痕会话(可为空串)。
   */
  | { type: 'skipped'; scheduleId: string; runId: string; sessionId: string }
  /**
   * Runner 在 fire() 内部拿到 sessionId 时主动上报(在 'completed' / 'failed' 之前)。
   * 让 UI 能在 run 还在 running 状态时就拿到 sessionId,"Open session" 按钮即时可用。
   */
  | { type: 'session-bound'; scheduleId: string; runId: string; sessionId: string }
  | { type: 'changed'; scheduleId: string }
  /** in-flight 数量或并发闸门等待队列发生变化。 */
  | { type: 'runtime-state'; snapshot: SchedulerRuntimeSnapshot }
  /** 主进程在标记某个 schedule 下的已完成 run 为已读后广播,让 sidebar 未读 badge 重新拉数。 */
  | { type: 'read'; scheduleId: string }
  /** 主进程在 "Mark all as read" 一次性清掉全部未读后广播;不带 scheduleId,所有 schedule 都受影响。 */
  | { type: 'all-read' }
  /**
   * Scheduler 实例 ready 信号(冷启 / 切账号 relogin 都会发)。
   * 由 main 端在 scheduler.on(...) 全部挂完后 broadcast 一次。
   * 唯一用途:让 renderer 的 schedulesStore 在切账号场景下后台预热 cache(冷启动场景下
   * useSchedules.ensure() 已经在跑 list,'ready' 不会重复触发——store 用 wasReset flag
   * 区分这两种场景)。
   */
  | { type: 'ready' };

export type SchedulerEventType = SchedulerEvent['type'];

// ── Schedule Template Types ──

export type TemplateSource = 'builtin' | 'user' | 'project';

export interface TemplateParameter {
  key: string;
  label: string;
  type: 'string' | 'number' | 'boolean' | 'select';
  required: boolean;
  default?: string;
  /** type='select' 时的选项。 */
  options?: string[];
  placeholder?: string;
}

export interface TemplateCategory {
  id: string;
  /** i18n key 或显示名。 */
  name: string;
  order: number;
}

/**
 * 模板能力标签,desktop 在模板卡片上渲染为能力 chip。
 * 词表收敛在这里而不是放开 string,让渲染端的图标/文案映射可以被 typecheck 兜住。
 */
export type TemplateCapability = 'worktree' | 'pr' | 'web' | 'params';

export interface ScheduleTemplate {
  id: string;
  name: string;
  description: string;
  category: string;
  icon?: string;
  source: TemplateSource;

  prompt?: string;
  cronExpr?: string;
  timezone?: string;
  recurring?: boolean;
  agentKind?: AgentKind;
  model?: string;
  /**
   * 显式选定的供应商(来源)id。undefined / 空 → 回落该 agent 原生默认来源
   * (no-break,与未升级行为字节级一致);非空才按 catalog RoutingDescriptor 路由。
   * 语义与 desktop `session-provider-store` 的 null 对齐。
   */
  providerId?: string;
  effort?: string;
  /** Codex Fast 模式开关,仅 Codex 有意义。详见 Schedule.fastMode。 */
  fastMode?: boolean | 'ultrafast';
  useWorktree?: boolean;
  persistentSession?: boolean;
  silentWhenIdle?: boolean;
  notify?: ScheduleNotifyConfig;

  parameters?: TemplateParameter[];
  /** 能力标签(隔离工作区 / PR 自动化 / Web 搜索 / 可自定义),仅影响展示。 */
  capabilities?: TemplateCapability[];

  createdAt?: number;
  updatedAt?: number;
}