openyida

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

宜搭 AI 应用开发指南

概述

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

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

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

环境依赖

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

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

更新 openyida

手动更新：

npm install -g openyida@latest

让 AI 帮你更新：

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

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

AI 会自动执行以下命令完成更新：

npm install -g openyida@latest

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

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

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

openyida env --json
openyida login --check-only --json

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

若用户明确要求登录某个宜搭入口 URL，登录命令必须携带该 URL 或对应环境 flag。例如 https://yida-group.alibaba-inc.com/ 是阿里内网宜搭，应执行 openyida login https://yida-group.alibaba-inc.com/ 或 openyida login --alibaba，不要退化成裸 openyida login，否则会落到默认公有云 www.aliwork.com / cookies-public.json。

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

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

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

输出解读：

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

🔧 初始化 project 工作目录

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

openyida copy

复制目标说明

AI 执行规则

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

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

若不存在，执行初始化：

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 按文档提示按需读取，避免一次性加载全量文档。

关键规则

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 范式 理解脱敏 schema 的承载方式，再优化技能或实现方案；不要只凭截图、卡片标题或页面视觉做判断。
• 按 schema 证据选择技能：先看 formType、组件树和 dataSource.online。receipt/process/report 分别优先落到表单、流程、报表技能；只有默认页是自定义展示页、或确实需要列表/看板/工具页交互时，才默认落到 yida-custom-page。
• 配置承载优先于代码承载：字段结构、公式、联动、报表聚合、审批规则、集成自动化、连接器动作应分别由对应技能承载；自定义页面代码只做展示、事件分发和必要胶水。

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

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

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

4. 配置信息分两处存储

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/ 文件夹中，不要写到仓库根目录，也不要写在系统其他位置。

推荐路径：

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

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

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

提示话术示例：

我可以通过两种方式帮你优化报表：

1. 优化原生报表：调整图表类型组合、布局排列、添加筛选器，快速提升效果
2. 创建 ECharts 高级报表：使用 ECharts 自定义页面，实现更精美的视觉效果和交互体验（如渐变色、动画、自定义主题等）

你想选择哪种方案？

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

表单字段类型速查

宜搭应用 URL 规则

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

常见问题

Q：发布时提示登录失效？

重新登录后再发布：

openyida login
openyida publish <源文件路径> <appType> <formUuid> --health-check

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

使用 yida-get-schema 技能获取表单 Schema，从中读取各字段的 fieldId：

openyida get-schema <appType> <formUuid>

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

使用 yida-create-form-page 的 update 模式，详见 skills/yida-create-form-page/SKILL.md：

openyida create-form update <appType> <formUuid> '[{"action":"add","field":{"type":"TextField","label":"新字段"}}]'

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

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

openyida logout
openyida login