@longzai-intelligence-workflow/core 0.0.1

package/src/schemas/workflow-doc.schema.ts

@@ -0,0 +1,365 @@
+/**
+ * workflow 声明档契约（frontmatter 结构领域真源——归属引擎主仓 core 包）
+ *
+ * 声明域方言 = 标量 + 字符串数组（declaration-frontmatter 方言）。
+ * 行内结构四段制：items = `<id> | <标题> | <指针> | <状态>`；
+ * gates = `<挂靠> | <类型> | <说明> | <裁定>`——执行状态与裁定事实归声明档（属主维护）。
+ * 依赖方向铁律：工具仓消费引擎契约，引擎不依赖工具仓（对齐 arxiv 家族与 ADR 0098 拓扑）。
+ */
+import * as z from 'zod';
+
+/**
+ * 工作项执行状态枚举（对齐台账家族词汇；执行状态归声明档，属主手改）
+ */
+export const WORK_ITEM_STATUSES = ['todo', 'doing', 'blocked', 'done', 'dropped'] as const;
+
+/**
+ * 工作项执行状态类型
+ */
+export type WorkItemStatus = (typeof WORK_ITEM_STATUSES)[number];
+
+/**
+ * kebab-case slug（id 与文件名 stem，去 .workflow.md）
+ */
+const KEBAB_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * 工作项指针备选：`task:<仓>/<slug>`（task 台账引用）或 `ref:<仓>/<仓内路径>`
+ */
+const ITEM_REF_ALTERNATION = 'task:[a-z0-9][a-z0-9-]*\\/[a-z0-9\\/-]+|ref:[a-z0-9][a-z0-9-]*\\/[a-z0-9\\/. _-]+';
+
+/**
+ * 工作项行：`<itemId> | <标题> | <指针> | <状态>`（四段制）
+ */
+const ITEM_LINE_PATTERN = new RegExp(
+  `^([a-z0-9]+(?:-[a-z0-9]+)*) \\| (.+) \\| (${ITEM_REF_ALTERNATION}) \\| (todo|doing|blocked|done|dropped)$`,
+);
+
+/**
+ * 裁定段：`pending` 或 `<结果>:<决定者>:<凭据>`（已裁必带决定者，凭据可省）
+ */
+const GATE_RULING_PATTERN = /^(pending)$|^(approved|rejected|escalated):([^:|]+)(?::([^:|]+))?$/;
+
+/**
+ * 裁定门行：`<挂靠> | <类型> | <说明> | <裁定>`（四段制；说明段禁含管道符）
+ */
+const GATE_LINE_PATTERN =
+  /^([a-z0-9]+(?:-[a-z0-9]+)*|workflow) \| ([a-z0-9-]+) \| ([^|]+?) \| (pending|(?:(?:approved|rejected|escalated):[^:|]+(?::[^:|]+)?))$/;
+
+/**
+ * 依赖边：`<from> -> <to>`（两端均为工作项 id）
+ */
+const EDGE_PATTERN = /^([a-z0-9]+(?:-[a-z0-9]+)*) -> ([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+/**
+ * 工作项（解析后形态）
+ */
+export type WorkflowItem = {
+  /**
+   * 工作项 id（工作流内唯一）
+   */
+  readonly id: string;
+
+  /**
+   * 标题（人读）
+   */
+  readonly title: string;
+
+  /**
+   * 指针（task 台账引用或 ref 路径引用）
+   */
+  readonly ref: string;
+
+  /**
+   * 执行状态（声明档承载，属主维护）
+   */
+  readonly status: WorkItemStatus;
+};
+
+/**
+ * 依赖边（解析后形态）
+ */
+export type WorkflowEdge = {
+  /**
+   * 前置工作项 id
+   */
+  readonly from: string;
+
+  /**
+   * 后继工作项 id
+   */
+  readonly to: string;
+};
+
+/**
+ * 裁定事实（裁定段解析形态）
+ */
+export type GateRuling = {
+  /**
+   * 裁定状态（pending 未裁；approved/rejected/escalated 已裁）
+   */
+  readonly status: 'pending' | 'approved' | 'rejected' | 'escalated';
+
+  /**
+   * 决定者（已裁时携带）
+   */
+  readonly decidedBy?: string;
+
+  /**
+   * 凭据指针（裁决记录文件路径等）
+   */
+  readonly evidence?: string;
+};
+
+/**
+ * 裁定门（解析后形态）
+ */
+export type WorkflowGate = {
+  /**
+   * 挂靠位置（工作项 id 或 `workflow` 工作流级）
+   */
+  readonly at: string;
+
+  /**
+   * 门类型（如 ruling = 人类裁定门）
+   */
+  readonly kind: string;
+
+  /**
+   * 说明（禁含管道符）
+   */
+  readonly note: string;
+
+  /**
+   * 裁定事实（归声明档，裁定人维护）
+   */
+  readonly ruling: GateRuling;
+};
+
+/**
+ * workflow 声明档 frontmatter schema（方言字符串数组 + 行内结构形态执法）
+ */
+export const WorkflowDocFrontmatterSchema = z.strictObject({
+  /**
+   * 工作流 id（= 文件名 stem，去 .workflow.md）
+   */
+  id: z.string().regex(KEBAB_PATTERN),
+
+  /**
+   * 工作流标题
+   */
+  title: z.string().min(1),
+
+  /**
+   * 声明状态（声明域生命周期，区别于执行状态）
+   */
+  status: z.enum(['draft', 'active', 'completed', 'archived']),
+
+  /**
+   * 工作项清单（行内方言四段制，逐行经 parseItemLine 执法）
+   */
+  items: z.array(z.string()),
+
+  /**
+   * 依赖边（行内方言：`<from> -> <to>`；可选）
+   */
+  edges: z.array(z.string().regex(EDGE_PATTERN)).optional(),
+
+  /**
+   * 裁定门（行内方言四段制，逐行经 parseGateLine 执法；可选）
+   */
+  gates: z.array(z.string()).optional(),
+});
+
+/**
+ * 声明档 frontmatter 形态（schema 推断）
+ */
+export type WorkflowDocFrontmatter = z.infer<typeof WorkflowDocFrontmatterSchema>;
+
+/**
+ * 解析工作项行（四段制）
+ *
+ * @param line - 行内方言文本
+ * @returns 解析成功时为工作项形态，失败时为 null
+ */
+export function parseItemLine(line: string): WorkflowItem | null {
+  /**
+   * 行内四段切分结果
+   */
+  const matched = ITEM_LINE_PATTERN.exec(line);
+  if (!matched) {
+    return null;
+  }
+
+  /**
+   * 工作项 id 捕获段（索引访问可能为 undefined，判空后收窄）
+   */
+  const id = matched[1];
+
+  /**
+   * 工作项标题捕获段（索引访问可能为 undefined，判空后收窄）
+   */
+  const title = matched[2];
+
+  /**
+   * 工作项指针捕获段（索引访问可能为 undefined，判空后收窄）
+   */
+  const ref = matched[3];
+
+  /**
+   * 执行状态捕获段（索引访问可能为 undefined，判空后收窄）
+   */
+  const status = matched[4];
+  if (id === undefined || title === undefined || ref === undefined || status === undefined) {
+    return null;
+  }
+
+  /**
+   * 状态段枚举守卫 schema（zod 收窄，零 as 断言）
+   */
+  const itemStatusGuardSchema = z.enum(WORK_ITEM_STATUSES);
+
+  /**
+   * 状态段枚举校验结果
+   */
+  const statusChecked = itemStatusGuardSchema.safeParse(status);
+  if (!statusChecked.success) {
+    return null;
+  }
+  return { id, title, ref, status: statusChecked.data };
+}
+
+/**
+ * 解析依赖边行
+ *
+ * @param line - 行内方言文本
+ * @returns 解析成功时为依赖边形态，失败时为 null
+ */
+export function parseEdgeLine(line: string): WorkflowEdge | null {
+  /**
+   * 行内两段切分结果
+   */
+  const matched = EDGE_PATTERN.exec(line);
+  if (!matched) {
+    return null;
+  }
+
+  /**
+   * 前置工作项 id 捕获段（索引访问可能为 undefined，判空后收窄）
+   */
+  const from = matched[1];
+
+  /**
+   * 后继工作项 id 捕获段（索引访问可能为 undefined，判空后收窄）
+   */
+  const to = matched[2];
+  if (from === undefined || to === undefined) {
+    return null;
+  }
+  return { from, to };
+}
+
+/**
+ * 解析裁定段（`pending` 或 `<结果>:<决定者>:<凭据>`）
+ *
+ * @param segment - 裁定段文本
+ * @returns 解析成功时为裁定事实形态，失败时为 null
+ */
+export function parseGateRuling(segment: string): GateRuling | null {
+  /**
+   * 裁定段切分结果
+   */
+  const matched = GATE_RULING_PATTERN.exec(segment);
+  if (!matched) {
+    return null;
+  }
+
+  /**
+   * 裁定状态捕获段（索引访问可能为 undefined，判空后收窄）
+   */
+  const status = matched[1] ?? matched[2];
+  if (status === undefined) {
+    return null;
+  }
+
+  /**
+   * 裁定状态枚举守卫 schema（zod 收窄，零 as 断言）
+   */
+  const rulingStatusGuardSchema = z.enum(['pending', 'approved', 'rejected', 'escalated']);
+
+  /**
+   * 裁定状态枚举校验结果
+   */
+  const statusChecked = rulingStatusGuardSchema.safeParse(status);
+  if (!statusChecked.success) {
+    return null;
+  }
+
+  /**
+   * 决定者捕获段（pending 时缺席）
+   */
+  const decidedBy = matched[3];
+
+  /**
+   * 凭据指针捕获段（可省）
+   */
+  const evidence = matched[4];
+  return {
+    status: statusChecked.data,
+    ...(decidedBy !== undefined ? { decidedBy } : {}),
+    ...(evidence !== undefined ? { evidence } : {}),
+  };
+}
+
+/**
+ * 解析裁定门行（四段制）
+ *
+ * @param line - 行内方言文本
+ * @returns 解析成功时为裁定门形态，失败时为 null
+ */
+export function parseGateLine(line: string): WorkflowGate | null {
+  /**
+   * 行内四段切分结果
+   */
+  const matched = GATE_LINE_PATTERN.exec(line);
+  if (!matched) {
+    return null;
+  }
+
+  /**
+   * 挂靠位置捕获段（索引访问可能为 undefined，判空后收窄）
+   */
+  const at = matched[1];
+
+  /**
+   * 门类型捕获段（索引访问可能为 undefined，判空后收窄）
+   */
+  const kind = matched[2];
+
+  /**
+   * 说明捕获段（禁含管道符；索引访问可能为 undefined，判空后收窄）
+   */
+  const note = matched[3];
+
+  /**
+   * 裁定段捕获文本（索引访问可能为 undefined，判空后收窄）
+   */
+  const rulingSegment = matched[4];
+  if (at === undefined || kind === undefined || note === undefined || rulingSegment === undefined) {
+    return null;
+  }
+
+  /**
+   * 裁定事实解析结果
+   */
+  const ruling = parseGateRuling(rulingSegment);
+  if (ruling === null) {
+    return null;
+  }
+  return { at, kind, note, ruling };
+}
+
+/**
+ * 家族引用（条目档 frontmatter 的 ref 字段值）
+ */
+export const WORKFLOW_REF_PATTERN = /^workflow:(global|[a-z0-9][a-z0-9-]*)\/([a-z0-9]+(?:-[a-z0-9]+)*)$/;

package/src/types/action-executor.ts

@@ -0,0 +1,64 @@
+/**
+ * action 执行器类型定义（W-3，Phase 2）
+ *
+ * 从 Zod Schema 推导类型，供 execution 子插件、action handler 实现、
+ * 工作流运行时与外部消费方共享类型契约。
+ */
+
+import type {
+  actionContextSchema,
+  actionResultSchema,
+  actionSchema,
+  actionTypeSchema,
+  feedApplyTagsActionSchema,
+  feedSummarizeActionSchema,
+  llmCompleteActionSchema,
+  webhookSendActionSchema,
+} from '../schemas';
+import type { z } from 'zod';
+
+/**
+ * action 类型枚举
+ */
+export type ActionType = z.infer<typeof actionTypeSchema>;
+
+/**
+ * feed.applyTags action 输入类型
+ */
+export type FeedApplyTagsAction = z.infer<typeof feedApplyTagsActionSchema>;
+
+/**
+ * feed.summarize action 输入类型
+ */
+export type FeedSummarizeAction = z.infer<typeof feedSummarizeActionSchema>;
+
+/**
+ * llm.complete action 输入类型
+ */
+export type LlmCompleteAction = z.infer<typeof llmCompleteActionSchema>;
+
+/**
+ * webhook.send action 输入类型
+ */
+export type WebhookSendAction = z.infer<typeof webhookSendActionSchema>;
+
+/**
+ * action 联合类型
+ *
+ * 所有内置 action 的联合类型，按 type 字段区分。
+ */
+export type Action = z.infer<typeof actionSchema>;
+
+/**
+ * action 执行上下文类型
+ *
+ * 工作流引擎在执行 action 节点时传入的上下文信息。
+ */
+export type ActionContext = z.infer<typeof actionContextSchema>;
+
+/**
+ * action 执行结果类型
+ *
+ * action handler 执行完成后返回的结果。
+ */
+export type ActionResult = z.infer<typeof actionResultSchema>;

package/src/types/api.ts

@@ -0,0 +1,10 @@
+/**
+ * 通用 API 响应类型已清理
+ *
+ * 历史上此文件导出 ApiResponse、PaginatedResponse、PaginationInfo、ApiError 等通用 API 类型，
+ * 但经核查无任何外部消费方（apps/web 与 packages/sdk 均使用 @longzai-intelligence-transport/http
+ * 提供的 ApiResponse，或在各自模块内本地定义 apiResponseSchema）。
+ *
+ * 为清理死代码，此文件内容已被清空，文件本身保留以维持包结构骨架。
+ */
+export {};

package/src/types/definition.ts

@@ -0,0 +1,49 @@
+export type DefinitionDTO = {
+  id: string;
+  name: string;
+  description: string | null;
+  version: number;
+  nodes: WorkflowNodeDTO[];
+  edges: WorkflowEdgeDTO[];
+  initialState: string;
+  states: string[];
+  publishedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type WorkflowNodeDTO = {
+  nodeId: string;
+  name: string;
+  type: string;
+  properties: Record<string, unknown>;
+  position: { x: number; y: number };
+};
+
+export type WorkflowEdgeDTO = {
+  edgeId: string;
+  sourceNodeId: string;
+  targetNodeId: string;
+  condition?: string;
+  label?: string;
+};
+
+export type CreateDefinitionInput = {
+  name: string;
+  description?: string;
+  nodes: WorkflowNodeDTO[];
+  edges: WorkflowEdgeDTO[];
+  initialState: string;
+  states: string[];
+  transitions: StateTransitionDTO[];
+};
+
+export type StateTransitionDTO = {
+  from: string;
+  to: string;
+  event: string;
+  guard?: string;
+  action?: string;
+};
+
+export type UpdateDefinitionInput = Partial<CreateDefinitionInput>;

package/src/types/feed-event-trigger.ts

@@ -0,0 +1,38 @@
+/**
+ * feed 事件触发器类型定义（W-2，Phase 2）
+ *
+ * 从 Zod Schema 推导类型，供 trigger 子插件、execution 子插件、
+ * 工作流运行时与外部消费方共享类型契约。
+ */
+
+import type {
+  feedEventFilterSchema,
+  feedEventNameSchema,
+  feedEventPayloadSchema,
+  feedEventTriggerSchema,
+} from '../schemas';
+import type { z } from 'zod';
+
+/**
+ * feed 事件名称类型
+ */
+export type FeedEventName = z.infer<typeof feedEventNameSchema>;
+
+/**
+ * feed 事件过滤条件类型
+ */
+export type FeedEventFilter = z.infer<typeof feedEventFilterSchema>;
+
+/**
+ * feed 事件触发器配置类型
+ *
+ * 工作流 trigger.type 为 'feed.event' 时的配置结构。
+ */
+export type FeedEventTrigger = z.infer<typeof feedEventTriggerSchema>;
+
+/**
+ * feed 事件 payload 类型
+ *
+ * feed 项目在事件触发时传递给工作流上下文的事件数据。
+ */
+export type FeedEventPayload = z.infer<typeof feedEventPayloadSchema>;

package/src/types/index.ts

@@ -0,0 +1,6 @@
+export * from './definition';
+export * from './instance';
+export * from './trigger';
+export * from './monitoring';
+export * from './feed-event-trigger';
+export * from './action-executor';

package/src/types/instance.ts

@@ -0,0 +1,49 @@
+export type InstanceDTO = {
+  id: string;
+  definitionId: string;
+  definitionVersion: number;
+  status: InstanceStatusDTO;
+  currentState: string;
+  previousState: string | null;
+  currentNodeId: string | null;
+  variables: Record<string, unknown>;
+  startedAt: string | null;
+  completedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type InstanceStatusDTO =
+  | 'pending'
+  | 'running'
+  | 'paused'
+  | 'completed'
+  | 'cancelled'
+  | 'failed';
+
+export type NodeExecutionDTO = {
+  id: string;
+  instanceId: string;
+  nodeId: string;
+  nodeName: string;
+  nodeType: string;
+  status: NodeExecutionStatusDTO;
+  startedAt: string | null;
+  completedAt: string | null;
+  error: string | null;
+  createdAt: string;
+};
+
+export type NodeExecutionStatusDTO = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+
+export type CreateInstanceInput = {
+  definitionId: string;
+  input?: Record<string, unknown>;
+};
+
+export type InstanceQueryParams = {
+  status?: InstanceStatusDTO;
+  definitionId?: string;
+  page?: number;
+  pageSize?: number;
+};

package/src/types/monitoring.ts

@@ -0,0 +1,54 @@
+export type AuditLogDTO = {
+  id: string;
+  instanceId: string;
+  nodeId: string | null;
+  action: string;
+  fromStatus: string | null;
+  toStatus: string;
+  operator: string | null;
+  detail: Record<string, unknown>;
+  createdAt: string;
+};
+
+export type AlertDTO = {
+  id: string;
+  definitionId: string;
+  type: AlertTypeDTO;
+  threshold: number;
+  notifyConfig: Record<string, unknown>;
+  enabled: boolean;
+  lastTriggeredAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type AlertTypeDTO = 'timeout' | 'failure_rate' | 'slow_execution';
+
+export type PerformanceMetricDTO = {
+  id: string;
+  definitionId: string;
+  metricType: MetricTypeDTO;
+  value: number;
+  period: string;
+  calculatedAt: string;
+};
+
+export type MetricTypeDTO =
+  | 'avg_duration'
+  | 'success_rate'
+  | 'failure_rate'
+  | 'timeout_rate'
+  | 'instance_count';
+
+export type MonitoringDashboardDTO = {
+  runningInstances: number;
+  successRate: number;
+  avgDuration: number;
+  failureAlerts: number;
+  trend: TrendPointDTO[];
+};
+
+export type TrendPointDTO = {
+  date: string;
+  value: number;
+};

package/src/types/trigger.ts

@@ -0,0 +1,39 @@
+/**
+ * 触发器对外暴露的传输结构
+ */
+export type TriggerDTO = {
+  id: string;
+  definitionId: string;
+  name: string;
+  type: TriggerTypeDTO;
+  config: Record<string, unknown>;
+  enabled: boolean;
+  lastTriggeredAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/**
+ * 触发器类型枚举
+ *
+ * - timer：定时触发
+ * - webhook：Webhook 触发
+ * - event：通用事件触发
+ * - feed.event：feed 事件触发（W-2，Phase 2）
+ */
+export type TriggerTypeDTO = 'timer' | 'webhook' | 'event' | 'feed.event';
+
+/**
+ * 创建触发器的入参
+ */
+export type CreateTriggerInput = {
+  definitionId: string;
+  name: string;
+  type: TriggerTypeDTO;
+  config: Record<string, unknown>;
+};
+
+/**
+ * 更新触发器的入参
+ */
+export type UpdateTriggerInput = Partial<CreateTriggerInput>;