qi-coding-agent 0.1.0__py3-none-any.whl

qi_agent/config.py

@@ -0,0 +1,409 @@
+"""模型配置 `models.json`(对齐 pi 格式)+ 解析。
+
+文件位置(优先级从高到低):
+  $QI_AGENT_CONFIG(指定文件)→ <项目>/.qi/models.json → ~/.qi/agent/models.json
+合并:键级深合并,内层覆盖外层;providers 按 provider 名合并。
+
+默认模型 `defaultProvider` / `defaultModel` **只属于 settings.json**(对齐 pi):
+
+    <项目>/.qi/settings.json  >  ~/.qi/agent/settings.json
+
+models.json 里的这两个键**已不再被读取**(不是"优先级更低",是彻底不参与);
+启动时若发现残留,报错/诊断里会给出可照抄的迁移命令。
+
+格式与 pi 的 models.json 相同:
+
+    {
+      "providers": {
+        "deepseek": {
+          "baseUrl": "https://api.deepseek.com/v1",
+          "api": "openai-completions",
+          "apiKey": "$DEEPSEEK_API_KEY",
+          "models": [
+            { "id": "deepseek-chat", "reasoning": false,
+              "contextWindow": 128000, "maxTokens": 16384 }
+          ]
+        }
+      }
+    }
+
+凭证明文永不写入本文件:只允许 `apiKey` 引用(字面量/`$ENV`/`!command`)或 auth store。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .paths import MODELS_FILE_NAME, SETTINGS_FILE_NAME, models_file_candidates
+from .settings import SettingsError, deep_merge, load_settings, read_json
+
+# 支持 pi 的 api 类型(见 docs/models.md)
+DEFAULT_API = "openai-completions"
+SUPPORTED_APIS = (
+    "openai-completions",
+    "openai-responses",
+    "anthropic-messages",
+    "google-generative-ai",
+)
+
+DEFAULT_CONTEXT_WINDOW = 128000
+DEFAULT_MAX_TOKENS = 16384
+
+
+class ConfigError(Exception):
+    """配置缺失/校验失败,启动即报(对应 qi doctor 的检查项)。"""
+
+
+class ModelEntry(BaseModel):
+    """pi 格式的单个模型定义(额外字段原样保留)。"""
+
+    model_config = {"extra": "allow"}  # type: ignore[assignment]
+
+    id: str
+    name: str | None = None
+    api: str | None = None
+    reasoning: bool = False
+    input: list[str] = Field(default_factory=lambda: ["text"])
+    contextWindow: int = DEFAULT_CONTEXT_WINDOW
+    maxTokens: int = DEFAULT_MAX_TOKENS
+    cost: dict[str, Any] | None = None
+    headers: dict[str, str] | None = None
+    compat: dict[str, Any] | None = None
+
+
+class ProviderConfig(BaseModel):
+    """pi 格式的 provider 定义(额外字段原样保留)。"""
+
+    model_config = {"extra": "allow"}  # type: ignore[assignment]
+
+    baseUrl: str | None = None
+    api: str | None = None
+    apiKey: str | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+    models: list[ModelEntry] = Field(default_factory=list)
+
+
+class QiConfig(BaseModel):
+    """models.json 的配置面。未知顶层段原样保留(extra=allow)。
+
+    注:`defaultProvider` / `defaultModel` **不在这里** —— 默认模型属于
+    `settings.json`(见 settings.QiSettings);models.json 里写了也会被剔除。
+    """
+
+    model_config = {"extra": "allow"}  # type: ignore[assignment]
+
+    routerProvider: str | None = None
+    routerModel: str | None = None
+    providers: dict[str, ProviderConfig] = Field(default_factory=dict)
+    #: 哪些 provider 来自 **qi 的预置表**(`presets.py`)而不是用户的 models.json。
+    #: 由 `load_config` 填充,只给 UI / 诊断做标记用 —— models.json 里写了就以它为准。
+    presetProviders: set[str] = Field(default_factory=set)
+
+
+@dataclass
+class ResolvedModel:
+    """解析后的运行期模型(provider 默认 + 模型条目合并)。"""
+
+    provider: str
+    model: str
+    api: str
+    base_url: str | None
+    api_key_ref: str | None
+    reasoning: bool
+    context_window: int
+    max_tokens: int
+    entry: ModelEntry | None = None
+
+    @property
+    def label(self) -> str:
+        return f"{self.provider}/{self.model}"
+
+
+def deep_merge_config(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """兼容旧调用名;实现已统一到 settings.deep_merge。"""
+    return deep_merge(base, override)
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    """读取单个 JSON 文件;失败转 ConfigError(settings.read_json 报路径)。"""
+    try:
+        return read_json(path)
+    except SettingsError as exc:
+        raise ConfigError(str(exc)) from exc
+
+
+def load_raw(cwd: Path | None = None) -> tuple[dict[str, Any], list[Path]]:
+    """按优先级装载并深合并;返回 (merged_dict, 实际读取的文件列表)。"""
+    merged: dict[str, Any] = {}
+    loaded: list[Path] = []
+    # 高优先级在前;从低到高合并,让高优先级覆盖
+    for path in reversed(models_file_candidates(cwd)):
+        if not path.is_file():
+            continue
+        merged = deep_merge(merged, _read_json(path))
+        loaded.append(path)
+    return merged, list(reversed(loaded))
+
+
+def default_model_spec(cwd: Path | None = None) -> tuple[str | None, str | None, str]:
+    """默认模型及其来源,供 `qi doctor` 诊断。
+
+    **只从 settings.json 读**(对齐 pi):
+
+        <项目>/.qi/settings.json  >  ~/.qi/agent/settings.json
+
+    `models.json` 里的 `defaultProvider` / `defaultModel` **不再被读取** ——
+    如果旧文件里还留着,`legacy_default_keys()` 会报出来。
+    """
+    try:
+        settings, files = load_settings(cwd)
+    except SettingsError as exc:
+        raise ConfigError(str(exc)) from exc
+    if settings.defaultProvider and settings.defaultModel:
+        return settings.defaultProvider, settings.defaultModel, (
+            f"settings:{files[0]}" if files else "settings"
+        )
+    return None, None, "未配置"
+
+
+def legacy_default_keys(cwd: Path | None = None) -> list[tuple[Path, str | None, str | None]]:
+    """找出 models.json 里残留的 `defaultProvider`/`defaultModel`。
+
+    返回 `(文件, provider, model)`;空列表表示没有残留。这两个键已不再生效,
+    仅用于在报错/诊断里给出可照抄的迁移指令。
+    """
+    hits: list[tuple[Path, str | None, str | None]] = []
+    for path in models_file_candidates(cwd):
+        if not path.is_file():
+            continue
+        try:
+            data = read_json(path)
+        except SettingsError:
+            continue
+        if "defaultProvider" not in data and "defaultModel" not in data:
+            continue
+        provider = data.get("defaultProvider")
+        model = data.get("defaultModel")
+        hits.append((
+            path,
+            str(provider) if provider else None,
+            str(model) if model else None,
+        ))
+    return hits
+
+
+def _legacy_hint(cwd: Path | None) -> str:
+    """残留老的默认模型键时,拼一段可照抄的迁移提示。"""
+    try:
+        hits = legacy_default_keys(cwd)
+    except Exception:  # noqa: BLE001 - 提示文本不该反过来炸掉启动
+        return ""
+    if not hits:
+        return ""
+    path, provider, model = hits[0]
+    cmd = "qi config"
+    if provider:
+        cmd += f" --set defaultProvider={provider}"
+    if model:
+        cmd += f" --set defaultModel={model}"
+    body = (
+        f"\n已从 {path} 读到 `defaultProvider`/`defaultModel`,但这两个键已不再从 "
+        f"{MODELS_FILE_NAME} 读取(默认模型属于 {SETTINGS_FILE_NAME})。\n"
+        f"    {cmd}\n"
+        f"然后删掉 {path} 里的这两行。"
+    )
+    if len(hits) > 1:
+        body += "\n(另有残留:" + ", ".join(str(p) for p, _x, _y in hits[1:]) + ")"
+    return body
+
+
+def with_preset_providers(raw: dict[str, Any]) -> set[str]:
+    """把**预置 provider** 补给 `models.json` 里没写到的那些(原地修改 `raw`)。
+
+    规矩一条:**models.json 里写了的以它为准**,预置只当兜底。
+
+    为什么要兜底:预置的意义就是“`qi auth login deepseek` 之后立刻能用”,而不是先要求用户去
+    跑一次 `qi init --preset`。所以 `deepseek` / `moonshot` 这些只要没在 models.json 里出现,
+    就按 `presets.py` 的定义补上(baseUrl / api / 约定环境变量的 apiKey 引用 / 模型清单)。
+    想改它们就 `qi init --preset <名>` 物化到 models.json 里再改(那时预置就不再插手)。
+
+    返回补进去的 provider 名(给 `QiConfig.presetProviders` 做标记)。
+    """
+    from .presets import PRESETS, model_entry, provider_entry
+
+    providers: dict[str, Any] = raw.setdefault("providers", {})
+    added: set[str] = set()
+    for name, preset in PRESETS.items():
+        if isinstance(providers.get(name), dict):
+            continue                       # 用户写了这个 provider —— 以他为准
+        entry = provider_entry(preset)
+        entry["models"] = [model_entry(model) for model in preset.models]
+        providers[name] = entry
+        added.add(name)
+    return added
+
+
+def load_config(cwd: Path | None = None) -> tuple[QiConfig, list[Path]]:
+    """装载 models.json(用户写的 + **预置兜底**,见 `with_preset_providers`)。
+
+    注:默认模型**不在**这里 —— 它属于 settings.json,
+    由 `resolve_default_model()` / `default_model_spec()` 单独解析。
+    """
+    raw, loaded = load_raw(cwd)
+    # models.json 里的 default* 不再是有效字段:剔掉,避免被 pydantic 当成未知键静默收下
+    raw.pop("defaultProvider", None)
+    raw.pop("defaultModel", None)
+    preset_providers = with_preset_providers(raw)
+    try:
+        cfg = QiConfig.model_validate(raw)
+    except Exception as exc:  # pydantic.ValidationError
+        raise ConfigError(f"配置校验失败: {exc}") from exc
+    cfg.presetProviders = preset_providers
+    return cfg, loaded
+
+
+def models_file_for_provider(provider: str, cwd: Path | None = None) -> Path | None:
+    """哪个 `models.json` 文件定义了这个 provider(**优先级最高**的那个)。
+
+    给 `qi init --refresh` 用:刷新要写回**定义它的那个文件**,而不是无脑写用户级 ——
+    否则会在另一个文件里长出一份同名的新定义,而合并取高优先级的那个,于是
+    “刷新了却看不到效果”。哪个文件都没定义(预置兜底来的)才回落到用户级。
+    """
+    for path in models_file_candidates(cwd):
+        if not path.is_file():
+            continue
+        try:
+            providers = read_json(path).get("providers")
+        except SettingsError:
+            continue
+        if isinstance(providers, dict) and provider in providers:
+            return path
+    return None
+
+
+def in_play_providers(cfg: QiConfig, *, default_provider: str | None = None,
+                      router_provider: str | None = None) -> set[str]:
+    """“在用”的 provider:`models.json` 里显式写过的 + 默认 / 路由模型指向的那个。
+
+    用来做**“缺凭证”的告警口径**:预置兜底那批只是目录(没配、也没被选为默认),
+    不该算“缺凭证” —— 否则预置有十家、“凭证全部就绪”永远不可能成立。
+    但被选为默认模型的预置 provider **必须算** —— 不然用户看不出自己缺哪把钥匙。
+    """
+    explicit = set(cfg.providers) - set(cfg.presetProviders)
+    return explicit | {name for name in (default_provider, router_provider) if name}
+
+
+def selectable_models(cfg: QiConfig, *, store: Any = None) -> list[tuple[str, str]]:
+    """**可选模型**清单(`provider, model_id`)—— `/model` / ctrl+l·p 轮换 / `/scoped-models` /
+    web 的模型菜单 / `qi --list-models` 共用这一份。
+
+    口径一条:**解析得出凭证的 provider 才列**(`resolve_key(...).ok`)—— auth store →
+    约定环境变量 → `models.json` 里的 `apiKey` 引用(含 `$(命令)`),三路任一命中即可;
+    `ollama` 这类本来就不需要密钥的在 `KEYLESS_PROVIDERS` 里,照样算命中。
+
+    与 pi 对齐:pi 的清单是 `modelRuntime.getAvailableSnapshot()`,而它由
+    `Models.getAvailable()` → `checkProviderAuth()` 产出 —— **没有凭证的 provider
+    一个模型都不进选择器**(pi 只提示 “Only showing models from configured providers.
+    Use /login to add providers.”)。`models.json` 里显式写过的 provider **没有豁免**:
+    写了 `apiKey` 却解析不出来(环境变量没导出、`$(…)` 跑不通),那就是“用不了”,
+    不该在选择器里冒充可选 —— 用户的口径是“我把 mimo logout 了,它怎么还在”,
+    而 `qi doctor` / `--list-models` 仍然会把“缺密钥”列出来(那两个面就是用来看配置的)。
+
+    返回按 provider、再按模型 id 排序(界面直接照着画,不需要各自再排一遍)。
+
+    `store` 是凭证库(默认真的那个)。之所以收 `Any` 而不是 `AuthStore`:这个模块
+    不 import `auth`(auth 的 `apiKey` 引用语法在本模块解析,反向 import 会成环),
+    而调用方传进来的可能是 `AuthOverride`。
+    """
+    if store is None:
+        from .auth import AuthStore            # 局部导入:只在真的要判凭证时用
+        store = AuthStore()
+    from .auth import resolve_key
+    out: list[tuple[str, str]] = []
+    for provider, prov in sorted((cfg.providers or {}).items()):
+        if not resolve_key(provider, prov.apiKey, store).ok:
+            continue
+        for entry in prov.models:
+            out.append((provider, entry.id))
+    return out
+
+
+def resolve_model(cfg: QiConfig, provider: str, model: str) -> ResolvedModel:
+    """按 provider 默认 + 模型条目合并出运行期模型(模型条目可缺省)。"""
+    prov = cfg.providers.get(provider)
+    entry: ModelEntry | None = None
+    if prov is not None:
+        for m in prov.models:
+            if m.id == model:
+                entry = m
+                break
+    api = (entry.api if entry and entry.api else None) or (prov.api if prov else None) or DEFAULT_API
+    return ResolvedModel(
+        provider=provider,
+        model=model,
+        api=api,
+        base_url=prov.baseUrl if prov else None,
+        api_key_ref=prov.apiKey if prov else None,
+        reasoning=entry.reasoning if entry else False,
+        context_window=entry.contextWindow if entry else DEFAULT_CONTEXT_WINDOW,
+        max_tokens=entry.maxTokens if entry else DEFAULT_MAX_TOKENS,
+        entry=entry,
+    )
+
+
+def resolve_default_model(cfg: QiConfig, cwd: Path | None = None) -> ResolvedModel:
+    """解析默认模型;未配置则启动失败(带可照抄的指引)。
+
+    默认模型只从 `settings.json` 读(对齐 pi),`models.json` 不参与。
+    """
+    provider, model, _source = default_model_spec(cwd)
+    if not provider or not model:
+        raise ConfigError(
+            f"缺少默认模型:{SETTINGS_FILE_NAME} 里需要 defaultProvider + defaultModel。\n"
+            "    qi config --set defaultProvider=<name> --set defaultModel=<id>\n"
+            "    （或 `qi init` 引导写入;`qi init --preset deepseek` 一条命令连 provider + 默认模型都写好）\n"
+            "    （预置 provider:deepseek / dashscope / moonshot / zhipu … 见 `qi init --list-presets`）\n"
+            f"    ~/.qi/agent/{SETTINGS_FILE_NAME}    ← 默认模型(对齐 pi)\n"
+            f"    ~/.qi/agent/{MODELS_FILE_NAME}      ← 只放 provider / 模型定义\n"
+            "示例:\n"
+            "    {\n"
+            '      "defaultProvider": "deepseek",\n'
+            '      "defaultModel": "deepseek-chat"\n'
+            "    }\n"
+            + _legacy_hint(cwd)
+        )
+    return resolve_model(cfg, provider, model)
+
+
+def resolve_router_model(cfg: QiConfig, cwd: Path | None = None) -> ResolvedModel:
+    """router 模型;未单独配置则回退 default。"""
+    if cfg.routerProvider and cfg.routerModel:
+        return resolve_model(cfg, cfg.routerProvider, cfg.routerModel)
+    return resolve_default_model(cfg, cwd)
+
+
+# ── 读写原始 models.json(qi init 用) ─────────────────────
+
+def load_models_file(path: Path) -> dict[str, Any]:
+    """读取单个 models.json(不存在/损坏返回 {})。"""
+    if not path.is_file():
+        return {}
+    try:
+        return _read_json(path)
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def save_models_file(path: Path, data: dict[str, Any]) -> None:
+    """写入单个 models.json(0600;虽只存引用,也按敏感文件处理)。"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    with contextlib.suppress(OSError):   # Windows 无 posix chmod
+        os.chmod(path, 0o600)

qi_agent/docs/cli.md

@@ -0,0 +1,188 @@
+# 命令行
+
+qi 的内置命令与选项。装了什么扩展,顶层就还会多出它们注册的旗标与子命令 —— 以 `qi --help` 为准。
+
+```sh
+qi [options] [--] [@files...] [messages...]
+qi install <来源> [options]
+qi remove <来源> [options]
+qi uninstall <来源> [options]
+qi update [来源|self] [options]
+qi list
+qi doctor
+qi config [options]
+qi init [options]
+qi auth <login|logout|list|print-api-key|print-bearer-token|check> [options]
+```
+
+## 调用与输出
+
+```sh
+qi                                  # 交互界面(默认)
+qi "分析这个仓库"                    # 进界面,并把这句话作为首条消息发出
+qi -p "把 CHANGELOG 最近 10 条汇总"   # 无头:只把最终答案写到 stdout
+git diff | qi -p "审查这个改动"       # 管道进来的内容会加到第一条消息前面
+qi --mode json "跑一遍测试" > e.jsonl # 事件流
+qi --export out.html                # 导出会话后退出
+```
+
+| 输入 | 行为 |
+| --- | --- |
+| `message` | 作为第一条消息 |
+| `@path` | 把文本文件内容带进第一条消息 |
+| 管道 stdin | 内容**前置**到第一条消息 |
+| `--` | 停止选项解析(消息本身以 `-` 开头时用) |
+
+| 选项 | 行为 |
+| --- | --- |
+| `-p`, `--print` | 跑完退出,**只把最终答案写 stdout** |
+| `--mode text` | 文本输出;**stdin/stdout 都是终端时仍进界面**(要一次执行就配 `-p`) |
+| `--mode json` | 输出事件流(一行一个 JSON,**隐含无头**)→ [json.md](json.md) |
+| `--mode rpc` | **未实现**:传了会明确报错(见 [PLAN.md](../design/PLAN.md) 的 v2 清单) |
+| `--export <file>` | 导出会话:`.html` → 自包含 HTML,其余 → 原始 JSONL |
+
+**选项写在消息之前**(`qi -nt "问题"`,不是 `qi "问题" -nt`):顶层选项在遇到消息后不再解析 —— 写反了会报错并提示怎么改。
+
+### 输出与中断契约
+
+| 流 | 内容 |
+| --- | --- |
+| stdout | **仅答案正文**(`--mode json` 时为事件 JSON 行) |
+| stderr | 默认空;`--verbose` 时为工具进度(`⚙ ls {"path": "."}` / `↳ …`) |
+
+所以 `qi -p "问题" > out.txt` 拿到的就是纯答案,脚本无需过滤;TUI 不受此限,仍实时显示工具调用。
+
+轮次**不设上限**(交互式与无头都是):退出靠模型不再调工具、中止,或嵌入方的 `stop_after` 谓词(qi 自己从不传)。
+中断退出码 `128+n`:`SIGTERM` / `SIGHUP` → 回收在跑的子进程组 + `exit(143/129)`;`SIGINT` → asyncio 取消 →
+`run_shell` 的 finally 回收 + `exit(130)`,不打 traceback。两条路径的半截回答都会落盘。
+
+## 模型
+
+```sh
+qi --model sonnet:high
+```
+
+选择与凭证见 [models.md](models.md)、[providers.md](providers.md)。
+
+- `--provider <名>`:把 `--model` 的查找限制在一家。
+- `--model <模式>`:写 `provider/模型`,可带 `:<思考级别>` 后缀(**只认已知级别**,所以 `openrouter/x:free` 不会被误切);只给 `--provider` 时用它 `models.json` 里的第一个模型。
+- `--api-key <键>`:**按次**覆盖密钥,不落盘(优先于 auth store / 环境变量 / `models.json`)。
+- `--thinking <级别>`:`off` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`(非法值退出码 2;不传用 settings 的 `defaultThinkingLevel`,没配就 `medium`)。
+- `--models <清单>`:本次运行 `ctrl+p` 的轮换清单(逗号分隔),**不回写** settings。
+- `--list-models [搜索词]`:列出模型后退出(每行带 `credential` 列;缺密钥的也列,这是诊断面)。
+
+## 会话
+
+```sh
+qi -c
+```
+
+细节见 [sessions.md](sessions.md)。
+
+- `-c`, `--continue`:接着最近一条(按**文件修改时间**,不是 header 时间)。
+- `-r`, `--resume`:打开会话选择器(**需要 TTY**;与 TUI 的 `/resume` 同一条路)。
+- `--session <路径|id>`:先当文件路径,再当 id / 文件名前缀。
+- `--session-id <id>`:精确的项目会话 id,不存在则建。
+- `--fork <路径|id>`:从已有会话分叉出新会话(复制当前分支)。
+- `--session-dir <dir>`:会话目录(优先于 `settings.sessionDir`)。
+- `--no-session`:内存会话,**不落盘**。
+- `-n`, `--name <名>`:会话显示名(命名即落盘)。
+
+## 工具
+
+```sh
+qi --tools read,grep,find,ls -p "审查这个项目"
+```
+
+内置工具清单与三态语义见 [how-qi-works.md](how-qi-works.md);默认档在 `settings.defaultTools`。
+
+- `-t`, `--tools <清单>`:**严格白名单** —— 最终工具集就是这些(不再叠加默认集)。
+- `-xt`, `--exclude-tools <清单>`:从最终集合里排除(在其它选择之后生效)。
+- `-nbt`, `--no-builtin-tools`:禁用内置工具,**保留扩展装的**。
+- `-nt`, `--no-tools`:禁用全部工具。
+
+`-t` 与 `-nt` / `-nbt` **互斥**(同给报错退出码 2);未注册的名字会报一条提示,不静默丢。
+
+## 资源
+
+- `--skill <路径>`:额外加载一个技能(可重复,叠加;优先级高于所有自动发现层)。
+- `--no-skills` / `-ns`:关掉技能的**自动发现**(`--skill` 仍生效)。
+- `-e`, `--extension <目录>`:本次运行临时加载一个扩展目录(仅本进程,`scope=temporary`;TUI 与无头都生效)。
+- `--ext name=value`:给扩展声明过的**旗标**传值(与 `-e` 不是一回事)。见 [extensions.md](extensions.md)。
+- `--no-extensions` / `-ne`:关掉扩展**发现**,`-e` 显式给的仍生效。
+
+## 提示词与上下文
+
+- `--system-prompt "<文本\|文件>"`:**整体替换**基座(与 `.qi/SYSTEM.md` 同语义,只本次运行)。
+- `--append-system-prompt "<文本\|文件>"`:追加到每回合提示词末尾(可重复,空行连接)。
+- `--no-context-files` / `-nc`:不注入 `AGENTS.md` / `CLAUDE.md`。
+
+语义与副作用见 [configuration.md](configuration.md)。
+
+## 界面
+
+- `--tui-mode <regular|fullscreen>`:渲染模式(非法值退出码 2),压过 `settings.tuiMode`。
+  `fullscreen`(默认)= 备用屏、qi 拥有视口;`regular` = inline、滚动交给终端。见 [usage.md](usage.md)。
+
+## 包命令
+
+```sh
+qi install <来源> [-l]      # 调 pip + 写进 settings.packages;本地目录只登记(不调 pip)
+qi remove <来源> [-l]       # 只从声明里移除(不卸包),并把 pip uninstall 命令打出来
+qi uninstall <来源> [-l]    # 同 remove
+qi update [来源|self] [--self|--extensions|--all|--extension <来源>|--force]
+qi list                     # 列出已装扩展,并与声明双向比对
+qi doctor                   # 诊断(含「声明了没装」的可复制装法)
+```
+
+`qi update` 默认只更 qi 自己;`--models` 在 qi **无意义**(模型全在 `models.json` 里自己维护,它只说明这一点然后退出)。
+`qi install` 每次都先把要跑的 pip 命令打出来 —— 目标环境(自家 venv / `uv tool` / 只读解释器)的行为真的不同,
+声明与比对的意义见 [packages.md](packages.md)。
+
+## 设置与初始化
+
+```sh
+qi config [-l] [--get K] [--set K=V] [--unset K] [--json]
+qi init [-y] [-l] [--provider … --model …]
+qi init --list-presets | --preset <名>[,<名>] | --refresh <名>[,<名>] | --refresh-all
+```
+
+- `qi config` 不带旗标:TTY 下开**资源启停面板**(space 勾选 · `ctrl+s` 保存 · `escape` 取消;`-l` 切作用域),
+  非 TTY 打一张资源表 + 设置总览。`--set` 的值先按 JSON 解析、失败则当字符串;`--get` / `--unset` 支持点号路径。
+  字段清单见 [settings.md](settings.md)。
+- 资源的"关"写的是**声明**:目录扩展 → `settings.extensions[]` 加 `-<路径>`;pip 包 → `packages` 里那条换成
+  `{"source": …, "extensions": []}`。所以状态被记住,也能表达"项目关掉、全局还开着"。
+- `qi init` 引导默认模型,详见 [models.md](models.md)。
+
+## 凭证命令
+
+```sh
+qi auth login <provider>            # 输入可见地写入 auth.json(0600);TUI 里的 /login 是遮罩输入
+qi auth logout <provider>           # 删除该 provider 的凭证(= qi auth rm)
+qi auth list                        # 只列有凭证的 provider 名
+qi auth print-api-key [--provider P] [--model M]
+qi auth print-bearer-token [--provider P] [--model M] [--min-expiry 30m]
+qi auth check [--provider P] [--model M] [--json] [--credentials]
+```
+
+- 解析顺序:auth store(`auth.json`)→ 约定环境变量 → `models.json` 的 `apiKey` 引用。
+- 只读子命令必须给 `--provider` 或 `--model` 之一(只给 `--model` 时反查 provider;多家都有该模型时报错)。
+- `check` 退出码:`ready`=0 / `not_ready`=1 / `invalid`=2。`print-bearer-token` 的 `--min-expiry` **只校验格式**
+  (`qi` 的凭证没有过期时间)。两个命令都接受 `--no-refresh` 但它是空操作 —— **qi 没有 OAuth**。
+
+## 信任
+
+- `-a`, `--approve`:信任本项目 `.qi`(本次运行,加载项目级扩展)。
+- `-na`, `--no-approve`:明确不信任。两个同给报错退出码 2。
+
+未表态时看用户级 `settings.defaultProjectTrust`(`ask` 在无头下保守判不信任,并在 stderr 提示用 `-a`)。
+见 [security.md](security.md)。
+
+## 通用
+
+- `-h`, `--help` / `-v`, `--version` / `--`(结束参数解析)。
+- `--verbose`:把工具进度打到 stderr(TUI 里本来就有)。
+- `--offline`:**被接受但什么都不做** —— qi 启动期没有任何网络操作(唯一联网的地方是模型调用)。
+- **短旗标 `-t` / `-xt` / `-nt` / `-nbt` 是 argv 展开**:click 会按字符解析短选项(`-nt` 会被拆成 `-n t`,
+  会话名静默变成 `"t"`),所以 qi 在交给 typer 之前把它们展开成长写法。代价是值位置上的 `-nt` 不被当旗标
+  (`qi -n -nt` = 会话名叫 `-nt`)—— 这是对的。