dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-misc/scripts/yida_report_update.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""
+宜搭报表 schema 生成/修改（编排：get-schema → apply chart changes → update-schema）
+
+用法:
+    python yida_report_update.py --app APP_X --form REPORT-XXX \\
+        --changes-file changes.json --corp-id <corpId> --yes
+
+changes.json 格式（非空数组，≤ 20 条）：
+
+    [
+      {"action": "add", "chart": {"type": "bar", "title": "新图", ...}, "after": "现有图标题"},
+      {"action": "remove", "title": "废弃图表"},
+      {"action": "replace", "title": "旧图", "chart": {"type": "line", ...}},
+      {"action": "update-props", "title": "总览", "props": {"isHeightAuto": true}}
+    ]
+
+action: add / remove / replace / update-props
+
+chart 对象格式、字段对象格式、数据绑定模型、布局系统、常见陷阱等完整规范，
+请参考同目录下的参考文档：references/yida-report-builder.md
+
+构建 chart 前必须先获取源表字段：
+    dws yida form components --app <appType> --form <源表formUuid>
+
+新建场景：CLI 先 `dws yida design form create --form-type report` 拿到 formUuid，
+再调本脚本传全 add 的 changes → 自动走全量构建；即使空报表 schema 暂无
+RootContent，也会自动生成完整报表骨架。
+
+更新场景：传含 add/remove/replace/update-props 的 changes → 增量修改既有 schema。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+_SCRIPT_DIR = Path(__file__).resolve().parent
+if str(_SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPT_DIR))
+
+from yida_report_builder import (  # noqa: E402
+    apply_chart_changes_to_schema,
+    build_report_schema_with_filters,
+    count_report_children,
+)
+
+MAX_CHANGES = 20
+MAX_FILE_SIZE = 512 * 1024
+MAX_INLINE_JSON = 64 * 1024
+
+
+def _resolve_safe_path(path_str: str) -> Path:
+    allowed_root = os.environ.get("OPENCLAW_WORKSPACE", os.getcwd())
+    allowed_root_p = Path(allowed_root).resolve()
+    target = Path(path_str).resolve() if Path(path_str).is_absolute() else (Path.cwd() / path_str).resolve()
+    try:
+        target.relative_to(allowed_root_p)
+    except ValueError:
+        raise ValueError(f"路径超出允许范围：{path_str}\n允许根目录：{allowed_root_p}")
+    return target
+
+
+def _run_dws(args: list[str], dry_run: bool = False) -> Any | None:
+    cmd = ["dws"] + args
+    if dry_run:
+        print(f"  [dry-run] {' '.join(cmd)}")
+        return {"dry_run": True}
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+    except FileNotFoundError:
+        print("  ✗ 找不到 'dws' 命令", file=sys.stderr)
+        return None
+    except subprocess.TimeoutExpired:
+        print("  ✗ dws 超时", file=sys.stderr)
+        return None
+    if result.returncode != 0:
+        err = result.stderr.strip() or result.stdout.strip()
+        print(f"  ✗ dws 失败 (exit {result.returncode}): {err}", file=sys.stderr)
+        return None
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as e:
+        print(f"  ✗ 非 JSON: {e}\n  输出: {result.stdout[:300]}", file=sys.stderr)
+        return None
+
+
+def _extract_payload(data: Any) -> Any:
+    """Unwrap common dws JSON envelopes and parse JSON-string payloads."""
+    current = data
+    for _ in range(3):
+        if isinstance(current, dict):
+            for key in ("content", "result", "data"):
+                if key in current and current[key] not in (None, ""):
+                    current = current[key]
+                    break
+            else:
+                break
+            continue
+        break
+
+    if isinstance(current, str):
+        stripped = current.strip()
+        if stripped.startswith(("{", "[")):
+            try:
+                return json.loads(stripped)
+            except json.JSONDecodeError:
+                return current
+    return current
+
+
+def _extract_title(info: Any) -> str:
+    payload = _extract_payload(info)
+    if isinstance(payload, dict):
+        title = payload.get("title") or payload.get("name") or ""
+        if isinstance(title, dict):
+            return str(title.get("zh_CN") or title.get("en_US") or "报表")
+        if title:
+            return str(title)
+    return "报表"
+
+
+def _load_changes(args: argparse.Namespace) -> list[dict]:
+    if args.changes_file:
+        safe = _resolve_safe_path(args.changes_file)
+        if not safe.exists():
+            raise ValueError(f"文件不存在: {safe}")
+        if safe.stat().st_size > MAX_FILE_SIZE:
+            raise ValueError(f"文件过大 (限制 {MAX_FILE_SIZE:,} 字节)")
+        with safe.open("r", encoding="utf-8") as f:
+            changes = json.load(f)
+    elif args.changes_json:
+        if len(args.changes_json.encode("utf-8")) > MAX_INLINE_JSON:
+            raise ValueError("--changes-json 过长")
+        changes = json.loads(args.changes_json)
+    else:
+        raise ValueError("必须提供 --changes-file 或 --changes-json")
+
+    if not isinstance(changes, list) or not changes:
+        raise ValueError("changes 必须是非空数组")
+    if len(changes) > MAX_CHANGES:
+        raise ValueError(f"changes 过多 ({len(changes)} > {MAX_CHANGES})")
+    valid_actions = {"add", "remove", "replace", "update-props"}
+    for i, c in enumerate(changes):
+        if c.get("action") not in valid_actions:
+            raise ValueError(f"change #{i+1} action 无效: {c.get('action')}")
+    return changes
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="宜搭报表 schema 生成/修改",
+                                 formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__)
+    ap.add_argument("--app", required=True, help="应用编码 appType")
+    ap.add_argument("--form", required=True, help="报表 formUuid")
+    ap.add_argument("--changes-file", help="变更定义 JSON 文件路径")
+    ap.add_argument("--changes-json", help="变更定义 JSON 内联")
+    ap.add_argument("--corp-id", default="", help="企业 ID")
+    ap.add_argument("--yes", action="store_true", help="确认写入")
+    ap.add_argument("--dry-run", action="store_true", help="只生成不写入")
+    ap.add_argument("--force-rebuild", action="store_true", help="强制全量重建（丢弃已有图表）")
+    args = ap.parse_args()
+
+    try:
+        changes = _load_changes(args)
+    except ValueError as e:
+        print(f"错误: {e}", file=sys.stderr)
+        return 1
+
+    # Step 1
+    print("Step 1/3: 获取现有 schema")
+    resp = _run_dws(["yida", "design", "form", "get-schema", "--app", args.app,
+                     "--form", args.form, "--format", "json"], dry_run=args.dry_run)
+    if args.dry_run:
+        print(json.dumps({"ok": True, "dry_run": True, "changeCount": len(changes)}, ensure_ascii=False))
+        return 0
+    if not resp:
+        return 1
+    schema = _extract_payload(resp)
+    if not isinstance(schema, dict):
+        print("错误: get-schema 返回内容不是对象，无法生成报表 schema", file=sys.stderr)
+        return 1
+    print("  ✓ 拿到 schema")
+
+    # Step 2
+    all_add = all(c.get("action") == "add" for c in changes)
+    child_count = count_report_children(schema)
+
+    do_full_build = False
+    if child_count < 0:
+        if all_add:
+            if args.force_rebuild:
+                print("  ⚠ schema 结构异常（找不到 RootContent），--force-rebuild 强制全量重建")
+            else:
+                print("  ⚠ schema 结构异常（找不到 RootContent）+ 全 add → 自动全量构建")
+            do_full_build = True
+        else:
+            print("错误: schema 结构异常，找不到 RootContent，无法安全操作", file=sys.stderr)
+            print("  提示: 若这是新建空报表，请传全 add；若是已有报表，请先确认 schema 是否完整", file=sys.stderr)
+            return 1
+    elif child_count == 0 and all_add:
+        print("  ⚠ 空骨架 + 全 add → 全量构建")
+        do_full_build = True
+    elif args.force_rebuild and all_add:
+        print(f"  ⚠ --force-rebuild: 强制全量重建（丢弃已有 {child_count} 个组件）")
+        do_full_build = True
+
+    try:
+        if do_full_build:
+            if not all_add:
+                print("错误: 全量构建只支持全 add 操作", file=sys.stderr)
+                return 1
+            info = _run_dws(["yida", "design", "form", "get-info", "--app", args.app,
+                             "--form", args.form, "--format", "json"])
+            title = _extract_title(info)
+            charts = [c["chart"] for c in changes]
+            schema = build_report_schema_with_filters(report_title=title, charts=charts,
+                                                      report_id=args.form, corp_id=args.corp_id)
+        else:
+            print(f"Step 2/3: 应用 {len(changes)} 条变更（已有 {child_count} 个组件）")
+            schema = apply_chart_changes_to_schema(schema, changes, cube_tenant_id=args.corp_id)
+    except ValueError as e:
+        print(f"错误: {e}", file=sys.stderr)
+        return 1
+    print("  ✓ 变更完成")
+
+    # Step 3
+    schema_json = json.dumps(schema, ensure_ascii=False, separators=(",", ":"))
+    print(f"Step 3/3: 写入 schema ({len(schema_json):,} 字节)")
+    resp = _run_dws(["yida", "design", "form", "update-schema", "--app", args.app,
+                     "--form", args.form, "--form-type", "report",
+                     "--content", schema_json, "--yes", "--format", "json"])
+    if not resp:
+        return 1
+    print("  ✓ 写入成功")
+    print(json.dumps({"ok": True, "formUuid": args.form, "changeCount": len(changes)}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/dws/dingtalk-misc/scripts/yida_schema_common.py

@@ -0,0 +1,340 @@
+"""
+宜搭 schema 公共工具模块
+
+提供 form / report / custom-page 三类 builder 共用的基础函数：
+  - next_node_id / generate_field_id — ID 生成
+  - i18n / build_yida_i18n — 国际化包装
+  - build_option_data_source — 选项 dataSource 构造 + 语义色彩
+  - build_components_map — componentsMap 构造
+  - FIELD_TYPE_ALIAS — 字段类型别名映射
+"""
+from __future__ import annotations
+
+import random
+import string
+import time
+from typing import Any, Optional
+
+# ---------------------------------------------------------------------------
+# 常量
+# ---------------------------------------------------------------------------
+
+COMPONENT_PACKAGE = "@ali/vc-deep-yida"
+COMPONENT_VERSION = "1.5.169"
+
+REPORT_COMPONENT_PACKAGE = "@/components/vc-yida-report"
+REPORT_COMPONENT_VERSION = "1.0.6"
+
+UTILS_LEGAO_BUILTIN = {
+    "name": "legaoBuiltin",
+    "type": "npm",
+    "content": {
+        "package": "@ali/vu-legao-builtin",
+        "version": "3.0.0",
+        "exportName": "legaoBuiltin",
+    },
+}
+
+UTILS_YIDA_PLUGIN = {
+    "name": "yidaPlugin",
+    "type": "npm",
+    "content": {
+        "package": "@ali/vu-yida-plugin",
+        "version": "1.0.13",
+        "exportName": "yidaPlugin",
+    },
+}
+
+# 字段类型别名 → 标准 componentName
+FIELD_TYPE_ALIAS: dict[str, str] = {
+    "text": "TextField",
+    "textfield": "TextField",
+    "textarea": "TextareaField",
+    "textareafield": "TextareaField",
+    "number": "NumberField",
+    "numberfield": "NumberField",
+    "rate": "RateField",
+    "ratefield": "RateField",
+    "date": "DateField",
+    "datefield": "DateField",
+    "cascadedate": "CascadeDateField",
+    "cascadedatefield": "CascadeDateField",
+    "daterange": "CascadeDateField",
+    "radio": "RadioField",
+    "radiofield": "RadioField",
+    "select": "SelectField",
+    "selectfield": "SelectField",
+    "checkbox": "CheckboxField",
+    "checkboxfield": "CheckboxField",
+    "multiselect": "MultiSelectField",
+    "multiselectfield": "MultiSelectField",
+    "country": "CountrySelectField",
+    "countryselectfield": "CountrySelectField",
+    "address": "AddressField",
+    "addressfield": "AddressField",
+    "attachment": "AttachmentField",
+    "attachmentfield": "AttachmentField",
+    "image": "ImageField",
+    "imagefield": "ImageField",
+    "employee": "EmployeeField",
+    "employeefield": "EmployeeField",
+    "department": "DepartmentSelectField",
+    "departmentselectfield": "DepartmentSelectField",
+    "table": "TableField",
+    "tablefield": "TableField",
+    "association": "AssociationFormField",
+    "associationformfield": "AssociationFormField",
+    "serialnumber": "SerialNumberField",
+    "serialnumberfield": "SerialNumberField",
+    "divider": "Divider",
+}
+
+DATA_SOURCE_FIT_COMPILED = (
+    "'use strict';\n\nvar __preParser__ = function fit(response) {\n"
+    "  var content = response.content !== undefined ? response.content : response;\n"
+    "  var error = {\n"
+    "    message: response.errorMsg || response.errors && response.errors[0] && response.errors[0].msg || response.content || '远程数据源请求出错，success is false'\n"
+    "  };\n"
+    "  var success = true;\n"
+    "  if (response.success !== undefined) {\n"
+    "    success = response.success;\n"
+    "  } else if (response.hasError !== undefined) {\n"
+    "    success = !response.hasError;\n"
+    "  }\n"
+    "  return {\n"
+    "    content: content,\n"
+    "    success: success,\n"
+    "    error: error\n"
+    "  };\n"
+    "};"
+)
+
+DATA_SOURCE_FIT_SOURCE = (
+    "function fit(response) {\r\n"
+    "  const content = (response.content !== undefined) ? response.content : response;\r\n"
+    "  const error = {\r\n"
+    "    message: response.errorMsg ||\r\n"
+    "      (response.errors && response.errors[0] && response.errors[0].msg) ||\r\n"
+    "      response.content || '远程数据源请求出错，success is false',\r\n"
+    "  };\r\n"
+    "  let success = true;\r\n"
+    "  if (response.success !== undefined) {\r\n"
+    "    success = response.success;\r\n"
+    "  } else if (response.hasError !== undefined) {\r\n"
+    "    success = !response.hasError;\r\n"
+    "  }\r\n"
+    "  return {\r\n"
+    "    content,\r\n"
+    "    success,\r\n"
+    "    error,\r\n"
+    "  };\r\n"
+    "}"
+)
+
+SUPPORTED_FIELD_TYPES = {
+    "TextField", "TextareaField", "NumberField", "RateField",
+    "DateField", "CascadeDateField",
+    "RadioField", "SelectField", "CheckboxField", "MultiSelectField",
+    "CountrySelectField", "AddressField",
+    "AttachmentField", "ImageField",
+    "EmployeeField", "DepartmentSelectField",
+    "TableField", "AssociationFormField", "SerialNumberField",
+    "Divider",
+}
+
+OPTION_FIELD_TYPES = {"RadioField", "SelectField", "CheckboxField", "MultiSelectField"}
+
+# ---------------------------------------------------------------------------
+# ID 生成
+# ---------------------------------------------------------------------------
+
+_node_counter = 0
+
+
+def _random_chars(n: int = 6) -> str:
+    return "".join(random.choices(string.ascii_letters + string.digits, k=n))
+
+
+def unique_id(prefix: str = "", separator: str = "") -> str:
+    timestamp = str(int(time.time() * 1000000))[-6:]
+    random_part = _random_chars(6)
+    return f"{prefix}{separator}{timestamp}{random_part}"
+
+
+def next_node_id() -> str:
+    global _node_counter
+    _node_counter += 1
+    ts = int(time.time() * 1000)
+    base36 = ""
+    n = ts
+    while n > 0:
+        n, r = divmod(n, 36)
+        base36 = "0123456789abcdefghijklmnopqrstuvwxyz"[r] + base36
+    return f"node_oc{base36}{_node_counter}"
+
+
+def generate_field_id(component_name: str) -> str:
+    if not component_name:
+        return unique_id()
+    first_char_lower = component_name[0].lower()
+    rest_of_name = component_name[1:]
+    return f"{first_char_lower}{rest_of_name}_{unique_id()}"
+
+
+# ---------------------------------------------------------------------------
+# 国际化
+# ---------------------------------------------------------------------------
+
+
+def i18n(text: str, en_text: Optional[str] = None) -> dict[str, str]:
+    return {
+        "type": "i18n",
+        "zh_CN": text,
+        "en_US": en_text or text,
+    }
+
+
+def build_yida_i18n(text: str, translations: Optional[dict[str, str]] = None) -> dict[str, str]:
+    result: dict[str, str] = {"type": "i18n", "zh_CN": text, "en_US": text}
+    if translations:
+        result.update(translations)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# 语义色彩
+# ---------------------------------------------------------------------------
+
+_NEGATIVE_KEYWORDS = ['不通过', '拒绝', '失败', '错误', '否', '不同意', '驳回', '取消', '删除', '禁止', '异常', '警告', '危险']
+_POSITIVE_KEYWORDS = ['通过', '同意', '成功', '完成', '是', '正常', '确认', '批准', '接受', '优秀', '合格']
+_PROCESSING_KEYWORDS = ['处理中', '进行中', '待审核', '审核中', '处理', '待定', '等待']
+_WARNING_KEYWORDS = ['注意', '提醒', '待办', '紧急', '重要']
+_PAUSE_KEYWORDS = ['暂停', '挂起', '冻结', '停用']
+
+COLOR_PALETTE = [
+    '#e0f0ff', '#e0f4e6', '#fff2e0', '#ffece6', '#eee9fe',
+    '#e0f2f2', '#fff7e0', '#fde5ec', '#f6e4ff', '#e8ebfc',
+    '#f6f6f7', '#bbddff', '#bbe7c8', '#ffe2bb', '#ffcfd8',
+    '#d9cefd', '#bbe3e3', '#ffeebb', '#fac4d4', '#ebc4ff',
+    '#cbd2f8', '#edeeef',
+    '#007fff', '#00a532', '#fd9100', '#f2510c', '#704af7',
+    '#009595', '#fdbd00', '#e9235d', '#b421fd', '#3954e4',
+    '#76787a', '#0058b1', '#007423', '#b16600', '#a62700',
+    '#4f34af', '#006868', '#b18500', '#a41841', '#7e17b1',
+    '#2a3d9f', '#181c1f',
+]
+
+
+def get_semantic_color(text: str) -> Optional[str]:
+    text_lower = text.lower().strip()
+    if any(k in text_lower for k in _NEGATIVE_KEYWORDS):
+        return '#FF4D4F'
+    if any(k in text_lower for k in _POSITIVE_KEYWORDS):
+        return '#52C41A'
+    if any(k in text_lower for k in _PROCESSING_KEYWORDS):
+        return '#1890FF'
+    if any(k in text_lower for k in _WARNING_KEYWORDS):
+        return '#FA8C16'
+    if any(k in text_lower for k in _PAUSE_KEYWORDS):
+        return '#8C8C8C'
+    return None
+
+
+def build_option_data_source(
+    options: list[str],
+    *,
+    is_checkbox: bool = False,
+    used_colors: Optional[set[str]] = None,
+) -> tuple[list[dict[str, Any]], set[str]]:
+    if used_colors is None:
+        used_colors = set()
+    color_idx = 0
+    data_source: list[dict[str, Any]] = []
+    for idx, opt_name in enumerate(options):
+        semantic = get_semantic_color(opt_name)
+        if semantic:
+            color = semantic
+        else:
+            while color_idx < len(COLOR_PALETTE) and COLOR_PALETTE[color_idx] in used_colors:
+                color_idx += 1
+            color = COLOR_PALETTE[color_idx % len(COLOR_PALETTE)]
+            color_idx += 1
+        used_colors.add(color)
+        data_source.append({
+            "text": i18n(opt_name),
+            "value": opt_name,
+            "defaultChecked": False if is_checkbox else (idx == 0),
+            "color": color,
+        })
+    return data_source, used_colors
+
+
+# ---------------------------------------------------------------------------
+# componentsMap
+# ---------------------------------------------------------------------------
+
+
+def build_components_map(component_names: list[str]) -> list[dict[str, str]]:
+    seen: set[str] = set()
+    result: list[dict[str, str]] = []
+    for name in component_names:
+        if name not in seen:
+            seen.add(name)
+            result.append({
+                "package": COMPONENT_PACKAGE,
+                "version": COMPONENT_VERSION,
+                "componentName": name,
+            })
+    return result
+
+
+_REPORT_LOWCODE_COMPONENTS = {"YoushuSelect"}
+
+
+def build_report_components_map(component_names: list[str]) -> list[dict[str, str]]:
+    seen: set[str] = set()
+    result: list[dict[str, str]] = []
+    for name in component_names:
+        if name not in seen:
+            seen.add(name)
+            if name in _REPORT_LOWCODE_COMPONENTS:
+                result.append({
+                    "devMode": "lowcode",
+                    "componentName": name,
+                })
+            else:
+                result.append({
+                    "package": REPORT_COMPONENT_PACKAGE,
+                    "version": REPORT_COMPONENT_VERSION,
+                    "componentName": name,
+                })
+    return result
+
+
+def collect_component_names(field_nodes: list[dict[str, Any]]) -> list[str]:
+    names: list[str] = []
+
+    def _walk(node: dict[str, Any]) -> None:
+        cn = node.get("componentName", "")
+        if cn:
+            names.append(cn)
+        for child in node.get("children", []):
+            _walk(child)
+
+    for node in field_nodes:
+        _walk(node)
+    return names
+
+
+# ---------------------------------------------------------------------------
+# 类型解析
+# ---------------------------------------------------------------------------
+
+
+def normalize_field_type(raw_type: str) -> str:
+    lower = raw_type.lower().replace("_", "").replace("-", "")
+    if lower in FIELD_TYPE_ALIAS:
+        return FIELD_TYPE_ALIAS[lower]
+    if raw_type in SUPPORTED_FIELD_TYPES:
+        return raw_type
+    raise ValueError(f"不支持的字段类型: {raw_type}")

package/skills/dws/dingtalk-shared/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: dingtalk-shared
+description: 钉钉(DingTalk) MultiSkill 的轻量共享入口。Use when 用户泛称 DWS/钉钉操作但未明确产品、请求跨产品编排、需要 URL 类型预检或产品边界消歧。清晰的单产品操作优先使用对应 dingtalk-* 子 skill；本 skill 只提供全局执行契约和按需 reference 导航，不承载产品命令全集。
+metadata:
+  cli_version: ">=0.2.14"
+  category: shared
+  requires:
+    bins:
+      - dws
+---
+
+# DWS 共享执行契约
+
+本文件只在泛称 DWS、跨产品流程、URL 预检或意图不清时作为入口。明确单产品请求直接使用对应 `dingtalk-*` skill；已经内嵌最小执行契约的产品根 Skill 不需要先完整读取本文件。
+
+<!-- DWS_RUNTIME_CONTRACT_START -->
+## 最小 DWS 执行契约
+
+- 只通过 `dws` CLI 操作钉钉；结构化读取使用 `--format json`，按真实返回判断结果。
+- 已知命令直接执行。只有 leaf 参数或安全语义不确定时读取精确 Schema，只有 Cobra flag 不确定时读取精确 leaf Help；不要加载产品级 Catalog 代替选路。
+- 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。
+- 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 `isOrgCurrent=true` 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。
+- 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。
+- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加 `--yes`。
+- 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。
+- 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。
+- 遇到认证、权限、profile、confirmation 或未知错误时，只加载 `dingtalk-shared` 中对应 reference；不要连续猜测替代命令。
+<!-- DWS_RUNTIME_CONTRACT_END -->
+
+产品或跨产品规则在最小契约之上增量加载。用户已明确产品内容意图时，意图优先于 URL 形态；多账号选择与跨组织规则读取 [`../dingtalk-misc/references/profile.md`](../dingtalk-misc/references/profile.md)。本地文件、产品边界和跨产品传递规则只在对应任务中加载，避免把全局手册放入每个单产品请求。
+
+## 渐进加载
+
+只读取当前任务需要的文件，不要一次性加载全部 shared references：
+
+| 当前情况 | 必读内容 |
+|---|---|
+| 已明确单一产品 | 对应 `../dingtalk-*/SKILL.md`；不读路由 reference |
+| 泛称 DWS、需要选择产品 | [routing.md](references/routing.md) |
+| 跨产品、多步骤、汇总或报告 | [workflow-routing.md](references/workflow-routing.md) |
+| 输入含 alidocs、shanji 等钉钉 URL 且类型不明 | [url-patterns.md](references/url-patterns.md) |
+| 产品边界仍然难以判断 | [intent-guide.md](references/intent-guide.md) 的相关章节 |
+| 认证、全局 flag 或输出格式问题 | [global-reference.md](references/global-reference.md) |
+| 命令已经返回错误 | [error-codes.md](references/error-codes.md)；只查错误对应章节 |
+| `confirmation_required` / 写操作确认 | [confirmation.md](references/confirmation.md) |
+| 命令发现、Schema / `--compact` / `--all` | [schema-usage.md](references/schema-usage.md) |
+| 怀疑能力不支持 | [capability-limits.md](references/capability-limits.md) |
+| 批量/多源采集 | [conventions.md](references/recipes/conventions.md) |
+| 固定短流程 | [lite-catalog.md](references/recipes/lite-catalog.md) 对应章节 |
+
+产品命令、脚本和字段细节位于对应产品 skill，不在 `dingtalk-shared` 重复维护。
+
+## 本 skill 作为入口时的路由顺序
+
+1. 先识别明确的产品内容意图；明确意图直接进入对应产品。仅当输入包含钉钉 URL
+   且类型不明确或意图与链接类型可能冲突时，读取 `url-patterns.md` 识别节点类型。
+2. 请求包含多个时序步骤、跨产品数据传递或汇总报告：即使 URL 已识别，也要读取
+   `workflow-routing.md`，按行动指南组合需要的产品 skill；当前发布包不包含独立
+   scenario skill。
+3. 请求是单产品操作但产品不明确：读取 `routing.md`，再显式读取目标产品
+   `SKILL.md`。
+4. `doc/drive/wiki`、`aitable/sheet`、`calendar/minutes` 等边界仍不清楚：
+   只读取 `intent-guide.md` 的对应章节。
+5. 仍无法判断时向用户追问，不要猜测产品或命令。
+
+## 跨 skill 执行
+
+- 正文中的相对 `Read` 链接是运行时依赖；`metadata.requires.skills` 不会自动加载。
+- 选择目标产品后，以目标 skill 的命令、参数和风险规则为准。
+- 多步骤流程按顺序传递真实返回值；可以并行的只读采集按对应 workflow/reference
+  执行，写操作默认串行并逐步验证。
+- 产品 skill 已内联的清晰操作直接执行；仅在遇到该 skill 未覆盖的参数或边界时读取
+  更深层 reference。
+
+## 错误最短路径
+
+1. `unknown command` / `unknown flag`：运行对应层级 `--help`，按公开 flag 修正后最多重试一次；命令选择不确定时读 [schema-usage.md](references/schema-usage.md)。
+2. `reason=confirmation_required`：按 [confirmation.md](references/confirmation.md) 处理，不要当普通校验错误放弃或静默加 `--yes`。
+3. 认证或权限错误：读取 `global-reference.md` 与 `error-codes.md` 对应章节。
+4. 其他错误：优先读取 JSON 错误中的 `retryable`、`retry_after_seconds`、
+   `next_retry_at`、`hint` 和 `actions`。只有明确 `retryable=true` 时才按服务端节奏重试；
+   缺少重试语义时用 `--verbose` 获取诊断并停止，不连续尝试替代命令。
+5. 明确不支持的能力：说明边界，不通过其他接口绕过。