yida-app
# 宜搭完整应用开发技能
## 概述
本技能描述如何从零到一完整搭建一个宜搭应用，涵盖从应用创建到代码发布的全流程。每个步骤均依赖对应的子技能完成。
## 何时使用
当以下场景发生时使用此技能：
- 用户想要一句话生成完整的宜搭应用
- 用户需要从头开始开发一个宜搭应用
- 用户不了解宜搭开发流程，需要完整指导
- 进行完整的宜搭应用开发项目
## 使用示例
### 示例 1：一句话生成应用
**场景**：用户说"帮我搭建一个生日祝福小游戏"
**流程**：
1. 调用 yida-create-app 创建应用
2. 需求分析，写入 prd 文档
3. 调用 yida-create-page 创建自定义页面
4. 如需存储数据，调用 yida-create-form-page 创建表单
5. 调用 yida-custom-page 编写页面代码
6. 调用 yida-publish-page 发布页面
---
## 完整开发流程
```
创建应用
↓
需求分析 → 创建 prd 文档（prd/<项目名>.md）
↓
创建自定义页面
↓
（如需存储数据）创建表单 → 将字段描述信息写入 prd 文档
↓
调用 yida-custom-page 技能编写页面代码（src/<name>.js）
↓
自动调用 yida-publish-page 技能发布代码
```
> 💡 **登录态说明**：各脚本会自动读取项目根目录的 `.cache/cookies.json`。**若 Cookie 不存在或已失效，脚本会报错退出，此时必须先调用 `yida-login` skill 完成交互式扫码登录（agent 用 browser 工具打开页面截图发给用户扫码），再重新执行后续步骤。严禁直接告知用户去自己打开浏览器扫码。**
---
## 步骤详解
### ⚠️ 前置强制规则（必须遵守）
在开始任何宜搭应用开发前，**必须先执行以下检查**：
#### ⚠️ corpId 一致性检查（关键步骤）
在执行创建页面前，**必须检查 prd 文档中的 corpId 与当前登录态的 corpId 是否一致**：
1. **读取 prd 文档中的应用配置**，获取已记录的 `corpId`
2. **读取 `.cache/cookies.json`**，获取当前登录态的 `corpId`
3. **对比两个 corpId**：
- **如果一致**：继续执行创建页面
- **如果不一致或 prd 中无 corpId**：提示用户选择处理方式
**corpId 不一致时的处理选项**：
| 场景 | 建议操作 |
| --- | --- |
| prd 中有 corpId，但与当前登录态不一致 | **询问用户**：是重新登录到 prd 中的组织，还是在当前组织新建应用？ |
| prd 中无 corpId | 直接新建应用 |
**决策流程**：
```
检查 prd.corpId vs Cookie.corpId
│
├── 一致 → 继续创建页面
│
└── 不一致
│
├── 用户选择"重新登录" → 执行 yida-logout → 重新扫码登录到正确组织
│
└── 用户选择"新建应用" → 回到 Step 1 创建新应用（会自动覆盖 prd 配置）
```
### Step 1：创建应用
调用 `yida-create-app` 技能创建宜搭应用，获取 `appType`。
```bash
node .claude/skills/yida-create-app/scripts/create-app.js "<应用名称>" "[描述]"
```
**输出**：`appType`（如 `APP_XXXXXX`），用 markdown 记录到 prd 文件夹下文档备用。
> 详见 `yida-create-app` 技能文档。
---
### Step 2：创建自定义页面
#### 创建页面命令
确认 corpId 一致后，调用 `yida-create-page` 技能：
```bash
node .claude/skills/yida-create-page/scripts/create-page.js "<appType>" "<页面名称>"
```
**输出**：`pageId`（如 `FORM-XXXXXX`），记录到 prd 文档备用。
> 详见 `yida-create-page` 技能文档。
---
### Step 3：需求分析 → 写入 prd 文档
将分析的需求文档结果写入 `prd/<项目名>.md`：
**prd 文档应包含以下内容**：
```markdown
# <项目名> 需求文档
## 应用配置
| 配置项 | 值 |
| --- | --- |
| appType | APP_XXXXXX |
| corpId | dingXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| baseUrl | https://ding.aliwork.com |
> 💡 **提示**：
> - `corpId` 由 `create-app.js` 自动写入，用于组织一致性校验
> - 如果登录态变更或创建新应用，`create-app.js` 会自动更新本表格
## 功能需求
- 描述页面的核心功能、交互逻辑、业务规则
- 深度分析需求，并且识别核心功能 和 隐含期望，体现应用的潜在价值
- 应用RD文档需要与上述步骤紧密相关，按照步骤产出详细功能说明
- 表单字段设计需要优先满足用户指定需要的字段，再根据实际使用场景进行字段的合理扩充，以更好的满足实际场景表单对于数据的收集，发挥表单数据的价值挖掘，同时避免字段冗余
- PRD 不要包含测试、发布、推广等其他内容，不要包含 PRD 文件头、文件尾等，直接输出核心内容
## 页面与表单配置
（记录每个页面/表单的名称、类型和字段信息，见 Step 5）
格式示例：
### 用户信息表（表单页面）
| 字段名称 | 字段类型 | 说明 |
| --- | --- | --- |
| 姓名 | TextField / 单行文本 | 必填 |
| 部门 | SelectField / 下拉单选 | 必填，选项：技术部、产品部、运营部 |
| 备注 | TextareaField / 多行文本 | 选填 |
### 首页（自定义页面）
展示用户信息列表，支持搜索和分页。
## UI 设计
（描述页面风格、布局、响应式要求）
```
> **重要**：
> - prd 文档只记录**业务语义信息**（应用名称、页面名称、页面类型、字段名称、字段类型、字段说明），**不记录** `formUuid`、`fieldId` 等 Schema 中的具体 ID 值
> - Schema ID（`formUuid`、`fieldId` 等）写入 `.cache/<项目名>-schema.json` 临时文件，供编码时读取，**注意不要写在系统的其他文件夹中**
> - **每次创建或修改表单/自定义页面后，必须同步更新 prd 文档中对应的页面/字段信息**
---
### Step 5：创建表单（按需）
**当页面需要存储数据时**，调用 `yida-create-form-page` 技能创建表单页面。
#### 5.1 定义字段
将字段定义写入 `prd/<项目名>-pageName-field.md`
```json
[
{ "type": "TextField", "label": "词语", "required": true },
{ "type": "TextField", "label": "图片地址" },
{ "type": "TextField", "label": "用户ID" },
{ "type": "TextField", "label": "用户名" }
]
```
#### 5.2 创建表单
```bash
node .claude/skills/yida-create-form-page/scripts/create-form-page.js create "<appType>" "<表单名称>" .claude/skills/yida-create-form-page/scripts/fields.json
```
**输出**：`formUuid` 和各字段的 `fieldId`（如 `textField_xxxxxxxx`）。
#### 5.3 将表单信息写入 prd 文档和 .cache 临时文件
**写入 prd 文档**（只记录业务语义信息，不记录 Schema ID）：
```markdown
## 页面与表单配置
### 图片生成表（表单页面）
| 字段名称 | 字段类型 | 说明 |
| --- | --- | --- |
| 词语 | TextField / 单行文本 | 必填 |
| 图片地址 | TextField / 单行文本 | 选填 |
| 用户ID | TextField / 单行文本 | 系统字段，自动填充 |
| 用户名 | TextField / 单行文本 | 系统字段，自动填充 |
### 首页（自定义页面）
展示图片生成结果，支持关键词搜索。
```
**写入 `.cache/<项目名>-schema.json`**（记录 Schema ID，供编码时读取）：
```json
{
"appType": "APP_XXXXXX",
"pages": {
"图片生成表": {
"formUuid": "FORM-XXXXXX",
"fields": {
"词语": "textField_xxxxxxxx",
"图片地址": "textField_xxxxxxxx",
"用户ID": "textField_xxxxxxxx",
"用户名": "textField_xxxxxxxx"
}
},
"首页": {
"formUuid": "FORM-XXXXXX"
}
}
}
```
> ⚠️ **重要**：每次创建或修改表单/自定义页面后，必须同步更新：
> 1. **prd 文档**：更新对应页面/表单的字段名称、类型、说明
> 2. **`.cache/<项目名>-schema.json`**：更新对应的 `formUuid` 和 `fieldId`
> 详见 `yida-create-form-page` 技能文档。
---
### Step 6：编写页面代码
调用 `yida` 技能，根据 prd 文档中的需求和配置信息编写自定义页面代码。
**编写前必读 prd 文档**，从中获取：
- `appType`、`formUuid`（自定义页面）
- 各表单的 `formUuid` 和字段 ID
- 功能需求和 UI 设计要求
**代码文件命名规范**：`pages/src/<项目名>.js`
**核心规范**（详见 `yida-custom-page` 技能文档）：
- 使用 `export function` 导出函数
- 状态管理使用 `_customState` + `setCustomState`
- 必须包含 `didMount`、`didUnmount`、`renderJsx` 三个导出函数
- 输入框使用非受控组件（`defaultValue` 而非 `value`）
- 所有样式通过内联 `style` 对象定义
> 详见 `yida-custom-page` 技能文档。
---
### Step 7：发布代码
调用 `yida-publish-page` 技能，将源码编译并部署到宜搭平台。
```bash
cd .claude/skills/yida-publish-page/scripts
npm install # 首次需要安装依赖
node publish.js <appType> <formUuid> <源文件路径>
```
**示例**：
```bash
node publish.js APP_XXX FORM-XXXXXX pages/src/xxx.js
```
**发布流程**：
1. Babel 编译 JSX → ES5
2. UglifyJS 压缩
3. 动态构建 Schema JSON
4. 读取 `.cache/cookies.json` 获取登录态（若不存在或接口返回 302，自动触发扫码登录）
5. 调用 `saveFormSchema` 接口保存 Schema
> 详见 `yida-publish-page` 技能文档。
---
### Step 7：输出访问链接并直接使用系统浏览器打开
* 访问地址参考「宜搭应用 url 规则说明」
## 快速参考
### 子技能一览
| 技能 | 用途 | 调用时机 |
| --- | --- | --- |
| `yida-login` | 登录态管理 | 接口返回 302 时自动触发（无需手动调用） |
| `yida-logout` | 退出登录 | 需要切换账号或 Cookie 失效时 |
| `yida-create-app` | 创建应用 | Step 1，获取 appType |
| `yida-create-page` | 创建自定义页面 | Step 2，获取 pageId |
| `yida-create-form-page` | 创建表单页面 | Step 5，需要存储数据时 |
| `yida-get-schema` | 获取表单 Schema | 需要分析已有表单字段结构时 |
| `yida-custom-page` | 编写自定义页面代码 | Step 6，核心开发阶段 |
| `yida-publish-page` | 编译并发布代码 | Step 7，部署到宜搭 |
### 关键配置速查
配置信息分两处存储，各司其职：
| 信息类型 | 存储位置 | 示例 |
| --- | --- | --- |
| 应用名称、页面名称、页面类型、字段名称、字段类型、字段说明 | `prd/<项目名>.md` | 姓名、TextField / 单行文本、必填 |
| `appType`、`formUuid`、`fieldId` 等 Schema ID | `.cache/<项目名>-schema.json` | `"姓名": "textField_xxxxxxxx"` |
编码时从 `.cache/<项目名>-schema.json` 读取 Schema ID，无需重复查询接口。
### 宜搭应用 URL 规则说明
| 页面类型 | URL 格式 | 说明 |
|---------|---------|------|
| **应用首页** | `{base_url}/{appType}/workbench` | 标准的应用首页 |
| **表单提交页** | `{base_url}/{appType}/submission/{formUuid}` | 可用于自定义页面用 iframe 嵌入表单或直接跳转使用表单 |
| **自定义页面** | `{base_url}/{appType}/custom/{formUuid}` | 自定义页面 |
| **自定义页面（隐藏导航）** | `{base_url}/{appType}/custom/{formUuid}?isRenderNav=false` | 可用于自定义页面作为首页，不希望展示导航信息 |
| **表单详情页面** | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}` | 可用于自定义页面用 iframe 嵌入表单详情页或直接跳转查看详情 |
| **表单详情页面（自动开启编辑状态）** | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}&mode=edit` | 可以直接开启表单编辑状态 |
> 💡 **提示**：所有地址上拼接 `&corpid={corpId}` 后可以自动切换到对应的组织，建议首页加上 `&corpid={corpId}`
### 常见问题
**Q：发布时提示登录失效怎么办？**
A：使用 `yida-logout` 清空 Cookie 缓存，再重新执行发布命令，会自动触发扫码登录。
```bash
echo -n "" > .cache/cookies.json
node publish.js ...
```
**Q：一直登录失败怎么办？**
A：不需要自主尝试其他登录方案，直接提示登录失败，请联系开发同学@天晟。
**Q：如何查看已有表单的字段 ID？**
A：使用 `get-schema` 技能获取表单 Schema，从中读取各字段的 `fieldId`。
**Q：页面代码更新后如何重新发布？**
A：直接重新执行 `yida-publish` 命令即可，会覆盖已有 Schema。
---
## 文件结构约定
```
项目根目录/
├── README.md # 用来判断根目录路径，必须存在
├── config.json # 全局配置（loginUrl、defaultBaseUrl）
├── .cache/
│ └── cookies.json # 登录态缓存和其他临时文件（运行时自动生成）
├── pages/src/
│ └── <项目名>.js # 自定义页面源码
├── pages/dist/
│ └── <项目名>.js # 自定义页面编译后的代码
├── prd/
│ └── <项目名>.md # 需求文档（含所有配置信息）
└── .claude/
└── skills/ # 各子技能目录
```
> - **临时文件写在当前工程根目录的 .cache 文件夹中，如果没有就创建一个文件夹，注意不要写在系统的其他文件夹中**
标签
skill
ai
