开发任务管理 Skill

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

---

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

铁律

每个版本封版后必须立即归档完整代码和文档！ 严禁在没有存档的情况下开始新版本号的开发！

违规后果

• v1.X 代码永久丢失 — 未归档即开始 v1.X+1 开发
• 无法回滚到中间版本
• 版本历史断档

必须归档的内容

---

项目版本结构规范

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）："

版本号规则：

• 主版本号 (X.0.0): 重大功能变更、架构调整
• 次版本号 (0.X.0): 新增功能、向下兼容
• 修订号 (0.0.X): Bug 修复、小优化

检查规则：

• 如果 versions/vX.Y.Z 已存在 → 询问继续开发还是换新版本
• 如果当前开发目录有未归档代码 → 必须先封版上一个版本！

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: 开始开发

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

---

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

何时封版

• 功能开发完成
• 测试通过
• 准备部署或发布

封版检查清单

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

• CHANGELOG.md 已更新

  • 新增功能列表
  • Bug 修复记录
  • 已知问题说明
  • 部署日期

• REQUIREMENTS.md 已更新

  • 需求完成情况
  • 功能清单核对

• DEPLOY.md 已更新

  • 部署步骤
  • 环境要求
  • 回滚方案

• 代码已归档

  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/
  

• versions/README.md 已更新

  • 当前版本信息
  • 版本历史记录

封版命令

#!/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/：

---

违规处理

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

---

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% 是复杂的优先级/兼容性问题。先查基础，再查复杂。

经验教训归档

• 参考 workspace/lessons/CSS_DEBUG_LESSON.md
• 每次遇到典型问题，更新此文档

---

一句话总结

封版必归档，文档不能少，跳过是违规！ CSS 调试先查选择器，90% 问题都是命名不匹配！