@downcity/plugins 1.0.4

package/src/task/runtime/TaskRunnerTypes.ts

@@ -0,0 +1,199 @@
+/**
+ * TaskRunner 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里集中声明 task runner 在拆分后跨模块共享的内部类型。
+ * - 这些类型服务于 task 运行链路，统一归档到 `src/types/task/`。
+ */
+
+import type { JsonlSessionHistoryStore } from "@downcity/agent/internal/executor/store/history/jsonl/JsonlSessionHistoryStore.js";
+import type { SessionExecutor } from "@downcity/agent/internal/executor/types/SessionExecutor.js";
+import type {
+  ShipTaskRunExecutionStatusV1,
+  ShipTaskRunProgressPhaseV1,
+  ShipTaskRunProgressStatusV1,
+  ShipTaskRunResultStatusV1,
+  ShipTaskRunStatusV1,
+} from "@/task/types/Task.js";
+
+/**
+ * run-progress.json 的当前快照状态。
+ */
+export type RunProgressSnapshot = {
+  /**
+   * 当前进度状态。
+   */
+  status: ShipTaskRunProgressStatusV1;
+  /**
+   * 当前进度阶段。
+   */
+  phase: ShipTaskRunProgressPhaseV1;
+  /**
+   * 当前阶段对人类可读的说明文本。
+   */
+  message: string;
+  /**
+   * 当前对话轮次。
+   */
+  round?: number;
+  /**
+   * 最大允许轮次。
+   */
+  maxRounds?: number;
+  /**
+   * 运行结束时间（毫秒时间戳）。
+   */
+  endedAt?: number;
+  /**
+   * 任务总体运行状态。
+   */
+  runStatus?: ShipTaskRunStatusV1;
+  /**
+   * 执行阶段状态。
+   */
+  executionStatus?: ShipTaskRunExecutionStatusV1;
+  /**
+   * 结果校验状态。
+   */
+  resultStatus?: ShipTaskRunResultStatusV1;
+};
+
+/**
+ * 任务结果校验结果。
+ */
+export type TaskResultValidation = {
+  /**
+   * 结果校验后的状态。
+   */
+  resultStatus: ShipTaskRunResultStatusV1;
+  /**
+   * 校验失败时的错误列表。
+   */
+  errors: string[];
+};
+
+/**
+ * 模拟用户的判定结果。
+ */
+export type UserSimulatorDecision = {
+  /**
+   * 模拟用户是否认为当前结果已满足要求。
+   */
+  satisfied: boolean;
+  /**
+   * 模拟用户给出的回复文本。
+   */
+  reply: string;
+  /**
+   * 判定理由。
+   */
+  reason: string;
+  /**
+   * 可选评分，范围通常为 0-10。
+   */
+  score?: number;
+  /**
+   * 原始输出文本快照。
+   */
+  raw: string;
+};
+
+/**
+ * 单轮对话的落盘记录。
+ */
+export type DialogueRoundRecord = {
+  /**
+   * 当前任务是否启用了 review 多轮模式。
+   */
+  reviewEnabled: boolean;
+  /**
+   * 当前轮次编号。
+   */
+  round: number;
+  /**
+   * 本轮执行器收到的 query。
+   */
+  executorQuery: string;
+  /**
+   * 本轮执行器输出文本。
+   */
+  executorOutput: string;
+  /**
+   * 本轮执行器是否通过 `chat_send` 等方式实际送达文本。
+   */
+  executorDelivered: boolean;
+  /**
+   * 执行器 assistantMessage 的调试快照。
+   */
+  executorAssistantMessageSnapshot?: string;
+  /**
+   * 本轮结果校验状态。
+   */
+  validationResultStatus: ShipTaskRunResultStatusV1;
+  /**
+   * 本轮规则校验失败项。
+   */
+  ruleErrors: string[];
+  /**
+   * 模拟用户收到的 query。
+   */
+  userSimulatorQuery?: string;
+  /**
+   * 模拟用户输出文本。
+   */
+  userSimulatorOutput?: string;
+  /**
+   * 模拟用户 assistantMessage 的调试快照。
+   */
+  userSimulatorAssistantMessageSnapshot?: string;
+  /**
+   * 模拟用户最终判定结果。
+   */
+  userSimulator: UserSimulatorDecision;
+  /**
+   * 传递给下一轮执行器的反馈文本。
+   */
+  feedbackForNextRound?: string;
+};
+
+/**
+ * script 类型任务的执行结果。
+ */
+export type ScriptExecutionResult = {
+  /**
+   * script 标准输出与标准错误合并后的文本。
+   */
+  outputText: string;
+};
+
+/**
+ * task 运行专用的 session runtime 端口。
+ *
+ * 关键点（中文）
+ * - task runner 不直接依赖具体 SDK `Session` 实现。
+ * - 这里暴露的是 task 场景最小可用端口：执行器 + history Store。
+ */
+export type TaskSessionRuntimePort = {
+  /**
+   * 获取指定 sessionId 对应的 Session 执行端口。
+   */
+  getExecutor(sessionId: string): SessionExecutor;
+  /**
+   * 获取指定 sessionId 对应的 JsonlSessionHistoryStore。
+   */
+  getHistoryStore(sessionId: string): JsonlSessionHistoryStore;
+};
+
+/**
+ * 从 assistant 输出中提取的文本结果。
+ */
+export type ChatSendOutputPick = {
+  /**
+   * 最终提取到的文本内容。
+   */
+  text: string;
+  /**
+   * 该文本是否已经通过 chat_send 等方式送达。
+   */
+  delivered: boolean;
+};

package/src/task/types/Cron.ts

@@ -0,0 +1,16 @@
+/**
+ * cron 触发定义。
+ */
+export type TaskCronTriggerDefinition = {
+  id: string;
+  expression: string;
+  timezone?: string;
+  execute: () => Promise<void> | void;
+};
+
+/**
+ * cron 引擎端口。
+ */
+export type TaskCronEngine = {
+  register(definition: TaskCronTriggerDefinition): void;
+};

package/src/task/types/Task.ts

@@ -0,0 +1,157 @@
+/**
+ * Task System domain 类型。
+ *
+ * 关键点（中文）
+ * - task 定义使用 markdown + frontmatter
+ * - 每次执行产出 run 目录用于审计
+ */
+
+export type ShipTaskStatus = "enabled" | "paused" | "disabled";
+export type ShipTaskKind = "agent" | "script";
+
+export type ShipTaskFrontmatterV1 = {
+  /** 任务名称（唯一语义标识；对外统一使用 title） */
+  title: string;
+  /** 触发条件：`@manual`、cron 表达式，或 `time:<ISO8601-with-timezone>` */
+  when: string;
+  /** 任务描述（给执行器的意图说明） */
+  description: string;
+  /** 任务执行会话标识（sessionId） */
+  sessionId: string;
+  /** 任务执行类型（agent=交给 agent 执行；script=直接执行 task 正文脚本） */
+  kind?: ShipTaskKind;
+  /** 是否启用 review 多轮复核（仅 `kind=agent` 生效；默认 false，false 时单轮执行） */
+  review?: boolean;
+  /** 启停状态 */
+  status: ShipTaskStatus;
+};
+
+export type ShipTaskDefinitionV1 = {
+  /** schema 版本 */
+  v: 1;
+  /** 稳定任务键（与 title 同值，用于目录与运行上下文） */
+  taskId: string;
+  /** task.md frontmatter */
+  frontmatter: ShipTaskFrontmatterV1;
+  /** 任务正文（可直接作为执行 prompt） */
+  body: string;
+  /** 相对项目根目录的 task.md 路径 */
+  taskMdPath: string;
+};
+
+export type ShipTaskRunTriggerV1 =
+  | { type: "cron" }
+  | { type: "time" }
+  | { type: "manual"; reason?: string };
+
+export type ShipTaskRunStatusV1 = "success" | "failure" | "skipped";
+export type ShipTaskRunExecutionStatusV1 = "success" | "failure" | "skipped";
+export type ShipTaskRunResultStatusV1 = "valid" | "invalid" | "not_checked";
+export type ShipTaskRunProgressStatusV1 = "running" | "success" | "failure";
+
+/**
+ * 执行进度阶段（用于 Console 实时展示）。
+ */
+export type ShipTaskRunProgressPhaseV1 =
+  | "preparing"
+  | "script_running"
+  | "agent_executor_round"
+  | "agent_user_simulator_round"
+  | "validating"
+  | "writing_artifacts"
+  | "completed";
+
+/**
+ * 单条进度事件。
+ */
+export type ShipTaskRunProgressEventV1 = {
+  /** 事件时间（ms） */
+  at: number;
+  /** 当前阶段 */
+  phase: ShipTaskRunProgressPhaseV1;
+  /** 阶段说明 */
+  message: string;
+  /** 当前轮次（agent 场景可选） */
+  round?: number;
+  /** 最大轮次（agent 场景可选） */
+  maxRounds?: number;
+};
+
+/**
+ * 运行中进度快照（run-progress.json）。
+ */
+export type ShipTaskRunProgressV1 = {
+  /** schema 版本 */
+  v: 1;
+  /** taskId */
+  taskId: string;
+  /** run 时间戳目录名 */
+  timestamp: string;
+  /** 触发来源 */
+  trigger: ShipTaskRunTriggerV1;
+  /** 任务类型 */
+  kind: ShipTaskKind;
+  /** 当前进度状态 */
+  status: ShipTaskRunProgressStatusV1;
+  /** 当前阶段 */
+  phase: ShipTaskRunProgressPhaseV1;
+  /** 当前阶段说明 */
+  message: string;
+  /** 开始时间（ms） */
+  startedAt: number;
+  /** 最近更新时间（ms） */
+  updatedAt: number;
+  /** 结束时间（ms，完成后可选） */
+  endedAt?: number;
+  /** 最终 run 状态（完成后可选） */
+  runStatus?: ShipTaskRunStatusV1;
+  /** 最终执行状态（完成后可选） */
+  executionStatus?: ShipTaskRunExecutionStatusV1;
+  /** 最终结果校验状态（完成后可选） */
+  resultStatus?: ShipTaskRunResultStatusV1;
+  /** 当前轮次（agent 场景可选） */
+  round?: number;
+  /** 最大轮次（agent 场景可选） */
+  maxRounds?: number;
+  /** 最近进度事件（仅保留有限窗口） */
+  events: ShipTaskRunProgressEventV1[];
+};
+
+export type ShipTaskRunMetaV1 = {
+  /** schema 版本 */
+  v: 1;
+  /** 任务 ID */
+  taskId: string;
+  /** 本次 run 时间戳（目录名） */
+  timestamp: string;
+  /** 本次执行唯一 ID */
+  executionId: string;
+  /** 任务执行会话标识 */
+  sessionId: string;
+  /** 触发来源 */
+  trigger: ShipTaskRunTriggerV1;
+  /** 最终状态（综合执行阶段 + 结果校验） */
+  status: ShipTaskRunStatusV1;
+  /** 执行阶段状态（agent run 是否成功） */
+  executionStatus: ShipTaskRunExecutionStatusV1;
+  /** 结果校验状态（产物/输出是否满足要求） */
+  resultStatus: ShipTaskRunResultStatusV1;
+  /** 结果校验错误摘要（可选） */
+  resultErrors?: string[];
+  /** 实际执行的双边对话轮数 */
+  dialogueRounds: number;
+  /** 模拟用户在最终轮是否判定“满意” */
+  userSimulatorSatisfied: boolean;
+  /** 模拟用户的最终回复（可选） */
+  userSimulatorReply?: string;
+  /** 模拟用户的最终理由（可选） */
+  userSimulatorReason?: string;
+  /** 模拟用户的最终评分（0-10，可选） */
+  userSimulatorScore?: number;
+  /** 开始时间（ms） */
+  startedAt: number;
+  /** 结束时间（ms） */
+  endedAt: number;
+  /** 失败摘要（可选） */
+  error?: string;
+};

package/src/task/types/TaskCommand.ts

@@ -0,0 +1,165 @@
+/**
+ * Task 命令协议类型。
+ *
+ * 关键点（中文）
+ * - task 模块相关 DTO 就近放在 task/types
+ * - 统一给 CLI / Server / service 复用
+ */
+
+import type {
+  ShipTaskKind,
+  ShipTaskRunExecutionStatusV1,
+  ShipTaskRunResultStatusV1,
+  ShipTaskRunStatusV1,
+  ShipTaskStatus,
+} from "./Task.js";
+
+export type TaskCreateRequest = {
+  /** 任务名称。 */
+  title: string;
+  /** 触发条件。 */
+  when: string;
+  /** 任务描述。 */
+  description: string;
+  /** 任务会话标识。 */
+  sessionId: string;
+  /** 任务执行类型。 */
+  kind?: ShipTaskKind;
+  /** 是否启用 review 多轮复核。 */
+  review?: boolean;
+  /** 任务状态。 */
+  status?: ShipTaskStatus;
+  /** 任务正文。 */
+  body?: string;
+  /** 是否覆盖已有定义。 */
+  overwrite?: boolean;
+};
+
+export type TaskCreateResponse = {
+  /** 调用是否成功 */
+  success: boolean;
+  /** 任务名称（新建成功或复用已有任务时返回） */
+  title?: string;
+  /** 任务定义文件相对路径 */
+  taskMdPath?: string;
+  /** 是否复用了已有任务（true 表示未新建） */
+  reusedExisting?: boolean;
+  /** 说明信息（例如“复用已有任务”） */
+  message?: string;
+  /** 错误信息 */
+  error?: string;
+};
+
+export type TaskUpdateRequest = {
+  /** 当前任务名称。 */
+  title: string;
+  /** 新任务名称。 */
+  titleNext?: string;
+  /** 新触发条件。 */
+  when?: string;
+  /** 是否清空触发条件并回退到 `@manual`。 */
+  clearWhen?: boolean;
+  /** 新任务描述。 */
+  description?: string;
+  /** 新会话标识。 */
+  sessionId?: string;
+  /** 新任务执行类型。 */
+  kind?: ShipTaskKind;
+  /** 是否启用 review 多轮复核。 */
+  review?: boolean;
+  /** 新任务状态。 */
+  status?: ShipTaskStatus;
+  /** 新任务正文。 */
+  body?: string;
+  /** 是否清空正文。 */
+  clearBody?: boolean;
+};
+
+export type TaskUpdateResponse = {
+  success: boolean;
+  title?: string;
+  taskMdPath?: string;
+  error?: string;
+};
+
+export type TaskListItemView = {
+  /** 任务名称。 */
+  title: string;
+  /** 任务描述。 */
+  description: string;
+  /** 任务正文。 */
+  body?: string;
+  /** 触发条件。 */
+  when: string;
+  /** 任务状态。 */
+  status: string;
+  /** 当前是否正在执行。 */
+  running?: boolean;
+  /** 任务会话标识。 */
+  sessionId: string;
+  /** 任务执行类型。 */
+  kind?: ShipTaskKind;
+  /** 是否启用 review 多轮复核。 */
+  review?: boolean;
+  /** 任务定义文件相对路径。 */
+  taskMdPath: string;
+  /** 最近一次运行时间戳。 */
+  lastRunTimestamp?: string;
+};
+
+export type TaskListResponse = {
+  success: true;
+  tasks: TaskListItemView[];
+};
+
+export type TaskRunRequest = {
+  title: string;
+  reason?: string;
+};
+
+export type TaskRunResponse = {
+  success: boolean;
+  /** 是否已受理后台执行（true 表示任务已开始异步执行） */
+  accepted?: boolean;
+  /** 给调用方的简短提示（例如“任务已开始，完成后 task 会自动发送给用户，请直接继续后续流程，无需等待完成”） */
+  message?: string;
+  /** 本次执行 ID（可用于 UI 关联执行状态） */
+  executionId?: string;
+  status?: ShipTaskRunStatusV1;
+  executionStatus?: ShipTaskRunExecutionStatusV1;
+  resultStatus?: ShipTaskRunResultStatusV1;
+  resultErrors?: string[];
+  dialogueRounds?: number;
+  userSimulatorSatisfied?: boolean;
+  userSimulatorReply?: string;
+  userSimulatorReason?: string;
+  userSimulatorScore?: number;
+  title?: string;
+  timestamp?: string;
+  runDir?: string;
+  runDirRel?: string;
+  error?: string;
+};
+
+export type TaskSetStatusRequest = {
+  title: string;
+  status: ShipTaskStatus;
+};
+
+export type TaskSetStatusResponse = {
+  success: boolean;
+  title?: string;
+  status?: ShipTaskStatus;
+  error?: string;
+};
+
+export type TaskDeleteRequest = {
+  title: string;
+};
+
+export type TaskDeleteResponse = {
+  success: boolean;
+  title?: string;
+  taskDirPath?: string;
+  error?: string;
+};

package/src/task/types/TaskPluginTypes.ts

@@ -0,0 +1,55 @@
+/**
+ * Task plugin runtime 类型定义。
+ *
+ * 关键点（中文）
+ * - 这里集中声明 task plugin runtime 在类化拆分后共享的 action payload 与调度结果类型。
+ * - 跨模块复用的 task plugin runtime 类型统一收敛在 `plugins/task/types/`。
+ */
+
+import type { ShipTaskStatus } from "@/task/types/Task.js";
+
+/**
+ * `task.list` action 的输入载荷。
+ */
+export type TaskListActionPayload = {
+  /**
+   * 按任务状态过滤；省略时返回全部状态。
+   */
+  status?: ShipTaskStatus;
+};
+
+/**
+ * task cron runtime 启动或重载后的统计结果。
+ */
+export type TaskCronRegisterResult = {
+  /**
+   * 本次扫描到的任务定义数量。
+   */
+  tasksFound: number;
+  /**
+   * 本次成功注册到 cron engine 的作业数量。
+   */
+  jobsScheduled: number;
+};
+
+/**
+ * 任务定义变更后 scheduler 重载结果。
+ */
+export type TaskSchedulerReloadResult = {
+  /**
+   * scheduler 是否成功完成重载。
+   */
+  reloaded: boolean;
+  /**
+   * 成功重载时扫描到的任务数量。
+   */
+  tasksFound?: number;
+  /**
+   * 成功重载时注册成功的 cron 作业数量。
+   */
+  jobsScheduled?: number;
+  /**
+   * 重载失败时的错误文本。
+   */
+  error?: string;
+};