最佳实践

使用 OpenYida 和 AI 驱动应用生成的最佳实践建议，涵盖提示词编写、增量迭代、环境配置和协作开发等方面。

​

1. 编写详细提示词

生成应用的质量与提示词的详细程度成正比。对比：

模糊（避免）

创建一个 CRM

---

​

2. 使用需求文档

复杂应用先写 PRD，再交给 AI：

根据以下需求文档生成宜搭应用：

[粘贴 PRD — 字段名、类型、验证规则、工作流等]

这种方式比迭代提示词产生更准确的结果。

---

​

3. 增量迭代

不要试图在一个提示词中构建所有内容。先构建核心结构，再逐步添加复杂度：

第 1 步：创建基础员工信息表单
第 2 步：添加关联员工的请假申请表单
第 3 步：配置请假审批流程
第 4 步：添加显示待审批的经理看板
第 5 步：发布看板为公开页面

---

​

4. 数据操作前必须执行 get-schema

宜搭字段 ID 由平台随机生成（如 textField_eftt1aa5m），无法从字段名称猜测。在创建、更新或按字段条件查询数据前，务必先执行：

openyida get-schema <appType> <formUuid>

写入数据后，查询至少一条记录验证结果：

openyida data query form <appType> <formUuid> --size 1

确认 formData 中字段有实际值。若所有值为空，说明字段 ID 有误，需重新运行 get-schema 并修正。

---

​

5. 每步验证

AI 创建每个组件后，让它验证：

显示 [表单名] 表单的当前 Schema
检查 [页面名] 页面是否已发布并可访问

及早发现问题，避免累积成大问题。

---

​

6. 复用项目工作目录

每个项目只运行一次 openyida copy，不要每会话都运行。project/config.json 文件存储 appId 和 corpId —— AI 用它知道目标应用。项目中途不要删除此文件。

---

​

7. 环境和登录检查

OpenYida 会自动检测 Codex、Claude Code、Cursor、Qoder、悟空等 AI 工具。切换工具、组织或部署环境时，先运行：

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

常用登录方式：

场景	命令
默认缓存优先登录	openyida login
指定浏览器登录	openyida login --browser
终端二维码登录	openyida login --qr
AI 对话框二维码交接	openyida login --agent-qr
指定组织	openyida login --corp-id <corpId>

---

​

8. 自定义页面图片使用 CDN

自定义页面含图片时，先上传到 CDN 确保可靠渲染：

openyida cdn-config   # 配置阿里云 OSS + CDN（一次性）
openyida cdn-upload ./my-image.png   # 获取稳定 CDN URL

然后在页面提示词中引用 CDN URL：

使用此 CDN URL 给落地页添加首屏横幅图片：https://cdn.example.com/banner.png

---

​

9. 处理多组织设置

可访问多个宜搭组织时：

openyida org list          # 查看所有可用组织
openyida org switch --corp-id <id>   # 切换到目标组织
openyida env               # 确认切换

创建应用前始终验证激活组织，避免在错误空间构建。

---

​

10. 调试前先运行 Doctor

花时间调试失败命令前，先运行：

openyida doctor --fix

自动检测并解决最常见问题：过期会话、缺失配置文件、环境不匹配。

---

​

11. AI 辅助 PR 欢迎

向 OpenYida 本身贡献时，完全接受 AI 生成的代码。在 PR 描述中注明使用的 AI 工具 —— 帮助维护者理解生成上下文，更高效地 review。