@longzai-intelligence-workflow/core 0.0.1 → 0.0.5

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

@@ -9,25 +9,31 @@ import {
   NODE_EXECUTION_STATUSES,
   NODE_TYPES,
   TRIGGER_TYPES,
-} from '../../constants/workflow';
+} from '@/constants/workflow';
 
 describe('DEFAULT_PAGE_SIZE', () => {
   it('默认分页大小为 20', () => {
-    // Arrange & Act & Assert
+    /*
+     * 断言 DEFAULT_PAGE_SIZE 的导出值为 20
+     */
     expect(DEFAULT_PAGE_SIZE).toBe(20);
   });
 });
 
 describe('MAX_PAGE_SIZE', () => {
   it('最大分页大小为 100', () => {
-    // Arrange & Act & Assert
+    /*
+     * 断言 MAX_PAGE_SIZE 的导出值为 100
+     */
     expect(MAX_PAGE_SIZE).toBe(100);
   });
 });
 
 describe('NODE_TYPES', () => {
   it('包含预期的节点类型', () => {
-    // Arrange
+    /*
+     * 列出全部预期节点类型的字面量清单
+     */
     const expectedTypes = [
       'StartEvent',
       'EndEvent',
@@ -40,90 +46,129 @@ describe('NODE_TYPES', () => {
       'TimerEvent',
       'ErrorEvent',
       'SignalEvent',
-    ];
+    ] as const;
 
-    // Act & Assert
+    /*
+     * 断言 NODE_TYPES 与清单逐项一致
+     */
     expect(NODE_TYPES).toEqual(expectedTypes);
   });
 
   it('包含 StartEvent', () => {
-    // Arrange & Act & Assert
+    /*
+     * 断言 NODE_TYPES 包含 StartEvent 成员
+     */
     expect(NODE_TYPES).toContain('StartEvent');
   });
 
   it('包含 EndEvent', () => {
-    // Arrange & Act & Assert
+    /*
+     * 断言 NODE_TYPES 包含 EndEvent 成员
+     */
     expect(NODE_TYPES).toContain('EndEvent');
   });
 
   it('为只读数组', () => {
-    // Arrange & Act & Assert
+    /*
+     * 断言 NODE_TYPES 本体是数组实例
+     */
     expect(Array.isArray(NODE_TYPES)).toBe(true);
   });
 });
 
 describe('INSTANCE_STATUSES', () => {
   it('包含预期的实例状态', () => {
-    // Arrange
-    const expectedStatuses = ['pending', 'running', 'paused', 'completed', 'cancelled', 'failed'];
-
-    // Act & Assert
+    /*
+     * 列出全部预期实例状态的字面量清单
+     */
+    const expectedStatuses = [
+      'pending',
+      'running',
+      'paused',
+      'completed',
+      'cancelled',
+      'failed',
+    ] as const;
+
+    /*
+     * 断言 INSTANCE_STATUSES 与清单逐项一致
+     */
     expect(INSTANCE_STATUSES).toEqual(expectedStatuses);
   });
 
   it('包含 pending 状态', () => {
-    // Arrange & Act & Assert
+    /*
+     * 断言 INSTANCE_STATUSES 包含 pending
+     */
     expect(INSTANCE_STATUSES).toContain('pending');
   });
 
   it('包含 failed 状态', () => {
-    // Arrange & Act & Assert
+    /*
+     * 断言 INSTANCE_STATUSES 包含 failed
+     */
     expect(INSTANCE_STATUSES).toContain('failed');
   });
 });
 
 describe('NODE_EXECUTION_STATUSES', () => {
   it('包含预期的节点执行状态', () => {
-    // Arrange
-    const expectedStatuses = ['pending', 'running', 'completed', 'failed', 'skipped'];
-
-    // Act & Assert
+    /*
+     * 列出全部预期节点执行状态的字面量清单
+     */
+    const expectedStatuses = ['pending', 'running', 'completed', 'failed', 'skipped'] as const;
+
+    /*
+     * 断言 NODE_EXECUTION_STATUSES 与清单逐项一致
+     */
     expect(NODE_EXECUTION_STATUSES).toEqual(expectedStatuses);
   });
 });
 
 describe('TRIGGER_TYPES', () => {
   it('包含预期的触发器类型', () => {
-    // Arrange
-    const expectedTypes = ['timer', 'webhook', 'event'];
-
-    // Act & Assert
+    /*
+     * 列出全部预期触发器类型的字面量清单
+     */
+    const expectedTypes = ['timer', 'webhook', 'event', 'feed.event'] as const;
+
+    /*
+     * 断言 TRIGGER_TYPES 与清单逐项一致
+     */
     expect(TRIGGER_TYPES).toEqual(expectedTypes);
   });
 });
 
 describe('ALERT_TYPES', () => {
   it('包含预期的告警类型', () => {
-    // Arrange
-    const expectedTypes = ['timeout', 'failure_rate', 'slow_execution'];
-
-    // Act & Assert
+    /*
+     * 列出全部预期告警类型的字面量清单
+     */
+    const expectedTypes = ['timeout', 'failure_rate', 'slow_execution'] as const;
+
+    /*
+     * 断言 ALERT_TYPES 与清单逐项一致
+     */
     expect(ALERT_TYPES).toEqual(expectedTypes);
   });
 });
 
 describe('METRIC_TYPES', () => {
   it('包含预期的指标类型', () => {
-    // Arrange
+    /*
+     * 列出全部预期指标类型的字面量清单
+     */
     const expectedTypes = [
       'avg_duration',
       'success_rate',
       'failure_rate',
       'timeout_rate',
       'instance_count',
-    ];
+    ] as const;
 
-    // Act & Assert
+    /*
+     * 断言 METRIC_TYPES 与清单逐项一致
+     */
     expect(METRIC_TYPES).toEqual(expectedTypes);
   });
 });

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

@@ -1,69 +1,99 @@
 import { describe, expect, it } from 'bun:test';
 
-import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from '../../constants/workflow';
-import { formatDate, getPagination, getTotalPages } from '../../utils/index';
+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
+    /*
+     * 不传参直接调用 getPagination 取得分页结果
+     */
     const result = getPagination();
 
-    // Assert
+    /*
+     * 断言默认偏移为 0 且条数取默认分页大小
+     */
     expect(result.offset).toBe(0);
     expect(result.limit).toBe(DEFAULT_PAGE_SIZE);
   });
 
   it('page=2, pageSize=10 返回 offset=10, limit=10', () => {
-    // Arrange & Act
+    /*
+     * 以第二页与每页十条的参数调用 getPagination
+     */
     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
+    /*
+     * 构造超出 MAX_PAGE_SIZE 的每页条数
+     */
     const oversizedPageSize = MAX_PAGE_SIZE + 50;
 
-    // Act
+    /*
+     * 将超限条数传入 getPagination
+     */
     const result = getPagination(1, oversizedPageSize);
 
-    // Assert
+    /*
+     * 断言条数被收口到 MAX_PAGE_SIZE
+     */
     expect(result.limit).toBe(MAX_PAGE_SIZE);
   });
 
   it('page=0 时默认为 page=1', () => {
-    // Arrange & Act
+    /*
+     * 以零页码调用 getPagination
+     */
     const result = getPagination(0, 10);
 
-    // Assert
+    /*
+     * 断言零页码被归位到首页偏移
+     */
     expect(result.offset).toBe(0);
     expect(result.limit).toBe(10);
   });
 
   it('page 为负数时默认为 page=1', () => {
-    // Arrange & Act
+    /*
+     * 以负数页码调用 getPagination
+     */
     const result = getPagination(-1, 10);
 
-    // Assert
+    /*
+     * 断言负页码同样回落到首页偏移
+     */
     expect(result.offset).toBe(0);
   });
 
   it('仅传入 page 时 pageSize 使用默认值', () => {
-    // Arrange & Act
+    /*
+     * 只传页码而省略每页条数调用 getPagination
+     */
     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
+    /*
+     * 页码缺省而只传每页条数调用 getPagination
+     */
     const result = getPagination(undefined, 15);
 
-    // Assert
+    /*
+     * 断言首页偏移为零且条数原样保留
+     */
     expect(result.offset).toBe(0);
     expect(result.limit).toBe(15);
   });
@@ -71,86 +101,128 @@ describe('getPagination', () => {
 
 describe('getTotalPages', () => {
   it('正确计算总页数', () => {
-    // Arrange
+    /*
+     * 准备总数 45 与每页 10 条的输入
+     */
     const total = 45;
     const pageSize = 10;
 
-    // Act
+    /*
+     * 用该输入计算总页数
+     */
     const result = getTotalPages(total, pageSize);
 
-    // Assert
+    /*
+     * 断言有余数时向上取整为 5 页
+     */
     expect(result).toBe(5);
   });
 
   it('总数恰好整除时返回精确页数', () => {
-    // Arrange
+    /*
+     * 准备总数 40 与每页 10 条的整除输入
+     */
     const total = 40;
     const pageSize = 10;
 
-    // Act
+    /*
+     * 用该输入计算总页数
+     */
     const result = getTotalPages(total, pageSize);
 
-    // Assert
+    /*
+     * 断言整除时返回精确的 4 页
+     */
     expect(result).toBe(4);
   });
 
   it('总数为 0 时返回 0', () => {
-    // Arrange
+    /*
+     * 准备总数为 0 的空集输入
+     */
     const total = 0;
     const pageSize = 10;
 
-    // Act
+    /*
+     * 用该输入计算总页数
+     */
     const result = getTotalPages(total, pageSize);
 
-    // Assert
+    /*
+     * 断言空集时总页数为 0
+     */
     expect(result).toBe(0);
   });
 
   it('总数为 1 时返回 1', () => {
-    // Arrange
+    /*
+     * 准备总数为 1 的单条输入
+     */
     const total = 1;
     const pageSize = 10;
 
-    // Act
+    /*
+     * 用该输入计算总页数
+     */
     const result = getTotalPages(total, pageSize);
 
-    // Assert
+    /*
+     * 断言单条数据占 1 页
+     */
     expect(result).toBe(1);
   });
 });
 
 describe('formatDate', () => {
   it('将 Date 对象转换为 ISO 字符串', () => {
-    // Arrange
+    /*
+     * 构造固定时刻的日期对象
+     */
     const date = new Date('2025-01-15T10:30:00.000Z');
 
-    // Act
+    /*
+     * 将日期对象交给 formatDate 转换
+     */
     const result = formatDate(date);
 
-    // Assert
+    /*
+     * 断言输出与输入的 ISO 表示逐字符一致
+     */
     expect(result).toBe('2025-01-15T10:30:00.000Z');
   });
 
   it('将日期字符串转换为 ISO 字符串', () => {
-    // Arrange
+    /*
+     * 准备纯日期字符串输入
+     */
     const dateStr = '2025-06-01';
 
-    // Act
+    /*
+     * 把字符串交给 formatDate 转换
+     */
     const result = formatDate(dateStr);
 
-    // Assert
+    /*
+     * 断言输出包含原日期且类型为字符串
+     */
     expect(result).toContain('2025-06-01');
     expect(typeof result).toBe('string');
   });
 
   it('返回值为有效的 ISO 格式', () => {
-    // Arrange
+    /*
+     * 取当前时刻构造日期对象
+     */
     const date = new Date();
 
-    // Act
+    /*
+     * 将当前日期交给 formatDate 转换
+     */
     const result = formatDate(date);
 
-    // Assert
+    /*
+     * 断言输出经日期还原后与自身一致
+     */
     expect(new Date(result).toISOString()).toBe(result);
   });
 });

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

@@ -3,8 +3,14 @@
  */
 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';
+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('工作项行：状态段执法', () => {
@@ -19,9 +25,13 @@ describe('声明方言四段制解析', () => {
   });
 
   test('裁定门行：裁定段四形态执法', () => {
-    expect(parseGateLine('t-013 | ruling | 载体指示待裁 | pending')?.ruling).toEqual({ status: 'pending' });
+    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({
+    expect(
+      parseGateLine('t-013 | ruling | 载体指示待裁 | approved:user:decisions/019.md')?.ruling,
+    ).toEqual({
       status: 'approved',
       decidedBy: 'user',
       evidence: 'decisions/019.md',
@@ -68,7 +78,10 @@ describe('视图派生（依赖门控与未决裁定）', () => {
     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']);
+    expect(view.pendingRulings.map((ruling) => ruling.key)).toEqual([
+      'b:ruling',
+      'workflow:ruling',
+    ]);
   });
 
   test('前置闭环解除阻塞；门批准解除门控；escalated 仍属未决', () => {

package/src/index.ts

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

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

@@ -6,6 +6,7 @@
  * 当工作流执行到 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
@@ -16,7 +17,7 @@
  * C1 合规：本端口为零框架依赖的纯类型契约，由具体适配器层提供实现。
  */
 
-import type { Action, ActionContext, ActionResult, ActionType } from '../types';
+import type { Action, ActionContext, ActionResult, ActionType } from '@/types';
 
 /**
  * 单个 action handler 函数签名

package/src/ports/feed-event.port.ts

@@ -8,7 +8,7 @@
  * C1 合规：本端口为零框架依赖的纯类型契约，由 feed 项目的实现层提供具体实现。
  */
 
-import type { FeedEventFilter, FeedEventName, FeedEventPayload } from '../types';
+import type { FeedEventFilter, FeedEventName, FeedEventPayload } from '@/types';
 
 /**
  * feed 事件订阅句柄

package/src/ports/index.ts

@@ -6,4 +6,5 @@
  */
 
 export * from './feed-event.port';
+
 export * from './action-executor.port';

package/src/schemas/action-executor.schema.ts

@@ -5,6 +5,7 @@
  * 供 execution 子插件注册 action handler 时使用。
  *
  * 支持的 action 类型：
+ *
  * - feed.applyTags：调用 feed F-2 applyTags，为条目打标签
  * - feed.summarize：调用 feed F-3 summarize，生成摘要
  * - llm.complete：调用 agent LlmCompletePort，完成文本
@@ -15,7 +16,7 @@
 
 import { z } from 'zod';
 
-import { ACTION_TYPES } from '../constants/workflow';
+import { ACTION_TYPES } from '@/constants/workflow';
 
 /**
  * action 类型 Schema

package/src/schemas/definition.schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { NODE_TYPES } from '../constants/workflow';
+import { NODE_TYPES } from '@/constants/workflow';
 
 export const workflowNodeDtoSchema = z.object({
   nodeId: z.string(),

package/src/schemas/feed-event-trigger.schema.ts

@@ -12,7 +12,7 @@
 
 import { z } from 'zod';
 
-import { FEED_EVENT_NAMES } from '../constants/workflow';
+import { FEED_EVENT_NAMES } from '@/constants/workflow';
 
 /**
  * feed 事件名称 Schema

package/src/schemas/index.ts

@@ -1,8 +1,15 @@
 export * from './definition.schema';
+
 export * from './workflow-doc.schema';
+
 export * from './instance.schema';
+
 export * from './trigger.schema';
+
 export * from './monitoring.schema';
+
 export * from './feed-event-trigger.schema';
+
 export * from './action-executor.schema';
+
 export * from './workflow-doc.schema';

package/src/schemas/instance.schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { INSTANCE_STATUSES, NODE_EXECUTION_STATUSES } from '../constants/workflow';
+import { INSTANCE_STATUSES, NODE_EXECUTION_STATUSES } from '@/constants/workflow';
 
 export const instanceStatusDtoSchema = z.enum(INSTANCE_STATUSES);
 

package/src/schemas/monitoring.schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { ALERT_TYPES, METRIC_TYPES } from '../constants/workflow';
+import { ALERT_TYPES, METRIC_TYPES } from '@/constants/workflow';
 
 export const alertTypeDtoSchema = z.enum(ALERT_TYPES);
 

package/src/schemas/trigger.schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { TRIGGER_TYPES } from '../constants/workflow';
+import { TRIGGER_TYPES } from '@/constants/workflow';
 
 export const triggerTypeDtoSchema = z.enum(TRIGGER_TYPES);
 

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

@@ -26,7 +26,8 @@ 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\\/. _-]+';
+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> | <标题> | <指针> | <状态>`（四段制）
@@ -362,4 +363,5 @@ export function parseGateLine(line: string): WorkflowGate | null {
 /**
  * 家族引用（条目档 frontmatter 的 ref 字段值）
  */
-export const WORKFLOW_REF_PATTERN = /^workflow:(global|[a-z0-9][a-z0-9-]*)\/([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+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

@@ -14,7 +14,7 @@ import type {
   feedSummarizeActionSchema,
   llmCompleteActionSchema,
   webhookSendActionSchema,
-} from '../schemas';
+} from '@/schemas';
 import type { z } from 'zod';
 
 /**