npm - chaimi-keep-mcp - Versions diffs - 3.3.0-beta.8 → 3.3.1-beta.0 - Mend

chaimi-keep-mcp 3.3.0-beta.8 → 3.3.1-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -89,6 +89,16 @@ export MCP_PROMPT_URL="你的Prompt服务地址"
 ## Changelog
+### v3.3.1-beta.0 (2026-04-27)
+- **优化** 简化工具描述 - save_expense/save_receipt/save_income 描述更简洁，不暴露业务逻辑
+- **优化** 参数类型自动转换 - 支持 CLI 工具的字符串传参自动转为数字
+- **优化** 改进错误提示 - 添加 `hint` 和 `debug` 字段，帮助 Agent 自查参数问题
+- **新增** 参数查看指南 - SKILL.md 添加"六.5 如何查看工具参数"章节
+- **优化** 更新记账流程 - 简化为"4步记账法"，更易于 Agent 执行
+### v3.3.0-beta.8 (2026-04-27)
+- **重要变更** Server 只返回原始数据 - 不再构建 userMessage，由 Agent 使用模板渲染
 ### v3.1.47-beta.5 (2026-04-22)
 - **修复** 输入长度限制 - 添加硬性长度检查，防止超大字符串攻击
 - **修复** 错误信息泄露 - 生产环境只显示友好提示，不暴露内部错误

package/SKILL.md CHANGED Viewed

@@ -4,8 +4,7 @@ description: >-
   柴米AI记账MCP Server，连接微信小程序记账功能。
   TRIGGER: 用户提及"记账/记录/保存"并涉及金额或商品信息。
   DO NOT TRIGGER: 非记账操作，或明确使用其他记账工具时。
-version: "3.2.0"
-updated: "2026-04-25"
+updated: "2026-04-27"
 ---
 # 柴米AI记账 Skill
@@ -122,29 +121,71 @@ chaimi-keep-mcp ⭐ 本Skill
 ## 六、快速开始
-### 3步极简记账流程
+### 4步记账法
 ```
-第1步：状态自检
-    ↓ 检查依赖历史习惯
-第2步：获取Skill
-    ↓ 调用 get_skill 获取最新规范
-第3步：执行记账
-    ↓ 调用对应工具(save_expense/income/receipt)
-    ↓ 返回美学回复
-```
+第1步：读文档
+   └─ get_skill() 获取 SKILL.md 规范
+   └─ references/response-templates.md 了解回复模板
+第2步：拿Token
+   └─ 文字记账：get_text_parse_prompt() 获取 Token 和解析模板
+   └─ 小票记账：get_parse_prompt() 获取 Token 和解析模板
-### 首次使用必做
+第3步：AI解析
+   └─ 按模板解析用户输入，生成结构化数据 + _requestToken
-1. **完成授权** → 运行 `./scripts/auth-flow.sh`
-2. **验证安装** → 运行 `./scripts/verify-setup.sh`
-3. **开始记账** → "午餐35元"
+第4步：执行记账
+   └─ 调用工具（save_expense/income/receipt，带上 _requestToken）
+   └─ 根据 _templateLocation 使用模板渲染美学回复
+```
 ---
 ## 七、回复规范
-### 7.1 5层视觉结构
+### 7.1 核心原则
+**Server 只返回原始数据，Agent 必须使用模板自行渲染回复。**
+所有工具调用成功后：
+- ❌ 不再返回 `userMessage` 字段
+- ✅ 返回 `_templateLocation` 指向模板文件位置
+- ✅ 返回 `_templateHint` 提示使用哪个模板
+- ✅ 返回 `_templateVariables` 提供模板变量数据
+### 7.2 模板文件位置
+**主模板文件**: `references/response-templates.md`
+**模板文件结构**:
+```
+references/
+└── response-templates.md    # 完整回复模板库（包含所有工具的回复模板）
+```
+### 7.3 各工具对应的回复模板
+| 工具 | 模板位置 | 模板章节 | 说明 |
+|------|---------|---------|------|
+| `save_expense` | `references/response-templates.md` | 2.1 标准成功模板 | 文字记账成功 |
+| `save_income` | `references/response-templates.md` | 2.1 标准成功模板 | 收入记账成功 |
+| `save_receipt` | `references/response-templates.md` | 2.3 小票记账模板 | 小票记账成功 |
+| `get_expenses` | `references/response-templates.md` | 2.5 查询结果模板 | 消费记录查询 |
+| `get_receipt_list` | `references/response-templates.md` | 2.5 查询结果模板 | 小票列表查询 |
+| `get_statistics` | `references/response-templates.md` | 2.6 统计结果模板 | 消费统计分析 |
+### 7.4 回复模板使用流程
+```
+1. 调用工具 → 返回原始数据 + _templateLocation + _templateHint + _templateVariables
+2. 读取 _templateLocation 指定的模板文件
+3. 根据 _templateHint 选择对应模板章节
+4. 使用 _templateVariables 填充模板变量
+5. 渲染最终回复给用户
+```
+### 7.5 5层视觉结构
 ```
 【第1层：成功标识】✅ 「Agent名称」已帮您记账成功
@@ -164,7 +205,7 @@ chaimi-keep-mcp ⭐ 本Skill
     ───────────────
 ```
-### 7.2 标准成功模板（方案1：双分隔线短版）
+### 7.6 标准成功模板
 ```markdown
 ✅ 「{agentName}」已帮您记账成功
@@ -180,40 +221,13 @@ chaimi-keep-mcp ⭐ 本Skill
 💡 消费洞察：{洞察内容}（可选）
 ───────────────
-🎉 {正能量祝福语}！
-  柴米AI记账
-  chaimi-keep-mcp v{版本号}
-───────────────
-```
-### 7.3 极简模板（连续记账）
-```markdown
-✅ 已记录：{商品名} ¥{金额} · {分类}
-   {正能量祝福语}
-```
-### 7.4 高金额模板（>1000元）
-```markdown
-⚠️ 大额消费确认
-═══════════════
-💰 金额：¥{金额}
-📦 商品：{商品名}
-🕐 时间：{日期}
-✅ 已确认录入「柴米AI记账」
-💡 消费洞察：{洞察内容}（可选）
-───────────────
-💡 {消费建议}
+🎉 {正能量情绪词}！
   柴米AI记账
   chaimi-keep-mcp v{版本号}
 ───────────────
 ```
-### 7.5 变量说明
+### 7.7 模板变量说明
 | 变量 | 说明 | 示例 |
 |:-----|:-----|:-----|
@@ -224,10 +238,12 @@ chaimi-keep-mcp ⭐ 本Skill
 | {商家} | 商家名称（可选） | 麦当劳 |
 | {日期时间} | 格式化时间 | 2026-04-24 12:30 |
 | {洞察内容} | 消费洞察建议（可选） | 本月餐饮支出占比30%，建议控制 |
-| {正能量祝福语} | 分类对应祝福语 | 美食为梦想充电，继续向前冲！🍚 |
+| {正能量情绪词} | 分类对应正能量祝福语 | 美食为梦想充电，继续向前冲！🍚 |
 | {版本号} | MCP版本 | 3.2.0 |
-**详细正能量词库和模板** → 见 references/response-templates.md
+**详细正能量情绪词库和完整模板** → 见 references/response-templates.md
+**历史变更记录** → 见 CHANGELOG.md
 ---
@@ -269,6 +285,6 @@ chaimi-keep-mcp ⭐ 本Skill
 ---
-**文档版本：v3.2.0**
-**最后更新：2026-04-25**
+**最后更新：2026-04-27**
 **Status：生产就绪**

package/package.json CHANGED Viewed

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

package/server.js CHANGED Viewed

@@ -244,7 +244,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'save_expense',
-        description: '保存单商品消费记录（AI文字记账）。只需提供商品名称和金额，其他参数自动填充。示例：name="午餐", amount=35',
+        description: '【强制验证Token】保存单商品消费记录。前置要求：先调用 get_skill 和 get_text_parse_prompt。字段列表见 get_text_parse_prompt 返回的模板。',
         inputSchema: {
           type: 'object',
           properties: {
@@ -266,7 +266,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'save_receipt',
-        description: '【图片小票专用】保存购物小票/发票/收据。⚠️ 重要：items数组中每个商品必须包含完整的4个字段：name（商品名称）、amount（金额=单价×数量）、price（单价）、quantity（数量）。示例：[{"name":"苹果","amount":5.5,"price":5.5,"quantity":1}]',
+        description: '【强制验证Token】【必须上传图片】保存购物小票/发票/收据图片。⚠️ 注意：必须是图片才能使用此工具记账，文字描述请用 save_expense。前置要求：先调用 get_skill 和 get_parse_prompt。items为商品数组，字段列表见 get_parse_prompt 返回的模板.',返回的模板。',
         inputSchema: {
           type: 'object',
           properties: {
@@ -309,7 +309,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'get_expenses',
-        description: '查询消费记录（支持周/月周期）。支持按周/月或日期范围筛选，可查看分类、商家、来源等多维度数据。新功能：新增 period 参数，以及消费模式分析（高频商家、消费时间等）',
+        description: '查询消费记录（支持周/月周期）。支持按周/月或日期范围筛选，可查看分类、商家、来源等多维度数据。新功能：新增 period 参数，以及消费模式分析（高频商家、消费时间等）。返回格式：本工具只返回原始数据，不返回格式化消息。Agent必须使用get_skill获取SKILL.md中的"七、回复规范"，再读取references/response-templates.md中的模板自行渲染回复。',
         inputSchema: {
           type: 'object',
           properties: {
@@ -330,7 +330,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'get_receipt_list',
-        description: '获取小票列表。支持按日期范围、商家、金额等多维度筛选',
+        description: '获取小票列表。支持按日期范围、商家、金额等多维度筛选。返回格式：本工具只返回原始数据，不返回格式化消息。Agent必须使用get_skill获取SKILL.md中的"七、回复规范"，再读取references/response-templates.md中的模板自行渲染回复。',
         inputSchema: {
           type: 'object',
           properties: {
@@ -347,7 +347,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'get_statistics',
-        description: '获取消费统计（支持周/月周期）。支持按周/月或日期范围统计，可查看分类占比、消费趋势等。新功能：新增 period 参数（this_week、last_week、this_month、last_month），以及 insights 洞察数据',
+        description: '获取消费统计（支持周/月周期）。支持按周/月或日期范围统计，可查看分类占比、消费趋势等。新功能：新增 period 参数（this_week、last_week、this_month、last_month），以及 insights 洞察数据。返回格式：本工具只返回原始数据，不返回格式化消息。Agent必须使用get_skill获取SKILL.md中的"七、回复规范"，再读取references/response-templates.md中的模板自行渲染回复。',
         inputSchema: {
           type: 'object',
           properties: {
@@ -365,7 +365,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'get_insights',
-        description: '【新功能】获取消费洞察线索（包含趋势、模式、健康、优化建议）。纯云端计算，零AI成本！返回洞察线索，供 Agent 结合用户大模型进行深度分析',
+        description: '【新功能】获取消费洞察线索（包含趋势、模式、健康、优化建议）。纯云端计算，零AI成本！返回洞察线索，供 Agent 结合用户大模型进行深度分析。返回格式：本工具只返回原始数据，不返回格式化消息。Agent必须使用get_skill获取SKILL.md中的"七、回复规范"，再读取references/response-templates.md中的模板自行渲染回复。',
         inputSchema: {
           type: 'object',
           properties: {
@@ -376,7 +376,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'export_data',
-        description: '【新功能】导出完整的消费数据，供 Agent 深度分析（零AI成本！）。支持导出完整的消费记录和小票数据，然后在用户侧使用大模型进行深度分析',
+        description: '【新功能】导出完整的消费数据，供 Agent 深度分析（零AI成本！）。支持导出完整的消费记录和小票数据，然后在用户侧使用大模型进行深度分析。返回格式：本工具只返回原始数据，不返回格式化消息。Agent必须使用get_skill获取SKILL.md中的"七、回复规范"，再读取references/response-templates.md中的模板自行渲染回复。',
         inputSchema: {
           type: 'object',
           properties: {
@@ -390,7 +390,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'save_income',
-        description: '保存收入记录（工资、奖金、红包等）。⚠️ 重要：必须先调用 get_text_parse_prompt 解析，然后传入所有解析结果字段',
+        description: '【强制验证Token】保存收入记录。前置要求：先调用 get_skill 和 get_text_parse_prompt。字段列表见 get_text_parse_prompt 返回的模板.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -409,7 +409,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'get_text_parse_prompt',
-        description: '获取文字记账解析的Prompt模板，用于指导大模型如何解析用户输入的记账文字。返回的Prompt应作为system message，配合用户输入的记账文字作为user message调用大模型',
+        description: '【不调用100%失败】获取文字记账解析的Prompt模板和requestToken。⚠️ 文字/语音记账必须先调用此工具获取Token，AI解析时必须返回_requestToken字段，否则save_expense/save_income会报MISSING_TOKEN错误！',
         inputSchema: {
           type: 'object',
           properties: {
@@ -420,7 +420,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'get_parse_prompt',
-        description: '获取小票图片解析的Prompt模板，用于指导大模型如何格式化输出小票信息。返回的Prompt应作为system message，配合小票图片作为user message调用大模型',
+        description: '【不调用100%失败】获取小票图片解析的Prompt模板和requestToken。⚠️ 小票记账必须先调用此工具获取Token，AI解析时必须返回_requestToken字段，否则save_receipt会报MISSING_TOKEN错误！',
         inputSchema: {
           type: 'object',
           properties: {
@@ -430,7 +430,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'submit_feedback',
-        description: '提交反馈、建议或问题报告。当用户遇到记账问题、有功能建议或发现异常时，可使用此工具提交反馈。反馈类型包括：bug(问题报告)、feature(功能建议)、improvement(优化建议)、other(其他)。提交成功后会返回反馈编号，可用于查询处理进度。注意：反馈内容不要超过150个字符，超过部分会被截断',
+        description: '提交反馈、建议或问题报告。当用户遇到记账问题、有功能建议或发现异常时，可使用此工具提交反馈。反馈类型包括：bug(问题报告)、feature(功能建议)、improvement(优化建议)、other(其他)。提交成功后会返回反馈编号，可用于查询处理进度。注意：反馈内容不要超过150个字符，超过部分会被截断。返回格式：本工具只返回原始数据，不返回格式化消息。Agent必须使用get_skill获取SKILL.md中的"七、回复规范"，再读取references/response-templates.md中的模板自行渲染回复。',
         inputSchema: {
           type: 'object',
           properties: {
@@ -478,9 +478,7 @@ async function getToken() {
     const existingToken = await oauthManager.tokenStorage.load();
     if (existingToken && existingToken.accessToken && existingToken.expiresAt) {
       const expiresAt = new Date(existingToken.expiresAt).getTime();
-      const now = Date.now();
-      const threshold = now + 5 * 60 * 1000;
-      if (expiresAt > threshold) {
+      if (expiresAt > Date.now() + 5 * 60 * 1000) {
         // Token 有效，直接使用
         cachedToken = existingToken.accessToken;
         tokenExpireTime = expiresAt;
@@ -886,8 +884,41 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
     }
+    // 【新增】参数类型自动转换（兼容 CLI 工具的字符串传参）
+    function autoConvertTypes(toolName, args) {
+      const numberFields = {
+        'save_expense': ['amount', 'date'],
+        'save_receipt': ['totalAmount', 'actualAmount', 'originalAmount', 'discountAmount', 'date'],
+        'save_income': ['amount', 'date'],
+      };
+      const fields = numberFields[toolName] || [];
+      for (const field of fields) {
+        if (field in args && typeof args[field] !== 'number') {
+          const parsed = parseFloat(args[field]);
+          if (!isNaN(parsed)) {
+            console.error(`[TypeConvert] ${field}: "${args[field]}" → ${parsed}`);
+            args[field] = parsed;
+          }
+        }
+      }
+      // 转换 items 数组中的数字字段
+      if (args.items && Array.isArray(args.items)) {
+        args.items.forEach(item => {
+          ['amount', 'price', 'quantity'].forEach(field => {
+            if (field in item && typeof item[field] !== 'number') {
+              const parsed = parseFloat(item[field]);
+              if (!isNaN(parsed)) item[field] = parsed;
+            }
+          });
+        });
+      }
+    }
+    autoConvertTypes(name, processedArgs);
     let result;
-    let userMessage;
     switch (name) {
       case 'get_skill': {
@@ -931,8 +962,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (missingFields.length > 0) {
           result = {
             success: false,
-            error: `必填字段缺失：${missingFields.join(', ')}。请从解析结果中提取并传递所有字段。`,
-            code: 400
+            error: `必填字段缺失：${missingFields.join(', ')}`,
+            code: 400,
+            hint: '解决方法：1.查看 SKILL.md 中"六.5 如何查看工具参数" 2.运行 mcporter list 柴米记账 --schema 查看完整参数结构',
+            debug: {
+              missing: missingFields,
+              received: Object.keys(processedArgs),
+              docs: '调用 get_skill() 获取详细使用指南'
+            }
           };
           userMessage = `❌ 记账失败\n\n错误：缺少必填字段：${missingFields.join(', ')}\n\n💡 解决方案：\n1. 请检查是否从用户输入中提取了所有信息\n2. 确保传递以下字段：name（商品名）、amount（金额）、category（分类）、rawInput（原始输入）\n3. 参考 SKILL.md 中的"调用前检查清单"`;
           break;
@@ -995,17 +1032,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             achievementsText = '\n\n🎉 成就解锁：' + result.newlyUnlocked.map(a => `${a.icon} ${a.title}（+${a.points}分）`).join('；');
           }
-          // 【新增】获取 Agent 名称
-          const agentName = await getAgentName();
-          // 按 SKILL 规范格式：新的回复模板
-          const displayStoreText = displayStore ? `【${displayStore}】` : '';
-          const dateStr = result.data?.date ? new Date(result.data.date).toLocaleDateString('zh-CN') : new Date().toLocaleDateString('zh-CN');
-          userMessage = `✅ 「${agentName}」已帮您录入「柴米AI记账」\n    · 商品/店名：${displayName}${displayStoreText} 💰¥${displayAmount}\n    · 收支类型： 支出\n    · 分类：${result.data?.categoryName || displayCategory}\n    · 时间：${dateStr}\n✅ ${friendlyEnding}${insightsText}${achievementsText}\n-------------\nchaimi-keep-mcp: v${MCP_VERSION}`;
-          if (!processedArgs.agentType || !processedArgs.apiProvider) {
-            userMessage += '\n\n💡 提示：传递agentType和apiProvider参数可解锁小程序记录来源统计功能，示例：agentType="openclaw", apiProvider="doubao"';
-          }
+          // 【新增】返回模板位置信息（Server只返回原始数据，Agent使用模板渲染）
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的2.1标准成功模板渲染回复';
+          result._templateVariables = {
+            agentName: await getAgentName(),
+            商品名: displayName,
+            商家: displayStore || '',
+            金额: displayAmount,
+            分类: result.data?.categoryName || displayCategory,
+            日期: result.data?.date ? new Date(result.data.date).toLocaleDateString('zh-CN') : new Date().toLocaleDateString('zh-CN'),
+            正能量祝福语: friendlyEnding,
+            insightsText,
+            achievementsText
+          };
         }
         break;
       }
@@ -1024,14 +1064,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (missingFields.length > 0) {
           result = {
             success: false,
-            error: `必填字段缺失：${missingFields.join(', ')}。请从 get_parse_prompt 的解析结果中提取并传递所有字段。`,
-            code: 400
+            error: `必填字段缺失：${missingFields.join(', ')}`,
+            code: 400,
+            hint: '解决方法：1.查看 SKILL.md 中"六.5 如何查看工具参数" 2.运行 mcporter list 柴米记账 --schema 查看完整参数结构',
+            debug: {
+              missing: missingFields,
+              received: Object.keys(processedArgs),
+              docs: '调用 get_skill() 获取详细使用指南'
+            }
           };
-          userMessage = `❌ 保存失败\n\n错误：缺少必填字段：${missingFields.join(', ')}\n\n💡 解决方案：\n1. 请检查是否从 get_parse_prompt 的解析结果中提取了所有信息\n2. 确保传递以下字段：store、totalAmount、actualAmount、originalAmount、discountAmount、storeCategory、storeSubCategory\n3. 参考 SKILL.md 中的"小票字段核对清单"`;
-          break;
-        }
-        // 数值校验
+          userMessage = `❌ 保存失败\n\n错误：缺少必填字段：${missingFields.join(', ')}\n\n💡 解决方案：\n1. 请检查是否从 get_parse_prompt 的解析结果中提取了所有信息\n2. 确保传递以下字段：store、totalAmount、actualAmount、originalAmount、discountAmount、storeCategory、storeSubCategory\n3. 参考 SKILL.md 中的"小票字段核对清单"`;\n          break;\n        }\n        \n        // 数值校验
         const amountFields = ['totalAmount', 'actualAmount', 'originalAmount'];
         for (const field of amountFields) {
           if (typeof processedArgs[field] !== 'number' || processedArgs[field] <= 0) {
@@ -1240,16 +1282,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             achievementsText = '\n\n🎉 成就解锁：' + result.newlyUnlocked.map(a => `${a.icon} ${a.title}（+${a.points}分）`).join('；');
           }
-          // 【新增】获取 Agent 名称
-          const agentName = await getAgentName();
-          // 按 SKILL 规范格式：新的回复模板
-          const dateStr = result.data?.date ? new Date(result.data.date).toLocaleDateString('zh-CN') : new Date().toLocaleDateString('zh-CN');
-          userMessage = `✅ 「${agentName}」已帮您录入「柴米AI记账」\n    · 商品/店名：${storeName} 💰¥${totalAmount}\n    · 收支类型： 支出\n    · 分类：${result.data?.storeCategory || category}\n    · 商品数量：${itemCount}件\n    · 时间：${dateStr}\n✅ ${friendlyEnding}${insightsText}${achievementsText}\n-------------\nchaimi-keep-mcp: v${MCP_VERSION}`;
-          if (!processedArgs.agentType || !processedArgs.apiProvider) {
-            userMessage += '\n\n💡 提示：传递agentType和apiProvider参数可解锁小程序记录来源统计功能，示例：agentType="openclaw", apiProvider="doubao"';
-          }
+          // 【新增】返回模板位置信息（Server只返回原始数据，Agent使用模板渲染）
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的2.3小票记账模板渲染回复';
+          result._templateVariables = {
+            agentName: await getAgentName(),
+            store: storeName,
+            totalAmount: totalAmount,
+            category: result.data?.storeCategory || category,
+            itemCount: itemCount,
+            date: result.data?.date ? new Date(result.data.date).toLocaleDateString('zh-CN') : new Date().toLocaleDateString('zh-CN'),
+            正能量祝福语: friendlyEnding,
+            insightsText,
+            achievementsText,
+            items: processedArgs.items
+          };
         }
         break;
       }
@@ -1265,33 +1312,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const items = result.data?.items || [];
           const patterns = result.data?.patterns || {};
-          // 构建友好的摘要信息
-          let summary = `📊 消费记录查询成功\n\n`;
-          summary += `📋 共找到 ${total} 条记录\n`;
-          // 高频商家
-          if (patterns.highFrequencyStores && patterns.highFrequencyStores.length > 0) {
-            const topStore = patterns.highFrequencyStores[0];
-            summary += `🏪 高频商家：${topStore.store}（${topStore.count}次，均价¥${topStore.avgAmount}）\n`;
-          }
-          // 消费时间模式
-          if (patterns.timePattern) {
-            summary += `⏰ 消费高峰：${patterns.timePattern.peakTime}\n`;
-            if (patterns.timePattern.lateNightCount > 0) {
-              summary += `🌙 深夜消费：${patterns.timePattern.lateNightCount}次\n`;
-            }
-          }
-          // 异常消费
-          if (patterns.unusualItems && patterns.unusualItems.length > 0) {
-            const topUnusual = patterns.unusualItems[0];
-            summary += `💡 大额消费：${topUnusual.name} ¥${topUnusual.amount}\n`;
-          }
-          summary += `\n💡 提示：完整数据（含每笔明细、flags标记）请查看下方 JSON 数据`;
-          userMessage = summary;
+          // 【新增】返回模板位置信息（Server只返回原始数据，Agent使用模板渲染）
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的2.5查询结果模板渲染回复';
+          result._templateVariables = {
+            total: total,
+            items: items,
+            patterns: patterns
+          };
         }
         break;
       }
@@ -1304,42 +1332,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (result.success) {
           const data = result.data || {};
-          // 构建友好的统计摘要
-          let summary = `📈 统计查询成功\n\n`;
-          summary += `📅 周期：${data.periodDisplay || data.period || '未知'}\n`;
-          summary += `💰 总支出：¥${data.totalAmount || 0}（${data.totalCount || 0}笔）\n`;
-          // 环比对比
-          if (data.compare && data.compare.vsLastPeriod !== undefined) {
-            const change = data.compare.vsLastPeriod;
-            const emoji = change > 0 ? '📈' : change < 0 ? '📉' : '➡️';
-            summary += `${emoji} 环比：${change > 0 ? '+' : ''}${change}%\n`;
-          }
-          // 预算进度
-          if (data.budget) {
-            summary += `🎯 预算：已用¥${data.budget.used}/¥${data.budget.total}（${data.budget.progress}%）\n`;
-          }
-          // Top 3 分类
-          if (data.categories && data.categories.length > 0) {
-            summary += `\n📂 消费分类 Top3：\n`;
-            data.categories.slice(0, 3).forEach((cat, idx) => {
-              summary += `  ${idx + 1}. ${cat.category}：¥${cat.amount}（${cat.percentage}%）\n`;
-            });
-          }
-          // 洞察摘要
-          if (data.insights && data.insights.length > 0) {
-            summary += `\n💡 洞察线索（${data.insights.length}条）：\n`;
-            data.insights.slice(0, 3).forEach(insight => {
-              summary += `  ${insight.emoji || '•'} ${insight.title}：${insight.message}\n`;
-            });
-          }
-          summary += `\n💡 提示：完整数据（含每日统计、所有洞察）请查看下方 JSON 数据`;
-          userMessage = summary;
+          // 【新增】返回模板位置信息（Server只返回原始数据，Agent使用模板渲染）
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的2.6统计结果模板渲染回复';
+          result._templateVariables = {
+            period: data.periodDisplay || data.period || '未知',
+            totalAmount: data.totalAmount || 0,
+            totalCount: data.totalCount || 0,
+            compare: data.compare,
+            budget: data.budget,
+            categories: data.categories,
+            insights: data.insights
+          };
         }
         break;
       }
@@ -1383,9 +1387,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
           }
-          summary += `\n💡 提示：每条洞察都包含 suggestionForAgent 字段，可用于深度分析`;
-          userMessage = summary;
+          // 【新增】返回模板位置信息（Server只返回原始数据，Agent使用模板渲染）
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的2.6智能洞察模板渲染回复';
+          result._templateVariables = {
+            insights: insights
+          };
         }
         break;
       }
@@ -1401,15 +1408,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const totalAmount = summary.totalAmount || 0;
           const periodDisplay = result.data?.periodDisplay || '';
-          let summaryText = `📦 数据导出完成\n\n`;
-          if (periodDisplay) {
-            summaryText += `📅 周期：${periodDisplay}\n`;
-          }
-          summaryText += `📊 导出记录数：${totalRecords}条\n`;
-          summaryText += `💰 总金额：¥${totalAmount.toFixed ? totalAmount.toFixed(2) : totalAmount}\n`;
-          summaryText += `\n✅ 完整数据已准备好，你可以使用自己的大模型进行深度分析了！\n（完整数据在下方的完整数据JSON中）`;
-          userMessage = summaryText;
+          // 【新增】返回模板位置信息（Server只返回原始数据，Agent使用模板渲染）
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的模板渲染回复';
+          result._templateVariables = {
+            period: periodDisplay,
+            totalRecords: totalRecords,
+            totalAmount: totalAmount
+          };
         }
         break;
       }
@@ -1428,8 +1434,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (missingFields.length > 0) {
           result = {
             success: false,
-            error: `必填字段缺失：${missingFields.join(', ')}。请从用户输入中提取并传递所有字段。`,
-            code: 400
+            error: `必填字段缺失：${missingFields.join(', ')}`,
+            code: 400,
+            hint: '解决方法：1.查看 SKILL.md 中"六.5 如何查看工具参数" 2.运行 mcporter list 柴米记账 --schema 查看完整参数结构',
+            debug: {
+              missing: missingFields,
+              received: Object.keys(processedArgs),
+              docs: '调用 get_skill() 获取详细使用指南'
+            }
           };
           userMessage = `❌ 收入记录失败\n\n错误：缺少必填字段：${missingFields.join(', ')}\n\n💡 解决方案：\n1. 请检查是否从用户输入中提取了所有信息\n2. 确保传递以下字段：name（收入来源）、amount（金额）、category（分类）、date（日期）、rawInput（原始输入）\n3. 参考 SKILL.md 中的"调用前检查清单"`;
           break;
@@ -1468,14 +1480,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           const displayAmount = processedArgs.amount || 0;
           const displayCategory = processedArgs.category || '其他';
           const displayStore = processedArgs.store || '';
-          const displayStoreText = displayStore ? `【${displayStore}】` : '';
-          // 【新增】获取 Agent 名称
-          const agentName = await getAgentName();
-          // 按 SKILL 规范格式：新的回复模板
-          const dateStr = result.data?.date ? new Date(result.data.date).toLocaleDateString('zh-CN') : new Date().toLocaleDateString('zh-CN');
-          userMessage = `✅ 「${agentName}」已帮您录入「柴米AI记账」\n    · 商品/店名：${displayName}${displayStoreText} 💰¥${displayAmount}\n    · 收支类型： 收入\n    · 分类：${result.data?.categoryName || displayCategory}\n    · 时间：${dateStr}\n✅ 入账顺利！💰\n-------------\nchaimi-keep-mcp: v${MCP_VERSION}`;
+          // 【新增】返回模板位置信息（Server只返回原始数据，Agent使用模板渲染）
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的2.1标准成功模板渲染回复';
+          result._templateVariables = {
+            agentName: await getAgentName(),
+            商品名: displayName,
+            商家: displayStore,
+            金额: displayAmount,
+            分类: result.data?.categoryName || displayCategory,
+            日期: result.data?.date ? new Date(result.data.date).toLocaleDateString('zh-CN') : new Date().toLocaleDateString('zh-CN'),
+            正能量祝福语: '入账顺利！💰'
+          };
         }
         break;
       }
@@ -1493,13 +1510,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               systemPrompt: promptResult.data.systemPrompt,
               userPromptTemplate: promptResult.data.userPromptTemplate,
               examples: promptResult.data.examples,
-              instructions: '请将 systemPrompt 作为 system message，把小票图片作为 user message，调用你的大模型进行解析。解析完成后，调用 save_receipt 工具保存结果。'
+              requestToken: promptResult.data.requestToken,
+              instructions: '请将 systemPrompt 作为 system message，把小票图片作为 user message，调用你的大模型进行解析。解析完成后，调用 save_receipt 工具保存结果。⚠️ 注意：AI解析结果必须包含 _requestToken 字段！'
             }
           };
-          userMessage = `✅ 获取解析Prompt成功\n\n版本: ${promptResult.data.version}\n\n## System Prompt\n\n请将以下内容作为 system message 发送给大模型：\n\n\`\`\`\n${promptResult.data.systemPrompt}\n\`\`\`\n\n## 使用说明\n\n1. 将上面的 System Prompt 作为 system message\n2. 将小票图片作为 user message\n3. 调用大模型解析\n4. 解析完成后，调用 save_receipt 工具保存结果\n\n## 示例\n\n${JSON.stringify(promptResult.data.examples, null, 2)}`;
+          // 【新增】返回模板位置信息（Server只返回原始数据，Agent使用模板渲染）
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的2.1标准成功模板渲染回复';
+          result._templateVariables = {
+            version: promptResult.data.version,
+            examples: promptResult.data.examples
+          };
         } else {
           result = { success: false, error: promptResult.error };
-          userMessage = `❌ 获取Prompt失败：${promptResult.error}`;
         }
         break;
       }
@@ -1515,13 +1538,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               prompt: promptResult.data.prompt,
               currentDate: promptResult.data.currentDate,
               currentTime: promptResult.data.currentTime,
+              requestToken: promptResult.data.requestToken,
               instructions: promptResult.data.instructions
             }
           };
-          userMessage = `✅ 获取文字记账解析 Prompt 成功\n\n当前日期: ${promptResult.data.currentDate}\n当前时间: ${promptResult.data.currentTime}\n\n## Prompt\n\n请将以下内容作为 system message 发送给大模型：\n\n\`\`\`\n${promptResult.data.prompt}\n\`\`\`\n\n## 使用说明\n\n1. 将上面的 Prompt 作为 system message\n2. 将用户输入的记账文字（如"午餐 24块"）作为 user message\n3. 调用大模型解析，获取 JSON 结果\n4. 解析完成后，调用 save_expense 或 save_income 工具保存结果`;
+          // 【新增】返回模板位置信息（Server只返回原始数据，Agent使用模板渲染）
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的2.1标准成功模板渲染回复';
+          result._templateVariables = {
+            currentDate: promptResult.data.currentDate,
+            currentTime: promptResult.data.currentTime
+          };
         } else {
           result = { success: false, error: promptResult.error };
-          userMessage = `❌ 获取文字记账解析 Prompt 失败：${promptResult.error}`;
         }
         break;
       }
@@ -1548,9 +1577,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             other: '其他反馈'
           }[feedbackData.feedType] || '其他反馈';
-          userMessage = `✅ 反馈提交成功！\n\n感谢您的反馈，我们会尽快处理。\n\n━━━━━━━━━━━━━━\n📋 反馈编号：${result.data.feedbackId}\n📂 类型：${typeText}\n⏰ 时间：${new Date().toLocaleString('zh-CN')}\n━━━━━━━━━━━━━━\n\n💡 提示：\n- 反馈编号可用于查询处理进度\n- 如需补充信息，可再次提交并备注原编号\n- 我们会在小程序客服中回复您`;
+          // 【新增】返回模板位置信息（Server只返回原始数据，Agent使用模板渲染）
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的模板渲染回复';
+          result._templateVariables = {
+            feedbackId: result.data.feedbackId,
+            type: typeText,
+            time: new Date().toLocaleString('zh-CN')
+          };
         } else {
-          userMessage = `❌ 反馈提交失败\n\n错误信息：${result.error || '未知错误'}\n\n💡 建议：\n- 检查网络连接后重试\n- 如持续失败，请稍后重试或联系客服`;
+          result._templateLocation = 'references/response-templates.md';
+          result._templateHint = '请使用references/response-templates.md中的模板渲染回复';
+          result._templateVariables = {
+            error: result.error || '未知错误'
+          };
         }
         break;
       }
@@ -1559,21 +1599,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw new Error(`未知工具: ${name}`);
     }
-    if (!result.success) {
-      userMessage = `❌ 操作失败：${result.error || '未知错误'}`;
-    }
     // 【新增】在结果中添加 agentName，让 Agent 可以使用
     const agentName = await getAgentName();
     if (result && typeof result === 'object') {
       result.agentName = agentName;
     }
+    // 【修改】Server 只返回原始数据，不再构建格式化消息
+    // Agent 必须使用 references/response-templates.md 中的模板自行渲染回复
+    const responseData = {
+      success: result.success,
+      data: result.data,
+      error: result.error,
+      _templateLocation: result._templateLocation,
+      _templateHint: result._templateHint,
+      _templateVariables: result._templateVariables,
+      agentName: agentName
+    };
     return {
       content: [
         {
           type: 'text',
-          text: `${userMessage}\n\n---\n📦 柴米记账 MCP v${MCP_VERSION}\n\n## 完整数据\n\`\`\`json\n${safeStringify(result)}\n\`\`\``,
+          text: `⚠️ 【注意】Server 只返回原始数据，不返回格式化消息。\n请使用 _templateLocation 指定的模板自行渲染回复。\n\n---\n📦 柴米记账 MCP v${MCP_VERSION}\n\n## 完整数据\n\`\`\`json\n${safeStringify(responseData)}\n\`\`\``,
         },
       ],
     };
@@ -2185,23 +2233,11 @@ async function pollForAuthInBackground(deviceCode, interval) {
         authState.isWaiting = false;
         // 保存token到文件
-        try {
-          await oauthManager.tokenStorage.save(token);
-          console.error('🔍 [DEBUG] Token 保存完成');
-        } catch (error) {
-          console.error('❌ Token 保存失败:', error.message);
-          throw error;
-        }
+        await oauthManager.tokenStorage.save(token);
         // 【新增】保存默认 Agent 名称和 deviceCode（首次记账时会获取真实名称）
-        try {
-          await oauthManager.tokenStorage.saveAgentName('柴米AI助手');
-          await oauthManager.tokenStorage.saveDeviceCode(authState.deviceCode);
-          console.error('🔍 [DEBUG] Agent 名称和 deviceCode 保存完成');
-        } catch (error) {
-          console.error('❌ Agent 信息保存失败:', error.message);
-          // 这个失败不影响授权，只记录日志
-        }
+        await oauthManager.tokenStorage.saveAgentName('柴米AI助手');
+        await oauthManager.tokenStorage.saveDeviceCode(authState.deviceCode);
         // 清除授权状态
         await oauthManager.clearAuthState();