Yida Get Schema

获取表单 Schema

严格禁止 (NEVER DO)

• 绝对禁止猜测或编造 fieldId，宜搭字段 ID 由平台随机生成（格式如 textField_eftt1aa5m、selectField_fix024y92），无法从字段名称推断，必须通过此命令获取
• 不要在未获取 Schema 的情况下执行任何涉及字段 ID 的操作
• 不要假设字段 ID 格式，即使看起来像 textField_xxx，也必须通过命令确认
• 不要跳过 Schema 获取步骤直接进行数据操作，即使用户催促也必须先获取
• 不要在 Schema 获取失败时继续执行后续操作，必须先解决问题
• 不要缓存过期的 Schema 信息，表单结构变更后必须重新获取
• 不要把进程内状态或 CLI 自动派生索引当作跨调用缓存；查询新字段时允许重新拉取完整 Schema
• 不要把 openyida get-schema 的 stdout 通过 shell 重定向保存成 JSON，也不要用 heredoc、cat/echo/printf/tee 生成 Schema 文件
• 不要把 openyida get-schema 的 stdout 再接 head、tail、grep、sed、awk 等截断/筛选命令作为 Schema 证据；这会丢字段、选项或子表路径，导致后续重复拉取
• 不要在同一阶段对同一个 formUuid 连续执行 --compact、--field-map-json、完整 Schema 等多轮“探一段 stdout”式查询；除非表单刚被修改、上次命令失败/不完整，或排障需要完整组件 props

严格要求 (MUST DO)

• 凡是需要用到字段 ID（fieldId）的操作，必须先执行此命令，不得跳过
• 页面开发、数据查询、报表配置或流程规则只需要字段身份时，先执行 openyida get-schema <appType> <formUuid> --compact --resolve-fields "<字段1,字段2>"，不要拉取完整 Schema
• 页面开发默认使用 compact 输出，只读取必要字段契约，不内联完整 Schema
• 完整应用页面、看板、列表或详情页需要一个表单的大部分字段，或需要跨多个表单建立 dataBinding 时，优先对每个表单执行一次 openyida get-schema <appType> <formUuid> --field-map-json，消费完整 JSON 后解析所需字段，不用 shell 截断 stdout
• 分析、复刻或迁移已有表单时，执行一次 openyida get-schema <appType> <formUuid> --analysis-json，同时消费字段与 semantics.actions/fieldBehaviors/associationRuleCount；不得只凭 field map 推断原表单没有生命周期、联动、公式、关联或数据源行为
• 多表单场景同一阶段同一 formUuid 默认最多拉取一次字段映射；把 appType、formUuid、fieldId、label、componentName、options 等合并写入 <projectRoot>/.cache/<项目名>-schema.json，后续 page-spec.json 和源码复用该本地 ID 映射
• 执行 compact 查询后，只消费唯一命中的 fields[]；missingFields 或 ambiguousFields 非空时停止，不得猜测或继续写操作
• 只有用户明确需要完整组件 props、布局结构、字段数据源配置，或 compact/summary 无法排障时，才执行不带 --compact/--summary-json 的完整 Schema 输出；拿到完整 Schema 后只读取必要片段，不内联完整 Schema
• 已有 <projectRoot>/.cache/<项目名>-schema.json 等本地 ID 映射文件可显式复用；目标字段缺失、重名、结构已变或无法确认新鲜度时，必须重新执行 compact 查询
• 如需保存关键字段 ID 映射，使用结构化文件写入工具；这是 agent 管理的本地工件，不是 OpenYida CLI 自动缓存
• 如需保存完整 Schema 文件，先执行命令获取 stdout，再用 create_file / Write / file edit tool 写入 <projectRoot>/.cache/openyida/<项目名或任务名>/<表单名>-schema.json；从 workspace 根执行后续命令时传 project/.cache/...
• 录入/更新数据后，必须用 openyida data query --size 1 抽查一条记录，确认 formData 中字段有实际值（非空 ""），若全部为空说明字段 ID 有误，需重新排查

适用场景

在执行以下操作前必须使用：

• 新增/录入表单数据（yida-data-management create）← 最常见的遗漏场景，必须先 get-schema
• 更新表单数据（yida-data-management update）
• 配置数据查询条件（yida-data-management query searchFieldJson）
• 更新表单字段结构（yida-create-form-page update 模式）
• 配置流程字段权限（yida-process-rule）
• 自定义页面中引用字段 ID 常量（ yida-canvas-custom-page）

触发条件

正向触发：

• 任何需要用到 fieldId 的操作前（自动前置触发）
• "查看表单结构"、"获取字段 ID"、"查看 Schema"
• "分析/复刻/迁移已有表单"、"比较表单行为"、"查看生命周期/联动/公式/数据源"
• 其他技能（yida-data-management、yida-process-rule、页面源码维护技能）执行前的字段 ID 前置步骤
• "批量获取所有表单 Schema"、"导出应用下所有字段 ID"、"不知道 formUuid 先全量看一遍"

命令

bashCopy code
openyida get-schema <appType> <formUuid> --compact [--resolve-fields <labelOrFieldId,...>]
openyida get-schema <appType> <formUuid> [--summary-json|--field-map-json]
openyida get-schema <appType> <formUuid> --analysis-json
openyida get-schema <appType> --all [--summary-json|--analysis-json] [--output-dir <dir>] [--keyword <text>] [--concurrency N] [--retries N]

两个位置参数顺序固定：先传 appType，再传 formUuid，不得调换。

单表模式

bashCopy code
openyida get-schema APP_XXX FORM-XXX --compact --resolve-fields "访客姓名,状态"
openyida get-schema APP_XXX FORM-XXX --field-map-json
openyida get-schema APP_XXX FORM-XXX --analysis-json

Agent 只需要少量字段 ID 时，默认使用 --compact --resolve-fields，读取 fields[].label、fields[].fieldId、fields[].componentType、fields[].valueType、fields[].path、fields[].labelPath 和 fields[].parentFieldId。path 是稳定的 fieldId 数组，labelPath 是可读路径；所有可用语言的 label 都参与精确匹配。同名字段会进入 ambiguousFields[].matches，必须使用完整 labelPath、稳定 path 或已返回的 fieldId 重新精确选择，禁止取第一个。

需要全量字段摘要和选项时继续使用 --summary-json。只有需要组件完整 props、布局结构、字段数据源配置或排障时，才执行不带 compact/summary 参数的完整 Schema 输出。

反向分析时读取 --analysis-json，重点区分：源码字节数大不等于业务行为多；以 urlParams、fieldMutations、动作绑定、字段行为、关联规则和数据源摘要判断业务语义。需要等价迁移时，把字段结构与行为结构分别交给 yida-create-form-page，不要把缺失行为误报成“字段已创建所以表单完成”。

消费输出时读取完整 JSON，再由 agent / 脚本解析字段；不要用 tail -20、head -30 或 grep 只看局部 stdout。局部查看可以作为人工调试，但不能作为后续写页面、写数据或配置流程的字段证据。

如需复用输出，使用 agent 的结构化文件写入工具创建：

textCopy code
<projectRoot>/.cache/openyida/customer/customer-schema.json
<projectRoot>/.cache/customer-schema.json   # 仅保存 appType/formUuid/fieldId/reportId 等 ID 映射

批量模式

bashCopy code
openyida get-schema APP_XXX --all --summary-json --output-dir .cache/openyida/customer/schemas
openyida get-schema APP_XXX --all --analysis-json --output-dir .cache/openyida/customer/schema-analysis
openyida get-schema APP_XXX --all --keyword 客户 --concurrency 5 --retries 2

批量模式会先读取应用导航中的表单/页面列表，再逐个请求 getFormSchema。如果指定 --output-dir：

• 每个成功的 Schema 会写入 <表单名>-<formUuid>.json
• index.json 会记录 formUuid、名称、类型、字段摘要、失败原因和 schema 文件路径
• stdout 仍输出汇总 JSON，便于脚本继续处理

输出

Agent compact 模式输出共享 contract，不包含完整 Schema 或 props：

jsonCopy code
{
  "kind": "yida_schema_field_resolution",
  "contractVersion": 1,
  "resource": {
    "appType": "APP_XXX",
    "formUuid": "FORM-XXX",
    "schemaHash": "sha256:<64位小写十六进制>"
  },
  "fields": [
    {
      "query": "订单明细/商品名称",
      "label": "商品名称",
      "fieldId": "textField_xxx",
      "componentType": "TextField",
      "valueType": "custom",
      "path": ["tableField_xxx", "textField_xxx"],
      "labelPath": ["订单明细", "商品名称"],
      "parentFieldId": "tableField_xxx",
      "alias": ""
    }
  ],
  "missingFields": [],
  "ambiguousFields": []
}

--compact 不带 --resolve-fields 时按 Schema 顺序返回全部正规化字段。指定 --resolve-fields 时，fields 只含唯一命中项，未命中和重名分别进入 missingFields、ambiguousFields。

单表模式默认仍将完整的 Schema JSON 输出到 stdout，包含 pages、componentsMap 等字段结构；兼容摘要模式可用 --summary-json 或 --field-map-json：

jsonCopy code
{
  "success": true,
  "appType": "APP_XXX",
  "formUuid": "FORM-XXX",
  "fieldCount": 2,
  "fields": [
    {
      "label": "访客姓名",
      "componentName": "TextField",
      "fieldId": "textField_xxx",
      "alias": "visitorName",
      "reportFieldCode": "textField_xxx",
      "options": [],
      "optionCount": 0,
      "optionsTruncated": false
    }
  ]
}

批量模式将汇总 JSON 输出到 stdout；指定 --output-dir 时，完整 Schema 写入文件，stdout 中的 forms[].schemaFile 指向对应文件。加 --summary-json 时，stdout 和 index.json 都只保留字段摘要与 schemaFile 指针，不内联完整 Schema。

编码前可用此命令确认表单中各字段的 fieldId。

异常处理