聊天命令

配对（新用户）

/pair                                       请求配对（生成代码）
/pair-code ABC123                           输入配对代码
/unpair                                     移除你的配对

管理员命令

/pairing list                               列出待处理请求
/pairing approve <code>                     批准配对请求
/pairing reject <code>                      拒绝配对请求
/pairing users                              列出配对用户
/pairing remove <user>                      移除用户配对

信任管理

/trust <user> owner                         授予所有者信任
/trust <user> paired                        标准信任
/trust list                                列出信任级别

TypeScript API参考

创建配对服务

import { createPairingService } from 'clodds/pairing';

const pairing = createPairingService({
  // 代码设置
  codeLength: 8,
  codeExpiryMinutes: 60,
  maxPendingPerChannel: 3,

  // 自动批准设置
  autoApproveLocal: true,      // 自动批准localhost
  autoApproveTailscale: true,  // 自动批准Tailscale IP
  autoApproveOwners: true,     // 所有者自动批准他们的请求

  // 存储
  storage: 'sqlite',
  dbPath: './pairing.db',
});

创建配对请求

// 用户请求配对
const request = await pairing.createPairingRequest({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
  username: 'johndoe',
  displayName: 'John Doe',
});

console.log(`配对代码: ${request.code}`);
console.log(`过期时间: ${request.expiresAt}`);
console.log(`与管理员分享此代码以获得批准`);

验证代码

// 检查代码是否有效
const valid = await pairing.validateCode({
  code: 'ABC123XY',
});

if (valid) {
  console.log(`有效代码，用户: ${valid.username}`);
  console.log(`频道: ${valid.channelId}`);
}

批准请求

// 管理员批准配对
await pairing.approveRequest({
  code: 'ABC123XY',
  approvedBy: 'admin-user-id',
  trustLevel: 'paired',
});

拒绝请求

// 管理员拒绝配对
await pairing.rejectRequest({
  code: 'ABC123XY',
  rejectedBy: 'admin-user-id',
  reason: '未知用户',
});

检查配对状态

// 检查用户是否配对
const isPaired = await pairing.isPaired({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

if (isPaired) {
  console.log('用户已配对，可以使用Clodds');
}

获取信任级别

const trust = await pairing.getTrustLevel({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

console.log(`信任级别: ${trust}`);
// 'owner' | 'paired' | 'stranger'

// 检查特定权限
if (trust === 'owner') {
  console.log('完全管理员权限');
} else if (trust === 'paired') {
  console.log('标准交易权限');
} else {
  console.log('无权限 - 必须先配对');
}

列出待处理请求

const pending = await pairing.listPendingRequests({
  channelId: 'telegram-123',  // 可选：按频道过滤
});

for (const req of pending) {
  console.log(`代码: ${req.code}`);
  console.log(`用户: ${req.username} (${req.displayName})`);
  console.log(`请求时间: ${req.createdAt}`);
  console.log(`过期时间: ${req.expiresAt}`);
}

列出配对用户

const users = await pairing.listPairedUsers({
  channelId: 'telegram-123',  // 可选：按频道过滤
});

for (const user of users) {
  console.log(`${user.username}: ${user.trustLevel}`);
  console.log(`配对时间: ${user.pairedAt}`);
  console.log(`批准人: ${user.approvedBy}`);
}

检查所有者状态

const isOwner = await pairing.isOwner({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

if (isOwner) {
  console.log('用户具有所有者权限');
}

移除配对

// 移除用户的配对
await pairing.removePairing({
  channelId: 'telegram-123',
  userId: 'telegram-user-456',
});

信任级别

级别	访问权限
所有者	完全管理员：批准用户，管理设置，交易
配对	标准：交易，投资组合，查询
陌生人	无：必须先配对

配对代码格式

长度：8个字符
字符：大写字母+数字
排除：0, O, 1, I, L（避免混淆）
示例：ABC234XY

自动批准规则

条件	行为
本地主机	自动批准，赋予所有者信任
Tailscale IP	自动批准，赋予所有者信任
所有者请求	自动批准他们的其他频道

安全特性

特性	描述
代码过期	代码1小时后过期
速率限制	每个频道最多3个待处理
清晰代码	无易混淆字符
审计追踪	谁批准/拒绝，何时

CLI管理员命令

# 列出待处理配对请求
clodds pairing list telegram

# 批准请求
clodds pairing approve ABC234XY

# 列出配对用户
clodds pairing users telegram

# 直接添加用户（绕过代码）
clodds pairing add telegram user-123

# 移除用户
clodds pairing remove telegram user-123

最佳实践

安全分享代码 —— 不要在公共频道发布
适当设置过期时间 —— 对于敏感系统更短
定期审查待处理 —— 不要让请求堆积
谨慎使用所有者 —— 大多数用户只需要’配对’
定期审计 —— 审查谁有访问权限