@jsonstudio/rcc 0.90.141 → 0.90.181

package/dist/server/utils/finish-reason.js

@@ -0,0 +1,75 @@
+export const STREAM_LOG_FINISH_REASON_KEY = "__routecodex_finish_reason";
+export function deriveFinishReason(body) {
+    const record = asRecord(body);
+    if (!record) {
+        return undefined;
+    }
+    const choices = Array.isArray(record.choices) ? record.choices : [];
+    const firstChoice = asRecord(choices[0]);
+    const choiceFinishReason = readNonEmptyString(firstChoice?.finish_reason);
+    if (choiceFinishReason) {
+        return choiceFinishReason;
+    }
+    const stopReason = readNonEmptyString(record.stop_reason);
+    if (stopReason) {
+        return mapStopReasonToFinishReason(stopReason);
+    }
+    const responseStatus = readNonEmptyString(record.status)?.toLowerCase();
+    if (hasResponsesToolCall(record)) {
+        return "tool_calls";
+    }
+    const incompleteReason = readNonEmptyString(asRecord(record.incomplete_details)?.reason);
+    if (incompleteReason) {
+        return mapIncompleteReasonToFinishReason(incompleteReason);
+    }
+    if (responseStatus === "completed") {
+        return "stop";
+    }
+    if (responseStatus === "requires_action") {
+        return "tool_calls";
+    }
+    return readNonEmptyString(record[STREAM_LOG_FINISH_REASON_KEY]);
+}
+function hasResponsesToolCall(record) {
+    const requiredAction = asRecord(record.required_action);
+    if (asRecord(requiredAction?.submit_tool_outputs)) {
+        return true;
+    }
+    const output = Array.isArray(record.output) ? record.output : [];
+    return output.some((item) => {
+        const type = readNonEmptyString(asRecord(item)?.type)?.toLowerCase();
+        return type === "function_call" || type === "tool_call";
+    });
+}
+function mapStopReasonToFinishReason(stopReason) {
+    const normalized = stopReason.trim().toLowerCase();
+    switch (normalized) {
+        case "end_turn":
+            return "stop";
+        case "tool_use":
+            return "tool_calls";
+        case "max_tokens":
+            return "length";
+        default:
+            return normalized;
+    }
+}
+function mapIncompleteReasonToFinishReason(reason) {
+    const normalized = reason.trim().toLowerCase();
+    switch (normalized) {
+        case "max_output_tokens":
+        case "max_tokens":
+            return "length";
+        default:
+            return normalized;
+    }
+}
+function readNonEmptyString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+//# sourceMappingURL=finish-reason.js.map

package/dist/server/utils/finish-reason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-reason.js","sourceRoot":"","sources":["../../../src/server/utils/finish-reason.ts"],"names":[],"mappings":"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"}

package/docs/provider-analysis.md

@@ -0,0 +1,331 @@
+# RouteCodex Provider 配置与初始化引导梳理
+
+## 一、当前 Provider 初始化状态机
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Provider 初始化流程                        │
+└─────────────────────────────────────────────────────────────────┘
+
+[开始]
+   │
+   ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  1. 检查配置状态 (inspectConfigState)                          │
+│     ├─ missing → 首次初始化                                       │
+│     ├─ invalid → 错误退出                                          │
+│     ├─ v1 → V1→V2 迁移                                            │
+│     └─ v2 → V2 维护菜单                                            │
+└─────────────────────────────────────────────────────────────────┘
+   │
+   ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  2. 配置初始化分支                                                 │
+│                                                                   │
+│  ┌─────────────┐    ┌──────────────┐    ┌──────────────────┐ │
+│  │ 首次初始化    │→   │ V1→V2 迁移   │→   │  V2 维护菜单      │ │
+│  └─────────────┘    └──────────────┘    └──────────────────┘ │
+│         │                  │                      │             │
+│         ▼                  ▼                      ▼             │
+│  ┌──────────────┐  ┌──────────────┐   ┌──────────────────┐ │
+│  │- 选择 Provider│  │- 拆分 Provider│   │- 编辑路由         │ │
+│  │  模板         │  │  配置文件      │   │- 添加/删除 Provider│ │
+│  │- 设置默认     │  │- 备份原配置    │   │- 调整端口/主机     │ │
+│  │  Provider     │  │- 生成 V2 配置  │   │- 配置 Web Search  │ │
+│  │- 配置路由     │  └──────────────┘   └──────────────────┘ │
+│  └──────────────┘                                             │
+└─────────────────────────────────────────────────────────────────┘
+   │
+   ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  3. Provider 配置生成 (writeProviderV2)                        │
+│     位置: ~/.routecodex/provider/{providerId}/config.v2.json  │
+│                                                                   │
+│  配置结构:                                                       │
+│  {                                                               │
+│    "version": "v2",                                              │
+│    "providerId": "openai",                                       │
+│    "provider": {                                                  │
+│      "id": "openai",                                             │
+│      "enabled": true,                                             │
+│      "type": "openai",                                           │
+│      "baseURL": "https://api.openai.com/v1",                   │
+│      "auth": { "type": "apikey", "apiKey": "${OPENAI_API_KEY}" },│
+│      "models": { "gpt-5.2": { "supportsStreaming": true } }   │
+│    }                                                             │
+│  }                                                               │
+└─────────────────────────────────────────────────────────────────┘
+   │
+   ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  4. 主配置生成 (buildV2ConfigObject)                            │
+│     位置: ~/.routecodex/config.json                              │
+│                                                                   │
+│  配置结构:                                                       │
+│  {                                                               │
+│    "virtualrouterMode": "v2",                                    │
+│    "httpserver": { "host": "127.0.0.1", "port": 5555 },      │
+│    "virtualrouter": {                                             │
+│      "activeRoutingPolicyGroup": "default",                      │
+│      "routingPolicyGroups": {                                     │
+│        "default": {                                               │
+│          "routing": {                                             │
+│            "default": [{ "id": "default-primary", "targets": [...] }],│
+│            "thinking": [...],                                     │
+│            "tools": [...],                                        │
+│            "web_search": [...]                                    │
+│          }                                                       │
+│        }                                                         │
+│      }                                                           │
+│    }                                                             │
+│  }                                                               │
+└─────────────────────────────────────────────────────────────────┘
+   │
+   ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  5. 可选: Camoufox 环境准备 (maybePrepareCamoufoxEnvironment) │
+└─────────────────────────────────────────────────────────────────┘
+   │
+   ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  6. Provider 运行时初始化 (服务器启动时)                          │
+│     ├─ bootstrapVirtualRouterConfig()                            │
+│     ├─ initializeProviderRuntimes()                              │
+│     ├─ 非阻塞认证验证 (runNonBlockingCredentialValidation)      │
+│     └─ Antigravity 预热 (fire-and-forget)                       │
+└─────────────────────────────────────────────────────────────────┘
+   │
+   ▼
+[完成]
+```
+
+## 二、如何初始化新的 Provider
+
+### 方式一: 使用 CLI 交互式初始化
+
+```bash
+# 1. 查看可用 Provider 模板
+routecodex init --list-providers
+
+# 2. 交互式初始化 (选择 Provider、路由等)
+routecodex init
+
+# 3. 或使用命令行参数直接指定
+routecodex init --providers openai,qwen --default-provider qwen --force
+```
+
+### 方式二: 手动添加 Provider
+
+1. **创建 Provider 配置目录**:
+
+```bash
+mkdir -p ~/.routecodex/provider/myprovider
+```
+
+2. **创建 config.v2.json**:
+
+```json
+{
+  "version": "v2",
+  "providerId": "myprovider",
+  "provider": {
+    "id": "myprovider",
+    "enabled": true,
+    "type": "openai",
+    "baseURL": "https://api.myprovider.com/v1",
+    "compatibilityProfile": "chat:openai",
+    "auth": {
+      "type": "apikey",
+      "apiKey": "${MYPROVIDER_API_KEY}"
+    },
+    "models": {
+      "my-model-1": { "supportsStreaming": true },
+      "my-model-2": { "supportsStreaming": true }
+    },
+    "defaultModel": "my-model-1"
+  }
+}
+```
+
+3. **更新主配置 config.json 中的路由**:
+
+```json
+{
+  "virtualrouter": {
+    "routingPolicyGroups": {
+      "default": {
+        "routing": {
+          "default": [
+            {
+              "id": "default-primary",
+              "targets": ["myprovider.my-model-1"]
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+4. **设置环境变量**:
+
+```bash
+export MYPROVIDER_API_KEY="your-api-key-here"
+```
+
+### 方式三: 使用 Provider Doctor 验证
+
+```bash
+# 检查 Provider 配置
+routecodex provider inspect myprovider
+
+# 使用路由提示
+routecodex provider inspect myprovider --routing-hints
+
+# 使用 Vercel AI SDK 验证连接
+routecodex provider doctor myprovider
+```
+
+## 三、README 中标注情况分析
+
+### ✅ 已清晰标注的内容
+
+1. **基本初始化流程** (README.md 第 93-157 行):
+   - `rcc init` 基本用法
+   - V1→V2 迁移步骤
+   - 环境变量配置
+   - Provider 鉴权类型对照表
+
+2. **Provider 目录结构** (README.md 第 142-144 行):
+   - `~/.routecodex/provider/<providerId>/config.v2.json`
+
+3. **Provider 类型文档**:
+   - `docs/PROVIDER_TYPES.md` - Provider 类型说明
+   - `docs/PROVIDERS_BUILTIN.md` - 内置 Provider 列表
+
+4. **Provider 模块架构**:
+   - `src/providers/README.md` - Provider V2 模块说明
+
+### ⚠️ 不够清晰或缺失的内容
+
+1. **手动添加 Provider 的完整步骤** - 只有 CLI 方式，缺少手动创建配置的详细指南
+2. **Provider 配置文件 schema 说明** - 没有完整的 config.v2.json 字段说明文档
+3. **自定义 Provider 开发指南** - 如何添加不在 catalog 中的新 Provider 类型
+4. **路由配置详细说明** - routingPolicyGroups 的完整 schema 和最佳实践
+5. **provider inspect/routing-hints 的使用场景** - 这些高级功能的实际应用案例
+
+## 四、优化方向
+
+### 1. 文档优化
+
+#### A. 新增或完善文档
+
+- [ ] `docs/PROVIDER_CONFIG_V2.md` - Provider V2 配置完整 schema 说明
+- [ ] `docs/PROVIDER_ADD_MANUAL.md` - 手动添加 Provider 完整步骤指南
+- [ ] `docs/ROUTING_POLICY_GUIDE.md` - 路由策略配置完整指南
+- [ ] 更新 `README.md` - 补充手动添加 Provider 的章节
+
+#### B. 增强现有文档
+
+- [ ] 在 `README.md` 中添加 "Provider 管理" 独立章节
+- [ ] 在 `src/providers/README.md` 中添加配置示例
+- [ ] 补充 `provider inspect --routing-hints` 的实际应用案例
+
+### 2. CLI 工具增强
+
+#### A. 新增命令
+
+```bash
+# 新增 provider add 命令
+routecodex provider add myprovider \
+  --type openai \
+  --base-url https://api.myprovider.com/v1 \
+  --auth-type apikey \
+  --env-var MYPROVIDER_API_KEY \
+  --model "my-model-1:supportsStreaming=true" \
+  --model "my-model-2:supportsStreaming=true" \
+  --default-model my-model-1
+
+# 新增 provider template 命令 - 导出模板
+routecodex provider template openai > myprovider-template.json
+
+# 新增 provider validate 命令 - 验证配置
+routecodex provider validate myprovider
+```
+
+#### B. 增强现有命令
+
+- [ ] `init` 命令支持从 JSON 模板导入 Provider 配置
+- [ ] `provider inspect` 输出更友好的配置建议
+- [ ] `provider doctor` 支持更多 Provider 类型
+
+### 3. 配置系统增强
+
+#### A. Provider Catalog 扩展
+
+- [ ] 支持自定义 catalog 扩展 (`~/.routecodex/provider-catalog.json`)
+- [ ] 支持从远程 URL 加载 catalog
+- [ ] catalog 版本管理和更新检查
+
+#### B. 配置验证
+
+- [ ] Provider 配置加载时的完整 schema 验证
+- [ ] 更友好的配置错误提示
+- [ ] 配置 lint 工具
+
+### 4. 开发者体验优化
+
+#### A. 配置生成辅助
+
+- [ ] 交互式 `provider add` 向导
+- [ ] 从 OpenAPI/Swagger 文档生成 Provider 配置
+- [ ] Provider 配置分享和导入导出
+
+#### B. 调试工具
+
+- [ ] Provider 配置 dry-run 模式
+- [ ] 实时配置变更预览
+- [ ] 配置历史和回滚
+
+## 五、优先级建议
+
+### P0 (立即实施)
+
+1. **文档**: 新增 `docs/PROVIDER_CONFIG_V2.md` - Provider V2 配置完整 schema
+2. **文档**: 在 `README.md` 中补充"手动添加 Provider"完整步骤
+3. **CLI**: 增强 `provider inspect --routing-hints` 输出更实用的配置片段
+
+### P1 (短期)
+
+1. **CLI**: 新增 `provider add` 命令
+2. **文档**: 新增 `docs/ROUTING_POLICY_GUIDE.md`
+3. **验证**: 实现 Provider 配置 schema 验证
+
+### P2 (中期)
+
+1. **扩展**: 支持自定义 Provider catalog
+2. **工具**: Provider 配置导入导出
+3. **调试**: 配置 dry-run 和预览
+
+## 六、总结
+
+### 当前状态
+
+- ✅ CLI 初始化流程完善
+- ✅ Provider 模板 catalog 丰富
+- ✅ 基本文档覆盖
+- ⚠️ 手动配置指引不足
+- ⚠️ 高级功能文档缺失
+
+### 核心问题
+
+1. **新用户上手难**: 缺少完整的手动添加 Provider 指南
+2. **配置不透明**: 缺少完整的配置 schema 文档
+3. **工具链不完整**: 缺少 `provider add` 等便捷命令
+
+### 优化重点
+
+1. **文档优先**: 先完善文档，降低使用门槛
+2. **工具增强**: 补充便捷 CLI 命令
+3. **扩展性**: 支持自定义 Provider 类型和 catalog

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsonstudio/rcc",
-  "version": "0.90.141",
+  "version": "0.90.181",
   "description": "Multi-provider OpenAI proxy server with anthropic/responses/chat support (release)",
   "type": "module",
   "main": "dist/index.js",
@@ -156,11 +156,14 @@
     "fix:cli-permission": "node scripts/ensure-cli-executable.mjs"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.58",
+    "@ai-sdk/openai": "^3.0.41",
     "@anthropic-ai/sdk": "^0.65.0",
-    "@jsonstudio/llms": "0.6.3214",
+    "@jsonstudio/llms": "0.6.3539",
     "@lmstudio/sdk": "^1.5.0",
     "@radix-ui/react-switch": "^1.2.6",
     "@types/socket.io": "^3.0.1",
+    "ai": "^6.0.116",
     "ajv": "^8.17.1",
     "axios": "^1.12.2",
     "chalk": "^5.6.2",