概述
saveArticle工具是commit-message-generator-mcp项目中的一个重要扩展功能,主要用于将对话内容生成技术类或学习类文档,并保存到远程API。该工具通过DeepSeekClient的扩展实现,提供了完整的文档生成和保存解决方案。
核心功能
1. DeepSeekClient扩展
generateArticle方法
新增的generateArticle方法负责生成结构化的文章内容,包含以下关键特性:
- 结构化输出:生成包含title、description、content三个主要字段的完整文章结构
- 类型支持:支持技术类和学习类两种文档类型
- 标题控制:严格将标题长度限制在32个字符以内,确保符合API要求
代码示例
// 生成文章内容示例
const article = await deepSeekClient.generateArticle({
conversationContent: "技术讨论内容",
articleType: "technical" // 可选:technical | learning
});
2. MCP Tool定义
工具配置
const saveArticleTool: McpTool = {
name: "saveArticle",
description: "将对话内容生成技术文档并保存",
inputSchema: {
type: "object",
properties: {
conversationContent: {
type: "string",
description: "对话内容"
},
articleType: {
type: "string",
enum: ["technical", "learning"],
description: "文章类型"
}
},
required: ["conversationContent"]
}
};
3. 处理逻辑
配置检查
工具执行前会进行必要的配置验证:
- UUID配置检查
- 手机号配置验证
- API Key状态检查
API Key管理
- 自动检查API Key的有效性
- 支持API Key的自动续期
- 提供友好的错误提示
文章生成流程
- 接收对话内容输入
- 根据articleType参数确定文档类型
- 调用generateArticle方法生成结构化内容
- 验证生成内容的完整性
- 调用远程API保存文档
4. API响应处理
响应结构解析
工具正确处理API响应,重点关注:
result.data.auid:文章唯一标识result.code === 200:业务状态码检查
错误处理增强
- 网络异常处理
- API响应错误处理
- 业务逻辑错误处理
- 提供详细的错误信息和解决方案
技术特点
配置驱动
工具采用配置驱动的设计理念,所有关键参数都通过配置文件管理,便于维护和部署。
自动API Key管理
- 自动检测API Key过期
- 无缝续期机制
- 减少手动干预需求
类型安全
使用TypeScript确保类型安全,提供完整的类型定义和接口约束。
错误友好
提供清晰易懂的错误信息,帮助开发者快速定位和解决问题。
API接口规范
请求接口
- 方法: POST
- URL:
https://spacehelper.site/api/third-article/insert - Content-Type: application/json
请求体结构
interface ArticleRequest {
uuid: string; // 用户唯一标识
title: string; // 文章标题(≤32字符)
description: string; // 文章描述
content: string; // 文章内容
}
响应结构
interface ArticleResponse {
code: number; // 状态码(200表示成功)
data: {
auid: string; // 文章唯一标识
};
}
使用指南
安装和配置
环境要求
- Node.js 16+
- TypeScript 4.5+
依赖安装
npm install commit-message-generator-mcp
- 配置设置 在项目配置文件中添加必要的配置项:
// config.ts
export const config = {
uuid: "your-uuid",
phoneNumber: "your-phone",
apiKey: "your-api-key"
};
基本使用
生成技术文档
import { saveArticle } from 'commit-message-generator-mcp';
const result = await saveArticle({
conversationContent: "关于微服务架构的技术讨论...",
articleType: "technical"
});
console.log(`文章保存成功,AUID: ${result.auid}`);
生成学习文档
const result = await saveArticle({
conversationContent: "机器学习基础知识学习笔记...",
articleType: "learning"
});
高级用法
批量处理
支持批量处理多个对话内容,自动生成多篇文档:
const conversations = [
"对话内容1",
"对话内容2",
"对话内容3"
];
for (const content of conversations) {
await saveArticle({ conversationContent: content });
}
自定义标题生成
通过预处理对话内容,实现自定义标题生成逻辑:
function generateCustomTitle(content: string): string {
// 自定义标题生成逻辑
return content.substring(0, 30) + "...";
}
错误处理
常见错误及解决方案
API Key过期
- 症状:返回401状态码
- 解决方案:检查配置并更新API Key
网络连接问题
- 症状:请求超时或连接失败
- 解决方案:检查网络连接,重试机制
参数验证失败
- 症状:返回400状态码
- 解决方案:检查输入参数格式和必填项
错误处理示例
try {
const result = await saveArticle({
conversationContent: "技术内容"
});
} catch (error) {
if (error.code === 401) {
console.error("API Key已过期,请更新配置");
} else if (error.code === 400) {
console.error("参数验证失败:", error.message);
} else {
console.error("未知错误:", error);
}
}
性能优化
缓存策略
- 实现API响应缓存
- 减少重复请求
- 提升响应速度
并发控制
- 支持并发请求处理
- 配置并发数量限制
- 避免API限流
版本信息
- 当前版本: 1.6.1
- 主要文件:
src/deepSeekClient.tssrc/index.ts
- 依赖版本: 查看package.json获取详细信息
总结
saveArticle工具提供了一个完整的技术文档生成和保存解决方案,通过配置驱动、类型安全和错误友好的设计,帮助开发者快速集成和使用。该工具特别适合需要将技术讨论或学习内容转化为结构化文档的场景。
通过本文档,开发者可以全面了解saveArticle工具的功能特性、使用方法和最佳实践,从而更好地在项目中应用该工具。