coze-plugin-utils/.trae/project_rules.md

Comprehensive utility library for Coze plugins with multimedia processing, browser automation, cloud storage integration, and AI-powered video/audio generation capabilities

# Coze Plugin Utils 项目规范

## 🎯 项目概述

Coze Plugin Utils 是一个为 Coze 插件开发提供支持的工具函数库，提供各种实用功能以简化 Coze 插件开发。

## ⚙️ 技术栈配置

- 使用 **Node.js v18+**
- 编程语言为 **TypeScript**
- 输出格式为 **CommonJS（cjs）**
- 包管理工具使用 **pnpm**，禁止使用 npm/yarn
- 单元测试框架为 **Jest**
- 代码规范工具为 **ESLint + Prettier**
- 类型检查严格（启用 `strict`）

## 📦 项目结构

```bash
📁 src/                 # 核心源码
├── index.ts           # 模块入口
├── utils/             # 工具函数
├── media/             # 媒体处理相关
├── storage/           # 存储服务相关
├── types/             # 类型定义
📁 tests/              # 单元测试文件夹
.trae/
├── project_rules.md   # 项目规范
├── memory_bank/       # 项目记忆
```

## 📐 开发原则

- 所有函数模块必须使用 **明确的类型注解**
- 所有工具函数应配套测试用例（Jest）
- 所有模块必须支持 Tree-shaking（尽量使用纯函数）
- 函数/类注释需包含用途说明、参数定义和示例用法
- 严格遵循 ESLint + Prettier 风格
- 依赖安装必须使用 **pnpm**

## 🧪 单元测试规则

- 所有核心逻辑必须编写测试覆盖（建议 90% 覆盖率以上）
- 测试文件放在 `tests/` 目录下，与源码保持相同的目录结构
- 测试框架：Jest（支持 TypeScript）

## 🚫 严格禁止

- 禁止在任何地方使用 `npm` 或 `yarn`
- 禁止生成无类型注解的函数/类
- 禁止使用默认导出（保持命名导出）
- 禁止将测试代码混入生产模块（必须隔离）
- 禁止生成无注释、无文档说明的函数/类

## 📄 命名规范

- 文件名：使用小写字母，多个单词用点号分隔（例如：`aliyun.oss.ts`）
- 函数名：使用驼峰命名法（例如：`getGlobalConfig`）
- 接口名：使用大写 I 前缀 + 驼峰命名法（例如：`IGlobalConfig`）
- 常量名：使用全大写，多个单词用下划线分隔（例如：`DEFAULT_CONFIG`）

## 📝 注释规范

- 所有导出的函数、类、接口必须有 JSDoc 注释
- 注释必须包含功能描述、参数说明、返回值说明
- 复杂函数应该包含使用示例