luma-mcp 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.1] - 2025-11-18
+
+### Changed
+- 📝 **文档优化**: 精简 README，移除冲余配置文件路径说明
+- 📝 **更新日志简化**: 将 README 中的详细更新日志替换为 CHANGELOG.md 链接
+- ✨ **Qwen 测试示例**: 添加 Qwen3-VL-Flash 本地测试命令
+- 💰 **定价信息**: 添加阿里云通义千问定价参考链接
+- 📋 **模型对比**: 更新模型选择表，完善 Qwen3-VL-Flash 信息
+- 🔗 **API Key 获取**: 添加阿里云百炼 API Key 获取指南
+- 📚 **相关链接**: 新增阿里云百炼平台和 Qwen3-VL 文档链接
+- 🐛 **错误信息**: 优化 API 调用失败排查提示，包含阿里云账户
+
+### Fixed
+- 🐛 **描述修正**: 修正 package.json 中模型名称为 qwen3-vl-flash
+- 📝 **注释精简**: 简化 prompts.ts 注释头
+
 ## [1.2.0] - 2025-11-17
 
 ### Added

package/README.md

@@ -48,10 +48,6 @@ npx luma-mcp
 
 #### Claude Desktop
 
-**Windows 配置文件位置**: `%APPDATA%\Claude\claude_desktop_config.json`
-
-**macOS 配置文件位置**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-
 **方案 A: 使用智谱 GLM-4.5V**:
 
 ```json
@@ -229,7 +225,7 @@ claude mcp add -s user luma-mcp --env MODEL_PROVIDER=qwen --env DASHSCOPE_API_KE
 
 **注意**: 直接在聊天框粘贴图片，非视觉模型不会自动调用 Luma，需要明确指示。
 
-### 在 Claude Desktop 中使用
+### 在 Claude code 中使用
 
 配置完成后，在 Claude 对话中可以这样使用：
 
@@ -272,6 +268,19 @@ $env:SILICONFLOW_API_KEY="your-api-key"    # Windows PowerShell
 npm run test:local ./test.png
 ```
 
+**测试阿里云通义千问 Qwen3-VL-Flash**:
+```bash
+# 设置 API Key 和提供商
+export MODEL_PROVIDER=qwen
+export DASHSCOPE_API_KEY="your-api-key"  # macOS/Linux
+
+$env:MODEL_PROVIDER="qwen"
+$env:DASHSCOPE_API_KEY="your-api-key"    # Windows PowerShell
+
+# 测试本地图片
+npm run test:local ./test.png
+```
+
 **其他测试命令**:
 ```bash
 # 测试并提问
@@ -328,31 +337,39 @@ analyze_image({
 
 ### 通用配置
 
-| 变量名          | 必需 | 默认值      | 说明                                    |
-|------------------|------|-------------|---------------------------------------|
-| `MODEL_PROVIDER` | 否   | `zhipu`     | 模型提供商：`zhipu` 或 `siliconflow` |
-| `MODEL_NAME`     | 否   | 见下文     | 模型名称（自动根据提供商选择）       |
-| `MAX_TOKENS`     | 否   | `4096`      | 最大生成 tokens                        |
-| `TEMPERATURE`    | 否   | `0.7`       | 温度参数 (0-1)                          |
-| `TOP_P`          | 否   | `0.7`       | Top-p 参数 (0-1)                        |
-| `ENABLE_THINKING`| 否   | `false`     | 是否启用思考模式（仅 GLM-4.5V）      |
+| 变量名            | 必需 | 默认值  | 说明                                          |
+|-------------------|------|---------|----------------------------------------------|
+| `MODEL_PROVIDER`  | 否   | `zhipu` | 模型提供商：`zhipu`、`siliconflow` 或 `qwen` |
+| `MODEL_NAME`      | 否   | 见下文  | 模型名称（自动根据提供商选择）                  |
+| `MAX_TOKENS`      | 否   | `4096`  | 最大生成 tokens                               |
+| `TEMPERATURE`     | 否   | `0.7`   | 温度参数 (0-1)                                |
+| `TOP_P`           | 否   | `0.7`   | Top-p 参数 (0-1)                              |
+| `ENABLE_THINKING` | 否   | `false` | 是否启用思考模式（GLM-4.5V 和 Qwen3-VL-Flash）  |
 
 ### 智谱 GLM-4.5V 专用
 
-| 变量名          | 必需               | 默认值      | 说明                 |
-|------------------|---------------------|-------------|----------------------|
-| `ZHIPU_API_KEY`  | 是（使用智谱时） | -           | 智谱 AI 的 API 密钥  |
+| 变量名          | 必需           | 默认值 | 说明                |
+|-----------------|----------------|--------|---------------------|
+| `ZHIPU_API_KEY` | 是（使用智谱时） | -      | 智谱 AI 的 API 密钥 |
 
 默认模型：`glm-4.5v`
 
 ### 硅基流动 DeepSeek-OCR 专用
 
-| 变量名                | 必需                     | 默认值                       | 说明                     |
-|------------------------|-------------------------|---------------------------------|----------------------------|
-| `SILICONFLOW_API_KEY`  | 是（使用硅基流动时） | -                               | 硅基流动的 API 密钥      |
+| 变量名                | 必需               | 默认值 | 说明                |
+|-----------------------|--------------------|--------|---------------------|
+| `SILICONFLOW_API_KEY` | 是（使用硅基流动时） | -      | 硅基流动的 API 密钥 |
 
 默认模型：`deepseek-ai/DeepSeek-OCR`
 
+### 阿里云通义千问 Qwen3-VL-Flash 专用
+
+| 变量名            | 必需             | 默认值 | 说明                    |
+|-------------------|------------------|--------|------------------------|
+| `DASHSCOPE_API_KEY` | 是（使用千问时） | -      | 阿里云百炼的 API 密钥   |
+
+默认模型：`qwen3-vl-flash`
+
 **思考模式说明**:
 - 默认开启，提高图片分析的准确性和详细程度
 - 如需关闭（提高速度、降低成本），请在配置文件中设置：
@@ -426,6 +443,12 @@ luma-mcp/
 3. 进入 API 管理创建 API Key
 4. 复制 API Key 到配置文件
 
+**阿里云通义千问 Qwen3-VL-Flash**:
+1. 访问 [阿里云百炼平台](https://bailian.console.aliyun.com/)
+2. 注册/登录账号
+3. 进入 API-KEY 管理创建 API Key
+4. 复制 API Key 到配置文件
+
 ### 支持哪些图片格式？
 
 支持 JPG、PNG、WebP、GIF 格式。建议使用 JPG 格式以获得更好的压缩率。
@@ -455,7 +478,7 @@ data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
 ### API 调用失败怎么办？
 
 1. 检查 API Key 是否正确
-2. 确认智谱账户余额充足
+2. 确认账户余额充足（智谱/阿里云）
 3. 检查网络连接
 4. 查看日志文件了解详细错误信息
 
@@ -465,25 +488,29 @@ data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
 
 **智谱 GLM-4.5V**: 定价请参考[智谱官方定价](https://open.bigmodel.cn/pricing)。
 
-典型场景估算（GLM-4.5V）:
+**阿里云通义千问 Qwen3-VL-Flash**: 定价请参考[阿里云百炼定价](https://help.aliyun.com/zh/model-studio/getting-started/models)。
+
+典型场景估算：
 - 简单图片理解: 500-1000 tokens
 - 代码截图分析: 1500-2500 tokens
 - 详细 UI 分析: 2000-3000 tokens
 
-启用思考模式会增加约 20-30% tokens。
+启用思考模式（GLM-4.5V/Qwen3-VL-Flash）会增加约 20-30% tokens。
 
 ### 如何选择模型？
 
-| 特性       | GLM-4.5V（智谱） | DeepSeek-OCR（硅基流动） |
-|------------|----------------|------------------------|
-| **费用**   | 收费           | **完全免费**           |
-| **中文理解** | 优秀           | 良好                   |
-| **OCR 能力** | 良好           | **优秀**               |
-| **思考模式** | 支持           | 不支持                 |
-| **适用场景** | 通用图片分析 | OCR、文字识别          |
+| 特性         | GLM-4.5V（智谱） | DeepSeek-OCR（硅基流动） | Qwen3-VL-Flash（阿里云） |
+|--------------|----------------|------------------------|------------------------|
+| **费用**     | 收费           | **完全免费**           | 收费                   |
+| **中文理解** | 优秀           | 良好                   | **优秀**               |
+| **OCR 能力** | 良好           | **优秀**               | 优秀                   |
+| **思考模式** | 支持           | 不支持                 | 支持                   |
+| **速度/成本** | 中等           | 免费                   | **快速/低成本**         |
+| **适用场景** | 通用图片分析   | OCR、文字识别           | 快速分析、3D定位        |
 
 **推荐**:
 - 需要 OCR 或文字识别：选择 **DeepSeek-OCR**（免费）
+- 需要快速低成本分析：选择 **Qwen3-VL-Flash**
 - 需要深度图片理解：选择 **GLM-4.5V**
 
 ## 贡献
@@ -500,50 +527,12 @@ MIT License
 - [GLM-4.5V 文档](https://docs.bigmodel.cn/cn/guide/models/vlm/glm-4.5v)
 - [硅基流动平台](https://cloud.siliconflow.cn/)
 - [DeepSeek-OCR 文档](https://docs.siliconflow.cn/cn/api-reference/chat-completions/chat-completions)
+- [阿里云百炼平台](https://bailian.console.aliyun.com/)
+- [Qwen3-VL 文档](https://help.aliyun.com/zh/model-studio/getting-started/models)
 - [MCP 协议文档](https://modelcontextprotocol.io/)
 
 ## 更新日志
 
-### [1.1.1] - 2025-11-13
-
-#### 新增
-- 🖼️ **Data URI 支持**: 支持接收 base64 编码的图片数据（`data:image/png;base64,...`）
-- 🚀 **为未来做准备**: 当 MCP 客户端支持时，可直接传递用户粘贴的图片
-
-#### 修改
-- 更新工具描述，说明支持三种输入格式：本地路径、URL、Data URI
-- 新增 Data URI 格式验证（MIME 类型、大小限制）
-
-### [1.1.0] - 2025-11-13
-
-#### 新增
-- 🎉 **多模型支持**: 新增硅基流动 DeepSeek-OCR 支持
-- 🆓 **免费选项**: DeepSeek-OCR 通过硅基流动提供完全免费的 OCR 服务
-- 📐 **统一接口**: 创建 VisionClient 接口，支持灵活扩展更多视觉模型
-- ⚙️ **灵活配置**: 通过 `MODEL_PROVIDER` 环境变量轻松切换模型
-
-#### 修改
-- 🔧 环境变量命名优化，支持通用配置（`MODEL_NAME`、`MAX_TOKENS` 等）
-- 📝 更新文档，提供双模型配置说明和选择建议
-- 🏭️ 重构代码结构，提升可维护性
-
-#### 技术细节
-- 新增文件:
-  - `src/vision-client.ts` - 视觉模型客户端统一接口
-  - `src/siliconflow-client.ts` - 硅基流动 API 客户端实现
-  - `.env.example` - 配置示例文件
-- 修改文件:
-  - `src/config.ts` - 支持多提供商配置
-  - `src/zhipu-client.ts` - 实现 VisionClient 接口
-  - `src/index.ts` - 根据配置动态选择客户端
-
-### [1.0.3] - 2025-11-12
-
-- 基于智谱 GLM-4.5V 的视觉理解能力
-- 支持本地文件和远程 URL
-- 内置重试机制
-- 思考模式支持
-
 更多更新历史请查看 [CHANGELOG.md](./CHANGELOG.md)
 
 ## 作者

package/build/prompts.d.ts

@@ -1,6 +1,5 @@
 /**
- * 提示词模板
- * 参考 Claude Sonnet 4.5 的视觉理解方法
+ * 视觉提示词
  */
 /**
  * 构建图片分析提示词

package/build/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAkC7D"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAkC7D"}

package/build/prompts.js

@@ -1,6 +1,5 @@
 /**
- * 提示词模板
- * 参考 Claude Sonnet 4.5 的视觉理解方法
+ * 视觉提示词
  */
 /**
  * 构建图片分析提示词

package/build/prompts.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,IAAI,QAAQ,EAAE,CAAC;QACb,gBAAgB;QAChB,OAAO;;;;EAIT,QAAQ;;;;;;;;;;;CAWT,CAAC,IAAI,EAAE,CAAC;IACP,CAAC;SAAM,CAAC;QACN,aAAa;QACb,OAAO;;;;;;;;;;;CAWV,CAAC,IAAI,EAAE,CAAC;IACP,CAAC;AACH,CAAC"}
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,IAAI,QAAQ,EAAE,CAAC;QACb,gBAAgB;QAChB,OAAO;;;;EAIT,QAAQ;;;;;;;;;;;CAWT,CAAC,IAAI,EAAE,CAAC;IACP,CAAC;SAAM,CAAC;QACN,aAAa;QACb,OAAO;;;;;;;;;;;CAWV,CAAC,IAAI,EAAE,CAAC;IACP,CAAC;AACH,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "luma-mcp",
-  "version": "1.2.0",
-  "description": "Multi-model vision understanding MCP server. Supports GLM-4.5V (Zhipu), DeepSeek-OCR (SiliconFlow - Free), and Qwen3-VL-Plus (Aliyun)",
+  "version": "1.2.1",
+  "description": "Multi-model vision understanding MCP server. Supports GLM-4.5V (Zhipu), DeepSeek-OCR (SiliconFlow - Free), and Qwen3-VL-Flash (Aliyun)",
   "type": "module",
   "bin": {
     "luma-mcp": "build/index.js"