@downcity/agent 1.1.1

package/src/service/schedule/Store.ts

@@ -0,0 +1,316 @@
+/**
+ * Service Schedule 持久化存储。
+ *
+ * 关键点（中文）
+ * - 使用项目内 SQLite 持久化 one-shot service action 调度任务。
+ * - 当前模块只维护“当前状态”，不维护额外审计事件流。
+ */
+
+import fs from "fs-extra";
+import Database from "better-sqlite3";
+import path from "node:path";
+import { and, asc, desc, eq, inArray, lte } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import { scheduledJobsTable } from "./Schema.js";
+import type {
+  CreateScheduledJobInput,
+  ScheduledJobRecord,
+  ScheduledJobStatus,
+} from "@/shared/types/ServiceSchedule.js";
+import type { JsonValue } from "@/shared/types/Json.js";
+import { generateId } from "@shared/utils/Id.js";
+import { getDowncityScheduleDbPath } from "@/config/Paths.js";
+
+type ScheduledJobRow = typeof scheduledJobsTable.$inferSelect;
+
+/**
+ * Service Schedule Store。
+ */
+export class ServiceScheduleStore {
+  private readonly sqlite: Database.Database;
+
+  private readonly db: ReturnType<typeof drizzle>;
+
+  constructor(projectRoot: string) {
+    const dbPath = getDowncityScheduleDbPath(projectRoot);
+    fs.ensureDirSync(path.dirname(dbPath));
+    this.sqlite = new Database(dbPath);
+    this.sqlite.pragma("journal_mode = WAL");
+    this.db = drizzle(this.sqlite);
+    this.ensureSchema();
+  }
+
+  /**
+   * 初始化表结构。
+   */
+  private ensureSchema(): void {
+    this.sqlite.exec(`
+      CREATE TABLE IF NOT EXISTS scheduled_jobs (
+        id TEXT PRIMARY KEY NOT NULL,
+        service_name TEXT NOT NULL,
+        action_name TEXT NOT NULL,
+        payload_json TEXT NOT NULL,
+        run_at_ms INTEGER NOT NULL,
+        status TEXT NOT NULL,
+        error TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+    `);
+    this.sqlite.exec(`
+      CREATE INDEX IF NOT EXISTS scheduled_jobs_status_run_at_idx
+      ON scheduled_jobs(status, run_at_ms);
+    `);
+    this.sqlite.exec(`
+      CREATE INDEX IF NOT EXISTS scheduled_jobs_run_at_idx
+      ON scheduled_jobs(run_at_ms);
+    `);
+  }
+
+  /**
+   * 关闭数据库连接。
+   */
+  close(): void {
+    this.sqlite.close();
+  }
+
+  /**
+   * 创建调度任务。
+   */
+  createJob(input: CreateScheduledJobInput): ScheduledJobRecord {
+    const now = Date.now();
+    const id = `sched_${generateId()}`;
+    const payloadJson = JSON.stringify(input.payload ?? null);
+    this.db.insert(scheduledJobsTable).values({
+      id,
+      serviceName: String(input.serviceName || "").trim(),
+      actionName: String(input.actionName || "").trim(),
+      payloadJson,
+      runAtMs: Math.trunc(input.runAtMs),
+      status: "pending",
+      error: null,
+      createdAt: now,
+      updatedAt: now,
+    }).run();
+
+    return {
+      id,
+      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,
+    };
+  }
+
+  /**
+   * 获取单个任务。
+   */
+  getJobById(jobId: string): ScheduledJobRecord | null {
+    const row = this.db.select().from(scheduledJobsTable)
+      .where(eq(scheduledJobsTable.id, String(jobId || "").trim()))
+      .get();
+    return row ? this.toJobRecord(row) : null;
+  }
+
+  /**
+   * 列出指定状态的任务。
+   */
+  listJobsByStatus(statuses: ScheduledJobStatus[]): ScheduledJobRecord[] {
+    if (statuses.length === 0) return [];
+    const rows = this.db.select().from(scheduledJobsTable)
+      .where(inArray(scheduledJobsTable.status, statuses))
+      .orderBy(asc(scheduledJobsTable.runAtMs))
+      .all();
+    return rows.map((row) => this.toJobRecord(row));
+  }
+
+  /**
+   * 列出任务。
+   *
+   * 说明（中文）
+   * - 默认按 `runAtMs` 升序返回，便于排查“接下来会执行什么”。
+   * - 可选状态过滤与数量限制，避免一次输出过多记录。
+   */
+  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 status = params?.status;
+    const query = this.db.select().from(scheduledJobsTable);
+    const rows =
+      typeof status === "string" && status
+        ? query
+            .where(eq(scheduledJobsTable.status, status))
+            .orderBy(asc(scheduledJobsTable.runAtMs), desc(scheduledJobsTable.createdAt))
+            .limit(limit)
+            .all()
+        : query
+            .orderBy(asc(scheduledJobsTable.runAtMs), desc(scheduledJobsTable.createdAt))
+            .limit(limit)
+            .all();
+    return rows.map((row) => this.toJobRecord(row));
+  }
+
+  /**
+   * 列出已到点且待执行的任务。
+   */
+  listDuePendingJobs(nowMs: number): ScheduledJobRecord[] {
+    const rows = this.db.select().from(scheduledJobsTable)
+      .where(
+        and(
+          eq(scheduledJobsTable.status, "pending"),
+          lte(scheduledJobsTable.runAtMs, Math.trunc(nowMs)),
+        ),
+      )
+      .orderBy(asc(scheduledJobsTable.runAtMs))
+      .all();
+    return rows.map((row) => this.toJobRecord(row));
+  }
+
+  /**
+   * 启动恢复时，把历史 `running` 回退到 `pending`。
+   */
+  resetRunningJobsToPending(): number {
+    const now = Date.now();
+    const result = this.db.update(scheduledJobsTable)
+      .set({
+        status: "pending",
+        updatedAt: now,
+        error: null,
+      })
+      .where(eq(scheduledJobsTable.status, "running"))
+      .run();
+    return Number(result.changes || 0);
+  }
+
+  /**
+   * 将任务标记为执行中。
+   *
+   * 关键点（中文）
+   * - 仅允许从 `pending` 进入 `running`，避免重复领取。
+   */
+  markJobRunning(jobId: string): boolean {
+    const result = this.db.update(scheduledJobsTable)
+      .set({
+        status: "running",
+        updatedAt: Date.now(),
+        error: null,
+      })
+      .where(
+        and(
+          eq(scheduledJobsTable.id, String(jobId || "").trim()),
+          eq(scheduledJobsTable.status, "pending"),
+        ),
+      )
+      .run();
+    return Number(result.changes || 0) > 0;
+  }
+
+  /**
+   * 将任务标记为成功。
+   */
+  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",
+    });
+  }
+
+  /**
+   * 取消待执行任务。
+   *
+   * 关键点（中文）
+   * - 仅允许取消 `pending`，避免打断已经开始执行的任务。
+   */
+  cancelPendingJob(jobId: string): boolean {
+    const result = this.db.update(scheduledJobsTable)
+      .set({
+        status: "cancelled",
+        updatedAt: Date.now(),
+        error: null,
+      })
+      .where(
+        and(
+          eq(scheduledJobsTable.id, String(jobId || "").trim()),
+          eq(scheduledJobsTable.status, "pending"),
+        ),
+      )
+      .run();
+    return Number(result.changes || 0) > 0;
+  }
+
+  /**
+   * 统一写入终态。
+   */
+  private updateTerminalStatus(params: {
+    jobId: string;
+    status: Exclude<ScheduledJobStatus, "pending" | "running">;
+    error?: string;
+  }): boolean {
+    const result = this.db.update(scheduledJobsTable)
+      .set({
+        status: params.status,
+        updatedAt: Date.now(),
+        error: params.error ? String(params.error) : null,
+      })
+      .where(eq(scheduledJobsTable.id, String(params.jobId || "").trim()))
+      .run();
+    return Number(result.changes || 0) > 0;
+  }
+
+  /**
+   * 行转业务对象。
+   */
+  private toJobRecord(row: ScheduledJobRow): ScheduledJobRecord {
+    return {
+      id: row.id,
+      serviceName: row.serviceName,
+      actionName: row.actionName,
+      payload: this.parsePayloadJson(row.payloadJson),
+      runAtMs: row.runAtMs,
+      status: row.status as ScheduledJobStatus,
+      ...(typeof row.error === "string" && row.error ? { error: row.error } : {}),
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+    };
+  }
+
+  /**
+   * 安全解析 payload JSON。
+   */
+  private parsePayloadJson(input: string): JsonValue {
+    try {
+      return JSON.parse(String(input || "null")) as JsonValue;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/service/schedule/Time.ts

@@ -0,0 +1,131 @@
+/**
+ * Service Schedule 时间解析工具。
+ *
+ * 关键点（中文）
+ * - 统一解析 `--delay` / `--time` 对应的调度时间。
+ * - 输出统一毫秒时间戳，供 command 层与持久化层复用。
+ */
+
+/**
+ * 判断是否为“缺少时区”的 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 parseScheduledRunAtMsOrThrow(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/services/BaseService.ts

@@ -0,0 +1,85 @@
+/**
+ * BaseService：service 类实现的统一基类。
+ *
+ * 关键点（中文）
+ * - agent 会持有 per-agent 的 service instance，而不再直接依赖全局 service 单例对象。
+ * - 各 service 的长期状态应归属于实例本身，而不是模块级单例。
+ */
+
+import type { AgentRuntime } from "@/types/agent/AgentRuntime.js";
+import type {
+  Service,
+  ServiceActions,
+  ServiceLifecycle,
+} from "@/shared/types/Service.js";
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+import type { ServiceStateRecord } from "@/shared/types/ServiceState.js";
+
+/**
+ * BaseService 抽象基类。
+ *
+ * 关键点（中文）
+ * - 保留统一 `Service` 契约。
+ * - 为实例字段状态（cronEngine / queueWorker / watchers / shellSessions）预留宿主引用。
+ */
+export abstract class BaseService implements Service {
+  /**
+   * 当前实例持有的通用 service 状态记录。
+   *
+   * 关键点（中文）
+   * - 通用 lifecycle 状态直接归属于 service 实例。
+   * - `ServiceStateController` 只负责读写，不再维护全局状态表。
+   */
+  public readonly serviceStateRecord: ServiceStateRecord = {
+    state: "stopped",
+    updatedAt: Date.now(),
+    chain: Promise.resolve(),
+  };
+
+  /**
+   * 当前 service 所属的 agent 宿主。
+   *
+   * 关键点（中文）
+   * - 允许为空，仅用于静态装配与无宿主测试场景。
+   * - 真正运行中的 service 实例应始终绑定一个 agent。
+   */
+  protected readonly agent: AgentRuntime | null;
+
+  constructor(agent: AgentRuntime | null) {
+    this.agent = agent;
+  }
+
+  /**
+   * 当前 service 名称。
+   */
+  abstract readonly name: string;
+
+  /**
+   * 当前 service 的 action 定义表。
+   */
+  abstract readonly actions: ServiceActions;
+
+  /**
+   * 可选的 service 级 system 文本提供器。
+   */
+  system?(context: AgentContext): string | Promise<string>;
+
+  /**
+   * 可选的 service 生命周期定义。
+   */
+  lifecycle?: ServiceLifecycle;
+
+  /**
+   * 读取绑定的 agent 宿主。
+   *
+   * 关键点（中文）
+   * - 仅供后续真正 class service 在实例方法中读取宿主能力。
+   * - 未绑定 agent 时直接 fail-fast，避免静默读取 undefined。
+   */
+  protected requireAgent(): AgentRuntime {
+    if (this.agent) return this.agent;
+    throw new Error(
+      `Service "${this.name}" is not bound to an agent instance.`,
+    );
+  }
+}

package/src/services/README.md

@@ -0,0 +1,100 @@
+# services
+
+## 模块定位
+
+`services/` 是 Downcity 的主动业务层。  
+每个 service 对外暴露统一的 `Service` 契约，但在运行时已经逐步迁移为 `BaseService` 子类，由 agent 在启动时创建 `per-agent service instance`。
+
+## 当前整体模型
+
+1. `main/service/Services.ts`
+   - 维护 service 的静态注册清单。
+2. `main/registries/ServiceClassRegistry.ts`
+   - 负责把静态 service 定义实例化为 `BaseService` 子类。
+3. `agent/AgentRuntime.ts`
+   - agent 持有当前运行中的 service 实例集合。
+4. `main/service/Manager.ts`
+   - 统一做 service lifecycle、action 调度、CLI/API 桥接。
+5. `src/types/Service.ts`
+   - 作为 service 共享契约的单一事实源。
+
+## 当前内建 service
+
+1. `chat/`
+   - 负责聊天渠道接入、session 路由、消息发送与会话查询。
+   - `ChatService.ts` 是实例入口。
+   - `ChatService` 只保留实例骨架，持有实例级 `channelState` 与 `queueWorker`。
+   - `runtime/ChatServiceActions.ts` 负责 action 注册表装配。
+   - `runtime/ChatServiceSystem.ts` 负责 system prompt。
+   - `runtime/ChatChannelCore.ts` 负责渠道基础 helper。
+   - `runtime/ChatChannelLifecycle.ts` 负责渠道 bot 生命周期。
+   - `runtime/ChatChannelConfig.ts` 负责状态快照与配置落盘。
+   - `runtime/ChatChannelActions.ts` 负责渠道类 action 执行。
+   - `runtime/ChatChannelFacade.ts` 只保留门面导出。
+   - `runtime/ChatActionInput.ts` 负责 CLI/API 输入映射。
+   - `runtime/ChatActionExecution.ts` 负责消息类 action 执行。
+   - `runtime/ChatQueueSessionBridge.ts` 负责 queue 与 session 的桥接写入协议。
+   - `runtime/ChatQueueWorkerSupport.ts` 负责 worker 辅助能力。
+   - `runtime/ChatQueueReplyDispatch.ts` 负责 direct/fallback 回复分发。
+   - `runtime/ChatQueueWorker.ts` 负责 queue lane 调度与主执行链。
+   - `channels/BaseChatChannel.ts` 负责渠道基类门面与公共编排。
+   - `channels/BaseChatChannelSupport.ts` 负责 session 映射、history 与 chat meta 辅助。
+   - `channels/BaseChatChannelQueue.ts` 负责 audit/exec 入队编排。
+   - `channels/telegram/Bot.ts` 现在只保留 Telegram 渠道门面与编排。
+   - `channels/telegram/TelegramPlatformClient.ts` 负责 Telegram polling/API/发送主逻辑。
+   - `channels/telegram/TelegramInbound.ts` 负责 Telegram 入站归一化辅助。
+   - `channels/feishu/Feishu.ts` 现在只保留 Feishu 渠道门面与编排。
+   - `channels/feishu/FeishuPlatformClient.ts` 负责 Feishu runtime 宿主与 token/cache 状态。
+   - `channels/feishu/FeishuPlatformLookup.ts` 负责 Feishu 用户/群聊/reply 查询与入站附件下载。
+   - `channels/feishu/FeishuPlatformMessaging.ts` 负责 Feishu 消息发送与附件上传。
+   - `channels/feishu/FeishuInbound.ts` 负责 Feishu 入站归一化辅助。
+   - `channels/qq/QQ.ts` 现在只保留 QQ 渠道门面与编排。
+   - `channels/qq/QQSupport.ts` 负责 QQ READY 身份解析、命令映射与入站增强组装。
+  - `channels/qq/QQGatewayClient.ts` 负责 QQ Gateway runtime 宿主、WS 编排与重连调度。
+  - `channels/qq/QQGatewaySupport.ts` 负责 QQ Gateway 状态快照、心跳判断与 payload 解析。
+   - `channels/qq/QQGatewayAuth.ts` 负责 QQ 鉴权、Gateway URL 与 HTTP 连通性测试。
+   - `channels/qq/QQGatewaySend.ts` 负责 QQ 回发请求构造、超时与自动重试。
+   - `channels/qq/QQInbound.ts` 负责 QQ 入站归一化辅助。
+2. `task/`
+   - 负责任务定义、计划调度、手动执行与 run 落盘。
+   - `TaskService.ts` 是实例入口，持有实例级 cron runtime 状态。
+   - `runtime/TaskServiceActions.ts` 负责 action 注册表装配。
+   - `runtime/TaskServiceSystem.ts` 负责 task system prompt。
+   - `runtime/TaskActionInput.ts` 负责 CLI/API 输入映射。
+   - `runtime/TaskActionExecution.ts` 负责 task 领域执行逻辑。
+   - `runtime/TaskRunnerProgress.ts` 负责 progress 快照与文本辅助。
+   - `runtime/TaskRunnerSession.ts` 负责 task 专用 session runtime。
+   - `runtime/TaskRunnerRound.ts` 负责单轮执行与模拟用户判定。
+   - `runtime/TaskRunArtifacts.ts` 负责 run 产物写入与 markdown/json 摘要格式。
+   - `runtime/Runner.ts` 负责主编排并协调 run 产物写入。
+3. `memory/`
+   - 负责记忆提取、索引、检索与 flush。
+   - `MemoryService.ts` 持有实例级 memory runtime 状态。
+4. `shell/`
+   - 负责 shell session 生命周期与命令执行。
+   - `ShellService.ts` 持有实例级 shell session 状态。
+   - `runtime/ShellActionRuntime.ts` 负责公开 action 编排。
+   - `runtime/ShellActionRuntimeSupport.ts` 负责持久化、waiter 与 session 查找等共享运行时细节。
+   - `session/tools/shell/ShellToolDefinition.ts` 作为 session tool facade，只做协议适配。
+   - `session/tools/shell/ShellToolSchemas.ts` 负责 shell tool schema。
+   - `session/tools/shell/ShellToolBridge.ts` 负责 runtime bridge 与响应整理。
+
+## 统一服务模式
+
+1. `Index.ts`
+   - 只保留静态导出入口。
+2. `<Domain>Service.ts`
+   - 作为真正的 class service 实现。
+3. `Action.ts`
+   - 保留该领域的核心业务 helper，供 service/runtime 复用。
+4. `runtime/`
+   - 承载具体运行时实现、状态管理与输入映射。
+5. `types/`
+   - 存放领域内部协议；跨层共享契约统一提升到 `src/types/`。
+
+## 边界约束
+
+1. service 通过 `AgentContext` 读取运行时能力。
+2. service 的实例状态应归属于 service instance，而不是模块级单例。
+3. plugin 只能作为被动扩展，不替代 service 主流程。
+4. service 间协作优先通过 `AgentContext.invoke`，而不是隐式全局状态。