@downcity/plugins 1.0.4

package/src/task/runtime/CronTrigger.ts

@@ -0,0 +1,110 @@
+/**
+ * Task cron 触发引擎。
+ *
+ * 关键点（中文）
+ * - 该模块仅服务于 task plugin runtime，不放在 core。
+ * - 只提供 cron 注册与调度，不承载 task 业务语义。
+ */
+
+import cron from "node-cron";
+import type { ScheduledTask } from "node-cron";
+import {
+  TaskCronEngine,
+  TaskCronTriggerDefinition,
+} from "../types/Cron.js";
+
+export class TaskCronTriggerEngine implements TaskCronEngine {
+  private readonly definitions: Map<string, TaskCronTriggerDefinition> =
+    new Map();
+  private readonly scheduledJobs: Map<string, ScheduledTask> = new Map();
+  private started = false;
+
+  register(definition: TaskCronTriggerDefinition): void {
+    const id = String(definition.id || "").trim();
+    if (!id) throw new Error("TaskCronTriggerDefinition.id is required");
+
+    const expression = String(definition.expression || "").trim();
+    if (!expression)
+      throw new Error(`Cron expression is required for job: ${id}`);
+    if (!cron.validate(expression)) {
+      throw new Error(`Invalid cron expression for job ${id}: ${expression}`);
+    }
+
+    const normalized: TaskCronTriggerDefinition = {
+      ...definition,
+      id,
+      expression,
+    };
+
+    this.definitions.set(id, normalized);
+
+    if (this.started) {
+      this.scheduleOne(normalized);
+    }
+  }
+
+  unregister(id: string): void {
+    const key = String(id || "").trim();
+    if (!key) return;
+
+    this.definitions.delete(key);
+
+    const scheduled = this.scheduledJobs.get(key);
+    if (scheduled) {
+      try {
+        scheduled.stop();
+      } catch {
+        // ignore
+      }
+      this.scheduledJobs.delete(key);
+    }
+  }
+
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+    for (const definition of this.definitions.values()) {
+      this.scheduleOne(definition);
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (!this.started) return;
+    this.started = false;
+
+    for (const scheduled of this.scheduledJobs.values()) {
+      try {
+        scheduled.stop();
+      } catch {
+        // ignore
+      }
+    }
+    this.scheduledJobs.clear();
+  }
+
+  private scheduleOne(definition: TaskCronTriggerDefinition): void {
+    const previous = this.scheduledJobs.get(definition.id);
+    if (previous) {
+      try {
+        previous.stop();
+      } catch {
+        // ignore
+      }
+      this.scheduledJobs.delete(definition.id);
+    }
+
+    const scheduled = cron.schedule(
+      definition.expression,
+      async () => {
+        try {
+          await Promise.resolve(definition.execute());
+        } catch {
+          // ignore
+        }
+      },
+      definition.timezone ? { timezone: definition.timezone } : undefined,
+    );
+
+    this.scheduledJobs.set(definition.id, scheduled);
+  }
+}

package/src/task/runtime/Frontmatter.ts

@@ -0,0 +1,24 @@
+/**
+ * Markdown frontmatter parser（任务系统内核复用）。
+ *
+ * 关键点（中文）
+ * - 内核只保留通用 frontmatter 解析，不依赖 skills 模块实现。
+ * - 解析规则保持稳定：仅识别文档起始的 `--- yaml ---` 头块。
+ */
+
+export type FrontMatterParseResult = {
+  frontMatterYaml: string | null;
+  body: string;
+};
+
+export function parseFrontMatter(markdown: string): FrontMatterParseResult {
+  const text = String(markdown ?? "");
+  if (!text.startsWith("---")) return { frontMatterYaml: null, body: text };
+
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return { frontMatterYaml: null, body: text };
+
+  const frontMatterYaml = match[1] ?? "";
+  const body = text.slice(match[0].length);
+  return { frontMatterYaml, body };
+}

package/src/task/runtime/Model.ts

@@ -0,0 +1,347 @@
+/**
+ * Task definition parsing and validation.
+ *
+ * 关键点（中文）
+ * - `task.md` 使用 YAML frontmatter + markdown 正文
+ * - frontmatter 必须包含：title/when/description/sessionId/status
+ * - `when` 统一承载触发语义：`@manual` / cron / `time:<ISO8601-with-timezone>`
+ */
+
+import yaml from "js-yaml";
+import path from "node:path";
+import cron from "node-cron";
+import { parseFrontMatter } from "./Frontmatter.js";
+import type {
+  ShipTaskDefinitionV1,
+  ShipTaskFrontmatterV1,
+  ShipTaskKind,
+  ShipTaskStatus,
+} from "@/task/types/Task.js";
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+
+/**
+ * 必填 frontmatter 字段清单。
+ */
+const REQUIRED_FIELDS: Array<keyof ShipTaskFrontmatterV1> = [
+  "title",
+  "when",
+  "description",
+  "sessionId",
+  "status",
+];
+
+type TaskRawValue = JsonValue | undefined;
+
+function normalizeTaskReview(input: TaskRawValue): boolean | null {
+  if (typeof input === "boolean") return input;
+  if (typeof input !== "string") return null;
+  const value = input.trim().toLowerCase();
+  if (!value) return null;
+  if (["true", "1", "yes", "on"].includes(value)) return true;
+  if (["false", "0", "no", "off"].includes(value)) return false;
+  return null;
+}
+
+/**
+ * cron alias 映射表。
+ */
+const CRON_ALIAS_TO_EXPRESSION: Record<string, string> = {
+  "@manual": "@manual",
+  "@hourly": "0 * * * *",
+  "@daily": "0 0 * * *",
+  "@weekly": "0 0 * * 0",
+  "@monthly": "0 0 1 * *",
+  "@yearly": "0 0 1 1 *",
+  "@annually": "0 0 1 1 *",
+};
+
+const ISO_DATETIME_WITH_TZ_REGEXP =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:\d{2})$/i;
+const ISO_DATETIME_WITHOUT_TZ_REGEXP =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?$/i;
+
+function normalizeCronExpression(raw: string): string | null {
+  const value = String(raw || "").trim();
+  if (!value) return null;
+  const lower = value.toLowerCase();
+  return CRON_ALIAS_TO_EXPRESSION[lower] || value;
+}
+
+function normalizeOneShotTime(raw: string): { ok: true; value: string } | { ok: false; error: string } {
+  const value = String(raw || "").trim();
+  if (!value) {
+    return {
+      ok: false,
+      error:
+        "Invalid when time: expected ISO8601 datetime with timezone, e.g. 2026-03-08T10:30:00+08:00 or Z",
+    };
+  }
+  if (!ISO_DATETIME_WITH_TZ_REGEXP.test(value)) {
+    return {
+      ok: false,
+      error:
+        `Invalid when time: "${value}" (expected ISO8601 datetime with timezone, e.g. 2026-03-08T10:30:00+08:00 or Z)`,
+    };
+  }
+  const ms = Date.parse(value);
+  if (!Number.isFinite(ms) || Number.isNaN(ms)) {
+    return {
+      ok: false,
+      error:
+        `Invalid when time: "${value}" (expected ISO8601 datetime with timezone, e.g. 2026-03-08T10:30:00+08:00 or Z)`,
+    };
+  }
+  return { ok: true, value: new Date(ms).toISOString() };
+}
+
+/**
+ * 校验并归一化 when。
+ *
+ * 规则（中文）
+ * - `@manual`
+ * - cron / alias
+ * - `time:<ISO8601-with-timezone>`（一次性触发）
+ * - 兼容裸 ISO 时间输入，会归一化为 `time:<iso>`
+ */
+export function normalizeTaskWhen(
+  input: TaskRawValue,
+): { ok: true; value: string } | { ok: false; error: string } {
+  const raw = String(input || "").trim();
+  if (!raw) return { ok: false, error: "when cannot be empty" };
+
+  const lower = raw.toLowerCase();
+  if (lower === "@manual") return { ok: true, value: "@manual" };
+
+  if (lower.startsWith("time:")) {
+    const timeRaw = raw.slice(raw.indexOf(":") + 1).trim();
+    const normalized = normalizeOneShotTime(timeRaw);
+    if (!normalized.ok) return normalized;
+    return { ok: true, value: `time:${normalized.value}` };
+  }
+
+  if (ISO_DATETIME_WITH_TZ_REGEXP.test(raw)) {
+    const normalized = normalizeOneShotTime(raw);
+    if (!normalized.ok) return normalized;
+    return { ok: true, value: `time:${normalized.value}` };
+  }
+
+  if (ISO_DATETIME_WITHOUT_TZ_REGEXP.test(raw)) {
+    return {
+      ok: false,
+      error:
+        `Invalid when time: "${raw}" (expected ISO8601 datetime with timezone, e.g. 2026-03-08T10:30:00+08:00 or Z)`,
+    };
+  }
+
+  const cronExpression = normalizeCronExpression(raw);
+  if (!cronExpression) return { ok: false, error: "when cannot be empty" };
+  const canonical = CRON_ALIAS_TO_EXPRESSION[lower] ? lower : raw;
+  if (cronExpression !== "@manual" && !cron.validate(cronExpression)) {
+    return { ok: false, error: `Invalid when (cron): "${raw}"` };
+  }
+  return { ok: true, value: canonical };
+}
+
+/**
+ * 兼容旧调用名：返回 cron 表达式或 `@manual`。
+ */
+export function normalizeTaskCronExpression(raw: string): string | null {
+  const when = normalizeTaskWhen(raw);
+  if (!when.ok) return null;
+  if (isTaskWhenOneShot(when.value)) return null;
+  return normalizeCronExpression(when.value);
+}
+
+export function isTaskWhenManual(input: string): boolean {
+  const when = String(input || "").trim().toLowerCase();
+  return when === "@manual";
+}
+
+export function isTaskWhenOneShot(input: string): boolean {
+  const when = String(input || "").trim().toLowerCase();
+  return when.startsWith("time:");
+}
+
+/**
+ * when -> cron expression；非 cron 返回 null。
+ */
+export function resolveTaskWhenCronExpression(input: string): string | null {
+  const normalized = normalizeTaskWhen(input);
+  if (!normalized.ok) return null;
+  if (isTaskWhenManual(normalized.value)) return null;
+  if (isTaskWhenOneShot(normalized.value)) return null;
+  return normalizeCronExpression(normalized.value);
+}
+
+/**
+ * when -> one-shot 毫秒时间戳；非 one-shot 返回 null。
+ */
+export function resolveTaskWhenOneShotMs(input: string): number | null {
+  const normalized = normalizeTaskWhen(input);
+  if (!normalized.ok) return null;
+  if (!isTaskWhenOneShot(normalized.value)) return null;
+  const iso = normalized.value.slice("time:".length).trim();
+  const ms = Date.parse(iso);
+  if (!Number.isFinite(ms) || Number.isNaN(ms)) return null;
+  return ms;
+}
+
+/**
+ * 归一化 task 状态。
+ */
+export function normalizeTaskStatus(input: TaskRawValue): ShipTaskStatus | null {
+  const s = typeof input === "string" ? input.trim().toLowerCase() : "";
+  if (s === "enabled") return "enabled";
+  if (s === "paused") return "paused";
+  if (s === "disabled") return "disabled";
+  return null;
+}
+
+/**
+ * 归一化 task 执行类型。
+ */
+export function normalizeTaskKind(input: TaskRawValue): ShipTaskKind {
+  const s = typeof input === "string" ? input.trim().toLowerCase() : "";
+  if (s === "script") return "script";
+  return "agent";
+}
+
+/**
+ * 解析 task.md 为结构化定义。
+ */
+export function parseTaskMarkdown(params: {
+  taskId: string;
+  markdown: string;
+  taskMdPath: string;
+  projectRoot: string;
+}): { ok: true; task: ShipTaskDefinitionV1 } | { ok: false; error: string } {
+  const { taskId, markdown, taskMdPath, projectRoot } = params;
+  const text = String(markdown ?? "");
+  const { frontMatterYaml, body } = parseFrontMatter(text);
+
+  if (!frontMatterYaml || !frontMatterYaml.trim()) {
+    return { ok: false, error: "Missing YAML frontmatter (--- ... ---) in task.md" };
+  }
+
+  let meta: JsonObject | null = null;
+  try {
+    const loaded = yaml.load(frontMatterYaml) as JsonValue;
+    if (loaded && typeof loaded === "object" && !Array.isArray(loaded)) {
+      meta = loaded as JsonObject;
+    } else {
+      meta = null;
+    }
+  } catch (e) {
+    return { ok: false, error: `Invalid YAML frontmatter: ${String(e)}` };
+  }
+
+  if (!meta || typeof meta !== "object") {
+    return { ok: false, error: "Invalid frontmatter: must be a YAML object" };
+  }
+
+  // 兼容已有任务定义：若无 when，则按旧字段推导。
+  const rawWhen = String(meta.when ?? "").trim();
+  if (!rawWhen) {
+    const rawTime = String(meta.time ?? "").trim();
+    const rawCron = String(meta.cron ?? "").trim();
+    if (rawTime) {
+      meta.when = `time:${rawTime}`;
+    } else if (rawCron) {
+      meta.when = rawCron;
+    }
+  }
+
+  const missing: string[] = [];
+  const rawTitle = String(meta?.title ?? "").trim();
+  if (!rawTitle) missing.push("title");
+  for (const f of REQUIRED_FIELDS.filter((x) => x !== "title")) {
+    if (meta?.[f] === undefined || meta?.[f] === null || String(meta?.[f]).trim() === "") {
+      missing.push(String(f));
+    }
+  }
+  if (missing.length > 0) {
+    return { ok: false, error: `Missing required frontmatter fields: ${missing.join(", ")}` };
+  }
+
+  const status = normalizeTaskStatus(meta.status);
+  if (!status) {
+    return {
+      ok: false,
+      error: `Invalid status: "${String(meta.status)}" (expected: enabled|paused|disabled)`,
+    };
+  }
+
+  const whenNormalized = normalizeTaskWhen(meta.when);
+  if (!whenNormalized.ok) {
+    return { ok: false, error: whenNormalized.error };
+  }
+
+  const kind = normalizeTaskKind(meta.kind);
+  const bodyText = String(body ?? "").trim();
+  if (kind === "script" && !bodyText) {
+    return { ok: false, error: "script task body cannot be empty" };
+  }
+
+  const fm: ShipTaskFrontmatterV1 = {
+    title: rawTitle,
+    when: whenNormalized.value,
+    description: String(meta.description).trim(),
+    sessionId: String(meta.sessionId).trim(),
+    kind,
+    ...(kind === "agent" && normalizeTaskReview(meta.review) === true ? { review: true } : {}),
+    status,
+  };
+
+  const relTaskMdPath = path
+    .relative(projectRoot, taskMdPath)
+    .split(path.sep)
+    .join("/");
+
+  const task: ShipTaskDefinitionV1 = {
+    v: 1,
+    taskId,
+    frontmatter: fm,
+    body: String(body ?? "").trim(),
+    taskMdPath: relTaskMdPath,
+  };
+
+  return { ok: true, task };
+}
+
+/**
+ * 生成 task.md 文本。
+ */
+export function buildTaskMarkdown(params: {
+  frontmatter: ShipTaskFrontmatterV1;
+  body: string;
+}): string {
+  const { frontmatter, body } = params;
+  const whenNormalized = normalizeTaskWhen(frontmatter.when);
+  if (!whenNormalized.ok) {
+    throw new Error(whenNormalized.error);
+  }
+
+  const kind = normalizeTaskKind(frontmatter.kind);
+  const bodyText = String(body ?? "").trim();
+  if (kind === "script" && !bodyText) {
+    throw new Error("script task body cannot be empty");
+  }
+
+  const meta = {
+    title: String(frontmatter.title || "").trim(),
+    when: whenNormalized.value,
+    description: String(frontmatter.description || "").trim(),
+    sessionId: String(frontmatter.sessionId || "").trim(),
+    kind,
+    ...(kind === "agent" ? { review: Boolean(frontmatter.review) } : {}),
+    status: String(frontmatter.status || "").trim(),
+  };
+
+  const yamlText = yaml.dump(meta, {
+    lineWidth: 120,
+    noRefs: true,
+  });
+
+  const bodyWithTrailingLf = bodyText ? bodyText + "\n" : "";
+  return `---\n${yamlText}---\n\n${bodyWithTrailingLf}`;
+}

package/src/task/runtime/Paths.ts

@@ -0,0 +1,116 @@
+/**
+ * Task System paths and identifiers.
+ *
+ * 约定（中文）
+ * - task root: `./.downcity/task/`
+ * - definition: `./.downcity/task/<taskId>/task.md`
+ * - run dir: `./.downcity/task/<taskId>/<timestamp>/`
+ *
+ * 同时定义“task run sessionId”格式，用于把 Agent 的 session 映射到 run 目录：
+ * - `task-run:<taskId>:<timestamp>`
+ */
+
+import path from "node:path";
+
+/**
+ * taskId 允许字符：
+ * - 首字符：任意语言字母/数字
+ * - 后续：字母/数字/空格/下划线/连字符
+ */
+const TASK_ID_REGEXP = /^[\p{L}\p{N}][\p{L}\p{N}_\-\s]{0,63}$/u;
+
+export function isValidTaskId(input: string): boolean {
+  const id = String(input || "").trim();
+  if (!id) return false;
+  // 关键点（中文）：taskId 直接参与文件路径拼接，必须是安全的文件夹名。
+  return TASK_ID_REGEXP.test(id);
+}
+
+/**
+ * 从 title 派生 taskId。
+ *
+ * 关键点（中文）
+ * - 目标：保证“title 与 taskId 同源”，避免随机 ID。
+ * - 处理：移除路径危险字符与非常见标点，压缩空白，最终按 taskId 规则校验。
+ */
+export function deriveTaskIdFromTitle(title: string): string {
+  const normalized = String(title || "")
+    .normalize("NFKC")
+    .replace(/[\\/:\u0000]/g, " ")
+    .replace(/[^\p{L}\p{N}_\-\s]/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 64)
+    .trim();
+
+  if (!normalized) {
+    throw new Error("Cannot derive taskId from title: title is empty after normalization.");
+  }
+  return normalizeTaskId(normalized);
+}
+
+export function normalizeTaskId(input: string): string {
+  const id = String(input || "").trim();
+  if (!isValidTaskId(id)) {
+    throw new Error(
+      `Invalid taskId: "${id}". Use a letter/number first, then letters/numbers/space/_/-, max 64 chars.`,
+    );
+  }
+  return id;
+}
+
+export function getTaskRootDir(projectRoot: string): string {
+  return path.join(String(projectRoot || "").trim(), ".downcity", "task");
+}
+
+export function getTaskDir(projectRoot: string, taskId: string): string {
+  return path.join(getTaskRootDir(projectRoot), normalizeTaskId(taskId));
+}
+
+export function getTaskMdPath(projectRoot: string, taskId: string): string {
+  return path.join(getTaskDir(projectRoot, taskId), "task.md");
+}
+
+export function formatTaskRunTimestamp(date: Date = new Date()): string {
+  const pad = (n: number, width: number) => String(n).padStart(width, "0");
+  // 关键点（中文）：run 目录名统一使用 UTC，避免跨时区/DST 下时间排序歧义。
+  const yyyy = date.getUTCFullYear();
+  const mm = pad(date.getUTCMonth() + 1, 2);
+  const dd = pad(date.getUTCDate(), 2);
+  const hh = pad(date.getUTCHours(), 2);
+  const mi = pad(date.getUTCMinutes(), 2);
+  const ss = pad(date.getUTCSeconds(), 2);
+  const ms = pad(date.getUTCMilliseconds(), 3);
+  return `${yyyy}${mm}${dd}-${hh}${mi}${ss}-${ms}`;
+}
+
+export function getTaskRunDir(
+  projectRoot: string,
+  taskId: string,
+  timestamp: string,
+): string {
+  const ts = String(timestamp || "").trim();
+  if (!ts) throw new Error("timestamp is required");
+  return path.join(getTaskDir(projectRoot, taskId), ts);
+}
+
+export function createTaskRunSessionId(taskId: string, timestamp: string): string {
+  const id = normalizeTaskId(taskId);
+  const ts = String(timestamp || "").trim();
+  if (!ts) throw new Error("timestamp is required");
+  return `task-run:${id}:${ts}`;
+}
+
+export function parseTaskRunSessionId(
+  sessionId: string,
+): { taskId: string; timestamp: string } | null {
+  const key = String(sessionId || "").trim();
+  if (!key) return null;
+  const m = key.match(/^task-run:([^:]+):(.+)$/);
+  if (!m) return null;
+  const taskId = String(m[1] || "").trim();
+  const timestamp = String(m[2] || "").trim();
+  if (!taskId || !timestamp) return null;
+  if (!isValidTaskId(taskId)) return null;
+  return { taskId, timestamp };
+}