chaimi-keep-mcp 3.1.29 → 3.1.30

package/SKILL.md

@@ -125,28 +125,56 @@ Agent 通过 MCP 协议自动获取工具列表，无需手动查询。
 
 ---
 
+### 📝 简单记账字段核对清单（save_expense）
+
+**调用 `save_expense` 前必须检查：**
+
+| 字段 | 是否必须 | 说明 |
+|------|----------|------|
+| `name` | ✅ | 商品/服务名称 |
+| `amount` | ✅ | 金额（正数）|
+| `category` | ✅ **新增** | 分类（如：餐饮、交通）|
+| `date` | ✅ | 日期（ISO 8601 格式）|
+| `store` | 可选 | 商家名称 |
+| `note` | 可选 | 备注 |
+
+**⚠️ 注意**：category 是记账的基本信息，必须提供！
+
+---
+
 ### 🚨 小票字段核对清单（调用前必须检查）
 
 **从 prompt 解析结果中提取的所有字段，必须全部传递给 `save_receipt`**：
 
-| 字段 | 是否必须 | 常见遗漏 | 检查方式 |
-|------|----------|----------|----------|
+| 字段 | 是否必须 | 常见遗漏 | 说明 |
+|------|----------|----------|------|
 | `store` | ✅ | 否 | 商家名称 |
 | `date` | ✅ **高频遗漏** | **是** | ISO 8601 格式，如：2026-01-08T11:42:27 |
 | `totalAmount` | ✅ | 否 | 商品原价总和 |
 | `actualAmount` | ✅ **高频遗漏** | **是** | 实付金额（优惠后）|
 | `originalAmount` | ✅ **高频遗漏** | **是** | 原价（优惠前）|
 | `discountAmount` | ✅ **高频遗漏** | **是** | 优惠金额 |
-| `paymentMethod` | ✅ **高频遗漏** | **是** | 如：支付宝支付、微信支付 |
-| `items` | ✅ | 否 | 商品数组，每个必须有 name/amount/price/quantity |
+| `paymentMethod` | 可选 | 是 | 如：支付宝支付、微信支付 |
+| `items` | ✅ | 否 | 商品数组，每个必须有完整字段 |
+
+**items 数组中每个商品必须包含：**
+
+| 字段 | 是否必须 | 说明 |
+|------|----------|------|
+| `name` | ✅ | 商品名称 |
+| `amount` | ✅ | 金额（= price × quantity）|
+| `price` | ✅ | 单价 |
+| `quantity` | ✅ | 数量 |
+| `category` | ✅ **新增** | 分类（如：食品、日用品）|
 
 **核对步骤**：
 1. 提取完小票信息后，对照上表检查每个字段
-2. **重点检查标记"高频遗漏"的字段**：date、actualAmount、originalAmount、discountAmount、paymentMethod
-3. 确认所有字段都在 args 中后再调用 `save_receipt`
-4. 如果某个字段小票上确实没有，可以传空字符串或 0，但不能省略
+2. **重点检查标记"高频遗漏"的字段**：date、actualAmount、originalAmount、discountAmount
+3. **确保每个商品都有 category**，这是记账的基本信息
+4. 确认所有字段都在 args 中后再调用 `save_receipt`
+5. 如果某个字段小票上确实没有，可以传空字符串或 0，但不能省略
 
-**注意**：MCP 工具会不断迭代更新，请以实际通过 MCP 协议获取的工具定义为准。
+**⚠️ 重要**：缺少必填字段会导致保存失败，请严格按照清单核对！
 
 ---
 
@@ -160,6 +188,49 @@ Agent 通过 MCP 协议自动获取工具列表，无需手动查询。
 
 ---
 
+## 防重复录入（Agent 本地实现）
+
+**目标**：提醒用户可能的重复录入，但不阻止保存
+
+### 实现方式
+
+Agent 维护本地记账记录日志（内存或本地文件）：
+
+```javascript
+// 记录格式
+{
+  store: "商家名称",
+  date: "2026-01-08",  // 只记录到日期
+  actualAmount: 25.88,
+  timestamp: 1704694947000  // 记账时间戳
+}
+```
+
+### 重复检测规则
+
+- **时间窗口**：24 小时内
+- **匹配条件**：`store` + `date(到天)` + `actualAmount` 相同
+- **处理方式**：
+  1. 发现重复时，提醒用户："⚠️ 24 小时内已有相似记录（华润万家春风店 25.88元），确认要重复录入吗？"
+  2. 用户确认后，继续调用 `save_receipt`
+  3. 用户取消，停止操作
+
+### 代码示例
+
+```javascript
+// 检查是否重复
+function isDuplicate(store, date, actualAmount) {
+  const fingerprint = `${store}_${date.substring(0,10)}_${actualAmount}`;
+  const recentRecord = recentLogs.find(log => {
+    const timeDiff = Date.now() - log.timestamp;
+    return log.fingerprint === fingerprint && timeDiff < 24 * 60 * 60 * 1000;
+  });
+  return recentRecord;
+}
+```
+
+---
+
 ## 回复规范（必须严格遵守）
 
 记账成功后，回复内容必须包含以下格式：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chaimi-keep-mcp",
-  "version": "3.1.29",
+  "version": "3.1.30",
   "description": "柴米记账 MCP Server - 支持 Claude、Cursor、OpenClaw、WorkBuddy 等 AI 工具直接记账",
   "main": "server.js",
   "bin": {

package/server.js

@@ -441,6 +441,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     switch (name) {
       case 'save_expense': {
+        // P0: 数据完整性检查 - 必填字段验证
+        const requiredFields = ['name', 'amount', 'category', 'date'];
+        const missingFields = [];
+        
+        for (const field of requiredFields) {
+          if (processedArgs[field] === undefined || processedArgs[field] === null || processedArgs[field] === '') {
+            missingFields.push(field);
+          }
+        }
+        
+        if (missingFields.length > 0) {
+          result = {
+            success: false,
+            error: `必填字段缺失：${missingFields.join(', ')}。请从解析结果中提取并传递所有字段。`,
+            code: 400
+          };
+          userMessage = `❌ 记账失败\n\n错误：缺少必填字段：${missingFields.join(', ')}\n\n💡 解决方案：\n1. 请检查是否从用户输入中提取了所有信息\n2. 确保传递以下字段：name（商品名）、amount（金额）、category（分类）、date（日期）\n3. 参考 SKILL.md 中的"调用前检查清单"`;
+          break;
+        }
+        
+        // 数值校验
+        if (typeof processedArgs.amount !== 'number' || processedArgs.amount <= 0) {
+          result = {
+            success: false,
+            error: '金额必须是正数',
+            code: 400
+          };
+          userMessage = '❌ 记账失败：金额必须是正数';
+          break;
+        }
+        
         const mcpParams = convertParams('save_expense', processedArgs);
         result = await callMcpHub('addExpense', mcpParams, token);
         
@@ -459,45 +490,86 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'save_receipt': {
-        // 0. 参数完整性检查 - 提醒 Agent 哪些字段缺失
-        const requiredFields = ['store', 'date', 'totalAmount', 'actualAmount', 'originalAmount', 'discountAmount', 'paymentMethod'];
+        // P0: 数据完整性检查 - 必填字段验证
+        const requiredFields = ['store', 'date', 'totalAmount', 'actualAmount', 'originalAmount', 'discountAmount'];
         const missingFields = [];
-        requiredFields.forEach(field => {
+        
+        for (const field of requiredFields) {
           if (processedArgs[field] === undefined || processedArgs[field] === null || processedArgs[field] === '') {
             missingFields.push(field);
           }
-        });
+        }
         
         if (missingFields.length > 0) {
-          console.error(`⚠️ 警告：save_receipt 缺少以下字段：${missingFields.join(', ')}`);
-          console.error(`   请从 get_parse_prompt 的解析结果中提取并传递所有字段`);
+          result = {
+            success: false,
+            error: `必填字段缺失：${missingFields.join(', ')}。请从 get_parse_prompt 的解析结果中提取并传递所有字段。`,
+            code: 400
+          };
+          userMessage = `❌ 保存失败\n\n错误：缺少必填字段：${missingFields.join(', ')}\n\n💡 解决方案：\n1. 请检查是否从 get_parse_prompt 的解析结果中提取了所有信息\n2. 确保传递以下字段：store、date、totalAmount、actualAmount、originalAmount、discountAmount\n3. 参考 SKILL.md 中的"小票字段核对清单"`;
+          break;
         }
         
-        // 1. 参数格式强制检查 - 确保 items 中每个商品都有完整的字段
-        if (processedArgs.items && Array.isArray(processedArgs.items)) {
-          const invalidItems = [];
-          processedArgs.items.forEach((item, index) => {
-            const itemMissingFields = [];
-            if (!item.hasOwnProperty('name')) itemMissingFields.push('name');
-            if (!item.hasOwnProperty('amount')) itemMissingFields.push('amount');
-            if (!item.hasOwnProperty('price')) itemMissingFields.push('price');
-            if (!item.hasOwnProperty('quantity')) itemMissingFields.push('quantity');
-            
-            if (itemMissingFields.length > 0) {
-              invalidItems.push(`商品${index + 1}(${item.name || '未命名'})缺少字段: ${itemMissingFields.join(', ')}`);
-            }
-          });
-          
-          if (invalidItems.length > 0) {
+        // 数值校验
+        const amountFields = ['totalAmount', 'actualAmount', 'originalAmount'];
+        for (const field of amountFields) {
+          if (typeof processedArgs[field] !== 'number' || processedArgs[field] <= 0) {
             result = {
               success: false,
-              error: `参数格式错误：${invalidItems.join('; ')}。请更新您的 MCP Skill 或检查 items 数组格式。每个商品必须包含：name, amount, price, quantity`,
+              error: `${field} 必须是正数`,
               code: 400
             };
-            userMessage = `❌ 保存失败\n\n错误：商品数据格式不完整\n\n${invalidItems.join('\n')}\n\n💡 解决方案：\n1. 请更新您的柴米记账 MCP Skill\n2. 确保每个商品包含完整的4个字段：name, amount, price, quantity\n3. amount 必须等于 price × quantity`;
+            userMessage = `❌ 保存失败：${field} 必须是正数`;
             break;
           }
         }
+        if (result && !result.success) break;
+        
+        if (typeof processedArgs.discountAmount !== 'number' || processedArgs.discountAmount < 0) {
+          result = {
+            success: false,
+            error: 'discountAmount 必须是非负数',
+            code: 400
+          };
+          userMessage = '❌ 保存失败：优惠金额必须是非负数';
+          break;
+        }
+        
+        // 检查 items 是否存在且非空
+        if (!processedArgs.items || !Array.isArray(processedArgs.items) || processedArgs.items.length === 0) {
+          result = {
+            success: false,
+            error: 'items 不能为空，必须包含至少一个商品',
+            code: 400
+          };
+          userMessage = '❌ 保存失败：商品列表不能为空\n\n💡 请确保从 get_parse_prompt 的解析结果中正确提取了 items 数组';
+          break;
+        }
+        
+        // 检查 items 中每个商品的必填字段（包括 category）
+        const invalidItems = [];
+        processedArgs.items.forEach((item, index) => {
+          const itemMissingFields = [];
+          if (!item.hasOwnProperty('name') || item.name === '') itemMissingFields.push('name');
+          if (!item.hasOwnProperty('amount') || item.amount === undefined) itemMissingFields.push('amount');
+          if (!item.hasOwnProperty('price') || item.price === undefined) itemMissingFields.push('price');
+          if (!item.hasOwnProperty('quantity') || item.quantity === undefined) itemMissingFields.push('quantity');
+          if (!item.hasOwnProperty('category') || item.category === '') itemMissingFields.push('category');
+          
+          if (itemMissingFields.length > 0) {
+            invalidItems.push(`商品${index + 1}(${item.name || '未命名'})缺少字段: ${itemMissingFields.join(', ')}`);
+          }
+        });
+        
+        if (invalidItems.length > 0) {
+          result = {
+            success: false,
+            error: `商品数据不完整：${invalidItems.join('; ')}。每个商品必须包含：name, amount, price, quantity, category`,
+            code: 400
+          };
+          userMessage = `❌ 保存失败\n\n错误：商品数据格式不完整\n\n${invalidItems.join('\n')}\n\n💡 解决方案：\n1. 请更新您的柴米记账 MCP Skill\n2. 确保每个商品包含完整的5个字段：name, amount, price, quantity, category\n3. category 是记账的基本信息，不能为空`;
+          break;
+        }
         
         // 1. 调用 parseReceipt 重新提取小票信息（覆盖 Agent 传的数据）
         if (processedArgs.rawInput) {