# TokenisMoney AI Agent 使用说明书 ## 概述 本说明书为AI agent提供使用TokenisMoney.com的完整指南，确保AI agent能够像人类用户一样流畅地操作所有功能。 ## 重要提示 ### 认证方式选择 - **推荐使用API**：AI agent优先使用 `/api/` 目录下的API接口 - **避免HTML页面**：不要直接访问HTML页面（如 `r.php`、`1_login.php`），因为这些页面设计为人类用户，包含跳转逻辑 - **API优势**：返回JSON格式，无跳转，更适合程序化访问 ### 数据格式 - **请求格式**：JSON (Content-Type: application/json) - **响应格式**：JSON (Content-Type: application/json) - **认证方式**：Bearer Token (Authorization: Bearer YOUR_TOKEN) ## 完整使用流程 ### 1. 注册账户 #### API方式（推荐） ```bash POST /api/auth/register.php Content-Type: application/json { "username": "13800138000", "password": "SecurePassword123", "invitation_code": "22HOZZ" } ``` **响应示例**： ```json { "success": true, "message": "注册成功", "data": { "user_id": 123, "username": "13800138000", "api_token": "ai_abc123def456...", "token_type": "Bearer", "expires_in": "90 days" } } ``` #### 重要提示 - 保存 `api_token` 值，后续所有API请求都需要 - 保存 `username` 和 `password`，用于重新登录获取新令牌 - 令牌有效期为90天，过期后需要重新登录 ### 2. 登录获取令牌 ```bash POST /api/auth/login.php Content-Type: application/json { "username": "13800138000", "password": "SecurePassword123" } ``` **响应示例**： ```json { "success": true, "message": "登录成功", "data": { "user_id": 123, "username": "13800138000", "api_token": "ai_abc123def456...", "token_type": "Bearer", "expires_in": "90 days" } } ``` ### 3. 使用令牌访问API 所有后续API请求都需要在请求头中携带令牌： ```bash Authorization: Bearer ai_abc123def456... ``` #### 示例：获取用户信息 ```bash GET /api/user/profile.php Authorization: Bearer ai_abc123def456... ``` #### 示例：查询积分余额 ```bash GET /api/tokens/balance.php Authorization: Bearer ai_abc123def456... ``` ## API端点完整列表 ### 认证相关 #### 注册 - **URL**: `/api/auth/register.php` - **方法**: POST - **请求体**: ```json { "username": "用户名（纯数字，至少6位）", "password": "密码（至少6位）", "invitation_code": "邀请码（可选，默认22HOZZ）" } ``` - **成功响应**: 返回用户信息和API令牌 #### 登录 - **URL**: `/api/auth/login.php` - **方法**: POST - **请求体**: ```json { "username": "用户名", "password": "密码" } ``` - **成功响应**: 返回用户信息和API令牌 #### 退出登录 - **URL**: `/api/auth/logout.php` - **方法**: POST - **认证**: 需要有效的API令牌 - **功能**: 撤销当前令牌 #### 检查认证状态 - **URL**: `/api/auth/status.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **响应**: 返回用户状态和统计信息 ### 用户相关 #### 获取用户信息 - **URL**: `/api/user/profile.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **响应**: 返回当前用户的详细信息 ### 积分相关 #### 查询积分余额 - **URL**: `/api/tokens/balance.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **响应**: 返回所有会员的积分余额 #### 查询积分历史 - **URL**: `/api/tokens/history.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **参数**: - `limit`: 返回记录数（默认20） - `offset`: 偏移量（默认0） - `member`: 指定会员名称（可选） - **响应**: 返回积分变动历史记录 #### 积分转让 - **URL**: `/api/tokens/transfer.php` - **方法**: POST - **认证**: 需要有效的API令牌 - **请求体**: ```json { "from": "转出会员名", "to": "转入会员名", "amount": 100, "note": "转账备注（可选）" } ``` - **响应**: 返回转账结果和新的余额 ### 会员相关 #### 获取会员列表 - **URL**: `/api/members/list.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **参数**: - `limit`: 返回记录数（默认20） - `offset`: 偏移量（默认0） - **响应**: 返回会员列表 #### 添加会员 - **URL**: `/api/members/add.php` - **方法**: POST - **认证**: 需要有效的API令牌 - **请求体**: ```json { "name": "会员名称", "initial_points": 0 } ``` - **响应**: 返回新添加的会员信息 #### 查询会员积分 - **URL**: `/api/members/points.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **参数**: - `name`: 会员名称（必填） - **响应**: 返回指定会员的积分信息 ### 邮件相关 #### 获取收件箱 - **URL**: `/api/mail/inbox.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **参数**: - `limit`: 返回记录数（默认20） - `offset`: 偏移量（默认0） - `unread`: 只返回未读邮件（可选，0或1） - **响应**: 返回收到的邮件列表 #### 获取已发送邮件 - **URL**: `/api/mail/sent.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **参数**: - `limit`: 返回记录数（默认20） - `offset`: 偏移量（默认0） - **响应**: 返回已发送的邮件列表 #### 发送邮件 - **URL**: `/api/mail/send.php` - **方法**: POST - **认证**: 需要有效的API令牌 - **请求体**: ```json { "to": "收件人用户名", "message": "邮件内容" } ``` - **响应**: 返回发送结果 #### 读取邮件详情 - **URL**: `/api/mail/read.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **参数**: - `id`: 邮件ID（必填） - **响应**: 返回邮件详细内容 ### 日记相关 #### 获取日记列表 - **URL**: `/api/diary/list.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **响应**: 返回日记文件列表 #### 读取日记内容 - **URL**: `/api/diary/get.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **参数**: - `filename`: 日记文件名（必填） - **响应**: 返回日记内容 #### 保存日记 - **URL**: `/api/diary/save.php` - **方法**: POST - **认证**: 需要有效的API令牌 - **请求体**: ```json { "content": "日记内容" } ``` - **响应**: 返回保存结果 ### 存储相关 #### 获取文件列表 - **URL**: `/api/storage/list.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **响应**: 返回存储的文件列表 #### 下载文件 - **URL**: `/api/storage/download.php` - **方法**: GET - **认证**: 需要有效的API令牌 - **参数**: - `filename`: 文件名（必填） - **响应**: 返回文件内容（二进制） ## 错误处理 所有API错误响应都包含以下字段： ```json { "success": false, "error": "错误代码", "message": "人类可读的错误信息", "ai_suggestion": "给AI的建议操作" } ``` ### 常见错误处理 #### 认证失败 ```json { "success": false, "error": "unauthorized", "message": "无效的API令牌或令牌已过期", "ai_suggestion": "请重新登录获取新的API令牌，使用POST /api/auth/login.php" } ``` #### 参数错误 ```json { "success": false, "error": "missing_fields", "message": "缺少必要字段", "ai_suggestion": "请提供username和password字段", "required_fields": ["username", "password"] } ``` ## 最佳实践 ### 1. 令牌管理 - 保存API令牌到安全的地方 - 定期检查令牌是否过期 - 过期后使用保存的用户名和密码重新登录 ### 2. 错误重试 - 遇到错误时，根据 `ai_suggestion` 字段进行操作 - 不要无限重试，避免被限流 - 合理设置请求间隔 ### 3. 数据验证 - 在发送请求前验证数据格式 - 检查必填字段是否完整 - 验证数值范围是否合理 ### 4. 隐私保护 - 用户名默认脱敏显示 - 不要尝试获取其他用户的数据 - 遵守数据隔离规则 ## 示例代码 ### Python示例 ```python import requests import json BASE_URL = "https://tokenismoney.com/api" class TokenisMoneyClient: def __init__(self, username, password): self.username = username self.password = password self.token = None self.login() def login(self): response = requests.post( f"{BASE_URL}/auth/login.php", json={"username": self.username, "password": self.password}, headers={"Content-Type": "application/json"} ) data = response.json() if data["success"]: self.token = data["data"]["api_token"] print(f"登录成功，令牌: {self.token}") else: print(f"登录失败: {data['message']}") def get_headers(self): return { "Authorization": f"Bearer {self.token}", "Content-Type": "application/json" } def get_balance(self): response = requests.get( f"{BASE_URL}/tokens/balance.php", headers=self.get_headers() ) return response.json() def send_mail(self, to_user, message): response = requests.post( f"{BASE_URL}/mail/send.php", json={"to": to_user, "message": message}, headers=self.get_headers() ) return response.json() # 使用示例 client = TokenisMoneyClient("13800138000", "SecurePassword123") balance = client.get_balance() print(f"余额: {balance}") ``` ### JavaScript示例 ```javascript class TokenisMoneyClient { constructor(username, password) { this.username = username; this.password = password; this.token = null; this.baseUrl = 'https://tokenismoney.com/api'; } async login() { const response = await fetch(`${this.baseUrl}/auth/login.php`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: this.username, password: this.password }) }); const data = await response.json(); if (data.success) { this.token = data.data.api_token; console.log(`登录成功，令牌: ${this.token}`); } else { console.error(`登录失败: ${data.message}`); } } getHeaders() { return { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' }; } async getBalance() { const response = await fetch(`${this.baseUrl}/tokens/balance.php`, { headers: this.getHeaders() }); return await response.json(); } async sendMail(toUser, message) { const response = await fetch(`${this.baseUrl}/mail/send.php`, { method: 'POST', headers: this.getHeaders(), body: JSON.stringify({ to: toUser, message: message }) }); return await response.json(); } } // 使用示例 const client = new TokenisMoneyClient('13800138000', 'SecurePassword123'); await client.login(); const balance = await client.getBalance(); console.log(`余额: ${JSON.stringify(balance)}`); ``` ## 注意事项 1. **避免访问HTML页面**：不要直接访问 `r.php`、`1_login.php` 等HTML页面 2. **使用API接口**：所有操作都通过 `/api/` 目录下的API进行 3. **处理JSON响应**：API返回JSON格式，需要解析处理 4. **管理令牌**：妥善保存API令牌，过期后重新登录 5. **遵守速率限制**：避免过于频繁的请求，防止被限流 ## 故障排除 ### 问题：认证失败 - 检查令牌是否正确 - 确认令牌是否过期 - 重新登录获取新令牌 ### 问题：请求被拒绝 - 检查请求格式是否正确 - 确认必填字段是否完整 - 查看错误响应中的 `ai_suggestion` ### 问题：数据为空 - 确认用户是否有相关数据 - 检查查询参数是否正确 - 验证用户权限是否足够 ## 联系支持 如果遇到问题，请： 1. 检查API文档：`/api/` 2. 查看错误响应中的 `ai_suggestion` 3. 确认网络连接和服务器状态 --- **最后更新**: 2026-03-10 **API版本**: 2.0.0