📚 AI 工程与智能体教程站

简体中文

English

简体中文

English

第 14 章 · CLI 与本地运行 ​

本章目标：掌握 flue 命令行工具的核心用法——本地运行 agent、用 blueprints 脚手架生成项目、离线查阅文档。

14.1 安装与命令总览 ​

CLI 由 @flue/cli 包提供。它不是构建工具——本地开发与生产构建由 Vite 负责（vite dev / vite build），CLI 只负责脚手架、单次运行、blueprint 与离线文档：

bash
# 项目内安装（推荐，flue init 会把它写成 devDependency）
npm install @flue/runtime @flue/cli

npx flue --help
text
flue <command>

Commands:
  flue init [dir]               脚手架创建 Flue 项目（交互式选择 target 与部署方式）
  flue run <path>               本地直跑一个 agent 模块：提交一条消息、流式输出、打印回复
  flue add [kind] [name|url]    拉取集成 blueprint 实现指南（供 coding agent 参照实现）
  flue update <kind> <name>     为已有集成拉取更新版 blueprint 指南
  flue docs [read|search]       离线查阅与当前安装版本一致的文档

v2 移除了 dev / build / new / deploy 命令

Flue 2.0 起 flue dev、flue build 由 Vite 接管（vite dev / vite build 配合 @flue/vite 插件）；旧的 flue new 并入 flue init 的完整项目脚手架；flue deploy 不再存在（各目标平台见生态部署指南）。flue run 也从"调用已构建服务"改为进程内直接执行 agent 模块。

14.2 本地运行 agent ​

两条路径对应两种场景：

bash
# ① 开发 HTTP 服务：Vite 承担 dev server 与热更新
npx vite dev          # 默认 http://localhost:5173，自动加载 .env

# ② 单次直跑：不启服务、不开端口，提交一条消息并打印回复后退出
npx flue run src/agents/triage.ts --message "分诊仓库里所有带 bug 标签的 issue"
typescript
// src/agents/echo.ts — 最小的可运行 agent，用来验证环境
'use agent';
import { useModel } from '@flue/runtime';

export function Echo() {
  useModel('anthropic/claude-sonnet-4-6');
  return '把用户输入原样重复一遍。';
}
bash
npx flue run src/agents/echo.ts --message "hello flue"
# stdout 只输出回复；日志走 stderr，管道化安全

常用参数（完整清单见 flue run --help）：

参数作用
-m/--message必填：本次任务的消息文本
--id <conversation-id>复用同一会话继续对话（会话按 ID 持久化）
--name <agentName>同一模块导出多个 agent 时选择其一
--data '<json>'创建数据（需在 agent 上声明 initialData 静态校验）
--uid / --new发送条件：续接指定实例 / 仅允许新建
--json输出结构化结果信封

服务开发用 vite dev

vite dev 由 @flue/vite 插件驱动：解析 'use agent' 文件、提供 HMR 热更新，改完 useModel() 或指令文本保存即生效。.env 由 Vite 标准机制自动加载（shell 导出的值优先）。注意 CLI 与 vite dev 都不会执行 app.ts 里注册的 provider——依赖模块级 setProvider() 时应写在 agent 模块中。

14.3 Blueprints：项目脚手架 ​

Flue 2.0 的脚手架统一由 flue init 完成——一条命令生成完整可跑的项目骨架（含 flue.config.ts、package.json、src/app.ts、.env、示例 agent 等；它只写文件，不装依赖）：

bash
# 交互式脚手架（必须显式给 --target，否则在无 TTY 环境会报错）
npx @flue/cli init my-bot --target node           # 或 --target cloudflare [--deploy]

cd my-bot && npm install
npx vite dev                                      # 本地服务开发
npx flue run src/agents/hello.ts -m "hi"          # 无服务直跑冒烟测试

生成的典型目录结构：

text
my-bot/
├── src/
│   ├── app.ts          # 路由入口（必需）：挂载 agent 路由
│   ├── agents/         # 'use agent' 函数
│   │   └── hello.ts
│   ├── skills/         # SKILL.md 技能包
│   ├── tools/          # 类型化工具
│   └── channels/       # 入站事件通道
├── flue.config.ts      # target: 'node' | 'cloudflare'
├── vite.config.ts      # --deploy 时生成
└── package.json

init 与 add/update 的分工

flue init 负责新项目骨架；flue add [kind] [name|url] 与 flue update <kind> <name> 则是拉取某个集成（数据库、沙箱、Slack 通道等）的 blueprint 实现指南，交给 coding agent 参照落地——两个命令都不会直接改你的业务代码。不带参数执行 flue add 可列出全部可用 blueprint。

14.4 离线文档 ​

flue docs 把与当前安装版本一致的官方文档装进终端，适合在飞机上或内网环境工作，也避免了网页文档与你安装的版本不同步的问题：

bash
# 列出所有文档页
flue docs

# 搜索某个主题（输出 JSON 结果）
flue docs search "sandbox"

# 打印某一页为 Markdown
flue docs read /docs/guide/sandboxes
bash
# CI 里校验 agent 文件能否被正确解析（不真正调用模型）
flue run src/agents/triage.ts --dry-run

密钥检查

flue run 首次调用模型前会检查 provider 凭证。缺 key 时会明确报错而不是静默失败： Error: no credentials for provider "anthropic" — set ANTHROPIC_API_KEY

14.5 调试技巧 ​

bash
# 带详细日志运行，观察工具调用与模型回合（日志走 stderr）
npx flue run src/agents/triage.ts --message "分诊 issue #42" --verbose

# 同一模块多个 agent 时指定目标，并以结构化信封输出结果
npx flue run src/agents/tasks.ts --name triage --json

# 复用会话继续对话（第二次能看到第一次的内容）
npx flue run src/agents/triage.ts --id ticket-42 --message "还有遗漏吗？"

配合第 13 章的 observer，本地也能看到完整事件流：

typescript
// 仅在本地开发时挂载控制台 observer
if (process.env.NODE_ENV === 'development') {
  observe((event) => console.log(new Date().toISOString(), event.type));
}

14.6 本章小结 ​

  • v2 CLI 只有五个命令：init / run / add / update / docs；
  • dev 与 build 由 Vite 接管：vite dev 开发热更新、vite build 产出 dist/server.mjs；
  • flue run 进程内直跑单个 agent 模块，stdout 只出回复、日志走 stderr，天然适配 CI；
  • flue docs 提供与安装版本一致的离线文档；blueprint 靠 add/update 拉取实现指南。

🧪 随堂测验

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

1. 想要修改代码后立即生效、无需重启进程，应该使用哪个命令？

2. flue new my-bot --blueprint support-agent 会生成什么？

3. 在内网无法访问外网时，如何查阅 Flue 文档？

4. 只想验证 agents/triage.ts 能否被正确解析（不实际调用模型），应该怎么做？

🛠️ 动手实践 ​

  1. 用 flue init 生成一个 support-agent 项目，画出它的目录树并说明每个目录的职责。
  2. 写一个 echo agent 分别用 vite dev 和 flue run 运行，对比两种方式的适用场景。
  3. 在断网状态下使用 flue docs --serve 查阅 Sandboxes 文档，验证离线能力。