npm package: @hjyue1/workflow-parser
Description: Text parser for converting structured text to workflow node data using AI and rule-based parsing
Latest version: 1.0.4-beta.16

# @hjyue1/workflow-parser

企业级工作流文本解析器，采用现代架构设计，支持 AI 和规则双模式解析。

## 🚀 核心特性

### 🎯 架构设计

- **策略模式** - 多场景解析策略灵活切换
- **工厂模式** - 统一解析器创建，支持扩展注册
- **单例模式** - PromptBuilder 性能优化，避免重复计算
- **依赖注入** - Logger 和 LLMProvider 可配置注入

### ⚡ 性能优化

- **智能缓存** - 系统消息缓存，提升响应速度
- **批量处理** - 智能并发控制，API限流保护
- **指数退避** - 网络重试策略，提高成功率
- **常量管理** - 配置集中化，消除运行时计算

### 🛡️ 安全可靠

- **类型安全** - 完整的 TypeScript + Zod 验证
- **错误处理** - 标准化错误消息和日志模板
- **降级策略** - AI 解析失败自动降级到规则解析
- **格式兼容** - 支持全角/半角分号分隔符

## 安装

```bash
pnpm install @hjyue1/workflow-parser
```

## 使用方式

### 基础用法

```typescript
import { TextToWorkflowParser, ParseScenario } from '@hjyue1/workflow-parser'

const parser = new TextToWorkflowParser({
  apiKey: 'your-qwen-api-key',
  temperature: 0.1,
  maxRetries: 3,
})

// 设置解析场景
parser.setScenario(ParseScenario.PreCondition)

// 解析单个文本
const workflow = await parser.parseText('要解析的文本')
console.log('解析结果:', workflow)
```

### 工厂模式用法

```typescript
import { parserFactory, ParseScenario } from '@hjyue1/workflow-parser'

// 创建特定场景的解析器
const executionParser = parserFactory.createParser(ParseScenario.ExecutionStep, {
  apiKey: 'your-api-key',
})

// 批量创建多个解析器
const parsers = parserFactory.createAllParsers({ apiKey: 'your-api-key' })

// 检查支持的场景
console.log('支持的场景:', parserFactory.getSupportedScenarios())
```

### 批量处理

```typescript
// 智能批量解析 - 自动并发控制和限流保护
const workflows = await parser.parseMultiple(['文本1', '文本2', '文本3'], 3)

// 指定场景的批量解析
const results = await parser.parseMultipleWithScenario(
  ['文本1', '文本2'],
  ParseScenario.ExpectedResult,
  2
)
```

### 安全解析

```typescript
// 带错误处理的安全解析
const result = await parser.safeParseText('文本内容')
if (result.success) {
  console.log('解析成功:', result.data)
} else {
  console.error('解析失败:', result.error)
}
```

## 解析场景

**PreCondition** - 前置条件

```
#帐号 uid:123 country:ID token:abc；#环境 dpath:test.com;#页面 url:app://page
```

**ExecutionStep** - 执行步骤

```
点击登录按钮；输入用户名;等待3秒；滑动到底部;点击确认
```

**ExpectedResult** - 期望结果

```
Fill in personal details页面打开正常;每个未填写信息的表单项都有红字提示用户输入
```

## 🏗️ 架构设计

### 核心架构

```
TextToWorkflowParser (策略模式)
├── ParserFactory (工厂模式)
│   ├── PreConditionParser
│   ├── ExecutionStepParser
│   └── ExpectedResultParser
├── PromptBuilder (单例模式)
└── Constants (配置管理)
```

### 设计模式应用

- **策略模式** - 多场景解析策略
- **工厂模式** - 统一解析器创建
- **单例模式** - PromptBuilder 实例管理
- **依赖注入** - Logger 和 LLMProvider 注入

## 📋 API 参考

### TextToWorkflowParser 类

```typescript
// 构造函数
new TextToWorkflowParser(config: ParserConfig | string)

// 场景管理
getCurrentScenario(): ParseScenario                                     // 获取当前场景
setScenario(scenario: ParseScenario): void                             // 设置解析场景
getSupportedScenarios(): ParseScenario[]                               // 获取支持的场景

// 解析方法
parseText(text: string): Promise<Workflow>                              // 解析单个文本
parseTextWithScenario(text: string, scenario: ParseScenario): Promise<Workflow> // 指定场景解析
parseMultiple(texts: string[], concurrency?: number): Promise<Workflow[]>       // 批量解析
parseMultipleWithScenario(texts: string[], scenario: ParseScenario, concurrency?: number): Promise<Workflow[]> // 指定场景批量解析
safeParseText(text: string): Promise<ParseResult<Workflow>>            // 安全解析（带错误处理）

// 实用方法
parseNodeType<T>(text: string, nodeType: string): Promise<T | null>    // 解析特定类型节点
validateWorkflow(workflow: unknown): boolean                           // 验证工作流结构
```

### ParserFactory 工厂

```typescript
// 实例获取
ParserFactory.getInstance(): ParserFactory                             // 获取工厂实例

// 创建方法
createParser(scenario: ParseScenario, config: ParserConfig, logger?: Logger, llmProvider?: ILLMProvider): BaseParser
createParsers(scenarios: ParseScenario[], config: ParserConfig): Map<ParseScenario, BaseParser>
createAllParsers(config: ParserConfig): Map<ParseScenario, BaseParser>

// 扩展支持
getSupportedScenarios(): ParseScenario[]                               // 获取支持的场景
isScenarioSupported(scenario: string): boolean                         // 检查场景支持
registerParser(scenario: ParseScenario, parserClass: ParserConstructor): void // 注册新解析器
```

## 配置

```typescript
interface ParserConfig {
  apiKey: string // 通义千问 API Key
  scenario?: ParseScenario // 默认解析场景
  maxRetries?: number // 重试次数，默认 3
  temperature?: number // AI 温度，默认 0.1
}
```

## 测试

```bash
pnpm test       # 运行测试
pnpm typecheck  # 类型检查
pnpm lint       # 代码检查
```

## 性能

- 系统消息缓存
- 智能批量处理 + 限流保护
- 文件代码行数从 535 → 181 (-66%)
- 模块化架构：1 → 14 个模块

## 数据结构

```typescript
interface Workflow {
  nodes: WorkflowNode[] // 解析出的节点数组
  parseMode: ParseMode // 解析模式 (ai | fallback)
  success: boolean // 解析是否成功
  message?: string // 解析消息（失败时包含错误信息）
}

enum ParseMode {
  AI = 'ai', // AI解析成功
  Fallback = 'fallback', // 降级到规则解析
}
```