sdd-full 4.0.0 → 4.2.0

package/skills/chinese-git-workflow/SKILL.md

@@ -0,0 +1,510 @@
+---
+name: chinese-git-workflow
+description: 适配国内 Git 平台和团队习惯的工作流规范——Gitee、Coding、极狐 GitLab 全覆盖
+---
+
+# 国内 Git 工作流规范
+
+## 概述
+
+国内团队用 Git 经常踩的坑：GitHub 访问不稳定、CI/CD 方案照搬国外水土不服、commit message 中英混杂没有规范。本技能提供一套**完整适配国内平台和团队习惯的 Git 工作流**。
+
+**核心原则：** 工作流服务于团队效率，不是为了流程而流程。选适合团队规模的，别硬套大厂方案。
+
+## 国内 Git 平台适配
+
+### 平台对比
+
+| 特性 | Gitee | Coding.net | 极狐 GitLab | GitHub |
+|------|-------|------------|-------------|--------|
+| 国内访问 | 快 | 快 | 快 | 不稳定 |
+| 免费私有仓库 | 有 | 有 | 有 | 有 |
+| CI/CD | Gitee Go | Coding CI | 内置 GitLab CI | GitHub Actions |
+| 代码审查 | PR | MR | MR | PR |
+| 制品库 | 有限 | 完整 | 完整 | Packages |
+| 适合场景 | 开源/小团队 | 中大型团队 | 企业私有化 | 国际项目 |
+
+### Gitee 特有配置
+
+```bash
+# 设置 Gitee 远程仓库
+git remote add origin https://gitee.com/<org>/<repo>.git
+
+# Gitee 的 SSH 配置
+# ~/.ssh/config
+Host gitee.com
+    HostName gitee.com
+    User git
+    IdentityFile ~/.ssh/gitee_rsa
+    PreferredAuthentications publickey
+
+# 同时推送到 Gitee 和 GitHub（镜像同步）
+git remote set-url --add --push origin https://gitee.com/<org>/<repo>.git
+git remote set-url --add --push origin https://github.com/<org>/<repo>.git
+```
+
+### Coding.net 特有配置
+
+```bash
+# Coding 的仓库地址格式
+git remote add origin https://e.coding.net/<team>/<project>/<repo>.git
+
+# Coding 支持的 SSH 地址
+git remote add origin git@e.coding.net:<team>/<project>/<repo>.git
+```
+
+### 极狐 GitLab 特有配置
+
+```bash
+# 极狐 GitLab 私有化部署常见地址格式
+git remote add origin https://jihulab.com/<group>/<repo>.git
+
+# 或者企业内部部署
+git remote add origin https://gitlab.yourcompany.com/<group>/<repo>.git
+```
+
+## 工作流选择
+
+### 方案一：主干开发（Trunk-Based Development）
+
+**适合：** 小团队（2-8 人）、迭代速度快、有完善的自动化测试。
+
+```
+main ──●──●──●──●──●──●──●──●──●──
+        \   /  \   /       \   /
+feat/x  ●─●   ●─●    fix/y ●─●
+（短命分支，1-2 天内合回）
+```
+
+**规则：**
+- 主干（main）始终保持可发布状态
+- 功能分支生命周期不超过 2 天
+- 每天至少合并一次到主干
+- 用 Feature Flag 控制未完成功能的可见性
+
+```bash
+# 从 main 拉分支
+git checkout -b feat/user-login main
+
+# 开发完成后，rebase 到最新 main
+git fetch origin
+git rebase origin/main
+
+# 提交 PR/MR，合并后删除分支
+```
+
+### 方案二：Git Flow（经典分支模型）
+
+**适合：** 中大团队、版本发布节奏固定（如双周迭代）、需要维护多个版本。
+
+```
+main     ──●────────────────●────────────── 生产环境
+            \              / \
+release     ●──●──●──●──●    ●──●──●──●── 发布分支
+            \              /
+develop  ──●──●──●──●──●──●──●──●──●──●── 开发主线
+             \   /  \       /
+feat/x       ●─●    ●─────●               功能分支
+                      \   /
+                  fix/y ●─●                修复分支
+```
+
+**分支说明：**
+- `main` — 生产环境代码，只接受 release 和 hotfix 的合并
+- `develop` — 开发主线，功能分支从这里拉出，合回这里
+- `release/*` — 发布分支，从 develop 拉出，只修 bug 不加功能
+- `feat/*` — 功能分支
+- `hotfix/*` — 紧急修复，从 main 拉出，同时合回 main 和 develop
+
+### 方案三：国内团队常用简化流程
+
+**适合：** 大多数国内中小团队的实际情况。
+
+```
+main     ──●──────●──────●──── 生产环境（受保护）
+            \    / \    /
+dev      ──●──●─●──●──●─●──── 开发/测试环境
+             \  /    \  /
+feat/x       ●●      ●●       功能分支
+```
+
+**规则：**
+- `main` 分支受保护，只能通过 PR/MR 合并
+- `dev` 分支对应测试环境，自动部署
+- 功能分支从 `dev` 拉出，合回 `dev`
+- `dev` 测试通过后，合并到 `main` 进行发布
+
+## 分支命名规范
+
+### 国内团队常用命名
+
+```bash
+# 功能分支
+feat/user-login              # 新功能
+feat/JIRA-1234-order-refund  # 关联任务编号
+
+# 修复分支
+fix/payment-callback         # Bug 修复
+fix/JIRA-5678-null-pointer   # 关联 Bug 编号
+
+# 发布分支
+release/v2.1.0               # 版本发布
+release/2024-03-sprint       # 按迭代命名
+
+# 紧急修复
+hotfix/v2.0.1                # 线上紧急修复
+hotfix/fix-login-crash       # 描述性命名
+
+# 个人分支（部分团队使用）
+dev/zhangsan/feat-login      # 个人开发分支
+```
+
+### 命名规则
+
+1. 全部小写，用 `-` 连接单词（不用下划线或驼峰）
+2. 前缀明确分支类型：`feat/`、`fix/`、`hotfix/`、`release/`
+3. 关联任务管理平台的编号（如有）：`feat/TAPD-12345-description`
+4. 长度适中，能看出分支目的即可
+
+## 中文 Commit Message 规范
+
+### 约定式提交（Conventional Commits）中文版
+
+```
+<类型>(<范围>): <简要描述>
+                                    ← 空行
+<正文（可选）>
+                                    ← 空行
+<脚注（可选）>
+```
+
+### 类型清单
+
+| 类型 | 说明 | emoji（可选） |
+|------|------|--------------|
+| feat | 新增功能 | ✨ |
+| fix | 修复 Bug | 🐛 |
+| docs | 文档更新 | 📝 |
+| style | 代码格式（不影响逻辑） | 💄 |
+| refactor | 重构（不是新功能也不是修 Bug） | ♻️ |
+| perf | 性能优化 | ⚡ |
+| test | 测试相关 | ✅ |
+| build | 构建系统或外部依赖 | 📦 |
+| ci | CI/CD 配置 | 👷 |
+| chore | 其他杂项 | 🔧 |
+| revert | 回滚 | ⏪ |
+
+### 好的 commit message
+
+```
+feat(购物车): 支持批量删除商品
+
+- 新增全选/反选功能
+- 删除操作增加二次确认弹窗
+- 批量删除接口使用 POST /cart/batch-delete
+
+关联需求：TAPD-12345
+```
+
+```
+fix(支付): 修复微信支付在 iOS 16 上无法唤起的问题
+
+原因：微信 SDK 8.0.33 版本在 iOS 16 上 Universal Links 校验逻辑变更，
+导致 openURL 回调失败。
+
+方案：升级 SDK 至 8.0.38，并更新 Associated Domains 配置。
+
+Closes #567
+```
+
+### 不好的 commit message
+
+```
+# 太笼统
+update code
+fix bug
+修改了一些东西
+
+# 没有上下文
+fix: 修复问题
+feat: 新增功能
+
+# 中英混杂无规范
+fix：修复了一个bug，因为user login的时候会crash
+```
+
+## CI/CD 平台适配
+
+### Gitee Go
+
+```yaml
+# .gitee/pipelines/pipeline.yml
+name: 构建与测试
+displayName: '构建与测试流水线'
+
+triggers:
+  push:
+    branches:
+      include:
+        - main
+        - dev
+
+stages:
+  - name: 测试
+    jobs:
+      - name: 单元测试
+        steps:
+          - step: npmbuild@1
+            name: install_and_test
+            displayName: '安装依赖并执行测试'
+            inputs:
+              nodeVersion: 20
+              commands:
+                - npm ci
+                - npm test
+```
+
+### Coding CI
+
+```groovy
+// Jenkinsfile（Coding CI 支持 Jenkinsfile 语法）
+pipeline {
+    agent any
+
+    stages {
+        stage('安装依赖') {
+            steps {
+                sh 'npm ci'
+            }
+        }
+
+        stage('单元测试') {
+            steps {
+                sh 'npm test'
+            }
+        }
+
+        stage('构建') {
+            steps {
+                sh 'npm run build'
+            }
+        }
+
+        stage('部署到测试环境') {
+            when {
+                branch 'dev'
+            }
+            steps {
+                sh './scripts/deploy-staging.sh'
+            }
+        }
+
+        stage('部署到生产环境') {
+            when {
+                branch 'main'
+            }
+            steps {
+                sh './scripts/deploy-production.sh'
+            }
+        }
+    }
+
+    post {
+        failure {
+            // 企业微信/钉钉通知
+            sh './scripts/notify-failure.sh'
+        }
+    }
+}
+```
+
+### 极狐 GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - test
+  - build
+  - deploy
+
+variables:
+  NODE_IMAGE: node:20-alpine
+  # 使用国内镜像加速
+  NPM_REGISTRY: https://registry.npmmirror.com
+
+单元测试:
+  stage: test
+  image: $NODE_IMAGE
+  script:
+    - npm config set registry $NPM_REGISTRY
+    - npm ci
+    - npm test
+  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'
+
+构建:
+  stage: build
+  image: $NODE_IMAGE
+  script:
+    - npm config set registry $NPM_REGISTRY
+    - npm ci
+    - npm run build
+  artifacts:
+    paths:
+      - dist/
+
+部署测试环境:
+  stage: deploy
+  script:
+    - ./scripts/deploy-staging.sh
+  only:
+    - dev
+  environment:
+    name: staging
+
+部署生产环境:
+  stage: deploy
+  script:
+    - ./scripts/deploy-production.sh
+  only:
+    - main
+  environment:
+    name: production
+  when: manual  # 生产环境手动触发
+```
+
+### GitHub Actions 国内替代方案对照
+
+| GitHub Actions 功能 | Gitee Go | Coding CI | 极狐 GitLab CI |
+|---------------------|----------|-----------|----------------|
+| 触发条件 | triggers | Jenkinsfile triggers | only/rules |
+| 缓存依赖 | cache step | stash/unstash | cache |
+| 制品存储 | artifacts | 制品库 | artifacts |
+| 环境变量 | env | environment | variables |
+| 密钥管理 | 环境变量配置 | 凭据管理 | CI/CD Variables |
+| 手动触发 | 手动运行 | 手动触发 | when: manual |
+
+## PR/MR 描述模板
+
+### 中文模板
+
+在仓库中创建 PR/MR 模板文件：
+
+**Gitee：** `.gitee/PULL_REQUEST_TEMPLATE.md`
+
+**Coding / GitLab：** `.gitlab/merge_request_templates/default.md`
+
+```markdown
+## 变更说明
+
+<!-- 简要描述这次改动做了什么，解决了什么问题 -->
+
+## 变更类型
+
+- [ ] 新功能（feat）
+- [ ] Bug 修复（fix）
+- [ ] 重构（refactor）
+- [ ] 性能优化（perf）
+- [ ] 文档更新（docs）
+- [ ] 其他：
+
+## 关联信息
+
+- 需求/Bug 链接：
+- 设计文档：
+
+## 改动范围
+
+<!-- 列出主要改动的模块和文件 -->
+
+## 测试情况
+
+- [ ] 单元测试通过
+- [ ] 手动测试通过
+- [ ] 相关模块回归测试通过
+
+## 测试方法
+
+<!-- 描述如何验证这次改动 -->
+
+## 影响范围
+
+<!-- 这次改动可能影响哪些功能？是否需要通知其他团队？ -->
+
+## 部署注意事项
+
+- [ ] 需要执行数据库迁移
+- [ ] 需要更新配置文件
+- [ ] 需要更新环境变量
+- [ ] 无特殊注意事项
+
+## 截图/录屏
+
+<!-- 如果涉及 UI 变更，贴截图或录屏 -->
+```
+
+## 常用 Git 配置
+
+### 国内环境优化
+
+```bash
+# 设置用户信息
+git config --global user.name "张三"
+git config --global user.email "zhangsan@company.com"
+
+# commit message 编辑器设置为 VS Code
+git config --global core.editor "code --wait"
+
+# 解决中文文件名显示为转义字符的问题
+git config --global core.quotepath false
+
+# 设置默认分支名
+git config --global init.defaultBranch main
+
+# 代理设置（如果需要同时使用 GitHub）
+git config --global http.https://github.com.proxy socks5://127.0.0.1:7890
+
+# NPM 使用国内镜像
+npm config set registry https://registry.npmmirror.com
+```
+
+### .gitignore 国内项目常见配置
+
+```gitignore
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# 依赖
+node_modules/
+vendor/
+
+# 构建产物
+dist/
+build/
+*.exe
+
+# 环境配置
+.env
+.env.local
+.env.*.local
+
+# 系统文件
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# 国内平台特有
+.coding/
+```
+
+## 检查清单
+
+在推送代码前，确认：
+
+- [ ] 分支命名符合团队规范
+- [ ] commit message 格式正确，类型和范围准确
+- [ ] 关联了对应的需求/Bug 编号
+- [ ] PR/MR 描述填写完整
+- [ ] CI 流水线通过
+- [ ] 已请求相关同事 Review

package/skills/design-planning/enterprise-spec/SKILL.md

@@ -0,0 +1,5 @@
+# enterprise-spec - 企业级全栈工程规范
+
+## 功能说明
+
+环境预检前置、

package/skills/design-planning/flutter-av/SKILL.md

@@ -0,0 +1,44 @@
+# flutter-av - Flutter音视频全栈SDD
+
+## 功能说明
+
+离线ASR语音转写、TTS语音合成、OCR文字识别接入规范。
+
+## 触发词
+
+`Flutter音视频`、`ASR`、`TTS`、`OCR`、`语音识别`
+
+## 参数说明
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| project_name | string | 是 | 项目名称 |
+| modules | string | 否 | 模块列表：asr/tts/ocr |
+
+## 核心内容
+
+### 1. 离线ASR
+- 语音识别引擎选择
+- 模型下载与更新
+- 实时识别优化
+
+### 2. TTS语音合成
+- 语音引擎配置
+- 音色选择
+- 语速语调控制
+
+### 3. OCR文字识别
+- 图像预处理
+- 识别精度优化
+- 多语言支持
+
+## 使用示例
+
+```
+trae调用 Flutter音视频全栈SDD 项目名称=智能助手APP
+trae调用 Flutter音视频全栈SDD 项目名称=教育平台 模块=asr,tts
+```
+
+## 版本
+
+v4.1.0

package/skills/design-planning/flutter-map/SKILL.md

@@ -0,0 +1,44 @@
+# flutter-map - Flutter地图导航业务SDD
+
+## 功能说明
+
+高德SDK集成、Marker警告处理、地图不显示问题落地规范。
+
+## 触发词
+
+`Flutter地图`、`地图导航`、`骑手端`、`高德地图`
+
+## 参数说明
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| project_name | string | 是 | 项目名称 |
+| features | string | 否 | 功能列表（逗号分隔） |
+
+## 核心内容
+
+### 1. 高德SDK集成
+- SDK版本选择
+- 密钥配置
+- 权限申请
+
+### 2. Marker处理
+- Marker创建与管理
+- 警告Marker样式
+- 点击事件处理
+
+### 3. 常见问题
+- 地图不显示排查
+- 定位不准处理
+- 性能优化
+
+## 使用示例
+
+```
+trae调用 Flutter地图导航业务SDD 项目名称=骑手端APP
+trae调用 Flutter地图导航业务SDD 项目名称=物流配送系统 功能=定位,路线规划
+```
+
+## 版本
+
+v4.1.0

package/skills/design-planning/ui-sdd-specialized/SKILL.md

@@ -0,0 +1,50 @@
+# ui-sdd-specialized - UI专用SDD模板
+
+## 功能说明
+
+UI设计稿对应结构化SDD固定格式、字段、交付标准的专用模板。
+
+## 触发词
+
+`UI-SDD`、`UI设计`、`界面设计`、`设计转代码`
+
+## 参数说明
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| page_name | string | 是 | 页面名称 |
+| design_source | string | 否 | 设计稿来源（Figma/Sketch/其他） |
+| platform | string | 否 | 目标平台：web/mobile/desktop |
+
+## 输出结构
+
+### 1. 页面概览
+- 页面定位
+- 功能概述
+- 用户场景
+
+### 2. 布局结构
+- 页面框架
+- 组件分布
+- 响应式适配
+
+### 3. 组件规格
+- 组件清单
+- 样式规范
+- 交互说明
+
+### 4. 交付标准
+- 设计稿规范
+- 切图标注
+- 动效要求
+
+## 使用示例
+
+```
+trae调用 UI-SDD专用模板 页面名称=首页
+trae调用 UI-SDD专用模板 页面名称=商品详情页 平台=mobile
+```
+
+## 版本
+
+v4.1.0

package/skills/development-execution/flutter-errors/SKILL.md

@@ -0,0 +1,44 @@
+# flutter-errors - Flutter常见异常专项
+
+## 功能说明
+
+SocketException、Framebuffer渲染异常排查与修复标准化流程。
+
+## 触发词
+
+`Flutter异常`、`异常处理`、`SocketException`、`渲染错误`
+
+## 参数说明
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| error_type | string | 是 | 异常类型 |
+| scenario | string | 否 | 发生场景 |
+
+## 异常类型
+
+### 1. SocketException
+- 网络连接失败
+- 超时处理
+- 重试机制
+
+### 2. Framebuffer渲染异常
+- UI卡顿
+- 内存泄漏
+- 渲染优化
+
+### 3. 其他常见异常
+- 空指针异常
+- 类型转换错误
+- 状态管理问题
+
+## 使用示例
+
+```
+trae调用 Flutter常见异常专项SDD 异常类型=SocketException
+trae调用 Flutter常见异常专项SDD 异常类型=Framebuffer渲染异常 场景=列表滚动
+```
+
+## 版本
+
+v4.1.0