openyida 2026.8.28 → 2026.8.30

package/README.md

@@ -199,6 +199,7 @@ openyida create-process APP_XXX "Purchase Request" .cache/openyida/process/field
 openyida configure-process APP_XXX FORM_XXX .cache/openyida/process/process.json
 openyida process preview APP_XXX PROC_INST_XXX --output .cache/openyida/process/process.html
 openyida data query form APP_XXX FORM_XXX --page 1 --size 20
+openyida data query form APP_XXX FORM_XXX --dynamic-order '{"dateField_xxx":"-"}'
 openyida data create form APP_XXX FORM_XXX --data-file .cache/openyida/data-import/record.json
 openyida get-permission APP_XXX FORM_XXX
 ```
@@ -226,6 +227,7 @@ openyida get-permission APP_XXX FORM_XXX
 发布成功还必须精确回读同一 PUBLISHED `processId/processVersion` 的 `getProcessById` 平台视图，并验证可见节点的组件、名称、顺序和审批模式。只有输出 `verificationLevel: "PLATFORM_VIEW_VERIFIED"` 才表示平台 view 已验证；`PUBLISHED_UNVERIFIED` 表示发布可能已生效但回读不完整，不能宣称 `processJson` 已验证，也不能直接重放写请求。
 
 When creating or updating test data with `openyida data`, Yida date fields must use 13-digit millisecond timestamps, for example `"dateField_xxx": 1719705600000`. Do not submit `YYYY-MM-DD` strings for `DateField` or `CascadeDateField` values.
+For deterministic query order, pass `--dynamic-order '{"fieldId":"+"}'` for ascending order or `--dynamic-order '{"fieldId":"-"}'` for descending order. Without `--dynamic-order`, `searchFormDatas` does not guarantee a stable result order; pagination, comparison, and pairing logic must not depend on the default order.
 Temporary JSON, CSV, and one-off import scripts should live under `.cache/openyida/` so generated run artifacts do not clutter the repository root.
 
 ### Real Environment E2E
@@ -305,6 +307,10 @@ OPENYIDA_E2E=1 npm run eval:e2e -- --skill yida-dashboard --screenshot --auto-sc
 # above, here the agent self-orchestrates.
 OPENYIDA_E2E=1 npm run eval:generate -- --screenshot
 
+# Re-evaluate an archived real CLI trace against the latest scenario contract and
+# current read-only platform state. This does not run an agent or mutate resources.
+npm run eval:replay -- --report <generation-report.json> --scenario <scenario.json> --app-type APP_XXX
+
 # Run all three in one pass (routing + tool-pipeline baseline + real generation).
 OPENYIDA_E2E=1 npm run eval:all -- --skill yida-dashboard --screenshot
 
@@ -406,7 +412,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida create-form add-option <appType> <formUuid> <fieldLabel> <option1> [option2] ...` | Update a form page |
 | `openyida list-forms <appType> [--keyword <text>]` | List forms/pages in an app |
 | `openyida aggregate-table <list\|create-empty\|inspect\|preview\|save\|publish\|status> <appType> ...` | Manage aggregate tables (virtualView) |
-| `openyida get-schema <appType> <formUuid\|--all> [--summary-json\|--field-map-json]` | Get one form Schema or all form Schemas |
+| `openyida get-schema <appType> <formUuid\|--all> [--summary-json\|--field-map-json\|--analysis-json]` | Get one form Schema or all form Schemas |
 | `openyida check-prd-completeness <prd.md> --app-type <appType> [--build-manifest <file>] [--json]` | Check PRD page/resource count risk |
 | `openyida er <appType> [--format mermaid\|json] [--output file] [--include-system] [--include-pages]` | Export app entity relationship diagram |
 | `openyida create-page <appType> "<name>" [--mode dashboard] [--hide-nav] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a custom display page |
@@ -424,13 +430,13 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 
 | Command | Description |
 |---------|-------------|
-| `openyida data <action> <resource> [args]` | Unified data management (form/process/task/subform) |
+| `openyida data <query\|get\|create\|update\|delete> <form\|process\|subform\|tasks\|operation-records\|task> [args]` | Unified data management (form/process/task/subform) |
 | `openyida task-center <type> [options]` | Global task center (todo/processed/cc etc.) |
 | `openyida basic-info <overview\|commodity\|grant\|capacity\|quota\|abs-path\|dataflow\|i18n\|domain>` | Query organization basic info, capacity, quotas, and domain settings |
 | `openyida read-dingtalk-doc <docUrl> [--output <file>] [--json]` | Fetch Markdown content from a DingTalk document |
 | `openyida read-dingtalk-tingji <taskUuid> [--json]` | Fetch DingTalk Tingji details by task UUID |
-| `openyida get-permission <appType> <formUuid>` | Query form permission config |
-| `openyida save-permission <appType> <formUuid> ...` | Save form permission config |
+| `openyida get-permission <appType> <formUuid> [--package-uuid <packageUuid>] [--json]` | Query form permission config |
+| `openyida save-permission <appType> <formUuid> --package-uuid <packageUuid> [--data-permission <json>\|--action-permission <json>\|--field-permission <json>]` | Save form permission config |
 | `openyida corp-manager <search-user\|list\|add\|remove\|address-book> ...` | Manage platform admins and address book permissions |
 | `openyida agent-center <list\|create\|update\|cancel\|range\|search-user> ...` | Manage process and departure delegation |
 
@@ -485,7 +491,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 |---------|-------------|
 | `openyida integration create <appType> ... [--spec file.json]` | Create integration automation flow |
 | `openyida integration update <appType> <formUuid> <processCode> --spec <desired-spec.json> [--publish]` | Probe integration update capability (currently blocked without full readback) |
-| `openyida integration list <appType> [--form-uuid <uuid>] [--status y\|n] [--json]` | List integration automation flows |
+| `openyida integration list <appType> [--flow-types 1,2,3,5,6] [--form-uuid <uuid>] [--status y\|n] [--json]` | List integration automation flows |
 | `openyida integration enable <appType> <formUuid> <processCode>` | Enable integration automation flow |
 | `openyida integration disable <appType> <formUuid> <processCode>` | Disable integration automation flow |
 | `openyida integration check <appType...>` | Check abnormal integration automation run logs |

package/bin/yida.js

@@ -484,6 +484,45 @@ function printCommandUsage(...lines) {
   console.log(lines.filter(Boolean).join('\n'));
 }
 
+const MANIFEST_HELP_PATHS = Object.freeze({
+  'get-schema': ['get-schema'],
+  'query-data': ['data'],
+  'data-manage': ['data'],
+  data: ['data'],
+  report: ['report'],
+  'create-process': ['create-process'],
+  'create-report': ['create-report'],
+  'save-share-config': ['save-share-config'],
+  'verify-short-url': ['verify-short-url'],
+  'integration-create': ['integration', 'create'],
+  'save-permission': ['save-permission'],
+  'get-permission': ['get-permission'],
+});
+
+function printManifestCommandHelp(commandName) {
+  const canonicalPath = MANIFEST_HELP_PATHS[commandName];
+  if (!canonicalPath) {
+    return false;
+  }
+
+  const manifest = buildCommandManifest({ t, version: currentVersion });
+  const matches = manifest.commands.filter((entry) =>
+    canonicalPath.every((token, index) => entry.path[index] === token)
+  );
+  const exact = matches.find((entry) => entry.path.length === canonicalPath.length);
+  const entries = exact ? [exact] : matches;
+  if (entries.length === 0) {
+    return false;
+  }
+
+  printCommandUsage(...entries.flatMap((entry) => [
+    entry.usage,
+    entry.description,
+    ...(entry.examples || []),
+  ]));
+  return true;
+}
+
 function printLoginHelp() {
   printCommandUsage(t('cli.login_usage'), t('cli.login_example'));
 }
@@ -549,6 +588,10 @@ async function main() {
     return;
   }
 
+  if (hasHelpFlag(args) && printManifestCommandHelp(command)) {
+    return;
+  }
+
   switch (command) {
     case 'commands': {
       if (args[0] === 'validate' || args[0] === 'build') {

package/lib/app/get-schema.js

@@ -3,8 +3,8 @@
  *
  * 用法：
  *   openyida get-schema <appType> <formUuid> [--compact] [--resolve-fields <labelOrFieldId,...>]
- *   openyida get-schema <appType> <formUuid> [--summary-json|--field-map-json]
- *   openyida get-schema <appType> --all [--summary-json] [--output-dir <dir>] [--concurrency N] [--retries N]
+ *   openyida get-schema <appType> <formUuid> [--summary-json|--field-map-json|--analysis-json]
+ *   openyida get-schema <appType> --all [--summary-json|--analysis-json] [--output-dir <dir>] [--concurrency N] [--retries N]
  */
 
 'use strict';
@@ -22,15 +22,27 @@ const { t } = require('../core/i18n');
 const { throwCommandError } = require('../core/command-errors');
 const { fetchFormPageList } = require('./form-navigation');
 const { buildFieldResolution } = require('./schema-field-resolution');
+const { buildSemanticAnalysis } = require('./schema-semantic-analysis');
 
 // 需要在报表 fieldCode 中加 _value 后缀的字段类型
 const FIELD_TYPES_NEEDING_VALUE_SUFFIX = new Set([
   'SelectField',
+  'MultiSelectField',
   'EmployeeField',
+  'DepartmentSelectField',
   'RadioField',
   'CheckboxField',
 ]);
 
+const FIELD_COMPONENT_NAMES = new Set([
+  'TextField', 'TextareaField', 'SelectField', 'MultiSelectField',
+  'DateField', 'CascadeDateField', 'NumberField', 'RadioField', 'CheckboxField',
+  'EmployeeField', 'DepartmentSelectField', 'PhoneField', 'EmailField',
+  'CascadeSelectField', 'CountrySelectField', 'CitySelectField', 'AddressField',
+  'ImageField', 'AttachmentField', 'TableField', 'AssociationFormField',
+  'RateField', 'SignatureField', 'SerialNumberField',
+]);
+
 /**
  * 从 Schema 中提取字段摘要，列出每个字段的真实 fieldId、组件别名和报表用 reportFieldCode。
  * @param {object} schemaResult - getFormSchema API 返回结果
@@ -44,12 +56,6 @@ function extractFieldSummary(schemaResult) {
   }
   const aliasMaps = buildComponentAliasMaps(schemaResult);
 
-  const FIELD_COMPONENT_NAMES = new Set([
-    'TextField', 'TextareaField', 'SelectField', 'DateField', 'NumberField',
-    'RadioField', 'CheckboxField', 'EmployeeField', 'PhoneField', 'EmailField',
-    'CascadeSelectField', 'ImageField', 'AttachmentField', 'TableField',
-  ]);
-
   function traverse(node) {
     if (!node) {
       return;
@@ -67,6 +73,15 @@ function extractFieldSummary(schemaResult) {
       if (fieldId) {
         const options = extractOptionSummary(props);
         const optionSource = getOptionSource(props) || [];
+        const complexDefault = props.complexValue && typeof props.complexValue === 'object'
+          ? props.complexValue.value
+          : undefined;
+        const defaultValue = firstPresent([complexDefault, props.defaultValue, props.value, props.default]);
+        const validationRules = Array.isArray(props.validation) ? props.validation : [];
+        const hasRequiredSignal = Object.prototype.hasOwnProperty.call(props, 'required')
+          || validationRules.some(rule => rule && (rule.type === 'required' || rule.required === true));
+        const required = props.required === true || props.required === 'true'
+          || validationRules.some(rule => rule && (rule.type === 'required' || rule.required === true));
         fields.push({
           label,
           componentName: node.componentName,
@@ -76,6 +91,10 @@ function extractFieldSummary(schemaResult) {
           options,
           optionCount: optionSource.length,
           optionsTruncated: optionSource.length > options.length,
+          ...(hasRequiredSignal
+            ? { required }
+            : {}),
+          ...(defaultValue !== undefined ? { defaultValue } : {}),
         });
       }
     }
@@ -321,6 +340,7 @@ function parseArgs(args) {
     field: '',
     json: false,
     summaryJson: false,
+    analysisJson: false,
   };
 
   for (let index = 1; index < args.length; index++) {
@@ -354,6 +374,8 @@ function parseArgs(args) {
       parsed.json = true;
     } else if (arg === '--summary-json' || arg === '--field-map-json') {
       parsed.summaryJson = true;
+    } else if (arg === '--analysis-json') {
+      parsed.analysisJson = true;
     } else if (!arg.startsWith('--') && !parsed.formUuid) {
       parsed.formUuid = arg;
     }
@@ -426,15 +448,6 @@ function collectFieldNodes(schemaResult) {
   const pages = schemaResult && schemaResult.content && schemaResult.content.pages;
   if (!pages || pages.length === 0) {return nodes;}
 
-  const FIELD_COMPONENT_NAMES = new Set([
-    'TextField', 'TextareaField', 'SelectField', 'DateField', 'NumberField',
-    'RadioField', 'CheckboxField', 'EmployeeField', 'PhoneField', 'EmailField',
-    'CascadeSelectField', 'ImageField', 'AttachmentField', 'TableField',
-    'MultiSelectField', 'DepartmentSelectField', 'AssociationFormField',
-    'CountrySelectField', 'CitySelectField', 'RateField', 'SignatureField',
-    'SerialNumberField',
-  ]);
-
   function traverse(node) {
     if (!node) {return;}
     if (FIELD_COMPONENT_NAMES.has(node.componentName)) {
@@ -486,7 +499,10 @@ async function fetchSchema(appType, formUuid, authRef) {
 }
 
 function isSuccessfulSchemaResult(result) {
-  return !!(result && result.success !== false && !result.__needLogin);
+  const content = resolveSchemaContent(result);
+  const pages = content && content.pages;
+  return !!(result && result.success !== false && !result.__needLogin
+    && Array.isArray(pages));
 }
 
 function printFieldSummary(result) {
@@ -722,6 +738,16 @@ async function runSingle(parsed, authRef) {
     return;
   }
 
+  if (parsed.analysisJson) {
+    console.log(JSON.stringify(buildSemanticAnalysis(
+      parsed.appType,
+      parsed.formUuid,
+      result,
+      extractFieldSummary(result)
+    ), null, 2));
+    return;
+  }
+
   chalkSuccess(t('get_schema.success'));
   printFieldSummary(result);
   console.log(JSON.stringify(result, null, 2));
@@ -756,6 +782,14 @@ async function runBatch(parsed, authRef) {
 
   const records = await mapLimit(forms, parsed.concurrency, async (form) => {
     const record = await fetchSchemaRecord(parsed.appType, form, authRef, parsed.retries);
+    if (record.success && parsed.analysisJson) {
+      record.semanticAnalysis = buildSemanticAnalysis(
+        parsed.appType,
+        record.formUuid,
+        record.schema,
+        record.fieldSummary
+      );
+    }
     if (record.success) {
       info(`  ✅ ${record.formName || record.formUuid}`);
     } else {
@@ -764,7 +798,9 @@ async function runBatch(parsed, authRef) {
     return record;
   });
 
-  const outputRecords = writeBatchOutput(parsed.outputDir, records, { compact: parsed.summaryJson });
+  const outputRecords = writeBatchOutput(parsed.outputDir, records, {
+    compact: parsed.summaryJson || parsed.analysisJson,
+  });
   const successCount = records.filter(record => record.success).length;
   const failedCount = records.length - successCount;
 
@@ -780,6 +816,7 @@ async function runBatch(parsed, authRef) {
     successCount,
     failedCount,
     summaryOnly: parsed.summaryJson || undefined,
+    analysisOnly: parsed.analysisJson || undefined,
     outputDir: parsed.outputDir ? path.resolve(parsed.outputDir) : undefined,
     forms: outputRecords,
   }, null, 2));
@@ -800,6 +837,8 @@ module.exports = {
   extractFieldSummary,
   extractOptionSummary,
   buildSchemaSummary,
+  buildSemanticAnalysis,
+  isSuccessfulSchemaResult,
   buildComponentAliasMaps,
   parseArgs,
   appendFieldQueries,

package/lib/app/schema-semantic-analysis.js

@@ -0,0 +1,223 @@
+'use strict';
+
+const crypto = require('crypto');
+
+function parseObject(value) {
+  if (typeof value !== 'string') {
+    return value && typeof value === 'object' ? value : null;
+  }
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveContent(schemaResult) {
+  if (!schemaResult) {return null;}
+  return parseObject(schemaResult.content !== undefined ? schemaResult.content : schemaResult);
+}
+
+function labelText(label) {
+  if (label === null || label === undefined) {return '';}
+  if (typeof label === 'object') {
+    return String(label.zh_CN || label.zh_HK || label.en_US || label.text || label.label || '');
+  }
+  return String(label);
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function isPresent(value) {
+  if (value === null || value === undefined || value === '') {return false;}
+  if (Array.isArray(value)) {return value.length > 0;}
+  if (typeof value === 'object') {return Object.keys(value).length > 0;}
+  return true;
+}
+
+function hasFormulaSemantics(value) {
+  if (!isPresent(value)) {return false;}
+  if (typeof value === 'string') {return value.trim() !== '';}
+  if (Array.isArray(value)) {return value.length > 0;}
+  if (typeof value !== 'object') {return true;}
+  if (['expression', 'source', 'value', 'formula'].some(key => isPresent(value[key]))) {
+    return true;
+  }
+  if (Array.isArray(value.data) && value.data.length > 0) {return true;}
+  if (value.event && typeof value.event === 'object') {
+    return Object.values(value.event).some(events => Array.isArray(events) ? events.length > 0 : isPresent(events));
+  }
+  return false;
+}
+
+function extractFunctionNames(source) {
+  const names = [];
+  const patterns = [
+    /export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/g,
+    /exports\.([A-Za-z_$][\w$]*)\s*=\s*/g,
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(source)) !== null) {
+      names.push(match[1]);
+    }
+  }
+  return unique(names);
+}
+
+function extractUrlParams(source) {
+  const keys = [];
+  const pattern = /urlParams(?:\.([A-Za-z_$][\w$]*)|\[['"]([^'"]+)['"]\])/g;
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    keys.push(match[1] || match[2]);
+  }
+  return unique(keys);
+}
+
+function extractFieldMutations(source) {
+  const mutations = [];
+  const pattern = /this\.\$\(\s*['"]([^'"]+)['"]\s*\)\s*\.\s*(setValue|setBehavior|reset|validate|show|hide)\s*\(/g;
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    mutations.push({ fieldId: match[1], operation: match[2] });
+  }
+  const seen = new Set();
+  return mutations.filter((item) => {
+    const key = `${item.fieldId}:${item.operation}`;
+    if (seen.has(key)) {return false;}
+    seen.add(key);
+    return true;
+  });
+}
+
+function bindingFromValue(value, path) {
+  if (!value || typeof value !== 'object' || value.type !== 'actionRef') {return null;}
+  return {
+    event: path[path.length - 1] || '',
+    actionName: value.name || value.id || '',
+    fieldId: path.find(part => typeof part === 'string' && /Field_/.test(part)) || '',
+  };
+}
+
+function buildSemanticAnalysis(appType, formUuid, schemaResult, fieldSummary = []) {
+  const content = resolveContent(schemaResult) || {};
+  const actionModule = content.actions && content.actions.module || {};
+  const source = typeof actionModule.source === 'string' ? actionModule.source : '';
+  const compiled = typeof actionModule.compiled === 'string' ? actionModule.compiled : '';
+  const fieldBehaviors = [];
+  const bindings = [];
+  let associationRuleCount = 0;
+
+  function visit(value, path = []) {
+    if (!value) {return;}
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => visit(item, path.concat(index)));
+      return;
+    }
+    if (typeof value !== 'object') {return;}
+
+    const binding = bindingFromValue(value, path);
+    if (binding) {bindings.push(binding);}
+
+    const props = value.props || {};
+    if (Array.isArray(props.associationRules)) {
+      associationRuleCount += props.associationRules.length;
+    }
+    if (props.fieldId) {
+      const validation = Array.isArray(props.validation) ? props.validation : [];
+      const validationTypes = unique(validation.map(rule => rule && (rule.type || rule.name || (rule.required ? 'required' : ''))));
+      const behavior = props.behavior && props.behavior !== 'NORMAL' ? String(props.behavior) : '';
+      const formula = hasFormulaSemantics(props.formula)
+        || hasFormulaSemantics(props.defaultDataSource && props.defaultDataSource.formula);
+      const dataSourceUrl = props.remoteDataSource && props.remoteDataSource.url
+        || props.dataSource && !Array.isArray(props.dataSource) && props.dataSource.url
+        || props.dataSource && props.dataSource.searchConfig && props.dataSource.searchConfig.url
+        || '';
+      const hasDataSourceBinding = !!(
+        props.remoteDataSource
+        || dataSourceUrl
+        || props.dataSourceLinkage
+        || (props.dataSourceType && props.dataSourceType !== 'custom')
+      );
+      const association = props.associationForm || props.associationFormConfig || null;
+      if (behavior || validationTypes.length || formula || hasDataSourceBinding || association) {
+        fieldBehaviors.push({
+          fieldId: String(props.fieldId),
+          label: labelText(props.label),
+          componentName: value.componentName || '',
+          ...(behavior ? { behavior } : {}),
+          ...(validationTypes.length ? { validationTypes } : {}),
+          ...(formula ? { hasFormulaOrLinkage: true } : {}),
+          ...(hasDataSourceBinding ? {
+            dataSource: {
+              type: props.dataSourceType || (props.remoteDataSource ? 'remote' : 'linked'),
+              hasUrl: !!dataSourceUrl,
+            },
+          } : {}),
+          ...(association ? {
+            association: {
+              formUuid: association.formUuid || association.targetFormUuid || association.formId || '',
+              hasBackfill: !!(association.backfill || association.backfillRules || association.fillRules),
+            },
+          } : {}),
+        });
+      }
+    }
+
+    Object.keys(value).forEach((key) => {
+      if (key !== 'source' && key !== 'compiled') {
+        visit(value[key], path.concat(key));
+      }
+    });
+  }
+
+  visit(content.pages || []);
+
+  const actionList = content.actions && Array.isArray(content.actions.list)
+    ? content.actions.list
+    : [];
+  const actionEntries = actionList.map(item => ({
+    id: item.id || item.name || '',
+    name: item.name || item.title || item.id || '',
+    type: item.type || '',
+    relatedEventId: item.relatedEventId || '',
+  }));
+  const mutationFields = unique(extractFieldMutations(source).map(item => item.fieldId));
+
+  return {
+    kind: 'yida_schema_semantic_analysis',
+    contractVersion: 1,
+    resource: {
+      appType,
+      formUuid,
+      schemaHash: `sha256:${crypto.createHash('sha256').update(JSON.stringify(content)).digest('hex')}`,
+    },
+    fieldCount: fieldSummary.length,
+    fields: fieldSummary,
+    semantics: {
+      actions: {
+        sourceBytes: Buffer.byteLength(source, 'utf8'),
+        compiledBytes: Buffer.byteLength(compiled, 'utf8'),
+        functions: extractFunctionNames(source),
+        entries: actionEntries,
+        bindings,
+        urlParams: extractUrlParams(source),
+        fieldMutations: extractFieldMutations(source),
+        referencedMutationFields: mutationFields,
+      },
+      fieldBehaviors,
+      associationRuleCount,
+    },
+  };
+}
+
+module.exports = {
+  buildSemanticAnalysis,
+  extractFieldMutations,
+  extractFunctionNames,
+  extractUrlParams,
+};

package/lib/core/agent-capabilities.js

@@ -136,6 +136,10 @@ const BUILDER_CORE_COMMAND_IDS = Object.freeze([
   'app-list',
   'list-forms',
   'get-schema',
+  'data',
+  'nav-group',
+  'get-permission',
+  'save-permission',
   'create-app',
   'create-form.create',
   'create-page',
@@ -154,6 +158,7 @@ function commandBriefs(manifest, commandIds) {
       output: entry.output,
       permission_mode: entry.permission && entry.permission.mode,
       side_effect_kind: entry.side_effect && entry.side_effect.kind,
+      examples: entry.examples || [],
     }));
 }
 

package/lib/core/command-manifest.js

@@ -920,7 +920,7 @@ const FORBIDDEN_ALIASES = Object.freeze([
     suggested_usage: 'openyida app-list [--size N]',
     alternative_command_ids: ['get-schema', 'agent-capabilities'],
     alternative_usages: [
-      'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json]',
+      'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json|--analysis-json]',
       'openyida agent-capabilities --summary-json',
     ],
     message_key: 'cli.forbidden_alias_get_app',
@@ -958,7 +958,7 @@ const FORBIDDEN_ALIASES = Object.freeze([
     pattern: 'get-schema --app-type',
     matcher: { type: 'command_has_option', command: 'get-schema', option: '--app-type' },
     suggested_command_id: 'get-schema',
-    suggested_usage: 'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json]',
+    suggested_usage: 'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json|--analysis-json]',
     message_key: 'cli.forbidden_alias_get_schema_app_type_option',
     message_args: ['get-schema', '--app-type'],
   }),
@@ -967,7 +967,7 @@ const FORBIDDEN_ALIASES = Object.freeze([
     pattern: 'get-schema --form-uuid',
     matcher: { type: 'command_has_option', command: 'get-schema', option: '--form-uuid' },
     suggested_command_id: 'get-schema',
-    suggested_usage: 'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json]',
+    suggested_usage: 'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json|--analysis-json]',
     message_key: 'cli.forbidden_alias_get_schema_form_uuid_option',
     message_args: ['get-schema', '--form-uuid'],
   }),
@@ -1038,6 +1038,10 @@ const COMMAND_GROUPS = [
       command('nav-group', ['nav-group'], 'nav-group <list|create|rename|delete|move|order|auto-order|hide|show> <appType> ...', 'help.cmd_nav_group', {
         output: 'json',
         aliases: ['group'],
+        examples: [
+          'openyida nav-group list APP_XXX --flat',
+          'openyida nav-group move APP_XXX FORM_XXX --to NAV_XXX',
+        ],
       }),
       command('app-permission', ['app-permission'], 'app-permission <get|set|add|remove|search-user> ...', 'help.cmd_app_permission', {
         output: 'json',
@@ -1133,11 +1137,15 @@ const COMMAND_GROUPS = [
       command('add-validation', ['add-validation'], 'add-validation <appType> <formUuid> --field <labelOrId> --type <phone|regex|idCard|email|...> [--message <text>]', 'help.cmd_update_form'),
       command('create-form.bind-datasource', ['create-form', 'bind-datasource'], 'create-form bind-datasource <appType> <formUuid> <fieldLabelOrId> <dataSourceJsonOrFile> [--open|--no-open]', 'help.cmd_update_form'),
       command('create-form.add-option', ['create-form', 'add-option'], 'create-form add-option <appType> <formUuid> <fieldLabel> <option1> [option2] ...', 'help.cmd_update_form'),
-      command('list-forms', ['list-forms'], 'list-forms <appType> [--keyword <text>]', 'help.cmd_list_forms'),
+      command('list-forms', ['list-forms'], 'list-forms <appType> [--keyword <text>]', 'help.cmd_list_forms', {
+        examples: ['openyida list-forms APP_XXX --keyword 客户'],
+      }),
       command('aggregate-table', ['aggregate-table'], 'aggregate-table <list|create-empty|inspect|preview|save|publish|status> <appType> ...', 'help.cmd_aggregate_table', {
         output: 'json',
       }),
-      command('get-schema', ['get-schema'], 'get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json]', 'help.cmd_get_schema'),
+      command('get-schema', ['get-schema'], 'get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json|--analysis-json]', 'help.cmd_get_schema', {
+        examples: ['openyida get-schema APP_XXX FORM_XXX --field-map-json'],
+      }),
       command('check-prd-completeness', ['check-prd-completeness'], 'check-prd-completeness <prd.md> --app-type <appType> [--build-manifest <file>] [--json]', 'help.cmd_check_prd_completeness', {
         output: 'json',
       }),
@@ -1160,7 +1168,11 @@ const COMMAND_GROUPS = [
     id: 'data',
     titleKey: 'help.group_data',
     commands: [
-      command('data', ['data'], 'data <action> <resource> [args]', 'help.cmd_data'),
+      command('data', ['data'], 'data <query|get|create|update|delete> <form|process|subform|tasks|operation-records|task> [args]', 'help.cmd_data', {
+        examples: [
+          'openyida data create form APP_XXX FORM_XXX --data-json \'{"textField_name":"客户 A","dateField_followUp":1787932800000}\'',
+        ],
+      }),
       command('task-center', ['task-center'], 'task-center <type> [options]', 'help.cmd_task_center'),
       command('basic-info', ['basic-info'], 'basic-info <overview|commodity|grant|capacity|quota|abs-path|dataflow|i18n|domain>', 'help.cmd_basic_info', {
         output: 'json',
@@ -1171,8 +1183,13 @@ const COMMAND_GROUPS = [
       command('read-dingtalk-tingji', ['read-dingtalk-tingji'], 'read-dingtalk-tingji <taskUuid> [--json]', 'help.cmd_read_dingtalk_tingji', {
         output: 'json',
       }),
-      command('get-permission', ['get-permission'], 'get-permission <appType> <formUuid>', 'help.cmd_get_permission'),
-      command('save-permission', ['save-permission'], 'save-permission <appType> <formUuid> ...', 'help.cmd_save_permission'),
+      command('get-permission', ['get-permission'], 'get-permission <appType> <formUuid> [--package-uuid <packageUuid>] [--json]', 'help.cmd_get_permission'),
+      command('save-permission', ['save-permission'], 'save-permission <appType> <formUuid> --package-uuid <packageUuid> [--data-permission <json>|--action-permission <json>|--field-permission <json>]', 'help.cmd_save_permission', {
+        examples: [
+          'openyida get-permission APP_XXX FORM_XXX --json',
+          'openyida save-permission APP_XXX FORM_XXX --package-uuid PACKAGE_XXX --data-permission \'{"dataRange":"ORIGINATOR"}\'',
+        ],
+      }),
       command('corp-manager', ['corp-manager'], 'corp-manager <search-user|list|add|remove|address-book> ...', 'help.cmd_corp_manager', { output: 'json' }),
       command('agent-center', ['agent-center'], 'agent-center <list|create|update|cancel|range|search-user> ...', 'help.cmd_agent_center', { output: 'json' }),
     ],
@@ -1240,7 +1257,7 @@ const COMMAND_GROUPS = [
         requiresLogin: false,
         output: 'json',
       }),
-      command('integration.list', ['integration', 'list'], 'integration list <appType> [--form-uuid <uuid>] [--status y|n] [--json]', 'help.cmd_integration_list', {
+      command('integration.list', ['integration', 'list'], 'integration list <appType> [--flow-types 1,2,3,5,6] [--form-uuid <uuid>] [--status y|n] [--json]', 'help.cmd_integration_list', {
         output: 'json',
       }),
       command('integration.enable', ['integration', 'enable'], 'integration enable <appType> <formUuid> <processCode>', 'help.cmd_integration_enable', {

package/lib/core/query-data.js

@@ -24,7 +24,7 @@ const { readFormMode } = require('../app/services/form-mode-service');
 const USAGE = `openyida data - Unified Yida data CLI
 
 Usage:
-  openyida data query form <appType> <formUuid> [--page N] [--size N] [--all] [--max-pages N] [--search-json JSON|--search-file .cache/openyida/search.json] [--resolve-aliases] [--inst-id ID] [--no-hydrate-subforms]
+  openyida data query form <appType> <formUuid> [--page N] [--size N] [--all] [--max-pages N] [--search-json JSON|--search-file .cache/openyida/search.json] [--dynamic-order '{"fieldId":"+"}'] [--resolve-aliases] [--inst-id ID] [--no-hydrate-subforms]
   openyida data get form <appType> --inst-id <formInstId> [--form-uuid <formUuid>] [--no-hydrate-subforms]
   openyida data create form <appType> <formUuid> (--data-json <JSON>|--data-file .cache/openyida/data.json) [--dept-id ID] [--resolve-aliases]
     说明：若目标表单为流程表单，会自动使用 /v1/process/startInstance.json 发起流程。
@@ -41,6 +41,8 @@ Usage:
   openyida data query tasks <appType> --type <todo|done|submitted|cc> [--page N] [--size N] [--keyword TEXT] [--process-codes JSON] [--instance-status STATUS]
 
 Add --resolve-aliases when JSON keys use Yida component aliases instead of field IDs.
+Use --dynamic-order '{"fieldId":"+"}' for ascending order or '{"fieldId":"-"}' for descending order.
+When --dynamic-order is omitted, the API does not guarantee a stable result order.
 `;
 
 function fail(message) {