feat: 新增面向 AI Coding 的 LLMs 文档生成#3495
Open
alvinhui wants to merge 7 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.
github-actions
Bot
added
the
action:review
alvinhui
changed the title
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
Walkthrough新增元数据聚合脚本与 llms 文档产物生成脚本，并将相关产物接入 Vite 文档站构建/开发流程，同时补充对应 npm 脚本与忽略规则。 ChangesLLM 文档生成与集成
Estimated code review effort: 3 (Moderate) | ~25 minutes 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
scripts/site/vite-plugin-llms.mjs (1)
58-76: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick windev 模式下每次请求都重新调用
collectFiles()读取全部文件
collectFiles()会读取meta/components.json、所有组件doc.md，并调用generateLlmsFull拼接两份全量文档。在 dev 模式下，每次命中 llms 路由的请求都触发完整的磁盘 I/O 和字符串拼接，组件数量较多时会有明显延迟。建议在 dev 中间件内加一层简单的内存缓存，配合
server.watcher在meta/components.json或doc.md变更时失效：♻️ 基于 watcher 的缓存方案
configureServer(server) { const base = SITE_BASE.replace(/\/$/, '') + let cache = null + const invalidate = () => { cache = null } + server.watcher.add(path.join(ROOT, 'meta/components.json')) + server.watcher.on('change', (f) => { + if (f.endsWith('meta/components.json') || f.endsWith('.md')) invalidate() + }) server.middlewares.use((req, res, next) => { // ... existing URL parsing ... if (!isTarget) return next() - const files = collectFiles() + if (!cache) cache = collectFiles() + const files = cache if (!(key in files)) return next() res.setHeader('Content-Type', contentType(key)) res.end(files[key]) })🤖 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 58 - 76, The dev middleware in configureServer is rebuilding llms content on every request by calling collectFiles(), which causes repeated disk I/O and expensive generation work. Add a simple in-memory cache around the file map used by the middleware, and invalidate that cache from server.watcher when meta/components.json or any component doc.md changes. Keep the routing logic in configureServer unchanged, but make the request path read from the cached result instead of recomputing it each time.
🤖 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-llms.mjs`:
- Around line 70-89: The full-document generator in generateLlmsFull currently
hardcodes SUMMARY, so the English output mixes an English title with a Chinese
summary. Add a language-specific summary constant or mapping and switch the
block that builds parts in generateLlmsFull based on lang (alongside the
existing title selection) so generateLlmsFull(meta, 'enUS') uses an English
summary while other locales keep the current Chinese text.
- Around line 111-113: 入口判断在 Windows 下会因为 file URL 格式不匹配而失效，导致 main() 不执行；请在
scripts/build-llms.mjs 的入口检测逻辑中，将 import.meta.url 与通过
pathToFileURL(process.argv[1]).href 生成的 URL 进行比较，确保跨平台一致。定位时关注 main() 以及当前的
import.meta.url 条件判断。
In `@scripts/build-meta.mjs`:
- Around line 141-148: The parseTokens default-value handling is stripping a
trailing right parenthesis from already complete values, which breaks
function-style CSS defaults. In parseTokens inside build-meta.mjs, remove the
extra .replace(/\)\s*$/, '') cleanup when deriving def from m[3], and keep the
captured default value intact so tokens like rgba(...), scale-px(...), and
var(...) remain valid in meta/components.json.
---
Nitpick comments:
In `@scripts/site/vite-plugin-llms.mjs`:
- Around line 58-76: The dev middleware in configureServer is rebuilding llms
content on every request by calling collectFiles(), which causes repeated disk
I/O and expensive generation work. Add a simple in-memory cache around the file
map used by the middleware, and invalidate that cache from server.watcher when
meta/components.json or any component doc.md changes. Keep the routing logic in
configureServer unchanged, but make the request path read from the cached result
instead of recomputing it each time.
🪄 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: 8e43d8b2-95da-416d-b942-8abb97708b3e
📒 Files selected for processing (7)
.gitignoremeta/components.jsonpackage.jsonscripts/build-llms.mjsscripts/build-meta.mjsscripts/site/vite-plugin-llms.mjsvite.config.site.mts
- Replaced direct comparison of import.meta.url with pathToFileURL for improved URL handling.
Collaborator
|
1、meta的数据只能这么大么，有没有其他方式 |
Author
|
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
2 participants
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.
🤔 这个变动的性质是？
🔗 相关 Issue
面向 AI Coding 的能力调研与落地方案
第一步（统一元数据层）+ 第二步（llms.txt 文档入口），落地方案 P0 阶段。
💡 需求背景和解决方案
背景
大模型训练数据有截止时间，而组件库 API 持续演进，AI Coding Agent（Copilot / Cursor / Claude
Code）基于"记忆"生成代码时会出现 API 幻觉、版本错配、约定缺失 三类问题。业界解法（如 Ant
Design）不是训练更好的模型，而是给 Agent
提供一套权威、离线、可程序化查询的事实源，把"猜"变成"查"。
本 MR 落地该方案的地基两步（P0）：统一元数据层 + llms.txt 文档入口，且覆盖 NutUI
差异化的 H5 / Taro 双端。
方案
① 统一元数据层（单一事实源）
新增
scripts/build-meta.mjs，以src/config.json为遍历入口，聚合四处分散数据为一份自描述、机器友好的中间产物
meta/components.json：config.json第一~四列语义化为prop/desc/type/default，按表分组并标注kind）←
scripts/properties.jsondemos/{h5,taro}/*.tsx）、四语言/端文档路径、DesignToken（按最长前缀归属组件）
覆盖 106 个组件（85 个含 API 表、105 个全局 Token），后续 llms.txt / CLI / MCP
全部读这一份，改一处全链路生效。
② llms.txt 文档入口（H5 + Taro 双端）
新增
scripts/build-llms.mjs+scripts/site/vite-plugin-llms.mjs，读 meta 产出遵循llmstxt.org 标准的文档入口：
llms.txt—— 导航索引（H1 → 摘要 → 分类 → 各组件.md链接）llms-full-cn.txt/llms-full.txt—— 全部文档拼接单文件，可整体注入上下文.md路由 —— 构建时经emitFile落到<base>/components/<id>.md，dev时中间件实时返回，供 Agent 按需精确拉取纯文档原文
双端参数化：通过⚠️ Taro 站严格使用 Taro 端文档而非复用
PLATFORMS配置区分 H5（/h5/react/4x，用doc.md，含中英文）与Taro（
/taro/react/4x，用doc.taro.md，仅中文）。H5——两端存在实质 API 差异（包名
@nutui/nutui-react-taro、按钮类型 6 vs 7种等），复用会给小程序端 AI 喂错 API。
③ 工程约定：产物不落库，构建时自动生成
meta 及 llms 均为派生产物，不进 git：
.gitignore忽略整个/meta/package.json新增prebuild:site/prebuild:taro:site钩子，build:site/build:taro:site前自动generate:meta && generate:llms，CI 无需改动验证（清空 meta 从零构建）
button.md导入语句@nutui/nutui-react@nutui/nutui-react-taro/h5/react/4x/taro/react/4x交叉验证两端
button.md内容确实不同（各取对应端文档）。涉及文件
scripts/build-meta.mjs（新增）—— 元数据聚合器scripts/build-llms.mjs（新增）—— llms 产物生成器，双端参数化scripts/site/vite-plugin-llms.mjs（新增）—— 站点构建/dev 期产出单组件 md 与 llms 文件vite.config.site.mts/vite.config.site.taro.mts—— 挂载插件（分别传 platform: h5 /taro）
package.json—— generate:meta / generate:llms 脚本 + prebuild 钩子.gitignore—— 忽略 /meta/ 派生产物☑️ 请求合并前的自查清单