---
name: openyida
description: >
  宜搭 AI 应用开发总入口技能。通过有 AI Coding 能力的智能体（悟空/Claude/Open Code 等）+ 宜搭低代码平台，实现一句话生成完整应用。
  包含应用创建、表单设计、自定义页面开发、页面发布、登录态管理等完整开发流程。
  当用户提到"宜搭"、"yida"、"低代码"、"创建应用"、"创建表单"、"发布页面"、"搭建"、"系统"等关键词时，使用此技能；以下情况不要触发：只是讨论通用前端/后端代码、非宜搭平台产品、或只需要解释概念而不操作宜搭资源。
---

# 宜搭 AI 应用开发指南

## 概述

本技能通过有 AI Coding 能力的智能体（悟空/Claude/Open Code 等） + 宜搭低代码平台，实现一句话生成完整应用。涵盖从应用创建、表单设计、自定义页面开发到页面发布的完整链路。

所有操作通过 **`openyida`** 命令行工具统一执行，无需关心脚本路径或运行环境差异。

**登录态说明**：所有命令自动读取 `.cache/cookies.json`，首次运行或 Cookie 失效时自动触发登录流程，无需手动执行登录命令。

---

## 环境依赖

| 依赖 | 版本 | 用途 |
|------|------|------|
| Node.js | ≥ 16 | 运行 openyida |

```bash
# 安装 openyida（首次使用前执行）
npm install -g openyida

# 更新 openyida 到最新版本
npm install -g openyida@latest
```

---

## 更新 openyida

**手动更新**：
```bash
npm install -g openyida@latest
```

**让 AI 帮你更新**：

执行 `openyida` 命令出现报错时，直接告诉 AI：

> "openyida 命令出错了，请帮我更新 openyida"

AI 会自动执行以下命令完成更新：
```bash
npm install -g openyida@latest
```

更新完成后重新执行出错的命令即可。

---

## ⚡ 首要步骤：检测运行环境（必须先执行）

**在执行任何宜搭操作前，必须先运行环境检测命令**，确认当前 AI 工具环境和登录态：

```bash
openyida env --json
openyida login --check-only --json
```

`openyida env --json` 用于确认当前 AI 工具、项目根目录、配置文件和登录态拆解项；`openyida login --check-only --json` 只读取本地登录缓存，不触发登录、不打开浏览器、不创建任何资源。

**悟空（Wukong）降级规则**：如果在悟空环境中本地命令执行入口连续失败，不要继续重试，也不要判断为 OpenYida 登录失败。进入人工协同诊断模式，请用户在可用终端执行以下低风险命令并贴回输出：

```bash
openyida -v
openyida env --json
openyida login --check-only --json
```

在拿到上述输出并确认 `loggedIn/can_auto_use`、`csrf_token_found`、`corp_id_found`、`base_url_found` 等关键项前，禁止创建应用、页面、表单或发布页面等会产生真实宜搭资源的操作。

**输出解读**：

| 字段 | 说明 |
|------|------|
| AI 工具检测 | 显示当前活跃的 AI 工具（悟空/OpenCode/Aone Copilot 等） |
| 当前生效环境 | 显示项目根目录路径 |
| 登录态检测 | 显示是否已登录、域名、组织 ID |

> **若显示"未登录"，先执行 `openyida login`。Codex 中默认返回内置浏览器 handoff：用 Browser Use 打开 `login_url`，让钉钉/宜搭页面承接扫码和组织选择。若 Browser Use 不能直接打开外部 URL，先打开临时本地 redirect 页面再跳转到 `login_url`。页面登录完成后必须再次执行 `openyida login --check-only --json` 验证缓存写入。不要在只读验证通过前执行真实资源创建。**

---

## 🔧 初始化 project 工作目录

**如果当前工程目录下没有 `project/` 目录**（例如切换了 AI 工具、或在新工程中首次使用），需要手动执行初始化：

```bash
openyida copy
```

### 复制目标说明

| AI 工具 | project 目录位置 | 说明 |
|---------|-----------------|------|
| **悟空（Wukong）** | `~/.real/workspace/project` | 悟空有专属 workspace，与工程目录无关 |
| **其他工具**（Aone Copilot、Cursor、Claude Code、OpenCode 等） | `<当前工程目录>/project` | 以项目为单位，需在工程根目录下执行 |

### AI 执行规则

**在执行任何宜搭操作前，先检查 project 目录是否存在**：

- **悟空**：检查 `~/.real/workspace/project` 是否存在
- **其他工具**：检查当前工程目录下的 `project/` 是否存在

若不存在，执行初始化：
```bash
openyida copy
```

> ⚠️ 对于非悟空工具，必须先 `cd` 到工程根目录再执行 `openyida copy`。

---

## 何时使用

当用户提出以下需求时，使用本技能并按照完整开发流程执行：
- 创建宜搭应用、表单、自定义页面
- 创建、查看或发布宜搭聚合表（virtualView）
- 发布或更新宜搭页面
- 配置页面公开访问/组织内分享
- 查询表单 Schema 或字段 ID
- 管理宜搭登录态（登录/退出）

---

## 完整开发流程

```
[Step 1] 创建应用 → openyida create-app          → 获得 appType
              ↓
[Step 2] 需求分析 → 写入 prd/<项目名>.md
              ↓      （必须包含 MVP 边界、角色权限、核心旅程、状态机、数据约束、验收标准）
              ↓
[Step 3] 创建自定义页面 → openyida create-page    → 获得 formUuid（看板用 --mode dashboard）
              ↓
[Step 4]（按需）创建/更新表单 → openyida create-form → 获得 formUuid（表单）
              ↓
[Step 5] 编写自定义页面代码 → yida-custom-page 规范 → pages/src/<项目名>.js
              ↓
[Step 6] 发布页面 → openyida publish
              ↓
[Step 7]（按需）配置公开访问 → openyida verify-short-url / save-share-config
              ↓
[Step 8] 输出访问链接，用系统浏览器打开
```

---

## 子技能速查

> 每个子技能均有独立的 SKILL.md。执行时先选定一个最匹配的子技能，只读取该子技能文档；references 按文档提示按需读取，避免一次性加载全量文档。

| 技能 | SKILL.md 路径 | 用途 | 典型命令 |
|------|--------------|------|---------|
| `yida-app` | `skills/yida-app/SKILL.md` | 完整应用开发编排 | 详见 SKILL.md |
| `yida-login` | `skills/yida-login/SKILL.md` | 登录态管理（通常自动触发） | `openyida login` |
| `yida-logout` | `skills/yida-logout/SKILL.md` | 退出登录 / 切换账号 | `openyida logout` |
| `yida-create-app` | `skills/yida-create-app/SKILL.md` | 创建应用，获取 appType | `openyida create-app "<名称>"` |
| `yida-create-page` | `skills/yida-create-page/SKILL.md` | 创建自定义页面，获取 formUuid | `openyida create-page <appType> "<页面名>" [--mode dashboard]` |
| `yida-create-form-page` | `skills/yida-create-form-page/SKILL.md` | 创建/更新表单页面、追加选项、绑定数据源、字段联动规则 | `openyida create-form <create\|update\|bind-datasource\|rule\|patch\|add-option> ...` |
| `yida-create-process` | `skills/yida-create-process/SKILL.md` | 创建流程表单并配置流程 | `openyida create-process <appType> "<表单名>" <字段JSON> <流程JSON>` |
| `yida-aggregate-table` | — | 聚合表（virtualView）列表、创建空白页、读取配置、预览、保存草稿和发布 | `openyida aggregate-table <list\|create-empty\|inspect\|preview\|save\|publish\|status> ...` |
| `yida-get-schema` | `skills/yida-get-schema/SKILL.md` | 获取单个/全部表单 Schema，确认字段 ID | `openyida get-schema <appType> <formUuid>` |
| `yida-custom-page` | `skills/yida-custom-page/SKILL.md` | 编写自定义页面 JSX 代码规范 | 详见 SKILL.md |
| `yida-publish-page` | `skills/yida-publish-page/SKILL.md` | 编译并发布自定义页面 | `openyida publish <源文件路径> <appType> <formUuid> [--health-check]` |
| `yida-page-config` | `skills/yida-page-config/SKILL.md` | 页面公开访问/组织内分享配置 | `openyida verify-short-url <appType> <formUuid> <url>` |
| `yida-basic-info` | `skills/yida-basic-info/SKILL.md` | 组织基本信息、资源容量、额度和域名设置查询 | `openyida basic-info overview` |
| `yida-nav-group` | `skills/yida-nav-group/SKILL.md` | 应用左侧导航分组管理（查询/创建/重命名/删除/移动/显隐） | `openyida nav-group list <appType>` |
| `yida-form-permission` | `skills/yida-form-permission/SKILL.md` | 表单权限查询与保存 | `openyida get-permission <appType> <formUuid>` |
| `yida-app-permission` | `skills/yida-app-permission/SKILL.md` | 应用级管理员设置（主管理员/数据管理员/开发成员） | `openyida app-permission get <appType>` |
| `yida-i18n` | `skills/yida-i18n/SKILL.md` | 应用多语言管理（语言配置、词条、翻译、升级） | `openyida i18n overview <appType>` |
| `yida-corp-manager` | `skills/yida-corp-manager/SKILL.md` | 平台管理员、应用管理员、子管理员与通讯录权限 | `openyida corp-manager <子命令>` |
| `yida-agent-center` | `skills/yida-agent-center/SKILL.md` | 代理中心：在职流程代理、离职代理、撤销和部分流程范围 | `openyida agent-center <子命令>` |
| `yida-form-detail` | `skills/yida-form-detail/SKILL.md` | 表单详情页 formDetail 样式优化 | 详见 SKILL.md |
| `yida-data-management` | `skills/yida-data-management/SKILL.md` | 表单/子表/流程/任务数据查询与变更 | `openyida data query form <appType> <formUuid>` |
| `yida-corp-efficiency` | `skills/yida-corp-efficiency/SKILL.md` | 平台管理企业效能概览、查看明细报表、报表接口模板、学习成果和通知群动作 | `openyida corp-efficiency` |
| `yida-table-form` | `skills/yida-table-form/SKILL.md` | 表格形态批量录入页面 | 详见 SKILL.md |
| `yida-process-rule` | `skills/yida-process-rule/SKILL.md` | 配置流程规则、审批/办理/抄送、条件/并行分支、字段权限、跳转规则和官方组件节点配置适配 | `openyida configure-process <appType> <formUuid> <流程JSON>` |
| `yida-ai-form-setting` | — | 管理流程表单「AI审批提示」配置：查询字段/模型、开启关闭、保存文本/图文/附件提示词 | `openyida ai-form-setting <get\|fields\|models\|enable\|disable\|save> ...` |
| `yida-integration` | `skills/yida-integration/SKILL.md` | 集成自动化逻辑流（创建/列表/启停） | `openyida integration <create\|list\|enable\|disable> ...` |
| `yida-business-rule` | `skills/yida-business-rule/SKILL.md` | 表单业务关联规则高级函数（INSERT/UPDATE/DELETE/UPSERT） | 详见 SKILL.md |
| `yida-connector` | `skills/yida-connector/SKILL.md` | HTTP 连接器创建、测试与动作管理 | `openyida connector smart-create <配置>` |
| `yida-connector-safe-actions` | `skills/yida-connector-safe-actions/SKILL.md` | 从前后端接口安全生成 HTTP 连接器执行动作，并修复测试后动作消失问题 | `openyida connector add-action --operations <动作JSON> --connector-id <id> --confirm` |
| `yida-data-source-connectors` | `skills/yida-data-source-connectors/SKILL.md` | 自定义页面调用连接器/远程 API 时，必须通过设计器“数据源”创建并使用 `this.dataSourceMap` 调用 | 详见 SKILL.md |
| `sls-log-workbench` | `skills/sls-log-workbench/SKILL.md` | SLS 日志查询工作台排查（内部技术支持） | 详见 SKILL.md |
| `yida-dashboard` | `skills/yida-dashboard/SKILL.md` | 经营看板/驾驶舱/数据大屏完整产品化交付（单屏控制塔+宜搭待办连接器真实钉钉待办闭环+卡片截图+组织内短链） | 详见 SKILL.md |
| `yida-chart` | `skills/yida-chart/SKILL.md` | 报表可视化（ECharts 图表 + 数据聚合） | 详见 SKILL.md |
| `yida-report` | `skills/yida-report/SKILL.md` | 宜搭原生报表创建（标准报表） | `openyida create-report <appType> "<名称>" <配置>` |
| `yida-density` | `skills/yida-density/SKILL.md` | 列表/表格页面信息密度选择 | 详见 SKILL.md |
| `yida-formula` | `skills/yida-formula/SKILL.md` | 公式字段和赋值规则配置 | 详见 SKILL.md |
| `yida-formula-evaluate` | `skills/yida-formula-evaluate/SKILL.md` | 静态检查公式语法和字段引用 | `openyida formula evaluate <公式或文件>` |
| `yida-voc` | `skills/yida-voc/SKILL.md` | 需求/故障/性能反馈 VOC 信息整理 | 详见 SKILL.md |
| `yida-db-seq-fix` | `skills/yida-db-seq-fix/SKILL.md` | PostgreSQL sequence 漂移修复 | `openyida db-seq-fix <配置>` |
| `yida-export-conversation` | `skills/yida-export-conversation/SKILL.md` | 导出 AI 对话记录 | `openyida export-conversation` |
| `yida-flash-note-to-prd` | `skills/yida-flash-note-to-prd/SKILL.md` | 闪记/会议纪要转 PRD prompt | `openyida flash-to-prd <文件>` |
| `yida-ai` | — | 宜搭 AI 文生文与识图接口调用 | `openyida ai text --prompt "..."` / `openyida ai image --file <图片> --app-type APP_XXX` |
| `yida-ppt-slider` | `skills/yida-ppt-slider/SKILL.md` | 宜搭全屏幻灯片页面 | 详见 SKILL.md |
| `yida-ppt` | `skills/yida-ppt/SKILL.md` | 已废弃，改用 `yida-ppt-slider` | 详见 SKILL.md |
| `yida-batch` | — | 批量命令编排（一次登录，多命令顺序执行） | `openyida batch <file> --json` 或 `openyida batch --commands "cmd1;cmd2"` |
| `large-file-write` | `skills/large-file-write/SKILL.md` | 大文件可靠写入辅助技能 | 详见 SKILL.md |

---

## 关键规则

### 1. 执行子技能前必须读取其 SKILL.md

每个子技能的详细参数、注意事项、示例均在其 SKILL.md 中。**执行任何子技能前，必须先读取对应的 SKILL.md**，不要凭记忆猜测参数格式。

### 2. 执行成功率与性能规则（必须遵守）

- **只读必要文档**：先根据用户意图选定 1 个主技能；只有该技能明确要求时，才读取对应 `references/` 文档，禁止一次性读取全部技能文档。
- **优先复用缓存**：已创建的 `appType`、`formUuid`、`fieldId`、`reportId` 优先从 `.cache/<项目名>-schema.json` 读取；缺失或不确定时再执行 `openyida get-schema`。
- **先本地校验再发布**：自定义页面发布前运行 `openyida check-page <源文件路径>` 和 `openyida compile <源文件路径>`；发布时留意同名双副本内容不一致警告，必要时加 `--health-check` 做首屏 HTTP 健康检查；JSON 配置写入文件后先做 JSON 解析校验，再调用平台命令。
- **避免无效重试**：同一命令失败后，先根据错误信息检查登录态、组织、参数和字段 ID；不要无修改地连续重试超过 1 次。
- **数据性能优先**：统计/聚合类需求优先使用 `yida-report` 原生报表服务端聚合；不要在自定义页面前端分页拉取大量表单数据后自行聚合。
- **模板优先**：自定义页面、表单字段、报表配置等复杂产物优先使用 `openyida sample` 或现有示例生成骨架，再做最小改动。
- **官方示例范式优先**：用户要求参考/蒸馏宜搭示例中心时，先按 [官方示例中心 Schema 范式](references/official-example-schema-patterns.md) 理解脱敏 schema 的承载方式，再优化技能或实现方案；不要只凭截图、卡片标题或页面视觉做判断。
- **按 schema 证据选择技能**：先看 `formType`、组件树和 `dataSource.online`。`receipt/process/report` 分别优先落到表单、流程、报表技能；只有默认页是自定义展示页、或确实需要列表/看板/工具页交互时，才默认落到 `yida-custom-page`。
- **配置承载优先于代码承载**：字段结构、公式、联动、报表聚合、审批规则、集成自动化、连接器动作应分别由对应技能承载；自定义页面代码只做展示、事件分发和必要胶水。

### 3. corpId 一致性检查（必须遵守）

在创建页面前，**必须对比 prd 文档中的 corpId 与 `.cache/cookies.json` 中的 corpId 是否一致**：

- **一致** → 继续执行
- **不一致** → 询问用户：重新登录到正确组织，还是在当前组织新建应用？

### 4. 配置信息分两处存储

| 信息类型 | 存储位置 | 内容示例 |
|---------|---------|---------|
| 业务语义信息 | `prd/<项目名>.md` | 字段名称、字段类型、字段说明 |
| Schema ID | `.cache/<项目名>-schema.json` | `appType`、`formUuid`、`fieldId` |

> **prd 文档不记录 `formUuid`、`fieldId` 等 ID**，这些写入 `.cache/` 临时文件。

### 4.1 PRD 质量门槛（必须遵守）

`prd/<项目名>.md` 不是普通需求摘要，必须能直接驱动后续技能执行。创建或评审 PRD 时至少包含：

- MVP 范围与版本边界：V1 必做、V1 不做、V2 候选
- 目标用户与权限：角色、入口、可执行操作
- 核心用户旅程：用户完成关键任务的步骤和成功标准
- 页面与表单配置：业务语义字段，不写 `formUuid`/`fieldId`
- 流程与状态机：状态、允许操作、下一状态、操作角色
- 数据关联与约束：唯一性、关联关系、冲突校验、并发/重复提交风险
- 交互与验收标准：用可验证标准描述“好用”
- OpenYida 落地约束：Schema 写 `.cache/<项目名>-schema.json`，发布前 `check-page` + `compile`

### 5. 临时文件规范

所有临时文件（cookies、schema 缓存、字段配置、报表配置、流程配置、导入数据、一次性脚本等）**必须写在项目根目录的 `.cache/` 文件夹中**，不要写到仓库根目录，也不要写在系统其他位置。

推荐路径：

| 工件类型 | 推荐位置 |
|---------|---------|
| Schema / ID 映射 | `.cache/<项目名>-schema.json` |
| 表单字段 / 报表 / 流程配置 | `.cache/openyida/<项目名>/` |
| 批量导入数据 JSON / JSONL / CSV | `.cache/openyida/data-import/` |
| 一次性 Python / JS 执行脚本 | `.cache/openyida/scripts/` |

> 若只是为了调用 `openyida` 命令临时生成的 `*.json`、`*.js`、`*.py`、`*.csv` 文件，一律放入 `.cache/openyida/` 子目录；只有需要长期维护的 PRD、页面源码或示例资源才写入 `prd/`、`pages/src/`、`project/` 等正式目录。

### 6. 报表优化/美化提示规则（必须遵守）

当用户提到"优化"、"美化"、"更好看"、"不够漂亮"等与报表视觉效果相关的关键词时，**必须先询问用户**选择以下哪种方案：

| 方案 | 说明 | 适用场景 |
|------|------|---------|
| **方案 A：优化宜搭原生报表** | 调整图表类型、布局、筛选器等，仍使用宜搭原生报表组件 | 快速优化，无需编写代码 |
| **方案 B：创建 ECharts 高级报表** | 使用 ECharts + 自定义页面 JSX，实现高度定制化、更美观的数据可视化 | 需要更精美的视觉效果、复杂交互、数据大屏 |

**提示话术示例**：

> 我可以通过两种方式帮你优化报表：
> 1. **优化原生报表**：调整图表类型组合、布局排列、添加筛选器，快速提升效果
> 2. **创建 ECharts 高级报表**：使用 ECharts 自定义页面，实现更精美的视觉效果和交互体验（如渐变色、动画、自定义主题等）
>
> 你想选择哪种方案？

- 用户选择方案 A → 使用 `yida-report` 技能（`openyida create-report`）
- 用户选择方案 B → 读取 `skills/yida-chart/SKILL.md`，使用 `yida-chart` 技能

---

## 表单字段类型速查

| 类型 | 说明 | 特殊属性 |
|------|------|---------|
| `TextField` | 单行文本 | — |
| `TextareaField` | 多行文本 | — |
| `NumberField` | 数字 | `precision`（小数位）、`innerAfter`（单位） |
| `RadioField` | 单选 | `options` |
| `CheckboxField` | 多选 | `options` |
| `SelectField` | 下拉单选 | `options` / `remoteDataSource` |
| `MultiSelectField` | 下拉多选 | `options` / `remoteDataSource` |
| `DateField` | 日期 | `format`（如 `"YYYY-MM-DD"`） |
| `CascadeDateField` | 级联日期（范围） | `format` |
| `EmployeeField` | 成员选择 | `multiple` |
| `DepartmentSelectField` | 部门选择 | `multiple` |
| `AddressField` | 地址 | — |
| `AttachmentField` | 附件上传 | — |
| `ImageField` | 图片上传 | — |
| `TableField` | 子表格 | `children`（子字段列表） |
| `AssociationFormField` | 关联表单 | `associationForm` |
| `SerialNumberField` | 流水号 | `serialNumberRule` |
| `RateField` | 评分 | `count`（星级数） |
| `CountrySelectField` | 国家选择 | `multiple` |

---

## 宜搭应用 URL 规则

| 页面类型 | URL 格式 |
|---------|---------|
| 应用首页 | `{base_url}/{appType}/workbench` |
| 表单提交页 | `{base_url}/{appType}/submission/{formUuid}` |
| 自定义页面 | `{base_url}/{appType}/custom/{formUuid}` |
| 自定义页面（隐藏导航） | `{base_url}/{appType}/custom/{formUuid}?isRenderNav=false` |
| 表单详情页 | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}` |
| 表单详情页（编辑模式） | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}&mode=edit` |

> 所有地址拼接 `&corpid={corpId}` 可自动切换到对应组织。

---

## 常见问题
**Q：发布时提示登录失效？**

重新登录后再发布：
```bash
openyida login
openyida publish <源文件路径> <appType> <formUuid> --health-check
```

**Q：如何查看已有表单的字段 ID？**

使用 `yida-get-schema` 技能获取表单 Schema，从中读取各字段的 `fieldId`：
```bash
openyida get-schema <appType> <formUuid>
```

**Q：如何更新已有表单字段？**

使用 `yida-create-form-page` 的 update 模式，详见 `skills/yida-create-form-page/SKILL.md`：
```bash
openyida create-form update <appType> <formUuid> '[{"action":"add","field":{"type":"TextField","label":"新字段"}}]'
```

**Q：发布时提示 corpId 不匹配？**

询问用户是否在当前组织创建新应用发布，或重新登录到正确组织：
```bash
openyida logout
openyida login
```
