Lesson 0002 · 12–18 min

Quickstart 不是背命令：读懂第一个 Flue 项目会出现什么

今天只学一个技能：看到 Flue quickstart 的命令后，能预测每一步会创建什么、注册什么、运行什么。

目标：读懂安装路径不需要 API key练习：命令→结果配对

1. 为什么不是立刻跑命令？

Flue 官方 quickstart 确实很短：安装 runtime 和 CLI，运行 flue init，创建 agents/hello-world.ts，再用 flue run 执行一次 prompt。

但更重要的是：你要能说出每条命令改变了哪个层面：依赖、配置、agent 注册、运行时调用。否则跑通一次也很容易忘。

Primary source: Flue Getting Started。官方要求 Node.js >=22.19.0，并需要至少一个模型 provider 配置；Cloudflare 的 cloudflare/* 模型可走 Cloudflare 内置访问。

2. Quickstart 的三步地图

步骤你输入你应该预期发生什么
安装依赖npm install @flue/runtime
npm install --save-dev @flue/cli		项目获得运行时 API 与 CLI；还没有 agent，只是具备 Flue 能力。
初始化 targetnpx flue init --target node
或 --target cloudflare		生成 flue.config.ts 等目标运行时配置；告诉 Flue 以后如何启动应用。
创建 agent moduleagents/hello-world.ts 默认导出 defineAgent(...)文件名注册 agent 名称：hello-world；默认导出定义模型、instructions、能力。
运行一次npx flue run hello-world --input '{"message":"Tell me a joke."}'CLI 启动配置的 runtime，通过应用调用这个 agent，打印响应并退出。

3. 第一个 agent module：最小形状

先把官方例子读成一张 mental map：

// agents/hello-world.ts
import { defineAgent } from '@flue/runtime';

export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  instructions: 'Tell a funny "hello world" engineering joke.',
}));

agents/hello-world.ts

文件位置与文件名让 Flue 发现 agent；名字变成 hello-world。

defineAgent

声明 harness：模型是谁、instructions 是什么、将来有哪些 tools / skills / sandbox。

model

不是硬编码只能用 Anthropic；官方 quickstart 只是示例。模型 specifier 取决于 provider。

instructions

agent 的长期行为规则。后续复杂项目通常会抽到 markdown 文件中。

安全习惯：provider key 放在 .env，并把 .env 加入 .gitignore；不要把 API key 写进 lesson、代码仓库或聊天记录。

4. Node target vs Cloudflare target：先选哪个？

你现在学习阶段，我建议先理解 Node target，因为它最像本地 TypeScript 项目。等你理解 agent/workflow/sandbox 后，再切到 Cloudflare target 学 durable runtime 与 deployment。

目标适合学习时的风险
--target node本地实验、理解文件结构、接入本地工具。本地凭据和 local sandbox 要谨慎。
--target cloudflare部署 durable agent、Cloudflare Workers/DO 场景。概念更多：账号、绑定、部署、runtime 差异。

5. 练习：命令→结果配对

先遮住答案，自己说：

  1. npx flue init --target node 的产物主要是什么？
  2. 为什么 agents/hello-world.ts 会注册出 hello-world 这个 agent 名？
  3. flue run 是直接调模型 API，还是通过配置的应用 runtime 调用 agent？
查看参考答案
  1. 初始化 Flue 配置，例如 flue.config.ts，让项目知道目标 runtime。
  2. Flue 会发现 agent module，文件名成为 agent 名称；默认导出 defineAgent(...) 定义行为。
  3. 官方描述是启动配置的 Node.js 或 Cloudflare runtime，通过应用调用 agent，然后打印结果退出。

小测验

哪一项最准确描述 defineAgent 的作用？

再来一题

Quickstart 中，哪一步让 hello-world 成为可运行的 agent 名？

本课结束后你应该能说出

  • 安装依赖 ≠ 已经有 agent；只是项目具备 Flue runtime/CLI。
  • flue init 建立 target 配置；agent module 负责注册具体 agent。
  • defineAgent 是 harness 的声明入口。
  • flue run 通过配置 runtime 执行一次 agent 输入，而不是让你手写 raw LLM call。

下一课建议：0003 — Workflow 的最小代码：输入 schema、输出 schema、run 函数。这样你会同时掌握 Flue 的两个基本构建块。

如果你想真的在本地跑，我也可以下一轮生成一个“可复制命令 + 常见报错排查”的实操课。

← Lesson 0001Quickstart Cheatsheet →
↑