# Sisyphus Scene

## 用途

`@zat-design/sisyphus-scene` 从截图或需求识别保险业务场景，强制查询真实 Sisyphus API/demo，生成可验证的 React/TypeScript 页面骨架。

## 安装

需要 Node.js 18+、Sisyphus 4.x 和 Ant Design `>=6 <7`。Node.js 20 可直接使用。选择 Codex 平台时，终端中的 Codex CLI 还需支持 `mcp list --json` 和 `mcp add`。默认安装 npm `latest` 稳定版：

```bash
npx -y @zat-design/sisyphus-scene install --check
npx -y @zat-design/sisyphus-scene install
```

常用参数：`--global`、`--platform claude,cursor,codex`、`--project <项目根>`、`--mcp-cwd <前端目录>`、`--skip-mcp`、`--skill sisyphus-scene-legacy`。`--skip-mcp` 只安装 Skill，不提供组件 API/demo 查询能力；不需要 Codex 时可显式使用 `--platform claude,cursor`。

Codex 项目配置写入 `<项目根>/.codex/config.toml`。当 Codex 保存项目根是 monorepo 或工作区父目录，而 Sisyphus 前端位于子目录时，使用 `--mcp-cwd` 单独指定组件解析目录；相对路径以 `--project` 为基准。该参数不能与 `--skip-mcp`、legacy 技能或不含 Codex 的平台组合。用户级安装默认不会绑定业务项目；对尚不加载项目级 MCP 的旧版 Codex Desktop，可显式组合 `--global --mcp-cwd <前端目录>` 创建兼容入口。

安装器修正已有 Codex `cwd` 前会创建带时间戳的配置备份，通过同目录临时文件原子替换，并在 Codex CLI 读回校验失败时恢复原文件。更新仅定位有效的 `[mcp_servers.sisyphus-react]` 表，不匹配注释中的示例，也不改动后续 MCP 表。

Codex MCP 安装失败时，先在同一终端运行 `codex --version` 和 `codex mcp list --json`。若 Codex 命令非零退出且 stdout/stderr 为空，请检查当前终端实际命中的 Codex CLI 来源和兼容性；可临时使用 `--skip-mcp` 绕过 MCP，但这不代表 MCP 已安装。

安装器会将 MCP 锁定到 Scene 自身精确版本。锁版或 beta 项目使用 `@<完整版本>`，并保持组件库、MCP 和 Scene 三包完全同版。

## 场景与 MCP 工具

| 场景            | Agent 处理                               |
| --------------- | ---------------------------------------- |
| 截图还原        | 识别布局/字段/交互，用 MCP 校准组件      |
| 需求生成        | 建立 SceneSpec，匹配注册场景             |
| 已有页扩展      | 读相邻代码、做 GitNexus impact、只补需求 |
| 参考其他项目    | 复用业务结构，重新查询当前 MCP           |
| 无模板场景      | 从组件/demo 组合临时场景                 |
| legacy v3/antd4 | 切换 `sisyphus-scene-legacy`             |

| MCP 工具                     | Scene Agent 中的用途          |
| ---------------------------- | ----------------------------- |
| `sisyphus-get-meta-status`   | 验证版本、schema 和元数据     |
| `sisyphus-search`            | 将业务语言映射到候选组件/能力 |
| `sisyphus-list-components`   | 确认候选组件存在              |
| `sisyphus-get-component-api` | 获取候选组件的真实 API        |
| `sisyphus-get-type`          | 核对公开 TypeScript 类型      |
| `sisyphus-list-examples`     | 按组件和场景词筛选 demo ID    |
| `sisyphus-get-example`       | 获取选中的单个 demo 源码      |
| `sisyphus-get-examples`      | 仅供旧工作流兼容              |

## 开发校验

```bash
npm test && npm run validate && npm run mcp:check && npm run pack:check
```

发布必须从仓库根目录执行 `yarn release:beta` 或 `yarn release`。