CLI 使用指南

Stream UI 的 CLI 借鉴 shadcn/ui 的工作流，将组件源码复制到你的项目中。

注意：CLI 是纯 ESM JavaScript，位于 cli/ 目录，入口为 bin/stream-ui.js。

全局命令

npx @huiol/stream-ui <command> [name] [flags]

init

初始化项目，创建 stream-ui.json 配置文件并复制核心引擎。

npx stream-ui init

执行后：

• 生成 stream-ui.json（项目根目录）
• 创建 src/components/ui/stream-contains.ts（核心解析器 + Vue 包装器 + DefaultTag）

stream-ui.json

{
  "$schema": "https://huiol.com/schema/stream-ui-components.json",
  "style": "default",
  "framework": "vue",
  "typescript": true,
  "aliases": {
    "ui": "@/components/ui"
  }
}

add

添加内置组件到项目。

npx stream-ui add <name> [name ...]

可用组件

名称	文件	说明
think	think/Think.vue, think/index.ts	可折叠推理面板
text	text/Text.vue, text/index.ts	内联文本包装器
base	base/stream-base.ts	Base 组件工厂
base-md	base/md-support.ts	Markdown 支持插件
base-latex	base/latex-support.ts	LaTeX 支持插件

npx stream-ui add base base-md base-latex

create

创建自定义组件脚手架。

npx stream-ui create <name>

生成一个 .vue 文件，包含 @stream-ui 元数据注释、预设的 props（block、attrs、content、isClosed、reportData）和基础样式模板。

生成组件会内联一份轻量的 StreamBlockComponentProps 类型，便于在 local-first 源码复制模式下直接修改，不要求业务项目额外导入类型。

npx stream-ui create reasoning-card
# 生成 src/components/ui/reasoning-card.vue

prompt

扫描自定义组件目录，生成 LLM 提示词。让大模型学会使用你的 stream-ui 组件标签。

npx stream-ui prompt [components...] [--dir <path>] [--out <path>]

用法

先为你的组件添加 @stream-ui 元数据注释：

<!--
@stream-ui
tag: code
description: Render source code with syntax highlighting and copy.
attrs:
  lang: language id (e.g. ts, python)
  filename: optional display filename
content: source code to highlight
example: <code lang="ts">const a = 1</code>
-->
<script setup lang="ts">
defineProps<{
  attrs?: { lang?: string, filename?: string }
  content?: string
}>()
</script>

# 生成项目中所有组件的 prompt，直接输出到终端
npx stream-ui prompt

# 只生成指定组件的 prompt
npx stream-ui prompt code think

# 指定组件目录并输出到文件
npx stream-ui prompt --dir src/components/ui --out prompt.md

工作原理

1. 递归扫描 --dir 目录（默认为 stream-ui.json 中的 ui 别名路径）中的 .vue/.ts/.tsx 文件
2. 解析 @stream-ui 注释和 TypeScript prop 类型
3. 合并属性描述与类型信息
4. 生成格式化的标签列表，包含示例、属性和说明
5. 将这份提示词注入 LLM 的 system message，模型即会使用你定义的标签

元数据格式

支持 HTML 注释和 JSDoc 两种写法：

<!-- @stream-ui
tag: my-tag
description: ...
attrs:
  key: description
-->

<script setup lang="ts">
/**
 * @stream-ui
 * @tag my-tag
 * @description Render something.
 * @attr key - description
 */
</script>

Flags

标志	说明
--dir <path>	指定组件扫描目录（默认从 stream-ui.json 读取）
--out <path>	输出到文件（默认 stdout）
--cwd <path>	指定项目目录

list

列出所有可用的内置组件。

npx stream-ui list

Flags

标志	别名	说明
--yes	-y	跳过确认提示
--overwrite	-o	直接覆盖已有文件
--diff	—	覆盖前显示差异
--cwd <path>	—	指定目标项目目录
--dir <path>	—	指定组件扫描目录（仅 prompt 命令）
--out <path>	—	输出到文件（仅 prompt 命令）

npx stream-ui add think --yes
npx stream-ui add base base-md --overwrite
npx stream-ui init --cwd ../my-project