@rinova/playground-mcp 0.5.0 → 0.7.1

package/dist/index.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { scaffoldScene, validateScenes } from './validate.js';
 const toPosix = (value) => value.split(path.sep).join('/');
 /** 在源文件里定位某个标识符首次出现的行，产出 `path:line` 锚点 */
 const locate = (root, rel, needle) => {
@@ -21,19 +22,74 @@ const locate = (root, rel, needle) => {
         codeLines.find((item) => word.test(item.line));
     return hit ? `${rel}:${hit.index + 1}` : rel;
 };
+const USAGE = `rinova-playground-mcp —— 把契约清单暴露给 AI 编码工具（只读）
+
+用法：
+  rinova-playground-mcp [--project <目录>] [--manifest <文件>]
+
+选项：
+  --project <目录>   项目根（默认：当前目录，并向上找 .playground/manifest.json）
+  --manifest <文件>  直接指定清单文件
+  -h, --help         显示帮助
+
+清单由 @rinova/playground-vite 在 pnpm dev / pnpm build 时生成，需要 playground.config.ts 里配置 components。
+`;
+/** 从 start 向上最多 6 层找 .playground/manifest.json（客户端启动目录常常是包内子目录） */
+const findManifestUp = (start) => {
+    let dir = path.resolve(start);
+    for (let depth = 0; depth < 6; depth += 1) {
+        const candidate = path.join(dir, '.playground/manifest.json');
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+};
+const readStamp = (file) => {
+    try {
+        const stat = fs.statSync(file);
+        return `${stat.mtimeMs}:${stat.size}`;
+    }
+    catch {
+        return 'missing';
+    }
+};
 const parseArgs = (argv) => {
     const args = argv.slice(2);
-    const projectIndex = args.indexOf('--project');
-    const manifestIndex = args.indexOf('--manifest');
-    const project = path.resolve(projectIndex > -1 ? (args[projectIndex + 1] ?? '.') : '.');
-    const manifest = manifestIndex > -1
-        ? path.resolve(args[manifestIndex + 1] ?? '')
-        : path.join(project, '.playground/manifest.json');
-    return { project, manifest };
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(USAGE);
+        process.exit(0);
+    }
+    const readFlag = (flag) => {
+        const index = args.indexOf(flag);
+        return index > -1 ? args[index + 1] : undefined;
+    };
+    const manifestArg = readFlag('--manifest');
+    if (manifestArg) {
+        const manifest = path.resolve(manifestArg);
+        return { project: path.dirname(path.dirname(manifest)), manifest, searchFrom: path.dirname(manifest) };
+    }
+    const projectArg = readFlag('--project');
+    const base = projectArg ? path.resolve(projectArg) : process.cwd();
+    const found = findManifestUp(base);
+    return {
+        project: found ? path.dirname(path.dirname(found)) : base,
+        manifest: found ?? path.join(base, '.playground/manifest.json'),
+        searchFrom: base,
+    };
 };
-const loadManifest = (file) => {
+const loadManifest = (file, searchFrom) => {
     if (!fs.existsSync(file)) {
-        throw new Error(`找不到契约清单：${file}\n先运行 pnpm dev 或 pnpm build 生成（需要 playground.config.ts 里配置 components）`);
+        throw new Error([
+            `找不到契约清单：${file}`,
+            `（从 ${searchFrom} 向上找了 6 层）`,
+            '',
+            '生成方式：在项目里配置 playground.config.ts 的 components（可选 modules），然后跑一次 pnpm dev 或 pnpm build。',
+            '也可以在客户端配置里用 --project <项目根> 或 --manifest <.playground/manifest.json 的绝对路径> 显式指定。',
+        ].join('\n'));
     }
     return JSON.parse(fs.readFileSync(file, 'utf8'));
 };
@@ -106,22 +162,40 @@ const matches = (component, query) => {
         component.scenes.some((scene) => scene.toLowerCase().includes(needle)));
 };
 const main = async () => {
-    const { project, manifest: manifestPath } = parseArgs(process.argv);
+    const { project, manifest: manifestPath, searchFrom } = parseArgs(process.argv);
     let manifest;
     try {
-        manifest = loadManifest(manifestPath);
+        manifest = loadManifest(manifestPath, searchFrom);
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : error);
         process.exitCode = 1;
         return;
     }
-    const server = new McpServer({ name: 'rinova-playground', version: '0.5.0' });
+    /**
+     * 清单是构建产物，dev server 会在场景 / 组件变化后重写它。
+     * 每次工具调用前比一下 mtime+size，变了就重读 —— 否则 MCP 会一直拿启动那一刻的页面表。
+     */
+    let manifestStamp = readStamp(manifestPath);
+    const refresh = () => {
+        const stamp = readStamp(manifestPath);
+        if (stamp === manifestStamp)
+            return;
+        try {
+            manifest = loadManifest(manifestPath, searchFrom);
+            manifestStamp = stamp;
+        }
+        catch {
+            // 清单正在被写（JSON 半个文件）或暂时不可读：沿用上一次的，下次调用再试
+        }
+    };
+    const server = new McpServer({ name: 'rinova-playground', version: '0.7.1' });
     server.registerTool('capability_search', {
         title: '搜索组件能力',
         description: '按组件名 / prop 名 / 场景 id 搜索，返回带文件行号的摘要',
         inputSchema: { query: z.string().min(1).describe('关键词'), limit: z.number().int().min(1).max(20).optional() },
     }, ({ query, limit }) => {
+        refresh();
         const hits = manifest.components.filter((component) => matches(component, query)).slice(0, limit ?? 5);
         if (!hits.length) {
             return { content: [{ type: 'text', text: `没有匹配 "${query}" 的组件。已知组件：${manifest.components.map((item) => item.name).join(', ')}` }] };
@@ -136,6 +210,7 @@ const main = async () => {
         description: '返回组件的 props / events / slots / exposed、源码锚点与相关场景',
         inputSchema: { component: z.string().min(1).describe('组件名，如 MyButton') },
     }, ({ component }) => {
+        refresh();
         const found = manifest.components.find((item) => item.name.toLowerCase() === component.toLowerCase() || item.rel.endsWith(component));
         if (!found) {
             return {
@@ -152,6 +227,7 @@ const main = async () => {
         description: '列出全部场景；传 component 则只列该组件相关的场景',
         inputSchema: { component: z.string().optional().describe('组件名，可选') },
     }, ({ component }) => {
+        refresh();
         const scenes = component
             ? manifest.scenes.filter((scene) => {
                 const target = manifest.components.find((item) => item.name === component);
@@ -170,12 +246,221 @@ const main = async () => {
         description: '列出没有场景覆盖的 props，作为补场景的待办',
         inputSchema: {},
     }, () => {
+        refresh();
         const rows = manifest.components.flatMap((component) => component.uncoveredProps.map((prop) => `- ${component.name}.${prop}  ← ${locate(project, component.rel, prop)}`));
         const total = manifest.components.reduce((sum, component) => sum + component.props.length, 0);
         const uncovered = rows.length;
         const head = `覆盖 ${total - uncovered}/${total}｜清单生成时间 ${manifest.generatedAt}`;
         return { content: [{ type: 'text', text: rows.length ? `${head}\n\n${rows.join('\n')}` : `${head}\n\n全部 props 都有场景覆盖。` }] };
     });
+    const kebab = (input) => {
+        const ascii = input
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '');
+        return ascii || '';
+    };
+    const formatEnv = (manifest) => {
+        const env = manifest.env;
+        if (!env) {
+            return '这份清单里没有 env 段（0.5 及更早的清单没有）。重新跑一次 pnpm dev 生成：清单由 @rinova/playground-vite 在扫描场景时写入。';
+        }
+        const lines = [
+            `# 演示环境：${env.title}`,
+            '',
+            `- 场景目录：${env.sceneRoot}（严格三层：<分组>/<页面>/<场景>；子组件页可四层）`,
+            `- 路由：history 路由 ${env.routeBase} + <分组>/<页面>，页内锚点 #<场景名>`,
+            `- 外壳能力：明暗切换、预览宽度（自适应 / 手机 390 / 平板 820 / 桌面 1280）、源码卡片内搜索、页内索引`,
+            `- 契约：组件 ${env.components.count} 个${env.components.configured ? '' : '（未配置 components）'}、模块 ${env.modules.count} 个${env.modules.configured ? '' : '（未配置 modules）'}、插件 ${env.plugins.length} 个`,
+            `- 主题：外壳 ${env.theme.ui}、演示画布 ${env.theme.stage}；颜色只用 var(--rp-color-*)`,
+            '',
+            '## 分组',
+            '',
+        ];
+        if (!env.groups.length)
+            lines.push('（没有分组：playground.config.ts 里配置 groups）');
+        for (const group of env.groups)
+            lines.push(`- ${group.dir} = ${group.label}`);
+        lines.push('', '## globals（场景里 usePlaygroundEnv() 读取）', '');
+        lines.push(Object.keys(env.globals).length ? '```json\n' + JSON.stringify(env.globals, null, 2) + '\n```' : '（没有配置 globals）');
+        lines.push('', '## 插件', '');
+        if (!env.plugins.length) {
+            lines.push('（没有配置插件；场景里不能假设存在登录态 / 环境变量）');
+        }
+        else {
+            for (const plugin of env.plugins)
+                lines.push(`- ${plugin}`);
+            lines.push('', '场景里这样取：');
+            lines.push('```ts');
+            lines.push("const env = usePlaygroundEnv<{ apiBase: string }>()  // globals + 插件返回值合并");
+            lines.push("const auth = usePlaygroundPlugin<{ user: { name: string } }>('auth')  // name 是插件注册的名字");
+            lines.push('```');
+        }
+        lines.push('', `## 页面（${env.pages.length}）`, '', '| 页面 | id | 绑定 | 场景 |', '|---|---|---|---|');
+        for (const page of env.pages) {
+            const binding = page.component ? `组件 ${page.component}` : page.module ? `模块 ${page.module}` : '内容页';
+            lines.push(`| ${page.title} | ${page.id} | ${binding} | ${page.scenes.length} 个 |`);
+        }
+        return lines.join('\n');
+    };
+    server.registerTool('env_get', {
+        title: '演示环境',
+        description: '返回 globals / 插件 / 分组 / 页面清单与外壳能力，写场景前先读它',
+        inputSchema: {},
+    }, () => {
+        refresh();
+        return { content: [{ type: 'text', text: formatEnv(manifest) }] };
+    });
+    server.registerTool('scene_scaffold', {
+        title: '生成场景骨架',
+        description: '按环境规则算出该建的文件路径与内容（不落盘，写入交给客户端的文件工具）',
+        inputSchema: {
+            title: z.string().min(1).describe('场景标题，如「基础用法」'),
+            page: z.string().optional().describe('已有页面 id（如 button/button）；新建页时传页目录名'),
+            group: z.string().optional().describe('分组目录名，如 button；page 已存在时可省略'),
+            component: z.string().optional().describe('这一页演示的组件名，如 MyButton'),
+            lang: z.enum(['vue', 'md']).optional().describe('场景类型，默认 vue'),
+            section: z.enum(['overview', 'props', 'events', 'exposes', 'slots']).optional(),
+            api: z.array(z.string()).optional().describe('这个场景演示的 API 名'),
+            slug: z.string().optional().describe('场景文件名（不含扩展名）；中文标题请显式传，默认取标题的英文缩写'),
+        },
+    }, ({ title, page, group, component, lang, section, api, slug }) => {
+        refresh();
+        const env = manifest.env;
+        if (!env) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: '这份清单里没有 env 段，无法推算目录。先跑一次 pnpm dev 重新生成清单。',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const matchesPage = page
+            ? env.pages.filter((item) => item.id === page ||
+                (group ? item.id === `${group}/${page}` : false) ||
+                item.dir.split('/').pop() === page ||
+                item.title === page)
+            : [];
+        if (matchesPage.length > 1) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `"${page}" 命中多个页面：${matchesPage.map((item) => item.id).join(', ')}。请传完整 id。`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const target = matchesPage[0];
+        const groupDir = target?.groupDir ?? group;
+        if (!groupDir) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `需要知道放在哪个分组。已有分组：${env.groups.map((item) => item.dir).join(', ') || '（无）'}\n` +
+                            `已有页面：${env.pages.map((item) => item.id).join(', ') || '（无）'}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (!env.groups.some((item) => item.dir === groupDir)) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `分组 "${groupDir}" 不在 playground.config.ts 的 groups 里（现有：${env.groups
+                            .map((item) => item.dir)
+                            .join(', ')}）。要么先登记分组，要么换一个。`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const pageDir = target ? (target.dir.split('/').pop() ?? target.id) : kebab(page ?? component ?? groupDir) || groupDir;
+        const chosenSlug = slug ?? kebab(title) ?? '';
+        if (!chosenSlug) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `标题「${title}」不是英文，算不出文件名。请再传一个 slug（如 basic / size）。`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const componentName = component ?? target?.component;
+        const componentRel = componentName
+            ? manifest.components.find((item) => item.name === componentName)?.rel
+            : undefined;
+        if (componentName && !componentRel) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `组件 "${componentName}" 不在组件契约里（可用：${manifest.components.map((item) => item.name).join(', ') || '无'}）。`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const scaffold = scaffoldScene({
+            sceneRoot: env.sceneRoot,
+            groupDir,
+            pageDir,
+            slug: chosenSlug,
+            title,
+            lang: lang ?? 'vue',
+            component: componentName,
+            componentRel,
+            section,
+            api,
+        });
+        const lines = [`# 要写入的文件`, ''];
+        lines.push('## ' + scaffold.sceneFile, '', '```' + (lang ?? 'vue'), scaffold.sceneContent.trimEnd(), '```', '');
+        if (fs.existsSync(path.join(project, scaffold.pageMetaFile))) {
+            lines.push(`页面目录已存在（${scaffold.pageMetaFile}），只写场景文件即可。`, '');
+        }
+        else {
+            lines.push('## ' + scaffold.pageMetaFile + '（新页面，需要建）', '', '```ts', scaffold.pageMetaContent.trimEnd(), '```', '');
+        }
+        lines.push(`写完之后调 scene_validate（path=${scaffold.sceneFile}）校验；dev server 会自己热更新。`);
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
+    server.registerTool('scene_validate', {
+        title: '校验场景',
+        description: '按框架的硬约束检查场景文件：目录层级、样式 scoped、禁用全局选择器、sceneMeta 字段、页绑定',
+        inputSchema: {
+            path: z.string().optional().describe('只校验这个文件（相对项目根）；不传则全量校验'),
+        },
+    }, ({ path: target }) => {
+        refresh();
+        if (!manifest.env) {
+            return {
+                content: [{ type: 'text', text: '这份清单里没有 env 段，无法校验。先跑一次 pnpm dev 重新生成清单。' }],
+                isError: true,
+            };
+        }
+        const issues = validateScenes(project, manifest, target);
+        const errors = issues.filter((item) => item.level === 'error');
+        const warns = issues.filter((item) => item.level === 'warn');
+        const scope = target ? `文件 ${target}` : `${manifest.scenes.length} 个场景`;
+        if (!issues.length) {
+            return { content: [{ type: 'text', text: `校验通过（${scope}）。` }] };
+        }
+        const lines = [`${scope}：${errors.length} 个错误 / ${warns.length} 个提醒`, ''];
+        for (const issue of [...errors, ...warns]) {
+            lines.push(`- [${issue.level === 'error' ? '错误' : '提醒'}] ${issue.file}${issue.line ? `:${issue.line}` : ''} · ${issue.rule}`);
+            lines.push(`  ${issue.message}`);
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }], isError: errors.length > 0 };
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`[rinova-playground-mcp] 已启动，清单：${manifestPath}（${manifest.components.length} 个组件）`);

package/dist/validate.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 场景校验：把插件的构建期约束抽成可复跑的一套规则，供 MCP 的 `scene_validate` 调用。
+ *
+ * 刻意不依赖任何包（只用 fs / path）：脚本、MCP、verify 都能直接 import 同一份实现。
+ */
+export interface SceneIssue {
+    level: 'error' | 'warn';
+    /** 规则名，报告里直接显示 */
+    rule: string;
+    /** 相对项目根的路径 */
+    file: string;
+    line?: number;
+    message: string;
+}
+export interface ValidatePage {
+    id: string;
+    group: string;
+    groupDir: string;
+    dir: string;
+    component?: string;
+    module?: string;
+    showSource?: boolean;
+    doc?: boolean;
+}
+export interface ValidateManifest {
+    env?: {
+        sceneRoot?: string;
+        pages?: ValidatePage[];
+    };
+    components: Array<{
+        name: string;
+    }>;
+    modules: Array<{
+        name: string;
+    }>;
+    scenes: Array<{
+        id: string;
+        rel: string;
+        lang?: 'vue' | 'md';
+    }>;
+}
+/**
+ * 校验场景与页面绑定。
+ *
+ * `only` 传一个相对路径时只校验该文件（用于「写完立刻验」），否则全量。
+ */
+export declare const validateScenes: (root: string, manifest: ValidateManifest, only?: string) => SceneIssue[];
+/** 场景骨架：`scene_scaffold` 用它生成文件内容（不落盘，写入交给客户端） */
+export interface ScaffoldInput {
+    sceneRoot: string;
+    groupDir: string;
+    pageDir: string;
+    /** 场景文件名（不含扩展名） */
+    slug: string;
+    title: string;
+    lang: 'vue' | 'md';
+    component?: string;
+    /** 组件源码相对项目根的路径（来自清单），用来算相对 import */
+    componentRel?: string;
+    section?: string;
+    api?: string[];
+}
+export declare const scaffoldScene: (input: ScaffoldInput) => {
+    sceneFile: string;
+    sceneContent: string;
+    pageMetaFile: string;
+    pageMetaContent: string;
+};

package/dist/validate.js

@@ -0,0 +1,294 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** sceneMeta 允许的字段（拼错的字段构建期会被静默忽略，所以这里显式列出来） */
+const SCENE_META_FIELDS = new Set([
+    'title',
+    'order',
+    'tags',
+    'description',
+    'hideInNav',
+    'files',
+    'section',
+    'api',
+    'showSource',
+]);
+const toPosix = (value) => value.split(path.sep).join('/');
+const lineOf = (source, index) => source.slice(0, index).split('\n').length;
+/** 极简 frontmatter 读取：只认 `---` 头里的 `key: value` */
+const readFrontmatter = (source) => {
+    const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const data = {};
+    for (const raw of (match[1] ?? '').split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const index = line.indexOf(':');
+        if (index < 1)
+            continue;
+        data[line.slice(0, index).trim()] = line.slice(index + 1).trim();
+    }
+    return data;
+};
+/** 取出 `<script>`（不含 setup）块里的 sceneMeta 对象原文 */
+const readSceneMetaBlock = (source) => {
+    const scripts = [...source.matchAll(/<script([^>]*)>([\s\S]*?)<\/script>/g)];
+    for (const script of scripts) {
+        if (/\bsetup\b/.test(script[1] ?? ''))
+            continue;
+        const body = script[2] ?? '';
+        if (body.includes('sceneMeta'))
+            return body;
+    }
+    return null;
+};
+const checkVueScene = (rel, source) => {
+    const issues = [];
+    for (const style of source.matchAll(/<style([^>]*)>([\s\S]*?)<\/style>/g)) {
+        const attrs = style[1] ?? '';
+        const body = style[2] ?? '';
+        const start = style.index ?? 0;
+        if (!/\bscoped\b/.test(attrs)) {
+            issues.push({
+                level: 'error',
+                rule: 'style-scoped',
+                file: rel,
+                line: lineOf(source, start),
+                message: '<style> 缺少 scoped，样式会污染其它场景',
+            });
+        }
+        for (const hit of body.matchAll(/(?:^|[},])\s*(:root|html|body)\b/gm)) {
+            issues.push({
+                level: 'error',
+                rule: 'style-global',
+                file: rel,
+                line: lineOf(source, start + (hit.index ?? 0)),
+                message: `样式命中 \`${hit[2]}\`，会影响整个 playground`,
+            });
+        }
+    }
+    if (!/<style/.test(source)) {
+        // 不需要样式是合法写法，这里不报
+    }
+    if (/\buseScenePayload\b/.test(source)) {
+        issues.push({
+            level: 'error',
+            rule: 'deprecated-api',
+            file: rel,
+            line: lineOf(source, source.search(/\buseScenePayload\b/)),
+            message: 'useScenePayload 已删除，改用 useSceneArgs / useSceneOutput',
+        });
+    }
+    const meta = readSceneMetaBlock(source);
+    if (meta) {
+        for (const field of meta.matchAll(/(?:^|[{,;\n])\s*([A-Za-z_$][\w$]*)\s*:/gm)) {
+            const name = field[1] ?? '';
+            if (SCENE_META_FIELDS.has(name))
+                continue;
+            issues.push({
+                level: 'warn',
+                rule: 'scene-meta-field',
+                file: rel,
+                line: lineOf(source, (source.indexOf(meta) + (field.index ?? 0))),
+                message: `sceneMeta 里没有 \`${name}\` 这个字段（会被静默忽略）`,
+            });
+        }
+        if (/\bpayload\s*:/.test(meta)) {
+            issues.push({
+                level: 'error',
+                rule: 'deprecated-api',
+                file: rel,
+                line: lineOf(source, source.indexOf(meta)),
+                message: 'sceneMeta.payload 不生效，改用 useSceneArgs / useSceneOutput',
+            });
+        }
+    }
+    else if (source.includes('sceneMeta')) {
+        issues.push({
+            level: 'warn',
+            rule: 'scene-meta-block',
+            file: rel,
+            message: 'sceneMeta 必须写在普通 <script> 块里（<script setup> 里的构建期读不到）',
+        });
+    }
+    return issues;
+};
+const checkMarkdownScene = (rel, source) => {
+    const issues = [];
+    const data = readFrontmatter(source);
+    if (!data.title) {
+        issues.push({ level: 'warn', rule: 'md-title', file: rel, line: 1, message: 'Markdown 场景缺少 frontmatter `title`' });
+    }
+    if (data.showSource && data.showSource !== 'false') {
+        issues.push({
+            level: 'warn',
+            rule: 'md-source',
+            file: rel,
+            line: 1,
+            message: 'Markdown 场景默认不展示源码，这里的 showSource 通常不需要',
+        });
+    }
+    return issues;
+};
+/**
+ * 校验场景与页面绑定。
+ *
+ * `only` 传一个相对路径时只校验该文件（用于「写完立刻验」），否则全量。
+ */
+export const validateScenes = (root, manifest, only) => {
+    const issues = [];
+    const sceneRoot = toPosix(manifest.env?.sceneRoot ?? 'src/scenes').replace(/\/$/, '');
+    const pages = manifest.env?.pages ?? [];
+    const componentNames = new Set(manifest.components.map((item) => item.name));
+    const moduleNames = new Set(manifest.modules.map((item) => item.name));
+    const target = only ? toPosix(only).replace(/^\.\//, '') : '';
+    // 页绑定：组件 / 模块必须真的在契约里（只校验单个文件时跳过，避免报告与这次改动无关的页面）
+    for (const page of target ? [] : pages) {
+        const metaFile = `${page.dir}/meta.ts`;
+        if (page.component && !componentNames.has(page.component)) {
+            issues.push({
+                level: 'error',
+                rule: 'page-component',
+                file: metaFile,
+                message: `pageMeta.component = "${page.component}" 不在组件契约里（可用：${[...componentNames].join(', ') || '无'}）`,
+            });
+        }
+        if (page.module && !moduleNames.has(page.module)) {
+            issues.push({
+                level: 'error',
+                rule: 'page-module',
+                file: metaFile,
+                message: `pageMeta.module = "${page.module}" 不在模块契约里（可用：${[...moduleNames].join(', ') || '无'}）`,
+            });
+        }
+        if (!page.component && !page.module && page.showSource !== false && !page.doc) {
+            issues.push({
+                level: 'warn',
+                rule: 'page-content-source',
+                file: metaFile,
+                message: '内容页（没有 component / module）应写 showSource: false，否则源码卡片会挂在文档页上',
+            });
+        }
+    }
+    const pageDirs = new Set(pages.map((page) => toPosix(page.dir)));
+    const entries = [...manifest.scenes];
+    // 刚写出来的场景还没被扫进清单：指定 path 时也校验（读磁盘，不依赖清单）
+    if (target && !entries.some((scene) => toPosix(scene.rel ?? '') === target)) {
+        entries.push({ id: target, rel: target, lang: target.endsWith('.md') ? 'md' : 'vue' });
+    }
+    for (const scene of entries) {
+        const rel = toPosix(scene.rel ?? '');
+        if (!rel)
+            continue;
+        if (target && rel !== target)
+            continue;
+        const segments = rel.split('/');
+        const depth = segments.length - sceneRoot.split('/').length;
+        if (!rel.startsWith(`${sceneRoot}/`)) {
+            issues.push({
+                level: 'error',
+                rule: 'scene-dir',
+                file: rel,
+                message: `场景必须放在 \`${sceneRoot}/\` 下面`,
+            });
+            continue;
+        }
+        if (depth < 3 || depth > 4) {
+            issues.push({
+                level: 'error',
+                rule: 'scene-dir',
+                file: rel,
+                line: 1,
+                message: `目录层级是 ${depth} 层，必须是 <分组>/<页面>/<场景>（3 层）或 <分组>/<页面>/<子页>/<场景>（4 层）`,
+            });
+        }
+        const pageDir = segments.slice(0, -1).join('/');
+        if (pages.length && !pageDirs.has(pageDir)) {
+            issues.push({
+                level: 'error',
+                rule: 'scene-page',
+                file: rel,
+                message: `所在目录 \`${pageDir}\` 不是任何已登记的页面（缺 meta.ts？）`,
+            });
+        }
+        let source = '';
+        try {
+            source = fs.readFileSync(path.join(root, rel), 'utf8');
+        }
+        catch {
+            issues.push({ level: 'error', rule: 'scene-missing', file: rel, message: '读不到文件' });
+            continue;
+        }
+        if ((scene.lang ?? (rel.endsWith('.md') ? 'md' : 'vue')) === 'md') {
+            issues.push(...checkMarkdownScene(rel, source));
+        }
+        else {
+            issues.push(...checkVueScene(rel, source));
+        }
+    }
+    return issues.sort((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0) || a.level.localeCompare(b.level));
+};
+/** 相对 import：从场景目录指向组件文件 */
+const relativeImport = (fromDir, targetRel) => {
+    const rel = path.posix.relative(fromDir, targetRel);
+    return rel.startsWith('.') ? rel : `./${rel}`;
+};
+export const scaffoldScene = (input) => {
+    const dir = `${input.sceneRoot}/${input.groupDir}/${input.pageDir}`;
+    const component = input.component || 'MyComponent';
+    const importPath = input.componentRel ? relativeImport(dir, input.componentRel) : `@/lib/${component}.vue`;
+    const importHint = input.componentRel ? '' : `  // 换成真实路径：清单里没有 ${component}`;
+    const section = input.section || 'overview';
+    const metaLines = [
+        'export const sceneMeta = {',
+        `  title: '${input.title}',`,
+        `  section: '${section}',`,
+        ...(input.api?.length ? [`  api: [${input.api.map((name) => `'${name}'`).join(', ')}],`] : []),
+        '}',
+    ];
+    const sceneContent = input.lang === 'md'
+        ? ['---', `title: ${input.title}`, '---', '', '正文……', ''].join('\n')
+        : [
+            '<script setup lang="ts">',
+            "import { useSceneArgs } from '@rinova/playground'",
+            `import ${component} from '${importPath}'`,
+            ...(importHint ? [importHint] : []),
+            '',
+            'const args = useSceneArgs({})',
+            '</script>',
+            '',
+            '<script lang="ts">',
+            ...metaLines,
+            '</script>',
+            '',
+            '<template>',
+            '  <div class="demo">',
+            `    <${component} v-bind="args" />`,
+            '  </div>',
+            '</template>',
+            '',
+            '<style scoped lang="less">',
+            '.demo {',
+            '  display: flex;',
+            '  gap: 8px;',
+            '}',
+            '</style>',
+            '',
+        ].join('\n');
+    const pageMetaContent = [
+        "import { definePageMeta } from '@rinova/playground'",
+        '',
+        'export const pageMeta = definePageMeta({',
+        `  title: '${input.pageDir}',`,
+        ...(input.component ? [`  component: '${input.component}',`] : []),
+        '})',
+        '',
+    ].join('\n');
+    return {
+        sceneFile: `${dir}/${input.slug}.${input.lang}`,
+        sceneContent,
+        pageMetaFile: `${dir}/meta.ts`,
+        pageMetaContent,
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rinova/playground-mcp",
-  "version": "0.5.0",
+  "version": "0.7.1",
   "description": "rinova-playground 的 MCP server：把契约清单暴露给 AI 编码工具",
   "type": "module",
   "license": "MIT",