precis-cli 0.1.4__tar.gz → 0.1.6__tar.gz

{precis_cli-0.1.4 → precis_cli-0.1.6}/MANIFEST.in

@@ -1,3 +1,2 @@
 include README.md
 include pyproject.toml
-recursive-include app *.yaml

precis_cli-0.1.6/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: precis-cli
+Version: 0.1.6
+Summary: Precis - 可配置数据校验工具 CLI（校验 CSV/Excel/JSON 数据质量）
+Author: Precis Team
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/AirSaiga/Precis
+Project-URL: Repository, https://github.com/AirSaiga/Precis
+Project-URL: Bug Tracker, https://github.com/AirSaiga/Precis/issues
+Project-URL: Discussions, https://github.com/AirSaiga/Precis/discussions
+Keywords: data-quality,data-validation,csv,excel,json,yaml,cli,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: pandas<3.0,>=2.2.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: xlrd>=2.0.1
+Requires-Dist: SQLAlchemy>=2.0.48
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: ruamel.yaml>=0.19.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: readchar>=4.2.0
+Requires-Dist: cryptography>=44.0.0
+Requires-Dist: simpleeval>=1.0.0
+Requires-Dist: filelock>=3.12.0
+Provides-Extra: api
+Requires-Dist: fastapi!=0.136.3,>=0.135.0; extra == "api"
+Requires-Dist: uvicorn>=0.42.0; extra == "api"
+Requires-Dist: email-validator>=2.3.0; extra == "api"
+Requires-Dist: uritemplate>=4.2.0; extra == "api"
+Requires-Dist: python-multipart>=0.0.26; extra == "api"
+Requires-Dist: cryptography>=44.0.0; extra == "api"
+Provides-Extra: ai
+Requires-Dist: openai>=1.6.0; extra == "ai"
+Requires-Dist: aiohttp>=3.9.0; extra == "ai"
+Requires-Dist: psutil>=5.9.6; extra == "ai"
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.30.0; extra == "mcp"
+Provides-Extra: completion
+Requires-Dist: pyreadline3>=0.1.8; sys_platform == "win32" and extra == "completion"
+Provides-Extra: full
+Requires-Dist: precis-cli[ai,api,completion,mcp]; extra == "full"
+Provides-Extra: dev
+Requires-Dist: precis-cli[ai,api,mcp]; extra == "dev"
+Requires-Dist: debugpy>=1.8.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+
+# Precis CLI
+
+> Local-first data validation engine — define schemas and constraints in YAML, validate CSV / Excel / JSON with a single command.
+> 本地优先的数据校验引擎：用 YAML 定义表结构与约束规则，一条命令校验 CSV / Excel / JSON。
+
+**Alpha** — 核心功能稳定，配置格式有版本保障（V2）。
+
+## 安装
+
+```bash
+pip install precis-cli          # 需要 Python >= 3.12
+
+# 或免安装直接运行（需要 uv）
+uvx --from precis-cli precis --version
+```
+
+## 快速上手
+
+```bash
+# 1. 从数据文件推断 schema 草稿
+precis infer-schema orders.csv > schemas/orders.schema.yaml
+
+# 2. 在项目清单 project.precis.yaml 中登记 schema 与约束文件
+#    （格式见下方示例）
+
+# 3. 执行校验
+precis validate --manifest project.precis.yaml --format json
+```
+
+退出码契约（CI / AI agent 友好）：
+
+| 退出码 | 含义 |
+|--------|------|
+| `0` | 校验通过 |
+| `1` | 校验完成，发现数据违规（详情见 JSON 输出的 `errors`） |
+| `2` | 工具自身错误（参数错误、文件不存在、异常崩溃） |
+
+## 配置示例（V2 YAML）
+
+`project.precis.yaml`：
+
+```yaml
+version: 2
+project:
+  id: my-project
+  name: 订单数据校验
+schemas:
+  - id: orders
+    path: schemas/orders.schema.yaml
+constraints:
+  - id: orders_amount_range
+    path: constraints/orders_amount_range.constraint.yaml
+```
+
+`constraints/orders_amount_range.constraint.yaml`：
+
+```yaml
+version: 2
+id: orders_amount_range
+type: Range
+enabled: true
+refs:
+  table_id: orders
+  column_id: amount
+params:
+  min: 0
+  max: 1000000
+  boundary_mode: inclusive
+```
+
+## 10 种约束类型
+
+`NotNull` 非空 · `Unique` 唯一 · `AllowedValues` 枚举 · `Range` 数值区间 ·
+`ForeignKey` 跨表引用 · `Conditional` 条件约束 · `Scripted` 脚本表达式 ·
+`Charset` 字符集 · `DateLogic` 日期逻辑 · `Composite` 组合约束
+
+数据类型：`string` / `integer` / `float` / `decimal` / `boolean` / `date`。
+大文件（>500MB）自动分块加载。
+
+## 与 AI Agent 集成
+
+`--format json` 输出为机器可读契约（含行级错误定位与约束来源文件回溯），
+可直接被 AI 编程助手消费：
+
+- **MCP server**：`pip install "precis-cli[mcp]"` 后运行 `precis-mcp`（stdio），
+  提供 `validate_data` / `infer_schema` / `check_config` / `describe_constraints` 四个工具
+- **Kimi Code 插件**：`/plugins install https://github.com/AirSaiga/Precis`
+- **CLI 自带 AI 命令**（自然语言生成/修改校验配置，独立于宿主 agent）：
+  `pip install "precis-cli[ai]"`，然后 `precis ai chat` 或 `precis ai ask "..."`
+
+## 链接
+
+- 仓库与文档：<https://github.com/AirSaiga/Precis>
+- 问题反馈：<https://github.com/AirSaiga/Precis/issues>
+- 桌面 GUI 版本（画布式可视化编辑）见仓库 releases
+
+License: Apache-2.0

precis_cli-0.1.6/PYPI_README.md

@@ -0,0 +1,97 @@
+# Precis CLI
+
+> Local-first data validation engine — define schemas and constraints in YAML, validate CSV / Excel / JSON with a single command.
+> 本地优先的数据校验引擎：用 YAML 定义表结构与约束规则，一条命令校验 CSV / Excel / JSON。
+
+**Alpha** — 核心功能稳定，配置格式有版本保障（V2）。
+
+## 安装
+
+```bash
+pip install precis-cli          # 需要 Python >= 3.12
+
+# 或免安装直接运行（需要 uv）
+uvx --from precis-cli precis --version
+```
+
+## 快速上手
+
+```bash
+# 1. 从数据文件推断 schema 草稿
+precis infer-schema orders.csv > schemas/orders.schema.yaml
+
+# 2. 在项目清单 project.precis.yaml 中登记 schema 与约束文件
+#    （格式见下方示例）
+
+# 3. 执行校验
+precis validate --manifest project.precis.yaml --format json
+```
+
+退出码契约（CI / AI agent 友好）：
+
+| 退出码 | 含义 |
+|--------|------|
+| `0` | 校验通过 |
+| `1` | 校验完成，发现数据违规（详情见 JSON 输出的 `errors`） |
+| `2` | 工具自身错误（参数错误、文件不存在、异常崩溃） |
+
+## 配置示例（V2 YAML）
+
+`project.precis.yaml`：
+
+```yaml
+version: 2
+project:
+  id: my-project
+  name: 订单数据校验
+schemas:
+  - id: orders
+    path: schemas/orders.schema.yaml
+constraints:
+  - id: orders_amount_range
+    path: constraints/orders_amount_range.constraint.yaml
+```
+
+`constraints/orders_amount_range.constraint.yaml`：
+
+```yaml
+version: 2
+id: orders_amount_range
+type: Range
+enabled: true
+refs:
+  table_id: orders
+  column_id: amount
+params:
+  min: 0
+  max: 1000000
+  boundary_mode: inclusive
+```
+
+## 10 种约束类型
+
+`NotNull` 非空 · `Unique` 唯一 · `AllowedValues` 枚举 · `Range` 数值区间 ·
+`ForeignKey` 跨表引用 · `Conditional` 条件约束 · `Scripted` 脚本表达式 ·
+`Charset` 字符集 · `DateLogic` 日期逻辑 · `Composite` 组合约束
+
+数据类型：`string` / `integer` / `float` / `decimal` / `boolean` / `date`。
+大文件（>500MB）自动分块加载。
+
+## 与 AI Agent 集成
+
+`--format json` 输出为机器可读契约（含行级错误定位与约束来源文件回溯），
+可直接被 AI 编程助手消费：
+
+- **MCP server**：`pip install "precis-cli[mcp]"` 后运行 `precis-mcp`（stdio），
+  提供 `validate_data` / `infer_schema` / `check_config` / `describe_constraints` 四个工具
+- **Kimi Code 插件**：`/plugins install https://github.com/AirSaiga/Precis`
+- **CLI 自带 AI 命令**（自然语言生成/修改校验配置，独立于宿主 agent）：
+  `pip install "precis-cli[ai]"`，然后 `precis ai chat` 或 `precis ai ask "..."`
+
+## 链接
+
+- 仓库与文档：<https://github.com/AirSaiga/Precis>
+- 问题反馈：<https://github.com/AirSaiga/Precis/issues>
+- 桌面 GUI 版本（画布式可视化编辑）见仓库 releases
+
+License: Apache-2.0

{precis_cli-0.1.4 → precis_cli-0.1.6}/app/cli/shared_services/config_ops.py

@@ -41,6 +41,7 @@
 from __future__ import annotations
 
 import logging
+import math
 import os
 import tempfile
 from collections.abc import Iterator
@@ -207,6 +208,10 @@ def resolve_config_file(project_path: str, filename: str | None) -> tuple[str |
 def get_by_dotpath(data: dict, key_path: str) -> tuple[bool, Any]:
     """按点号路径从字典中查找值。
 
+    YAML 键可为非字符串（如 ``2024:`` 解析为 int、``true:`` 解析为 bool）——
+    路径段除精确匹配外也按字符串形态匹配非字符串键，防止"键存在却查不到"
+    进而被 set 侧写出同形态影子键。
+
     Args:
         data: 配置字典
         key_path: 点号路径，如 "project.name"
@@ -217,8 +222,16 @@ def get_by_dotpath(data: dict, key_path: str) -> tuple[bool, Any]:
     keys = key_path.split(".")
     value: Any = data
     for key in keys:
-        if isinstance(value, dict) and key in value:
-            value = value[key]
+        if isinstance(value, dict):
+            if key in value:
+                value = value[key]
+                continue
+            for k, v in value.items():
+                if not isinstance(k, str) and str(k) == key:
+                    value = v
+                    break
+            else:
+                return False, None
         else:
             return False, None
     return True, value
@@ -227,7 +240,8 @@ def get_by_dotpath(data: dict, key_path: str) -> tuple[bool, Any]:
 def set_by_dotpath(data: dict, key_path: str, value: Any) -> dict:
     """按点号路径写入值，返回新 data（不改原 dict）。
 
-    中间层级不存在时自动创建空字典。
+    中间层级不存在时自动创建空字典；路径段与既有非字符串键（如 int ``2024``）
+    字符串形态相同时复用原键，防止写出同形态影子键并存。
 
     Args:
         data: 原配置字典（不会被修改）
@@ -244,10 +258,21 @@ def set_by_dotpath(data: dict, key_path: str, value: Any) -> dict:
     keys = key_path.split(".")
     current = new_data
     for key in keys[:-1]:
-        if key not in current or not isinstance(current[key], dict):
-            current[key] = {}
-        current = current[key]
-    current[keys[-1]] = value
+        existing = current.get(key)
+        if isinstance(existing, dict):
+            current = existing
+            continue
+        # 同形态非字符串键复用（写原键而非另建字符串影子键）
+        non_str_key = next((k for k in current if not isinstance(k, str) and str(k) == key), None)
+        if non_str_key is not None and isinstance(current[non_str_key], dict):
+            current = current[non_str_key]
+            continue
+        target = non_str_key if non_str_key is not None else key
+        current[target] = {}
+        current = current[target]
+    leaf = keys[-1]
+    leaf_key = next((k for k in current if not isinstance(k, str) and str(k) == leaf), leaf)
+    current[leaf_key] = value
     return new_data
 
 
@@ -267,8 +292,9 @@ def parse_config_value(value_str: str) -> tuple[bool, Any, str]:
         value_str: 原始字符串值
 
     Returns:
-        (成功, 转换后的值, 错误信息)；本实现始终成功，错误信息为空字符串。
-        保留 tuple 三元组以匹配接口契约，便于未来扩展严格模式。
+        (成功, 转换后的值, 错误信息)；毒化字面量（inf/nan/下划线整数等
+        无法被下游安全消费的数值形态）返回 (False, None, 错误信息)，
+        调用方应拒绝落盘。
     """
     # 尝试布尔值
     if value_str.lower() == "true":
@@ -278,17 +304,24 @@ def parse_config_value(value_str: str) -> tuple[bool, Any, str]:
     if value_str.lower() == "null" or value_str.lower() == "none":
         return True, None, ""
 
-    # 尝试整数
-    try:
-        return True, int(value_str), ""
-    except ValueError:
-        pass
+    # 尝试整数：拒绝 Python 下划线字面量（'1_0' 静默变 10 会毒化下游数值读取）
+    if "_" not in value_str:
+        try:
+            return True, int(value_str), ""
+        except ValueError:
+            pass
 
-    # 尝试浮点数
-    try:
-        return True, float(value_str), ""
-    except ValueError:
-        pass
+    # 尝试浮点数：拒绝非有限值（inf/nan/溢出 1e999）与下划线字面量——
+    # timeout_seconds: .inf 落盘后 validate 侧 int(inf) 抛 OverflowError，项目从此无法校验
+    if "_" not in value_str:
+        try:
+            parsed_float = float(value_str)
+        except ValueError:
+            parsed_float = None
+        if parsed_float is not None:
+            if not math.isfinite(parsed_float):
+                return False, None, f"不接受非有限数值: {value_str}（inf/nan 落盘会使项目无法校验）"
+            return True, parsed_float, ""
 
     # 去除引号
     if (value_str.startswith('"') and value_str.endswith('"')) or (

{precis_cli-0.1.4 → precis_cli-0.1.6}/app/cli/shared_services/generation_ops.py

@@ -36,6 +36,7 @@ from __future__ import annotations
 import glob
 import logging
 import os
+import re
 from pathlib import Path
 from typing import Any
 
@@ -46,6 +47,25 @@ logger = logging.getLogger(__name__)
 # 支持的文件扩展名（generate/migrate 共用）
 SUPPORTED_EXTENSIONS = (".xlsx", ".xls", ".csv", ".json", ".jsonl")
 
+# 实体 id 安全白名单：字母/数字/下划线/连字符（H10——LLM 生成的 id 未消毒即拼盘
+# 路径时，`../../evil` 类路径成分可越项目写文件/建目录，写盘前须拒绝）
+_SAFE_ENTITY_ID_RE = re.compile(r"[A-Za-z0-9_-]+")
+
+
+def _filter_safe_entity_ids(entities: dict[str, Any], kind: str) -> dict[str, Any]:
+    """过滤掉含路径成分或非法字符的实体 id，记录错误日志（H10）。
+
+    Returns:
+        仅保留安全 id 的实体字典；非法 id 整体跳过（不写盘、不进 manifest 引用）
+    """
+    safe: dict[str, Any] = {}
+    for eid, body in entities.items():
+        if isinstance(eid, str) and _SAFE_ENTITY_ID_RE.fullmatch(eid):
+            safe[eid] = body
+        else:
+            logger.error("跳过非法实体 id（含路径成分或非法字符，kind=%s）: %r", kind, eid)
+    return safe
+
 
 def scan_data_files(patterns: list[str], project_path: str) -> list[str]:
     """展开数据文件路径（支持通配符、相对路径、data/ 目录扫描）。
@@ -91,8 +111,9 @@ def scan_data_files(patterns: list[str], project_path: str) -> list[str]:
 def apply_generated_config(result: dict[str, Any], project_path: str) -> list[str]:
     """将生成的配置写入项目目录。
 
-    会保留现有 project.precis.yaml 中的 transforms/manual_data 等引用，
-    覆盖写入 schemas、constraints、regex_nodes。
+    保留策略为并集（R6）：生成 manifest 未携带的既有顶层键（project/settings/
+    templates/data_sources 等）一律保留，防止空/局部 manifest 清空既有配置；
+    schemas、constraints、regex_nodes 引用则始终按生成结果覆盖写入。
 
     Args:
         result: ConfigGenerationService / ConfigMigrationService 返回的配置字典
@@ -111,16 +132,24 @@ def apply_generated_config(result: dict[str, Any], project_path: str) -> list[st
         except Exception:
             logger.warning("读取现有 manifest 失败，将覆盖写入", exc_info=True)
 
-    manifest = result.get("manifest") or {"version": 2, "project": {"id": "", "name": ""}}
-
-    # 保留现有 manifest 中生成未覆盖的引用
-    for key in ("transforms", "manual_data"):
-        if key in existing_manifest and key not in manifest:
-            manifest[key] = existing_manifest[key]
-
-    schemas = result.get("schemas", {})
-    constraints = result.get("constraints", {})
-    regex_nodes = result.get("regex_nodes", {})
+    generated_manifest = result.get("manifest")
+    if generated_manifest:
+        manifest = dict(generated_manifest)
+    else:
+        # LLM 未返回 manifest：以现有 manifest 为底仅补最小骨架，
+        # 不再制造空 project 兜底清空既有 project.id/settings（R6）
+        manifest = dict(existing_manifest)
+        manifest.setdefault("version", 2)
+        manifest.setdefault("project", {"id": "", "name": ""})
+
+    # 保留策略并集（R6）：生成 manifest 未携带的既有键一律保留
+    for key, value in existing_manifest.items():
+        if key not in manifest:
+            manifest[key] = value
+
+    schemas = _filter_safe_entity_ids(result.get("schemas", {}) or {}, "schema")
+    constraints = _filter_safe_entity_ids(result.get("constraints", {}) or {}, "constraint")
+    regex_nodes = _filter_safe_entity_ids(result.get("regex_nodes", {}) or {}, "regex")
 
     # 确保目录存在
     (Path(project_path) / "schemas").mkdir(exist_ok=True)

{precis_cli-0.1.4 → precis_cli-0.1.6}/app/cli/shared_services/project_ops.py

@@ -51,10 +51,25 @@ HISTORY_FILE = os.path.expanduser("~/.precis_project_history")
 MAX_HISTORY = 10
 
 
+def _backup_corrupt_history() -> None:
+    """把损坏的历史文件改名备份（.corrupt.bak），失败仅记日志。
+
+    原实现在 JSON 损坏后静默按空历史继续——下次保存直接覆盖，
+    用户历史不可恢复；备份保留现场供手工抢救。
+    """
+    try:
+        backup = f"{HISTORY_FILE}.corrupt.bak"
+        os.replace(HISTORY_FILE, backup)
+        logger.warning("项目历史文件损坏，已备份到 %s 并从空历史继续", backup)
+    except OSError:
+        logger.error("备份损坏的项目历史文件失败: %s", HISTORY_FILE, exc_info=True)
+
+
 def load_history() -> list[dict]:
     """加载项目打开历史。
 
     从 HISTORY_FILE 读取历史记录。文件不存在、格式损坏或权限不足时返回空列表。
+    JSON 损坏时先把原文件备份为 ``*.corrupt.bak`` 再按空历史继续（不静默清零）。
 
     Returns:
         历史记录列表，每个元素为包含 path 和 last_opened 的字典
@@ -78,7 +93,8 @@ def load_history() -> list[dict]:
                 return valid
             return []
     except json.JSONDecodeError:
-        # JSON 格式损坏，返回空列表
+        # JSON 格式损坏：备份后按空历史继续
+        _backup_corrupt_history()
         return []
     except PermissionError:
         # 无权限读取，返回空列表
@@ -91,7 +107,8 @@ def load_history() -> list[dict]:
 def _save_history(history: list[dict]) -> None:
     """保存项目打开历史。
 
-    将历史记录写入 HISTORY_FILE。保存失败仅记录日志，不阻断主流程。
+    原子写（临时文件 + os.replace）：进程中断不会留下半截 JSON——
+    半截文件在下次 load 即被判损坏。保存失败仅记录日志，不阻断主流程。
 
     Args:
         history: 历史记录列表
@@ -99,8 +116,10 @@ def _save_history(history: list[dict]) -> None:
     try:
         # 确保目录存在（用户主目录）
         os.makedirs(os.path.dirname(HISTORY_FILE), exist_ok=True)
-        with open(HISTORY_FILE, "w", encoding="utf-8") as f:
+        tmp_file = f"{HISTORY_FILE}.tmp"
+        with open(tmp_file, "w", encoding="utf-8") as f:
             json.dump(history, f, ensure_ascii=False, indent=2)
+        os.replace(tmp_file, HISTORY_FILE)
     except (PermissionError, OSError):
         # 保存失败时记录错误日志，但不阻断主流程
         logger.error("保存项目历史记录失败", exc_info=True)

{precis_cli-0.1.4 → precis_cli-0.1.6}/app/cli/shell/commands/ai/__init__.py

@@ -23,7 +23,8 @@
 - 支持直接通过自然语言执行 AI 指令
 
 架构设计:
-- AICommand 作为聚合命令，管理 chat、status、switch、delete、setup 等子命令
+- AICommand 作为聚合命令，管理 chat、status、switch、delete、provider 等子命令
+- 裸装（无 [ai] extra）时入口门控：help 标注缺依赖，execute 直接给安装指引
 - 无参数时显示交互式菜单（支持方向键导航）
 - 第一个参数如果不是子命令，则将其视为直接询问的消息
 - 使用 execute_ai_chat 统一执行 AI 对话
@@ -52,6 +53,31 @@ from app.cli.shell.config_storage import get_cli_config
 from app.cli.shell.formatter import Formatter
 from app.cli.shell.interactive_menu import InteractiveMenu
 
+# [ai] 扩展依赖探测结果缓存（失败导入不会被 import 机制负缓存，help 每次渲染
+# 都会读 description，缓存避免重复文件系统扫描；测试可经 monkeypatch 覆盖）
+_AI_DEPS_AVAILABLE: bool | None = None
+
+
+def ai_dependencies_available() -> bool:
+    """探测 AI 功能的可选依赖是否已安装（裸装 precis-cli 不含 [ai] extra）。
+
+    openai 是核心门控导入（OpenAI 兼容 provider 全系走它）；aiohttp/psutil
+    随同一 extra 安装，openai 可导入即视为 extra 已装。
+    """
+    global _AI_DEPS_AVAILABLE  # noqa: PLW0603
+    if _AI_DEPS_AVAILABLE is None:
+        try:
+            import openai  # noqa: F401
+        except ImportError:
+            _AI_DEPS_AVAILABLE = False
+        else:
+            _AI_DEPS_AVAILABLE = True
+    return _AI_DEPS_AVAILABLE
+
+
+# 依赖缺失时 ai 入口的统一提示（help 标注与 execute 门控共用同一安装指引）
+_AI_INSTALL_HINT = 'pip install "precis-cli[ai]"（源码安装用 pip install -e ".[ai]"）'
+
 
 class AICommand(Command):
     """AI 助手命令。
@@ -82,6 +108,10 @@ class AICommand(Command):
 
     @property
     def description(self) -> str:
+        # help 列表动态标注：裸装（无 [ai] extra）不伪装成可用功能，
+        # 让用户在进菜单之前就知道差什么、怎么补
+        if not ai_dependencies_available():
+            return f"AI 助手 - 未安装依赖（{_AI_INSTALL_HINT}）"
         return "AI 助手 - 使用自然语言修改项目配置"
 
     @property
@@ -139,6 +169,14 @@ class AICommand(Command):
         Returns:
             子命令执行结果或 AI 对话结果
         """
+        if not ai_dependencies_available():
+            # 门控在菜单/子命令分发之前：缺依赖时不进交互菜单（菜单里每个
+            # 选项最终都会失败），直接给安装指引；provider 预配置不受影响
+            # （顶层 provider 命令不依赖 LLM 库）
+            return CommandResult.error(
+                f"AI 功能需要可选依赖，当前未安装。安装命令: {_AI_INSTALL_HINT}\n"
+                "如仅需预配置 AI Provider，可先运行 'provider add'（无需依赖）。"
+            )
         if not args:
             # 无参数时显示交互式菜单
             return self._show_interactive_menu(context)

{precis_cli-0.1.4 → precis_cli-0.1.6}/app/cli/shell/commands/ai/chat.py

@@ -100,7 +100,7 @@ class AIChatCommand(Command):
         # 检查 AI 配置（使用 CLI 配置）
         provider = self._cli_config.get_active_provider()
         if not provider:
-            return CommandResult.error("没有可用的 LLM Provider 配置\n请先运行 'setup' 命令配置 API Key")
+            return CommandResult.error("没有可用的 LLM Provider 配置\n请先运行 'provider add' 命令配置 API Key")
 
         # 解析命令行参数（--stream/--no-stream 已随 execute_ai_chat 的死参数一并移除）
         agent_mode = True  # 默认启用 Agent 深度模式
@@ -258,8 +258,6 @@ AI 助手帮助
   qq           - 直接退出整个程序（全局可用）
 
 启动选项:
-    --stream         - 启用流式输出
-    --no-stream      - 禁用流式输出（默认，显示 loading spinner）
     --no-agent-mode  - 关闭 Agent 深度模式（降级为旧 JSON actions 路径）
 
 你可以用自然语言描述你的需求，例如:

{precis_cli-0.1.4 → precis_cli-0.1.6}/app/cli/shell/commands/ai/executor.py

@@ -80,7 +80,7 @@ def execute_ai_chat(
     # 获取用于显示的 Provider 配置（脱敏，用于日志或展示）
     provider_config_display = _get_provider_display()
     if not provider_config_display:
-        return CommandResult.error("没有可用的 LLM Provider 配置，请先运行 'setup' 命令配置 AI Provider")
+        return CommandResult.error("没有可用的 LLM Provider 配置，请先运行 'provider add' 命令配置 AI Provider")
 
     # 获取包含完整 API Key 的 Provider 配置（用于实际调用 API）
     provider_config = _get_provider_with_key()

{precis_cli-0.1.4 → precis_cli-0.1.6}/app/cli/shell/commands/ai/generate.py

@@ -53,6 +53,7 @@ from app.cli.shared_services.generation_ops import (
 )
 from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
 from app.cli.shell.formatter import Formatter
+from app.shared.core.utils.path_utils import display_relpath
 from app.shared.services.llm.generation import (
     ConfigGenerationService,
     GenerationOptions,
@@ -200,7 +201,7 @@ class AIGenerateCommand(Command):
         print(Formatter.info(f"迭代次数: {max_iterations}"))
         print(Formatter.info("数据文件:"))
         for p in file_paths:
-            print(f"  - {os.path.relpath(p, project_path)}")
+            print(f"  - {display_relpath(p, project_path)}")
 
         def progress_callback(stage: str, progress: float, extra: dict[str, Any] | None = None) -> None:
             """终端进度回调。"""

{precis_cli-0.1.4 → precis_cli-0.1.6}/app/cli/shell/commands/ai/migrate.py

@@ -51,6 +51,7 @@ from app.cli.shared_services.generation_ops import (
 )
 from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
 from app.cli.shell.formatter import Formatter
+from app.shared.core.utils.path_utils import display_relpath
 from app.shared.services.ai.migrate_service import ConfigMigrationService
 from app.shared.services.llm.generation import (
     GenerationOptions,
@@ -72,6 +73,10 @@ def _infer_language(file_path: str) -> str:
     return "natural_language"
 
 
+# --language 可选值（与 usage 声明一致）
+_SUPPORTED_LANGUAGES = ("python", "sql", "excel_formula", "natural_language")
+
+
 class AIMigrateCommand(Command):
     """AI 配置迁移命令。
 
@@ -171,6 +176,9 @@ class AIMigrateCommand(Command):
 
         if language is None:
             language = _infer_language(script_path)
+        elif language not in _SUPPORTED_LANGUAGES:
+            # 枚举校验：非法值前置拒绝（usage 已声明可选值），不透传下游晦涩报错
+            return CommandResult.error(f"--language 仅支持 {'|'.join(_SUPPORTED_LANGUAGES)}，收到: {language}")
 
         try:
             with open(script_path, encoding="utf-8") as f:
@@ -202,10 +210,10 @@ class AIMigrateCommand(Command):
 
         print(Formatter.header("\nAI 配置迁移"))
         print(Formatter.info(f"项目: {project_name}"))
-        print(Formatter.info(f"脚本: {os.path.relpath(script_path, project_path)} ({language})"))
+        print(Formatter.info(f"脚本: {display_relpath(script_path, project_path)} ({language})"))
         print(Formatter.info("数据文件:"))
         for p in file_paths:
-            print(f"  - {os.path.relpath(p, project_path)}")
+            print(f"  - {display_relpath(p, project_path)}")
 
         def progress_callback(stage: str, progress: float, extra: dict[str, Any] | None = None) -> None:
             """终端进度回调。"""