common-project-standard

项目规范技能

功能描述

提供项目结构、文档管理、代码忽略等方面的标准和最佳实践，帮助团队建立统一的项目规范。同时提供技能规范验证工具和开源技能包装机制。

何时使用

在以下情况调用此技能：

• 创建新项目时
• 维护现有项目时
• 需要制定项目规范时
• 需要验证技能规范性时
• 需要集成开源技能时

核心功能

• 技能管理：规范技能的创建和管理流程
• 文档管理：规范文档的编写和维护标准
• Git忽略：规范 .gitignore 文件的配置
• AI忽略：规范 AI 相关文件的忽略规则
• 项目结构：规范项目目录结构
• 技能安装：提供技能安装和配置指导
• 规范验证：验证技能是否符合标准格式
• 开源集成：支持开源技能的包装和切换

输入参数

输出格式

{
  "status": "SUCCESS",
  "projectType": "backend",
  "framework": "Spring Boot",
  "guidelines": {
    "skill": {...},
    "documentation": {...},
    "gitignore": {...},
    "aiIgnore": {...},
    "structure": {...},
    "installation": {...},
    "validation": {...},
    "openSourceIntegration": {...}
  }
}

---

1. 技能管理规范

1.1 技能目录结构

skills/
├── skill-name/           # 技能名称（小写连字符）
│   └── SKILL.md          # 技能定义文件（必填）

1.2 技能命名规范

1.3 SKILL.md 文档结构

---
name: "skill-name"
description: "技能描述，简要说明技能的核心价值和用途"
trigger: "触发条件，简洁描述技能何时被触发"
disable-when: "禁用条件，描述不适合使用此技能的场景"
category: "技能分类，如：backend/frontend/database/devops/ai"
tags: ["标签1", "标签2"]
requires: ["依赖技能1", "依赖技能2"]
---

# 技能名称

## 功能描述
## 触发条件
## 何时使用
## 何时不使用
## 核心功能
## 输入参数
## 输出格式
## 使用流程
## 调用示例
## 失败案例
## 最佳实践
## 配置要求
## 扩展指南

1.3.0 Frontmatter 元数据规范

Frontmatter 是技能的元数据定义区，用于描述技能的基本信息和属性：

Frontmatter 示例：

---
name: "common-spring-boot-init"
description: "快速创建 Spring Boot 项目结构，支持多种数据库和依赖配置"
trigger: "用户请求创建新的 Spring Boot 项目时"
disable-when: "项目已存在或非 Java 技术栈项目"
category: "backend"
tags: ["spring", "java", "backend", "project-init"]
requires: ["common-db-design"]
---

1.3.1 文档章节说明

1.3.2 触发条件规范

触发条件应明确以下内容：

1. 前置条件：使用技能前必须满足的条件
2. 环境要求：所需的软件、依赖、权限等
3. 数据准备：需要预先准备的数据或配置
4. 触发方式：技能被调用的方式（API、命令行、事件等）

示例格式：

## 触发条件

- **前置条件**：项目已初始化，具备基础目录结构
- **环境要求**：Java 21+, Maven 3.8+, Spring Boot 3.2+
- **数据准备**：配置文件 `application.yml` 已存在
- **触发方式**：API 调用 / 命令行执行 / 事件触发

1.3.3 何时不使用（禁用样例）

明确列出不适合使用此技能的场景：

示例格式：

## 何时不使用

- 当项目已使用其他 ORM 框架时，不建议使用此技能
- 简单的 CRUD 操作无需使用此技能
- 需要复杂事务管理的场景请使用其他方案

1.3.4 失败案例规范

记录常见的失败场景及解决方案：

示例格式：

## 失败案例

| 错误场景 | 错误信息 | 解决方案 |
|----------|----------|----------|
| 数据库连接失败 | `Connection refused` | 检查数据库服务是否启动 |
| 权限不足 | `Permission denied` | 确认用户有足够的文件权限 |
| 依赖缺失 | `ClassNotFoundException` | 检查 pom.xml 依赖配置 |

1.4 技能注册流程

1. 在 skills/ 目录下创建技能目录
2. 创建 SKILL.md 文件
3. 在 AGENTS.md 中添加技能说明
4. 在 SKILLS.md 中注册技能

---

2. 文档管理规范

2.1 文档目录结构

docs/
├── api/                  # API 文档
│   └── openapi.yaml
├── architecture/         # 架构文档
│   └── architecture.md
├── guides/               # 使用指南
│   └── getting-started.md
├── README.md             # 项目说明（根目录）
├── AGENTS.md             # 代理与技能架构（根目录）
└── SKILLS.md             # 技能清单（根目录）

2.2 文档命名规范

2.3 文档模板

README.md 模板

# 项目名称

## 项目简介
## 技术栈
## 快速开始
## 项目结构
## API 接口
## 开发指南
## 部署说明
## 贡献指南
## 许可证

SKILLS.md 模板

# 技能清单

## 个人定制技能

| 技能名称 | 描述 |
|----------|------|
| personal-backend-coding-standard | 后端编码规范技能 |
| personal-frontend-coding-standard | 前端编码规范技能 |
| personal-java-common | Java 通用工具技能 |
| personal-project-runner | 项目启动管理技能 |
| personal-doc-manager | 个人文档管理技能 |
| personal-solution-research | 方案调研技能 |
| personal-brief-style | 简洁风格技能 |

## 通用技能

| 技能名称 | 描述 |
|----------|------|
| common-project-standard | 项目规范技能 |
| common-contract-generation | 契约生成技能 |
| common-frontend-playwright-test | 前端Playwright测试技能 |
| common-backend-unit-test | 后端单元测试技能 |
| common-coding | 编码技能 |
| common-requirement-clarification | 需求澄清技能 |
| common-api-doc | API文档生成技能 |
| common-data-migration | 数据迁移技能 |
| common-db-design | 数据库设计技能 |
| common-dockerize | Docker容器化技能 |
| common-grill-me | Grill Me 深度质询技能 |
| common-spec-driven | Spec驱动规范技能 |
| common-spring-boot-init | Spring Boot项目初始化技能 |
| common-ui-design-spec | UI设计规范技能 |
| common-ui-mockup | UI原型图生成技能 |
| common-vue-init | Vue项目初始化技能 |

## 开源技能包装

| 技能名称 | 描述 | 底层实现 |
|----------|------|----------|
| os-ui-library | UI组件库技能 | 可配置（自研/Component-A/Component-B） |
| os-chat-model | 聊天模型技能 | 可配置（OpenAI/DeepSeek/Claude） |

AGENTS.md 模板

# 代理与技能架构

## 概述

本项目使用 Trae AI 技能系统，通过技能扩展项目能力。

## 技能目录

所有技能位于 `skills/` 目录下。

## 技能分类

### 个人定制技能
- personal-backend-coding-standard - 后端编码规范
- personal-frontend-coding-standard - 前端编码规范
- personal-java-common - Java 通用工具
- personal-project-runner - 项目启动管理
- personal-doc-manager - 个人文档管理
- personal-solution-research - 方案调研
- personal-brief-style - 简洁风格

### 通用技能
- common-project-standard - 项目规范
- common-contract-generation - 契约生成
- common-frontend-playwright-test - 前端测试
- common-backend-unit-test - 后端测试
- common-coding - 编码规范
- common-requirement-clarification - 需求澄清
- common-api-doc - API文档生成
- common-data-migration - 数据迁移
- common-db-design - 数据库设计
- common-dockerize - Docker容器化
- common-grill-me - Grill Me 深度质询
- common-spec-driven - Spec驱动规范
- common-spring-boot-init - Spring Boot初始化
- common-ui-design-spec - UI设计规范
- common-ui-mockup - UI原型图生成
- common-vue-init - Vue项目初始化

## 技能使用方式

### 1. 安装技能

使用项目根目录的 `install-skills.sh` 脚本安装技能：

```bash
# 安装所有技能
./install-skills.sh /path/to/project

# 安装指定技能
./install-skills.sh -s common-coding -s common-project-standard .

2. 注册技能

在 SKILLS.md 中注册技能，系统会自动加载。

3. 使用技能

在需要时调用相应的技能接口。

4. 验证技能规范

# 验证所有技能
./validate-skills.sh

# 验证指定技能
./validate-skills.sh -s common-coding

# 修复技能格式
./validate-skills.sh -f

### 2.4 文档编写规范

1. **语言**：统一使用中文
2. **格式**：使用 Markdown 格式
3. **标题**：使用 `#` 表示标题层级
4. **代码块**：使用三个反引号 + 语言标识
5. **链接**：使用绝对路径或相对路径

---

## 3. Git 忽略规范

### 3.1 .gitignore 文件位置

- 根目录：`.gitignore` - 全局忽略规则
- 模块目录：`module/.gitignore` - 模块特定规则

### 3.2 通用忽略规则

```gitignore
# 构建产物
target/
build/
dist/
*.class
*.jar
*.war

# IDE 文件
.idea/
.vscode/
.project
.classpath
.settings/

# 日志文件
*.log
logs/

# 配置文件
application-local.yml
application-local.properties
.env

# OS 文件
.DS_Store
Thumbs.db

# Maven
.mvn/
mvnw
mvnw.cmd

# Gradle
.gradle/
gradlew
gradlew.bat

3.3 后端项目忽略规则

# 数据库文件
*.db
*.sqlite

# JVM 相关
hs_err_pid*
replay_pid*

# Spring Boot
spring-shell.log

3.4 前端项目忽略规则

# Node.js
node_modules/
package-lock.json
yarn.lock

# 构建工具
.next/
.nuxt/
.svelte-kit/

# TypeScript
*.tsbuildinfo

---

4. AI 忽略规范

4.1 AI 相关文件识别

4.2 AI 忽略规则

# AI 模型文件
*.pt
*.pth
*.onnx
*.h5
*.bin
*.ckpt

# 数据集
data/
dataset/
datasets/

# 向量数据库
chroma/
pinecone/
qdrant/
weaviate/

# 缓存目录
.cache/
__pycache__/
.huggingface/
.tensorflow/

# 模型下载目录
models/
downloads/
checkpoints/

4.3 AI 配置文件管理

# API Key 文件
*.key
*.secret
api-keys.json

# 配置文件
config/secrets.yml
config/secrets.json

# 环境变量
.env.local
.env.production

---

5. Trae 忽略规范

5.1 .traeignore 文件位置

• 根目录：.traeignore - 全局 Trae 忽略规则

5.2 .traeignore 作用

.traeignore 文件用于指定 Trae AI 系统应忽略的文件和目录，这些文件不会被技能系统加载或处理。

5.3 .traeignore 标准配置

# 技能缓存目录
.cache/
.skills-cache/

# 技能临时文件
*.tmp
*.temp

# 技能索引文件
skills-index.json
skills-mapping.json

# 日志文件
*.log
logs/

# 测试文件
__tests__/
*.test.js
*.spec.js

# 编辑器文件
.vscode/
.idea/
*.swp
*.swo
*~

# 系统文件
.DS_Store
Thumbs.db

# 技能开发文件
dev/
examples/
samples/

# 技能模板文件
*.template
*.stub

# 技能打包文件
*.zip
*.tar.gz
*.tgz

# 依赖目录
node_modules/
vendor/

# 构建产物
dist/
build/

5.4 .traeignore 与 .gitignore 的区别

5.5 联合使用建议

项目根目录
├── .gitignore          # Git 版本控制忽略
├── .traeignore         # Trae 技能系统忽略
└── .trae/
    ├── skills/         # 技能目录（Git 追踪，Trae 加载）
    └── cache/          # 缓存目录（Git 忽略，Trae 忽略）

5.6 示例配置

项目根目录 .gitignore：

# Trae 缓存目录
.trae/cache/
.trae/.cache/

# Trae 临时文件
.trae/*.tmp

项目根目录 .traeignore：

# 忽略技能开发目录
dev/
examples/

# 忽略测试文件
__tests__/
*.test.js

# 忽略编辑器配置
.vscode/
.idea/

技能目录 .traeignore（可选）：

# 技能内部忽略规则
node_modules/
*.log

---

6. AI 编码标准

6.1 AGENTS.md 文档规范

AGENTS.md 是项目级 AI 编码助手的行为规范文档，定义 AI 在本项目中应该遵循的编码规范、禁止操作、上下文规则等。

6.1.1 AGENTS.md 结构

# AI 编码助手规范（AGENTS.md）

## 1. 项目上下文

### 1.1 项目概述
{项目名称、技术栈、主要功能}

### 1.2 架构说明
{整体架构、模块划分、关键技术点}

### 1.3 代码风格
{编码规范、命名约定、格式要求}

## 2. 编码规则

### 2.1 必须遵循
- {规则1}
- {规则2}

### 2.2 禁止操作
- {禁止1}
- {禁止2}

### 2.3 最佳实践
- {实践1}
- {实践2}

## 3. 技能使用指引

### 3.1 推荐技能
- {技能名称} - {使用场景}

### 3.2 技能组合
- {场景} → {技能1} → {技能2}

## 4. 工具配置

### 4.1 Linter/Formatter
{ESLint、Prettier、Checkstyle等配置}

### 4.2 测试框架
{测试框架选择、测试覆盖率要求}

## 5. 安全规范

### 5.1 敏感信息
{API Key、密码等敏感信息处理规则}

### 5.2 代码审查
{PR审查要求、安全检查清单}

6.1.2 AGENTS.md 示例

# AI 编码助手规范（AGENTS.md）

## 1. 项目上下文

### 1.1 项目概述
- 项目名称：xx-service
- 技术栈：Java 21, Spring Boot 3.2, MyBatis Plus
- 主要功能：订单管理、支付处理

### 1.2 架构说明
- 分层架构：Controller → Service → Repository
- 外部调用：统一通过 infra/client 层
- 配置管理：Spring Boot 配置 + 环境变量

### 1.3 代码风格
- 命名：驼峰命名法
- 格式：Google Java Style
- 注释：Javadoc 风格

## 2. 编码规则

### 2.1 必须遵循
- 所有外部调用必须放在 infra/client 层
- 使用 @Metric 注解进行埋点
- 统一使用 ThreadPoolUtils 获取线程池
- 参数校验使用 @Valid + ValidateUtils

### 2.2 禁止操作
- 禁止在 Controller 中写业务逻辑
- 禁止硬编码配置值
- 禁止使用 System.out.println
- 禁止直接操作数据库连接

### 2.3 最佳实践
- 优先使用枚举定义常量
- 使用 DTO 进行数据传输
- 异常统一处理，使用 BusinessException
- 日志使用 LogUtils，分级记录

## 3. 技能使用指引

### 3.1 推荐技能
- common-coding - 编码规范指导
- common-db-design - 数据库设计
- personal-java-common - Java 通用工具

### 3.2 技能组合
- 新建功能 → common-requirement-clarification → common-spec-driven → common-spring-boot-init

## 4. 工具配置

### 4.1 Linter/Formatter
- Checkstyle：google_checks.xml
- Spotless：Google Java Format

### 4.2 测试框架
- JUnit 5 + Mockito
- 测试覆盖率要求：≥80%

## 5. 安全规范

### 5.1 敏感信息
- API Key 存储在环境变量
- 配置文件中使用 ${ENV_VAR} 引用
- 禁止提交 .env 文件

### 5.2 代码审查
- PR 必须通过 CI 检查
- 必须有至少1个 reviewer
- 安全扫描必须通过

6.1.3 AGENTS.md 与 .cursorrules 对比

6.2 多 AI 工具忽略文件规范

为支持多种 AI 编码助手，项目应提供统一的忽略文件体系。

6.2.1 忽略文件矩阵

6.2.2 .cursorignore 标准配置

# 构建产物
target/
build/
dist/

# IDE 文件
.idea/
.vscode/

# 日志文件
*.log
logs/

# 配置文件
.env
application-local.yml

# 系统文件
.DS_Store
Thumbs.db

# 依赖目录
node_modules/

# AI 模型文件
*.pt
*.pth
*.onnx

# 数据集
data/
dataset/

# 缓存目录
.cache/
__pycache__/

6.2.3 .codeiumignore 标准配置

# Codeium 忽略规则
# 大文件（超过 1MB）
*.jar
*.war
*.zip
*.tar.gz

# 二进制文件
*.class
*.dll
*.so

# 日志文件
*.log

# 临时文件
*.tmp
*.temp

# 构建产物
target/
build/
dist/

# 依赖目录
node_modules/

# 缓存目录
.cache/

6.2.4 .aiderignore 标准配置

# Aider 忽略规则
# 大型二进制文件
*.jar
*.war
*.exe

# 构建目录
target/
build/
dist/

# 依赖目录
node_modules/

# 日志文件
*.log

# 配置文件
.env
application-local.yml

# IDE 文件
.idea/
.vscode/

# 系统文件
.DS_Store

6.2.5 .copilotignore 标准配置

# GitHub Copilot 忽略规则
# 敏感文件
.env
*.key
*.secret

# 构建产物
target/
build/
dist/

# 依赖目录
node_modules/

# 日志文件
*.log

# 测试报告
reports/
coverage/

# 临时文件
*.tmp
*.temp

6.2.6 统一忽略规则建议

为简化维护，建议在项目根目录创建统一的忽略规则文件：

项目根目录/
├── .gitignore              # Git 版本控制（最全）
├── .traeignore             # Trae 技能系统
├── .cursorignore           # Cursor AI
├── .codeiumignore          # Codeium AI
├── .aiderignore            # Aider AI
└── .copilotignore          # Copilot AI

统一规则策略：

1. .gitignore 作为主忽略文件，包含所有规则
2. 其他 AI 忽略文件引用 .gitignore 或仅包含特定规则

6.3 AI 辅助开发工作流标准

6.3.1 代码生成流程

需求澄清 → 方案设计 → 代码生成 → 规范验证 → 测试编写 → 代码审查
  ↓           ↓           ↓           ↓           ↓           ↓
grill-me   solution-    coding      code-      unit-test  code-review
           research                 review

6.3.2 AI 使用规则

6.3.3 AI 输出规范

1. 代码质量：生成的代码必须符合项目编码规范
2. 可维护性：代码结构清晰，注释完整
3. 安全性：不包含敏感信息，遵循安全规范
4. 测试覆盖：关键功能必须有单元测试
5. 文档配套：代码必须有相应的文档说明

---

7. 项目结构规范

7.1 后端项目结构

xx-parent/                     # Maven 父模块
├── pom.xml                    # 父 POM 配置
├── xx-gateway/               # 网关模块
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/bage/xx/gateway/
│       └── resources/
├── xx-biz/                   # 业务模块
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/bage/xx/biz/
│       └── resources/
├── xx-infra/                 # 基础设施模块
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/bage/xx/infra/
│       └── resources/
└── .trae/                    # 技能目录
    └── skills/

7.2 模块职责说明

7.3 包结构规范

com/bage/xx/
├── controller/          # REST API 控制层
├── service/             # 业务逻辑层
│   └── impl/           # 服务实现
├── repository/          # 数据访问层
├── entity/              # 数据库实体
├── dto/                 # 数据传输对象
│   ├── request/        # 请求 DTO
│   └── response/       # 响应 DTO
├── config/              # 配置类
├── exception/           # 自定义异常
└── util/                # 工具类

---

7. 技能安装与配置

7.1 安装方式

使用安装脚本（推荐）

# 从 skills 仓库安装到目标项目
bash <(curl -s https://raw.githubusercontent.com/your-repo/study-ai-skills/main/install-skills.sh) /path/to/your/project

# 或者克隆仓库后安装
git clone https://github.com/your-repo/study-ai-skills.git
cd study-ai-skills
./install-skills.sh /path/to/your/project

手动安装

# 创建技能目录
mkdir -p /path/to/your/project/.trae/skills

# 复制技能（以 common-project-standard 为例）
cp -r /path/to/study-ai-skills/skills/common-project-standard /path/to/your/project/skills/

7.2 安装脚本使用说明

# 查看帮助
./install-skills.sh -h

# 列出所有可用技能
./install-skills.sh -l

# 安装所有技能到当前目录
./install-skills.sh .

# 安装所有技能到指定目录
./install-skills.sh /path/to/project

# 安装指定技能
./install-skills.sh -s common-coding -s personal-backend-coding-standard .

# 强制覆盖已存在的技能
./install-skills.sh -f -s common-project-standard .

# 交互式安装
./install-skills.sh -i

# 指定IDE安装
./install-skills.sh --ide trae .

7.3 配置文件

创建 .trae/config.yml 配置文件：

# .trae/config.yml
skills:
  # 是否自动加载所有技能
  auto-load: true
  
  # 技能搜索路径
  paths:
    - .trae/skills
  
  # 默认启用的技能
  enabled:
    - personal-backend-coding-standard
    - personal-frontend-coding-standard
    - personal-java-common
    - personal-project-runner
    - personal-doc-manager
    - personal-solution-research
    - personal-brief-style
    - common-project-standard
    - common-coding
    - common-contract-generation
    - common-backend-unit-test
    - common-frontend-playwright-test
    - common-requirement-clarification
    - common-api-doc
    - common-data-migration
    - common-db-design
    - common-dockerize
    - common-grill-me
    - common-spec-driven
    - common-spring-boot-init
    - common-ui-design-spec
    - common-ui-mockup
    - common-vue-init

7.4 全局配置（推荐）

在用户主目录创建配置文件，使所有项目默认使用这些技能：

# 创建全局配置目录
mkdir -p ~/.trae

# 创建全局技能配置
cat > ~/.trae/skills-config.yml << 'EOF'
# 全局技能配置
skills:
  # 技能仓库位置
  repository: ~/bage/github/study/study-ai-skills/.trae/skills
  
  # 默认启用的技能
  default-enabled:
    - personal-backend-coding-standard
    - personal-frontend-coding-standard
    - common-project-standard
    - common-coding
  
  # 自动同步更新
  auto-sync: true
EOF

# 创建全局安装脚本链接
ln -sf ~/bage/github/study/study-ai-skills/install-skills.sh ~/.trae/install-skills.sh

# 添加到 PATH
echo 'export PATH="$HOME/.trae:$PATH"' >> ~/.bashrc
echo 'export PATH="$HOME/.trae:$PATH"' >> ~/.zshrc

---

8. 技能规范验证

8.1 验证脚本使用

# 验证所有技能
./validate-skills.sh

# 验证指定技能
./validate-skills.sh -s common-coding

# 列出所有技能
./validate-skills.sh -l

# 修复技能格式
./validate-skills.sh -f

# 修复指定技能
./validate-skills.sh -f -s common-coding

8.2 验证规则

8.3 修复功能

验证脚本的 -f 参数可以自动修复以下问题：

1. 创建缺失的 SKILL.md 文件
2. 添加缺失的 Frontmatter 字段
3. 添加缺失的章节标题

---

9. 开源技能包装机制

9.1 设计理念

为了支持多种实现的切换，开源技能采用包装模式：

┌─────────────────────────────────────────────────────┐
│                    技能接口层                       │
│              (Skill Interface)                      │
│  ┌─────────────────────────────────────────────┐   │
│  │  - 统一的输入参数                            │   │
│  │  - 统一的输出格式                            │   │
│  │  - 统一的调用方式                            │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│                    实现切换层                       │
│              (Implementation Switch)               │
│  ┌─────────────────────────────────────────────┐   │
│  │  - 配置驱动的实现选择                         │   │
│  │  - 运行时动态切换                           │   │
│  │  - 实现隔离与解耦                           │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│  自研实现     │ │ 开源实现 A    │ │ 开源实现 B    │
│ (Default)    │ │ (OpenSourceA) │ │ (OpenSourceB) │
└───────────────┘ └───────────────┘ └───────────────┘

9.2 技能命名约定

9.3 配置方式

# .trae/config.yml
skills:
  open-source:
    # UI组件库实现选择: native/componenta/componentb
    os-ui-library:
      active: native
      implementations:
        - name: native
          description: 自研轻量级实现
          enabled: true
        - name: componenta
          description: 基于 Component Library A
          enabled: true
          dependencies:
            - "@componenta/core"
        - name: componentb
          description: 基于 Component Library B
          enabled: false
          dependencies:
            - "@componentb/react"
    
    # 聊天模型实现选择: openai/deepseek/claude
    os-chat-model:
      active: deepseek
      implementations:
        - name: openai
          description: OpenAI API
          enabled: true
          env:
            - OPENAI_API_KEY
        - name: deepseek
          description: DeepSeek API
          enabled: true
          env:
            - DEEPSEEK_API_KEY
        - name: claude
          description: Claude API
          enabled: true
          env:
            - CLAUDE_API_KEY

9.4 开源技能包装示例

技能目录结构

skills/
├── os-ui-library/                    # 包装技能（统一接口）
│   └── SKILL.md
├── os-ui-library-impl-native/        # 自研实现
│   └── SKILL.md
├── os-ui-library-impl-componenta/    # 组件库A实现
│   └── SKILL.md
└── os-ui-library-impl-componentb/    # 组件库B实现
    └── SKILL.md

SKILL.md 包装层示例

---
name: "os-ui-library"
description: "UI组件库技能 - 支持多种实现切换"
---

# UI组件库技能

## 功能描述

提供统一的 UI 组件库接口，支持多种实现切换。

## 何时使用

需要使用 UI 组件时，通过配置选择不同实现。

## 核心功能

- 统一的组件接口
- 运行时实现切换
- 多种开源组件库支持

## 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| componentType | String | 是 | 组件类型 |
| props | Object | 否 | 组件属性 |
| implementation | String | 否 | 指定实现（native/componenta/componentb） |

## 输出格式

```json
{
  "status": "SUCCESS",
  "implementation": "native",
  "component": {...}
}

实现配置

在 .trae/config.yml 中配置：

skills:
  open-source:
    os-ui-library:
      active: native

可用实现

### 9.5 切换实现流程

```bash
# 查看当前配置
cat .trae/config.yml | grep -A 5 "os-ui-library"

# 切换到 Component Library A
sed -i '' 's/active: native/active: componenta/' .trae/config.yml

# 安装依赖（如果需要）
npm install @componenta/core

# 验证切换
./validate-skills.sh -s os-ui-library

---

10. 代码审查检查清单

---

11. 配置要求

11.1 环境变量

11.2 配置文件

project:
  name: xx
  type: backend
  modules:
    - gateway
    - biz
    - infra

skills:
  auto-load: true
  paths:
    - .trae/skills
  open-source:
    os-ui-library:
      active: native
    os-chat-model:
      active: deepseek

---

12. 扩展指南

12.1 添加新技能

1. 在 skills/ 目录下创建新目录
2. 创建 SKILL.md 文件
3. 在 AGENTS.md 中注册技能
4. 在 SKILLS.md 中添加技能清单
5. 使用 ./validate-skills.sh 验证格式

12.2 添加开源技能包装

1. 创建包装层技能（os-{name}）
2. 创建各实现技能（os-{name}-impl-{implementation}）
3. 在配置文件中定义可用实现
4. 实现统一接口层

12.3 切换开源实现

1. 修改 .trae/config.yml 中的 active 配置
2. 安装必要的依赖
3. 验证配置正确性

---

附录：常用忽略规则汇总

Java 项目

# Compiled class files
*.class

# Package files
*.jar
*.war
*.nar
*.ear
*.zip
*.tar.gz
*.rar

# Maven
target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup
pom.xml.next
release.properties
dependency-reduced-pom.xml
buildNumber.properties
.mvn/timing.properties
.mvn/wrapper/maven-wrapper.jar

# IDE
.idea/
*.iws
*.iml
*.ipr
.vscode/

JavaScript/TypeScript 项目

# Dependencies
node_modules/

# Build outputs
dist/
build/
.next/
.nuxt/

# TypeScript
*.tsbuildinfo
*.log

# IDE
.vscode/
.idea/

# Environment
.env
.env.local
.env.*.local

AI/ML 项目

# Model files
*.pt
*.pth
*.onnx
*.h5
*.bin
*.ckpt
*.joblib
*.pickle

# Datasets
data/
dataset/
datasets/

# Vector databases
chroma/
pinecone/
qdrant/

# Cache
.cache/
__pycache__/
.huggingface/
.tensorflow/