chaimi-keep-mcp 3.1.49 → 3.2.1-beta.0

package/bin/sync-skill.js

@@ -2,7 +2,7 @@
 /**
  * Skill 文件同步脚本
  * 
- * 功能：安装时自动同步 SKILL.md 到 Skill 架构的 Agent
+ * 功能：安装时自动同步完整 Skill 目录到 Skill 架构的 Agent
  * 支持：OpenClaw、WorkBuddy 等
  * 扩展：可通过 ~/.chaimi-mcp/skill-config.json 添加自定义路径
  */
@@ -22,6 +22,11 @@ const BUILT_IN_PATHS = [
     name: 'WorkBuddy',
     skillPath: path.join(os.homedir(), '.workbuddy', 'skills', 'chaimi-keep-mcp'),
     platform: ['darwin', 'linux', 'win32']
+  },
+  {
+    name: 'Hermes',
+    skillPath: path.join(os.homedir(), '.hermes', 'skills', 'chaimi-keep-mcp'),
+    platform: ['darwin', 'linux', 'win32']
   }
 ];
 
@@ -44,39 +49,99 @@ function loadUserConfig() {
 }
 
 /**
- * 同步 SKILL.md 到指定目录
+ * 同步整个 Skill 目录到指定路径
  */
-function syncSkillToDirectory(targetPath, agentName) {
+function syncSkillDirectory(targetPath, agentName) {
+  const results = [];
+  
   try {
-    const skillSourcePath = path.join(__dirname, '..', 'SKILL.md');
-
-    // 检查源文件是否存在
-    if (!fs.existsSync(skillSourcePath)) {
-      console.error(`❌ ${agentName}: SKILL.md 源文件不存在`);
-      return { success: false, error: 'source-not-found' };
-    }
-
+    const skillSourceDir = path.join(__dirname, '..');
+    
+    // 需要同步的文件和目录
+    const itemsToSync = [
+      { source: 'SKILL.md', target: 'SKILL.md', required: true },
+      { source: '_meta.json', target: '_meta.json', required: true },
+      { source: 'references', target: 'references', required: true, isDirectory: true }
+    ];
+    
     // 检查父目录是否存在（Agent 是否安装）
     const parentDir = path.dirname(targetPath);
     if (!fs.existsSync(parentDir)) {
-      // Agent 未安装，静默跳过
-      return { success: false, reason: 'agent-not-installed' };
+      return { success: false, reason: 'agent-not-installed', details: results };
     }
-
+    
     // 创建 skill 目录
     if (!fs.existsSync(targetPath)) {
       fs.mkdirSync(targetPath, { recursive: true });
     }
-
-    // 复制 SKILL.md
-    const targetFilePath = path.join(targetPath, 'SKILL.md');
-    fs.copyFileSync(skillSourcePath, targetFilePath);
-
-    return { success: true, path: targetFilePath };
-
+    
+    // 同步每个文件/目录
+    for (const item of itemsToSync) {
+      const sourcePath = path.join(skillSourceDir, item.source);
+      const targetItemPath = path.join(targetPath, item.target);
+      
+      // 检查源文件是否存在
+      if (!fs.existsSync(sourcePath)) {
+        if (item.required) {
+          console.error(`❌ ${agentName}: ${item.source} 源文件不存在`);
+          results.push({ file: item.source, success: false, error: 'source-not-found' });
+        }
+        continue;
+      }
+      
+      try {
+        if (item.isDirectory) {
+          // 同步目录
+          syncDirectory(sourcePath, targetItemPath);
+        } else {
+          // 同步文件
+          fs.copyFileSync(sourcePath, targetItemPath);
+        }
+        results.push({ file: item.source, success: true });
+      } catch (error) {
+        console.error(`❌ ${agentName}: 同步 ${item.source} 失败 - ${error.message}`);
+        results.push({ file: item.source, success: false, error: error.message });
+      }
+    }
+    
+    const allSuccess = results.filter(r => r.required !== false).every(r => r.success);
+    return { 
+      success: allSuccess, 
+      path: targetPath,
+      details: results 
+    };
+    
   } catch (error) {
     console.error(`❌ ${agentName}: 同步失败 - ${error.message}`);
-    return { success: false, error: error.message };
+    return { success: false, error: error.message, details: results };
+  }
+}
+
+/**
+ * 递归同步目录
+ */
+function syncDirectory(sourceDir, targetDir) {
+  // 创建目标目录
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+  
+  // 读取源目录内容
+  const items = fs.readdirSync(sourceDir);
+  
+  for (const item of items) {
+    const sourcePath = path.join(sourceDir, item);
+    const targetPath = path.join(targetDir, item);
+    
+    const stat = fs.statSync(sourcePath);
+    
+    if (stat.isDirectory()) {
+      // 递归同步子目录
+      syncDirectory(sourcePath, targetPath);
+    } else {
+      // 复制文件
+      fs.copyFileSync(sourcePath, targetPath);
+    }
   }
 }
 
@@ -95,7 +160,7 @@ function main() {
       continue;
     }
 
-    const result = syncSkillToDirectory(agent.skillPath, agent.name);
+    const result = syncSkillDirectory(agent.skillPath, agent.name);
     results.push({ agent: agent.name, ...result });
 
     if (result.success) {
@@ -115,7 +180,7 @@ function main() {
       continue;
     }
 
-    const result = syncSkillToDirectory(userPath.path, userPath.name);
+    const result = syncSkillDirectory(userPath.path, userPath.name);
     results.push({ agent: userPath.name, ...result });
 
     if (result.success) {

package/oauth.js

@@ -146,7 +146,7 @@ class OAuthManager {
     await execPromise(command);
   }
 
-  async requestDeviceCode(useUrlScheme = false) {
+  async requestDeviceCode(useUrlScheme = false, extraParams = {}) {
     const response = await fetch(this.mcpOAuthUrl, {
       method: 'POST',
       headers: {
@@ -156,7 +156,8 @@ class OAuthManager {
         tool: 'deviceCode',
         params: {
           clientId: 'chaihuo-mcp-client',
-          useUrlScheme: useUrlScheme
+          useUrlScheme: useUrlScheme,
+          ...extraParams
         }
       })
     });
@@ -494,8 +495,9 @@ class FileTokenStorage extends TokenStorage {
         updatedAt: new Date().toISOString()
       };
       await this.fs.writeFile(agentNamePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+      console.error('✅ Agent 名称已保存:', agentNamePath);
     } catch (err) {
-      // 忽略错误，不影响主流程
+      console.error('❌ 保存 Agent 名称失败:', err.message);
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chaimi-keep-mcp",
-  "version": "3.1.49",
+  "version": "3.2.1-beta.0",
   "description": "柴米记账 MCP Server - 支持 Claude、Cursor、OpenClaw、WorkBuddy 等 AI 工具直接记账",
   "main": "server.js",
   "bin": {
@@ -9,9 +9,11 @@
   "files": [
     "bin/",
     "utils/",
+    "references/",
     "server.js",
     "oauth.js",
     "SKILL.md",
+    "_meta.json",
     "README.md",
     "config.example.yaml",
     ".env.example"

package/references/advanced-features.md

@@ -0,0 +1,146 @@
+---
+name: "chaimi-keep-advanced-features"
+description: 柴米AI记账高级功能详解，包含深度分析和智能洞察
+version: "1.0.0"
+updated: "2026-04-25"
+---
+
+# 柴米AI记账高级功能
+
+---
+
+## 目录
+
+- [一、智能洞察详解](#一智能洞察详解)
+- [二、消费模式分析](#二消费模式分析)
+- [三、数据导出与分析](#三数据导出与分析)
+- [四、高级查询技巧](#四高级查询技巧)
+
+---
+
+## 一、智能洞察详解
+
+### 1.1 洞察维度
+
+| 维度 | 说明 | 示例 |
+|:-----|:-----|:-----|
+| **消费频次** | 某类消费次数 | "本周餐饮消费5次" |
+| **消费趋势** | 环比变化 | "比上月增长20%" |
+| **异常检测** | 超出常规的消费 | "今日消费超过日均3倍" |
+| **时段分析** | 高频消费时间 | "午餐时间消费占比60%" |
+| **商家偏好** | 常去商家统计 | "本月麦当劳消费8次" |
+
+### 1.2 洞察生成逻辑
+
+```
+原始数据
+    ↓
+数据清洗（去除异常值）
+    ↓
+模式识别（聚类分析）
+    ↓
+趋势计算（环比/同比）
+    ↓
+洞察生成（自然语言）
+    ↓
+建议推荐（基于规则）
+```
+
+---
+
+## 二、消费模式分析
+
+### 2.1 分析类型
+
+#### 餐饮消费模式
+
+```
+分析维度：
+- 用餐时段偏好（早餐/午餐/晚餐）
+- 用餐方式分布（外卖/堂食/自制）
+- 人均消费区间
+- 高频商家TOP5
+
+输出示例：
+"您偏好午餐外出就餐（占餐饮消费65%），
+ 平均消费35元/餐，
+ 常去商家：麦当劳、肯德基、真功夫"
+```
+
+#### 交通消费模式
+
+```
+分析维度：
+- 出行方式占比（地铁/打车/公交）
+- 通勤成本趋势
+- 高频路线
+
+输出示例：
+"地铁通勤为主（占交通费用80%），
+ 日均通勤成本12元，
+ 建议购买月票可节省20%"
+```
+
+---
+
+## 三、数据导出与分析
+
+### 3.1 导出格式
+
+| 格式 | 适用场景 | 工具 |
+|:-----|:---------|:-----|
+| JSON | 程序处理 | Python/JavaScript |
+| CSV | Excel分析 | Excel/Google Sheets |
+| Markdown | 报告生成 | Markdown编辑器 |
+
+### 3.2 分析示例
+
+```python
+# Python分析示例
+import json
+
+# 加载导出的数据
+with open('chaimi_data.json') as f:
+    data = json.load(f)
+
+# 计算日均消费
+total = sum(item['amount'] for item in data['expenses'])
+days = 30
+daily_avg = total / days
+
+print(f"日均消费：¥{daily_avg:.2f}")
+```
+
+---
+
+## 四、高级查询技巧
+
+### 4.1 时间范围技巧
+
+| 查询需求 | 参数设置 | 说明 |
+|:---------|:---------|:-----|
+| 本周 | period="this_week" | 周一到周日 |
+| 本月 | period="this_month" | 1号到今天 |
+| 上月 | period="last_month" | 完整上月 |
+| 自定义 | start_date + end_date | 任意范围 |
+
+### 4.2 筛选组合
+
+```
+# 查询本月餐饮消费
+{
+  "period": "this_month",
+  "category": "餐饮"
+}
+
+# 查询大额消费（>500）
+{
+  "period": "this_month",
+  "min_amount": 500
+}
+```
+
+---
+
+**文档版本：v1.0.0**
+**最后更新：2026-04-25**

package/references/api-reference.md

@@ -0,0 +1,205 @@
+---
+name: "chaimi-keep-api-reference"
+description: 柴米AI记账API参考 - 查询分析类工具说明
+description: >-
+  柴米AI记账MCP Server API参考。包含查询、统计、分析类工具说明。
+  TRIGGER: 需要查询消费记录、查看统计、导出数据时。
+  DO NOT TRIGGER: 记账操作（直接使用工具即可）。
+version: "1.0.0"
+updated: "2026-04-25"
+---
+
+# 柴米AI记账 API 参考
+
+> ⚠️ **保密提示**：记账类工具（save_expense/save_income/save_receipt）为内部实现，不对外开放详细文档
+
+---
+
+## 目录
+
+- [一、工具分类说明](#一工具分类说明)
+- [二、查询工具](#二查询工具)
+- [三、分析工具](#三分析工具)
+- [四、辅助工具](#四辅助工具)
+- [五、错误码](#五错误码)
+
+---
+
+## 一、工具分类说明
+
+| 分类 | 工具 | 说明 |
+|:-----|:-----|:-----|
+| **记账** | save_expense、save_income、save_receipt | 核心功能，直接调用即可 |
+| **查询** | get_expenses、get_statistics、get_receipt_list | 查询消费记录和统计 |
+| **分析** | get_insights、export_data | AI洞察和数据导出 |
+| **辅助** | get_skill、submit_feedback | 获取文档、提交反馈 |
+
+---
+
+## 二、查询工具
+
+### 2.1 get_expenses - 查询消费记录
+
+**功能：** 按时间范围查询消费记录
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 | 示例 |
+|:-------|:-----|:----:|:-----|:-----|
+| period | string | ✅ | 时间范围 | "this_week", "this_month", "last_month" |
+| start_date | string | ❌ | 开始日期 | "2026-04-01" |
+| end_date | string | ❌ | 结束日期 | "2026-04-30" |
+| category | string | ❌ | 分类筛选 | "餐饮" |
+| limit | number | ❌ | 返回条数 | 10 |
+
+**返回值：**
+
+```json
+{
+  "success": true,
+  "data": {
+    "total": 1250.00,
+    "count": 15,
+    "items": [
+      {
+        "id": "exp_123",
+        "amount": 35.00,
+        "item": "午餐",
+        "category": "餐饮",
+        "date": "2026-04-24"
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 2.2 get_statistics - 统计分析
+
+**功能：** 获取消费统计分析
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 | 示例 |
+|:-------|:-----|:----:|:-----|:-----|
+| period | string | ✅ | 时间范围 | "this_month" |
+| group_by | string | ❌ | 分组方式 | "category", "day" |
+
+**返回值：**
+
+```json
+{
+  "success": true,
+  "data": {
+    "total": 3500.00,
+    "by_category": {
+      "餐饮": 1200.00,
+      "交通": 500.00,
+      "购物": 800.00
+    },
+    "daily_avg": 116.67
+  }
+}
+```
+
+---
+
+### 2.3 get_receipt_list - 小票列表
+
+**功能：** 查询已识别的小票记录
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+|:-------|:-----|:----:|:-----|
+| period | string | ❌ | 时间范围 |
+| limit | number | ❌ | 返回条数 |
+
+---
+
+## 三、分析工具
+
+### 3.1 get_insights - 智能洞察
+
+**功能：** AI分析消费习惯
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 | 示例 |
+|:-------|:-----|:----:|:-----|:-----|
+| period | string | ✅ | 分析周期 | "this_month" |
+| focus | string | ❌ | 关注维度 | "category", "trend" |
+
+**返回值：**
+
+```json
+{
+  "success": true,
+  "data": {
+    "insights": [
+      "本周餐饮消费偏高，建议控制",
+      "通勤费用稳定，继续保持"
+    ],
+    "suggestions": [
+      "尝试自带午餐，可节省约200元/周"
+    ]
+  }
+}
+```
+
+---
+
+### 3.2 export_data - 数据导出
+
+**功能：** 导出完整数据
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 | 示例 |
+|:-------|:-----|:----:|:-----|:-----|
+| format | string | ✅ | 导出格式 | "json", "csv" |
+| period | string | ✅ | 时间范围 | "this_year" |
+
+---
+
+## 四、辅助工具
+
+### 4.1 get_skill - 获取Skill文档
+
+**功能：** 获取最新Skill文档
+
+**参数：** 无
+
+**⚠️ 重要：** 首次使用时调用，获取最新规范
+
+---
+
+### 4.2 submit_feedback - 提交反馈
+
+**功能：** 提交问题反馈
+
+**参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+|:-------|:-----|:----:|:-----|
+| content | string | ✅ | 反馈内容 |
+| type | string | ❌ | 反馈类型 |
+
+---
+
+## 五、错误码
+
+| 错误码 | 说明 | 解决方案 |
+|:-------|:-----|:---------|
+| 400 | 参数错误 | 检查参数格式 |
+| 401 | 未授权 | 完成授权流程 |
+| 403 | 权限不足 | 检查Token权限 |
+| 404 | 记录不存在 | 确认记录ID |
+| 408 | 请求超时 | 稍后重试 |
+| 500 | 服务器错误 | 联系技术支持 |
+
+---
+
+**文档版本：v1.0.0**
+**最后更新：2026-04-25**

package/references/authentication.md

@@ -0,0 +1,142 @@
+---
+name: "chaimi-keep-authentication"
+description: 柴米AI记账授权流程详解
+version: "1.0.0"
+updated: "2026-04-25"
+---
+
+# 柴米AI记账授权流程
+
+---
+
+## 目录
+
+- [一、授权原理](#一授权原理)
+- [二、授权流程](#二授权流程)
+- [三、Token管理](#三token管理)
+- [四、安全最佳实践](#四安全最佳实践)
+
+---
+
+## 一、授权原理
+
+### 1.1 授权模型
+
+```
+用户（小程序端）          Agent（MCP端）
+    │                         │
+    │  1. 请求授权             │
+    │────────────────────────>│
+    │                         │
+    │  2. 生成验证码           │
+    │<────────────────────────│
+    │                         │
+    │  3. 小程序确认           │
+    │────────────────────────>│
+    │                         │
+    │  4. 发放Token            │
+    │<────────────────────────│
+    │                         │
+    │  5. Token记账            │
+    │────────────────────────>│
+```
+
+### 1.2 Token有效期
+
+| Token类型 | 有效期 | 说明 |
+|:----------|:-------|:-----|
+| Access Token | 24小时 | 日常记账使用 |
+| Refresh Token | 7天 | 用于刷新Access Token |
+
+---
+
+## 二、授权流程
+
+### 2.1 首次授权
+
+**步骤：**
+
+1. **生成验证码**
+   ```bash
+   ./scripts/auth-flow.sh
+   ```
+   输出：
+   ```
+   🔐 柴米AI记账授权
+   ═══════════════════════════
+   📱 验证码：GGCY-AC84
+   ⏰ 有效期：5分钟
+   ```
+
+2. **小程序确认**
+   - 打开"柴米AI记账"小程序
+   - 点击"我的" → "Agent 授权"
+   - 输入验证码
+   - 点击确认
+
+3. **完成授权**
+   - Agent显示授权成功
+   - 开始记账
+
+### 2.2 重新授权
+
+**场景：** Token过期、更换设备、安全考虑
+
+```bash
+# 方式1：直接重新授权
+./scripts/auth-flow.sh
+
+# 方式2：先撤销再授权
+./scripts/revoke-auth.sh
+./scripts/auth-flow.sh
+```
+
+---
+
+## 三、Token管理
+
+### 3.1 检查Token状态
+
+```bash
+./scripts/check-auth.sh
+```
+
+**输出：**
+```
+✅ 授权状态：有效
+📅 Token有效期：还剩 23 小时
+🔒 安全等级：高
+```
+
+### 3.2 Token刷新
+
+Token将在过期前自动刷新，无需手动操作。
+
+---
+
+## 四、安全最佳实践
+
+### 4.1 安全建议
+
+| 建议 | 说明 |
+|:-----|:-----|
+| 定期更换 | 建议每周重新授权一次 |
+| 设备专用 | 不同设备使用不同Token |
+| 及时撤销 | 不再使用时立即撤销 |
+| 保护验证码 | 勿将验证码告知他人 |
+
+### 4.2 撤销授权
+
+```bash
+./scripts/revoke-auth.sh
+```
+
+**场景：**
+- 更换Agent
+- 安全考虑
+- 不再使用
+
+---
+
+**文档版本：v1.0.0**
+**最后更新：2026-04-25**