Harness 与 Koa2 登录实践（一）：先别急着写代码，把「意图」钉成契约
配套开源仓库：harness-login-now-koa2
本文是系列第一篇， clone 仓库后对照implement guide/即可进行一次完整实现；附cursor分步骤提示词实现：juejin.cn/spost/76355…
这篇在讲什么
很多人接到「做一个登录」会立刻打开编辑器写路由。结果往往是：接口字段改来改去、和前端对不齐、Agent 多轮对话后「到底成功长什么样」没人说得清。
这一篇用大白话说明：我这次练习里采用的 Harness 思路——先把任务说清楚、再让实现和验收有共同标准——具体落在一个最小的 Koa2 会话登录 上是什么样子。不讲框架细节，只讲为什么这样拆步、第一步写什么。
Harness 是什么（一句话版）
可以把它理解成：给「写代码 / 用 AI 写代码」搭一套不容易跑偏的环境。
- 模型再聪明，如果成功标准模糊、上下文乱塞，输出也会飘。
- Harness 关心的是：任务怎么表达、上下文怎么裁剪、最后怎么证明做对了——而不只是「让 LLM 多试几次」。
本仓库把这套想法写进了 HARNESS-SELF-CHECK.md，用 八个要素 和当前登录系统做了一行对照；概念侧还可参考仓库里对「迷你 Harness」的归纳（意图、快照、验收、隔离等）。
为什么拿「登录」练 Harness
登录人人都熟，但细节很多：密码怎么存、会话用 Cookie 还是 JWT、错误码怎么统一、日志里会不会打出密码……若一开始没有单一事实来源，改着改着就会和「自己以为的」不一致。
所以这次练习刻意做成：
| 做法 | 通俗理解 |
|---|---|
| 契约先行 | 接口路径、状态码、JSON 字段、Cookie 名，先写在 implement guide/NOTES-API-CONTRACT.md 里 |
| 分阶段实现 | 从 /health 到注册、再到 session，每步都能单独验收 |
| 脚本闭环 | npm run verify 用 curl 串一整条链路，避免「我本地好像能登录」 |
仓库的 README.md 里把这些设计选择说得很集中：代码是练习体，重心是跑通「意图 → 契约 → 分阶段实现 → 可复现验收」。
第一步：输出契约（阶段 0）
在动 src/ 之前，先回答清楚几个问题：
- 注册、登录、
/me、登出分别是什么方法、什么路径？ - 成功时 HTTP 状态码是多少（例如注册成功用 201）？
- 会话方案定哪一种？本仓库定的是 httpOnly Cookie + 服务端 session，Cookie 名
app_session。 - 密码绝不出现在响应和日志里，磁盘上只存 bcrypt 哈希。
这些不是「文档形式主义」，而是给自己、同事、Cursor 里的 Agent同一个判据：什么叫做完、什么叫做错。
在 Cursor 里可以先把 harness guide 里的材料与 implement guide/NOTES-API-CONTRACT.md 钉在上下文，再让模型根据仓库产出或修订契约草案——这比从零口述「做个登录」稳定得多。更细的分步操作见仓库 implement guide/V1/KOA2登录系统-Harness与Cursor分步指南.md 的阶段 0。
和「八要素」怎么对上号（入门只记两条）
全表见 HARNESS-SELF-CHECK.md。入门阶段只要记住两条就够：
- 任务如何被表达 → 契约 + README 把接口写死。
- 系统如何验证真的做好了 → 后面会上的
npm run verify（第二、三篇会展开）。
其余六条（上下文组织、工具治理、状态保存与裁剪、反馈回流、错误分类、安全边界）会在实现过程中自然出现，不必一开始就背下来。
小结
- Harness 在这里不是新名词堆叠，而是：先契约、再小步实现、每步能验收。
- 登录 很适合练手，因为安全与接口边界特别需要「先写清楚」。
- 本仓库把契约、分步指南、自检表都放在
implement guide/与HARNESS-SELF-CHECK.md，方便你或 Agent 按图施工。
下一篇与仓库
- （二） 会按递进顺序讲：工程初始化 →
/health→ 用户文件与注册 → 登录与会话，以及每步怎么用curl快速验收。 - 完整源码与文档请直接访问：github.com/RonnyJung20… —— 建议 star 或 fork，跟着分步指南在自己的环境里跑一遍
npm run verify，体感会完全不一样。
