用途:这是 Tether Wallet Development Kit(WDK)的代码行为准则,对所有贡献者(包括 AI 编程助手)具有约束力,适用于 WDK 的 wallets、protocols、core 等所有模块的编写、修改与审查。规则与具体仓库无关,任何模块都不是“黄金参考”;若现有代码与规则冲突,应改代码而非改规则。审查时须逐条指出违规并引用规则 ID,提出具体修复方案。
主要能力与规则要点: 项目与流程(P)——P001 每个 Pull Request 只应包含单个原子功能,公共 API 类的每个公共方法视为一个原子功能,可在保持 PR 小而快审的前提下酌情合并若干小功能;P002 先设计后实现,改动公共 API 或新模块前须先写技术规格文档并达成共识,规格只描述公共 API 组件、对每个新公共组件给出完整技术参考(含类型与描述),可选记录设计理由。 代码(C)——C001 避免代码坏味道(如魔法数字、重复代码、长方法、大类、依恋情结),魔法数字应提取为具名常量;C002 不得违反 S.O.L.I.D. 五原则,例如为覆写方法添加更严格的后置条件会破坏里氏替换;C003 所有公共与受保护组件需有恰当文档与类型,@protected 也属公共 API;C004 属性与方法使用最窄的合适类型,未知类型优先 unknown 而非 any,任意用户数据用 Record<string, unknown> 而非 Object;C005 避免防御式编程,参数类型由生成的 .d.ts 与消费者类型检查器保证,不要对已类型化参数做运行时判空或类型检查;C006 方法可能抛出的每个错误都须用 @throws 标注错误类型与触发条件。 测试(T)——T001 遵循 Arrange → Act → Assert 结构,前置/后置钩子属 Arrange;T002 只测试公共 API 组件,不直接测试 _ 前缀私有成员,通过公共 API 间接覆盖受保护与私有代码;T003 断言真实期望值而非模式或形状匹配;T004 jest 函数应在测试套件顶层定义与赋值,因使用 ESM 通常需 jest 的 unstable_mockModule,桩的返回值只在 before 钩子或各测试用例中设置,断言步骤须验证每个桩以正确参数被调用;T005 单测必须 mock 所有与外部服务(网络、区块链节点、I/O)交互的依赖组件,真实集成由集成测试覆盖。
使用方式:在提交或审查 WDK 代码前逐条对照规则;提供合规检查清单(PR 单一原子功能、有共识规格文档、无坏味道、无 S.O.L.I.D. 违规、公共与受保护组件文档类型齐全、使用最窄类型、无冗余防御检查、可抛错误均已 @throws、测试遵循 AAA、只测公共 API、断言真实值等)。相关技能 wdk-review-jsdocs、wdk-review-dts 深入执行 C003/C004 的 JSDoc 与 .d.ts 约定,wdk-review-tests 深入执行 T 组规则。
限制:官方文本中尚未提供文档模板(仍在编写中),仅建议参考 wdk-protocol-swap-aori-evm 的规格作为示例;资料未说明收费、授权方式或具体执行工具,这些暂未提供。