@downcity/agent 1.1.35 → 1.1.43

package/src/plugin/core/ActionScheduleStore.ts

@@ -0,0 +1,371 @@
+/**
+ * ActionSchedule 持久化存储。
+ *
+ * 关键点（中文）
+ * - ActionSchedule 是 plugin action 的延迟执行能力，不是一个独立 plugin。
+ * - 任务使用项目内 `jsonl` 事件流持久化，不再依赖 SQLite。
+ * - 这里采用“全量重放 + 内存归并”的最简实现，保持职责清晰且易于迁移。
+ * - 文件只记录状态事件；对外仍暴露稳定的调度任务查询与状态更新接口。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type {
+  ActionScheduleJobRecord,
+  ActionScheduleJobStatus,
+  CreateActionScheduleJobInput,
+} from "@/plugin/types/ActionSchedule.js";
+import { generateId } from "@/utils/Id.js";
+import { getDowncityScheduleDbPath } from "@/config/Paths.js";
+
+type ActionScheduleJobEvent =
+  | {
+      /**
+       * 事件版本号。
+       */
+      v: 1;
+      /**
+       * 事件类型：创建任务。
+       */
+      type: "created";
+      /**
+       * ActionSchedule 任务快照。
+       */
+      job: ActionScheduleJobRecord;
+    }
+  | {
+      /**
+       * 事件版本号。
+       */
+      v: 1;
+      /**
+       * 事件类型：状态更新。
+       */
+      type: "status";
+      /**
+       * 目标任务 ID。
+       */
+      jobId: string;
+      /**
+       * 新状态。
+       */
+      status: ActionScheduleJobStatus;
+      /**
+       * 最新更新时间。
+       */
+      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: ActionScheduleJobRecord,
+): ActionScheduleJobRecord {
+  return {
+    id: String(input.id || "").trim(),
+    pluginName: String(input.pluginName || "").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): ActionScheduleJobEvent | null {
+  try {
+    const raw = JSON.parse(line) as Partial<ActionScheduleJobEvent> | null;
+    if (!raw || typeof raw !== "object") return null;
+    if (raw.type === "created" && raw.job) {
+      return {
+        v: 1,
+        type: "created",
+        job: normalizeJobRecord(raw.job as ActionScheduleJobRecord),
+      };
+    }
+    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 ActionScheduleJobStatus,
+        updatedAt: Math.trunc(raw.updatedAt),
+        ...(typeof raw.error === "string" ? { error: raw.error } : {}),
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function compareJobs(
+  a: ActionScheduleJobRecord,
+  b: ActionScheduleJobRecord,
+): number {
+  if (a.runAtMs !== b.runAtMs) return a.runAtMs - b.runAtMs;
+  return b.createdAt - a.createdAt;
+}
+
+/**
+ * ActionSchedule Store。
+ */
+export class ActionScheduleStore {
+  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: CreateActionScheduleJobInput): ActionScheduleJobRecord {
+    const now = Date.now();
+    const job: ActionScheduleJobRecord = {
+      id: `sched_${generateId()}`,
+      pluginName: String(input.pluginName || "").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): ActionScheduleJobRecord | null {
+    const key = String(jobId || "").trim();
+    if (!key) return null;
+    return this.readJobMap().get(key) || null;
+  }
+
+  /**
+   * 列出指定状态的任务。
+   */
+  listJobsByStatus(
+    statuses: ActionScheduleJobStatus[],
+  ): ActionScheduleJobRecord[] {
+    if (statuses.length === 0) return [];
+    const allowed = new Set(statuses);
+    return this.readJobs()
+      .filter((job) => allowed.has(job.status))
+      .sort(compareJobs);
+  }
+
+  /**
+   * 列出任务。
+   */
+  listJobs(params?: {
+    status?: ActionScheduleJobStatus;
+    limit?: number;
+  }): ActionScheduleJobRecord[] {
+    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): ActionScheduleJobRecord[] {
+    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(): ActionScheduleJobRecord[] {
+    return [...this.readJobMap().values()];
+  }
+
+  /**
+   * 重放事件流，构造当前任务快照。
+   */
+  private readJobMap(): Map<string, ActionScheduleJobRecord> {
+    const jobs = new Map<string, ActionScheduleJobRecord>();
+    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: ActionScheduleJobEvent): 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<ActionScheduleJobStatus, "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/plugin/core/ActionScheduleTime.ts

@@ -0,0 +1,132 @@
+/**
+ * ActionSchedule 时间解析工具。
+ *
+ * 关键点（中文）
+ * - 统一解析 plugin action 通用 `--delay` / `--time` 参数。
+ * - 输出统一毫秒时间戳，供 command 请求解析与持久化层复用。
+ * - 该模块只处理“action 延迟执行时间”，不表达独立 schedule plugin。
+ */
+
+/**
+ * 判断是否为“缺少时区”的 ISO 时间字符串。
+ */
+function looksLikeIsoDatetimeWithoutTimezone(value: string): boolean {
+  const text = String(value || "").trim();
+  if (!text) return false;
+  const isoLike = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(text);
+  if (!isoLike) return false;
+  return !/(?:Z|[+-]\d{2}:\d{2})$/i.test(text);
+}
+
+/**
+ * 解析非负整数。
+ */
+function parseNonNegativeIntOptionOrThrow(value: string, fieldName: string): number {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+  if (!/^\d+$/.test(text)) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  const parsed = Number.parseInt(text, 10);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  return parsed;
+}
+
+/**
+ * 解析绝对执行时间。
+ *
+ * 支持格式（中文）
+ * - Unix 时间戳秒/毫秒
+ * - ISO 时间字符串（必须显式带时区）
+ */
+export function parseScheduleTimeOptionOrThrow(
+  value: string,
+  fieldName: string,
+): number {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+
+  if (/^\d+$/.test(text)) {
+    const parsed = Number.parseInt(text, 10);
+    if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+      throw new Error(`Invalid ${fieldName}: ${value}`);
+    }
+    return parsed < 1_000_000_000_000 ? parsed * 1000 : parsed;
+  }
+
+  if (looksLikeIsoDatetimeWithoutTimezone(text)) {
+    throw new Error(
+      `Invalid ${fieldName}: ${value}. ISO datetime must include timezone offset (e.g. +08:00 or Z).`,
+    );
+  }
+
+  const parsed = Date.parse(text);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+    throw new Error(
+      `Invalid ${fieldName}: ${value}. Use Unix timestamp (seconds/ms) or ISO datetime.`,
+    );
+  }
+  return parsed;
+}
+
+/**
+ * 解析 command 层调度输入并归一化为绝对毫秒时间戳。
+ *
+ * 说明（中文）
+ * - `delayMs` 与 `time` 只能二选一。
+ * - 未传时返回 `undefined`，表示立即执行。
+ */
+export function parseActionScheduleRunAtMsOrThrow(params: {
+  delay?: string | number | undefined;
+  time?: string | number | undefined;
+}): number | undefined {
+  const delayText =
+    params.delay === undefined || params.delay === null
+      ? ""
+      : String(params.delay).trim();
+  const timeText =
+    params.time === undefined || params.time === null
+      ? ""
+      : String(params.time).trim();
+
+  if (delayText && timeText) {
+    throw new Error("`--delay` and `--time` cannot be used together.");
+  }
+
+  if (delayText) {
+    return Date.now() + parseNonNegativeIntOptionOrThrow(delayText, "delay");
+  }
+
+  if (timeText) {
+    return parseScheduleTimeOptionOrThrow(timeText, "time");
+  }
+
+  return undefined;
+}
+
+/**
+ * 规范化 API/存储层传入的 runAtMs。
+ */
+export function normalizeRunAtMsOrThrow(
+  value: string | number | undefined,
+  fieldName: string,
+): number {
+  const text = String(value ?? "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+  if (!/^\d+$/.test(text)) {
+    throw new Error(`Invalid ${fieldName}: ${String(value)}`);
+  }
+  const parsed = Number.parseInt(text, 10);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+    throw new Error(`Invalid ${fieldName}: ${String(value)}`);
+  }
+  return parsed;
+}

package/src/plugin/core/Activation.ts

@@ -2,25 +2,27 @@
  * Plugin 激活判定工具。
  *
  * 关键点（中文）
- * - 统一收敛“某个 plugin 在当前 city 配置下是否启用”的规则。
- * - plugin 启用态属于 city 级生命周期配置，不再来自 agent `downcity.json`。
+ * - 统一收敛“某个 plugin 在当前项目配置下是否启用”的规则。
+ * - plugin 启用态直接来自项目 `downcity.json` 的 `plugins.<name>.enabled`。
  */
 
+import { readProjectPluginEnabled } from "@/plugin/core/ProjectConfigStore.js";
 import type { Plugin } from "@/plugin/types/Plugin.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { AgentRuntimeBase } from "@/core/AgentCoreTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentRuntimeBase } from "@/types/runtime/agent/AgentRuntime.js";
 
 /**
- * 读取当前 city 配置下的 plugin 启用态。
+ * 读取当前项目配置下的 plugin 启用态。
  */
 export function isPluginEnabled(params: {
   plugin: Plugin;
-  context?: Pick<AgentContext, "platform">;
-  runtime?: Pick<AgentRuntimeBase, "platform">;
+  context?: Pick<AgentContext, "config">;
+  runtime?: Pick<AgentRuntimeBase, "config">;
 }): boolean {
   const pluginName = String(params.plugin.name || "").trim();
   if (!pluginName) return false;
-  if (pluginName === "auth") return true;
-  const platform = params.context?.platform || params.runtime?.platform;
-  return platform ? platform.isPluginEnabled(pluginName) : true;
+  return readProjectPluginEnabled({
+    pluginName,
+    config: params.context?.config || params.runtime?.config,
+  });
 }

package/src/plugin/core/BasePlugin.ts

@@ -7,8 +7,8 @@
  * - 旧生命周期模型暂时通过 `lifecycle` 兼容，后续可逐步收敛到 `start/stop/command`。
  */
 
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
+import type { AgentRuntime } from "@/types/runtime/agent/AgentRuntime.js";
 import type {
   Plugin,
   PluginActions,
@@ -23,7 +23,7 @@ import type {
   PluginStateRecord,
   PluginUsageDefinition,
 } from "@/plugin/types/Plugin.js";
-import type { StructuredConfig } from "@/core/AgentContextTypes.js";
+import type { StructuredConfig } from "@/types/runtime/agent/AgentContext.js";
 
 /**
  * BasePlugin 抽象基类。

package/src/plugin/core/HookRegistry.ts

@@ -13,7 +13,7 @@ import type {
   PluginPipelineHook,
   PluginResolveHook,
 } from "@/plugin/types/Plugin.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 
 type ContextResolver = () => AgentContext;
 type PluginEnabledChecker = (pluginName: string, context: AgentContext) => boolean;

package/src/plugin/core/PluginActionRunner.ts

@@ -2,7 +2,7 @@
  * PluginActionRunner：主动型 plugin action/command 执行模块。
  */
 
-import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { AgentContext } from "@/types/runtime/agent/AgentContext.js";
 import type { BasePlugin } from "@/plugin/core/BasePlugin.js";
 import type {
   PluginAction,
@@ -11,10 +11,10 @@ import type {
   PluginStateControlAction,
   PluginStateSnapshot,
 } from "@/plugin/types/Plugin.js";
-import type { PluginCommandScheduleInput } from "@/plugin/types/PluginSchedule.js";
+import type { PluginActionScheduleInput } from "@/plugin/types/ActionSchedule.js";
 import type { JsonValue } from "@/types/common/Json.js";
-import { PluginScheduleStore } from "@/plugin/core/schedule/Store.js";
-import { normalizeRunAtMsOrThrow } from "@/plugin/core/schedule/Time.js";
+import { ActionScheduleStore } from "@/plugin/core/ActionScheduleStore.js";
+import { normalizeRunAtMsOrThrow } from "@/plugin/core/ActionScheduleTime.js";
 import {
   controlPluginState,
   ensurePluginStateRecord,
@@ -90,17 +90,17 @@ async function schedulePluginAction(params: {
   plugin: BasePlugin;
   command: string;
   payload?: JsonValue;
-  schedule: JsonValue | PluginCommandScheduleInput;
+  schedule: JsonValue | PluginActionScheduleInput;
   recordSnapshot: PluginStateSnapshot;
   context: AgentContext;
 }): Promise<PluginCommandResult & { plugin?: PluginStateSnapshot }> {
   try {
-    const scheduleInput = params.schedule as Partial<PluginCommandScheduleInput>;
+    const scheduleInput = params.schedule as Partial<PluginActionScheduleInput>;
     const runAtMs = normalizeRunAtMsOrThrow(
       scheduleInput.runAtMs,
       "schedule.runAtMs",
     );
-    const store = new PluginScheduleStore(params.context.rootPath);
+    const store = new ActionScheduleStore(params.context.rootPath);
     try {
       const job = store.createJob({
         pluginName: params.plugin.name,
@@ -137,7 +137,7 @@ export async function runPluginCommand(params: {
   pluginName: string;
   command: string;
   payload?: JsonValue;
-  schedule?: JsonValue | PluginCommandScheduleInput;
+  schedule?: JsonValue | PluginActionScheduleInput;
   context: AgentContext;
 }): Promise<PluginCommandResult & { plugin?: PluginStateSnapshot }> {
   const plugin = resolvePluginByName(params.pluginName, {