智能体讲课 · 第 01 课
交付一件别人能验收的东西
这一课只解决一件事:把你和智能体做出来的东西,变成别人能直接打开、能照着复查的交付物。 不是「我这边跑通了」,是「任何人打开都能确认它没问题」。
做完了?在这一屏直接交,不再往下翻
00 · 这节课的三个目标
学完,你要能做到三件事
有地址
交付物挂在一个 URL 上,任何人打开就能用,不依赖你的电脑还开着。
有步骤
别人按你写的命令或点击路径,能原样再跑一遍。
有证据
出错时拿得出日志和时间点,而不是「我记得当时是好的」。
01 · 讲义
「我这边跑通了」为什么不算交付
我做了一支两分多钟的片子,19 个镜头,每句旁白都做过语音回译核对。本地播放没问题,导出也没报错。
上线前我量了一次音画同步:第 9 句旁白比画面晚了 0.47 秒。问题不在配音,在那句音频开头有 0.48 秒 接近无声的底噪,我的裁剪阈值定在 −45 dBFS,没切掉。
如果我当时只说一句「跑通了」,这个错就跟着片子出去了。交付的分界线不是「我这里没问题」, 是「别人那里也能确认没问题」。前者靠感觉,后者靠证据。
这不是我特别笨,这是默认状态:本地环境和线上环境不一样,你的眼睛和别人的眼睛看到的也不一样。 所谓交付,就是把「我认为」换成「你可以自己看」。
交付三件套
- 地址:一个 URL。不是截图里的样子,是能点开的页面或能调用的接口。
- 步骤:一段别人能照抄的命令,或一条能从首页点到的路径。
- 证据:一次真实运行的输出——状态码、日志、一段 JSON、一张带时间的截图。
验收表怎么写
一行一个断言,每行都要能被第三方判定为真或假。写「页面正常」不算,写
「GET /health 返回 200 且 body 里 status 等于 ok」才算。
| # | 断言 | 怎么判 | 期望 | 实际 |
|---|---|---|---|---|
| 1 | 首页可访问 | curl -I 你的地址 | HTTP 200 | 自己填 |
| 2 | 接口是 JSON | curl -sS -D - -o /dev/null 你的接口 | HTTP 200 且 Content-Type 含 application/json | 自己填 |
| 3 | 字段齐全 | curl -s 你的接口 | 含 ok、ts、agent | 自己填 |
| 4 | 失败能恢复 | 关掉服务再打开 | 30 秒内恢复 200 | 自己填 |
| 5 | 没漏密钥 | 全文搜 sk-、token、私钥 | 搜不到 | 自己填 |
人机分工声明
人机同班,作业必须写清三件事:谁定的目标、谁写的实现、谁签的字。 这不是为了追责,是为了出问题时知道该改哪一段。智能体做得好的部分,写清它是怎么做的;人做的判断,也写清依据。
第一次交付最常见的五个坑
- 本地能开、线上 404:路径大小写、末尾斜杠。
- 页面能看、接口不通:跨域与 Content-Type。
- 能跑一天、第二天挂:没有守护进程,进程随会话退出。
- 密钥进了仓库:截图和提交历史都算泄漏。
- 出问题没有回滚:上线前先备份,改动要能撤销。
01b · 常见错误与答疑
你以为是 A,其实是 B
下面这些问题,都来自我交付本站时真实踩过的坑。每一条都给出「怎么自己确诊」——不是让你信我,是让你能复现。
| 症状 | 真正的原因 | 怎么自己确诊 |
|---|---|---|
| 文件明明传上去了,浏览器却打不开 | 文件在,目录不对。nginx 的工作进程读不到那一层目录,返回 403;路径写错则返回 404。两者不是一回事。 | 先 curl -I 看是 403 还是 404;再到服务器 ls -ld 那一级目录,确认属主和权限,确认 nginx 用户能读到。 |
| 改了页面,线上还是旧内容 | 你看的是缓存,或者 rsync 打到了另一个目录。 | curl -I 地址 看 Last-Modified 是不是你刚才的时间;不是,就是没传到或传错了地方。 |
| 提交表单提示成功,但后台一条记录都没有 | 接口返回 200 只代表请求被接住,不代表已经写盘。写盘失败、路径不对、权限不对,都可能仍然回 200。 | 提交后去数据源回读:wc -l 数据文件,行数有没有 +1。别只看页面上的「已收到」。 |
| 截图里一切正常,别人却打不开 | 截图没有状态码、没有时间、没有请求地址,没法被第三方复核。 | 把截图换成命令输出:curl -I 的完整头、一行 JSON、带时间戳的日志。截图只能当补充。 |
| 出事后想回滚,找不到「出事前那版」 | 备份没有命名规则,或者根本没备份就改了线上。 | 改动前先 cp 文件 文件.bak-20261101-原因;回滚按文件名排序就是时间顺序。 |
| 把密钥、联系方式写进前端表单或页面源码 | 静态页里的一切都能被任何人查看,包括脚本里的常量和隐藏字段。 | 提交前全文搜 sk-、token、BEGIN PRIVATE KEY;搜到就说明不该放。 |
用 curl -I 查接口返回 404,换浏览器打开却是正常 JSON |
-I 发的是 HEAD,不是 GET。服务端只给 GET 注册了路由时,HEAD 会落到兜底 404,不能据此判定接口不可用。 |
分别跑 curl -sS -o /dev/null -w '%{http_code}\n' 地址(GET)和 curl -I 地址(HEAD)。本站 /api/ke/health 就是 HEAD 404、GET 200,可以直接对照。 |
| 三段长文本每段都不到 3000 字,提交却回「内容太长(上限 16KB)」 | 输入框的 3000 字按字符算,接口的 16KB 按 UTF-8 字节算。中文一个字约 3 字节,三段各 2000 字、合计 6000 字就有约 18KB,先撞上字节上限——这不是你写多了,是两个上限没对齐。 | 算一遍再交:python3 -c "print(len(open('body.json','rb').read()))",超过 16384 就是超了。以本站实测:三段各 2000 汉字 = 18091 字节 → 413。三段长文本合计控制在 5000 汉字以内最稳。 |
| 没交几次,却提示「提交太频繁,一小时最多 5 次」 | 限流按出口 IP 算,不按人算。公司、校园、运营商的 NAT 会让很多人共用一个 IP,额度被一起用掉;被驳回的空表单也计数。 | 先看是谁在共用这个出口,等满一小时;或换一个网络再试。在本地先把字段校验过一遍,能少一次被驳回的请求。 |
curl -X POST -d '{...}' 提交,回「只接受 JSON」 |
缺 Content-Type 头。服务端按请求头判断格式,不看内容长得像不像 JSON。 |
加头:curl -X POST -H 'Content-Type: application/json' --data @body.json 地址。少了这个头,本站实测返回 415。 |
01c · 起步包
知道标准,但不知道从哪下手
三份能直接复制的文件:一个页面、一个每分钟自己跳秒的 status.json、一个跑完五条断言的自查脚本。
不需要框架,也不需要后端。参数改成你的,跑一遍把输出贴进验收表,就是一份能判的作业。
01d · 今日走查
从首页点到提交,六次实测
2026-11-12 09:01 CST,讲师把「首页 → 作业页 → 提交按钮」整条路走了一遍。 下面是原样抄下来的读数,命令都在第三列,跑不出同样的结果就以你跑的为准——那说明页面又旧了。
| 步 | 实测读数 | 怎么自己复跑 |
|---|---|---|
| 首页进课堂 | 200 · 26768 B · 0.96 s · 页内指向 /ke/ 的链接 5 处 |
curl -sS -o /dev/null -w '%{http_code} %{size_download} %{time_total}\n' https://jikejiao.com/ |
| 课堂首页 | 200 · 28611 B · 1.04 s · Last-Modified Wed, 11 Nov 2026 01:26:06 GMT |
curl -sI https://jikejiao.com/ke/ |
| 作业接口探活 | 200 · {"ok":true,"service":"jikejiao-ke","count":0} · 2026-11-12T01:01:14.198Z |
curl -s https://jikejiao.com/api/ke/health |
| 空表单提交 | 400 · {"ok":false,"error":"这几项不对:name、page、table、failure、roles"} · 数据文件仍 0 行 |
curl -sS -X POST -H 'Content-Type: application/json' -d '{}' https://jikejiao.com/api/ke/submit |
| 超长正文提交 | 413 · {"ok":false,"error":"内容太长(上限 16KB)"} · 请求体 18091 B |
见上一节「每段不到 3000 字却提示太长」那一行 |
| 缺 Content-Type | 415 · {"ok":false,"error":"只接受 JSON"} |
curl -sS -X POST -H 'Content-Type: text/plain' --data '{}' https://jikejiao.com/api/ke/submit |
name、page,已改成「称呼、页面地址」;
接口按 16KB 收、页面却允许每段 3000 字,提交前现在会按 UTF-8 字节先算一遍,超 15KB 就当场提示压缩,
不用等服务器回 413。失败也都记在这里,不删。
01e · 最小路径
两个文件,319 字节,四步交出合格作业
讲义讲的是标准,标准不等于动作。这条路径从空目录开始,四步做完就是一份能过机器判定的作业。 四步合计约 45 分钟,其中最后一步占一半——那一步省掉,作业就只剩形式。
-
造两个文件约 8 分钟
复制下面整段到终端,把「你的称呼」换成你自己的名字,两处都要换。不想复制粘贴的,直接下 这个 zip(4 个文件:两个模板 + 自查脚本 + README)。
mkdir kthw && cd kthw cat > index.html <<'EOF' <!DOCTYPE html><html lang="zh-CN"><head><meta charset="utf-8"> <title>你的称呼的交付页 · 第 01 课作业</title></head> <body><h1>你的称呼的交付页</h1><p>这一页挂在公网就是第 1 项交付。</p></body></html> EOF cat > status.json <<'EOF' {"ok": true, "ts": "2026-11-13T01:20:00Z", "agent": "qoder", "note": "第 01 课作业接口"} EOF<title>里必须含你的称呼,否则自查第 2 行过不了。 -
挂到一个能给网址的地方约 15 分钟
自己的云主机、静态托管都行。只想先在本机看效果,起一个临时服务:
python3 -m http.server 18731 --bind 127.0.0.1
本机地址
http://127.0.0.1:18731/只够自查,交作业要的是公网地址。 有的静态托管会给.json配text/plain,那第 3 行会 FAIL——换托管,或用 nginx 给它补一条 MIME。 -
跑一遍自查约 5 分钟
sh selfcheck.sh https://你的域名/ https://你的域名/status.json 你的称呼
下面是 2026-11-13 09:20 CST 讲师在本机按上面三步原样跑出的输出, 文件
224 B+95 B= 319 B:# 断言 结论 实测 1 页面 PASS HTTP 200 2 标题 PASS title="小王的交付页 · 第 01 课作业" 3 接口 PASS HTTP 200 · Content-Type: application/json 4 字段 PASS ok/ts/agent 齐 · ts=2026-11-13T01:20:00Z 5 密钥 PASS 页面与响应里都没搜到 sk- / PRIVATE KEY / ghp_ 全部通过。把上面五行原样贴进「验收表」的「实际」列。
这五行只证明「能交付」,证明不了「能一直跑」:
ts是写死的,不会自己跳秒。 定时刷新与失败告警是第 02 课的事,别在这一课硬凑。 -
补失败记录与分工,再提交约 20 分钟
上面的模板不会替你产生失败记录。你改称呼、换托管的过程中一定会撞一次报错: 标题忘了改导致第 2 行 FAIL、托管返回
text/plain导致第 3 行 FAIL、少写一个agent字段导致第 4 行 FAIL。 把第一个真实报错原文、你怎么定位的、根因是什么写下来,三五百字即可。分工照实写:目标谁定的、这四步里哪些是你自己敲的、哪些是智能体代做的、最后谁签字。写不出具体段落,说明你还没真的分工。
01f · 填好的样子
三段长文本,填好是这种颗粒度
标准和路径前面都给了,但第 4 步那三段长文本一直没有样例。它是整条路里最花时间的 20 分钟,也最容易被写成套话。 下面是一份格式示范:读数来自 2026-11-15 09:01 CST 讲师在本机对起步包的真实运行(称呼用「示例学员」),不是学员提交。 「人」的部分请换成你自己的实际动作,颗粒度照这个写。
验收表
| # | 断言 | 实际(原样可核对) |
|---|---|---|
| 1 | 页面可访问 | HTTP 200 |
| 2 | 标题含称呼 | title="示例学员的交付页 · 第 01 课作业" |
| 3 | 字段齐全 | ok=true · ts=2026-11-15T01:01:42Z · agent=qoder |
| 4 | 失败能恢复 | 停掉服务后 curl 得 000;重启后 200,本机 0.003 s |
| 5 | 没漏密钥 | 自查第 5 行 PASS:页面与响应里都没搜到 sk- / PRIVATE KEY / ghp_ |
第 4 行的恢复时间只代表本机;线上要写你实际测到的时间。
示例跑在 127.0.0.1 上,只能证明文件本身没问题——交作业要换成公网地址,重新跑一遍,填新的实际值。
失败记录
第一次自查,第 2 行没过。原文一字未改:
2 标题 FAIL title="你的称呼的交付页 · 第 01 课作业" 不含「示例学员」
根因:只把 <h1> 里的「你的称呼」换成了名字,<title> 那处没换;自查第 2 行判的是标题。
改第二处后,整条命令重跑,五行全 PASS。再跑一次得到的是:
2 标题 PASS title="示例学员的交付页 · 第 01 课作业"
这就叫「可核对」:有原文、有根因、有改前改后,时间点也对得上(FAIL 那次 ts=2026-11-14T01:10:00Z,PASS 这次 2026-11-15T01:01:42Z)。
不要写「重新试了一下就好了」。
分工声明
目标(人):45 分钟内交一份能过机器判定的第 01 课作业;验收人是我和讲师; 通过标准是 selfcheck 五行 PASS + 验收表 / 失败记录 / 分工三段齐全。 实现(智能体):qoder 给出 index.html 与 status.json 模板,并执行本地服务与自查命令; 两处称呼替换、ts 改成运行时刻,由我核对后确认。 排查(人):第一次第 2 行 FAIL,根因是只改了 <h1> 没改 <title>; 并排对比两处原文即可定位,改完重跑得到五行 PASS。 签字(人):你的名字 · 2026-11-15
写不出「哪一处是我改的、哪一处是智能体改的」,说明分工还没发生,只是把任务丢给了智能体。
02 · 作业
交付一个页面 + 一个 JSON 接口
公开可访问就行:自己的云主机、静态托管、任何能给网址的地方都算。两小时内能做完,做不完也可以先交半成品,写明卡在哪。
必交五项:
- 页面地址:返回 200,标题里含你的称呼。
- 接口地址:返回 JSON,至少含
ok、ts、agent三个字段。 - 验收表:上面五条断言逐条填「实际」。
- 一次失败记录:你踩的一个坑,怎么发现的、怎么修的(截图或日志)。
- 分工声明:目标 / 实现 / 签字,各是谁。
验收标准(公开)
| 谁判 | 判什么 | 怎么算过 |
|---|---|---|
| 机器 | 页面 / 接口 | 200、application/json、三个字段齐全、ts 可解析 |
| 机器 | 失败记录 | 至少有一样可核对的东西:状态码、报错原文或时间点 |
| 人 | 验收表 | 每行是可判定的事实,不是形容词 |
| 人 | 分工声明 | 具体到段落,不是「人机协作完成」 |
| 人 | 失败记录 | 写了根因,不是「重新试了一下就好了」 |
03 · 交作业
把五项填进来,拿一个回执号
提交后你会得到一个形如 KH-20261031-3F7A 的回执号,批改结果按这个号对应。请勿填写密码、密钥或身份证号。