Deploy-Guide 工作流
一份元层面的自我解剖

写在开头

这篇文档不是教你怎么装修、也不是讲冰箱板材。它解剖的是"Claude 和 Andy 一起搭建的、把内容自动变成上线 H5 页面的工作流"。

整套系统在 2026 年 4 月 15 日一天之内从单个臃肿 skill进化到 5 个专职 skill + 1 个 orchestrator + 分层记忆系统，当天完成了 4 次真实内容部署实战，其中一次还触发了"用户反馈 → 规则升格 → 下次不再犯"的完整闭环。

这篇文档的目的

1. 穷尽地把流程每一步讲清楚，不遗漏任何细节
2. 诚实地列出优点和缺点，不美化
3. 具体地给出改进方向，不空谈

问题的起源

为什么单一 skill 不够？旧流程有什么痛点？这个工作流的重构是怎么开始的？

2.1 · 旧流程是什么样的

最早只有一个 aliyun-deploy skill，SKILL.md 长达 336 行，里面捆绑了 6 件事：

1. SSH / SCP 部署命令
2. nginx 配置拉编辑推
3. 首页卡片插入规则
4. 近期动态更新规则
5. 字体合规检查
6. 三件套 HTTP 验证

每次部署，我要从头读完 336 行、在脑子里临时拼装步骤顺序、边做边漏。第一次跑 paint-guide 时，因为认知负担太大，出现了至少 2 次 Edit 工具失败（参数名写错成 old_str、全角半角标点不匹配）、差点漏掉首页同步。

2.2 · 痛点的根本原因

2.3 · Andy 的关键观察

用户在 4 月 15 日的对话中提出了四点扩展要求，直接催生了现在的架构：

1. 是否应该有风格选择机制，确保已有分类的内容保持风格统一，新分类能自由创作
2. aliyun-deploy skill 应该只聚焦于部署，不承担其他功能
3. 整个流程可以分别创建 skills 来执行，并且 skill 可以嵌套调用 skill
4. 最关键的：这个工作流要有自己的记忆系统，能够持续进化，犯过的错和成功的 case 都要记住

架构总览

5 个专职 skill + 1 个 orchestrator + 2 个支撑系统（styles / memory）。每个 skill 都有清晰的职责边界。

3.1 · 职责边界（硬规则）

这五条边界是硬规则，每个 skill 的 SKILL.md 的"反模式"段落里都写清楚了"这些事不要做"。

3.2 · 关于"skill 调用 skill"的真相

Claude Code 的 skill 本质是 playbook（写给 Claude 看的操作手册），不是真正的函数调用。所谓 deploy-guide "调用" build-h5，实际上是 deploy-guide 的 SKILL.md 告诉我"现在去调 /build-h5 工具"，然后我在主对话里串起来执行。

Orchestrator 8 Phase 详解

这是整套工作流的核心心脏。每个 Phase 都有明确的输入、动作、输出。

分类决策树
│
├─ 明显匹配已注册分类（主题 + 源路径 + 文件名都指向同一个）
│    → 自动归类，无需问用户
│
├─ 完全新主题（和任何已有分类对不上）
│    → 创建新分类候选 + 向用户确认
│
└─ 歧义（可能 A 可能 B）
     → 列出候选让用户选

Step 1: scp server:/index.html → 本地
Step 2: 5 个并行 Edit
  Edit A0: Hero 全局 stats (R13)
  Edit A:  分类 section-count (+1)
  Edit B:  新卡片插入
  Edit C:  近期动态顶部插入
  Edit D:  footer 导航追加
Step 3: scp 本地 → server:/index.html

build-h5 Sub-Skill 详解

骨架优先 + 预览 + 批次填充的执行引擎。R6 规则的具体落实者。

5.1 · 核心原则：骨架优先

为什么不能一次 Write 一个完整的 2000 行 HTML？三个原因：

1. 视觉方向错了返工成本巨大。写了 2000 行才发现色调不对，要么忍着用，要么全删重来。骨架 700 行可以快速试错。
2. 章节内容的 Edit 是原子操作。骨架完成后，每个章节都是一次独立 Edit，出错只影响那一章，不会污染全局。
3. 预览驱动。骨架 + preview 截图让"视觉对不对"在填充前就有答案。

5.2 · 批次填充的尺寸经验

从 5 次实战看，每批 3-4 章是最优尺寸：

特殊情况：超大章节独立一批。steam-oven-guide 的 Ch4 有 18 个小节，独立成一批处理，避免和其他章节混批导致的复杂度失控。

5.3 · preview_eval 的坑和技巧

• location.href = '...' 不一定跳转，要用 window.location.replace('...')
• window.scrollTo(y) 在 reload 后会被重置，要用 document.getElementById(id).scrollIntoView()
• .fade-in 类靠 IntersectionObserver 在滚动时加 .in，截图前必须 querySelectorAll('.fade-in').forEach(el => el.classList.add('in'))

这些细节都写进了 R12 规则。

homepage-sync Sub-Skill 详解

改首页元数据的单一职责 skill。5 个锚点 + 先拉后推。

6.1 · 5 个锚点

这个 skill 最初只管 4 个锚点，后来因为用户反馈升格出 R13，变成 5 个：

6.2 · 先拉后推的执行逻辑

# 1. scp 从服务器拉最新版覆盖本地
scp -i ~/.ssh/qinan_wang \
  root@8.148.210.114:/var/www/html/index.html \
  /Users/.../qinan.wang/index.html

# 2. Read 确认结构 → 5 个并行 Edit

# 3. scp 推回
scp /Users/.../qinan.wang/index.html \
  root@8.148.210.114:/var/www/html/index.html

# 4. curl 验证

6.3 · 字数计算的公式

R13 规则里定义了正文字数统计命令：

perl -0777 -pe 's{<style[^>]*>.*?</style>}{}gs;
              s{<script[^>]*>.*?</script>}{}gs;
              s{<[^>]*>}{}g;
              s{&[a-z#0-9]+;}{}g' file.html | tr -d '[:space:]' | wc -m

然后按"旧万字数 + 新页面万字数（向下取整）"更新 Hero stats。

aliyun-deploy Sub-Skill 详解

瘦身后的单一职责 skill。只做 ssh + scp + 可选 nginx 更新，不再是什么都做的"万金油"。

7.1 · 瘦身前后对比

剥离出去的职责全部有了新归宿：

• 首页同步 → homepage-sync
• 三件套验证 → page-verify (online)
• 字体合规 / 设计一致性 → page-verify (local)

这不是删代码，是把代码搬家到正确的位置。每段逻辑都找到了它的单一归属。

7.2 · nginx 配置更新的铁律

# 3a. 拉到本地
scp root@server:/etc/nginx/conf.d/qinan.conf /tmp/qinan.conf

# 3b. Read → 用 Edit 工具插入 location 块（在"# Gzip 压缩"之前）
#   location /{slug}/ {
#     try_files $uri $uri/ /{slug}/index.html;
#   }

# 3c. 推回 + reload
scp /tmp/qinan.conf root@server:/etc/nginx/conf.d/qinan.conf
ssh root@server "nginx -t && systemctl reload nginx"

Edit 工具处理缩进和转义比 sed 安全得多，推送前可以 Read 检查结果。

7.3 · 瘦身的意外副作用

page-verify Sub-Skill 详解

双模式检查器。只做检查，不修任何东西——发现问题交给调用方决定。

8.1 · Local 模式（部署前）

输入一个 HTML 文件路径，跑 5 个检查：

L1-L4 是硬检查（FAIL 就停），L5 是警告（提示人工 review）。

8.2 · Online 模式（部署后三件套）

输入 URL，跑 5 个 curl：

第 2 项特别重要——很多时候页面 HTML 能访问，但共享资源挂了导致页面"裸奔"（只有 DOM 没有样式）。裸 grep 没法发现这种情况。

风格注册表机制

把"用什么视觉风格"这件事从"每次即兴发挥"变成"注册表驱动"。

9.1 · 文件结构

~/.claude/skills/deploy-guide/styles/
├── registry.md                    ← 分类↔预设映射表
└── presets/
    ├── andy-lab-warm-paper.md     ← 装修避坑 / 暖纸色系
    ├── andy-lab-tech-report.md    ← Claude Code 解读 / 技术报告
    └── andy-lab-product-card.md   ← 产品与工具 / 产品卡

9.2 · registry.md 的作用

这是一份人类可读的 markdown 表格：

9.3 · preset 文件的内容

每个 preset 描述文件包含：

• 字体组合（Syne / DM Sans / JetBrains Mono）
• 核心 tokens（继承自 /shared/andy-lab.css）
• 辅助色规则（哪些可以定制、哪些禁止）
• 必须引入的 CSS/JS link
• 页面结构骨架（ASCII 树）
• 动效约定
• 语气与文案风格

写得够具体，让我看完就能直接写 HTML，不需要再问"这个预设下 hero 应该长什么样"。

9.4 · 辅助色复用 accent 的沉淀

记忆系统三层结构

让 AI 真正"记得"自己踩过的坑。rules / raw / successes 三层职责分明。

10.1 · 物理结构

~/.claude/skills/deploy-guide/memory/
├── rules.md           ← 正式规则（目前 13 条）
├── successes.md       ← 成功案例索引（每次 1 行）
└── raw/
    ├── 2026-04-15-paint-guide.md
    ├── 2026-04-15-cabinet-guide.md
    ├── 2026-04-15-steam-oven-guide.md
    └── ...

三层的定位完全不同：

• rules.md：必须读，每次 Phase 0 加载。规则的权威源。
• raw/：运行日志，写入多读取少。记录每次跑的细节。
• successes.md：索引用，一行一次运行。回顾性用途。

10.2 · 硬触发 vs 软触发

这个设计避免了我"自作主张判断什么算失误"——我对自己失误的识别能力有系统性偏差（往往觉得自己做得很好），所以必须让用户当最终裁判。

10.3 · 升格门槛

10.4 · R13 升格的完整案例

这是记忆系统第一次完整运转的案例。

13 条硬规则全集

前 8 条继承自历史项目 MEMORY，后 5 条来自 4 月 15 日当天的实战。每条都有来源标注。

5 次实战数据对比

4 月 15 日当天跑了 5 次部署。数据说话，趋势一目了然。

12.1 · 显著的趋势

• Edit 失败次数从 2 → 0 → 0：架构升级后，严格的 rules.md + preset 体系让低级错误消失
• 返工次数从 1 → 0 → 0：骨架优先策略稳定后，视觉方向一次确定
• 源 md → HTML 行数比：从 paint 的 2.86 降到 cabinet 的 4.4，说明模板化 CSS 组件在复用（每篇新写的 CSS 越来越少）
• 运行体验：paint 感觉紧张磕磕绊绊；cabinet 感觉顺；steam-oven 感觉轻松

12.2 · 时间分布

按 Phase 耗时比例（主观感受）：

Phase 0-1 (Read 规则 + 内容摄入)  ████░░░░░░░░░░░░░░░░░░░░ 10%
Phase 4 骨架 (Write 一次)         ████████░░░░░░░░░░░░░░░░ 20%
Phase 4 预览验证                  ██░░░░░░░░░░░░░░░░░░░░░░  5%
Phase 4 批次填充 (主要耗时)       ████████████████░░░░░░░░ 40%
Phase 5 本地验证                  █░░░░░░░░░░░░░░░░░░░░░░░  3%
Phase 6 部署                      ██░░░░░░░░░░░░░░░░░░░░░░  5%
Phase 7 首页同步                  ████░░░░░░░░░░░░░░░░░░░░ 10%
Phase 8 验证 + 记忆                ███░░░░░░░░░░░░░░░░░░░░░  7%

批次填充仍然是最重的一环——因为内容本身就要写进 HTML 里。

优点分析

8 条真正兑现过的优点，每一条都有实战证据。

缺点 & 痛点

8 条真实的问题。有些是架构局限，有些是 SDK 层面的制约，不美化。

改进方向

按落地难度分三档：下次运行就能做的 / 需要改 skill 架构的 / 需要外部支持的。

结语：这套系统给"AI 协作"的启发

这套工作流从"1 个臃肿 skill"进化到"5 个专职 skill + 1 orchestrator + 记忆系统"花了一天。最大的启发不是架构本身，是这种架构可以被 AI 自己迭代。

16.1 · "playbook 式 skill" 是 AI 协作的合理抽象

传统软件的 function / module 是为"确定性执行"设计的。AI 协作是"非确定性对话"，需要的是 playbook——一份写给 AI 看的"下次怎么做"的手册。

playbook 的好处是可被 AI 自己修改：我犯了错，可以把"这个错别再犯"写进 playbook；下次的我（或者别的 agent）读了 playbook 就会避开。这是一个可自我强化的闭环。

16.2 · 规则升格的门槛是反脆弱的核心

不是每个观察都该变成规则。rules.md 的价值在于"少而精"——13 条每一条都是硬约束，没有"参考建议"。

门槛设计得好：出现 2 次才升格 + 用户反馈直接升格。前者防噪声，后者留出人类裁判的位置。两种机制互补，让规则数量可控。

16.3 · 记忆系统的三层结构可以推广

raw（写多读少）/ rules（读多写少）/ successes（索引）的三层结构不是我原创的，但在这个场景下的运转效果值得记下来。它可以推广到任何"需要从经验中学习"的 AI 系统：

• raw 是"意识流"
• rules 是"反思后的结论"
• successes 是"目录"

这三层必须职责分离。混在一起就会乱。

16.4 · 最重要的一条：人类裁判不可缺席

16.5 · 运行这套系统的 30 秒摘要

如果你只看这一段：

用户: /deploy-guide ~/path/to/content.md

Claude:
  Phase 0: 并行读 rules.md + registry.md + 项目 memory
  Phase 1: Grep 章节 + 分段 Read 内容
  Phase 2: 自动归类 或 提议新分类
  Phase 3: 套用已有预设 或 创建新预设
  Phase 4: 骨架 Write → preview 截图 → 批次 Edit 填充
  Phase 5: 本地字体 + 共享资源 + DOM 检查
  Phase 6: ssh mkdir + scp + 可选 nginx 三步更新
  Phase 7: 先拉后推 + 5 个并行 Edit 更新首页
  Phase 8: curl 三件套 + 写 raw 日志 + 问用户有没有教训

约 15 分钟，happy path 无人工干预。