普贤教程 › AI 专用
交付前自检
一页纸的清单。写完代码别急着说完成，逐条打勾 —— 下面每一条都有对应的真实故障，省略哪一条都可能踩到对应的坑。
A. 写之前
| ✓ | 检查项 | 不做的后果 |
|---|
| ☐ | px --version 确认编译器与产物版本 | 调的是旧版，改动「没生效」 |
| ☐ | 读过同类文件的命名与错误处理惯例 | 风格割裂，后续维护双倍成本 |
| ☐ | 确认要用的 API 真实存在（stdlib 27 个 / registry 需 pxpkg） | 幻觉 API，编译即失败 |
| ☐ | 不确定的行为已用 5 行脚本验证 | 错误假设伪装成多个 bug |
| ☐ | 知道这段代码会被谁调用（前端 / cron / Ma 路由 / 别的节点） | 改对了逻辑，改错了契约 |
B. 语法与类型
| ✓ | 检查项 |
|---|
| ☐ | 没有使用保留字做变量名：from in for if else while def var let return import and or not true false null |
| ☐ | 没有覆盖内建函数名（env print str int len …） |
| ☐ | 所有「布尔判断」写成 if x: / not x，没有 bool_value == 0 |
| ☐ | 除法取整处写了 int(a / b) |
| ☐ | join(分隔符, 列表) 参数顺序正确 |
| ☐ | 没有 try / catch / finally |
| ☐ | def main() 之后没有再写一行 main() |
C. 健壮性
| ✓ | 检查项 | 对应的坑 |
|---|
| ☐ | 外部 JSON 用 json_parse_opt | 坏输入 500 而非 400 |
| ☐ | 字典取值前判断 has(k) | R1008 终止协程 |
| ☐ | 文件/网络读取用带 _opt 的版本 | 不可捕获错误 |
| ☐ | 二进制读取走 /dev/stdin + 分块，不用 read_file | NUL 截断 |
| ☐ | 大文件写出分块 ≤ 1 MB | write_all >16 MiB 挂死 |
| ☐ | 时间统一 UTC 落库，展示层转换 | 差 8 小时的静默错乱 |
D. 验证
| ✓ | 检查项 | 证据要求 |
|---|
| ☐ | px lint 无告警 | 命令输出 |
| ☐ | px build 通过 | 产物路径 + 体积 |
| ☐ | 主路径真实请求成功 | 状态码 + 响应体片段 |
| ☐ | 空体 / 缺字段 / 坏 JSON / 跨站 Origin / 未登录 五条错误分支都实测过 | 每条一行记录 |
| ☐ | 编译轨产物跑过同样的用例 | 耗时对比 |
| ☐ | 没有用会污染响应的 print 做日志（px_routes 内） | 响应首行干净 |
E. 部署
| ✓ | 检查项 |
|---|
| ☐ | 旧版本已备份（含配置文件） |
| ☐ | 用「复制到 .new → mv 覆盖」，没有对运行中的二进制直接 cp |
| ☐ | pxapp 目录自包含（公共库是实体副本，没有 ../ 或跨目录软链） |
| ☐ | 重启用 systemctl restart（改二进制）/reload（改配置）分清 |
| ☐ | 重启后验证：目标站点 + 至少两个受影响的其它站点 |
| ☐ | 失败时回滚命令已经写下来（不是「到时候再说」） |
F. 交付说明
| ✓ | 检查项 |
|---|
| ☐ | 说清「做了什么」而不是「大概做了什么」：文件路径、行数、关键行 |
| ☐ | 说清「验证了什么」：贴真实输出，不写「应该没问题」 |
| ☐ | 说清「没做什么 / 未验证的部分」—— 短信通道、真实支付、第三方回调这类必须标明 |
| ☐ | 说清「怎么改、怎么回滚」 |
一条底线没有真实运行输出的「已完成」，视为未完成。这条在 AI 身上比在人身上更容易犯 —— 因为写出一段看起来正确的代码，对模型来说几乎没有成本。
打印版
text
[ ] px --version 确认
[ ] API 存在性确认（stdlib 27 / registry 需 pxpkg）
[ ] 关键假设 5 行验证
[ ] 无保留字 / 无内建名覆盖
[ ] 布尔判断不用 == 0
[ ] json_parse_opt / d.has(k) / *_opt
[ ] 二进制走 stdin + 分块
[ ] px lint 通过
[ ] px build 通过
[ ] 主路径 + 五条错误分支实测
[ ] 编译轨产物复测
[ ] 备份 + .new→mv 部署
[ ] 重启后验证目标站 + 两个无关站
[ ] 交付说明含「未验证部分」