第 15 章 · 终章

Agent SDK 与动态工作流

把 AI 能力嵌入你的程序，编排大规模 AI 协作

当 AI 能被编程调度，软件开发的范式才真正改变

CLI 还不够

有些场景，你需要用代码精细控制 AI

想把它嵌进产品

你做一个开发者工具，想集成 Qoder 的 AI 能力，但 CLI 是给人用的，没有编程接口。

复杂编排做不到

"让 5 个 AI 专家并行评审，再让 1 个汇总，最后让第 7 个挑刺"——这种复杂编排，对话和脚本都很难表达。

想动态决策

根据上一步结果决定下一步做什么——这种条件分支、循环、并行的逻辑，需要真正的编程语言。

本章给出两个答案：① Agent SDK——用 TypeScript/Python 把 AI 能力嵌进你的程序；② 动态工作流——用 JavaScript 编排大规模 AI 协作。这是 Qoder CLI 能力栈的最顶层。

什么是 SDK

定义、白话、和 CLI 的关系

Agent SDK 是 Qoder 提供的编程库（TypeScript 和 Python 两个版本），让你在自己的代码里直接调用 AI 的能力——读文件、改代码、执行命令、委派子代理，全部通过 API 控制。

说白了，CLI 是给人用的遥控器，SDK 是给程序用的接口。同一个 AI 引擎，两种调用方式：你敲命令，或你的代码调函数。

CLI（命令行）

  • 给人用，交互式或 Print 模式
  • 配置驱动（文件、参数）
  • 适合开发者日常工作
  • 编排能力有限

SDK（编程库）

  • 给程序用，代码调用
  • 代码驱动，完全可编程
  • 适合构建 AI 产品/工具
  • 可表达任意复杂逻辑

SDK 用法

用几行代码唤起一个 AI 会话

TypeScript 示例——在你的程序里创建一个 AI agent，让它完成任务：

import { query } from "@qoder-ai/qoder-sdk";

// 用一行代码发起一个 AI 任务
const result = await query({
  prompt: "审查 src/ 目录的代码，找出潜在 bug",
  options: {
    permissionMode: "plan",       // 只读模式，安全
    outputFormat: "json",         // 结构化输出
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

console.log(result.text);  // 处理 AI 返回的结果
SDK 的威力：你拿到了 AI 的结果作为程序变量，可以继续处理——存数据库、发通知、传给下一个 AI、做条件判断。AI 成了你程序里的一个函数调用。

SDK 场景

什么时候该用 SDK 而不是 CLI

构建 AI 产品

做一个代码审查 SaaS、智能 commit 工具、自动化文档平台——把 AI 能力包装成你的产品。

定制工作流

有独特的研发流程，CLI 的配置不够灵活——用代码精确描述你的流程。

批量处理

遍历 100 个仓库做统一改造、分析 1000 个文件——代码循环比手动高效。

嵌入现有系统

把 AI 能力加进你的 CI 平台、IDE 插件、内部工具——SDK 是集成的基础。

别为了用 SDK 而用 SDK。如果你的需求 CLI + 脚本就能满足，没必要上 SDK。SDK 适合需要编程级控制力的场景——产品化、复杂逻辑、深度集成。

动态工作流

用 JavaScript 编排大规模 AI 协作

动态工作流是 Qoder 的高级编排能力：用 JavaScript 脚本描述多个 AI 如何协作——谁先做、谁后做、谁并行、谁汇总。它提供几个核心原语：

原语作用
agent()创建并调用一个 AI agent 执行任务
parallel()让多个 agent 同时执行
pipeline()让任务串行流水线式推进
phase()划分执行阶段
启用方式：动态工作流是高级功能，通常需要环境变量启用（如 CLAUDE_CODE_WORKFLOWS=1，Qoder 沿用类似机制），并通过特定关键字（如 ultracode）或 SDK 触发。具体开关以官方文档为准。

工作流示例

一个"多专家并行评审 + 汇总"的工作流

// 伪代码：展示工作流的编排思路
const reviews = await parallel([
  agent({ role: "security-auditor", task: "查安全问题" }),
  agent({ role: "perf-analyst",     task: "查性能问题" }),
  agent({ role: "code-reviewer",    task: "查代码质量" })
]);
// 三个专家并行跑，各自专注一面

const summary = await agent({
  role: "tech-lead",
  task: `汇总这三份评审，按优先级排序：${JSON.stringify(reviews)}`
});

return summary;
这段编排的含义：三个专家 AI同时从不同角度评审（并行省时），结果交给一个"技术负责人"AI 汇总排序。用代码精确描述了协作结构——这是对话和脚本都难以做到的。
运行约束：工作流有并发限制（如同时不超过 16 个 agent）、总量限制（如单次最多 1000 个）、以及一些确定性约束（如不使用 Date.now()，保证可复现）。具体数值以官方文档为准。

对抗式验证

工作流的高级用法——让 AI 互相挑刺

动态工作流最强大的模式之一是对抗式验证：让一个 AI 写代码，另一个 AI 专门挑刺，形成"红蓝对抗"。

图：对抗式验证工作流

实现者

写代码、修 bug、实现功能。

攻击者

专门找实现者的破绽——边界情况、安全漏洞、逻辑错误。

裁判

判断攻击是否成立，决定通过还是打回重做。

为什么有效：单个 AI 容易"自满"——写完就觉得没问题。对抗机制强制它接受审视，显著提升产出质量。这是 AI 协作的高级形态。

如何选择

CLI、SDK、工作流——三个层次各管一段

层次适合典型用户
CLI（含 Print 模式） 日常开发、CI 自动化、脚本任务 所有开发者
Agent SDK 构建 AI 产品、定制工作流、深度集成 工具/产品开发者
动态工作流 大规模 AI 协作、对抗验证、复杂编排 AI 工程师、高级用户
选择原则：从 CLI 开始——它覆盖 90% 的需求。当你需要"编程级控制"时上 SDK；当你需要"多 AI 复杂协作"时上工作流。不要跳级，每一层都建立在前一层的理解上。

排错指南

SDK 与工作流相关的高频问题

SDK 认证失败

原因：Token 未配置或失效。修复：设置 QODER_PERSONAL_ACCESS_TOKEN 环境变量；确认 Token 未过期。

工作流没触发

原因：未启用工作流功能。修复：设置启用环境变量；确认用的触发关键字正确；查官方文档当前启用方式。

并发超限

原因：同时调度的 agent 超过上限。修复：减少 parallel 的并发数；分批处理。

结果不确定（每次不同）

原因：用了非确定性函数（如时间）。修复：工作流内避免 Date.now() 等；需要确定性时固定随机种子。

课程总结

14 章走过的完整能力地图

起步篇（01-03）

认识 CLI、装好它、掌握五种输入模式——你能和 AI 对话了。

基础篇（04-05）

斜杠命令调度功能、AGENTS.md 让 AI 记住项目——AI 懂你的项目了。

扩展篇（06-10）

技能、子代理、MCP、钩子、插件——AI 变成一支专家团队。

控制篇（11-12）

权限系统、Quest 模式——你敢安全地把活交出去了。

工程化篇（13-14）

Print 模式、CI/CD、SDK、工作流——AI 进了你的流水线和产品。

这条路径的核心逻辑：从"和 AI 对话"，到"让 AI 记住"，到"扩展 AI 能力"，到"安全委派 AI"，最后到"编程调度 AI"。每一步都在扩大 AI 能为你做的事的边界。

下一步

学完之后，怎么继续提升

实践出真知

把 Qoder CLI 用到你的真实项目里。从一个小任务开始，逐步引入技能、子代理、Quest。理论懂了不算会，用过才是你的。

沉淀团队资产

把团队的规范、流程做成 AGENTS.md、技能、插件——把个人经验变成组织资产，这是最大的长期价值。

关注官方动态

Qoder 更新很快，新模型、新功能不断。订阅 更新日志，定期看新能力能不能优化你的工作流。

探索工程化

尝试把 AI 接进 CI、用 SDK 做个小工具、写个工作流——当你开始"造工具给别人用"，你才算真正掌握了它。

写在最后

AI 编程不是替代你，而是放大你

走到这里，你已经完整走过了 Qoder CLI 的能力栈。最后想和你分享一个观念：

AI 编程工具的真正价值，不在于"让 AI 替你写代码"，而在于放大你的判断力和创造力。你依然是那个决定做什么、判断对不对、把握方向的人——AI 让你从机械操作中解放，把精力留给真正需要思考的部分。

Qoder CLI 给了你一套完整的工具：对话、记忆、技能、团队、权限、委派、工程化。工具再强，关键在你怎么用。希望这门课能成为你 AI 编程之旅的一个扎实起点。

感谢你走到这里。祝你在 AI 编程的世界里，走得又快又稳。

—— 课程完 ——

延伸阅读

回顾本课程

官方资源与社区