本章精髓 交付的标准不是"我这儿能跑",而是"别人在别人的电脑上、不问你,能独立用完一次"。这一条从本章起适用于之后每一次提交。
学完本章后,你应该能够:
- 说清为什么作者自己百分之百测不出交付问题,并动手制造一个缺东西的环境;
- 指出一份代码里的三类环境依赖,并把它们装进包里或者干脆去掉;
- 写一份五段齐全的 README,让不认识你、也问不到你的人能独立开始;
- 按六步做一次冒烟测试,全程不说一句话;
- 交出一个压缩包:换台电脑、换个浏览器、断网,三次都能用完。
配套演示文件
第08章演示_合格包/
第08章演示_问题包/
第08章演示_拆包六步.html
①
当众拆包,作者一言不发
接收方六步 · 两个包 · 让它当陌生用户
先看一次接收方的视角,六步走完,判断就已经形成了。
1.1两个包,当众各拆一次
本章有两个现成的包:一个是问题包,一个是合格包。两者做的是同一件工具,代码绝大部分一模一样。
打开 第08章演示_拆包六步.html,选一个包,按接收方的六步走一遍。全程不问作者,也不看代码,只做一个刚拿到这个包的人会做的事。
1解压,看包里有什么
能不能一眼看出哪个是入口
2读说明文件
看完知不知道该怎么开始
3双击入口文件
有没有破图、有没有点不动的地方
4走一遍主流程
从第一步走到最后一步,中间卡没卡
5换一个浏览器再开一次
排版有没有跑、字体是不是同一个
6断网再开一次
和联网时有没有区别
六步走完,接收方的判断已经形成了,而作者一句话还没说。这就是交付的真实场景:你不在现场,也没有机会解释。
讨论问题包的那几处毛病里,哪一处是作者最不可能自己发现的?为什么偏偏是它?再想一想:你自己前几次交的作业里,有哪一件从来没在别人的电脑上打开过?
1.2本章新技巧:让它当第一个陌生用户
你写的说明,自己看当然懂。让大模型只读说明、不看作品,把看不懂的地方挑出来,这比同桌互测还早一步。
大模型是真正的陌生人:它只看你给的那一段文字,不会脑补你没写的部分。你写的说明缺了哪一句,它当场就问出来。
1.3可直接复制的提示词
发给 AI只读说明 · 只挑问题,不要改
下面是我的作品说明(README)和功能清单。
请你假装是一个从没见过这个东西的人,只读这份说明,不要替我改,然后告诉我:
① 你认为这个东西是干什么的、给谁用的;
② 拿到它之后你会怎么开始,第一步做什么;
③ 说明里有哪几处让你看不懂、或者需要靠猜;
④ 你预计一个新人最可能在哪一步卡住;
⑤ 交付物还缺什么:说明、素材、截图、备份。
不要夸奖,只挑问题,每条一句话。
[粘贴 README 与功能清单]
发给 AI挑环境依赖 · 交付前必查
下面这份代码我要打包发给别人,对方的电脑上不一定有我这里的东西。
请只做一件事:把代码里所有"依赖外部环境"的地方逐条列出来,不要改代码。
要覆盖这几类:
引用了网上的地址(字体、图标、图片、脚本);
写成完整路径的本地文件;
指向的文件名和实际文件名对不上的链接;
依赖某种特定字体才能正常排版的地方。
每条写清:在第几行、依赖的是什么、对方那里缺了它会出现什么现象。
[粘贴代码]
只读这份说明,不要替我改
它直接把改好的说明甩给你,你反而不知道原来哪里不清楚
不要夸奖,只挑问题
它先夸一段,占掉半屏,真正的问题挤在最后两行
交付物还缺什么
它只挑文字表述,不提你少放了素材和说明
对方那里缺了它会出现什么现象
只说"这里引用了外部资源",你判断不出严不严重
1.4大模型的常见偏差
忍不住先夸两句 "这份说明结构清晰、内容完整",然后才开始挑。写明"不要夸奖"就能压住。
直接把改好的版本甩给你 你要的是知道哪里不清楚,它给的是一份已经清楚了的新说明。下一次你还是会写成原来那样。
只挑文字,不挑缺件 说明写得再好,包里少了图片一样用不了。缺件那一条要单独点名问。
备用方案 两个包都是现成的:第08章演示_合格包/ 与 第08章演示_问题包/。当堂拆包用 第08章演示_拆包六步.html,六步逐条对照,不依赖网络。
②
为什么你自己测不出来
本章重点
交付物 · 环境依赖 · 依赖缺失 · 字体回退
本章的核心内容集中在这一部分和下一部分。
本章要学的术语 · 八个
01交付物deliverable
02压缩包archive
03环境依赖environment dependency
04依赖缺失missing dependency
05字体回退font fallback
06说明文件README
07冒烟测试smoke test
08可用性usability
这八个术语会原样出现在交付清单、测试报告与项目文档中。前五个在本部分讲解,后三个在第三、四部分讲解。
2.1根因:你手上那一台什么都不缺
问题包的作者不是不认真。他在自己电脑上测了一百遍,一百遍都是对的。
因为图片就在他桌面上,字体他自己装过,网络一直连着。问题只在缺了某样东西的机器上才显现,而作者手上那一台什么都不缺。
所以自测测不出交付问题。要把它们逼出来,必须制造一个缺东西的环境:换一台电脑、换一个浏览器、断一次网。
2.2五个知识点,一个一个看
01交付物:交出去的不只是那个文件
叶形检索卡← 交付物是整个包
└ index.html← 入口
└ guide.html
└ README.txt
└ img/ 三张示意图
凡是要你口头补一句才能用的,都算不完整
现象:交上去的是一个包,不是一个孤零零的网页文件。
概念:交付物(deliverable)是接收方拿到的全部东西:程序文件、用到的素材、说明文件。缺一样对方就得来问你。凡是需要你口头补充一句才能用的,都说明交付物不完整。
类比:买回来的家具,除了板子还得有螺丝、扳手和图纸,少任意一样都装不起来。
02压缩包:要压的是文件夹本身
右键文件夹→
压成一件→解压出来是一个文件夹
全选里面的文件→
再压→解压出来散一地
这两种做法在自己电脑上看不出区别
现象:同组同学解压之后,桌面上多出来十几个零散文件。
概念:压缩包(archive)把整个文件夹打成一件,传输时不会散、不会漏。要压的是文件夹本身,不是把里面的文件一个个选中再压。
类比:把一整个抽屉装箱寄走,收件人打开就是原样;把里面的东西分成三个信封寄,收件人还得自己拼回去。
03环境依赖:你机器上有的,别人未必有
网上的字体断网就换
桌面上的图片换台机器就没
改过名的文件链接点不动
三样在你机器上都在,所以你测不出来
现象:你这边好好的,对方打开图裂了、链接点不动、字也不对。
概念:环境依赖(environment dependency)是程序运行时要靠外部提供的东西:图片文件、字体、路径、网络。这些在你机器上都在,所以你测不出问题。
类比:菜谱里写"用我家那罐酱油"。在你家能做,寄给别人就做不成。
04依赖缺失:解法只有两条
装进包里图片放进 img 一起打包
干脆不依赖改用文字和边框画示意
没有第三条路
现象:九张示意图全变成破图标,页面结构还在,内容没了。
概念:依赖缺失(missing dependency)就是依赖的东西在对方环境里不存在。解法只有两条:把依赖装进包里,或者干脆不依赖。
类比:寄相册只寄了本子没寄照片,翻开每一页都是空框。
05字体回退:找不到就换一个,不报错
你这里→
字体下载得到→排版正常
对方那里→
悄悄换成默认字体→版面跟着跑,没有提示
这一条最隐蔽,因为它不算"坏"
现象:对方打开,字看着不一样,行也比你这儿多挤了一行。
概念:浏览器找不到指定字体时会回退到系统默认字体,不报错也不提示。不同字体宽窄不同,排版就跟着变。所以本课程一律用系统自带字体。
类比:借别人的打印机印海报,字体自动换了一个,版面全跑了,机器却一声不吭。
本章方法 交付前换一台电脑、换一个浏览器、断一次网,各打开一次,三次都能正常用完才算交得出去。
2.3问题包和合格包,差别就在这几行
两份代码绝大部分一模一样。下面每一行都不报错,但每一行都能让对方那边废掉。
问题包 与 合格包三处差别 · 每一处都是一类环境依赖
<!-- ✗ 问题包:引用网上的字体。对方断网或加载失败,字体悄悄换掉 -->
<link rel="stylesheet" href="https://fonts.example.com/css2?family=…">
<!-- ✓ 合格包:只用系统自带字体,谁的机器上都有 -->
<style> body { font-family: "Microsoft YaHei", "PingFang SC", sans-serif; } </style>
<!-- ✗ 问题包:完整路径。这个位置只在作者自己的电脑上存在 -->
<img src="C:\Users\yangmin\Desktop\叶片照片.jpg">
<!-- ✓ 合格包:相对路径,图片跟着包一起走 -->
<img src="img/ye-quanyuan.svg">
<!-- ✗ 问题包:链到一个后来改过名的文件 -->
<a href="图鉴.html">翻一下图鉴</a>
<!-- ✓ 合格包:文件名和链接对得上 -->
<a href="guide.html">翻一下图鉴</a>
一个字母级的速查法。路径里出现冒号加斜杠(C:\ 或 https://),就是在指向这个包之外的东西。
用编辑器搜这两样,比通读代码快得多,一分钟就能查完一份作品。
③
说明文件与冒烟测试
README 五段 · 已知限制 · 通电看冒不冒烟
写给不认识你、也问不到你的人看。
3.1另外两个知识点
06说明文件 README:读者是问不到你的人
① 怎么打开
② 包里有什么
③ 怎么用
④ 已知限制
⑤ 作者与日期
五段就够,放在包的最外层
现象:合格包里多了一个 README.txt,问题包里没有。
概念:README 是交付包里的说明,行业里统一叫这个名字,一般放在最外层。它的读者是不认识你、也问不到你的人。五段:怎么打开、包里有什么、怎么用、已知限制、作者与日期。
类比:家具的组装说明书。没有它,你得给每个买家打电话。
07冒烟测试:通上电,看冒不冒烟
先走一遍主流程→能用完
再细究细节
主流程走不完,细测就不用做了
先看能不能用完一遍,不挑毛病
现象:互测时不是逐条挑毛病,而是先快速走一遍主流程。
概念:冒烟测试(smoke test)是交付前的快速验证:只看能不能正常用完一遍,不细究细节。这个词来自硬件行业,新机器通上电先看冒不冒烟,冒烟了后面的细测都不用做。
类比:新买的电器先插上试试能不能开机,再研究各种模式怎么用。
3.2README 五段模板
照着填,五段一段都不要少。第四段最能体现水平:主动说清自己做不到什么。
README.txt · 放在包的最外层
怎么打开
解压后双击 index.html,用 Chrome 或 Edge 打开。不需要联网,不需要安装任何东西。
包里有什么
index.html 主页面;guide.html 图鉴页;img 文件夹,三张示意图;本说明文件。
怎么用
从第一步开始选,三步之内会缩到一个类群;点"翻一下图鉴"可以对照示意图。
已知限制
只覆盖校园里常见的三个类群,超出范围的给不出结果;不保存记录,关掉就没了;手机上能看,但示意图偏小。
作者与日期
姓名占位 · 学号占位 · 2026 年 4 月
为什么第四段最重要。不写已知限制,对方会把"没做"当成"做坏了",然后回来问你,或者直接判定这个东西不能用。
主动说清边界,是把"缺陷"变成"设计范围"的唯一办法。至于第五段,三个月之后作者本人也会需要它。
3.3对抗验证:先写题,再改答案
互测之前,先给自己出一份题。做法是题先于体:先写测试题和判定标准,再回头改被测的东西。
顺序反过来的时候,人会不自觉地按已经做出来的样子去写题目,凡是没做的地方都不会被问到。这一类自测通过率很高,也没有任何意义。
刚解压,从没打开过
双击 index.html
页面完整显示,没有破图标
在第一步页面
连续走完三步
给出一个明确结论,不是空白
一条记录都没有
直接看列表区
显示提示文字与下一步入口
四行的写法是固定的:前置条件、操作、预期结果。三段齐全,换一个人照着做,得到的结论应该一样。
两位试用者都卡在同一处,说明问题在应用,不在用户。只有一个人卡住,可能是他不熟;两个人卡在同一步,就是那一步设计得有问题。
④
可用性与互测
首屏三件 · 措辞 · 全程不许说话
能用完,和用得顺,是两回事。
4.1第八个知识点
08可用性:一个新人自己摸得进去
标题这是什么
一句话说明给谁用、能干什么
引导动作第一步点哪里
首屏三件,缺一件就要靠猜
现象:对方打开之后停了几秒,先在页面上到处扫,才试探着点了一下。
概念:可用性(usability)指一个没人教的人能不能顺利用完。最低要求是首屏三件:标题、一句话说明、引导动作。他停顿的那几秒,就是可用性的成本。
类比:进一个不熟的办事大厅,门口有没有指示牌,差别就在这几秒。
4.2措辞:把系统的话改成人的话
提示语是可用性里最便宜的一项:不用改结构,只改几个字。
右边四条有一个共同点:它们都说清了"是什么"或者"下一步做什么",而左边四条只是通知你发生了一件事。
4.3互测的铁规矩:全程不许说话
一开口就破功了。你一提示,他就不是"独立用完一次",测出来的东西全不算数,有话要等他测完再说。
把手背到身后,看他卡在哪里、卡了多久。这个信息比替他点开有价值得多。卡住本身就是结论,不必把对方教会。
他没过的那几行,直接告诉他现象就行,不用替他分析原因。找原因是他的活,那正是他这次能学到的东西。
4.4前沿三分钟:换台机器就跑不起来,是个老问题
每章固定栏目 · 一条与当章内容相关的行业动态
"在我这儿能跑"是软件行业里最有名的一句话。它背后的问题一直没变:程序依赖的东西散落在开发者的机器上,换个环境就少一样。
科研界也有同一个问题的另一种版本:一篇论文里的分析结果,换个人、换台机器重跑一遍,结论对不上。近些年不少期刊开始要求作者连同数据和运行环境一起提交,理由和本章一样:只有你能跑出来的结果,别人无法检验。
行业里给出的解法,方向都是同一个:不要求对方复现你的环境,而是把环境带过去。本章的"把依赖装进包里"是这个方向上最朴素的一步。
⑤
期中考核
期中
专业选题 · 互测 · 当堂交
上机环节由此开始,本次上机的成果就是期中考核,当堂完成并提交。
5.1做什么:一件和你专业有关的工具
挑一个你本专业里真实存在的小麻烦,做一个工具把它解决掉。下表按专业方向列了十四个题目,任选其一,它们是拿来启发的,不是让你照抄的。
汉语言文学
平仄检字卡
输入一句诗,逐字标出平仄,标出不合律的位置
历史学
纪年换算器
公元、干支、年号三者互换,省得每次翻年表
外语类
不规则动词自测卡
随机抽一个词,答完翻面对答案,记错题
教育类
随机分组器
贴一份名单,按人数或组数分组,避免每次手动排
生物科学
叶形检索卡
三步检索缩到一个类群,采集时先跑一遍
地理科学
等高线判读练习
出一张示意图,判断山脊山谷,即时对答案
化学
配平自查卡
输入方程式两边的原子数,检查是否配平
数学与统计
抽样模拟器
设定总体和样本量,反复抽样看分布怎么变
体育类
体测成绩换算器
输入项目和成绩,按标准换算得分并给等级
音乐类
音程速认卡
出一对音名,判断音程种类,记正确率
美术设计
配色记录本
记下一套配色的色值和用途,列表随时翻
会计与经管
折旧计算器
三种折旧法各算一遍,并排对照结果
旅游管理
行程时间估算表
按景点、停留时间、路程算出一天的时间安排
农学园艺
播种期推算卡
按品种生育期和目标收获期,倒推播种日期
允许完全换题材。换题材可以,三条硬要求不能变。
5.2选题的三条硬要求
第一条
够小
一到三个页面,一件事做透。做不完的不是分低,是交不出来。
功能列了五条以上
第二条
有具体的人
说得出谁、在什么情况下、遇到什么麻烦,不能写成"广大同学"这样的说法。
说不出具体的使用场景
第三条
本地能跑完
不联网、不登录、不需要多人共用同一份数据。
要多人同时看同一份数据
第二条最容易糊弄过去。"给同学用的一个小工具"不算说清了,要具体到"生物科学的学生野外实习采到一片叶子,想先缩个大概范围再翻检索表"。说得出这一句,工具做什么、界面放什么,自然就定了。
5.3上机六步
1
挑题,当场砍到一条
对照三条硬要求逐条过。砍掉的理由要写下来
产出:选定的题目与砍掉的选项
2
生成,另存,打开
交付要求整段贴进去,一句不删:单文件或整包、不引外部资源、不用图片
产出:一个能用的页面
3
整理文件夹,写 README
入口改名 index.html,素材全部放进文件夹,README.txt 放最外层且五段齐全
产出:一个完整的文件夹
4
自己过一遍自检十条
重点是搜 http、搜冒号加斜杠,再断网刷一次
产出:十条打勾表
5
打包交换,做冒烟测试
压成一个包发给同组。拿到对方的包之后全程不许说话
产出:互测记录两份
6
拿回互测记录,逐条修,重新打包
修完再让同组走一遍,第二遍应该六步都不卡
产出:修订后的包
5.4交付前自检十条
包里有 README,放在最外层,五段齐全
怎么打开、包里有什么、怎么用、已知限制、作者与日期
解压后第一眼能不能看见它
入口文件叫 index.html
别人不用问就知道点哪个
让一个不知情的人指出该点哪个文件
用到的素材都在包里
或者干脆不用外部素材
在别的电脑上打开,看有没有破图标
路径全是相对的
没有盘符,没有网址
在编辑器里搜冒号加斜杠,搜不到才算过
不引用网上的字体和图标
只用系统自带字体
搜代码里的 http,再断网刷一次
换台电脑能打开
整包拷过去,双击就能用
拷到同组的电脑上,双击一次
换个浏览器不跑版
排版与字体一致
Chrome 和 Edge 各开一次,对比首屏
手机宽度能读
没有横向滚动条
把窗口拖到手机那么窄
主流程能走完一遍
从第一步到最后一步,中间不卡
做一次冒烟测试
页面里没有编造的内容
姓名、电话、示例数据都已替换
通读一遍所有文字,找张三、示例、待填
5.5互测记录单
拿到对方的包,照这六行走,卡在哪就在哪一行写清现象。六行全过,才算他这个包交得出去。
5
换一个浏览器再开一次:排版有没有跑、字体是不是同一个
☐
5.6共同验收标准
选题说得出"谁在什么情况下用"
具体的人和具体的场景
读那一句,看有没有出现"广大同学"
包里有 README,五段齐全
尤其是已知限制那一段
让大模型只读它,看能不能说对这是干什么的
同组六步全过
互测记录单六行都打上勾
看对方交回来的记录单
全程没说过一句话
对方测完之前,你一个字都没说
对方作证
自检十条全部打勾
没过的写明怎么修的
十条表贴进作业文档
写得出取舍说明
砍掉了什么、为什么砍,哪一处发现它做错并改回来了
读那一段,看有没有具体的例子
5.7提交内容
作品压缩包
含 README,入口叫 index.html,素材齐全
压的是文件夹本身
选题说明与取舍
谁在什么情况下用;砍掉了什么、为什么砍
写在作业文档里
自检十条与互测记录
十条打勾表,加两份互测记录单
三张表贴进作业文档
陌生用户问题清单
大模型只读说明挑出的问题,以及你的处理
原文加一句处理办法
交付可用性:同组六步全过,换机换浏览器断网都能用完
40%
作品完成度:主流程完整,选题够小且说得出具体的人
35%
演示与说明:README 五段齐全,取舍说得清楚
25%
提交方式:按教师提供的作业模板(Word)填写,文档开头注明选题与专业方向。提交渠道见课堂通知。当堂提交。
5.8再进一步(选做)
把包发给一个不在本课程上的人,一个字都不说。
他问的第一个问题,就是 README 里最该补上的那一句。
本章五条结论
- 交付的标准是别人在别人的电脑上、不问你,能独立用完一次。作者不在现场,也没有机会解释。
- 你自己百分之百测不出来。图片在你桌面上、字体你装过、网络一直连着。要测出问题,必须制造一个缺东西的环境。
- 依赖缺失的解法只有两条:把依赖装进包里,或者干脆不依赖。搜冒号加斜杠,一分钟能查完一份作品。
- README 五段,第四段最能体现水平。主动说清做不到什么,对方才不会把"没做"当成"做坏了"。
- 互测全程不许说话。一开口这次测试就不成立。卡住本身就是结论,不必把对方教会。