vendor-implementation

使用此技能当需要：

• 为新交易所创建供应商实现
• 设计微服务架构和 API 集成
• 实现交易系统核心功能（账户、订单、市场数据）
• 遵循 Yuan 框架规范和最佳实践

简洁至上

上下文窗口是公共资源。技能与系统提示、对话历史、其他技能的元数据和用户请求共享上下文。

默认假设：Claude 已经很智能。只添加 Claude 不具备的上下文。对每条信息进行挑战："Claude 真的需要这个解释吗？"，"这个段落是否值得其令牌成本？"

优先使用简洁示例而非冗长解释。

设置适当的自由度

将特异性级别与任务的脆弱性和可变性匹配：

高自由度（文本指令）：当多种方法都有效、决策依赖上下文，或启发式指导方法时使用。

中等自由度（伪代码或带参数的脚本）：当存在首选模式、某些变化可接受，或配置影响行为时使用。

低自由度（特定脚本，少数参数）：当操作易错、一致性至关重要，或必须遵循特定序列时使用。

```

apps/vendor-{exchange}/src/

├── api/ # API层

│ ├── client.ts # HTTP客户端设置

│ ├── public-api.ts # 公共API端点

│ ├── private-api.ts # 私有API端点

│ └── types.ts # TypeScript类型定义

├── services/ # 服务层

│ ├── accounts/ # 账户服务

│ │ └── perp.ts # 永续账户信息

│ ├── orders/ # 订单管理

│ │ ├── submitOrder.ts # 订单提交

│ │ ├── cancelOrder.ts # 订单取消

│ │ ├── modifyOrder.ts # 订单修改

│ │ └── listOrders.ts # 订单列表

│ ├── markets/ # 市场数据

│ │ ├── quote.ts # 实时报价

│ │ ├── product.ts # 产品信息

│ │ ├── ohlc.ts # K线数据

│ │ └── interest-rate.ts # 利率数据

│ ├── account-actions-with-credential.ts # 账户RPC

│ ├── order-actions-with-credential.ts # 订单RPC

│ └── fill-history.ts # 成交记录（如果支持）

├── utils.ts # 工具函数

├── sign.ts # 请求签名

├── index.ts # 主入口

├── cli.ts # CLI入口

├── AGENTS.md # Agent文档

├── SESSION_NOTES.md # 会话记录

└── package.json # 依赖

```

缓存模式（使用 createCache）

```typescript

import { createCache } from '@yuants/cache';

const CACHE_TTL = 60_000;

const metaCache = createCache>(

async () => {

console.info([${formatTime(Date.now())}] 刷新交易所元数据缓存);

const data = await fetchExchangeMetadata();

return processData(data);

},

{ expire: CACHE_TTL },

);

export const getAssetInfo = async (symbol: string) => {

const cache = await metaCache.query('meta');

return cache.get(symbol);

};

```

服务注册模式

```typescript

export const submitOrder = async (credential: ICredential, order: IOrder) => {

console.info([${formatTime(Date.now())}] 提交订单: ${order.product_id});

try {

const payload = buildOrderPayload(order);

const result = await placeOrder(credential, payload);

if (!result.status || result.status !== 'ok') {

throw new Error(订单提交失败: ${result.error});

}

const orderId = extractOrderId(result);

console.info([${formatTime(Date.now())] 订单提交成功: ${orderId});

return { order_id: ${orderId} };

} catch (error) {

const errorMessage = error instanceof Error ? error.message : '未知错误';

console.error([${formatTime(Date.now())}] 订单提交失败: ${errorMessage});

throw new Error(订单提交失败: ${errorMessage});

}

};

```

RPC 注册模式

```typescript

import { provideOrderActionsWithCredential } from '@yuants/data-order';

provideOrderActionsWithCredential(

Terminal.fromNodeEnv(),

'EXCHANGE',

{

type: 'object',

required: ['private_key', 'address'],

properties: {

private_key: { type: 'string' },

address: { type: 'string' },

},

},

{

submitOrder,

cancelOrder,

modifyOrder,

listOrders,

},

);

```

✅ 必需核心功能

1. 账户信息

- [ ] 现货账户余额和持仓

- [ ] 永续账户保证金和持仓

- [ ] 多账户类型支持

1. 订单管理

- [ ] 订单提交（市价/限价）

- [ ] 订单取消

- [ ] 订单修改（如果支持）

- [ ] 待成交订单列表

1. 市场数据

- [ ] 实时报价

- [ ] K 线数据

- [ ] 产品信息

- [ ] 利率数据（如适用）

1. API 集成

- [ ] 公共 API 端点

- [ ] 带认证的私有 API

- [ ] 错误处理和重试逻辑

🎯 高级功能

1. 交易历史

- [ ] 成交记录实现

- [ ] 交易记录

1. 转账支持

- [ ] 内部转账

- [ ] 提现

- [ ] 充值地址

代码质量

• ✅ TypeScript 严格模式
• ✅ 全面的错误处理
• ✅ 单元测试覆盖
• ✅ 集成测试验证

性能

• ✅ createCache高效缓存
• ✅ API 速率限制
• ✅ 批量操作优化

文档

• ✅ AGENTS.md 实现细节
• ✅ SESSION_NOTES.md 变更跟踪
• ✅ API 文档集成
• ✅ 完整 README

学习这些示例

1. Hyperliquid: 原生 modify order API + 完整功能集
2. Aster: 清晰结构 + 现货/永续分离
3. OKX: 综合功能 + 转账支持

关键学习点

1. 目录结构: vendor-aster 的可扩展模式
2. 缓存策略: createCache vs 手动管理
3. 错误处理: 跨服务的一致模式
4. 类型安全: 完整 TypeScript 接口
5. 文档维护: AGENTS.md + SESSION_NOTES.md

1. 使用原生 API

优先使用交易所的原生 API 而非模拟方案：

• 使用 modify order 而非 cancel + place new
• 保持订单优先级，减少 API 调用

2. 日志标准

```typescript

console.info([${formatTime(Date.now())] 操作成功);

console.error([${formatTime(Date.now())] 操作失败: ${error.message});

```

3. 类型安全

```typescript

interface IExchangeResponse {

status: string;

data?: any;

error?: string;

}

function validateResponse(response: IExchangeResponse): T {

if (response.status !== 'ok') {

throw new Error(response.error || 'API调用失败');

}

return response.data as T;

}

```

4. 文档维护

SESSION_NOTES.md 记录每次重要变更，包括：

• 技术决策 (D1, D2, ...)
• 架构变更
• 错误解决记录
• TODO 和风险项

1. API 限制 - 始终检查官方文档
2. 速率限制 - 实现适当节流
3. 认证安全 - 绝不在代码中硬编码密钥
4. 数据一致性 - 处理部分失败场景
5. 测试依赖 - 正确模拟外部服务

成功的供应商实现应该：

1. ✅ 通过所有集成测试
2. ✅ 优雅处理 API 限制
3. ✅ 提供一致的错误消息
4. ✅ 支持所有必需 RPC 方法
5. ✅ 包含全面文档
6. ✅ 遵循既定编码模式
7. ✅ 可维护和可扩展

• 工作流模式: references/workflows.md
• 输出模式: references/output-patterns.md
• 错误处理: references/error-handling.md

---

_基于 Hyperliquid、Aster、OKX 供应商实现经验生成_