@zat-design/sisyphus-scene 1.0.0 → 4.5.7

package/README.md

@@ -1,44 +1,37 @@
 # Sisyphus Scene
 
-`sisyphus-agent` 下的保险业务场景 Agent 包，跨 Claude Code、Codex、Cursor 分发 Agent Skills 与 Sisyphus MCP 配置。
+## 解决什么问题
 
-## 安装
+从截图或需求识别保险业务场景，查询真实 Sisyphus API/demo，生成可验证的 React/TypeScript 页面骨架。
 
-Node.js 18 及以上版本执行：
+## 前置版本
 
-```bash
-npx -y @zat-design/sisyphus-scene@1.0.0 install
-```
+- Node.js 18+
+- Sisyphus 组件库、MCP 和 Scene：`4.5.7`
+- Ant Design `>=6 <7`
 
-默认在当前项目为 Claude Code、Cursor、Codex 安装最新 Skill 与 MCP。常用参数：
+## 三步安装
 
-| 参数 | 用途 |
-| --- | --- |
-| `--global` | 安装到用户级目录 |
-| `--skill sisyphus-scene-legacy` | 安装 Sisyphus v3 + antd4 技能，不配置 4.x MCP |
-| `--platform claude,cursor,codex` | 仅安装指定平台 |
-| `--skip-mcp` | 只安装 Skill |
-| `--check` | 只检查，不写文件 |
+1. `npx -y @zat-design/sisyphus-scene@4.5.7 install --check`
+2. `npx -y @zat-design/sisyphus-scene@4.5.7 install`
+3. 重启 AI 工具并调用 `sisyphus-get-meta-status`
 
-后续可将 `@1.0.0` 改为 `@latest`。Skill 唯一事实来源仍为 `skills/`；MCP 唯一事实来源为 `mcp/sisyphus-react.json`。
+常用参数：`--global`、`--platform claude,cursor,codex`、`--skip-mcp`、`--skill sisyphus-scene-legacy`。
 
-## 发布检查
+## 推荐调用顺序
 
-```bash
-npm run build:plugin
-npm test
-npm run validate
-npm run mcp:check
-npm run release:check
-npm run pack:check
-```
+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`
 
-`mcp:check` 只检查发布所需的 Claude/Cursor 配置，不要求发布机安装 Codex CLI。需要验证本机 Codex MCP 时执行：
+开发校验使用 `npm test && npm run validate && npm run mcp:check && npm run pack:check`。发布必须从仓库根目录使用 `yarn release:beta` 或 `yarn release`。
 
-```bash
-npm run mcp:check:codex
-```
+## 常见错误
 
-在仓库根目录可直接执行 `npm run release:scene`；子包的 `prepublishOnly` 会自动重复执行上述校验，然后发布到公共 npm registry。
-
-全部通过后，使用具备 `@zat-design` 权限的账号执行 `npm publish --access public`。
+- MCP 冲突：安装器不覆盖现有异构配置。
+- 版本不同：三包必须使用完全相同 SemVer。
+- Cursor 找不到 Skill：检查 `.cursor/skills/sisyphus-scene`。
+- 发布中断：回到仓库根目录重跑同一命令，已发布的同版本包会被跳过。

package/mcp/sisyphus-react.json

@@ -2,7 +2,10 @@
   "mcpServers": {
     "sisyphus-react": {
       "command": "npx",
-      "args": ["-y", "@zat-design/sisyphus-react-mcp@1.0.2"]
+      "args": [
+        "-y",
+        "@zat-design/sisyphus-react-mcp@4.5.7"
+      ]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zat-design/sisyphus-scene",
-  "version": "1.0.0",
+  "version": "4.5.7",
   "description": "Sisyphus 业务场景 Agent 技能，跨 Claude Code、Codex、Cursor 分发 Sisyphus 4 + Ant Design 6 场景与 MCP 配置",
   "type": "module",
   "license": "MIT",
@@ -24,13 +24,12 @@
   },
   "scripts": {
     "build:plugin": "node scripts/build-plugin-package.mjs",
-    "validate": "node scripts/validate-distribution.mjs",
+    "validate:skill": "node skills/sisyphus-scene/scripts/validate-skill.mjs",
+    "validate": "npm run validate:skill && node scripts/validate-distribution.mjs",
     "test": "node --test tests/*.test.mjs",
     "pack:check": "npm pack --dry-run",
     "mcp:check": "node scripts/install-mcp.mjs --platform claude,cursor --project . --check",
     "mcp:check:codex": "node scripts/install-mcp.mjs --platform codex --project . --check",
-    "sync:check": "node scripts/sync-platforms.mjs --platform all --scope user --check",
-    "release:check": "node scripts/release.mjs --check",
-    "prepublishOnly": "npm run build:plugin && npm test && npm run validate && npm run mcp:check && npm run release:check && npm run pack:check"
+    "sync:check": "node scripts/sync-platforms.mjs --platform all --scope user --check"
   }
 }

package/scripts/sync-platforms.mjs

@@ -26,30 +26,47 @@ const parseArgs = (argv) => {
 };
 
 const args = parseArgs(process.argv.slice(2));
-const platforms = String(args.platform || 'all') === 'all' ? ['claude', 'codex', 'cursor'] : String(args.platform).split(',');
+const platforms =
+  String(args.platform || 'all') === 'all'
+    ? ['claude', 'codex', 'cursor']
+    : String(args.platform).split(',');
 const scope = String(args.scope || 'user');
 const skills = String(args.skill || 'sisyphus-scene').split(',');
 const write = Boolean(args.write);
 const check = Boolean(args.check);
 if (write === check || (!write && !check)) throw new Error('必须且只能指定 --check 或 --write。');
 if (!['user', 'project'].includes(scope)) throw new Error(`不支持的 scope：${scope}`);
-for (const platform of platforms) if (!['claude', 'codex', 'cursor'].includes(platform)) throw new Error(`不支持的平台：${platform}`);
+for (const platform of platforms)
+  if (!['claude', 'codex', 'cursor'].includes(platform))
+    throw new Error(`不支持的平台：${platform}`);
 for (const skill of skills) {
-  if (!['sisyphus-scene', 'sisyphus-scene-legacy'].includes(skill)) throw new Error(`不支持的 skill：${skill}`);
+  if (!['sisyphus-scene', 'sisyphus-scene-legacy'].includes(skill))
+    throw new Error(`不支持的 skill：${skill}`);
 }
 
 const projectRoot = path.resolve(String(args.project || process.cwd()));
 const baseDirectories = {
-  claude: scope === 'user' ? path.join(os.homedir(), '.claude', 'skills') : path.join(projectRoot, '.claude', 'skills'),
-  codex: scope === 'user' ? path.join(os.homedir(), '.agents', 'skills') : path.join(projectRoot, '.agents', 'skills'),
-  cursor: scope === 'user' ? path.join(os.homedir(), '.agents', 'skills') : path.join(projectRoot, '.agents', 'skills'),
+  claude:
+    scope === 'user'
+      ? path.join(os.homedir(), '.claude', 'skills')
+      : path.join(projectRoot, '.claude', 'skills'),
+  codex:
+    scope === 'user'
+      ? path.join(os.homedir(), '.agents', 'skills')
+      : path.join(projectRoot, '.agents', 'skills'),
+  cursor:
+    scope === 'user'
+      ? path.join(os.homedir(), '.cursor', 'skills')
+      : path.join(projectRoot, '.cursor', 'skills'),
 };
 
 const hashDirectory = (directory) => {
   if (!fs.existsSync(directory)) return null;
   const hash = crypto.createHash('sha256');
   const visit = (current, relative = '') => {
-    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+    for (const entry of fs
+      .readdirSync(current, { withFileTypes: true })
+      .sort((left, right) => left.name.localeCompare(right.name))) {
       const nextRelative = path.join(relative, entry.name);
       const next = path.join(current, entry.name);
       if (entry.isDirectory()) visit(next, nextRelative);
@@ -84,4 +101,7 @@ for (const platform of platforms) {
   }
 }
 
-process.stdout.write(JSON.stringify({ sourceRoot, scope, skills, mode: write ? 'write' : 'check', results }, null, 2) + '\n');
+process.stdout.write(
+  JSON.stringify({ sourceRoot, scope, skills, mode: write ? 'write' : 'check', results }, null, 2) +
+    '\n',
+);

package/skills/sisyphus-scene/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sisyphus-scene
-description: 基于最新 @zat-design/sisyphus-react 4.x 与 Ant Design 6，从页面截图或需求描述识别保险业务场景并生成 React/TypeScript 脚手架。用于查询列表、Tab 分组列表、列表弹窗、多 Tab 详情、分区详情、列表跳转详情、步骤条分区表单、参考其他应用实现，以及无法命中既有模板时基于 MCP demo 组合新场景；支持 Claude Code、Codex、Cursor，不绑定 Umi Max。
+description: 基于与 Scene Agent 完全同版的 @zat-design/sisyphus-react 4.x 和 Ant Design 6，从页面截图或需求描述识别保险业务场景并生成 React/TypeScript 脚手架。用于查询列表、Tab 分组列表、列表弹窗、多 Tab 详情、分区详情、列表跳转详情、步骤条分区表单、参考其他应用实现，以及无法命中既有模板时基于 MCP demo 组合新场景；支持 Claude Code、Codex、Cursor，不绑定 Umi Max。
 ---
 
 # Sisyphus 业务场景生成
@@ -9,7 +9,7 @@ description: 基于最新 @zat-design/sisyphus-react 4.x 与 Ant Design 6，从
 
 ## 不可跳过的约束
 
-- 仅支持 React + TypeScript、最新目标版本的 `@zat-design/sisyphus-react` 4.x 和 Ant Design 6。
+- 仅支持 React + TypeScript、`assets/ai-contract.json` 声明的 Sisyphus 完全同版组合和 Ant Design 6。
 - Umi Max、React Router、请求库、权限和状态库都属于目标项目适配，不是技能依赖。
 - 无论场景是否命中模板，先查询 Sisyphus MCP 的组件列表、完整 API 和 demo。
 - 只有 Sisyphus MCP 明确给出 `missing` 的能力才可进入 Ant Design 补全；`unverified` 必须先修复 MCP 连接或版本问题。
@@ -41,13 +41,12 @@ description: 基于最新 @zat-design/sisyphus-react 4.x 与 Ant Design 6，从
 运行：
 
 ```bash
-node scripts/resolve-versions.mjs --root <项目根目录> --channel stable
+node scripts/resolve-versions.mjs --root <项目根目录>
 ```
 
-- Ant Design 必须满足最新稳定 `>=6 <7`。
-- Sisyphus 必须满足最新稳定 `>=4 <5`。
-- beta 仅在用户明确要求时使用 `--channel beta`。
-- 项目版本、registry 最新版本、MCP 报告版本不一致时停止，并输出独立升级建议。
+- Ant Design 本地安装版本必须满足 `>=6 <7`。
+- Sisyphus 本地安装版本、MCP 内置元数据、MCP 和 Scene 契约版本必须完全相等。
+- registry latest 默认只警告；用户明确要求追踪最新版时增加 `--strict-latest`。
 
 ### 3. 从截图或需求建立 SceneSpec
 
@@ -65,11 +64,14 @@ node scripts/resolve-versions.mjs --root <项目根目录> --channel stable
 
 对本次候选组件依次执行：
 
-1. `sisyphus-list-components`
-2. `sisyphus-get-component-api(<组件名>)`
-3. `sisyphus-get-examples(<组件名>, <场景关键词>)`
+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(<示例 ID>)`
 
-记录 MCP 报告版本、API 证据和 demo 证据。模板与 MCP 冲突时以匹配目标版本的 MCP 为准。
+记录结构化 API/demo 证据，包含工具名、目标、完整版本、schema v2 和 demo ID。禁止为找一个用法一次拉取全部 demo 源码。
 
 ### 5. 匹配或构造场景
 
@@ -146,4 +148,4 @@ node scripts/validate-scaffold.mjs \
 - 生成后校验规则：`references/validation-rules.md`
 - 可引用的团队批准样例：`references/approved-examples.yaml`
 - 结构模板注册表：`assets/templates/scene-registry.json`
-
+- 同版本 MCP/Scene 机器契约：`assets/ai-contract.json`

package/skills/sisyphus-scene/assets/ai-contract.json

@@ -0,0 +1,14 @@
+{
+  "version": "4.5.7",
+  "schemaVersion": 2,
+  "tools": [
+    "sisyphus-get-meta-status",
+    "sisyphus-list-components",
+    "sisyphus-get-component-api",
+    "sisyphus-get-type",
+    "sisyphus-list-examples",
+    "sisyphus-get-example",
+    "sisyphus-search",
+    "sisyphus-get-examples"
+  ]
+}

package/skills/sisyphus-scene/evals/fixtures/valid-decisions.json

@@ -5,8 +5,19 @@
     "status": "covered",
     "source": "sisyphus",
     "component": "ProForm",
-    "apiEvidence": "sisyphus-get-component-api(ProForm)",
-    "demoEvidence": "sisyphus-get-examples(ProForm, 查询)"
+    "apiEvidence": {
+      "tool": "sisyphus-get-component-api",
+      "target": "ProForm",
+      "libraryVersion": "4.5.7",
+      "schemaVersion": 2
+    },
+    "demoEvidence": {
+      "tool": "sisyphus-get-example",
+      "target": "ProForm/demos/base.tsx",
+      "libraryVersion": "4.5.7",
+      "schemaVersion": 2,
+      "exampleId": "ProForm/demos/base.tsx"
+    }
   },
   {
     "requirementId": "data-table",
@@ -14,8 +25,18 @@
     "status": "covered",
     "source": "sisyphus",
     "component": "ProTable",
-    "apiEvidence": "sisyphus-get-component-api(ProTable)",
-    "demoEvidence": "sisyphus-get-examples(ProTable, 查询列表)"
+    "apiEvidence": {
+      "tool": "sisyphus-get-component-api",
+      "target": "ProTable",
+      "libraryVersion": "4.5.7",
+      "schemaVersion": 2
+    },
+    "demoEvidence": {
+      "tool": "sisyphus-get-example",
+      "target": "ProTable/demos/base.tsx",
+      "libraryVersion": "4.5.7",
+      "schemaVersion": 2,
+      "exampleId": "ProTable/demos/base.tsx"
+    }
   }
 ]
-

package/skills/sisyphus-scene/evals/generation-cases.yaml

@@ -18,6 +18,15 @@ cases:
   - id: unverified-is-not-missing
     sisyphus_status: unverified
     expected_result: generation-blocked
+  - id: string-evidence-is-invalid
+    evidence_shape: string
+    expected_result: validation-failure
+  - id: mismatched-mcp-evidence-version
+    evidence_version: '4.5.7-beta.2'
+    expected_result: validation-failure
+  - id: demo-evidence-without-id
+    evidence_tool: sisyphus-get-example
+    expected_result: validation-failure
   - id: project-component-fallback
     sisyphus_status: missing
     antd_status: missing

package/skills/sisyphus-scene/references/approved-examples.yaml

@@ -7,10 +7,9 @@ examples: []
 #   status: approved
 #   application: xk-wjs-claim-web
 #   capabilities: [search-form, data-table, table-tabs, drawer-form]
-#   sisyphus_range: ">=4 <5"
+#   sisyphus_version: "4.5.7"
 #   antd_range: ">=6 <7"
 #   paths:
 #     - src/pages/litigationManagement/index.tsx
 #   verified_at: 2026-07-10
 #   notes: 只复用结构，不覆盖 MCP API 证据
-

package/skills/sisyphus-scene/references/integration-contracts.md

@@ -71,14 +71,22 @@ interface CapabilityRequirement {
   required: boolean;
 }
 
+interface ComponentEvidence {
+  tool: string;
+  target: string;
+  libraryVersion: string;
+  schemaVersion?: number;
+  exampleId?: string;
+}
+
 interface ComponentDecision {
   requirementId: string;
   requirement: string;
   status: CapabilityStatus;
   source: ComponentSource;
   component?: string;
-  apiEvidence?: string;
-  demoEvidence?: string;
+  apiEvidence?: ComponentEvidence;
+  demoEvidence?: ComponentEvidence;
   fallbackReason?: string;
 }
 ```
@@ -86,7 +94,8 @@ interface ComponentDecision {
 规则：
 
 - 每个必需 requirement 恰好一条 decision。
-- `sisyphus` 来源必须有 API 和 demo 证据。
+- `sisyphus` 来源必须使用结构化 API/demo 证据，记录完全相同的组件版本与 schema v2。
+- API 证据必须来自 `sisyphus-get-component-api`；demo 证据必须来自 `sisyphus-get-example` 并记录 `exampleId`。
 - `antd` 来源必须有 API/demo 证据与 fallbackReason。
 - `project` 来源必须有源码路径与调用示例证据。
 - `unresolved` 或 `unverified` 阻断生成。
@@ -95,10 +104,19 @@ interface ComponentDecision {
 
 ```ts
 interface ComponentDocsProvider {
+  getMetaStatus(): Promise<ComponentMetaStatus>;
   listComponents(): Promise<ComponentSummary[]>;
   getComponentApi(name: string): Promise<ComponentApi>;
-  getExamples(name: string, scenario?: string): Promise<ComponentExample[]>;
-  getVersion(): Promise<string>;
+  getType(name: string): Promise<ComponentType>;
+  listExamples(
+    name: string,
+    scenario?: string,
+    cursor?: string,
+  ): Promise<ComponentExampleSummary[]>;
+  getExample(id: string): Promise<ComponentExample>;
+  search(query: string): Promise<ComponentSearchResult[]>;
+  /** 仅用于兼容旧 MCP 工具，新流程不得使用。 */
+  getExamples?(name: string, scenario?: string): Promise<ComponentExample[]>;
 }
 ```
 
@@ -109,4 +127,3 @@ interface ComponentDocsProvider {
 - `Context7AntdProvider`
 
 这里只定义能力，不把任何平台的 MCP 工具前缀写入生成代码。
-

package/skills/sisyphus-scene/references/platform-claude.md

@@ -3,8 +3,7 @@
 - 用户级安装目录：`~/.claude/skills/sisyphus-scene`
 - 项目级安装目录：`.claude/skills/sisyphus-scene`
 - 使用 `${CLAUDE_SKILL_DIR}` 定位 scripts、references 和 assets。
-- 首先通过 ToolSearch 发现 `sisyphus-list-components`、`sisyphus-get-component-api`、`sisyphus-get-examples` 和 `sisyphus-search`。
+- 首先通过 ToolSearch 发现 `sisyphus-get-meta-status`、`sisyphus-list-components`、`sisyphus-get-component-api`、`sisyphus-get-type`、`sisyphus-list-examples`、`sisyphus-get-example` 和 `sisyphus-search`。
 - Ant Design MCP 不可用时，通过 Context7 查询 antd 6 官方文档。
 - 读取项目 `CLAUDE.md`，同时显式检查 `AGENTS.md` 和 `.cursor/rules`；同级冲突时停止。
 - 不使用 Claude 专属 frontmatter 驱动共享核心行为，保证同一 SKILL.md 可被其他平台读取。
-

package/skills/sisyphus-scene/references/platform-codex.md

@@ -3,8 +3,8 @@
 - 用户级安装目录：`~/.agents/skills/sisyphus-scene`
 - 项目级安装目录：`.agents/skills/sisyphus-scene`
 - 以当前加载的 SKILL.md 所在目录解析相对资源。
-- 从当前工具列表或 MCP 资源中发现 Sisyphus 工具；工具未安装时停止并给出配置建议，不读取 node_modules 替代。
+- 按 `get-meta-status` → `list-components` → `get-component-api` →按需 `get-type` → `list-examples` → `get-example` 的顺序调用 Sisyphus MCP。
+- 工具未安装时停止并给出配置建议，不读取 node_modules 替代。
 - `agents/openai.yaml` 只承载 UI 元数据。当前 Sisyphus MCP 是本地 stdio 命令，没有可验证的 streamable HTTP URL，因此不伪造 Codex MCP dependency。
 - 读取最近层级的 `AGENTS.md`，并显式检查 `CLAUDE.md` 和 `.cursor/rules`。
 - 修改已有代码符号前遵循项目 GitNexus impact 约束，完成后执行 detect changes。
-

package/skills/sisyphus-scene/references/platform-cursor.md

@@ -3,8 +3,7 @@
 - 用户级安装目录：`~/.cursor/skills/sisyphus-scene`
 - 项目级安装目录：`.cursor/skills/sisyphus-scene`
 - 以当前技能目录解析 scripts、references 和 assets。
-- 从 Cursor MCP 配置发现 `sisyphus-react`、Ant Design 文档提供器和 Context7。
+- 从 Cursor MCP 配置发现 `sisyphus-react`，按 `get-meta-status` → `list-components` → `get-component-api` →按需 `get-type` → `list-examples` → `get-example` 调用。
 - 读取并应用 `.cursor/rules/*.mdc`，同时检查项目根 `AGENTS.md` 与 `CLAUDE.md`。
 - Cursor Rules 是持久项目规范，Skill 是按需工作流；不要把整份团队规范复制进 SKILL.md。
 - MCP 工具未出现或缓存版本与目标包不一致时，停止并要求刷新 MCP，不使用旧缓存继续生成。
-

package/skills/sisyphus-scene/scripts/resolve-versions.mjs

@@ -4,11 +4,12 @@ import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
 
-const PACKAGES = [
-  { name: 'antd', major: 6 },
-  { name: '@zat-design/sisyphus-react', major: 4 },
-];
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const contract = JSON.parse(
+  fs.readFileSync(path.join(skillRoot, 'assets', 'ai-contract.json'), 'utf8'),
+);
 
 const parseArgs = (argv) => {
   const args = {};
@@ -57,8 +58,12 @@ const readPackageJson = (root) => {
 };
 
 const getDeclaredVersion = (packageJson, packageName) => {
-  const sections = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
-  for (const section of sections) {
+  for (const section of [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+  ]) {
     const value = packageJson[section]?.[packageName];
     if (value) return value;
   }
@@ -66,27 +71,23 @@ const getDeclaredVersion = (packageJson, packageName) => {
 };
 
 const getPackageLockVersion = (root, packageName) => {
-  const packageLockPath = path.join(root, 'package-lock.json');
-  if (!fs.existsSync(packageLockPath)) return undefined;
-  try {
-    const lock = JSON.parse(fs.readFileSync(packageLockPath, 'utf8'));
-    return lock.packages?.[`node_modules/${packageName}`]?.version;
-  } catch {
-    return undefined;
-  }
+  const file = path.join(root, 'package-lock.json');
+  if (!fs.existsSync(file)) return undefined;
+  return JSON.parse(fs.readFileSync(file, 'utf8')).packages?.[`node_modules/${packageName}`]
+    ?.version;
 };
 
 const getYarnLockVersion = (root, packageName, declared) => {
-  const yarnLockPath = path.join(root, 'yarn.lock');
-  if (!fs.existsSync(yarnLockPath)) return undefined;
-  const content = fs.readFileSync(yarnLockPath, 'utf8');
+  const file = path.join(root, 'yarn.lock');
+  if (!fs.existsSync(file)) return undefined;
+  const content = fs.readFileSync(file, 'utf8');
   const escaped = packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const escapedSelector = declared
+  const selector = declared
     ? `${escaped}@${String(declared).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`
     : undefined;
   for (const block of content.split(/\n{2,}/)) {
     const header = block.split('\n', 1)[0];
-    if (escapedSelector && !new RegExp(`(?:^|["',\\s])${escapedSelector}(?:["',:]|$)`).test(header)) continue;
+    if (selector && !new RegExp(`(?:^|["',\\s])${selector}(?:["',:]|$)`).test(header)) continue;
     if (!new RegExp(`(?:^|["',\\s])${escaped}@`).test(header)) continue;
     const version = block.match(/^\s{2}version\s+["']?([^"'\n]+)["']?$/m);
     if (version) return version[1];
@@ -95,29 +96,27 @@ const getYarnLockVersion = (root, packageName, declared) => {
 };
 
 const getPnpmLockVersion = (root, packageName) => {
-  const pnpmLockPath = path.join(root, 'pnpm-lock.yaml');
-  if (!fs.existsSync(pnpmLockPath)) return undefined;
-  const content = fs.readFileSync(pnpmLockPath, 'utf8');
+  const file = path.join(root, 'pnpm-lock.yaml');
+  if (!fs.existsSync(file)) return undefined;
+  const content = fs.readFileSync(file, 'utf8');
   const escaped = packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const patterns = [
+  for (const pattern of [
     new RegExp(`(?:^|\\n)\\s{2,}['"]?${escaped}@([^:'"\\s]+)`, 'm'),
     new RegExp(`(?:^|\\n)\\s{2,}/?${escaped}/([^:\\s]+):`, 'm'),
-  ];
-  for (const pattern of patterns) {
+  ]) {
     const match = content.match(pattern);
     if (match) return match[1];
   }
   return undefined;
 };
 
-const getResolvedVersions = (root, packageName, declared) => {
+const getResolution = (root, packageName, declared) => {
   const values = {
     packageLock: getPackageLockVersion(root, packageName),
     yarnLock: getYarnLockVersion(root, packageName, declared),
     pnpmLock: getPnpmLockVersion(root, packageName),
   };
-  const present = Object.values(values).filter(Boolean);
-  const unique = [...new Set(present)];
+  const unique = [...new Set(Object.values(values).filter(Boolean))];
   return {
     values,
     resolved: unique.length === 1 ? unique[0] : undefined,
@@ -125,80 +124,86 @@ const getResolvedVersions = (root, packageName, declared) => {
   };
 };
 
-const queryVersions = (root, packageName) => {
-  const output = execFileSync('npm', ['view', packageName, 'versions', '--json'], {
-    cwd: root,
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  const parsed = JSON.parse(output);
-  return Array.isArray(parsed) ? parsed : [parsed];
-};
-
-const chooseLatest = (versions, major, channel) =>
-  versions
-    .filter((version) => {
-      const parsed = parseVersion(version);
-      if (!parsed || parsed.major !== major) return false;
-      return channel === 'beta' || !parsed.prerelease;
+const queryLatest = (root, packageName, major, channel) => {
+  const output = execFileSync(
+    process.env.NPM_EXECUTABLE || 'npm',
+    ['view', packageName, 'versions', '--json'],
+    { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+  );
+  const values = JSON.parse(output);
+  return (Array.isArray(values) ? values : [values])
+    .filter((value) => {
+      const parsed = parseVersion(value);
+      return parsed?.major === major && (channel === 'beta' || !parsed.prerelease);
     })
     .sort(compareVersions)
     .at(-1);
-
-const evaluateStatus = ({ declared, resolved, latest, major, lockConflict }) => {
-  if (lockConflict) return 'lock-conflict';
-  const active = parseVersion(resolved || declared);
-  if (!active) return 'unknown';
-  if (active.major !== major) return 'unsupported-major';
-  if (!latest) return 'unknown';
-  return compareVersions(active.raw, latest) === 0 ? 'ok' : 'outdated';
 };
 
 const args = parseArgs(process.argv.slice(2));
 const root = path.resolve(String(args.root || process.cwd()));
-const channel = String(args.channel || 'stable');
+const expected = parseVersion(contract.version);
+const channel = String(args.channel || (expected.prerelease ? 'beta' : 'stable'));
 if (!['stable', 'beta'].includes(channel)) throw new Error(`不支持的 channel：${channel}`);
 const offline = Boolean(args.offline);
+const strictLatest = Boolean(args['strict-latest']);
 const packageJson = readPackageJson(root);
+const warnings = [];
 
-const results = PACKAGES.map(({ name, major }) => {
+const packages = [
+  { name: 'antd', major: 6 },
+  { name: '@zat-design/sisyphus-react', major: expected.major },
+].map(({ name, major }) => {
   const declared = getDeclaredVersion(packageJson, name);
-  const lockResolution = getResolvedVersions(root, name, declared);
-  let versions = [];
+  const resolution = getResolution(root, name, declared);
+  const active = resolution.resolved || parseVersion(declared)?.raw;
+  let latest;
   let registryError;
   if (!offline) {
     try {
-      versions = queryVersions(root, name);
+      latest = queryLatest(root, name, major, channel);
     } catch (error) {
       registryError = error.stderr?.trim() || error.message;
     }
   }
-  const latest = chooseLatest(versions, major, channel);
+
+  let status = 'ok';
+  if (resolution.conflict) status = 'lock-conflict';
+  else if (!parseVersion(active)) status = 'unknown';
+  else if (name === 'antd' && parseVersion(active).major !== 6) status = 'unsupported-major';
+  else if (name === '@zat-design/sisyphus-react' && active !== contract.version)
+    status = 'version-mismatch';
+  else if (strictLatest && (!latest || active !== latest)) status = 'outdated';
+  else if (latest && active !== latest)
+    warnings.push(`${name} 当前 ${active}，registry ${channel} 最新 ${latest}`);
+  if (registryError) warnings.push(`${name} registry 查询失败：${registryError}`);
+
   return {
     name,
-    requiredRange: `>=${major} <${major + 1}`,
-    channel,
+    required: name === 'antd' ? '>=6 <7' : contract.version,
     declared,
-    resolved: lockResolution.resolved,
-    resolvedVersions: lockResolution.values,
+    resolved: resolution.resolved,
+    resolvedVersions: resolution.values,
+    active,
     latest,
-    status: evaluateStatus({
-      declared,
-      resolved: lockResolution.resolved,
-      latest,
-      major,
-      lockConflict: lockResolution.conflict,
-    }),
+    status,
     ...(registryError ? { registryError } : {}),
   };
 });
 
 const report = {
   root,
+  contract,
   channel,
-  ok: results.every((item) => item.status === 'ok'),
-  packages: results,
+  strictLatest,
+  metadata: {
+    source: '@zat-design/sisyphus-react-mcp',
+    version: contract.version,
+    schemaVersion: contract.schemaVersion,
+  },
+  ok: packages.every((item) => item.status === 'ok'),
+  warnings,
+  packages,
 };
-
 process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 if (!report.ok) process.exitCode = 2;

package/skills/sisyphus-scene/scripts/validate-scaffold.mjs

@@ -3,6 +3,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const contract = JSON.parse(
+  fs.readFileSync(path.join(skillRoot, 'assets', 'ai-contract.json'), 'utf8'),
+);
 
 const parseArgs = (argv) => {
   const args = {};
@@ -32,11 +38,18 @@ const readDecisions = (filePath) => {
 
 const extractNamedImports = (content, source) => {
   const escaped = source.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const regex = new RegExp(`import\\s+(?:type\\s+)?\\{([^}]+)\\}\\s+from\\s+['"]${escaped}['"]`, 'g');
+  const regex = new RegExp(
+    `import\\s+(?:type\\s+)?\\{([^}]+)\\}\\s+from\\s+['"]${escaped}['"]`,
+    'g',
+  );
   const names = [];
   for (const match of content.matchAll(regex)) {
     for (const token of match[1].split(',')) {
-      const name = token.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim();
+      const name = token
+        .trim()
+        .replace(/^type\s+/, '')
+        .split(/\s+as\s+/)[0]
+        .trim();
       if (name) names.push(name);
     }
   }
@@ -60,25 +73,92 @@ const checks = [];
 
 const addError = (file, rule, message) => errors.push({ file, rule, message });
 const addWarning = (file, rule, message) => warnings.push({ file, rule, message });
+const isEvidence = (value) =>
+  value &&
+  typeof value === 'object' &&
+  !Array.isArray(value) &&
+  [value.tool, value.target, value.libraryVersion].every(
+    (item) => typeof item === 'string' && item.trim(),
+  );
+const validateSisyphusEvidence = (decision, key, tool, requireExampleId = false) => {
+  const evidence = decision[key];
+  if (!isEvidence(evidence)) {
+    addError(
+      decisionsPath,
+      'sisyphus-evidence',
+      `${decision.requirement} 的 ${key} 必须是结构化证据`,
+    );
+    return;
+  }
+  if (evidence.tool !== tool) {
+    addError(
+      decisionsPath,
+      'sisyphus-evidence-tool',
+      `${decision.requirement} 的 ${key} 必须来自 ${tool}`,
+    );
+  }
+  if (
+    evidence.libraryVersion !== contract.version ||
+    evidence.schemaVersion !== contract.schemaVersion
+  ) {
+    addError(
+      decisionsPath,
+      'sisyphus-evidence-version',
+      `${decision.requirement} 的 ${key} 版本/schema 必须为 ${contract.version}/v${contract.schemaVersion}`,
+    );
+  }
+  if (requireExampleId && (!evidence.exampleId || evidence.exampleId !== evidence.target)) {
+    addError(
+      decisionsPath,
+      'sisyphus-demo-id',
+      `${decision.requirement} 的 demo 证据必须记录与 target 一致的 exampleId`,
+    );
+  }
+};
 
 for (const decision of decisions) {
   if (!decision.requirementId || !decision.requirement) {
-    addError(decisionsPath, 'decision-schema', '每条 decision 必须包含 requirementId 和 requirement');
+    addError(
+      decisionsPath,
+      'decision-schema',
+      '每条 decision 必须包含 requirementId 和 requirement',
+    );
+  }
+  if (!['covered', 'partial', 'missing', 'unverified'].includes(decision.status)) {
+    addError(decisionsPath, 'decision-schema', `非法的能力状态：${decision.status}`);
   }
-  if (['unverified', 'unresolved'].includes(decision.status) || decision.source === 'unresolved') {
-    addError(decisionsPath, 'unresolved-capability', `能力未解决：${decision.requirement || decision.requirementId}`);
+  if (decision.status === 'unverified' || decision.source === 'unresolved') {
+    addError(
+      decisionsPath,
+      'unresolved-capability',
+      `能力未解决：${decision.requirement || decision.requirementId}`,
+    );
   }
-  if (decision.source === 'sisyphus' && (!decision.apiEvidence || !decision.demoEvidence)) {
-    addError(decisionsPath, 'sisyphus-evidence', `Sisyphus 决策缺少 API 或 demo 证据：${decision.requirement}`);
+  if (decision.source === 'sisyphus') {
+    validateSisyphusEvidence(decision, 'apiEvidence', 'sisyphus-get-component-api');
+    validateSisyphusEvidence(decision, 'demoEvidence', 'sisyphus-get-example', true);
   }
   if (
     decision.source === 'antd' &&
-    (!decision.apiEvidence || !decision.demoEvidence || !decision.fallbackReason)
+    (!isEvidence(decision.apiEvidence) ||
+      !isEvidence(decision.demoEvidence) ||
+      !decision.fallbackReason)
   ) {
-    addError(decisionsPath, 'antd-fallback-evidence', `Ant Design fallback 证据不完整：${decision.requirement}`);
+    addError(
+      decisionsPath,
+      'antd-fallback-evidence',
+      `Ant Design fallback 证据不完整：${decision.requirement}`,
+    );
   }
-  if (decision.source === 'project' && (!decision.apiEvidence || !decision.demoEvidence)) {
-    addError(decisionsPath, 'project-evidence', `项目组件决策缺少源码或调用示例：${decision.requirement}`);
+  if (
+    decision.source === 'project' &&
+    (!isEvidence(decision.apiEvidence) || !isEvidence(decision.demoEvidence))
+  ) {
+    addError(
+      decisionsPath,
+      'project-evidence',
+      `项目组件决策缺少源码或调用示例：${decision.requirement}`,
+    );
   }
 }
 
@@ -105,31 +185,49 @@ for (const filePath of files) {
   }
 
   if (/\bProForm\b/.test(content) && /<Form\.Item\b/.test(content)) {
-    addError(relative, 'proform-form-item', 'ProForm 中混入 Form.Item，必须提供明确组件证据或改用配置列');
+    addError(
+      relative,
+      'proform-form-item',
+      'ProForm 中混入 Form.Item，必须提供明确组件证据或改用配置列',
+    );
   }
 
-  const sisyphusImports = extractNamedImports(content, '@zat-design/sisyphus-react').filter((name) =>
-    /^Pro[A-Z]/.test(name) && !/(Type|Props)$/.test(name),
+  const sisyphusImports = extractNamedImports(content, '@zat-design/sisyphus-react').filter(
+    (name) => /^Pro[A-Z]/.test(name) && !/(Type|Props)$/.test(name),
   );
   for (const component of sisyphusImports) {
     const decision = decisions.find(
-      (item) => item.source === 'sisyphus' && item.component === component && item.status !== 'unverified',
+      (item) =>
+        item.source === 'sisyphus' && item.component === component && item.status !== 'unverified',
     );
     if (!decision) {
-      addError(relative, 'sisyphus-component-decision', `组件 ${component} 缺少 ComponentDecision 证据`);
+      addError(
+        relative,
+        'sisyphus-component-decision',
+        `组件 ${component} 缺少 ComponentDecision 证据`,
+      );
     }
   }
 
-  const structuralAntdComponents = new Set(['Tabs', 'Modal', 'Drawer', 'Table', 'Steps', 'Collapse']);
-  const antdImports = extractNamedImports(content, 'antd').filter((name) => structuralAntdComponents.has(name));
+  const structuralAntdComponents = new Set([
+    'Tabs',
+    'Modal',
+    'Drawer',
+    'Table',
+    'Steps',
+    'Collapse',
+  ]);
+  const antdImports = extractNamedImports(content, 'antd').filter((name) =>
+    structuralAntdComponents.has(name),
+  );
   for (const component of antdImports) {
     const decision = decisions.find(
       (item) =>
         item.source === 'antd' &&
         item.component === component &&
         item.fallbackReason &&
-        item.apiEvidence &&
-        item.demoEvidence,
+        isEvidence(item.apiEvidence) &&
+        isEvidence(item.demoEvidence),
     );
     if (!decision) {
       addError(relative, 'antd-fallback-decision', `结构组件 ${component} 缺少完整 fallback 证据`);
@@ -139,8 +237,15 @@ for (const filePath of files) {
   const routerImports = ['@umijs/max', 'react-router-dom', 'next/navigation'].filter((source) =>
     new RegExp(`from\\s+['"]${source.replace('/', '\\/')}['"]`).test(content),
   );
-  if (routerImports.length > 0 && !decisions.some((item) => /导航|路由|返回|跳转/.test(item.requirement))) {
-    addWarning(relative, 'router-without-decision', `存在路由 import，但没有导航能力决策：${routerImports.join(', ')}`);
+  if (
+    routerImports.length > 0 &&
+    !decisions.some((item) => /导航|路由|返回|跳转/.test(item.requirement))
+  ) {
+    addWarning(
+      relative,
+      'router-without-decision',
+      `存在路由 import，但没有导航能力决策：${routerImports.join(', ')}`,
+    );
   }
 
   checks.push({ file: relative, status: 'checked' });

package/skills/sisyphus-scene/scripts/validate-skill.mjs

@@ -35,14 +35,33 @@ for (const required of [
   'references/integration-contracts.md',
   'references/validation-rules.md',
   'assets/templates/scene-registry.json',
+  'assets/ai-contract.json',
   'agents/openai.yaml',
+  'evals/generation-cases.yaml',
+  'evals/trigger-cases.yaml',
+  'evals/fixtures/valid-decisions.json',
+  'evals/fixtures/invalid-decisions.json',
 ]) {
   if (!fs.existsSync(path.join(skillRoot, required))) errors.push(`缺少资源：${required}`);
 }
 
 JSON.parse(fs.readFileSync(path.join(skillRoot, 'assets/templates/scene-registry.json'), 'utf8'));
+const contract = JSON.parse(
+  fs.readFileSync(path.join(skillRoot, 'assets/ai-contract.json'), 'utf8'),
+);
+if (contract.schemaVersion !== 2 || !Array.isArray(contract.tools) || contract.tools.length !== 8) {
+  errors.push('ai-contract 必须声明 schema v2 和 8 个 MCP 工具');
+}
+for (const relative of ['evals/generation-cases.yaml', 'evals/trigger-cases.yaml']) {
+  const value = fs.readFileSync(path.join(skillRoot, relative), 'utf8');
+  if (!/^schema_version:\s*1$/m.test(value)) errors.push(`${relative} 缺少 schema_version: 1`);
+}
+for (const relative of [
+  'evals/fixtures/valid-decisions.json',
+  'evals/fixtures/invalid-decisions.json',
+])
+  JSON.parse(fs.readFileSync(path.join(skillRoot, relative), 'utf8'));
 
 const report = { skillRoot, ok: errors.length === 0, errors };
 process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 if (!report.ok) process.exitCode = 1;
-