Skip to content

Commit 095d527

Browse files
rhlinrhlin
authored
Merge pull request #81 from gimmyhehe/cgm/add-docs
docs: add contribute and readme docs
2 parents 64198c7 + 1169ed2 commit 095d527

8 files changed

Lines changed: 393 additions & 2 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: '🐛 Bug report'
2+
description: Create a report to help us improve GenUI SDK
3+
title: '🐛 [Bug]: '
4+
labels: ['🐛 bug']
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Please fill out the following carefully in order to better fix the problem.
10+
- type: dropdown
11+
id: genui-sdk-packages
12+
attributes:
13+
label: GenUI SDK Packages
14+
description: |
15+
### **Please select the packages that are affected by the issue, you can select multiple packages.**
16+
multiple: true
17+
options:
18+
- '@opentiny/genui-sdk-server'
19+
- '@opentiny/genui-sdk-vue'
20+
- '@opentiny/genui-sdk-angular'
21+
validations:
22+
required: true
23+
- type: input
24+
id: package-version
25+
attributes:
26+
label: Package Version
27+
placeholder: latest
28+
validations:
29+
required: true
30+
- type: textarea
31+
id: minimal-repo
32+
attributes:
33+
label: Minimal reproduction
34+
description: |
35+
**The code or a link to reproduce the issue.**
36+
placeholder: Please Input
37+
validations:
38+
required: true
39+
- type: textarea
40+
id: reproduce
41+
attributes:
42+
label: Step to reproduce
43+
description: |
44+
**After the replay is turned on, what actions do we need to perform to make the bug appear? Simple and clear steps can help us locate the problem more quickly. Please clearly describe the steps of reproducing the issue. Issues without clear reproducing steps will not be repaired. If the issue marked with 'need reproduction' does not provide relevant steps within 7 days, it will be closed directly.**
45+
placeholder: Please Input
46+
validations:
47+
required: true
48+
- type: textarea
49+
id: expected
50+
attributes:
51+
label: What is expected
52+
placeholder: Please Input
53+
- type: textarea
54+
id: actually
55+
attributes:
56+
label: What is actually happening
57+
placeholder: Please Input
58+
- type: textarea
59+
id: additional-comments
60+
attributes:
61+
label: Any additional comments (optional)
62+
description: |
63+
**Some background / context of how you ran into this bug.**
64+
placeholder: Please Input

‎.github/ISSUE_TEMPLATE/feature-request.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: ✨ Feature Request
2+
description: Propose new features to GenUI SDK to improve it.
3+
title: '✨ [Feature]: '
4+
labels: ['✨ feature']
5+
body:
6+
- type: textarea
7+
id: feature-solve
8+
attributes:
9+
label: What problem does this feature solve
10+
description: |
11+
Explain your use case, context, and rationale behind this feature request. More importantly, what is the end user experience you are trying to build that led to the need for this feature?
12+
placeholder: Please Input
13+
validations:
14+
required: true
15+
- type: textarea
16+
id: feature-api
17+
attributes:
18+
label: What does the proposed API look like
19+
description: |
20+
Describe how you propose to solve the problem and provide code samples of how the API would work once implemented. Note that you can use Markdown to format your code blocks.
21+
placeholder: Please Input
22+
validations:
23+
required: true

‎CONTRIBUTING.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Contributing Guide
2+
3+
Language: English | [简体中文](CONTRIBUTING.zh-CN.md)
4+
5+
Thank you for your interest in contributing to the GenUI SDK open source project! There are many ways to contribute—you can choose one or more based on your strengths and interests:
6+
7+
- [Report new bugs](https://github.com/opentiny/genui-sdk/issues/new?template=bug-report.yml)
8+
- Provide more details for [existing bugs](https://github.com/opentiny/genui-sdk/labels/bug), such as screenshots, detailed reproduction steps, or links to minimal reproducible demos
9+
- Fix typos or improve documentation
10+
- Fix bugs
11+
- Implement new features
12+
- Improve unit tests
13+
- Participate in code reviews
14+
15+
## Submitting Issues
16+
17+
Use GitHub Issues to report bugs. Please include the following information:
18+
19+
- **Clear problem description**: Describe what issue you encountered
20+
- **Reproduction steps**: Describe in detail how to reproduce the issue
21+
- **Expected vs actual behavior**: Explain what you expected and what actually happened
22+
- **Environment information**: Node version, OS, relevant dependency versions, etc.
23+
24+
## Feature Requests
25+
26+
If you have ideas for new features, please submit them via [Issues](https://github.com/opentiny/genui-sdk/issues). Include:
27+
28+
- What problem the feature would solve
29+
- Your expected API or usage pattern
30+
31+
## Submitting Pull Requests
32+
33+
1. **Fork this repository**: Click the Fork button on the [GenUI SDK](https://github.com/opentiny/genui-sdk) repository
34+
2. **Create a new branch**: `git checkout -b feature/amazing-feature` and start your changes
35+
3. **Follow code style**: Ensure your code adheres to the project's coding standards
36+
4. **Update documentation**: Update README.md or relevant docs if needed
37+
5. **Submit Pull Request**: Submit a PR after completing your changes
38+
39+
### Running the Playground Locally
40+
41+
- After forking to your account, clone your fork to your local machine
42+
- Add the upstream remote to sync with the latest upstream code
43+
- Run `pnpm i` in the genui-sdk root directory to install dependencies
44+
- Run `pnpm dev` to start the playground
45+
- Open your browser to access it
46+
47+
```shell
48+
# Replace username with your GitHub username
49+
git clone git@github.com:username/genui-sdk.git
50+
cd genui-sdk
51+
52+
# Add upstream remote
53+
git remote add upstream git@github.com:opentiny/genui-sdk.git
54+
55+
# Install dependencies
56+
pnpm i
57+
58+
# Start Playground development environment
59+
pnpm dev
60+
```
61+
62+
### Running Other Projects Locally
63+
64+
The setup steps for server, docs, etc. are similar to the playground—only the start command differs. See `package.json` for specific commands.
65+
66+
### PR Submission Steps
67+
68+
1. Ensure your local development environment is set up and running correctly
69+
2. Sync with upstream: `git pull upstream main`
70+
3. Create a new branch from upstream: `git checkout -b username/feature-name upstream/main`
71+
4. Develop locally
72+
5. Follow [Conventional Commits](https://www.conventionalcommits.org/) when committing
73+
6. Push to your fork: `git push origin branch-name`
74+
7. Create a PR on the [Pull Requests](https://github.com/opentiny/genui-sdk/pulls) page
75+
8. Wait for code review and address feedback
76+
77+
## Join the Community
78+
79+
If you're interested in GenUI SDK or the OpenTiny open source project, you're welcome to join via:
80+
81+
- Add WeChat assistant: `opentiny-official` to join the tech discussion group
82+
- Join the mailing list: <opentiny@googlegroups.com>
83+
84+
---
85+
86+
Thank you for contributing!

‎CONTRIBUTING.zh-CN.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# 贡献指南
2+
3+
语言： [English](CONTRIBUTING.md) | 简体中文
4+
5+
感谢你有意愿参与 GenUI SDK 开源项目的贡献！参与贡献的形式有很多种，你可以根据自己的特长和兴趣选择其中的一个或多个：
6+
7+
- 报告[新缺陷](https://github.com/opentiny/genui-sdk/issues/new?template=bug-report.yml)
8+
- 为[已有缺陷](https://github.com/opentiny/genui-sdk/labels/bug)提供更详细的信息，比如补充截图、提供更详细的复现步骤、提供最小可复现 demo 链接等
9+
- 修改文档中的错别字或完善文档
10+
- 修复缺陷
11+
- 实现新特性
12+
- 完善单元测试
13+
- 参与代码检视
14+
15+
## 提交 Issue
16+
17+
使用 GitHub Issues 报告缺陷。报告时请包含以下信息：
18+
19+
- **清晰的问题描述**：说明你遇到了什么问题
20+
- **复现步骤**：详细描述如何复现该问题
21+
- **预期行为 vs 实际行为**：说明你期望的结果和实际发生的情况
22+
- **环境信息**：如 Node 版本、操作系统、相关依赖版本等
23+
24+
## 新特性建议
25+
26+
如果你有新特性想法，欢迎通过 [Issues](https://github.com/opentiny/genui-sdk/issues) 提交，请说明：
27+
28+
- 该特性主要解决什么问题
29+
- 你期望的 API 或使用方式
30+
31+
## 提交 Pull Request
32+
33+
1. **Fork 本仓库**：点击 [GenUI SDK](https://github.com/opentiny/genui-sdk) 仓库右上角的 Fork 按钮
34+
2. **创建新分支**：`git checkout -b feature/amazing-feature` 并开始你的修改
35+
3. **遵循代码规范**：确保你的代码符合项目的代码风格规范
36+
4. **更新文档**：如有需要，请更新 README.md 或相关文档
37+
5. **提交 Pull Request**：完成修改后提交 PR
38+
39+
### 本地启动演练场
40+
41+
- fork 到个人仓后，使用git 克隆个人仓库到本地
42+
- 关联上游仓库，方便同步上游仓库最新代码
43+
- 在 genui-sdk 根目录下运行 `pnpm i`, 安装依赖
44+
- 运行 `pnpm dev`，启动演练场
45+
- 打开浏览器访问
46+
47+
```shell
48+
# 将 username 替换为你的 GitHub 用户名
49+
git clone git@github.com:username/genui-sdk.git
50+
cd genui-sdk
51+
52+
# 关联上游仓库
53+
git remote add upstream git@github.com:opentiny/genui-sdk.git
54+
55+
# 安装依赖
56+
pnpm i
57+
58+
# 启动 Playground 开发环境
59+
pnpm dev
60+
```
61+
62+
### 本地启动其他项目
63+
64+
server、docs等启动步骤与演练场相似，仅需修改启动命名，具体命令请查看`package.json`
65+
66+
### 提交 PR 的步骤
67+
68+
1. 确保已完成本地开发环境搭建，并能正常运行
69+
2. 同步上游仓库最新代码：`git pull upstream main`
70+
3. 从上游创建新分支：`git checkout -b username/feature-name upstream/main`
71+
4. 进行本地开发
72+
5. 遵循 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/v1.0.0/) 规范提交
73+
6. 推送到你的 Fork：`git push origin branch-name`
74+
7. 在 [Pull Requests](https://github.com/opentiny/genui-sdk/pulls) 页面创建 PR
75+
8. 等待 Code Review，根据反馈调整代码
76+
77+
### Commit 规范示例
78+
79+
推荐使用 Conventional Commits 格式，例如：
80+
81+
```
82+
feat: 添加 schema 校验功能
83+
fix: 修复渲染器在空数据时的崩溃问题
84+
docs: 更新贡献指南
85+
style: 统一代码缩进格式
86+
refactor: 重构 schema 解析逻辑
87+
test: 添加 tiny-schema-renderer 单元测试
88+
chore: 升级依赖版本
89+
```
90+
91+
### 代码规范
92+
93+
- 保持代码简洁、可读
94+
- 为新功能补充必要的注释和文档
95+
- 修改或新增功能时，请同步更新相关测试用例
96+
97+
## 加入社区
98+
99+
如果你对 GenUI SDK 或 OpenTiny 开源项目感兴趣，欢迎通过以下方式加入：
100+
101+
- 添加官方小助手微信：`opentiny-official`，加入技术交流群
102+
- 加入邮件列表：<opentiny@googlegroups.com>
103+
104+
---
105+
106+
感谢你的贡献！

‎README.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
## GenUI SDK
2+
3+
Language: English | [简体中文](README.zh-CN.md)
4+
5+
GenUI SDK is a full‑stack development toolkit developed by OpenTiny for building **Generative UI**–based AI applications. It helps you quickly create AI apps and embed generative interfaces into existing products.
6+
7+
### Instruction
8+
9+
**GenUI SDK** is an open‑source solution built by the OpenTiny team around the Generative UI concept, providing integrated capabilities across both frontend and backend.
10+
It follows the OpenAI API specification, so you can connect to mainstream LLM providers out of the box.
11+
The SDK ships with Vue and Angular renderers, and supports custom component libraries, interaction logic, and theming.
12+
Whether you are building an AI chat application from scratch or adding generative UI capabilities into an existing business system, GenUI SDK is designed to be ready‑to‑use yet highly extensible.
13+
14+
### Try It Now
15+
16+
You can visit the [Playground](https://playground.opentiny.design/genui-sdk) to experience Generative UI capabilities in action.
17+
The playground itself is built using GenUI SDK.
18+
19+
### Getting Started
20+
21+
If you want to use GenUI SDK in your own project, please refer to the
22+
[Quick Start](https://docs.opentiny.design/genui-sdk/guide/quick-start.html) guide and the [Server package usage](https://docs.opentiny.design/genui-sdk/guide/server-usage.html) documentation.
23+
24+
### Core Capabilities
25+
26+
GenUI SDK is designed to balance **out‑of‑the‑box experience** with **deep customization**, offering rich features and strong ecosystem compatibility:
27+
28+
| Feature | Description |
29+
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
30+
| AI ecosystem compatibility | Follows the OpenAI API specification and can integrate mainstream LLM services. Supports MCP for extending tools and connecting external/enterprise systems. |
31+
| Theme customization | Supports theme switching, dark mode, and token‑based theming to adapt to different brand and product style guides. |
32+
| Custom components | Provides schema‑driven component descriptions, allowing you to extend generative UI component libraries and incorporate business components. |
33+
| Custom interactions | Allows flexible configuration of multi‑turn conversation flows and custom commands/actions (e.g., open page, fetch data, generate forms) to fit complex scenarios. |
34+
| Multi‑stack support | Bundles Vue and Angular renderers so you can adopt GenUI SDK in new projects or integrate it progressively into existing frontends. |
35+
| Advanced capabilities | Offers sample projects and best‑practice templates. Combined with server‑side features, you can implement message orchestration, tool invocation, access control, and more. |
36+
37+
For more details, see the GenUI SDK [feature examples](https://docs.opentiny.design/genui-sdk/examples/renderer/custom-actions.html) for complete explanations and practical guides.
38+
39+
### Packages
40+
41+
| Name | Description |
42+
| --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
43+
| `@opentiny/genui-sdk-server` | Backend service that integrates Generative UI capabilities. Easy to configure and quick to start, with support for custom components and actions. |
44+
| `@opentiny/genui-sdk-vue` | Vue‑based frontend components and renderer for quickly building Generative UI web apps, with powerful customization for complex applications. |
45+
| `@opentiny/genui-sdk-angular` | Angular‑based renderer for integrating Generative UI into Angular applications. |
46+
47+
### Contributing
48+
49+
If you are interested in GenUI SDK, we welcome contributions.
50+
Before contributing, please read the [Contributing Guide](CONTRIBUTING.md).
51+
52+
You can also reach us via:
53+
54+
- Add the official WeChat assistant: `opentiny-official` to join the technical discussion group
55+
- Join the mailing list: <opentiny@googlegroups.com>
56+
57+
### License
58+
59+
[MIT](https://opensource.org/license/MIT)

‎README.zh-CN.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# GenUI SDK
2+
3+
> 语言: [English](README.md) | 简体中文
4+
5+
GenUI SDK 是 OpenTiny 面向生成式 UI（Generative UI）场景的全栈开发套件，帮助你快速搭建 AI 应用。
6+
7+
## 简介
8+
9+
**GenUI SDK** 是 OpenTiny 团队基于生成式 UI 理念打造的开源解决方案，提供完整的前后端一体化集成能力。它遵循 OpenAI 接口规范，可无缝对接主流大模型服务；内置 Vue 与 Angular 双框架渲染器，支持自定义的组件库、交互行为与主题样式。无论是从零搭建一个 AI 对话应用，还是在现有业务系统中嵌入生成式界面能力，GenUI SDK 都能让开发者开箱即用、灵活扩展。
10+
11+
## 立即体验
12+
13+
你可以前往[演练场](https://playground.opentiny.design/genui-sdk)立即体验生成式 UI 能力。演练场正是基于 GenUI SDK 开发的应用。
14+
15+
## 快速开始
16+
17+
如果你希望在自己的项目中集使用 GenUI SDK，可以参考官方[快速开始](https://docs.opentiny.design/genui-sdk/guide/quick-start.html)文档，以及[server包使用文档](https://docs.opentiny.design/genui-sdk/guide/server-usage.html)
18+
19+
## 核心能力
20+
21+
GenUI SDK 在设计上兼顾了”开箱即用“与”深度定制“，具备丰富的特性和良好的生态兼容性。
22+
23+
| 特性 | 说明 |
24+
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
25+
| 现有 AI 生态兼容 | 遵循 OpenAI 接口规范，可无缝对接主流 LLM 服务，并支持 MCP 能力扩展，方便集成各类外部工具与企业内部系统。 |
26+
| 定制主题 | 支持主题切换、暗黑模式以及基于 Token 的主题定制，适配不同品牌与产品的界面规范。 |
27+
| 自定义组件 | 提供 Schema 驱动的组件描述能力，可扩展生成式 UI 组件库，将业务组件纳入统一的生成式交互体系中。 |
28+
| 自定义交互 | 支持灵活配置多轮对话流程、自定义指令与操作（如打开页面、拉取数据、生成表单等），满足复杂业务场景下的人机协同需求。 |
29+
| 多技术栈支持 | 内置 Vue 与 Angular 渲染器，既可在新项目中直接使用，也可为已有前端项目提供渐进式接入方案。 |
30+
| 更多能力 | 提供示例工程与最佳实践模板，结合服务端能力实现消息编排、工具调用、权限控制等高级能力，帮助你快速构建可落地的 AI 应用。 |
31+
32+
若想进一步了解 GenUI SDK 的用法，可以前往 GenUI SDK [特性示例文档](https://docs.opentiny.design/genui-sdk/examples/renderer/custom-actions.html)查看更完整的功能说明与实践指南。
33+
34+
## 组件包
35+
36+
| 名称 | 描述 |
37+
| ------------------- | ------------------------------ |
38+
| `@opentiny/genui-sdk-server` | 集成生成式 UI 能力的后台服务，配置简单，启动快速。支持自定义组件、自定义操作等能力 |
39+
| `@opentiny/genui-sdk-vue` | 基于 Vue 的前端组件与渲染器，可用于快速构建生成式 UI Web 应用。同时拥有强大的定制能力，可用于构建复杂应用。 |
40+
| `@opentiny/genui-sdk-angular` | 基于 Angular 的渲染器，支持在Angular应用中集成生成式 UI 能力。 |
41+
42+
## 贡献指南
43+
44+
如果你对 GenUI SDK 感兴趣，你可以参与贡献。参与贡献前，请先阅读[贡献指南](CONTRIBUTING.zh-CN.md)
45+
46+
你也可以通过以下方式联系我们，进一步交流：
47+
- 添加官方小助手微信：`opentiny-official`，加入技术交流群
48+
- 加入邮件列表：<opentiny@googlegroups.com>
49+
50+
## 授权协议
51+
52+
[MIT](https://opensource.org/license/MIT)

‎README_zh-cn.md‎

Whitespace-only changes.

0 commit comments

Comments
 (0)