yida-get-schema

name	yida-get-schema
description	确定性解析表单字段 ID、子表路径和表单行为语义；agent 按字段引用、完整字段映射或反向分析场景选择对应 contract。

获取表单 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 先全量看一遍"

---

命令

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，不得调换。

参数	必填	说明
appType	是	应用 ID
formUuid	单表模式必填	表单 UUID
--compact	否	输出 yida_schema_field_resolution contract v1，不输出完整 Schema
--resolve-fields <query,...>	否	按精确 label、fieldId、alias、稳定 ID 路径或 子表/字段 可读路径筛选；可重复，自动启用 compact
--all	批量模式必填	获取应用下所有表单/页面的 Schema
--output-dir <dir>	否	将每个 Schema 写入独立 JSON 文件，并生成 index.json
--keyword <text>	否	仅批量导出名称、UUID、类型或路径匹配关键词的表单
--concurrency N	否	批量并发数，默认 3，范围 1-10
--retries N	否	单个 Schema 失败后的重试次数，默认 1，范围 0-5
--summary-json / --field-map-json	否	只输出字段摘要 JSON，不把完整 Schema 放入 stdout；--field-map-json 是语义别名
--analysis-json	否	输出 yida_schema_semantic_analysis contract v1：字段摘要、动作函数/绑定、URL 参数、字段 mutation、只读/隐藏、校验、公式/联动、关联和数据源摘要；不回显动作源码

单表模式

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 的结构化文件写入工具创建：

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

批量模式

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：

{
  "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"],
        
       
       
    
  
   
   

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

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

{
  "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。

异常处理

异常场景	处理方式
命令返回失败	确认 appType 和 formUuid 正确，检查登录态
输出被终端截断	优先改用 --summary-json；确需完整 Schema 时，再将 stdout 通过结构化文件写入工具保存到 <projectRoot>/.cache/openyida/<项目名或任务名>/<表单名>-schema.json；不要使用 shell 重定向
需要多个表单字段 ID	使用批量摘要或每表单完整字段映射：openyida get-schema <appType> --all --summary-json --output-dir .cache/openyida/<项目名或任务名>/schemas，或对目标表单逐个执行一次 --field-map-json；默认只读完整 JSON / index.json 字段摘要，不用 head/tail/grep 截断
批量部分失败	查看 stdout 的 failedCount 和 forms[].errorMsg，必要时提高 --retries 或缩小 --keyword 范围
找不到目标字段	查看 missingFields，确认字段已创建后重新查询；不能手写猜测 fieldId
同名字段无法唯一确定	查看 ambiguousFields[].matches[].labelPath 和稳定 path，使用完整路径或 fieldId 重新查询；不得默认取第一个
Schema 输出为空	表单可能没有字段，先用 yida-create-form-page 创建字段