开发任务管理 Skill
本 Skill 用于规范化的项目版本管理和开发任务流程。
⚠️ 版本管理纪律（强制执行）
铁律
每个版本封版后必须立即归档完整代码和文档！ 严禁在没有存档的情况下开始新版本号的开发！
违规后果
- v1.X 代码永久丢失 — 未归档即开始 v1.X+1 开发
- 无法回滚到中间版本
- 版本历史断档
必须归档的内容
| 类别 | 必须文件 | 说明 |
|---|---|---|
| 代码 | 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）："
版本号规则：
- 主版本号 (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/：
| 模板文件 | 用途 | 输出位置 |
|---|---|---|
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% 是复杂的优先级/兼容性问题。先查基础，再查复杂。
经验教训归档
- 参考
workspace/lessons/CSS_DEBUG_LESSON.md - 每次遇到典型问题，更新此文档
一句话总结
封版必归档，文档不能少，跳过是违规！ CSS 调试先查选择器，90% 问题都是命名不匹配！