@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/skills/cosmic-meta-api/SKILL.md

@@ -1,7 +1,6 @@
+> 📝 **[G15-script]**: 当向用户转述脚本输出时，按系统 `<language-policy>` 的 `response_language` 改写；脚本语言不一致时不要原样复制日志。
 
-> 📝 **[G15-script]**: When relaying script output to the user, rephrase it in the `response_language` declared in the system prompt's `<language-policy>`. Do not copy-paste logs verbatim when their language differs from that language.
-
-# 苍穹 Open API 调用技能
+# 苍穹 Open API 调用参考
 
 
 ## 技能说明
@@ -24,31 +23,26 @@ AI 在需要生成苍穹 API 调用代码或解答相关问题时，应优先读
 | 导出/下载元数据（dym 文件同步到本地）                         | `modules/export/SKILL.md`  |
 | 生成 PDM / PDM 同步 / 同步数据模型 / 生成建表脚本             | `modules/pdm/SKILL.md`     |
 
-### Workspace / 应用上下文（与建模一致）
-
-源码 DYM/DYMX 只在 app-build 会话收口时同步，不在每条写命令后同步。
-`render_output_cards.py` 汇总本轮表单编码，只对本地已经存在 `.dym` 的表单执行一次批量
-`syncDym --existing-only`；没有现存 DYM 的表单直接跳过，不创建新文件。报表命令若需要 DYM
-完成即时验证，只导出到 `_runtime/`，不会更新源码元数据。
+### 应用上下文与交付
 
-- **应用编码（真实场景唯一起源）**：**仅**当前已绑定应用 **`{appRoot}/archive.json` 中的 `appCode`。**`workspace.json` 的 `appNumber` 须与此一致，由 `bootstrapWorkspace` 从 `archive.json` 同步，**不是**让 AI 在对话中自行推断或从别处「猜」一个编码。
-- **入口应用必须已存在**：根入口已经在当前苍穹平台验证 `appCode`。`bootstrapWorkspace` 只能复核并同步该应用；查询不到时以 `EXISTING_APP_NOT_FOUND` 中止，也不会调用通用 `createApp`。源应用验证后，已注册的 `extendApp` 操作可以创建扩展应用。
-- **身份交接**：表单扩展采用不同的已有或新建扩展应用时，必须先验证并把应用编码、ID、名称同步到当前 archive/context，再执行下游写入。
-- **业务云**：`bizCloudId` / `bizCloudName` 必须来自 `{appRoot}/archive.json`（由主入口应用归属判断写入）；`bootstrapWorkspace` 从 archive 读取，缺失则阻断。**禁止**用多轮聊天开放式收集云名/应用作为真源。
-- **ISV / standard**：由 `getDevInfo` API 动态获取并写入 `workspace.json`，不硬编码。
-- **自举主命令**：`{python} scripts/cosmic_api.py bootstrapWorkspace --app-root "<appRoot>"`。凭据就绪后，它只校验并同步已经绑定的应用身份，不创建流程工作项。
+命令负责线上目标绑定、鉴权及运行时上下文；本地 archive 是已验证绑定的记录，
+不是线上对象是否存在的证明。绑定缺失或归属冲突时按
+[应用上下文](../../references/application-context.md)处理，不另建初始化流程。
 
+本轮表单汇总、卡片输出及 DYM/DYMX 同步统一遵循
+[交付契约](../../references/delivery.md)。源码同步创建缺失文件并更新已有文件；
+即时验证导出的运行时副本不等于源码同步。
 
 ---
 
-> **路径推算**：SKILL_DIR = 本文件所在目录（`cosmic-meta-api/`）。CONFIG = `SKILL_DIR/../config.json`（= `skills/config.json`）。Python 脚本统一使用 `{python}`（遵循 `[G9.1]`）。
+> **路径推算**：SKILL_DIR 是当前 `cosmic-meta-api/` 目录。使用根入口提供的 `{python}`；配置及运行时路径由 CLI 解析。
 
 ## 共用资源
 
 
 | 资源       | 路径                                                                         | 说明                                     |
 | -------- | -------------------------------------------------------------------------- | -------------------------------------- |
-| API 凭据配置 | `../config.json`（即 `skills/config.json`）                                   | 唯一真源，`server.`* 节                      |
+| 环境配置 | `~/.kd/config.json`，由 `kd_env_loader.py` 解析 | 初始化与恢复使用 init/reset 入口 |
 | 核心脚本     | `scripts/cosmic_api.py`                                                    | 所有子命令入口                                |
 | 路径推算     | SKILL_DIR 相对方式（无需 skill_env.json）                                          |                                        |
 | 运行时状态    | `RUNTIME_DIR`（= `{PROJECT_ROOT}/app/_runtime/cosmic-metadata/`，定义见本文件目录结构） | context.md / biz_cache.json / token    |

package/skills/cosmic-build/skills/cosmic-meta-api/apis/ai_meta.md

@@ -1,7 +1,7 @@
 # AI 建模中心 API
 
 > 基础路径：`{BASE_URL}{api_base_path}`  
-> `api_base_path` 从 `scripts/config.json` 的 `api_base_path` 字段读取（如 `/ierp/kapi/v2/uhyl/uhyl_aireqdecomp/ai-meta`）  
+> `api_base_path` 为脚本内部注册的固定接口前缀（如 `/ierp/kapi/v2/uhyl/uhyl_aireqdecomp/ai-meta`），不读取技能目录内的 config.json  
 > 鉴权方式：请求头 `accessToken: <access_token>`，详见 `../auth.md`
 
 ---

package/skills/cosmic-build/skills/cosmic-meta-api/apis/app_menu.md

@@ -1,7 +1,7 @@
 # 应用菜单管理 API
 
 > 基础路径：`{BASE_URL}{api_base_path}/app/menu`  
-> `api_base_path` 从 `scripts/config.json` 的 `api_base_path` 字段读取（如 `/ierp/kapi/v2/uhyl/uhyl_aireqdecomp/ai-meta`）  
+> `api_base_path` 为脚本内部注册的固定接口前缀（如 `/ierp/kapi/v2/uhyl/uhyl_aireqdecomp/ai-meta`），不读取技能目录内的 config.json  
 > 鉴权方式：请求头 `accessToken: <access_token>`，详见 `../auth.md`
 
 ---

package/skills/cosmic-build/skills/cosmic-meta-api/apis/meta_log.md

@@ -1,7 +1,7 @@
 # 元数据历史记录 API
 
 > 基础路径：`{BASE_URL}{api_base_path}/metalog`
-> `api_base_path` 读取 `scripts/config.json` 的 `api_base_path` 字段（例如 `/ierp/kapi/v2/devportal/ai-meta`）
+> `api_base_path` 为脚本内部注册的固定接口前缀（例如 `/ierp/kapi/v2/devportal/ai-meta`），不读取技能目录内的 config.json
 > 鉴权方式：请求头 `accessToken: <access_token>`，详见 `../auth.md`
 > 后端 Controller：`kd.bos.designer.meta.metalog.MetaLogApiController`
 

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/control-authoring.json

@@ -2,7 +2,48 @@
   "schemaVersion": "app-build-control-authoring/v1",
   "command": "addControls",
   "scope": "one exact existing PC form",
-  "semantics": "one compact request creates one or many independently verified controls under an exact existing container, or atomically creates one titled general-control panel and places the complete batch inside it; the CLI resolves aliases, parents and generated keys before writing",
+  "semantics": "one compact request creates one or many independently verified controls under an exact existing container, or atomically creates one titled general-control panel and places the complete batch inside it; omitted placement uses the live form root. The CLI resolves aliases, parents and generated keys before writing. Retries match exact keys, not control types",
+  "inputSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "General control batch input",
+    "type": "object",
+    "required": ["controls"],
+    "properties": {
+      "parent": {"type": "string", "minLength": 1, "description": "Exact existing container key or unique caption; omitted means the live form root. Not combined with panel."},
+      "panel": {"$ref": "#/$defs/panel"},
+      "controls": {"type": "array", "minItems": 1, "maxItems": 50, "items": {"$ref": "#/$defs/control"}}
+    },
+    "not": {"required": ["parent", "panel"]},
+    "additionalProperties": false,
+    "$defs": {
+      "key": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,35}$"},
+      "panel": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "key": {"$ref": "#/$defs/key", "description": "Stable panel identity; generated from name when omitted."},
+          "name": {"type": "string", "minLength": 1},
+          "parent": {"type": "string", "minLength": 1, "description": "Existing container selector; omitted means the live form root."},
+          "presentation": {"type": "string", "enum": ["auto", "stack"], "default": "auto"}
+        },
+        "additionalProperties": false
+      },
+      "control": {
+        "type": "object",
+        "required": ["type", "name"],
+        "properties": {
+          "key": {"$ref": "#/$defs/key", "description": "Stable control identity; generated from resolved type and name when omitted. Repeating the same key verifies the existing control; another control of the same type does not satisfy this request."},
+          "type": {"type": "string", "minLength": 1, "description": "Released type or case-insensitive alias from x-controlTypes."},
+          "name": {"type": "string", "minLength": 1, "description": "Control display name."},
+          "parent": {"type": "string", "minLength": 1, "description": "Overrides the batch parent. Omit for a declared panel. Without either parent, use the live form root."},
+          "index": {"type": "integer", "minimum": 0},
+          "properties": {"type": "object", "description": "Only x-commonProperties and the selected type's x-controlTypes properties are accepted, with their declared value types."}
+        },
+        "additionalProperties": false
+      }
+    },
+    "examples": [{"controls": [{"type": "LabelAp", "name": "Notice"}]}]
+  },
   "commonProperties": {
     "visible": {"type": "string", "readProperty": "Visible"},
     "lock": {"type": "string", "readProperty": "Lock"},
@@ -19,6 +60,7 @@
     "VectorAp": {"aliases": ["图标", "icon", "vector"], "properties": {"fontClass": {"type": "string", "readProperty": "FontClass"}, "clickable": {"type": "boolean", "readProperty": "Clickable"}}},
     "ImageListAp": {"aliases": ["图片列表", "image list"], "properties": {"displayTitle": {"type": "boolean", "readProperty": "DisplayTitle"}, "multiImg": {"type": "boolean", "readProperty": "MultiImg"}, "uploadImg": {"type": "boolean", "readProperty": "UploadImg"}, "maxImgSize": {"type": "integer", "minimum": 0, "readProperty": "MaxImgSize"}, "imgSource": {"type": "integer", "minimum": 0, "readProperty": "ImgSource"}, "showName": {"type": "boolean", "readProperty": "ShowName"}, "colNum": {"type": "integer", "minimum": 1, "readProperty": "ColNum"}}},
     "CodeEditAp": {"aliases": ["代码编辑器", "code editor"], "properties": {"fileType": {"type": "string", "readProperty": "FileType"}, "codeEditTheme": {"type": "string", "readProperty": "CodeEditTheme"}, "showLineNumber": {"type": "boolean", "readProperty": "ShowLineNumber"}}},
+    "FilterGridAp": {"aliases": ["通用过滤", "common filter", "common filter grid"], "properties": {}},
     "TreeViewAp": {"aliases": ["树控件", "tree"], "properties": {"rootVisible": {"type": "boolean", "readProperty": "RootVisible"}, "multiCheck": {"type": "boolean", "readProperty": "Multi"}, "dragEnable": {"type": "boolean", "readProperty": "DragEnable"}}},
     "AttachmentPanelAp": {"aliases": ["附件面板", "attachment panel"], "properties": {"collapsible": {"type": "boolean", "readProperty": "Collapsible"}, "defaultCollapse": {"type": "boolean", "readProperty": "DefaultCollapse"}, "showTitle": {"type": "boolean", "readProperty": "ShowTitle"}, "showAttachmentTips": {"type": "boolean", "readProperty": "ShowAttachmentTips"}, "expandMore": {"type": "boolean", "readProperty": "ExpandMore"}, "uploadProgressBar": {"type": "boolean", "readProperty": "UploadProgressBar"}}},
     "QRCodeAp": {"aliases": ["二维码", "qr code"], "properties": {"qrCodeShowStyle": {"type": "integer", "minimum": 0, "readProperty": "QrCodeShowStyle"}, "showBarCodeValue": {"type": "boolean", "readProperty": "ShowBarCodeValue"}}},
@@ -44,8 +86,7 @@
     "TabAp": {"alias": "页签控件", "route": "applyFormTabs/applyFormUi"},
     "FieldsetPanelAp": {"alias": "字段布局面板", "route": "addFieldPanel/applyFormUi"},
     "SplitContainerAp": {"alias": "分割容器", "route": "applyFormSplit"},
-    "AdvConAp": {"alias": "高级容器", "route": "addAdvancedContainer"},
-    "FilterGridAp": {"alias": "通用过滤", "route": "configureList"}
+    "AdvConAp": {"alias": "高级容器", "route": "addAdvancedContainer"}
   },
   "panel": {
     "type": "FlexPanelAp",
@@ -82,7 +123,7 @@
     ]
   },
   "deferredTypes": {
-    "AdvFilterGridAp": {"alias": "高级过滤", "reason": "platform feature remains unreleased"},
+    "AdvFilterGridAp": {"alias": "高级过滤", "reason": "designer can place the shell, but advanced-filter behavior and wiring are not verified for CLI authoring"},
     "CustomControlAp": {"alias": "自定义控件", "reason": "requires an exact t_meta_ctlschema schemaId"},
     "ClientAjaxAp": {"alias": "客户端AJAX", "reason": "design metadata persists but the current runtime creates no control node without a request/response contract"},
     "WebOfficeAp": {"alias": "WebOffice", "reason": "design metadata persists but runtime requires a document/session binding contract"},

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/form-control-traits.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "app-build-form-control-traits/v1",
-  "evidenceSource": "tests/metadata-xml-corpus/contracts/element-superclasses.json",
+  "evidenceSource": "platform metadata class hierarchy captured during contract harvest",
   "purpose": "Language-neutral policy for existing PC-form subtree moves and role classification. Runtime code consumes this contract; the model does not read or reproduce it.",
   "types": {
     "FieldAp": {

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/layout-ui.json

@@ -130,6 +130,24 @@
         ]
       }
     },
+    "configureDropdownMenu": {
+      "effect": "write",
+      "semantics": "stage append, update, remove and order/moves on one existing button menu, retaining unmentioned items and original IDs, then save once; the command reads the menu and resolves exact keys or unique titles/operation keys",
+      "requiredByAppBuild": ["appRoot OR projectRoot", "formNumber OR form-name", "input"],
+      "parentResolution": "elementKey/element is optional when existing item selectors identify one menu in the primary form. Otherwise the command returns button candidates without writing.",
+      "itemFields": ["key", "title", "subtitle", "operation", "background", "icon", "switch", "theme", "merge", "lock", "visible", "uploadable", "uploadConfig"],
+      "locale": "When a title has several languages and no language is selected, the receipt returns language keys and --locale; retry the same intent with the chosen key. Ownership and other translations remain unchanged.",
+      "safety": {
+        "preflight": "reads current menu; checks executable operation type or attached implementation only for new or changed operation bindings. Display-only edits preserve the original binding without revalidating its business implementation; missing or ambiguous targets return menu candidates without writing",
+        "identity": "existing keys and IDs are retained; append never silently overwrites an existing key; clear and replace are not semantic edit actions",
+        "references": "binding an operation does not implement its business behavior; never create a no-op placeholder to satisfy a missing operation",
+        "failure": "no clear/rebuild/rename fallback; failed verification is not successful delivery",
+        "preservation": "Python copies the native menu objects from loadFullMetadata, retaining Id, IsvFlag, multilingual text and unmentioned properties; it changes only the selected menu path and uses existing saveFullMetadata. A fresh baseline check precedes saving, followed by a full-document comparison and a retained recovery snapshot. No new backend endpoint is required.",
+        "order": "selected items come first; unmentioned items follow in their original relative order",
+        "verification": "full-snapshot read-back checks menu order, IDs, ownership and values plus unrelated metadata; only top-level modifyDate and modifierId are excluded as server audit fields; no-op edits do not save",
+        "icons": "use an existing ImageKey from the platform picture selector; semantic icon names are not verified resource keys"
+      }
+    },
     "addFieldPanel": {
       "effect": "write",
       "semantics": "Create or reuse one titled FieldsetPanelAp for grouping fields, directly inside the exact existing TabPageAp selected by --page when supplied, otherwise under the inferred content root. Page resolution is type-scoped and fails before writing on missing or ambiguous targets. This command does not create fields. Add fields with addField --panel using the returned panelVerification.panelKey.",

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/menu-publish.json

@@ -24,7 +24,13 @@
         "linkWithoutUrl": "menuType=link without linkUrl",
         "formUuid": "form UUID passed where server expects formNumber"
       },
-      "readBack": ["getMenu for each record", "one final queryMenuTree for the complete requested path"]
+      "readBack": ["getMenu for each record", "one final queryMenuTree for the complete requested path"],
+      "afterVerifiedMenuTree": {
+        "command": "publishApp",
+        "arguments": ["--bizAppId", "<archive.appId>", "--action", "enable"],
+        "precondition": "仅明确要求发布菜单；先用 getApp 核对同一应用身份",
+        "alreadyEnabled": "平台明确回复应用已启用时视为无变化，不重试"
+      }
     },
     "publishApp": {
       "effect": "platform-application-state-write",
@@ -42,7 +48,7 @@
     }
   },
   "verificationMapping": {
-    "design": "getMenu contains the exact record identity and one final queryMenuTree contains every requested parent/category/page path",
+    "design": "getMenu 验证准确菜单记录；最终 queryMenuTree 验证全部目标路径；明确发布菜单后用 getApp/publishApp 核实同一应用的启用状态",
     "runtime": "not part of default delivery; only run separate acceptance when explicitly requested by the user",
     "rollback": "verify deletion through the command's design-state read-back; external runtime acceptance is user-initiated"
   }

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/property-batch.json

@@ -78,6 +78,13 @@
       "idempotency": "请求与线上值已一致时返回 status true、changed=false 且 writeAttempted=false，两条路都是",
       "readBack": "getProperties.InstantSync 从 JSON 字符串解码后，canUpdate 为 false 的列集合必须等于请求，且解码出来的每个行事件状态也必须等于请求；清空必须读回 null。写入后不一致按 unknown_after_write 报出"
     },
+    "renameElementKey": {
+      "effect": "write",
+      "scope": "one exact existing form element",
+      "arguments": ["app_root OR project_root with app identity", "formNumber OR form_name", "element as current exact key or unique caption", "new_key"],
+      "semantics": "applies the developer namespace once, renames through the live single-target Key setter, migrates matching form/biz-rule preCondition and triggerField strings, and verifies the element name/type/parent/index plus absence of stale rule references",
+      "failureBoundary": "rule inventory is required before mutation; a failed rule migration triggers a key rollback and reports whether metadata remains changed"
+    },
     "setProperties": {
       "legacyFailureReceipt": {
         "results": "retains each raw result, including the failed item and unknown write state",

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/property-input-index.json

@@ -40407,11 +40407,11 @@
         "valueDomains": null,
         "appliesTo": null,
         "writeRoute": {
-          "command": "setComplexProperty",
+          "command": "configureDropdownMenu",
           "complexType": "dropdownItems",
-          "dataKind": "array",
+          "dataKind": "editIntent",
           "requiresElementKey": true,
-          "backendMethod": "setDropdownItems"
+          "backendMethod": "loadFullMetadata + saveFullMetadata"
         }
       }
     },

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/report-write-contracts.json

@@ -23,6 +23,7 @@
     "setReportFilters": {
       "payloadSchemaRef": "skills/cosmic-meta-api/contracts/schema/report-write.schema.json#/$defs/filters",
       "writeSemantics": "full replacement; the supplied array is the desired complete filter state",
+      "controlTypeBoundary": "Optional source={formNumber,fieldKey} selects ReportFilters.typed. The platform resolves the native field and creates its editor type with reference/enum options; date between uses DateRangeField. getReportSchema reads actual configuration, independently compared to fresh source fieldSchemas. Source conditions requiring unresolved organization or conditional references fail before mutation. Older platforms reject the typed route; never retry through the legacy text route.",
       "readBack": "getReportSchema.reportFilters matches the requested filter controls and panel state",
       "preWriteGuard": "REPORT_FILTER_KEY_COLLIDES_WITH_COLUMN: a fieldPath repeating a report column or group fieldKey is refused before the platform call, because control and column would share one element key and only the designer would reject the duplicated identifier. Use a distinct key such as flt_<column> and apply it to the column inside the data-fetch plugin."
     },

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/rule-domain.json

@@ -1,6 +1,7 @@
 {
   "schemaVersion": "app-build-rule-domain/v1",
   "contract": "rule-domain",
+  "actionTiming": "每个带 RET 的规则服务动作都可用 events 指定新规则的完整触发时机，或用 addEvents 追加时机而不清除原值。原子服务命令重复传 --event / --add-event，ensureRuleSet 的各项透传相同参数。已有规则要替换整组时机需用准确 ruleId 调用 updateRule。ensureFieldCalculation 和 ensureConditionalEntryStyle 不是 RET 服务动作。",
   "targetBinding": {
     "form": "每条已发布 ensure* 规则命令只接受 formNumber 或 form-name 之一。使用 form-name 时，同一调用通过 prepareFormMutationTarget 解析并验证可编辑表单；准确编码加 app-root 的旧路径继续作为兼容快路径。",
     "entity": "entity 为可选参数；表头、明细、分录、单据体等业务别名由 CLI 内部解析。一张苍穹单据包含一个主元数据实体，也可能包含多个 EntryEntity。实体业务规则绑定一个所属实体；界面/控件规则通过表单控件树绑定。需要实体求值的命令优先准确 key，并推导唯一共享 EntityKey。",
@@ -13,6 +14,7 @@
   },
   "sceneBoundary": {
     "sameEntityBinaryNumericCalculation": "ensureFieldCalculation",
+    "sameEntityTimeDifferenceHours": "ensureTimeDifferenceCalculation",
     "entryNumericSummaryToHeader": "setSummaryToField",
     "conditionalRequired": "setMustInputCondition plus ensureMustInputValidation when the operation must block",
     "operationBlockingMessage": "ensureOperationValidation",
@@ -23,6 +25,7 @@
     "advancedEntityActions": "addRule with ruleType=bizRule only for a released action family",
     "advancedClientReportListActions": "addRule with ruleType=formRule, an exact ClientRules-owning mount, and the action-specific ClientProperty/DisplayStyle/RowStyle caller shape",
     "conditionalClearSameEntityFields": "ensureConditionalClearFields",
+    "conditionalFieldValueUpdateService": "ensureConditionalFieldChange",
     "conditionalCopySameEntityFieldValue": "ensureConditionalCopyFieldValue",
     "conditionalCarryDeclaredReferenceProperty": "ensureConditionalCarryReferenceProperty",
     "conditionalSameEntityBinaryCalculation": "ensureConditionalCalculation",
@@ -44,11 +47,15 @@
       "semantics": "validate one 1..20 item whitelist batch, then invoke only released rule-domain ensure writers in order; each writer keeps its own deterministic identity and read-back, and a failure returns completed results plus a continuation without crossing domains",
       "arguments": ["formNumber OR form-name", "input {rules:[{id,command,args}]}"],
       "allowedCommands": [
+        "ensureRuleFunctionFormula",
         "ensureFieldCalculation",
+        "ensureTimeDifferenceCalculation",
         "ensureConditionalFieldState",
         "ensureConditionalEntryStyle",
+        "ensureConditionalClientAppearance",
         "ensureConditionalControlState",
         "ensureConditionalClearFields",
+        "ensureConditionalFieldChange",
         "ensureConditionalCopyFieldValue",
         "ensureConditionalCalculation",
         "ensureConditionalCarryReferenceProperty",
@@ -71,10 +78,23 @@
         "duplicate actions for the same source and target fail closed"
       ]
     },
+    "ensureTimeDifferenceCalculation": {
+      "effect": "write",
+      "semantics": "解析同一实体中的一个数值目标字段和两个 TimeField，编译 target = (end - start) / 3600.0 的 FormulaAction，启用两个来源字段的更新事件；任一时间为空时清空目标，并独立回读完整规则",
+      "arguments": ["formNumber 或 form-name", "可选 entity", "target", "start", "end"],
+      "resultUnit": "十进制小时",
+      "timeStorage": "TimeField 以整数秒存储；必须使用 3600.0 才能保留小数小时，避免整数除法截断",
+      "overnightBoundary": "公式计算带符号的同日时间差；结束时间早于开始时间时不会自行推断为次日，需先取得明确业务决定",
+      "failClosed": [
+        "start 和 end 必须是所选实体内两个不同的 TimeField",
+        "target 必须是同一实体内另一个数值字段",
+        "同一目标已有不同 FormulaAction 或 ExecuteActions 计算时在写入前停止"
+      ]
+    },
     "ensureRuleFunctionFormula": {
       "effect": "write",
       "semantics": "解析同一实体中的目标字段和类型化 FX 调用树，从当前全局 listRuleFunctions 目录获取实际公式函数名与签名，编译一个 RET 253 的 FormulaAction；普通调用按字段类型保护（数值：field <> null；文本：field <> null and field <> ''）并带清空目标的 false 分支，空值处理函数与 MultiSelectBaseData 谓词仍可在空输入时执行；启用来源字段变化触发器并独立回读完整规则",
-      "arguments": ["formNumber OR form-name", "可选 entity", "target", "input {call:{functionId,args:[{field}|{literal}|{call}|{condition}]}}"],
+      "arguments": ["formNumber OR form-name", "可选 entity", "target", "input {call:{functionId,args:[{field}|{literal}|{call}|{condition}]}}", "可选重复 event/events 或 add-event/addEvents"],
       "releasedGroups": ["Math", "String", "DateTime", "Set", "JudgeNull", "NullJudge", "MultiSelectBaseData", "Bill", "Common"],
       "setFunctionBoundary": "if 使用类型化 condition 节点；sum/min/max/count/avg 仅接受同实体标量字段、嵌套调用和字面量。原始 addRule 的聚合函数仍被阻断，分录汇总到表头仍使用 setSummaryToField。",
       "multiSelectBaseDataBoundary": "MulBasedataIsNull/MulBasedataNotNull 接受一个 MulBasedataField。MulBasedataInclude/MulBasedataNotInclude 还要求非空记录编码字面量，多个编码用英文逗号分隔；编译器输出该字段的 .number 属性，调用方不得手写点路径。四个函数在空选择时返回自身布尔结果，不使用普通空值保护。",
@@ -99,7 +119,7 @@
       "effect": "write",
       "existingCondition": "a related generated rule with the same trigger and inverse actions blocks appending a conflicting condition; return RULE_CONDITION_UPDATE_REQUIRES_RULE_ID with candidates and a unique suggestedUpdate, never automatically replace it",
       "semantics": "解析一个条件作用域、触发字段、一个或多个同实体目标字段和业务比较；布尔常量不加字符串引号；下拉显示名、物理值和 @first 第一项哨兵均在命令内解析；创建一条动作包含完整目标集合和正确反向动作的确定性 formRule；主描述使用可读业务语义并保留末尾短标识；独立回读两个分支，重复执行不写入",
-      "arguments": ["formNumber OR form-name", "optional entity", "condition-field", "operator", "value", "one or more repeated target", "behavior"],
+      "arguments": ["formNumber OR form-name", "optional entity", "condition-field", "operator", "value", "one or more repeated target", "behavior", "optional exact repeated event / events array OR appended add-event / addEvents array"],
       "behaviors": ["show", "hide", "lock", "unlock"],
       "operators": ["equals", "not-equals", "greater-than", "greater-or-equal", "less-than", "less-or-equal", "empty", "not-empty"],
       "conditionScope": "挂载点跟随目标字段所在实体；条件字段可以在该实体上，也可以在单据头上——分录上的界面规则在行上下文里能读到单头值。empty 与 not-empty 不传 value。",
@@ -129,7 +149,7 @@
     "ensureConditionalClientAppearance": {
       "effect": "write",
       "semantics": "resolve one ClientRules-owning list grid/card row and one business condition, compile row style, field style and client field properties into one deterministic client rule, and independently read back the nested actions",
-      "arguments": ["formNumber OR form-name", "input {clientMount, optional entity, conditionField, operator, value, effects[]}"],
+      "arguments": ["formNumber OR form-name", "input {clientMount, optional entity, conditionField, operator, value, effects[], optional events OR addEvents}"],
       "effectKinds": ["rowStyle", "fieldStyle", "fieldProperty"],
       "scopeRules": {"ListGridViewAp": ["rowStyle", "fieldStyle"], "CardEntryRowAp/CardRowPanelAp": ["fieldStyle", "fieldProperty"]},
       "failClosed": [
@@ -155,8 +175,8 @@
     },
     "ensureConditionalClearFields": {
       "effect": "write",
-      "semantics": "解析一个实体、条件和一个或多个目标字段，包括下拉显示名、物理值和 @first；编译平台冒号分隔字段表达式与 RET 253 的单个 ClearValueAction，启用触发事件、去重并独立回读动作",
-      "arguments": ["formNumber OR form-name", "optional entity", "condition-field", "operator", "value", "one or more target"],
+      "semantics": "解析实体、条件与目标字段，编译单个 ClearValueAction。通用 events 指定新规则的准确时机，addEvents 在默认或已有 RET 上追加；更新后回读确认动作 ID 和完整规则均保留。重复执行已满足时零写入。",
+      "arguments": ["formNumber OR form-name", "optional entity", "condition-field", "operator", "value", "one or more target", "optional repeated event / events array OR add-event / addEvents array"],
       "failClosed": [
         "every target must resolve to a field owned by the selected entity",
         "duplicate targets are collapsed deterministically",
@@ -164,8 +184,19 @@
         "the caller never supplies Expression, RET, Seq, itemId or mountPoint"
       ]
     },
+    "ensureConditionalFieldChange": {
+      "effect": "write",
+      "semantics": "按字段名称或 key 解析条件和目标，编译平台支持的非空条件，创建一条 CallFieldChangeAction。新建时 events 只选择用户指定时机；addEvents 追加到默认时机或准确匹配的已有规则。回读规则身份、条件、目标和时机；设计态成功不代表运行态已分发后续规则。",
+      "arguments": ["formNumber OR form-name", "optional entity", "condition-field", "operator", "optional value", "target", "optional exact repeated event / events array OR appended add-event / addEvents array"],
+      "failClosed": [
+        "字段不存在或歧义时写前失败",
+        "不新增第二条语义相同的规则",
+        "运行态分发仍需目标环境验证"
+      ]
+    },
     "ensureConditionalCopyFieldValue": {
       "effect": "write",
+      "multiMapping": "多组字段带出用 --input {mappings:[{source,target,可选 onlyEmptyTarget}],可选 conditionField/operator/value/ruleId/branch}，或 ensureRuleSet 的 args.mappings；一条 SetEqutionAction 包含全部映射。省略 branch 表示条件成立时执行；branch=false 只在条件不成立时执行；不成立时不执行服务就省略 branch。合并已有拆分规则必须传准确 ruleId。",
       "semantics": "resolve one entity, condition, source and distinct target; compile SetEqutionAction Expression/FieldName as one TakeValueId mapping pair with optional only-empty behavior, validate entity scope, deduplicate semantically and independently read back the nested mapping",
       "arguments": ["formNumber OR form-name", "optional entity", "condition-field", "operator", "value", "source", "target", "optional only-empty-target"],
       "failClosed": [
@@ -177,6 +208,7 @@
     },
     "ensureConditionalCarryReferenceProperty": {
       "effect": "write",
+      "multiMapping": "多组基础资料属性带出用 --input {mappings:[{sourceReference,sourceProperty,target,可选 onlyEmptyTarget}],可选 conditionField/operator/value/ruleId/branch}，或 ensureRuleSet 的 args.mappings；一条 TakeBaseProAction 包含全部映射。省略 branch 表示条件成立时执行；branch=false 只在条件不成立时执行；不成立时不执行服务就省略 branch。合并已有拆分规则必须传准确 ruleId。",
       "semantics": "解析一个实体、已有引用字段、引用实体上的准确属性和不同目标；默认在来源引用不为空时触发，也可传显式业务条件；RefProps 缺少该属性时，通过 BaseEntityId 定位引用表单、验证唯一字段并用 setRefProps 闭环追加；编译带嵌套 TakeValueId、RET 253 和来源触发器的 TakeBaseProAction；规则语义相同时不重写规则",
       "arguments": ["formNumber OR form-name", "optional entity", "optional condition-field/operator/value", "source-reference", "source-property", "target", "optional only-empty-target"],
       "failClosed": [

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/rule-event-contract.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "app-build-rule-event-contract/v1",
-  "legalEventUnion": 1023,
+  "legalEventUnion": 2047,
   "eventBits": {
     "1": "FieldChanged",
     "2": "Initialized",
@@ -11,7 +11,26 @@
     "64": "SelectRowChanged",
     "128": "ItemAdding",
     "256": "AfterAdded",
-    "512": "AfterFieldChanged"
+    "512": "AfterFieldChanged",
+    "1024": "AfterCopy"
+  },
+  "actionMasksMeaning": "Metamodel raiseEventType values retained for registration and reference, not per-action event limits. Explicit RET is validated against the known event bits.",
+  "eventAliases": {
+    "新建": "ItemAdded",
+    "新增": "ItemAdded",
+    "值更新": "FieldChanged",
+    "字段值变化": "FieldChanged",
+    "加载": "Initialized",
+    "创建": "ItemAdded",
+    "创建后": "AfterAdded",
+    "值更新后": "AfterFieldChanged",
+    "字段值变化后": "AfterFieldChanged",
+    "Create": "ItemAdded",
+    "Update": "FieldChanged",
+    "FieldChange": "FieldChanged",
+    "AfterCreate": "AfterAdded",
+    "AfterFieldChange": "AfterFieldChanged",
+    "复制后": "AfterCopy"
   },
   "actionMasks": {
     "FormulaAction": 1021,
@@ -47,7 +66,9 @@
     "ClientSetRowFmtAction": 251
   },
   "blockedActions": {
-    "CallFieldChangeAction": "Current-version isolated runtime testing still proves that the action does not dispatch the target field's downstream business-rule or form-rule chain, even with a bare exact field key and RET=773.",
     "SetVisibleAction": "历史 Schema 占位名，不是平台动作：8.0 的 FormRuleActionTypes.xml 与 bos-metadata 类清单均不存在 SetVisibleAction。请使用已验证的 ShowFieldAction/HideFieldAction 或 ShowControlAction/HideControlAction 配对。"
+  },
+  "runtimeWarnings": {
+    "CallFieldChangeAction": "设计器支持此动作，元数据回读可验证配置。较早平台版本的隔离运行态测试未观察到后续规则链分发；在目标环境验证前不得声称运行效果已生效。"
   }
 }

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/cli/run-build-meta.json

@@ -3,14 +3,34 @@
   "commands": {
     "run": {
       "effect": "platform-create",
-      "requiredByAppBuild": ["appRoot", "artifact"],
+      "requiredByAppBuild": [
+        "appRoot",
+        "artifact"
+      ],
       "resolvers": {
-        "artifact": ["explicit artifact path", "metadata/_emit_manifest.json first artifact"],
-        "templateNumber": ["explicit template", "artifact.templateNumber", "matching manifest item templateNumber"],
-        "bizAppId": ["workspace.json bizAppId", "bootstrapWorkspace result"]
+        "artifact": [
+          "explicit artifact path",
+          "metadata/_emit_manifest.json first artifact"
+        ],
+        "templateNumber": [
+          "explicit template",
+          "artifact.templateNumber",
+          "matching manifest item templateNumber"
+        ],
+        "bizAppId": [
+          "workspace.json bizAppId",
+          "bootstrapWorkspace result"
+        ]
       },
       "positiveExample": {
-        "arguments": ["--app-root", "<owned-app-root>", "--artifact", "<decorated-artifact-path>", "--template", "bos_billtpl"],
+        "arguments": [
+          "--app-root",
+          "<owned-app-root>",
+          "--artifact",
+          "<decorated-artifact-path>",
+          "--template",
+          "bos_billtpl"
+        ],
         "artifactRequirements": {
           "entities": "non-empty array",
           "entityKey": "non-empty for non-report entities",
@@ -35,14 +55,38 @@
     },
     "runBatch": {
       "effect": "platform-create-batch",
-      "requiredByAppBuild": ["appRoot", "appCode", "artifacts"],
+      "requiredByAppBuild": [
+        "appRoot",
+        "appCode",
+        "artifacts"
+      ],
       "resolvers": {
-        "artifacts": ["explicit artifact paths", "metadata/_emit_manifest.json artifacts"],
-        "templateNumberPerArtifact": ["batch template override", "artifact.templateNumber", "matching manifest item templateNumber"],
-        "bizAppId": ["workspace.json bizAppId", "bootstrapWorkspace result"]
+        "artifacts": [
+          "explicit artifact paths",
+          "metadata/_emit_manifest.json artifacts"
+        ],
+        "templateNumberPerArtifact": [
+          "batch template override",
+          "artifact.templateNumber",
+          "matching manifest item templateNumber"
+        ],
+        "bizAppId": [
+          "workspace.json bizAppId",
+          "bootstrapWorkspace result"
+        ]
       },
       "positiveExample": {
-        "arguments": ["--app-root", "<owned-app-root>", "--app-code", "<exact-existing-app-code>", "--artifacts", "<decorated-artifact-1>", "<decorated-artifact-2>", "--concurrency", "4"],
+        "arguments": [
+          "--app-root",
+          "<owned-app-root>",
+          "--app-code",
+          "<exact-existing-app-code>",
+          "--artifacts",
+          "<decorated-artifact-1>",
+          "<decorated-artifact-2>",
+          "--concurrency",
+          "4"
+        ],
         "rules": [
           "one artifact per independently creatable main object",
           "concurrency is clamped to 1..8",
@@ -65,12 +109,17 @@
         "write": "every successful item independently exposes created formId/formNumber",
         "telemetry": "one batch started/finished pair records artifacts, waves and concurrency",
         "readBack": "queryForms/getFormSchema 独立验证每个成功项；动态项返回 dynamicUiResult，截图/业务组合返回 formCompositionResult",
-        "partialSuccess": "保留元数据的后置失败返回 forms，以及 continuation.appRoot/formNumber/formId/command/input 和 rerunBuildMeta=false"
+        "partialSuccess": "保留元数据的后置失败返回 forms，以及 continuation.appRoot/formNumber/formId/command/input 和 rerunBuildMeta=false",
+        "postBuildFailure": "POST_BUILD_PHASE_FAILED retains the exact saved target even when entityResults.success=true. Reconciliation precedes narrow repair; repairPlans preserve the failed phase, original artifact and available pending write input. notStartedArtifacts contains only explicit writeAttempted=false items. Never recreate a retained or verified form."
       }
     }
   },
   "verificationMapping": {
-    "design": ["queryFormsByApp", "getFormSchema", "listElements"],
+    "design": [
+      "queryFormsByApp",
+      "getFormSchema",
+      "listElements"
+    ],
     "runtime": "not part of default delivery; only run separate acceptance when the user explicitly requests it and names an available tool",
     "rollback": "delete only disposable forms created by this campaign, then independently confirm absence"
   }