npm - @zat-design/sisyphus-react-mcp - Versions diffs - 1.0.2 → 4.5.7 - Mend

@zat-design/sisyphus-react-mcp 1.0.2 → 4.5.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -1,65 +1,48 @@
 # @zat-design/sisyphus-react-mcp
-`@zat-design/sisyphus-react` 组件库的 MCP（Model Context Protocol）server，向 Claude Code / Cursor 等 AI 编码助手实时暴露组件库的**组件清单、API、配置式约定、真实示例**查询能力。
+## 解决什么问题
-元数据随组件库版本构建生成，**永不与版本漂移**，离线可用，无需自建服务。
+向 AI 暴露 Sisyphus 真实的组件清单、API、TypeScript 类型和 demo，避免凭记忆生成过时代码。元数据随 MCP 发布，业务组件包不再携带 AI 快照。
-## 为什么需要它
+## 前置版本
-大模型训练数据几乎没收录这个内网组件库，写代码时靠幻觉或过时记忆（如残留 v3 的 `ProColumnProps`）。本 MCP 让 AI 在生成代码前能查到当前版本**真实存在的** props、配置约定与可运行示例。
+- Node.js 18+
+- `@zat-design/sisyphus-react@4.5.7`
+- `@zat-design/sisyphus-react-mcp@4.5.7`
-## 提供的工具
+两包必须完全同版。启动时校验项目组件版本、MCP 内置元数据版本、schema v2 和 SHA-256。
-| 工具 | 作用 |
-|------|------|
-| `sisyphus-list-components` | 列出全部组件及业务域分类、一句话描述 |
-| `sisyphus-get-component-api` | 按组件名返回 props/fieldProps 与配置式约定枚举（`type`/`valueType`/`names`）。默认不内联示例 |
-| `sisyphus-get-examples` | 按组件名（可选场景关键词）返回真实可运行的 demo 源码 |
-| `sisyphus-search` | 按关键词跨组件清单/props 描述/示例标题检索 |
+## 三步安装
-## 接入方式
-### Claude Code（`.mcp.json`）
-在项目根目录的 `.mcp.json` 中加入：
+1. 安装同版组件库。
+2. 在 `.mcp.json` 或 `.cursor/mcp.json` 配置：
 ```json
 {
   "mcpServers": {
     "sisyphus-react": {
       "command": "npx",
-      "args": ["-y", "@zat-design/sisyphus-react-mcp"]
+      "args": ["-y", "@zat-design/sisyphus-react-mcp@4.5.7"]
     }
   }
 }
 ```
-重启 Claude Code 后即可发现并调用上述工具。
-### Cursor（`.cursor/mcp.json`）
-在项目根目录的 `.cursor/mcp.json` 中加入相同配置：
-```json
-{
-  "mcpServers": {
-    "sisyphus-react": {
-      "command": "npx",
-      "args": ["-y", "@zat-design/sisyphus-react-mcp"]
-    }
-  }
-}
-```
+3. 重启 AI 工具并调用 `sisyphus-get-meta-status`。
-重启 Cursor 后生效。
+## 推荐调用顺序
-## 工作原理
+1. `sisyphus-get-meta-status`
+2. `sisyphus-list-components`
+3. `sisyphus-get-component-api`
+4. 按需 `sisyphus-get-type`
+5. `sisyphus-list-examples`
+6. `sisyphus-get-example`
-- stdio 传输，`npx -y` 免安装拉取启动，离线运行。
-- 启动时加载包内随附的元数据 JSON（`meta/`），元数据缺失或损坏时显式报错，不静默返回空。
-- 返回内容经脱水压缩（剔除呈现噪声、双语保留中文、去重）以降低 token 占用。
-- 元数据版本标记与对应组件库版本一致，可供消费方核对。
+`sisyphus-search` 用于跨元数据检索；`sisyphus-get-examples` 仅作兼容。
-## 与组件库的关系
+## 常见错误
-本包与主包 `@zat-design/sisyphus-react` **解耦**：主包体积与版本不受影响，本包可独立迭代。集中更新通过发布新版本实现，用户下次 `npx` 自动获取最新版。
+- 版本不同：将组件库、MCP 和 Scene Agent 统一到完全相同的 SemVer。
+- 找不到组件包：确认当前业务项目安装了同版 `@zat-design/sisyphus-react`。
+- schema/哈希错误：重新安装同版 MCP，不继续使用损坏缓存。

package/meta/components.json CHANGED Viewed

@@ -1,187 +1,390 @@
 {
-  "version": "4.5.6-beta.4",
+  "schemaVersion": 2,
+  "version": "4.5.7",
   "components": [
     {
-      "name": "FormsProvider",
-      "category": "",
-      "description": "",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProCollapse",
+      "aliases": [],
+      "category": "布局",
+      "description": "ProCollapse 折叠标题",
+      "whenToUse": [
+        "页面内容需要按模块分组展示，并支持折叠/展开时",
+        "需要一级或二级标题区域折叠，节省长表单或详情页空间时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProCollapseType"
     },
     {
-      "name": "ProAction",
-      "category": "通用",
-      "description": "ProAction 事件封装",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProFooter",
+      "aliases": [],
+      "category": "布局",
+      "description": "ProFooter 底部",
+      "whenToUse": [
+        "页面底部需要固定悬浮操作栏（提交、保存、取消等）时",
+        "当底部栏需自适应侧栏宽度，避免遮挡菜单或内容区域时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProFooterType"
     },
     {
-      "name": "ProConfigProvider",
-      "category": "通用",
-      "description": "ProConfigProvider 全局化配置",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProHeader",
+      "aliases": [],
+      "category": "布局",
+      "description": "ProHeader 头部",
+      "whenToUse": [
+        "页面头部需要展示返回按钮、标题与面包屑导航时",
+        "头部需展示单号复制、功能按钮等页级操作时",
+        "头部有摘要信息需要通过 Popover 查看详情数据时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProHeaderType"
     },
     {
-      "name": "ProDownload",
-      "category": "通用",
-      "description": "ProDownload 下载按钮",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProLayout",
+      "aliases": [],
+      "category": "布局",
+      "description": "ProLayout 菜单",
+      "whenToUse": [
+        "需要搭建带侧边栏菜单、顶部栏与内容区的后台管理系统页面框架时",
+        "当页面需要标签页导航、iframe 嵌入第三方系统或工作台模式时",
+        "需要统一管理全局水印、应用入口切换等页面级能力时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProLayoutType"
+    },
+    {
+      "name": "ProStep",
+      "aliases": [],
+      "category": "布局",
+      "description": "ProStep 步骤条",
+      "whenToUse": [
+        "当长页面需要锚点定位并分步骤展示内容区块时",
+        "当你需要在步骤间跳转并自动收集各模块的表单校验错误时",
+        "配合 ProCollapse 使用时，可实现分组折叠与步骤导航联动"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProStepType"
+    },
+    {
+      "name": "ProTabs",
+      "aliases": [],
+      "category": "布局",
+      "description": "ProTabs 工作台 Tabs",
+      "whenToUse": [
+        "工作台页面需要以 Tab 切换展示不同业务分区，且每个 Tab 需显示数量徽标时",
+        "当 Tab 数据需通过接口异步刷新，或切换 Tab 时触发列表查询时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProTabsType"
+    },
+    {
+      "name": "ProTable",
+      "aliases": [],
+      "category": "数据展示",
+      "description": "ProTable 高扩展表格",
+      "whenToUse": [
+        "提供多达十种常用类型(`百分比、千分位、枚举、地址、日期时间等`)的快捷展示方式，当你需要快速转换时",
+        "当你的表格需要支持`自定义列、可伸缩列、拖拽排序、重置列宽、缓存列配置、合计`等功能时",
+        "配合框架提供的`useAntdTable`使用更佳"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProTableType"
+    },
+    {
+      "name": "ProTooltip",
+      "aliases": [],
+      "category": "数据展示",
+      "description": "ProTooltip 文本提示",
+      "whenToUse": [
+        "文案超长需要设置制定行数省略，然后通过 Tooltip 提示",
+        "表格中文案需要折叠时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProTooltipType"
+    },
+    {
+      "name": "ProViewer",
+      "aliases": [],
+      "category": "数据展示",
+      "description": "ProViewer 文件预览",
+      "whenToUse": [
+        "需要在页面内预览 PDF、图片等常见附件，无需用户下载后打开时",
+        "支持弹窗或新开页面两种预览模式，并可接收接口地址或二进制流数据",
+        "预览 Word/Excel 时依赖外网微软服务，内网环境可能不可用"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProViewerType"
+    },
+    {
+      "name": "ProEditTable",
+      "aliases": [],
+      "category": "数据录入",
+      "description": "ProEditTable 可编辑表格",
+      "whenToUse": [
+        "表格数据需行内直接编辑，无需弹窗或抽屉二次录入时",
+        "需要预设新增、删除、保存、取消、批量删除等行操作并同步 Form 值时",
+        "当表格需支持拖拽排序、虚拟列表、列联动等复杂可编辑场景时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProEditTableType"
     },
     {
       "name": "ProDrawerForm",
+      "aliases": [],
       "category": "数据录入",
       "description": "ProDrawerForm 抽屉或者弹窗表单组件",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "whenToUse": [
+        "复杂表单需要在抽屉或弹窗中承载，避免跳转新页面时",
+        "需要查看模式、自定义头底部、或拖拽调整弹窗/抽屉尺寸时",
+        "嵌套 ProForm 时，可复用 columns 配置快速搭建弹窗表单"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProDrawerFormType"
     },
     {
       "name": "ProEditLabel",
+      "aliases": [],
       "category": "数据录入",
       "description": "ProEditLabel 编辑的 label",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "whenToUse": [
+        "表格里只想编辑其中的某一个部分，默认支持 ProForm 内置的所有表单与转换器",
+        "审核与删除或者其他场景通过按钮或文字触发弹窗再次填写信息时使用"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProEditLabelType"
     },
     {
-      "name": "ProEditTable",
+      "name": "ProStepTab",
+      "aliases": [],
       "category": "数据录入",
-      "description": "ProEditTable 可编辑表格",
+      "description": "ProStepTab 分步表单 Tab",
+      "whenToUse": [
+        "需要将长表单拆分为多个步骤 Tab 分步填写时",
+        "当切换 Tab 或刷新页面后需保持当前激活步骤状态时",
+        "需要有序激活、自动跳转下一步或全局模式控制分步流程时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProStepTabType"
+    },
+    {
+      "name": "ProCascader",
+      "aliases": [],
+      "category": "表单",
+      "description": "ProCascader 级联组件",
       "whenToUse": [
-        "当你的表格需要与服务端进行交互，或者列表字段不多的情况时，不需要弹框或者抽屉的形式去更新表格信息，此时 ProEditTable 是不二选择"
+        "需要级联选择地址，或通过 mode 为 address 录入省市区街道时",
+        "数据源可通过全局枚举 code 读取，也支持自定义接口请求与数据转换",
+        "结合 ProForm 使用时，可一键配置表单项级联与值转换逻辑"
       ],
-      "importPath": "@zat-design/sisyphus-react"
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProCascaderType"
     },
     {
       "name": "ProEnum",
+      "aliases": [],
       "category": "表单",
       "description": "ProEnum 枚举组件",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "whenToUse": [
+        "需要根据全局枚举或自定义数据展示下拉框、单选/多选等表单控件时",
+        "同一枚举需在页面多处复用，且支持 tag、Segmented 等多种展示形式时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProEnumType"
     },
     {
       "name": "ProForm",
+      "aliases": [],
       "category": "表单",
       "description": "ProForm 表单引擎",
       "whenToUse": [
-        "提供类似 ant table 的`columns`快速配置，一个输入组件最少只需要配置两个字段即可配置成功",
-        "内置`枚举、日期增强（无需关注dayjs转换）、下拉框增强、地址、开关增强（支持设置自定义值）、证件号码、证件有效期、范围框、枚举选择弹框`等自定义输入组件类型",
-        "提供查看模式，避免统一使用禁用模式"
+        "提供类似 ant table 的 `columns` 快速配置，一个输入组件最少只需两个字段即可",
+        "内置枚举、日期增强、地址、证件号码、范围框等多种自定义输入组件类型",
+        "提供查看模式，避免统一使用禁用模式展示只读数据"
       ],
-      "importPath": "@zat-design/sisyphus-react"
-    },
-    {
-      "name": "ProHeader",
-      "category": "布局",
-      "description": "ProHeader 头部",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProFormType"
     },
     {
-      "name": "ProIcon",
-      "category": "通用",
-      "description": "ProIcon 图标",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProModalSelect",
+      "aliases": [],
+      "category": "表单",
+      "description": "ProModalSelect 弹窗分页选择",
+      "whenToUse": [
+        "当下拉框无法展示足够信息，需要通过表格分页搜索选择数据时",
+        "需要多选、远程回显、labelInValue 提交对象或自定义确认选择流程时",
+        "结合 ProForm 使用时，可复用 columns 配置快速搭建弹窗选择表单"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProModalSelectType"
     },
     {
-      "name": "ProLayout",
-      "category": "布局",
-      "description": "ProLayout 菜单",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProNumberRange",
+      "aliases": [],
+      "category": "表单",
+      "description": "ProNumberRange 数字范围",
+      "whenToUse": [
+        "表单中需要录入金额、数量等数字的最小值和最大值范围时",
+        "结合 ProForm 使用时，支持范围值的自动拆分与合并转换"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProNumberRangeType"
     },
     {
       "name": "ProSelect",
+      "aliases": [],
       "category": "表单",
       "description": "ProSelect 加强下拉框",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "whenToUse": [
+        "当标准 Select 无法满足远程搜索、异步加载或 value-label 回显需求时",
+        "需要下拉选项超长展示 tooltip，或提交对象/多选字符串等多种值格式时",
+        "结合 ProForm 使用时，可统一配置 fieldNames 和接口数据转换",
+        "*dataSource** 默认数据数据格式为:",
+        "```js",
+        "const dataSource = [",
+        "{ label: '上海', value: 'sh' },",
+        "{ label: '北京', value: 'bj' },",
+        "{ label: '武汉', value: 'wh' },",
+        "];",
+        "```"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProSelectType"
     },
     {
-      "name": "ProStep",
-      "category": "布局",
-      "description": "ProStep 步骤条",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProTimeLimit",
+      "aliases": [],
+      "category": "表单",
+      "description": "ProTimeLimit 证件有效期",
+      "whenToUse": [
+        "录入身份证、护照等证件有效期，且需提供「长期有效」快捷选项时",
+        "结合 ProForm 使用时，支持切换日期格式和不同 valueType 回传"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProTimeLimitType"
     },
     {
-      "name": "ProStepTab",
-      "category": "数据录入",
-      "description": "ProStepTab 分步表单 Tab",
+      "name": "ProTree",
+      "aliases": [],
+      "category": "表单",
+      "description": "ProTree 树",
       "whenToUse": [
-        "需要分步表单时",
-        "需要表单刷新保持激活状态时",
-        "需要表单分步激活时"
+        "需要树形或下拉树方式选择层级数据，支持搜索、全选、只选叶子节点时",
+        "数据源可通过接口、ProEnum 全局枚举获取，并支持查看模式与粘连选择时",
+        "在表单中需要展示 value-label 格式，或自定义渲染树节点时"
       ],
-      "importPath": "@zat-design/sisyphus-react"
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProTreeType"
     },
     {
-      "name": "ProTable",
-      "category": "数据展示",
-      "description": "ProTable 高扩展表格",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProTreeModal",
+      "aliases": [],
+      "category": "表单",
+      "description": "ProTreeModal 树弹框选择",
+      "whenToUse": [
+        "当平铺列表或树形结构的选择项过多，需要弹窗分页/搜索选取时",
+        "需要限制选择数量、支持拖拽排序、级联展示或指定模式操作时",
+        "表单中需以 labelInValue 提交对象，或自定义 trigger 触发选择时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProTreeModalType"
     },
     {
-      "name": "ProTabs",
-      "category": "布局",
-      "description": "ProTabs 工作台 Tabs",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProUpload",
+      "aliases": [],
+      "category": "表单",
+      "description": "ProUpload 上传控件",
+      "whenToUse": [
+        "需要拖拽上传、模板下载后上传，或多文件/图片证件上传场景时",
+        "当上传需结合 ProForm 表单，或需外部手动控制上传时机时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProUploadType"
     },
     {
       "name": "ProThemeTools",
+      "aliases": [],
       "category": "通用",
       "description": "ProThemeTools 主题配置",
       "whenToUse": [
-        "应用层级需要改变全局主题，间隔，表单对齐方式时",
-        "微前端场景需要改变整个系统的全局主题配置时",
+        "开发环境需要快速调试全局主题色、间距、表单对齐方式时",
+        "微前端场景需要调整整个系统的主题配置并持久化缓存时",
         "主题配置工具，用于开发环境"
       ],
-      "importPath": "@zat-design/sisyphus-react"
-    },
-    {
-      "name": "ProTooltip",
-      "category": "数据展示",
-      "description": "ProTooltip 文本提示",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProThemeToolsType"
     },
     {
-      "name": "ProTree",
-      "category": "表单",
-      "description": "基本使用",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProIcon",
+      "aliases": [],
+      "category": "通用",
+      "description": "ProIcon 图标",
+      "whenToUse": [
+        "需要展示 iconFont 图标库中的图标，或在菜单、表单前后缀位置使用图标时",
+        "当图标需要配合 tooltip、主题色、loading 等状态展示时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProIconType"
     },
     {
-      "name": "ProTreeModal",
-      "category": "表单",
-      "description": "基本使用",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProDownload",
+      "aliases": [],
+      "category": "通用",
+      "description": "ProDownload 下载按钮",
+      "whenToUse": [
+        "需要在当前页面触发文件下载，避免打开新标签页时",
+        "当文件需通过 Post 接口返回文件流下载，或支持静态资源地址下载时",
+        "下载按钮需继承 antd Button 属性，并支持下载前/后自定义处理时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProDownloadType"
     },
     {
-      "name": "ProUpload",
-      "category": "表单",
-      "description": "ProUpload 上传控件",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProWaterMark",
+      "aliases": [
+        "ProWatermark"
+      ],
+      "category": "通用",
+      "description": "ProWaterMark 水印组件",
+      "whenToUse": [
+        "页面或局部区域需要添加文字/图片水印，标识版权或敏感信息时",
+        "当需要对特定容器而非全屏添加水印保护时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProWaterMarkType"
     },
     {
-      "name": "ProViewer",
-      "category": "数据展示",
-      "description": "ProViewer 文件预览",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProConfigProvider",
+      "aliases": [],
+      "category": "通用",
+      "description": "ProConfigProvider 全局化配置",
+      "whenToUse": [
+        "需要在应用入口统一配置 ProForm、ProEnum、ProTable 等组件的默认行为和全局数据源时",
+        "当需要切换中英文国际化，或统一设置 antd 主题与组件默认样式时",
+        "微前端或大型应用中，需在根布局一次性注入枚举接口、地址栏等公共配置时"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProConfigProviderType"
     },
     {
-      "name": "ProWaterMark",
-      "category": "",
-      "description": "",
-      "whenToUse": [],
-      "importPath": "@zat-design/sisyphus-react"
+      "name": "ProAction",
+      "aliases": [],
+      "category": "通用",
+      "description": "ProAction 事件封装",
+      "whenToUse": [
+        "表格删除、编辑等操作需要先调用接口校验并展示错误信息时",
+        "需要在操作前弹出确认框，并支持链式异步请求串联多个步骤时",
+        "当与 ProTable 等列表组件结合，统一处理鉴权、删除确认等重复交互时",
+        "对表格删除、鉴权等场景的函数封装、支持异步、事件流链式调用",
+        "*解析弹框数据格式如下**、可以通过 `useRequest` 中的 `transformResponse` 进行格式化",
+        "```ts",
+        "interface Datta {",
+        "errorTitle: string;",
+        "list: string[];",
+        "}",
+        "```"
+      ],
+      "importPath": "@zat-design/sisyphus-react",
+      "propsType": "ProActionType"
     }
   ]
-}
+}