📚 编程进阶教程站

第 14 章 · CLI 与本地运行 ​

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

14.1 安装与命令总览 ​

CLI 由 @flue/cli 包提供，安装后得到全局 flue 二进制：

bash
# 全局安装（也可用 npx flue 临时执行）
npm install -g @flue/cli

flue --help
text
flue <command>

Commands:
  flue dev        本地开发运行 agent
  flue run        执行一次 agent 任务
  flue new        用 blueprint 生成新项目
  flue docs       离线文档
  flue deploy     部署辅助

14.2 本地运行 agent ​

开发期最高频的两个命令是 dev 与 run：

bash
# 开发模式：启动本地服务，监听文件变化自动重载
flue dev --port 3000

# 单次运行：直接给 Triage agent 一个任务并等待完成
flue run agents/triage.ts "分诊仓库里所有带 bug 标签的 issue"
typescript
// agents/echo.ts — 最小的可运行 agent，用来验证环境
'use agent';
import { useModel } from '@flue/runtime';

export function Echo() {
  useModel('anthropic/claude-sonnet-4-6');
  return '把用户输入原样重复一遍。';
}
bash
flue run agents/echo.ts "hello flue"
# hello flue

dev 模式的好处

flue dev 底层走 @flue/vite，享受 Vite 的即时热更新：改完 useModel() 或指令文本，保存即生效，无需手动重启。

14.3 Blueprints：项目脚手架 ​

Blueprint 是官方预设的项目模板，一条命令生成完整可跑的骨架：

bash
# 用 blueprint 创建新项目
flue new my-bot --blueprint support-agent

cd my-bot && npm install && flue dev

生成的典型目录结构：

text
my-bot/
├── agents/          # 'use agent' 函数
│   └── triage.ts
├── skills/          # SKILL.md 技能包
│   ├── triage/SKILL.md
│   └── verify/SKILL.md
├── tools/           # 类型化工具
│   └── github.ts
├── channels/        # 入站事件通道
├── vite.config.ts   # @flue/vite 配置
└── package.json

14.4 离线文档 ​

flue docs 把官方文档装进终端，适合在飞机上或内网环境工作：

bash
# 启动本地文档站（无需联网）
flue docs --serve --port 4321

# 直接搜索某个主题
flue docs search "sandbox"
bash
# CI 里校验 agent 文件能否被正确解析（不真正调用模型）
flue run agents/triage.ts --dry-run
# ✔ parsed agents/triage.ts (2 tools, 1 skill, model: anthropic/claude-sonnet-4-6)

密钥检查

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

14.5 调试技巧 ​

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

# 指定只跑某个 agent 并输出结构化结果到文件
flue run agents/triage.ts --output result.json

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

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

14.6 本章小结 ​

  • flue dev 热更新开发、flue run 单次执行任务；
  • flue new --blueprint 一条命令生成 agents/skills/tools/channels 完整骨架；
  • flue docs --serve 提供完全离线的官方文档；
  • --dry-run 校验解析、--verbose 看全量日志，是排障第一梯队。

🧪 随堂测验

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

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

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

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

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

🛠️ 动手实践 ​

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