precis-cli 0.1.8__tar.gz → 0.1.9__tar.gz

{precis_cli-0.1.8/precis_cli.egg-info → precis_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: precis-cli
-Version: 0.1.8
+Version: 0.1.9
 Summary: Precis - 可配置数据校验工具 CLI（校验 CSV/Excel/JSON 数据质量）
 Author: Precis Team
 License: Apache-2.0

{precis_cli-0.1.8 → precis_cli-0.1.9}/app/api/models/projects.py

@@ -78,3 +78,15 @@ class CloseProjectResponse(BaseModel):
     """关闭项目的响应。"""
 
     success: bool
+
+
+class CheckProjectResponse(BaseModel):
+    """项目探测端点（GET /projects/check）的响应。
+
+    设计约束：对合法输入一律 200，探测结果用布尔字段表达——前端「智能打开」
+    用它预判目录是否为项目根，避免探测请求在浏览器控制台留下 404 红字。
+    """
+
+    path: str
+    dir_exists: bool
+    is_project: bool

{precis_cli-0.1.8 → precis_cli-0.1.9}/app/api/routers/ai/models.py

@@ -39,7 +39,7 @@
         manifest: Optional[dict[str, Any]] = None
 """
 
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -110,7 +110,9 @@ class AiChatRequest(BaseModel):
 class AiChatConfirmRequest(BaseModel):
     """AI Chat apply_actions 确认/拒绝请求"""
 
-    decision: str = Field(..., description="confirm(确认并落盘)或 reject(拒绝,不落盘)")
+    # Literal 枚举：非法值（如 "yes"/"ok"）由 Pydantic 自动 422 并回显合法值集合，
+    # 不再被静默当作 reject 处理
+    decision: Literal["confirm", "reject"] = Field(..., description="confirm(确认并落盘)或 reject(拒绝,不落盘)")
     apply_id: str | None = Field(
         default=None,
         description="本次 apply 的 ID（{job_id}#{seq}）。为空时回退到该 job 当前唯一挂起项。",

{precis_cli-0.1.8 → precis_cli-0.1.9}/app/api/routers/ai/stream.py

@@ -27,7 +27,12 @@
 - 取消信号: 内存中 _cancel_events 字典(job_id → asyncio.Event)
 - Last-Event-ID: 仅作为本连接内 journal 回放的起始游标（§2.8）；不支持跨连接断线续传——
   每次请求都新建 job_id 与 journal,重连等价于重新发起会话(真续传需 job 持久化+按 job_id 重连端点,属未来 feature)
-- 资源清理: orchestrator 结束后注销 cancel_event,防止内存泄漏
+- SSE 断开宽限期: 客户端断开不取消后台任务(网络抖动/休眠/组件卸载等瞬断不应软取消
+  整个 job)；任务继续运行至终态事件或挂起确认自然超时,EventJournal 持续落盘。
+  断开仅登记"客户端失联",让等待中的 apply/ask 超时兜底按"连接中断"回灌文案；
+  显式取消走 /jobs/{job_id}/cancel 端点(行为不变)
+- 资源清理: orchestrator 结束后注销 cancel_event,防止内存泄漏——
+  cancel_event 的存续期等于后台 task 生命周期(宽限期内 task 未结束则保留,属在用而非泄漏)
 """
 
 from __future__ import annotations
@@ -67,6 +72,12 @@ _cancel_events_lock = threading.Lock()
 # task 完成后通过 add_done_callback 自动从集合移除
 _background_tasks: set[asyncio.Task[None]] = set()
 
+# 实时事件队列容量上限：journal 是权威全量记录（终止事件携带完整快照兜底），
+# 丢实时帧只影响投递即时性、无正确性影响；而 SSE 断开宽限期内（挂起确认 300s × N +
+# LLM 流式）队列无人消费，无界队列会让 delta/tool 事件持续内存积压。
+# 有界后 orchestrator.emit 的 QueueFull 丢弃守卫被激活：满员丢实时帧、journal 照常落盘
+_EVENT_QUEUE_MAXSIZE = 1000
+
 # journal 存储目录基础(按项目 config_path 分片),复用 AgentJobStorage 的 .precis 约定
 # 实际路径在端点中按 project_path 拼接
 
@@ -89,6 +100,41 @@ def _journal_dir_for(project_path: str | None) -> str:
     return os.path.join(os.path.expanduser("~"), ".precis", "stream_jobs")
 
 
+async def _sse_frames_with_disconnect_grace(
+    job_id: str,
+    journal: EventJournal,
+    last_event_id: int,
+    event_queue: asyncio.Queue[dict[str, Any]],
+) -> AsyncIterator[str]:
+    """@methoddesc SSE 帧生成器（断开宽限期语义）
+
+    与旧实现的差异：客户端断开时不再 cancel_event.set()——瞬断（网络抖动/系统休眠/
+    IDE↔Agent 模式切换卸载组件）不应软取消整个后台任务。任务继续运行至终态事件
+    （completed/error/cancelled）或挂起确认自然超时（300s），期间 EventJournal 持续
+    落盘（重连回放/事后审计的前提），confirm/respond 端点仍可决议挂起交互。
+
+    断开时只做一件事：登记该 job 客户端失联（mark_job_client_gone），使等待中的
+    apply 确认/ask 提问在超时兜底时按"连接中断"（decision=disconnected）而非
+    "用户拒绝/跳过"回灌文案。显式取消走 /jobs/{job_id}/cancel 端点，行为不变。
+    """
+    completed_normally = False
+    try:
+        async for frame in sse_event_stream(
+            journal=journal,
+            last_event_id=last_event_id,
+            event_queue=event_queue,
+        ):
+            yield frame
+        # 流自然耗尽 == 已投递终态事件（sse_event_stream 仅在终态后结束）：
+        # 任务已结束、挂起交互已决议，无需登记失联
+        completed_normally = True
+    finally:
+        # 仅异常终止（客户端断开触发 GeneratorExit/CancelledError、流内部异常）
+        # 才登记失联；正常收尾不登记，避免给每个已完成 job 留下失联残影
+        if not completed_normally:
+            get_global_pending_interaction_store().mark_job_client_gone(job_id)
+
+
 @router.post("/chat/stream", summary="AI 聊天流式接口(SSE)")
 async def chat_stream(
     request: AiChatRequest,
@@ -148,8 +194,10 @@ async def chat_stream(
     canvas_nodes = [node.model_dump() for node in request.context.canvasNodes]
     history = [{"role": h.role, "content": h.content} for h in (request.history or [])]
 
-    # 实时事件队列: orchestrator emit 时推入, sse_event_stream 消费
-    event_queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+    # 实时事件队列: orchestrator emit 时推入, sse_event_stream 消费。
+    # 有界（_EVENT_QUEUE_MAXSIZE）：宽限期内无人消费时不内存积压，
+    # 满员由 emit 侧丢弃实时帧（journal 仍是权威全量记录）
+    event_queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=_EVENT_QUEUE_MAXSIZE)
 
     orchestrator = StreamingOrchestrator(
         job_id=job_id,
@@ -177,21 +225,17 @@ async def chat_stream(
     _background_tasks.add(task)
     task.add_done_callback(_background_tasks.discard)
 
-    # 返回 SSE 流: 先回放 journal(本连接内,自 last_event_id 起), 再实时推送队列
-    async def _sse_generator() -> AsyncIterator[str]:
-        try:
-            async for frame in sse_event_stream(
-                journal=journal,
-                last_event_id=last_event_id,
-                event_queue=event_queue,
-            ):
-                yield frame
-        finally:
-            # 客户端断连时（StreamingResponse 被取消），通知后台 task 停止
-            # 这让 executor 在下一个取消检查点中断，避免后台 task 泄漏
-            cancel_event.set()
-
-    return StreamingResponse(_sse_generator(), media_type="text/event-stream")
+    # 返回 SSE 流: 先回放 journal(本连接内,自 last_event_id 起), 再实时推送队列。
+    # 生成器含断开宽限期语义：断开不取消后台任务（见 _sse_frames_with_disconnect_grace）
+    return StreamingResponse(
+        _sse_frames_with_disconnect_grace(
+            job_id=job_id,
+            journal=journal,
+            last_event_id=last_event_id,
+            event_queue=event_queue,
+        ),
+        media_type="text/event-stream",
+    )
 
 
 @router.post("/jobs/{job_id}/cancel", summary="取消正在运行的 AI job(软取消)")
@@ -234,7 +278,8 @@ async def confirm_apply(job_id: str, request: AiChatConfirmRequest) -> dict[str,
 
     参数:
         job_id: 任务 ID
-        request: 含 decision 字段("confirm" 或 "reject")
+        request: 含 decision 字段("confirm" 或 "reject"；非法值由 Pydantic 校验
+                 返回 422 并回显合法值集合)
 
     返回:
         {"status": "resolved", "decision": "confirm"} 或 404

{precis_cli-0.1.8 → precis_cli-0.1.9}/app/api/routers/projects/__init__.py

@@ -17,9 +17,10 @@
 
 from fastapi import APIRouter
 
-from . import create, open, scan
+from . import check, create, open, scan
 
 router = APIRouter(prefix="/api/latest/projects", tags=["Projects"])
 router.include_router(scan.router)
 router.include_router(open.router)
 router.include_router(create.router)
+router.include_router(check.router)

precis_cli-0.1.9/app/api/routers/projects/check.py

@@ -0,0 +1,62 @@
+# 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 项目探测路由：只读判断目录是否为合法 Precis 项目根
+
+功能概述:
+- GET /api/latest/projects/check?path=<绝对路径>
+- 供前端「智能打开」（useSmartProjectOpen）在引导就地新建前探测目录
+
+架构设计:
+- 与 open.py/create.py 对称，但**永不 404**：空目录/不存在的目录都用布尔
+  字段表达（dir_exists/is_project），浏览器控制台不会因探测留下 404 红字；
+  仅非法输入（相对路径/路径穿越）返回 400
+- 路径经 query 参数传递（UTF-8 自动编解码），无 X-Project-Config-Path
+  header 的 latin-1 编码问题
+- 不经 get_project_config_path 依赖（该依赖对缺 manifest 的目录抛 404，
+  正是本端点要避免的语义）
+"""
+
+from __future__ import annotations
+
+import os
+
+from fastapi import APIRouter, HTTPException, Query
+
+from app.api.models.projects import CheckProjectResponse
+
+router = APIRouter(prefix="", tags=["Projects-Check"])
+
+
+@router.get(
+    "/check",
+    response_model=CheckProjectResponse,
+    summary="探测目录是否为 Precis 项目（永不 404）",
+)
+def check_project(path: str = Query(..., description="待探测的目录绝对路径")) -> CheckProjectResponse:
+    """只读探测目录状态，不创建、不修改任何文件，不改变"当前项目"。"""
+    # 输入校验与 get_project_config_path 同规：先拒绝相对路径（Windows 下
+    # abspath 会把相对路径解析成绝对路径，必须先判 isabs），再防路径穿越
+    if not os.path.isabs(path):
+        raise HTTPException(status_code=400, detail="path 必须是一个绝对路径。")
+
+    normalized = os.path.abspath(os.path.normpath(path))
+    if ".." in normalized.split(os.sep):
+        raise HTTPException(status_code=400, detail="path 不允许包含 .. 目录穿越。")
+
+    dir_exists = os.path.isdir(normalized)
+    is_project = os.path.isfile(os.path.join(normalized, "project.precis.yaml"))
+    return CheckProjectResponse(path=normalized, dir_exists=dir_exists, is_project=is_project)

{precis_cli-0.1.8 → precis_cli-0.1.9}/app/cli/shell/commands/ai/agent_interaction.py

@@ -157,11 +157,27 @@ def _print_ask_question(payload: dict[str, Any]) -> None:
     options = payload.get("options")
     if isinstance(options, list) and options:
         for idx, opt in enumerate(options, start=1):
-            print(f"  {idx}. {opt}")
+            _, text = _split_option(opt)
+            print(f"  {idx}. {text}")
     if payload.get("optional"):
         print(Formatter.info("  （直接回车跳过此问题）"))
 
 
+def _split_option(opt: Any) -> tuple[str, str]:
+    """解析单个选项为 (value, 展示文本)。
+
+    ask_user 工具 schema 声明 options 为 {label, value, description?} 对象；
+    纯字符串形态（历史/测试用例）兼容处理，value 即字符串本身。
+    """
+    if isinstance(opt, dict):
+        value = str(opt.get("value", opt.get("label", "")))
+        label = str(opt.get("label", value))
+        desc = str(opt.get("description") or "")
+        text = f"{label} — {desc}" if desc else label
+        return value, text
+    return str(opt), str(opt)
+
+
 def _read_ask_response(payload: dict[str, Any]) -> dict[str, Any]:
     """按 question_type 读取终端回答，构造 AskResponseBody 形态。
 
@@ -182,7 +198,8 @@ def _read_ask_response(payload: dict[str, Any]) -> dict[str, Any]:
             picked: list[str] = []
             for part in indexes:
                 if part.isdigit() and 1 <= int(part) <= len(options):
-                    picked.append(str(options[int(part) - 1]))
+                    # 按编号选中：回灌选项的 value 字段（与前端 AskUserCard 契约一致）
+                    picked.append(_split_option(options[int(part) - 1])[0])
                 else:
                     picked.append(part)
             if payload.get("multiple"):

{precis_cli-0.1.8 → precis_cli-0.1.9}/app/cli/shell/commands/ai/executor.py

@@ -18,6 +18,7 @@
 功能概述:
 - 执行 AI 聊天命令的主入口
 - 辅助函数已拆分到 executor_utils.py / diff.py / display.py
+- agent 模式经 ChatStreamRenderer（stream_renderer.py）接终端流式渲染
 """
 
 from __future__ import annotations
@@ -39,6 +40,7 @@ from .executor_utils import (
 )
 from .interaction import confirm_actions as base_confirm_actions
 from .resolver import resolve_ambiguities as base_resolve_ambiguities
+from .stream_renderer import ChatStreamRenderer
 
 # 为模型回复预留的 token 预算
 RESERVED_OUTPUT_TOKENS = 8000
@@ -134,6 +136,10 @@ def execute_ai_chat(
 
         agent_apply_callbacks, agent_ask_callbacks = build_agent_interaction(spinner)
 
+    # 流式渲染器：agent 模式把 runner 的 on_chunk/on_tool_* 回调接到终端，
+    # LLM 逐字输出与工具过程实时可见；legacy JSON 路径无流式管道，保持原 spinner 体验
+    stream_renderer = ChatStreamRenderer(spinner=spinner, interactive=interactive) if agent_mode else None
+
     # 配置对话选项
     options = ChatOptions(
         history=history or [],
@@ -149,6 +155,7 @@ def execute_ai_chat(
         apply_callbacks=agent_apply_callbacks,
         ask_callbacks=agent_ask_callbacks,
         dry_run_enabled=agent_apply_callbacks is not None,
+        agent_stream_callbacks=stream_renderer.callbacks() if stream_renderer else None,
     )
 
     try:
@@ -166,19 +173,26 @@ def execute_ai_chat(
             spinner.start()
 
         # 执行 AI 对话（CLI 是同步环境：asyncio.run 创建一次性事件循环并在结束时确保关闭，
-        # 不再使用已弃用的 get_event_loop + run_until_complete，避免循环泄漏）
-        result = asyncio.run(
-            orchestrator.execute_chat(
-                message=message,
-                project_path=project_path,
-                context_nodes=context_nodes,
-                options=options,
+        # 不再使用已弃用的 get_event_loop + run_until_complete，避免循环泄漏）。
+        # 收尾走 finally：流式中途 Ctrl+C 等任何退出路径（含 BaseException）都先 finish
+        # 再 stop——spinner.stop 的清行序列从行首覆盖，必须保证光标已落在干净行首
+        try:
+            result = asyncio.run(
+                orchestrator.execute_chat(
+                    message=message,
+                    project_path=project_path,
+                    context_nodes=context_nodes,
+                    options=options,
+                )
             )
-        )
+        finally:
+            # 收尾流式文本行（先于 spinner.stop，顺序不可颠倒）
+            if stream_renderer:
+                stream_renderer.finish()
 
-        # 停止 spinner 动画
-        if spinner:
-            spinner.stop()
+            # 停止 spinner 动画
+            if spinner:
+                spinner.stop()
 
         # 处理结果：如果失败则返回错误
         if not result.success:
@@ -189,11 +203,12 @@ def execute_ai_chat(
 
         reply = result.reply
         actions = result.actions
+        # 流式已把最终回复逐字上屏时不再整段重复打印（多轮中间文本已由 on_turn 重置排除）
+        reply_streamed = bool(stream_renderer and stream_renderer.final_reply_already_shown(reply))
 
         # 在交互模式下显示 AI 的文本回复
-        if interactive:
-            if reply:
-                print(reply)
+        if interactive and reply and not reply_streamed:
+            print(reply)
 
         # 在交互模式下显示 Agent 工具轨迹（仅 Agent 模式有 tool_steps）
         if interactive and agent_mode and result.tool_steps:
@@ -208,7 +223,8 @@ def execute_ai_chat(
             _display_execution_results(result, project_path, original_files_cache)
 
         return CommandResult.ok(
-            reply if not interactive else "",
+            # 非交互（ai ask）单发模式由 main 打印 message：流式已输出过回复时置空避免重复
+            "" if interactive or reply_streamed else reply,
             data={
                 "reply": reply,
                 "actions": actions,
@@ -217,10 +233,7 @@ def execute_ai_chat(
         )
 
     except Exception as e:
-        # 发生异常时确保 spinner 停止，避免动画残留
-        if spinner:
-            spinner.stop()
-
+        # 流式收尾与 spinner 停止已由内层 finally 覆盖（任何退出路径），此处只做错误呈现
         logger.error(f"AI 对话失败: {e}", exc_info=True)
         error_msg = f"AI 对话失败: {str(e)}"
 

precis_cli-0.1.9/app/cli/shell/commands/ai/stream_renderer.py

@@ -0,0 +1,188 @@
+# 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.
+# backend/app/cli/shell/commands/ai/stream_renderer.py
+"""
+@fileoverview CLI 终端流式渲染器（AI agent 聊天）
+
+功能概述:
+- 把 ChatAgentRunner 的流式回调（on_chunk/on_turn/on_tool_call/on_tool_result）渲染到终端
+- LLM 文本逐字增量打印（flush 即时），工具调用/结果打紧凑单行状态
+- 首个内容事件到达后永久停掉 spinner——流式反馈本身即"进行中"提示
+
+渲染协调（三个交互点）:
+- spinner: 首个 chunk / 工具事件停掉 spinner（spinner.stop 的清行序列会从行首覆盖，
+  调用前必须保证光标已落在干净行首，否则抹掉未换行的流式文本）
+- 交互提示（两阶段确认 / ask_user）: 提示在工具执行期触发，而 on_tool_call 先于工具执行
+  收尾换行，故提示出现时流式文本已完整落行，不粘连
+- 工具轨迹: 流式期间只给轻量单行状态；循环结束后的 _display_tool_trail 总结保留，
+  两者角色不同（实时进度 vs 结束审计），不视为重复
+
+输入示例:
+    renderer = ChatStreamRenderer(spinner=spinner, interactive=True)
+    options = ChatOptions(..., agent_stream_callbacks=renderer.callbacks())
+
+输出示例:
+    → 调用工具 修改配置...
+    ✓ 修改配置 完成
+    已为 users.nickname 创建 chinese_mixed 字符集约束。
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, TextIO
+
+from app.cli.shell.commands.ai.executor_utils import SpinnerController
+from app.cli.shell.formatter import Formatter
+
+# 交互模式工具失败错误信息截断上限：单行状态不刷屏（完整 error 由结束后的
+# _display_tool_trail 展示）；非交互模式 stderr 是唯一诊断通道（工具轨迹不运行），不截断
+_MAX_ERROR_CHARS = 60
+
+# 工具名 → 中文标签缓存（单一事实源：ChatAgentRunner._TOOL_LABELS；
+# 延迟导入避免 CLI 启动时把 agent 工具链全部加载进 import 图）
+_TOOL_LABELS: dict[str, str] | None = None
+
+
+def _tool_label(name: str) -> str:
+    """取工具的中文展示标签，未知工具回退原始名。"""
+    global _TOOL_LABELS
+    if _TOOL_LABELS is None:
+        from app.shared.services.ai.chat_agent_runner import ChatAgentRunner
+
+        _TOOL_LABELS = dict(ChatAgentRunner._TOOL_LABELS)
+    return _TOOL_LABELS.get(name, name)
+
+
+def _print_to(stream: TextIO, text: str, end: str = "\n") -> None:
+    """向流打印；GBK 等本地编码管道下遇不可编码字符（✓/✗、emoji）降级替换输出。
+
+    流式渲染发生在对话运行中途，一次编码异常会击穿整个 agent 循环——
+    真实控制台（Windows console IO）不受影响，重定向/管道场景必须兜底。
+    """
+    try:
+        print(text, end=end, file=stream, flush=True)
+    except UnicodeEncodeError:
+        encoding = getattr(stream, "encoding", None) or "utf-8"
+        fallback = text.encode(encoding, errors="replace").decode(encoding, errors="replace")
+        print(fallback, end=end, file=stream, flush=True)
+
+
+class ChatStreamRenderer:
+    """Agent 流式回调 → 终端渲染适配器。
+
+    经 ChatOptions.agent_stream_callbacks 注入，由编排器转交给
+    ChatAgentRunner.configure_callbacks；回调在事件循环协程内同步触发，
+    仅做 print，无阻塞操作。
+
+    Attributes:
+        _spinner: 交互模式的 spinner 控制器（None 表示无动画）
+        _interactive: 是否交互模式（决定错误信息截断策略）
+        _status_stream: 过程状态（工具行/轮次分隔）输出流；非交互模式走 stderr，
+            保证 `ai ask` 管道场景 stdout 只含回复正文
+        _started: 首个内容事件已处理（spinner 已永久停止）
+        _pending_newline: 当前行有未收尾的流式文本
+        _turn_text: 最近一轮已流式打印的累积文本（判定最终回复是否已上屏）
+    """
+
+    def __init__(
+        self,
+        spinner: SpinnerController | None = None,
+        interactive: bool = True,
+    ) -> None:
+        self._spinner = spinner
+        self._interactive = interactive
+        self._status_stream = sys.stdout if interactive else sys.stderr
+        self._started = False
+        self._pending_newline = False
+        self._turn_text = ""
+
+    def callbacks(self) -> dict[str, Any]:
+        """构造注入 ChatOptions.agent_stream_callbacks 的回调字典。"""
+        return {
+            "on_chunk": self.on_chunk,
+            "on_turn": self.on_turn,
+            "on_tool_call": self.on_tool_call,
+            "on_tool_result": self.on_tool_result,
+        }
+
+    def _stop_spinner_once(self) -> None:
+        """首个内容事件到达后永久停掉 spinner（此后流式事件接管反馈）。"""
+        if self._started:
+            return
+        self._started = True
+        if self._spinner:
+            self._spinner.stop()
+
+    def _terminate_line(self) -> None:
+        """收尾未换行的流式文本行，保证后续行式输出不粘连。"""
+        if self._pending_newline:
+            _print_to(sys.stdout, "")
+            self._pending_newline = False
+
+    def on_chunk(self, text: str) -> None:
+        """LLM 文本增量：停 spinner 后逐字打印（不主动换行，随流自然收尾）。"""
+        self._stop_spinner_once()
+        if not text:
+            return
+        self._turn_text += text
+        _print_to(sys.stdout, text, end="")
+        self._pending_newline = not text.endswith("\n")
+
+    def on_turn(self, turn: int) -> None:
+        """轮次开始：重置本轮累积文本，仅在已有内容输出后打一个空行分隔（克制使用）。"""
+        self._turn_text = ""
+        if turn < 2 or not self._started:
+            return
+        self._terminate_line()
+        _print_to(self._status_stream, "")
+
+    def on_tool_call(self, name: str, call_id: str, turn: int) -> None:
+        """工具调用开始：收尾流式文本行（先于停 spinner，见模块注释）后打单行状态。"""
+        self._terminate_line()
+        self._stop_spinner_once()
+        _print_to(self._status_stream, Formatter.dim(f"→ 调用工具 {_tool_label(name)}..."))
+
+    def on_tool_result(self, tr: Any) -> None:
+        """工具调用结束：单行成败状态。
+
+        失败错误信息：交互模式截断到单行上限并补 "…" 标记（完整 error 由
+        _display_tool_trail 结束总结展示）；非交互模式 stderr 是唯一诊断通道
+        （_display_tool_trail 不运行），不截断，仅把换行压成空格保持单行形状。
+        """
+        self._terminate_line()
+        self._stop_spinner_once()
+        label = _tool_label(tr.name)
+        if tr.success:
+            _print_to(self._status_stream, Formatter.success(f"✓ {label} 完成"))
+        else:
+            error = (tr.error or "").replace("\n", " ")
+            if self._interactive and len(error) > _MAX_ERROR_CHARS:
+                error = error[:_MAX_ERROR_CHARS] + "…"
+            suffix = f" — {error}" if error else ""
+            _print_to(self._status_stream, Formatter.error(f"✗ {label} 失败{suffix}"))
+
+    def finish(self) -> None:
+        """流结束后收尾：保证末行换行，终端留给后续输出（确认提示/轨迹/错误信息）。"""
+        self._terminate_line()
+
+    def final_reply_already_shown(self, reply: str) -> bool:
+        """最终回复是否已随流式上屏。
+
+        runner 的 reply 即最后一轮 content，而每轮 content 均由 on_chunk 逐段
+        累积而来——两者完全相等说明全文已流式打印，调用方无需再整段重复输出。
+        """
+        return bool(reply) and reply == self._turn_text

{precis_cli-0.1.8 → precis_cli-0.1.9}/app/mcp_server.py

@@ -24,7 +24,7 @@
 Tools:
 - validate_data: 执行校验，返回契约 payload（docs/contracts/validate-json-v1.md）
 - check_config: 检查项目配置加载情况（loading_errors/warnings + 装载计数）
-- describe_constraints: 列出约束类型与参数说明（类型清单从 registry 派生）
+- describe_constraints: 列出约束类型与参数说明（refs/params 从 actions registry 派生）
 - infer_schema: 从数据文件推断 schema 草稿
 
 安全（P3-3）:
@@ -42,24 +42,6 @@ import sys
 from pathlib import Path
 from typing import Any
 
-# 约束类型的参数说明（类型清单从 core registry 派生，此表只补人话描述；
-# 新增约束类型时 registry 派生会自动带上，缺描述时用通用文案兜底）
-_CONSTRAINT_PARAM_DOCS: dict[str, dict[str, str]] = {
-    "NotNull": {"refs": "table_id + column_id", "params": "无"},
-    "Unique": {"refs": "table_id + column_ids（列表）", "params": "无"},
-    "AllowedValues": {"refs": "table_id + column_id", "params": "allowed_values: 允许值列表"},
-    "Range": {"refs": "table_id + column_id", "params": "min/max/boundary_mode(inclusive|exclusive)"},
-    "ForeignKey": {"refs": "from_table_id + from_column_id + to_table_id + to_column_id", "params": "无"},
-    "Conditional": {
-        "refs": "table_id + then_column_id + if_conditions[{if_column_id, operator, value}] + if_logic",
-        "params": "then_condition: {operator: not_null}",
-    },
-    "Scripted": {"refs": "table_id + column_id", "params": "name + expression（需 allow_eval）"},
-    "Charset": {"refs": "table_id + column_id", "params": "charset_mode: ascii|chinese|chinese_mixed"},
-    "DateLogic": {"refs": "table_id + column_id", "params": "logic_mode: compare + compare_op + reference_date"},
-    "Composite": {"refs": "table_id", "params": "logic(all|any) + sub_constraints（内嵌子约束列表）"},
-}
-
 
 def _allowed_roots() -> list[Path]:
     """路径白名单根：server 工作目录 + 环境变量追加根。"""
@@ -136,20 +118,13 @@ def tool_check_config(manifest: str) -> dict[str, Any]:
 
 
 def tool_describe_constraints() -> dict[str, Any]:
-    """列出全部约束类型与参数说明（类型清单从 core registry 派生）。"""
-    from app.shared.core.project.constraint.registry import CONSTRAINT_TYPE_ALIASES
-
-    # registry 的别名值集合即受支持的标准类型名集合
-    canonical_types = sorted(set(CONSTRAINT_TYPE_ALIASES.values()) | set(_CONSTRAINT_PARAM_DOCS.keys()))
-    types = [
-        {
-            "type": type_name,
-            "refs": _CONSTRAINT_PARAM_DOCS.get(type_name, {}).get("refs", "见 v2-format 文档"),
-            "params": _CONSTRAINT_PARAM_DOCS.get(type_name, {}).get("params", "见 v2-format 文档"),
-        }
-        for type_name in canonical_types
-    ]
-    return {"types": types, "note": "refs 指向 schema 的表/列 ID；配置格式详见插件 v2-format.md"}
+    """列出全部约束类型与参数说明（refs/params 均从 actions registry 单一事实源派生）。"""
+    from app.shared.services.llm.actions.registry import build_constraint_param_docs_structured
+
+    return {
+        "types": build_constraint_param_docs_structured(),
+        "note": "refs 指向 schema 的表/列 ID；params 为 V2 文件 params 区的 snake_case 键（含值域/默认值）；配置格式详见插件 v2-format.md",
+    }
 
 
 def tool_infer_schema(
@@ -278,7 +253,9 @@ def _warm_up_imports() -> None:
     不变量：工具线程内出现的所有 app 内延迟导入都必须在此登记——2026-09-21
     审计实证 json_payload（tool_validate_data 内）与 project_loader
     （executor.build_dataset_schema 惰性导入）破坏该不变量，已补齐。
+    describe_constraints 的 actions registry 延迟导入（轻量纯数据模块）同样登记。
     """
+    from app.shared.services.llm.actions import registry  # noqa: F401
     from app.shared.services.project_loader import build_dataset_schema  # noqa: F401
     from app.shared.services.schema_inference import infer_schema  # noqa: F401
     from app.shared.services.validation import (