@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/rule/SKILL.md

@@ -3,6 +3,7 @@
 本模块处理已有表单的条件界面行为（`formRule`）和元数据业务规则
 （`bizRule`）。直接执行最小匹配命令；普通修改不创建二次流程、临时规则文件，
 也不追加用户确认步骤。
+`description` 显示在设计器规则列表；专家原始规则使用简短业务语句，领域命令自行生成。
 
 修改已有规则条件/阈值时，读取本目录的 `update.md`。
 
@@ -36,6 +37,21 @@
 已有 `ensure*` 命令及其 `args`；单个意图仍调用原子 writer。该批次不接受 raw `addRule`、
 操作校验、属性、UI 或插件命令。
 
+触发时机是每个规则服务动作的通用属性，不是清空规则特例。已发布的规则服务命令在
+`ensureRuleSet` 对应项的 `args` 中用 `events` 指定新规则的完整时机集合，或用
+`addEvents` 向现有规则追加时机；原子命令分别重复传 `--event` / `--add-event`。
+“创建/新建”是 `ItemAdded`，“值更新”是 `FieldChanged`；“创建后”才是
+`AfterAdded`，“值更新后”才是 `AfterFieldChanged`。`create` / `update`
+也分别表示前两者，不应将“创建”解释为“创建后”。
+不要根据某个示例省略用户要求的时机。已有规则要替换整个集合，需用准确 `ruleId`
+调用 `updateRule`，语义 `ensure*` 不会悄悄删除旧时机。`ensureFieldCalculation`
+与 `ensureConditionalEntryStyle` 不是 RET 服务动作，不接受上述参数。专家
+`addRule` / `updateRule` 的每个已注册 true/false action 也可用语义
+`events` / `addEvents`，由 CLI 统一编译为 `RET`。
+原始动作的 `addEvents` 必须带回读得到的当前 `RET`；未回读时使用领域命令追加。
+`ensureConditionalClientAppearance` 在原有 `--input` 对象内传时机；批量调用则
+把同一个对象放在 `args.request` 中。
+
 
 计算操作符仅为 `add`、`subtract`、`multiply`、`divide`；这些已发布值不需要检查 contract 或源码。
 
@@ -43,6 +59,9 @@
 # 目标 = 左值 × 右值；两个来源变化都会更新目标
 ... ensureFieldCalculation --entity "<用户位置>" --target "<目标>" --left "<左值>" --operator multiply --right "<右值>"
 
+# 目标十进制小时 =（结束 TimeField - 开始 TimeField）/ 3600.0
+... ensureTimeDifferenceCalculation --entity "<用户位置>" --target "<目标>" --start "<开始时间>" --end "<结束时间>"
+
 # 条件成立时锁定/隐藏；命令自动生成反向分支
 ... ensureConditionalFieldState --entity "<用户位置>" --condition-field "<条件字段>" --operator equals --value "<值>" --target "<目标>" --behavior lock
 
@@ -66,6 +85,10 @@
 任一来源为空或为零时，目标金额回到空值呈现，不残留旧金额；不得为此再追加清空规则。用户要求
 不同于该标准行为时，只有已有发布命令能准确表达才继续，否则单独报告。
 
+`ensureTimeDifferenceCalculation` 负责平台 TimeField 的整数秒语义，并固定除以
+`3600.0` 保留小数小时；任一时间为空时清空目标。结果是带符号的同日时间差；结束时间早于
+开始时间若表示次日，必须先解决该业务决定，不能静默加 24 小时。
+
 ## 函数公式
 
 需求中的表达式需要设计器函数（如舍入、文本处理、日期或空值处理）时，读取
@@ -80,6 +103,8 @@
 
 - 同一实体内两个数值字段计算目标数值字段：`ensureFieldCalculation`；命令解析业务字段名并
   负责两个来源字段的更新触发器。
+- 同一实体内两个 TimeField 计算十进制小时：`ensureTimeDifferenceCalculation`；命令负责
+  `3600.0` 换算、两个来源字段触发器及空输入分支。
 - 带业务条件的同实体二元数值计算：`ensureConditionalCalculation`；由命令负责 FormulaAction、
   RET 及条件/操作数字段触发器。
 - 分录数值字段汇总到表头：直接调用
@@ -88,6 +113,7 @@
 - 条件隐藏/显示或锁定/解锁字段：`ensureConditionalFieldState`；只传一次业务条件，
   由命令生成反向动作。"为空/不为空"用 `--operator empty` / `not-empty` 且不传 `--value`。
   同一条件和行为作用于多个字段时重复传 `--target`，命令创建一条包含完整目标集合的规则。
+  新规则的准确触发时机重复传 `--event`；向已有规则追加时机才用 `--add-event`。
   挂载点跟随目标字段所在实体。目标位于分录时，条件字段可以来自该分录或表头。其他跨实体
   组合不预先假定支持，按命令返回的结构化结果处理。
 - 条件设置分录行/单元格样式：`ensureConditionalEntryStyle`，由命令负责
@@ -112,25 +138,56 @@
 - 条件隐藏/显示或锁定/解锁控件：`ensureConditionalControlState`；传准确控件名称/key，
   由命令负责控件身份与反向动作。
 - 同一实体内按条件清空一个或多个字段：`ensureConditionalClearFields`，由命令负责
-  分隔符、RET 与实体作用域。
+  分隔符、RET 与实体作用域。多个目标重复传 `--target`，仍是一条规则；
+  用户指定的“新建”“字段值变化”等时机可直接传给 `--add-event`。
 - 同一实体内按条件把源字段复制到目标字段：`ensureConditionalCopyFieldValue`，由命令负责
-  两组 TakeValueId 映射。
+  两组 TakeValueId 映射。同一条件、触发时机下要复制多组字段时，向同一命令的
+  `--input` 传 `{"conditionField":"...","operator":"...","value":"...","mappings":[{"source":"...","target":"..."}]}`；
+  一条服务包含全部映射行。省略 `branch` 即条件成立时执行；只有要求条件不成立时执行，
+  才传 `"branch":"false"`。要求不成立时不执行任何服务，就保持 `falseActions` 为空。
 - 按条件携带引用实体属性：`ensureConditionalCarryReferenceProperty`；常见的
   “来源引用变化且不为空”场景省略条件参数即可。命令会解析引用实体上的唯一准确属性，
   缺少 `RefProps` 声明时先通过已验证属性闭环补齐，再写携带规则。
+  同一服务带出多个字段时，用其 `--input` 传由 `sourceReference`、
+  `sourceProperty`、`target` 组成的 `mappings` 数组；仅在用户要求时附上共同条件。
+  默认在条件成立时执行；仅要求条件不成立时执行才用 `"branch":"false"`。
+  若引用资料中不存在与用户给定名称或编码唯一匹配的属性，报告命令返回的候选并等待用户指定，
+  不把其他属性（如普通“名称”）当作用户要求的属性。`ensureRuleSet` 在该项 `args` 中传同一数组及分支。
+  已有拆分规则须指定准确 `ruleId`
+  才合并，不能隐式删改无关动作或条件不成立分支。
+  如果需要解析命令的 JSON 输出，只读取 stdout；认证提示在 stderr，不能用 `2>&1`
+  合并后交给 JSON 解析器。
 - 关联单位的数量字段换算：`ensureQuantityConversion`；由命令负责 UnitConvertDTO JSON 与 RET 249。
 - 领域命令未覆盖的高级公式赋值进入下方专家 raw-rule 逃生口；语义命令失败后不得改走此路由。
-- `CallFieldChangeAction` 已阻断：它能序列化和回读，但隔离运行态证明不会触发目标字段事件链。
+- 条件清空需要增加“复制后”时，使用 `ensureConditionalClearFields --add-event AfterCopy`；
+  其他已支持时机可重复传该参数，CLI 合并已有时机并验证保留结果。
+  `ensureRuleSet` 的对应项使用 `addEvents: ["AfterCopy"]`。
+- 按业务条件调用字段值更新服务使用 `ensureConditionalFieldChange`。条件为“不为空”时传
+  `--operator not-empty`，不传值。新规则的准确时机重复传 `--event`，向已有规则追加
+  时机才用 `--add-event`。回执只证明设计态，后续规则链须在目标环境验证。
 - 没有条件的静态显隐或锁定：使用属性/UI 命令，不创建规则。
 
 只有进入下方专家 raw-rule 逃生口并构造动作时读取
 `{ROOT_DIR}/skills/cosmic-meta-modifier/modules/rule/rule-actions.md`；只有条件包含
 不熟悉的专家 raw-rule 语法时读取
 `{ROOT_DIR}/skills/cosmic-meta-knowledge/conventions/rule-expression-syntax.md`。
-两个资源都使用上方完整 `ROOT_DIR` 路径。
+两个资源都使用上方完整 `{ROOT_DIR}` 路径。
 
 只有领域规则命令不能表达请求时，读取 [raw-rule-authoring.md](raw-rule-authoring.md) 中的原始规则边界与执行契约。
 
+
+## 引用带出的准确输入与类型边界
+
+单个映射且默认“来源非空”时直接用完整参数，不先查询人员候选记录或猜 JSON：
+
+```text
+{python} {ROOT_DIR}/skills/cosmic-meta-api/scripts/cosmic_api.py --stdout ensureConditionalCarryReferenceProperty --app-root "<appRoot>" --form-name "<表单>" --source-reference "<引用字段>" --source-property "<引用实体表头属性>" --target "<目标字段>"
+```
+
+多映射的 `--input` 形状为 `{"mappings":[{"sourceReference":"<引用字段>","sourceProperty":"<属性>","target":"<目标>"}]}`，三个选择器均在数组行内。批量未给条件时是 `1 = 1`；需要“来源非空”时指定 `conditionField` 与 `operator: "not-empty"`，不得把两种默认语义混为一谈。
+
+writer 负责发现来源属性及其表头/分录归属。已有 `RefProps` 不证明其值为单值；人员部门分录等来源返回集合，即使叶子类型是 `OrgField`。`CARRY_REFERENCE_COLLECTION_UNSUPPORTED` 在写入前阻断：按根入口的 Java 插件路线实现明确的选择/汇总策略，不重试同一属性、不改用 raw rule、不任意取首行。`listDefaultCandidates` 用于选择记录，不用于发现引用属性。
+
 ## 完成
 
 使用 writer 的独立验证与返回的 `data.appRoot` / `data.formNumber`；验证成功后无需

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/rule/raw-rule-authoring.md

@@ -40,8 +40,10 @@ key；`addRule` 内部解析并校验 `itemId` 与 `mountPoint`。
 `bizRule` 优先使用语义化调用契约：`actionType`、`description`、`expression`、
 `fieldName`、`ret`、`seq`。CLI 会编译为平台 PascalCase 表示，PascalCase 仅作为
 兼容输入。`TakeBaseProAction` 和 `SetEqutionAction` 的 `expression`、`fieldName`
-各写一组语义映射，由 CLI 补齐嵌套的 `TakeValueId` 类型。不要强塞通用 `RET`，
+各写一组或多组逐行对应的语义映射，由 CLI 补齐嵌套的 `TakeValueId` 类型。不要强塞通用 `RET`，
 默认值按动作类型决定。
+条件清空增加触发时机使用 `ensureConditionalClearFields --add-event`，
+由命令合并；不需要原始动作或手算事件位。
 
 ## 执行与验证
 

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/rule/rule-actions.md

@@ -111,7 +111,7 @@ CLI 会编译 `ClientProperty`、`DisplayStyle`、`RowStyle` 值对象，并完
 |------------|------|------|
 | FormulaAction | 同实体公式赋值 | 带条件的二元数值计算使用 `ensureConditionalCalculation`，无条件使用 `ensureFieldCalculation`；常量/函数等高级场景才使用语义输入 `expression: "target = expr"`；生产默认 RET 为 253 |
 | ClearValueAction | 清空字段值 | 普通请求使用 `ensureConditionalClearFields`；存储 `Expression` 为 `field1:field2`，`RET:253` |
-| CallFieldChangeAction | 已阻断 | 设计态可序列化，但运行态不会触发目标字段事件链 |
+| CallFieldChangeAction | 调用单个字段的值更新服务 | `expression` 传目标字段名称或 key；CLI 解析准确 key 并补 RET 773；运行效果需在目标环境验证 |
 
 ### 3.2 高级动作（含 TakeValueId 列表参数）
 
@@ -170,7 +170,7 @@ FormulaAction 的全部字段必须属于挂载实体。聚合函数和点号跨
 }
 ```
 
-`SetEqutionAction` 的 `expression`、`fieldName` 各写一条语义映射：
+`SetEqutionAction` 的 `expression`、`fieldName` 逐行对应；同一服务可配置多组字段映射：
 
 ```json
 {

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/rule/rule-reference.md

@@ -235,7 +235,7 @@ CLI 会生成 `_Type_: "DisplayStyle"`，保持 `id` 为分录字段业务 key
 |-----------|------|---------|
 | `FormulaAction` | 同实体公式赋值 | 带条件二元计算使用 `ensureConditionalCalculation`，无条件使用 `ensureFieldCalculation`；高级语义表达式默认 RET 253 |
 | `ClearValueAction` | 清空字段值 | 普通请求使用 `ensureConditionalClearFields`；平台存储为 `Expression:"field1:field2", RET:253` |
-| `CallFieldChangeAction` | 已阻断 | 可序列化和回读，但隔离运行态正对照证明不会触发目标字段变更事件 |
+| `CallFieldChangeAction` | 调用字段值更新服务 | CLI 校验单个目标并回读设计态；后续规则是否执行需在目标环境验证 |
 
 #### 高级动作（含 TakeValueId 列表参数）
 
@@ -310,10 +310,10 @@ CLI 会生成 `_Type_: "DisplayStyle"`，保持 `id` 为分录字段业务 key
 
 #### 5.3.4 CallFieldChangeAction（触发字段值更新）
 
-当前不可用。元模型与运行类都只声明一个字符串 `Expression`，运行类把它作为
-单个属性名传给 `IDataModel.getProperty()`，不存在分号多字段语法。当前版本使用
-裸字段 key 和 `RET=773` 重新做了业务规则、界面规则双观察器测试，仍未分发目标
-字段的后续规则链，因此 CLI 在平台写入前阻断该动作，不提供可复制的写入示例。
+元模型与运行类都只声明一个字符串 `Expression`，运行类将其当作单个字段属性名；
+不存在分号多字段语法。`addRule` / `updateRule` 接受目标字段名称或 key，CLI 解析
+准确 key、补 `RET=773`，并回读已保存的规则。历史平台版本的双观察器测试未观察到
+后续规则链分发，因此回执会把运行态标记为未验证；实际效果须在目标环境检查。
 ```
 
 ---
@@ -566,4 +566,4 @@ true/falseActions。
 | 5 | FillQtyAction | 数量换算 | 根据单位自动计算目标数量 | FillQtyAction |
 | 6 | CallFieldChangeAction | 调用字段值更新服务 | 触发对应业务规则和界面规则 | CallFieldChangeAction |
 
-> **注意**：`CallFieldChangeAction` 已确认运行态失败并阻断。FormulaAction 受实体作用域约束并拒绝聚合函数；TakeBaseProAction / SetEqutionAction 使用已验证列表结构；FillQtyAction 只通过 `ensureQuantityConversion` 开放。
+> **注意**：`CallFieldChangeAction` 仅验证设计态，既有运行态测试未观察到后续规则链。FormulaAction 受实体作用域约束并拒绝聚合函数；TakeBaseProAction / SetEqutionAction 使用已验证列表结构；FillQtyAction 只通过 `ensureQuantityConversion` 开放。

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/rule/state.md

@@ -1,7 +1,7 @@
 # 启用或停用已有规则
 
 输入是用户的项目目录、应用名称/编码、表单名称，以及规则的业务条件与动作。即使不知道本地
-应用文件夹，这些信息也足够执行。`ROOT_DIR` 使用宿主提供的 Skill package directory。
+应用文件夹，这些信息也足够执行。`{ROOT_DIR}` 使用宿主提供的 Skill package directory。
 `--project-root` 使用用户明确给出的项目目录；未给出时直接使用宿主的 **Working directory**。
 它是绑定位置，不是需要另行查找或检查目录内容才能确定的身份。
 

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/unit/SKILL.md

@@ -25,7 +25,7 @@ description: app-build 内部执行技能，用于查询和管理已经验证的
 listUnits --bizAppId "<appId>"
 resolveUnit --bizAppId "<appId>" --name "<精确一级分组名称>"
 getUnit --bizAppId "<appId>" --unitId "<unitId>"
-addUnit --bizAppId "<appId>" --name "<名称>" [--number "<编码>"] [--description "<描述>"] [--seq <0-999>] [--parentUnitId ...]
+addUnit --app-root "<appRoot>" --name "<名称>" --number "<编码>" [--description "<描述>"] [--seq <1-999>] [--parentUnitId ...]
 updateUnit --bizAppId "<appId>" --unitId "<unitId>" <只传变更字段>
 deleteUnit --bizAppId "<appId>" --unitId "<unitId>"
 ```
@@ -36,8 +36,11 @@ deleteUnit --bizAppId "<appId>" --unitId "<unitId>"
 异常返回 `FUNCTIONAL_GROUP_QUERY_FAILED`。用户需要分组树本身或嵌套父分组时才用
 `listUnits`。唯一命中后才能继续，不得编造有业务意义的父分组或编码。
 
-`addUnit` 只需 `--name`：后端按 `lingee_<小写unitId>` 生成编码，描述缺省为空、
-`seq` 缺省为 0。只有用户明确指定时才传 `--number` / `--description` / `--seq`。
+`addUnit` 从 `appRoot` 解析所选应用身份；显式应用参数必须与绑定一致。平台要求非空分组编码：
+保留需求给出的编码，命名已委托时自行选择技术编码。描述缺省为分组名称；
+无需向用户询问应用 ID 或可选描述。
+一级分组省略 `--seq` 时，CLI 先回读现有一级分组的真实序号并追加下一整数；子分组
+必须显式传同级 `--seq`。所需回读不可用时写前停止，不猜测顺序。
 
 祈使式新增/修改请求已授权所述变更。明确点名精确分组的删除请求视为已经授权；否则
 先展示解析结果并取得确认。禁止级联删除；存在子分组或关联资源时交由用户处理。

package/skills/cosmic-build/skills/cosmic-meta-modifier/modules/verify/usage-guide.md

@@ -30,8 +30,8 @@
 | 项目 | 要求 |
 |------|------|
 | Python | 3.8+ |
-| config.json | 已完成初始化（`server` 下 `user`、`appId`、`appSecret`、`accountId` 均已填写） |
-| 鉴权 | config.json 中的凭据有效，能正常调用苍穹 OpenAPI |
+| `~/.kd/config.json` | 环境已配置（所选环境的 `client_id`、`client_secret`、`accountId` 已填写） |
+| 鉴权 | `~/.kd/config.json` 中的凭据有效，能正常调用苍穹 OpenAPI |
 
 ### 脚本位置
 
@@ -344,7 +344,7 @@ WARN 表示命中了已知缺陷库，是苍穹 API 的限制，不是你的操
 
 ### ERROR 时怎么办
 
-1. **检查鉴权**：token 是否过期，config.json 中凭据是否正确
+1. **检查鉴权**：token 是否过期，`~/.kd/config.json` 中凭据是否正确
 2. **检查网络**：苍穹服务是否可达（`server.baseUrl`）
 3. **重试验证**（最多 2 次）
 4. 仍失败则检查环境配置
@@ -360,7 +360,7 @@ A: 清除设计器缓存或刷新页面。验证工具通过 API 直接读取数
 A: `--artifact`、`--ops`、`--expected` 参数支持文件路径或内联 JSON。如果传文件路径，确保路径正确（相对于当前工作目录的路径，或绝对路径）。
 
 **Q: 报错 `鉴权失败` 或连接超时？**
-A: 检查 `config.json` 中 `server.baseUrl`、`appId`、`appSecret` 是否正确，苍穹服务是否正常运行。
+A: 检查 `~/.kd/config.json` 所选环境的 `url`、`client_id`、`client_secret` 是否正确，苍穹服务是否正常运行。
 
 **Q: `--expected` 参数在 PowerShell 中如何传递 JSON？**
 A: 用单引号包裹，内部双引号不需要转义：

package/skills/cosmic-build/skills/cosmic-meta-modifier/references/list-filter-modification.md

@@ -1,6 +1,9 @@
 # 修改已有表单的列表
 
-`ROOT_DIR` 是 app-build 根入口提供的 **Skill package directory** 绝对路径，必须原样复制。
+`configureList.commonFilters` 配置列表里的过滤列。设计器“通用控件”分类中的“通用过滤”
+是 `FilterGridAp` 表单控件，应使用 `addControls`。
+
+`{ROOT_DIR}` 是 app-build 根入口提供的 **Skill package directory** 绝对路径，必须原样复制。
 禁止根据 profile 根目录、本地化 Base directory、工作目录或本文件路径重新推导。
 
 `configureList` 是**局部更新**：只传用户点名要改的字段和属性。未传的列、字段绑定、

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

@@ -26,8 +26,9 @@ description: app-build 内部的苍穹表单/列表控件、容器、页签、
 | 移动或排序一个已有表头字段、面板或已发布的非分录控件 | `moveFormElement --element ... [--parent ...] [--before ... 或 --after ...]`；同父节点排序省略 parent |
 | 调整分录/明细网格内的字段或列顺序 | `configureEntryGrid --input '{"moves":[{"field":"<字段>","after":"<锚点>"}]}'`；移到锚点前时使用 `before`，未点名分录时省略 `entry` |
 | 新增标题字段组并添加字段 | `addFieldPanel --caption ... [--page <已有页面>]`，再用返回的 panelKey 执行一条 `addField --panel` 批次 |
-| 新增通用控件 | `addControls` |
+| 新增通用控件 | `addControls --input '{"controls":[{"type":"<控件类型>","name":"<显示名称>"}]}'`；未传父容器时由命令解析实时表单根节点 |
 | 为已验证操作添加可见触发按钮 | `addButton --skipOperation` |
+| 追加、修改、删除或排序工具栏/按钮下拉菜单 | `configureDropdownMenu --element "<按钮>" --input '<意图>'`；命令负责原菜单定位与保留，不以清空重建恢复失败 |
 | 新增设计器高级容器 | `addAdvancedContainer` |
 | 修改字段/控件/容器的单项属性 | 属性入口的 `setProperties` |
 | 修改表单背景 | `setFormBackground` |
@@ -45,6 +46,13 @@ description: app-build 内部的苍穹表单/列表控件、容器、页签、
 
 ## 语义边界
 
+- “通用控件”是设计器分类，不是具体控件类型。用户只说分类时先确认要添加哪一种；
+  其中“通用过滤”是 `FilterGridAp` 表单控件，列表过滤条件才走 `configureList`。
+
+- 菜单项的显示名称和说明对应 Title、SubTitle，与绑定操作的名称是不同对象。
+  显示文字修改使用 configureDropdownMenu；菜单项名称能唯一定位所属按钮时可省略
+  --element，否则使用命令返回的按钮候选。
+
 - 用户要求的角色必须对应实时类型。页面是 `TabAp` 下的 `TabPageAp`，标题字段组是
   `FieldsetPanelAp`，Flex 只排列子项。基础移动成功只证明位置，不能证明另一种 UI 角色。
 - `EntryFieldAp` 顺序只属于 `configureEntryGrid`，`moveFormElement` 不接收分录列。直接传递

package/skills/cosmic-build/skills/cosmic-meta-ui/modules/button/SKILL.md

@@ -2,3 +2,6 @@
 
 本旧模块没有独立流程，返回 `../../SKILL.md`。操作的可见触发按钮使用 `addButton`，普通控件
 按钮使用 `addControls`；key、父节点、载荷和回读均由 CLI 契约负责。
+已有按钮的菜单项使用 `configureDropdownMenu`。
+命令负责读取和定位原菜单、合并定向修改，并一次保存和回读验证。菜单 Key 和 ID 是已有设计身份；
+编辑失败不代表可以清空、重建或改名。绑定的操作须有实际业务实现，占位操作不代表需求已交付。

package/skills/cosmic-build/skills/mcp-server/SKILL.md

@@ -0,0 +1,210 @@
+# mcp-server — 管理金蝶 OpenAPI MCP 服务（open_mcp_ext）
+
+## 对话输出规则
+
+本技能继承主技能的全局对话输出规则：
+
+- 默认静默执行；不要向用户逐步复述中间过程（读取配置、解析参数、翻页等）。
+- 按 system prompt `<language-policy>` 中声明的 `response_language` 汇总结果；
+  转述数量、状态与工具名，不要粘贴原始 JSON。
+- 用户确认破坏性操作后直接执行，不要输出「好的」「继续」「收到」等确认性废话。
+
+## 概述
+
+苍穹 OpenAPI 平台提供 **MCP 服务列表**（元数据 `open_mcp_ext`），每条记录把一个
+已发布 API 注册为 AI 可调用的 MCP 工具。本技能通过平台 `devportal/ai-meta/mcpserver`
+接口族（即 `OpenApiMcpServerFormPlugin` / `OpenApiMcpServerListPlugin` 界面背后的
+同一套服务端逻辑）以对话方式驱动该完整生命周期。
+
+适用场景：把 API 注册为 MCP 工具、查询/检索既有 MCP 服务、从 OpenAPI YAML 批量
+导入工具、重新注册失败的服务、下架（unshelve）服务、导出服务用于环境间迁移。
+
+## 端到端流程：单据 → API → MCP 工具
+
+用户说"把单据做成可对话操作的完整流程"时，指的是这条流水线：
+
+1. **单据** —— 用 app-build 主技能交付单据/表单元数据（字段、操作、布局）。
+2. **API** —— openapi-gen 技能为单据操作生成 v2 零码 API（实体服务）。生成的
+   `apiIds` 归档到 `{outputRoot}/{appCode}/archive.json`，按单据编号分组。
+   若第三方应用需要调用这些 API，用 `newApiAuthInThirdApp` 授权
+   （见 `skills/openapi-gen/docs/auth-api.md`，按需冷加载）。
+3. **MCP** —— 本技能：`save --api-type openapi_apilist --api-id <apiId>` 附带
+   AI 工具元数据（说明、领域/模块、条件字段）。平台校验 API 存在且开发商标识
+   匹配，自动构建工具名并把工具注册到 AI 网关。
+
+衔接契约：第 1→2 步传递 `formNumber`（单据编号）；第 2→3 步传递归档的 `apiId`
+（即平台 API 列表中的同一 ID）。openapi-gen 产物的 `apiType` 恒为
+`openapi_apilist`；`open_rest_api` 仅用于手写的 v3 RESTful API。要一次审计某张
+单据的流水线状态，运行 `listByForm --form-number <formNumber>`——单次调用同时
+返回该单据的 API 列表（`apis[]`，含 `id`/`number`/`operation`）与已注册的 MCP
+工具（`items[]`），出现在 `apis[]` 但不在 `items[]` 的 API 即未注册。
+
+**不要**用本技能创建 API 本身——从实体操作生成 v2 零码 API 属于 openapi-gen 技能
+（`skills/openapi-gen/SKILL.md`，按需冷加载）。
+
+## 字段语义（编写指引）
+
+| 字段 | 平台键 | 规则 |
+|---|---|---|
+| 目标API | `apiId` + `apiType` | 必填。`apiType`：`openapi_apilist`（V2 零码 API）或 `open_rest_api`（V3 RESTful）。目标 API 必须已存在且开发商标识与当前环境匹配（否则平台报 `API_ISV_MISMATCH`）。 |
+| 说明 | `description` | 必填；有长度上限（平台报 `DESCRIPTION_TOO_LONG`）。 |
+| 工具名称 | `toolNameNew` | 可选。缺省时服务端自动构建 `云_应用_方法_路径` 形式的名称；重名自动加后缀。 |
+| 操作类型 | `operateType` | 英文枚举：`query`/`create`/`update`/`save`/`delete`/`submit`/`unsubmit`/`audit`/`unaudit`/`enable`/`disable`/`execute`/`invoke`/`action`/`cancel`（传中文显示名如"保存操作"会报 `OPERATE_TYPE_INVALID`）。 |
+| 所属领域/模块 | `domain` / `module` | 实体必填（`x-ai-domain`、`x-ai-module`）。 |
+| 前置条件/后置效果/错误恢复 | `beforeCondition` / `afterCondition` / `errRecovery` | 长文本（`x-ai-preconditions` / `x-ai-postconditions` / `x-ai-error-recovery`）；AI 工具语义字段，每个正式工具都建议填写。 |
+| 是否敏感操作 | — | 由目标 API 派生（delete/unaudit 等），不接受调用方传入。保存敏感 API 的工具时，先向用户明示再确认。 |
+| 自定义参数扩展配置 | `cusParamExtCfg` | 必须是单个 JSON **对象**字符串，如 `{"key": "value"}`（否则 `CUS_PARAM_INVALID`）。 |
+| 服务来源 | `sourceType` | 调用方只读。`custom` = 租户自建；非白名单环境不可修改标品预置服务（`MCP_DEV_DISABLED`）。 |
+
+## 注册状态生命周期
+
+`register_status`（code → 显示名）：`SUCCESS` 已发布 · `FAILED` 失败 · `UNPUBLISH` 待注册 ·
+`UNSHELVES` 下架中 · `UNSHELVESED` 已下架 · `PENDING_UPDATE` 待更新。
+
+- 保存会异步把工具注册到 AI 网关：记录先以 `UNPUBLISH`（待注册）创建，后台
+  注册完成后变为 `SUCCESS`（已发布）——先用 `get` 复核再判断成败。保存响应携带
+  `registerInfo`（`triggered`/`skipped`/`successCount`/`failCount`/`message`）；
+  无真实 AI 网关的环境报 `skipped: true`，但状态机仍照常流转。
+- `resetStatus`（→ `UNPUBLISH`）只接受 **FAILED 或 UNSHELVESED** 的记录。
+- `unshelves`（→ `UNSHELVES`）只接受 **SUCCESS 或 PENDING_UPDATE** 的记录。
+  下架同样是异步的：记录先经 `UNSHELVES`（下架中）再到 `UNSHELVESED`
+  （已下架）——用 `get` 轮询确认。
+- `delete` 仅对 **UNSHELVESED**（已下架）的记录成功：删除已发布或下架中的
+  记录会报 `DELETE_FAIL`（成功0条）——先下架、等状态到已下架再删。
+  `UNSHELVESED` **不是稳定终态**：实测平台后台会把已下架记录重新发布回
+  `SUCCESS`，因此「下架 → 轮询 → 删除」必须作为连续序列在同一执行轮内
+  一气呵成。
+- 锁定态（下架中的 `UNSHELVES`，以及受限环境中的标品预置记录）拒绝编辑，
+  报 `STATUS_LOCKED` / `MCP_DEV_DISABLED`。
+
+## CLI 参考
+
+所有命令经同一脚本执行，输出单条机器可读 JSON 行
+（退出码 0 成功 / 1 平台失败 / 2 CLI 参数错误）：
+
+```
+{python} {ROOT_DIR}/skills/mcp-server/scripts/mcp_cli.py <command> [flags]
+```
+
+| 命令 | 效果 | 关键 flag |
+|---|---|---|
+| `list` | 读 | `--status`, `--source-type`, `--api-type`, `--tool-name`, `--number`, `--api-number`, `--page-index`, `--page-size` |
+| `listByForm` | 读 | `--form-number` |
+| `get` | 读 | `--id` |
+| `save` | 写 | `--id`（缺省为新增）, `--api-type`, `--api-id`, `--description`, `--operate-type`, `--domain`, `--module`, `--before-condition`, `--after-condition`, `--err-recovery`, `--cus-param-ext-cfg`, `--tool-name`, `--source-yaml` |
+| `delete` | 破坏性 | `--ids`, `--confirm` |
+| `importYaml` | 写 | `--file`, `--mode override\|ignore`, `--save-yaml` |
+| `resetStatus` | 破坏性 | `--ids`, `--confirm` |
+| `unshelves` | 破坏性 | `--ids`, `--confirm` |
+| `export` | 读 | `--ids`, `--format dts\|yaml`, `--output` |
+
+首次调用前按主技能的启动器探测约定绑定一次 `{python}`。
+
+HTTP 方法由平台控制器固定：`listByForm` 与 `get` 为 GET（payload 作为 query
+参数传递），其余 7 个命令为 POST + JSON body。对 GET 端点发 POST 会返回 HTTP
+405 `HttpMethod POST is not allowed`——真实路由不匹配（带 TraceId），不是部署缺失。
+
+## 对话流程
+
+### 查找 MCP 服务
+1. 用户明确提到某张单据（"那张单据的 MCP 工具有哪些"）时优先
+   `listByForm --form-number <formNumber>`——单次调用返回该单据的 API 与已注册
+   工具，直接指出哪些 API 尚未注册。
+2. 其余情况按用户给的条件 `list`（状态/来源/工具名）。total > pageSize 时用
+   `--page-index` 翻页。
+3. 需要单条记录的完整字段（条件文本、YAML、网关日志）时运行 `get --id`。
+4. 最多展示 8-10 行，投影成用户语言：工具名、目标 API、状态（显示名）、
+   来源、操作类型。
+
+### 把 API 注册为 MCP 工具
+1. 用户点名某表单操作（如"把在养批次查询注册成 MCP 工具"）时，先解析到
+   已存在的 API——`listByForm --form-number <formNumber>` 列出该单据全部 API
+   及其 `id`；也可向用户确认或查 openapi-gen 归档。需要 `apiType` + `apiId`。
+2. 询问或起草 AI 工具元数据：说明、领域/模块、操作类型、前置条件、后置效果、
+   错误恢复。三个条件字段建议写成模型可读的明确句子——它们是工具被调用时
+   模型看到的语义描述。
+3. 不带 `--id` 执行 `save`（新增）。转述 `registerInfo`：`failCount` > 0 表示
+   工具已保存但未发布成功——上报网关 message，建议 `resetStatus` 后重存或
+   平台侧排查。
+4. 更新时先 `list` 定位记录，再 `save --id <id>` 只传变更字段。
+
+### 从 OpenAPI YAML 批量导入
+1. YAML 必须含 OpenAPI `paths` 节点；每个操作生成一个 MCP 工具。操作级
+   `x-ai-domain` / `x-ai-module` 覆盖默认值。
+2. `--mode`：`override`（默认）覆盖更新已存在的记录；`ignore` 跳过已存在记录。
+   `--save-yaml` 额外把原始 YAML 存入 `source_yaml`。
+3. 汇报拆分结果：`total`、`successCount` / `failCount` / `ignoreCount` 及
+   v2/v3 明细，逐条列出失败路径与原因。
+
+### 重新注册 / 下架 / 删除
+1. `resetStatus` 仅用于 FAILED/UNSHELVESED 记录；`unshelves` 仅用于
+   SUCCESS/PENDING_UPDATE 记录。CLI 返回 `RESET_STATUS_INVALID` /
+   `UNSHELVES_INVALID` 时，重新 `list` 并解释记录的实际状态。
+2. 已发布工具的完整删除序列——三步在**同一执行轮**内连续完成、中间不暂停：
+   `unshelves --confirm` → 每 2–5 秒用 `get` 轮询直到 `UNSHELVESED`（实测
+   15 秒到 1 分钟以上不等）→ 立即 `delete --confirm`。提前删除报
+   `DELETE_FAIL`；步骤间暂停会让平台把记录重新发布回 `SUCCESS`，届时整个
+   序列须从头再来。删除后用 `get` 验证：返回 `bos.orm.read.dataNotExist`
+   即删除成功的证据。
+3. 三者都有 `--confirm` 门禁——缺省时 CLI 直接拒绝。向用户确认记录清单
+   （工具名，不只是 id）后再传。
+
+### 导出 / 环境间迁移
+1. `export --ids … --format dts` 产出平台 DTS 包格式（已实测通过）。
+   `--format yaml` 在当前平台构建上返回成功但 `content` 为空——在平台修复前
+   把 yaml 导出视为不可靠，优先用 `dts`。
+2. 在目标环境执行 `importYaml` 导入的是 OpenAPI YAML 文件（dts 是 DTS 包
+   产物，不是 importYaml 的输入）。
+
+## 错误码（平台侧）
+
+| Code | 含义 / 恢复 |
+|---|---|
+| `PARAM_EMPTY` / `API_ID_EMPTY` | 缺少必填参数。 |
+| `API_TYPE_INVALID` | `apiType` 只能是 `openapi_apilist` 或 `open_rest_api`。 |
+| `API_NOT_FOUND` | 目标 API id 不存在——重新解析 API。 |
+| `API_ISV_MISMATCH` | 目标 API 属于其他开发商标识。 |
+| `API_DUPLICATE` | 已有 MCP 记录绑定了该 API。 |
+| `TOOL_NAME_INVALID` | 显式工具名被拒（格式/长度）。 |
+| `STATUS_LOCKED` | 记录下架中（`UNSHELVES`）——等待完成后再编辑。 |
+| `SOURCE_MISMATCH` | 租户环境修改标品预置记录（或反向）被拒。 |
+| `MCP_COUNT_LIMIT` | 租户 MCP 数量达到 `openapi_mcp_maxCount` 上限。 |
+| `MCP_DEV_DISABLED` | 当前环境未开放 MCP 开发。 |
+| `DESCRIPTION_TOO_LONG` / `CUS_PARAM_INVALID` / `OPERATE_TYPE_INVALID` | 字段级校验——修正输入值。 |
+| `RESET_STATUS_INVALID` / `UNSHELVES_INVALID` | 状态前置条件不满足——用 `list` 复核。 |
+| `DELETE_FAIL` | 删除被拒——通常是记录尚未到 `UNSHELVESED`；先下架再重试。 |
+| `bos.orm.read.dataNotExist` | `get` 查询已删除记录——这是删除成功的验证证据，不是故障。 |
+
+## 环境兼容性
+
+灵基（本技能树）与苍穹平台**独立发版**：灵基先行更新后，可能运行在尚未部署
+`devportal/ai-meta/mcpserver` 接口族的旧苍穹上。CLI 会识别这一情形并返回专用
+错误码 `MCP_API_NOT_DEPLOYED`，而不是裸传输错误：
+
+- **网关 NullPointerException 无 TraceId**（HTTP 400，`TraceId：null`）：API
+  条目已在平台 API 列表登记、但后端控制器缺失——请求未到达业务实例。
+- **404 `Cannot found OpenAPI`**（HTTP 层或 body 级 errorCode 皆算）：该环境
+  根本没有登记本接口族。
+
+触发时，向用户明确说明当前环境尚未携带 MCP 管理 API 族（灵基更新领先于平台），
+并给出手工替代方案：OpenAPI 模块的 MCP 服务界面（元数据 `open_mcp_ext`）覆盖
+同一生命周期。相关但不同的情形：403 该第三方应用…没有此接口访问权限 说明接口族
+**已部署**、只是未授权给所配置的第三方应用——在平台 API 管理列表做「应用授权」
+即可，无需重新部署。
+
+绝不要在接口族缺失时改用零码实体 API 直写 `open_mcp_ext` 表来绕过：注册状态机、
+AI 网关注册、数量管控、敏感操作检查全部在服务端控制器里——直写表会让记录进入
+不一致状态。
+
+## 边界说明
+
+- 其余传输/凭证/网络故障表现为 `PLATFORM_ERROR`，`message` 携带原始原因（网关
+  NPE **带** TraceId 的是真实服务端缺陷而非部署缺失——按缺陷上报，不要误判）。
+  失败 message 由 CLI 截断（剥离 Java 栈、长度硬上限）以保持单条 JSON 机器
+  输出紧凑；TraceId 保留在截断后的部分。
+- 长文本字段经平台多语言表存储，可能在中文中插入空格——写入「各科目」回读为
+  「各科 目」，`module` 值也可能带前导空格。回读比对时应做空白归一化，
+  不要误判为 CLI 数据损坏。
+- `register_status`、`source_type`、`cloud`、`app`、`log_err` 由服务端维护；
+  CLI 没有对应 flag。
+- 平台侧删除不可恢复；用户意图只是"下线"时优先用 `unshelves`。