# Pitfalls Research

**Domain:** Skill-based Workflow Orchestration (LLM Agent Pipeline)
**Researched:** 2026-03-13
**Confidence:** HIGH

---

## Critical Pitfalls

### Pitfall 1: Statelessness = Restart from Scratch

**What goes wrong:**
系统没有持久化状态，任何失败都需要从头重新执行整个流程。Whisper 识别了 20 分钟，后续步骤失败？重新识别。下载了 2GB 视频，分析失败？重新下载。

**Why it happens:**
开发者低估了多步骤流程的失败概率。假设每步都成功，或者认为"重新执行一次很快"。实际上，Whisper 识别可能需要 30 分钟，视频下载可能需要 10 分钟，重复执行成本极高。

**How to avoid:**
- 每个主要步骤完成后，将状态写入 `workflow_state.json`
- 状态包含：步骤名、输入参数、输出路径、完成时间戳
- 重新执行时，检查状态文件，跳过已完成的步骤
- 使用幂等设计：重复执行同一链接不会产生重复文件

**Warning signs:**
- 没有状态文件或状态文件只在流程结束时写入
- 重复执行同一任务产生重复输出文件
- 用户抱怨"又要重新跑一遍"

**Phase to address:**
Phase 1 (PIPE-02: 步骤级状态管理, PIPE-04: 幂等执行保证)

---

### Pitfall 2: Error Propagation Without Context

**What goes wrong:**
错误在步骤链中传播时丢失了上下文。步骤 6 失败时报告 "AI API 调用失败"，但不知道是哪个内容、哪个步骤、什么输入导致的。调试需要从头重现。

**Why it happens:**
错误处理只关注"失败了"，没有保留足够上下文。LLM 调用失败时只记录 "API error"，没有记录请求内容、模型参数、重试次数等。

**How to avoid:**
- 每个步骤输出结构化 JSON，包含 `success`、`error`、`context` 字段
- 错误消息必须包含：步骤名、输入摘要、失败原因、可操作建议
- 使用 correlation ID 追踪整个流程
- 区分可重试错误（超时、503）和不可重试错误（403、验证失败）

**Warning signs:**
- 错误消息只有 "Error" 或 "Failed"
- 需要问用户"你输入的是什么？"来调试
- 同样的错误重复出现但不知道根本原因

**Phase to address:**
Phase 1 (PIPE-05: 错误恢复策略, PIPE-07: Schema 验证机制)

---

### Pitfall 3: Assuming Model "Understands Context"

**What goes wrong:**
主代理期望子代理"理解"整个流程的上下文，但实际上每个子代理只看到自己步骤的输入。kb-deep-analyzer 不知道之前的 Whisper 识别质量如何，只能假设输入是可靠的。

**Why it happens:**
人类可以自然地维持上下文，开发者误以为 LLM 也能做到。但每次子代理调用都是独立的会话，没有跨步骤的"记忆"。

**How to avoid:**
- 显式传递所有需要的上下文，不要假设子代理"知道"
- 每个步骤的输入 JSON 必须包含该步骤需要的所有信息
- 使用结构化的输入格式（Schema），而不是自然语言描述
- 在状态文件中记录关键决策和上下文

**Warning signs:**
- 子代理行为不符合预期，"它应该知道..."
- 需要阅读多个文档才能理解一个步骤的输入要求
- 步骤之间的"隐式约定"没有文档化

**Phase to address:**
Phase 1 (PIPE-03: 统一 JSON Schema, PIPE-06: 清晰的流程定义)

---

### Pitfall 4: Parallel Chaos (Uncoordinated Parallel Execution)

**What goes wrong:**
多个子代理同时执行但没有协调机制。结果：文件被覆盖、状态不一致、资源竞争。例如：同时下载和 OCR 处理同一视频导致文件损坏。

**Why it happens:**
并行看起来更"高效"，开发者没有考虑共享资源（文件、状态、API 配额）的并发访问问题。

**How to avoid:**
- 对于这个项目：**串行执行**。每个步骤完成后才开始下一个
- 如果未来需要并行：使用文件锁、状态锁、或任务队列
- 明确定义哪些资源是共享的，哪些步骤可以并行

**Warning signs:**
- 偶发的"文件不存在"或"文件损坏"错误
- 状态文件内容不符合预期
- 同一时间大量 API 调用导致限流

**Phase to address:**
Phase 1 (设计文档中明确：串行执行模式)

---

### Pitfall 5: "Automating Bad Processes"

**What goes wrong:**
手动流程本身有问题（不清晰、有冗余、有错误），自动化只是让错误发生得更快。例如：元数据提取逻辑有 bug，自动化后每个视频都提取错误信息。

**Why it happens:**
急于自动化，没有先验证和优化手动流程。"先写代码再说"的心态。

**How to avoid:**
- 先手动执行完整流程一次，记录每一步
- 验证每个步骤的输出是否符合预期
- 修复流程问题后再自动化
- 每个步骤有明确的成功标准，不只是"没有报错"

**Warning signs:**
- 自动化后发现输出质量不如手动
- 需要频繁修改代码来"修复"流程
- 用户仍然需要手动检查和修正输出

**Phase to address:**
Phase 1 之前：手动验证流程 (PROJECT.md 中已验证的技能列表)

---

### Pitfall 6: Environment Variable Sprawl

**What goes wrong:**
环境变量分散在多个地方：`~/.kb_env`、子技能自己的配置、HF_TOKEN 在子章节、ZHIHU_COOKIE 在另一个文件。配置遗漏或冲突时，错误难以定位。

**Why it happens:**
每个技能独立开发，各自管理配置。没有统一的配置策略。

**How to avoid:**
- 所有环境变量集中在一个文件 (`~/.kb_env`)
- 工作流启动时检查所有必需变量，缺失则报错退出
- 文档中明确列出所有变量及其用途
- 可选变量有明确的默认值和回退策略

**Warning signs:**
- "在我的机器上能跑"问题
- 需要检查多个文件才能找到配置
- 同一变量在不同地方有不同值

**Phase to address:**
Phase 1 (环境变量检查已在 SKILL.md 中定义，需要统一执行)

---

### Pitfall 7: Graceful Degradation That Isn't

**What goes wrong:**
声称有"降级策略"，但实际上降级到无意义的内容。例如：深度分析失败时返回一个模板文本，看起来"成功"了但没有实际价值。

**Why it happens:**
开发者不想让流程"失败"，认为返回一些内容比报错好。但这掩盖了问题，用户得到的是无用的输出。

**How to avoid:**
- **关键步骤必须成功，否则整个流程失败** (PROJECT.md 已定义)
- 区分"必须有"和"最好有"的功能
- 失败时明确报告失败原因，不要假装成功
- 降级策略只用于非关键功能（如：OCR 失败时跳过图片分析）

**Warning signs:**
- 输出看起来"正常"但没有实际内容
- 用户发现分析报告是模板文本
- 成功率统计很高但用户不满意

**Phase to address:**
Phase 1 (SKILL.md 中的"严格失败处理原则"需要严格执行)

---

## Technical Debt Patterns

Shortcuts that seem reasonable but create long-term problems.

| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
|----------|-------------------|----------------|-----------------|
| 跳过 Schema 验证 | 快速开发，减少代码 | 后续调试困难，接口不兼容问题频发 | Never |
| 状态只在内存中 | 简单实现 | 无法恢复，每次失败重头开始 | 仅限一次性任务 |
| 硬编码路径 | 不用配置 | 迁移困难，环境差异问题 | Never |
| 自然语言描述步骤输入 | 灵活，文档友好 | LLM 理解不一致，调试困难 | 仅限人类阅读的文档 |
| 跳过错误处理 | 节省开发时间 | 生产环境频繁崩溃 | 仅限原型/POC |
| 不记录中间结果 | 节省存储 | 无法断点续传，无法审计 | 仅限幂等操作 |

---

## Integration Gotchas

Common mistakes when connecting to external services.

| Integration | Common Mistake | Correct Approach |
|-------------|----------------|------------------|
| B站 API | 没有处理 403/超时 | 实现重试机制，区分可重试和不可重试错误 |
| Whisper | 假设输出完美 | 后处理清理（数字格式、标点、分段） |
| AI API (GLM-5) | 单次调用失败即退出 | 指数退避重试 (1s → 2s → 4s → 8s) |
| HuggingFace | 没有 HF_TOKEN 仍尝试说话者分离 | 检测 token 存在，无则降级到普通识别 |
| 知乎 | Cookie 过期导致失败 | 明确错误消息，提示用户更新 Cookie |
| Git 归档 | 没有配置用户信息 | 检查 KB_GIT_USER/EMAIL，缺失则跳过 Git |

---

## Performance Traps

Patterns that work at small scale but fail as usage grows.

| Trap | Symptoms | Prevention | When It Breaks |
|------|----------|------------|----------------|
| 内存中累积所有中间结果 | 内存占用持续增长 | 每步完成后写入文件，释放内存 | 处理 1 小时以上视频 |
| 同步等待 Whisper 完成 | 用户长时间无反馈 | 定时汇报进度（每 2-3 分钟） | 超过 10 分钟的任务 |
| 单次下载整个视频 | 网络超时，下载失败 | 分块下载，支持断点续传 | 大于 500MB 的视频 |
| 无限制重试 | 无限循环，资源浪费 | 最大重试次数 + 总超时时间 | 任何外部服务调用 |

---

## Security Mistakes

Domain-specific security issues beyond general web security.

| Mistake | Risk | Prevention |
|---------|------|------------|
| API Key 硬编码 | 泄露到 Git 仓库 | 使用环境变量，.gitignore 排除配置文件 |
| Cookie 明文存储 | 账号被盗风险 | 提醒用户 Cookie 敏感性，不记录到日志 |
| 用户输入直接拼接到命令 | 命令注入 | 验证输入格式，使用参数化调用 |
| 日志记录敏感信息 | 信息泄露 | 过滤 API Key、Cookie 等敏感字段 |

---

## "Looks Done But Isn't" Checklist

Things that appear complete but are missing critical pieces.

- [ ] **State Management:** Often missing `workflow_state.json` — verify 状态文件在每个步骤后更新
- [ ] **Error Handling:** Often missing 可重试/不可重试区分 — verify 错误消息包含可操作建议
- [ ] **Schema Validation:** Often missing 输出验证 — verify 每个步骤输出符合定义的 Schema
- [ ] **Environment Check:** Often missing 启动前检查 — verify 工作流开始时验证所有必需变量
- [ ] **Success Criteria:** Often missing 明确标准 — verify 每个步骤有可验证的成功条件
- [ ] **Resume Capability:** Often missing 断点续传 — verify 中断后可以从最后完成步骤继续
- [ ] **Idempotency:** Often missing 幂等保证 — verify 重复执行不产生重复文件

---

## Recovery Strategies

When pitfalls occur despite prevention, how to recover.

| Pitfall | Recovery Cost | Recovery Steps |
|---------|---------------|----------------|
| 无状态导致重新执行 | HIGH | 1. 识别已完成的步骤（通过输出文件） 2. 手动创建状态文件 3. 从断点继续 |
| 错误上下文丢失 | MEDIUM | 1. 检查所有输出文件 2. 重新执行失败的步骤（带详细日志） 3. 对比成功和失败案例 |
| 配置分散导致问题 | LOW | 1. 创建统一的 ~/.kb_env 2. 迁移所有配置 3. 验证每个技能 |
| 并发问题 | MEDIUM | 1. 停止所有执行 2. 清理临时文件 3. 串行重新执行 |
| 降级处理不当 | LOW | 1. 删除无效输出 2. 修复根本问题 3. 重新执行 |

---

## Pitfall-to-Phase Mapping

How roadmap phases should address these pitfalls.

| Pitfall | Prevention Phase | Verification |
|---------|------------------|--------------|
| Statelessness = Restart from Scratch | Phase 1 (PIPE-02, PIPE-04) | 中断执行后可以从断点继续 |
| Error Propagation Without Context | Phase 1 (PIPE-05, PIPE-07) | 错误消息包含完整上下文和可操作建议 |
| Assuming Model "Understands Context" | Phase 1 (PIPE-03, PIPE-06) | 每个步骤输入 JSON 自包含所有需要信息 |
| Parallel Chaos | Phase 1 (设计文档) | 明确文档：串行执行，无并发 |
| "Automating Bad Processes" | Phase 0 (验证阶段) | 手动执行完整流程，验证每步输出 |
| Environment Variable Sprawl | Phase 1 (环境检查) | 启动时验证所有必需变量，缺失则报错 |
| Graceful Degradation That Isn't | Phase 1 (失败处理原则) | 关键步骤失败 = 整体失败，不假装成功 |

---

## Phase-Specific Warnings

| Phase Topic | Likely Pitfall | Mitigation |
|-------------|---------------|------------|
| 管道模型定义 | 步骤边界模糊 | 明确定义每个步骤的输入、输出、前置条件 |
| 状态管理实现 | 状态格式不一致 | 使用统一的 JSON Schema |
| Schema 设计 | 过于复杂或过于简单 | 从现有输出反推，迭代优化 |
| 幂等实现 | 判断"已存在"的逻辑有漏洞 | 使用内容哈希或唯一标识符 |
| 错误恢复 | 重试导致无限循环 | 设置最大重试次数和总超时 |
| 代码重构 | 破坏现有功能 | 先写测试，小步重构 |

---

## Sources

- [AI Agent Anti-Patterns: Architectural Pitfalls](https://achan2013.medium.com/ai-agent-anti-patterns-part-1-architectural-pitfalls-that-break-enterprise-agents-before-they-32d211dded43) - MEDIUM confidence
- [Demystifying Failures in Platform-Orchestrated Workflows](https://arxiv.org/html/2509.23735v2) - HIGH confidence
- [10 Reasons Multi-Agent Workflows Fail](https://www.infoq.com/presentations/multi-agent-workflow/) - MEDIUM confidence
- [How Tool Chaining Fails in Production LLM Agents](https://futureagi.substack.com/p/how-tool-chaining-fails-in-production) - MEDIUM confidence
- [Why Multi-Agent LLM Systems Fail](https://orq.ai/blog/why-do-multi-agent-llm-systems-fail) - MEDIUM confidence
- [Multi-Step LLM Chains: Best Practices](https://deepchecks.com/orchestrating-multi-step-llm-chains-best-practices/) - HIGH confidence
- [Data Pipeline State Management: An Underappreciated Challenge](https://www.fivetran.com/blog/data-pipeline-state-management-an-underappreciated-challenge) - HIGH confidence
- [9 Things I Hate About Environment Variables](https://prefab.cloud/blog/9-problems-with-env-vars/) - HIGH confidence
- [Mastering Retry Logic Agents: 2025 Best Practices](https://sparkco.ai/blog/mastering-retry-logic-agents-a-deep-dive-into-2025-best-practices) - MEDIUM confidence
- [Structured Handling of Exceptions in LLM-Driven Agentic Workflows](https://arxiv.org/pdf/2508.07935) - HIGH confidence
- [Subagent orchestration: The complete 2025 guide](https://www.eesel.ai/blog/subagent-orchestration) - MEDIUM confidence
- [How Idempotency Keeps Your API Out of Trouble](https://medium.com/@shreyagupta3011/how-idempotency-keeps-your-api-out-of-trouble-7f7848188d39) - HIGH confidence
- [AI Agent 工作流设计的5 个反模式](https://www.moltbook.com/post/f826b987-641d-4bb5-9938-b825ac5a6b13) - MEDIUM confidence
- [Workflow Process Automation Gone Wrong](https://www.flowwright.com/workflow-process-automation-gone-wrong-lessons-learned) - MEDIUM confidence

---
*Pitfalls research for: Skill-based Workflow Orchestration*
*Researched: 2026-03-13*