@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/skills/mcp-server/scripts/mcp_cli.py

@@ -0,0 +1,431 @@
+#!/usr/bin/env python3
+"""MCP service management CLI for open_mcp_ext.
+
+调用平台 devportal/ai-meta/mcpserver/* 接口族（9 个端点：listByForm/get 为 GET，
+其余 7 个为 POST），覆盖 MCP 服务列表的对话式全生命周期：查询、按单据查询、
+新增/修改、删除、YAML 批量导入、注册状态重置、下架、导出。
+
+接口契约来源：kd.bos.mcp.McpServerApiController（@ApiController("devportal") +
+@ApiMapping("/ai-meta/mcpserver")）。平台响应为 CustomApiResult 包装
+（{status, errorCode, message, data}），与 kd_api 消费的现有 ai-meta 家族同构。
+
+用法（机器模式统一加 --stdout，输出单条 JSON）:
+  mcp_cli.py list [--status CODE] [--source-type V] [--api-type V] [--tool-name S]
+                  [--number S] [--api-number S] [--page-index N] [--page-size N]
+  mcp_cli.py listByForm --form-number FORMNUMBER
+  mcp_cli.py get --id ID
+  mcp_cli.py save --api-type openapi_apilist|open_rest_api --api-id ID --description D
+                  [--operate-type V] [--domain D] [--module D]
+                  [--before-condition S] [--after-condition S] [--err-recovery S]
+                  [--cus-param-ext-cfg JSON] [--tool-name S] [--source-yaml S]
+  mcp_cli.py save --id ID [--description D] [同上可选字段…]
+  mcp_cli.py delete --ids 1,2,3 --confirm
+  mcp_cli.py importYaml --file PATH [--mode override|ignore] [--save-yaml]
+  mcp_cli.py resetStatus --ids 1,2,3 --confirm
+  mcp_cli.py unshelves --ids 1,2,3 --confirm
+  mcp_cli.py export --ids 1,2,3 --format dts|yaml [--output PATH]
+
+destructive 命令（delete/resetStatus/unshelves）必须显式带 --confirm，缺省时
+拒绝执行并以退出码 2 结束，防脚本误触。
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+
+# 引导到 app-build/scripts，复用 kd_api / kd_env_loader 认证与传输基建
+_ROOT_SCRIPTS = os.path.normpath(
+    os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "..", "scripts")
+)
+if _ROOT_SCRIPTS not in sys.path:
+    sys.path.insert(0, _ROOT_SCRIPTS)
+
+import kd_api  # noqa: E402
+from kd_env_loader import load_effective_skill_config  # noqa: E402
+
+# ─── 平台端点契约 ────────────────────────────────────────────────────────────
+_API_PREFIX = "/kapi/v2/devportal/ai-meta/mcpserver"
+
+ENDPOINTS = {
+    "list": _API_PREFIX + "/list",
+    "listByForm": _API_PREFIX + "/listByForm",
+    "get": _API_PREFIX + "/get",
+    "save": _API_PREFIX + "/save",
+    "delete": _API_PREFIX + "/delete",
+    "importYaml": _API_PREFIX + "/importYaml",
+    "resetStatus": _API_PREFIX + "/resetStatus",
+    "unshelves": _API_PREFIX + "/unshelves",
+    "export": _API_PREFIX + "/export",
+}
+
+# 平台侧只读端点走 GET（query 参数），POST 会命中 HTTP 405 HttpMethod POST is
+# not allowed；写端点仍为 POST + JSON body。GET 分支的 payload 直接作为 query
+# 参数（值需为字符串或可 urlencode 的标量），本 CLI 现有的 formNumber/id 均满足。
+GET_ENDPOINTS = frozenset({"listByForm", "get"})
+
+# McpRegisterStatusEnum 枚举 code（code → 显示名映射见 SKILL.md「注册状态生命周期」）
+REGISTER_STATUS = frozenset({
+    "SUCCESS", "FAILED", "UNPUBLISH", "UNSHELVES", "UNSHELVESED", "PENDING_UPDATE",
+})
+
+# MCP 服务指向的目标 API 实体：V2 零码 API / V3 RESTful API
+API_TYPES = ("openapi_apilist", "open_rest_api")
+
+EXPORT_FORMATS = ("dts", "yaml")
+
+# importYaml mode：override=已存在则覆盖更新（默认）；ignore=已存在则跳过
+IMPORT_MODES = ("override", "ignore")
+
+DESTRUCTIVE_COMMANDS = frozenset({"delete", "resetStatus", "unshelves"})
+
+
+def _load_config():
+    """加载运行时配置并展平成 kd_api 消费的形状。
+
+    load_effective_skill_config 返回 {server, pdm, preview, featureServer}
+    嵌套结构（server.baseUrl 等），而 kd_api 读取顶层 baseUrl/appId/appSecret/
+    accountId/tenantId。测试打桩点。
+    """
+    config = load_effective_skill_config()
+    server = config.get("server") or {}
+    flat = dict(server)
+    flat.update(config.get("pdm") or {})
+    for key in ("baseUrl", "appId", "appSecret", "accountId", "tenantId"):
+        if not flat.get(key):
+            flat[key] = server.get(key)
+    return flat
+
+
+def _ok(data):
+    return {"status": True, "errorCode": None, "message": None, "data": data}
+
+
+def _fail(error_code, message):
+    return {"status": False, "errorCode": error_code, "message": message, "data": None}
+
+
+# 灵基与苍穹发版解耦：目标环境可能未部署 ai-meta/mcpserver 接口族。两类特征归并
+# 为 MCP_API_NOT_DEPLOYED——网关 NPE 无 TraceId（API 条目已登记、后端控制器未部署）
+# 与 404 Cannot found OpenAPI（API 条目未登记）。
+_NOT_DEPLOYED_MESSAGE = (
+    "the devportal/ai-meta/mcpserver API family is not deployed on this "
+    "environment (Lingee and Cosmic release on independent schedules); "
+    "deploy the platform package or operate via the OpenAPI MCP UI"
+)
+
+# 平台失败 message 可携带 TraceId/WebInstance/完整 Java 栈（如 get 命中已删除记录的
+# bos.orm.read.dataNotExist 响应，栈迹数 KB）；栈迹对诊断无价值（TraceId 在其前），
+# 剥离后仍设长度上限，保持单条 JSON 机器输出契约紧凑。
+_STACK_MARKER = "====Stack===="
+_MESSAGE_LIMIT = 500
+
+
+def _sanitize_message(message):
+    text = message or ""
+    stack_at = text.find(_STACK_MARKER)
+    if stack_at != -1:
+        text = text[:stack_at]
+    if len(text) > _MESSAGE_LIMIT:
+        text = text[:_MESSAGE_LIMIT] + "...(truncated)"
+    return text
+
+
+def _read_http_error_body(exc):
+    try:
+        return exc.read()
+    except Exception:
+        return b""
+
+
+def _classify_transport_failure(command, detail):
+    """区分「接口族未部署」与一般传输故障，兼容灵基/苍穹发版解耦场景。
+
+    404 用词边界匹配：真实 TraceId 的十六进制串可能恰好含 "404" 子串
+    （如 a41f404c81fe2eec37），裸子串匹配会把带 TraceId 的真实服务端缺陷
+    误判为未部署、且丢弃 TraceId——必须保持 PLATFORM_ERROR 并保留原样。
+    """
+    if "NullPointerException" in detail and ("TraceId：null" in detail or "TraceId:null" in detail):
+        return "MCP_API_NOT_DEPLOYED", _NOT_DEPLOYED_MESSAGE
+    if re.search(r"\b404\b", detail) or "Cannot found OpenAPI" in detail:
+        return "MCP_API_NOT_DEPLOYED", _NOT_DEPLOYED_MESSAGE
+    return "PLATFORM_ERROR", f"{command} call failed: {detail}"
+
+
+def _call(command, payload, cfg):
+    """按 GET_ENDPOINTS 路由到 kd_api.get/post 并把 CustomApiResult 折叠为 CLI 结果。
+
+    listByForm/get 走 GET（payload 作为 query 参数），其余命令走 POST + JSON body。
+    平台成功时 data 为业务对象；失败时 status=false 且 message 携带原因，
+    继续透传平台 errorCode（如 STATUS_LOCKED / API_NOT_FOUND）。HTTP 层异常
+    折叠为受控错误码（不让 traceback 泄漏到机器输出流）：MCP_API_NOT_DEPLOYED
+    表示环境未部署接口族，其余为 PLATFORM_ERROR。
+    """
+    try:
+        if command in GET_ENDPOINTS:
+            result = kd_api.get(None, ENDPOINTS[command], cfg, params=payload)
+        else:
+            result = kd_api.post(None, ENDPOINTS[command], cfg, payload)
+    except urllib.error.HTTPError as exc:
+        body = _read_http_error_body(exc).decode("utf-8", errors="replace")
+        detail = f"HTTP {exc.code}: {body[:200]}" if body else str(exc)
+        return _fail(*_classify_transport_failure(command, detail))
+    except Exception as exc:  # noqa: BLE001 — transport/token/gateway failures all fold
+        return _fail(*_classify_transport_failure(command, str(exc)))
+    if result.get("status"):
+        return _ok(result.get("data"))
+    if str(result.get("errorCode") or "") == "404":
+        # body 级 404（HTTP 200 + "Cannot found OpenAPI"）：该环境未登记本接口族
+        return _fail("MCP_API_NOT_DEPLOYED", _NOT_DEPLOYED_MESSAGE)
+    return _fail(
+        result.get("errorCode") or "PLATFORM_ERROR",
+        _sanitize_message(result.get("message")) or "platform call failed",
+    )
+
+
+def _parse_ids(raw):
+    """'1,2,3'（或空白分隔）→ [1,2,3]；非法输入抛 ValueError。"""
+    parts = [part for part in raw.replace(" ", ",").split(",") if part]
+    ids = []
+    for part in parts:
+        if not part.isdigit():
+            raise ValueError(f"invalid id value: {part!r} (positive integers expected)")
+        ids.append(int(part))
+    if not ids:
+        raise ValueError("ids must not be empty")
+    return ids
+
+
+def _read_file(path):
+    if not os.path.isfile(path):
+        raise ValueError(f"file not found: {path}")
+    with open(path, "r", encoding="utf-8") as handle:
+        return handle.read()
+
+
+def _parse_json(raw, field):
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"--{field} is not valid JSON: {exc}") from exc
+
+
+def build_list_payload(args):
+    payload = {
+        "pageIndex": args.page_index,
+        "pageSize": args.page_size,
+    }
+    filters = {
+        "registerStatus": args.status,
+        "sourceType": args.source_type,
+        "apiType": args.api_type,
+        "toolName": args.tool_name,
+        "number": args.number,
+        "apiNumber": args.api_number,
+    }
+    for key, value in filters.items():
+        if value:
+            payload[key] = value
+    return payload
+
+
+def build_save_payload(args):
+    payload = {
+        "id": args.id,
+        "apiType": args.api_type,
+        "apiId": args.api_id,
+        "description": args.description,
+        "operateType": args.operate_type,
+        "domain": args.domain,
+        "module": args.module,
+        "beforeCondition": args.before_condition,
+        "afterCondition": args.after_condition,
+        "errRecovery": args.err_recovery,
+        "cusParamExtCfg": args.cus_param_ext_cfg,
+        "toolNameNew": args.tool_name,
+        "sourceYaml": args.source_yaml,
+    }
+    return {key: value for key, value in payload.items() if value is not None}
+
+
+def build_import_payload(args):
+    return {
+        "yamlContent": _read_file(args.file),
+        "fileName": os.path.basename(args.file),
+        "mode": args.mode,
+        "saveYaml": args.save_yaml,
+    }
+
+
+def build_export_payload(args):
+    return {"ids": _parse_ids(args.ids), "format": args.format}
+
+
+def save_export_content(args, data):
+    """导出内容落盘，stdout 只回元数据（content 可能极大，不进 JSON 流）。"""
+    if not data:
+        raise ValueError("export response has no data")
+    output_path = args.output or os.path.abspath(data.get("fileName") or "mcp-export.txt")
+    with open(output_path, "w", encoding="utf-8") as handle:
+        handle.write(data.get("content") or "")
+    return {
+        "format": data.get("format"),
+        "fileName": os.path.basename(output_path),
+        "savedTo": output_path,
+        "count": data.get("count"),
+    }
+
+
+def run_command(args):
+    """分发表。返回 (result_dict, exit_code)。"""
+    command = args.command
+    if command in DESTRUCTIVE_COMMANDS and not args.confirm:
+        return _fail(
+            "CONFIRM_REQUIRED",
+            f"'{command}' is destructive and modifies platform records. "
+            "Re-run with --confirm after the user has explicitly approved.",
+        ), 2
+
+    try:
+        if command == "list":
+            payload = build_list_payload(args)
+        elif command == "listByForm":
+            payload = {"formNumber": args.form_number}
+        elif command == "get":
+            payload = {"id": args.id}
+        elif command == "save":
+            # cusParamExtCfg 必须是 JSON 对象串，客户端先行校验（服务端 CUS_PARAM_INVALID 兜底）
+            if args.cus_param_ext_cfg:
+                parsed = _parse_json(args.cus_param_ext_cfg, "cus-param-ext-cfg")
+                if not isinstance(parsed, dict):
+                    raise ValueError('--cus-param-ext-cfg must be a JSON object, e.g. {"key": "value"}')
+            payload = build_save_payload(args)
+        elif command in ("delete", "resetStatus", "unshelves"):
+            payload = {"ids": _parse_ids(args.ids)}
+        elif command == "importYaml":
+            payload = build_import_payload(args)
+        elif command == "export":
+            payload = build_export_payload(args)
+        else:
+            return _fail("UNKNOWN_COMMAND", f"unknown command: {command}"), 2
+    except (ValueError, OSError) as exc:
+        # OSError 并入：--file 指向存在但无读权限的文件时 _read_file 抛
+        # PermissionError，属参数指向的文件不可读，归 CLI_ARGUMENT_ERROR（exit 2）
+        return _fail("CLI_ARGUMENT_ERROR", str(exc)), 2
+
+    result = _call(command, payload, _load_config())
+    if not result["status"]:
+        return result, 1
+    if command == "export":
+        try:
+            result = _ok(save_export_content(args, result["data"]))
+        except (ValueError, OSError) as exc:
+            return _fail("EXPORT_WRITE_ERROR", str(exc)), 1
+    return result, 0
+
+
+class _JsonArgumentParser(argparse.ArgumentParser):
+    """argparse 层错误（无效枚举/缺参/未知子命令）也输出单条 JSON，对齐 cosmic_api.py 的机器模式契约。"""
+
+    def error(self, message):
+        print(json.dumps(_fail("CLI_ARGUMENT_ERROR", message), ensure_ascii=False))
+        raise SystemExit(2)
+
+
+def build_parser():
+    parser = _JsonArgumentParser(
+        prog="mcp_cli.py",
+        description="Manage Kingdee OpenAPI MCP services (open_mcp_ext) via devportal/ai-meta/mcpserver endpoints.",
+    )
+    parser.add_argument("--stdout", action="store_true", help="machine-readable single-JSON output")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_list = sub.add_parser("list", help="List MCP services with optional filters")
+    p_list.add_argument("--status", choices=sorted(REGISTER_STATUS), help="register status code, e.g. SUCCESS")
+    p_list.add_argument("--source-type", help="source type filter, e.g. custom (tenant-built)")
+    p_list.add_argument("--api-type", choices=list(API_TYPES), help="target API type filter")
+    p_list.add_argument("--tool-name", help="tool name keyword filter")
+    p_list.add_argument("--number", help="MCP record number (billno) filter")
+    p_list.add_argument("--api-number", help="target API number filter")
+    p_list.add_argument("--page-index", type=int, default=1)
+    p_list.add_argument("--page-size", type=int, default=20)
+
+    p_list_by_form = sub.add_parser(
+        "listByForm",
+        help="List APIs and registered MCP tools of one form (end-to-end pipeline query)",
+    )
+    p_list_by_form.add_argument("--form-number", required=True,
+                                help="form number, e.g. kdtest_food")
+
+    p_get = sub.add_parser("get", help="Get one MCP service detail by id")
+    p_get.add_argument("--id", type=int, required=True)
+
+    p_save = sub.add_parser("save", help="Create or update an MCP service (update: pass --id)")
+    p_save.add_argument("--id", type=int, help="record id; omit to create")
+    p_save.add_argument("--api-type", choices=list(API_TYPES), help="target API entity: openapi_apilist (V2) or open_rest_api (V3)")
+    p_save.add_argument("--api-id", type=int, help="target API primary key")
+    p_save.add_argument("--description", help="tool description (required by entity)")
+    p_save.add_argument(
+        "--operate-type",
+        help="operation type enum: query/create/update/save/delete/submit/unsubmit/"
+             "audit/unaudit/enable/disable/execute/invoke/action/cancel",
+    )
+    p_save.add_argument("--domain", help="x-ai-domain")
+    p_save.add_argument("--module", help="x-ai-module")
+    p_save.add_argument("--before-condition", help="x-ai-preconditions text")
+    p_save.add_argument("--after-condition", help="x-ai-postconditions text")
+    p_save.add_argument("--err-recovery", help="x-ai-error-recovery text")
+    p_save.add_argument("--cus-param-ext-cfg", help="custom param extension config, JSON object string")
+    p_save.add_argument("--tool-name", help="explicit tool name; server builds one when omitted")
+    p_save.add_argument("--source-yaml", help="source YAML text")
+
+    for name, help_text in (
+        ("delete", "Delete MCP services by ids"),
+        ("resetStatus", "Reset register status to UNPUBLISH (FAILED/UNSHELVESED only)"),
+        ("unshelves", "Unpublish MCP services (SUCCESS/PENDING_UPDATE only)"),
+    ):
+        p_batch = sub.add_parser(name, help=help_text)
+        p_batch.add_argument("--ids", required=True, help="comma-separated record ids, e.g. 1,2,3")
+        p_batch.add_argument("--confirm", action="store_true", help="required: acknowledge the destructive effect")
+
+    p_import = sub.add_parser("importYaml", help="Batch import MCP services from an OpenAPI YAML file")
+    p_import.add_argument("--file", required=True, help="local OpenAPI YAML file path")
+    p_import.add_argument("--mode", choices=list(IMPORT_MODES), default="override",
+                          help="override: update existing records (default); ignore: skip existing")
+    p_import.add_argument("--save-yaml", action="store_true",
+                          help="store the raw YAML into source_yaml (default off)")
+
+    p_export = sub.add_parser("export", help="Export MCP services as DTS or YAML")
+    p_export.add_argument("--ids", required=True, help="comma-separated record ids")
+    p_export.add_argument("--format", required=True, choices=list(EXPORT_FORMATS))
+    p_export.add_argument("--output", help="output file path (default: server-provided fileName in cwd)")
+
+    return parser
+
+
+def main(argv=None):
+    """Parse argv, run the command, print the single-JSON result. Returns exit code.
+
+    --stdout is accepted for convention parity with cosmic_api.py but output is
+    always a single machine-readable JSON line — this CLI has no human mode.
+    run_command 之外的意外异常（如 _load_config 里 kd_env_loader 的 RuntimeError、
+    磁盘故障等）也折叠为 CLI_EXECUTION_ERROR 单条 JSON（对齐 cosmic_api.py 的
+    _emit_machine_error 兜底），绝不向 stdout 泄漏 traceback。
+    """
+    args = build_parser().parse_args(argv)
+    try:
+        result, exit_code = run_command(args)
+    except Exception as exc:  # noqa: BLE001 — fold into the single-JSON contract
+        result = _fail(
+            "CLI_EXECUTION_ERROR",
+            _sanitize_message(f"{type(exc).__name__}: {exc}") or type(exc).__name__,
+        )
+        exit_code = 1
+    print(json.dumps(result, ensure_ascii=False))
+    return exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/cosmic-build/skills/openapi-gen/SKILL.md

@@ -150,7 +150,7 @@ app-build 进入本技能后，直接根据用户要求和已验证表单身份
 - **bizobject**：实体编码
 - **operations**：要生成的 API 操作（如 save,query,submit）
 - **实体中文名**：用于 API 命名
-- **appid**：从 context.json 或 config.json 获取
+- **appid**：从 context.json 或 `~/.kd/config.json` 获取
 
 ### 进入标准流程
 
@@ -188,7 +188,7 @@ app-build 进入本技能后，直接根据用户要求和已验证表单身份
    - operations（必须）：只使用用户明确要求的操作，如 save,query,submit
      · 若未提供 operations，立即阻断并请求明确 API 操作；不读取计划产物，不回退为"全部生成"
      · appendentryrows / deleteentryrows 还需 --target-entry <分录字段名>
-   - appid（可选）：默认元数据 BizAppNumber → config.json 的 server.appNumber → CLI --appid 覆盖
+   - appid（可选）：默认元数据 BizAppNumber → `~/.kd/config.json` 的 server.appNumber → CLI --appid 覆盖
 
 2. 跑命令（一条搞定，自动获取元数据 → 动态查操作 → 构造 body → 提交 → 归档）：
    python scripts/api/gen_runner.py <bizobject> --operations <ops> [--app-root <appRoot>]
@@ -402,7 +402,7 @@ python scripts/api/gen_runner.py <bizobject> --operations deleteentryrows \
 6. **`resp_from_body` 每次调用必须重新生成 id**，不能跨 API 复用同一份返回参数。
 7. `urlformat` 全局唯一，重复提交时脚本自动降级为更新（upsert 逻辑）。
 8. `apiservicetype` 固定 `"0"`，`version` 固定 `"2"`，`enable` 传 `"1"`。
-9. **APPID 来源**：优先从 getEntityType 接口返回的 `BizAppNumber` 获取，没有则取 config.json 的 `server.appNumber`，也可通过 `--appid` 参数显式覆盖。
+9. **APPID 来源**：优先从 getEntityType 接口返回的 `BizAppNumber` 获取，没有则取 `~/.kd/config.json` 所选环境的 `server.appNumber`，也可通过 `--appid` 参数显式覆盖。
 10. **`paramtype`/`respparamtype` 只能用合法枚举值**（两者共 12 项：`String` / `Long` / `Integer` / `Boolean` / `Decimal` / `Date` / `DateTime` / `Array<String>` / `Array<Long>` / `Array<Integer>` / `Entries` / `Flex`）。`Object` / `Map` / `Array<Map>` 仅在固定返回分录 `respentryentity_s` 中合法，**本 skill 不生成该分录**，故禁止使用。
 11. **下拉列表当文本处理**（ComboProp/MulComboProp/BillStatusProp → `String`，不是 `Entries`）。
 12. **示例值必须是 JSON 字符串**（用双引号包裹），不能是裸值。

package/skills/cosmic-build/skills/openapi-gen/scripts/api/gen_runner.py

@@ -940,7 +940,7 @@ def run(bizobject, appid=None, name_prefix=None, operations=None, configs=None,
     v2 zero-code API batch generation public entry point.
 
     :param bizobject: entity code (required)
-    :param appid: app code; defaults to metadata BizAppNumber first, then config.json server.appNumber
+    :param appid: app code; defaults to metadata BizAppNumber first, then ~/.kd/config.json server.appNumber
     :param name_prefix: API name prefix; defaults to entity display name from metadata
     :param operations: list of operations to generate (e.g. ['save','query']), must be explicitly provided
     :param configs: API config dict or 'k=v,k=v' string, normalized by parse_configs() and merged into body.data
@@ -1076,7 +1076,7 @@ if __name__ == '__main__':
     import argparse
     parser = argparse.ArgumentParser(description='v2 zero-code API batch generation')
     parser.add_argument('bizobject', help='Entity code (required)')
-    parser.add_argument('--appid', default=None, help='App code; defaults to metadata BizAppNumber first, then config.json server.appNumber')
+    parser.add_argument('--appid', default=None, help='App code; defaults to metadata BizAppNumber first, then ~/.kd/config.json server.appNumber')
     parser.add_argument('--prefix', default=None, help='API name prefix; defaults to entity display name from metadata')
     parser.add_argument('--operations', required=True, help='Operations to generate, comma-separated (e.g. save,query,submit). query generates a GET query API')
     parser.add_argument('--config', default=None,

package/skills/cosmic-dev-best-practices/references/bill-dev-convention.md

@@ -33,10 +33,12 @@
 
 - 模板编码：`bos_billorgtpl`（带组织单据，含主业务组织字段）；
 - 实测继承路径（过磅单）：`00305e8b000006ac,ab7efc31000010ac`（`ab7efc31000010ac` = `bos_billorgtpl`）；
-- 主业务组织字段：`org`（OrgField，引用 `bos_org`），必填。
+- 主业务组织字段：`org`（OrgField，引用 `bos_org`）——**模板未设必填，业务单据通常应设必填并指定为主业务组织**。
 
 > ⚠️ 这是统一要求——单据都走 `bos_billorgtpl`，不另选其他模板。
 
+> 📌 **authoring 必须显式写 `templateKey: "bos_billorgtpl"`**：`data_model_emit` 省略时补的是 `bos_billtpl`（**不含 `org`**），不写即违反本条。
+
 ### 1.1 模板自带字段（继承 `bos_billorgtpl` 自动获得，无需开发）
 
 > 依据运行时模板 schema 实测（`getFormSchema bos_billorgtpl`），共 **9 个字段**（无分录——分录由开发单据自行添加）。
@@ -53,6 +55,8 @@
 | 创建时间 | `createtime` | CreateDateField | 否 | 审计字段 |
 | 组织 | `org` | OrgField [引用 `bos_org`] | 否 | 主业务组织（单据业务组织） |
 
+> 📌 模板显示名是「组织」（既有单据多改为「业务组织」）——`uiComposition` 等按名选择时**用 fieldKey `org`**，避免解析不到。
+
 > **⚠️ 组织管控要求**：如果当前单据需要**组织管控**（权限控制、数据隔离），则 `org` 字段**必须录入**，且**必须设置为主业务组织字段**（单据属性中指定主业务组织）——否则权限/数据隔离不生效。
 > 参考：过磅单 `org` 为主组织（OrgField），且单据一般必填组织。
 
@@ -77,9 +81,13 @@
 > 附件面板 + 制单信息面板与基础资料一致（元素标识统一，见 `basedata-dev-...` 共性规范 + layout-control §〇）。
 > **面板可折叠（Collapsible）**：所有新建 FieldsetPanelAp 业务面板默认可折叠——命令与细节见 **layout-control §A**。
 
+> 📌 **`uiComposition` 只排业务 Fieldset**：模板自带的 `attachmentpanel` 与平台补的 `advconap` 会留在原位，最终顺序要补一次 `applyPanelOrder`（**`order` 里带上 `advconap`**，否则"制单信息在最下方"会被顶掉）：
+> `applyPanelOrder --input '{"order":["fs_baseinfo","fs_payinfo","fs_platforminfo","fs_notifyinfo","attachmentpanel","fs_creator","advconap"]}'`
+> 📌 **制单信息面板**须在 `uiComposition` 中显式列出 `creator`/`createtime`/`modifier`/`modifytime`/`auditor`/`auditdate`，否则这些字段不会被移动。
+
 > ⚠️ **无分录单据也躲不开"空分录骨架"**（2026-09-29 实测）：
 > 平台会为**任何 `BillEntity`** 自动补出 `entryentity`（`EntryEntity`，**`table=""` 空表**，含默认字段 `modifierfield`/`modifydatefield`）
-> 与界面层 `advconap`（`AdvConAp → AdvConToolbarAp / AdvConChildPanelAp → EntryAp/entryentity`）。
+> 与界面层 `advconap`（`AdvConAp →（AdvConToolbarAp、AdvConChildPanelAp → EntryAp/entryentity）`）。
 > - **与模板无关**：`bos_billorgtpl` 与 `bos_billtpl` **都会**补；`bos_basetpl` + `BaseEntity` **不会**（两臂对照实验）。
 > - **CLI 既无参数抑制、也无命令删除**：平台请求契约 `buildMeta-direct.json` 里根本没有该字段；200 条命令中 entry 相关只有 `addEntryEntity`（增）。
 > - ⇒ 无分录对象的正确处置：**设计器整块删「高级容器」**（让平台级联带走 `EntryAp`/`entryentity`）。
@@ -98,8 +106,6 @@
 | 必须动作 | **配置该单据的编码规则**（苍穹「编码规则」功能：前缀/日期段/流水号等） |
 | 校验 | 保存/新建时单据编号自动按规则生成；未配置则编号为空或报错 |
 
-> ⚠️ 每个单据都要单独配置自己的编码规则（按单据类型区分），不能共用。
-
 ### 3.2 单据类型、业务日期（一般必加）
 
 | 字段 | fieldKey | 类型 | 说明 |
@@ -110,6 +116,8 @@
 
 > ⚠️ **billtype agent 不创建（2026-08-25 用户确认）**：`BillTypeField` 属系统字段类型（`SYSTEM_FIELD_TYPES` 硬编码，见 field-property §〇·二），authoring/CLI 通道禁止创建（实测 `modifyMeta`/`addField` 报「'BillTypeField' 是系统字段类型，禁止手动创建」，源码 `FieldValidation` 硬校验）——**agent 建模时跳过 billtype**，**开发者设计器手工添加 BillTypeField** + 预置单据类型数据（`T_BAS_BILLTYPE`/编码规则，无 API，§6.0）。agent 在设计文档 §八 待办提醒。
 
+> 📌 **系统字段（`billtype`/`paystatus` 等）交接**：① 后加字段落在面板末尾，需再排位置（`moveFormElement`）；② 依赖它们的批次（锁定/默认值、`StatusItems`、列表列）必须等字段建好后再跑；③ 待办写清 **字段名 + 类型 + 面板与位置锚点 + 状态/候选值**（例：`paystatus`，BillStatusField，基本信息紧跟 `billstatus`，`wait`/`paid`，`DefValue=wait`）。
+
 ### 3.3 审核字段（模板自带，必须锁定）
 
 > `auditor`/`auditdate` **已在模板 `bos_billorgtpl` 中自带**（见 1.1），开发无需再加——只需锁定。
@@ -159,6 +167,7 @@
 
 > ⭐ **状态字段最终形态 = BillStatusField（单据状态）（2026-08-25 用户确认 + khxty 现有单据 dym 实测）**：`closestatus`/`cancelstatus` 的**标准类型是「单据状态」BillStatusField**（带 StatusItems 状态列表、DefValue=A）——khxty 全部开发单据实测一致（`sd_returnapp` 4 个、`sd_conord` 8 个、`sd_executeorder` 5 个、`sd_conpur` 7 个 `<BillStatusField>`）。
 > ⚠️ **agent 不创建状态字段（2026-08-25 用户确认）**：BillStatusField 属系统字段类型，authoring/CLI 通道禁止创建（实测契约校验 `FIELD_TYPE_MANUAL_FORBIDDEN`）——**agent 建模时跳过 closestatus/cancelstatus**，**开发者设计器手工添加 BillStatusField**；配套 closer/closedate/canceler/canceldate 由 agent 建模（UserField/DateTimeField）。
+> 交接要求（位置 / 批次后置 / 待办要素）见 §3.2。
 >
 > ✅ **但「状态列表」（StatusItems）自 app-build 0.0.299 起有 API 通道**（本节旧文写的"StatusItems，无 API"**已过时**）——
 > 即：**字段本身**仍需设计器手工建，但**字段建好之后**其 StatusItems **可读可写**（**均已实证**）：
@@ -266,20 +275,21 @@
 
 ## 七、建模后必做批次（buildMeta 默认缺口，2026-08-27 出口合同重建实测）
 
-> **buildMeta 只建「字段 + 基础布局」**，以下默认缺口必须后续批次补齐（固定五批次流程）：
+> **buildMeta 只建「字段 + 基础布局」**，以下默认缺口必须后续批次补齐（固定批次流程 0~5）：
 
 | 批次 | 内容 | 说明 |
 |---|---|---|
 | **0 补字段** | 设计文档 §四 配套字段（`closer`/`closedate`/`canceler`/`canceldate` 等）buildMeta **不自动建** | 增量用 `decorate_ops(standard=True)` + `do_modify_meta` **脚本直调**（CLI 走 workspace standard 会拼前缀） |
-| **1 字段属性** | F 批次：org 职能+必录、客户/港口使用组织、币种默认 CNY、**汇率 5 项关联（传 UUID）**、单位关联物料、金额关联币种、必录日期缺省当天、金额族/状态族锁定、ViewDetail=false | `setProperties` / `setRefProps` / `setDefValueDesign` |
-| **2 面板布局** | 业务面板（`fs_financeinfo`/`fs_clause`/`fs_creator`）**不自动建**——所有字段初始堆在 `fs_baseinfo`（`runBatch` 的 `uiComposition` 步骤被前序阶段失败中止时尤其如此，见 cosmic-meta-api §9.2） | **优先 `applyFormComposition`**（0.0.299 定型命令：**一次创建多分区并归位字段**，字段用**显示名**，输入 `{sections:[{key,caption,rows:[{fields:[...]}]}]}`；2026-09-29 实测 43 ops 一次成功并独立验证）；面板顺序用 `applyPanelOrder --input '{"order":[...]}'`。⚠️ 旧法 `modifyMeta` 手写 add/move op 属**已弃的低层路径**，仅在前者不覆盖时使用（move op：`target.value=字段key` + `extra.destination=面板key`；面板排序 `destination=contentpanel`+`index`） |
-| **3 状态族锁定** | `billstatus`/`auditor`/`auditdate`/`closer`/`closedate`/`canceler`/`canceldate` form 层全状态锁 | `setProperties {"Lock":"new,edit,view,submit,audit"}`（开发字段报假阴性，**以 getFormSchema formLayout 为准**） |
+| **1 字段属性** | F 批次：org 职能+必录、客户/港口使用组织、币种默认 CNY、**汇率 5 项关联（传 UUID）**、单位关联物料、金额关联币种、必录日期缺省当天、金额族/状态族锁定、ViewDetail=false | `setProperties`（批量与锁定用 `--policy`；`--elementKey/--input` 对 Lock 报 `PROPERTY_READ_ONLY`）/ `setRefProps` / `setDefValueDesign` |
+| **2 面板布局** | 业务面板（`fs_financeinfo`/`fs_clause`/`fs_creator`）**不自动建**——所有字段初始堆在 `fs_baseinfo`（`runBatch` 的 `uiComposition` 步骤被前序阶段失败中止时尤其如此，见 cosmic-meta-api §9.2） | **优先 `applyFormComposition`**（0.0.299 定型命令：**一次创建多分区并归位字段**，字段用**显示名**，输入 `{sections:[{key,caption,rows:[{fields:[...]}]}]}`；2026-09-29 实测 43 ops 一次成功并独立验证）；面板顺序用 `applyPanelOrder --input '{"order":[...]}'`（`advconap` 也要进 `order`，见 §二）。⚠️ 旧法 `modifyMeta` 手写 add/move op 属**已弃的低层路径**，仅在前者不覆盖时使用（move op：`target.value=字段key` + `extra.destination=面板key`；面板排序 `destination=contentpanel`+`index`） |
+| **3 状态族锁定** | `billstatus`/`auditor`/`auditdate`/`closer`/`closedate`/`canceler`/`canceldate` form 层全状态锁 | `setProperties --policy` 的 `{"set":{"Lock":"…"}}`（只走 `--policy`）。⚠️ 写 `submit,audit`（平台默认）时回执必报 `STATIC_FIELD_LOCK_READBACK_MISMATCH`（属确定性假阴性，写入已生效）——以 `formLayout.lock` 为准，不要重试；其它值均 `verified=true` |
 | **4 汇率/汇总** | `exchangerate` FireUpdEvt=true（含绑定 5 字段共 6 处）；SummaryToField 金额三件套（input 写文件裸 JSON 字符串） | `setProperties` / `setSummaryToField` |
+| **5 列表列** | buildMeta 后平台**按全部字段**建列；authoring 的 `listConfiguration` 只补列/设排序，**不裁剪、不排顺序**（实测声明 11 列得 37 列，且仍报 `verified`） | 要"只有这几列"：`modifyMeta remove listcolumn` 删多余列 → `configureList` 按序补列（它只增不删，`order` 是排序不是列序）；列序只能"全删后重建" |
 
 > **配套铁律**：
 > - buildMeta 后 formId 以 `discover`/`queryForms` **实时解析为准**（runBatch 响应 formId 不可信，moveForm 报 `FORM_NOT_FOUND`）；
 > - 字段类型契约：**无 `BooleanField`**（布尔用 `CheckBoxField`）；QtyField 必须 `unitFieldRef` 关联单位（见 cosmic-meta-api §8.1）；
-> - 完整流程顺序：buildMeta → moveForm（归属功能分组）→ 批次 0~4 → getFormSchema 回读验证。
+> - 完整流程顺序：authoring（显式 `templateKey`）→ runBatch（`bizUnitName` 在初始批次完成分组）→ 批次 0~5 → `getFormSchema` 回读验证。
 
 ---
 

package/skills/cosmic-dev-best-practices/references/cosmic-meta-api.md

@@ -53,7 +53,7 @@
 
 | 想做什么 | 标准写法 | 易错点 |
 |---|---|---|
-| 字段锁定 | `setProperties {"Lock":"new,edit,view,submit,audit"}`，**form 层（FieldAp）**（§2.1） | entity 层设置返回 success 但**不生效**；验证用 getFormSchema 读 formLayout 的 lock |
+| 字段锁定 | `setProperties --policy`：`{"targets":{"fields":[...],"entities":["header"]},"set":{"Lock":"new,edit,submit,audit"}}`，**form 层（FieldAp）**（§2.1） | entity 层不生效；校验以 getFormSchema 的 formLayout.lock 为准 |
 | 列表列隐藏 | `modifyMeta` remove listcolumn `listcol_<fieldKey>`（§3.2） | `modify path=visible` 报「修改执行失败: null」不生效——用 remove 代替 |
 | 默认值 | `setProperties {"DefValue":"A"}` 或 `setDefValueDesign` | — |
 | 用户字段「查看详情」 | `setProperties {"ViewDetail": false}` | 制单信息面板用户字段默认关闭 |
@@ -74,27 +74,30 @@
 ### 2.1 setProperties（简单属性，最常用）
 
 ```bash
+# 单元素（非 Lock 的简单属性）
 python cosmic_api.py setProperties --app-root <appRoot> --formNumber <表单> --elementKey <字段> --input <文件或JSON>
+# 批量 / 字段锁定（Lock 只认这条路径）
+python cosmic_api.py setProperties --app-root <appRoot> --form-name <表单> --policy <policy.json>
 ```
 
 **适用**：简单属性（editorType ≠ btnedit）——`Lock`、`DefValue`、`ViewDetail`、`FieldName`、`BackColor`、`Collapsible`、`Grow`/`Shrink` 等。
 
 **⚡ 关键坑（必读）**：
-1. **`--input` 传属性映射本身**（`{"Lock": "new,edit,view,submit,audit"}`），**不要**包外层 `{"properties": {...}}`——包外层会报 `META_SAVE_FAIL`（本次实战踩过）；
-2. **字段锁定必须设置 form 层（FieldAp）才生效**：entity 层设置返回 success 但**不生效**（auditor 等开发字段 entity lock 仍为 null）——页面不可编辑依赖 form 层控件锁定；
-3. 设置后用 `getProperties` 回读验证（`setProperty` 单属性快捷命令也可）。
+1. **`--input`（旧路径）传属性映射本身**（`{"Lock": "..."}`），**不要**包外层 `{"properties": {...}}`——包外层会报 `META_SAVE_FAIL`（本次实战踩过）。⚠️ **2026-10-19 复验：`--elementKey/--input` 对 `Lock` 已完全不可用**——业务字段与**模板字段都**恒报 `PROPERTY_READ_ONLY`；Lock 一律走 `--policy`，该条只对其它简单属性与旧版本有效；
+2. **字段锁定必须设置 form 层（FieldAp）才生效**：entity 层不生效（`getProperties` 读 entity 层恒为 null，正常）——页面不可编辑依赖 form 层控件锁定；
+3. 设置后按下方「锁定（Lock）验证方法」回读：**Lock 用 `getFormSchema`**，其它属性用 `getProperties`。
 4. **⚠️ 必填 `--app-root`（2026-08-25 实测）**：`setProperties`/`setComplexProperty` 缺 `--app-root` 报 `FORM_TARGET_UNVERIFIED: ... requires --app-root to prove form ownership`——所有写操作命令统一带 `--app-root <appRoot>`（modifyMeta 四参同款）。
 
-**⚡ 锁定（Lock）验证方法（2026-08-25 实测修正）**：
-- `setProperties {"Lock": ...}` 返回 success **不代表 entity 层已生效**——`getProperties --propertyNames Lock` 回读 entity 层 lock **仍为 null**（正常，entity 层本就不存）；
-- **正确验证 = `getFormSchema` 读 formLayout 中对应 FieldAp 控件的 `lock` 字段**（如 `"lock": "new,edit,view,submit,audit"`）——form 层生效的唯一判据；
-- 切勿因 `getProperties` 读到 null 就误判失败重试（会做无用功）；
-- ⚠️ **CLI 自身报错也是假阴性（2026-08-25 实测）**：`setProperties --elementKey <字段> --input '{"Lock":"..."}'` 对**业务/金额字段**会返回 `属性目标状态未满足，独立回读与请求值不一致`（其 verified 变体用 entity 层回读判败）——但 form 层 lock **实际已生效**。**以 formLayout 为准，勿因该报错重试**（仅模板自带字段如 billstatus/creator 的 entity 层有 lock，会返回 success）。
+**⚡ 锁定（Lock）验证方法（2026-10-19 复验，覆盖旧结论）**：
+- **写入只走 `setProperties --policy`**：`--elementKey/--input` 对 Lock 恒报 `PROPERTY_READ_ONLY`（模板字段同样被拒）；
+- **取值**：`new`/`edit`/`submit`/`audit`，顺序无关（CLI 会归一）；
+- **验证 = `getFormSchema` 读 formLayout 中对应 FieldAp 的 `lock`**——form 层生效的唯一判据（`getProperties` 读 entity 层恒为 null 属正常）；
+- ⚠️ **唯一需要特别注意的回执：请求值恰为 `submit,audit`**（= 平台默认锁定，新字段初始值）时，写入**已生效**，但回执**必报** `STATIC_FIELD_LOCK_READBACK_MISMATCH` / `outcome=unknown_after_write` / `actual:{"<字段>":""}`——因为平台元数据**省略"等于默认值"的 Lock 属性**，CLI 回读为空。**这是确定性假阴性，不要重试**，按 formLayout 复核即可；其它任意取值回执均 `verified=true`。
 
 **示例（字段锁定，全状态）**：
 ```bash
-# input: {"Lock": "new,edit,view,submit,audit"}
-python cosmic_api.py setProperties --app-root <appRoot> --formNumber sd_harbor --elementKey auditor --input lock.json
+# policy: {"targets":{"fields":["auditor","auditdate"],"entities":["header"]},"set":{"Lock":"new,edit,submit,audit"}}
+python cosmic_api.py setProperties --app-root <appRoot> --form-name sd_harbor --policy lock.json
 ```
 
 ### 2.2 setComplexProperty（复合/复杂属性）

package/skills/cosmic-dev-best-practices/references/design-examples/basedata-design-example.md

@@ -63,7 +63,7 @@
 | 禁用人 | `disabler` | UserField [引用 `bos_user`] | 否 | 禁用后记录（框架自动写入） |
 | 禁用时间 | `disabledate` | DateTimeField | 否 | 禁用后记录（框架自动写入） |
 
-> 🔒 **锁定约束**：上述 4 个字段 + 制单信息面板的创建/修改字段（`creator`/`createtime`/`modifier`/`modifytime`）共 8 个，在**页面（form 层）锁定为 `new,edit,view,submit,audit`（全状态不可编辑）**——由框架自动写入，用户不可手改（属性按字段属性规范 **F.17** 用户字段 / **F.16** 长日期 / **F.18** 创建修改人套用；参考 `sd_agent` 同名字段配置）。
+> 🔒 **锁定约束**：上述 4 个字段 + 制单信息面板的创建/修改字段（`creator`/`createtime`/`modifier`/`modifytime`）共 8 个，在**页面（form 层）锁定为 `new,edit,submit,audit`（全状态不可编辑）**——由框架自动写入，用户不可手改（属性按字段属性规范 **F.17** 用户字段 / **F.16** 长日期 / **F.18** 创建修改人套用；参考 `sd_agent` 同名字段配置）。
 
 ---