@colin4k1024/tsp 2.4.0 → 2.4.2

package/docs/runbooks/demo-execution-log.md

@@ -0,0 +1,530 @@
+# 完整示例执行记录
+
+> Team Skills Platform 端到端演示
+> 场景：用户积分等级系统
+
+---
+
+## 阶段 0：初始化
+
+**当前状态检查**：
+- ✅ hooks 已启用（memory、context compression、error-experience）
+- ✅ 8 个角色已定义
+- ✅ 27 个 specialist agents 就绪
+- ✅ 团队命令已配置
+
+---
+
+## 阶段 1：/team-intake
+
+### 🎬 场景设定
+
+**用户**：业务方提出需求
+**Agent 角色**：Tech Lead（主导）、Product Manager（参与）
+
+### Tech Lead 第一性原理思考
+
+```
+在接收需求前，Tech Lead 追问：
+
+Evidence（证据）:
+- 这个需求背后有什么数据支持？（用户活跃度下降 15%）
+- 谁是最终决策者？（业务负责人 + CTO）
+- 有没有明确的业务指标？（DAU 提升 10%，付费率提升 5%）
+
+Reasoning（推理）:
+- 为什么是积分系统而不是其他激励方式？（维持利润空间，用户心理锚定）
+- 为什么不外购而要自研？（需要与现有用户中心深度集成）
+- 为什么现在做而不是下个季度？（Q2 业绩压力）
+
+Implications（影响）:
+- 如果做失败了最坏怎样？（浪费 4 周，错过营销节点）
+- 有没有 MVP 方案？（先做核心积分获取，其他后续迭代）
+- 能否分阶段交付？（先上线积分获取，再做兑换）
+```
+
+### /team-intake 执行
+
+**输入**：
+```yaml
+业务背景: 用户活跃度下降 15%，需要积分激励
+核心功能: 积分获取、兑换、等级权益
+交付时间: 4 周内
+技术要求: Spring Boot + React
+```
+
+**输出（Tech Lead 锁定）**：
+
+| 字段 | 内容 |
+|------|------|
+| 目标 | 提升用户活跃度 10%，付费率提升 5% |
+| 范围 | 积分获取、等级计算、基础兑换（优惠券） |
+| 成功标准 | 积分 API 可用，前端页面可展示，等级计算正确 |
+| 约束 | 必须与现有用户中心对接，需 API 契约测试 |
+| MVP | 第一期只做积分获取和等级展示，兑换下期做 |
+| 风险 | 时间紧（4周），依赖外部系统对接 |
+
+### 第一性原理应用记录
+
+| 决策 | Evidence | Reasoning | Implications |
+|------|----------|-----------|--------------|
+| MVP 策略 | Q2 时间紧 | 先验证核心价值，减小失败成本 | 可能影响用户体验，但降低整体风险 |
+| 自研决策 | 需要深度集成 | 外购无法满足定制化需求 | 开发成本高，但长期可控 |
+
+---
+
+## 阶段 2：/team-plan
+
+### 🎬 Tech Lead 主导任务分解
+
+### Architect 第一性原理思考
+
+```
+在设计架构前，Architect 追问：
+
+Evidence（证据）:
+- 现有系统是什么架构？（微服务，Spring Boot + MySQL）
+- 峰值 QPS 是多少？（5000/s 峰值）
+- 数据一致性要求？（最终一致即可，有补偿机制）
+
+Reasoning（推理）:
+- 为什么不用现成的积分服务？（定制化程度高）
+- 为什么选择事件驱动？（解耦订单系统和积分系统）
+- 为什么不同步调用？（避免强依赖，降低失败影响）
+
+Implications（影响）:
+- 如果事件丢失了？（需要补偿机制，用户可能少积分）
+- 如果数据库挂了？（积分不可用，但不影响下单）
+```
+
+### Project Manager 第一性原理思考
+
+```
+在制定计划前，Project Manager 追问：
+
+Evidence（证据）:
+- 类似项目通常多久？（6-8 周）
+- 团队人数是多少？（后端 2人，前端 2人，QA 1人）
+- 外部依赖可控吗？（用户中心 API 已定义）
+
+Reasoning（推理）:
+- 为什么 4 周可行？（并行开发，前后端分离）
+- 为什么不是 5 周？（业务方时间窗口固定）
+- 为什么不能加人？（资源已最大化）
+
+Implications（影响）:
+- 如果某个任务延期？（关键路径分析，识别风险）
+- 有没有缓冲时间？（10% 缓冲）
+```
+
+### /team-plan 执行
+
+**任务分解（Tech Lead）**：
+
+| 任务 ID | 任务描述 | 主责角色 | 依赖 | 工期 |
+|---------|---------|---------|------|------|
+| T1 | 积分服务架构设计 | architect | - | 2天 |
+| T2 | 用户中心 API 对接方案 | architect | T1 | 1天 |
+| T3 | 积分数据库设计 | backend-engineer | T1 | 1天 |
+| T4 | 积分获取 API 开发 | backend-engineer | T1, T2 | 5天 |
+| T5 | 等级计算服务 | backend-engineer | T4 | 3天 |
+| T6 | 前端积分页面开发 | frontend-engineer | T1 | 5天 |
+| T7 | 前端等级展示 | frontend-engineer | T6 | 2天 |
+| T8 | API 契约测试 | qa-engineer | T4, T5, T6 | 3天 |
+| T9 | E2E 测试 | qa-engineer | T8 | 2天 |
+| T10 | 发布上线 | devops-engineer | T9 | 1天 |
+
+**里程碑**：
+
+| 里程碑 | 日期 | 交付物 |
+|--------|------|--------|
+| M1 | 第1周周五 | 架构设计、API 契约 |
+| M2 | 第2周周五 | 积分 API 完成 |
+| M3 | 第3周周五 | 前端完成，E2E 开始 |
+| M4 | 第4周周五 | 测试通过，发布上线 |
+
+**关键路径**：T1 → T4 → T5 → T8 → T9 → T10
+
+**风险识别**：
+
+| 风险 | 概率 | 影响 | 应对 |
+|------|------|------|------|
+| 用户中心 API 延期 | 中 | 高 | 预先 Mock，后补对接 |
+| 前端复杂度超预期 | 低 | 中 | 优先保核心功能 |
+| 测试发现重大 bug | 中 | 高 | 预留 2 天缓冲 |
+
+### ADR（架构决策记录）
+
+```markdown
+# ADR-001: 积分服务架构选型
+
+## 决策
+采用独立积分微服务，通过事件驱动与订单系统解耦
+
+## 证据
+- 订单系统 QPS 5000/s，积分计算不应阻塞主流程
+- 未来可能有多个系统产生积分（签到、任务等）
+
+## 推理
+同步调用 → 强依赖 → 一个系统慢影响全部
+事件驱动 → 弱依赖 → 可独立扩展和容错
+
+## 影响
+- 需要事件补偿机制（幂等设计）
+- 数据最终一致性（非强一致）
+- 运维复杂度增加
+
+## 回退方案
+如果事件驱动过于复杂，可降级为同步调用 + 本地缓存
+```
+
+---
+
+## 阶段 3：/handoff
+
+### 🎬 角色间标准化交接
+
+### Architect → Backend Engineer 交接
+
+**Handoff 契约**：
+
+```yaml
+输入:
+  - 架构方案: ADR-001
+  - API 契约: user-center-api-contract.yaml
+  - 数据库设计: points-schema.md
+
+交付物:
+  - 积分获取 API (POST /api/points/earn)
+  - 积分查询 API (GET /api/points/{userId})
+  - 等级计算 API (GET /api/points/{userId}/level)
+
+质量门禁:
+  - API 响应时间 < 100ms (P99)
+  - 支持幂等重试
+  - 错误码符合规范
+
+风险提示:
+  - 用户中心 API 尚未提供，需要先 Mock
+```
+
+### Backend Engineer → QA Engineer 交接
+
+**Handoff 契约**：
+
+```yaml
+输入:
+  - 积分 API 实现代码
+  - API 契约文档
+  - 自测报告
+
+交付物:
+  - API 契约测试用例
+  - 集成测试用例
+  - 性能测试计划
+
+质量门禁:
+  - 契约测试 100% 通过
+  - 边界条件覆盖: 负积分、积分溢出、并发扣减
+  - 回归测试覆盖: 订单取消退积分
+
+风险提示:
+  - 事件补偿机制需要额外测试
+```
+
+### Frontend Engineer → QA Engineer 交接
+
+**Handoff 契约**：
+
+```yaml
+输入:
+  - 积分页面实现
+  - 组件文档
+  - 自测报告
+
+交付物:
+  - 页面 E2E 测试用例
+  - 响应式测试用例
+  - 可访问性测试报告
+
+质量门禁:
+  - 核心用户路径 E2E 通过
+  - 响应式: 320px - 1920px
+  - A11y: WCAG 2.1 AA
+
+风险提示:
+  - 多浏览器兼容（Chrome, Safari, Firefox）
+```
+
+---
+
+## 阶段 4：/team-execute
+
+### 🎬 并行执行
+
+### Backend Engineer 执行记录
+
+**第一性原理思考**：
+
+```
+Evidence:
+- 数据库选型: MySQL 8.0（团队熟悉，满足需求）
+- 连接池: HikariCP（Spring Boot 默认，高性能）
+- ORM: JPA（开发效率）
+
+Reasoning:
+为什么不用 Redis 缓存？（数据量可控，一致性要求高）
+为什么不用 MongoDB？（团队不熟悉，维护成本高）
+
+Implications:
+如果 MySQL 成为瓶颈？（可水平扩展，但短期不会）
+```
+
+**实现产出**：
+
+| 文件 | 说明 |
+|------|------|
+| `PointsService.java` | 积分业务逻辑 |
+| `PointsController.java` | REST API |
+| `PointsRepository.java` | 数据访问层 |
+| `LevelCalculator.java` | 等级计算逻辑 |
+| `PointsEventConsumer.java` | 事件消费 |
+
+**自测结果**：
+
+```
+✅ 积分获取 API: P99 < 50ms
+✅ 等级计算: 正确处理 L1-L5 边界
+✅ 幂等性: 重复提交不重复积分
+✅ 并发测试: 100 并发无数据竞争
+```
+
+### Frontend Engineer 执行记录
+
+**第一性原理思考**：
+
+```
+Evidence:
+- 组件库: Ant Design（团队熟悉）
+- 状态管理: Zustand（轻量）
+- 构建工具: Vite（快）
+
+Reasoning:
+为什么不用 Redux？（过于复杂，不值得）
+为什么不用组件库自带图标？（定制化程度低）
+
+Implications:
+如果样式不统一？（使用 Design Token，保证一致性）
+```
+
+**实现产出**：
+
+| 文件 | 说明 |
+|------|------|
+| `PointsPage.tsx` | 积分主页 |
+| `LevelBadge.tsx` | 等级徽章组件 |
+| `PointsHistory.tsx` | 积分历史 |
+| `usePoints.ts` | 积分 Hook |
+
+**自测结果**：
+
+```
+✅ 响应式: 320px - 1920px 正常
+✅ A11y: 键盘导航正常，屏幕阅读器兼容
+✅ 性能: LCP < 2.5s, FID < 100ms
+```
+
+---
+
+## 阶段 5：/team-review
+
+### 🎬 QA Engineer 主导
+
+**第一性原理思考**：
+
+```
+Evidence:
+- 测试策略依据: 历史上 60% 的 bug 来自边界条件
+- 回归范围: 积分获取、等级计算、兑换流程
+
+Reasoning:
+为什么 pairwise 测试？（组合爆炸，用正交表压缩）
+为什么 E2E 优先核心路径？（资源有限，先保核心）
+
+Implications:
+如果漏测了非核心功能？（可接受，有兜底方案）
+```
+
+### /team-review 执行
+
+**测试计划**：
+
+| 测试类型 | 用例数 | 覆盖 |
+|---------|-------|------|
+| 契约测试 | 24 | 100% |
+| 单元测试 | 156 | 85% |
+| 集成测试 | 32 | 80% |
+| E2E 测试 | 18 | 核心路径 |
+| 性能测试 | 8 | 峰值场景 |
+
+**发现的问题**：
+
+| 问题 | 严重度 | 状态 |
+|------|--------|------|
+| 积分并发扣减有竞争条件 | 高 | 已修复 |
+| 等级边界计算错误（L4/L5） | 中 | 已修复 |
+| 前端响应式布局在 Safari 有问题 | 低 | 已修复 |
+| 事件补偿机制缺少超时处理 | 高 | 已修复 |
+
+**质量评估**：
+
+```
+代码覆盖率: 78%
+契约测试通过率: 100%
+阻塞项: 0
+非阻塞风险: 2 (已记录)
+放行建议: ✅ 可以发布
+```
+
+---
+
+## 阶段 6：/team-release
+
+### 🎬 DevOps Engineer 主导
+
+**第一性原理思考**：
+
+```
+Evidence:
+- 发布窗口: 周五 18:00（非高峰期）
+- 回滚时间目标: < 5 分钟
+- 监控告警: 已配置
+
+Reasoning:
+为什么选择周五发布？（给周末观察时间）
+为什么不热部署？（需要重启生效）
+
+Implications:
+如果发布失败？（5 分钟内回滚到上一版本）
+```
+
+### /team-release 执行
+
+**发布前检查**：
+
+```
+✅ SLSA Level 2 供应链安全验证通过
+✅ SBOM 生成完成
+✅ 镜像签名完成（Cosign）
+✅ 回滚方案已验证
+✅ 监控告警已配置
+✅ 值班人员已确认
+```
+
+**发布执行**：
+
+```
+18:00 - 开始发布
+18:02 - 灰度 5% 用户
+18:05 - 观察无异常
+18:08 - 灰度扩到 50%
+18:12 - 观察无异常
+18:15 - 全量发布
+18:18 - 发布完成
+```
+
+**发布后验证**：
+
+```
+✅ 积分 API 响应正常
+✅ 等级计算正确
+✅ 监控指标正常（QPS: 1200, 错误率: 0.1%）
+✅ 日志无异常
+```
+
+---
+
+## 交付总结
+
+### 最终交付物
+
+| 类别 | 交付物 | 状态 |
+|------|--------|------|
+| 后端 | 积分微服务（Spring Boot） | ✅ |
+| 前端 | 积分页面（React + TypeScript） | ✅ |
+| 数据库 | MySQL Schema + 迁移脚本 | ✅ |
+| 测试 | 契约测试、单元测试、E2E | ✅ |
+| 安全 | CodeQL、Secret 扫描、SLSA | ✅ |
+| 部署 | Docker 镜像、Helm Chart | ✅ |
+
+### 成功标准达成
+
+| 标准 | 目标 | 实际 | 状态 |
+|------|------|------|------|
+| 上线时间 | 4 周 | 4 周 | ✅ |
+| API 响应 | < 100ms | 95ms | ✅ |
+| 用户活跃度提升 | 10% | 待验证（上线后观察） | ⏳ |
+| 付费率提升 | 5% | 待验证 | ⏳ |
+
+### 经验沉淀
+
+**Error Experience Library 记录**：
+
+```json
+{
+  "pattern_id": "points-concurrent-race",
+  "error_type": "concurrency_bug",
+  "error_message": "Duplicate points awarded on concurrent requests",
+  "root_cause": "Missing optimistic locking on points balance",
+  "solution": "Add @Version column or use SELECT FOR UPDATE",
+  "tags": ["concurrency", "database", "points"]
+}
+```
+
+### 下一步行动
+
+1. **第一性原理复盘**：
+   - MVP 策略是否正确？（✅ 先验证核心价值）
+   - 4 周时间是否合理？（✅ 刚好完成，有缓冲）
+
+2. **遗留项**：
+   - 积分兑换功能（Q3）
+   - 积分退款处理（待业务确认）
+
+3. **监控观察**：
+   - 用户活跃度指标（2 周后评估）
+   - 系统性能指标（持续监控）
+
+---
+
+## 附录：关键决策记录
+
+### 决策 1：MVP 范围
+
+| 属性 | 内容 |
+|------|------|
+| 决策 | 第一期只做积分获取和等级展示 |
+| 证据 | Q2 时间窗口固定，资源有限 |
+| 推理 | 先验证核心价值，减小失败成本 |
+| 影响 | 用户体验不完整，但风险可控 |
+| 回退 | 如验证失败，可快速调整方向 |
+
+### 决策 2：事件驱动架构
+
+| 属性 | 内容 |
+|------|------|
+| 决策 | 采用事件驱动解耦订单和积分系统 |
+| 证据 | 订单系统 QPS 高，不应阻塞 |
+| 推理 | 同步调用导致强依赖，一个慢全部慢 |
+| 影响 | 需要补偿机制，运维复杂度增加 |
+| 回退 | 如过于复杂，降级为同步调用 |
+
+### 决策 3：技术选型
+
+| 属性 | 内容 |
+|------|------|
+| 决策 | Spring Boot + React + MySQL |
+| 证据 | 团队技术栈匹配，社区活跃 |
+| 推理 | 减少学习成本，加快交付 |
+| 影响 | 技术债未来需要偿还 |
+| 回退 | 预留 10% 时间处理技术债 |

package/docs/runbooks/demo-scenario.md

@@ -0,0 +1,129 @@
+# 示例需求：用户积分等级系统
+
+> 本文档用于演示 Team Skills Platform 的完整流程，所有 8 个角色都将参与。
+
+## 业务背景
+
+公司希望上线一个「用户积分等级系统」，用于激励用户活跃度和付费行为。
+
+## 需求概述
+
+- 用户每次消费、签到、完成任务获得积分
+- 积分可兑换优惠券、会员权益
+- 积分等级（L1-L5）解锁不同权益
+- 后台管理系统可配置积分规则、查询用户积分
+
+## 涉及系统
+
+- 用户中心（已有微服务）
+- 订单系统（已有微服务）
+- 营销系统（已有微服务）
+- **新开发：积分服务**
+
+## 技术约束
+
+- 微服务架构，使用 Spring Boot + MySQL
+- 需要与现有用户中心、订单系统对接
+- 前端使用 React + TypeScript
+- 需要 API 契约测试
+- 需要 SLSA Level 2 供应链安全
+
+## 交付要求
+
+- 4 周内完成
+- 需要前端和后端
+- 需要完整的测试覆盖
+
+---
+
+## 第一性原理分析（示例）
+
+在开始之前，Tech Lead 需要追问：
+
+**Evidence（证据）**：
+- 业务方提供了什么数据支持这个需求？（用户活跃度下降 15%）
+- 有没有竞品分析？（某平台积分系统带来 20% 活跃度提升）
+
+**Reasoning（推理）**：
+- 为什么用积分而不是直接降价？（保持利润空间）
+- 为什么不做成订阅制？（降低用户决策门槛）
+
+**Implications（影响）**：
+- 如果积分系统崩了，最坏影响？（用户无法兑换，客诉激增）
+- 有没有灰度发布方案？（先对 5% 用户开放）
+
+---
+
+## 角色参与计划
+
+| 阶段 | 主导角色 | 参与角色 |
+|------|---------|---------|
+| Intake | tech-lead | product-manager |
+| Plan | tech-lead | architect, project-manager, product-manager |
+| Handoff | tech-lead | 所有角色 |
+| Execute | frontend-engineer, backend-engineer | architect, qa-engineer |
+| Review | qa-engineer | tech-lead, architect, devops-engineer |
+| Release | devops-engineer | tech-lead, qa-engineer |
+
+---
+
+## 执行记录
+
+### Step 1: /team-intake
+
+**由 Tech Lead 主导，Product Manager 参与**
+
+输入：
+- 业务背景：用户活跃度下降，需要激励手段
+- 核心需求：积分获取、兑换、等级权益
+- 交付时间：4 周
+
+输出：
+- 锁定的目标、范围、成功标准
+- 关键约束和风险识别
+
+### Step 2: /team-plan
+
+**由 Tech Lead 主导，Architect、Project Manager 参与**
+
+输入：
+- PRD 和验收标准
+- 技术约束
+
+输出：
+- 任务分解和角色分工
+- 里程碑和依赖关系
+- ADR（架构决策记录）
+
+### Step 3: /handoff
+
+**角色间交接**
+
+- architect → frontend-engineer + backend-engineer
+- backend-engineer → qa-engineer
+- frontend-engineer → qa-engineer
+- qa-engineer → devops-engineer
+
+### Step 4: /team-execute
+
+**由 Frontend Engineer 和 Backend Engineer 实现**
+
+- 后端：积分服务开发、API 接口、数据模型
+- 前端：积分页面、等级展示、兑换入口
+- 自测和代码提交
+
+### Step 5: /team-review
+
+**由 QA Engineer 主导**
+
+- 测试计划执行
+- 回归验证
+- 质量评估和放行建议
+
+### Step 6: /team-release
+
+**由 DevOps Engineer 主导**
+
+- 发布前检查
+- 环境变更
+- 回滚保障

package/docs/runbooks/dependency-review-gates.md

@@ -0,0 +1,63 @@
+# Dependency Review 门禁手册
+
+本手册承接 `actions/dependency-review-action` 的工程实践，用于把依赖升级、新增包、漏洞和许可证变化前置到 PR 级别检查。它是安全 review 和发布准备的补充，不替代人工安全判断或运行时验证。
+
+## 适用场景
+
+- PR 涉及 `pom.xml`、`package.json`、`go.mod`、`Cargo.toml`、lockfile 或 CI 依赖版本调整。
+- 团队希望在合并前知道“引入了什么新依赖、是否带来已知漏洞、许可证是否变化”。
+- 需要把依赖升级从“代码 review 顺手看看”升级为明确的检查项。
+
+## 不适用场景
+
+- 仓库没有稳定的依赖清单或 lockfile，无法判断真实变更面。
+- 团队还没有定义哪些漏洞级别、许可证类型或来源策略会阻塞合并。
+- 期望只靠依赖扫描结果替代代码级安全 review。
+
+## 推荐落地方式
+
+1. 先明确阻塞策略：哪些漏洞等级、哪些许可证变化、哪些来源风险必须拦截。
+2. 第一阶段优先检查：
+   - 新增直接依赖
+   - 高危漏洞
+   - 明显的许可证变化
+3. 将依赖门禁与安全评审角色、`/code-review`、`/team-review` 的人工判断分层：
+   - 依赖门禁负责发现清单和风险信号
+   - 安全 review 负责判断风险是否成立、是否可接受
+4. 若团队希望把依赖升级从“偶尔集中处理”转成“持续发现 + 分批 triage”，参考 [dependency-update-automation.md](dependency-update-automation.md) 设计分组、自动提 PR 和验证节奏。
+5. 若仓库同时启用了 AI PR review 或 reviewdog，避免重复轰炸：依赖风险结论只保留一个权威展示位。
+6. 结果必须写回 PR 描述、review 结论或发布检查项，不能只停在 action 日志中。
+
+## 最小门禁模型
+
+- `change layer`：依赖清单和 lockfile diff
+- `scan layer`：新增依赖、漏洞、许可证和来源风险检查
+- `decision layer`：安全评审角色、`code-review`、`tech-lead` 决定是否阻塞
+
+先把“发现”和“决策”分开，避免把扫描器当成最终审批者。
+
+## 重点检查项
+
+- 是否新增了直接依赖或关键传递依赖
+- 是否引入高危 / 严重漏洞
+- 是否出现许可证从宽松到受限的变化
+- manifest 与 lockfile 是否一致更新
+- 开发依赖是否意外进入运行时依赖面
+
+## 反模式
+
+- 只看“有几个警告”，不分析哪些会真正影响本仓库。
+- 升级依赖却不更新 lockfile，导致本地和 CI 解析结果不一致。
+- 让 dependency gate 替代人工安全 review，以为“没报警就一定安全”。
+- 明明是依赖来源或许可证问题，却只在发布时才第一次发现。
+
+## 输出回落
+
+- PR 阶段：把新增依赖、高风险漏洞、许可证变化写入 PR 描述或 review 结论。
+- 评审阶段：在 `/team-review` 中说明哪些问题来自依赖门禁，哪些经人工判断后仍需阻塞。
+- 发布阶段：若依赖风险被有条件接受，必须回写到 `/team-release` 的风险、放行结论或观察项。
+
+## 参考来源
+
+- [actions/dependency-review-action](https://github.com/actions/dependency-review-action)
+- [dependency-update-automation.md](dependency-update-automation.md)