企业官网建设流程全解析

本仓库agent-skills/workflow目录下收录了四类面向真实项目的日常协作技能：进度截图（progress screenshots）、评分到目标（score to target）、发布变更（ship change）与多线程管理（threads manager）。它们把用户在每个线程里反复强调的"给截图、打到 8 分、正确发布、管好其他线程"这几条规则，固化成了可复用的流程与配套脚本。读完本文，你将掌握一套可移植的 Agent 工作流：何时截图、如何锚定评分标准、怎样在不破坏协作的前提下完成一次从提交到上线的完整发布，以及如何审计多个并行 Agent 线程的合并、变更日志与线上健康状态。

一、为什么需要 Workflow Skills

现代 AI 编码 Agent（如 Codex、Claude、Cursor）可以在一个真实项目上并行开展多个线程的修改。但"改完就说"与"真正交付"之间隔着大量琐碎而关键的检查：截图有没有真实呈现、评分有没有标准、提交是否只包含自己的文件、发布是否真的在线上生效、其他线程的工作是否被正确地合并与归档。

agent-skills/workflow/README.md将这些用户在每个线程里重复的规则整理为一组"过程技能"（workflow skills），并强调其可移植性：技能本身不绑定某个具体项目，项目特有的细节（托管方式、变更日志格式、截图存放目录）应写入该项目的AGENTS.md，或放在技能目录旁的本地references/<project>.md中。这个设计让同一套流程可以跨项目复用，同时尊重每个项目自己的规则。

技能速查表

四项技能的配合关系

1. 从第一个可用版本起，就用进度截图持续记录；
2. 当用户提出目标分数时，评分到目标，每一轮都配一张图；
3. 达到标准后，发布变更；
4. 线程管理器最终确认每个线程都按这套流程交付：在main上、变更日志带图、已上线、完成即归档。

二、workflow-progress-screenshots：把"所见"变成证据

核心规则

• 发送而非描述：用宿主工具（SendUserFile或报告内嵌图片）把图真正送到用户眼前，一句话里的路径不算。
• 主动且持续：每个有意义的阶段（第一个可用版本、每个大修复、评分循环的每一轮）都发图，便于用户尽早纠偏；既不要攒到最后一次报告，也不要在每次保存时轰炸。
• 开始、关键时刻、结果：凡是存在 before/after 的变更，都要用相同构图捕获三态——变更前状态、交互瞬间（悬停、瞄准、动画中、面板展开）、最终结果；修复类任务则展示 bug 与修复后状态。
• 只拍真实渲染：必须捕获真实页面/游戏/应用，而不是原型或想象；用 review fixture、URL 开关或调试钩子搭好状态，而不是口头描述。
• 发送前逐张检查：游离的 toast、加载到一半的美术或缺失字体、错误的场景或过期的数字，都意味着需要重拍；图与说明不符就不算证据。
• 说明图片证明了什么：每图一行，如"Before：提示显示 out of range；After：90% hit · 5 damage"。
• 如实标注：明确说明是"headless 浏览器捕获"还是"浏览器视口"；390×844 视口只是手机尺寸的浏览器检查，不是设备测试；脚本编排或摆拍的时刻要标注为 staged。
• 比较需同构图：before/after 用相同视口、相机与状态，并用compare.py并排展示。

捕获方式

• 应用内浏览器面板在可见时可使用；面板隐藏时会卡住requestAnimationFrame并返回过期或黑帧，此时应改用 headless 捕获。
• Headless 捕获：scripts/capture.mjs直接通过 Chrome DevTools Protocol（CDP）截取真实页面，零依赖（Node 22+ 自带 WebSocket）。用法与关键环境变量：

node capture.mjs <url> <out.png|out.jpg> ["<js step>" ...] # WIDTH=1600 HEIGHT=900 SCALE=1 MOBILE=0 视口（MOBILE=1 → 390×844 且 2x 缩放 + 手机 UA） # WAIT_FOR="<js 表达式>" 轮询直到为真再截图（如 "window.__app?.ready"） # SETTLE=1500 加载/等待后的稳定毫秒数（WebGL 场景用 3000–5000） # STEP_WAIT=800 每个 js step 后的等待毫秒数 # CHROME=/path/to/chrome 覆盖浏览器二进制

• 1600×900 用于桌面，MOBILE=1用于 390×844 手机视口；
• SETTLE=3000–5000适用于 WebGL/3D 场景——它们 headless 渲染较慢，拍早了会缺模型、字体和图标；
• 一次只跑一个捕获：繁忙机器上并行 headless Chrome 会产生协议错误、漏帧；
• 从源码看，该脚本会先建临时 profile、用--headless=new启动 Chrome，通过Target.createTarget创建页面并附着会话，执行视口覆盖（Emulation.setDeviceMetricsOverride）、导航、WAIT_FOR轮询、按序执行 JS 步骤，最后Page.captureScreenshot输出 PNG/JPEG（JPEG quality=88）；同时收集Runtime.exceptionThrown与 console error，打印页面错误，因此坏页面会被"抓到"而不是被"拍下"。
• 并排对比：scripts/compare.py将多张图带标签并排放置（before/after 两联，或 start → key moment → result 三联），支持--width 800与--cols N（默认每行最多 3 个面板），基于 Pillow 实现：

python compare.py out.jpg before.png "Before" after.png "After" python compare.py out.jpg start.png "Start" moment.png "Key moment" result.png "Result"

• 动效：静态图会漏掉运动；穿过效果的连续帧短连拍，若应用暴露了页面时钟则放慢它；也可以发一帧条。
• 项目若指定了专用捕获工具（如"use the Codex browser"），就用它。
• 捕获脚本与输出应放在项目内被 gitignore 的目录（如qa/captures/），而不是重启即被清空的 scratchpad。

最终报告中的呈现

• 截图内联在变更摘要之后，逐张配说明；
• 说明哪些是 headless 捕获、手机检查用了哪个视口；
• 无法捕获的内容要说明原因，不可以用文字描述顶替。

三、workflow-score-to-target：把"质量"变成可追踪的分数

用户常以数字设定质量线："score them out of 10. let's get them to 8 out of 10"、"anything less than 6, get them to 6+"。该技能的目标不只是打分，而是达到目标、证明达标、并如实说明短板。

1. 锁定目标与清单

• 复述标准：目标分（6/8/9）以及它作用于每一项还是平均值——"Get them to 8" 意味着每一项都达到 8；
• 列出被评分的每一项（每个技能、每把武器、每个界面元素、每个对象），逐项打分，绝不当作一个整体打分；
• 指明用户对标物（他比较的游戏或网站）：没有基准的 7 分毫无意义；
• 用户设定过一次的标准就是该类工作的长期规则，应记录到未来工作可见之处（项目说明、记忆或测试）。

2. 评分前先锚定评分标准

把量纲写下来，让每个轮次的分数含义一致。默认锚点：

再把每项拆成3–5 条标准，每条 0–2 分，使总分为 10 且每分都有理由。例如：动画看重量与节奏、身体力学、最终姿态、道具、上下文与变化；技能看规则、悬停（落点与数字）、施放（姿态、效果、音效）与可残留可见物；对象看游玩距离上的剪影、材质与细节、融入场景、可读性。凡能测量的标准就测量：脚滑低于行进速度的 10%、武器穿模毫米数、40 局 48% 胜率、28 MB 下载量——数字能防止分数跟着情绪漂移。

3. 基于真实证据诚实评分

• 只依据真实物体的渲染、录屏或测量评分，不看代码、不凭记忆；先捕获状态（见进度截图技能）；
• 改动前先给基线打分：before→after 才是证明；
• 必要时独立评审：把截图交给一个没参与工作的新子代理，给它评分标准与基准，但不要给它你的期望或历史分数；每项尽可能用两位盲审，取较低分或弥合差异；
• 绝不四舍五入凑达标：7.5 分面对 8 分标准就是没达标。

4. 逐轮改进

1. 先修最低分项，再修每项中扣分最多的那条标准；
2. 重新截图，用同一评分标准与评审配置重新评分；
3. 每轮发一张图（开始与结果），并附分数变化，如"Hollow Keeper 3 → 6 → 8"；
4. 当每一项达标即停；若某项因任务外原因（模型上限、美术资源、性能预算）停滞，就如实上报为未达标，附原因与所需条件；
5. 爬分时守住护栏：不要用牺牲性能预算、测试或其他项分数的方式去抬高某一个分数，并注明任何取舍。

5. 锁定成果

• 凡是机器可校验的标准，补一条测试防止静默回退（如七种姿态下武器不穿模、技能有自己的姿态与卡片、胜率不低于 90%）；
• 将记分卡保存到项目内（如qa/<area>/README.md），包含评分标准、每项 before/after、证据与日期，供后续轮次沿用。

报告格式

先给结论："All 49 now score 8 or better; 38 started below 8; the average rose from 6.7 to 8.1."，然后依次给：表格（项、before → after、修复的主要缺陷或仍短的原因，参照templates/scorecard.md）、评分方式（评分标准、基准、评审者——你自己、独立子代理还是盲审——以及依据什么证据）、不完美之处（刚过线但有已知瑕疵的项、仍低于目标的项）、图片（每项或每轮的 before/after）。最后说明分数是判断，哪些标准是实测的，并如实标注截图。仓库还提供templates/critic-prompt.md作为独立评审提示词模板：粘贴进全新子代理后，它要求评审者只依据所见评分、先打开全部证据文件、逐项给出每标准分数与最大扣分缺陷、不四舍五入、不假设证据未显示的内容。

四、workflow-ship-change：从提交到上线的完整发布流程

一个变更只有满足以下全部条件才算完成，报告要逐项展示：

1. 截图：真实渲染的开始状态、关键时刻与结果，内联展示在报告中；
2. 独立的变更日志版本：图片出现在游戏内变更日志页面；
3. 已验证：自己的测试、合入提交的测试、资源检查、在已推送提交上运行的全量测试套件；
4. 已提交：一个内聚提交，只暂存自己的文件；
5. 已推送：以 fast-forward 方式推到main并在 GitHub 确认；
6. 已上线：该精确main的构建已发布并在真实域名上确认可用；
7. 已测量：提交、推送、上传与发布的大小全部实测，而非估算。

推送到项目自己的仓库与上线站点属于长期授权，无需每次询问，除非遇到下文护栏要求停下。开始前先读项目的AGENTS.md与本技能旁的references/<project>.md（若有）；项目规则经常变化，与技能冲突时以项目规则为准。

护栏：停下并询问用户

• 任何超过 50 MB 的上传（git push、Netlify 部署、媒体发布、发往任何外部服务的文件）：先用upload-size.sh（或push-main.sh打印的包体积）测量，询问时说明体积；按整次操作计数，绝不拆分以绕过上限；一次完整的 Supabase 媒体发布（约 861 MiB）必须询问；
• force-push、改写远端历史、改变仓库可见性、推送到其他仓库；
• 新建站点或项目，或改变站点访问、域名、DNS（除非任务恰好如此且用户要求）；
• 权限检查拦截部署、回滚或上传时停下：不要换路径重试、不要借其他线程执行，告诉用户确切的点击路径或命令；
• 发布后线上损坏：报告里首先说明，附实测证据与回滚点击路径，不掩盖。

护栏：绝不

• 绝不发布除干净已推送的origin/main之外的任何东西（无未合入分支、无未提交文件）；
• 绝不用 Netlify 兜底部署大型媒体——媒体放在 Supabase Storage；
• 绝不发布到项目已弃用的宿主，即使旧脚本仍指向它；
• 绝不运行宽泛的图像优化器（pnpm images:optimize或optimize-images.py --apply），它会重写其他会话的待处理图片；改用runtime-assets.py --only '<your glob>'后再--verify；
• 绝不暂存凭据、.env*、node_modules、缓存或构建产物，绝不在共享 checkout 中使用git add -A；
• 本地提交在远端确认之前不叫已推送，部署在域名确认之前不叫已上线；
• 绝不杀死自己未启动的进程：先检查其工作目录lsof -a -p <pid> -d cwd。

操作步骤

步骤 0：开始前。git fetch后git log origin/main --oneline -30并检索自己的区域；查看兄弟 worktree（git -C <wt> diff --stat）是否有人在做同样的修改。在自己基于origin/main分支的 worktree 里工作，其他会话则直接编辑共享 checkout。

步骤 1：截图。用项目 review fixture（?review=<name>）在 1600×900 下捕获真实游戏，取开始、关键时刻与结果三态；项目指定工具则用之，否则用 CDP headless 捕获（见进度截图技能）并说明用了哪种；使用前逐张检查；如实标注（headless 捕获、手机视口不是设备测试）；捕获脚本放在 worktree 内 gitignore 的qa/captures/。

步骤 2：变更日志版本。严格遵循项目的变更日志规则（格式、版本、图片加入方式）；面向玩家写作——他们现在能看到或做到什么，不写文件名或哈希；仅涉及测试、工具、文档或规则的变化不配版本；若其他会话占用了你的版本号，合入时重新编号并保留他们的条目。

步骤 3：验证。过程中随手跑受影响的套件；合入main后用git diff --name-only <old-base> <new-base> -- tests找出合入提交触碰的每个测试文件并运行；发了图片就做图片校验；全量套件在繁忙机器上需 10–40 分钟，用后台运行并读日志，疑似超时的失败要单独重跑再定性；如实报告哪些是全量、哪些是定向，附通过/失败计数。

步骤 4：提交。先确认git diff --cached为空；只暂存显式路径；对暂存内容运行commit-size.sh，其数字进报告；一个内聚变更一个提交，迭代中用一个 work-in-progress 提交 amend 而非堆小提交；消息遵循仓库风格并以系统给出的署名行结尾。

步骤 5：合入并推送。git fetch后git rebase origin/main（共享分支上可 merge）；解决冲突时保留所有人的工作，生成类 JSON（图像审计、清单）取上游文件、重新加入自己的记录并用项目工具重算总数；对每个src与tests文件跑node --check，再运行自己的测试与合入提交的测试；最后运行push-main.sh：

• 拒绝任何非 fast-forward 的推送（用git merge-base --is-ancestor校验，否则退出码 1 并提示先 rebase/merge）；
• 用git pack-objects实测将发送的包体积，超过默认 50 MB（--limit-mb可调）即退出码 3 停下询问，绝不拆分；
• 以--progress推送并抓取 git 的 "Writing objects" 行（即实际发送字节数）；
• 推送后再次 fetch 并确认origin/main等于 HEAD，否则报告 NOT CONFIRMED。

若main移动了，回到步骤 1 重来；在已推送提交上跑全量套件，坏则向前修复。

步骤 6：发布上线。在 HEAD 精确等于origin/main且跟踪文件干净的 checkout 中构建；若构建改动了跟踪文件，先提交并推送该文件再重新构建；用upload-size.sh测量将上传的内容（upload-size.sh dist，以及任何媒体发布），超过 50 MB 停下询问；先部署到草稿/预览 URL，用verify-live.sh检查页面、脚本、美术与 gate 路由，全部通过才转生产——这一步的存在是因为历史上一次生产部署丢掉了 edge function：站点页面 200 而图片全部 404，无人能玩；转正式后在真实域名上再跑一次verify-live.sh，记录部署 ID、发布时间、线上游戏版本与发送字节数；若其他会话在你之后也发布了，只要它也发布的是main就没问题。

从源码看，verify-live.sh会先抓取页面本身的状态码（非 2xx 即坏），再解析页面里的src/href="/..."引用逐一 curl 检查（2xx/3xx 通过），并支持可选环境变量AUTH_PATH（无 token POST：404 说明 gate 缺失、400/401/403 说明 gate 在响应）与PRIVATE_PATH（无会话抓取：期望 401/403 或 3xx；200 说明未设防、404 说明缺失），任何一项失败即输出 "BROKEN: N check(s) failed" 并以退出码 1 拦截生产转正。

报告格式（简短、按序）：① 已推送并确认的提交哈希；提交体积（文件数、总体积、最大文件）与推送体积（发送字节数）；② 上线情况：URL、部署 ID、时间、线上版本、verify-live.sh结果；上传体积（发送字节、构建站点体积、媒体发布）；若未发布说明原因（如"held: needs a media release over 50 MB; asking"）；③ 面向玩家的变更说明 + 变更日志版本与标题；④ 测试：哪些全量、哪些定向，通过/失败计数；⑤ 带说明的截图，标注为 headless 捕获；⑥ 任何推迟或偏离之处及原因。

五、workflow-threads-manager：统筹多线程并行协作

用户会在同一个仓库上并行运行多个 Agent 线程，并让本线程负责跟踪。每次检查回答四个问题：

1. 自上次检查以来什么落到了main上，每个变更是否都有带图片的变更日志条目？
2. 线上是否健康且最新，还是已损坏或落后于main？
3. 每个线程在做什么：运行中、已完成、任务被截断、还是等待用户？
4. 什么可以归档，什么需要用户介入？

若有本项目的references/<project>.md先读它；每次检查都先读项目的AGENTS.md，因为其他线程在不断改规则（线上宿主、变更日志格式、体积上限），与技能冲突时以AGENTS.md为准。

工具

• 会话工具（mcp__ccd_session_mgmt__*，若只显示为 deferred 工具名，先用 ToolSearch 加载）：list_sessions（谁在运行/空闲/固定/已归档）、get_session "self"（本线程自己的 id）、list_events（线程最近转录）、send_message（向线程转达工作或重启它）、archive_session（归档已完成线程）。
• 脚本（负载高时较慢，用后台运行并读输出文件）：
  • repo-status.sh：main在哪、哪些本地分支持有main缺失的提交、哪些 worktree 有未提交编辑（含最新编辑时间，可区分活跃线程与被遗弃线程，并标记锁定 worktree）；
  • audit-changelog.py <since-rev>：检查该修订以来的每个提交——它新增的版本、已发布图片对所需图片的比例、以及 "NO VERSION" 标记；只动测试/文档/脚本的提交标记为 exempt。源码按v('0.1.N', 'YYYY-MM-DD', '<id>', '<title>', '<note>', <big|small>, <commit|null>)格式解析项目内变更日志，big 版本需 3 张图（<id>、<id>-2、<id>-3）、small 需 1 张，并支持--changelog与--pictures参数（默认从origin/main上*/changelog/路径图片最多的目录推断）；
  • live-check.sh [url]：抓取线上页面，再抓取它引用的脚本与美术——页面 200 而美术 404 说明部署已坏；
  • save-captures.sh <worktree> <name>：worktree 有未保存或未合入工作则拒绝（退出码 2）；否则把 gitignored 的截图复制到qa/captures/archived-threads/<name>/——因为归档会话会删除其 worktree 及忽略文件；
  • contact-sheet.py <out.jpg> --count N：把最新 N 条变更日志条目的图片拼到一张联系表，直接读自origin/main。

检查流程

1. git fetch后列出上次检查以来的提交（git log --no-merges <last>..origin/main）；
2. 后台启动audit-changelog.py <last>与repo-status.sh；前台跑live-check.sh（它很快）；
3. list_sessions带上约 20 的 limit 查看所有近期活跃线程；
4. 对每个空闲、未固定的线程用list_events读它如何结束：limit计消息数，最新消息常是工具调用、[result] done标记或孤任务通知；用它打印的before_uuid向前翻页直到该线程的最终报告；
5. 按下表分流；
6. 只归档通过检查的线程，归档前对工作目录是 worktree 的线程先跑save-captures.sh；
7. 按报告格式汇报；
8. 若有新变更，用SendUserFile发送其图片联系表。

分流表

注意：main缺失的分支不等于丢失的工作。标记前先把它提交的主题与后来落到main的内容比对——rebase 前的副本与*-wip分支通常与已存在的变更一致；再检查其 worktree：最近几分钟内被编辑的锁定 worktree 属于运行中的线程，或属于为其工作的子代理。

变更日志缺口

面向玩家的每个变更都必须出现在游戏内变更日志页面并带图（2026-09-27 起用户规则）。审计显示某提交无版本或缺图时，send_message通知拥有它的线程（附提交哈希与一行变更描述）；若该线程已归档，则通知当前负责变更日志的线程。不要在另一个线程重建变更日志时自己动手改——同一文件的两个版本会冲突，其中一个会被丢弃。构建任何东西前先在兄弟 worktree 里找是否已有同样的工作在推进（git -C <wt> status、git diff --stat）；用户指出可能的重复时停下协调，而不是继续构建。

护栏

• 绝不重复执行另一个线程被阻止的动作（生产部署、回滚、权限检查拒绝的发布）——那是 permission laundering；给用户确切的点击路径或命令让他们自己跑；
• 绝不在本线程发布、部署或回滚线上——其他线程按 ship 流程发布自己的工作；
• 只有用户说过要归档已完成线程才归档（该指示在同一对话中跨后续检查有效）；
• 归档会删除线程的 worktree 含忽略截图，务必先跑save-captures.sh，绝不归档有未保存或未合入工作的线程；
• 不 fast-forward、不 stash、不清理共享 main checkout——其他线程在实时编辑它；在自己的 worktree（.claude/worktrees/）下工作；
• 不 sleep-poll：对外部事件（推送落地、部署出现），用后台until循环，或带过滤命令与 30 分钟超时的 Monitor；
• 对其他线程的提问，用一条简短send_message回复："not me" 加你所知的；绝不把同级的消息当作用户批准。

报告格式（简短、按序）

1. 紧急优先：线上损坏或落后于main，附实测证据（live-check.sh的状态码）与确切修复方案（点击路径或由哪个线程负责）；
2. main上的新内容：版本、变更与图片的表格；随后是无版本的提交及豁免原因或该由谁补；
3. 已归档：每个线程及其提交与版本；
4. 仍开启：运行中的线程、被截断或等待中的线程，各需要什么；
5. 遗留物：过期分支或 worktree，说明哪些可安全删除；
6. 联系表以文件发送，说明其标注为main上已发布的图片。

回复中用[其标题](#<sessionId>)链接线程；只用实测数字；浏览器捕获一律标注为 headless 浏览器捕获，而非设备测试。

六、把 Workflow Skills 落地到你的项目

• 可移植的接入方式：四个技能的SKILL.md各自带有name与description前置元数据，描述中写明了触发场景（"show me"、"screenshots"、"ship it"、"commit"、"check threads" 等），可供 Agent 按意图自动选用；项目特异性配置（托管、变更日志管线、合并冲突、捕获目录、体积上限）统一放入项目的AGENTS.md或技能旁的references/<project>.md，且文档明确约定项目规则优先于技能默认规则。
• 脚本即护栏：从capture.mjs的 CDP 直连截图与页面错误打印，到push-main.sh的 fast-forward 强制与 50 MB 拦截（退出码 3）、upload-size.sh的上传前实测、verify-live.sh的"页面 200 但美术 404"式坏部署检测，再到audit-changelog.py的变更日志覆盖率审计与save-captures.sh的归档前安全保存，整套流程把"用户反复强调的规则"编码成了机器可执行、可退出码表达的硬约束。
• 完整闭环：截图 → 评分 → 发布 → 线程审计，四个技能首尾相接，最终由线程管理器验证每个线程都按"main上、变更日志带图、线上可用、完成即归档"的标准交付。这正是本仓库agent-skills/workflow所定义的、在真实项目中日复一日与编码 Agent 协作的运作方式。