@symerian/symi 3.0.20 → 3.0.22

package/docs/zh-CN/concepts/model-providers.md

@@ -1,320 +0,0 @@
----
-read_when:
-  - 你需要按提供商分类的模型设置参考
-  - 你需要模型提供商的示例配置或 CLI 新手引导命令
-summary: 模型提供商概述，包含示例配置和 CLI 流程
-title: 模型提供商
-x-i18n:
-  generated_at: "2026-02-03T07:46:28Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 14f73e5a9f9b7c6f017d59a54633942dba95a3eb50f8848b836cfe0b9f6d7719
-  source_path: concepts/model-providers.md
-  workflow: 15
----
-
-# 模型提供商
-
-本页介绍 **LLM/模型提供商**（不是 WhatsApp/Telegram 等聊天渠道）。
-关于模型选择规则，请参阅 [/concepts/models](/concepts/models)。
-
-## 快速规则
-
-- 模型引用使用 `provider/model` 格式（例如：`opencode/claude-opus-4-5`）。
-- 如果设置了 `agents.defaults.models`，它将成为允许列表。
-- CLI 辅助工具：`symi onboard`、`symi models list`、`symi models set <provider/model>`。
-
-## 内置提供商（pi-ai 目录）
-
-Symi 附带 pi-ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证 + 选择模型。
-
-### OpenAI
-
-- 提供商：`openai`
-- 认证：`OPENAI_API_KEY`
-- 示例模型：`openai/gpt-5.2`
-- CLI：`symi onboard --auth-choice openai-api-key`
-
-```json5
-{
-  agents: { defaults: { model: { primary: "openai/gpt-5.2" } } },
-}
-```
-
-### Anthropic
-
-- 提供商：`anthropic`
-- 认证：`ANTHROPIC_API_KEY` 或 `claude setup-token`
-- 示例模型：`anthropic/claude-opus-4-5`
-- CLI：`symi onboard --auth-choice token`（粘贴 setup-token）或 `symi models auth paste-token --provider anthropic`
-
-```json5
-{
-  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } },
-}
-```
-
-### OpenAI Code (Codex)
-
-- 提供商：`openai-codex`
-- 认证：OAuth (ChatGPT)
-- 示例模型：`openai-codex/gpt-5.2`
-- CLI：`symi onboard --auth-choice openai-codex` 或 `symi models auth login --provider openai-codex`
-
-```json5
-{
-  agents: { defaults: { model: { primary: "openai-codex/gpt-5.2" } } },
-}
-```
-
-### OpenCode Zen
-
-- 提供商：`opencode`
-- 认证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
-- 示例模型：`opencode/claude-opus-4-5`
-- CLI：`symi onboard --auth-choice opencode-zen`
-
-```json5
-{
-  agents: { defaults: { model: { primary: "opencode/claude-opus-4-5" } } },
-}
-```
-
-### Google Gemini（API 密钥）
-
-- 提供商：`google`
-- 认证：`GEMINI_API_KEY`
-- 示例模型：`google/gemini-3-pro-preview`
-- CLI：`symi onboard --auth-choice gemini-api-key`
-
-### Google Vertex、Antigravity 和 Gemini CLI
-
-- 提供商：`google-vertex`、`google-antigravity`、`google-gemini-cli`
-- 认证：Vertex 使用 gcloud ADC；Antigravity/Gemini CLI 使用各自的认证流程
-- Antigravity OAuth 作为捆绑插件提供（`google-antigravity-auth`，默认禁用）。
-  - 启用：`symi plugins enable google-antigravity-auth`
-  - 登录：`symi models auth login --provider google-antigravity --set-default`
-- Gemini CLI OAuth 作为捆绑插件提供（`google-gemini-cli-auth`，默认禁用）。
-  - 启用：`symi plugins enable google-gemini-cli-auth`
-  - 登录：`symi models auth login --provider google-gemini-cli --set-default`
-  - 注意：你**不需要**将客户端 ID 或密钥粘贴到 `symi.json` 中。CLI 登录流程将令牌存储在 Gateway 网关主机的认证配置文件中。
-
-### Z.AI (GLM)
-
-- 提供商：`zai`
-- 认证：`ZAI_API_KEY`
-- 示例模型：`zai/glm-4.7`
-- CLI：`symi onboard --auth-choice zai-api-key`
-  - 别名：`z.ai/*` 和 `z-ai/*` 规范化为 `zai/*`
-
-### Vercel AI Gateway
-
-- 提供商：`vercel-ai-gateway`
-- 认证：`AI_GATEWAY_API_KEY`
-- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.5`
-- CLI：`symi onboard --auth-choice ai-gateway-api-key`
-
-### 其他内置提供商
-
-- OpenRouter：`openrouter`（`OPENROUTER_API_KEY`）
-- 示例模型：`openrouter/anthropic/claude-sonnet-4-5`
-- xAI：`xai`（`XAI_API_KEY`）
-- Groq：`groq`（`GROQ_API_KEY`）
-- Cerebras：`cerebras`（`CEREBRAS_API_KEY`）
-  - Cerebras 上的 GLM 模型使用 ID `zai-glm-4.7` 和 `zai-glm-4.6`。
-  - OpenAI 兼容的基础 URL：`https://api.cerebras.ai/v1`。
-- Mistral：`mistral`（`MISTRAL_API_KEY`）
-- GitHub Copilot：`github-copilot`（`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`）
-
-## 通过 `models.providers` 配置的提供商（自定义/基础 URL）
-
-使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容的代理。
-
-### Moonshot AI (Kimi)
-
-Moonshot 使用 OpenAI 兼容端点，因此将其配置为自定义提供商：
-
-- 提供商：`moonshot`
-- 认证：`MOONSHOT_API_KEY`
-- 示例模型：`moonshot/kimi-k2.5`
-
-Kimi K2 模型 ID：
-
-{/_ moonshot-kimi-k2-model-refs:start _/ && null}
-
-- `moonshot/kimi-k2.5`
-- `moonshot/kimi-k2-0905-preview`
-- `moonshot/kimi-k2-turbo-preview`
-- `moonshot/kimi-k2-thinking`
-- `moonshot/kimi-k2-thinking-turbo`
-  {/_ moonshot-kimi-k2-model-refs:end _/ && null}
-
-```json5
-{
-  agents: {
-    defaults: { model: { primary: "moonshot/kimi-k2.5" } },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      moonshot: {
-        baseUrl: "https://api.moonshot.ai/v1",
-        apiKey: "${MOONSHOT_API_KEY}",
-        api: "openai-completions",
-        models: [{ id: "kimi-k2.5", name: "Kimi K2.5" }],
-      },
-    },
-  },
-}
-```
-
-### Kimi Coding
-
-Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
-
-- 提供商：`kimi-coding`
-- 认证：`KIMI_API_KEY`
-- 示例模型：`kimi-coding/k2p5`
-
-```json5
-{
-  env: { KIMI_API_KEY: "sk-..." },
-  agents: {
-    defaults: { model: { primary: "kimi-coding/k2p5" } },
-  },
-}
-```
-
-### Qwen OAuth（免费层级）
-
-Qwen 通过设备码流程提供对 Qwen Coder + Vision 的 OAuth 访问。
-启用捆绑插件，然后登录：
-
-```bash
-symi plugins enable qwen-portal-auth
-symi models auth login --provider qwen-portal --set-default
-```
-
-模型引用：
-
-- `qwen-portal/coder-model`
-- `qwen-portal/vision-model`
-
-参见 [/providers/qwen](/providers/qwen) 了解设置详情和注意事项。
-
-### Synthetic
-
-Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型：
-
-- 提供商：`synthetic`
-- 认证：`SYNTHETIC_API_KEY`
-- 示例模型：`synthetic/hf:MiniMaxAI/MiniMax-M2.1`
-- CLI：`symi onboard --auth-choice synthetic-api-key`
-
-```json5
-{
-  agents: {
-    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.1" } },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      synthetic: {
-        baseUrl: "https://api.synthetic.new/anthropic",
-        apiKey: "${SYNTHETIC_API_KEY}",
-        api: "anthropic-messages",
-        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.1", name: "MiniMax M2.1" }],
-      },
-    },
-  },
-}
-```
-
-### MiniMax
-
-MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
-
-- MiniMax（Anthropic 兼容）：`--auth-choice minimax-api`
-- 认证：`MINIMAX_API_KEY`
-
-参见 [/providers/minimax](/providers/minimax) 了解设置详情、模型选项和配置片段。
-
-### Ollama
-
-Ollama 是提供 OpenAI 兼容 API 的本地 LLM 运行时：
-
-- 提供商：`ollama`
-- 认证：无需（本地服务器）
-- 示例模型：`ollama/llama3.3`
-- 安装：https://ollama.ai
-
-```bash
-# Install Ollama, then pull a model:
-ollama pull llama3.3
-```
-
-```json5
-{
-  agents: {
-    defaults: { model: { primary: "ollama/llama3.3" } },
-  },
-}
-```
-
-当 Ollama 在本地 `http://127.0.0.1:11434/v1` 运行时会自动检测。参见 [/providers/ollama](/providers/ollama) 了解模型推荐和自定义配置。
-
-### 本地代理（LM Studio、vLLM、LiteLLM 等）
-
-示例（OpenAI 兼容）：
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "lmstudio/minimax-m2.1-gs32" },
-      models: { "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" } },
-    },
-  },
-  models: {
-    providers: {
-      lmstudio: {
-        baseUrl: "http://localhost:1234/v1",
-        apiKey: "LMSTUDIO_KEY",
-        api: "openai-completions",
-        models: [
-          {
-            id: "minimax-m2.1-gs32",
-            name: "MiniMax M2.1",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 200000,
-            maxTokens: 8192,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-注意事项：
-
-- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 是可选的。
-  省略时，Symi 默认为：
-  - `reasoning: false`
-  - `input: ["text"]`
-  - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
-  - `contextWindow: 200000`
-  - `maxTokens: 8192`
-- 建议：设置与你的代理/模型限制匹配的显式值。
-
-## CLI 示例
-
-```bash
-symi onboard --auth-choice opencode-zen
-symi models set opencode/claude-opus-4-5
-symi models list
-```
-
-另请参阅：[/gateway/configuration](/gateway/configuration) 了解完整配置示例。

package/docs/zh-CN/concepts/models.md

@@ -1,196 +0,0 @@
----
-read_when:
-  - 添加或修改模型 CLI（models list/set/scan/aliases/fallbacks）
-  - 更改模型回退行为或选择用户体验
-  - 更新模型扫描探测（工具/图像）
-summary: 模型 CLI：列表、设置、别名、回退、扫描、状态
-title: 模型 CLI
-x-i18n:
-  generated_at: "2026-02-03T10:05:42Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: e8b54bb370b4f63a9b917594fb0f6ff48192e168196d30c713b8bbe72b78fef6
-  source_path: concepts/models.md
-  workflow: 15
----
-
-# 模型 CLI
-
-参见 [/concepts/model-failover](/concepts/model-failover) 了解认证配置文件轮换、冷却时间及其与回退的交互。
-快速提供商概述 + 示例：[/concepts/model-providers](/concepts/model-providers)。
-
-## 模型选择工作原理
-
-Symi 按以下顺序选择模型：
-
-1. **主要**模型（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
-2. `agents.defaults.model.fallbacks` 中的**回退**（按顺序）。
-3. **提供商认证故障转移**在移动到下一个模型之前在提供商内部发生。
-
-相关：
-
-- `agents.defaults.models` 是 Symi 可使用的模型白名单/目录（加上别名）。
-- `agents.defaults.imageModel` **仅在**主要模型无法接受图像时使用。
-- 每个智能体的默认值可以通过 `agents.list[].model` 加绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/concepts/multi-agent)）。
-
-## 快速模型推荐（经验之谈）
-
-- **GLM**：在编程/工具调用方面稍好。
-- **MiniMax**：在写作和氛围方面更好。
-
-## 设置向导（推荐）
-
-如果你不想手动编辑配置，请运行新手引导向导：
-
-```bash
-symi onboard
-```
-
-它可以为常见提供商设置模型 + 认证，包括 **OpenAI Code（Codex）订阅**（OAuth）和 **Anthropic**（推荐使用 API 密钥；也支持 `claude setup-token`）。
-
-## 配置键（概述）
-
-- `agents.defaults.model.primary` 和 `agents.defaults.model.fallbacks`
-- `agents.defaults.imageModel.primary` 和 `agents.defaults.imageModel.fallbacks`
-- `agents.defaults.models`（白名单 + 别名 + 提供商参数）
-- `models.providers`（写入 `models.json` 的自定义提供商）
-
-模型引用会规范化为小写。提供商别名如 `z.ai/*` 会规范化为 `zai/*`。
-
-提供商配置示例（包括 OpenCode Zen）在 [/gateway/configuration](/gateway/configuration#opencode-zen-multi-model-proxy)。
-
-## "Model is not allowed"（以及为什么回复停止）
-
-如果设置了 `agents.defaults.models`，它将成为 `/model` 和会话覆盖的**白名单**。当用户选择不在该白名单中的模型时，Symi 返回：
-
-```
-Model "provider/model" is not allowed. Use /model to list available models.
-```
-
-这发生在正常回复生成**之前**，所以消息可能感觉像"没有响应"。修复方法是：
-
-- 将模型添加到 `agents.defaults.models`，或
-- 清除白名单（删除 `agents.defaults.models`），或
-- 从 `/model list` 中选择一个模型。
-
-白名单配置示例：
-
-```json5
-{
-  agent: {
-    model: { primary: "anthropic/claude-sonnet-4-5" },
-    models: {
-      "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
-      "anthropic/claude-opus-4-5": { alias: "Opus" },
-    },
-  },
-}
-```
-
-## 在聊天中切换模型（`/model`）
-
-你可以在不重启的情况下切换当前会话的模型：
-
-```
-/model
-/model list
-/model 3
-/model openai/gpt-5.2
-/model status
-```
-
-注意事项：
-
-- `/model`（和 `/model list`）是紧凑的编号选择器（模型系列 + 可用提供商）。
-- `/model <#>` 从该选择器中选择。
-- `/model status` 是详细视图（认证候选项，以及配置时的提供商端点 `baseUrl` + `api` 模式）。
-- 模型引用通过在**第一个** `/` 处分割来解析。输入 `/model <ref>` 时使用 `provider/model`。
-- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（例如：`/model openrouter/moonshotai/kimi-k2`）。
-- 如果省略提供商，Symi 将输入视为别名或**默认提供商**的模型（仅在模型 ID 中没有 `/` 时有效）。
-
-完整命令行为/配置：[斜杠命令](/tools/slash-commands)。
-
-## CLI 命令
-
-```bash
-symi models list
-symi models status
-symi models set <provider/model>
-symi models set-image <provider/model>
-
-symi models aliases list
-symi models aliases add <alias> <provider/model>
-symi models aliases remove <alias>
-
-symi models fallbacks list
-symi models fallbacks add <provider/model>
-symi models fallbacks remove <provider/model>
-symi models fallbacks clear
-
-symi models image-fallbacks list
-symi models image-fallbacks add <provider/model>
-symi models image-fallbacks remove <provider/model>
-symi models image-fallbacks clear
-```
-
-`symi models`（无子命令）是 `models status` 的快捷方式。
-
-### `models list`
-
-默认显示已配置的模型。有用的标志：
-
-- `--all`：完整目录
-- `--local`：仅本地提供商
-- `--provider <name>`：按提供商筛选
-- `--plain`：每行一个模型
-- `--json`：机器可读输出
-
-### `models status`
-
-显示已解析的主要模型、回退、图像模型，以及已配置提供商的认证概述。它还显示认证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内警告）。`--plain` 仅打印已解析的主要模型。
-OAuth 状态始终显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印 **Missing auth** 部分。
-JSON 包括 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的有效认证）。
-使用 `--check` 进行自动化（缺失/过期时退出 `1`，即将过期时退出 `2`）。
-
-首选的 Anthropic 认证是 Claude Code CLI setup-token（在任何地方运行；如需要在 Gateway 网关主机上粘贴）：
-
-```bash
-claude setup-token
-symi models status
-```
-
-## 扫描（OpenRouter 免费模型）
-
-`symi models scan` 检查 OpenRouter 的**免费模型目录**，并可选择性地探测模型的工具和图像支持。
-
-关键标志：
-
-- `--no-probe`：跳过实时探测（仅元数据）
-- `--min-params <b>`：最小参数量（十亿）
-- `--max-age-days <days>`：跳过较旧的模型
-- `--provider <name>`：提供商前缀筛选
-- `--max-candidates <n>`：回退列表大小
-- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择
-- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择
-
-探测需要 OpenRouter API 密钥（来自认证配置文件或 `OPENROUTER_API_KEY`）。没有密钥时，使用 `--no-probe` 仅列出候选项。
-
-扫描结果按以下顺序排名：
-
-1. 图像支持
-2. 工具延迟
-3. 上下文大小
-4. 参数数量
-
-输入
-
-- OpenRouter `/models` 列表（筛选 `:free`）
-- 需要来自认证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/help/environment)）
-- 可选筛选器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
-- 探测控制：`--timeout`、`--concurrency`
-
-在 TTY 中运行时，你可以交互式选择回退。在非交互模式下，传递 `--yes` 接受默认值。
-
-## 模型注册表（`models.json`）
-
-`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.symi/agents/<agentId>/models.json`）。除非 `models.mode` 设置为 `replace`，否则此文件默认会被合并。