xg-cli 1.0__py3-none-any.whl

xg/cli/help.py

@@ -0,0 +1,185 @@
+"""Formatting helpers for the shared slash-command help."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from xg.cli.commands import SLASH_COMMANDS, SlashCommandSpec, SlashSubcommandSpec
+
+
+CATEGORY_LABELS: dict[str, str] = {
+    "workflow": "工作流",
+    "config": "配置与能力",
+    "session": "会话",
+    "memory": "记忆",
+    "safety": "安全",
+    "control": "控制",
+    "general": "通用",
+}
+
+CATEGORY_ORDER = (
+    "workflow",
+    "config",
+    "session",
+    "memory",
+    "safety",
+    "control",
+    "general",
+)
+
+SHORTCUTS = (
+    ("Enter", "发送输入"),
+    ("↑ / ↓", "浏览输入历史；输入 / 时浏览命令建议"),
+    ("Ctrl+C", "取消当前任务"),
+    ("Ctrl+L", "清屏"),
+    ("Ctrl+R", "显示或隐藏侧栏"),
+    ("Ctrl+T", "打开配置面板（Provider 与 SmartRouter）"),
+    ("Ctrl+1..4", "切换 Inspector 视图（Session/Plan/Memory/Safety）"),
+    ("Ctrl+Tab", "Inspector 视图循环切换（Ctrl+Shift+Tab 反向）"),
+    ("Esc", "关闭弹窗、取消当前交互或清除输入"),
+)
+
+
+def _command_key(value: str) -> str:
+    """Normalize a command name or alias for exact help lookup."""
+
+    return value.strip().lower().lstrip("/")
+
+
+def parse_help_command(raw: str) -> str | None:
+    """Return the optional help query, or ``None`` for a non-help input."""
+
+    parts = raw.strip().split(maxsplit=1)
+    if not parts or parts[0].lower() not in ("/help", "/?"):
+        return None
+    return parts[1].strip() if len(parts) > 1 else ""
+
+
+def _aliases_text(spec: SlashCommandSpec) -> str:
+    if not spec.aliases:
+        return ""
+    return f"（别名：{'、'.join(spec.aliases)}）"
+
+
+def _command_lines(commands: Sequence[SlashCommandSpec]) -> list[str]:
+    visible = [spec for spec in commands if spec.usage and spec.description]
+    if not visible:
+        return []
+    usage_width = max(len(spec.usage) for spec in visible)
+    lines: list[str] = []
+    for category in CATEGORY_ORDER:
+        grouped = [spec for spec in visible if spec.category == category]
+        if not grouped:
+            continue
+        lines.append(CATEGORY_LABELS.get(category, category))
+        for spec in grouped:
+            usage = spec.usage.ljust(usage_width)
+            lines.append(f"  {usage}  {spec.description}{_aliases_text(spec)}")
+        lines.append("")
+
+    # Keep custom categories visible even if a future command adds one that
+    # is not yet part of the standard presentation order.
+    known = set(CATEGORY_ORDER)
+    for category in dict.fromkeys(spec.category for spec in visible if spec.category not in known):
+        lines.append(CATEGORY_LABELS.get(category, category))
+        for spec in visible:
+            if spec.category == category:
+                usage = spec.usage.ljust(usage_width)
+                lines.append(f"  {usage}  {spec.description}{_aliases_text(spec)}")
+        lines.append("")
+    return lines
+
+
+def format_help(
+    commands: Sequence[SlashCommandSpec] = SLASH_COMMANDS,
+    *,
+    include_shortcuts: bool = True,
+) -> str:
+    """Return the complete, renderer-neutral slash-command help text."""
+
+    lines = ["XG 命令帮助", ""]
+    lines.extend(_command_lines(commands))
+
+    aliases = [
+        f"{alias} = {spec.name}"
+        for spec in commands
+        for alias in spec.aliases
+    ]
+    if aliases:
+        lines.extend(["命令别名", f"  {'    '.join(aliases)}", ""])
+
+    if include_shortcuts:
+        lines.append("TUI 快捷键")
+        shortcut_width = max(len(key) for key, _ in SHORTCUTS)
+        lines.extend(
+            f"  {key.ljust(shortcut_width)}  {description}"
+            for key, description in SHORTCUTS
+        )
+        lines.append("")
+
+    lines.extend(
+        [
+            "提示：输入 / 后可以使用 ↑ / ↓ 选择命令建议。",
+            "输入 /help <命令> 可查看某条命令的详细用法。",
+        ]
+    )
+    return "\n".join(lines).rstrip()
+
+
+def format_command_help(
+    query: str,
+    commands: Sequence[SlashCommandSpec] = SLASH_COMMANDS,
+) -> str:
+    """Return help for one command or an actionable unknown-command hint."""
+
+    token = query.strip().split(maxsplit=1)[0] if query.strip() else ""
+    normalized = _command_key(token)
+    if not normalized:
+        return format_help(commands)
+
+    spec = find_command(token, commands)
+    if spec is None:
+        return f"未找到命令帮助：{token}。输入 /help 查看全部命令。"
+
+    lines = [f"{spec.name} — {spec.description}", f"用法：{spec.usage}"]
+    if spec.aliases:
+        lines.append(f"别名：{'、'.join(spec.aliases)}")
+    if spec.details:
+        lines.extend(["", *spec.details])
+    if spec.subcommands:
+        lines.extend(["", "子命令"])
+        lines.extend(_subcommand_lines(spec.subcommands))
+    if spec.examples:
+        lines.extend(["", "示例"])
+        lines.extend(f"  {example}" for example in spec.examples)
+    return "\n".join(lines)
+
+
+def _subcommand_lines(subcommands: Sequence[SlashSubcommandSpec]) -> list[str]:
+    """Format detailed command modes with stable aligned columns."""
+
+    usage_width = max(len(item.usage) for item in subcommands)
+    return [
+        f"  {item.usage.ljust(usage_width)}  {item.description}"
+        for item in subcommands
+    ]
+
+
+def find_command(
+    query: str,
+    commands: Sequence[SlashCommandSpec] = SLASH_COMMANDS,
+) -> SlashCommandSpec | None:
+    """Find a command by its name or alias."""
+
+    normalized = _command_key(query)
+    if not normalized:
+        return None
+    return next(
+        (
+            item
+            for item in commands
+            if _command_key(item.name) == normalized
+            or any(_command_key(alias) == normalized for alias in item.aliases)
+        ),
+        None,
+    )

xg/cli/train.py

@@ -0,0 +1,200 @@
+"""训练 ML 模型命令的执行层：/train 的参数解析、确认提示与子进程流式执行。
+
+设计口径（对齐 05 文档与现有 /provider 红线）：
+- 训练仍是显式手动触发：不带 --yes 只返回确认提示，绝不静默跑。
+- 训练跑在独立子进程 :file:`tools/train_router.py`，本层只「spawn + 收日志」，
+  不 import 训练逻辑，规避 torch 等重依赖进主进程。
+- inline 走同步版 :func:`run_training_sync`；TUI 走异步版 :func:`run_training_async`，
+  两者共用参数解析与 argv 构造，日志都逐行流式上报。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+_TRAIN_SCRIPT = Path(__file__).resolve().parents[2] / "tools" / "train_router.py"
+_TRAIN_DEPS = ("lightgbm", "sklearn", "joblib", "numpy")
+
+
+@dataclass
+class TrainPlan:
+    dataset: str | None = None
+    output: str | None = None
+    overwrite: bool = False
+    feedback_only: bool = False
+    semantic: bool = True  # 默认带语义列：自动探测语义编码器；--no-semantic 关闭
+
+
+def _default_output() -> Path:
+    """默认产物路径：与 feedback.log 同目录的 router.lgb（对齐 train_router）。"""
+    from xg.adaptive.store import data_dir  # noqa: PLC0415
+
+    return data_dir() / "router.lgb"
+
+
+def _default_semantic_onnx() -> Path | None:
+    """自动探测默认语义编码器产物：数据目录 → 随包 assets 兜底，找到即返回路径。"""
+    from xg.adaptive.store import data_dir  # noqa: PLC0415
+
+    primary = data_dir() / "router_semantics.onnx"
+    if primary.exists():
+        return primary
+    bundled = Path(__file__).resolve().parents[1] / "assets" / "router_semantics.onnx"
+    return bundled if bundled.exists() else None
+
+
+def check_train_deps() -> str | None:
+    """缺训练依赖时返回安装提示；全部可用返回 None。
+
+    注意：语义编码器（bge）非必需——缺失时 train_router 自动回退 TF-IDF 特征。
+    """
+    missing = [m for m in _TRAIN_DEPS if _import_safe(m) is False]
+    if missing:
+        return (
+            "缺少训练依赖："
+            + ", ".join(missing)
+            + "。请先 `pip install -e .` 安装核心依赖后再试。"
+        )
+    return None
+
+
+def _import_safe(mod: str) -> bool:
+    try:
+        __import__(mod)
+        return True
+    except Exception:
+        return False
+
+
+def parse_train_command(raw: str) -> tuple[TrainPlan, str | None]:
+    """解析 `/train [...]` 参数，返回 (plan, error)。错误时 plan 不保证完整。"""
+    plan = TrainPlan()
+    tokens = raw.split(maxsplit=1)[1].split() if len(raw.split(maxsplit=1)) > 1 else []
+    i = 0
+    while i < len(tokens):
+        t = tokens[i]
+        if t in ("--yes", "-y"):
+            plan.overwrite = True
+        elif t == "--feedback-only":
+            plan.feedback_only = True
+        elif t == "--no-semantic":
+            plan.semantic = False
+        elif t in ("--output", "--out", "-o"):
+            i += 1
+            if i >= len(tokens):
+                return plan, "--output 需要一个路径参数"
+            plan.output = tokens[i]
+        elif t.startswith("-"):
+            return plan, f"未知参数: {t}"
+        else:
+            if plan.dataset is not None:
+                return plan, f"多余参数: {t}"
+            plan.dataset = t
+        i += 1
+    if plan.dataset and plan.feedback_only:
+        return plan, "不能同时指定数据集与 --feedback-only"
+    if not plan.dataset and not plan.feedback_only:
+        plan.feedback_only = True  # 缺省：仅用 feedback.log
+    if plan.output is not None:
+        plan.output = plan.output.strip('"\'')
+    return plan, None
+
+
+def confirmation_message(plan: TrainPlan) -> str:
+    """未带 --yes 时返回的确认提示：告知将如何训练、需加 --yes 才执行。"""
+    src = "反馈日志 feedback.log" if plan.feedback_only else f"数据集 {plan.dataset}"
+    out = plan.output or str(_default_output())
+    sem_note = "带语义列（默认，自动探测语义编码器）" if plan.semantic else "纯 TF-IDF（--no-semantic）"
+    return (
+        "确认将运行 SmartRouter 训练：\n"
+        f"  样本来源: {src}\n"
+        f"  产物路径: {out}\n"
+        f"  语义特征: {sem_note}\n"
+        "完整数据集 / feedback 样本会被去噪后用于训练；训练为手动触发，"
+        "不会自动运行。确认执行请在命令末尾加 --yes。"
+    )
+
+
+def build_argv(plan: TrainPlan) -> list[str]:
+    """构造 tools/train_router.py 的 argv（output 缺省时不传，交给脚本默认）。
+
+    语义列默认启用：plan.semantic 为真时自动探测默认语义编码器产物并传入
+    --semantic-onnx；未探测到或 --no-semantic 则不传，训练回退纯 TF-IDF 特征。
+    """
+    argv = [sys.executable, str(_TRAIN_SCRIPT)]
+    if plan.output:
+        argv += ["--out", plan.output]
+    if plan.feedback_only:
+        argv += ["--feedback-only"]
+    elif plan.dataset:
+        argv += [plan.dataset]
+    if plan.semantic:
+        onnx = _default_semantic_onnx()
+        if onnx is not None:
+            argv += ["--semantic-onnx", str(onnx)]
+    return argv
+
+
+def _build_env() -> dict[str, str]:
+    """让子进程以 UTF-8 输出（Windows 默认 GBK 会与读取端 utf-8 解码冲突导致乱码）。"""
+    env = dict(os.environ)
+    env["PYTHONUTF8"] = "1"
+    env.setdefault("PYTHONIOENCODING", "utf-8")
+    return env
+
+
+def run_training_sync(
+    plan: TrainPlan, on_line: callable | None = None
+) -> tuple[bool, list[str]]:
+    """同步执行训练（inline 用）。逐行流式读子进程输出交给 on_line，返回 (ok, lines)。"""
+    argv = build_argv(plan)
+    proc = subprocess.Popen(
+        argv,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        env=_build_env(),
+    )
+    lines: list[str] = []
+    try:
+        assert proc.stdout is not None
+        for line in proc.stdout:
+            line = line.rstrip("\n")
+            lines.append(line)
+            if on_line is not None:
+                on_line(line)
+    finally:
+        rc = proc.wait()
+    return rc == 0, lines
+
+
+async def run_training_async(
+    plan: TrainPlan, on_line: callable | None = None
+) -> tuple[bool, list[str]]:
+    """异步执行训练（TUI / CommandService 用）。逐行流式上报，返回 (ok, lines)。"""
+    argv = build_argv(plan)
+    proc = await asyncio.create_subprocess_exec(
+        *argv,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.STDOUT,
+        env=_build_env(),
+    )
+    lines: list[str] = []
+    assert proc.stdout is not None
+    while True:
+        raw = await proc.stdout.readline()
+        if not raw:
+            break
+        line = raw.decode("utf-8", errors="replace").rstrip("\n")
+        lines.append(line)
+        if on_line is not None:
+            on_line(line)
+    await proc.wait()
+    return (proc.returncode or 0) == 0, lines

xg/config/env_writer.py

@@ -0,0 +1,121 @@
+"""幂等读写本地 :file:`.env` 文件（用于交互式写入 API Key）。
+
+设计口径（对齐 02 方案 F2 / J2）：
+- config.json 永不落 key；key 只经 :file:`.env` 的 ``XG_<NAME>_API_KEY`` 提供。
+- 本模块只负责「定位、增改、去重、原子写」某一行，不做其他配置管理。
+- 写入对原文幂等：已存在 -> 原位保留注释风格并替换值；不存在 -> 追加。
+- 用临时文件 + ``os.replace`` 原子落盘，失败不破坏原文件。
+
+定位规则（J2）：从工作目录向上查找命中现有的 :file:`.env`（最多 3 层）；
+找不到时回退到 ``fallback_dir / ".env"``。
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+def find_env_file(start_dir: str | Path | None = None, max_up: int = 3) -> Path | None:
+    """从 ``start_dir`` 向上查找已存在的 :file:`.env`（最多 ``max_up`` 层）。"""
+    cur = Path(start_dir) if start_dir else Path.cwd()
+    for _ in range(max_up):
+        candidate = cur / ".env"
+        if candidate.is_file():
+            return candidate
+        if cur == cur.parent:
+            break
+        cur = cur.parent
+    return None
+
+
+def decide_env_path(start_dir: str | Path | None = None, fallback_dir: str | Path | None = None) -> Path:
+    """确定要写入的 .env 路径：优先命中现有文件，否则落到 fallback 目录。"""
+    existing = find_env_file(start_dir)
+    if existing is not None:
+        return existing
+    base = Path(fallback_dir) if fallback_dir else Path.cwd()
+    return base / ".env"
+
+
+def env_value(lines: list[str], key: str) -> str | None:
+    """取 ``key`` 当前生效值（容忍 ``KEY=v`` / ``KEY = v``，返回去引号值）。"""
+    prefix = f"{key}="
+    for raw in lines:
+        line = raw.strip()
+        if line.startswith(prefix):
+            return line[len(prefix):].strip().strip('"').strip("'")
+        if line.startswith(f"{key} ="):
+            return line[len(f"{key} ="):].strip().strip('"').strip("'")
+    return None
+
+
+def upsert_env_key(lines: list[str], key: str, value: str) -> list[str]:
+    """返回把 ``key=value`` 写入后的新行列表（已存在则替换，否则追加）。
+
+    - 只匹配精确 ``KEY=...`` 行；注释行、导出行不变。
+    - 存在重复行时保留第一处位置并去重后续重复。
+    """
+    prefix = f"{key}="
+    key_line = f"{key}={value}"
+    out: list[str] = []
+    replaced = False
+    for raw in lines:
+        line = raw.strip()
+        if not replaced and line.startswith(prefix):
+            # 保留该行缩进/前缀风格：追加新赋值行
+            spaces = raw[: len(raw) - len(raw.lstrip())]
+            out.append(f"{spaces}{key_line}")
+            replaced = True
+            continue
+        if line.startswith(prefix):
+            # 已存在 -> 去重后续重复行
+            continue
+        out.append(raw)
+    if not replaced:
+        out.append(key_line)
+    return out
+
+
+def write_env_atomic(path: str | Path, lines: list[str]) -> None:
+    """把 ``lines`` 原子写入 ``path``（临时文件 + reinstated替换）。"""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), prefix=".env.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
+            for line in lines:
+                handle.write(line if line.endswith("\n") else line + "\n")
+        os.replace(tmp_name, str(target))
+    except BaseException:
+        try:
+            os.remove(tmp_name)
+        except OSError:
+            pass
+        raise
+
+
+def set_env_key(
+    path: str | Path,
+    key: str,
+    value: str,
+    *,
+    overwrite: bool = False,
+) -> tuple[bool, str | None]:
+    """写入 ``key=value`` 到 ``path``。
+
+    返回 ``(changed, previous)``：
+    - ``key`` 不存在 -> 追加，返回 ``(True, None)``；
+    - ``key`` 已存在且 ``overwrite=True`` -> 替换，返回 ``(True, 旧值)``；
+    - ``key`` 已存在且 ``overwrite=False`` -> 不做修改，返回 ``(False, 旧值)``。
+    由调用方负责占位值拦截与确认，本函数只做机械写入（幂等原则）。
+    """
+    target = Path(path)
+    original = target.read_text(encoding="utf-8").splitlines() if target.is_file() else []
+    previous = env_value(original, key)
+    if previous is not None and not overwrite:
+        return False, previous
+    next_lines = upsert_env_key(original, key, value)
+    write_env_atomic(target, next_lines)
+    return True, previous