运行指南

从零到跑起来的完整清单。所有命令都在 final-project/ 目录下执行。

• 环境要求
• 三步跑起来
• 接真实模型（可选）
• 验证清单
• 构建与类型检查
• 目录速查
• 常见问题

环境要求

工具	版本	检查
Node.js	≥ 20.19（推荐 22+）	node -v
npm	随 Node	npm -v
DeepSeek API Key	可选	仅"接真实模型"需要

三步跑起来

# ① 安装
cd final-project
npm install

# ② 核心库冒烟测试（无网络、无 Key）
npm run demo

# ③ 完整前后端（开两个终端）
npm run dev:server     # 终端 A：后端 http://127.0.0.1:4317
npm run dev:web        # 终端 B：前端 http://localhost:5174

浏览器打开 http://localhost:5174：

1. 提供方选 mock（默认），点击「新建会话」；
2. 输入 请 echo 一句话验证工具链路 回车；
3. 观察三件事同时发生：聊天流逐字输出 → 黄色工具卡片出现 → 右侧事件面板逐条滚动。

接真实模型（可选）

后端启动时注入环境变量：

# DeepSeek 官方 API
OPENAI_API_KEY=sk-xxx npm run dev:server
# 或任意 OpenAI 兼容端点
OPENAI_API_KEY=sk-xxx OPENAI_BASE_URL=https://your-gateway/v1 npm run dev:server

前端：提供方切到 openai-compat，model 填 deepseek-chat（或你端点的模型名），新建会话即可。适配器实现见第二步。

验证清单

对照这张表逐项确认，全部通过才算"跑起来了"：

验证点	预期
npm run demo	输出两段任务：普通对话 + 工具循环（tool/call → tool/result → 第二个 step）
后端日志	mini-harness server 已启动：http://127.0.0.1:4317 + 两个适配器注册行
前端三栏	左会话 / 中聊天 / 右事件面板
聊天流	用户气泡 + 逐字流式 + 🛠 工具卡片 + ✓ 结果卡片
事件面板	turn/start → … → turn/end 全序列可见
取消按钮	发送中可点，流立即中断，turn/end reason=aborted
切换会话	事件面板从日志全量重建

构建与类型检查

npm run typecheck      # 三个 workspace 全部 tsc --noEmit
npm run build          # 前端 tsc + vite build（产物在 apps/web/dist）

目录速查

final-project/
├── packages/mini-harness/
│   ├── src/            # 核心库（约 900 行）
│   │   ├── context.ts  events.ts  plugin.ts  service.ts
│   │   ├── llm/        # types / adapter / adapters/{mock,openai-compat}
│   │   ├── agent/      # session / tools / system-prompt / agent
│   │   └── index.ts
│   └── examples/hello-agent.ts   # npm run demo
├── apps/server/src/    # bootstrap.ts + index.ts（Express + SSE）
└── apps/web/src/       # App.tsx + api.ts + styles.css（React + Vite）

常见问题

见附录 · 常见错误与排障。