Chapter 08 · StoryCam Development Process

Agent Skills、gstack 与 PR Gate 工作流建设

本章记录一次从“要不要安装更多 skills”开始，逐步演化为 StoryCam 自己的 CI、PR 审查、发布和上线后验证流程的工程协作 session。

TL;DR

本章学习目标

识别 skill 的真实价值

学会判断一个 skill 是流程制度、执行工具、参考手册，还是与项目现有机制重叠。

设计 PR 前质量门

理解为什么确定性检查适合 hook/CI，而 AI review 更适合显式触发并留下审查报告。

组合 gstack 与 Codex

把 gstack 的 ship、land-and-deploy、canary 与 Codex 的 code-reviewer/security-auditor/test-engineer 思路分层使用。

从讨论落到项目文件

把抽象流程变成 `.github/workflows`、PR 模板、脚本、docs 和 AGENTS 规则。

让验证结果诚实暴露风险

掌握“流程落地后第一件事就是跑它”，并接受它揭示已有测试失败的事实。

避免过度自动化

理解 commit、push、PR、merge、deploy 这类外部可见动作为什么需要显式确认。

工具、参考图和可视化证据

本章没有围绕一个产品截图调试，而是围绕“工程流程如何被产品化”展开。可视化证据主要是流程图、项目已有 UI flow reference，以及实际新增的质量门文件。

Reference参考仓库：https://github.com/addyosmani/agent-skills
Installed全局安装多组 skills：spec、plan、incremental、TDD、API、source、docs、review、security、debug、performance、shipping、CI。
gstack对照 gstack 的 ship、land-and-deploy、canary、qa、benchmark、checkpoint。
Project落地 StoryCam 自己的 PR gate：CI、PR template、local script、docs、agent map。
Evidence本地验证：lint/build 通过；unit test 暴露 4 个失败。
StoryCam UI flow board
项目已有 UI flow board。它不是本章调试对象，但提醒读者：StoryCam 的工程 gate 必须保护完整的“私密想法 → 故事世界 → 分镜 → 短片 → 最终作品”用户路径。

沿时间排列的原始 Prompt

1. 研究 agent-skills 与 gstack 的互补关系
https://github.com/addyosmani/agent-skills
仔细研究下这个 skills 里的技能都是做什么的，和 gstack 有什么可以互补的？
教师批注：这是本章起点。用户没有直接要求安装，而是先要求“研究”和“互补分析”，说明关注点是能力地图，不是盲目堆工具。
2. 聚焦 implementation 与 TDD 的必要性
incremental-implementation + test-driven-development，这两个一定要都用么？主要功能都是什么？
教师批注：这是第一次范围收敛。用户开始区分“什么时候必须用”和“什么时候不必强行套流程”，这是避免流程形式主义的关键。
3. 全局安装 spec 与 plan 阶段 skills
先全局帮我安装spec-driven-development 和planning-and-task-breakdown
教师批注：用户先安装前置规划类能力，反映出项目已经需要把需求和计划沉淀为可复用流程。
4. 从 planning 进入实现阶段技能选择
现在我已经做完了planning-and-task-breakdown，那还需要安装哪些 skills 比较适合？
好的，那全局安装在 -> incremental-implementation
-> test-driven-development
-> api-and-interface-design
-> source-driven-development
-> documentation-and-adrs
教师批注：这里形成第一条完整开发链路：spec → plan → incremental implementation → TDD/API/source/docs。读者可以看到工具安装是跟项目阶段同步推进的。
5. 进入 Review / Verify / Ship 阶段
https://github.com/addyosmani/agent-skills里Review 类和Verify 类和 ship 类有哪些比较适合安装的，现在项目开发已经到了这些阶段
好的，可以将推荐的 6 个skills 全局安装。同时看看这些 skills （https://github.com/addyosmani/agent-skills ）是不是有对应的 subagent 和 hooks 设计来保证执行效果
教师批注：这是本章的第一个转折点。用户不再只问“装什么”，而是问“有没有 subagent 和 hooks 来保证执行效果”，关注点从知识转向机制。
6. 把 subagent 思想转成 StoryCam PR 流程
现在已经将项目上传到了 github，每次提交pr 还是希望有code-reviewer 等环节，但我用的 codex，看看有什么设计理念可以结合到现在这个项目，比如每次 pr 前是要有 hook 调起code-reviewer
好的，按照这个设计理念迭代下
教师批注：这是最重要的执行 prompt。用户提出了一个具体机制猜想：pre-PR hook 调 code-reviewer。最终方案保留目标，但修正实现方式：hook 跑确定性检查，Codex review 显式触发。
7. 理解 gstack 的发布链路能力
ci-cd-and-automation和shipping-and-launch 这两个 skill 主要做什么的，是否适合融入到我们现在的开发流程中，gstack 里是不是也有类似的技能
那有没有集合 commit-push-pr-更新本地-分辨 worktree 相关的 skills
那我感觉现在的流程也可以，好像安不安装这几个 skills 都没关系？
教师批注：用户逐步意识到“项目流程才是地基，skills 是脚手架”。这是本章第二个转折点：从安装技能转向维护项目自己的制度。
8. 询问 gstack ship / land / canary 的边界
gstack ship 统一 commit/push/PR，这个 skill 具体是什么功能
gstack-land-and-deploy 这个 skill 主要什么功能
gstack-canary呢
教师批注：这一组问题把发布链路拆成三段：创建 PR、合并部署、上线后观察。它帮助团队避免把所有动作塞进一个不可控的大按钮。

时间线

用户原话“仔细研究下这个 skills 里的技能都是做什么的，和 gstack 有什么可以互补的？”
Codex 总结分析 addyosmani/agent-skills 的 20 个技能、3 个 persona、commands 和 references，并与 gstack 的 office-hours、review、qa、ship、land-and-deploy、canary 等能力对照。
结果：形成基本判断：addy 更偏工程纪律，gstack 更偏产品化执行和浏览器/发布自动化。
用户原话“incremental-implementation + test-driven-development，这两个一定要都用么？主要功能都是什么？”
Codex 总结解释两者不是重复：incremental-implementation 负责把大功能切成小步，TDD 负责每个行为的机器证明。
结果：确定“高风险/核心逻辑两者一起用，纯样式或低风险改动不强行 TDD”。
用户原话“先全局帮我安装spec-driven-development 和planning-and-task-breakdown”
Codex 总结使用 skill-installer 从 GitHub 安装两个全局 skills 到 /Users/vc3vc3/.codex/skills/。
结果：项目有了“先写 spec，再拆 plan”的全局 agent 行为提醒。
用户原话“现在我已经做完了planning-and-task-breakdown，那还需要安装哪些 skills 比较适合？”
Codex 总结推荐安装实现阶段的五个 skills：incremental-implementation、test-driven-development、api-and-interface-design、source-driven-development、documentation-and-adrs。
结果：全局形成开发链路：spec → plan → 小步实现 → 测试驱动 → API/官方文档 → 文档沉淀。
用户原话“Review 类和Verify 类和 ship 类有哪些比较适合安装的，现在项目开发已经到了这些阶段”
Codex 总结推荐并安装 6 个 skills：code-review-and-quality、security-and-hardening、debugging-and-error-recovery、performance-optimization、shipping-and-launch、ci-cd-and-automation。
结果：Review、Verify、Ship 阶段的全局参考能力补齐。
用户原话“看看这些 skills 是不是有对应的 subagent 和 hooks 设计来保证执行效果”
Codex 总结确认仓库有 3 个 persona：code-reviewer、security-auditor、test-engineer；/ship 会并行 fan-out 三者并合并为 GO/NO-GO。hooks 主要包括 session-start、source-driven-development cache、code-simplify ignore。
结果：明确 subagent 是 review/ship 的核心机制，hooks 不是主要用来自动触发 PR review。
用户原话“每次提交pr 还是希望有code-reviewer 等环节，但我用的 codex……比如每次 pr 前是要有 hook 调起code-reviewer”
Codex 总结提出三层 PR Gate：本地确定性检查、Codex 显式三角色 review、GitHub CI 强制门禁。反对把 AI review 藏进 git hook。
结果：确定 StoryCam 的 PR review 设计理念：hook/CI 跑机器检查，AI review 由人触发并留下报告。
用户原话“好的，按照这个设计理念迭代下”
Codex 总结新增 GitHub CI、PR 模板、本地 scripts/pr-ready.sh、可选 .githooks/pre-push、docs/PR_REVIEW.md，并更新 AGENTS.md、docs/README.md、docs/QUALITY_SCORE.md。
结果：抽象讨论落成项目文件；本地验证发现 lint/build 通过，unit test 仍有失败。
用户原话“那我感觉现在的流程也可以，好像安不安装这几个 skills 都没关系？”
Codex 总结确认：skills 是脚手架，项目流程才是地基。既然 StoryCam 已经有 docs、CI、PR template、pr-ready、gstack 流程，就不必追求装全。
结果：团队共识从“继续安装技能”转为“维护项目自己的流程”。
用户原话“gstack ship / land-and-deploy / canary 具体是什么功能？”
Codex 总结解释三者边界：ship 负责 commit/push/create PR；land-and-deploy 负责 merge、等待部署、线上验证；canary 负责部署后持续观察页面、console、网络、性能和关键路径。
结果：发布链路被拆成清晰阶段：准备 PR → 合并部署 → 上线后监控。

关键时刻

转折点：从“装哪些 skills”到“如何保证执行效果”

问题不是缺少知识，而是缺少可重复执行的质量门。用户追问 subagent 和 hooks 后，讨论从技能清单转向机制设计。

关键发现：addy 与 gstack 的分工不同

addy/agent-skills 更像工程纪律手册；gstack 更像执行系统。最好的组合是：addy 定义流程，gstack 执行 QA、ship、deploy、canary。

风险判断：AI review 不适合藏进 git hook

AI 审查慢、可能波动、需要上下文，也不适合在 commit/push 这类外部可见动作中悄悄触发。最终选择是显式 Codex PR Gate。

工程现实：流程落地后会暴露已有债务

scripts/pr-ready.sh 一跑就暴露了 4 个单元测试失败。这是好事：质量门的价值就是让“还不能合并”的事实尽早出现。

关键决策表

方案 当时看起来的好处 为什么放弃或保留 最终选择
全量安装 addy/agent-skills 似乎可以覆盖完整软件生命周期。 很多能力与 gstack 或 StoryCam 项目流程重叠；安装本身不能保证执行。 只安装阶段相关 skills，并把关键思想写入项目流程。
pre-push hook 自动调用 code-reviewer 每次 PR 前看似都能强制 AI review。 AI review 不确定、慢、依赖上下文，不适合隐藏在 git hook；本地 hook 也不能代表团队/CI。 hook 只跑确定性检查；Codex 三角色 review 由用户显式触发。
只依赖 GitHub CI 稳定、可强制、所有 PR 一致。 CI 能抓 lint/test/build，但不擅长产品方向、安全边界、可靠性语义和测试覆盖判断。 CI 作为机械门禁，Codex PR Gate 作为语义审查。
用 gstack 完全替代 addy skills gstack 有 ship、qa、canary、land-and-deploy 等执行能力。 gstack 很强在执行，但 addy skills 的工程纪律和 review persona 仍适合做流程参考。 addy 做制度语言，gstack 做执行动作。
让 StoryCam 自己沉淀 PR_REVIEW 文档 项目规则可被人和 agent 共同遵守，且能与 StoryCam 安全/可靠性约束绑定。 需要额外维护，但比只依赖全局 skill 更稳定。 保留并新增 docs/PR_REVIEW.md。

可复用方法

1. Skills 三问法

评估一个 skill 前先问：它是制度、执行器还是参考手册？项目里是否已经有等价机制？它能否留下可验证证据？

2. PR Gate 分层法

把 PR 前检查拆成三层：本地快速检查、CI 强制检查、AI 语义审查。不要把三者混成一个不可解释的大按钮。

3. AI Review 显式触发法

AI review 适合由人发起，并要求输出 GO/NO-GO、blockers、accepted risks、verification evidence 和 rollback plan。

4. 发布链路拆段法

把发布拆成准备 PR、合并部署、上线后 canary。每段有不同风险和工具，不要让一个命令承担全部责任。

5. 项目地基优先法

全局 skills 会提醒 agent，但真正可靠的是项目内的 docs、scripts、CI、PR template 和 AGENTS 触发规则。

6. 质量门反向验收法

新增 gate 后立刻运行。若暴露失败，不要视为流程失败，而是说明流程开始承担“揭示风险”的职责。

工程证据

Branch / Remote

当前分支曾显示为 dev...origin/dev；远端为 https://github.com/nlp-zn/storycam.git。

注意 本章没有记录 PR 编号、commit hash 或部署结果。

全局 skills 安装

已安装：spec-driven-development、planning-and-task-breakdown、incremental-implementation、test-driven-development、api-and-interface-design、source-driven-development、documentation-and-adrs。

Review/Verify/Ship 阶段安装：code-review-and-quality、security-and-hardening、debugging-and-error-recovery、performance-optimization、shipping-and-launch、ci-cd-and-automation。

新增项目文件
  • .github/workflows/ci.yml：GitHub CI。
  • .github/pull_request_template.md：PR 模板。
  • scripts/pr-ready.sh：本地 PR 前 deterministic gate。
  • .githooks/pre-push：可选 pre-push hook。
  • docs/PR_REVIEW.md：StoryCam PR Gate 规则。
更新项目文档
  • AGENTS.md：新增 PR Gate 触发规则。
  • docs/README.md：把 PR_REVIEW.md 纳入文档索引。
  • docs/QUALITY_SCORE.md：新增 PR Gate 最低质量要求。
本地验证

passed bash -n scripts/pr-ready.sh .githooks/pre-push

passed git diff --check

passed pnpm lint，但仍有 2 个 warning。

passed pnpm typecheck

passed pnpm build

failed pnpm test：4 个单元测试失败。

测试失败摘要
  • src/server/storycam/metadataRepositories.test.ts：generation job insert 断言与当前字段不一致。
  • src/server/storycam/storyWorldAssetImageService.test.ts：placeholder image 响应新增/包含 reason 字段，测试预期未同步。
  • src/lib/providers/openrouter/imageProvider.test.ts：representative image provider 的 ready/placeholder 结果与测试预期不一致。
关键命令 
scripts/pr-ready.sh
PR_READY_E2E=1 scripts/pr-ready.sh
git config core.hooksPath .githooks
pnpm lint
pnpm typecheck
pnpm test
pnpm build

后续事项

已完成

  • 完成 addy/agent-skills 与 gstack 的互补分析。
  • 安装开发、review、verify、ship 阶段相关全局 skills。
  • 建立 StoryCam PR Gate 文档与触发规则。
  • 新增 CI、PR template、本地 pr-ready 脚本和可选 pre-push hook。
  • 修复 StoryWorldReview.tsx 中阻塞 lint 的 error。

待确认

  • 是否启用本地 hook：git config core.hooksPath .githooks。
  • GitHub CI 是否需要把 E2E 设为必须检查，或先作为非阻塞观察项。
  • 是否需要把 Codex PR Gate 输出模板进一步写入 PR template。
  • 是否需要安装或定制本地 code-reviewer/security-auditor/test-engineer persona。

后续开发

  • 修复当前 4 个单元测试失败。
  • 处理剩余 2 个 ESLint warning。
  • 为 release 阶段补充 docs/RELEASE.md 或在 docs/PR_REVIEW.md 增加发布 checklist。
  • 在首个正式 PR 中实测：CI → Codex PR Gate → gstack ship → land-and-deploy → canary。