@xtcel/reaui-mcp 0.1.0 → 0.2.0

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.
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  MCP server for [REA UI](https://github.com/xtcel/rea.ui). It wraps the `reaui` CLI so Claude Code, Cursor, Cline, or any MCP client can create, validate and pack `.reaui` design documents — React TSX + Tailwind that opens in the REA UI editor and exports as production code.
6
6
 
7
- Agents are good at writing TSX and bad at guessing file layout. This server encodes the contract: one protocol resource, eight tools, and structured validation errors a model can act on without reading source.
7
+ Agents are good at writing TSX and bad at guessing file layout. This server encodes the contract: one protocol resource, ten tools, and structured validation errors a model can act on without reading source.
8
8
 
9
9
  ## Two transports, one package
10
10
 
@@ -41,6 +41,8 @@ claude mcp add reaui -- npx -y @xtcel/reaui-mcp --root /absolute/path/to/designs
41
41
 
42
42
  You can also reach it through the CLI: `npx @xtcel/reaui-cli mcp`.
43
43
 
44
+ Per-client guides, with prompts and rules files: [Claude Code](https://github.com/xtcel/rea.ui/blob/main/docs/agents/claude-code.md) · [Cursor](https://github.com/xtcel/rea.ui/blob/main/docs/agents/cursor.md) · [Codex CLI](https://github.com/xtcel/rea.ui/blob/main/docs/agents/codex-cli.md) · [WorkBuddy](https://github.com/xtcel/rea.ui/blob/main/docs/agents/workbuddy.md)
45
+
44
46
  ## Remote (Streamable HTTP)
45
47
 
46
48
  ```bash
@@ -83,6 +85,8 @@ Remote sessions are **not persisted**: the workspace is a temp directory created
83
85
  | `reaui_pack` | Pack a validated document into a single `.reaui` |
84
86
  | `reaui_unpack` | Unpack `.reaui` into a directory for page-by-page edits |
85
87
  | `reaui_preview` | Render a self-contained `preview.html` |
88
+ | `reaui_get_system` | Read the complete project snapshot (or null); use it before editing existing projects |
89
+ | `reaui_set_system` | Set a full system JSON package, or pass null to remove an unused system; validates all references before writing |
86
90
  | `reaui_diff` | Compare two design sources and report what changed |
87
91
 
88
92
  All paths are relative to the workspace root; absolute paths and `..` escapes are rejected.
@@ -116,3 +120,7 @@ Node.js **22.18+**. macOS, Linux, Windows. No Rust toolchain.
116
120
  ## License
117
121
 
118
122
  [Apache-2.0](https://github.com/xtcel/rea.ui/blob/main/LICENSE)
123
+
124
+ ## Project-owned systems
125
+
126
+ `reaui_init` and `reaui_create_design` accept optional `system` (a complete serialized `reaui-design-system` JSON package). The package is embedded before token-aware pages are validated. `reaui_create_design` also accepts optional static `components` source; v4 supports both. Existing projects use their embedded snapshot, never a global default. Without a system, use existing page styling and literal values. Adopting a system does not publish a library version.
@@ -19344,7 +19344,7 @@ var EMPTY_COMPLETION_RESULT = { completion: {
19344
19344
  hasMore: false
19345
19345
  } };
19346
19346
  // ../../docs/agent-protocol.md?raw
19347
- var agent_protocol_default = "# REA UI Agent 设计协议\n\n面向 WorkBuddy 等外部 Agent 的稳定契约。CLI 的校验标准就是编辑器的校验标准:通过这里的所有规则,`.reaui` 就能在 ReaUI 桌面版打开并继续编辑。\n\n## 1. 文档结构\n\n```text\nrea.json 清单(format/version/id/name/pages/createdAt)\npages/<pageId>.page.tsx 每页一个静态 TSX\ncomponents/main.components.tsx 可选,v3 组件目录\nagent/sessions.json 可选元数据\neditor/guides.json 可选元数据\nassets/… 可选资源\n```\n\n页面 id 必须匹配 `^[a-z][a-z0-9-]{0,63}$`,文件路径固定为 `pages/<id>.page.tsx`,且 `Page` 的 `id` 与清单一致。\n\n## 2. 页面骨架\n\n```tsx\nimport { Page, Frame, Text } from '@rea/design';\n\nexport default (\n <Page id=\"main\" designId=\"page-root\" name=\"首页\">\n <Frame designId=\"desktop\" name=\"桌面画板\" className=\"absolute left-0 top-0 w-[1440px] h-[1024px] bg-white\">\n <Text designId=\"page-title\" name=\"标题\" className=\"absolute left-[64px] top-[64px] w-[600px] h-[44px] text-[30px] font-medium text-[#30343b]\">工作台</Text>\n </Frame>\n </Page>\n);\n```\n\n- 只允许 `import { … } from '@rea/design'` 与一个 `export default` 的 `<Page>`。\n- 顶层 `Frame` 必须同时具备 `absolute`、`left`、`top`、`w-[…]`、`h-[…]`。\n- 桌面画板常用 `1440×1024`,移动画板常用 `390×844`,后台列表可用 `1280×900`。\n- 所有内容必须落在画板内,不要依赖画板外的溢出。\n\n## 3. 允许的原语\n\n| 原语 | 用途 | 关键属性 |\n|---|---|---|\n| `Page` | 页面根,不能嵌套 | `id`、`designId`、`name`、`className` |\n| `Frame` | 画板或容器 | `designId`、`className`、子节点 |\n| `Group` | 逻辑分组 | `designId`、`className`、子节点 |\n| `Rect` | 矩形、卡片、输入框外框 | `designId`、`className` |\n| `Ellipse` | 圆、头像底、状态点 | 默认 `rounded-full`,可覆盖圆角 |\n| `Text` | 所有文字 | 子节点只能是字符串 |\n| `Vector` | 图标路径 | `d` 或 `path`,`viewBox` |\n| `Line` | 分割线、箭头 | `x1/y1/x2/y2`(0–100)、`startArrow/endArrow` |\n| `Polygon` | 三角形等 | `count` |\n| `Star` | 星形 | `count`、`innerRatio` |\n\n禁止使用 `Image`(本期不支持资源)、`Instance` / `Slot`(组件实例由编辑器维护)、任何 HTML 标签(`div`、`span`、`p`、`img`、`svg`)。\n\n## 4. 属性规则\n\n- 公共属性:`designId`、`name`、`hidden`、`locked`、`className`。\n- 属性只能是静态字符串、有限数字、布尔值、`null`、数组或普通对象字面量。\n- `className` 必须是字符串;允许 `{\"文字\"}` 这种字符串表达式。\n- 禁止:`style`、`key`、`ref`、`onClick` 等事件、`href`、函数调用、模板字符串、展开运算符、变量、条件表达式、`map`、计算属性。\n- `designId` 匹配 `^[a-z][a-z0-9-]{1,63}$`,同一页面内唯一,使用语义化命名:`hero-title`、`nav-logo`、`card-1`。\n\n## 5. Tailwind 约定\n\n使用 Tailwind CSS 4.3.3 默认主题与 preflight。\n\n- 优先刻度:`p-6`、`w-80`、`gap-4`、`mt-8`。\n- 非刻度用任意值:`w-[317px]`、`left-[64px]`、`text-[30px]`、`bg-[#f7f8fa]`、`rounded-[10px]`。\n- 颜色一律写 16 进制:`bg-[#ffffff]`、`text-[#30343b]`、`border-[#e5e7eb]`、`stroke-[#98a2b3]`、`fill-none`。\n- 字体:`text-[28px]`、`font-medium`、`leading-[36px]`、`tracking-[0.2px]`。\n- 阴影:`shadow-sm`、`shadow-md`;任意阴影用下划线代替空格:`shadow-[0_1px_2px_rgba(16,24,40,0.06)]`。\n- 布局:绝对定位用于精确还原;`flex flex-col gap-4 items-start justify-between` 用于容器内部。\n- 不使用百分比宽度、`vw/vh`、`calc()`、CSS 变量与自定义 `@apply`。\n\n## 6. 硬性限制\n\n- 每页最多 80 个图层;每个文档最多 12 页(与编辑器 AI 限制一致)。\n- 不执行任何页面代码;页面里没有运行时。\n- 不引用外部字体、图片、图标库;图标用 `Vector` 的 `d` 路径或几何原语绘制。\n- 不写 `library`、`variant`、`overrides`、`parameters` 等组件高级字段。\n- 文案使用中文,除非用户明确要求其他语言。\n\n## 7. CLI 工作流\n\n```bash\nREAUI=\"node $REAUI_ROOT/packages/reaui-cli/bin/reaui.mjs\"\n\n$REAUI init ./design --name \"我的应用\" --page main --page-name 首页 --width 1440 --height 1024\n$REAUI validate ./design --json\n$REAUI pack ./design --out ./design.reaui\n$REAUI preview ./design --out ./preview.html\n```\n\n多轮修改:\n\n```bash\n$REAUI unpack ./design.reaui --out ./design\n# 修改 pages/*.page.tsx,保留未涉及的 designId\n$REAUI diff ./design.before ./design\n$REAUI validate ./design --json\n$REAUI pack ./design --out ./design.reaui --force\n```\n\n### 校验输出\n\n```json\n{\n \"ok\": false,\n \"errors\": [{\n \"code\": \"PAGE_SUBSET\",\n \"path\": \"pages/main.page.tsx\",\n \"message\": \"pages/main.page.tsx: 未注册的设计节点:div\",\n \"hint\": \"只使用 @rea/design 的页面原语,不要使用 div/span 等 HTML 标签或项目组件。\"\n }]\n}\n```\n\n退出码:`0` 通过,`1` 校验失败,`2` 用法或 I/O 错误。\n\n## 8. 常见错误与修复\n\n| 错误码 | 典型原因 | 修复 |\n|---|---|---|\n| `PAGE_SUBSET` | 用了 `div`、`span`、外部组件 | 换成 `Frame` / `Group` / `Rect` |\n| `PAGE_STATIC_ONLY` | 函数、事件、变量、模板字符串 | 改成静态字面量或直接写文字 |\n| `PAGE_STRUCTURE` | 顶层 Frame 缺 `absolute` 或尺寸 | 补 `absolute left-0 top-0 w-[…] h-[…]` |\n| `DESIGN_ID` | 大写、下划线、重复 | 改为小写连字符并保证页面内唯一 |\n| `MANIFEST_INVALID` | 清单字段或页面路径不合法 | 用 `reaui init` 重新生成清单 |\n| `PAGE_MISSING` | 清单引用了不存在的页面 | 补齐 `pages/<id>.page.tsx` |\n\n## 9. 交付要求\n\n- 先 `validate` 通过,再 `pack`;不得交付未通过校验的 `.reaui`。\n- 同时提供 `preview.html`,让用户在 WorkBuddy 结果区直接看到设计。\n- 回复中列出 `.reaui` 与预览路径、页面数、画板尺寸,并说明双击 `.reaui` 可用 ReaUI 打开继续编辑。\n- 不声称已完成视觉验收或真机验收;静态预览不等于交互原型。\n";
19347
+ var agent_protocol_default = "# REA UI Agent 设计协议\n\n面向 WorkBuddy 等外部 Agent 的稳定契约。CLI 的校验标准就是编辑器的校验标准:通过这里的所有规则,`.reaui` 就能在 ReaUI 桌面版打开并继续编辑。\n\n## 1. 文档结构\n\n```text\nrea.json 清单(format/version/id/name/pages/createdAt)\npages/<pageId>.page.tsx 每页一个静态 TSX\ncomponents/main.components.tsx 可选,v3/v4 组件目录\nagent/sessions.json 可选元数据\neditor/guides.json 可选元数据\nassets/… 可选资源\n```\n\n页面 id 必须匹配 `^[a-z][a-z0-9-]{0,63}$`,文件路径固定为 `pages/<id>.page.tsx`,且 `Page` 的 `id` 与清单一致。\n\n## 2. 页面骨架\n\n```tsx\nimport { Page, Frame, Text } from '@rea/design';\n\nexport default (\n <Page id=\"main\" designId=\"page-root\" name=\"首页\">\n <Frame designId=\"desktop\" name=\"桌面画板\" className=\"absolute left-0 top-0 w-[1440px] h-[1024px] bg-white\">\n <Text designId=\"page-title\" name=\"标题\" className=\"absolute left-[64px] top-[64px] w-[600px] h-[44px] text-[30px] font-medium text-[#30343b]\">工作台</Text>\n </Frame>\n </Page>\n);\n```\n\n- 只允许 `import { … } from '@rea/design'` 与一个 `export default` 的 `<Page>`。\n- 顶层 `Frame` 必须同时具备 `absolute`、`left`、`top`、`w-[…]`、`h-[…]`。\n- 桌面画板常用 `1440×1024`,移动画板常用 `390×844`,后台列表可用 `1280×900`。\n- 所有内容必须落在画板内,不要依赖画板外的溢出。\n\n## 3. 允许的原语\n\n| 原语 | 用途 | 关键属性 |\n|---|---|---|\n| `Page` | 页面根,不能嵌套 | `id`、`designId`、`name`、`className` |\n| `Frame` | 画板或容器 | `designId`、`className`、子节点 |\n| `Group` | 逻辑分组 | `designId`、`className`、子节点 |\n| `Rect` | 矩形、卡片、输入框外框 | `designId`、`className` |\n| `Ellipse` | 圆、头像底、状态点 | 默认 `rounded-full`,可覆盖圆角 |\n| `Text` | 所有文字 | 子节点只能是字符串 |\n| `Vector` | 图标路径 | `d` 或 `path`,`viewBox` |\n| `Line` | 分割线、箭头 | `x1/y1/x2/y2`(0–100)、`startArrow/endArrow` |\n| `Polygon` | 三角形等 | `count` |\n| `Star` | 星形 | `count`、`innerRatio` |\n\n禁止 HTML 标签(`div`、`span`、`p`、`img`、`svg`)和业务 React 组件。组件目录可使用 Components/Component/Slot,页面可使用 Instance/SlotContent;Image 仅引用 assets/ 内的本地资产。\n\ncore/full profile 仅描述语言能力,不再决定复用策略。默认评估并使用组件,无需用户额外授权;通过 CLI 管理组件目录及版本。\n\n## 4. 属性规则\n\n- 公共属性:`designId`、`name`、`hidden`、`locked`、`className`。\n- 属性只能是静态字符串、有限数字、布尔值、`null`、数组或普通对象字面量。\n- `className` 必须是字符串;允许 `{\"文字\"}` 这种字符串表达式。\n- 文档固定了设计系统时,`className` 可用 `var(--rea-ds-*)` 引用令牌(见 §10);其它 CSS 变量仍被拒绝。\n- 禁止:`style`、`key`、`ref`、`onClick` 等事件、`href`、函数调用、模板字符串、展开运算符、变量、条件表达式、`map`、计算属性。\n- `designId` 匹配 `^[a-z][a-z0-9-]{1,63}$`,同一页面内唯一,使用语义化命名:`hero-title`、`nav-logo`、`card-1`。\n\n## 5. Tailwind 约定\n\n使用 Tailwind CSS 4.3.3 默认主题与 preflight。\n\n- 优先刻度:`p-6`、`w-80`、`gap-4`、`mt-8`。\n- 非刻度用任意值:`w-[317px]`、`left-[64px]`、`text-[30px]`、`bg-[#f7f8fa]`、`rounded-[10px]`。\n- 颜色一律写 16 进制:`bg-[#ffffff]`、`text-[#30343b]`、`border-[#e5e7eb]`、`stroke-[#98a2b3]`、`fill-none`。\n- 字体:`text-[28px]`、`font-medium`、`leading-[36px]`、`tracking-[0.2px]`。\n- 阴影:`shadow-sm`、`shadow-md`;任意阴影用下划线代替空格:`shadow-[0_1px_2px_rgba(16,24,40,0.06)]`。\n- 布局:绝对定位用于精确还原;`flex flex-col gap-4 items-start justify-between` 用于容器内部。\n- 不使用百分比宽度、`vw/vh`、`calc()`、`env()`、自定义 `@apply`;只允许 `var(--rea-ds-*)` 设计令牌。\n\n## 6. 硬性限制\n\n- 每文档最多 12 页;80 图层仅为软预算,不得为了压缩节点破坏布局分组或合并业务内容。\n- 不执行任何页面代码;页面里没有运行时。\n- 不引用外部字体、图片、图标库;图标用 `Vector` 的 `d` 路径或几何原语绘制。\n- 可用 parameters / variants / overrides / binding / bindings 表达组件内容与状态;不得伪造 library 来源。\n- 文案使用中文,除非用户明确要求其他语言。\n\n## 7. CLI 工作流\n\n```bash\nREAUI=\"node $REAUI_ROOT/packages/reaui-cli/bin/reaui.mjs\"\n\n$REAUI init ./design --name \"我的应用\" --page main --page-name 首页 --width 1440 --height 1024\n$REAUI validate ./design --json\n$REAUI pack ./design --out ./design.reaui\n$REAUI preview ./design --out ./preview.html\n```\n\n多轮修改:\n\n```bash\n$REAUI unpack ./design.reaui --out ./design\n# 修改 pages/*.page.tsx,保留未涉及的 designId\n$REAUI diff ./design.before ./design\n$REAUI validate ./design --json\n$REAUI pack ./design --out ./design.reaui --force\n```\n\n### 校验输出\n\n```json\n{\n \"ok\": false,\n \"errors\": [{\n \"code\": \"PAGE_SUBSET\",\n \"path\": \"pages/main.page.tsx\",\n \"message\": \"pages/main.page.tsx: 未注册的设计节点:div\",\n \"hint\": \"只使用 @rea/design 的页面原语,不要使用 div/span 等 HTML 标签或项目组件。\"\n }]\n}\n```\n\n退出码:`0` 通过,`1` 校验失败,`2` 用法或 I/O 错误。\n\n## 8. 常见错误与修复\n\n| 错误码 | 典型原因 | 修复 |\n|---|---|---|\n| `PAGE_SUBSET` | 用了 `div`、`span`、外部组件 | 换成 `Frame` / `Group` / `Rect` |\n| `PAGE_STATIC_ONLY` | 函数、事件、变量、模板字符串 | 改成静态字面量或直接写文字 |\n| `PAGE_STRUCTURE` | 顶层 Frame 缺 `absolute` 或尺寸 | 补 `absolute left-0 top-0 w-[…] h-[…]` |\n| `DESIGN_ID` | 大写、下划线、重复 | 改为小写连字符并保证页面内唯一 |\n| `MANIFEST_INVALID` | 清单字段或页面路径不合法 | 用 `reaui init` 重新生成清单 |\n| `PAGE_MISSING` | 清单引用了不存在的页面 | 补齐 `pages/<id>.page.tsx` |\n\n## 9. 交付要求\n\n- 先 `validate` 通过,再 `pack`;不得交付未通过校验的 `.reaui`。\n- 同时提供 `preview.html`,让用户在 WorkBuddy 结果区直接看到设计。\n- 回复中列出 `.reaui` 与预览路径、页面数、画板尺寸,并说明双击 `.reaui` 可用 ReaUI 打开继续编辑。\n- 不声称已完成视觉验收或真机验收;静态预览不等于交互原型。\n\n## 10. 设计系统与设计令牌\n\n文档可以固定一套设计系统:`design/system.json` 保存自包含快照,清单同时为 `version: 4`。快照结构为 `{ format: \"reaui-design-system\", schemaVersion, id, revision, hash, name, tokens, components, guidelines }`,`hash` 是除自身外全部字段按键排序、无空白序列化后的 SHA-256。`schemaVersion` 1 与 2 都可读,新发布的版本为 2。\n\n项目快照是生成、渲染与校验的共同依据。采用系统不隐式发布,全局选择只影响新建。项目内编辑首次建立独立 id 并携带 `projectId` 与 `origin: {id, revision, hash}`;库变更不影响项目。v4 同时支持组件目录。页面 AI 的工作区不允许写系统,但宿主在候选校验前合并自己的快照,拒绝外部替换和未知引用。项目系统编辑会话保存到 `agent/system-sessions.json`,页面会话到 `agent/sessions.json`,引用其它项目时必须排除 `agent/` 内容。\n\nCLI 可通过 `reaui init ./design --system ./brand.json` 或 `reaui system set ./design --system ./brand.json` 采用系统;`system get` 读取完整快照,`system remove` 仅在没有令牌引用时成功。MCP 的 `reaui_init/reaui_create_design` 接受可选 system JSON,另有 `reaui_get_system/reaui_set_system`(null 移除)。已有项目先读取系统,再生成页面。\n\n### 10.1 令牌模型\n\n- `color`:`primary` 核心必需;`background/surface/text/muted/border` 为可选预置角色,其余为自定义语义角色(如 `on_primary`、`surface_dark_1`、`card`、`cardForeground`、`ring`、`onPrimary` 等),键名支持 `snake_case`、`kebab-case` 或 `camelCase`(匹配 `^[a-zA-Z][a-zA-Z0-9_-]*$`)。v2 的颜色值可以是 `#RGB` / `#RRGGBB` / `#RRGGBBAA` 十六进制或 `var(--rea-ds-color-*)` 别名,别名必须指向已声明的角色且不能成环。\n- `typography`:`family` 加 `roles`(至少 1 个角色,最多 48 个角色;不强制要求字面键名为 `body`,支持 `display_xl`、`body_lg`、`body_sm` 等 `snake_case` / `kebab-case` / `camelCase` 角色名);每个角色为 `{ size, lineHeight, weight }`(`size` 为 `4–240`,`lineHeight` 为 `0.5–4` 倍数或 `4–300` px,`weight` 为 `100–900` 整数),可选 `letterSpacing` 与 `family`。\n- `space`:`unit` 加升序 `scale`。\n- `radius`:`sm/md/lg` 必需,可选 `xl/full` 及其他扩展圆角键。\n- `shadow`:命名的静态 `box-shadow` 值。\n- `motion`:`duration`(毫秒整数)与 `easing`(`linear` / `ease*` / `cubic-bezier` / `steps`)。\n\n变量命名:所有含下划线 `_` 或驼峰的令牌键名均通过 `kebab()` 统一转换为连字符 `-`(如 `on_primary` -> `--rea-ds-color-on-primary`,`display_xl` -> `--rea-ds-type-display-xl-size`);颜色 `--rea-ds-color-*`,排版 `--rea-ds-type-<role>-size/-line/-weight/-tracking/-family`,兼容别名 `--rea-ds-typography-body|heading|caption-*`,间距 `--rea-ds-space-<n>`,圆角 `--rea-ds-radius-*`,阴影 `--rea-ds-shadow-*`,动效 `--rea-ds-motion-duration-*` / `--rea-ds-motion-easing-*`。\n\n### 10.2 生成规则\n\n提示词与校验共用同一个「是否已固定」判断:\n\n- 文档已固定(`design/system.json` 存在):颜色、间距、圆角、阴影只能引用 `var(--rea-ds-*)`,例如 `bg-[var(--rea-ds-color-surface)]`、`rounded-[var(--rea-ds-radius-md)]`、`p-[var(--rea-ds-space-24)]`、`shadow-[var(--rea-ds-shadow-card)]`;字号与行高优先写 `text-[length:var(--rea-ds-type-body-size)]`。\n- 文档未固定:颜色、间距、圆角与字号使用十六进制与 px 字面量,**不得**写 `var(--rea-ds-*)`;使用已有页面风格和用户要求,不注入全局默认系统。\n- 位置与尺寸(`left` / `top` / `right` / `bottom` / `w-` / `h-`)始终使用设计 px,不使用间距令牌。\n- 组件规范按 `key` 引用;条目声明了 `component` 时优先写 `<Instance component=\"…\" />`(full profile),不要重画矩形与文字。\n\n### 10.3 DESIGN.md 通道\n\n`renderDesignMarkdown()` 与 `exportDesignMarkdown()` 把设计系统写成 DESIGN.md:frontmatter 是机器层(`colors` / `typography` / `rounded` / `spacing` / `shadow` / `motion` / `components` / `guidelines`),正文按 Overview、Colors、Typography、Layout、Elevation、Motion、Components、Guidance 生成,仅供人阅读。其中 `renderDesignMarkdown()` 支持对尚未发布或仍含待修项的草稿直接渲染 `DESIGN.md` 文本而不抛错,供对话内资源卡片与详情页「源文件」小节实时展示和导出。`importDesignMarkdown()` 只读 frontmatter,接受三位 hex、`Npx` 字符串与 `tight/control/popup/dialog`、`one/two/...` 这类自有命名,按数值映射到契约并返回 warning;正文不参与解析。往返(导出→导入→导出)保持 hash 与字节稳定。\n\nUI 的「导入 DESIGN.md / CSS」入口不直接调用 `importDesignMarkdown()`:选中的文件挂到输入框并预填提取指令,用户确认后才发送,由生成流程按 `systemSchema` 产出系统;散文型 DESIGN.md 因此在入口处不再报 `DS_MD_INVALID`。库函数仍服务 CLI、测试与精确往返。\n\n生成结果由 `parseGeneratedSystem()` 接收:只做形状转换(角色数组折回记录,缺失的令牌分组开成空容器),返回值 `{ system, warnings }`。**不补齐、不映射别名、不排序刻度、不重试**——`systemSchema` 只能约束结构,模型仍可能给出 `components: []`、`primary: 'blue'` 或乱序刻度,这些内容原样写进草稿,`warnings` 逐条说明缺什么、哪个字段不合法。理由是不能把中间修改藏进黑盒:用户要先看到模型到底返回了什么,再决定怎么改。真正的闸门在发布与「设为新建默认」:`validateTokens()` 有问题时两个按钮都禁用,提示语是「先修正标出的令牌问题」。设计系统页用同一份 `SystemIssue` 驱动三处提示——轮次内的清单、页面顶部计数条、左侧目录的受影响小节标记。\n\n校验:\n\n```bash\n$REAUI validate ./design --system ./design-system.json --strict --json\n$REAUI pack ./design --out ./design.reaui # 有设计系统 warning 时需要再加 --force\n```\n\n`--system` 用于把外部生成的设计系统与文档固定版本比对,`id` 或 `hash` 不一致报 `DS_SYSTEM_MISMATCH`。默认退出码只看 error;`--strict` 把 warning 也视为失败。错误码:`DS_SCHEMA`、`DS_SCHEMA_UNSUPPORTED`、`DS_HASH_MISMATCH`、`DS_TOKEN_UNDECLARED`、`DS_TOKEN_INVALID`、`DS_LITERAL_COLOR`、`DS_OFF_SCALE`、`DS_CONTRAST`、`DS_SYSTEM_MISMATCH`、`DS_REQUIRES_V4`。`DS_LITERAL_COLOR`、`DS_OFF_SCALE`、`DS_CONTRAST`、`DS_COMPONENT_MISSING` 为 warning,其余为 error。\n\n## 可编辑性要求(格式校验之外)\n\n- 先画布局树:侧边栏 / 顶部栏 / 内容区 / 面板 / 记录行。每区用有业务名称的 Frame/Group,子层使用局部坐标,容器边界贴合内容。例如父 `absolute left-[240px] top-[80px] w-[960px] h-[720px]`,子 `absolute left-[24px] top-[24px]`。\n- 优先使用已有组件。同结构重复两次及以上时评估提取 Component/Instance;文字、数字用参数,状态用变体,图标差异可用实例参数,额外内容用插槽。一次性布局不强行组件化。不需要用户每次强调复用。\n- 一个业务图标对应独立容器、语义名称(如“搜索图标”)和局部 viewBox(如 `0 0 24 24`)。图标内多个轮廓可属于同一 Vector;禁止按颜色跨图标合并路径,禁止跨业务记录合并多行 Text。Rect/Frame/Line 能表达的内容优先用原语。\n- 优先结构化 `path`:`anchors/closed` 为首轮廓,`contours` 为后续轮廓数组,每项也有 `anchors/closed`,锚点 id 全路径唯一。新编辑器支持 A/a 转贝塞尔(转换误差界默认 0.01 SVG 用户单位)和多轮廓锚点编辑。孔洞保留整体 `[fill-rule:evenodd]`,或保留 nonzero 的轮廓方向,不拆成填实形状。\n- 80 图层仅为软预算。复杂还原优先保留语义层级、独立编辑与完整内容,不通过合并业务对象来压缩节点。使用已有字体,不下载字体。\n- `validate` 只证明格式/契约有效。交付前另运行 `reaui audit <dir> --json` 与最终 `.reaui` 审计;按 path/node/hint 修复,人工判断疑似重复和合并提示,披露保留的建议。不得将零格式错误称为视觉验收或可编辑性证明。\n- 新的复合 `path.contours` 需要包含本次改动的编辑器。旧编辑器兼容输出可保留独立 Vector 的原始 d,但必须说明无法在旧编辑器逐点编辑;不得承诺全面可编辑。\n\n### 组件工作流\n\n先使用 `reaui init <dir> --components`;已有文档用 `reaui components init <dir>`。CLI 自动创建合法空目录并按需升级 v3,已有 v4 保留,不手改清单。然后写 `components/main.components.tsx`:\n\n```tsx\nimport { Components, Component, Frame, Text } from '@rea/design';\nexport default <Components>\n <Component id=\"record-row\" designId=\"record-definition\" name=\"实验记录行\" parameters={{label:{type:'string',default:'实验名称'}}}>\n <Frame designId=\"record-content\" name=\"记录内容\" className=\"relative w-[320px] h-[48px]\">\n <Text designId=\"record-label\" name=\"实验名称\" binding=\"label\" className=\"absolute left-[16px] top-[12px] w-[280px] h-[24px] text-[14px]\" />\n </Frame>\n </Component>\n</Components>;\n```\n\n页面 import `Instance`,写静态 `<Instance designId=\"record-one\" name=\"实验一\" component=\"record-row\" values={{label:'稳定性实验'}} className=\"absolute left-[24px] top-[24px]\" />`。每个实例独立 designId;不运行函数、不直接导入业务 React 组件、不伪造 library 来源。\n\nCLI 预检除版本外必须检查 `reaui help` 含 `audit` 和 `components`。这些能力随本次仓库/插件构建提供,尚未发布 npm;旧版 npx 回退没有这些命令时使用更新的仓库/插件构建,不能手改 version 绕过。\n";
19348
19348
  // src/cli.ts
19349
19349
  var require$1 = createRequire(import.meta.url);
19350
19350
  var cachedBin;
@@ -19457,8 +19457,105 @@ async function exists(target) {
19457
19457
  return false;
19458
19458
  }
19459
19459
  }
19460
+ /** Pass package content to the CLI without shell interpolation or a permanent sidecar. */
19461
+ async function withSystemFile(root, source, run) {
19462
+ if (source === void 0) return run([]);
19463
+ await mkdir(root, { recursive: true });
19464
+ const file = path.join(root, `.reaui-system-${crypto.randomUUID()}.json`);
19465
+ try {
19466
+ await writeFile(file, source, "utf8");
19467
+ return await run(["--system", file]);
19468
+ } finally {
19469
+ await rm(file, { force: true });
19470
+ }
19471
+ }
19460
19472
  function registerTools(server, context) {
19461
19473
  const { root } = context;
19474
+ server.registerTool("reaui_get_system", {
19475
+ title: "Read the project design system",
19476
+ description: "Read the complete embedded project system, or null when none is set. This project snapshot is authoritative for generation.",
19477
+ inputSchema: { path: stringType().describe("Project directory or .reaui file relative to the workspace root") }
19478
+ }, async (input) => {
19479
+ try {
19480
+ const target = resolveInRoot(root, input.path);
19481
+ const result = await runCli([
19482
+ "system",
19483
+ "get",
19484
+ relativeTo(root, target),
19485
+ "--json"
19486
+ ], root);
19487
+ return reply(parseJsonOutput(result.stdout) ?? { error: result.stderr || result.stdout }, result.code !== 0);
19488
+ } catch (error) {
19489
+ return failure(error);
19490
+ }
19491
+ });
19492
+ server.registerTool("reaui_set_system", {
19493
+ title: "Set or remove the project design system",
19494
+ description: "Adopt a complete reaui-design-system package in a project directory. Pass null to remove. Validates all page/component token references before writing; does not publish a library version.",
19495
+ inputSchema: {
19496
+ path: stringType().describe("Project directory relative to the workspace root"),
19497
+ system: stringType().nullable().describe("Full JSON package including schemaVersion, revision and hash; null removes the system")
19498
+ }
19499
+ }, async (input) => {
19500
+ try {
19501
+ const target = resolveInRoot(root, input.path);
19502
+ const result = await withSystemFile(root, input.system ?? void 0, (args) => runCli([
19503
+ "system",
19504
+ input.system === null ? "remove" : "set",
19505
+ relativeTo(root, target),
19506
+ ...args,
19507
+ "--json"
19508
+ ], root));
19509
+ return reply(parseJsonOutput(result.stdout) ?? { error: result.stderr || result.stdout }, result.code !== 0);
19510
+ } catch (error) {
19511
+ return failure(error);
19512
+ }
19513
+ });
19514
+ server.registerTool("reaui_audit", {
19515
+ title: "Audit design editability",
19516
+ description: "Read-only heuristic suggestions for hierarchy, names, component reuse and editable SVG geometry. Separate from format validation.",
19517
+ inputSchema: {
19518
+ path: stringType(),
19519
+ strict: booleanType().optional()
19520
+ }
19521
+ }, async (input) => {
19522
+ try {
19523
+ const target = resolveInRoot(root, input.path);
19524
+ const result = await runCli([
19525
+ "audit",
19526
+ relativeTo(root, target),
19527
+ "--json",
19528
+ ...input.strict ? ["--strict"] : []
19529
+ ], root);
19530
+ return reply(parseJsonOutput(result.stdout) ?? {
19531
+ ok: false,
19532
+ error: result.stderr || result.stdout
19533
+ }, result.code !== 0);
19534
+ } catch (error) {
19535
+ return failure(error);
19536
+ }
19537
+ });
19538
+ server.registerTool("reaui_init_components", {
19539
+ title: "Initialize reusable components",
19540
+ description: "Add a catalog to an existing document directory; upgrades v2 to v3, keeps v4, never overwrites existing definitions.",
19541
+ inputSchema: { path: stringType() }
19542
+ }, async (input) => {
19543
+ try {
19544
+ const target = resolveInRoot(root, input.path);
19545
+ const result = await runCli([
19546
+ "components",
19547
+ "init",
19548
+ relativeTo(root, target),
19549
+ "--json"
19550
+ ], root);
19551
+ return reply(parseJsonOutput(result.stdout) ?? {
19552
+ ok: false,
19553
+ error: result.stderr || result.stdout
19554
+ }, result.code !== 0);
19555
+ } catch (error) {
19556
+ return failure(error);
19557
+ }
19558
+ });
19462
19559
  server.registerTool("reaui_init", {
19463
19560
  title: "Create a design document",
19464
19561
  description: "Create a minimal valid .reaui document (rea.json + one page TSX) at the given path. Use this before writing page content. Returns the created path and exit code.",
@@ -19468,7 +19565,9 @@ function registerTools(server, context) {
19468
19565
  pageId: stringType().optional().describe("First page id, lowercase kebab-case. Defaults to \"main\""),
19469
19566
  pageName: stringType().optional().describe("Display name of the first page"),
19470
19567
  width: numberType().int().positive().optional().describe("Desktop artboard width, default 1440"),
19471
- height: numberType().int().positive().optional().describe("Desktop artboard height, default 1024")
19568
+ height: numberType().int().positive().optional().describe("Desktop artboard height, default 1024"),
19569
+ system: stringType().optional().describe("Optional complete reaui-design-system JSON package embedded before page generation"),
19570
+ components: booleanType().optional().describe("Initialize a reusable component catalog (v3, or retain v4 with a system)")
19472
19571
  }
19473
19572
  }, async (input) => {
19474
19573
  try {
@@ -19483,7 +19582,8 @@ function registerTools(server, context) {
19483
19582
  if (input.pageName) args.push("--page-name", input.pageName);
19484
19583
  if (input.width) args.push("--width", String(input.width));
19485
19584
  if (input.height) args.push("--height", String(input.height));
19486
- const result = await runCli(args, root);
19585
+ if (input.components) args.push("--components");
19586
+ const result = await withSystemFile(root, input.system, (extra) => runCli([...args, ...extra], root));
19487
19587
  if (result.code !== 0) return reply({
19488
19588
  ok: false,
19489
19589
  exitCode: result.code,
@@ -19714,6 +19814,8 @@ function registerTools(server, context) {
19714
19814
  })).min(1).describe("One or more pages, written in order"),
19715
19815
  width: numberType().int().positive().optional().describe("Desktop artboard width, default 1440"),
19716
19816
  height: numberType().int().positive().optional().describe("Desktop artboard height, default 1024"),
19817
+ system: stringType().optional().describe("Optional complete reaui-design-system JSON package; pages can reference its --rea-ds-* variables"),
19818
+ components: stringType().optional().describe("Optional complete static components/main.components.tsx source"),
19717
19819
  out: stringType().optional().describe("Output .reaui path, defaults to <path>.reaui")
19718
19820
  }
19719
19821
  }, async (input) => {
@@ -19745,13 +19847,18 @@ function registerTools(server, context) {
19745
19847
  ];
19746
19848
  if (input.width) initArgs.push("--width", String(input.width));
19747
19849
  if (input.height) initArgs.push("--height", String(input.height));
19748
- const init = await runCli(initArgs, root);
19850
+ if (input.components !== void 0) initArgs.push("--components");
19851
+ const init = await withSystemFile(root, input.system, (extra) => runCli([...initArgs, ...extra], root));
19749
19852
  if (init.code !== 0) return reply({
19750
19853
  ok: false,
19751
19854
  stage: "init",
19752
19855
  exitCode: init.code,
19753
19856
  error: init.stdout || init.stderr
19754
19857
  }, true);
19858
+ if (input.components !== void 0) {
19859
+ await mkdir(path.join(docDir, "components"), { recursive: true });
19860
+ await writeFile(path.join(docDir, "components/main.components.tsx"), input.components, "utf8");
19861
+ }
19755
19862
  await mkdir(path.join(docDir, "pages"), { recursive: true });
19756
19863
  for (const page of input.pages) {
19757
19864
  const relative = pageFile(page.id);
@@ -19802,25 +19909,35 @@ function registerTools(server, context) {
19802
19909
  });
19803
19910
  }
19804
19911
  // src/version.ts
19805
- var VERSION = "0.1.0";
19912
+ var VERSION = "0.2.0";
19806
19913
  var SERVER_NAME = "reaui";
19807
19914
  /** 客户端连接时收到的使用说明,决定 agent 第一轮怎么调用。 */
19808
19915
  var INSTRUCTIONS = `REA UI turns a request into an editable .reaui design document.
19809
19916
 
19810
19917
  Typical flow:
19811
19918
  1. reaui_init creates the document directory (or skip it and call reaui_create_design for one-shot generation).
19919
+ Both accept an optional complete system JSON package; it is embedded before token-aware pages are written.
19812
19920
  2. reaui_write_page writes full page TSX and validates immediately, returning structured errors.
19813
- 3. Fix the reported errors and write again, then reaui_pack into a single .reaui file.
19921
+ 3. Fix errors; run reaui_audit for editability suggestions; then reaui_pack into a single .reaui file.
19814
19922
  4. reaui_preview renders a self-contained HTML file you can hand to a human.
19815
19923
 
19816
19924
  Page rules (validation enforces them):
19817
- - Only use primitives exported by @rea/design: Page, Frame, Group, Rect, Ellipse, Text, Vector, Line, Polygon, Star.
19925
+ - Only use primitives exported by @rea/design: Page, Frame, Group, Rect, Ellipse, Text, Vector, Line, Polygon, Star, Instance, SlotContent; define reusable Components/Component/Slot in the component catalog.
19818
19926
  - Do not use div, span, img, svg or project components.
19819
19927
  - Props must be static literals. No functions, events, variables, template strings, map or conditionals.
19820
19928
  - Every top-level Frame needs absolute positioning plus explicit width and height.
19821
- - All styling goes into a Tailwind className string with hex colours.
19929
+ - First use reaui_get_system for an existing project. Its embedded system is the only design-system authority; never substitute a global default.
19930
+ - All styling goes into static Tailwind className. With an embedded system, use declared var(--rea-ds-*) tokens; without one, use existing page styles and literal values.
19931
+ - Use reaui_set_system to adopt a system or remove an unused one. This does not publish a library version. Document v4 supports both components and the embedded system.
19822
19932
  - designId must be lowercase kebab-case and unique within a page.
19823
19933
 
19934
+ Editability rules (quality, not format validation):
19935
+ - Plan named Frame/Group layout sections and records with local coordinates; never flatten a whole screen.
19936
+ - Reuse existing components first; evaluate extracting structures repeated twice or more. Use parameters for content and variants for state. reaui_init accepts components:true; reaui_init_components adds a catalog later without manual manifest edits.
19937
+ - Keep each icon independent with a local viewBox; never merge paths across icons by color or merge text across business records. Preserve compound contours and fill-rule for holes.
19938
+ - 80 layers is a soft planning budget, never a reason to lose hierarchy or independent editing.
19939
+ - Run reaui_audit, inspect its node-level heuristic warnings, repair relevant findings and disclose any accepted limitations. Format validation alone does not prove editability or visual fidelity.
19940
+
19824
19941
  Read the reaui://protocol resource for the full contract and error code table.`;
19825
19942
  // src/server.ts
19826
19943
  function createReauiServer(options) {
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "@xtcel/reaui-mcp",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
+ "mcpName": "io.github.xtcel/reaui",
4
5
  "type": "module",
5
6
  "description": "MCP server for REA UI: let any AI agent create, validate and pack editable .reaui design documents. Runs locally over stdio or remotely over HTTP.",
6
7
  "license": "Apache-2.0",
@@ -45,7 +46,7 @@
45
46
  },
46
47
  "dependencies": {
47
48
  "@modelcontextprotocol/sdk": "^1.32.2",
48
- "@xtcel/reaui-cli": "0.1.3",
49
+ "@xtcel/reaui-cli": "0.2.0",
49
50
  "zod": "^3.25.0"
50
51
  },
51
52
  "devDependencies": {