feat: 新增组件样式结构(Semantic)文档,完善面向 AI Coding 的站点接入#3496
Open
alvinhui wants to merge 13 commits into
Open
Conversation
- Introduced a new script `build-meta.mjs` to aggregate component metadata from various sources. - Added a new command `generate:meta` in `package.json` to run the metadata generation. - Created `meta/components.json` to store the generated component metadata, including categories and global tokens.
- Replaced direct comparison of import.meta.url with pathToFileURL for improved URL handling.
# Conflicts: # .gitignore # scripts/build-llms.mjs # scripts/site/vite-plugin-llms.mjs
github-actions
Bot
added
the
action:review
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Walkthrough本次变更新增组件样式语义数据生成流程，将语义信息接入 LLM 文档产物，并为 React、Taro 站点增加 AI 文档路由、导航入口及中英文使用说明。 Changes语义文档与 AI 站点
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant Prebuild
participant SemanticGenerator
participant LlmsPlugin
participant Site
Prebuild->>SemanticGenerator: 执行 generate:semantic
SemanticGenerator->>SemanticGenerator: 生成 semantic.json
LlmsPlugin->>SemanticGenerator: 读取语义数据
LlmsPlugin->>Site: 提供 llms-semantic 与组件 semantic.md
Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## feat_v4.x #3496 +/- ##
=============================================
+ Coverage 88.33% 88.44% +0.10%
=============================================
Files 295 296 +1
Lines 19747 19812 +65
Branches 3117 3134 +17
=============================================
+ Hits 17443 17522 +79
+ Misses 2298 2284 -14
Partials 6 6 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
scripts/build-llms.mjs (1)
111-128: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
generateLlmsTxt与generateLlmsFull的 Semantic 标题不一致。
generateLlmsTxt第 114 行使用样式结构 (Semantic)，而generateLlmsFull第 143 行使用样式结构 (Semantic DOM)。两处指向同一类文档，标题用词不统一可能造成使用者困惑。建议统一为样式结构 (Semantic)或样式结构 (Semantic DOM)。🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/build-llms.mjs` around lines 111 - 128, 统一 generateLlmsTxt 与 generateLlmsFull 中 Semantic 文档分区的标题文本；将两处标题都改为同一表述，建议使用“样式结构 (Semantic)”，并检查相关生成内容保持一致。scripts/build-semantic.mjs (1)
152-163: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
emptyComps命名有误导性。该过滤器选出的是「有 token 但无 class」的组件，并非「空组件」。建议更名为
tokenOnlyComps以准确表达含义，避免后续维护者误解。♻️ 建议的重命名
- emptyComps: validIds.filter( + tokenOnlyComps: validIds.filter( (id) => !classesByComp[id]?.length && (meta.components[id].tokens || []).length ),并在
main()中相应更新日志输出：- if (stats.emptyComps.length) { + if (stats.tokenOnlyComps.length) { console.log( - ` 仅 token 无 class 的组件 (${stats.emptyComps.length}): ${stats.emptyComps.join(', ')}` + ` 仅 token 无 class 的组件 (${stats.tokenOnlyComps.length}): ${stats.tokenOnlyComps.join(', ')}` ) }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/build-semantic.mjs` around lines 152 - 163, Rename the stats field emptyComps to tokenOnlyComps in the stats construction and update all references, including the corresponding log output in main(), while preserving the existing filter logic for components with tokens but no classes.scripts/site/vite-plugin-llms.mjs (1)
82-87: 🚀 Performance & Scalability | 🔵 Trivial | 💤 Low valueDev 中间件每次请求都重新读取磁盘文件。
collectFiles(platform)在configureServer中间件内被每次请求调用，会重复执行loadMeta()、tryLoadSemantic()及collectLlmsFiles()的磁盘读取和文档生成。对于 dev server 而言可以接受，但如果组件数量较多，可以考虑添加简单的内存缓存（如基于文件 mtime 或 Vite 的server.watcher触发刷新）以提升开发体验。🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/site/vite-plugin-llms.mjs` around lines 82 - 87, 在开发中间件处理逻辑中为 collectFiles(platform) 增加内存缓存，避免每次请求重复执行 loadMeta()、tryLoadSemantic() 和 collectLlmsFiles() 的磁盘读取与文档生成；可按平台缓存结果，并利用文件修改时间或 server.watcher 事件使缓存失效后重新生成。src/sites/sites-react/doc-taro/router.ts (1)
51-51: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win正则
exec结果的空值安全
RegExp.exec()可能返回null，as any[]类型断言掩盖了这一风险。如果 glob 返回的路径不符合预期正则模式，[1]会抛出TypeError。虽然 glob 约束了文件路径使实际触发概率较低，但仍建议加入空值保护。♻️ 建议的改进
- let name = (/docs\/ai-taro\/(.*).md/.exec(path) as any[])[1]; + const match = /docs\/ai-taro\/(.*).md/.exec(path); + if (!match) continue; + const name = match[1];对第二个循环（line 60）同理：
- let name = (/docs\/ai-taro\/(.*).en-US.md/.exec(path) as any[])[1]; + const match = /docs\/ai-taro\/(.*).en-US.md/.exec(path); + if (!match) continue; + const name = match[1];Also applies to: 60-60
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/sites/sites-react/doc-taro/router.ts` at line 51, 在路由路径解析逻辑中为两个 RegExp.exec 调用加入空值保护，避免匹配失败时直接访问 [1] 导致 TypeError；移除 let name 和对应解析表达式上的 as any[]，并在继续使用捕获组前处理 null（例如跳过该路径或采用安全回退值）。
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/build-semantic.mjs`:
- Around line 34-52: 在 extractClasses 中构造 Sass entry 前，将 VARIABLES_PATH 和
scssPath 统一转换为 POSIX 路径格式，把反斜杠替换为正斜杠后再拼入两个 `@import`，确保 Windows 路径不会被 Sass 误解析。
---
Nitpick comments:
In `@scripts/build-llms.mjs`:
- Around line 111-128: 统一 generateLlmsTxt 与 generateLlmsFull 中 Semantic
文档分区的标题文本；将两处标题都改为同一表述，建议使用“样式结构 (Semantic)”，并检查相关生成内容保持一致。
In `@scripts/build-semantic.mjs`:
- Around line 152-163: Rename the stats field emptyComps to tokenOnlyComps in
the stats construction and update all references, including the corresponding
log output in main(), while preserving the existing filter logic for components
with tokens but no classes.
In `@scripts/site/vite-plugin-llms.mjs`:
- Around line 82-87: 在开发中间件处理逻辑中为 collectFiles(platform) 增加内存缓存，避免每次请求重复执行
loadMeta()、tryLoadSemantic() 和 collectLlmsFiles() 的磁盘读取与文档生成；可按平台缓存结果，并利用文件修改时间或
server.watcher 事件使缓存失效后重新生成。
In `@src/sites/sites-react/doc-taro/router.ts`:
- Line 51: 在路由路径解析逻辑中为两个 RegExp.exec 调用加入空值保护，避免匹配失败时直接访问 [1] 导致 TypeError；移除
let name 和对应解析表达式上的 as any[]，并在继续使用捕获组前处理 null（例如跳过该路径或采用安全回退值）。
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 0f3956b7-7858-4611-b7f0-f0cf2d2a5d23
📒 Files selected for processing (16)
.gitignorepackage.jsonscripts/build-llms.mjsscripts/build-semantic.mjsscripts/site/vite-plugin-llms.mjssrc/sites/config/baseConfig.tssrc/sites/sites-react/doc-taro/App.tsxsrc/sites/sites-react/doc-taro/router.tssrc/sites/sites-react/doc/App.tsxsrc/sites/sites-react/doc/components/header/header.tsxsrc/sites/sites-react/doc/components/nav/nav.tsxsrc/sites/sites-react/doc/docs/ai-react/llms.en-US.mdsrc/sites/sites-react/doc/docs/ai-react/llms.mdsrc/sites/sites-react/doc/docs/ai-taro/llms.en-US.mdsrc/sites/sites-react/doc/docs/ai-taro/llms.mdsrc/sites/sites-react/doc/router.ts
Co-Authored-By: Claude <noreply@anthropic.com>
alvinhui
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
功能说明
在已有 LLMs 文档能力基础上：
主要变更
一、补齐样式结构(Semantic)事实源
1. 新增 semantic 生成脚本
scripts/build-semantic.mjsvariables.scss),用 postcss 提取全部.nut-*class@import共享 class 的去重(判给更具体的子组件)nut-countup-*→animatingnumbers)nut-img→image)meta/semantic.json(样式结构事实源)llms-semantic-cn.txt/llms-semantic.txt(中英聚合单文件)nut-rtl)记为 orphan 丢弃2. 扩展
scripts/build-llms.mjsllms.txt索引与llms-full中接入 semantic 链接与「样式结构」分区semantic.json避免与 build-semantic 循环依赖;未生成时优雅跳过而非报错3. 扩展
scripts/site/vite-plugin-llms.mjscomponents/<id>/semantic.md二、站点接入 AI 文档
router.ts挂载ai-react/ai-taro中英路由,App.tsx注入对应 routesbaseConfig.ts增加 AI 导航项llms.md(react / taro × 中 / 英),介绍 LLMs.txt 用法与 AI 工具接入方式构建流程
package.jsongenerate:semantic脚本prebuild:site/prebuild:taro:site,顺序为generate:meta → generate:semantic → generate:llms产物与使用
llms.txtllms-full-cn.txt/llms-full.txtllms-semantic-cn.txt/llms-semantic.txtcomponents/<id>.mdcomponents/<id>/semantic.mdmeta/全目录为构建产物,不落库(已在.gitignore中说明)。验证点
npm run generate:semantic全部 scss 编译成功、无异常 orphannpm run build:site/build:taro:site正常产出 semantic 虚拟文件llms-semantic*.txt、components/<id>/semantic.md均可访问)Summary by CodeRabbit