第 18 讲 一个需求到一个作品站
【可执行状态】现在就能做（样本已在线，骨架一次生成、逐页铺开即可）
【本讲对应资产】app-builder 引擎（8 个工具）：app_samples / app_scaffold / app_page / app_flow_contract / app_verify / shop_shelf / shop_publish / puer_shop_publish
【本讲原理来源】L3 第 19 课（Agent 成长五步中的“沉淀成技能”）、吴恩达四大设计模式中的“规划”
引子：为什么学生交上来的作品“看着挺好，没人想用”
带过竞赛的老师都有这个经验：学生做了一个页面，配色漂亮、动画流畅，
演示时台下一片“哇”，可真让人用一次，问题就来了——
点进去找不到返回、数据看不出从哪来、讲完一页不知道下一步该干什么。
打个比方：这就像做了一份精美的展览海报，但没人告诉参观者从哪个门进。
作品不是给人看的，是给人用的。
这一讲讲的是怎么把“一个需求”变成“一个能被用的作品站”：先搭骨架，再填内容，最后拿尺子量。
一、场景
省赛初评那天，评委面前摊着几十份作品。多数作品的现场是同一个样子：一份 PPT 从头翻到尾，
图表一张接一张，最后一张写“谢谢聆听”。评委心里只有三个问题：
这是真的吗？这是学生自己做的吗？这东西能不能落地？
李老师（化名，云南德宏职业学院）带学生做的跨境茶品作品，初评时被连问三句，答得都很吃力——
“你这个数据真的采集过吗？”“这几个环节谁接谁？”“上线以后谁维护？”
作品本身做得不错，但呈现方式让评委找不到证据。
那天晚上她回去只做一件事：把这套东西重新摆一遍。要求写在一张便签上——
一个需求，一个作品站：把一条业务过程拆成几个环节，每个环节做成一页，
最左边常驻一条流程栏，走到哪一步一眼看得见；页面上的每个数字都要说得出从哪来。
第二天她照这张便签重建，用的就是一个引擎、八个工具。
这一讲要解决的就是这件事：同样是这套东西，怎么摆，才能让评委在五分钟里看见它的价值。
二、原理一页：环节链是骨架，八条铁律是尺子
打个比方：环节链就像一份“旅行日程表”——哪一天在哪儿、上一站交了什么、
下一站要带什么，一目了然。没有日程表的旅行，走到一半就会乱。
1. 一句话规矩
每一步的产出，就是下一步的输入。
我们过去习惯把工作流放在“后台”：画布给内行看，页面给外行看。
于是页面上只剩指标和图——看起来像一个看板，看不出这是一条生产线。
环节链呈现法换个思路：把工作流本身搬到页面上，让它当页面的骨架。
具体就是把一条业务流拆成 N 个环节（不是 N 个数据模块），每个环节做成一页，页与页之间用“交接”连起来：
| 环节链的构成 | 做什么 | 为什么 |
|---|---|---|
| 常驻左栏（画布流程） | 竖排显示工作流节点，随当前环节“往下走”（走过的打勾变灰、当前高亮、未到保持灰色） | 让人随时知道“现在到哪一步”，换页不消失 |
| 顶部环节条 | N 个环节的名字与序号，可点 | 一屏说清整条链 |
| 每环节三段式 | 上游交付物 → 本步产出 → 交接下一步 | 证明“上一步真的交给了下一步” |
| 末环节闭环 | “回到第一环节，开启下一轮” | 说明这是可持续经营的循环，不是一次性演示 |
2. 拿什么判断“该切成几个环节”
三个标准，缺一条就说明这一刀切歪了：
- 有交付物：这一步干完，手上有一样东西（一份数据、一批设计、一串上架记录）
- 说得清交接：谁交给谁，一句话能讲明白
- 能闭环：最后一步能回到起点，开启下一轮
例如：做一份“班级读书会”的作品站，环节可以是——选书 → 报名 → 排期 → 记录 → 展示，
五个环节、五页；再比如“实验室安全管理”，环节是——风险登记 → 培训 → 检查 → 整改 → 复盘。
环节从业务过程里长出来，不是从页面上分出来的。
3. 工具链路：五步生成一个作品站
一个作品站不是一次“生成”出来的，是五步搭出来的。记住这条链，你换任何业务都能重走一遍：
| 步 | 工具 | 干什么 |
|---|---|---|
| 一 | app_samples | 取样本规范。sample 可传 puer、africa 或 all。一次拿回：节点定义、页面映射、8 条 UI 铁律，以及“模拟真网店上架”的落地形态（本线自有网店「普洱购」）——照抄用 |
| 二 | app_scaffold | 生成骨架包（一个 zip）：static/rail.css、static/rail.js、app-config.js、index.html。要传 app_id、title、nodes_json（环节定义），pages_json、canvas_url、brand、subtitle 可选 |
| 三 | app_page | 逐页生成。一个环节一页，带常驻左栏与“上游交付 / 本步产出”卡；upstream_json、outputs_json 写两张卡的内容，deliver 写交给下一步的说明 |
| 四 | app_flow_contract | 生成流程契约。产出 /api/<app>/flow 的 JSON，steps_json 写每个环节的 id、key、名称、层次、上游、产出、交接，sources_json 写真实抓取记录 |
| 五 | app_verify | 结构验收。传 html 源码或 url（抓取后验收），检五件事：iframe=0 / rail 引用 / 单导航源 / 正文字数 / 表格折叠 |
另有三个工具管“货架与上架”，用在环节链的“选择上架”这一环：
shop_shelf 出网店货架页（商品卡：图 / 名 / 价 / 划线价 / 已售 + 上架状态徽章）、
shop_publish 出上架数据契约与后端路由片段（把设计稿转成 listing 记录：sku / 价格 / 库存 / 状态 / 上架时间）、
puer_shop_publish 把商品真上架到「普洱购」自有网店。第 19 讲会看到它们在链上怎么用。
4. 八条 UI 铁律
这八条来自样本规范，app_samples 一次就能取到。它们不是审美偏好，是验收标准——
每一条都能被工具量出来：
| 序 | 铁律 | 说人话 |
|---|---|---|
| 1 | 常驻左栏画布 | 左栏在所有页面的外层，换页不消失，只“节点往下走” |
| 2 | 单导航源 | 导航只留左栏，页面顶部不许再长出第二套导航 |
| 3 | 禁止 iframe 套面板 | 不许把一个页面套进另一个页面 |
| 4 | 一页一屏不嵌套 | 一个环节一屏装完，不往下叠别的环节 |
| 5 | 表格默认折叠 | 表格只用于核对，默认收起，需要时展开 |
| 6 | 正文字数上限 | 正文有上限，写不下的移到明细页，不硬塞 |
| 7 | 数字必须能追溯来源 | 每个数字后面要么有接口、要么有文件 |
| 8 | 交付必须给可打开的真产物 | 说“做好了”，后面必须跟一个能打开的链接 |
为什么铁律要写成“能验收的句子”：一条规矩如果只能靠“感觉挺好看”来判断，
它在汇报现场就是无效的。第 3、5、6 条能被工具直接数出来，第 1、2 条能被结构检查测出来，
第 7、8 条能被追问测出来——能验收，才是纪律。
5. 为什么“契约”这一步不能省
页面和看板，是两处显示同一件事的地方。手写两遍，一定对不上；
改了页面忘了改看板，评委一问就露馅。
app_flow_contract 生成的是一份双方共用的流程契约：每个环节的上游、产出、交接都写在里面，
页面和看板读的是同一份。改契约，两处同时跟着变。
在普洱茶那个项目里，这份契约由 puer_flow 提供——同一种做法，在两个引擎里都留了位置。
6. 一条反馈纪律：一次只改一层
页面改不动，多半不是不会改，是一次说了三层。作品站有三层，提意见时一次只说一层：
| 层 | 说的是什么 | 例子 |
|---|---|---|
| 骨架层 | 环节怎么切、一共几屏、顺序对不对 | “第三环和第四环合成一屏” |
| 页面层 | 某一屏里放什么、放哪儿 | “第二屏的产出卡放到正文最上面” |
| 数据层 | 数字从哪来、口径是什么 | “这个价格带换成抓取口径” |
纪律是：提一层 → 改 → app_verify 验收 → 再提下一层。
三层混在一句话里说，它只会听进去一层，另外两层你以为改了、其实没改——
这是作品站返工的第一大原因。
作品形态的四代：从 PPT 到环节链
例如，学生竞赛作品的形态，这十几年换了四代：
第一代是 PPT——评委看的是排版和讲解，交付物是一份文件；
第二代是网页——能点、能滚，但往往是“一页长图”，还是给人看的；
第三代是小程序/APP——能用，但开发和部署门槛高，学生常常只做一个壳；
第四代是“环节链应用”——把一个真实业务过程拆成 N 个环节，
每个环节一页，左栏常驻流程与进度，自己会讲故事。
打个比方：前三代像“相册”，第四代像“流水线的监控屏”——
看的人一眼就知道：现在走到哪一步、上一步交了什么、下一步该产什么。
再比如，工业上的看板（Kanban）也是这个道理：把一个过程画成连续的格子，
活儿走到哪里一目了然。环节链就是把工业看板搬进了网页。
三、动手三件套
一句话指令（点名工具，一路走通）
帮我把这件作品做成一个环节链作品站：
先用 app_samples 取样本规范（sample 传 puer）；再用 app_scaffold 生成骨架包，app_id 用 chake，title 写“跨境茶品作品站”，节点按五个环节写，每个节点给名称、类型、层次、颜色、图标、页码；
然后逐页用 app_page 生成，每页要带常驻左栏、上游交付卡、本步产出卡和交接说明；再用 app_flow_contract 生成流程契约（页面与看板共用一份）；最后用 app_verify 验收，把 iframe 数、rail 引用、导航源、正文字数、表格折叠五项结果报给我。保留原有全部功能与真实接口，不要改数据来源。
预期产物
| 产物 | 形态 | 验收要点 |
|---|---|---|
| 骨架包 | 一个 zip，含 static/rail.css、static/rail.js、app-config.js、index.html | 解开后四个文件齐全 |
| 环节页 | 每个环节一个 URL（如 ?step=3） | 可单独发链接，也能做成二维码 |
| 常驻左栏 | 换环节时不消失，只“节点往下走” | 节点名与画布一致 |
| 三段式流程条 | 每屏都能看到“上游是什么、本步产出什么、交给谁” | 五屏串成一条链，末屏回到起点 |
| 流程契约 | /api/<app>/flow 的 JSON | 页面与看板读同一份 |
| 验收报告 | app_verify 的五项结论 | iframe=0、rail 被引用、导航源唯一、正文字数在内、表格默认折叠 |
| 货架页（可选） | shop_shelf 出的商品卡页 | 上架后商品真出现在货架上 |
校验点（照这五条量，别看“感觉挺好看”）
- 一屏一环节：打开任一环节，页面上只出现这一环节的内容，别的环节不叠在上头
- 左栏常驻：首屏与末屏的左栏都在，宽度稳定（约 226 像素），不压主内容区
- 状态正确：走到第 3 步时，前两步显示“已走过”，第 3 步高亮，后面的保持未到
- 产出可见：该有图表的环节有图，该有视频的有视频，该有表格的有行数
- 验收五项全过：
app_verify报 iframe=0、rail 有引用、导航源唯一、正文字数在内、表格默认折叠
再补一条纪律：来回切换两轮（1→5→1），页面不出错、图表不空白，才算过。
这一步能抓出“切换两次以后图表消失”这类隐性毛病。
四、常见错误与排错
错误一：N 个环节叠在同一屏上。
表现：打开页面看到全部内容从上到下排开，左栏被挤得看不出结构。
原因：控制“一页一屏不嵌套”的显示规则没生效（改写页面时最常丢的就是这一条）。
排错：先确认这一条规则真的写进页面了，再谈别的——不要凭“我加过样式了”判断。
错误二：左栏不常驻，或者顶部又长出一套导航。
表现：左栏只在第一屏有，切到后面就没了；或者顶部多出一条横向导航，和左栏抢着当入口。
原因：左栏被放进了某一个环节内部，而不是放在所有环节的外层；顶部那条是多加出来的“第二导航源”。
排错：左栏必须在所有环节的外层容器里，切换环节时只换内容、不重建左栏；
顶部只保留环节条，导航只留左栏这一处——这一条正是铁律第 2 条。
错误三：图表切换后空白。
表现：第一次看有图，切走再切回来图表就空了。
原因：同一个容器被重复初始化，或者初始化时容器还是隐藏状态（尺寸为零）。
排错：每个环节的取数只做一次；显示之后再让图表按当前尺寸重算。
错误四：页面里套了 iframe。
表现：某一屏把另一个页面整个套进来当面板，看起来“功能很全”。
原因：想省事复用旧页面，于是嵌了一层。这是铁律第 3 条明令禁止的——
套进去的那一层会带进自己的导航、自己的滚动条，左栏常驻和单导航源同时失效。
排错：app_verify 会直接报出 iframe 数，这个数必须是 0；不是 0 就拆掉重做那一屏。
错误五：只给描述，不给能打开的东西；拿手写数据当产出。
表现：汇报时说“我们做了一个环节链页面”，但没有链接、没有二维码、当场打不开；
或者页面上数字很漂亮，一问来源就露馅。
排错：两条交付纪律——任何“做好了”的说法，后面必须跟一个能打开的链接（铁律第 8 条）；
每个数字后面要么有接口、要么有文件（铁律第 7 条）。上游真跑出来的东西才算产出。
五、边界与红线
- 数据来源要标：真实采集的、公开报告整理的、演示模拟的，在页面上分开标明（作品页页脚写清）
- 数据等级要守：公开平台抓取的数据、自己写的材料可以放；
学生个人信息、未公开的合作方材料不要进作品站（处理方式见第 12 讲）
- 学生自主设计要有痕迹：环节怎么切、每步产出什么、策略怎么定，是学生的设计；
平台与工具是技术底座。材料里把这层关系写清楚，既是事实，也是保护
- 不夸大：“已上线”就说已上线，能跑几件就说几件；没跑通的功能不写进作品页
- 别把演示当承诺：作品页上的运营数据是演示场景，对外说明时如实讲
六、拓展与学科迁移
- 同类作品：电商选品、农产品溯源、社区服务、金融数据分析——换环节名即可，骨架不动
- 教学场景：把一门课的“教学环节链”做成一页（采集案例→分析→建模→报告→答辩），
学生一看就知道这门课要交出什么
- 专业建设与汇报：把一个专业的“产教融合链路”（调研→共建→实训→就业反馈）按这套呈现，
比一页罗列成绩更容易被看懂
- 延伸一步：把这套骨架写进学院的作品模板，学生新作品直接套——
模板化就是把经验变成组织能力；app_scaffold 生成的骨架包，本身就是那份可以传下去的模板
带走一句话
内容与入口只写一处——重复就是嵌套，嵌套就是学生找不到北。
数据与平台：本讲所述的八条 UI 铁律与“环节链”骨架，来自 zhenyuonline.cn 平台上多个真实项目的共同规范
（普洱跨境、中非贸易等），并由 app-builder 引擎的 app_samples 工具固化下来；
结构验收由 app_verify 自动完成（检查 iframe=0、左栏引用、单导航源、正文字数、表格折叠五项）。
背后的引擎（本讲速查）
| 你在书上看到的话 | 工具全名怎么读 | 一句话作用 |
|---|---|---|
| 取样本规范（节点定义 / 页面映射 / 8 条铁律） | mcp__app-builder__app_samples | 照抄用的结构规范，sample 传 puer、africa 或 all |
| 生成骨架包 | mcp__app-builder__app_scaffold | 出一个 zip：rail.css、rail.js、app-config.js、index.html |
| 逐页生成环节页 | mcp__app-builder__app_page | 一环节一页，带常驻左栏与上游交付 / 本步产出卡 |
| 生成流程契约 | mcp__app-builder__app_flow_contract | /api/<app>/flow 一份，页面与看板永远一致 |
| 出网店货架页 | mcp__app-builder__shop_shelf | 商品卡形态的“选择上架”页 |
| 出上架数据契约 | mcp__app-builder__shop_publish | 设计稿 → listing 记录（sku / 价格 / 库存 / 状态 / 时间） |
| 真上架到自有网店 | mcp__app-builder__puer_shop_publish | 写进「普洱购」商品库，前台立刻可见 |
| 结构验收 | mcp__app-builder__app_verify | 检 iframe=0 / rail 引用 / 单导航源 / 正文字数 / 表格折叠 |
本讲要点（速记）
- 一句话规矩：每一步的产出，就是下一步的输入
- 骨架四件：常驻左栏 · 顶部环节条 · 每环节三段式 · 末环节闭环
- 工具五步：
app_samples取规范 →app_scaffold出骨架 →app_page逐页 →app_flow_contract定契约 →app_verify验收 - 八条铁律：常驻左栏 · 单导航源 · 禁 iframe · 一页一屏 · 表格折叠 · 正文字数上限 · 数字可追溯 · 交付必给真产物
- 一条反馈纪律：一次只改一层（骨架 / 页面 / 数据），改完先验收再提下一层
- 迁移一格：换环节名就能复用到另一件作品，
app_scaffold的骨架包就是可传下去的模板