precis-cli 0.1.3__py3-none-any.whl

app/shared/services/llm/actions/regex_handlers.py

@@ -0,0 +1,284 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview Regex 动作处理器模块
+
+功能概述:
+- 处理 AI 生成的 Regex CRUD 动作（ADD_REGEX / UPDATE_REGEX / DELETE_REGEX）
+- 通过 core 层 writer 持久化 Regex YAML 文件
+- 同步更新 project.precis.yaml 中的 RegexRef
+
+架构设计:
+- 复用 core/project/regex/writer.py 的 save_regex_node()
+- 复用 core/project/manifest/writer.py 的 ensure_regex_ref() / save_manifest()
+- 使用 RegexNodeFile Pydantic 模型确保类型安全
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from app.shared.core.project.manifest.reader import load_manifest
+from app.shared.core.project.manifest.writer import ensure_regex_ref, save_manifest
+from app.shared.core.project.regex.types import RegexNodeFile, RegexSourceRef
+from app.shared.core.project.regex.writer import save_regex_node
+from app.shared.services.llm.yaml_io import FileLock, atomic_write_yaml
+
+logger = logging.getLogger(__name__)
+
+VALID_MATCH_MODES = {"full", "partial", "extract"}
+
+
+def _sanitize_resource_id(resource_id: str) -> str:
+    cleaned = os.path.basename(resource_id)
+    if "/" in resource_id or "\\" in resource_id or ".." in resource_id:
+        raise ValueError(f"非法的资源 ID: {resource_id!r}")
+    return cleaned
+
+
+def process_regex_action(action: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """
+    @methoddesc 处理 Regex 动作
+
+    根据 actionType 分发到对应的处理函数。
+
+    参数:
+        action: 动作字典，包含 actionType 和 regexSpec
+        workspace_path: 项目工作区路径
+
+    返回:
+        处理结果字典 {"success": bool, "message": str}
+    """
+    action_type = action.get("actionType", "")
+    spec = action.get("regexSpec", {})
+
+    if action_type == "ADD_REGEX":
+        return _add_regex(spec, workspace_path)
+    elif action_type == "UPDATE_REGEX":
+        return _update_regex(spec, workspace_path)
+    elif action_type == "DELETE_REGEX":
+        return _delete_regex(spec, workspace_path)
+    else:
+        return {"success": False, "message": f"未知的 Regex 动作类型: {action_type}"}
+
+
+def _add_regex(spec: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """创建新的 Regex YAML 文件"""
+    regex_name = spec.get("name", "")
+    regex_id = spec.get("regexId") or spec.get("id") or regex_name
+    try:
+        regex_id = _sanitize_resource_id(regex_id)
+    except ValueError:
+        return {"success": False, "message": f"非法的 Regex ID: {regex_id}"}
+    pattern = spec.get("pattern", "")
+    match_mode = spec.get("matchMode", "full")
+    case_sensitive = spec.get("caseSensitive", False)
+    description = spec.get("description")
+    target_node_id = spec.get("targetNodeId")
+    target_column = spec.get("targetColumn")
+
+    if not regex_name:
+        return {"success": False, "message": "Regex 名称不能为空"}
+    if not pattern:
+        return {"success": False, "message": "Regex 模式不能为空"}
+
+    if match_mode not in VALID_MATCH_MODES:
+        match_mode = "full"
+
+    workspace = Path(workspace_path)
+    # V2 标准：regex 文件统一存放在 regex/ 目录（manifest 登记与全仓读取方均认此目录），
+    # 旧版写入 regex_nodes/ 会导致 manifest 引用的路径与实际文件位置漂移
+    regex_dir = workspace / "regex"
+    regex_dir.mkdir(parents=True, exist_ok=True)
+
+    regex_file = regex_dir / f"{regex_id}.regex.yaml"
+    # 已存在检测同时覆盖新旧目录（历史版本曾写入 regex_nodes/），避免跨目录产生同 ID 重复文件
+    if regex_file.exists() or _find_regex_file(workspace_path, regex_id):
+        # 提示 Agent 改用 ADD_TO_CANVAS（同 schema_handlers 的引导逻辑）
+        return {
+            "success": False,
+            "message": (
+                f"Regex 文件已存在: {regex_id}.regex.yaml。"
+                f"若用户想把已存在的资源显示到画布，请改用 actionType=ADD_TO_CANVAS"
+                f"（canvasSpec.resourceKind='regex'），它不会重复创建文件。"
+            ),
+        }
+
+    # 构建 source_ref
+    source_ref = None
+    if target_node_id and target_column:
+        source_ref = RegexSourceRef(table_id=target_node_id, column_id=target_column)
+
+    try:
+        regex_node = RegexNodeFile(
+            version=2,
+            id=regex_id,
+            name=regex_name,
+            pattern=pattern,
+            match_mode=match_mode,
+            case_sensitive=case_sensitive,
+            description=description,
+            enabled=True,
+            uses_pattern=None,
+            flags="",
+            input_from_node=None,
+            input_column=None,
+            source_ref=source_ref,
+            source_column_name=target_column,
+        )
+        save_regex_node(regex_node, regex_file)
+    except Exception as e:
+        return {"success": False, "message": f"写入 Regex 文件失败: {e}"}
+
+    # 更新 manifest —— §2.7: 登记失败时回滚删除已写文件（对齐 Schema 路径），
+    # 否则磁盘留下孤儿 .regex.yaml：重启后不被加载、不报错、画布节点还在
+    try:
+        _ensure_manifest_regex_ref(workspace_path, regex_id)
+    except Exception as e:
+        Path(regex_file).unlink(missing_ok=True)
+        return {"success": False, "message": f"更新 manifest 引用失败（已回滚 Regex 文件）: {e}"}
+
+    logger.info(f"[RegexHandler] 创建 Regex: {regex_id}")
+    return {"success": True, "message": regex_id}
+
+
+def _update_regex(spec: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """更新现有 Regex"""
+    regex_id = spec.get("regexId") or spec.get("id") or spec.get("name", "")
+    try:
+        regex_id = _sanitize_resource_id(regex_id)
+    except ValueError:
+        return {"success": False, "message": f"非法的 Regex ID: {regex_id}"}
+
+    if not regex_id:
+        return {"success": False, "message": "缺少 Regex ID"}
+
+    regex_file = _find_regex_file(workspace_path, regex_id)
+    if not regex_file:
+        return {"success": False, "message": f"Regex 文件不存在: {regex_id}"}
+
+    try:
+        with FileLock(str(regex_file)):
+            with open(regex_file, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+
+            if spec.get("pattern"):
+                data["pattern"] = spec["pattern"]
+            if spec.get("name"):
+                data["name"] = spec["name"]
+            if spec.get("matchMode"):
+                data["match_mode"] = spec["matchMode"]
+            if "caseSensitive" in spec:
+                data["case_sensitive"] = spec["caseSensitive"]
+            if "description" in spec:
+                data["description"] = spec["description"]
+            if spec.get("targetNodeId") and spec.get("targetColumn"):
+                data["source_ref"] = {"table_id": spec["targetNodeId"], "column_id": spec["targetColumn"]}
+                data["source_column_name"] = spec["targetColumn"]
+
+            # §2.10: UPDATE 显式整体替换语义（与 UPDATE_TRANSFORM/UPDATE_SCHEMA 同族对齐）
+            atomic_write_yaml(regex_file, data, preserve_format=False)
+
+    except Exception as e:
+        return {"success": False, "message": f"更新 Regex 失败: {e}"}
+
+    logger.info(f"[RegexHandler] 更新 Regex: {regex_id}")
+    return {"success": True, "message": regex_id}
+
+
+def _delete_regex(spec: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """删除 Regex 文件"""
+    regex_id = spec.get("regexId") or spec.get("id") or spec.get("name", "")
+    try:
+        regex_id = _sanitize_resource_id(regex_id)
+    except ValueError:
+        return {"success": False, "message": f"非法的 Regex ID: {regex_id}"}
+
+    if not regex_id:
+        return {"success": False, "message": "缺少 Regex ID"}
+
+    regex_file = _find_regex_file(workspace_path, regex_id)
+    if not regex_file:
+        return {"success": False, "message": f"Regex 文件不存在: {regex_id}"}
+
+    try:
+        regex_file.unlink()
+    except OSError as e:
+        return {"success": False, "message": f"删除 Regex 文件失败: {e}"}
+
+    _remove_manifest_regex_ref(workspace_path, regex_id)
+
+    logger.info(f"[RegexHandler] 删除 Regex: {regex_id}")
+    return {"success": True, "message": regex_id}
+
+
+def _find_regex_file(workspace_path: str, regex_id: str) -> Path | None:
+    """在工作区中查找 regex 文件"""
+    # 检查多个可能的目录名
+    for dirname in ("regex_nodes", "regex"):
+        regex_dir = Path(workspace_path) / dirname
+        if not regex_dir.exists():
+            continue
+        # 按 ID 精确匹配
+        for rf in regex_dir.glob("*.yaml"):
+            try:
+                with open(rf, encoding="utf-8") as f:
+                    data = yaml.safe_load(f) or {}
+                if data.get("id") == regex_id or data.get("name") == regex_id:
+                    return rf
+            except Exception:
+                continue
+        # 按文件名匹配
+        candidate = regex_dir / f"{regex_id}.regex.yaml"
+        if candidate.exists():
+            return candidate
+        candidate = regex_dir / f"{regex_id}.yaml"
+        if candidate.exists():
+            return candidate
+
+    return None
+
+
+def _ensure_manifest_regex_ref(workspace_path: str, regex_id: str) -> None:
+    """确保 manifest 中包含指定 Regex 引用。
+
+    §2.7: 异常向上传播（不再吞掉只留 warning）——调用方据此回滚已写的 Regex 文件。
+    """
+    manifest_path = Path(workspace_path) / "project.precis.yaml"
+    if not manifest_path.exists():
+        return
+
+    manifest = load_manifest(manifest_path)
+    ensure_regex_ref(manifest, regex_id)
+    save_manifest(manifest, manifest_path)
+
+
+def _remove_manifest_regex_ref(workspace_path: str, regex_id: str) -> None:
+    """从 manifest 中移除指定 Regex 引用"""
+    manifest_path = Path(workspace_path) / "project.precis.yaml"
+    if not manifest_path.exists():
+        return
+
+    try:
+        manifest = load_manifest(manifest_path)
+        manifest.regex_nodes = [r for r in manifest.regex_nodes if r.id != regex_id]
+        save_manifest(manifest, manifest_path)
+    except Exception as e:
+        logger.warning(f"[RegexHandler] 更新 manifest 引用失败: {e}")

app/shared/services/llm/actions/registry.py

@@ -0,0 +1,336 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview AI 动作注册表 — 单一事实源
+
+本模块是所有 AI 动作类型（actionType）的唯一权威定义处。
+其他模块（解析、校验、执行、前端指令生成、提示词）一律从此派生，
+禁止重复硬编码动作类型集合，以消灭"同步遗漏"类 bug（如计数写错、
+enum 漏条目、spec 字段映射不一致）。
+
+三类内容在此收敛：
+1. 动作类型（15种）及其 spec 字段、分类、读写性
+2. 派生集合：ALL_ACTION_TYPES / BY_CATEGORY / READ_ONLY_TYPES / SPEC_FIELD_FOR 等
+3. 子类型白名单：约束类型、转换子类型、数据类型、设置分类（原散落 2-4 处）
+
+设计原则：
+- 注册表只描述"是什么"（声明性），不描述"怎么做"（执行逻辑仍在各 handler）。
+- 派生属性用普通函数/常量，导入即用，零运行时开销。
+- 新增一个动作 = 在 ACTIONS 加一行 + 配套 validator/handler，其余全自动派生。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# =============================================================================
+# 子类型白名单（规范来源）——原散落于 action_validator / response_parser /
+# suggestion_utils / transform_handlers / _schema_validator / settings_handlers 等
+# =============================================================================
+
+# 约束类型（PascalCase 正名）——与前端 CONSTRAINT_TYPE_MAP 的 value 侧一致
+# 注意：仅含"标准名"，大写别名（NOT_NULL 等）由 ALIAS_CONSTRAINT_TYPES 单独管理
+CONSTRAINT_TYPES: frozenset[str] = frozenset(
+    {
+        "NotNull",
+        "Unique",
+        "Range",
+        "AllowedValues",
+        "ForeignKey",
+        "Conditional",
+        "Scripted",
+        "DateLogic",
+        "Charset",
+        "Composite",
+    }
+)
+
+# 约束类型大写别名（LLM 可能输出）→ 标准名。
+# 这是唯一的别名映射表，取代散落各处的重复副本。
+# Scripted 的别名 REGEX 保留（历史兼容：旧约束用 REGEX 表示正则脚本约束）。
+CONSTRAINT_TYPE_ALIASES: dict[str, str] = {
+    "NOT_NULL": "NotNull",
+    "UNIQUE": "Unique",
+    "RANGE": "Range",
+    "ALLOWED_VALUES": "AllowedValues",
+    "FOREIGN_KEY": "ForeignKey",
+    "CONDITIONAL": "Conditional",
+    "DATE_LOGIC": "DateLogic",
+    "CHARSET": "Charset",
+    "COMPOSITE": "Composite",
+    "REGEX": "Scripted",
+}
+
+# 约束类型全集（标准名 + 别名），供校验白名单使用
+ALL_CONSTRAINT_TYPES: frozenset[str] = CONSTRAINT_TYPES | frozenset(CONSTRAINT_TYPE_ALIASES.keys())
+
+# 需要特定参数的约束类型（供参数完整性校验）
+# 注意：Range 的 min/max 实际允许"至少一个"（见 _constraint_validator 特殊处理），
+# 此处仅声明"需要关注的参数键"，具体宽松度由 validator 决定。
+CONSTRAINT_REQUIRED_PARAMS: dict[str, list[str]] = {
+    "Range": ["min", "max"],
+    "AllowedValues": ["allowedValues"],
+    "ForeignKey": ["toTableId", "toColumnId"],
+}
+
+# 转换子类型白名单（22种）——原 response_parser(21条) 与 transform_handlers(22条) 不一致，
+# 以 transform_handlers 的 22 条为准（response_parser 缺 FillNA，实际是有效类型）。
+TRANSFORM_SUB_TYPES: frozenset[str] = frozenset(
+    {
+        "StringSplit",
+        "RegexExtract",
+        "MathExpr",
+        "DateFormat",
+        "Lookup",
+        "Strip",
+        "UpperCase",
+        "LowerCase",
+        "Replace",
+        "FillNA",
+        "FilterRows",
+        "DropDuplicates",
+        "CastType",
+        "Concat",
+        "Substring",
+        "Aggregate",
+        "ConditionalAssign",
+        "SortRows",
+        "Digits",
+        "WeightedSum",
+        "Modulo",
+        "MapValue",
+    }
+)
+
+# Schema 列数据类型白名单
+DATA_TYPES: frozenset[str] = frozenset({"string", "integer", "decimal", "boolean", "datetime", "date", "time", "float"})
+
+# 设置分类白名单
+SETTINGS_CATEGORIES: frozenset[str] = frozenset({"validation", "fileProcessing", "scriptSecurity"})
+
+# ADD_TO_CANVAS 支持的资源类型
+CANVAS_RESOURCE_KINDS: frozenset[str] = frozenset({"schema", "regex", "constraint", "transform"})
+
+
+# =============================================================================
+# 动作类型定义
+# =============================================================================
+
+
+@dataclass(frozen=True)
+class ActionTypeDef:
+    """单个动作类型的声明性定义。
+
+    Attributes:
+        type: actionType 字符串，如 "ADD_SCHEMA"
+        spec_field: 对应的 spec 字段名，如 "schemaSpec"（None 表示无 spec，如 VALIDATE_PROJECT）
+        category: 动作家族，用于分类桶：constraint/schema/regex/transform/settings/canvas/validate
+        read_only: True=不写盘（纯读），False=写盘动作
+    """
+
+    type: str
+    spec_field: str | None
+    category: str
+    read_only: bool
+
+
+# 动作类型唯一注册表——新增动作只需在此加一行，其余派生属性自动更新
+ACTIONS: dict[str, ActionTypeDef] = {
+    # 约束 CRUD（写盘）
+    "ADD_CONSTRAINT_NODE": ActionTypeDef("ADD_CONSTRAINT_NODE", "constraintSpec", "constraint", False),
+    "UPDATE_CONSTRAINT_NODE": ActionTypeDef("UPDATE_CONSTRAINT_NODE", "constraintSpec", "constraint", False),
+    "DELETE_CONSTRAINT_NODE": ActionTypeDef("DELETE_CONSTRAINT_NODE", "constraintSpec", "constraint", False),
+    # Schema CRUD（写盘）
+    "ADD_SCHEMA": ActionTypeDef("ADD_SCHEMA", "schemaSpec", "schema", False),
+    "UPDATE_SCHEMA": ActionTypeDef("UPDATE_SCHEMA", "schemaSpec", "schema", False),
+    "DELETE_SCHEMA": ActionTypeDef("DELETE_SCHEMA", "schemaSpec", "schema", False),
+    # Regex CRUD（写盘）
+    "ADD_REGEX": ActionTypeDef("ADD_REGEX", "regexSpec", "regex", False),
+    "UPDATE_REGEX": ActionTypeDef("UPDATE_REGEX", "regexSpec", "regex", False),
+    "DELETE_REGEX": ActionTypeDef("DELETE_REGEX", "regexSpec", "regex", False),
+    # Transform CRUD（写盘）
+    "ADD_TRANSFORM": ActionTypeDef("ADD_TRANSFORM", "transformSpec", "transform", False),
+    "UPDATE_TRANSFORM": ActionTypeDef("UPDATE_TRANSFORM", "transformSpec", "transform", False),
+    "DELETE_TRANSFORM": ActionTypeDef("DELETE_TRANSFORM", "transformSpec", "transform", False),
+    # 设置（写盘）
+    "UPDATE_SETTINGS": ActionTypeDef("UPDATE_SETTINGS", "settingsSpec", "settings", False),
+    # 校验（只读）
+    "VALIDATE_PROJECT": ActionTypeDef("VALIDATE_PROJECT", "constraintSpec", "validate", True),
+    # 显示到画布（只读，不写盘）
+    "ADD_TO_CANVAS": ActionTypeDef("ADD_TO_CANVAS", "canvasSpec", "canvas", True),
+}
+
+
+# =============================================================================
+# 派生属性（自动生成，禁止手动维护）
+# =============================================================================
+
+# 全部动作类型列表（顺序稳定，供 LLM enum 与提示词清单）
+ALL_ACTION_TYPES: list[str] = [a.type for a in ACTIONS.values()]
+
+# LLM 工具 schema 的 enum 数组
+ACTION_ENUM: list[str] = ALL_ACTION_TYPES
+
+# 动作总数（消灭硬编码 "15种"）
+ACTION_COUNT: int = len(ACTIONS)
+
+# 按 category 分组的动作集合（先收集到普通 set，再冻结为 frozenset）
+_category_buckets: dict[str, set[str]] = {}
+for _a in ACTIONS.values():
+    _category_buckets.setdefault(_a.category, set()).add(_a.type)
+BY_CATEGORY: dict[str, frozenset[str]] = {k: frozenset(v) for k, v in _category_buckets.items()}
+
+# 家族集合的便捷别名（最常引用的几个）
+CONSTRAINT_ACTION_TYPES: frozenset[str] = BY_CATEGORY["constraint"]
+SCHEMA_ACTION_TYPES: frozenset[str] = BY_CATEGORY["schema"]
+REGEX_ACTION_TYPES: frozenset[str] = BY_CATEGORY["regex"]
+TRANSFORM_ACTION_TYPES: frozenset[str] = BY_CATEGORY["transform"]
+
+# 只读动作集合（不写盘）
+READ_ONLY_ACTION_TYPES: frozenset[str] = frozenset(a.type for a in ACTIONS.values() if a.read_only)
+
+# 写盘动作集合（READ_ONLY 的补集）
+WRITE_ACTION_TYPES: frozenset[str] = frozenset(a.type for a in ACTIONS.values() if not a.read_only)
+
+# actionType → spec 字段映射（None 表示无 spec 字段要求）
+SPEC_FIELD_FOR: dict[str, str | None] = {a.type: a.spec_field for a in ACTIONS.values()}
+
+
+def get_action_def(action_type: str) -> ActionTypeDef | None:
+    """查询动作定义，不存在返回 None。"""
+    return ACTIONS.get(action_type)
+
+
+def is_read_only(action_type: str) -> bool:
+    """判断动作是否只读（不写盘）。未知动作视为写（保守）。"""
+    d = ACTIONS.get(action_type)
+    return d.read_only if d else False
+
+
+def is_known_action(action_type: str) -> bool:
+    """判断是否为已注册的动作类型。"""
+    return action_type in ACTIONS
+
+
+# =============================================================================
+# 提示词文本派生（从注册表生成 LLM 可见的动作清单，消灭手写源文本漂移）
+# =============================================================================
+
+# category 的中文标签（用于提示词动作清单的分组标题）
+_CATEGORY_LABELS: dict[str, str] = {
+    "constraint": "约束",
+    "schema": "Schema",
+    "regex": "正则",
+    "transform": "转换",
+    "settings": "设置",
+    "validate": "校验",
+    "canvas": "显示到画布",
+}
+
+
+def build_action_type_list_text() -> str:
+    """生成 actionType 可选值清单（按 category 分组），供系统提示词使用。
+
+    新增动作后自动出现在此清单，无需手动同步提示词文本。
+    """
+    lines: list[str] = []
+    for category, types in BY_CATEGORY.items():
+        label = _CATEGORY_LABELS.get(category, category)
+        types_sorted = " / ".join(sorted(types))
+        suffix = ""
+        # ADD_TO_CANVAS 特殊标注"不写盘"
+        if category == "canvas":
+            suffix = "（把已存在的配置显示到画布，不写盘）"
+        lines.append(f"- {label}: {types_sorted}{suffix}")
+    return "\n".join(lines)
+
+
+def build_spec_field_mapping_text() -> str:
+    """生成 actionType → spec 字段映射清单，供系统提示词使用。
+
+    从 SPEC_FIELD_FOR 派生，新增动作后自动更新。
+    """
+    # spec 字段的中文说明（用于提示词）
+    _spec_notes: dict[str, str] = {
+        "constraintSpec": "含 type, tableName, targetColumn, isInline, params 等",
+        "schemaSpec": "含 name, columns",
+        "regexSpec": "含 name, pattern, matchMode",
+        "transformSpec": "含 type, inputColumn, params, outputColumns",
+        "settingsSpec": "含 category, settings",
+        "canvasSpec": "含 resourceKind: schema/regex/constraint/transform, resourceId 或 resourceName",
+    }
+    lines: list[str] = []
+    for category, types in BY_CATEGORY.items():
+        label = _CATEGORY_LABELS.get(category, category)
+        # 取该 category 第一个动作的 spec 字段（同 category 共享 spec 字段）
+        sample_type = sorted(types)[0]
+        spec_field = SPEC_FIELD_FOR.get(sample_type)
+        if spec_field is None:
+            continue
+        note = _spec_notes.get(spec_field, "")
+        # 特殊：校验动作用 constraintSpec 但 tableName 可选
+        if category == "validate":
+            note = "含 tableName，可选"
+        lines.append(f"- {label}动作 → {spec_field} ({note})" if note else f"- {label}动作 → {spec_field}")
+    return "\n".join(lines)
+
+
+# =============================================================================
+# Codegen 导出（供 frontend/scripts/codegen.mjs 通过 subprocess 读取）
+# =============================================================================
+
+
+def export_for_codegen() -> dict[str, object]:
+    """将动作类型单一事实源序列化为 JSON-friendly dict，供前端 codegen 生成 TS 类型。
+
+    设计要点:
+    - frozenset 统一转 sorted list，保证顺序稳定（生成的 TS 文件可 diff）
+    - 仅导出 codegen 所需字段（type/spec_field/category/read_only + 派生集合）
+    - 纯函数、零 IO、零副作用，可在 subprocess 中安全 import 调用
+
+    返回结构（JSON 兼容）::
+
+        {
+            "actions": [ {type, spec_field, category, read_only}, ... ],  # 按 ACTIONS 插入序
+            "all_action_types": [...],
+            "by_category": { "constraint": [...], ... },
+            "read_only_action_types": [...],
+            "write_action_types": [...],
+            "constraint_types": [...],            # 约束类型标准名（PascalCase，sorted）
+            "constraint_type_aliases": {...},     # 大写别名 → 标准名
+        }
+
+    constraint_types/constraint_type_aliases 供前端 codegen 生成约束类型映射，
+    使前端 AI 指令处理器与后端提示词/写盘路径消费同一份约束类型清单，
+    消灭"新增约束类型时前端 map/提示词漏同步"类漂移。
+    """
+    return {
+        # 按 ACTIONS 插入序保留（dict 保序），便于生成稳定 TS
+        "actions": [
+            {
+                "type": a.type,
+                "spec_field": a.spec_field,
+                "category": a.category,
+                "read_only": a.read_only,
+            }
+            for a in ACTIONS.values()
+        ],
+        "all_action_types": list(ALL_ACTION_TYPES),
+        "by_category": {k: sorted(v) for k, v in BY_CATEGORY.items()},
+        "read_only_action_types": sorted(READ_ONLY_ACTION_TYPES),
+        "write_action_types": sorted(WRITE_ACTION_TYPES),
+        "constraint_types": sorted(CONSTRAINT_TYPES),
+        "constraint_type_aliases": dict(sorted(CONSTRAINT_TYPE_ALIASES.items())),
+    }