Hybrid LLM/Code Workflow Coordinator

由LLM驱动的工作流具有非确定性——即便是精心设计的prompt也可能产生不可预测的结果。对于某些任务（例如根据PR状态在Slack消息中添加表情符号），哪怕是偶尔出错也无法接受。但LLM工作流的原型开发速度快，且能在很多场景下良好运行。你需要兼顾两者：实验阶段的灵活性与关键场景下的确定性。

通过可配置的coordinator（协调器）参数同时支持LLM驱动和代码驱动的工作流。建议先使用LLM开展快速原型开发，当需要确定性执行能力时，再迁移至代码驱动方案。

协调器配置：

# LLM驱动（默认模式，迭代速度最快）
coordinator: llm

# 代码驱动（执行结果确定，需通过代码评审）
coordinator: script
coordinator_script: scripts/pr_merged.py

当设置coordinator: llm时：

• 处理器根据触发条件匹配对应配置
• 加载prompt、工具及虚拟文件
• 由LLM决策需要调用的工具
• 处理器依据LLM的响应结果协调工具调用流程

当设置coordinator: script时：

• 自定义Python脚本主导工作流的全流程控制
• 拥有与LLM模式完全一致的工具、触发数据和虚拟文件访问权限
• 仅在明确需求场景下，可通过subagent（子代理）工具调用LLM
• 需像其他软件代码一样通过代码评审环节

渐进式增强实施路径：

1. 从LLM模式起步 - 原型开发效率高，可覆盖多数业务场景
2. 观测失效场景 - 跟踪记录非确定性行为引发问题的具体环节
3. 重写为脚本 - 借助Claude Code一键将prompt直接转换为代码
4. 放心发布上线 - 代码经过评审验证，具备确定性执行特性

graph LR
    A[触发事件] --> B{协调器类型}
    B -->|llm| C[LLM 编排调度]
    B -->|script| D[脚本编排调度]
    C --> E[工具调用]
    D --> E
    D -.可选.-> F[子代理LLM]
    E --> G[输出结果]

    style C fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style D fill:#e8f5e9,stroke:#388e3c,stroke-width:2px

实现方案：

# 支持两种协调器的处理器
def execute_workflow(trigger, config):
    if config.get("coordinator") == "script":
        # 代码驱动：执行逻辑确定，需经过代码评审
        script = config["coordinator_script"]
        return run_python_script(script, trigger)
    else:
        # LLM驱动：灵活性强，迭代速度快
        prompt = load_prompt(config["prompt"])
        tools = load_tools(config["tools"])
        return llm_orchestrate(trigger, prompt, tools)

脚本与LLM具备同等能力：

# scripts/pr_merged.py
def handler(trigger, tools, virtual_files, subagent):
    # 拥有与LLM一致的工具集、触发数据和虚拟文件
    messages = tools.slack.get_messages(limit=10)

    pr_urls = extract_pr_urls(messages)
    statuses = [tools.github.get_status(url) for url in pr_urls]

    for msg, status in zip(messages, statuses):
        if status in ["merged", "closed"]:
            tools.slack.add_reacji(msg, "merged")

    # 必要时可按需选择性调用LLM
    # summary = subagent.summarize(statuses)

适用场景对比：

| 选择LLM驱动的场景 | 选择代码驱动的场景 | |----------------------------|----------------------------| | 新工作流原型开发 | 不允许出现任何错误 | | 业务逻辑可能频繁变更 | 要求执行逻辑完全确定 | | 可容忍偶发故障 | 工作流已进入稳定状态 | | 重视快速迭代效率 | 需要严格遵循代码评审流程 |

迁移路径：

1. 以coordinator: llm为配置完成原型开发
2. 部署上线并观察故障模式
3. 当故障影响业务时，向Claude Code发起请求：“将此工作流重写为脚本”
4. 更新配置为coordinator: script
5. 提交PR完成代码评审后，即可放心合并上线

优势：

• 兼顾两者优势：原型开发阶段借助LLM的灵活性，成熟阶段依托代码的确定性
• 迁移便捷：可一次性将prompt重写为脚本
• 能力一致：脚本可调用全部工具，还能通过subagent（子代理）调用LLM
• 代码评审：核心工作流可遵循标准评审流程
• 渐进式增强：无需从一开始就过度设计

劣势：

• 双代码路径：需同时维护LLM和脚本处理逻辑
• 重写成本：从LLM迁移到脚本需要投入时间成本
• 灵活性不足：脚本的修改难度高于prompt

不适用场景：

• 纯确定性任务（直接从一开始就使用代码即可）
• 高度探索性任务，这类场景始终需要依赖LLM