create-yss-spec 3.0.0 → 3.1.0

package/template/.hermes/skills/yss-ui/assets/docs/guide/llms.md

@@ -1,295 +0,0 @@
----
-title: AI 工具集成指南（LLMs.txt）
-description: 如何在 Cursor、Windsurf 等 AI 编程工具中使用 YSS UI 文档
-toc: content
----
-
-# AI 工具集成指南
-
-YSS UI 支持通过 <a href="https://llmstxt.org/" target="_blank">LLMs.txt</a> 文件向大语言模型（LLMs）提供文档。此功能可帮助 AI 工具更好地理解我们的组件库、API 及使用模式。
-
-## 什么是 LLMs.txt？
-
-LLMs.txt 是一个专门为大语言模型设计的文档格式规范。通过提供结构化的组件概览和完整文档，AI 编程工具能够：
-
-- 🤖 **自动获取组件文档** - AI 工具可以直接访问最新的组件 API 和用法
-- 💡 **提供准确的代码建议** - 基于真实文档生成正确的组件使用示例
-- 📚 **降低学习成本** - 开发时无需频繁切换到文档页面
-- ✨ **提高代码质量** - AI 能根据最佳实践自动提供建议
-
-## 可用资源
-
-我们提供两个 LLMs.txt 文件来帮助 AI 工具访问文档：
-
-### 推荐使用：llms-full.txt ⭐
-
-**<a href="/llms-full.txt" target="_blank">llms-full.txt</a>** - 完整文档
-
-包含所有组件的完整 API 文档、使用示例和最佳实践。**强烈推荐**作为默认配置，因为：
-- ✅ **更准确的代码生成** - AI 能看到完整的 Props、Events、Slots 定义
-- ✅ **真实示例参考** - 包含实际使用代码，避免 AI 猜测用法
-- ✅ **完整上下文** - 现代 AI 工具（Claude 200K、GPT-4 128K）完全支持这个大小
-
-### 轻量级索引：llms.txt
-
-**<a href="/llms.txt" target="_blank">llms.txt</a>** - 简版索引（1.6KB，70 行）
-
-仅包含组件列表和文档链接。适用于：
-- 上下文窗口受限的旧版 AI 工具
-- 只需要快速组件发现的场景
-- 网络带宽受限的环境
-
-> **建议**：优先使用 `llms-full.txt`，只有在遇到上下文限制时才降级使用 `llms.txt`。
-
-## 在 AI 工具中的使用
-
-### Cursor
-
-在 Cursor 中使用 `@Docs` 功能将 LLMs.txt 文件包含到您的项目中。这有助于 Cursor 为 YSS UI 组件提供更准确的代码建议和文档。
-
-**使用方法：**
-
-1. 在 Cursor 聊天窗口中输入 `@Docs`
-2. 输入 YSS UI 文档站点的 URL（部署后的地址）
-3. Cursor 会自动加载 llms.txt 文件
-
-**示例：**
-
-```
-@Docs http://192.168.164.27:3200
-```
-
-然后你可以直接询问：
-
-```
-如何使用 YTable 组件实现远程分页？
-```
-
-Cursor 将基于 YSS UI 的真实文档提供准确的回答和代码示例。
-
-<a href="https://docs.cursor.com/context/@-symbols/@-docs" target="_blank">详细了解 Cursor 中的 @Docs 功能</a>
-
----
-
-### Windsurf
-
-通过 `@` 引用或在 `.windsurf/rules` 文件中配置 LLMs.txt 文件，以增强 Windsurf 对 YSS UI 组件的理解。
-
-**使用方法 1：临时引用**
-
-```
-@ http://192.168.164.27:3200/llms-full.txt
-```
-
-**使用方法 2：持久化配置**
-
-在项目根目录创建 `.windsurf/rules` 文件：
-
-```markdown
-# YSS UI Documentation
-
-Always reference the YSS UI documentation when working with components:
-- http://192.168.164.27:3200/llms-full.txt
-```
-
-<a href="https://docs.windsurf.com/windsurf/cascade/memories" target="_blank">详细了解 Windsurf Memories 功能</a>
-
----
-
-### Claude Code
-
-在 Claude Code 中，将 LLMs.txt 添加到工作区的知识库（Docs / Context Files）配置中，即可在代码补全与解释时引用其中的内容。
-
-**使用方法：**
-
-1. 打开 Claude Code 设置
-2. 找到 "Docs / Context Files" 配置
-3. 添加 `http://192.168.164.27:3200/llms-full.txt`
-
-<a href="https://code.claude.com/docs" target="_blank">详细了解 Claude Code 文档上下文配置</a>
-
----
-
-### Gemini CLI
-
-在 Gemini CLI 中，可以通过 `--context` 参数或在 `.gemini/config.json` 中指定 LLMs.txt 文件路径。
-
-**使用方法 1：命令行参数**
-
-```bash
-gemini --context http://192.168.164.27:3200/llms-full.txt "如何使用 YTable 组件？"
-```
-
-**使用方法 2：配置文件**
-
-在项目根目录创建 `.gemini/config.json`：
-
-```json
-{
-  "context": [
-    "http://192.168.164.27:3200/llms-full.txt"
-  ]
-}
-```
-
-<a href="https://ai.google.dev/gemini-api/docs" target="_blank">详细了解 Gemini CLI 上下文配置</a>
-
----
-
-### Antigravity
-
-Antigravity（Google Gemini 官方 AI 编程助手）可以通过 `read_url_content` 工具直接读取在线文档。
-
-**方式 1：全局规则配置（强力推荐）** 🚀
-
-配置 `~/.gemini/GEMINI.md`，从根本上教会 AI "文档优先"，无需每次重复提示。
-
-```markdown
-## 核心原则：文档优先
-在回答关于 YSS UI 问题时，必须优先读取以下文档：
-http://192.168.164.27:3200/llms-full.txt
-```
-
-**方式 2：项目 README 配置**
-
-在项目根目录 `README.md` 中添加文档链接，Antigravity 读取项目概况时会自动发现。
-
-```markdown
-## 相关文档
-- YSS UI: http://192.168.164.27:3200/llms-full.txt
-```
-
-**方式 3：对话直接引用**
-
-临时询问时，直接在对话中粘贴 URL：
-
-```
-参考文档 http://192.168.164.27:3200/llms-full.txt，帮我写一个表格。
-```
-
-> **提示**：Antigravity 不支持类似 Cursor `@Docs` 的配置，主要依靠上下文理解和工具调用。
-
----
-
-### Trae
-
-在 Trae 中，将 LLMs.txt 文件放入项目的 knowledge sources 并在设置里开启引用。
-
-**使用方法：**
-
-1. 打开 Trae 项目设置
-2. 找到 "Knowledge Sources" 配置
-3. 添加 `http://192.168.164.27:3200/llms-full.txt`
-4. 启用该知识源
-
-<a href="https://trae.ai/docs" target="_blank">详细了解 Trae 的知识源功能</a>
-
----
-
-### Qoder
-
-在 Qoder 中，可以在 `.qoder/config.yml` 中添加 LLMs.txt 作为外部知识文件，或在对话中通过 `@docs` 进行临时引用。
-
-**使用方法 1：配置文件**
-
-在项目根目录创建 `.qoder/config.yml`：
-
-```yaml
-knowledge:
-  external_docs:
-    - url: http://192.168.164.27:3200/llms-full.txt
-      name: YSS UI Documentation
-```
-
-**使用方法 2：临时引用**
-
-```
-@docs http://192.168.164.27:3200/llms-full.txt
-```
-
-<a href="https://docs.qoder.com/" target="_blank">详细了解 Qoder 配置方法</a>
-
----
-
-### 其他 AI 工具
-
-任何支持 LLMs.txt 的 AI 工具均可使用以上路径来更好地理解 YSS UI。
-
-<!-- ## 本地开发
-
-如果你在本地开发环境中使用 AI 工具，推荐使用完整文档：
-
-```
-http://localhost:8000/llms-full.txt
-```
-
-如果遇到上下文限制，可以降级使用：
-```
-http://localhost:8000/llms.txt -->
-```
-
-## 最佳实践建议
-
-### 选择合适的文件
-
-**大多数情况：使用 llms-full.txt** ✅
-- 开发新功能、编写业务代码
-- 需要 AI 提供准确的 API 用法
-- 学习组件库的使用方式
-
-**特殊情况：使用 llms.txt**
-- AI 工具报告上下文窗口不足
-- 只需要快速查找组件名称
-- 网络环境较差，需要减少传输量
-
-### 如何验证 AI 已正确加载文档
-
-询问 AI 一些特定的问题来验证：
-
-```
-Q: YTable 组件的 pagination 属性支持哪些配置项？
-Q: YssFormily 的 mode 属性有哪些可选值？各代表什么含义？
-Q: 如何使用 YTree 组件的搜索功能？
-```
-
-如果 AI 能准确回答这些问题并提供符合实际 API 的代码示例，说明文档已成功加载。
-
-## 自动更新
-
-LLMs.txt 文件会在每次 CI/CD 构建时自动生成和更新，确保 AI 工具始终访问到最新的文档。
-
-如需手动重新生成，可以运行：
-
-```bash
-pnpm run generate:llms
-```
-
-## 常见问题
-
-### Q: llms.txt 和 llms-full.txt 有什么区别？应该用哪个？
-
-**A:** 
-- **推荐使用 `llms-full.txt`**（71KB）- 包含完整的 API 文档、Props、Events、示例代码，让 AI 生成更准确的代码
-- `llms.txt`（1.6KB）- 仅包含组件列表和链接，适合上下文窗口受限的场景
-
-现代 AI 工具（Claude、GPT-4、Gemini 等）完全支持 `llms-full.txt` 的大小，优先使用它能获得更好的代码生成效果。
-
-### Q: 如何确认 AI 工具已成功加载文档？
-
-**A:** 
-你可以直接询问 AI 工具关于 YSS UI 特定组件的问题，如果它能准确回答并提供符合实际 API 的代码示例，说明已成功加载。
-
-### Q: 文档更新后 AI 工具没有获取到最新内容？
-
-**A:** 
-某些 AI 工具会缓存文档内容。尝试：
-1. 重新加载文档引用
-2. 清除 AI 工具缓存
-3. 使用新的会话窗口
-
-## 反馈与建议
-
-如果你在使用 AI 工具集成时遇到问题，或有改进建议，欢迎：
-
-- 提交 Issue 到项目仓库
-- 联系技术支持团队

package/template/.hermes/skills/yss-ui/assets/docs/guide/monorepo-versioning.md

@@ -1,149 +0,0 @@
-# Monorepo 版本管理说明
-
-## ⚠️ 当前方案的限制
-
-### 问题：所有包同步发版
-
-当前我们使用 `standard-version` 配置了统一的版本管理，这导致：
-
-```javascript
-// .versionrc.js
-bumpFiles: [
-  { filename: 'package.json' },
-  { filename: 'packages/components/package.json' },  // ← 所有包
-  { filename: 'packages/hooks/package.json' },       // ← 都会同步
-  { filename: 'packages/utils/package.json' },       // ← bump 版本
-  { filename: 'packages/theme/package.json' },
-]
-```
-
-**影响**：
-- ✅ 优点：版本号统一管理，简单清晰
-- ❌ 缺点：即使只修改了 `hooks`，`components`、`utils` 等所有包的版本号都会一起更新
-
-### 示例
-
-```bash
-# 提交了一个 hooks 的新功能
-git commit -m "feat(hooks): useFullscreen 新增功能"
-
-# 执行发版后
-pnpm release:minor
-
-# 结果：所有包版本号都从 1.0.3 升级到 1.0.4
-- @yss-ui/components: 1.0.3 → 1.0.4  (但实际没有修改)
-- @yss-ui/hooks: 1.0.3 → 1.0.4       (实际修改的包)
-- @yss-ui/utils: 1.0.3 → 1.0.4       (但实际没有修改)
-```
-
----
-
-## 💡 解决方案（可选）
-
-如果需要独立管理各个包的版本号，有以下选择：
-
-### 方案 1：使用 Lerna + Conventional Commits
-
-```bash
-# 安装 Lerna
-pnpm add -D lerna
-
-# 配置 lerna.json
-{
-  "version": "independent",  // 独立版本模式
-  "command": {
-    "version": {
-      "conventionalCommits": true,
-      "message": "chore(release): publish"
-    }
-  }
-}
-
-# 发版命令
-lerna version --conventional-commits
-```
-
-**特点**：
-- ✅ 只更新有变更的包
-- ✅ 自动生成 CHANGELOG
-- ✅ 支持独立版本号
-- ❌ 配置相对复杂
-
-### 方案 2：使用 Changeset
-
-```bash
-# 安装 Changeset
-pnpm add -D @changesets/cli
-
-# 初始化
-pnpm changeset init
-
-# 工作流
-pnpm changeset       # 创建变更文件
-pnpm changeset version  # 消费变更并 bump 版本
-pnpm changeset publish  # 发布包
-```
-
-**特点**：
-- ✅ 精确控制哪些包需要发版
-- ✅ 支持独立版本号
-- ✅ 社区广泛使用
-- ❌ 需要手动创建 changeset 文件
-
-### 方案 3：保持当前方案（推荐 ⭐）
-
-如果你们的发版策略是：
-- 各个包通常一起发版
-- 版本号保持同步
-- 简化管理流程
-
-那么 **当前方案已经足够**，无需改动。
-
----
-
-## 🔧 当前方案的使用建议
-
-### 1. 版本号语义
-
-即使所有包都同步 bump，但更新日志中会清晰标注哪个包有真实变更：
-
-```markdown
-## v1.0.4
-
-### ✨ Features
-- **[@yss-ui/hooks]** useFullscreen: 新增 Esc 键提示功能
-
-### 🐞 Bug Fixes
-(empty - components 和 utils 没有实际变更)
-```
-
-### 2. 发版时机
-
-建议按照实际需求发版：
-- **Patch** (1.0.0 → 1.0.1)：Bug 修复
-- **Minor** (1.0.0 → 1.1.0)：新功能
-- **Major** (1.0.0 → 2.0.0)：破坏性更新
-
-### 3. npm 发布策略
-
-如果发布到 npm，可以配置 Lerna 的 `--force-publish` 避免发布没有变更的包：
-
-```bash
-# 只发布有变更的包
-lerna publish from-package --no-git-tag-version
-```
-
----
-
-## 📝 总结
-
-| 方案 | 版本管理 | 复杂度 | 适用场景 |
-|------|---------|--------|---------|
-| **当前方案** (standard-version) | 统一版本号 | ⭐ 简单 | 各包同步发版 |
-| **Lerna** | 独立版本号 | ⭐⭐⭐ 中等 | 需要独立管理版本 |
-| **Changeset** | 独立版本号 | ⭐⭐⭐⭐ 复杂 | 精确控制发版范围 |
-
-**建议**：
-- 如果当前工作流没有问题，保持现状即可
-- 如果需要独立版本管理，可以考虑引入 Changeset
-- 定期检查发版日志，确保每次发版都有相应的代码变更

package/template/.hermes/skills/yss-ui/assets/docs/guide/release-workflow.md

@@ -1,251 +0,0 @@
-# YSS UI 发版工作流指南
-
-## 📋 Commit Message 规范（必须遵守）
-
-### 格式
-
-```
-<type>(<scope>): <subject>
-
-[可选的 body]
-
-[可选的 footer]
-```
-
-### Type 类型
-
-| Type | Emoji | 说明 | 示例 |
-|------|-------|------|------|
-| `feat` | ✨ | 新功能 | `feat(@yss-ui/components): Table 新增远程筛选功能` |
-| `fix` | 🐞 | Bug 修复 | `fix(@yss-ui/hooks): useFullscreen 修复 iOS 兼容性` |
-| `docs` | 📝 | 文档更新 | `docs(components): 更新 Table 组件文档` |
-| `style` | 💅 | 代码格式 | `style(@yss-ui/components): 统一组件代码缩进` |
-| `refactor` | 🛠 | 重构 | `refactor(@yss-ui/hooks): 优化 useLoading 实现` |
-| `perf` | ⚡ | 性能优化 | `perf(@yss-ui/utils): 优化 formatDate 性能` |
-| `test` | ✅ | 测试 | `test(@yss-ui/components): 添加 Table 单元测试` |
-| `build` | 📦 | 构建系统 | `build: 升级 vite 到 5.0` |
-| `ci` | 🔧 | CI 配置 | `ci: 更新 GitLab CI 配置` |
-| `chore` | 🔨 | 其他 | `chore: 更新依赖包` |
-
-### Scope 范围
-
-- `@yss-ui/components` 或 `components` - 组件库
-- `@yss-ui/hooks` 或 `hooks` - Hooks 库
-- `@yss-ui/utils` 或 `utils` - 工具库
-- `@yss-ui/theme` 或 `theme` - 主题配置
-- `docs` - 文档
-- `scripts` - 脚本
-- `config` - 配置文件
-- `deps` - 依赖更新
-
-### 示例
-
-**✅ 正确示例**：
-
-```bash
-# 新功能
-git commit -m "feat(@yss-ui/components): Table 支持虚拟滚动"
-git commit -m "feat(@yss-ui/hooks): 新增 useDebounce Hook"
-
-# Bug 修复
-git commit -m "fix(@yss-ui/components): Table 修复空数据时的报错"
-git commit -m "fix(@yss-ui/utils): formatDate 修复时区问题"
-
-# 文档更新
-git commit -m "docs(components): 更新 Table API 文档"
-git commit -m "docs(hooks): 添加 useFullscreen 使用示例"
-
-# 重构
-git commit -m "refactor(@yss-ui/hooks): useLoading 采用模块化结构"
-
-# 多行 commit message（使用编辑器）
-```
-feat(@yss-ui/components): Table 新增远程筛选功能
-
-- 支持服务端分页
-- 支持多字段筛选
-- 新增 filterMethod 配置项
-
-Closes #123
-```
-```
-
-**❌ 错误示例**：
-
-```bash
-# 缺少 scope
-git commit -m "feat: 添加新功能"
-
-# type 错误
-git commit -m "add: 新增功能"
-
-# scope 不在枚举中
-git commit -m "feat(table): 新增功能"
-
-# 以句号结尾
-git commit -m "feat(@yss-ui/components): 新增功能。"
-```
-
----
-
-## 🚀 发版流程
-
-### 本地发版（推荐）
-
-```bash
-# 步骤 1: 确保本地代码最新
-git pull origin main
-
-# 步骤 2: 选择发版类型
-
-# 发布补丁版本 (1.0.0 -> 1.0.1) - 修复 bug
-pnpm release:patch
-
-# 发布次版本 (1.0.0 -> 1.1.0) - 新增功能，向下兼容
-pnpm release:minor
-
-# 发布主版本 (1.0.0 -> 2.0.0) - 破坏性更新
-pnpm release:major
-
-# 首次发版（不改变版本号，只生成日志和 tag）
-pnpm release:first
-
-# 步骤 3: 脚本自动执行以下操作
-# - 根据 commit 历史生成 docs/changelog.md
-# - bump 所有 package.json 的版本号
-# - 创建 git commit 和 tag
-# - 等待你确认推送
-
-# 步骤 4: 检查生成的日志
-git diff HEAD~1 docs/changelog.md
-
-# 步骤 5: 如果满意，推送到远程
-git push --follow-tags origin main
-
-# 步骤 6: 在 GitLab UI 点击「手动发版」按钮触发 CI/CD
-```
-
-### GitLab CI 自动发版
-
-如果配置了 GitLab CI，可以自动化整个流程：
-
-```yaml
-# .gitlab-ci.yml 示例
-release:
-  stage: release
-  only:
-    - main
-  when: manual
-  script:
-    - git config user.name "GitLab CI"
-    - git config user.email "ci@gitlab.com"
-    - pnpm release  # 自动检测版本类型
-    - git push --follow-tags origin main
-```
-
----
-
-## 📝 更新日志管理
-
-### 自动生成规则
-
-standard-version 会根据 commit message 自动生成更新日志：
-
-1. **Type 映射**：
-   - `feat` → ✨ Features
-   - `fix` → 🐞 Bug Fixes
-   - `docs` → 📝 Documentation
-   - `refactor` → 🛠 Refactoring
-   - `style` → 💅 Style
-
-2. **Scope 转换**：
-   - `@yss-ui/components` → `[@yss-ui/components]`
-   - `components` → `[@yss-ui/components]`
-   - `@yss-ui/hooks` → `[@yss-ui/hooks]`
-   - `hooks` → `[@yss-ui/hooks]`
-
-3. **分包日志**：
-   - 自动从综合日志提取各包的更新
-   - 生成 `docs/changelog/{components,hooks,utils}.md`
-
-### 手动调整日志
-
-如果自动生成的日志需要调整：
-
-```bash
-# 1. 发版后手动编辑综合日志
-vim docs/changelog.md
-
-# 2. 手动更新分包日志
-vim docs/changelog/hooks.md
-vim docs/changelog/components.md
-vim docs/changelog/utils.md
-
-# 3. 修正 commit（如果还没推送）
-git add docs/changelog*
-git commit --amend --no-edit
-
-# 4. 推送
-git push --follow-tags origin main
-```
-
----
-
-## 🔧 常见问题
-
-### Q: Commit message 格式错误怎么办？
-
-A: Husky 的 commit-msg hook 会自动检查格式，不符合规范的 commit 会被拒绝：
-
-```bash
-$ git commit -m "add new feature"
-⧗   input: add new feature
-✖   subject may not be empty [subject-empty]
-✖   type may not be empty [type-empty]
-```
-
-修正方式：
-```bash
-git commit -m "feat(@yss-ui/components): Table 新增远程筛选功能"
-```
-
-### Q: 如何撤销错误的发版？
-
-A: 使用 Git 回退：
-
-```bash
-# 回退到上一个版本
-git reset --hard HEAD~1
-
-# 删除错误的 tag
-git tag -d v1.0.1
-git push origin :refs/tags/v1.0.1
-```
-
-### Q: 如何跳过某些 commit？
-
-A: 在 commit message 中添加 `[skip ci]` 或使用 `chore` type：
-
-```bash
-git commit -m "chore: 更新 README (不会出现在 changelog 中)"
-```
-
-### Q: 如何添加 Breaking Changes？
-
-A: 在 commit message 中添加 `BREAKING CHANGE:`：
-
-```bash
-git commit -m "feat(@yss-ui/components): 重构 Table API
-
-BREAKING CHANGE: `columns` 属性不再支持字符串数组
-"
-```
-
----
-
-## 📚 参考资源
-
-- [Conventional Commits 规范](https://www.conventionalcommits.org/)
-- [Semantic Versioning](https://semver.org/lang/zh-CN/)
-- [standard-version 文档](https://github.com/conventional-changelog/standard-version)
-- [commitlint 文档](https://commitlint.js.org/)