@oakkles/llm-ui-react 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +102 -16
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,15 +1,23 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
+
<img src="./assets/llm-ui-logo.png" alt="LLM UI logo" width="180" />
|
|
4
|
+
|
|
3
5
|
# @oakkles/llm-ui-react
|
|
4
6
|
|
|
5
7
|
面向 AI / LLM 产品的 React 组件库，用一套可组合组件快速搭建 Chat、Agent、知识库问答和流式生成界面。
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
9
|
+
<p>
|
|
10
|
+
<a href="https://www.npmjs.com/package/@oakkles/llm-ui-react"><img alt="npm version" src="https://img.shields.io/npm/v/@oakkles/llm-ui-react?style=flat-square&label=npm&labelColor=0f172a&color=2563eb" /></a>
|
|
11
|
+
<img alt="React 18+" src="https://img.shields.io/badge/React-18%2B-149eca?style=flat-square&logo=react&logoColor=white" />
|
|
12
|
+
<img alt="TypeScript ready" src="https://img.shields.io/badge/TypeScript-ready-3178c6?style=flat-square&logo=typescript&logoColor=white" />
|
|
13
|
+
<img alt="Storybook docs" src="https://img.shields.io/badge/Storybook-docs-ff4785?style=flat-square&logo=storybook&logoColor=white" />
|
|
14
|
+
<img alt="Package format" src="https://img.shields.io/badge/ESM%20%2B%20CJS-111827?style=flat-square&label=package" />
|
|
15
|
+
<img alt="License" src="https://img.shields.io/npm/l/@oakkles/llm-ui-react?style=flat-square&label=license&labelColor=0f172a&color=16a34a" />
|
|
16
|
+
</p>
|
|
17
|
+
|
|
18
|
+
<p>
|
|
19
|
+
<a href="https://llm-ui-react.vercel.app"><strong>在线 Storybook / Vercel Demo</strong></a>
|
|
20
|
+
</p>
|
|
13
21
|
|
|
14
22
|
</div>
|
|
15
23
|
|
|
@@ -22,8 +30,9 @@
|
|
|
22
30
|
| 流式生成 | `useStream`、`mockStream` 和 Markdown streaming 状态适配流式回复 |
|
|
23
31
|
| 富文本输出 | `Mark`、`CodeHighlighter` 支持 Markdown、GFM、代码块和语法高亮 |
|
|
24
32
|
| Agent 过程 | `Think`、`Thought`、`Citation` 展示思考过程、步骤和引用来源 |
|
|
33
|
+
| 会话管理 | `ConversationList`、`ConversationItem` 支持搜索、折叠、收藏、置顶和删除 |
|
|
25
34
|
| 主题系统 | 基于 `data-theme` 和 CSS Variables，内置 light / dark 主题和柔和切换动画 |
|
|
26
|
-
| AI Ready | Demo
|
|
35
|
+
| AI Ready | 在线 Demo 已接入真实 AI，优先通过 Vercel `/api/chat` 服务端代理请求模型 |
|
|
27
36
|
|
|
28
37
|
## 安装
|
|
29
38
|
|
|
@@ -68,9 +77,15 @@ export function Chat() {
|
|
|
68
77
|
}
|
|
69
78
|
```
|
|
70
79
|
|
|
71
|
-
##
|
|
80
|
+
## 在线 Demo
|
|
81
|
+
|
|
82
|
+
当前 Storybook 已部署到 Vercel：
|
|
83
|
+
|
|
84
|
+
```txt
|
|
85
|
+
https://llm-ui-react.vercel.app
|
|
86
|
+
```
|
|
72
87
|
|
|
73
|
-
|
|
88
|
+
其中 `Examples / AI Conversation Demo / Default` 已接入真实 AI：
|
|
74
89
|
|
|
75
90
|
```txt
|
|
76
91
|
浏览器 Demo
|
|
@@ -79,14 +94,82 @@ export function Chat() {
|
|
|
79
94
|
-> OpenAI-compatible 模型服务
|
|
80
95
|
```
|
|
81
96
|
|
|
82
|
-
|
|
97
|
+
`Mocked` story 保留本地模拟流式回复，用于稳定的 Storybook interaction / browser tests。
|
|
98
|
+
|
|
99
|
+
Storybook 的全局 Light / Dark toolbar、左侧 manager、顶部工具栏和组件展示区会保持主题同步；Demo 内部的主题按钮也会反向同步 Storybook 全局主题。
|
|
100
|
+
|
|
101
|
+
## AI 协作开发流程
|
|
102
|
+
|
|
103
|
+
此项目在开发过程中使用 `Claude Code CLI` 接入 `gpt-5.5`，核心实现围绕当前代码的结构、Storybook 反馈和本地验证闭环推进。
|
|
104
|
+
|
|
105
|
+
| 环节 | 使用方式 |
|
|
106
|
+
| ------------- | ------------------------------------------------------------------------ |
|
|
107
|
+
| 需求拆解 | 通过 Plan 模式先梳理实现边界、关键文件、风险点和验证方式，再进入编码 |
|
|
108
|
+
| CLAUDE.md | 通过 `/init` 初始化项目级`memory`在CLAUDE.md中,规范组件开发的流程
|
|
109
|
+
| 代码检索 | 使用 `Explore` subagent 搜索组件、hooks、构建配置和 Storybook 相关实现 |
|
|
110
|
+
| 组件设计 | 使用 `component-design-researcher` subagent 对比 shadcn/ui、assistant-ui、Ant Design X 等 AI UI 组件模式 |
|
|
111
|
+
| 视觉与文档 | 使用 `frontend-design`、`readme-polish` skills 辅助 Demo 和视觉表达优化 |
|
|
112
|
+
| MCP 辅助 | 结合 shadcn / assistant-ui 文档 MCP 获取组件 API、示例和设计参考，避免只凭记忆实现 |
|
|
113
|
+
| 安全边界 | 真实模型密钥只放在 Vercel 服务端环境变量；README、源码和 Storybook 中只保留占位变量 |
|
|
114
|
+
| 代码 Review | 修改后通过 `git diff` 逐项检查变更，重点看 API 设计、类型约束、主题同步、密钥暴露风险和 Storybook 交互稳定性 |
|
|
115
|
+
| 验证闭环 | 使用 `pnpm lint`、`pnpm build`、`pnpm test:storybook`、`pnpm build-storybook` 和线上 Vercel Demo 检查关键路径 |
|
|
116
|
+
|
|
117
|
+
AI 主要负责扩大检索范围、给出实现计划、辅助生成样板代码和发现遗漏；最终合入前仍以项目实际代码、lint/build/test 结果和浏览器中的 Storybook 表现为准。
|
|
118
|
+
|
|
119
|
+
## 项目结构
|
|
120
|
+
|
|
121
|
+
```txt
|
|
122
|
+
D:\LLM-UI
|
|
123
|
+
├── api/ # Vercel Serverless Functions
|
|
124
|
+
│ └── chat.ts # 同源 AI 流式代理接口
|
|
125
|
+
├── assets/ # README 与文档静态资源
|
|
126
|
+
├── .storybook/ # Storybook 配置、主题同步和预览样式
|
|
127
|
+
│ ├── main.ts
|
|
128
|
+
│ ├── manager.ts
|
|
129
|
+
│ ├── preview.ts
|
|
130
|
+
│ └── preview.css
|
|
131
|
+
├── src/
|
|
132
|
+
│ ├── components/ # Primitive + Styled 组件实现与 stories
|
|
133
|
+
│ │ ├── actions/
|
|
134
|
+
│ │ ├── bubble/
|
|
135
|
+
│ │ ├── citation/
|
|
136
|
+
│ │ ├── code-highlighter/
|
|
137
|
+
│ │ ├── config-provider/
|
|
138
|
+
│ │ ├── conversation/
|
|
139
|
+
│ │ ├── demo/
|
|
140
|
+
│ │ ├── mark/
|
|
141
|
+
│ │ ├── message-list/
|
|
142
|
+
│ │ ├── notification/
|
|
143
|
+
│ │ ├── prompts/
|
|
144
|
+
│ │ ├── sender/
|
|
145
|
+
│ │ ├── think/
|
|
146
|
+
│ │ └── thought/
|
|
147
|
+
│ ├── hooks/ # 组件库 hooks
|
|
148
|
+
│ ├── locale/ # 多语言文案
|
|
149
|
+
│ ├── styles/ # tokens、light / dark 主题变量
|
|
150
|
+
│ ├── types/ # 公共类型
|
|
151
|
+
│ ├── utils/ # className、stream、Markdown 等工具
|
|
152
|
+
│ ├── index.ts # 组件库入口
|
|
153
|
+
│ ├── index.css # 全量组件样式入口
|
|
154
|
+
│ └── style.ts # CSS 构建入口
|
|
155
|
+
├── dist/ # npm 发布产物
|
|
156
|
+
├── storybook-static/ # Storybook 静态构建产物
|
|
157
|
+
├── tsup.config.ts # JS / DTS 构建配置
|
|
158
|
+
├── vite.config.ts # 开发与测试配置
|
|
159
|
+
├── vite.styles.config.ts # 样式构建配置
|
|
160
|
+
└── package.json
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## 真实 AI 接入
|
|
164
|
+
|
|
165
|
+
推荐把模型 API Key 只放在 Vercel 服务端环境变量中，前端只调用同源后端接口：
|
|
83
166
|
|
|
84
167
|
```txt
|
|
85
168
|
DEEPSEEK_API_KEY=your-server-side-key
|
|
86
169
|
DEEPSEEK_MODEL=deepseek-chat
|
|
87
170
|
```
|
|
88
171
|
|
|
89
|
-
|
|
172
|
+
前端请求示例：
|
|
90
173
|
|
|
91
174
|
```ts
|
|
92
175
|
async function* requestAI(message: string) {
|
|
@@ -109,7 +192,14 @@ async function* requestAI(message: string) {
|
|
|
109
192
|
}
|
|
110
193
|
```
|
|
111
194
|
|
|
112
|
-
|
|
195
|
+
当前 Demo 还提供浏览器直连 DeepSeek 的兜底路径：当 `/api/chat` 不可用或未配置时，可通过 `VITE_DEEPSEEK_API_KEY` 和 `VITE_DEEPSEEK_MODEL` 在静态 Storybook 中直接请求模型。
|
|
196
|
+
|
|
197
|
+
```txt
|
|
198
|
+
VITE_DEEPSEEK_API_KEY=your-browser-visible-key
|
|
199
|
+
VITE_DEEPSEEK_MODEL=deepseek-chat
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
注意：`VITE_*` 变量会进入前端构建产物，任何访问页面的人都能在浏览器 DevTools 中看到这个 key。生产环境更推荐使用 `/api/chat` 服务端代理。
|
|
113
203
|
|
|
114
204
|
## 组件矩阵
|
|
115
205
|
|
|
@@ -197,7 +287,3 @@ dist/style.css # 组件样式
|
|
|
197
287
|
import { Bubble } from '@oakkles/llm-ui-react'
|
|
198
288
|
import '@oakkles/llm-ui-react/style.css'
|
|
199
289
|
```
|
|
200
|
-
|
|
201
|
-
## 在线文档
|
|
202
|
-
|
|
203
|
-
Storybook / Vercel Demo：Coming soon
|