chaimi-keep-mcp 3.3.2-beta.0 → 3.3.3-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.
package/README.md CHANGED
@@ -89,11 +89,15 @@ export MCP_PROMPT_URL="你的Prompt服务地址"
89
89
 
90
90
  ## Changelog
91
91
 
92
- ### v3.3.2-beta.0 (2026-04-26)
93
- - **修复** agent-name.json 和 device-code.json 文件写入 0 字节问题
94
- - 将异步 `fs.writeFile()` 改为同步 `fs.writeFileSync()`
95
- - 根本原因:授权成功后从 `process.exit(0)` 改为 `return`,导致异步写入未完成
96
- - 使用同步写入确保文件立即写入完成
92
+ ### v3.3.1-beta.0 (2026-04-27)
93
+ - **优化** 简化工具描述 - save_expense/save_receipt/save_income 描述更简洁,不暴露业务逻辑
94
+ - **优化** 参数类型自动转换 - 支持 CLI 工具的字符串传参自动转为数字
95
+ - **优化** 改进错误提示 - 添加 `hint` `debug` 字段,帮助 Agent 自查参数问题
96
+ - **新增** 参数查看指南 - SKILL.md 添加"六.5 如何查看工具参数"章节
97
+ - **优化** 更新记账流程 - 简化为"4步记账法",更易于 Agent 执行
98
+
99
+ ### v3.3.0-beta.8 (2026-04-27)
100
+ - **重要变更** Server 只返回原始数据 - 不再构建 userMessage,由 Agent 使用模板渲染
97
101
 
98
102
  ### v3.1.47-beta.5 (2026-04-22)
99
103
  - **修复** 输入长度限制 - 添加硬性长度检查,防止超大字符串攻击
@@ -154,12 +158,6 @@ AI 会自动调用 `save_income` 工具记录收入。
154
158
 
155
159
  ## 更新日志
156
160
 
157
- ### v3.3.2-beta.0 (2026-04-26)
158
- - **修复** agent-name.json 和 device-code.json 文件写入 0 字节问题
159
- - 将异步 `fs.writeFile()` 改为同步 `fs.writeFileSync()`
160
- - 根本原因:授权成功后从 `process.exit(0)` 改为 `return`,导致异步写入未完成
161
- - 使用同步写入确保文件立即写入完成
162
-
163
161
  ### v3.1.49-beta.2 (2026-04-24)
164
162
  - **新增** period 参数支持
165
163
  - getStatistics: 支持 this_week/last_week/this_month/last_month 周期筛选
package/SKILL.md CHANGED
@@ -4,8 +4,7 @@ description: >-
4
4
  柴米AI记账MCP Server,连接微信小程序记账功能。
5
5
  TRIGGER: 用户提及"记账/记录/保存"并涉及金额或商品信息。
6
6
  DO NOT TRIGGER: 非记账操作,或明确使用其他记账工具时。
7
- version: "3.2.0"
8
- updated: "2026-04-25"
7
+ updated: "2026-04-27"
9
8
  ---
10
9
 
11
10
  # 柴米AI记账 Skill
@@ -83,90 +82,110 @@ chaimi-keep-mcp ⭐ 本Skill
83
82
 
84
83
  根据用户意图,快速匹配工具和参考文档:
85
84
 
86
- | 用户意图 | 关键词示例 | 前置步骤 | 推荐工具 | 参考文档 | 回复模板 |
87
- |---------|-----------|---------|---------|---------|---------|
88
- | **文字记账** | "午餐35元" | get_text_parse_prompt → AI解析 | save_expense | - | 标准成功模板 |
89
- | **收入记账** | "工资5000" | get_text_parse_prompt → AI解析 | save_income | - | 标准成功模板 |
90
- | **小票记账** | "小票识别" | **get_parse_prompt → AI解析** ⭐ | save_receipt | - | 高金额模板 |
91
- | **查询记录** | "这周花了多少" | - | get_expenses | api-reference.md | 查询结果模板 |
92
- | **消费统计** | "月度统计" | - | get_statistics | api-reference.md | 统计分析模板 |
93
- | **智能洞察** | "分析消费习惯" | - | get_insights | advanced-features.md | 洞察分析模板 |
94
- | **深度分析** | "详细分析" | - | export_data | advanced-features.md | 分析模板 |
95
- | **授权问题** | "无法记账" | - | - | troubleshooting.md | 错误提示模板 |
96
- | **回复格式** | "回复格式" | - | - | response-templates.md | - |
85
+ | 用户意图 | 关键词示例 | 推荐工具 | 参考文档 | 回复模板 |
86
+ |---------|-----------|---------|---------|---------|
87
+ | **文字记账** | "午餐35元" | save_expense | - | 标准成功模板 |
88
+ | **收入记账** | "工资5000" | save_income | - | 标准成功模板 |
89
+ | **小票记账** | "小票识别" | save_receipt | - | 高金额模板 |
90
+ | **查询记录** | "这周花了多少" | get_expenses | api-reference.md | 查询结果模板 |
91
+ | **消费统计** | "月度统计" | get_statistics | api-reference.md | 统计分析模板 |
92
+ | **智能洞察** | "分析消费习惯" | get_insights | advanced-features.md | 洞察分析模板 |
93
+ | **深度分析** | "详细分析" | export_data | advanced-features.md | 分析模板 |
94
+ | **授权问题** | "无法记账" | - | troubleshooting.md | 错误提示模板 |
95
+ | **回复格式** | "回复格式" | - | response-templates.md | - |
97
96
 
98
97
  ---
99
98
 
100
99
  ## 五、工具速查表
101
100
 
102
101
  **设计原则:** Agent一眼看到所有工具,按功能分类
103
- - **记账工具**:⚠️ 小票记账必须先调用 `get_parse_prompt`,不可跳过!
102
+ - **记账工具**:直接调用,无需查看详细文档
104
103
  - **查询分析工具**:详细参数见 api-reference.md
105
104
 
106
- | 分类 | 工具名 | 前置要求 | 功能一句话 | 典型场景 |
107
- |:-----|:-------|:---------|:-----------|:---------|
108
- | **记账** | save_expense | 先 get_text_parse_prompt | 支出记账 | "午餐35元" |
109
- | | save_income | 先 get_text_parse_prompt | 收入记账 | "工资5000" |
110
- | | save_receipt | **先 get_parse_prompt** ⭐ | 小票图片记账 | 上传小票照片 |
111
- | **查询** | get_expenses | - | 查询消费记录 | "这周花了多少" |
112
- | | get_statistics | - | 消费统计分析 | "月度统计" |
113
- | | get_receipt_list | - | 查询小票列表 | "查看小票记录" |
114
- | **分析** | get_insights | - | AI消费洞察 | "分析消费习惯" |
115
- | | export_data | - | 导出完整数据 | 深度分析 |
116
- | **辅助** | get_skill | - | 【必须】获取Skill文档 | 记账前调用 |
117
- | | get_text_parse_prompt | - | 获取文字解析模板 | 文字记账前置 |
118
- | | get_parse_prompt | - | **获取小票解析模板** | 小票记账前置 ⭐ |
119
- | | submit_feedback | - | 提交反馈 | 问题反馈 |
120
-
121
- **⚠️ 重要**:save_receipt 必须前置调用 get_parse_prompt,否则会导致 weight 和 marketPrice 计算错误!
105
+ | 分类 | 工具名 | 功能一句话 | 典型场景 |
106
+ |:-----|:-------|:-----------|:---------|
107
+ | **记账** | save_expense | 支出记账 | "午餐35元" |
108
+ | | save_income | 收入记账 | "工资5000" |
109
+ | | save_receipt | 小票图片记账 | 上传小票照片 |
110
+ | **查询** | get_expenses | 查询消费记录 | "这周花了多少" |
111
+ | | get_statistics | 消费统计分析 | "月度统计" |
112
+ | | get_receipt_list | 查询小票列表 | "查看小票记录" |
113
+ | **分析** | get_insights | AI消费洞察 | "分析消费习惯" |
114
+ | | export_data | 导出完整数据 | 深度分析 |
115
+ | **辅助** | get_skill | 【必须】获取Skill文档 | 记账前调用 |
116
+ | | get_text_parse_prompt | 获取文字解析模板 | 文字记账前 |
117
+ | | get_parse_prompt | 获取小票解析模板 | 小票记账前 |
118
+ | | submit_feedback | 提交反馈 | 问题反馈 |
122
119
 
123
120
  ---
124
121
 
125
122
  ## 六、快速开始
126
123
 
127
- ### 记账流程(按类型区分)
128
-
129
- #### A. 文字记账
124
+ ### 4步记账法
130
125
 
131
126
  ```
132
- 第1步:获取文字解析模板
133
- 调用 get_text_parse_prompt 获取Prompt
134
- 第2步:AI解析文字
135
- ↓ 使用Prompt + 用户输入调用AI
136
- 3步:保存数据
137
- 调用 save_expense save_income
138
- 返回美学回复
127
+ 第1步:读文档
128
+ └─ get_skill() 获取 SKILL.md 规范
129
+ └─ references/response-templates.md 了解回复模板
130
+
131
+ 2步:拿Token
132
+ └─ 文字记账:get_text_parse_prompt() 获取 Token 和解析模板
133
+ └─ 小票记账:get_parse_prompt() 获取 Token 和解析模板
134
+
135
+ 第3步:AI解析
136
+ └─ 按模板解析用户输入,生成结构化数据 + _requestToken
137
+
138
+ 第4步:执行记账
139
+ └─ 调用工具(save_expense/income/receipt,带上 _requestToken)
140
+ └─ 根据 _templateLocation 使用模板渲染美学回复
139
141
  ```
140
142
 
141
- #### B. 小票图片记账(复杂)
143
+ ---
144
+
145
+ ## 七、回复规范
146
+
147
+ ### 7.1 核心原则
148
+
149
+ **Server 只返回原始数据,Agent 必须使用模板自行渲染回复。**
150
+
151
+ 所有工具调用成功后:
152
+ - ❌ 不再返回 `userMessage` 字段
153
+ - ✅ 返回 `_templateLocation` 指向模板文件位置
154
+ - ✅ 返回 `_templateHint` 提示使用哪个模板
155
+ - ✅ 返回 `_templateVariables` 提供模板变量数据
142
156
 
157
+ ### 7.2 模板文件位置
158
+
159
+ **主模板文件**: `references/response-templates.md`
160
+
161
+ **模板文件结构**:
143
162
  ```
144
- 第1步:获取小票解析模板 ⭐关键
145
- 调用 get_parse_prompt(type: 'parseReceipt')
146
- ↓ 获取Prompt模板和字段规范
147
-
148
- 第2步:AI解析图片 ⭐关键
149
- ↓ 使用Prompt模板 + 小票图片调用AI
150
- ↓ 获取解析后的商品列表(items)
151
-
152
- 第3步:保存数据
153
- ↓ 调用 save_receipt(items: 步骤2的结果)
154
- ↓ 返回美学回复
163
+ references/
164
+ └── response-templates.md # 完整回复模板库(包含所有工具的回复模板)
155
165
  ```
156
166
 
157
- **重要提示**:小票记账必须执行第1、2步!跳过会导致数据格式错误!
167
+ ### 7.3 各工具对应的回复模板
158
168
 
159
- ### 首次使用必做
169
+ | 工具 | 模板位置 | 模板章节 | 说明 |
170
+ |------|---------|---------|------|
171
+ | `save_expense` | `references/response-templates.md` | 2.1 标准成功模板 | 文字记账成功 |
172
+ | `save_income` | `references/response-templates.md` | 2.1 标准成功模板 | 收入记账成功 |
173
+ | `save_receipt` | `references/response-templates.md` | 2.3 小票记账模板 | 小票记账成功 |
174
+ | `get_expenses` | `references/response-templates.md` | 2.5 查询结果模板 | 消费记录查询 |
175
+ | `get_receipt_list` | `references/response-templates.md` | 2.5 查询结果模板 | 小票列表查询 |
176
+ | `get_statistics` | `references/response-templates.md` | 2.6 统计结果模板 | 消费统计分析 |
160
177
 
161
- 1. **安装 MCP Server** → 参考 README.md 安装指引
162
- 2. **完成授权** → 首次使用时会自动显示授权码,在"柴米AI记账"小程序中输入即可完成授权
163
- 3. **开始记账** → "午餐35元"
178
+ ### 7.4 回复模板使用流程
164
179
 
165
- ---
166
-
167
- ## 七、回复规范
180
+ ```
181
+ 1. 调用工具 → 返回原始数据 + _templateLocation + _templateHint + _templateVariables
182
+ 2. 读取 _templateLocation 指定的模板文件
183
+ 3. 根据 _templateHint 选择对应模板章节
184
+ 4. 使用 _templateVariables 填充模板变量
185
+ 5. 渲染最终回复给用户
186
+ ```
168
187
 
169
- ### 7.1 5层视觉结构
188
+ ### 7.5 5层视觉结构
170
189
 
171
190
  ```
172
191
  【第1层:成功标识】✅ 「Agent名称」已帮您记账成功
@@ -186,7 +205,7 @@ chaimi-keep-mcp ⭐ 本Skill
186
205
  ───────────────
187
206
  ```
188
207
 
189
- ### 7.2 标准成功模板(方案1:双分隔线短版)
208
+ ### 7.6 标准成功模板
190
209
 
191
210
  ```markdown
192
211
  ✅ 「{agentName}」已帮您记账成功
@@ -202,33 +221,13 @@ chaimi-keep-mcp ⭐ 本Skill
202
221
  💡 消费洞察:{洞察内容}(可选)
203
222
 
204
223
  ───────────────
205
- 🎉 {正能量祝福语}!
224
+ 🎉 {正能量情绪词}!
206
225
  柴米AI记账
207
226
  chaimi-keep-mcp v{版本号}
208
227
  ───────────────
209
228
  ```
210
229
 
211
- ### 7.3 高金额模板(>1000元)
212
-
213
- ```markdown
214
- ⚠️ 大额消费确认
215
- ═══════════════
216
- 💰 金额:¥{金额}
217
- 📦 商品:{商品名}
218
- 🕐 时间:{日期}
219
-
220
- ✅ 已确认录入「柴米AI记账」
221
-
222
- 💡 消费洞察:{洞察内容}(可选)
223
-
224
- ───────────────
225
- 💡 {消费建议}
226
- 柴米AI记账
227
- chaimi-keep-mcp v{版本号}
228
- ───────────────
229
- ```
230
-
231
- ### 7.4 变量说明
230
+ ### 7.7 模板变量说明
232
231
 
233
232
  | 变量 | 说明 | 示例 |
234
233
  |:-----|:-----|:-----|
@@ -239,10 +238,12 @@ chaimi-keep-mcp ⭐ 本Skill
239
238
  | {商家} | 商家名称(可选) | 麦当劳 |
240
239
  | {日期时间} | 格式化时间 | 2026-04-24 12:30 |
241
240
  | {洞察内容} | 消费洞察建议(可选) | 本月餐饮支出占比30%,建议控制 |
242
- | {正能量祝福语} | 分类对应祝福语 | 美食为梦想充电,继续向前冲!🍚 |
241
+ | {正能量情绪词} | 分类对应正能量祝福语 | 美食为梦想充电,继续向前冲!🍚 |
243
242
  | {版本号} | MCP版本 | 3.2.0 |
244
243
 
245
- **详细正能量词库和模板** → 见 references/response-templates.md
244
+ **详细正能量情绪词库和完整模板** → 见 references/response-templates.md
245
+
246
+ **历史变更记录** → 见 CHANGELOG.md
246
247
 
247
248
  ---
248
249
 
@@ -262,11 +263,27 @@ chaimi-keep-mcp ⭐ 本Skill
262
263
 
263
264
  | 错误 | 现象 | 解决方案 | 参考文档 |
264
265
  |:-----|:-----|:---------|:---------|
265
- | **授权失败** | "未找到有效授权" | 运行 `./scripts/auth-flow.sh` 重新授权 | troubleshooting.md |
266
+ | **授权失败** | "未找到有效授权" | 执行 `mcporter auth 柴米记账` 重新授权 | troubleshooting.md |
266
267
  | **分类不明** | "无法识别分类" | 明确说分类:"午餐35元餐饮" | api-reference.md |
267
268
  | **网络超时** | "请求超时" | 检查网络,稍后重试 | troubleshooting.md |
268
269
 
269
- **完整故障排除** → 见 references/troubleshooting.md
270
+ ---
271
+
272
+ ## 📚 重要参考文档
273
+
274
+ > **遇到问题?查看详细文档:**
275
+
276
+ ### 🔧 故障排除
277
+ **完整故障排除指南 →** [references/troubleshooting.md](references/troubleshooting.md)
278
+ - 授权失败、Token过期
279
+ - 记账失败、分类错误
280
+ - 网络超时、服务器错误
281
+
282
+ ### 😊 回复模板
283
+ **详细情绪词库和完整模板 →** [references/response-templates.md](references/response-templates.md)
284
+ - 记账成功回复模板
285
+ - 错误引导模板
286
+ - 情感化表达词库
270
287
 
271
288
  ---
272
289
 
@@ -284,6 +301,6 @@ chaimi-keep-mcp ⭐ 本Skill
284
301
 
285
302
  ---
286
303
 
287
- **文档版本:v3.2.0**
288
- **最后更新:2026-04-25**
304
+
305
+ **最后更新:2026-04-27**
289
306
  **Status:生产就绪**
package/bin/cli.js CHANGED
@@ -293,13 +293,16 @@ function configureAllAgents() {
293
293
  * 注意:使用 console.error,避免污染 stdout(MCP 协议通信使用 stdout)
294
294
  */
295
295
  function showWelcome() {
296
- console.error('╔════════════════════════════════════════════════════════╗');
297
- console.error('║ ║');
298
- console.error(`║ 柴米记账 MCP Server v${CURRENT_VERSION} ║`);
299
- console.error(' ');
300
- console.error('║ 支持: OpenClaw | WorkBuddy | Claude | Cursor ║');
301
- console.error(' ');
302
- console.error('╚════════════════════════════════════════════════════════╝');
296
+ const ver = CURRENT_VERSION;
297
+
298
+ console.error('+--------------------------------------------------------+');
299
+ console.error('| |');
300
+ console.error('| 柴米记账 MCP Server v' + ver + ' |');
301
+ console.error('| |');
302
+ console.error('| 支持: OpenClaw/hermes/WorkBuddy 等国产小龙虾 |');
303
+ console.error('| Claude/Cursor 等支持 MCP 的 Agent |');
304
+ console.error('| |');
305
+ console.error('+--------------------------------------------------------+');
303
306
  console.error('');
304
307
  }
305
308
 
package/oauth.js CHANGED
@@ -497,8 +497,7 @@ class FileTokenStorage extends TokenStorage {
497
497
  agentName: agentName || '柴米AI助手',
498
498
  updatedAt: new Date().toISOString()
499
499
  };
500
- // 使用同步写入,确保立即完成(避免进程继续运行时文件未写入完成)
501
- require('fs').writeFileSync(agentNamePath, JSON.stringify(data, null, 2), { mode: 0o600 });
500
+ await this.fs.writeFile(agentNamePath, JSON.stringify(data, null, 2), 'utf8');
502
501
  console.error('✅ Agent 名称已保存:', agentNamePath);
503
502
  } catch (err) {
504
503
  console.error('❌ 保存 Agent 名称失败:', err.message);
@@ -525,8 +524,7 @@ class FileTokenStorage extends TokenStorage {
525
524
  deviceCode,
526
525
  updatedAt: new Date().toISOString()
527
526
  };
528
- // 使用同步写入,确保立即完成(避免进程继续运行时文件未写入完成)
529
- require('fs').writeFileSync(deviceCodePath, JSON.stringify(data, null, 2), { mode: 0o600 });
527
+ await this.fs.writeFile(deviceCodePath, JSON.stringify(data, null, 2), 'utf8');
530
528
  } catch (err) {
531
529
  // 忽略错误
532
530
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "chaimi-keep-mcp",
3
- "version": "3.3.2-beta.0",
3
+ "version": "3.3.3-beta.0",
4
4
  "description": "柴米记账 MCP Server - 支持 Claude、Cursor、OpenClaw、WorkBuddy 等 AI 工具直接记账",
5
5
  "main": "server.js",
6
6
  "bin": {
@@ -44,6 +44,7 @@
44
44
  "license": "MIT",
45
45
  "dependencies": {
46
46
  "@modelcontextprotocol/sdk": "^1.0.0",
47
+ "chaimi-keep-mcp": "^3.3.2-beta.1",
47
48
  "dotenv": "^17.3.1",
48
49
  "node-fetch": "^2.7.0"
49
50
  },
@@ -56,25 +56,31 @@ updated: "2026-04-25"
56
56
 
57
57
  **步骤:**
58
58
 
59
- 1. **生成验证码**
59
+ 1. **启动授权流程**
60
60
  ```bash
61
- ./scripts/auth-flow.sh
61
+ mcporter auth 柴米记账
62
62
  ```
63
- 输出:
63
+
64
+ ```bash
65
+ chaimi-keep-mcp
66
+ ```
67
+
68
+ 2. **查看验证码**
69
+ 终端会显示:
64
70
  ```
65
- 🔐 柴米AI记账授权
71
+ 🔐 柴米记账授权
66
72
  ═══════════════════════════
67
73
  📱 验证码:GGCY-AC84
68
74
  ⏰ 有效期:5分钟
69
75
  ```
70
76
 
71
- 2. **小程序确认**
72
- - 打开"柴米AI记账"小程序
73
- - 点击"我的" → "Agent 授权"
77
+ 3. **小程序确认**
78
+ - 打开"柴米记账"小程序
79
+ - 点击"我的" → "AI 助手绑定"
74
80
  - 输入验证码
75
81
  - 点击确认
76
82
 
77
- 3. **完成授权**
83
+ 4. **完成授权**
78
84
  - Agent显示授权成功
79
85
  - 开始记账
80
86
 
@@ -83,14 +89,66 @@ updated: "2026-04-25"
83
89
  **场景:** Token过期、更换设备、安全考虑
84
90
 
85
91
  ```bash
86
- # 方式1:直接重新授权
87
- ./scripts/auth-flow.sh
92
+ # 重新授权
93
+ mcporter auth 柴米记账
88
94
 
89
- # 方式2:先撤销再授权
90
- ./scripts/revoke-auth.sh
91
- ./scripts/auth-flow.sh
95
+ # 强制清除缓存后重新授权
96
+ mcporter auth 柴米记账 --reset
92
97
  ```
93
98
 
99
+ **然后:**
100
+ 1. 查看终端显示的验证码
101
+ 2. 打开"柴米记账"小程序
102
+ 3. 进入"我的" → "AI 助手绑定"
103
+ 4. 输入验证码完成授权
104
+
105
+ ### 2.3 原生 MCP 客户端授权失败(Claude/Cursor)
106
+
107
+ **适用场景:**
108
+ - Claude Desktop
109
+ - Cursor
110
+ - Windsurf
111
+ - 其他原生支持 MCP 的客户端
112
+
113
+ **现象:**
114
+ ```
115
+ 错误:未找到有效授权信息
116
+
117
+ 错误:Token 已过期
118
+ ```
119
+
120
+ **解决方案(方式1 - 命令行):**
121
+ 1. 打开终端执行:
122
+ ```bash
123
+ chaimi-keep-mcp
124
+ ```
125
+
126
+ ```bash
127
+ mcporter auth 柴米记账
128
+ ```
129
+ 2. 查看终端显示的验证码
130
+ 3. 在小程序"我的"→"AI 助手绑定"中输入验证码
131
+ 4. 返回 Claude/Cursor 重新尝试记账
132
+
133
+ **解决方案(方式2 - 删除 Token 文件):**
134
+
135
+ **macOS/Linux:**
136
+ ```bash
137
+ rm ~/.mcporter/oauth-token.json
138
+ ```
139
+
140
+ **Windows:**
141
+ ```cmd
142
+ del %USERPROFILE%\.mcporter\oauth-token.json
143
+ ```
144
+
145
+ 然后完全退出并重新启动 Claude/Cursor
146
+
147
+ **解决方案(方式3 - 重启客户端):**
148
+ 1. 完全退出 Claude/Cursor
149
+ 2. 重新启动
150
+ 3. 尝试记账,会触发重新授权流程
151
+
94
152
  ---
95
153
 
96
154
  ## 三、Token管理
@@ -98,19 +156,24 @@ updated: "2026-04-25"
98
156
  ### 3.1 检查Token状态
99
157
 
100
158
  ```bash
101
- ./scripts/check-auth.sh
159
+ # 查看 Token 文件是否存在
160
+ cat ~/.mcporter/oauth-token.json
161
+
162
+ # 或尝试调用工具测试
163
+ mcporter call 柴米记账.get_skill
102
164
  ```
103
165
 
104
- **输出:**
166
+ **Token 文件位置:**
105
167
  ```
106
- ✅ 授权状态:有效
107
- 📅 Token有效期:还剩 23 小时
108
- 🔒 安全等级:高
168
+ ~/.mcporter/oauth-token.json
109
169
  ```
110
170
 
111
171
  ### 3.2 Token刷新
112
172
 
113
- Token将在过期前自动刷新,无需手动操作。
173
+ Token 过期后需要重新授权:
174
+ ```bash
175
+ mcporter auth 柴米记账
176
+ ```
114
177
 
115
178
  ---
116
179
 
@@ -128,7 +191,8 @@ Token将在过期前自动刷新,无需手动操作。
128
191
  ### 4.2 撤销授权
129
192
 
130
193
  ```bash
131
- ./scripts/revoke-auth.sh
194
+ # 强制清除缓存后重新授权
195
+ mcporter auth 柴米记账 --reset
132
196
  ```
133
197
 
134
198
  **场景:**
@@ -12,6 +12,9 @@ updated: "2026-04-25"
12
12
  ## 目录
13
13
 
14
14
  - [一、授权问题](#一授权问题)
15
+ - [1.1 未找到有效授权](#11-未找到有效授权)
16
+ - [1.2 授权过期](#12-授权过期)
17
+ - [1.3 验证码错误](#13-验证码错误)
15
18
  - [二、记账失败](#二记账失败)
16
19
  - [三、查询问题](#三查询问题)
17
20
  - [四、网络与连接](#四网络与连接)
@@ -35,9 +38,10 @@ updated: "2026-04-25"
35
38
  - 授权被撤销
36
39
 
37
40
  **解决方案:**
38
- 1. 运行 `./scripts/auth-flow.sh` 生成新验证码
39
- 2. 在小程序中完成授权流程
40
- 3. 重新尝试记账
41
+ 1. 执行 `mcporter auth 柴米记账`
42
+ 2. 查看终端显示的验证码
43
+ 3. 在小程序"我的"→"AI 助手绑定"中输入验证码
44
+ 4. 重新尝试记账
41
45
 
42
46
  ### 1.2 授权过期
43
47
 
@@ -52,9 +56,13 @@ updated: "2026-04-25"
52
56
  - 超过有效期未使用
53
57
 
54
58
  **解决方案:**
55
- 1. 运行 `./scripts/check-auth.sh` 检查状态
56
- 2. 如已过期,运行 `./scripts/auth-flow.sh` 重新授权
57
- 3. 或使用 `./scripts/revoke-auth.sh` 清除后重新授权
59
+ ```bash
60
+ # 重新授权
61
+ mcporter auth 柴米记账
62
+
63
+ # 或强制清除缓存后重新授权
64
+ mcporter auth 柴米记账 --reset
65
+ ```
58
66
 
59
67
  ### 1.3 验证码错误
60
68
 
@@ -68,10 +76,12 @@ updated: "2026-04-25"
68
76
  - 验证码超过5分钟有效期
69
77
 
70
78
  **解决方案:**
71
- 1. 重新生成验证码:`./scripts/auth-flow.sh`
72
- 2. 在5分钟内在小程序中输入
79
+ 1. 重新执行 `mcporter auth 柴米记账` 生成新验证码
80
+ 2. 在5分钟内在小程序"我的"→"AI 助手绑定"中输入
73
81
  3. 注意区分大小写
74
82
 
83
+ > **注意:** 使用 Claude/Cursor 等原生 MCP 客户端的用户,如遇授权问题,请参考 [authentication.md - 2.3 原生 MCP 客户端授权失败](authentication.md#23-原生-mcp-客户端授权失败claudecursor)
84
+
75
85
  ---
76
86
 
77
87
  ## 二、记账失败
@@ -188,7 +198,10 @@ updated: "2026-04-25"
188
198
  1. 检查网络连接
189
199
  2. 稍后重试
190
200
  3. 减少查询时间范围
191
- 4. 使用 `./scripts/verify-setup.sh` 测试连接
201
+ 4. 测试连接:
202
+ ```bash
203
+ chaimi-keep-mcp --version
204
+ ```
192
205
 
193
206
  ### 4.2 服务器错误
194
207
 
@@ -252,14 +265,15 @@ cat /mcp-server-local/references/response-templates.md
252
265
  ## 快速诊断命令
253
266
 
254
267
  ```bash
255
- # 检查授权状态
256
- ./scripts/check-auth.sh
268
+ # 检查版本和安装状态
269
+ chaimi-keep-mcp --version
257
270
 
258
- # 验证安装完整性
259
- ./scripts/verify-setup.sh
271
+ # 重新授权
272
+ mcporter auth 柴米记账
260
273
 
261
274
  # 测试记账连接
262
- curl -X POST $MCP_URL -H "Content-Type: application/json" \
275
+ curl -X POST https://cloud1-2gfe5jhjef06b85d-1412172089.ap-shanghai.app.tcloudbase.com/mcpHub-mcp \
276
+ -H "Content-Type: application/json" \
263
277
  -d '{"action":"get_skill"}'
264
278
  ```
265
279