@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/schema/dropdown-menu.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "app-build://cosmic-meta-api/dropdown-menu.schema.json",
+  "title": "Dropdown menu edit intent",
+  "type": "object",
+  "properties": {
+    "append": {"type": "array", "items": {"$ref": "#/$defs/item"}},
+    "update": {"type": "array", "items": {"$ref": "#/$defs/itemPatch"}},
+    "remove": {"type": "array", "items": {"type": ["string", "object"]}},
+    "order": {"type": "array", "items": {"type": "string"}, "description": "Place these selected items first in this order; all unmentioned items follow in their original relative order."},
+    "moves": {"type": "array", "items": {"$ref": "#/$defs/move"}}
+  },
+  "minProperties": 1,
+  "additionalProperties": false,
+  "$defs": {
+    "item": {
+      "type": "object",
+      "required": ["key"],
+      "properties": {
+        "key": {"type": "string", "minLength": 1, "description": "New key for append; exact existing key or unique title/operation key for update. Existing identity is preserved."},
+        "title": {"type": "string"},
+        "subtitle": {"type": "string"},
+        "operation": {"type": "string"},
+        "background": {"type": "string"},
+        "icon": {"type": "string", "description": "Actual platform ImageKey resource, not an invented icon name"},
+        "switch": {"type": "boolean"},
+        "theme": {"type": "boolean"},
+        "merge": {"type": "boolean"},
+        "lock": {"type": ["string", "array"]},
+        "visible": {"type": ["string", "array"]},
+        "uploadable": {"type": "boolean"},
+        "uploadConfig": {
+          "type": "object",
+          "properties": {
+            "multiple": {"type": "boolean"},
+            "suffix": {"type": "string"},
+            "limitCount": {"type": "integer", "minimum": 0},
+            "limitSize": {"type": "integer", "minimum": 0},
+            "url": {"type": "string"},
+            "accept": {"type": "string", "description": "Alias for suffix"},
+            "maxFiles": {"type": "integer", "minimum": 0, "description": "Alias for limitCount"},
+            "maxFileSize": {"type": "integer", "minimum": 0, "description": "Alias for limitSize, same platform unit"}
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "itemPatch": {
+      "allOf": [{"$ref": "#/$defs/item"}]
+    },
+    "move": {
+      "type": "object",
+      "required": ["key"],
+      "properties": {
+        "key": {"type": "string"},
+        "before": {"type": "string"},
+        "after": {"type": "string"}
+      },
+      "oneOf": [{"required": ["before"]}, {"required": ["after"]}],
+      "additionalProperties": false
+    }
+  },
+  "examples": [{
+    "append": [{"key": "bar_print_pdf", "title": "打印 PDF", "operation": "printpdf", "visible": ["查看", "提交", "审核"]}],
+    "update": [{"key": "bar_print_setting", "subtitle": "打印配置"}],
+    "moves": [{"key": "bar_print_setting", "before": "bar_print_pdf"}]
+  }]
+}

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

@@ -98,8 +98,9 @@
         "displayName": {"type": "string", "minLength": 1},
         "compare": {
           "enum": ["=", "in", "between"],
-          "description": "Selects the filter control shape. 'between' requires a date/datetime value domain."
+          "description": "Query comparison (=, in, between), not an arbitrary control-type selector. The platform source may create DateRangeField for between and TextField otherwise; verify actual deployment output. This input cannot request DateField, MulBaseDataField or ComboListField."
         },
+        "source": {"type": "object", "additionalProperties": false, "required": ["formNumber", "fieldKey"], "properties": {"formNumber": {"$ref": "#/$defs/identifier"}, "fieldKey": {"$ref": "#/$defs/identifier"}}, "description": "Verified source form and field. Uses the ReportFilters.typed platform extension; copies its native editor type, reference, enum and numeric/date options. between on a date creates DateRangeField. Legacy platforms fail closed; no TextField fallback."},
         "defaultValue": {},
         "mustInput": {
           "type": "boolean",

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/schema/rule-set.schema.json

@@ -20,6 +20,7 @@
           "command": {
             "enum": [
               "ensureFieldCalculation",
+              "ensureTimeDifferenceCalculation",
               "ensureConditionalFieldState",
               "ensureConditionalEntryStyle",
               "ensureConditionalControlState",

package/skills/cosmic-build/skills/cosmic-meta-api/contracts/schema/rule-write.schema.json

@@ -9,8 +9,7 @@
     "ruleType",
     "description",
     "preDescription",
-    "preCondition",
-    "trueActions"
+    "preCondition"
   ],
   "properties": {
     "ruleType": {"enum": ["bizRule", "formRule"]},
@@ -23,7 +22,7 @@
     "preCondition": {"type": "string", "minLength": 1, "description": "Use 1=1 only when the requested rule is unconditional."},
     "triggerField": {"type": "string", "description": "Optional Display name(fieldKey) values separated by semicolons."},
     "enabled": {"type": "boolean", "default": true},
-    "trueActions": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/action"}},
+    "trueActions": {"type": "array", "items": {"$ref": "#/$defs/action"}},
     "falseActions": {"type": "array", "items": {"$ref": "#/$defs/action"}}
   },
   "oneOf": [
@@ -31,6 +30,10 @@
     {"required": ["clientMount"]},
     {"required": ["itemId", "mountPoint"]}
   ],
+  "anyOf": [
+    {"required": ["trueActions"], "properties": {"trueActions": {"minItems": 1}}},
+    {"required": ["falseActions"], "properties": {"falseActions": {"minItems": 1}}}
+  ],
   "allOf": [
     {
       "if": {"properties": {"ruleType": {"const": "bizRule"}}},
@@ -87,14 +90,16 @@
       "properties": {
         "actionType": {"enum": ["FormulaAction", "ClearValueAction", "CallFieldChangeAction", "TakeBaseProAction", "SetEqutionAction"], "description": "推荐的语义调用键；CLI 会编译为 ActionType。"},
         "ActionType": {"enum": ["FormulaAction", "ClearValueAction", "CallFieldChangeAction", "TakeBaseProAction", "SetEqutionAction"]},
-        "expression": {"description": "推荐的语义调用键。Formula/Clear/CallFieldChange 使用字符串；TakeBasePro/SetEqution 使用只含一个映射对象的数组。"},
+        "expression": {"description": "推荐的语义调用键。Formula/Clear/CallFieldChange 使用字符串；TakeBasePro/SetEqution 使用一组或多组有序映射对象。"},
         "Expression": {},
-        "fieldName": {"description": "TakeBasePro/SetEqution 单组显示名映射的推荐语义调用键。"},
+        "fieldName": {"description": "TakeBasePro/SetEqution 的显示名映射数组，与 expression 逐行对应。"},
         "FieldName": {},
         "description": {"type": "string"},
         "Description": {"type": "string"},
-        "ret": {"type": "integer", "description": "可选动作事件掩码；CallFieldChangeAction 已按运行态证据阻断，不得编写。"},
+        "ret": {"type": "integer", "description": "可选动作事件掩码；CallFieldChangeAction 默认 773。元数据回读不证明运行态分发。"},
         "RET": {"type": "integer", "description": "可选动作事件掩码的兼容别名。"},
+        "events": {"type": "array", "minItems": 1, "items": {"type": "string"}, "description": "为任一已注册业务服务动作指定完整触发时机，由 CLI 编译为 RET。"},
+        "addEvents": {"type": "array", "minItems": 1, "items": {"type": "string"}, "description": "向显式传入的当前 RET 追加时机；不使用隐式默认值。"},
         "seq": {"type": "integer", "minimum": 1},
         "Seq": {"type": "integer", "minimum": 1}
       },
@@ -120,7 +125,9 @@
         },
         "clientProperties": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/clientProperty"}},
         "rowStyles": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/rowStyle"}},
-        "RET": {"type": "integer", "default": 251}
+        "RET": {"type": "integer", "default": 251},
+        "events": {"type": "array", "minItems": 1, "items": {"type": "string"}, "description": "为任一已注册界面服务动作指定完整触发时机，由 CLI 编译为 RET。"},
+        "addEvents": {"type": "array", "minItems": 1, "items": {"type": "string"}, "description": "向显式传入的当前 RET 追加时机；不使用隐式默认值。"}
       },
       "additionalProperties": true,
       "not": {

package/skills/cosmic-build/skills/cosmic-meta-api/docs/api-summary.md

@@ -346,8 +346,8 @@ PDM 技能访问**两套独立的苍穹环境**，各自独立鉴权：
 
 | 环境 | 说明 | 使用的 API | 凭据配置文件 |
 |------|------|-----------|-------------|
-| **server**（设计期苍穹） | 提供设计期实体元数据 | entityMeta | `scripts/config.json`（经 `_cosmicConfig`） |
-| **datamodel**（数据模型环境） | PDM Diff 对比 + 脚本生成 | modelCode / save / submit | `pdm-automation/config.json` → **`datamodel` 块（五项必填，不继承主 config）** |
+| **server**（设计期苍穹） | 提供设计期实体元数据 | entityMeta | `~/.kd/config.json` 默认环境（经 `kd_env_loader.py`） |
+| **datamodel**（数据模型环境） | PDM Diff 对比 + 脚本生成 | modelCode / save / submit | `~/.kd/config.json` 的 **`pdm` section（留空字段继承默认环境）** |
 
 两套环境均使用相同的 OAuth2 `getToken` 鉴权流程（见 `pdm_client.py`）。
 

package/skills/cosmic-build/skills/cosmic-meta-api/modules/app-action/SKILL.md

@@ -43,15 +43,18 @@ description: app-build 内部执行技能，用于查询、扩展、修改、启
    验证成功后才用扩展应用的 `appCode`、`appId`、`appName`、`cosmicAppName` 替换
    当前 `archive.json` 身份，同步 `context.json`，并使旧 workspace 分组失效。
 4. `updateApp` 只传用户明确要求修改的字段，不得清空或重写未提及属性。
-5. `publishApp` 只把明确的启用/禁用意图映射为 `--action enable|disable`。
+5. `publishApp` 把明确的启用/禁用意图映射为 `--action enable|disable`。用户明确要求发布菜单，
+   也授权在最终菜单树回读通过后启用同一个已验证应用；不授权禁用或操作其他应用。
 6. 明确点名已验证应用的删除请求视为已经授权；否则先展示精确应用并取得确认。平台
    删除后禁止删除本地项目文件。
 7. 只写一次并解析 JSON；进程退出码为零或终端打印“成功”不能证明业务成功。
-8. `extendApp` 只有返回 `identitySynced=true` 且 `verifiedApp` 与扩展应用一致时才算
+8. `publishApp --action enable` 若平台明确回复应用已启用，在写入前准确核对身份后视为无变化；
+   不重复调用。其他失败仍按失败处理。
+9. `extendApp` 只有返回 `identitySynced=true` 且 `verifiedApp` 与扩展应用一致时才算
    完成；禁止再单独调用 `getApp` 或手改 archive/context。其他写入使用 `getApp`
    比较变更字段/状态，或用不存在结果证明删除。回读不可用或结论不明确时返回
    `unknown_after_write`，禁止重试。
-9. 采用 `extendPreCheck` 选出的已有扩展应用时，调用一次
+10. 采用 `extendPreCheck` 选出的已有扩展应用时，调用一次
    `getApp --app-root "<appRoot>" --sync-identity`；同样必须取得
    `identitySynced=true` 后才能继续写表单。
 

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

@@ -47,7 +47,6 @@
 
 ## 如何修改环境配置
 
-所有环境相关参数（服务地址、鉴权凭据、租户信息）统一在 `scripts/config.json` 中维护。  
-修改配置后无需改动任何接口文档或示例代码，示例代码通过引用配置变量保持一致。
+所有环境相关参数（服务地址、鉴权凭据、租户信息）由 `scripts/kd_env_loader.py` 从 `~/.kd/config.json` 中选定的环境解析——平台级配置是唯一来源。禁止在技能目录内创建或编辑明文 `config.json`；配置的变更与恢复一律走 init/reset 入口。工具链写入的密钥以密文（`kdsec:`）存储，绝不明文落盘。
 
 展示用缓存（ISV/业务云信息）在 `RUNTIME_DIR/config.md`，由脚本自动维护，无需手动编辑。

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

@@ -5,12 +5,12 @@ description: app-build 内部执行技能，把已有苍穹表单的 DYM/DYMX
 
 # DYM 元数据同步
 
-仅在 app-build 已初始化已有应用后使用。本模块只负责 `syncDym`；表单 zip 导入导出
+复用调用命令返回的已验证应用绑定。本模块只负责 `syncDym`；表单 zip 导入导出
 属于 `form-action`。
 
-普通 app-build 交付不会在每条修改后调用本模块。`render_output_cards.py` 负责会话边界：全部
-平台写入和读回完成后，只筛选本轮目标中本地已经存在 `.dym` 的表单，并执行唯一一次批量
-`syncDym --existing-only`。本地不存在 DYM 表示有意跳过，不能据此创建新文件。
+普通 app-build 交付不会在每条修改后调用本模块。会话边界的源码同步遵循
+[交付契约](../../../../references/delivery.md)：收口器为本轮表单创建同步请求，
+创建缺失的 DYM/DYMX 文件并更新已有文件。
 
 相对本模块，`cosmic_api` 位于 `../../scripts/cosmic_api.py`。
 
@@ -27,8 +27,7 @@ description: app-build 内部执行技能，把已有苍穹表单的 DYM/DYMX
 {python} {cosmic_api} syncDym --formNumber <formNumber...> --app-root "<appRoot>" --bizAppId "<archive.appId>" [--target "<目录>"]
 ```
 
-app-build 会话收口时追加 `--existing-only`。只有用户明确要求创建或下载元数据时，普通显式导出
-才保持原行为。
+只有用户明确要求仅同步本地已有文件时才传 `--existing-only`，普通 app-build 交付不使用此限制。
 
 机器契约见 `../../contracts/cli/export-sync.json`。`syncDym` 必须把所选应用身份传给
 元数据导出端点。

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

@@ -1,43 +1,20 @@
-# Pre-flight Gate（元数据操作专用，按需触发）
+# 环境初始化与绑定恢复
 
-> **路径推算**：SKILL_DIR = 本文件所在目录（`cosmic-meta-api/modules/init/`）。  
-> KD_CONFIG = `~/.kd/config.json`，是唯一配置真源。  
-> EFFECTIVE_CONFIG 由仓库根 `scripts/kd_env_loader.py` 负责装配：读取 `KD_CONFIG` 下 `default=true` 的环境，将 `url / username / client_id / client_secret / accountId` 映射并解密到运行时 `server.*`；`nonce / timestamp` 在发起 `getToken` 请求时动态生成。  
-> cosmic_api = `SKILL_DIR/../../scripts/cosmic_api.py`。  
-> Python 脚本统一使用 `{python}`（遵循 `[G9.1]`）。
+用户要求初始化环境，或命令明确报告环境配置、应用绑定缺失时使用本入口。
+普通领域命令已经负责鉴权和目标解析，无需先执行通用 Gate。
 
-> **此 Gate 是元数据操作（cosmic-meta-api / cosmic-meta-modeling / cosmic-meta-modifier）的统一入口。**  
-> 其他技能在其 SKILL.md 开头写「Step 0：执行 Pre-flight Gate」即引用本节，**不复制逻辑**。
+环境凭据由 `scripts/kd_env_loader.py` 从 `~/.kd/config.json` 中选定的环境解析。
+按照命令诊断说明缺失配置；普通任务无需检查或重建凭据。
 
-## Gate 流程
+对已明确选定、需要绑定的已有应用，遵循[应用上下文](../../../../references/application-context.md)，
+仅在该流程要求时执行已发布的自举命令：
 
+```text
+{python} {ROOT_DIR}/skills/cosmic-meta-api/scripts/cosmic_api.py --stdout bootstrapWorkspace --app-root "<appRoot>"
 ```
-Step G0：检查本地配置源
-  ├─ ~/.kd/config.json 不存在 → 提示用户先准备 ~/.kd/config.json 默认环境，停止执行
-  └─ 配置存在                → 继续 Step G1
 
-Step G1：一键自举（auth + getDevInfo + workspace 全部就绪）
-  执行：{python} "{cosmic_api}" bootstrapWorkspace --app-root "<appRoot>"
-  该命令内部自动完成：
-    1. auth 鉴权（有缓存则复用）
-    2. getDevInfo 获取 ISV 信息（动态写入 isv/standard 到 workspace）
-    3. 从 archive.json 读取 appCode 写入 workspace
-    4. 写入固定业务云默认值（bizCloudName/bizCloudId）
-    5. 查询应用是否存在，不存在则自动创建
-    6. 查询功能分组，为空则自动创建默认分组
-    7. 写入 workspace 全部 6 字段（appNumber/bizCloudName/isv/standard/bizAppId/bizUnitId）
-  ├─ 成功 → 静默通过，执行用户原始请求
-  └─ 失败（鉴权失败/配置缺失）→ 提示用户检查对应字段
-```
-
-> **不再需要分步调用 auth → getDevInfo → bootstrapWorkspace → addUnit → setConfig。**
-> 单条 bootstrapWorkspace 命令完成全部前置工作。
-
-### ⛔ Gate 硬性规则
+自举验证已有应用并同步运行时上下文，不创建缺失应用。应用目录或缓存 archive 不代表用户选择，
+也不能证明线上应用存在。应用不存在与鉴权失败按不同诊断处理。
 
-1. **任何元数据操作**执行前，必须先通过 Gate，不得跳过。
-2. Gate 通过后，**不向用户输出任何「环境检查通过」类提示**——用户无感。
-3. 失败时**只说缺什么、怎么补**，不暴露内部路径或脚本细节。
-4. `~/.kd/config.json` 是唯一配置真源；不得再引导用户填写 `skills/config.json`。
-5. `setConfig` 在本 Gate 中仅用于写入 `workspace.json` 相关字段；不得再作为 OpenAPI 凭据写入入口。
-6. **G5** 以 `archive.json` + `bootstrapWorkspace` 为唯一主路径；业务云不向用户做开放式收集；`appCode` 不得依赖用户口播，须与 `{appRoot}/archive.json` 或脚本落盘内容一致。
+成功绑定可供后续命令复用。失败遵循根入口的[执行契约](../../../../references/execution-contract.md)；
+环境恢复不隐含创建应用或重置环境的授权。

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

@@ -6,7 +6,7 @@
 
 > 从 SKILL.md 所在路径推算（禁止硬编码任何绝对路径）：
 > - SKILL_DIR = 本文件所在目录（`cosmic-meta-api/modules/pdm/`）
-> - CONFIG = `SKILL_DIR/../../../config.json`（= `skills/config.json`）
+> - CONFIG = `~/.kd/config.json`（平台级配置；`pdm_auto.py` 自行解析，无需传 `--config` 参数，不使用技能目录内的 config.json）
 > - pdm_auto = `SKILL_DIR/scripts/pdm_auto.py`
 > - pdm_client = `SKILL_DIR/scripts/pdm_client.py`
 > - python：统一使用 `{python}`（遵循 `[G9.1]`）
@@ -20,7 +20,7 @@
 ## 前置条件
 
 - 苍穹本地 server 已启动
-- datamodel 环境已配置（config.json 的 `pdm` section）
+- datamodel 环境已配置（`~/.kd/config.json` 的 `pdm` section）
 - 实体已关联应用
 
 ---
@@ -61,7 +61,7 @@
 运行脚本 dry-run 模式，收集所有信息但不修改任何数据：
 
 ```
-{PYTHON} "{SKILL_DIR}/scripts/pdm_auto.py" <entityNumber> --config "{CONFIG}" --dry-run
+{PYTHON} "{SKILL_DIR}/scripts/pdm_auto.py" <entityNumber> --dry-run
 ```
 
 脚本输出摘要 JSON 到 stdout，同时自动将完整 TableAps 存入文件。摘要包含：
@@ -179,7 +179,7 @@ Agent 对比 convertedTableAps 和 currentTableAps，**逐表**按以下格式
 - 修改 → 用户指定修改内容（如“FXXX 长度改 300”），Agent 运行 `--patch` 命令修改文件，根据 patch 输出更新对应行后**重新展示表格，再次等待确认**（循环直到用户说确认）
 
 ```
-{PYTHON} "{SKILL_DIR}/scripts/pdm_auto.py" <entityNumber> --config "{CONFIG}" --patch <tableApsFile> <field> <attr>=<value>
+{PYTHON} "{SKILL_DIR}/scripts/pdm_auto.py" <entityNumber> --patch <tableApsFile> <field> <attr>=<value>
 ```
 - 取消 → 终止
 
@@ -199,7 +199,7 @@ Agent 对比 convertedTableAps 和 currentTableAps，**逐表**按以下格式
 > ❌ 禁止创建辅助脚本。❌ 禁止在上下文中手动构建/修改完整 TableAps JSON。
 
 ```
-{PYTHON} "{SKILL_DIR}/scripts/pdm_auto.py" <entityNumber> --config "{CONFIG}" --apply --model-id <modelId> --table-aps-file <tempFile>
+{PYTHON} "{SKILL_DIR}/scripts/pdm_auto.py" <entityNumber> --apply --model-id <modelId> --table-aps-file <tempFile>
 ```
 
 其中 `<modelId>` 是 Step 3 用户确认的模型 ID，`<tableApsFile>` 是 dry-run 自动保存的文件路径（摘要 JSON 的 `tableApsFile` 字段）。
@@ -258,7 +258,7 @@ Agent 对比 convertedTableAps 和 currentTableAps，**逐表**按以下格式
   2. 使用 `AskUserQuestion`（遵循 [S1-5]-[S1-9]）询问是否强制继续提交，提供 2 个选项：强制继续提交（忽略校验错误）/ 取消
      - 用户选择"强制继续提交" → 加 `--force` 重新运行：
        ```
-       {PYTHON} "{SKILL_DIR}/scripts/pdm_auto.py" <entityNumber> --config "{CONFIG}" --apply --model-id <modelId> --table-aps-file <tempFile> --force
+       {PYTHON} "{SKILL_DIR}/scripts/pdm_auto.py" <entityNumber> --apply --model-id <modelId> --table-aps-file <tempFile> --force
        ```
      - 用户选择"取消" → 终止流程
 - 如果 JSON 不含 `"stopped"` 字段（exit code 0）：save + submit 均成功，进入 Step 6
@@ -332,7 +332,7 @@ python pdm_auto.py <entityNumber> [options]
   entityNumber              实体编码（如 testbill1）
 
 选项:
-  --config, -c CONFIG       配置文件路径（默认：skills/config.json）
+  --config, -c CONFIG       已废弃；运行时统一读取 ~/.kd/config.json
   --dry-run                 信息收集模式，输出摘要 JSON 到 stdout，完整 TableAps 自动存文件
   --output, -o FILE         dry-run 模式额外输出完整 JSON 到文件（可选）
   --apply                   执行模式，需配合 --model-id 和 --table-aps-file
@@ -364,5 +364,4 @@ python pdm_auto.py <entityNumber> [options]
 
 ## 配置
 
-复用 cosmic-meta-api 的共享 config.json，pdm 环境凭据在 `pdm` section 中配置。
-参考配置模板：`scripts/config.json.example`
+PDM 环境凭据位于 `~/.kd/config.json` 的 `pdm` section（平台级配置；`client_secret` 以 `kdsec:` 密文存储）。通过 `setPdmConfig` 命令配置——禁止在技能目录内创建明文配置文件。`pdm` section 字段结构参考 `scripts/config.json.example`。

package/skills/cosmic-build/skills/cosmic-meta-api/modules/pdm/scripts/config.json.example

@@ -1,23 +1,13 @@
 {
-    "_comment": "PDM 自动化配置模板。复制为 skills/config.json 并填入真实值。",
-    "_note": "此文件位于 modules/pdm/scripts/ 仅作参考；pdm_client.py 实际读取的是 skills/config.json（cosmic-meta-api 上一级目录）。",
-
-    "server": {
-        "_comment": "苍穹元数据环境（用于 entityMeta 接口）",
-        "baseUrl": "http://127.0.0.1:8080/ierp",
-        "user": "YOUR_USERNAME",
-        "appId": "YOUR_APP_ID",
-        "appSecret": "YOUR_APP_SECRET",
-        "accountId": "YOUR_ACCOUNT_ID",
-        "tenantId": "YOUR_TENANT_ID"
-    },
+    "_comment": "~/.kd/config.json 中 `pdm` section 的参考结构（平台级配置）。仅供参考——请勿将此文件复制进技能目录。",
+    "_note": "字段值由环境管理或 setPdmConfig 命令维护。client_secret 以 kdsec: 密文存储，绝不明文落盘。留空的字段回退继承默认环境条目。",
 
     "pdm": {
         "_comment": "PDM 数据模型环境（用于 convert / save / submit 等接口）",
         "baseUrl": "http://127.0.0.1:8080/ierp",
-        "user": "YOUR_USERNAME",
-        "appId": "YOUR_APP_ID",
-        "appSecret": "YOUR_APP_SECRET",
+        "username": "YOUR_USERNAME",
+        "client_id": "YOUR_APP_ID",
+        "client_secret": "kdsec:v1:gcm|win:<ciphertext>",
         "accountId": "YOUR_ACCOUNT_ID",
         "tenantId": "YOUR_TENANT_ID",
         "outputDir": "datamodel"

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

@@ -25,7 +25,7 @@
 |------|------|
 | `RUNTIME_DIR/.token_cache.json` | 鉴权 token 缓存 |
 | `RUNTIME_DIR/context.md` | 会话级状态（Token 描述、buildMeta 目标、最近建模结果等） |
-| `RUNTIME_DIR/config.md` | ISV/业务云展示缓存（非 `skills/config.json`） |
+| `RUNTIME_DIR/config.md` | ISV/业务云展示缓存（非 `~/.kd/config.json`） |
 | `RUNTIME_DIR/biz_cache.json` | bizApps 列表缓存 |
 | `RUNTIME_DIR/workspace.json` | 当前选中的应用上下文（appNumber / bizCloudName / bizAppId / bizUnitId / bizUnitName） |
 | `RUNTIME_DIR/ops/` | modifyMeta 临时 ops 文件（自动清理） |
@@ -35,7 +35,7 @@
 > `RUNTIME_DIR` = `{PROJECT_ROOT}/app/_runtime/cosmic-metadata/`  
 > `appCode` 从 `{PROJECT_ROOT}/app/_runtime/context.json.appCode` 读取
 
-**本步不含**：`skills/config.json` 中的 `server.*` / `pdm.*` 凭据字段。
+**本步不含**：`~/.kd/config.json` 中的凭据字段（默认环境 + `pdm` section）。
 
 **询问话术示例**：「是否执行上述缓存与会话重置？请回复 **确认 / 是** 表示同意第一步。」
 
@@ -45,13 +45,13 @@
 
 ## 步骤 B：是否重置「系统凭据」（第二步）
 
-说明涉及字段（均在 `skills/config.json` 中）：
+说明涉及字段（均在 `~/.kd/config.json` 中）：
 
-- **`server.*`**：`baseUrl`、`tenantId`、`accountId`、`appId`、`appSecret`、`user`（**保留** `isv`，仅清空凭据类字段，并将 `_initialized` 置为 false）。
-- **`pdm.*`**：`baseUrl`、`user`、`appId`、`appSecret`、`accountId`（**保留** `outputDir`）。
+- **默认环境（`env.*` 中 `default: true` 的条目）**：`url`、`username`、`client_id`、`client_secret`、`accountId`、`tenantId`（**保留** `isv` 等非凭据字段）。
+- **`pdm` section**：`baseUrl`、`username`、`client_id`、`client_secret`、`accountId`、`tenantId`（**保留** `outputDir`）。
 - `resetEnv --credentials clear` 一次性清空上述两组凭据字段，自动备份整个 config 文件。
 
-**询问话术示例**：「是否还要清空 `skills/config.json` 中的**系统凭据**，便于您重新填写新环境？  
+**询问话术示例**：「是否还要清空 `~/.kd/config.json` 中的**系统凭据**，便于您重新填写新环境？  
 - 回复 **保留凭据** → 只执行第一步缓存重置，不改动 config。  
 - 回复 **清空凭据** → 先自动备份 `*.bak.时间戳`，再清空凭据字段。」
 

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

@@ -1,159 +1,31 @@
-# 使用流程（API 命令参考）
+# API 命令使用
 
-## 读取路径（每次开始时执行）
+本参考用于已选定的 API 命令或 API 故障排查。普通表单修改直接遵循建模、修改或 UI 入口。
 
-> 从 SKILL.md 所在路径推算（禁止硬编码任何绝对路径）：
-> - SKILL_DIR = 本文件所在目录（`cosmic-meta-api/modules/usage/`）
-> - CONFIG = `SKILL_DIR/../../../config.json`（= `skills/config.json`）
-> - cosmic_api = `SKILL_DIR/../../scripts/cosmic_api.py`
-> - artifact_manager = `SKILL_DIR/../../scripts/artifact_manager.py`
-> - RUNTIME_DIR = `{appRoot}/_runtime/cosmic-metadata/`（从 `{PROJECT_ROOT}/app/_runtime/context.json` 读取 `projectRoot`）
-> - artifacts_dir = `{appRoot}/metadata/`
-> - batch_manifests_dir = `{appRoot}/modify/`
-> - python：统一使用 `{python}`（遵循 `[G9.1]`）
+使用根入口提供的 Python 解释器与技能包路径：
 
----
-
-## 方式一：运行 Python 脚本（推荐，无编码问题）
-
-> **优先使用此方式**。脚本自动处理 token 缓存、UTF-8 编码、JSON 序列化，不存在 PowerShell 中文乱码等问题。
-
-```bash
-# 鉴权（token 自动缓存在 RUNTIME_DIR/.token_cache.json，30分钟内复用）
-{python} "{cosmic_api}" auth
-
-# 强制刷新 token
-{python} "{cosmic_api}" auth --force
-
-# 查询业务云/应用（支持按名称过滤）
-{python} "{cosmic_api}" bizApps
-{python} "{cosmic_api}" bizApps --cloud bfyTest1 --app AI
-
-# 一步执行建模（读取 artifact 文件，自动鉴权）
-{python} "{cosmic_api}" run --bizAppId 5M3EVO2FU9EF --bizUnitId 5MJ9YP456GQ9 --template bos_billtpl
+```text
+{python} {ROOT_DIR}/skills/cosmic-meta-api/scripts/cosmic_api.py --stdout <命令> <参数>
 ```
 
-### workspace 自举与手工修正（与 L1 / Pre-flight 对齐）
-
-> **主路径**：`cosmic-meta-modeling` L1 与 `init` 在凭据就绪后，应执行 **`bootstrapWorkspace`**：从 `{appRoot}/archive.json` 读取经平台验证的 `appCode` 及 `bizCloudId`/`bizCloudName`，查询已有应用并写入 `bizAppId`/`bizUnitId`（见 `do_bootstrap_workspace`）。查询不到应用时必须停止，本命令永不创建应用。**不要**以「先问用户业务云、再问应用、再选分组」替代自举。
-> `setConfig` 仅作 **救急/手工纠偏**（如列表选中后写 id，或迁移旧环境）。
-
-```bash
-# 主路径：自举（AI 在 L1/Init 中自动执行，用户一般无需手打）
-{python} "{cosmic_api}" bootstrapWorkspace --app-root "<appRoot>"
-
-# 手工纠偏：仅当确需改 workspace 内字段时；--app-number 须与 {appRoot}/archive.json 的 appCode 一致或先已写回 archive
-{python} "{cosmic_api}" setConfig \
-  --app-number "<与 archive.json.appCode 一致的应用编码>" \
-  --biz-cloud-name "<与 archive.json.bizCloudName 一致的业务云名称>"
-
-# 查询开发商 ISV 信息并回写 isv
-{python} "{cosmic_api}" getDevInfo
-```
-
-| 命令 | 写入字段 | 是否需要鉴权 |
-|------|---------|------------|
-| `bootstrapWorkspace` | `appNumber`（来自 archive）、固定云、`bizAppId`/`bizUnitId` 等 | 是（内部 auth） |
-| `setConfig` | `workspace.json` 的若干键（如 `appNumber` / `bizCloudName` / id） | 否（直接写文件） |
-| `getDevInfo` | `isv`（由 API 返回值自动填入） | 是（需先 auth） |
-
-以上 `{python}` / `{cosmic_api}` 按本文件顶部「读取路径」小节推算，**无需读取 skill_env.json**。
-
-### 本地清理契约（`cleanTemp`）
-
-`cleanTemp` 是本地文件命令，不是平台元数据写入。必须显式传入 `--app-root`，不得从
-shell 当前目录猜测清理目标。
-
-```bash
-{python} "{cosmic_api}" --stdout cleanTemp --app-root "<appRoot>"
-{python} "{cosmic_api}" --stdout cleanTemp --app-root "<appRoot>" --all
-```
-
-- 默认模式只删除 `{appRoot}/_runtime/cosmic-metadata/` 直属的 `input_*.json` 和
-  `output_*.json`。
-- `--all` 删除该目录内容，并且只重建 `ops/`。
-- 两种模式都不得触碰 `_runtime/cli-verify/` 等同级运行目录。
-- 必须在隔离 app root 中用文件系统前后态断言验证；发布和外部运行态页面验证不适用。
-- 未知参数必须返回 `CLI_ARGUMENT_ERROR`，退出码为 2。
-
-### 平台写入的应用身份门禁
-
-每个绑定应用的平台写入都以 `{appRoot}/archive.json` 为权威身份：
-
-- 必须满足 `workspace.appNumber == archive.appCode`。
-- archive 有 `appId` 时，必须满足 `workspace.bizAppId == archive.appId`。
-- 命令携带 `--bizAppId` 或 `--bizAppNumber` 时，也必须与 archive 一致。
-- workspace 即使非空，只要不一致仍是不安全状态。必须在鉴权/写入前以
-  `APP_IDENTITY_MISMATCH` 或 `APP_TARGET_MISMATCH` 失败，执行
-  `bootstrapWorkspace --app-root` 后重新读取并比较。
+命令负责鉴权、令牌缓存、运行时路径和线上目标绑定。参数形状不明确时，在同一 CLI
+调用 `describeCommand <命令>`。较大的 JSON 输入使用 UTF-8 文件。
 
-`addMenu` 的页面目标实际使用**表单编码**。优先使用 `--formNumber`；`--formId` 只是同一
-formNumber 载荷的历史别名，不能传 form UUID。`publishApp` 表示应用 `enable`/`disable`，
-不是通用重新发布；应用已经启用时再次 `enable` 会失败。
+绑定缺失或归属冲突时读取[应用上下文](../../../../references/application-context.md)。
+本地 archive 记录已验证绑定，不证明线上表单是否存在。只有所选流程或恢复回执要求时才调用
+`bootstrapWorkspace`。
 
-**修改配置**：只需编辑 `skills/config.json`（= `SKILL_DIR/../../../config.json`），脚本无需改动。
+命令失败和验证遵循根入口的[执行契约](../../../../references/execution-contract.md)。
+依据回执区分鉴权失败、权限不足、接口未部署及业务对象不存在；修正实际原因后再重试。
+无需在每条命令前另行鉴权或让模型维护重试计数。凭据配置与环境变更使用 init/reset 入口。
 
----
+用户明确要求本地清理时，`cleanTemp --app-root "<appRoot>"` 仅删除契约规定的临时输入输出文件。
+`--all` 会清理该应用的元数据运行时目录，不属于普通交付流程；选择清理范围前读取命令契约。
 
-## 方式二：生成代码参考（查阅文档）
-
-查阅顺序：`RUNTIME_DIR/config.md` → `auth.md` → `apis/*.md` → `examples/python.md`
-
----
-
-## 鉴权失败处理规则（所有依赖本技能的流程均须遵守）
-
-> **鉴权最多尝试 3 次，第 3 次失败后必须立即终止整个流程，不得继续执行任何后续步骤。**
-
-| 次数 | 触发条件 | AI 行为 |
-|------|----------|---------|
-| 第 1 次失败 | `auth` 返回非 0 / token 为空 / HTTP 401 | 自动执行 `{python} "{cosmic_api}" auth --force` 强制刷新 |
-| 第 2 次失败 | 强制刷新后仍失败 | 提示用户检查 `config.json`（密钥/租户/服务地址），等待用户更新后再重试一次 |
-| 第 3 次失败 | 用户确认已更新配置但仍失败 | **立即终止**，输出以下信息并停止，不再执行建模/修改/查询等任何操作 |
-
-**第 3 次失败时的终止输出模板：**
-```
-❌ 鉴权连续失败 3 次，已终止本次流程。
-
-可能原因：
-1. config.json 中 app_id / app_secret / tenant_id 不正确
-2. 苍穹服务未启动或网络不通（base_url 无法访问）
-3. 账号无权限或已被锁定
-
-请检查以上配置后重新发起请求。
-```
-
-> **注意**：  
-> - 每次完整建模/修改流程（含 buildMeta / modifyMeta）内，失败计数从 0 开始重置  
-> - 仅 `auth` 步骤失败计入，接口调用（如 queryForms / buildMeta）返回 401 也按此规则处理
-
----
-
-## context.md 维护规则
-
-- `RUNTIME_DIR/context.md` 仅记录**本次会话**选定的 `bizAppId` / `bizUnitId`（建模目标）和最近一次建模结果
-- `buildMeta` 前先读取 `RUNTIME_DIR/context.md` 中的 `bizAppId` / `bizUnitId`
-- token 缓存由脚本的 `RUNTIME_DIR/.token_cache.json` 负责，`context.md` 作为人类可读记录
-- **ISV 信息 / 业务云列表** 属于持久配置，统一存放在 `RUNTIME_DIR/config.md`，不写入 `context.md`
-- 仅当用户主动说"刷新列表 / 切换业务云"时，才重新调用 `bizApps` 并将结果更新回 `RUNTIME_DIR/config.md`
-- `RUNTIME_DIR` = `{PROJECT_ROOT}/app/_runtime/cosmic-metadata/`
-
----
-
-## API 路径规则
-
-苍穹自定义 API 2.0 的请求路径格式：
-
-```
-{base_url}/ierp/kapi/v2/{ISV}/{appNumber}/{类@ApiMapping}/{方法@ApiGetMapping|@ApiPostMapping}
-```
+`addMenu` 使用表单编码定位页面，其历史别名 `--formId` 也不是表单 UUID。
+`publishApp` 表示启用或停用应用，不是通用重新部署。
 
-| 变量 | 说明 | 来源（`skills/config.json` 字段） |
-|------|------|------|
-| `base_url` | 服务地址 | `server.baseUrl` |
-| `ISV` | 开发商标识 | 顶层 `isv` |
-| `appNumber` | 苍穹应用编码 | `workspace.json` 的 `appNumber` |
-| 类路径 | `@ApiMapping` 的值 | 如 `/ai-meta` |
-| 方法路径 | `@ApiGetMapping` / `@ApiPostMapping` 的值 | 如 `/bizApps` |
+编写 API 集成代码时，仅查阅 `../../apis/` 下相关接口及对应语言示例。配置、URL 和凭据
+由 CLI 配置层负责，普通任务无需重建请求路径。
 
-> ⚠️ `appNumber` 原本硬编码在 `cosmic_api.py` 中，现统一由 `RUNTIME_DIR/workspace.json` 的 `appNumber` 提供；**真实流水线中**该值须与 `{appRoot}/archive.json` 的 `appCode` 由自举/同步保持一致，**不能**在脚本层单独发明应用编码。
+完成已验证修改后，遵循[交付契约](../../../../references/delivery.md)。

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

@@ -6,7 +6,7 @@
 
 > 从 SKILL.md 所在路径推算（禁止硬编码任何绝对路径）：
 > - SKILL_DIR = 本文件所在目录（`cosmic-meta-api/modules/verify/`）
-> - CONFIG = `SKILL_DIR/../../../config.json`（= `skills/config.json`）
+> - CONFIG = `~/.kd/config.json`（平台级配置，由脚本自行解析；无技能目录内的配置文件）
 > - meta_verifier = `SKILL_DIR/../../scripts/meta_verifier.py`
 > - python：统一使用 `{python}`（遵循 `[G9.1]`）