15 KiB
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 - MEDIUM confidence
- Demystifying Failures in Platform-Orchestrated Workflows - HIGH confidence
- 10 Reasons Multi-Agent Workflows Fail - MEDIUM confidence
- How Tool Chaining Fails in Production LLM Agents - MEDIUM confidence
- Why Multi-Agent LLM Systems Fail - MEDIUM confidence
- Multi-Step LLM Chains: Best Practices - HIGH confidence
- Data Pipeline State Management: An Underappreciated Challenge - HIGH confidence
- 9 Things I Hate About Environment Variables - HIGH confidence
- Mastering Retry Logic Agents: 2025 Best Practices - MEDIUM confidence
- Structured Handling of Exceptions in LLM-Driven Agentic Workflows - HIGH confidence
- Subagent orchestration: The complete 2025 guide - MEDIUM confidence
- How Idempotency Keeps Your API Out of Trouble - HIGH confidence
- AI Agent 工作流设计的5 个反模式 - MEDIUM confidence
- Workflow Process Automation Gone Wrong - MEDIUM confidence
Pitfalls research for: Skill-based Workflow Orchestration Researched: 2026-03-13