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

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

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

{precis_cli-0.1.8 → precis_cli-0.1.10}/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.10}/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.10}/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.10}/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.10/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.10}/app/cli/shell/commands/ai/agent_interaction.py

@@ -38,8 +38,9 @@ from app.shared.services.ai.agent.chat_tools.ask_user import AskCallbacks
 
 logger = logging.getLogger(__name__)
 
-# 终端 diff 展示上限：超长 diff 只显示前 N 行，避免刷屏（完整内容在 dry-run 文件里）
-_MAX_DIFF_LINES = 30
+# 确认清单（动作/文件）的展示上限：超长清单只显示前 N 项 + 总数，避免刷屏；
+# diff 正文不在此处展示，用户按 [d] 可查看全量内容
+_MAX_LIST_ITEMS = 10
 
 
 def build_agent_interaction(spinner: SpinnerController | None) -> tuple[ApplyCallbacks, AskCallbacks]:
@@ -61,7 +62,7 @@ def build_agent_interaction(spinner: SpinnerController | None) -> tuple[ApplyCal
         _print_apply_summary(payload)
 
         def _worker() -> None:
-            decision = _read_apply_decision()
+            decision = _read_apply_decision(payload)
             try:
                 future = asyncio.run_coroutine_threadsafe(_resolve_apply(apply_id, decision), loop)
                 future.result(timeout=10)
@@ -123,33 +124,75 @@ async def _resolve_ask(ask_id: str, response: dict[str, Any]) -> None:
 
 
 def _print_apply_summary(payload: dict[str, Any]) -> None:
-    """打印写盘计划摘要：文件清单 + 状态 + 截断 diff + 汇总行。"""
+    """打印写盘计划摘要：动作语义清单 + 文件状态清单（不打印 diff 正文）。
+
+    摘要优先——用户先确认"AI 要干什么"（动作清单），再看"动了哪些文件"；
+    diff 正文体积大（新建文件即全文），改为在决策提示中按 [d] 按需查看全量。
+    """
+    actions = payload.get("actions") or []
     files = payload.get("files") or []
-    print(Formatter.warning(f"\nAI 请求写入 {len(files)} 个文件："))
+
+    # 动作语义清单：一行一个动作（如 "添加约束：users.email — NotNull"）
+    if actions:
+        print(Formatter.warning(f"\n将执行 {len(actions)} 个动作："))
+        for i, action in enumerate(actions[:_MAX_LIST_ITEMS], start=1):
+            description = str(action.get("description") or action.get("action_type") or "")
+            print(f"  {i}. {description}")
+        if len(actions) > _MAX_LIST_ITEMS:
+            print(f"  ... 共 {len(actions)} 个")
+
+    # 文件清单：状态 + 路径（无 diff 正文）
+    counts = {"created": 0, "modified": 0, "deleted": 0}
     for f in files:
-        status = f.get("status", "?")
-        path = f.get("path", "?")
-        print(f"  [{status}] {path}")
-        diff = (f.get("diff") or "").strip()
-        if diff:
-            diff_lines = diff.splitlines()
-            shown = diff_lines[:_MAX_DIFF_LINES]
-            for line in shown:
-                print(f"      {line}")
-            if len(diff_lines) > _MAX_DIFF_LINES:
-                print(f"      ...（共 {len(diff_lines)} 行，已截断）")
+        status = str(f.get("status", ""))
+        if status in counts:
+            counts[status] += 1
+    print(
+        Formatter.warning(
+            f"\nAI 请求写入 {len(files)} 个文件"
+            f"（新增 {counts['created']}，修改 {counts['modified']}，删除 {counts['deleted']}）："
+        )
+    )
+    for f in files[:_MAX_LIST_ITEMS]:
+        print(f"  [{f.get('status', '?')}] {f.get('path', '?')}")
+    if len(files) > _MAX_LIST_ITEMS:
+        print(f"  ... 共 {len(files)} 个")
+
     summary = payload.get("summary")
     if summary:
         print(Formatter.info(f"  摘要: {summary}"))
 
 
-def _read_apply_decision() -> str:
-    """读取 y/n 决策；空输入与非 y 输入一律 reject（写盘默认保守）。"""
-    try:
-        raw = input(Formatter.warning("确认写入以上变更？[y/N]: ")).strip().lower()
-    except EOFError:
+def _print_full_diff(payload: dict[str, Any]) -> None:
+    """打印全量 diff（[d] 按需查看）：payload 携带的就是完整内容，不做截断。"""
+    files = payload.get("files") or []
+    if not files:
+        print(Formatter.info("  （无文件变更）"))
+        return
+    for f in files:
+        print(Formatter.info(f"\n--- {f.get('path', '?')}（{f.get('status', '?')}）---"))
+        diff = (f.get("diff") or "").strip()
+        print(diff if diff else "  （无 diff 内容）")
+
+
+def _read_apply_decision(payload: dict[str, Any]) -> str:
+    """三态决策循环：y 确认写入 / d 查看全量 diff 后回到提示 / 其余（含空输入）拒绝。
+
+    空输入与非 y 输入一律 reject（写盘默认保守），与旧版语义一致。
+    """
+    while True:
+        try:
+            raw = (
+                input(Formatter.warning("确认写入以上变更？[y]确认写入 / [d]查看详细 diff / [N]拒绝: ")).strip().lower()
+            )
+        except EOFError:
+            return "reject"
+        if raw in ("y", "yes", "是"):
+            return "confirm"
+        if raw in ("d", "diff", "查看"):
+            _print_full_diff(payload)
+            continue
         return "reject"
-    return "confirm" if raw in ("y", "yes", "是") else "reject"
 
 
 def _print_ask_question(payload: dict[str, Any]) -> None:
@@ -157,11 +200,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 +241,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.10}/app/cli/shell/commands/ai/chat.py

@@ -80,7 +80,7 @@ class AIChatCommand(Command):
 
     @property
     def usage(self) -> str:
-        return "ai chat [--no-agent-mode]"
+        return "ai chat [--no-agent-mode] [--no-pretty]"
 
     def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
         """执行 AI 交互式对话命令。
@@ -88,7 +88,7 @@ class AIChatCommand(Command):
         检查项目和 AI 配置，解析命令行参数，然后进入交互式输入循环。
 
         Args:
-            args: 命令参数列表，可能包含 --no-agent-mode
+            args: 命令参数列表，可能包含 --no-agent-mode / --no-pretty
             context: 命令上下文，必须包含已打开的项目
 
         Returns:
@@ -104,10 +104,14 @@ class AIChatCommand(Command):
 
         # 解析命令行参数（--stream/--no-stream 已随 execute_ai_chat 的死参数一并移除）
         agent_mode = True  # 默认启用 Agent 深度模式
+        pretty: bool | None = None  # markdown 流式渲染：None 自动（TTY 检测）
         filtered_args = []
         for arg in args:
             if arg == "--no-agent-mode":
                 agent_mode = False
+            elif arg == "--no-pretty":
+                # 关闭流式 markdown 渲染，回退原文直出（与非 TTY 管道路径一致）
+                pretty = False
             else:
                 filtered_args.append(arg)
 
@@ -209,6 +213,7 @@ class AIChatCommand(Command):
                     interactive=True,
                     history=chat_history,
                     agent_mode=agent_mode,
+                    pretty=pretty,
                 )
 
                 if result.success and result.data:
@@ -259,6 +264,7 @@ AI 助手帮助
 
 启动选项:
     --no-agent-mode  - 关闭 Agent 深度模式（降级为旧 JSON actions 路径）
+    --no-pretty      - 关闭流式 markdown 渲染（标题/粗体/表格重排），回退原文直出
 
 你可以用自然语言描述你的需求，例如:
   - "在 users 表的 email 列上添加非空约束"

{precis_cli-0.1.8 → precis_cli-0.1.10}/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
@@ -33,12 +34,12 @@ from .display import _display_execution_results, _display_tool_trail
 from .executor_utils import (
     SpinnerController,
     _collect_all_config_files,
-    _collect_declared_new_files,
     _get_provider_display,
     _get_provider_with_key,
 )
 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
@@ -52,6 +53,7 @@ def execute_ai_chat(
     interactive: bool = False,
     history: list[dict[str, str]] | None = None,
     agent_mode: bool = True,
+    pretty: bool | None = None,
 ) -> CommandResult:
     """执行 AI 对话（统一版本）。
 
@@ -68,6 +70,8 @@ def execute_ai_chat(
         interactive: 是否为交互模式（显示 spinner、提示确认等）
         history: 对话历史记录列表，每个元素包含 role 和 content
         agent_mode: 是否启用 Agent 深度模式（默认 True），CLI 无画布时仍走 Agent 工具循环
+        pretty: 流式 markdown 渲染开关（True/False 强制，None 自动按 stdout TTY 检测；
+            非 TTY 管道场景自动回退原文直出）
 
     Returns:
         命令执行结果，成功时 data 包含 reply、actions 和 frontend_instructions
@@ -134,6 +138,12 @@ 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, pretty=pretty) if agent_mode else None
+    )
+
     # 配置对话选项
     options = ChatOptions(
         history=history or [],
@@ -144,21 +154,23 @@ def execute_ai_chat(
         confirm_callback=confirm_actions_wrapper if interactive else None,
         ambiguity_resolver=ambiguity_resolver_wrapper if interactive else None,
         agent_mode=agent_mode,
-        max_agent_iterations=5,
         canvas_nodes=[],
+        # CLI 终端没有画布：隔离画布能力——read_canvas 工具不注册、
+        # ADD_TO_CANVAS 动作拦截、系统提示词剔除画布话术（agent/legacy 两路径共用）
+        canvas_enabled=False,
         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:
         import asyncio
 
-        # 收集原始文件内容（仅在交互模式下，用于 diff 对比）。
-        # 4.25: AI 本次新建的文件纳入执行前缓存（登记为空内容）——执行后它们
-        # 存在而缓存里没有，diff 生成器会跳过，新建文件的变更在摘要里永不显示
+        # 收集原始文件内容（仅 legacy 交互路径使用——agent 模式的 diff 由
+        # 确认框（apply 回调）基于 dry-run 计算，不需要会话前快照）
         original_files_cache = {}
-        if interactive and project_path:
+        if interactive and not agent_mode and project_path:
             original_files_cache = _collect_all_config_files(project_path)
 
         # 启动 spinner 动画，提示用户 AI 正在处理
@@ -166,19 +178,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,26 +208,27 @@ 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:
             _display_tool_trail(result.tool_steps)
 
-        # 在交互模式下显示执行结果和 diff。
-        # 4.25: AI 本次新建的文件先登记进缓存（空内容）——执行后它们存在而缓存
-        # 没有，diff 生成器会跳过，新建文件的变更在摘要里永不显示
-        if interactive and actions and project_path is not None:
-            for declared in _collect_declared_new_files(result, project_path):
-                original_files_cache.setdefault(declared, "")
+        # 在交互 + legacy（非 agent）模式下显示执行结果和 diff 摘要。
+        # agent 模式不再弹事后摘要：确认框（apply 回调）已展示完整 dry-run diff，
+        # 且这里的数据源是会话前快照（漏掉本会话新建的文件），input() 还会
+        # 吞掉用户的下一条命令
+        if interactive and not agent_mode and actions and project_path is not None:
             _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 +237,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)}"