BaseHalf
全部文章

把会被判错的写法,记在规则旁边

我们在 BaseHalf 文件夹里打开 RFC 9457,从官方 PDF 生长出一则笔记,核对省略 type、生成端的 status 不一致,以及 about:blank 时的 title,再把会被判错的写法连同官方规则写回同一页问题里。

我写 HTTP API 的错误响应时,常常先写成看起来像 problem details 的样子,随后才发现漏掉的字段,或所谓「写得更精确」的字段,并不符合规则。我想把会被判错的写法放在官方原句旁边,而不是只留在关掉就会消失的对话里。

我把 RFC 9457 的官方文本放进一个文件夹,再在 BaseHalf 0.7.0 里打开它。这份 RFC 的标题是 Problem Details for HTTP APIs,作者是 M. Nottingham、E. Wilde 和 S. Dalal,由 IETF 于 2023 年 7 月发布,并废止了 RFC 7807。我在 2026-11-15、Asia/Shanghai 时间从 RFC Editor 取回了 PDF 和 纯文本,留在文件夹里阅读,不会把整份文件重新发布。一份简短的 SOURCE.md 记录了这些事实,包括两个文件的 SHA-256。同一天我还看了 RFC Editor 的勘误表。勘误 7731 处于「待更新文档」状态,涉及附录 A 模式示例里的 additionalProperties。勘误 8858 是已报告、尚未核实,涉及附录 A 的模式标题仍写着 "RFC 7807"。这两条都不会改动本笔记所核的第 3.1.1、3.1.2 和 4.2.1 节里关于 type、status 和 about:blank 的规则。

我先写了 question.md,在核对原文之前,写下三个初步判断。

  1. 如果一份 problem document 省略了 type 成员,是不是就没有 problem type?初步判断:是。缺少 type,这份文档就没有类型。
  2. 生成端可否发出 HTTP 404 响应,而问题文档里写着 "status": 400?初步判断:可以。正文可以带一个比 HTTP 响应行更精确的状态。
  3. 如果省略了 type,title 可否写成一句一次性的话,比如用 "The thing you asked for is gone" 来表示 404?初步判断:可以。title 不过是对这一次情况的简短说明。

我在 Card Detail 里打开 PDF,搜索 When this member is not present,落到第 6 页的第 3.1.1 节,选中那里开头的那句话,然后使用 Grow branch。这生成了 rfc9457-note.md,它已经把 rfc9457.pdf 列为 upstream,并带有引用块和指向第 6 页的来源链接。产品把标题和引文截在了引号处,所以这则笔记没有记下 about:blank。我按产品写出的样子留下了它。

我把官方文本和这则生长出来的笔记写进 question.md 的 upstream 列表,从而把它们连上。画布上随即在这些文件之间出现了连线。SOURCE.md 就在旁边,但我没有连接它。放在旁边是给我自己看的。连线才是应当留下来的上下文。

problem-details-type 文件夹的 BaseHalf 画布:左侧是 rfc9457.pdf 和 rfc9457.txt,中间是生长出的笔记并连入问题,右侧是 SOURCE.md,它没有连到问题上。

Card Detail 打开 rfc9457.pdf,位于第 6 页第 3.1.1 节,官方原句已选中,工具栏里可见 Grow branch 按钮。

我选中问题卡片,并在 Agent Area 里启动 Claude Code。Agent Area 是会话运行的地方,它本身并不是那个 agent。我请它阅读 question.md 以及仅限其 upstream 里的文件,对三个问题分别说明我的初步判断对不对,给出答案,并引用官方规则和章节号,同时不要改动任何文件。

它打开了这些文件,1 分 7 秒之后,也就是 18:21 Asia/Shanghai,它说我的三个初步判断都是错的。本次 Claude Code 是 v2.1.325,模型为 Opus 5.5,xhigh 力度,Claude Ultra。

同一块画布旁,Agent Area 里的 Claude Code 在 1 分 7 秒后给出了核对结论,并可见官方关于 title 的规则。

我没有停在模型的措辞上。我对照官方文本核对了同样的句子。

  1. 省略 type 并不表示没有类型。第 3.1.1 节写着: "When this member is not present, its value is assumed to be "about:blank"." 第 4.2.1 节补充说,任何没有显式 type 成员的 problem details 对象都隐含使用这个 URI,而 about:blank 表示该问题除了 HTTP 状态码之外没有额外语义。
  2. 生成端必须在 HTTP 响应和 status 成员里使用同一个状态。第 3.1.2 节说,这个成员对消费端只是建议性的,并且: "Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly." 会被判错的写法是:HTTP 404,正文里却写着 "status": 400。第 5 节提到,如果中途的中间设备改了 HTTP 状态,两者可能不一致。那说的是传输过程中的故障,并不等于允许生成端发出不一致的组合。
  3. 那句一次性的话,不是正确的 title。省略 type 时,类型就是 about:blank,第 4.2.1 节说 title SHOULD 是该状态码的推荐短语,例如 404 用 "Not Found",不过 MAY 按客户端语言做本地化。第 3.1.3 节说,title 是对问题类型的简短概括,除本地化外,不应随每一次出现而改变。这句话属于 detail(第 3.1.4 节),也就是针对这一次情况的说明。

我把这些核对过的答案,连同章节号、用到的原句和会被判错的写法,写回同一页 question.md,放在事先留好的标题下面,并保留标题上面的初步判断。在 Card Detail 里,Preview 会显示明天重新打开时仍在的答案和引文。Source 视图则显示同一文件顶部的 upstream 列表:rfc9457.pdf、rfc9457.txt 和 rfc9457-note.md。

Card Detail 以 Preview 打开 question.md,可见初步判断仍在,核对后的答案写在下面,并带有 RFC 章节和会被判错的写法。

同一文件的 Source 视图,frontmatter 里是 upstream 列表,下面的 Markdown 是核对后的答案。

这并不是一个会自动给每个文件作答的笔记本,也不是内置摘要。状态栏里的选中只在窗口打开时有效。官方文本、生长出的笔记、问题和带有判错写法的核对答案,都是文件夹里的普通文件。即使我关掉对话,那一页仍然在,错误的写法和规则还挨在一起。