# 工程师自动化工作流系统 - 故障诊断手册

> **版本**: v1.0.0  
> **更新日期**: 2026-05-21  
> **适用范围**: 生产环境

---

## 📖 使用说明

本手册按照**问题严重程度**和**排查难度**组织,每个问题包含:

- **症状描述**: 问题的外在表现
- **可能原因**: 导致问题的根本原因
- **诊断步骤**: 逐步排查方法
- **解决方案**: 具体的修复步骤
- **预防措施**: 避免问题再次发生的建议

---

## 🔴 严重问题 (Critical)

### C1: 工作流完全无法触发

#### 症状

- 输入`[工程师模式]`无任何反应
- 控制台无日志输出
- TodoList无变化

#### 可能原因

1. 环境变量未启用
2. 模块未正确加载
3. engine.ts集成失败
4. TypeScript编译错误

#### 诊断步骤

**Step 1: 检查环境变量**

```bash
# 检查.env.workflow文件
cat packages/engineer-dev/.env.workflow | grep ENABLE_AUTO_WORKFLOW

# 预期: ENABLE_AUTO_WORKFLOW=true
```

**如果为false或不存在**:
```bash
# 修复
echo "ENABLE_AUTO_WORKFLOW=true" >> packages/engineer-dev/.env.workflow
```

**Step 2: 检查模块加载**

```bash
# 查看启动日志
grep "engineer-mode" logs/startup.log

# 预期: 看到模块加载成功日志
```

**如果未加载**:
```bash
# 检查index.ts导出
grep -A 5 "export.*WorkflowOrchestrator" packages/engineer-dev/src/engineer-mode/index.ts
```

**Step 3: 检查engine.ts集成**

```bash
# 搜索关键代码
grep -n "startAutomatedWorkflow" apps/electron/src/main/agent/engine.ts
grep -n "detectComplexTask" apps/electron/src/main/agent/engine.ts

# 预期: 应该找到相关代码行
```

**Step 4: 检查编译错误**

```bash
cd packages/engineer-dev
bun run typecheck

# 预期: 无编译错误
```

#### 解决方案

```bash
# 1. 设置环境变量
export ENABLE_AUTO_WORKFLOW=true

# 2. 重新编译
bun run build

# 3. 重启应用
./启动桌面版.bat

# 4. 验证
# 输入: [工程师模式] 测试
```

#### 预防措施

- 在`.env.example`中添加示例配置
- CI/CD中增加环境变量检查
- 添加启动时的模块健康检查

---

### C2: 计划生成失败

#### 症状

- 检测到工程师模式
- 但TodoList无计划显示
- 日志显示`计划生成失败`

#### 可能原因

1. generate-plan-tool未注册
2. 需求描述为空
3. 工具执行异常
4. LLM响应格式错误

#### 诊断步骤

**Step 1: 检查工具注册**

```bash
# 查看工具列表
grep -n "generatePlanTool" packages/engineer-dev/src/engineer-mode/index.ts

# 预期: 应该导出generatePlanTool
```

**Step 2: 检查需求参数**

```bash
# 查看日志中的需求参数
grep "requirement:" logs/workflow.log

# 预期: 应该有具体的需求文本
```

**Step 3: 查看工具执行日志**

```bash
# 搜索错误日志
grep "generate_plan.*ERROR" logs/workflow.log

# 分析具体错误信息
```

#### 解决方案

```typescript
// 临时调试: 在generate-plan-tool.ts中添加日志
console.log('[GeneratePlanTool] 需求:', args.requirement)
console.log('[GeneratePlanTool] 开始生成计划...')

// 检查LLM响应
try {
  const result = await llm.generatePlan(requirement)
  console.log('[GeneratePlanTool] LLM响应:', result)
} catch (error) {
  console.error('[GeneratePlanTool] LLM调用失败:', error)
}
```

#### 预防措施

- 增加需求非空校验
- 添加LLM响应格式验证
- 实现重试机制(最多3次)

---

### C3: 任务执行卡死

#### 症状

- 某个任务一直显示🔵 in_progress
- 超过预计时间2倍以上
- 无进度更新

#### 可能原因

1. 工具执行超时
2. 死循环
3. 外部依赖无响应
4. 资源耗尽(内存/CPU)

#### 诊断步骤

**Step 1: 查看任务详情**

```typescript
// 在控制台执行
const controller = getActiveWorkflow().controller
const currentTask = controller.context.currentTaskId

console.log('当前任务:', currentTask)
console.log('开始时间:', task.startedAt)
console.log('预计时间:', task.estimatedMinutes)
console.log('已耗时:', Date.now() - task.startedAt)
```

**Step 2: 检查工具执行状态**

```bash
# 查看工具执行日志
grep "executeTool.*$currentTask" logs/workflow.log | tail -20
```

**Step 3: 检查系统资源**

```bash
# Windows
tasklist | findstr "node"

# 查看内存使用
# 预期: <500MB
```

#### 解决方案

```typescript
// 1. 强制停止任务
controller.pauseExecution()

// 2. 标记任务失败
await controller.completeTask(currentTask, {
  success: false,
  errors: ['执行超时(>10min)']
})

// 3. 继续下一个任务
await controller.executeNext()
```

#### 预防措施

- 添加超时控制(默认10分钟)
- 实现任务心跳检测
- 设置最大重试次数

---

## 🟠 警告问题 (Warning)

### W1: 质量校验频繁失败

#### 症状

- 多个任务被标记🔴 blocked
- 质量通过率<80%
- 日志显示`质量校验失败`

#### 可能原因

1. 验收标准过于严格
2. 工具输出不符合预期
3. 安全检查规则误判
4. LLM输出质量问题

#### 诊断步骤

**Step 1: 查看质量校验报告**

```bash
# 查看失败详情
grep "质量校验失败" logs/workflow.log | tail -5

# 查看具体失败的检查项
grep "qualityCheck.*failed" logs/workflow.log
```

**Step 2: 分析失败模式**

```typescript
// 统计各类失败次数
const failures = {
  '输出完整性': 0,
  '错误检查': 0,
  '验收标准': 0,
  '代码质量': 0,
  '安全检查': 0
}

// 分析主要失败原因
```

**Step 3: 检查验收标准**

```bash
# 查看生成的验收标准
grep "acceptanceCriteria" logs/plans.log

# 评估是否过于严格
```

#### 解决方案

**方案1: 调整验收标准**

```typescript
// 降低验收标准严格度
const acceptanceCriteria = [
  '代码能编译通过',        // 原来是"零编译错误"
  '核心功能实现',          // 原来是"100%功能完整"
  '无严重安全漏洞'         // 原来是"零安全警告"
]
```

**方案2: 添加宽容模式**

```typescript
// 允许部分失败
if (passedChecks >= 0.8) {  // 80%通过即可
  return { passed: true }
}
```

#### 预防措施

- 根据历史数据动态调整标准
- 实现分级验收(strict/normal/loose)
- 提供失败原因详细分析

---

### W2: 性能指标下降

#### 症状

- 工作流耗时显著增加
- 成功率下降
- 内存占用增长

#### 诊断步骤

**Step 1: 查看性能趋势**

```typescript
const stats = perfMonitor.getHistoricalStats()
console.log('平均耗时:', stats.avgDuration, 'ms')
console.log('成功率:', stats.avgSuccessRate * 100, '%')
```

**Step 2: 对比历史数据**

```bash
# 查看性能报告
cat logs/performance-report-*.json

# 对比本周vs上周
```

**Step 3: 定位瓶颈**

```typescript
// 分析各阶段耗时
const breakdown = {
  modeDetection: 2ms,      // 正常<10ms
  planGeneration: 500ms,   // 正常<500ms
  taskExecution: 8000ms,   // 异常(应该<3000ms)
  qualityCheck: 200ms      // 正常<200ms
}
```

#### 解决方案

**针对taskExecution慢**:

```typescript
// 1. 拆分复杂任务
if (task.estimatedMinutes > 60) {
  // 拆分为多个子任务
  const subtasks = splitTask(task)
}

// 2. 增加缓存
const cache = new Map()
function executeTask(task) {
  if (cache.has(task.id)) {
    return cache.get(task.id)
  }
  // ...
}

// 3. 并发控制
const MAX_CONCURRENT = 3
```

#### 预防措施

- 设置性能基线,自动告警
- 定期清理缓存(>60min)
- 监控内存泄漏

---

### W3: TodoWrite同步延迟

#### 症状

- TodoList更新不及时
- 进度显示不准确
- 前端状态与后端不一致

#### 诊断步骤

**Step 1: 检查同步日志**

```bash
grep "syncToTodoWrite" logs/workflow.log | tail -10
```

**Step 2: 测量同步耗时**

```typescript
const start = Date.now()
await controller.syncToTodoWrite()
const duration = Date.now() - start
console.log('同步耗时:', duration, 'ms')

// 预期: <100ms
```

#### 解决方案

```typescript
// 优化: 批量同步而非每次任务都同步
let syncCounter = 0
async function syncToTodoWrite() {
  syncCounter++
  
  // 每3个任务同步一次
  if (syncCounter % 3 !== 0) {
    return
  }
  
  // 执行同步
  await this.toolExecuteCallback('todo_write', {
    action: 'set',
    todos: this.mapTasksToTodos()
  })
}
```

#### 预防措施

- 实现智能同步策略
- 添加同步失败重试
- 前端增加轮询兜底

---

## 🟡 轻微问题 (Info)

### I1: 触发规则误判

#### 症状

- 普通对话触发工程师模式
- 置信度较低但仍然触发

#### 诊断步骤

```bash
# 查看触发日志
grep "Engineer mode detected" logs/workflow.log | tail -5

# 检查置信度
# 如果<0.7可能是误判
```

#### 解决方案

```typescript
// 提高触发阈值
if (result.confidence < 0.8) {  // 从0.6提高到0.8
  console.log('[EngineerMode] 置信度较低,不触发')
  return
}
```

---

### I2: 缓存命中率低

#### 症状

- 相同输入重复检测
- 性能略低于预期

#### 诊断步骤

```typescript
const cacheStats = detector.getCacheStats()
console.log('命中率:', cacheStats.hitRate)

// 预期: >70%
```

#### 解决方案

```typescript
// 增加缓存容量
const MAX_CACHE_SIZE = 500  // 从100增加到500

// 优化缓存key
function getCacheKey(input: string): string {
  // 归一化处理
  return input.toLowerCase().trim()
}
```

---

## 🔍 高级诊断工具

### 诊断脚本1: 完整系统检查

```bash
#!/bin/bash
# system-diagnosis.sh

echo "=== 工程师自动化工作流系统诊断 ==="

echo ""
echo "1. 检查环境变量..."
grep "ENABLE_AUTO_WORKFLOW" packages/engineer-dev/.env.workflow

echo ""
echo "2. 检查模块加载..."
grep "engineer-mode" logs/startup.log | tail -3

echo ""
echo "3. 检查工具注册..."
grep "generate_plan" logs/startup.log

echo ""
echo "4. 检查最近的工作流..."
grep "Starting automated workflow" logs/workflow.log | tail -5

echo ""
echo "5. 检查错误..."
grep "ERROR" logs/workflow.log | tail -10

echo ""
echo "6. 性能统计..."
grep "Performance Report" logs/workflow.log | tail -1

echo ""
echo "=== 诊断完成 ==="
```

### 诊断脚本2: 性能分析

```typescript
// performance-analysis.ts

import { perfMonitor } from '@twork/engineer-dev/engineer-mode'

// 获取最近10个工作流
const workflows = perfMonitor.getRecentWorkflows(10)

// 分析趋势
const avgDuration = workflows.reduce((sum, w) => sum + w.duration, 0) / workflows.length
const successRate = workflows.filter(w => w.success).length / workflows.length

console.log('平均耗时:', avgDuration.toFixed(2), 'ms')
console.log('成功率:', (successRate * 100).toFixed(1), '%')

// 识别异常
const slowWorkflows = workflows.filter(w => w.duration > avgDuration * 2)
if (slowWorkflows.length > 0) {
  console.log('⚠️ 发现', slowWorkflows.length, '个异常慢的工作流')
  slowWorkflows.forEach(w => {
    console.log(`  - ${w.workflowId}: ${w.duration}ms`)
  })
}
```

---

## 📞 获取帮助

### 自助排查

1. 查阅本手册对应问题
2. 运行诊断脚本
3. 查看日志文件
4. 检查配置

### 提交Issue

如果问题仍未解决,请提交GitHub Issue并包含:

```markdown
## 问题描述
[详细描述问题现象]

## 复现步骤
1. [步骤1]
2. [步骤2]
3. [步骤3]

## 预期行为
[应该发生什么]

## 实际行为
[实际发生了什么]

## 环境信息
- TWork版本: [version]
- Node版本: [version]
- 操作系统: [OS]

## 日志
[附加相关日志]

## 已尝试的解决方案
1. [方案1] - 结果: [成功/失败]
2. [方案2] - 结果: [成功/失败]
```

---

## 📋 常见问题FAQ

### Q1: 如何禁用自动化工作流?

**A**: 设置环境变量:
```bash
export ENABLE_AUTO_WORKFLOW=false
```

### Q2: 如何查看工作流历史?

**A**: 查看日志文件:
```bash
grep "workflow" logs/workflow-execution.log
```

### Q3: 如何自定义触发规则?

**A**: 编辑关键词库:
```typescript
// engineer-mode-detector.ts
const explicitCommands = [
  '[工程师模式]',
  '[专家模式]',
  // 添加自定义关键词
]
```

### Q4: 如何调整质量校验标准?

**A**: 修改安全检查器:
```typescript
// security-checker.ts
const dangerousPatterns = [
  // 调整或添加规则
]
```

---

**手册版本**: v1.0.0  
**最后更新**: 2026-05-21  
**下次审查**: 2026-06-01
