@zmice/zc 0.1.1 → 0.2.1

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

@@ -0,0 +1,417 @@
+# CI/CD 与自动化
+
+## 概述
+
+自动化质量门禁，确保任何变更都必须通过测试、Lint、类型检查和构建才能进入生产环境。CI/CD 是所有其他技能的执行保障 — 它能一致地、在每一次变更上，捕获人类和 Agent 遗漏的问题。
+
+**左移原则（Shift Left）：** 尽早在管道中捕获问题。Lint 阶段发现的 bug 只花几分钟修；同样的 bug 到生产环境要花几小时。把检查往上游推 — 静态分析先于测试，测试先于 Staging，Staging 先于生产。
+
+**更频繁更安全：** 更小的批次和更频繁的发布降低风险，而非增加风险。3 个变更的部署比 30 个变更的部署更容易调试。频繁发布本身会建立对发布流程的信心。
+
+## 何时使用
+
+- 为新项目搭建 CI 管道
+- 添加或修改自动化检查
+- 配置部署管道
+- 变更应触发自动化验证时
+- 调试 CI 失败
+
+## 方法原则
+
+- 先建设最小可维护门禁，再按风险逐层加严；不要一开始堆满难以维护的检查
+- 自动化门禁要服务当前目标，避免为低价值信号引入高维护成本
+- 对已发布行为保持 drift control：代码、构建、契约、文档基线一旦变化，都要有明确校验点
+- 管道配置应保持外科式修改，避免为了补一个检查把整条流水线重写
+
+## 最小可维护门禁
+
+默认先确保下面这组门禁稳定可运行，再决定是否增加更重的环节：
+
+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
+```
+
+### 数据库集成测试
+
+```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 管理凭据，而非硬编码。这能养成好习惯，防止测试凭据被意外复用到其他场景。
+
+### E2E 测试
+
+```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/
+```
+
+## CI 失败反馈循环
+
+CI 与 AI Agent 的强大之处在于反馈循环。当 CI 失败时：
+
+```
+CI 失败
+    │
+    ▼
+复制失败输出
+    │
+    ▼
+反馈给 Agent：
+"CI 管道失败了，错误信息如下：
+[粘贴具体错误]
+修复问题并在本地验证后再推送。"
+    │
+    ▼
+Agent 修复 → 推送 → CI 再次运行
+```
+
+**常见模式：**
+
+```
+Lint 失败   → Agent 运行 `npm run lint --fix` 并提交
+类型错误    → Agent 读取错误位置并修复类型
+测试失败    → Agent 按 debugging-and-error-recovery 技能排查
+构建错误    → Agent 检查配置和依赖
+```
+
+CI 修复完成后，仍要回到 `verification-before-completion`：重新运行本地最小证明集，确认失败症状消失，再让 CI 作为第二层证据。
+
+## 部署策略
+
+### 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 }}
+```
+
+### 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 分钟窗口）
+    │
+    ├── 检测到错误 → 回滚
+    └── 正常 → 完成
+```
+
+## 发布后 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/ci-cd-and-automation/meta.yaml

@@ -0,0 +1,21 @@
+kind: skill
+name: ci-cd-and-automation
+title: CI/CD 自动化
+description: CI/CD 管道搭建与自动化。在搭建或修改构建和部署管道时使用。用于自动化质量门禁、配置 CI 测试运行器、制定部署策略。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:verification-before-completion
+  - skill:shipping-and-launch
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: ci-cd-and-automation
+  origin_path: skills/ci-cd-and-automation/SKILL.md
+  origin_id: skill:ci-cd-and-automation
+  notes: 基于上游自动化与发布能力整理为中文工作流。

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

@@ -0,0 +1,130 @@
+# 代码审查与质量
+
+## 何时使用
+
+- 合并任何变更之前
+- 完成一次功能实现之后
+- 评估自己、其他代理或人类写的代码时
+- bug 修复和重构之后
+
+## 输入前提
+
+- 已知道这次变更对应的规格或任务
+- 已有测试、构建或其他验证证据可供审查
+- 愿意按问题严重度给出明确结论，而不是泛泛评价
+
+## 执行步骤
+
+1. 先理解变更意图，再看测试和验证证据
+2. 按五个维度审查：
+   - 正确性
+   - 可读性
+   - 架构
+   - 安全性
+   - 性能
+3. 把发现按 `Critical / Important / Suggestion` 分级
+4. 对每条问题给出具体位置和修复方向
+5. 审查结论给出后，要求作者进入 review 响应闭环，逐条收敛问题
+6. 所有 Critical 清零并完成必要回归验证后，才算通过
+
+## 成功标准
+
+- 评审结论基于代码和证据，而不是个人偏好
+- 真正会阻塞合并的问题被明确指出
+- 报告能让作者快速定位问题和采取动作
+- 评审没有用“看起来还行”替代事实判断
+- 审查后的问题处理路径清楚，不把“提了意见”误当成“问题已关闭”
+
+## 相关原则
+
+- 先报问题，再做总结
+- 只评论代码，不评论作者
+- 技术事实高于风格偏好
+
+## 与其他技能的衔接
+
+- 接在 `incremental-implementation` 或 bug 修复之后
+- 安全和性能深挖时可转给对应专项 skill
+- 对验证证据的审查依赖 `verification-before-completion`
+- 审查输出如果产生待修问题，应进入 `review-response-and-resolution`
+
+```markdown
+## Review: [PR/Change title]
+
+### Context
+- [ ] I understand what this change does and why
+
+### Correctness
+- [ ] Change matches spec/task requirements
+- [ ] Edge cases handled
+- [ ] Error paths handled
+- [ ] Tests cover the change adequately
+
+### Readability
+- [ ] Names are clear and consistent
+- [ ] Logic is straightforward
+- [ ] No unnecessary complexity
+
+### Architecture
+- [ ] Follows existing patterns
+- [ ] No unnecessary coupling or dependencies
+- [ ] Appropriate abstraction level
+
+### Security
+- [ ] No secrets in code
+- [ ] Input validated at boundaries
+- [ ] No injection vulnerabilities
+- [ ] Auth checks in place
+- [ ] External data sources treated as untrusted
+
+### Performance
+- [ ] No N+1 patterns
+- [ ] No unbounded operations
+- [ ] Pagination on list endpoints
+
+### Verification
+- [ ] Tests pass
+- [ ] Build succeeds
+- [ ] Manual verification done (if applicable)
+
+### Verdict
+- [ ] **Approve** — Ready to merge
+- [ ] **Request changes** — Issues must be addressed
+```
+
+## 另见
+
+- 更详细的安全审查指导，请见 `references/security-checklist.md`
+- 更详细的性能审查检查项，请见 `references/performance-checklist.md`
+
+## 常见合理化说辞
+
+| Rationalization | Reality |
+|---|---|
+| “能跑就行” | 能跑但不可读、不安全或架构错误的代码，只会制造持续累积的技术债。 |
+| “我写的，所以我知道它是对的” | 作者往往看不到自己的假设。每次变更都值得多一双眼睛。 |
+| “以后再清理” | 以后通常不会来。审查就是质量门槛，应该在提交前清理，而不是之后。 |
+| “AI 生成的代码大概没问题” | AI 代码更需要审查，而不是更少。它会用很流畅的语言包装错误。 |
+| “测试都过了，所以没问题” | 测试是必要条件，但不是充分条件。它们不能发现架构问题、安全问题或可读性问题。 |
+
+## 红旗
+
+- PR 在没有审查的情况下合并
+- 审查只看测试是否通过，而忽略其他维度
+- 没有真正审查就直接说 “LGTM”
+- 安全敏感改动没有安全向审查
+- 大 PR 大到“没法好好审查”
+- bug 修复没有回归测试
+- 审查意见没有严重程度标签，导致不清楚哪些必须修
+- 接受“我以后再修”——通常不会发生
+
+## 验证
+
+审查完成后：
+
+- [ ] 所有 Critical 问题已解决
+- [ ] 所有 Important 问题已解决，或已明确延后并给出理由
+- [ ] 审查意见已逐条进入响应闭环，没有“已读未处理”的项
+- [ ] 测试通过
+- [ ] 构建成功
+- [ ] 已记录验证故事（改了什么、如何验证）

package/vendor/packages/toolkit/src/content/skills/code-review-and-quality/meta.yaml

@@ -0,0 +1,21 @@
+kind: skill
+name: code-review-and-quality
+title: 代码审查与质量
+description: 进行多维度代码审查。适用于合并任何变更之前；也适用于审查自己、其他代理或人类编写的代码，在进入主分支前从多个维度评估质量。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:review-response-and-resolution
+  - skill:engineering-principles
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: code-review-and-quality
+  origin_path: skills/code-review-and-quality/SKILL.md
+  origin_id: skill:code-review-and-quality
+  notes: 结合上游审查方法与本仓库五维度质量门禁整理。