@downcity/agent 1.1.287 → 1.1.310

package/src/plugin/core/ActionScheduleStore.ts

@@ -8,15 +8,14 @@
  * - 文件只记录状态事件；对外仍暴露稳定的调度任务查询与状态更新接口。
  */
 
-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";
+import { generate_id } from "@/utils/Id.js";
+import { get_downcity_schedule_db_path } from "@/workspace/WorkspacePaths.js";
+import type { FileSystem } from "@/types/workspace/FileSystem.js";
 
 type ActionScheduleJobEvent =
   | {
@@ -45,7 +44,7 @@ type ActionScheduleJobEvent =
       /**
        * 目标任务 ID。
        */
-      jobId: string;
+      job_id: string;
       /**
        * 新状态。
        */
@@ -53,16 +52,19 @@ type ActionScheduleJobEvent =
       /**
        * 最新更新时间。
        */
-      updatedAt: number;
+      updated_at: number;
       /**
        * 可选错误信息。
        */
       error?: string;
     };
 
-function readJsonlLines(filePath: string): string[] {
-  if (!fs.existsSync(filePath)) return [];
-  const raw = fs.readFileSync(filePath, "utf-8");
+async function read_jsonl_lines(
+  files: FileSystem,
+  file_path: string,
+): Promise<string[]> {
+  if (!(await files.path_exists(file_path))) return [];
+  const raw = (await files.read_file(file_path)).toString("utf8");
   return raw
     .split(/\r?\n/)
     .map((line) => line.trim())
@@ -74,16 +76,16 @@ function normalizeJobRecord(
 ): ActionScheduleJobRecord {
   return {
     id: String(input.id || "").trim(),
-    pluginName: String(input.pluginName || "").trim(),
-    actionName: String(input.actionName || "").trim(),
+    plugin_name: String(input.plugin_name || "").trim(),
+    action_name: String(input.action_name || "").trim(),
     payload: input.payload ?? null,
-    runAtMs: Math.trunc(input.runAtMs),
+    run_at_ms: Math.trunc(input.run_at_ms),
     status: input.status,
     ...(typeof input.error === "string" && input.error
       ? { error: input.error }
       : {}),
-    createdAt: Math.trunc(input.createdAt),
-    updatedAt: Math.trunc(input.updatedAt),
+    created_at: Math.trunc(input.created_at),
+    updated_at: Math.trunc(input.updated_at),
   };
 }
 
@@ -100,16 +102,16 @@ function parseEvent(line: string): ActionScheduleJobEvent | null {
     }
     if (
       raw.type === "status" &&
-      typeof raw.jobId === "string" &&
+      typeof raw.job_id === "string" &&
       typeof raw.status === "string" &&
-      typeof raw.updatedAt === "number"
+      typeof raw.updated_at === "number"
     ) {
       return {
         v: 1,
         type: "status",
-        jobId: raw.jobId,
+        job_id: raw.job_id,
         status: raw.status as ActionScheduleJobStatus,
-        updatedAt: Math.trunc(raw.updatedAt),
+        updated_at: Math.trunc(raw.updated_at),
         ...(typeof raw.error === "string" ? { error: raw.error } : {}),
       };
     }
@@ -123,22 +125,22 @@ function compareJobs(
   a: ActionScheduleJobRecord,
   b: ActionScheduleJobRecord,
 ): number {
-  if (a.runAtMs !== b.runAtMs) return a.runAtMs - b.runAtMs;
-  return b.createdAt - a.createdAt;
+  if (a.run_at_ms !== b.run_at_ms) return a.run_at_ms - b.run_at_ms;
+  return b.created_at - a.created_at;
 }
 
 /**
  * ActionSchedule Store。
  */
 export class ActionScheduleStore {
-  private readonly filePath: string;
+  private readonly file_path: string;
+  private readonly lock_path: string;
+  private readonly files: FileSystem;
 
-  constructor(projectRoot: string) {
-    this.filePath = getDowncityScheduleDbPath(projectRoot);
-    fs.ensureDirSync(path.dirname(this.filePath));
-    if (!fs.existsSync(this.filePath)) {
-      fs.writeFileSync(this.filePath, "", "utf-8");
-    }
+  constructor(files: FileSystem) {
+    this.files = files;
+    this.file_path = get_downcity_schedule_db_path(files.root_path);
+    this.lock_path = `${this.file_path}.lock`;
   }
 
   /**
@@ -152,22 +154,24 @@ export class ActionScheduleStore {
   /**
    * 创建调度任务。
    */
-  createJob(input: CreateActionScheduleJobInput): ActionScheduleJobRecord {
+  async create_job(input: CreateActionScheduleJobInput): Promise<ActionScheduleJobRecord> {
     const now = Date.now();
     const job: ActionScheduleJobRecord = {
-      id: `sched_${generateId()}`,
-      pluginName: String(input.pluginName || "").trim(),
-      actionName: String(input.actionName || "").trim(),
+      id: `sched_${generate_id()}`,
+      plugin_name: String(input.plugin_name || "").trim(),
+      action_name: String(input.action_name || "").trim(),
       payload: input.payload ?? null,
-      runAtMs: Math.trunc(input.runAtMs),
+      run_at_ms: Math.trunc(input.run_at_ms),
       status: "pending",
-      createdAt: now,
-      updatedAt: now,
+      created_at: now,
+      updated_at: now,
     };
-    this.appendEvent({
-      v: 1,
-      type: "created",
-      job,
+    await this.with_store_lock(async () => {
+      await this.append_event_unlocked({
+        v: 1,
+        type: "created",
+        job,
+      });
     });
     return job;
   }
@@ -175,85 +179,96 @@ export class ActionScheduleStore {
   /**
    * 获取单个任务。
    */
-  getJobById(jobId: string): ActionScheduleJobRecord | null {
-    const key = String(jobId || "").trim();
+  async get_job_by_id(job_id: string): Promise<ActionScheduleJobRecord | null> {
+    const key = String(job_id || "").trim();
     if (!key) return null;
-    return this.readJobMap().get(key) || null;
+    return await this.with_store_lock(async () =>
+      (await this.read_job_map_unlocked()).get(key) || null
+    );
   }
 
   /**
    * 列出指定状态的任务。
    */
-  listJobsByStatus(
+  async list_jobs_by_status(
     statuses: ActionScheduleJobStatus[],
-  ): ActionScheduleJobRecord[] {
+  ): Promise<ActionScheduleJobRecord[]> {
     if (statuses.length === 0) return [];
     const allowed = new Set(statuses);
-    return this.readJobs()
-      .filter((job) => allowed.has(job.status))
-      .sort(compareJobs);
+    return await this.with_store_lock(async () =>
+      (await this.read_jobs_unlocked())
+        .filter((job) => allowed.has(job.status))
+        .sort(compareJobs)
+    );
   }
 
   /**
    * 列出任务。
    */
-  listJobs(params?: {
+  async list_jobs(params?: {
     status?: ActionScheduleJobStatus;
     limit?: number;
-  }): ActionScheduleJobRecord[] {
+  }): Promise<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);
+    return await this.with_store_lock(async () => {
+      const jobs = (await this.read_jobs_unlocked())
+        .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);
+  async list_due_pending_jobs(nowMs: number): Promise<ActionScheduleJobRecord[]> {
+    return await this.with_store_lock(async () =>
+      (await this.read_jobs_unlocked())
+        .filter(
+          (job) =>
+            job.status === "pending" && job.run_at_ms <= 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;
+  async reset_running_jobs_to_pending(): Promise<number> {
+    return await this.with_store_lock(async () => {
+      const running_jobs = (await this.read_jobs_unlocked())
+        .filter((job) => job.status === "running");
+      const now = Date.now();
+      for (const job of running_jobs) {
+        await this.append_event_unlocked({
+          v: 1,
+          type: "status",
+          job_id: job.id,
+          status: "pending",
+          updated_at: now,
+        });
+      }
+      return running_jobs.length;
+    });
   }
 
   /**
    * 将任务标记为执行中。
    */
-  markJobRunning(jobId: string): boolean {
-    return this.transitionPendingJob(jobId, "running");
+  async mark_job_running(job_id: string): Promise<boolean> {
+    return await this.transition_pending_job(job_id, "running");
   }
 
   /**
    * 将任务标记为成功。
    */
-  markJobSucceeded(jobId: string): boolean {
-    return this.updateTerminalStatus({
-      jobId,
+  async mark_job_succeeded(job_id: string): Promise<boolean> {
+    return await this.update_terminal_status({
+      job_id,
       status: "succeeded",
     });
   }
@@ -261,56 +276,46 @@ export class ActionScheduleStore {
   /**
    * 将任务标记为失败。
    */
-  markJobFailed(jobId: string, error: string): boolean {
-    return this.updateTerminalStatus({
-      jobId,
+  async mark_job_failed(job_id: string, error: string): Promise<boolean> {
+    return await this.update_terminal_status({
+      job_id,
       status: "failed",
       error,
     });
   }
 
-  /**
-   * 将任务标记为取消。
-   */
-  markJobCancelled(jobId: string): boolean {
-    return this.updateTerminalStatus({
-      jobId,
-      status: "cancelled",
-    });
-  }
-
   /**
    * 取消待执行任务。
    */
-  cancelPendingJob(jobId: string): boolean {
-    return this.transitionPendingJob(jobId, "cancelled");
+  async cancel_pending_job(job_id: string): Promise<boolean> {
+    return await this.transition_pending_job(job_id, "cancelled");
   }
 
   /**
    * 仅读取当前任务快照。
    */
-  private readJobs(): ActionScheduleJobRecord[] {
-    return [...this.readJobMap().values()];
+  private async read_jobs_unlocked(): Promise<ActionScheduleJobRecord[]> {
+    return [...(await this.read_job_map_unlocked()).values()];
   }
 
   /**
    * 重放事件流，构造当前任务快照。
    */
-  private readJobMap(): Map<string, ActionScheduleJobRecord> {
+  private async read_job_map_unlocked(): Promise<Map<string, ActionScheduleJobRecord>> {
     const jobs = new Map<string, ActionScheduleJobRecord>();
-    for (const line of readJsonlLines(this.filePath)) {
+    for (const line of await read_jsonl_lines(this.files, this.file_path)) {
       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);
+      const current = jobs.get(event.job_id);
       if (!current) continue;
-      jobs.set(event.jobId, {
+      jobs.set(event.job_id, {
         ...current,
         status: event.status,
-        updatedAt: event.updatedAt,
+        updated_at: event.updated_at,
         ...(event.error ? { error: event.error } : {}),
         ...(event.status === "succeeded" || event.status === "cancelled"
           ? { error: undefined }
@@ -323,49 +328,56 @@ export class ActionScheduleStore {
   /**
    * 追加单条事件。
    */
-  private appendEvent(event: ActionScheduleJobEvent): void {
-    fs.appendFileSync(this.filePath, `${JSON.stringify(event)}\n`, "utf-8");
+  private async append_event_unlocked(event: ActionScheduleJobEvent): Promise<void> {
+    await this.files.append_file(this.file_path, `${JSON.stringify(event)}\n`);
+  }
+
+  /** 使用 Workspace 跨进程锁串行执行一次调度存储事务。 */
+  private async with_store_lock<T>(action: () => Promise<T>): Promise<T> {
+    return await this.files.with_file_lock(this.lock_path, action);
   }
 
   /**
    * 执行 pending -> target 的状态迁移。
    */
-  private transitionPendingJob(
-    jobId: string,
+  private async transition_pending_job(
+    job_id: 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(),
+  ): Promise<boolean> {
+    return await this.with_store_lock(async () => {
+      const current = (await this.read_job_map_unlocked()).get(job_id);
+      if (!current || current.status !== "pending") return false;
+      await this.append_event_unlocked({
+        v: 1,
+        type: "status",
+        job_id: current.id,
+        status,
+        updated_at: Date.now(),
+      });
+      return true;
     });
-    return true;
   }
 
   /**
    * 统一写入终态。
    */
-  private updateTerminalStatus(params: {
-    jobId: string;
+  private async update_terminal_status(params: {
+    job_id: 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) } : {}),
+  }): Promise<boolean> {
+    return await this.with_store_lock(async () => {
+      const current = (await this.read_job_map_unlocked()).get(params.job_id);
+      if (!current || current.status !== "running") return false;
+      await this.append_event_unlocked({
+        v: 1,
+        type: "status",
+        job_id: current.id,
+        status: params.status,
+        updated_at: Date.now(),
+        ...(params.error ? { error: String(params.error) } : {}),
+      });
+      return true;
     });
-    return true;
   }
 }

package/src/plugin/core/ActionScheduleTime.ts

@@ -43,7 +43,7 @@ function parseNonNegativeIntOptionOrThrow(value: string, fieldName: string): num
  * - Unix 时间戳秒/毫秒
  * - ISO 时间字符串（必须显式带时区）
  */
-export function parseScheduleTimeOptionOrThrow(
+export function parse_schedule_time_option_or_throw(
   value: string,
   fieldName: string,
 ): number {
@@ -79,10 +79,10 @@ export function parseScheduleTimeOptionOrThrow(
  * 解析 command 层调度输入并归一化为绝对毫秒时间戳。
  *
  * 说明（中文）
- * - `delayMs` 与 `time` 只能二选一。
+ * - `delay_ms` 与 `time` 只能二选一。
  * - 未传时返回 `undefined`，表示立即执行。
  */
-export function parseActionScheduleRunAtMsOrThrow(params: {
+export function parse_action_schedule_run_at_ms_or_throw(params: {
   delay?: string | number | undefined;
   time?: string | number | undefined;
 }): number | undefined {
@@ -104,16 +104,16 @@ export function parseActionScheduleRunAtMsOrThrow(params: {
   }
 
   if (timeText) {
-    return parseScheduleTimeOptionOrThrow(timeText, "time");
+    return parse_schedule_time_option_or_throw(timeText, "time");
   }
 
   return undefined;
 }
 
 /**
- * 规范化 API/存储层传入的 runAtMs。
+ * 规范化 API/存储层传入的 run_at_ms。
  */
-export function normalizeRunAtMsOrThrow(
+export function normalize_run_at_ms_or_throw(
   value: string | number | undefined,
   fieldName: string,
 ): number {

package/src/plugin/core/BasePlugin.ts

@@ -7,23 +7,17 @@
  * - Agent 注册 plugin 时自动启动 lifecycle；卸载时自动停止 lifecycle。
  */
 
-import type { AgentContext } from "@/agent/AgentContext.js";
+import type { PluginContext } from "@/types/plugin/PluginContext.js";
 import type { Plugin } from "@/types/plugin/PluginDefinition.js";
 import type { PluginActions } from "@/types/plugin/PluginAction.js";
-import type { PluginCommandContext, PluginLifecycle } from "@/types/plugin/PluginCommand.js";
+import type { PluginLifecycle } from "@/types/plugin/PluginCommand.js";
 import type {
   PluginAvailability,
-  PluginConfigDefinition,
   PluginHooks,
   PluginResolves,
 } from "@/types/plugin/PluginRuntime.js";
 import type { PluginHttpDefinition } from "@/types/plugin/PluginHttp.js";
-import type {
-  PluginSetupDefinition,
-  PluginUsageDefinition,
-} from "@/types/plugin/PluginSetup.js";
-import type { StructuredConfig } from "@/types/plugin/PluginConfig.js";
-import type { PluginRunContext } from "@/types/plugin/PluginRunContext.js";
+import type { PluginExecutionContext } from "@/types/plugin/PluginExecutionContext.js";
 
 /**
  * BasePlugin 抽象基类。
@@ -44,21 +38,6 @@ export abstract class BasePlugin implements Plugin {
    */
   readonly description: string = "";
 
-  /**
-   * 插件配置定义。
-   */
-  readonly config?: PluginConfigDefinition<StructuredConfig>;
-
-  /**
-   * 插件 setup 协议。
-   */
-  readonly setup?: PluginSetupDefinition;
-
-  /**
-   * 插件 usage 协议。
-   */
-  readonly usage?: PluginUsageDefinition;
-
   /**
    * 显式 action 集合。
    */
@@ -86,15 +65,15 @@ export abstract class BasePlugin implements Plugin {
    * Plugin 可用性检查。
    */
   availability?(
-    context: PluginCommandContext | AgentContext,
+    context: PluginContext,
   ): Promise<PluginAvailability> | PluginAvailability;
 
   /**
    * Plugin system 文本提供器。
    */
   system?(
-    context: AgentContext,
-    run_context?: PluginRunContext,
+    context: PluginContext,
+    execution_context?: PluginExecutionContext,
   ): Promise<string> | string;
 
 }