Stello App

基于 Stello 框架 搭建的 AI 旅行规划助手 Demo，展示了 Stello 的核心能力：会话树、智能记忆、Agent 驱动的话题分裂。

功能亮点

• 星空图可视化 — 对话以节点图的形式展示，每个节点是一个独立话题
• AI 主动分裂话题 — AI 发现可展开的子话题时，会主动创建分支节点
• SSE 流式响应 — 逐字输出，不再等 AI 写完整段才显示
• 智能记忆系统 — 三层记忆（当前对话 / Session 记忆 / 全局画像），子话题聊到的信息会自动冒泡到全局
• 旅行者画像 — AI 从对话中自动提炼用户偏好（旅行风格、预算、兴趣等），在侧边栏「画像」Tab 展示
• Markdown 渲染 — AI 回复支持富文本（标题、列表、代码块、表格等）

技术栈

层	技术
前端	React 19 + Vite 6 + TypeScript
后端	Express 4 + TypeScript (tsx)
LLM	OpenAI SDK（兼容任何 OpenAI API 格式的服务）
框架	@stello-ai/core + @stello-ai/visualizer

快速开始

1. 安装依赖

pnpm install

2. 配置 API Key

cp .env.example .env

编辑 .env，填入你的 LLM API Key：

# 方式一：直接用 OpenAI
LLM_API_KEY=sk-your-openai-key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o

# 方式二：用兼容 OpenAI 格式的第三方服务（如 DeepSeek、Moonshot 等）
LLM_API_KEY=sk-your-key
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL=deepseek-chat

# 方式三：也兼容 OPENAI_API_KEY 环境变量
OPENAI_API_KEY=sk-your-key

支持的环境变量（按优先级）：

变量	说明	默认值
LLM_API_KEY	API 密钥（推荐）	-
OPENAI_API_KEY	兼容 OpenAI 标准变量名	-
LLM_BASE_URL	API 地址	https://api.openai.com/v1
LLM_MODEL	模型名称	gpt-4o

只要你的 LLM 服务兼容 OpenAI Chat Completions API 格式（包括 tool calling 和 streaming），就可以直接用。

3. 启动

pnpm dev

浏览器打开 http://localhost:5173

4. 使用

1. 页面上看到星空图，中心有一个「旅行规划」节点
2. 点击节点 → 侧边栏弹出 → 开始和 AI 聊天
3. AI 会先了解你的旅行偏好，然后给出个性化推荐
4. 当话题可以展开时，AI 会提议创建分支 → 星空图出现新节点
5. 切到「画像」Tab 查看 AI 提炼的旅行者信息
6. 切到「文件」Tab 查看 Session 的记忆摘要

项目结构

stello-app/
├── server/
│   ├── index.ts          # Express API + SSE 端点
│   ├── stello.ts         # Stello 引擎封装
│   └── llm.ts            # LLM 调用（普通 / tool calling / 流式）
├── src/
│   ├── App.tsx            # 主组件（流式状态管理 + Markdown 渲染）
│   ├── ProfilePanel.tsx   # 旅行者画像面板
│   ├── api.ts             # 前端 API 封装（含 SSE 解析）
│   ├── main.tsx           # React 入口
│   ├── markdown.css       # Markdown 样式
│   └── visualizer-augment.d.ts  # TypeScript 类型扩展
├── patches/               # visualizer bug 修复 patch
├── .env.example           # 环境变量模板
├── CHANGELOG.md           # 开发历程
├── KNOWN_ISSUES.md        # 已知问题及修复方案
├── DEVELOPMENT.md         # 开发心得
└── TODO_OPTIMIZE.md       # 优化建议

API 端点

端点	方法	说明
/api/sessions	GET	获取所有 Session
/api/sessions/:id/messages	GET	获取对话记录
/api/sessions/:id/files	GET	获取 Session 文件
/api/sessions/:id/chat	POST	发消息（非流式）
/api/sessions/:id/chat/stream	POST	发消息（SSE 流式）
/api/core	GET	获取旅行者画像

已知问题

开发过程中发现了 @stello-ai/core 和 @stello-ai/visualizer 的 6 个 Bug，已通过 pnpm patch 和应用层 workaround 修复。详见 KNOWN_ISSUES.md。

License

MIT