财智记账 · AI-native 记账平台

caizhi-AGP v2.1

协议名称：caizhi-AGP (财智记账 Agent Guide Protocol)

版本：2.1

适用平台：财智记账 (caizhi.tongyueim.com)

适用对象：AI Agent / 调用财智 API 的程序

一、协议概述

1.1 协议目的

caizhi-AGP 是为 AI Agent 与财智记账平台 交互而制定的数据传输与行为规范文档。

核心目标：

1. 确保所有 Agent 在使用财智平台时遵循统一的操作流程
2. 保证数据准确性和操作规范性
3. 为 Agent 提供"零适配"接入体验

1.2 适用范围

• 所有通过 HTTP API 调用财智记账服务的 AI Agent
• 通过 MCP Server 调用的 AI Agent
• Agent 代表用户执行记账、查询、统计操作
• Agent 获取财务数据

1.3 基本原则

1. 操作前必查 - 任何写入操作前必须先查询相关数据
2. 严格计算 - 数据统计必须用程序计算，禁止在文字生成中"顺带"写数字
3. 数据准确 - 记录和转述财务数据需准确
4. 用户知情 - 操作需让用户确认
5. 隐私保护 - 不可泄露用户财务数据
6. 错误透明 - 问题需清晰反馈
7. 平台不存语义— 平台只做协议和数据，不做 LLM 解析

二、认证与身份

2.1 两种鉴权方式（并存）

优先级：财智服务端 优先看 X-API-Key，没有再看 JWT。

2.2 与同月平台账号的关系

• 财智记账与同月平台共用同一套用户体系
• 一个同月账号 = 一个财智账号 = 一套数据
• 关键标识：tongyueNo（数字（如 <tongyueNo>））
• 财智只认 tongyueNo，不认 UUID

2.3 JWT 登录

POST /api/auth/login

请求：

{
  "user_id": "<tongyueNo>",
  "password": "<your_password>"
}

响应（成功）：

{
  "success": true,
  "token": "<jwt_token>",
  "user": {
    "id": "<tongyueNo>",
    "name": "<your_name>"
  }
}

Token Payload：

{
  "user_id": "<tongyueNo>",
  "tongyue_user_id": <tongyueNo>,
  "iat": <issued_at_timestamp>,
  "exp": <expires_at_timestamp>
}

后续请求：

Authorization: Bearer <jwt_token>

2.4 API Key 申请 ⭐

核心流程：

用户 → 同月平台申请 → 拿到 API Key → 配置到 Agent → Agent 调财智 API
         (X-API-Key)

API Key 特性：

• 一次性显示：申请时返回明文 secret，只显示一次
• 前缀：sk-caizhi- （类似 OpenAI 的 sk-）
• 存储：同月数据库存 key_hash（SHA256），不存明文
• 作用域：MVP 默认全权限，预留 scopes 字段
• 可撤销：用户可主动 revoke
• 可观测：记录 last_used_at

申请流程：

1. 用户登录同月平台
2. 进入 "Agent 集成" 页面
3. 点 "为我的 Claude 申请 API Key"
4. 输入 Key 名称（如 "我的 Claude Desktop"）
5. 同月生成 secret：sk-caizhi-AbCdEf123...
6. 用户立即复制保存（刷新后不再显示明文）
7. 用户把 secret 配到 Agent 的 MCP 配置

API Key 调财智：

POST https://caizhi.tongyueim.com/api/v1/expenses/create
Headers:
  X-API-Key: sk-caizhi-AbCdEf123...
  Content-Type: application/json
Body:
  {
    "category_id": 11,
    "amount": 27.40,
    "payment_method": "zfb",
    "date": "2026-06-05"
  }

财智服务端处理：

收到 X-API-Key
  ↓
调同月 /api/agent-key/verify
  ↓
拿到 tongyueNo = <your-tongyueNo>
  ↓
挂到 req.user.id
  ↓
正常业务处理

4 个 API Key 接口（同月平台）：

2.5 鉴权失败处理

三、类别体系

（此章节未变动）

3.1 三层结构

⚠️ Agent 必须选择第三层（细项）类别，不能选择大类。

3.2 类别映射表

Agent 提示：使用 category_id 数字（不要传中文名）。

四、操作规范

4.1 记账操作流程（init + create 两步）

第一步：POST /api/v1/expenses/init
  → 拿到 categories 列表、字段要求、submit_endpoint

第二步：分析 init 响应，选择 category_id

第三步：POST {submit_endpoint} 提交数据

为什么需要 init：

• 拿到最新的类别表（避免硬编码过期）
• 拿到字段要求（payment_method 哪些可选）
• 拿到submit_endpoint（避免猜错地址）

为什么不跳过 init：

• 类别 ID 可能新增/废弃
• 直接硬编码会出错
• init 是"动态发现"的保证

4.2 MCP Server 调用

MCP Server 是首选调用方式，比直接 HTTP 更友好。

配置示例

Claude Desktop 配置（claude_desktop_config.json）：

{
  "mcpServers": {
    "caizhi": {
      "command": "npx",
      "args": ["-y", "caizhi-mcp-server"],
      "env": {
        "CAIZHI_API_KEY": "sk-caizhi-你的key",
        "CAIZHI_BASE": "https://mcp.caizhi.tongyueim.com"
      }
    }
  }
}

stdio 模式：本地运行，不走公网流量

SSE 模式：公网 endpoint，零配置

五、MCP Tool Schemas

这是 LLM 真正"看到"的部分。tool description 已经内嵌 AGP 关键规则。

5.1 list_categories

作用：获取所有支出/收入类别（Agent 自动发现用）

Tool Schema：

{
  name: "list_categories",
  description: `
    获取财智记账的所有支出/收入类别列表。
    
    【AGP 协议 v2 关键规则】
    - 必须返回细项类别（不是大类）
    - type 参数必填：'expense' 或 'income'
    - 返回的 category_id 是数字，记账时直接用
    
    使用场景：Agent 第一次记账前调用，确认类别 ID
  `,
  inputSchema: {
    type: "object",
    properties: {
      type: { 
        type: "string", 
        enum: ["expense", "income"],
        description: "类别类型：expense=支出，income=收入"
      }
    },
    required: ["type"]
  }
}

返回：

{
  "success": true,
  "categories": [
    { "id": 11, "name": "打车", "parent_name": "出行", "icon": "🚕" },
    { "id": 12, "name": "地铁", "parent_name": "出行", "icon": "🚇" },
    ...
  ]
}

5.2 record_expense

作用：记一笔支出（最常用）

Tool Schema：

{
  name: "record_expense",
  description: `
    记一笔支出到财智记账。
    
    【AGP 协议 v2 关键规则 - 必读】
    - category_id 必须是【细项类别】的 ID（如 11=打车, 16=早餐）
    - 不是大类 ID（不能用 1, 2 这种）
    - 不确定时，先调用 list_categories 查
    
    【字段规范】
    - category_id: 整数（细项）
    - amount: 数字，保留 2 位小数
    - payment_method: 'wx' | 'zfb' | 'card' | 'cash' 之一
      · wx = 微信支付
      · zfb = 支付宝
      · card = 银行卡
      · cash = 现金
    - date: YYYY-MM-DD 格式
    - note: 备注（可选）
    
    【使用流程】
    1. 如不知 category_id，先调 list_categories
    2. 调 init 拿最新字段要求（可选）
    3. 调本接口提交
    
    成功返回：{ success: true, data: { id, amount, ... } }
  `,
  inputSchema: {
    type: "object",
    properties: {
      category_id: { 
        type: "integer",
        description: "细项类别ID（必填）"
      },
      amount: { 
        type: "number",
        description: "金额（必填，2位小数）"
      },
      payment_method: { 
        type: "string", 
        enum: ["wx", "zfb", "card", "cash"],
        description: "支付方式（必填）"
      },
      date: { 
        type: "string",
        description: "日期 YYYY-MM-DD（必填）"
      },
      note: { 
        type: "string",
        description: "备注（可选）"
      }
    },
    required: ["category_id", "amount", "payment_method", "date"]
  }
}

5.3 record_income

（同 record_expense，type=income）

5.4 get_balance

作用：查询当前余额

Tool Schema：

{
  name: "get_balance",
  description: `
    查询当前用户的总余额。
    
    【AGP 协议 v2】
    - 返回 snapshot_balance（5月底快照）+
            this_month_income（本月收入）-
            this_month_expenses（本月支出）
    - 单位：元，2 位小数
    
    使用场景：用户问"我还有多少钱"
  `,
  inputSchema: {
    type: "object",
    properties: {}
  }
}

六、字段规范

支付方式映射（必填，不能传中文）：

• 微信支付 → wx
• 支付宝 → zfb
• 银行卡 → card
• 现金 → cash

七、错误处理（Agent 友好）

7.1 错误响应格式

{
  "success": false,
  "error_code": "STANDARD_CODE",
  "error": "人类可读描述",
  "hint": "Agent 可读的修复建议",
  "docs_url": "https://docs.caizhi.tongyueim.com/errors/CODE"
}

7.2 标准错误码（Agent 友好版）

7.3 错误转述模板

八、永久记忆内容（Agent 必须记住）

Agent 启动时把以下内容注入到自己的 MEMORY.md：

# 财智记账 AGP v2 必记规则

1. **鉴权**：
   - 优先用 X-API-Key（Agent 场景）
   - 用户登录用 Authorization: Bearer JWT

2. **记账流程**：
   - 第一步：POST /api/v1/expenses/init（拿最新类别和字段）
   - 第二步：POST /api/v1/expenses/create（提交数据）
   - 不能跳过 init

3. **类别规则**：
   - category_id 必须是【细项】ID（如 11=打车）
   - 不能用大类 ID（1=出行）
   - 不确定时调 list_categories

4. **字段规范**：
   - date: YYYY-MM-DD
   - amount: 数字，2位小数
   - payment_method: wx/zfb/card/cash（不能传中文）

5. **错误处理**：
   - 看到 error_code 字段（不是 error 字符串）
   - 用 hint 字段指导用户

6. **MCP 优先**：
   - 优先用 MCP Server 接入（标准化）
   - LLM 看到的 tool description 已含 AGP 规则

九、API 接口完整参考

9.1 认证

9.2 支出

9.3 收入

9.4 类别

9.5 余额

十、MCP Server 集成（已部署）⭐

10.1 官方 MCP Server（推荐使用）

财智记账提供官方 MCP Server（caizhi-mcp-server），让 Claude Desktop / Cursor / Cline / Continue 等任何支持 MCP 协议的 AI 客户端能以调用本地函数的方式调财智 API。

• 本项目位置：D:\OpenClawData\.openclaw\workspace\caizhi-mcp-server\
• 服务器位置：/home/admin/caizhi-mcp-server/
• 零依赖 — 纯 Node.js 18+ 原生 fetch
• 协议 — JSON-RPC 2.0 over stdio

10.2 工具清单（7 个）

10.3 端到端流程

用户: "记一笔打车27.4元"
  ↓
Claude Desktop (LLM)
  ↓ 看到 tool schema（来自 MCP tools/list）
  ↓ 推理出 {category_id: 11, amount: 27.4, payment_method: "zfb"}
  ↓
MCP Server (caizhi-mcp-server)
  ↓ 调财智 API，带 X-API-Key: sk-caizhi-xxx
  ↓
财智 API
  ↓ X-API-Key → 调同月 verify → 拿 tongyueNo=<your-tongyueNo>
  ↓ INSERT INTO expenses
  ↓
返回 {success: true, id: 119}
  ↓
LLM: "已记录：打车 27.40 元"

10.4 部署模式

当前推荐：用 stdio 模式。Agent 通过 MCP client 启动 stdio 进程，无需服务器暴露端口。

10.5 Claude Desktop 配置示例（stdio 模式）

{
  "mcpServers": {
    "caizhi": {
      "command": "node",
      "args": ["D:/OpenClawData/.openclaw/workspace/caizhi-mcp-server/src/index.js"],
      "env": {
        "CAIZHI_API_KEY": "sk-caizhi-你的key"
      }
    }
  }
}

获取 API Key：

# 1) 登录同月平台
curl -X POST https://www.tongyueim.com/api/users/login \
  -H "Content-Type: application/json" \
  -d '{"login":"<邮箱>","password":"<密码>"}'

# 2) 用 JWT 申请 Key
curl -X POST https://www.tongyueim.com/api/agent-key/apply \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name":"我的 Claude Desktop"}'
# 响应里的 secret 就是 sk-caizhi-xxxxx（只显示一次，妥善保存）

10.6 安全设计

1. API Key 永不明文返 — agent-key/list 只返 prefix
2. 错误码完整 — 业务错误返 isError: true + code + hint 让 Agent 自我纠错
3. 并发请求 — 多个工具调用并行不阻塞
4. Buffer 10MB 上限 — 防 DoS
5. SIGTERM 优雅退出 — 等 in-flight 请求最多 3 秒

十一、AGP 协议自身获取（B 方案）⭐⭐

11.1 问题

财智 AGP 文档本身 14,595 字符。如果在每次登录或每次 Agent 启动都把全文作为 prompt 注入，会浪费~10K token（中文为主）。

11.2 解决方案（B 方案）

B 方案 = 被动元数据 + 主动拉取 + ETag 缓存（类似 HTTP 缓存标准）：

1. 登录响应只返 AGP 元数据（约 100 字节），不返 content
2. Agent 决策是否需要拉取
3. 主动拉取走标准 HTTP 缓存：

• 首次 GET /api/v1/agp → 200 + 完整 content + ETag header
• 后续 GET + If-None-Match: "<etag>" → 304 Not Modified（0 字节 body）

1. 元数据快速校验走 ?format=metadata（仅返元数据，<300 字符）

11.3 三种接入方式对比

11.4 完整示例

Step 1：Agent 首次登录

POST /api/auth/login
→ 200 OK
{
  "token": "eyJ...",
  "user": {...},
  "AGP": {
    "url": "https://caizhi.tongyueim.com/api/v1/agp",
    "version": "2.1",
    "checksum": "sha256:9f89f6a99de71...",
    "content_length": 14595
  }
}

Step 2：Agent 主动拉取（如需）

GET /api/v1/agp
→ 200 OK
ETag: "9f89f6a99de719fe870d3da350c94712d438896d82fe80cf1faa8a14e13aed0f"
{
  "data": {
    "filename": "caizhi-AGP-v2.md",
    "version": "2.1",
    "content": "... 14,595 字符完整 AGP ...",
    "checksum": "sha256:9f89f6a99de71..."
  }
}

Step 3：Agent 后续拉取（带 ETag）

GET /api/v1/agp
If-None-Match: "9f89f6a99de71..."
→ 304 Not Modified
（无 body）

Step 4：AGP 更新后（自动拿到新内容）

GET /api/v1/agp
If-None-Match: "旧 etag"
→ 200 OK + 新 content + 新 ETag

11.5 为什么选 B 方案

B 方案的优势：

• 完全符合 HTTP 缓存标准（OpenID Connect Discovery、JSON Schema Registry 都是这么做）
• 零状态（不需要 DB 字段记录"用户是否拿过"）
• Agent 决策（Agent 拿到元数据后自己决定要不要拉）
• 代价最小（登录响应只多 ~100 字节）

11.6 字段含义

11.7 与同月 AGP 的协同

• 同月 AGP：登录时同月返回自己的 AGP 元数据
• 财智 AGP：登录时财智返回自己的 AGP 元数据
• Agent 同时拿到两个 URL，独立决定是否需要 fetch

11.8 与 MCP Server 的关系

• AGP 文档定义了接口规范（HTTP REST）
• MCP Server 是 AGP 的 LLM-friendly 包装（JSON Schema 工具定义）
• 两者互补不冲突：Agent 既可走 MCP（推荐），也可直接读 AGP 调 HTTP

十二、版本历史

附录 A：完整类别 ID 速查表

本文档由财智记账平台制定，解释权归财智记账平台所有。