📚 编程进阶教程站

第 2 章 · 项目搭建与开发流程 ​

本章目标：从零初始化一个 Flue 项目，理解目录约定，跑通"本地运行"与"开发服务器"两条路径。

2.1 环境准备与安装 ​

Flue 要求 Node.js ≥ 22.19.0，并复用 Pi 的全部 Provider 支持——你只需要对应 Provider 的 API Key：

bash
# 检查 Node 版本（必须 >= 22.19.0）
node --version

# 新建项目目录并初始化
mkdir my-flue-project && cd my-flue-project
npm init -y

# 安装运行时与 CLI
npm install @flue/runtime @flue/cli

用 .env 管理 API Key（切勿提交到 git）：

bash
# .env —— Flue 运行时自动加载
ANTHROPIC_API_KEY="sk-ant-xxx"
OPENAI_API_KEY="sk-xxx"

2.2 项目配置文件 ​

在项目根目录创建 flue.config.ts，声明构建目标：

typescript
// flue.config.ts —— target 决定 Flue 为哪个平台生成代码
import { defineConfig } from '@flue/runtime/config';

export default defineConfig({
  target: 'node', // 'node' 或 'cloudflare'
});

如果要把 agent 部署为 HTTP 服务，还需要 Vite 插件和 Hono 服务器框架：

bash
npm install @flue/vite hono vite
typescript
// vite.config.ts —— flue() 插件负责扫描 'use agent' 文件
import { flue } from '@flue/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [flue()],
});

只打包用到的 Provider

flue({ providers: ['anthropic', 'openai'] }) 可以把内置 Provider 收窄到白名单， 未列出的 Provider 的 SDK 完全不进产物——对 Cloudflare 部署的包体积尤其重要。

2.3 目录结构约定 ​

单 Agent 项目的推荐布局：

text
my-project/
├─ src/                  # 源码目录（推荐）
│  ├─ app.ts             # 服务器路由入口（部署时必需）
│  ├─ db.ts              # 数据库配置（可选）
│  ├─ agents/            # agent 定义
│  ├─ skills/            # 技能目录（SKILL.md）
│  ├─ tools/             # 工具目录
│  ├─ subagents/         # 子代理定义
│  └─ channels/          # 事件通道（Slack/GitHub 等）
├─ package.json
├─ vite.config.ts        # 可选
└─ flue.config.ts        # 可选

源码目录的选择顺序是 .flue/ → src/ → 项目根。Flue 不会合并多种布局：只要 .flue/ 存在，所有入口都从它解析。大型项目还可以按 agent 分子目录，每个 agent 自带 skills/tools/subagents。

2.4 第一个可运行的 Agent ​

创建 src/agents/assistant.ts：

typescript
// src/agents/assistant.ts
'use agent'; // 必须位于文件顶部、任何 import 之前
import { useModel } from '@flue/runtime';

export function Assistant() {
  // 声明驱动本 agent 的模型
  useModel('anthropic/claude-haiku-4-5');
  // 返回值 = 系统指令
  return 'You are a helpful assistant. Keep replies short.';
}

路径 A：CLI 本地运行 ​

最快验证方式——不起服务器，直接对话：

bash
# 单轮对话
npx flue run src/agents/assistant.ts --message "Say hello in five words or fewer."

# 带 --id 的多轮对话：同一 ID 的消息共享上下文
npx flue run src/agents/assistant.ts --id hello-1 --message "What's a good name for a pet crab?"
npx flue run src/agents/assistant.ts --id hello-1 --message "Give me three more."
# 第二条消息能接上第一条的话题——会话按 ID 持久化

路径 B：Vite 开发服务器 ​

先写路由入口 src/app.ts（Hono 应用）：

typescript
// src/app.ts —— Flue 应用的固定入口文件
import { createAgentRouter } from '@flue/runtime/routing';
import { Hono } from 'hono';
import { Assistant } from './agents/assistant.ts';

const app = new Hono();
// 把 agent 挂到 /agents/assistant 路由
app.route('/agents/assistant', createAgentRouter(Assistant));
export default app;

启动开发服务器并用 curl 发一条消息：

bash
npx vite dev   # 默认监听 http://localhost:5173

# 发消息：POST /agents/assistant/{id}，202 表示已受理
curl -X POST http://localhost:5173/agents/assistant/hello-1 \
  -H 'content-type: application/json' \
  -d '{"text": "你好"}'

createAgentRouter() 自动生成一组标准路由：POST /:id（发消息）、GET /:id（取会话）、POST /:id/abort(中止) 等。

本章小结 ​

  • 安装 @flue/runtime + @flue/cli；部署再加 @flue/vite + hono + vite；
  • flue.config.ts 声明 target；providers 白名单可收窄打包体积；
  • 源码目录顺序 .flue/ → src/ → 根，互斥不合并；
  • 两条运行路径：CLI 直跑（适合调试与 CI）、vite dev + Hono 路由（适合做服务）；
  • 会话按 agent ID 持久化，同 ID 多轮自动共享上下文。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Flue 要求的最低 Node.js 版本是？

2. 'use agent' 指令应该放在什么位置？

3. 当项目中同时存在 .flue/ 与 src/ 目录时，Flue 如何选择源码目录？

4. npx flue run 的 --id 参数作用是？

🛠️ 动手实践 ​

  1. 完成 2.1–2.4 全部步骤，分别用 CLI 和 vite dev 两种方式与你的 Assistant 对话。
  2. 用同一个 --id 连发三条相关消息，验证第三条能否记住第一天的内容。
  3. 在 flue() 插件配置里设置 providers: ['anthropic']，观察构建行为变化。

项目跑起来了！下一章深入 Flue 最核心的 'use agent' 编程模型。