chaimi-keep-mcp 3.1.39 → 3.1.40-beta.2

package/README.md

@@ -141,6 +141,13 @@ AI 会自动调用 `save_income` 工具记录收入。
 
 ## 更新日志
 
+### v3.1.39 (2026-04-18)
+- **新增** 店铺分类字段支持：`storeCategory`（一级分类）、`storeSubCategory`（二级分类）
+  - 小票记账时自动识别店铺分类（购物/美食/生活服务/其他）
+  - 支持二级细分类目（超市/便利店/中餐厅/药店等）
+  - 数据存储到 receipts 和 receipt_items 表，支持后续查询分析
+- **修复** 日期格式提示：统一改为"毫秒级时间戳（13位数字）"，与实际校验逻辑保持一致
+
 ### v3.1.38 (2026-04-16)
 - **优化** SKILL.md 时间戳说明：使用占位符避免 AI 抄写
   - 将示例时间戳改为占位符格式 `[毫秒时间戳]`

package/SKILL.md

@@ -84,15 +84,9 @@ Agent 必须输出：
 为数据安全起见，我已暂停记账操作。
 
 请开启新会话后重新触发记账。
-```
 
-Agent 根据当前环境，向用户说明开启新会话的具体操作方式：
-- **Cursor**: 按 `Cmd+N` (Mac) / `Ctrl+N` (Windows)
-- **Claude Desktop**: 点击 `+ New Chat`
-- **OpenClaw**: 输入 `/new`
-- **WorkBuddy**: 输入 `/clear`
-- **Trae**: 按 `Cmd/Ctrl + N` 或点击 `+` 按钮
-- **其他**: 输入 `/new` 或菜单"新建会话"
+（操作方式见上方「遇到问题时-方案1」）
+```
 
 ---
 
@@ -157,14 +151,45 @@ Agent 根据当前环境，向用户说明开启新会话的具体操作方式
 - **save_income** - 文字记账（收入）  
 - **save_receipt** - 小票记账（需先调用 get_parse_prompt）
 
+### 智能查询工具（新功能）
+- **get_insights** - 【推荐使用】获取消费洞察（零AI成本！）
+  - 返回消费趋势、模式、优化建议
+  - 让 Agent 结合用户的大模型分析
+- **export_data** - 【深度分析用】导出完整消费数据
+  - 用于 Agent 深度分析
+- **get_statistics** - 获取消费统计（支持周/月周期！）
+  - 新增 `period` 参数：支持 `this_week`、`last_week`、`this_month`、`last_month`
+
 ### 辅助工具
 - **get_skill** - 【记账前必须调用】获取 Skill 文档
 - **get_parse_prompt** - 获取小票解析模板
-- **get_expenses** - 查询支出记录
+- **get_expenses** - 查询支出记录（支持周/月周期！）
+  - 新增 `period` 参数：支持 `this_week`、`last_week`、`this_month`、`last_month`
 - **get_receipt_list** - 查询小票列表
-- **get_statistics** - 获取统计信息
 - **submit_feedback** - 提交反馈
 
+---
+
+## 📊 场景说明（智能分析）
+
+### 场景 1：用户问「帮我看看这周花了多少钱」
+**推荐工具：`get_statistics` 搭配 `period: this_week`**
+参数示例：
+```
+get_statistics period="this_week"
+```
+
+### 场景 2：用户问「分析一下消费习惯」
+**推荐工具：`get_insights` + `export_data`**
+1. 先用 `get_insights` 获取洞察
+2. 再用 `export_data` 获取完整数据
+3. 用用户的大模型进行深度分析
+
+### 场景 3：用户问「最近的消费记录」
+**推荐工具：`get_expenses`**
+- 也可以搭配 `period: this_week` 使用
+
+
 ---
 
 ## 工具详细说明
@@ -254,8 +279,10 @@ Agent **直接使用当前时间**作为收入时间，无需进行时间语义
 
 [自定义其他内容]
 
-MCP Server: v【版本号】
 【友好结束语】
+------------
+chaimi-keep-mcp: v【版本号】
+
 ```
 
 **友好结束语参考：**

package/package.json

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

package/server.js

@@ -187,6 +187,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             originalAmount: { type: 'number', description: '（必填）应付金额（优惠前）' },
             discountAmount: { type: 'number', description: '（必填）优惠金额' },
             actualAmount: { type: 'number', description: '（必填）实付金额（优惠后）' },
+            storeCategory: { type: 'string', description: '【必填】店铺一级分类（购物/美食/生活服务/其他）' },
+            storeSubCategory: { type: 'string', description: '【必填】店铺二级分类（超市/便利店/中餐厅/药店等）' },
             paymentMethod: { type: 'string', description: '支付方式，如：微信支付、支付宝' },
             receiptNo: { type: 'string', description: '小票编号' },
             items: {
@@ -214,15 +216,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             rawInput: { type: 'string', description: '【必填】用户的原始输入内容' },
             mcp_version: { type: 'string', description: '【自动填充】MCP Server版本号' },
           },
-          required: ['store', 'items', 'agentType', 'apiProvider', 'rawInput'],
+          required: ['store', 'items', 'storeCategory', 'storeSubCategory', 'agentType', 'apiProvider', 'rawInput'],
         },
       },
       {
         name: 'get_expenses',
-        description: '查询消费记录。支持按日期范围、分类、商家、来源等多维度筛选',
+        description: '查询消费记录（支持周/月周期）。支持按周/月或日期范围筛选，可查看分类、商家、来源等多维度数据。新功能：新增 period 参数，以及消费模式分析（高频商家、消费时间等）',
         inputSchema: {
           type: 'object',
           properties: {
+            period: { type: 'string', description: '统计周期（推荐使用）：this_week(本周)、last_week(上周)、this_month(本月)、last_month(上月)，与startDate/endDate二选一', enum: ['this_week', 'last_week', 'this_month', 'last_month'] },
             limit: { type: 'number', description: '返回数量限制，默认10条，最大100', default: 10 },
             skip: { type: 'number', description: '跳过条数，用于分页', default: 0 },
             startDate: { type: 'string', description: '开始日期（ISO格式，如：2026-04-01）' },
@@ -233,6 +236,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             source: { type: 'string', description: '按来源筛选（如：mcp_txt_expense、mcp_receipt）' },
             keyword: { type: 'string', description: '按商品名称关键词搜索' },
             orderBy: { type: 'string', description: '排序方式：date_desc(默认)、date_asc、amount_desc、amount_asc', enum: ['date_desc', 'date_asc', 'amount_desc', 'amount_asc'], default: 'date_desc' },
+            includeFlags: { type: 'boolean', description: '是否包含消费标记，默认true', default: true },
           },
         },
       },
@@ -255,13 +259,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'get_statistics',
-        description: '获取消费统计。支持按年月、日期范围统计，可查看分类占比、消费趋势等',
+        description: '获取消费统计（支持周/月周期）。支持按周/月或日期范围统计，可查看分类占比、消费趋势等。新功能：新增 period 参数（this_week、last_week、this_month、last_month），以及 insights 洞察数据',
         inputSchema: {
           type: 'object',
           properties: {
-            yearMonth: { type: 'string', description: '年月（如：2026-03），与startDate/endDate二选一' },
-            startDate: { type: 'string', description: '开始日期（ISO格式），与yearMonth二选一' },
-            endDate: { type: 'string', description: '结束日期（ISO格式），与yearMonth二选一' },
+            period: { type: 'string', description: '统计周期（推荐使用）：this_week(本周)、last_week(上周)、this_month(本月)、last_month(上月)，与yearMonth或startDate/endDate二选一', enum: ['this_week', 'last_week', 'this_month', 'last_month'] },
+            yearMonth: { type: 'string', description: '年月（如：2026-03），与period或startDate/endDate二选一' },
+            startDate: { type: 'string', description: '开始日期（ISO格式），与period或yearMonth二选一' },
+            endDate: { type: 'string', description: '结束日期（ISO格式），与period或yearMonth二选一' },
+            includeInsights: { type: 'boolean', description: '是否包含洞察数据，默认true', default: true },
             type: { type: 'string', description: '统计维度：item(商品明细)、receipt(小票汇总)、category(分类统计)、daily(每日趋势)、store(商家统计)', enum: ['item', 'receipt', 'category', 'daily', 'store'], default: 'category' },
             category: { type: 'string', description: '按特定分类筛选统计' },
             store: { type: 'string', description: '按特定商家筛选统计' },
@@ -269,6 +275,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           },
         },
       },
+      {
+        name: 'get_insights',
+        description: '【新功能】获取消费洞察线索（包含趋势、模式、健康、优化建议）。纯云端计算，零AI成本！返回洞察线索，供 Agent 结合用户大模型进行深度分析',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            period: { type: 'string', description: '统计周期：this_week(本周)、last_week(上周)、this_month(本月)、last_month(上月)', enum: ['this_week', 'last_week', 'this_month', 'last_month'], default: 'this_week' },
+            types: { type: ['string', 'array'], description: '洞察类型：trend(趋势)、pattern(模式)、health(健康)、optimization(优化)，默认为全部', default: ['trend', 'pattern', 'health', 'optimization'] },
+          },
+        },
+      },
+      {
+        name: 'export_data',
+        description: '【新功能】导出完整的消费数据，供 Agent 深度分析（零AI成本！）。支持导出完整的消费记录和小票数据，然后在用户侧使用大模型进行深度分析',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            period: { type: 'string', description: '周期：all(全部)、this_year(今年)、last_year(去年)、custom(自定义)', enum: ['all', 'this_year', 'last_year', 'custom'], default: 'this_year' },
+            format: { type: 'string', description: '导出格式：json 或 csv', enum: ['json', 'csv'], default: 'json' },
+            includeReceipts: { type: 'boolean', description: '是否包含小票记录，默认true', default: true },
+            startDate: { type: 'string', description: '开始日期（period=custom时必填）' },
+            endDate: { type: 'string', description: '结束日期（period=custom时必填）' },
+          },
+        },
+      },
       {
         name: 'save_income',
         description: '保存收入记录（工资、奖金、红包等）。⚠️ 重要：必须先调用 get_text_parse_prompt 解析，然后传入所有解析结果字段',
@@ -328,6 +359,8 @@ const toolMapping = {
   'get_receipt_list': 'getExpenses',
   'get_statistics': 'getStatistics',
   'submit_feedback': 'addFeedback',
+  'get_insights': 'getInsights',
+  'export_data': 'exportData',
 };
 
 // 获取或刷新 Token（OAuth 2.0 Device Flow）
@@ -637,10 +670,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               error: '日期格式无效',
               code: 400
             };
-            userMessage = '❌ 记账失败：日期格式无效，请使用 ISO 8601 格式（如：2026-01-08T11:42:27）';
+            userMessage = '❌ 记账失败：日期格式无效，请使用毫秒级时间戳（13位数字，如：xxxxxxxxxxxxx）';
             break;
           }
-          
+
           if (inputDate > now) {
             result = {
               success: false,
@@ -681,7 +714,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case 'save_receipt': {
         // P0: 数据完整性检查 - 必填字段验证（date 有兜底，不强制检查）
-        const requiredFields = ['store', 'totalAmount', 'actualAmount', 'originalAmount', 'discountAmount'];
+        const requiredFields = ['store', 'totalAmount', 'actualAmount', 'originalAmount', 'discountAmount', 'storeCategory', 'storeSubCategory'];
         const missingFields = [];
 
         for (const field of requiredFields) {
@@ -696,7 +729,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             error: `必填字段缺失：${missingFields.join(', ')}。请从 get_parse_prompt 的解析结果中提取并传递所有字段。`,
             code: 400
           };
-          userMessage = `❌ 保存失败\n\n错误：缺少必填字段：${missingFields.join(', ')}\n\n💡 解决方案：\n1. 请检查是否从 get_parse_prompt 的解析结果中提取了所有信息\n2. 确保传递以下字段：store、totalAmount、actualAmount、originalAmount、discountAmount\n3. 参考 SKILL.md 中的"小票字段核对清单"`;
+          userMessage = `❌ 保存失败\n\n错误：缺少必填字段：${missingFields.join(', ')}\n\n💡 解决方案：\n1. 请检查是否从 get_parse_prompt 的解析结果中提取了所有信息\n2. 确保传递以下字段：store、totalAmount、actualAmount、originalAmount、discountAmount、storeCategory、storeSubCategory\n3. 参考 SKILL.md 中的"小票字段核对清单"`;
           break;
         }
         
@@ -774,7 +807,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               error: '日期格式无效',
               code: 400
             };
-            userMessage = '❌ 保存失败：日期格式无效，请使用 ISO 8601 格式（如：2026-01-08T11:42:27）';
+            userMessage = '❌ 保存失败：日期格式无效，请使用毫秒级时间戳（13位数字，如：xxxxxxxxxxxxx）';
             break;
           }
           
@@ -943,6 +976,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         break;
       }
 
+      case 'get_insights': {
+        const toolName = toolMapping[name];
+        const mcpParams = convertParams(name, processedArgs);
+        result = await callMcpHub(toolName, mcpParams, token);
+
+        if (result.success) {
+          const insightsCount = result.data?.insights?.length || 0;
+          userMessage = `🔍 消费洞察获取成功\n共找到 ${insightsCount} 条洞察线索，供你进行深度分析！`;
+        }
+        break;
+      }
+
+      case 'export_data': {
+        const toolName = toolMapping[name];
+        const mcpParams = convertParams(name, processedArgs);
+        result = await callMcpHub(toolName, mcpParams, token);
+
+        if (result.success) {
+          const totalRecords = result.data?.summary?.totalRecords || 0;
+          const totalAmount = result.data?.summary?.totalAmount || 0;
+          userMessage = `📦 数据导出成功\n共导出 ${totalRecords} 条记录，总金额 ${totalAmount} 元\n数据已准备好，你可以使用大模型进行深度分析了！`;
+        }
+        break;
+      }
+
       case 'save_income': {
         // P0: 数据完整性检查 - 必填字段验证
         const requiredFields = ['name', 'amount', 'category', 'date', 'rawInput'];
@@ -1372,6 +1430,8 @@ function convertParams(toolName, args) {
         apiProvider: args.apiProvider || '',
         mcp_version: args.mcp_version || MCP_VERSION,
         source: 'mcp_receipt',
+        storeCategory: sanitizeString(args.storeCategory, 50) || '其他',
+        storeSubCategory: sanitizeString(args.storeSubCategory, 50) || '其他',
       };
     }