@longzai-intelligence-workflow/core 0.0.1

package/lzi-builder.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from '@longzai-intelligence-builder/esm';
+
+/**
+ * 核心包 tsdown 配置
+ *
+ * 包含核心类型定义、常量和 Zod schemas
+ */
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    schemas: 'src/schemas/index.ts',
+  },
+});

package/lzi-dev.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from '@longzai-intelligence-dev-tools/config';
+
+export default defineConfig({
+  clean: {
+    plugins: ['turbo', 'tsgo'],
+  },
+});

package/oxlint.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from '@longzai-intelligence-oxlint/presets/library';
+
+/**
+ * oxlint 代码检查配置
+ */
+export default defineConfig();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@longzai-intelligence-workflow/core",
+  "version": "0.0.1",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas.d.ts",
+      "import": "./dist/schemas.js"
+    }
+  },
+  "scripts": {
+    "build": "lzi-builder",
+    "build:prod": "NODE_ENV=production bun run build",
+    "prepublishOnly": "bun run build:prod",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "lzi-tsgo typecheck tsconfig/app.json",
+    "typecheck:node": "lzi-tsgo typecheck tsconfig/node.json",
+    "typecheck:test": "lzi-tsgo typecheck tsconfig/test.json",
+    "lint": "oxlint src && oxfmt --check src",
+    "lint:fix": "oxlint --fix src && oxfmt src",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "clean": "lzi-dev-cli clean"
+  },
+  "dependencies": {
+    "@longzai-intelligence-shared-kernel/core": "^0.1.4",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {}
+}

package/src/__tests__/helpers/setup.ts

@@ -0,0 +1,9 @@
+import { afterAll, afterEach, beforeAll } from 'bun:test';
+
+process.env.NODE_ENV ??= 'test';
+
+beforeAll(() => {});
+
+afterAll(() => {});
+
+afterEach(() => {});

package/src/__tests__/unit/constants.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  ALERT_TYPES,
+  DEFAULT_PAGE_SIZE,
+  INSTANCE_STATUSES,
+  MAX_PAGE_SIZE,
+  METRIC_TYPES,
+  NODE_EXECUTION_STATUSES,
+  NODE_TYPES,
+  TRIGGER_TYPES,
+} from '../../constants/workflow';
+
+describe('DEFAULT_PAGE_SIZE', () => {
+  it('默认分页大小为 20', () => {
+    // Arrange & Act & Assert
+    expect(DEFAULT_PAGE_SIZE).toBe(20);
+  });
+});
+
+describe('MAX_PAGE_SIZE', () => {
+  it('最大分页大小为 100', () => {
+    // Arrange & Act & Assert
+    expect(MAX_PAGE_SIZE).toBe(100);
+  });
+});
+
+describe('NODE_TYPES', () => {
+  it('包含预期的节点类型', () => {
+    // Arrange
+    const expectedTypes = [
+      'StartEvent',
+      'EndEvent',
+      'UserTask',
+      'ServiceTask',
+      'ExclusiveGateway',
+      'ParallelGateway',
+      'InclusiveGateway',
+      'SubProcess',
+      'TimerEvent',
+      'ErrorEvent',
+      'SignalEvent',
+    ];
+
+    // Act & Assert
+    expect(NODE_TYPES).toEqual(expectedTypes);
+  });
+
+  it('包含 StartEvent', () => {
+    // Arrange & Act & Assert
+    expect(NODE_TYPES).toContain('StartEvent');
+  });
+
+  it('包含 EndEvent', () => {
+    // Arrange & Act & Assert
+    expect(NODE_TYPES).toContain('EndEvent');
+  });
+
+  it('为只读数组', () => {
+    // Arrange & Act & Assert
+    expect(Array.isArray(NODE_TYPES)).toBe(true);
+  });
+});
+
+describe('INSTANCE_STATUSES', () => {
+  it('包含预期的实例状态', () => {
+    // Arrange
+    const expectedStatuses = ['pending', 'running', 'paused', 'completed', 'cancelled', 'failed'];
+
+    // Act & Assert
+    expect(INSTANCE_STATUSES).toEqual(expectedStatuses);
+  });
+
+  it('包含 pending 状态', () => {
+    // Arrange & Act & Assert
+    expect(INSTANCE_STATUSES).toContain('pending');
+  });
+
+  it('包含 failed 状态', () => {
+    // Arrange & Act & Assert
+    expect(INSTANCE_STATUSES).toContain('failed');
+  });
+});
+
+describe('NODE_EXECUTION_STATUSES', () => {
+  it('包含预期的节点执行状态', () => {
+    // Arrange
+    const expectedStatuses = ['pending', 'running', 'completed', 'failed', 'skipped'];
+
+    // Act & Assert
+    expect(NODE_EXECUTION_STATUSES).toEqual(expectedStatuses);
+  });
+});
+
+describe('TRIGGER_TYPES', () => {
+  it('包含预期的触发器类型', () => {
+    // Arrange
+    const expectedTypes = ['timer', 'webhook', 'event'];
+
+    // Act & Assert
+    expect(TRIGGER_TYPES).toEqual(expectedTypes);
+  });
+});
+
+describe('ALERT_TYPES', () => {
+  it('包含预期的告警类型', () => {
+    // Arrange
+    const expectedTypes = ['timeout', 'failure_rate', 'slow_execution'];
+
+    // Act & Assert
+    expect(ALERT_TYPES).toEqual(expectedTypes);
+  });
+});
+
+describe('METRIC_TYPES', () => {
+  it('包含预期的指标类型', () => {
+    // Arrange
+    const expectedTypes = [
+      'avg_duration',
+      'success_rate',
+      'failure_rate',
+      'timeout_rate',
+      'instance_count',
+    ];
+
+    // Act & Assert
+    expect(METRIC_TYPES).toEqual(expectedTypes);
+  });
+});

package/src/__tests__/unit/utils.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'bun:test';
+
+import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from '../../constants/workflow';
+import { formatDate, getPagination, getTotalPages } from '../../utils/index';
+
+describe('getPagination', () => {
+  it('默认参数返回 offset=0, limit=DEFAULT_PAGE_SIZE', () => {
+    // Arrange & Act
+    const result = getPagination();
+
+    // Assert
+    expect(result.offset).toBe(0);
+    expect(result.limit).toBe(DEFAULT_PAGE_SIZE);
+  });
+
+  it('page=2, pageSize=10 返回 offset=10, limit=10', () => {
+    // Arrange & Act
+    const result = getPagination(2, 10);
+
+    // Assert
+    expect(result.offset).toBe(10);
+    expect(result.limit).toBe(10);
+  });
+
+  it('pageSize 超过 MAX_PAGE_SIZE 时限制为 MAX_PAGE_SIZE', () => {
+    // Arrange
+    const oversizedPageSize = MAX_PAGE_SIZE + 50;
+
+    // Act
+    const result = getPagination(1, oversizedPageSize);
+
+    // Assert
+    expect(result.limit).toBe(MAX_PAGE_SIZE);
+  });
+
+  it('page=0 时默认为 page=1', () => {
+    // Arrange & Act
+    const result = getPagination(0, 10);
+
+    // Assert
+    expect(result.offset).toBe(0);
+    expect(result.limit).toBe(10);
+  });
+
+  it('page 为负数时默认为 page=1', () => {
+    // Arrange & Act
+    const result = getPagination(-1, 10);
+
+    // Assert
+    expect(result.offset).toBe(0);
+  });
+
+  it('仅传入 page 时 pageSize 使用默认值', () => {
+    // Arrange & Act
+    const result = getPagination(3);
+
+    // Assert
+    expect(result.offset).toBe((3 - 1) * DEFAULT_PAGE_SIZE);
+    expect(result.limit).toBe(DEFAULT_PAGE_SIZE);
+  });
+
+  it('仅传入 pageSize 时 page 默认为 1', () => {
+    // Arrange & Act
+    const result = getPagination(undefined, 15);
+
+    // Assert
+    expect(result.offset).toBe(0);
+    expect(result.limit).toBe(15);
+  });
+});
+
+describe('getTotalPages', () => {
+  it('正确计算总页数', () => {
+    // Arrange
+    const total = 45;
+    const pageSize = 10;
+
+    // Act
+    const result = getTotalPages(total, pageSize);
+
+    // Assert
+    expect(result).toBe(5);
+  });
+
+  it('总数恰好整除时返回精确页数', () => {
+    // Arrange
+    const total = 40;
+    const pageSize = 10;
+
+    // Act
+    const result = getTotalPages(total, pageSize);
+
+    // Assert
+    expect(result).toBe(4);
+  });
+
+  it('总数为 0 时返回 0', () => {
+    // Arrange
+    const total = 0;
+    const pageSize = 10;
+
+    // Act
+    const result = getTotalPages(total, pageSize);
+
+    // Assert
+    expect(result).toBe(0);
+  });
+
+  it('总数为 1 时返回 1', () => {
+    // Arrange
+    const total = 1;
+    const pageSize = 10;
+
+    // Act
+    const result = getTotalPages(total, pageSize);
+
+    // Assert
+    expect(result).toBe(1);
+  });
+});
+
+describe('formatDate', () => {
+  it('将 Date 对象转换为 ISO 字符串', () => {
+    // Arrange
+    const date = new Date('2025-01-15T10:30:00.000Z');
+
+    // Act
+    const result = formatDate(date);
+
+    // Assert
+    expect(result).toBe('2025-01-15T10:30:00.000Z');
+  });
+
+  it('将日期字符串转换为 ISO 字符串', () => {
+    // Arrange
+    const dateStr = '2025-06-01';
+
+    // Act
+    const result = formatDate(dateStr);
+
+    // Assert
+    expect(result).toContain('2025-06-01');
+    expect(typeof result).toBe('string');
+  });
+
+  it('返回值为有效的 ISO 格式', () => {
+    // Arrange
+    const date = new Date();
+
+    // Act
+    const result = formatDate(date);
+
+    // Assert
+    expect(new Date(result).toISOString()).toBe(result);
+  });
+});

package/src/__tests__/work-item-rules.test.ts

@@ -0,0 +1,90 @@
+/**
+ * 工作项判定核测试：四段制解析 + 转移表执法 + 视图派生
+ */
+import { describe, expect, test } from 'bun:test';
+
+import { parseGateLine, parseItemLine, type WorkflowEdge, type WorkflowGate, type WorkflowItem } from '../schemas/workflow-doc.schema';
+import { checkStatusTransition, deriveWorkflowView } from '../utils/work-item-rules.utils';
+
+describe('声明方言四段制解析', () => {
+  test('工作项行：状态段执法', () => {
+    expect(parseItemLine('t-011 | 生成器补全 | ref:demo/docs/tasks/a.md | todo')).toEqual({
+      id: 't-011',
+      title: '生成器补全',
+      ref: 'ref:demo/docs/tasks/a.md',
+      status: 'todo',
+    });
+    expect(parseItemLine('t-011 | 生成器补全 | ref:demo/docs/tasks/a.md')).toBeNull();
+    expect(parseItemLine('t-011 | 生成器补全 | ref:demo/docs/tasks/a.md | invalid')).toBeNull();
+  });
+
+  test('裁定门行：裁定段四形态执法', () => {
+    expect(parseGateLine('t-013 | ruling | 载体指示待裁 | pending')?.ruling).toEqual({ status: 'pending' });
+    expect(parseGateLine('workflow | ruling | TE 悬置 | pending')?.at).toBe('workflow');
+    expect(parseGateLine('t-013 | ruling | 载体指示待裁 | approved:user:decisions/019.md')?.ruling).toEqual({
+      status: 'approved',
+      decidedBy: 'user',
+      evidence: 'decisions/019.md',
+    });
+    expect(parseGateLine('t-013 | ruling | 载体指示待裁 | rejected:user')?.ruling).toEqual({
+      status: 'rejected',
+      decidedBy: 'user',
+    });
+    expect(parseGateLine('t-013 | ruling | 载体指示待裁 | approved')).toBeNull();
+  });
+});
+
+describe('状态转移表执法', () => {
+  test('合法/非法转移判定', () => {
+    expect(checkStatusTransition('todo', 'doing')).toBeNull();
+    expect(checkStatusTransition('doing', 'blocked')).toBeNull();
+    expect(checkStatusTransition('done', 'todo')).toBeNull();
+    const error = checkStatusTransition('todo', 'done');
+    expect(error?.code).toBe('INVALID_TRANSITION');
+    expect(error?.message).toContain('todo → done');
+  });
+});
+
+describe('视图派生（依赖门控与未决裁定）', () => {
+  /**
+   * 拓扑：a -> b（b 挂门）；c 独立；workflow 级门一枚
+   */
+  const items: readonly WorkflowItem[] = [
+    { id: 'a', title: '甲', ref: 'ref:demo/a.md', status: 'todo' },
+    { id: 'b', title: '乙', ref: 'ref:demo/b.md', status: 'todo' },
+    { id: 'c', title: '丙', ref: 'task:demo/c-item', status: 'doing' },
+  ];
+  const edges: readonly WorkflowEdge[] = [{ from: 'a', to: 'b' }];
+  const gates: readonly WorkflowGate[] = [
+    { at: 'b', kind: 'ruling', note: '乙项须裁定', ruling: { status: 'pending' } },
+    { at: 'workflow', kind: 'ruling', note: '工作流级悬置', ruling: { status: 'pending' } },
+  ];
+
+  test('依赖未满足派生阻塞；门未批不可启动；未决裁定含工作流级', () => {
+    const view = deriveWorkflowView(items, edges, gates);
+    const byId = new Map(view.items.map((entry) => [entry.id, entry]));
+
+    expect(byId.get('a')?.canStart).toBe(true);
+    expect(byId.get('b')?.blockedOnPrerequisite).toBe(true);
+    expect(byId.get('b')?.canStart).toBe(false);
+    expect(byId.get('c')?.canStart).toBe(false);
+    expect(view.pendingRulings.map((ruling) => ruling.key)).toEqual(['b:ruling', 'workflow:ruling']);
+  });
+
+  test('前置闭环解除阻塞；门批准解除门控；escalated 仍属未决', () => {
+    const settledItems: readonly WorkflowItem[] = [
+      { id: 'a', title: '甲', ref: 'ref:demo/a.md', status: 'done' },
+      { id: 'b', title: '乙', ref: 'ref:demo/b.md', status: 'todo' },
+    ];
+    const approvedGates: readonly WorkflowGate[] = [
+      { at: 'b', kind: 'ruling', note: '已裁', ruling: { status: 'approved', decidedBy: 'user' } },
+      { at: 'workflow', kind: 'ruling', note: '升级待裁', ruling: { status: 'escalated' } },
+    ];
+    const view = deriveWorkflowView(settledItems, edges, approvedGates);
+    const byId = new Map(view.items.map((entry) => [entry.id, entry]));
+
+    expect(byId.get('b')?.blockedOnPrerequisite).toBe(false);
+    expect(byId.get('b')?.canStart).toBe(true);
+    expect(view.pendingRulings.map((ruling) => ruling.rulingStatus)).toEqual(['escalated']);
+  });
+});

package/src/constants/index.ts

@@ -0,0 +1 @@
+export * from './workflow';

package/src/constants/workflow.ts

@@ -0,0 +1,114 @@
+/**
+ * 工作流节点类型枚举
+ */
+export const NODE_TYPES = [
+  'StartEvent',
+  'EndEvent',
+  'UserTask',
+  'ServiceTask',
+  'ExclusiveGateway',
+  'ParallelGateway',
+  'InclusiveGateway',
+  'SubProcess',
+  'TimerEvent',
+  'ErrorEvent',
+  'SignalEvent',
+] as const;
+
+/**
+ * 工作流实例状态枚举
+ */
+export const INSTANCE_STATUSES = [
+  'pending',
+  'running',
+  'paused',
+  'completed',
+  'cancelled',
+  'failed',
+] as const;
+
+/**
+ * 节点执行状态枚举
+ */
+export const NODE_EXECUTION_STATUSES = [
+  'pending',
+  'running',
+  'completed',
+  'failed',
+  'skipped',
+] as const;
+
+/**
+ * 触发器类型枚举
+ */
+export const TRIGGER_TYPES = ['timer', 'webhook', 'event', 'feed.event'] as const;
+
+/**
+ * feed 事件名称枚举（W-2，Phase 2）
+ *
+ * 用于 feed.event 触发器订阅 feed 项目暴露的事件总线。
+ */
+export const FEED_EVENT_NAMES = [
+  /**
+   * 新条目入库事件
+   */
+  'item.ingested',
+
+  /**
+   * 信息源抓取完成事件
+   */
+  'source.fetched',
+
+  /**
+   * 条目过滤事件
+   */
+  'item.filtered',
+
+  /**
+   * 行业识别事件
+   */
+  'industry.detected',
+] as const;
+
+/**
+ * 告警类型枚举
+ */
+export const ALERT_TYPES = ['timeout', 'failure_rate', 'slow_execution'] as const;
+
+/**
+ * 工作流内置 action 类型枚举（W-3，Phase 2）
+ *
+ * - feed.applyTags：调用 feed F-2 applyTags 为条目打标签
+ * - feed.summarize：调用 feed F-3 summarize 生成摘要
+ * - llm.complete：调用 agent LlmCompletePort 完成文本
+ * - webhook.send：调用 webhook 项目发送 webhook
+ *
+ * D-08 决策：不暴露 DSL 编辑 UI，action 通过自然语言编译的 DSL 执行。
+ */
+export const ACTION_TYPES = [
+  'feed.applyTags',
+  'feed.summarize',
+  'llm.complete',
+  'webhook.send',
+] as const;
+
+/**
+ * 监控指标类型枚举
+ */
+export const METRIC_TYPES = [
+  'avg_duration',
+  'success_rate',
+  'failure_rate',
+  'timeout_rate',
+  'instance_count',
+] as const;
+
+/**
+ * 分页查询默认每页条数
+ */
+export const DEFAULT_PAGE_SIZE = 20;
+
+/**
+ * 分页查询每页最大条数上限
+ */
+export const MAX_PAGE_SIZE = 100;

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 工作流核心包
+ *
+ * 提供共享基础类型、Schema、常量和工具函数。
+ * 不依赖任何 domain 包。
+ */
+// 类型导出
+export * from './types/index';
+// 常量导出
+export * from './constants/index';
+// 工具函数导出
+export * from './utils/index';
+// zod schema 导出
+export * from './schemas/index';
+// 端口契约导出（C1 合规，零框架依赖）
+export * from './ports/index';

package/src/ports/action-executor.port.ts

@@ -0,0 +1,73 @@
+/**
+ * action 执行器端口契约（W-3，Phase 2）
+ *
+ * 定义工作流内置 action 执行器的端口契约。
+ * execution 子插件通过此端口注册与调度 action handler，
+ * 当工作流执行到 action 节点时，根据 action.type 调用对应 handler。
+ *
+ * 支持的 action 类型：
+ * - feed.applyTags：调用 feed F-2 applyTags（Phase 2）
+ * - feed.summarize：调用 feed F-3 summarize（Phase 2）
+ * - llm.complete：调用 agent LlmCompletePort
+ * - webhook.send：调用 webhook 项目
+ *
+ * D-08 决策：不暴露 DSL 编辑 UI，action 通过自然语言编译的 DSL 执行。
+ *
+ * C1 合规：本端口为零框架依赖的纯类型契约，由具体适配器层提供实现。
+ */
+
+import type { Action, ActionContext, ActionResult, ActionType } from '../types';
+
+/**
+ * 单个 action handler 函数签名
+ *
+ * 注册到 ActionExecutorPort 中，按 action.type 路由调用。
+ *
+ * @param action - 待执行的 action（具体子类型由注册时的 actionType 决定）
+ * @param context - action 执行上下文
+ * @returns 执行结果
+ */
+export type ActionHandler = (action: Action, context: ActionContext) => Promise<ActionResult>;
+
+/**
+ * action 执行器端口
+ *
+ * 工作流引擎通过此端口调度内置 action。
+ * execution 子插件在初始化时注册各 actionType 的 handler，
+ * 工作流执行到 action 节点时调用 execute 方法。
+ */
+export type ActionExecutorPort = {
+  /**
+   * 执行指定 action
+   *
+   * 根据 action.type 路由到注册的 handler 执行。
+   * 未注册的 actionType 返回失败结果。
+   *
+   * @param action - 待执行的 action
+   * @param context - action 执行上下文
+   * @returns 执行结果
+   */
+  execute: (action: Action, context: ActionContext) => Promise<ActionResult>;
+
+  /**
+   * 注册 action handler
+   *
+   * 为指定 actionType 注册 handler，重复注册将覆盖旧 handler。
+   *
+   * @param actionType - action 类型
+   * @param handler - action 处理器
+   */
+  registerHandler: (actionType: ActionType, handler: ActionHandler) => void;
+
+  /**
+   * 检查 action 执行器是否可用
+   *
+   * @returns 端口是否可用
+   */
+  isAvailable: () => Promise<boolean>;
+};
+
+/**
+ * action 执行器端口 DI 令牌
+ */
+export const ACTION_EXECUTOR_PORT_TOKEN = Symbol('ACTION_EXECUTOR_PORT_TOKEN');