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

{precis_cli-0.1.7/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.7
+Version: 0.1.9
 Summary: Precis - 可配置数据校验工具 CLI（校验 CSV/Excel/JSON 数据质量）
 Author: Precis Team
 License: Apache-2.0

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/api/dependencies.py

@@ -36,6 +36,7 @@
 
 # backend/app/api/dependencies.py
 import os
+from urllib.parse import quote, unquote
 
 from fastapi import Depends, Header, HTTPException
 
@@ -65,6 +66,44 @@ class ProjectStore:
         self.project_path = project_path
 
 
+def _decode_header_path(value: str) -> str:
+    """还原 HTTP header 携带的非 ASCII 路径。
+
+    两种线上契约并存，按特征识别、互不干扰：
+
+    1. GUI 契约（axios/fetch）：前端在出口处对路径做 encodeURIComponent（纯
+       ASCII 百分号转义）。浏览器 XHR/fetch 的 header 值只接受 ByteString
+       （ISO-8859-1），中文原值会被 XHR 直接拒绝；axios 1.18 的
+       toByteStringHeaderValue 还会把 latin1 之外的字符静默删除——不转义的
+       中文路径会以"删字后的错误路径"上线且无从在服务端还原。判定是否为
+       规范转义串用 round-trip 校验（quote(unquote(v)) == v），字面上含 % 的
+       合法路径通常不会被误解码（例外：字面 "%XX" 恰为合法 UTF-8 转义序列
+       的路径会被还原，随后走校验链报错而非指向任意目录）。round-trip 的
+       转义集必须与 encodeURIComponent 的不转义集对齐：JS 保留
+       `!'()*` 五字符原样上线，校验端 quote 的 safe 集须包含它们，否则含
+       括号/感叹号的中文路径（如 `D:/项目(备份)`）契约判定必败，被契约 2
+       原样放行后以百分号串走校验链 400/404。
+    2. TUI/脚本契约（reqwest FromBytes、curl 等）：UTF-8 原始字节按 obs-text
+       上线。ASGI 服务器把 header 字节按 latin-1 解码成乱码，latin-1 与字节流
+       双射，编码回字节再按 UTF-8 解码即可无损还原；非 UTF-8 字节保持原值，
+       交由后续校验链正常报错。
+    """
+    # 契约 1：规范百分号转义（GUI）。safe 集对齐 encodeURIComponent 的保留集
+    # （`!'()*`），Python quote 恒不转义字母数字与 `_.-~`，两者已一致
+    if "%" in value:
+        try:
+            decoded = unquote(value, errors="strict")
+        except UnicodeDecodeError:
+            decoded = None
+        if decoded is not None and decoded != value and quote(decoded, safe="!'()*") == value:
+            return decoded
+    # 契约 2：UTF-8 原始字节（TUI/脚本）
+    try:
+        return value.encode("latin-1").decode("utf-8")
+    except (UnicodeEncodeError, UnicodeDecodeError):
+        return value
+
+
 async def get_project_config_path(
     x_project_config_path: str = Header(..., description="项目根目录的绝对路径（须含 project.precis.yaml）"),
 ) -> str:
@@ -121,6 +160,9 @@ def _validate_project_root(raw_path: str | None) -> str:
     """
     if not raw_path:
         raise HTTPException(status_code=400, detail="X-Project-Config-Path header 不能为空。")
+    # 还原 header 编码乱码（见 _decode_header_path）：中文路径经 UTF-8 上线、
+    # latin-1 解码后 isdir 必失败，必须先还原再做后续校验
+    raw_path = _decode_header_path(raw_path)
     # 步骤1：先校验原始输入是否为绝对路径
     # 在 Windows 下，os.path.abspath 会把相对路径（如 "../project"）解析成绝对路径，
     # 导致后续 isabs 检查无法拒绝相对路径。因此必须在规范化之前先做判断。

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/api/models/full_validation.py

@@ -438,6 +438,12 @@ class FullValidationErrorItem(BaseModel):
     source_sheet: str | None = Field(
         default=None, description="配置文件内定义的 Excel Sheet 名（可选）"
     )  # schema 配置中 source.sheet 定义的 Excel 工作表名称，可选
+    error_code: str | None = Field(
+        default=None, description="稳定错误码（UPPER_SNAKE），供前端映射 i18n key 按当前语言渲染"
+    )  # 与 message 同时给出：message 为后端默认语言的兜底文案
+    error_params: dict | None = Field(
+        default=None, description="错误码对应的插值参数（JSON 标量），如 {column: 'Total'}"
+    )  # 供前端 t(key, params) 插值
 
 
 class ValidationPassedItem(BaseModel):

{precis_cli-0.1.7 → 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.7 → precis_cli-0.1.9}/app/api/models/validation.py

@@ -257,6 +257,12 @@ class ValidationErrorRow(BaseModel):
     error_message: str | None = Field(
         None, description="错误信息"
     )  # 校验失败的具体错误描述，如"值不在允许列表中"，可选
+    error_code: str | None = Field(
+        None, description="稳定错误码（UPPER_SNAKE），供前端映射 i18n key 按当前语言渲染"
+    )  # 与 error_message 同时给出：message 为后端默认语言的兜底文案
+    error_params: dict | None = Field(
+        None, description="错误码对应的插值参数（JSON 标量），如 {column: 'Total', row: 1}"
+    )  # 供前端 t(key, params) 插值
 
 
 class ValidationResult(BaseModel):

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/api/routers/ai/hardware.py

@@ -117,7 +117,11 @@ def diagnose_hardware() -> HardwareDiagnoseResponse:
         import subprocess
 
         result = subprocess.run(
-            ["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv,noheader"], capture_output=True, text=True
+            ["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv,noheader"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",  # 中文 Windows 下 text=True 默认按 GBK 解码会乱码/抛错
         )
         if result.returncode == 0:
             for line in result.stdout.strip().split("\n"):

{precis_cli-0.1.7 → 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.7 → 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.7 → precis_cli-0.1.9}/app/api/routers/ai/utils.py

@@ -138,12 +138,19 @@ def expand_paths(
 
     数据文件类型：.xlsx, .xls, .csv, .json, .jsonl
     """
+    # 还原 header 线上编码（GUI 契约 percent-encode / TUI 原始 UTF-8 字节，见
+    # app.api.dependencies._decode_header_path）：前端出口统一转义后，未解码的
+    # 百分号串作 base 解析相对路径会全 miss，中文项目下静默返回空列表
+    from app.api.dependencies import _decode_header_path
+
+    base_path = _decode_header_path(x_project_config_path) if x_project_config_path else None
+
     result = []
     seen = set()
 
     for raw_path in paths:
         # 1. 解析为绝对路径
-        path = _resolve_path(raw_path, x_project_config_path)
+        path = _resolve_path(raw_path, base_path)
 
         # 2. 如果是目录，递归展开
         if os.path.isdir(path):

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/api/routers/core/data_sources.py

@@ -86,7 +86,7 @@ def load_workspace_config(project_root: str) -> dict[str, Any]:
         }
 
     try:
-        with open(config_path, encoding="utf-8") as f:
+        with open(config_path, encoding="utf-8-sig") as f:
             return yaml.safe_load(f) or {}
     except Exception as e:
         raise HTTPException(

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/api/routers/core/reporting.py

@@ -223,7 +223,7 @@ def get_reporting_config(store: ProjectStore = Depends(get_project_store)) -> Re
         )
     try:
         # 读取并解析 YAML 配置文件
-        with open(config_path, encoding="utf-8") as f:
+        with open(config_path, encoding="utf-8-sig") as f:
             config_data = yaml.safe_load(f)
         return ReportingConfig(**config_data)
     except Exception as e:

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/api/routers/preview/header_row.py

@@ -106,7 +106,7 @@ def handle_header_row_changed(
 
             if os.path.exists(schema_path):
                 try:
-                    with open(schema_path, encoding="utf-8") as f:
+                    with open(schema_path, encoding="utf-8-sig") as f:
                         schema_content = yaml.safe_load(f)
 
                     if "header_row" not in schema_content:

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/api/routers/project/helpers.py

@@ -67,7 +67,7 @@ def _load_yaml_file(path: str) -> dict:
     if not os.path.isfile(path):
         return {}
     try:
-        with open(path, encoding="utf-8") as f:
+        with open(path, encoding="utf-8-sig") as f:
             return yaml.safe_load(f) or {}
     except yaml.YAMLError:
         return {}

{precis_cli-0.1.7 → 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.7 → precis_cli-0.1.9}/app/api/routers/projects/open.py

@@ -36,7 +36,7 @@ def _get_project_name(project_path: str) -> str:
     """从 project.precis.yaml 中读取项目名称，失败时返回目录名。"""
     manifest_path = os.path.join(project_path, "project.precis.yaml")
     try:
-        with open(manifest_path, encoding="utf-8") as f:
+        with open(manifest_path, encoding="utf-8-sig") as f:
             manifest = yaml.safe_load(f)
         if isinstance(manifest, dict):
             project = manifest.get("project", {})

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/api/routers/projects/scan.py

@@ -69,7 +69,7 @@ def scan_projects(
 def _parse_project(project_path: str, manifest_path: str) -> ProjectInfo | None:
     """解析单个项目的 manifest 文件获取元信息。"""
     try:
-        with open(manifest_path, encoding="utf-8") as f:
+        with open(manifest_path, encoding="utf-8-sig") as f:
             manifest = yaml.safe_load(f)
     except Exception:
         return None

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/api/routers/validation/common.py

@@ -189,11 +189,14 @@ def execute_dataframe_validation(
     )
 
     # 将原始错误行列表转换为标准化的 ValidationErrorRow 对象列表
+    # error_code/error_params 透传给前端，供按当前语言渲染错误文案
     error_rows = [
         ValidationErrorRow(
             row_index=err.get("row_index", 0),
             cell_value=str(err.get("cell_value", "")),
             error_message=err.get("error_message"),
+            error_code=err.get("error_code"),
+            error_params=err.get("error_params"),
         )
         for err in result.error_rows
     ]

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/api/services/full_validation_response_builder.py

@@ -150,6 +150,9 @@ class FullValidationResponseBuilder:
                     source_path=err.get("source_path"),
                     source_file=err.get("source_file"),
                     source_sheet=err.get("source_sheet"),
+                    # i18n：稳定错误码 + 插值参数透传，message 保留兜底文案
+                    error_code=err.get("error_code"),
+                    error_params=err.get("error_params"),
                 )
             )
 

{precis_cli-0.1.7 → precis_cli-0.1.9}/app/cli/shared_services/config_ops.py

@@ -371,7 +371,7 @@ def set_config_value_in_file(project_path: str, filename: str, key_path: str, va
     yaml_parser.preserve_quotes = True
 
     try:
-        with open(config_path, encoding="utf-8") as f:
+        with open(config_path, encoding="utf-8-sig") as f:
             data = yaml_parser.load(f)
     except RuamelYAMLError as e:
         return False, f"YAML 解析失败: {e}"
@@ -482,7 +482,7 @@ def load_config_content(project_path: str, filename: str) -> dict | str:
     if not config_path:
         return f"配置文件不存在: {filename}"
     try:
-        with open(config_path, encoding="utf-8") as f:
+        with open(config_path, encoding="utf-8-sig") as f:
             content = yaml.safe_load(f)
             if content:
                 return content if isinstance(content, dict) else str(content)

{precis_cli-0.1.7 → 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.7 → 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)}"