@zmice/zc 0.2.4 → 0.2.6

package/vendor/packages/toolkit/src/content/skills/ci-cd-and-automation/body.md

@@ -1,417 +1,86 @@
 # CI/CD 与自动化
 
-## 概述
+## 角色定位
 
-自动化质量门禁，确保任何变更都必须通过测试、Lint、类型检查和构建才能进入生产环境。CI/CD 是所有其他技能的执行保障 — 它能一致地、在每一次变更上，捕获人类和 Agent 遗漏的问题。
-
-**左移原则（Shift Left）：** 尽早在管道中捕获问题。Lint 阶段发现的 bug 只花几分钟修；同样的 bug 到生产环境要花几小时。把检查往上游推 — 静态分析先于测试，测试先于 Staging，Staging 先于生产。
-
-**更频繁更安全：** 更小的批次和更频繁的发布降低风险，而非增加风险。3 个变更的部署比 30 个变更的部署更容易调试。频繁发布本身会建立对发布流程的信心。
+把质量门禁自动化，让每次变更都能被一致地构建、测试和验证。CI/CD 的目标不是堆检查，而是用最小可维护管道拦住真实风险。
 
 ## 何时使用
 
-- 为新项目搭建 CI 管道
-- 添加或修改自动化检查
-- 配置部署管道
-- 变更应触发自动化验证时
-- 调试 CI 失败
+- 新建或修改 CI pipeline。
+- 添加 lint、test、build、typecheck、安全扫描或发布门禁。
+- 调试 CI 失败。
+- 需要把本地验证提升成团队共享门禁。
+- 部署、preview、release 或 rollback 流程需要自动化。
 
-## 方法原则
+## 快速路径
 
-- 先建设最小可维护门禁，再按风险逐层加严；不要一开始堆满难以维护的检查
-- 自动化门禁要服务当前目标，避免为低价值信号引入高维护成本
-- 对已发布行为保持 drift control：代码、构建、契约、文档基线一旦变化，都要有明确校验点
-- 管道配置应保持外科式修改，避免为了补一个检查把整条流水线重写
+1. 明确要防的风险：格式、类型、测试、构建、发布、供应链、回滚。
+2. 先找现有 CI 文件和 package scripts，不重写整条流水线。
+3. 设计最小门禁：install/cache -> lint/format -> typecheck -> test -> build。
+4. 只在风险需要时增加 integration / E2E / security / bundle / deploy。
+5. 本地先跑等价命令，再改 CI。
+6. 对 CI 失败读取完整日志，定位失败阶段和根因。
+7. 记录门禁语义：smoke、full verify、release check 不要混名。
 
 ## 最小可维护门禁
 
-默认先确保下面这组门禁稳定可运行，再决定是否增加更重的环节：
-
-1. 依赖安装与缓存命中正常
-2. lint / format 校验
-3. 类型检查或等价静态分析
-4. 单元测试
-5. 构建产物可生成
-
-只有当风险或业务性质要求时，再增加集成测试、E2E、安全扫描、bundle 预算、分阶段部署等更重门禁。门禁越重，越要说明它在防什么风险。
-
-## 质量门禁管道
-
-每个变更在合并前必须通过这些门禁：
-
-```
-Pull Request 创建
-    │
-    ▼
-┌─────────────────┐
-│   LINT 检查      │  eslint, prettier
-│   ↓ 通过         │
-│   类型检查       │  tsc --noEmit
-│   ↓ 通过         │
-│   单元测试       │  jest/vitest
-│   ↓ 通过         │
-│   构建           │  npm run build
-│   ↓ 通过         │
-│   集成测试       │  API/数据库测试
-│   ↓ 通过         │
-│   E2E（可选）    │  Playwright/Cypress
-│   ↓ 通过         │
-│   安全审计       │  npm audit
-│   ↓ 通过         │
-│   Bundle 体积    │  bundlesize 检查
-└─────────────────┘
-    │
-    ▼
-  可以审查
-```
-
-**任何已定义门禁都不可跳过。** Lint 失败就修 Lint，不要禁用规则；测试失败就修代码，不要跳过测试。扩门禁前先确认它是否值得长期维护。
-
-## GitHub Actions 配置
-
-### 基础 CI 管道
-
-```yaml
-# .github/workflows/ci.yml
-name: CI
-
-on:
-  pull_request:
-    branches: [main]
-  push:
-    branches: [main]
-
-jobs:
-  quality:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'npm'
-
-      - name: 安装依赖
-        run: npm ci
-
-      - name: Lint
-        run: npm run lint
-
-      - name: 类型检查
-        run: npx tsc --noEmit
+默认顺序：
 
-      - name: 测试
-        run: npm test -- --coverage
-
-      - name: 构建
-        run: npm run build
-
-      - name: 安全审计
-        run: npm audit --audit-level=high
+```text
+install/cache -> lint/format -> typecheck -> unit test -> build
 ```
 
-### 数据库集成测试
-
-```yaml
-  integration:
-    runs-on: ubuntu-latest
-    services:
-      postgres:
-        image: postgres:16
-        env:
-          POSTGRES_DB: testdb
-          POSTGRES_USER: ci_user
-          POSTGRES_PASSWORD: ${{ secrets.CI_DB_PASSWORD }}
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'npm'
-      - run: npm ci
-      - name: 运行迁移
-        run: npx prisma migrate deploy
-        env:
-          DATABASE_URL: postgresql://ci_user:${{ secrets.CI_DB_PASSWORD }}@localhost:5432/testdb
-      - name: 集成测试
-        run: npm run test:integration
-        env:
-          DATABASE_URL: postgresql://ci_user:${{ secrets.CI_DB_PASSWORD }}@localhost:5432/testdb
-```
+升级门禁前必须说明：
 
-> **注意：** 即使是 CI 专用的测试数据库，也要使用 GitHub Secrets 管理凭据，而非硬编码。这能养成好习惯，防止测试凭据被意外复用到其他场景。
+- 它防什么风险。
+- 运行成本和维护成本。
+- 失败时谁能修、怎么修。
+- 是否需要 secrets、服务依赖或浏览器环境。
 
-### E2E 测试
+## CI 失败处理
 
-```yaml
-  e2e:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          cache: 'npm'
-      - run: npm ci
-      - name: 安装 Playwright
-        run: npx playwright install --with-deps chromium
-      - name: 构建
-        run: npm run build
-      - name: 运行 E2E 测试
-        run: npx playwright test
-      - uses: actions/upload-artifact@v4
-        if: failure()
-        with:
-          name: playwright-report
-          path: playwright-report/
+```text
+CI failure loop:
+1. Preserve log.
+2. Identify failing job and command.
+3. Reproduce locally when practical.
+4. Fix root cause.
+5. Run local proof.
+6. Re-run CI / explain why CI is the remaining proof.
 ```
 
-## CI 失败反馈循环
+不要用跳过测试、禁用规则或放宽门禁来掩盖失败。确需降级门禁时，必须写明风险和恢复计划。
 
-CI 与 AI Agent 的强大之处在于反馈循环。当 CI 失败时：
+## 部署与发布门禁
 
-```
-CI 失败
-    │
-    ▼
-复制失败输出
-    │
-    ▼
-反馈给 Agent：
-"CI 管道失败了，错误信息如下：
-[粘贴具体错误]
-修复问题并在本地验证后再推送。"
-    │
-    ▼
-Agent 修复 → 推送 → CI 再次运行
-```
-
-**常见模式：**
+发布管道至少要明确：
 
-```
-Lint 失败   → Agent 运行 `npm run lint --fix` 并提交
-类型错误    → Agent 读取错误位置并修复类型
-测试失败    → Agent 按 debugging-and-error-recovery 技能排查
-构建错误    → Agent 检查配置和依赖
-```
+- 触发条件：PR、main、tag、manual approval。
+- 环境：preview、staging、production。
+- secrets 来源和最小权限。
+- rollback 或 feature flag 策略。
+- release 前后验证命令。
 
-CI 修复完成后，仍要回到 `verification-before-completion`：重新运行本地最小证明集，确认失败症状消失，再让 CI 作为第二层证据。
+高风险发布优先使用小批次、preview、staging、feature flag 和可回滚路径，而不是一次性大改。
 
-## 部署策略
+## 输出契约
 
-### Preview 部署
-
-每个 PR 获得一个 Preview 部署用于手动测试：
-
-```yaml
-# PR 时部署 Preview（Vercel/Netlify 等）
-deploy-preview:
-  runs-on: ubuntu-latest
-  if: github.event_name == 'pull_request'
-  steps:
-    - uses: actions/checkout@v4
-    - name: 部署 Preview
-      run: npx vercel --token=${{ secrets.VERCEL_TOKEN }}
+```text
+CI/CD plan:
+- Risk addressed:
+- Existing pipeline:
+- Proposed gate:
+- Commands:
+- Secrets/services:
+- Failure handling:
+- Rollback:
+- Verification:
 ```
 
-### Feature Flag
-
-Feature Flag 将部署与发布解耦。在 Flag 后面部署未完成或有风险的功能：
+推荐结论：
 
-- **发布代码但不启用。** 尽早合并到 main，准备好再开启。
-- **不用重新部署就能回滚。** 关闭 Flag 而非回滚代码。
-- **金丝雀发布新功能。** 先对 1% 用户开放，再 10%，再 100%。
-- **A/B 测试。** 对比有无该功能的行为差异。
-
-```typescript
-// 简单的 Feature Flag 模式
-if (featureFlags.isEnabled('new-checkout-flow', { userId })) {
-  return renderNewCheckout();
-}
-return renderLegacyCheckout();
-```
-
-**Flag 生命周期：** 创建 → 测试启用 → 金丝雀 → 全量发布 → 移除 Flag 和死代码。永久存在的 Flag 是技术债 — 创建时就定好清理日期。
-
-### 分阶段灰度发布
-
-```
-PR 合并到 main
-    │
-    ▼
-  Staging 部署（自动）
-    │ 手动验证
-    ▼
-  生产部署（手动触发或 Staging 通过后自动）
-    │
-    ▼
-  监控错误（15 分钟窗口）
-    │
-    ├── 检测到错误 → 回滚
-    └── 正常 → 完成
+```text
+Recommendation: <add / change / defer / remove gate> because <风险、成本和被放弃替代方案>。
 ```
 
-## 发布后 drift control
-
-发布不是自动化的终点。对于已经上线的变更，至少补齐以下校验：
-
-- 发布后关键命令或 smoke test 仍然通过
-- 对外契约变化已有对应回归或监控
-- 文档、README、运行说明、发布说明没有落后于实际行为
-- 新增 flag、迁移、临时开关、补丁脚本有清理或追踪计划
-
-如果做不到这些，说明发布后仍存在 uncontrolled drift，任务不能算真正闭环。
-
-### 回滚方案
-
-每次部署都应可逆：
-
-```yaml
-# 手动回滚工作流
-name: Rollback
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: '要回滚到的版本'
-        required: true
-
-jobs:
-  rollback:
-    runs-on: ubuntu-latest
-    steps:
-      - name: 回滚部署
-        run: |
-          # 部署指定的上一个版本
-          npx vercel rollback ${{ inputs.version }}
-```
-
-## 环境管理
-
-```
-.env.example       → 已提交（开发者模板）
-.env                → 不提交（本地开发）
-.env.test           → 已提交（测试环境，无真实密钥）
-CI secrets          → 存储在 GitHub Secrets / Vault
-Production secrets  → 存储在部署平台 / Vault
-```
-
-CI 永远不应持有生产密钥。CI 测试使用独立的密钥。
-
-## CI 之外的自动化
-
-### Dependabot / Renovate
-
-```yaml
-# .github/dependabot.yml
-version: 2
-updates:
-  - package-ecosystem: npm
-    directory: /
-    schedule:
-      interval: weekly
-    open-pull-requests-limit: 5
-```
-
-### Build Cop 角色
-
-指定专人负责保持 CI 绿色。当构建失败时，Build Cop 负责修复或回滚 — 而非导致失败的人。这能防止在"别人会修的"的假设下，坏构建不断累积。
-
-### PR 检查
-
-- **必须审查：** 合并前至少 1 个 Approval
-- **必须通过状态检查：** CI 必须通过才能合并
-- **分支保护：** 禁止对 main 进行 force-push
-- **自动合并：** 所有检查通过且已批准时，自动合并
-
-## CI 优化
-
-当管道超过 10 分钟时，按影响从大到小依次应用：
-
-```
-CI 管道太慢？
-├── 缓存依赖
-│   └── 使用 actions/cache 或 setup-node 的 cache 选项
-├── 并行运行 Job
-│   └── 将 lint、typecheck、test、build 拆分为独立并行 Job
-├── 只运行变更相关的检查
-│   └── 使用路径过滤跳过无关 Job（如纯文档 PR 跳过 E2E）
-├── 矩阵构建
-│   └── 将测试套件分片到多个 Runner
-├── 优化测试套件
-│   └── 将慢测试移出关键路径，改为定时运行
-└── 使用更大的 Runner
-    └── GitHub 大规格 Runner 或自托管 Runner
-```
-
-**示例：缓存 + 并行**
-```yaml
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '22', cache: 'npm' }
-      - run: npm ci
-      - run: npm run lint
-
-  typecheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '22', cache: 'npm' }
-      - run: npm ci
-      - run: npx tsc --noEmit
-
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '22', cache: 'npm' }
-      - run: npm ci
-      - run: npm test -- --coverage
-```
-
-## 常见借口
-
-| 借口 | 现实 |
-|------|------|
-| "CI 太慢了" | 优化管道（见上方 CI 优化），不要跳过它。5 分钟的管道能省下几小时的调试。 |
-| "这个改动很小，跳过 CI 吧" | 小改动也会搞坏构建。而且小改动 CI 本来就很快。 |
-| "这个测试是 Flaky 的，重跑就好" | Flaky 测试掩盖真实 bug，浪费所有人的时间。修掉它。 |
-| "以后再加 CI" | 没有 CI 的项目会累积坏状态。第一天就搭建。 |
-| "手动测试就够了" | 手动测试无法扩展，也不可重复。能自动化的就自动化。 |
-
-## 危险信号
-
-- 项目没有 CI 管道
-- CI 失败被忽略或静音
-- 为了让管道通过而禁用测试
-- 生产部署不经过 Staging 验证
-- 没有回滚机制
-- 密钥存储在代码或 CI 配置文件中（而非密钥管理器）
-- CI 运行时间很长但无人优化
-
-## 验证清单
-
-搭建或修改 CI 后确认：
-
-- [ ] 所有质量门禁就位（lint、类型、测试、构建、审计）
-- [ ] 管道在每个 PR 和 main 推送时运行
-- [ ] 失败阻止合并（分支保护已配置）
-- [ ] CI 结果反馈到开发循环
-- [ ] 密钥存储在密钥管理器中，不在代码里
-- [ ] 部署有回滚机制
-- [ ] 管道在 10 分钟内完成测试套件
+如果新增门禁的维护成本高于它防住的风险，默认先不加。

package/vendor/packages/toolkit/src/content/skills/code-review-and-quality/body.md

@@ -35,6 +35,16 @@
 - 评审没有用“看起来还行”替代事实判断
 - 审查后的问题处理路径清楚，不把“提了意见”误当成“问题已关闭”
 
+## 推荐结论格式
+
+审查结论必须给出可执行推荐：
+
+```text
+Recommendation: <Approve / Request changes / Defer> because <evidence, risk, and trade-off>.
+```
+
+如果请求修改，说明哪些问题阻塞合并；如果批准，说明剩余风险和已验证证据；如果延后，说明为什么延后比本轮修复更合适。
+
 ## 相关原则
 
 - 先报问题，再做总结