@downcity/agent 1.1.25 → 1.1.32

package/src/service/core/schedule/Store.ts

@@ -1,358 +0,0 @@
-/**
- * Service Schedule 持久化存储。
- *
- * 关键点（中文）
- * - 调度任务改为使用项目内 `jsonl` 事件流持久化，不再依赖 SQLite。
- * - 这里采用“全量重放 + 内存归并”的最简实现，保持职责清晰且易于迁移。
- * - 文件只记录状态事件；对外仍暴露稳定的调度任务查询与状态更新接口。
- */
-
-import fs from "fs-extra";
-import path from "node:path";
-import type {
-  CreateScheduledJobInput,
-  ScheduledJobRecord,
-  ScheduledJobStatus,
-} from "@/service/types/ServiceSchedule.js";
-import { generateId } from "@/utils/Id.js";
-import { getDowncityScheduleDbPath } from "@/config/Paths.js";
-
-type ScheduledJobEvent =
-  | {
-      /**
-       * 事件版本号。
-       */
-      v: 1;
-      /**
-       * 事件类型：创建任务。
-       */
-      type: "created";
-      /**
-       * 调度任务快照。
-       */
-      job: ScheduledJobRecord;
-    }
-  | {
-      /**
-       * 事件版本号。
-       */
-      v: 1;
-      /**
-       * 事件类型：状态更新。
-       */
-      type: "status";
-      /**
-       * 目标任务 ID。
-       */
-      jobId: string;
-      /**
-       * 新状态。
-       */
-      status: ScheduledJobStatus;
-      /**
-       * 最新更新时间。
-       */
-      updatedAt: number;
-      /**
-       * 可选错误信息。
-       */
-      error?: string;
-    };
-
-function readJsonlLines(filePath: string): string[] {
-  if (!fs.existsSync(filePath)) return [];
-  const raw = fs.readFileSync(filePath, "utf-8");
-  return raw
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean);
-}
-
-function normalizeJobRecord(input: ScheduledJobRecord): ScheduledJobRecord {
-  return {
-    id: String(input.id || "").trim(),
-    serviceName: String(input.serviceName || "").trim(),
-    actionName: String(input.actionName || "").trim(),
-    payload: input.payload ?? null,
-    runAtMs: Math.trunc(input.runAtMs),
-    status: input.status,
-    ...(typeof input.error === "string" && input.error ? { error: input.error } : {}),
-    createdAt: Math.trunc(input.createdAt),
-    updatedAt: Math.trunc(input.updatedAt),
-  };
-}
-
-function parseEvent(line: string): ScheduledJobEvent | null {
-  try {
-    const raw = JSON.parse(line) as Partial<ScheduledJobEvent> | null;
-    if (!raw || typeof raw !== "object") return null;
-    if (raw.type === "created" && raw.job) {
-      return {
-        v: 1,
-        type: "created",
-        job: normalizeJobRecord(raw.job as ScheduledJobRecord),
-      };
-    }
-    if (
-      raw.type === "status" &&
-      typeof raw.jobId === "string" &&
-      typeof raw.status === "string" &&
-      typeof raw.updatedAt === "number"
-    ) {
-      return {
-        v: 1,
-        type: "status",
-        jobId: raw.jobId,
-        status: raw.status as ScheduledJobStatus,
-        updatedAt: Math.trunc(raw.updatedAt),
-        ...(typeof raw.error === "string" ? { error: raw.error } : {}),
-      };
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-function compareJobs(a: ScheduledJobRecord, b: ScheduledJobRecord): number {
-  if (a.runAtMs !== b.runAtMs) return a.runAtMs - b.runAtMs;
-  return b.createdAt - a.createdAt;
-}
-
-/**
- * Service Schedule Store。
- */
-export class ServiceScheduleStore {
-  private readonly filePath: string;
-
-  constructor(projectRoot: string) {
-    this.filePath = getDowncityScheduleDbPath(projectRoot);
-    fs.ensureDirSync(path.dirname(this.filePath));
-    if (!fs.existsSync(this.filePath)) {
-      fs.writeFileSync(this.filePath, "", "utf-8");
-    }
-  }
-
-  /**
-   * 关闭存储。
-   *
-   * 说明（中文）
-   * - jsonl 版本无需保持长连接，因此 close 为 no-op。
-   */
-  close(): void {}
-
-  /**
-   * 创建调度任务。
-   */
-  createJob(input: CreateScheduledJobInput): ScheduledJobRecord {
-    const now = Date.now();
-    const job: ScheduledJobRecord = {
-      id: `sched_${generateId()}`,
-      serviceName: String(input.serviceName || "").trim(),
-      actionName: String(input.actionName || "").trim(),
-      payload: input.payload ?? null,
-      runAtMs: Math.trunc(input.runAtMs),
-      status: "pending",
-      createdAt: now,
-      updatedAt: now,
-    };
-    this.appendEvent({
-      v: 1,
-      type: "created",
-      job,
-    });
-    return job;
-  }
-
-  /**
-   * 获取单个任务。
-   */
-  getJobById(jobId: string): ScheduledJobRecord | null {
-    const key = String(jobId || "").trim();
-    if (!key) return null;
-    return this.readJobMap().get(key) || null;
-  }
-
-  /**
-   * 列出指定状态的任务。
-   */
-  listJobsByStatus(statuses: ScheduledJobStatus[]): ScheduledJobRecord[] {
-    if (statuses.length === 0) return [];
-    const allowed = new Set(statuses);
-    return this.readJobs()
-      .filter((job) => allowed.has(job.status))
-      .sort(compareJobs);
-  }
-
-  /**
-   * 列出任务。
-   */
-  listJobs(params?: {
-    status?: ScheduledJobStatus;
-    limit?: number;
-  }): ScheduledJobRecord[] {
-    const limit =
-      typeof params?.limit === "number" && Number.isFinite(params.limit)
-        ? Math.max(1, Math.trunc(params.limit))
-        : 100;
-    const jobs = this.readJobs()
-      .filter((job) => !params?.status || job.status === params.status)
-      .sort(compareJobs);
-    return jobs.slice(0, limit);
-  }
-
-  /**
-   * 列出已到点且待执行的任务。
-   */
-  listDuePendingJobs(nowMs: number): ScheduledJobRecord[] {
-    return this.readJobs()
-      .filter((job) => job.status === "pending" && job.runAtMs <= Math.trunc(nowMs))
-      .sort(compareJobs);
-  }
-
-  /**
-   * 启动恢复时，把历史 `running` 回退到 `pending`。
-   */
-  resetRunningJobsToPending(): number {
-    const runningJobs = this.readJobs().filter((job) => job.status === "running");
-    const now = Date.now();
-    for (const job of runningJobs) {
-      this.appendEvent({
-        v: 1,
-        type: "status",
-        jobId: job.id,
-        status: "pending",
-        updatedAt: now,
-      });
-    }
-    return runningJobs.length;
-  }
-
-  /**
-   * 将任务标记为执行中。
-   */
-  markJobRunning(jobId: string): boolean {
-    return this.transitionPendingJob(jobId, "running");
-  }
-
-  /**
-   * 将任务标记为成功。
-   */
-  markJobSucceeded(jobId: string): boolean {
-    return this.updateTerminalStatus({
-      jobId,
-      status: "succeeded",
-    });
-  }
-
-  /**
-   * 将任务标记为失败。
-   */
-  markJobFailed(jobId: string, error: string): boolean {
-    return this.updateTerminalStatus({
-      jobId,
-      status: "failed",
-      error,
-    });
-  }
-
-  /**
-   * 将任务标记为取消。
-   */
-  markJobCancelled(jobId: string): boolean {
-    return this.updateTerminalStatus({
-      jobId,
-      status: "cancelled",
-    });
-  }
-
-  /**
-   * 取消待执行任务。
-   */
-  cancelPendingJob(jobId: string): boolean {
-    return this.transitionPendingJob(jobId, "cancelled");
-  }
-
-  /**
-   * 仅读取当前任务快照。
-   */
-  private readJobs(): ScheduledJobRecord[] {
-    return [...this.readJobMap().values()];
-  }
-
-  /**
-   * 重放事件流，构造当前任务快照。
-   */
-  private readJobMap(): Map<string, ScheduledJobRecord> {
-    const jobs = new Map<string, ScheduledJobRecord>();
-    for (const line of readJsonlLines(this.filePath)) {
-      const event = parseEvent(line);
-      if (!event) continue;
-      if (event.type === "created") {
-        jobs.set(event.job.id, normalizeJobRecord(event.job));
-        continue;
-      }
-      const current = jobs.get(event.jobId);
-      if (!current) continue;
-      jobs.set(event.jobId, {
-        ...current,
-        status: event.status,
-        updatedAt: event.updatedAt,
-        ...(event.error ? { error: event.error } : {}),
-        ...(event.status === "succeeded" || event.status === "cancelled"
-          ? { error: undefined }
-          : {}),
-      });
-    }
-    return jobs;
-  }
-
-  /**
-   * 追加单条事件。
-   */
-  private appendEvent(event: ScheduledJobEvent): void {
-    fs.appendFileSync(this.filePath, `${JSON.stringify(event)}\n`, "utf-8");
-  }
-
-  /**
-   * 执行 pending -> target 的状态迁移。
-   */
-  private transitionPendingJob(
-    jobId: string,
-    status: "running" | "cancelled",
-  ): boolean {
-    const current = this.getJobById(jobId);
-    if (!current || current.status !== "pending") {
-      return false;
-    }
-    this.appendEvent({
-      v: 1,
-      type: "status",
-      jobId: current.id,
-      status,
-      updatedAt: Date.now(),
-    });
-    return true;
-  }
-
-  /**
-   * 统一写入终态。
-   */
-  private updateTerminalStatus(params: {
-    jobId: string;
-    status: Exclude<ScheduledJobStatus, "pending" | "running">;
-    error?: string;
-  }): boolean {
-    const current = this.getJobById(params.jobId);
-    if (!current) return false;
-    this.appendEvent({
-      v: 1,
-      type: "status",
-      jobId: current.id,
-      status: params.status,
-      updatedAt: Date.now(),
-      ...(params.error ? { error: String(params.error) } : {}),
-    });
-    return true;
-  }
-}

package/src/service/types/Service.ts

@@ -1,200 +0,0 @@
-/**
- * Service 类型定义。
- *
- * 关键点（中文）
- * - 这里集中声明 service 体系的共享契约。
- * - 这些类型会被 service 管理层、内建 service 与测试多处复用，因此收敛在 `service/types/`。
- * - service 共享契约统一放在 `service/types/`，避免管理层门面文件承载类型来源职责。
- */
-
-import type { Command } from "commander";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { JsonValue } from "@/types/common/Json.js";
-
-/**
- * 服务运行状态。
- *
- * 说明（中文）
- * - `starting` / `stopping` 仅用于生命周期控制中的过渡态。
- * - `error` 表示最近一次控制或命令执行失败后留下的状态标记。
- */
-export type ServiceState =
-  | "running"
-  | "stopped"
-  | "starting"
-  | "stopping"
-  | "error";
-
-/**
- * 服务命令执行结果。
- */
-export type ServiceCommandResult = {
-  /**
-   * 本次命令是否执行成功。
-   */
-  success: boolean;
-  /**
-   * 对人类可读的补充说明文本。
-   */
-  message?: string;
-  /**
-   * 命令附带返回的数据载荷。
-   */
-  data?: JsonValue;
-};
-
-/**
- * 单个 action 执行结果。
- */
-export type ServiceActionResult<R extends JsonValue = JsonValue> = {
-  /**
-   * action 是否执行成功。
-   */
-  success: boolean;
-  /**
-   * action 成功时返回的数据载荷。
-   */
-  data?: R;
-  /**
-   * action 失败时返回的错误文本。
-   */
-  error?: string;
-};
-
-/**
- * Action CLI 输入。
- */
-export type ServiceActionCommandInput = {
-  /**
-   * 位置参数列表。
-   */
-  args: string[];
-  /**
-   * 解析后的 option 键值对。
-   */
-  opts: Record<string, JsonValue>;
-};
-
-/**
- * Action CLI 定义。
- */
-export type ServiceActionCommand<P extends JsonValue = JsonValue> = {
-  /**
-   * CLI 子命令描述。
-   */
-  description: string;
-  /**
-   * 对 commander command 的额外配置。
-   */
-  configure?: (command: Command) => void;
-  /**
-   * 把 CLI 输入映射为结构化 payload。
-   */
-  mapInput: (input: ServiceActionCommandInput) => P | Promise<P>;
-};
-
-/**
- * 单个 service action 定义。
- */
-export type ServiceAction<
-  P extends JsonValue = JsonValue,
-  R extends JsonValue = JsonValue,
-> = {
-  /**
-   * CLI 定义；省略则该 action 不暴露为 CLI 子命令。
-   */
-  command?: ServiceActionCommand<P>;
-  /**
-   * action 的实际执行函数。
-   */
-  execute: (params: {
-    /**
-     * 当前统一执行上下文。
-     */
-    context: AgentContext;
-    /**
-     * 当前 action 的结构化输入。
-     */
-    payload: P;
-    /**
-     * 当前 service 名称。
-     */
-    serviceName: string;
-    /**
-     * 当前 action 名称。
-     */
-    actionName: string;
-  }) => Promise<ServiceActionResult<R>> | ServiceActionResult<R>;
-};
-
-/**
- * Service action 映射。
- *
- * 关键点（中文）
- * - key 就是 action 名称。
- * - 使用对象结构，便于直接按名称索引和动态装配。
- */
-export type ServiceActions = {
-  [actionName: string]: ServiceAction<JsonValue, JsonValue>;
-};
-
-/**
- * Service 生命周期扩展能力。
- */
-export interface ServiceLifecycle {
-  /**
-   * service 启动钩子。
-   */
-  start?(context: AgentContext): Promise<void> | void;
-  /**
-   * service 停止钩子。
-   */
-  stop?(context: AgentContext): Promise<void> | void;
-  /**
-   * 非 action 命令分发钩子。
-   */
-  command?(params: {
-    /**
-     * 当前统一执行上下文。
-     */
-    context: AgentContext;
-    /**
-     * 当前命令名称。
-     */
-    command: string;
-    /**
-     * 可选 payload。
-     */
-    payload?: JsonValue;
-  }): Promise<ServiceCommandResult> | ServiceCommandResult;
-}
-
-/**
- * Service：服务统一契约。
- *
- * 关键点（中文）
- * - 一个 service 至少要提供稳定名称与 action 集合。
- * - 生命周期钩子与 system 构建器都是可选能力，不强制所有 service 实现。
- */
-export interface Service {
-  /**
-   * service 名称。
-   */
-  name: string;
-  /**
-   * action 集合。
-   *
-   * 关键点（中文）
-   * - 一个 service 对应多个 action。
-   * - main 会基于这里自动注册 CLI 与 HTTP 路由。
-   */
-  actions: ServiceActions;
-  /**
-   * service 级 system 文本构建器。
-   */
-  system?: (context: AgentContext) => string | Promise<string>;
-  /**
-   * service 生命周期钩子集合。
-   */
-  lifecycle?: ServiceLifecycle;
-}

package/src/service/types/ServiceSchedule.ts

@@ -1,134 +0,0 @@
-/**
- * Service Schedule 类型定义。
- *
- * 关键点（中文）
- * - 统一描述“延迟/定时执行 service action”的持久化记录结构。
- * - 该模块只承载调度层状态，不耦合具体 service 的业务语义。
- */
-
-import type { JsonValue } from "@/types/common/Json.js";
-
-/**
- * 调度任务状态。
- *
- * 说明（中文）
- * - `pending`：等待到点执行。
- * - `running`：已被调度器领取，当前正在执行。
- * - `succeeded`：执行成功。
- * - `failed`：执行失败。
- * - `cancelled`：已取消，不再执行。
- */
-export type ScheduledJobStatus =
-  | "pending"
-  | "running"
-  | "succeeded"
-  | "failed"
-  | "cancelled";
-
-/**
- * 调度任务完整记录。
- */
-export interface ScheduledJobRecord {
-  /**
-   * 调度任务唯一 ID。
-   *
-   * 说明（中文）
-   * - 由 runtime 创建并稳定持久化。
-   * - 用于取消、查询、状态更新与恢复。
-   */
-  id: string;
-
-  /**
-   * 目标 service 名称。
-   *
-   * 说明（中文）
-   * - 对应 `city <service> <action>` 中的 `<service>`。
-   */
-  serviceName: string;
-
-  /**
-   * 目标 action 名称。
-   *
-   * 说明（中文）
-   * - 对应 `city <service> <action>` 中的 `<action>`。
-   */
-  actionName: string;
-
-  /**
-   * 原始 action payload。
-   *
-   * 说明（中文）
-   * - 直接保存 service action 的 JSON payload。
-   * - 调度器到点后会原样回放给 `runServiceCommand(...)`。
-   */
-  payload: JsonValue;
-
-  /**
-   * 计划执行时间（毫秒时间戳）。
-   *
-   * 说明（中文）
-   * - 统一归一化为 Unix epoch ms。
-   */
-  runAtMs: number;
-
-  /**
-   * 当前调度状态。
-   */
-  status: ScheduledJobStatus;
-
-  /**
-   * 最近一次错误文本。
-   *
-   * 说明（中文）
-   * - 仅在失败场景下写入。
-   */
-  error?: string;
-
-  /**
-   * 创建时间（毫秒时间戳）。
-   */
-  createdAt: number;
-
-  /**
-   * 最近更新时间（毫秒时间戳）。
-   */
-  updatedAt: number;
-}
-
-/**
- * 创建调度任务所需输入。
- */
-export interface CreateScheduledJobInput {
-  /**
-   * 目标 service 名称。
-   */
-  serviceName: string;
-
-  /**
-   * 目标 action 名称。
-   */
-  actionName: string;
-
-  /**
-   * 目标 action payload。
-   */
-  payload: JsonValue;
-
-  /**
-   * 计划执行时间（毫秒时间戳）。
-   */
-  runAtMs: number;
-}
-
-/**
- * 统一 service command 调度输入。
- */
-export interface ServiceCommandScheduleInput {
-  /**
-   * 计划执行时间（毫秒时间戳）。
-   *
-   * 说明（中文）
-   * - command 层统一只接收归一化后的绝对时间。
-   */
-  runAtMs: number;
-}