@jsonstudio/rcc 0.89.1205 → 0.89.1348

package/docs/glm-history-inline-images.md

@@ -0,0 +1,44 @@
+# GLM 4.7 历史消息中的 inline 图片兼容说明
+
+## 背景
+
+在 `glm-4.7` 上游接口下，历史消息（history）中携带 `data:image/...` 形式的 inline base64 图片内容，在上下文较长时会触发 HTTP 400 / 错误码 `1210`（“API 调用参数有误，请检查文档。”），即使当前轮请求本身是合法的。
+
+本地调试（基于 snapshot 回放和 payload 二分）确认：
+
+- 只保留首条 `system` + 当前轮最后一条 `user` 时可以正常返回 200；
+- 从最早历史开始累积，当累积到某条 **带有 `type=image|image_url|input_image` 且 URL 以 `data:image` 开头** 的 `user` 历史消息时，首次出现 400 / `1210`。
+
+## RouteCodex 侧兼容策略
+
+为避免这类错误，RouteCodex 在 `chat:glm` 兼容配置中增加了专门的裁剪动作：
+
+- Action：`glm_history_image_trim`
+- 实现位置：`sharedmodule/llmswitch-core/src/conversion/compat/actions/glm-history-image-trim.ts`
+
+兼容策略规则：
+
+- 仅在以下条件同时满足时生效：
+  - 请求 `protocol` 为 `openai-chat`；
+  - `compatibilityProfile` 为 `chat:glm`；
+  - `model` 以 `glm-4.7` 开头。
+- 遍历 `messages`：
+  - 找到最后一条 `role: "user"` 的消息，视为当前轮请求；
+  - 对这条之前的所有 `user` 历史消息：
+    - 如果 `content` 中存在 `type ∈ { "image", "image_url", "input_image" }` 且 URL/数据以 `data:image` 开头的片段：
+      - 从该条 `content` 中丢弃这些 inline image 片段；
+    - 如果丢弃后该条消息不再包含任何内容（即之前是“纯图片历史”）：
+      - 直接移除整条历史消息。
+- 当前轮最后一条 `user` 消息（通常是用户最新问题）不会被该规则修改。
+
+## 对调用方的影响
+
+- 对于通过 RouteCodex 调用 `glm-4.7` 的业务方：
+  - 历史对话中包含 inline base64 图片时，RouteCodex 会在发送到上游之前自动裁剪掉这些历史图片内容；
+  - 当前轮用户输入中携带的图片内容不会被该规则移除。
+- 这样可以：
+  - 避免由于历史中的 `data:image/...` 导致的 400 / `1210` 错误；
+  - 保持当前轮请求的图片能力正常可用。
+
+如果需要完整重现原始 payload（包括被裁剪掉的 inline 图片），可以使用 snapshot 调试工具直接回放 provider 前的快照，而不是依赖线上请求路径。
+

package/docs/golden-ci-library.md

@@ -0,0 +1,66 @@
+## CI Golden 样本库
+
+`samples/ci-goldens/` 内置了一套最小化的请求样本，覆盖目前已经打通的三条聊天入口：
+
+```
+samples/ci-goldens/
+  openai-chat/
+    glm/
+      meta.json
+      request.sample.json
+  openai-responses/
+    fai/
+      meta.json
+      request.sample.json
+  anthropic-messages/
+    glm-anthropic/
+      meta.json
+      request.sample.json
+```
+
+每个目录直接包含阶段快照里抽取的 `request.sample.json`（等价于
+`*_req_outbound_stage2_format_build.json.body`），以及 `meta.json`，注明来源
+stage、providerId 与捕获时间。CI 或本地始终可以依赖这些样本来跑最基本的
+roundtrip/工具校验，而不需要访问真实 provider。
+
+### `npm run test:golden`
+
+命令会按照下面的顺序执行：
+
+1. `node scripts/tools/capture-provider-goldens.mjs --custom-only --update-golden`
+   - 优先读取 `~/.routecodex/golden_samples/new/<entry>/<provider>/`；
+   - 若用户目录缺失，则自动回退到 `samples/ci-goldens/...`；
+   - 最后才会使用 `samples/chat-blackbox/**/request-basic.json` 做最小回放。
+   - 结果写入 `~/.routecodex/golden_samples/provider_golden_samples/**`，供 Provider
+     单测与 mock 回放使用。
+2. `node scripts/mock-provider/run-regressions.mjs`
+   - 使用仓库内 `samples/mock-provider/_registry` 的样本，通过 mock provider
+     执行一轮端到端回放；
+   - 默认启用 `ROUTECODEX_MOCK_ENTRY_FILTER=all`，确保 chat/responses/anthropic
+     都被验证。
+
+如果检测到 `~/.routecodex/codex-samples`，脚本会提示可以运行
+`node scripts/mock-provider/capture-from-configs.mjs` 将真实请求转成 mock 回放样本。
+该命令会根据本地 `~/.routecodex/provider/**/config*.json` 与
+`~/.routecodex/golden_samples/new/**` 生成新的 `samples/mock-provider/...`
+目录，并刷新 `_registry/index.json`。随后再次执行 `npm run test:golden` 即可把
+“真实” provider 行为也纳入回归。
+
+### 如何补充新的 provider 样本
+
+1. 在本地 `routecodex` 服务上真实跑通一次请求，确认
+   `~/.routecodex/golden_samples/new/<entry>/<provider>/request.sample.json` 已生成。
+2. 运行 `npm run sync:ci-goldens`（或直接执行
+   `node scripts/tools/sync-ci-goldens.mjs --entry <entry> --provider <id>`）把刚产生的
+   样本复制到 `samples/ci-goldens/<entry>/<provider>/`，脚本会自动生成/刷新 `meta.json`
+   并用 `source: "ci-goldens"` 标识。
+3. 运行 `npm run test:golden`，确认新的样本能够被
+   `capture-provider-goldens.mjs` 消费并写入
+   `~/.routecodex/golden_samples/provider_golden_samples/<provider>/<entry>/`。
+4. 如需把同一份请求加入 mock provider 回放，可执行
+   `node scripts/mock-provider/capture-from-configs.mjs --filter <providerId>`，
+   该命令会复用刚才的 `request.sample` 生成 `samples/mock-provider/...` 记录。
+
+> 注意：CI goldens 只存储对齐 chat 入口输入字段的最终 JSON，不包含任何密钥或本地路径。
+> 如需测试特定机密字段，请在本地运行 `capture-provider-goldens` 并利用私有
+> `~/.routecodex/golden_samples/new/**`，不要把敏感样本提交到仓库。

package/docs/lmstudio-dry-run-summary.md

@@ -0,0 +1,203 @@
+# LM Studio Dry-Run Implementation Summary
+
+## Overview
+
+This document summarizes the comprehensive LM Studio dry-run implementation that focuses on capturing and analyzing response transformations in the RouteCodex pipeline system.
+
+## 🚀 Key Features Implemented
+
+### 1. Response-Focused Dry-Run Analysis
+- **Response Transformation Tracking**: Detailed analysis of how responses are transformed through each pipeline stage
+- **Performance Metrics**: Execution time, memory usage, and efficiency calculations
+- **Error Detection**: Comprehensive error tracking and reporting during response processing
+
+### 2. Comprehensive Analysis Scripts
+
+#### `tests/lmstudio-response-analysis-dry-run.mjs`
+- **Purpose**: Focused analysis on response transformations
+- **Features**:
+  - Real response generation and capture
+  - Detailed transformation step analysis
+  - Performance metrics and efficiency calculations
+  - Structure analysis of input/output data
+  - Tool call extraction and analysis
+
+#### `tests/lmstudio-comprehensive-dry-run.mjs`
+- **Purpose**: Complete pipeline dry-run with enhanced response analysis
+- **Features**:
+  - Multi-stage execution (request + response)
+  - Enhanced response wrappers with detailed logging
+  - Comprehensive analysis reports
+  - Performance comparison across stages
+
+### 3. Configuration Support
+
+#### `config/lmstudio-dry-run-config.json`
+- **Purpose**: Centralized configuration for LM Studio dry-run operations
+- **Features**:
+  - Request pipeline configuration with detailed node settings
+  - Response pipeline configuration with transformation analysis
+  - Performance thresholds and analysis levels
+  - Driver feedback configuration
+
+## 📊 Analysis Capabilities
+
+### Response Analysis Features
+1. **Structure Analysis**: Automatic analysis of response object structure
+2. **Tool Call Extraction**: Detection and analysis of tool calls in responses
+3. **Size Tracking**: Input/output size changes during transformation
+4. **Performance Metrics**: Execution time, throughput, and efficiency calculations
+5. **Error Tracking**: Comprehensive error detection and reporting
+
+### Transformation Chain Analysis
+1. **Step-by-Step Tracking**: Each transformation step is logged and analyzed
+2. **Data Flow Visualization**: Clear visualization of how data moves through the pipeline
+3. **Efficiency Metrics**: Transformation efficiency calculations at each stage
+4. **Comparative Analysis**: Before/after comparison of response data
+
+## 🛠️ Usage Examples
+
+### Basic Response Analysis
+```bash
+# Run response analysis with existing response file
+node tests/lmstudio-response-analysis-dry-run.mjs
+
+# Output files:
+# - tests/output/lmstudio-response-analysis-result.json
+# - tests/output/lmstudio-response-analysis-report.json
+```
+
+### CLI Tool Usage
+```bash
+# Run response analysis via CLI
+node scripts/dry-run-cli.mjs run-response \
+  --response tests/output/lmstudio-real-response.json \
+  --pipeline-id lmstudio-response-test
+```
+
+### Configuration-Based Analysis
+```bash
+# Use dedicated LM Studio dry-run configuration
+# Configuration: config/lmstudio-dry-run-config.json
+# Features: Request + response pipeline configuration
+```
+
+## 📈 Output Reports
+
+### 1. Response Analysis Report
+- **Location**: `tests/output/lmstudio-response-analysis-report.json`
+- **Contents**:
+  - Execution summary with timestamps
+  - Original response analysis
+  - Compatibility transformation analysis
+  - LLM Switch transformation analysis
+  - Performance insights and metrics
+
+### 2. Detailed Result Report
+- **Location**: `tests/output/lmstudio-response-analysis-result.json`
+- **Contents**:
+  - Complete execution pipeline details
+  - Node-by-node analysis results
+  - Performance metrics and timing
+  - Breakpoint status and recommendations
+
+## 🔧 Technical Implementation
+
+### Response Wrapper System
+```javascript
+// Enhanced response wrapper with analysis capabilities
+function createResponseWrapper(id, type, underlyingModule) {
+  return {
+    // Detailed analysis tracking
+    executionStats: { startTime: 0, endTime: 0, steps: [] },
+
+    // Structure analysis
+    analyzeStructure(obj) {
+      // Automatic structure detection and analysis
+    },
+
+    // Performance calculation
+    calculateEfficiency(input, output) {
+      // Transformation efficiency metrics
+    }
+  };
+}
+```
+
+### Analysis Data Structure
+```javascript
+const analysisData = {
+  transformationSteps: [],
+  inputAnalysis: { size, structure, toolCalls, choices },
+  outputAnalysis: { size, structure, toolCalls, choices },
+  performanceMetrics: { totalExecutionTime, throughput, transformationEfficiency },
+  errors: []
+};
+```
+
+## 🎯 Key Insights Generated
+
+### Performance Metrics
+- **Total Transformation Time**: Combined execution time across all stages
+- **Efficiency Ratios**: Input/output size efficiency calculations
+- **Throughput**: Data processing speed metrics
+- **Error Count**: Transformation and processing errors
+
+### Data Flow Analysis
+- **Size Changes**: Byte-level changes between input/output
+- **Structure Transformations**: Object structure changes during processing
+- **Tool Call Preservation**: How tool calls are handled through transformations
+- **Content Integrity**: Data consistency analysis
+
+## 📋 Test Results
+
+### Successful Execution
+- ✅ Response analysis dry-run completed successfully
+- ✅ Sample response data processed and analyzed
+- ✅ Comprehensive reports generated
+- ✅ CLI tool functionality verified
+- ✅ Configuration system integration tested
+
+### Generated Artifacts
+1. **Real Response Sample**: `tests/output/lmstudio-real-response.json`
+2. **Analysis Result**: `tests/output/lmstudio-response-analysis-result.json`
+3. **Analysis Report**: `tests/output/lmstudio-response-analysis-report.json`
+4. **Configuration**: `config/lmstudio-dry-run-config.json`
+
+## 🔮 Future Enhancements
+
+### Planned Features
+1. **HTML Report Generation**: Visual timeline and node tree visualization
+2. **Real-time Analysis**: Live monitoring of response transformations
+3. **Historical Comparison**: Compare transformation performance over time
+4. **Advanced Metrics**: Memory usage, CPU utilization, and network impact
+
+### Integration Opportunities
+1. **Web Interface**: Web-based dry-run analysis dashboard
+2. **API Endpoints**: RESTful API for programmatic analysis
+3. **Plugin System**: Custom analysis modules and extensions
+4. **Export Formats**: Multiple export formats (CSV, XML, HTML)
+
+## 🏆 Conclusion
+
+The LM Studio dry-run implementation provides a comprehensive solution for analyzing response transformations in the RouteCodex pipeline system. Key achievements:
+
+1. **Complete Response Analysis**: End-to-end analysis of response processing
+2. **Performance Insights**: Detailed performance metrics and efficiency calculations
+3. **Error Detection**: Comprehensive error tracking and reporting
+4. **Extensible Architecture**: Modular design for future enhancements
+5. **User-Friendly Tools**: CLI and script-based interfaces for easy usage
+
+This implementation demonstrates the power and flexibility of the RouteCodex dry-run system, providing deep insights into how AI model responses are processed and transformed through the pipeline architecture.
+
+---
+
+**Files Created/Modified:**
+- `tests/lmstudio-response-analysis-dry-run.mjs` - Response-focused analysis script
+- `tests/lmstudio-comprehensive-dry-run.mjs` - Complete pipeline analysis script
+- `config/lmstudio-dry-run-config.json` - Centralized configuration
+- `tests/output/sample-real-response.json` - Sample response data
+- `docs/lmstudio-dry-run-summary.md` - This documentation
+
+**Status**: ✅ Complete and tested
+**Version**: v2.1 - Response Analysis Enhancement

package/docs/lmstudio-tool-calling.md

@@ -0,0 +1,214 @@
+# LM Studio Tool Calling API Documentation
+
+## Overview
+
+LM Studio provides comprehensive tool calling functionality that enables Large Language Models (LLMs) to interact with external functions and APIs. All models in LM Studio support at least some degree of tool use, with two levels of support: **Native** and **Default**.
+
+## Tool Support Levels
+
+### Native Tool Use Support
+Models with native tool use support:
+- Have a hammer badge in the LM Studio app
+- Generally perform better in tool use scenarios
+- Include chat templates that specifically support tool use
+- Are trained for tool use functionality
+
+**Currently supported models with native tool use:**
+- **Qwen series**
+  - `lmstudio-community/Qwen2.5-7B-Instruct-GGUF` (4.68 GB)
+  - `mlx-community/Qwen2.5-7B-Instruct-4bit` (4.30 GB)
+- **Llama series**
+  - Llama-3.1, Llama-3.2 models
+
+### Default Tool Use Support
+**All models that don't have native tool use support will have default tool use support.**
+
+LM Studio uses a standardized tool calling format that works with any model. The system provides a consistent interface regardless of the underlying model's capabilities.
+
+## Tool Calling Format
+
+### System Prompt Template
+
+When tools are provided, LM Studio automatically formats the system prompt using this template:
+
+```
+# Tools
+
+You may call one or more functions to assist with the user query.
+
+You are provided with function signatures within <tools></tools> XML tags:
+<tools>
+{
+  "type": "function",
+  "function": {
+    "name": "get_delivery_date",
+    "description": "Get the delivery date for a customer's order",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "order_id": {"type": "string"}
+      },
+      "required": ["order_id"]
+    }
+  }
+}
+</tools>
+
+For each function call, return a json object with function name and arguments within
+
+{"name": "<function-name>", "arguments": <args-json-object>}```
+
+**Important:** The model can only *request* calls to these tools because LLMs *cannot* directly call functions, APIs, or any other tools. They can only output text, which can then be parsed to programmatically call the functions.
+
+### Response Options
+
+When prompted, the LLM can either:
+
+#### (a) Call one or more tools
+```xml
+User: Get me the delivery date for order 123
+Model:```
+
+#### (b) Respond normally
+```xml
+User: Hi
+Model: Hello! How can I assist you today?
+```
+
+## API Usage
+
+### Request Format
+
+```bash
+curl http://localhost:1234/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "lmstudio-community/qwen2.5-7b-instruct",
+    "messages": [{"role": "user", "content": "What dell products do you have under $50 in electronics?"}],
+    "tools": [
+      {
+        "type": "function",
+        "function": {
+          "name": "search_products",
+          "description": "Search the product catalog by various criteria. Use this whenever a customer asks about product availability, pricing, or specifications.",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "query": {
+                "type": "string",
+                "description": "Search terms or product name"
+              },
+              "category": {
+                "type": "string",
+                "description": "Product category to filter by",
+                "enum": ["electronics", "clothing", "home", "outdoor"]
+              },
+              "max_price": {
+                "type": "number",
+                "description": "Maximum price in dollars"
+              }
+            },
+            "required": ["query"],
+            "additionalProperties": false
+          }
+        }
+      }
+    ]
+  }'
+```
+
+### Response Format
+
+When the model decides to use tools, the response will include:
+
+```json
+{
+  "id": "chatcmpl-gb1t1uqzefudice8ntxd9i",
+  "object": "chat.completion",
+  "created": 1730913210,
+  "model": "lmstudio-community/qwen2.5-7b-instruct",
+  "choices": [
+    {
+      "index": 0,
+      "logprobs": null,
+      "finish_reason": "tool_calls",
+      "message": {
+        "role": "assistant",
+        "tool_calls": [
+          {
+            "id": "365174485",
+            "type": "function",
+            "function": {
+              "name": "search_products",
+              "arguments": "{\"query\": \"dell\", \"category\": \"electronics\", \"max_price\": 50}"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## LM Studio Processing
+
+### Parsing Logic
+
+LM Studio parses the text output from the model into an OpenAI-compliant `chat.completion` response object:
+
+1. **With tools array**: LM Studio attempts to parse tool calls into the `response.choices[0].message.tool_calls` field
+2. **No valid tool calls**: Returns response to the standard `response.choices[0].message.content` field
+3. **Invalid format**: Tool calls with incorrect formatting won't be parsed into the `tool_calls` field
+
+### Error Handling
+
+**Note:** Smaller models and models that were not trained for tool use may output improperly formatted tool calls, resulting in LM Studio being unable to parse them into the `tool_calls` field.
+
+**Example of improperly formatted tool call:**
+```xml
+```
+
+This fails because:
+- Brackets are incorrect (should be `{}` not `[]`)
+- Does not follow the required `name, arguments` format
+- `function: "date"` is not a valid argument structure
+
+## Alternative Tool Call Format
+
+For models that don't follow the standard XML format, LM Studio also supports an alternative format:
+
+```
+[TOOL_REQUEST]{"name": "get_delivery_date", "arguments": {"order_id": "123"}}[END_TOOL_REQUEST]
+```
+
+If a model follows this format exactly, LM Studio will parse those tool calls into the `chat.completions` object, just like for natively supported models.
+
+## Implementation Notes
+
+### Key Features
+
+1. **Universal Support**: All models have at least default tool use support
+2. **OpenAI Compatibility**: Responses follow OpenAI's chat.completion format
+3. **Flexible Parsing**: Supports multiple tool call formats
+4. **Error Resilience**: Gracefully handles malformed tool calls
+
+### Best Practices
+
+1. **Model Selection**: Use models with native tool support for better results
+2. **Parameter Validation**: Ensure all required parameters are included in function definitions
+3. **Error Handling**: Always check if `tool_calls` array is populated in responses
+4. **Testing**: Test tool calling with your specific model as capabilities vary
+
+### Troubleshooting
+
+If you're not receiving `tool_calls` as expected:
+1. Verify the model supports tool calling (native or default)
+2. Check the tool call format in the model's response
+3. Ensure all required parameters are properly defined
+4. Test with a model that has native tool support for comparison
+
+## File Information
+
+- **Source**: LM Studio Tool Use Documentation
+- **URL**: https://lmstudio.ai/docs/app/api/tools
+- **Extracted**: September 22, 2025