# Create App

Use this when the user wants one new app inside an existing package.
This playbook follows the current public builder surface, not legacy package helper tools.

Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:

1. read or create the package through `package_get` / `package_apply`
2. create the related apps in one `app_schema_apply(package_id=..., apps=[...])` call
3. keep package ownership on the public `package_id` path instead of a separate attach step
4. add same-call relation fields with `target_app_ref` when one new app references another new app; use `target_app_key` only after the target app already exists or readback confirms it
5. choose explicit non-template `icon + color` for each new package/app

Hierarchy reminder:

- package -> app -> field -> relation
- another business object is another app, not a text field

If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, create it through `package_apply(package_name=..., icon=..., color=...)`.

## Minimal sequence

1. `package_get` if `package_id` is already known; otherwise derive the package from related readback or ask the user for the id
2. `app_resolve`
3. `app_schema_apply`
4. `app_publish_verify` only when the user asks for explicit final verification

## Multi-app systems are different

If the user says things like:

- “创建一个完整应用包”
- “包含项目、需求、任务、缺陷、团队这几个表单”
- “这些表单之间建立关联关系”

then do not treat that as one app.

Use this pattern instead:

1. `package_get` or `package_apply(package_name=..., icon=..., color=...)`
2. for a multi-app system, run one `app_schema_apply` with `package_id` and `apps[]`
3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app

If that multi-app call times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, do not decide that the create failed. Run `readback_before_retry`: read the package, resolve each intended app by package/name or returned app key, read fields, and retry only verified missing apps or fields. Do not rebuild the same complete system as separate single-app creates, and do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.

## Example

When designing fields, do not add platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`. Qingflow provides them automatically; create only business fields.

Field authoring rules:

- Use intuitive field types in drafts: `text`, `multiline`, `select`, `multi_select`, `number`, `amount`, `date`, `datetime`, `member`, `department`, `attachment`, `relation`.
- The tool normalizes aliases before writing: `multiline -> long_text`, `select -> single_select`, `checkbox -> multi_select`, `currency -> amount`, `mobile -> phone`. Readback may show canonical types; that is not a failed write.
- Every new app must have exactly one top-level `as_data_title: true` field. `as_data_cover: true` is optional and only valid on a top-level `attachment`.
- Select fields must define `options` during schema design. Options may be strings or objects such as `{"label": "进行中"}`; sample data must use those labels or ids.
- Relation fields must use `target_app_ref` for same-batch apps or `target_app_key` for existing apps, plus object selectors: `display_field: {"name": "..."}` and `visible_fields: [{"name": "..."}]`. Do not write bare strings for display/visible field selectors.
- Do not impose a one-relation-field-per-app limit. Model the real business links and let backend validation/readback decide.

Create a new package only after the user confirms package creation:

```json
{
  "tool_name": "package_apply",
  "arguments": {
    "profile": "default",
    "package_name": "研发项目管理",
    "icon": "briefcase",
    "color": "azure"
  }
}
```

Read the package when `package_id` is already known:

```json
{
  "tool_name": "package_get",
  "arguments": {
    "profile": "default",
    "package_id": 1218950
  }
}
```

Apply schema for a new app:

```json
{
  "tool_name": "app_schema_apply",
  "arguments": {
    "profile": "default",
    "app_name": "客户订单",
    "package_id": 1218950,
    "icon": "delivery-box-1",
    "color": "emerald",
    "publish": true,
    "add_fields": [
      {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
      {"name": "客户名称", "type": "text", "required": true},
      {"name": "订单封面", "type": "attachment", "as_data_cover": true},
      {"name": "订单金额", "type": "amount"},
      {"name": "状态", "type": "select", "options": [{"label": "草稿"}, {"label": "进行中"}, {"label": "已完成"}], "required": true}
    ],
    "update_fields": [],
    "remove_fields": []
  }
}
```

Apply schema for multiple apps in one call:

```json
{
  "tool_name": "app_schema_apply",
  "arguments": {
    "profile": "default",
    "package_id": 1218950,
    "publish": true,
    "apps": [
      {
        "client_key": "customer",
        "app_name": "客户",
        "icon": "business-personalcard",
        "color": "emerald",
        "add_fields": [
          {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
        ]
      },
      {
        "client_key": "order",
        "app_name": "订单",
        "icon": "delivery-box-1",
        "color": "blue",
        "add_fields": [
          {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
          {
            "name": "关联客户",
            "type": "relation",
            "target_app_ref": "customer",
            "display_field": {"name": "客户名称"},
            "visible_fields": [{"name": "客户名称"}]
          }
        ]
      }
    ]
  }
}
```

Data title is required: mark exactly one top-level field with `as_data_title: true`. Data cover is optional and only valid on a top-level `attachment` field.

## Common failures

### `APP_NOT_FOUND`

For new apps, submit `app_schema_apply` with `package_id + app_name + icon + color`. For existing apps, resolve and pass the real `app_key`.

### `CREATE_APP_ROUTE_NOT_FOUND`

The create route did not resolve in the current backend route context. In Wingent Momo runtime, first retry the same `app_schema_apply` after confirming the injected session is still active. Only run `workspace_select` if a business tool explicitly reports a missing or wrong workspace.

### Hierarchy modeling mistake

If the user asked for several named forms/apps but the draft patch turns them into text fields inside one app, stop and remodel the task as:

- one package
- many apps
- relation fields between those apps