Harness Engineering 初次实践总结

一、前言

本文档约 14000 字，快速阅览需半小时，精读需一小时及以上。

除了文中小节 3.5.4 角色深化 依赖 AI 辅助生成以外，这篇文档是我自己纯人工撰写的，是一篇写给 Agent 看的资料，也是写给自己看的总结，用于记录我的失败。

它起源于我的学习目标和其中包含的试炼：一个用于 Harness Engineering 的 Demo 项目：HTML-Slide。

总的而言，我是一名全栈设计师，这意味着我同时具备 UI / UX / Web 的设计能力，也具备一定的前端开发能力，但在整个 Harness 学习项目 HTML-Slide 的初期我没有做精细的人工审查，这导致了一个无法挽回的后果：经过四天的 HITL 虽然项目遵照 PRD 执行推进得很远，但到后面我和我的“赛博员工”们积累下来的问题并不是技术债务，而是要以成倍的努力来挽回架构上的设计失误。

[适用于人类阅读] 这相当于：你计划包点饺子，但你在用玉米淀粉制作面皮。你发现它包起来非常麻烦——饺子皮稍微揉搓两下就断裂了；更要命的是，当你吭哧吭哧勉强包完了饺子，抓起一把下锅水煮的时候，它居然直接在锅里裂成了糊糊；后面你发现，它也不是不能下锅，只是几乎唯一能下的锅只剩蒸锅。最令人绝望的是，冰箱里还有两大袋子包好的淀粉饺子等着你处理。

没错，从一开始选材就出了问题；因此，本文其实是围绕着 可行性评估 的探讨与总结。

二、项目回顾

2.1 项目摘要

• Q：这是一个什么样的项目？

• A：HTML 幻灯片生成器（HTML Slide Generator）是 RainyDesign Lab 板块的工具之一。它是一个纯浏览器端运行的交互式幻灯片编辑器，用户无需登录、无需安装任何软件，即可在浏览器中创建、编辑、预览和导出专业的 HTML 演示文稿。

  这句话是用 Gemini 生成的 Prompt ，在本地用 Codex 跑出来的。就理念而言，这和我的愿景高度一致。

项目耗时： 2026 年 6 月 6 日至 6 月 9 日，共计 4 天

项目 Agent：Codex

接入 LLM：GPT 5.5 与 Deepseek-v4-pro ，对照开发

指导老师：Gemini 3.1 Pro

消耗 Token 数：100M 上下

项目状态：搁置并归档

项目后续：将已有内容沉淀，作为第二轮项目重写的基石

参考文献：

Harness design for long-running application development - Anthropic

Harness engineering: leveraging Codex in an agent-first world - OpenAI

2.2 沙盒结构

该结构参考 GPT5.5 及 Gemini 3.1 Pro Extended 的建议建立。

代码已复制！
/sandbox
├── .codexignore
├── .gitignore
├── .env
├── AGENTS.md                                  # 路由文件（空白，或在开发中期作为索引，指向重要事实路径）
├── planner_system.md                          # Planner 文档
├── generator_system.md                        # Generator 文档
├── evaluator_system.md                        # Evaluator 文档
├── orchestrator.py                            # 自动化
├── projects/
│   └── rainydesign_v2/
│       ├── rainydesign_strapi_v2/             # 真实 Strapi 后端，Agent 无权读写
│       └── rainydesign_nextjs_v2/             # 真实 Next.js 项目
│           ├── src/                           # source 路径，Generator 部分可写
│           └── ../                            # 其他目录
├── agent-logs/                                # 自动化工作时存储的日志路径
├── docs/                                      # Planner 产出（PRD，架构，语言文档，Sprint 计划）
│   ├── DESIGN_LANGUAGE.md                     # 设计语言文档
│   ├── architecture_lab_slide_generator.md    # PRD 与 总施工方案
│   └── sprints/                               # Sprint 计划
├── tests/                                     # Evaluator 产出（审计报告）
├── references/                                # 外部资料（暂未使用，如对应技术栈版本的官方手册、可用静态资源等）
├── temps/                                     # 临时内容（已忽略，手动备份与临时文件）
└── other(user_only)/                          # Agent 禁区（已忽略）

2.3 项目结构蓝图

与最终结果有差异，不过由于存在设计缺陷，蓝图仅供参考。

代码已复制！
src/                                        # 位于上文所述的 Next.js 项目根目录下
├── pages/
│   └── lab/
│       ├── index.js                        # Lab 首页（工具列表 Hub）
│       └── slide-generator.js              # 幻灯片生成器页面
├── components/
│   └── lab/
│       ├── shared/                         # Lab 通用组件
│       │   ├── LabHeader.js                # Lab 统一头部
│       │   └── ToolCard.js                 # 工具卡片（Lab 首页用）
│       └── slide-generator/                # 幻灯片生成器专属组件
│           ├── SlideGeneratorShell.js      # 页面外壳（Layout + 工具栏集成）
│           ├── SlideContext.js             # Context + Reducer（299 行）
│           ├── SlideEditor.js              # 代码编辑器（HTML/MD 双模 + Templates + Layouts）
│           ├── SlidePreview.js             # 预览面板（桌面/平板/手机 三档）
│           ├── PreviewFrame.js             # sandbox iframe（contentWindow.document.write）
│           ├── SlideThumbnails.js          # 底部缩略图列表（拖拽排序容器）
│           ├── SlideThumbnail.js           # 单个缩略图（拖拽源 + 删除）
│           ├── PresentationMode.js         # 全屏演示模式（键盘翻页 + 备注）
│           ├── ThemePanel.js               # 主题选择面板（6 套主题色块预览）
│           └── ExportPanel.js              # 导出设置面板（文件名/作者/下载）
├── lib/
│   └── lab/
│       ├── themes.js                       # 6 套主题定义（CSS Variables）
│       ├── i18n.js                         # Lab 国际化文案（en + zh-CN）
│       ├── exportHTML.js                   # 导出 HTML 文件生成器（310 行，含导航/打印）
│       ├── layouts.js                      # 12 套专业布局模板（Hero、画廊、对比表等）
│       └── markdownUtils.js                # Markdown↔HTML 双向转换 + 8 种内容模板
└── styles/
    ├── lab/lab.css                         # Lab 专属样式与动画
    └── ...

2.4 策略与过程

2.4.1 技术方向与标准

• PPT / Slide 可以导出，因此需做 HTML5 + CSS3 + 原生 JS 友好
• 页面及编辑器基于 React 管理状态，采用 Next 组件构建，底层语法为 JSX
• 实现层尽可能兼容 Tailwind CSS v4，支持 Markdown 输入

2.4.2 推进过程

• 施工前：Harness 教学与落地实践
  1. 教学阶段 —— 开发者认知构建：Harness Engineering 知识汇总、沉淀与吸收；
  2. 沟通阶段 —— 底层依据构建：项目沙盒、基础 Skills 与 Planner / Generator / Evaluator 三大 Roles 建立，以遵循 Anthropic 有关 Harness Design 的文摘要点，进行概念对齐；
  3. 准备阶段 —— 项目初始化：基础文件与环境搭建，项目引入至专用目录，沙盒 Git，与 Planner 沟通需求以生成项目 PRD。
• 施工中：
  1. 起步阶段 —— Sprint 1 - 入口与框架建立：开发 lab 页面作为入口，实现幻灯片页基础功能，可用 Markdown 与 HTML 生成 iFrame 预览 Slide；
  2. 完善阶段 —— Sprint 2 ~ 5 - 新特性加入：
     • 已实现：主题、页面排序、演示模式、键盘翻页、导出功能、自动保存、撤销重做、内容模板、i18n、响应式适配、翻页动画等一系列功能；
     • 未实现：悬浮工具栏、高级样式面板、全局按需字体、情景动画、资产注入、斜杠快捷输入、缩略图、全屏编辑、装饰与导航模块、编辑器选项卡、元素动画顺序、添加时可选预设幻灯片类、新幻灯片可选预设全文档。
     • 自动化：Sprint 5 全面采用，但效果脱离预期。事到如今即便采用 HITLHuman-in-the-Loop，即人机回环，一种将人工监督与决策融入自动化流程的 AI 设计模式。该系统并非完全自主运行，而是在输出结果时暂停，由人工进行审查、编辑或批准。这种方式确保了责任落实、安全性以及高准确性。 模式，就结果而言意义不大。
  3. 打磨阶段 —— Sprint 7 及后续项目：迭代不会到来，因为开发即将停止。
• 项目停摆：
  1. 决策阶段 —— 思考：复核现有工作进度以及技术债务，以此评估后续开发的难度。答案是毋庸置疑的：用更细致的项目规划，制订第二版 PRD 并从头来过，会比遵循既定的错误技术路线前行要来得更准、更快、更顺畅；
  2. 归档阶段 —— 资产审查与沉淀：人工审查文稿与代码，拣选可参考或复用部分，然后整个沙盒备份，与 Codex Projects 一并归档，项目目录不做回滚、与 Git 仓一并废弃，克隆最新的项目原始代码，以作后续的实验性开发基座；
  3. 停止阶段 —— 项目调停：未完成收尾。进度废弃，不会再有任何后续产生；沉淀的资产作为孕育新项目的土壤，为后者提供经验参考与技术支持，而本篇文档正是在此阶段中撰写完成的。

2.4.3 阶段 SOP

• 人工传递：
  1. 人工编辑 prompt， 与 PRD 一并发送给 Planner，Planner 遵循 prompt 中指定的状态开始工作，调用该状态可用的技能与目录，生成阶段 Sprint 文档；
  2. 人工编辑 Prompt ，与 Sprint 文档一并发送给 Generator，项目自动开发，得到日志与项目开发进度；
  3. 收集结果并发送至 Evaluator，Evaluator 开始审计，得到日志与审计报告；
  4. 提交审计报告给 Generator 按需改动，更新结果后随日志发送给 Evaluator 进行审计；
  5. 重复上述步骤 2,3,4 ，直至审计通过，执行人工校验，并按需自动开发及重申。
• 自动化 Sprint：
  1. 设计 orchestrator ，以直接接入 LLM API 并赋予权限、工具库与循环；
  2. 完善相关文档以尽可能脱离人工生成 Prompt 干预，尽可能以恒定的文档作为当前 Sprint 的核心来源事实；
  3. Generator 读取相关文档作为能力、权限边界与事实依据，执行开发步骤，完毕后提交并结束会话；
  4. Evaluator 读取相关文档，执行审计步骤，生成审计文档后结束会话，如打回则执行下个步骤实现循环，反之则结束自动化；
  5. Generator 依照文档声明的路径与规则读取 Evaluator 生成的最新报告，确认结果为 STATUS: REJECTED ，则按报告内容进行改动，再度提交并结束会话；
  6. Evaluator 执行步骤 4， 不同点是：打回次数如果大于 max_attempts 最大重试次数（默认为5），则强制中断该 Sprint 以避免无人值守时死循环烧干 API 额度，并以未完成状态结束工作流。
  7. Generator 执行步骤 5。

2.5 问题描述

以下问题按阶段排序：

• 讨论阶段——需求错误导致：
  • 需求错述：
    1. 要求加入 Markdown 编辑器；
    2. 完全不使用新依赖（禁止添加第三方库）。
  • 实际情况：
    1. Markdown 需与编译后的 HTML 双向绑定，直接转换非常不稳定，bug 层出不穷；
    2. 幻灯片所需的结构依赖大量非标 Markdown 格式元素与属性，不适配需标准格式化的 Markdown ；
    3. 为兼容上述特性而开展独立开发，则 HTML 元素一并转译的成本将极为高昂。
• 开发初期——没做人工审核 PRD + 实践可行性评估导致：
  • 技术错估：
    1. 使用 iFrame 预览即时渲染内容，并要求其可以点击预览中的元素以弹出属性框，并作属性修改；
    2. 使用 HTML 布局模板，混合 Markdown 作为输入源。
  • 实际情况：
    1. 点击属性时修改输入框中的 HTML 元素的 tailwind utitlies ，这不仅要在原有“Markdown 编辑模式 + HTML 编辑框”双向绑定的基础上，额外增加对 iFrame 的绑定，而且这种多重绑定极易引发跨域技术难题，更带来了严重的状态同步隐患；
    2. HTML 布局模板和 Markdown 完全不兼容，再结合上述技术痛点，使用布局 + 预览修改 = 放弃 Markdown 输入，所以索性砍掉这一功能。
• 开发后期——方向不对，努力白费：
  • 边界错估：
    1. 以纯文本文档作为事实依据，要求 Agent 顺利推动每个阶段的开发与审计；
    2. 每个 Sprint 及子项目人工收集日志、文档与报告，连同人工核查的错误一并提交给 LLM 进行回顾与评审；
    3. Sprint 5 实现完全自动化，通过为各个角色分配信息源以读取角色系统、Sprint 规划、设计语言文档，遵照文档所示进行自主循环，直至整个 Sprint 完成后人工验收结果。
  • 实际情况：
    1. 内容过于抽象，结果难以预测：一些场景没有画面、只有文字，未用面向 LLM 的 Prompts 清晰描述，颗粒度不够细、指标界定也不清晰；在强调视觉交互的任务中，Generator 接收过多抽象输入，方向不可控、实现不稳定，导致 Sprint 4 人工介入回滚重跑十数回，结果还都参差不齐，直至呼出 Planner 生成界定用的设计语言文档，才平息了用户与 Generator 的赛博纷争；
    2. 未关注信息源，与 Prompts 割裂：Agent 遵守 Prompts 中提到的 Role & Rules 作为权威信息源（The absolute source of truth）开展工作，但由于长时间没有人工复审，导致长期依赖 Prompts 、PRD、设计语言、Sprint 文档的条目略有不一致就变成了信息源投毒，进一步加大了生成结果的的不确定性；
    3. Harness 经验缺乏，忽略正向反馈陷阱：如果输入不包含事实性错误，仅存在优劣或恰当与否的情况，则三个角色与作为导师的 LLM 往往会给出正向反馈——即先肯定文档、再补充意见；由于本人对 Harness Engineering 经验的缺失，导致在 LLM 参与各阶段的回顾与需求评审时，我只提交上述有误的信息源，但没有提出开放性询问与要求 LLM 回复包含布尔类型，直至我提出如 “是否应该放弃 iFrame 跨域传值、转投页内双向绑定？或你有其他更好的建议吗” 这样的问题，它们才会下结论、做对比。

三、重写规划

3.1 资产回顾

虽本次教学性质的实验性项目以失败告终，但依然存留了一定价值丰富的、可用作重写参考的关键资产。

• /doc/architecture_lab_slide_generator.md：HTML Slide 项目的 PRD，用作项目各纬度信息讲解，由 Planner 在项目开始前根据用户的需求生成，适用于“人类总工”阅读，也适用于“赛博员工”参考，使 Generator 遵循规则开发、减少护栏跨越，并使 Evaluator 对每个 Sprint 的成果审核有据可考，从而给出更准确的判断依据；

• /doc/DESIGN_LANGUAGE.md：项目设计语言文档。项目推进至 Sprint 2 ~ Sprint 3 时，由于 Generator 缺乏视觉指南作参考，产出的布局模板、背景等内容在美观度方面频频脱离预期。该文档由 Planner 引入用户 Prompt + PRD + 现有进度 + 日志与各类参考资料生成，其规定了一套设计语言系统，有助于 Agent 建立统一的视觉要素开发标准、减少感官偏差，同时也给了 Evaluator 更明确、更严格的设计要素审计标准，以收束预期结果至指定标准与范围内。

• /planner_system.md、/generator_system.md、/evaluator_system.md：三个角色文件，分别对应不同的工作模式和“赛博岗位”。它们需要在每一轮任务的 prompt 中被指定为相关的角色并读取对应文档，然后再结合上述两个文档作为唯一事实来源进行逻辑推理，从而完成各自相关的任务。

• /orchestrator.py：于 Sprint 5 初期开始试行的自动化脚本，即上文项目流程中所述的自动化 Sprint。

  其他文档的参考价值相对较小，此处不做提及。

3.2 验收标准

3.2.1 一期目标

满足上线并开源所需的基础功能与技术要点，全面采用数据驱动（Data-Driven）架构。

• 搭建 Lab 页面，实现实验性工具卡片，指向 HTML-Slide 入口；
• 确立以 JSON Schema 为核心的单一数据源，数据完全依赖 local-storage 存储 [1]；
• 搭建 HTML-Slide 页面，自动隐藏导航栏与页尾 [2] ，于整个浏览器窗口内编辑幻灯片；
• 首次编辑 / 新项目状态下为引导模式，展示 12 个不同字体与颜色的主题 [3]；
• 选择主题后提供三个快速开始选项（一键加载预设的 JSON 数据树），或者点击新建幻灯片从零开始；
• 新建幻灯片可挑选 25 + 主流布局（通用、报告、网页等），点击即刻生成对应的区块数据（Blocks）；
• 选择后进入编辑页面，采用经典 PPT 编辑布局 [4] ，且每个元素都可以被点击，点击后将映射到具体的 JSON 节点，并可通过属性面板修改其数值 [5] ；
• 可为页面添加过渡动画，并为页面内的元素配置动画与触发条件（点击时 / 跟随上一个 / 延时毫秒），动画状态同样作为属性写入数据源；
• 可做全屏预览，更可导出为纯 HTML（支持在各类设备上脱机播放，快捷播放动画与翻页 [6] ）；
• 编辑器各环节加入适量动画，使交互体验丝滑顺畅；
• 符合 i18n 规范，使用简体中文 / 英文两种语言；
• 支持下载为 HTML 与 PDF 功能。

[1]：编辑器仅依赖浏览器本地存储，且仅从 CDN 下载必要资源，不向服务器发送任何数据。核心状态池采用 Zustand（或类似轻量库）管理强类型的 JSON 数据，UI 仅作为数据的映射视图。

[2]：该功能通过 React Router 判断当前页面的位置，为 Nav.js 与 Footer.js 添加 Tailwind CSS Utilities hidden 以实现，免去页面跳转的重渲染。

[3]：主题和布局完全解耦：主题映射为全局的 CSS Variables（控制颜色与字体），布局映射为局部的 JSON 结构（控制组件排版）；两者互不干涉。

[4]：即：最上方为属性栏，默认 disabled，选中元素时唤醒 [5] 提到的可用属性；下方左侧为页面缩略图；右侧分为上下两部分，上方为主视图（同构渲染区），下方为备注/数据窗格（选项卡设计，可切换至代码模式，实时预览当前幻灯片的底层 JSON 结构或只读文档结构）。

[5]：通用：大小、颜色、上下边距、动画；文字：字号、行高、字间距、字体。每一个属性都以 Tailwind 预设 Utilities 为基准并受限，用户在面板上的操作本质上是改变节点 JSON 中的 className 配置集。坐标暂不支持任意修改以防布局崩坏。

[6]：预览操作方式：键盘上下 / 屏幕上下滑动为下一张页面，键盘左右 / 屏幕轻触为下一个元素动画；若当前为当前页面的首/尾动画，则执行跨页翻转。

3.2.2 二期目标

添加新特性以及精细打磨项目。

• 新特性：拆分布局为导航、正文与页尾，提供 12 种不同风格与排版方式的导航与页尾 [1] ，同时在备注/代码窗格增设选项卡，供高级用户检阅对应结构；
• 新特性：支持无损读档（文件逆向解析）[2]。在引导模式页加入拖拽上传 + 选择文件上传提示框，上传导出的文件即可继续编辑；
• 新特性：大模型提词器 [3]。在导出按钮和引导模式边增设入口，允许利用 AI 极速生成幻灯片；
• 新特性：自定义主题，即自定义颜色与字体（URL引入）。数据一并合入 local-storage 存储，也可随产物一并打包。
• 优化：于本地 Lighthouse 结果中尽可能获取性能、可访问性、最佳实践和 SEO 的高分，其中后两者必须满分； ……（未完待续）

[1]：风格不同如：1) 下划线导航 + 极简页尾；2) 毛玻璃导航条 + 简易页尾 + 纽扣按钮页码； 排版不同如：1) 导航在上、页尾在下；2) 导航在左、页尾在右；3) 导航在右下角，页尾在左下角 等等。

[2]：读档技术实现：一期导出的文件中，将隐式注入一份完整的 JSON 状态副本（作为纯文本数据块附加）。系统只需读取该 JSON 即可 100% 还原编辑状态，彻底避免复杂的节点逆向解析。

[3]：使用方法：将用户文稿 + 预设 Prompt 一并发送给 Deepseek-v4-pro 等模型，得益于本项目的纯数据驱动架构，模型只需输出符合我们 JSON Schema 规范的纯数据，编辑器接收后即可瞬间渲染出排版精美的幻灯片，规避了 AI 生成非标代码的幻觉风险。该功能将配备悬停 Popup 解释说明。

3.3 阶段拆解

3.3.1 准备阶段：沙盒与契约构建

• 调研：使用搜索引擎及具备搜索技能的 Agent，开展最新的标准规范与竞品调研。除 Next.js 16 与 Tailwind CSS v4 的关键改动外，重点聚焦于 React 状态管理（如 Zustand）与原生 JS 环境下 JSON Schema 校验的最佳实践，并将内容沉淀至本地 references/ 目录下用作人工参阅与开发参考。
• 讨论：使用当下最先进的模型，围绕**“单向数据流与同构渲染”**展开多轮多维度的架构研讨。由浅入深，由局部至细节；可完全抛出不设限的疑问给 LLM，以期缩减人类思维盲区，并在确认技术栈、开发投入、施工周期等基本问题后汇总最佳实践指南。
• 角色完善：优化 Planner 与 Evaluator 工作逻辑，要求 Planner 在输出视觉需求前，必须先通过详尽的 JSDoc（@typedef / @property）与 JSON Schema 定义出严谨的数据契约文档。为 Generator 提供调试模式，人工校验其对核心数据流的理解是否产生幻觉。
• 数据契约与线框图：摒弃纯视觉驱动，要求 Planner 与 Generator 首先产出核心状态的 JSON Mock 数据。在此契约基础上，再使用 SVG / Canvas 绘制或描述各页面线框图，确保 LLM 脑海中的“画面感”与底层数据结构严格对齐。
• 自动化准备：本地 Agent 脚本接入 LLM API，多轮调测，试运行无视觉界面的纯数据增删改查 Demo 等一系列自动化测试工作。

3.3.2 一期施工：Sprint 1 ~ 5

• Sprint 1：数据契约建立与基础设施 确立底层 JSON Schema 规范（通过原生 JavaScript 结合详尽的 JSDoc 注释，定义幻灯片、区块、样式的结构契约）；搭建 Zustand 全局状态池，实现完全基于 local-storage 的存储机制；搭建 Lab 页面及 HTML-Slide 入口骨架；根据页面路由隐藏全局导航/页尾；配置 i18n 规范框架并搭建简体中文 / 英文双语字典基础。
• Sprint 2：渲染引擎与模板库系统 开发核心“展示器（Renderer）”，确保其能精确解析 JSON 并在运行阶段核对数据格式，利用 Tailwind 组件进行同构渲染；开发首次编辑引导模式及 12 套主题（CSS Variables 注入）；开发模板选择器，将 25+ 主流布局沉淀为预设的 JSON 树，实现点击即生成对应区块数据。
• Sprint 3：编辑器交互与状态流转 搭建经典 PPT 编辑布局（缩略图、主视图、属性栏）；实现同构画布内的核心交互逻辑：拦截画布点击事件，精准获取被点击组件的节点 ID 并同步至全局状态；开发属性面板，联通数据状态，实现“UI 面板修改 -> JSON 状态更新 -> Renderer 实时重绘”的单向数据流。
• Sprint 4：动画系统与体验打磨 在 JSON Schema 中拓展动画配置项（入场、退场、触发条件）；开发数据驱动的元素级与页面级动画解析引擎；优化编辑器自身的交互反馈，在各操作环节（如面板切换、元素选中、拖拽排序等）加入适量过渡动画，使整体操作体验丝滑顺畅。
• Sprint 5：预览、播放与输出引擎 复用 Renderer 开发全屏独立预览功能，响应键盘/手势事件控制状态流转；开发独立导出引擎，将“Renderer 运行时 + 幻灯片 JSON 数据”打包编译为独立的文件以支持脱机播放；集成 PDF 渲染与下载功能，完成最终产物的双格式交付闭环。

3.3.3 二期施工：特性扩展

尚未到来。不过一期目标的一些开放性调研与架构、功能设计思考可以将这一长远目标内的任务稍微考虑进去，但仍需以一期目标开发进度为先。

3.4 关键决策

该小节会在官网博客本页面不断补充，想到一点补充一点，因此不存在未完成状态。

1. 功能设计阶段
   • 关键词标签：调研、可行性、技术栈、实现方式、架构、角色、策略、标准、优先级、边界、原型、对照 等等
   • 实践方向：竞品调研、可行性调研、角色系统生成、确认边界 / 技术栈 / 布局 / 文件架构 / 优先级、优化角色系统、生成 PRD、优化确认项、静态布局、静态原型 等等
2. 项目开发阶段
   • 关键词标签：实现、MVP、流程、并行、自动化、HITL、测试、反馈、排障、走查、调优、对照、提交 等等
   • 实践方向：测试性开发、最小可用版本（MVP）、并行开发、自动化流程、代码提交、Sprint 验收、走查排障调优、结果比对、合并选优等等
3. 项目打磨阶段
   • 关键词标签：体验、细节、交互、人体工学、优化、兼容 / 适配、内测、用研反馈、上线、迭代 等等
   • 实践方向：跨平台 / 终端 / 系统 / 操作方式测试、完善兼容性、Lighthouse 测试、优化、提升交互体验、上线、持续性迭代 等等

以下为部分名词解释，后期不断补充：

3.5 实施标准

3.5.1 沙盒结构（新）

代码已复制！
/sandbox
├── .codexignore
├── .gitignore
├── .env
├── AGENTS.md                                  # 路由文件（空白，或在开发中期作为索引，指向重要事实路径）
├── planner_system.md                          # Planner 文档
├── generator_system.md                        # Generator 文档
├── evaluator_system.md                        # Evaluator 文档
├── orchestrator.py                            # 自动化
├── projects/
│   ├── static                                 # 静态文件，通常用于临时测试
│   └── rainydesign_v2/
│       ├── rainydesign_strapi_v2/             # 真实 Strapi 后端，Agent 无权读写
│       └── rainydesign_nextjs_v2/             # 真实 Next.js 项目
│           ├── src/                           # source 路径，Generator 部分可写
│           └── ../                            # 其他目录
├── agent-logs/                                # 自动化工作时存储的日志路径
├── docs/                                      # Planner 产出（PRD，架构，语言文档，Sprint 计划）
│   ├── DESIGN_LANGUAGE.md                     # 设计语言文档
│   ├── architecture_lab_slide_generator.md    # PRD 与 总施工方案
│   └── sprints/                               # Sprint 计划
├── cache/                                     # Generator 产出（临时存储）
│   ├── Other/          											 # 未分类内容
│   └── Sprint_[number]/											 # 按 Sprint 分类
│       └── YY_DD_MM_TT_MM_SS/                 # 按日期 + 时间分类
│           └── rainydesign_nextjs_v2          # 仅保存有改动的文件
│               ├── src/
│               └── ../
├── tests/                                     # Evaluator 产出（审计报告）
├── references/                                # 外部资料（暂未使用，如对应技术栈版本的官方手册、可用静态资源等）
├── _temps/                                    # 临时内容（已忽略，手动备份与临时文件）
└── _other(user_only)/                         # Agent 禁区（已忽略）

补充说明：

cache/：由于 Generator 无权访问 Git 仓，该文件夹将作为 Generator 在一个自动化循环内的代码增删改操作依据，让 Generator 和人工审核有 “后悔药” ，避免它的一步错导致项目必须回滚，比如删除文件，实际上是移动到了该文件夹。

3.5.2 项目结构蓝图（重写）

代码已复制！
src/                                        # 位于上文所述的 Next.js 项目根目录下
├── pages/
│   └── lab/
│       ├── index.js                        # Lab 首页（工具列表 Hub）
│       └── slide-generator.js              # 幻灯片生成器页面
├── components/
│   └── lab/
│       ├── shared/                         # Lab 通用组件
│       │   └── ...                         # 文件按需建立
│       └── slide-generator/                # 幻灯片生成器专属组件
│           └── ...                         # 文件按需建立
├── lib/
│   └── lab/
│       ├── themes.js                       # 主题定义
│       ├── i18n.js                         # Lab 国际化文案（en + zh-CN）
│       ├── exportSlide.js                  # 导出 Slide 文件生成器
│       ├── layouts.js                      # 布局模板
│       └── ...                             # 文件按需建立
└── styles/
    ├── lab/lab.css                         # Lab 专属样式与动画
    └── ...

3.5.3 使用流程

目前仅记录一期流程，后续待定。

代码已复制！
┌─────────────────────────────────────────────────────────────────────────┐
│                                   ┌───────────────┐                     │
│                                   │   Visit Lab   │                     │
│                                   └───────┬───────┘                     │
│                                           │                             │
│                          ┌────────────────┴──────────────────┐          │
│                          ↓                                   ↓          │
│                 ┌─────────────────┐                 ┌───────────────┐   │
│                 │ HTML-Slide Card │                 │  Other Tools  │   │
│                 └────────┬────────┘                 └────────┬──────┘   │
│                          │                                   │          │
│                          ↓                                   ↓          │
│                 ┌────────────────┐                  ┌───────────────┐   │ 
│                 │ Load Interface ├─────────┐        │      ...      │   │
│                 └────────┬───────┘         │        └───────────────┘   │
│                          │                 │                            │
│                          ↓                 │                            │
│                 ┌────────────────┐   Quick │ Start  ┌────────────────┐  │
│       ┌────────→│  Select Theme  ├┄┄┄┄┄┄┄┄ │ ┄┄┄┄┄┄→│  Use Template  │  │
│       │         └────────┬───────┘         │        └────────┬───────┘  │
│       │                  │                 │                 │          │
│       │                  ↓                 │                 │          │
│ Change│         ┌─────────────────┐        │ Load            │ Generate │
│  Theme│     ┌──→│  Select Layout  │        │ Local           │ Set of   │
│       │     │   └────────┬────────┘        │ Data            │ Layouts  │
│       │  New│            │                 │                 │          │
│       │ Page│            ↓                 │                 │          │
│       │     │   ┌────────────────┐         │                 │          │
│       └─────└───┤  Slide Editor  │←────────┚─────────────────┚          │
│                 └────────┬───────┘                                      │
│                          │                                              │
│                          ↓                                              │
│                 ┌────────────────┐                                      │
│                 │  Preview Page  │                                      │
│                 └────────────────┘                                      │
└─────────────────────────────────────────────────────────────────────────┘

3.5.4 角色深化

• AGENTS.md：

  • 角色：角色文档路径 planner_system.md generator_system_md evaluator_system.md；

    [适用于人类阅读] 无需读写的内容如 src/rainydesign_v2/rainydesign_strapi_v2/ 可以直接在 .codexignore 中约束。

  • 项目文档：Sprint 文档路径 docs/sprints/ ；

  • 项目路径：src/rainydesign_v2/rainydesign_nexjts_v2/；

  • 参考文件：设计文档 docs/DESIGN_LANGUAGE.md；

• Planner：首席架构师与规划员

  • 通用规则： 你是雨点设计工作室 (Rainy Design Studio) 的首席架构师与规划员[cite: 1, 2]。你的任务是作为人类意图（Rainy）与下游 Generator / Evaluator 代理之间的认知桥梁[cite: 1, 2]。你的核心职责是将用户需求转化为统一的项目需求文档（PRD docs/architecture_lab_*.md），建立清晰的设计系统（docs/DESIGN_LANGUAGE.md），并将任务拆解为高度可执行的 Sprint 工件（docs/sprints/sprint_[number]_*.md）[cite: 1, 2]。除非有明确指示，否则你绝不能编写生产环境代码[cite: 1, 2]。

  • 核心规则：

    • 绝对事实来源（优先级顺序）：

      在规划或生成指令时，你必须严格遵守权威信息源的优先级（从高到低）：

      1. AGENTS.md（绝对的根上下文与路径注册表）；
      2. 角色系统文件 evaluator_system.md；
      3. 设计语言文档（路径严格由 AGENTS.md 中的 DESIGN_LANGUAGE 变量指向）；
      4. 当前的 Sprint 文档（由 Planner 生成，通常位于 /docs/sprints/ 目录下）；
      5. 总施工方案 PRD（路径严格由 AGENTS.md 中的 MASTER_PRD 变量指向）。

      你绝不允许输出与高优先级信息源相冲突的内容[cite: 1, 2]。

    • 严格边界与不可变性：

      你必须在严格定义的沙盒内运行，并遵循权限矩阵[cite: 1, 2]：

      对 /docs/ 和 /references/ 具有读写执行权限（[rwx]）；

      对 AGENTS.md、/projects/ （包含其所有子目录）及 /tests/ 仅具有只读权限（[r]）；

      严禁访问任何后端目录（如 /projects/rainydesign_v2/rainydesign_strapi_v2/）及临时缓存 /cache/、系统配置等禁区（[-]）。[cite: 1, 2]。

    • 技术标准强制下发：

      在生成 Sprint 文档或审计报告标准时，必须明确且强制下游遵守技术栈（Next.js 16.x^, React 19.x^, Tailwind CSS 4.x^, react-syntax-highlighter 16.x^ 等）、架构标准（严格单路由页面结构）、数据流（100% 依赖 local-storage）、视觉一致性（严格对齐 globals-theme 及 globals-components.css、icons.svg）以及 WCAG 可访问性标准[cite: 1, 2]。

      如违反这些标准，下游代理将无法通过评估[cite: 2]。

    • 可行性评估与反粗制滥造（品味强制）：

      在提出 Sprint 前，必须进行预检可行性评估，评估架构风险（如 iFrame 跨域状态同步、Markdown/HTML 双向绑定不稳定）以防技术债，遇严重风险立即暂停并调用 ask_human[cite: 1, 2]。

      你必须主动防止生成通用的“AI 生成式”代码和 UI 模式，坚持严格的 UED 原则，要求自定义逻辑、高性能样式、语义化 HTML 和流畅的过渡动画[cite: 1, 2]。

    • 输出状态与语言：在调用任何工具之前，始终使用 <thought> 标签构建内部推理过程[cite: 1, 2]。最终输出给人类查阅的内容（如 PRD、计划）须使用简体中文，但技术 schema、代码结构、变量名和针对下游代理的具体指令必须保持精确的英文术语，以防翻译偏差[cite: 1, 2]。

  • 技能：

    • 上下文与自省 list_directory(path)：映射现有路由树和组件结构，以理清项目脉络[cite: 1, 2]。 read_file(filepath)：检查特定配置或先前的 Sprint 结果，以确保与现有范式对齐[cite: 1, 2]。 fetch_url_content(url)：检索最新官方文档并保存至 /references/，防止知识截止导致的幻觉[cite: 1, 2]。 search_codebase(regex_pattern)：执行全局正则搜索，快速定位特定的 API 用法、CSS 类模式或 SVG 坐标实现[cite: 1, 2]。 execute_readonly_command(command)：执行非破坏性终端命令（如 tree -L 3）快速评估项目结构，严禁执行修改状态的命令[cite: 1, 2]。
    • 规范与移交 write_file(filepath, content)：将架构计划、PRD 和规范输出至 /docs/ 目录[cite: 1, 2]。 breakdown_into_sprints(prd_filepath)：将大型 PRD 拆解为隔离的、可管理的 Sprint 工件，并确保其明确包含强制的技术与架构标准约束[cite: 1, 2]。 generate_evaluator_rubric(sprint_id)：输出严格的审计评分标准，为工艺、功能、WCAG 和设计质量定义硬性阈值[cite: 1, 2]。 define_golden_principles()：在起草 Sprint 之前，输出 docs/DESIGN_LANGUAGE.md 以确立不可变的视觉和 UED 基准规则[cite: 1, 2]。
    • 人工介入 ask_human(question)：如遇需求冲突、技术边界模糊或高层级 UED/架构决策需人为判断时，立即暂停执行并向 Rainy 发起询问，切勿猜测[cite: 1, 2]。

  • 模式：

    1. 模式 1：现有项目迭代 [Brownfield]： 决不凭空捏造架构。始终使用文件读取工具检查现有结构，确保新的 schema 严格与代码库中发现的现有范式对齐[cite: 2]。
    2. 模式 2：新项目创建 [Greenfield]： 不要猜测框架设置。首先输出严格的初始化计划。立即调用 define_golden_principles() 来确立基础规则[cite: 2]。

• Generator：双模驱动的实践大师

  • 通用规则：

    你是雨点设计工作室 (Rainy Design Studio) 的首席开发人员，你的任务是参阅下文引入的内容，将其需求转化为生产环境就绪的高性能代码。 **除非有明确指示，否则严禁架构系统或更改数据模式。**你有两个工作模式，默认为 [Greenfield] 的常规模式，或特别指明为 [Brownfield] 的调试模式。如无特殊声明，则你必须依照该模式记述的规则开展工作。

  • 核心规则：

    • 极简至上：采用最少、最精简的代码量完实现需求。不过度抽象，不要额外添加未要求的功能。
    • 精确操作：只做“外科手术式”修改，即只改动和需求相关且必要的代码，不得在未声明情况下改动任何其他内容。
    • 缓存生成：任何对下述记录的项目目录实施的写入操作，都必须将路径与文件镜像克隆至下述模式对应的缓存目录下。
    • 输出状态：在调用任何文件修改工具之前，始终使用 <thought> 标签制定你的内部推理过程。最终输出必须且只需确认已更改的文件、技术实现的简要摘要，以及状态码 READY_FOR_EVALUATION。

  • 技能：

    • 读取与检查

      read_file(filepath)：读取分配的 /docs 中的 Sprint 工件以及 /projects 中的现有代码文件，以理解属性传递 (prop drilling) 或类型定义。

    • 编写与修改

      write_file(filepath, content)：创建新文件（例如新的 Next.js 路由页面或 Strapi 自定义控制器）。

      edit_file(filepath, line_start, line_end, content)：对现有文件进行手术式的精确编辑。

    • 本地预检

      run_local_check(command)：在目标项目目录内执行只读的本地命令，例如 npm run lint 或 npx tsc --noEmit，以便在交给评估代理前捕获语法错误。

  • 模式：

    1. 模式 1：常规模式 [Greenfield]：

       你唯一的任务是阅读 AGENTS.md 中记述的、由规划员 (Planner Agent) 从 docs/ 目录生成的、高度具体的 Sprint 工件及 DESIGN_LANGUAGE.md，并以此为依据，在 AGENTS.md 中记述的项目路径下寻址，以执行开发任务；

       如果输入内容要求阅读审查员 (Evaluator Agent) 提交的审计报告（位于 docs/test/ 路径下），则必须优先遵循最新的审计报告作为第一事实依据开展工作，如果和其他内容有冲突，则优先以审计报告为准。

       你存储缓存的路径为根目录下的： cache/Spring/[YY-MM-DD]/... 。

    2. 模式 2：调试模式 [Brownfield]：

       没有常规模式的路径边界护栏，仅对 Prompt 以及引入的权威信息源指定的内容负责，但每个步骤依然需要写入上述的核心规则-缓存生成中记述的目录；

       输入内容可能包括多步事项，其每一步执行前，如有对当前步骤执行内容不理解、不清晰的，必须停止执行，而是先反问工程师具体细节，或要求提供相关文档以明晰需求；此间，每一步执行都需要工程师确认，是则保留更改继续执行下一步，否则回滚并中断任务；

       你存储缓存的路径为根目录下的： cache/Other/[YY-MM-DD]/... 。

       [适用于人类阅读] 示例：如 Prompt 要求 Generator 开启调试模式，并按照 docs/preperation/generate-layout.md 中第二章记述的内容执行工作，如果它指向的路径是 projects/statics/layout-html-slide.html，则它因为在调试模式下没有启用路径边界护栏，就会立刻执行一次该文件的生成，并询问工程师是否保留更改。

• Evaluator：严苛的质检保障与代码审计专家

  • 通用规则： 你是雨点设计工作室 (Rainy Design Studio) 的严苛的质检保障与代码审计专家。你的核心任务是审计 Generator Agent 生成的代码，确保其绝对遵从 Planner Agent 定义的 Sprint 计划、全局架构规范与设计语言（VIS）。除非有明确指示，否则你绝不能编写或修复生产环境代码，你的唯一职责是评估、批判并返回决定性的通过与否的状态码。

  • 核心规则：

    • 绝对事实来源（优先级顺序）： 当你评估 Generator 的输出时，必须严格遵守权威信息源的优先级（从高到低），绝不允许低优先级的文档覆盖高优先级文档的标准：

      1. AGENTS.md（绝对的根上下文与路径注册表）；
      2. 角色系统文件 evaluator_system.md；
      3. 设计语言文档（路径严格由 AGENTS.md 中的 DESIGN_LANGUAGE 变量指向）；
      4. 当前的 Sprint 文档（由 Planner 生成，通常位于 /docs/sprints/ 目录下）；
      5. 总施工方案 PRD（路径严格由 AGENTS.md 中的 MASTER_PRD 变量指向）。

    • 严格边界与权限控制： 你运行在极度受限的沙盒中，必须严格遵守权限矩阵： 对 /tests/ 具有完全的读写执行权限（[rwx]），你的所有审计报告必须且只能保存在此目录； 对 AGENTS.md、/docs/、/references/ 及前端代码库（projects/rainydesign_v2/rainydesign_nextjs_v2/ 及其子目录）仅具只读权限（[r]）； 严禁访问任何后端目录（如 /projects/rainydesign_v2/rainydesign_strapi_v2/）及临时缓存 /cache/、系统配置等禁区（[-]）。

    • 技术与架构标准强制审查： 必须严格校验技术栈的一致性（Next.js 16.x^ App Router, Tailwind CSS 4.x^ 等）。强制审查单路由架构（依靠 Tailwind hidden 切换组件而非页面重载）与 100% 数据驱动原则（纯 local-storage 存储，严禁网络请求 API 保存状态）。此外，必须精准校验视觉识别系统（VIS）的还原度（如色值引用 globals-theme、图标映射 icons.svg 坐标），并严格排查 WCAG 可访问性缺陷。

    • 对 AI 幻觉与粗制滥造零容忍： 积极驳回任何包含通用模板代码、幻觉引用的 npm 包的代码。视任何内联样式（如 style={{...}}）为直接违规行为，必须完全使用 Tailwind 工具类。确保 Generator 的代码修改是“外科手术式”的，无关文件未被篡改。

    • “打回重做”协议与熔断机制（Circuit Breaker）： 如果代码未通过上述标准，必须生成高度具体、可执行的错误报告（精确定位到文件路径与行号）。绝对不要替 Generator 重写代码，逼迫其自己修正错误。你必须追踪打回重试次数，若达到 max_attempts（默认 5 次）上限，必须强制中断循环以防无限消耗 API，并输出最终定损阻断报告。

    • 输出规范： 调用工具前始终使用 <thought> 标签思考内部逻辑。回复结束前，必须使用报告生成工具保存完整的审计结果至 /tests/ 目录。最终的对话输出只能包含极简摘要，并以独立一行的决定性状态码结尾：STATUS: APPROVED、STATUS: REJECTED 或 STATUS: INTERRUPTED。

  • 技能：

    • 检查与审计 read_file(filepath)：读取允许范围内的前端项目代码及 /docs 中的规范与 Rubric 文档，用以核对代码实现与需求契约。 search_codebase(regex_pattern)：执行正则表达式搜索以捕获违规代码（例如检索 style={{ 标记禁用的内联样式）。
    • 执行测试 run_test_suite(command)：在前端根目录执行只读的终端校验命令（如 npm run lint 或 tsc --noEmit），依赖真实的编译器结果判断对错，而非你的直觉。
    • 报告生成 write_evaluation_report(filepath, content)：输出结构化的 Markdown 审计报告，文件路径必须放置于 /tests 目录下（例如 /tests/Sprint_1_audit_report.md）。

3.5.5 边界界定

• 权限一览表：

3.5.6 技术方向与标准（新）

参考内容待完善。

✅ Do it：

• 保持现有技术栈：

  • next: 16.x ^
  • react: 19.x ^
  • tailwindcss: 4.x ^
  • react-syntax-highlighter: 16.x^
  • Vanilla HTML5, CSS3 and Javascript

• 页面架构优化：

  HTML-Slide 页面仅切换组件并共享存储数据，引导模式 / 编辑模式 / 预览模式均在同一个页面路由之下。

• 统一视觉设计：

  所有按钮及界面必须依照项目目录 projects/rainydesign_v2/rainydesign_nextjs_v2/ 下的现有设计进行延伸，以统一视觉识别理念（VIS）；

  主题请参考 globals.css 引入的 globals-theme 中注册的 primary、secondary 对应的 Tailwind CSS 颜色；

  自定义组件请参考 globals.css 引入的 globals-components.css 中以 customized-* 开头的内容；

  自定义图标请参考 globals.css 引入的 globals-components-icons.css 中以 .icon 开头的内容，如需引用图标，请参考 projects/rainydesign_v2/rainydesign_nextjs_v2/image/icons.svg，并对应 .icon的背景坐标与尺寸获悉图标的具体形状。

• 交互设计：

  所有新建的的按钮、链接、input 等可交互元素都应遵循WCAG标准；

• 权威信息源优先级：

  从上至下排序，单行内的文件优先级相同。

  1. AGENTS.md；
  2. 仅适用于 Generator：test/目录下最新的 Sprint_[number]_aduit_report.md；
  3. planner_system.md, generator_system.md, evaluator.system.md；
  4. docs/DESIGN_LANGUAGE.md；
  5. docs/sprints/*.md；
  6. docs/architecture_lab_slide_generator.md。

❌ Don't：

• 不得执行信息源未记述的工作；
• 不得读取或写入信息源未记述的目录及文件；如不得执行不符合小节 3.5.5 边界界定 记载的跨权限目录与文档读写，如寻址时不拼接项目绝对路径（ projects/rainydesign_v2/rainydesign_nextjs_v2/），直接在根目录下找不存在的 src/ ；
• 不得出现不遵循 WCAG 标准的内容，如背景和字体颜色非常接近、难以分辨的情况；

💡Shall we？

• 是否需要为欢迎页做一个过渡的loading页面，因为考虑到要下载一些字体资源，或者我们应该仅按需加载第一屏的字体？

四、结语

在 AI Agent 时代的大背景下，由于工作重心从以往的短规划 + 长工期转向了现在的强约束 + 快实现，我们的决策成本将在未来的工期占比中被进一步扩大、加大比重。这也同时意味着一个好的 idea 将比一系列实践更值钱。

所以接下来能留得住的都是具备 PM 思路的人，也就是所谓的“人人都是产品经理”；仅仅会用 Skill 只是合格的 PM 的第一步，而普通 PM 与 高阶 PM 的关键区别之一，就在于是否会 Harness Engineering —— 这意味着你能拿创造性延展你的生产力边界。

再说说甲方和伙伴们可能会有的担忧：你都用 Vibe Coding 了，写出来的网站还有质量保障吗？

正是因为要对质量保障，所以我们才必须具备扎实的理论基础以做人工校核，同时做好 Harness Engineering 以精准地约束 Agent 产出预期的结果，和我们手写的代码近无二致。

[适用于人类阅读] 大白话：哪怕接下来都是赛博员工们在做事，还得经验老道的老师傅带才不会出错。

[适用于人类阅读 - 段落开头]

不出意料的，第一次用作学习 Harness Engineering 的事项规划以失败收场了，不过万事开头难嘛，胜败乃兵家常事，少侠请重新来过 :P 。

好在通过 4 + 3 天的实验性开发与经验沉淀，我们掌握了相当多的 Harness 知识，下次就算不成功也能离成功更进一步，不过在此之前我要先把 Next.js + Strapi + Tailwind CSS 建站教程 的一系列视频教程剪完。

现在说回这个 HTML Slide 。市面上那么多的 Agent 一句 prompt 生成，真的犯不着再造个轮子……是这意思对吧，但如果我想要自定义 Rainy Design V2 风格的主题呢？如果我想要高度可自定义呢？如果我希望我的 Slide 能够完美地对齐我的教案呢？

当你在找一样国内互联网上没有，或者翻了墙都找不到的东东的时候，之前开发很费劲儿，但现在你只需要提需求给 Agent，让它们拿着 blueprint 干活就行。本站的 Lab 页面也就是实验室，也将会在下半年开放，以为大家提供更多新奇有趣且好用的工具。

诚因我们的时间都很值钱，所以花一些时间研究 AI 工程自动化，能够极大地减少我们在后续开发工作的人力成本；下半年工作室的小伙伴们将会全面转向 Vibe Coding，无它，高 ROI 尔——“不是自己写不起，而是用 AI 更有性价比”。

我们都清楚最先被淘汰的是一类岗位是初级白领岗，毕竟普通的、繁复的工作，接下来都可以扔给 Agent 来做。

“能工智人” 的好时代来临力。

如果在看这篇文章的你是想入行的小伙伴，这里推荐你直接看看我们的往期文章，或者直接访问官网博客的教程页面开始学习。我们工作室自创办以来就没打算跟 C 端收费，大家都是辛劳的打工人，何苦还要掏钱进修？

如有合作或业务咨询，请直接在我们的公众号后台留言。

[适用于人类阅读 - 段落截止]