开发任务管理 Skill

---

name: dev-task

description: 开发项目任务管理，支持版本化开发流程。当用户需要启动开发任务、创建新版本、管理项目版本文档时使用。每次启动开发任务必须向用户确认版本编号，按版本号管理代码、开发文档、需求文档、发布配置。严格执行版本归档纪律，封版必须立即归档完整代码和文档。

---

# 开发任务管理 Skill

本 Skill 用于规范化的项目版本管理和开发任务流程。

---

⚠️ 版本管理纪律（强制执行）

铁律

> **每个版本封版后必须立即归档完整代码和文档！**

> **严禁在没有存档的情况下开始新版本号的开发！**

违规后果

必须归档的内容

| 类别 | 必须文件 | 说明 |

|------|---------|------|

| **代码** | `src/` 目录 | 封版时的完整代码快照 |

| **变更** | `docs/CHANGELOG.md` | 功能列表、Bug修复、已知问题 |

| **需求** | `docs/REQUIREMENTS.md` | 需求规格、功能清单 |

| **运维** | `docs/DEPLOY.md` | 部署步骤、回滚方案、监控方法 |

---

项目版本结构规范

project-name/
├── [当前开发文件]              # 正在开发的代码
└── versions/                   # ★版本归档目录（不可跳过）
    ├── README.md              # 版本管理说明、当前版本
    ├── v1.0/                  # v1.0 版本（完整归档）
    │   ├── docs/
    │   │   ├── CHANGELOG.md   # 变更日志
    │   │   ├── REQUIREMENTS.md # 需求文档
    │   │   └── DEPLOY.md      # 部署文档
    │   ├── src/               # ★完整代码备份
    │   └── release/           # 发布包（可选）
    ├── v1.1/                  # v1.1 版本（完整归档）
    └── v1.2/                  # v1.2 版本（完整归档）

---

开发任务启动流程

Step 1: 确认版本编号（必须）

**必须**向用户确认版本号，格式为 `v主版本.次版本.修订号`：

> "请确认本次开发任务的版本编号（例如：v1.1.0）："

**版本号规则：**

**检查规则：**

Step 2: 检查上一个版本是否已归档

# 检查最新版本
ls -la versions/ | tail -5

# 如果上一个版本未完成归档，必须提醒用户：
# "⚠️ 警告：上一个版本 vX.Y.Z 尚未封版归档！"
# "必须先完成 vX.Y.Z 的归档，才能开始新版本开发。"

Step 3: 创建新版本目录结构

# 创建目录
mkdir -p versions/vX.Y.Z/{docs,src,release}

# 初始化文档
cp references/CHANGELOG.template.md versions/vX.Y.Z/docs/CHANGELOG.md
cp references/REQUIREMENTS.template.md versions/vX.Y.Z/docs/REQUIREMENTS.md
cp references/DEPLOY.template.md versions/vX.Y.Z/docs/DEPLOY.md

# 替换版本号占位符
sed -i 's/vX.Y.Z/vX.Y.Z/g' versions/vX.Y.Z/docs/*.md

Step 4: 更新 REQUIREMENTS.md

根据用户描述，填写本次开发的需求：

Step 5: 开始开发

在当前目录进行开发工作。

---

版本封版流程（★关键步骤）

何时封版

封版检查清单

**必须完成以下所有项，缺一不可：**

- [ ] 新增功能列表

- [ ] Bug 修复记录

- [ ] 已知问题说明

- [ ] 部署日期

- [ ] 需求完成情况

- [ ] 功能清单核对

- [ ] 部署步骤

- [ ] 环境要求

- [ ] 回滚方案

```bash

cp -r client versions/vX.Y.Z/src/

cp -r server versions/vX.Y.Z/src/

cp package.json versions/vX.Y.Z/src/

cp [其他必要文件] versions/vX.Y.Z/src/

```

- 当前版本信息

- 版本历史记录

封版命令

#!/bin/bash
VERSION=$1  # 传入版本号，如 v1.1.0

echo "=== 版本封版: $VERSION ==="

# 1. 验证文档存在
for doc in CHANGELOG REQUIREMENTS DEPLOY; do
    if [ ! -f "versions/$VERSION/docs/${doc}.md" ]; then
        echo "❌ 错误: ${doc}.md 不存在！"
        exit 1
    fi
done

# 2. 归档代码
echo "归档代码..."
cp -r client versions/$VERSION/src/
cp -r server versions/$VERSION/src/
cp package.json versions/$VERSION/src/ 2>/dev/null || true

# 3. 验证归档
if [ -d "versions/$VERSION/src/client" ] && [ -d "versions/$VERSION/src/server" ]; then
    echo "✅ 版本 $VERSION 封版完成！"
else
    echo "❌ 归档失败！"
    exit 1
fi

---

版本回滚

VERSION=$1  # 目标版本

echo "回滚到 $VERSION..."

# 1. 停止服务
pm2 stop [服务名]

# 2. 验证版本存在
if [ ! -d "versions/$VERSION/src" ]; then
    echo "❌ 版本 $VERSION 代码不存在！"
    exit 1
fi

# 3. 恢复代码
cp -r versions/$VERSION/src/* ./

# 4. 重新安装依赖
npm install

# 5. 启动服务
pm2 start [服务名]

echo "✅ 已回滚到 $VERSION"

---

参考模板

文档模板位于 `references/doc-templates/`：

| 模板文件 | 用途 | 输出位置 |

|---------|------|---------|

| `CHANGELOG.template.md` | 变更日志 | `docs/CHANGELOG.md` |

| `REQUIREMENTS.template.md` | 需求文档 | `docs/REQUIREMENTS.md` |

| `DEPLOY.template.md` | 部署说明 | `docs/DEPLOY.md` |

---

违规处理

如果发现以下情况，必须立即纠正：

| 违规情况 | 处理方式 |

|---------|---------|

| 未归档即开始新版本 | **立即停止**，先完成上一个版本归档 |

| 缺少 CHANGELOG.md | 补充编写，记录变更 |

| 缺少 REQUIREMENTS.md | 补充编写，明确需求 |

| 缺少 DEPLOY.md | 补充编写，确保可部署 |

| src/ 目录为空或不完整 | 重新归档完整代码 |

---

CSS/样式调试检查清单

**遇到样式不生效时，按此顺序排查：**

Step 1: 确认选择器匹配（最常见错误！）

✅ 检查 HTML 中元素的 id/class 是否与 CSS 选择器一致
   - id: chatInput vs #chat-input （命名不匹配！）
   - class: my-class vs .myClass （大小写敏感！）
✅ 用 DevTools Elements 面板确认元素的实际属性

Step 2: 确认文件加载

✅ Network 面板 → CSS 文件状态 200
✅ 文件名和路径是否正确（大小写敏感！）

Step 3: 确认样式应用

✅ DevTools Computed 面板 → 查看实际生效的样式
✅ Styles 面板 → 查看哪些规则被划掉（特异性问题）
✅ 检查是否有更高优先级的规则覆盖

Step 4: 复杂问题排查

✅ 浏览器默认样式 → 用 !important 或 appearance: none
✅ JS 动态修改 → 检查脚本是否修改了样式
✅ CSS 变量未定义 → 检查 var(--xxx) 是否有值

黄金法则

> **90% 的 CSS 问题是基础错误（选择器不匹配、文件未加载），只有 10% 是复杂的优先级/兼容性问题。先查基础，再查复杂。**

经验教训归档

---

一句话总结

> **封版必归档，文档不能少，跳过是违规！**

> **CSS 调试先查选择器，90% 问题都是命名不匹配！**