precis-cli 0.1.3__py3-none-any.whl

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

@@ -0,0 +1,335 @@
+# 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 Schema 动作处理器模块
+
+功能概述:
+- 处理 AI 生成的 Schema CRUD 动作（ADD_SCHEMA / UPDATE_SCHEMA / DELETE_SCHEMA）
+- 通过 core 层 writer 持久化 Schema YAML 文件
+- 同步更新 project.precis.yaml 中的 SchemaRef
+
+架构设计:
+- 复用 core/project/schema/writer.py 的 save_schema()
+- 复用 core/project/manifest/writer.py 的 ensure_schema_ref() / save_manifest()
+- 使用 atomic_write_yaml 保证文件写入安全
+"""
+
+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_schema_ref, save_manifest
+from app.shared.core.project.schema_ref_check import find_schema_references, format_reference_report
+from app.shared.services.llm.yaml_io import FileLock, atomic_write_yaml
+
+logger = logging.getLogger(__name__)
+
+# 数据类型白名单从注册表派生（单一事实源）
+from app.shared.services.llm.actions.registry import DATA_TYPES as VALID_DATA_TYPES
+
+
+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_schema_action(action: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """
+    @methoddesc 处理 Schema 动作
+
+    根据 actionType 分发到对应的处理函数：
+    - ADD_SCHEMA: 创建新的 Schema YAML 文件
+    - UPDATE_SCHEMA: 修改现有 Schema 的列定义或数据源
+    - DELETE_SCHEMA: 删除 Schema YAML 文件并移除 manifest 引用
+
+    参数:
+        action: 动作字典，包含 actionType 和 schemaSpec
+        workspace_path: 项目工作区路径
+
+    返回:
+        处理结果字典 {"success": bool, "message": str}
+    """
+    action_type = action.get("actionType", "")
+    spec = action.get("schemaSpec", {})
+
+    if action_type == "ADD_SCHEMA":
+        return _add_schema(spec, workspace_path)
+    elif action_type == "UPDATE_SCHEMA":
+        return _update_schema(spec, workspace_path)
+    elif action_type == "DELETE_SCHEMA":
+        return _delete_schema(spec, workspace_path)
+    else:
+        return {"success": False, "message": f"未知的 Schema 动作类型: {action_type}"}
+
+
+def _add_schema(spec: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """创建新的 Schema YAML 文件"""
+    schema_name = spec.get("name", "")
+    schema_id = spec.get("schemaId") or spec.get("id") or schema_name
+    try:
+        schema_id = _sanitize_resource_id(schema_id)
+    except ValueError:
+        return {"success": False, "message": f"非法的 Schema ID: {schema_id}"}
+    columns = spec.get("columns", [])
+    source = spec.get("source")
+
+    if not schema_name:
+        return {"success": False, "message": "Schema 名称不能为空"}
+
+    workspace = Path(workspace_path)
+    schemas_dir = workspace / "schemas"
+    schemas_dir.mkdir(parents=True, exist_ok=True)
+
+    # 检查是否已存在同名 Schema
+    schema_file = schemas_dir / f"{schema_id}.schema.yaml"
+    if schema_file.exists():
+        # 提示 Agent 改用 ADD_TO_CANVAS：用户的意图很可能是"把已存在的资源显示到画布"
+        # 而非"创建新文件"。把建议写进 message 让 LLM 自我修正。
+        return {
+            "success": False,
+            "message": (
+                f"Schema 文件已存在: {schema_id}.schema.yaml。"
+                f"若用户想把已存在的资源显示到画布，请改用 actionType=ADD_TO_CANVAS"
+                f"（canvasSpec.resourceKind='schema'），它不会重复创建文件。"
+            ),
+        }
+
+    # 构建列定义
+    column_defs = []
+    for i, col in enumerate(columns):
+        col_name = col.get("name", f"col_{i}")
+        col_type = col.get("type", "string")
+        if col_type not in VALID_DATA_TYPES:
+            col_type = "string"
+        column_defs.append(
+            {
+                "id": col_name,
+                "name": col_name,
+                "type": col_type,
+            }
+        )
+
+    # 构建 schema 数据
+    schema_data: dict[str, Any] = {
+        "version": 2,
+        "id": schema_id,
+        "name": schema_name,
+        "columns": column_defs,
+    }
+
+    if source:
+        source_path = source.get("path", "")
+        if source_path and (".." in source_path or os.path.isabs(source_path)):
+            return {"success": False, "message": f"source.path 不允许绝对路径或目录穿越: {source_path}"}
+        schema_data["source"] = source
+    try:
+        with FileLock(str(schema_file)):
+            atomic_write_yaml(schema_file, schema_data)
+    except Exception as e:
+        return {"success": False, "message": f"写入 Schema 文件失败: {e}"}
+
+    # 更新 manifest —— 失败时回滚已写入的 schema 文件，避免产生孤儿文件
+    try:
+        _ensure_manifest_schema_ref(workspace_path, schema_id)
+    except Exception as e:
+        logger.error(f"[SchemaHandler] 登记到 manifest 失败，回滚 schema 文件: {e}")
+        try:
+            schema_file.unlink(missing_ok=True)
+        except OSError as rollback_err:
+            logger.error(f"[SchemaHandler] 回滚 schema 文件失败: {rollback_err}")
+        return {"success": False, "message": f"更新 manifest 引用失败: {e}"}
+
+    logger.info(f"[SchemaHandler] 创建 Schema: {schema_id}")
+    return {"success": True, "message": schema_id}
+
+
+def _update_schema(spec: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """更新现有 Schema"""
+    schema_id = spec.get("schemaId") or spec.get("id") or spec.get("name", "")
+    try:
+        schema_id = _sanitize_resource_id(schema_id)
+    except ValueError:
+        return {"success": False, "message": f"非法的 Schema ID: {schema_id}"}
+    columns = spec.get("columns")
+    source = spec.get("source")
+
+    if not schema_id:
+        return {"success": False, "message": "缺少 Schema ID"}
+
+    schema_file = _find_schema_file(workspace_path, schema_id)
+    if not schema_file:
+        return {"success": False, "message": f"Schema 文件不存在: {schema_id}"}
+
+    try:
+        with FileLock(str(schema_file)):
+            with open(schema_file, encoding="utf-8") as f:
+                schema_data = yaml.safe_load(f) or {}
+
+            # 更新列定义
+            if columns is not None:
+                existing_cols = {c.get("name"): c for c in schema_data.get("columns", [])}
+                updated_cols = []
+                for col in columns:
+                    col_name = col.get("name", "")
+                    col_type = col.get("type", "string")
+                    if col_type not in VALID_DATA_TYPES:
+                        col_type = "string"
+                    if col_name in existing_cols:
+                        # 更新已有列
+                        existing = existing_cols[col_name]
+                        existing["type"] = col_type
+                        updated_cols.append(existing)
+                    else:
+                        # 新增列
+                        updated_cols.append(
+                            {
+                                "id": col_name,
+                                "name": col_name,
+                                "type": col_type,
+                            }
+                        )
+                # 保留未在更新列表中的列
+                updated_names = {c.get("name") for c in updated_cols}
+                for col in schema_data.get("columns", []):
+                    if col.get("name") not in updated_names:
+                        updated_cols.append(col)
+                schema_data["columns"] = updated_cols
+
+            # 更新数据源
+            if source is not None:
+                source_path = source.get("path", "")
+                if source_path and (".." in source_path or os.path.isabs(source_path)):
+                    return {"success": False, "message": "source.path 不允许绝对路径或目录穿越"}
+                schema_data["source"] = source
+
+            # §2.10: UPDATE 显式整体替换语义——preserve_format 默认 True 的递归合并
+            # "只增不删"，被删掉的列/字段会残留在文件里
+            atomic_write_yaml(schema_file, schema_data, preserve_format=False)
+
+    except Exception as e:
+        return {"success": False, "message": f"更新 Schema 失败: {e}"}
+
+    logger.info(f"[SchemaHandler] 更新 Schema: {schema_id}")
+    return {"success": True, "message": schema_id}
+
+
+def _delete_schema(spec: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """删除 Schema 文件"""
+    schema_id = spec.get("schemaId") or spec.get("id") or spec.get("name", "")
+    try:
+        schema_id = _sanitize_resource_id(schema_id)
+    except ValueError:
+        return {"success": False, "message": f"非法的 Schema ID: {schema_id}"}
+
+    if not schema_id:
+        return {"success": False, "message": "缺少 Schema ID"}
+
+    schema_file = _find_schema_file(workspace_path, schema_id)
+    if not schema_file:
+        return {"success": False, "message": f"Schema 文件不存在: {schema_id}"}
+
+    # §2.6: 删除前引用检查——与 REST DELETE /schemas/{id} 的 409 守卫同一套逻辑
+    # （公共函数 find_schema_references 单一事实源）。AI 不能成为绕开引用守卫的后门：
+    # 有引用时约束全部悬空，之后校验报"表不存在"而画布节点还在。
+    refs = find_schema_references(workspace_path, schema_id)
+    ref_report = format_reference_report(refs)
+    if ref_report:
+        return {
+            "success": False,
+            "message": (
+                f"Schema '{schema_id}' 仍被 {ref_report} 引用，请先删除这些引用再删除表"
+                "（可先逐一删除引用它的约束/正则/转换）"
+            ),
+        }
+
+    try:
+        schema_file.unlink()
+    except OSError as e:
+        return {"success": False, "message": f"删除 Schema 文件失败: {e}"}
+
+    # 从 manifest 移除引用 —— 失败时尝试恢复文件以保持一致，避免 dangling 引用
+    try:
+        _remove_manifest_schema_ref(workspace_path, schema_id)
+    except Exception as e:
+        logger.error(f"[SchemaHandler] 从 manifest 移除引用失败: {e}")
+        return {"success": False, "message": f"更新 manifest 引用失败，文件已删除但 manifest 残留: {e}"}
+
+    logger.info(f"[SchemaHandler] 删除 Schema: {schema_id}")
+    return {"success": True, "message": schema_id}
+
+
+def _find_schema_file(workspace_path: str, schema_id: str) -> Path | None:
+    """在工作区中查找 schema 文件"""
+    schemas_dir = Path(workspace_path) / "schemas"
+    if not schemas_dir.exists():
+        return None
+
+    # 先按 ID 精确匹配
+    for sf in schemas_dir.glob("*.yaml"):
+        try:
+            with open(sf, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+            if data.get("id") == schema_id or data.get("name") == schema_id:
+                return sf
+        except Exception:
+            continue
+
+    # 再按文件名匹配
+    candidate = schemas_dir / f"{schema_id}.schema.yaml"
+    if candidate.exists():
+        return candidate
+    candidate = schemas_dir / f"{schema_id}.yaml"
+    if candidate.exists():
+        return candidate
+
+    return None
+
+
+def _ensure_manifest_schema_ref(workspace_path: str, schema_id: str) -> None:
+    """确保 manifest 中包含指定 Schema 引用。
+
+    失败时抛出异常而非吞掉 —— 避免 schema 文件已写盘但 manifest 未登记，
+    从而产生孤儿文件（会触发后续 inspect 的 id 冲突 blocker）。
+    """
+    manifest_path = Path(workspace_path) / "project.precis.yaml"
+    if not manifest_path.exists():
+        return
+
+    manifest = load_manifest(manifest_path)
+    ensure_schema_ref(manifest, schema_id)
+    save_manifest(manifest, manifest_path)
+
+
+def _remove_manifest_schema_ref(workspace_path: str, schema_id: str) -> None:
+    """从 manifest 中移除指定 Schema 引用。
+
+    失败时抛出异常而非吞掉 —— 避免 schema 文件已删除但 manifest 仍残留引用，
+    从而产生 dangling 引用。
+    """
+    manifest_path = Path(workspace_path) / "project.precis.yaml"
+    if not manifest_path.exists():
+        return
+
+    manifest = load_manifest(manifest_path)
+    manifest.schemas = [s for s in manifest.schemas if s.id != schema_id]
+    save_manifest(manifest, manifest_path)

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

@@ -0,0 +1,180 @@
+# 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 生成的 UPDATE_SETTINGS 动作
+- 修改 project.precis.yaml 中的 settings 段
+- 支持三类设置：validation / file_processing / script_security
+
+架构设计:
+- 直接读写 project.precis.yaml 的 settings 字段
+- 使用 atomic_write_yaml 保证文件写入安全
+- 校验字段合法性
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, ValidationError
+
+from app.shared.core.project.manifest.types_parts.settings_file_processing import FileProcessingSettings
+from app.shared.core.project.manifest.types_parts.settings_script_security import ScriptSecuritySettings
+from app.shared.core.project.manifest.types_parts.settings_validation import ValidationSettings
+from app.shared.services.llm.yaml_io import FileLock, atomic_write_yaml
+
+logger = logging.getLogger(__name__)
+
+# 设置分类白名单从注册表派生（单一事实源）
+from app.shared.services.llm.actions.registry import SETTINGS_CATEGORIES as VALID_SETTINGS_CATEGORIES
+
+CATEGORY_TO_YAML_KEY = {
+    "validation": "validation",
+    "fileProcessing": "file_processing",
+    "scriptSecurity": "script_security",
+}
+
+# 分类 → manifest 设置模型：值域/类型的单一事实源是模型 Field 约束（C3 修复），
+# handler 校验与落盘前模型重建均以此为准，避免两套事实打架写坏 manifest。
+CATEGORY_TO_SETTINGS_MODEL: dict[str, type[BaseModel]] = {
+    "validation": ValidationSettings,
+    "fileProcessing": FileProcessingSettings,
+    "scriptSecurity": ScriptSecuritySettings,
+}
+
+VALID_ERROR_HANDLING = {"stop", "continue", "report"}
+VALID_ENCODINGS = {"utf-8", "gbk", "auto"}
+VALID_ALLOW_EVAL = {False}
+
+
+def process_settings_action(action: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """
+    @methoddesc 处理 UPDATE_SETTINGS 动作
+
+    根据 settingsSpec 中的 category 和 settings 更新项目配置。
+
+    参数:
+        action: 动作字典，包含 actionType 和 settingsSpec
+        workspace_path: 项目工作区路径
+
+    返回:
+        处理结果字典 {"success": bool, "message": str}
+    """
+    spec = action.get("settingsSpec", {})
+    category = spec.get("category", "")
+    settings = spec.get("settings", {})
+
+    if not category:
+        return {"success": False, "message": "缺少 settings category"}
+    if category not in VALID_SETTINGS_CATEGORIES:
+        return {"success": False, "message": f"未知的 settings category: {category}"}
+    if not settings:
+        return {"success": False, "message": "settings 不能为空"}
+
+    # 校验 settings 合法性
+    validation_errors = _validate_settings(category, settings)
+    if validation_errors:
+        return {"success": False, "message": f"设置校验失败: {'; '.join(validation_errors)}"}
+
+    manifest_path = Path(workspace_path) / "project.precis.yaml"
+    if not manifest_path.exists():
+        return {"success": False, "message": "project.precis.yaml 不存在"}
+
+    yaml_key = CATEGORY_TO_YAML_KEY[category]
+
+    try:
+        with FileLock(str(manifest_path)):
+            with open(manifest_path, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+
+            # 确保 settings 段存在
+            if "settings" not in data:
+                data["settings"] = {}
+
+            if yaml_key not in data["settings"]:
+                data["settings"][yaml_key] = {}
+
+            # 合并设置（不覆盖未指定的字段）
+            data["settings"][yaml_key].update(settings)
+
+            # C3: 落盘前经模型重建校验——非法值(如 sandbox_mode="strict"、
+            # timeout_seconds>300)直接落盘会导致下次加载 model_validate 422、
+            # 项目无法打开。模型是值域的单一事实源，merge 后的完整段必须能过模型。
+            model = CATEGORY_TO_SETTINGS_MODEL[category]
+            try:
+                model.model_validate(data["settings"][yaml_key])
+            except ValidationError as e:
+                return {"success": False, "message": f"设置校验失败: {e}"}
+
+            atomic_write_yaml(manifest_path, data)
+
+    except Exception as e:
+        return {"success": False, "message": f"更新项目设置失败: {e}"}
+
+    logger.info(f"[SettingsHandler] 更新设置: {category}")
+    return {"success": True, "message": f"settings.{category}"}
+
+
+def _validate_settings(category: str, settings: dict[str, Any]) -> list[str]:
+    """校验设置字段的合法性"""
+    errors = []
+
+    if category == "validation":
+        if "error_handling" in settings:
+            if settings["error_handling"] not in VALID_ERROR_HANDLING:
+                errors.append(f"error_handling 必须为: {', '.join(VALID_ERROR_HANDLING)}")
+        if "timeout_seconds" in settings:
+            val = settings["timeout_seconds"]
+            # 对齐 ValidationSettings: int 型, 1-300 (bool 是 int 子类,须显式排除)
+            if isinstance(val, bool) or not isinstance(val, int) or not 1 <= val <= 300:
+                errors.append("timeout_seconds 必须为 1-300 的整数")
+        if "batch_max_files" in settings:
+            val = settings["batch_max_files"]
+            # 对齐 ValidationSettings: int 型, 1-1000
+            if isinstance(val, bool) or not isinstance(val, int) or not 1 <= val <= 1000:
+                errors.append("batch_max_files 必须为 1-1000 的整数")
+
+    elif category == "fileProcessing":
+        if "default_encoding" in settings:
+            if settings["default_encoding"] not in VALID_ENCODINGS:
+                errors.append(f"default_encoding 必须为: {', '.join(VALID_ENCODINGS)}")
+        if "csv_delimiter" in settings:
+            val = settings["csv_delimiter"]
+            if not isinstance(val, str) or len(val) != 1:
+                errors.append("csv_delimiter 必须为单字符")
+
+    elif category == "scriptSecurity":
+        if "timeout_seconds" in settings:
+            val = settings["timeout_seconds"]
+            # 对齐 ScriptSecuritySettings: int 型, 1-60
+            if isinstance(val, bool) or not isinstance(val, int) or not 1 <= val <= 60:
+                errors.append("timeout_seconds 必须为 1-60 的整数")
+        if "allow_eval" in settings:
+            if settings["allow_eval"] not in VALID_ALLOW_EVAL:
+                errors.append("allow_eval 不允许通过 AI 修改")
+        if "sandbox_mode" in settings:
+            val = settings["sandbox_mode"]
+            # 对齐 ScriptSecuritySettings.sandbox_mode: bool 型——
+            # 旧白名单 {"strict","normal"} 与模型矛盾:唯一合法值 true 被拒、
+            # 非法字符串被放行,落盘后下次加载 model_validate 直接 422。
+            if not isinstance(val, bool):
+                errors.append("sandbox_mode 必须为布尔值")
+
+    return errors