【阻力 1】Cursor 批量生成组件 Schema

完全可以，而且这正是目前大厂前端架构师在推进“组件标准化”时效率最高、最接地气的落地方式。你提到的这个思路非常赞，因为它巧妙地避开了自己从零去写大模型批处理脚本的开发成本，直接复用了 Cursor 强大的本地上下文理解能力。但在实际操作中，不能只是简单地对 Cursor 说一句“帮我生成 Schema”，必须配合结构化的 Prompt（提示词模板）和 Cursor 的高级功能，才能生成真正能给低代码引擎消费的高质量文档。以下是利用 Cursor 高效生成规范 Schema 的具体实操指南：

一、核心技巧：编写一份“主厨级”的 Prompt 模板

Cursor 底层使用的是 Claude 3.5 Sonnet 或 GPT-4o，它们对代码的理解能力极强，但对“JSON Schema 的格式要求”需要非常明确的规范。你可以在项目的根目录下创建一个 .cursorrules 文件，或者在和 Cursor 对话（Ctrl + K 或 Chat 侧边栏）时，直接丢给它下面这段黄金提示词（Prompt）：

Role: 你是一个极其严苛的前端架构师和低代码专家。
Task: 请阅读我选中的 TypeScript 组件源码，为该组件生成一份用于低代码引擎消费的 schema.json。
Specification:

1. 严格符合 JSON Schema 草案规范。
2. 必须深度解析 TS Props 类型。遇到外部 import 的类型，请结合上下文推断。
3. 属性描述 (description)：必须是高质量、大白话的中文业务描述，写明该属性在电商活动中的具体作用（例如：不要写“按钮类型”，要写“大促按钮的视觉风格，如爆款红、高亮黄”）。
4. 约束挖掘 (enum/default)：请深度阅读组件内部的 if/else、switch 或样式逻辑，挖掘出隐藏的枚举值（enum）和默认值（default）。
5. 输出格式：只返回纯 JSON 块，不要任何解释，不要 Markdown 包装。

二、借助 Cursor 的高级功能破除“依赖盲区”

前面提到过，纯模型处理最大的痛点是“顺藤摸瓜”，即组件引了外部文件的类型，模型看不见。在 Cursor 中，我们可以通过以下两个功能完美解决：

使用 @Files 或 @Folders 喂入上下文：在 Chat 面板中，不要只选中当前组件。使用 @ 符号，把组件依赖的 types.ts 或者公共定义文件一起加入到上下文。
- 示例：@LiveCountdown.tsx @global-types.ts 请按照规则生成 schema
利用 Composer 功能（Ctrl + I）进行批量重构：如果你想给整个组件库的所有文件批量在同级目录下生成 schema.json，可以使用 Cursor 的 Composer 模式。直接下达指令：

“遍历 src/components/ 目录下的所有 .tsx 文件，读取其类型，并在各自的同级目录下创建一个对应的 schema.json 说明书。”

Cursor 会自动开启多文件编辑流，挨个帮你创建和填满这些文件。

三、这样做依然存在的“坎”：如何做工程化卡点？

用 Cursor 代替自己写脚本，把研发效率提升了 10 倍，但从架构师的角度看，它依然属于“半自动/人工辅助”阶段。在团队多人协作时，需要注意以下两点：

防止开发人员“作弊”：有些组员用 Cursor 生成了 Schema 之后，自己偷偷改了组件代码（比如删掉了一个属性），但忘记让 Cursor 重新生成 Schema。这会导致线上的低代码引擎和 AI 拿到错误的说明书。
架构师的解法（CI 卡点）：虽然文档是用 Cursor 生成的，但前端架构师必须在 Git 提交阶段（使用 husky + lint-staged）或 GitLab CI 流程中，加一道静态自动化卡点测试——用脚本比对组件的 TS 类型和 schema.json 的字段数量是否一致。如果不一致，直接拒绝代码合并（MR），逼迫开发人员用 Cursor 重新生成。

四、Schema 向量化入库：切割维度与 MCP 按需召回

Cursor 批量生成 schema.json 只是资产生产阶段。要让 AI 在运行时「查得到、查得准、不撑爆上下文」，还必须设计 Chunk 切割策略 + 向量库索引 +（可选）MCP 精确回源。这与阻力 3 两阶段 RAG 直接对接。

1. 是否需要 MCP？什么时候用？

阶段	是否需要 MCP	说明
研发期：Cursor 批量生成 Schema	❌ 不需要	本地 `@Files` + Composer 已足够；MCP 无增量价值
运行时：低代码 AI 配置 Agent	✅ 强烈建议	向量库负责「模糊召回」，MCP 负责「精确取数」——按需拉完整 `schema.json` 片段，避免把几百个组件说明书全塞进 Prompt
预览 / 校验服务	⚠️ 可选	若已有 BFF 暴露 REST，可不单独建 MCP；MCP 的优势是 Agent 工具调用标准化、与 Cursor / Claude Code 生态一致

结论：MCP 不是 Schema 生成的必需品，而是 Schema 消费（RAG 第二阶段参数配置）的推荐基础设施。向量库解决「找哪个组件」，MCP 解决「这个组件有哪些合法字段、enum 是什么」。

[运营需求]
     │
     ▼
[阶段 1：向量检索] ── 召回 Top-K 组件卡片 Chunk（L1）
     │
     ▼
[阶段 2：MCP 精确回源] ── get_component_schema(id, props?) 拉 L2 属性 Chunk
     │
     ▼
[AI 填参] ── JSON Schema 校验 ── 写入 pageSchema

2. 切割维度：五层 Chunk 模型

切忌「整份 schema.json 一个向量」——几百行 JSON 语义稀释，召回精度差，且 Stage 2 仍要把整文件塞进上下文。按检索意图分层切割：

层级	Chunk 类型	切割粒度	向量化文本来源	主要服务阶段
L1	组件卡片（Catalog）	1 组件 = 1 Chunk	`title` + `description` + 业务分类 + 适用场景标签 + props 名列表摘要	阶段 1：组件级召回
L2	属性颗粒（Prop）	1 属性 = 1 Chunk	`propName` + `description` + `enum` 值中文释义 + `default` + 关联约束	阶段 2：参数级增强
L3	场景标签（Scenario）	1 场景 = 1 Chunk，可跨组件	「大促倒计时」「新人礼包」「满减联动」等运营语义 + 推荐组件 ID 列表	阶段 1 增强 / Open Design Palette
L4	配置案例（Example）	1 成功案例 = 1 Chunk	历史 `pageSchema` 片段 + 活动类型 + 转化率备注	阶段 2 Few-Shot
L5	约束摘要（Constraint）	1 组件内成组约束 = 1 Chunk	「theme 与 backgroundColor 互斥」「couponId 必填时 showTag 必开」等规则 prose	校验失败自愈 / 拦截幻觉

L1 + L2 是 MVP 必做；L3 对接阻力 4 preset 映射；L4/L5 可在组件库稳定后迭代。

L1 组件卡片 Chunk 示例（向量化正文）

组件：LiveCountdown（直播倒计时）
分类：营销 / 紧迫感
适用场景：大促首页、直播间引流、限时秒杀
能力摘要：支持国潮/黑金主题切换，可绑定优惠券 ID，倒计时结束触发跳转
属性概览：theme, endTime, couponId, jumpUrl, heroStyle

L2 属性颗粒 Chunk 示例

组件：LiveCountdown | 属性：theme
业务含义：大促倒计时的视觉主题，影响背景色与数字动画风格
合法枚举：default（标准红）| nationalTide（国潮）| darkGold（黑金高端）
默认值：default
注意：选 darkGold 时不应再手动传 backgroundColor，由主题包接管

每条 Chunk 的 metadata（用于混合检索过滤，不参与 embedding 或少量参与）：

{
  "chunk_type": "prop",
  "component_id": "LiveCountdown",
  "prop_path": "theme",
  "category": "marketing",
  "tags": ["大促", "倒计时", "国潮"],
  "schema_version": "2.1.0",
  "required": false
}

3. 切割流水线（CI 自动化，非 Cursor 手工）

schema.json (Git)
      │
      ▼
[Chunker 脚本] ── 按 L1～L5 规则拆分为 *.chunk.jsonl
      │
      ├──> [Embedding] ──> 向量库（Milvus / pgvector / Pinecone）
      │
      └──> [MCP Schema Store] ── 存原始 JSON 片段，供精确回源（不走向量）

触发时机：schema.json 变更合并 main 后，CI 自动 re-chunk + re-embed（与第三节 TS/Schema 字段数卡点同一流水线）。
版本戳：每个 Chunk 带 schema_version；MCP 回源时校验 Agent 持有的版本，避免旧向量 + 新 Schema 不一致。
禁止整文件 embedding：schema.json 原文只存 MCP / 对象存储，向量库只存 Chunk 正文 + metadata。

4. MCP Server 工具设计（与向量库配合）

建议暴露最小三个 Tool，与阻力 3 两阶段对齐：

Tool	用途	典型入参
`search_components`	阶段 1 组件召回（也可由向量库 REST 替代，MCP 统一入口）	`query`, `top_k`, `category?`
`get_component_schema`	阶段 2 精确拉 Schema	`component_id`, `props?: string[]`（只拉 L2 相关字段，省 Token）
`get_config_examples`	拉 L4 历史成功案例	`component_id`, `scenario?`, `limit?`

Agent 收到「我要国潮风倒计时」
  → search_components → LiveCountdown (score 0.89)
  → get_component_schema("LiveCountdown", ["theme", "endTime", "couponId"])
  → get_config_examples("LiveCountdown", "nationalTide", 2)
  → 生成 props JSON → JSON Schema 校验

MCP vs 纯 RAG：纯向量检索 L2 属性时，同名 prop（如各组件都有 theme）易混淆；先 L1 锁定 component_id，再 MCP 按 ID 取 L2，是标准做法（Atlassian ADS MCP 同款「Plan → Fetch detail」模式）。

5. 切割维度决策清单（架构师自检）

阶段 1 召回粒度：运营说的是「组件意图」还是「属性意图」？前者 L1，后者 L2（但仍需 L1 先过滤 component_id）。
Chunk 大小：L2 单条控制在 150～400 中文 token；过长则按 enum 拆子 Chunk。
Metadata 过滤维度：category（营销/商品/互动）、tags（大促/直播/新人）、platform（H5/小程序）、deprecated。
跨组件语义：L3 场景 Chunk 维护「运营黑话 → 组件 ID 列表」，与阻力 4 preset 共用一份源数据。
召回阈值：L1 score < 0.6 走阻力 3 拦截，不进入 MCP 填参。

五、组件增量更新：改属性 / 新增 / 弃用

组件库是持续演进的。一次 MR 可能只是改了一个 prop 的 enum，也可能是全新组件入库，或老组件进入弃用。若仍靠「全量 re-chunk + 全量 re-embed」，成本高且容易漏删脏向量；若不同步，则 AI 会拿旧说明书填参，线上 pageSchema 与 Runtime 脱节。

1. 三类变更与影响面

变更类型	典型例子	Schema	向量库 Chunk	MCP Store	存量 pageSchema
属性修改	`theme` 新增 `darkGold` enum；`couponId` 改 required	重生成该组件 `schema.json`	仅 upsert 受影响 L2；L1 若 props 摘要变了则 upsert	按 `schema_version` 覆盖该组件片段	旧值仍合法则不动；非法则编译/发布时报错
新增组件	新增 `DragonBoatGame`	新增 `schema.json`	insert 全套 L1 + L2（+ 可选 L3）	insert 新 `component_id`	无影响
弃用组件	`OldTurntable` 下线	标记 `deprecated`，暂不删文件	L1/L2 设 `deprecated: true`，从默认检索过滤；向量可保留或降权	保留只读，MCP 返回 `status: deprecated`	已有页面继续渲染；新配置禁止选用

原则：Git 里的 schema.json 是唯一真相源；向量库与 MCP 都是派生索引，必须能增量对齐 Git diff。

2. 变更检测：CI Diff Gate（比「字段数比对」更细）

第三节的「TS 字段数 vs Schema 字段数」只能拦「忘了重新生成」，拦不住「enum 改了但数量没变」。增量流水线建议叠加：

[MR 变更文件]
      │
      ▼
[TS Props AST Diff] ── 对比同名组件 props 增/删/改/rename
      │
      ▼
[schema.json Diff] ── 是否同步变更？未同步 → 拒绝 MR
      │
      ▼
[SemVer 自动 bump] ── 写入 schema.json 的 x-component-version
      │
      ▼
[增量 Chunk Diff] ── 算出 upsert / delete 清单

版本号规则（x-component-version）：

变更	版本 bump	示例
仅改 `description`、文档	PATCH	1.2.0 → 1.2.1
新增 optional prop、新增 enum 值	MINOR	1.2.1 → 1.3.0
删除/重命名 prop、改 required、弃用组件	MAJOR	1.3.0 → 2.0.0

Agent 与 MCP 回源时携带 schema_version；MAJOR 升级触发存量 pageSchema 迁移检查（见下文第 5 小节）。

3. 向量库增量同步策略

每条 Chunk 必须有稳定主键，便于 upsert / delete，禁止只用 auto-id：

chunk_id = {component_id}:{chunk_type}:{prop_path|scenario|example_id}

操作	触发条件	向量库动作
upsert	prop 新增/修改、L1 摘要变化	重算 embedding，覆盖同 `chunk_id`
delete	prop 删除、组件物理移除	按 `component_id` 前缀或精确 `chunk_id` 删除
deprecate	组件/mark prop 弃用	不删向量；metadata `deprecated: true`，检索默认 `filter deprecated=false`

CI 增量任务（仅 main 合并后）
  │
  ├─ git diff HEAD~1 -- '**/schema.json'
  │
  ├─ 对每个变更 component_id:
  │     ├─ 属性级 diff → upsert/delete L2 chunk_id 列表
  │     ├─ 组件级 summary 变 → upsert L1
  │     └─ deprecated 标记 → 更新 metadata，不 embed 新正文
  │
  └─ MCP Schema Store 同步同一份 diff（原子提交）

禁止「每晚全量重建向量库」作为唯一手段——可以作为每周兜底对账，但日常必须走增量。

4. 弃用组件治理（Soft Deprecation，禁止硬删）

大厂组件库不能因 AI 低代码上线就物理删除老组件：线上成百上千个历史活动页仍引用 OldTurntable。

推荐三阶段生命周期：

active ──(标记 deprecated)──> deprecated ──(观察期结束 + 迁移完成)──> removed

active：RAG / Open Design Palette 正常召回。
deprecated：
- schema.json 增加 "x-status": "deprecated"、"x-replaced-by": "NewTurntable"。
- 阻力 3 阶段 1 默认过滤；运营强搜时可提示「已弃用，推荐 NewTurntable」。
- MCP get_component_schema 仍返回 Schema（只读），顶部带 deprecationNotice。
- Runtime 继续渲染存量页面；新保存的 pageSchema 禁止插入该 component_id（编译器卡点）。
removed：确认无线上引用后，删 Git 文件 → CI delete 全部 Chunk + MCP 条目；MAJOR 版本升级。

schema.json 弃用标记示例：

{
  "x-component-id": "OldTurntable",
  "x-component-version": "3.0.0",
  "x-status": "deprecated",
  "x-deprecated-at": "2026-06-01",
  "x-replaced-by": "NewTurntable",
  "x-migration": {
    "propMap": { "prizeList": "awards", "spinDuration": "durationMs" }
  }
}

5. 存量 pageSchema 怎么办？

组件 Schema 变了，已发布的活动页不能 silently break。Schema Compiler 在发布 / 再编辑时做版本对齐：

Schema 变更	对存量 pageSchema 的处理
新增 optional prop	无感；缺省走 default
新增 enum 值	无感
删除 enum 值 / 删除 prop	编译报错 + 提示运营改配；或按 `x-migration.propMap` 自动 rename
组件 deprecated	允许渲染，禁止新引用；编辑保存时提示替换为 `x-replaced-by`
组件 removed	渲染降级为占位块 + 告警；阻断新发布

与阻力 7 双向同步衔接：AI 迭代时用 JSON Patch 改单个 prop，不要因组件 MINOR 升级就全量覆盖运营手工字段；MAJOR 升级才触发迁移向导。线上若仍异常，走阻力 8 L2/L3 发布回滚与熔断；pageSchema 内 schemaPins 与本节 x-component-version 对齐，回滚时随版本一并恢复。

6. 研发侧 Cursor 工作流（增量，非全库重跑）

场景	Cursor 指令示例
改了单个组件 props	`@Button.tsx` `@schema.json` 按规则增量更新 schema，保留未变 prop 的 description，bump MINOR
新增组件	`@NewBanner.tsx` 生成同级 `schema.json`，`x-status: active`，version `1.0.0`
弃用组件	不删 TS 源码；改 `schema.json` 的 `x-status` / `x-replaced-by`，Composer 批量更新 L3 场景 Chunk 中的推荐列表

MR 模板建议勾选：[] schema 已同步 [] version 已 bump [] 弃用已填 replaced-by。

🚀 迈向下一个里程碑

用 Cursor 批量生成好这成百上千个组件的 schema.json，再经 L1～L5 分层切割 + 向量入库 + MCP 按需回源（见上文第四节），组件说明书才算真正进入 AI 运行时。接下来必须面对【阻力 2：动态语义表达与跨组件联动】，以及【阻力 3：RAG 两阶段拦截】如何消费这些 Chunk。

一、核心技巧：编写一份“主厨级”的 Prompt 模板​

二、借助 Cursor 的高级功能破除“依赖盲区”​

三、这样做依然存在的“坎”：如何做工程化卡点？​

四、Schema 向量化入库：切割维度与 MCP 按需召回​

1. 是否需要 MCP？什么时候用？​

2. 切割维度：五层 Chunk 模型​

L1 组件卡片 Chunk 示例（向量化正文）​

L2 属性颗粒 Chunk 示例​

3. 切割流水线（CI 自动化，非 Cursor 手工）​

4. MCP Server 工具设计（与向量库配合）​

5. 切割维度决策清单（架构师自检）​

五、组件增量更新：改属性 / 新增 / 弃用​

1. 三类变更与影响面​

2. 变更检测：CI Diff Gate（比「字段数比对」更细）​

3. 向量库增量同步策略​

4. 弃用组件治理（Soft Deprecation，禁止硬删）​

5. 存量 pageSchema 怎么办？​

6. 研发侧 Cursor 工作流（增量，非全库重跑）​

🚀 迈向下一个里程碑​