workflow-automation

工作流自动化

将此技能用作仓库的路由优先型周期性工作流自动化锚点。

目标不是倾倒一大堆 Makefile、shell 脚本、钩子配置和 CI YAML。 目标是：

1. 对周期性工作流进行分类，
2. 选择一种主要自动化模式，
3. 确保本地入口、钩子、CI 镜像和定期维护的职责范围明确，
4. 输出一个可复用的方案包，并清楚标明路由出口。

请先阅读这些支持文档：

• references/automation-modes.md
• references/mode-packets-and-route-outs.md
• references/handoff-boundaries.md

如果主要诉求是：

• 机器／运行时配置、本地服务、devcontainer 或跨机器可复现性 → 使用 system-environment-setup
• 部署发布、托管 CI/CD 架构、预览／预发布／生产环境晋级或回滚设计 → 使用 deployment-automation 或 vercel-deploy
• 分支／变基／恢复／推送安全 → 使用 git-workflow
• 测试深度／合并门禁策略 → 使用 testing-strategies
• 运行时遥测／告警／生产环境可见性 → 使用 monitoring-observability

何时使用此技能

• 用一个由仓库管理的可重复命令入口，取代 README 中零散的命令
• 在 package scripts、Make、just、Task、shell 入口、钩子、CI 包装器或维护机器人之间做出选择
• 为仓库设计 setup、bootstrap、dev、test、lint、verify 或 ci 命令
• 明确本地工作流辅助工具与托管 CI 强制措施之间的边界
• 决定重复性杂务应由钩子、任务运行器还是定期自动化处理
• 诊断散布在文档、脚本、钩子和 CI YAML 中的混乱工作流层

何时不使用此技能

• 真正的阻碍是机器配置、服务拓扑、工具链固定或容器／devcontainer 可复现性
• 真正的阻碍是发布／部署架构或云运行时自动化
• 真正的阻碍是 Git 协作／恢复，而非仓库命令设计
• 真正的阻碍是测试策略，而非命令的呈现方式
• 命令已经一目了然，唯一的工作只是简单实现

说明

第 1 步：规范化请求

首先按以下格式记录请求：

workflow_intake:
  primary_goal: task-entrypoints | bootstrap-onboarding | local-ci-parity | hook-guardrails | repo-maintenance | workflow-diagnosis | hybrid
  repo_shape: single-app | app-plus-services | monorepo | library-cli | docs-content | game-project | unknown
  current_surface: package-scripts | make-just-task | shell-scripts | ci-workflows | hooks | bots-schedules | mixed | none | unknown
  main_pain:
    - command-sprawl
    - onboarding-drift
    - local-vs-ci-mismatch
    - interactive-script
    - cross-platform-friction
    - duplicated-logic
    - hook-friction
    - bot-noise
    - unclear-owner
    - unknown
  blast_radius: local-dev-loop | repo-plus-ci | multi-team-repo | unknown
  confidence: high | medium | low

如果请求含糊不清，则采用最小且显而易见的仓库本地周期性工作流解释，并说明这一假设。

第 2 步：准确选择一种主要模式

为当前运行选择一种模式：

1. task-entrypoints — 为周期性人工操作提供一个易记的命令入口
2. bootstrap-onboarding — 首次运行设置、种子数据／初始化，或重复的仓库初始化
3. local-ci-parity — 提供一个本地验证命令，用于镜像 CI 的关键检查
4. hook-guardrails — 提交／推送前的快速本地规范检查
5. repo-maintenance — 依赖更新、定期清理、发布准备杂务、过期事项自动化
6. workflow-diagnosis — 工作流层混乱，需要先简化，再增加自动化

当仓库目前有太多入口，需要先简化再选择新的稳定模式时，使用 workflow-diagnosis。

第 3 步：选择最小化的自动化范围

采用以下默认方案：

• package scripts / Make / just / Task 用于面向用户的入口层
• 钩子 仅用于快速、确定性的防护措施
• 托管 CI 用于强制执行、矩阵、定时任务以及依赖机密信息的工作
• 本地 CI 包装器 用于加快推送前反馈
• 机器人／定时任务 用于周期性维护，而非需要人们每天输入的命令

不要让仓库自动化在无提示的情况下扩展到环境配置或部署架构。

第 4 步：让工作流不变量始终清晰可见

这些规则应在每次回答中保留：

• 优先选择一个清晰的入口，而不是多个文档不完整的入口
• 默认让引导流程具备幂等性且无需交互
• 钩子必须保持简短、确定，并在 CI 中设置对应检查，因为本地钩子可以绕过
• 本地 CI 一致性应覆盖关键检查，而非托管运行器的所有细节
• 定期维护需要明确负责人和审核策略，不能只有机器人配置
• 明确说明本地自动化和托管自动化有意采用不同做法的地方

第 5 步：构建工作流自动化方案包

按以下结构返回：

# Workflow Automation Packet

## Recommended mode
- Mode: task-entrypoints | bootstrap-onboarding | local-ci-parity | hook-guardrails | repo-maintenance | workflow-diagnosis
- Why this mode fits: ...

## Current state
- Repo shape: ...
- Current surface: ...
- Main pain: ...
- Blast radius: ...
- Confidence: high | medium | low

## Recommended surface
- Human-facing entrypoint: ...
- Supporting hooks / CI / schedules: ...
- What stays out of scope: ...

## Safest next move
1. ...
2. ...
3. ...

## Guardrails
- Idempotency / non-interactive behavior: ...
- Local vs CI boundary: ...
- Ownership / review policy: ...

## Route-outs
- `system-environment-setup` when ...
- `deployment-automation` / `vercel-deploy` when ...
- `git-workflow` when ...
- `testing-strategies` when ...

第 6 步：使用模式方案包，而不是庞大的工具目录

从 references/mode-packets-and-route-outs.md 中提取准确的方案包格式。

规则：

• task-entrypoints 应将多个命令整合到一个易于发现、面向用户的入口
• bootstrap-onboarding 必须以验证命令结束，并说明前置条件的边界
• local-ci-parity 必须指出一致性的限制，例如密钥、服务或矩阵差异
• hook-guardrails 必须足够快速，避免贡献者立即绕过钩子
• repo-maintenance 必须包括审核频率、批处理和噪声控制方面的预期
• workflow-diagnosis 必须先简化并去重，再提出增加其他层

输出格式

返回一份简短的 Workflow Automation Packet 或 Automation Hardening Brief。

必备要点：

• 在推荐工具之前先对工作流进行分类
• 选择一个主要模式
• 优先采用最小且实用的接口
• 如实说明本地命令、钩子、CI 和定时任务的边界
• 明确指出转交给其他流程的事项，不要让此技能承担相邻工作

示例

示例 1：杂乱的命令入口

输入：“这个仓库有 README 命令、过时的 Makefile，还有零散脚本。我们需要一套统一、可重复的开发、测试和 lint 自动化层。” 输出方向：选择 workflow-diagnosis，整合为一个面向用户的入口，然后将部署和环境相关事项转交出去。

示例 2：推送前进行本地验证

输入：“开发者总要等推送后才发现 CI 失败。我想要一个能充分模拟 CI、以便提前发现问题的本地命令。” 输出方向：选择 local-ci-parity，添加一个 ci 包装命令，并说明一致性限制，而不是承诺能完整复现 CI。

示例 3：入职流程繁琐

输入：“新贡献者每次切换分支都需要安装工具、复制环境文件、填充数据并运行设置。” 输出方向：选择 bootstrap-onboarding，推荐一个具备幂等性的引导入口，并将广泛的机器和服务设置转交给 system-environment-setup。

示例 4：定期处理仓库事务

输入：“依赖更新和清理任务总被搁置。应该把这些任务放在脚本、钩子还是定时自动化中？” 输出方向：选择 repo-maintenance，推荐使用机器人和定时任务，并制定审核规则，同时将每日开发入口分开。

最佳实践

1. 从重复出现的工作流入手，而不是从偏好的工具入手。
2. 优先采用一个易于发现的入口，而不是多个无人完整维护的接口。
3. 将仓库本地的衔接逻辑与环境、部署、Git 策略和可观测性分开。
4. 将交互式提示视为最后手段。
5. 如果本地与 CI 存在差异，要准确说明差异所在及原因。
6. 在添加更多自动化之前，先简化并去重。

参考资料

• Task: The Modern Task Runner
• Just Programmer's Manual
• mise tasks
• pre-commit
• GitHub Actions documentation
• act documentation
• Development containers