第 1 课：跑起来——把 LubanAgent 装进你的机器

学完本课你能：在本机跑起完整开发栈（API + 工作台前端），完成第一次对话并看懂它背后的原始事件流，逛遍工作台｜预计耗时 30-45 分钟｜前置：会用终端；装好 Python ≥3.11、uv、Node.js ≥20 ｜难度 ★☆☆

先交个底：这一课跑的是仓库内置的客服示例，你一行代码都不用写，也不需要任何模型 API Key。零密钥的代价是——回复内容是一句固定台词，因为默认绑的是一个"假模型"（FakeLLM）。这不是坏事，恰好让你先看清一件事：装好环境、跑通链路、看懂事件流，跟"模型聪不聪明"，是两件独立的事。前者是这一课，后者是第 3 课。

我们每一步后面都跟着"✅ 你应该看到"。对不上就停下来查——"常见坑"一节收着本课所有已知坑，都查不到再提 Issue。带着一个没验证的步骤往下走，三步之后你就分不清是哪步坏的了。

1. 学习目标

跑通 migrate → init → start 三步链路，知道每步各干了什么
在工作台调试台和用户端聊天页各完成一次对话（零密钥，FakeLLM）
用 curl 看懂一次 Run 的原始 SSE 事件流
说出工作台各页面的用途

2. 概念讲解：你装的到底是什么

为什么是克隆仓库，不是 pip install？ 因为你跟 LubanAgent 的关系不是"使用一个库"，而是"住进一个基座"。你要在里面长期写自己的 Agent、自己的工具——这些代码就住在仓库的 app/ 目录里。类比一下：用库像租酒店的房间，基座像拿了毛坯房的钥匙——结构是别人的，装修是你自己的，而且物业（框架）升级不会铲掉你的装修。app/ 你的领地和 lubanagent/ 框架领地的分界，第 0 课讲过，从这一课起你每次打开仓库都会看到它。

三条命令各干了什么。 后面要跑的 migrate、init、start 不是三个咒语，各有一件事干：

luban migrate——建表。在数据库（开发期是 SQLite，一个本地文件，免安装）里创建全部表结构。
luban init——种子落库。把仓库自带的种子（一个假模型 + 9 个 Agent 的 YAML 定义）写进数据库。
scripts/dev.sh start——起服务。后端 API 在 8000 端口，工作台前端在 5173。

这里有个认知现在就要立起来，第 2 课马上要用：YAML 是投喂口，数据库才是存储。luban init 把 app/agents/*.yaml 里的定义灌进数据库，之后系统运行读的是库，不是那个 YAML 文件。所以改 YAML 不会自动生效，要重跑 luban init。先记住，第 2 课你会亲手验证这个行为。

零密钥能跑到哪一步？ 两个兜底让你不用任何 Key 就能起全套环境：数据库用 SQLite，模型用 FakeLLM。FakeLLM 是一个"假大脑"——它会走完对话的全部流程（事件流、Trace、记忆一应俱全），但回复永远是同一句固定台词。它的作用是让你零成本验证"链路是通的"；至于查订单、答 FAQ、走审批这些需要真智力的活，要等第 3 课接上真模型（届时你需要一个大模型 API Key，充值 10 元足够走完整个教程）。

3. 动手：主线步骤

步骤 1：克隆并安装

git clone <仓库地址> luban-tutorial   # 名字随意，下面统一叫它"仓库根目录"
cd luban-tutorial
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e ".[dev]"

✅ 你应该看到：安装滚动输出，末尾无红色报错。首次约 2-5 分钟（取决于网络）。

Windows 用户：命令里的 .venv/bin/ 在你的机器上是 .venv\Scripts\。

步骤 2：配置

cp app/config/.env.example .env

✅ 你应该看到：仓库根目录出现 .env 文件。先不用改任何内容——打开扫一眼就行，你会看到数据库、观测、鉴权几组配置，全部带缺省值，此时一个都不用动。

步骤 3：建表 + 种子

.venv/bin/luban migrate
.venv/bin/luban init

✅ 你应该看到：migrate 输出一段 Alembic 迁移日志（Running upgrade ...，末行 migrated to head）；init 逐行输出 9 个 Agent，每个形如 cs-faq@1——@1 表示首次导入、版本 1。

顺手再跑一遍 luban init，这次输出变成 cs-faq@1 (unchanged)：内容没变就不追加新版本。init 是幂等的，重复跑安全——这个行为第 2 课你会靠它验证"改了 YAML 才产生新版本"。

步骤 4：起服务

bash scripts/dev.sh start

首次运行会自动 npm install 拉前端依赖（约 1 分钟，之后秒起）。

✅ 你应该看到：bash scripts/dev.sh status 显示——

后端 :8000 跑中 (pid ...)
前端 :5173 跑中 (pid ...)

浏览器打开 http://localhost:5173 ，左侧是工作台导航（Agents / Prompt 库 / 模型 / 工具 / Skills / 知识库 / 流程图 / Traces / 评测）。

步骤 5：工作台走一圈

别急着对话，先把 9 个页面点一遍，混个脸熟：

Agents：9 个内置 Agent 的列表——版本、状态、调试入口都在这。你以后自己的 Agent 也住这里。
Prompt 库 / 模型：人设模板与模型注册（第 3 课会回来细看模型页）。
工具 / Skills：Agent 能调用的工具和能力包。
知识库：文档上传与切块（第 5 课的主场）。
流程图 / Traces / 评测：图编排拓扑、运行回放、评测报告（第 6-8 课逐一回来）。

✅ 你应该看到：Agents 页列出 9 个 Agent，customer-service-bot（内置客服「小鲁」）排在你眼前。

步骤 6：调试台，第一次对话

Agents 页 → customer-service-bot → 进"调试台"（或直接开 http://localhost:5173/agents/customer-service-bot/debug ），输入：

你好

✅ 你应该看到：回复是——

你好，我是 LubanAgent。

无论你问什么，都是这一句。这是预期行为，不是坏了：零密钥下四个槽位都绑着 FakeLLM，它的剧本就这一句台词。你要在这一步确认的是：对话链路通了——输入被接收、Run 被执行、回复流式吐回来。

步骤 7：用户端聊天页

开 http://localhost:5173/chat ——这是没有管理侧栏的用户端视角，选 customer-service-bot 再说句话。

✅ 你应该看到：带问候语的聊天界面（问候语来自 Agent 定义里的 greeting 字段——定义里的静态文本，不需要模型），回复依旧是那句固定台词。

步骤 8：用 curl 看原始事件流

图形界面把细节藏起来了，现在扒开看。跑：

curl -N -X POST http://localhost:8000/v1/agents/customer-service-bot/runs \
  -H "Content-Type: application/json" \
  -d '{"input": "你好"}'

✅ 你应该看到：一串 event: ... / data: {...} 帧，肉眼能认出第 0 课讲过的那几种事件——

event: run.started        ← 开头，带 run_id
event: token.delta        ← 每帧吐几个字（固定台词也是"流式"吐出来的）
event: run.completed      ← 结尾，data 里带完整 output

这就是 SSE（Server-Sent Events）流——你的业务系统将来接 LubanAgent，消费的就是这条流。注意这一跑里没有 tool.started 之类的工具事件：FakeLLM 不做工具决策。接上真模型后（第 3 课），同样的命令会多出 tool.started → tool.finished 两段——到时候你会回来重跑这条命令做个对照。

步骤 9：回放刚才的现场

工作台 Traces 页，找到最近一次 Run（就是刚才 curl 那次），点进去。

✅ 你应该看到：这次 Run 的完整现场——用了哪个模型（fake-chat）、什么时候开始结束。工具调用区是空的（没调用过工具），但结构都在。

第 0 课说的"每个事件都留痕"就是这个。以后你的 Agent 说了不靠谱的话，来这调现场——第 3 课接真模型后，这里的工具入参出参、Token 消耗都会丰富起来。

步骤 10：收工（可选）

bash scripts/dev.sh stop

✅ 你应该看到：status 显示两个进程都不在了。想再跑，start 回来即可（数据库和种子都还在，不用重新 migrate/init）。

4. 完成自检清单

luban init 输出了 9 个 Agent；再跑一遍全部 (unchanged)
工作台 http://localhost:5173 能打开，9 个页面都点过
调试台和 /chat 各完成一次对话，回复为固定台词（预期行为）
curl 能肉眼认出 run.started / token.delta / run.completed 三种事件
Traces 页能回放最近一次 Run，模型显示 fake-chat

全勾了，这课就过了。缺哪个回对应步骤补。

5. 常见坑

问它查订单/答 FAQ，它还是那句固定台词。 预期行为，不是坑——零密钥下 FakeLLM 不做工具调用、不做检索，它只负责证明链路是通的。查单、审批、FAQ 引用这些体验从第 3 课接上真模型开始。

scripts/dev.sh 报 permission denied。 用 bash scripts/dev.sh start 显式用 bash 跑（本教程所有命令都写全了），或 chmod +x scripts/dev.sh 一次。

端口被占。 8000（API）、5173（前端）任何一个被占，对应服务起不来。lsof -i :8000 找到占用进程处理掉。

npm install 卡住或失败。 网络问题，多数是 npm 源。换国内镜像（npm config set registry https://registry.npmmirror.com）后删掉 lubanagent/ui/node_modules 重跑。

luban init 报数据库相关错误。 九成是忘了先跑 luban migrate（表还没建）。按步骤 3 的顺序来。

6. 练习

练习 A（观察）：在 curl 那一步换几个不同的输入（"帮我查订单""你是谁""今天天气怎么样"），确认回复都是同一句固定台词。然后想一个问题：既然回复都一样，这一课到底验证了什么？（提示：链路。事件流的每一种事件、Run 的留痕、工作台的每个页面——这些跟模型无关的部分，就是你以后接真模型时不用再操心的一半工程量。）

练习 B（观察）：Traces 页里点开两次不同的 Run，对比它们的 run_id 和时间。确认"每句话一次 Run、每次 Run 一条 Trace"这个对应关系。

练习 C（思考）：FakeLLM 的剧本只有一句话，你觉得这是偷懒还是设计？如果是你，会给零密钥用户的假模型设计一个多长的剧本？（这个问题没有标准答案——第 3 课接真模型时，你会直观感受到"假模型的意义就是让链路问题归链路、智力问题归模型"。）

7. 小结与下一课预告

你的机器上现在有一套完整能跑的 Agent 系统：环境就绪、种子入库、服务起停自如，你看懂了一次 Run 的完整事件流，也逛遍了工作台。同时你亲眼确认了零密钥的天花板：链路全通，大脑是假的。

第 2 课，你把内置客服复制一份，改成自己的"图书馆借阅助手"——写下你自己的第一份 Agent 定义，让它用你的人设说话。第 3 课再给它换上真大脑。

延伸阅读：用户手册 §0（三分钟认识）、§11（工作台）、§14（智能客服示例）｜涉及源码：scripts/dev.sh、app/main.py、demos/customer_service/