@colin4k1024/tsp 2.4.1 → 2.4.3

package/docs/runbooks/data-ml-pipeline-walkthrough.md

@@ -0,0 +1,119 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 数据与 ML Pipeline 演练
+
+本文演示一个以数据口径、任务编排、质量校验、回填影响和结果追溯为核心的数据 / ML pipeline 仓库，如何从边界澄清到验证收口完整跑通。
+
+## 1. 场景
+
+- 仓库当前主要维护数据处理任务、特征计算、批处理窗口和结果汇总
+- 团队准备新增一个特征计算任务，并同步补齐质量验证、回填边界和下游影响说明
+- 目标不是改分析台页面，而是把 pipeline 变更治理成可验证、可回溯、可发布的状态
+
+## 2. 推荐链路
+
+1. `/team-intake`
+2. `/team-plan`
+3. `/tdd`
+4. `/team-execute`
+5. `/verify`
+6. `/team-review`
+7. `/team-release`
+
+## 3. 第一步：/team-intake
+
+### 输入示例
+
+```text
+/team-intake
+目标：为数据流水线新增特征计算任务并补齐质量与回填验证
+范围：任务编排、转换逻辑、质量校验、结果汇总、测试计划
+不做：分析台 UI 改造
+约束：必须说明数据口径、批处理窗口、失败重试、回填范围和下游影响
+```
+
+### 期望输出重点
+
+- 识别这是数据 / pipeline 治理任务，而不是普通后端需求
+- 明确参与角色至少包括 `tech-lead`、`architect`、`backend-engineer`、`qa-engineer`
+- 风险应聚焦数据口径不清、回填影响不明、异常样本失控和下游依赖未评估
+
+## 4. 第二步：/team-plan
+
+### 需要拆清的动作
+
+- 任务编排和依赖调整
+- 数据口径与转换边界说明
+- 质量校验、异常样本与重试策略
+- 回填范围、批处理窗口与下游影响
+- review、release 中需要记录的结果摘要
+
+### 合格输出应该回答
+
+1. 哪些改动影响任务编排
+2. 哪些影响数据口径和质量判断
+3. 哪些影响回填和下游结果
+4. 哪些证据需要 verify 最终确认
+
+## 5. 第三步：/tdd
+
+在这类仓库里，`/tdd` 重点是先锁数据与任务完成标准：
+
+- 数据口径和成功阈值是否明确
+- 异常样本、失败重试和回填范围是否明确
+- 哪些结果必须进入 review 或 release
+- 哪些成本或窗口限制需要被记录
+
+## 6. 第四步：/team-execute
+
+执行阶段通常包含：
+
+- 调整任务编排与转换逻辑
+- 补质量校验、异常样本和结果汇总
+- 记录批处理窗口、重试结果和回填影响
+- 更新 review / release 摘要和测试计划
+
+本阶段输出至少应包含：
+
+- pipeline 变更摘要
+- 数据质量与异常样本摘要
+- 回填和下游影响摘要
+- 剩余风险和例外项
+
+## 7. 第五步：/verify
+
+Verify 阶段要回答：
+
+- 任务是否按预期运行
+- 数据质量是否达标
+- 异常样本和失败重试是否可解释
+- 回填范围和下游影响是否被确认
+- 是否满足 release 或继续迭代的条件
+
+## 8. 第六步：/team-review 与 /team-release
+
+### Review 阶段要回答
+
+- 当前是否还存在阻塞变更的质量或口径问题
+- 哪些回填或下游影响可以暂时接受
+- 哪些风险必须进入发布观察
+
+### Release 阶段要回答
+
+- 任务何时上线
+- 批处理窗口和回填窗口如何安排
+- 若结果异常，如何回退任务或暂停下游消费
+
+## 9. 常见错误
+
+- 只看任务运行成功，不看数据质量和异常样本
+- 没说明回填范围和下游影响
+- verify 没有形成正式结论，只留下运行日志
+
+建议配合阅读：[command-and-capability-matrix.md](command-and-capability-matrix.md)、[backend-engineer-daily-operations.md](backend-engineer-daily-operations.md)、[qa-engineer-daily-operations.md](qa-engineer-daily-operations.md)

package/docs/runbooks/data-observability-quality-demo-execution-log.md

@@ -0,0 +1,36 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 数据可观测性与质量平台演示执行记录
+
+本文记录一条数据可观测性 / 质量平台演示路径，重点展示团队如何把规则口径、异常检测、告警有效性和修复责任整理成正式 review 结论。
+
+## 1. 场景定义
+
+- 背景：仓库已维护质量规则与告警链路，但缺少误报 / 漏报和责任路径的正式收口
+- 目标：把质量平台从“规则可运行”升级成“告警可解释、可行动、可 review”的状态
+
+## 2. 关键阶段
+
+- `/team-intake`：锁规则口径、误报 / 漏报和责任路径
+- `/team-plan`：拆规则、告警和 review 收口
+- `/tdd`：先定义异常阈值、处置责任和验证标准
+- `/verify`：汇总异常结果和告警有效性
+- `/team-review`：形成正式优化与推广建议
+
+## 3. 校验结果
+
+```text
+Validation passed.
+- Roles: 8
+- Shared skills: 3
+- ECC skills: 9
+- Private overlay skills: not shipped in public repo
+- Specialist agents: 27
+- Generated artifacts: 70
+```

package/docs/runbooks/data-observability-quality-demo-script.md

@@ -0,0 +1,42 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 数据可观测性与质量平台演示剧本
+
+本文是一份可直接照着讲的演示脚本，面向规则口径、异常信号、告警路径和修复闭环场景。
+
+## 1. 演示目标
+
+- 说明规则命中不等于告警有效
+- 说明 `/tdd` 如何前置锁定误报 / 漏报和处置责任
+- 说明 `/verify` 如何把告警结果转成可 review 的结论
+
+## 2. 演示脚本
+
+### Step 1. 先讲规则与告警不是一个层次
+
+```text
+数据质量平台最容易被误判的是：规则命中了，不代表告警就可行动；没有误报、漏报和责任路径，平台价值不完整。
+```
+
+### Step 2. 用 `/team-intake` 锁边界
+
+```text
+/team-intake
+目标：为数据可观测性平台新增质量规则并补齐告警与修复闭环
+范围：规则定义、异常检测、告警通道、结果汇总、测试计划
+不做：无关分析台 UI 改造
+约束：必须说明规则口径、误报/漏报风险、告警责任和处置路径
+```
+
+### Step 3. 用 `/verify` 收口
+
+```text
+/verify
+请基于当前质量规则改动，输出异常检测结果、误报/漏报、告警有效性和可直接进入 /team-review 的结论。
+```

package/docs/runbooks/data-observability-quality-walkthrough.md

@@ -0,0 +1,86 @@
+---
+version: "0.1.0"
+status: draft
+created: 2026-03-29
+updated: 2026-03-29
+owner: 工程团队
+---
+
+# 数据可观测性与质量平台演练
+
+本文演示一个以规则口径、异常检测、告警路径和修复闭环为核心的数据可观测性 / 质量平台仓库，如何从需求澄清到 review 收口完整跑通。
+
+## 1. 场景
+
+- 仓库当前主要维护数据质量规则、异常检测与告警链路
+- 团队准备新增一条质量规则，并同步补齐告警和处置路径
+- 目标不是改业务页面，而是把异常发现和修复治理成可解释、可跟踪的状态
+
+## 2. 推荐链路
+
+1. `/team-intake`
+2. `/team-plan`
+3. `/tdd`
+4. `/team-execute`
+5. `/verify`
+6. `/team-review`
+
+## 3. 第一步：/team-intake
+
+### 输入示例
+
+```text
+/team-intake
+目标：为数据可观测性平台新增质量规则并补齐告警与修复闭环
+范围：规则定义、异常检测、告警通道、结果汇总、测试计划
+不做：无关分析台 UI 改造
+约束：必须说明规则口径、误报/漏报风险、告警责任和处置路径
+```
+
+## 4. 第二步：/team-plan
+
+### 需要拆清的动作
+
+- 规则定义与阈值
+- 异常信号与告警路径
+- 误报 / 漏报验证
+- review 中的可接受噪音和优化方向
+
+## 5. 第三步：/tdd
+
+重点是先锁：
+
+- 规则口径与阈值
+- 告警是否可行动
+- 误报 / 漏报判断标准
+- 谁来接异常处置
+
+## 6. 第四步：/team-execute
+
+执行阶段通常包含：
+
+- 调整质量规则与检测逻辑
+- 调整告警通道与结果汇总
+- 更新 review 摘要和责任路径
+
+## 7. 第五步：/verify
+
+Verify 阶段要回答：
+
+- 规则是否有效发现异常
+- 误报 / 漏报是否在可接受范围
+- 告警是否能指导行动
+
+## 8. 第六步：/team-review
+
+Review 阶段要回答：
+
+- 当前噪音是否可接受
+- 哪些告警仍需优化
+- 当前是否适合继续推广或放量
+
+## 9. 常见错误
+
+- 只看规则命中，不看告警是否可用
+- 没明确误报 / 漏报的接受度
+- 没有把责任路径写进 review 结论

package/docs/runbooks/demo-deliverables-overview.md

@@ -0,0 +1,278 @@
+# 用户积分等级系统 - 产出清单
+
+> 本文档说明基于示例需求，整个工程会产生什么内容。
+> 场景：用户积分等级系统（4周交付）
+
+---
+
+## 一、最终交付物（结果）
+
+### 1. 代码产物
+
+| 类别 | 交付物 | 位置 |
+|------|--------|------|
+| 后端服务 | 积分微服务（Spring Boot） | `points-service/` |
+| 数据库 | MySQL Schema + 迁移脚本 | `points-service/src/main/resources/db/` |
+| 前端应用 | 积分页面（React + TypeScript） | `points-frontend/` |
+| 契约 | API 契约文档 | `contracts/points-api.yaml` |
+| 测试 | 单元测试、集成测试、E2E | `**/*Test.java`, `**/*.test.ts` |
+
+### 2. 部署产物
+
+| 交付物 | 说明 |
+|--------|------|
+| Docker 镜像 | `points-service:latest` |
+| Helm Chart | `points-service-1.0.0.tgz` |
+| SBOM | `points-service-sbom.json` |
+| SLSA 证明 | `points-service.intoto.jsonl` |
+| 容器镜像签名 | `points-service.sig` |
+
+### 3. 安全产物
+
+| 交付物 | 说明 |
+|--------|------|
+| CodeQL 分析报告 | `reports/codeql.md` |
+| Secret 扫描结果 | `reports/secret-scan.json` |
+| Trivy 漏洞报告 | `reports/trivy.json` |
+| 依赖审查报告 | `reports/dependency-review.md` |
+
+---
+
+## 二、过程中的产物（中间产出）
+
+### 阶段 1: /team-intake
+
+**产出**：
+```
+📄 需求简报 (intake-brief.md)
+   - 目标: 提升用户活跃度 10%
+   - 范围: 积分获取、等级展示（MVP）
+   - 约束: 4 周，与用户中心对接
+
+📋 参与角色清单
+   - tech-lead, product-manager, architect, ...
+
+📝 待确认项列表
+   - 用户中心 API 接入时间？
+   - 积分兑换是否本期？
+```
+
+### 阶段 2: /team-plan
+
+**产出**：
+```
+📄 交付计划 (delivery-plan.md)
+   - 任务分解: T1-T10
+   - 里程碑: M1-M4
+   - 依赖关系图
+
+📊 角色分工表
+   - backend-engineer: T3, T4, T5
+   - frontend-engineer: T6, T7
+   - qa-engineer: T8, T9
+
+⚠️ 风险台账
+   - 用户中心 API 延期 (中/高)
+   - 前端复杂度超预期 (低/中)
+
+📑 ADR-001 (架构决策记录)
+   - 决策: 事件驱动解耦
+   - 证据: 订单系统 QPS 高
+   - 影响: 需要补偿机制
+```
+
+### 阶段 3: /handoff（角色间交接）
+
+**产出**（每次交接）：
+```
+🔄 Architect → Backend Engineer
+   📦 输入: ADR-001, API 契约, 数据库设计
+   📤 输出: 积分获取 API, 等级计算 API
+   ⚠️ 风险: 需要 Mock 用户中心 API
+
+🔄 Backend Engineer → QA Engineer
+   📦 输入: API 实现, 自测报告
+   📤 输出: 测试用例, 集成测试结果
+   ⚠️ 风险: 事件补偿机制复杂
+
+🔄 Frontend Engineer → QA Engineer
+   📦 输入: 积分页面, 组件文档
+   📤 输出: E2E 用例, A11y 报告
+   ⚠️ 风险: Safari 兼容问题
+```
+
+### 阶段 4: /team-execute
+
+**产出**：
+
+#### Backend Engineer
+```
+📂 积分服务代码
+   ├── PointsService.java       # 业务逻辑
+   ├── PointsController.java    # REST API
+   ├── PointsRepository.java    # 数据访问
+   ├── LevelCalculator.java      # 等级计算
+   └── PointsEventConsumer.java # 事件消费
+
+📊 自测报告
+   ├── API 响应时间: P99 < 50ms ✅
+   ├── 幂等性测试: 通过 ✅
+   └── 并发测试: 100并发无竞争 ✅
+```
+
+#### Frontend Engineer
+```
+📂 积分页面代码
+   ├── PointsPage.tsx          # 积分主页
+   ├── LevelBadge.tsx          # 等级徽章
+   ├── PointsHistory.tsx        # 积分历史
+   └── usePoints.ts            # 状态 Hook
+
+📊 自测报告
+   ├── 响应式: 320px-1920px ✅
+   ├── A11y: WCAG 2.1 AA ✅
+   └── 性能: LCP < 2.5s ✅
+```
+
+### 阶段 5: /team-review
+
+**产出**：
+```
+📋 测试报告
+   ├── 契约测试: 24用例 / 100%通过
+   ├── 单元测试: 156用例 / 85%覆盖
+   ├── 集成测试: 32用例 / 80%覆盖
+   ├── E2E测试: 18用例 / 核心路径
+   └── 性能测试: 8场景 / 峰值验证
+
+🐛 问题清单
+   ├── [高] 并发扣减竞争条件 → 已修复
+   ├── [中] 等级边界计算错误 → 已修复
+   └── [低] Safari 响应式问题 → 已修复
+
+📈 质量评估
+   ├── 代码覆盖率: 78%
+   ├── 阻塞项: 0
+   └── 放行建议: ✅ 可以发布
+```
+
+### 阶段 6: /team-release
+
+**产出**：
+```
+📦 发布包
+   ├── points-service-1.0.0.docker
+   ├── points-frontend-1.0.0.tar.gz
+   └── helm-chart-1.0.0.tgz
+
+✅ 发布检查清单
+   ├── SLSA Level 2 ✅
+   ├── SBOM 生成 ✅
+   ├── 镜像签名 ✅
+   ├── 回滚方案验证 ✅
+   └── 监控告警配置 ✅
+
+📝 发布报告
+   ├── 18:00 开始灰度 5%
+   ├── 18:08 扩至 50%
+   ├── 18:15 全量发布
+   └── 18:18 发布完成
+```
+
+---
+
+## 三、记忆与经验沉淀
+
+### Memory Store（~/.claude/memory/）
+
+```
+📂 sessions/
+   └── session_积分系统Demo.json
+       ├── tasks_completed: ["架构设计", "API开发", ...]
+       ├── decisions: [ADR-001, MVP策略, ...]
+       ├── pending_items: ["积分兑换下期", ...]
+       └── key_findings: ["事件驱动可行", ...]
+
+📂 error_experience/
+   └── patterns/
+       └── points-concurrent-race.json  # 错误经验
+           ├── root_cause: "Missing optimistic locking"
+           ├── solution: "Add @Version column"
+           └── success_count: 1
+```
+
+---
+
+## 四、产出汇总图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        最终交付物                                  │
+├─────────────────────────────────────────────────────────────────┤
+│  代码: points-service/, points-frontend/                        │
+│  部署: Docker镜像, Helm Chart, SBOM, SLSA                      │
+│  安全: CodeQL报告, Secret扫描, Trivy报告                        │
+│  文档: API契约, 测试报告, 发布报告                               │
+└─────────────────────────────────────────────────────────────────┘
+                                ↑
+                    ┌───────────┴───────────┐
+                    │      /team-release     │
+                    │    DevOps Engineer     │
+                    └───────────┬───────────┘
+                                ↑
+┌─────────────────────────────────────────────────────────────────┐
+│                      过程产物                                     │
+├─────────────────────────────────────────────────────────────────┤
+│  /team-intake  → intake-brief.md, 待确认项清单                  │
+│  /team-plan    → delivery-plan.md, ADR-001, 风险台账            │
+│  /handoff      → 交接契约 × N (角色间每对交接)                  │
+│  /team-execute → 代码, 自测报告                                  │
+│  /team-review  → 测试报告, 问题清单, 质量评估                   │
+│  /team-release → 发布清单, 检查报告                              │
+└─────────────────────────────────────────────────────────────────┘
+                                ↑
+                    ┌───────────┴───────────┐
+                    │     Memory Store     │
+                    │  session summary     │
+                    │  error patterns      │
+                    │  decisions snapshot  │
+                    └─────────────────────┘
+```
+
+---
+
+## 五、一句话总结
+
+| 阶段 | 主导角色 | 产生什么 |
+|------|---------|---------|
+| Intake | tech-lead | **需求简报** - 锁定目标、范围、MVP |
+| Plan | tech-lead | **交付计划** - 任务分解、里程碑、ADR |
+| Handoff | tech-lead | **交接契约** - 输入输出风险明确 |
+| Execute | frontend/backend | **代码+自测** - 可运行可验证的代码 |
+| Review | qa-engineer | **测试报告** - 质量评估+放行建议 |
+| Release | devops-engineer | **发布包** - 可部署+可回滚+可观测 |
+
+**整个工程的核心价值**：每一步都产出文档化的中间产物，确保可追溯、可审查、可复用。
+
+---
+
+## 六、平台能力升级版 Demo 材料
+
+如果你当前要讲的不是业务系统交付，而是“平台最近新增了哪些命令、skills、runtime 和文档入口”，请不要只用积分系统这个业务 demo。改为搭配下面这组材料：
+
+- [platform-capability-demo-script.md](platform-capability-demo-script.md)：面向讲解人的逐步演示剧本
+- [platform-capability-demo-execution-log.md](platform-capability-demo-execution-log.md)：面向团队同步或复盘的执行记录
+- [github-actions-supply-chain-demo-execution-log.md](github-actions-supply-chain-demo-execution-log.md)：GitHub Actions 与供应链治理场景的 execution log
+- [ai-eval-platform-demo-execution-log.md](ai-eval-platform-demo-execution-log.md)：AI / Eval 平台场景的 execution log
+- [mobile-miniapp-demo-execution-log.md](mobile-miniapp-demo-execution-log.md)：移动端 / 小程序交付场景的 execution log
+- [iac-kubernetes-platform-demo-execution-log.md](iac-kubernetes-platform-demo-execution-log.md)：IaC / Kubernetes 平台场景的 execution log
+- [plugin-extension-platform-demo-execution-log.md](plugin-extension-platform-demo-execution-log.md)：插件 / 扩展平台场景的 execution log
+- [data-ml-pipeline-demo-execution-log.md](data-ml-pipeline-demo-execution-log.md)：数据 / ML pipeline 场景的 execution log
+- [github-actions-supply-chain-demo-script.md](github-actions-supply-chain-demo-script.md)：GitHub Actions 与供应链治理场景的逐步演示剧本
+- [ai-eval-platform-demo-script.md](ai-eval-platform-demo-script.md)：AI / Eval 平台场景的逐步演示剧本
+- [mobile-miniapp-demo-script.md](mobile-miniapp-demo-script.md)：移动端 / 小程序交付场景的逐步演示剧本
+- [iac-kubernetes-platform-demo-script.md](iac-kubernetes-platform-demo-script.md)：IaC / Kubernetes 平台场景的逐步演示剧本
+- [plugin-extension-platform-demo-script.md](plugin-extension-platform-demo-script.md)：插件 / 扩展平台场景的逐步演示剧本
+- [data-ml-pipeline-demo-script.md](data-ml-pipeline-demo-script.md)：数据 / ML pipeline 场景的逐步演示剧本
+- [command-and-capability-matrix.md](command-and-capability-matrix.md)：命令与能力全景图
+- [runtime-capabilities-overview.md](runtime-capabilities-overview.md)：runtime 后台机制说明