precis-cli 0.1.3__py3-none-any.whl

app/shared/services/ai/agent/chat_tools/ask_user.py

@@ -0,0 +1,237 @@
+# 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 ask_user 工具
+
+Chat mini-agent 可调用的工具：在 loop 中途向用户提问。
+
+支持 4 种 question_type:
+1. free_text — 开放提问，用户输入任意文本
+2. choice — 消歧/选方案，单选或多选
+3. value — 补参数，结构化输入（带类型校验）
+4. confirm — 非写盘意图确认（yes/no）
+
+机制：
+- 创建 InteractionController，注册到 pending_interaction_store
+- emit user_input_requested 事件（前端渲染 AskUserCard）
+- await controller.await_response() 挂起（最多 5 分钟）
+- 用户通过 /respond 端点回答 → resolve 唤醒
+- observation {answer: ...} 或 {skipped: true} 回灌 LLM，loop 继续
+
+非流式环境（dry_run_enabled=False）fail-closed：不挂起，直接返回 unsupported。
+
+注意：InteractionController / get_global_pending_interaction_store 采用延迟导入
+（在 run() 内 import），与 apply_actions.py 一致，避免循环依赖：
+streaming/__init__ → orchestrator → chat_tools/__init__ → ask_user → streaming
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# 允许的提问类型
+_QUESTION_TYPES = ("free_text", "choice", "value", "confirm")
+# value 类型允许的值类型
+_VALUE_TYPES = ("string", "integer", "float", "boolean")
+
+
+@dataclass
+class AskCallbacks:
+    """ask_user 工具的回调集合，由 orchestrator 注入以实现事件桥接。"""
+
+    on_user_input_requested: Callable[[dict[str, Any]], None] | None = None
+    on_user_responded: Callable[[dict[str, Any]], None] | None = None
+
+
+class AskUserTool:
+    """让 agent 在 loop 中途向用户提问。"""
+
+    NAME = "ask_user"
+
+    def __init__(
+        self,
+        job_id: str,
+        ask_callbacks: AskCallbacks | None = None,
+        dry_run_enabled: bool = False,
+    ):
+        """
+        @methoddesc 初始化工具
+
+        参数:
+            job_id: 当前任务 ID，用于生成 ask_id（"{job_id}#ask#{seq}"）
+            ask_callbacks: 事件回调集合
+            dry_run_enabled: 是否启用交互（仅流式路径 True；非流式 fail-closed）
+        """
+        self._job_id = job_id
+        self._ask_callbacks = ask_callbacks or AskCallbacks()
+        self._dry_run_enabled = dry_run_enabled
+        self._ask_counter = 0
+
+    def get_definition(self) -> dict[str, Any]:
+        """返回 OpenAI tool 定义。"""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.NAME,
+                "description": (
+                    "向用户提问以获取澄清、消歧或缺失信息。仅当无法通过 read_project/read_table/read_canvas "
+                    "自行获取信息、或存在多方案需要用户抉择时调用。能自己查到的不要问。"
+                    "返回用户的回答或 skipped=true（用户跳过/超时/环境不支持）。"
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "question_type": {
+                            "type": "string",
+                            "enum": list(_QUESTION_TYPES),
+                            "description": "提问类型",
+                        },
+                        "prompt": {
+                            "type": "string",
+                            "description": "给用户看的问题文本",
+                        },
+                        "options": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "label": {"type": "string"},
+                                    "value": {"type": "string"},
+                                    "description": {"type": "string"},
+                                },
+                                "required": ["label", "value"],
+                            },
+                            "description": "choice 类型必填：候选项列表",
+                        },
+                        "multiple": {
+                            "type": "boolean",
+                            "description": "choice 类型：是否多选（默认 false）",
+                        },
+                        "value_type": {
+                            "type": "string",
+                            "enum": list(_VALUE_TYPES),
+                            "description": "value 类型必填：期望的值类型",
+                        },
+                        "placeholder": {
+                            "type": "string",
+                            "description": "输入框占位提示（可选，free_text/value 用）",
+                        },
+                        "optional": {
+                            "type": "boolean",
+                            "description": "value 类型：是否允许留空（默认 false）",
+                        },
+                    },
+                    "required": ["question_type", "prompt"],
+                },
+            },
+        }
+
+    def _validate_args(self, arguments: dict[str, Any]) -> str | None:
+        """校验参数完整性。返回错误描述或 None。"""
+        qt = arguments.get("question_type")
+        if qt not in _QUESTION_TYPES:
+            return f"非法 question_type: {qt}"
+        if qt == "choice":
+            opts = arguments.get("options")
+            if not opts or not isinstance(opts, list) or len(opts) < 1:
+                return "choice 类型必须提供至少一个 options"
+        if qt == "value":
+            vt = arguments.get("value_type")
+            if vt not in _VALUE_TYPES:
+                return "value 类型必须提供合法 value_type"
+        return None
+
+    async def run(self, arguments: dict[str, Any]) -> dict[str, Any]:
+        """
+        @methoddesc 执行提问
+
+        参数:
+            arguments: tool 参数，含 question_type/prompt 及类型相关字段
+
+        返回:
+            {"success": bool, "answer": {...}}
+            answer 为用户回答 {answer: ...} 或跳过 {skipped: true, reason: ...}
+        """
+        question_type = arguments.get("question_type")
+        prompt = arguments.get("prompt", "")
+
+        # 参数校验
+        err = self._validate_args(arguments)
+        if err:
+            logger.warning("[ask_user] 参数校验失败: %s", err)
+            return {
+                "success": False,
+                "error": err,
+                "answer": {"skipped": True, "reason": "bad_args"},
+            }
+
+        # 非流式环境 fail-closed
+        if not self._dry_run_enabled:
+            return {
+                "success": False,
+                "unsupported": True,
+                "error": "此环境不支持交互问答，请基于已知信息回答",
+                "answer": {"skipped": True, "reason": "unsupported_env"},
+            }
+
+        # 延迟导入避免循环依赖（streaming/__init__ → orchestrator → chat_tools → streaming）
+        # 与 apply_actions.py 的 _run_two_phase 一致：在方法内 import
+        from app.shared.services.ai.streaming.pending_interaction_store import (
+            InteractionController,
+            get_global_pending_interaction_store,
+        )
+
+        # 创建门控，生成独立 ask_id
+        self._ask_counter += 1
+        ask_id = f"{self._job_id}#ask#{self._ask_counter}" if self._job_id else f"ask#{self._ask_counter}"
+        controller = InteractionController(request_id=ask_id, pending_payload=arguments)
+        store = get_global_pending_interaction_store()
+        store.put(ask_id, controller)
+
+        try:
+            # emit user_input_requested（携带 question schema 给前端）
+            request_payload: dict[str, Any] = {
+                "ask_id": ask_id,
+                "question_type": question_type,
+                "prompt": prompt,
+            }
+            for k in ("options", "multiple", "value_type", "placeholder", "optional"):
+                if k in arguments:
+                    request_payload[k] = arguments[k]
+
+            if self._ask_callbacks.on_user_input_requested:
+                self._ask_callbacks.on_user_input_requested(request_payload)
+
+            # 挂起等待用户回答
+            response = await controller.await_response()
+
+            # emit user_responded（让前端清态）
+            if self._ask_callbacks.on_user_responded:
+                self._ask_callbacks.on_user_responded(
+                    {
+                        "ask_id": ask_id,
+                        "response": response,
+                    }
+                )
+
+            return {"success": True, "answer": response}
+        finally:
+            # 无论回答/跳过/超时/异常，都清理本次 ask 的 controller
+            store.pop(ask_id)

app/shared/services/ai/agent/chat_tools/read_canvas.py

@@ -0,0 +1,140 @@
+# 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 read_canvas 工具
+
+Chat mini-agent 可调用的工具：读取当前画布上实际显示的节点快照。
+
+与 read_project 的关键区别：
+- read_project 读项目配置文件（YAML），返回"项目里配置了什么"。
+- read_canvas 读请求时前端带来的画布快照，返回"画布上现在显示什么"。
+按项目架构，Schema/Constraint/Regex 节点不自动加载到画布，
+故两者会分叉——判断"画布上有没有 X"必须用本工具。
+
+无 project_path 依赖：画布数据在 runner 构造时已注入（来自请求体 canvasNodes 字段）。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# 画布上需要计数的业务节点类型前缀/集合，用于生成 summary
+_CONSTRAINT_TYPE_SUFFIX = "Constraint"
+_SCHEMA_TYPES = frozenset({"schema", "jsonSchema"})
+_SOURCE_TYPES = frozenset({"sourcePreview", "jsonSourcePreview"})
+
+
+def _summarize_canvas(nodes: list[dict[str, Any]]) -> dict[str, int]:
+    """统计画布快照中各类业务节点的数量，便于 LLM 快速判断。"""
+    schema_count = 0
+    constraint_count = 0
+    regex_count = 0
+    transform_count = 0
+    other_count = 0
+
+    for n in nodes:
+        ntype = n.get("type", "")
+        if ntype in _SCHEMA_TYPES:
+            schema_count += 1
+        elif ntype.endswith(_CONSTRAINT_TYPE_SUFFIX):
+            constraint_count += 1
+        elif ntype == "regex":
+            regex_count += 1
+        elif ntype in ("transform", "transformOutput"):
+            transform_count += 1
+        else:
+            other_count += 1
+
+    return {
+        "total": len(nodes),
+        "schema_count": schema_count,
+        "constraint_count": constraint_count,
+        "regex_count": regex_count,
+        "transform_count": transform_count,
+        "other_count": other_count,
+    }
+
+
+class ReadCanvasTool:
+    """
+    @classdesc 读取画布节点快照工具
+
+    返回当前画布上实际显示的节点（由前端在请求体携带），
+    区别于 read_project 返回的项目配置文件内容。
+    """
+
+    NAME = "read_canvas"
+
+    def __init__(self, canvas_nodes: list[dict[str, Any]] | None = None):
+        """
+        @methoddesc 初始化工具
+
+        参数:
+            canvas_nodes: 前端在请求体携带的画布节点快照（已裁剪）。
+                runner 构造时注入；None/空视为空画布。
+        """
+        # 防御性拷贝：避免外部 mutate 影响工具内视图
+        self._canvas_nodes: list[dict[str, Any]] = list(canvas_nodes) if canvas_nodes else []
+
+    def get_definition(self) -> dict[str, Any]:
+        """返回 OpenAI tool 定义。"""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.NAME,
+                "description": (
+                    "读取当前**画布上实际显示**的节点列表（Schema、约束、正则、转换等），"
+                    "含每类节点数量摘要。"
+                    "本工具返回的是画布快照，与 read_project 读项目配置文件不同——"
+                    "项目配置里有的表/约束不一定已拖到画布上。"
+                    "当用户说'画布上有没有 X'、'把 Y 放到画布/拖到画布'、"
+                    "'画布上现在有什么'时，先调用本工具确认画布真实状态，再决定是否需要 ADD 动作。"
+                    "无需参数。"
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                },
+            },
+        }
+
+    async def run(self, arguments: dict[str, Any]) -> dict[str, Any]:
+        """
+        @methoddesc 返回画布节点快照与摘要
+
+        参数:
+            arguments: tool 参数（本工具无参数，保留接口一致性）
+
+        返回:
+            {"success": bool, "canvas_nodes": [...], "summary": {...}, "error": str}
+            canvas_nodes 为前端裁剪后的节点摘要列表；空画布返回空列表而非错误。
+        """
+        # 本工具无参数，arguments 仅保留接口一致性
+        _ = arguments
+
+        try:
+            summary = _summarize_canvas(self._canvas_nodes)
+            return {
+                "success": True,
+                "canvas_nodes": self._canvas_nodes,
+                "summary": summary,
+            }
+        except Exception as e:
+            logger.exception("read_canvas 工具执行失败")
+            return {"success": False, "error": f"读取画布快照失败: {e}", "canvas_nodes": [], "summary": {}}

app/shared/services/ai/agent/chat_tools/read_project.py

@@ -0,0 +1,160 @@
+# 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 read_project 工具
+
+Chat mini-agent 可调用的工具：读取当前项目的完整概览。
+
+返回项目中的所有表结构、约束、转换、正则节点和设置信息，
+供 LLM 了解"当前项目里有什么"，从而决定后续操作。
+
+体积控制：大项目的 overview 可能几万字符，直接全量返回会被 memory 的 8000 字符硬切
+在 JSON 中途，破坏结构、让 LLM 拿到半截数据。本工具在返回前做语义截断：
+schemas/constraints/transforms/regex_nodes 各保留前 N 项 + 计数，每张表的 columns
+也只列前 N 个，让 LLM 既能判断项目规模，又能在需要详情时调 read_table。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from app.shared.services.ai.utils import get_project_overview
+
+logger = logging.getLogger(__name__)
+
+# 语义截断阈值（参考 validate_table 的"列表前 N 项 + 计数"模式）。
+# 目标：截断后 observation 控制在 memory 8000 字符硬切线以内，且仍是合法 JSON。
+_MAX_SCHEMAS_IN_OBSERVATION = 20
+_MAX_CONSTRAINTS_IN_OBSERVATION = 30
+_MAX_OTHER_NODES_IN_OBSERVATION = 10  # transforms / regex_nodes 共用
+_MAX_COLUMNS_PER_SCHEMA = 50
+
+
+class ReadProjectTool:
+    """
+    @classdesc 读取项目概览工具
+
+    封装 get_project_overview，返回项目的结构信息（大项目自动语义截断）。
+    不接收任何参数——它读取的就是 runner 绑定的当前项目。
+    """
+
+    NAME = "read_project"
+
+    def __init__(self, project_path: str):
+        """
+        @methoddesc 初始化工具
+
+        参数:
+            project_path: 当前项目配置目录路径
+        """
+        self.project_path = project_path
+
+    def get_definition(self) -> dict[str, Any]:
+        """返回 OpenAI tool 定义。"""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.NAME,
+                "description": (
+                    "读取当前项目的完整概览，包括所有表结构(schemas)、约束规则(constraints)、"
+                    "数据转换(transforms)、正则节点(regex)和项目设置(settings)。"
+                    "当用户询问'有哪些表'、'某个表有哪些约束'、'当前项目配置'等查询类问题时，"
+                    "先调用此工具获取信息，再用自然语言回答。无需参数。"
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {},
+                    "required": [],
+                },
+            },
+        }
+
+    @staticmethod
+    def _truncate_overview(overview: dict[str, Any]) -> dict[str, Any]:
+        """对 overview 做语义截断，避免 observation 过大被 memory 硬切破坏 JSON 结构。
+
+        截断策略：各资源列表保留前 N 项，并附 truncated_*_count 告知 LLM "还有更多"；
+        schemas 的 columns 也只列前 N 个（大宽表的关键体积来源）。
+        小项目（各项均未超阈值）原样返回，零影响。
+        """
+        schemas = overview.get("schemas", [])
+        truncated_schemas: list[dict[str, Any]] = []
+        truncated_column_total = 0
+        for schema in schemas[:_MAX_SCHEMAS_IN_OBSERVATION]:
+            cols = schema.get("columns", [])
+            if len(cols) > _MAX_COLUMNS_PER_SCHEMA:
+                truncated_column_total += len(cols) - _MAX_COLUMNS_PER_SCHEMA
+                schema = {**schema, "columns": cols[:_MAX_COLUMNS_PER_SCHEMA]}
+            truncated_schemas.append(schema)
+
+        constraints = overview.get("constraints", [])
+        transforms = overview.get("transforms", [])
+        regex_nodes = overview.get("regex_nodes", [])
+
+        result: dict[str, Any] = {
+            "schemas": truncated_schemas,
+            "constraints": constraints[:_MAX_CONSTRAINTS_IN_OBSERVATION],
+            "transforms": transforms[:_MAX_OTHER_NODES_IN_OBSERVATION],
+            "regex_nodes": regex_nodes[:_MAX_OTHER_NODES_IN_OBSERVATION],
+            "settings": overview.get("settings", {}),
+        }
+
+        # 截断计数：让 LLM 知道被省略了多少，需要详情时调 read_table
+        result["truncated_schema_count"] = max(0, len(schemas) - _MAX_SCHEMAS_IN_OBSERVATION)
+        result["truncated_constraint_count"] = max(0, len(constraints) - _MAX_CONSTRAINTS_IN_OBSERVATION)
+        result["truncated_transform_count"] = max(0, len(transforms) - _MAX_OTHER_NODES_IN_OBSERVATION)
+        result["truncated_regex_count"] = max(0, len(regex_nodes) - _MAX_OTHER_NODES_IN_OBSERVATION)
+        result["truncated_column_count"] = truncated_column_total
+        return result
+
+    async def run(self, arguments: dict[str, Any]) -> dict[str, Any]:
+        """
+        @methoddesc 执行项目概览读取
+
+        参数:
+            arguments: tool 参数（本工具无参数）
+
+        返回:
+            {"success": bool, "overview": {...}, "summary": {...}, "error": str}
+            overview 形如 {"schemas": [...], "constraints": [...], "transforms": [...],
+            "regex_nodes": [...], "settings": {...}, "truncated_*_count": int}
+            大项目会语义截断（列表前 N 项 + 计数），详见 _truncate_overview。
+        """
+        # arguments 无参数，但保留接口一致性
+        _ = arguments
+
+        if not self.project_path:
+            return {"success": False, "error": "未配置项目路径", "overview": {}}
+
+        try:
+            # get_project_overview 是同步函数，放到线程池避免阻塞事件循环
+            raw_overview = await asyncio.to_thread(get_project_overview, self.project_path)
+
+            # 语义截断，避免 observation 被 memory 硬切破坏 JSON
+            overview = self._truncate_overview(raw_overview)
+
+            # 统计摘要（基于截断前的真实数量，让 LLM 判断项目真实规模）
+            summary = {
+                "schema_count": len(raw_overview.get("schemas", [])),
+                "constraint_count": len(raw_overview.get("constraints", [])),
+                "transform_count": len(raw_overview.get("transforms", [])),
+                "regex_count": len(raw_overview.get("regex_nodes", [])),
+            }
+            return {"success": True, "overview": overview, "summary": summary}
+        except Exception as e:
+            logger.exception("read_project 工具执行失败")
+            return {"success": False, "error": f"读取项目概览失败: {e}", "overview": {}}