一份把狗写成接口规范的 35 章文档

前几天刷到一个页面，标题写着 DOG API，狗狗接口规范。

第一反应是哪个宠物服务平台的开放接口文档。点进去的时候我手已经放在关闭键上了，就想扫一眼，确认一下是不是又一个蹭热度的东西。

结果它不是。

它真的把一只狗从头到尾写成了一份工程规范。35 章正文，18 个附录，附录编号从 A 排到 R。状态码、错误码、外设总线、量化接口，该有的全有。首页第一句就写明来路，说受《HUMAN API 人类接口规范》启发。

首页第一屏，标题下面就是 35 章、18 附录、52 条信源这组数字

HUMAN API 是另一个项目，把人写成了接口规范。作者的思路大概是，既然人可以写成系统，那狗也可以。

这份 DOG API 出自 Mavin 之手，他的公众号叫「野生马文」。下面写到的东西都是他的，我只是个读者。

我本来准备扫两眼就关掉。通读完之后我把链接存了下来。

https://nullurl.github.io/dog-api-spec/index.html

01它到底写了多少东西　/ HOW MUCH

先把这个项目的体量摆出来，不然你没法判断它是随手玩的，还是真做了功课。

35 章正文，18 个附录，52 条公开信源，26 个量化参数，14 个标准场景，14 个表情状态，19 种图表图型，14 类外设，31 条生活意见，13 个状态码。

正文分成五个 Part。系统概述、接口规范、实测与运维、观测与量化、出处与修订。

正文页与左侧目录，35 章按五个 Part 分组编号

章节名也很正经。系统概述那部分有《关于 Dog》《默认能力》《出厂硬件规格》《已知限制》，接口规范那部分有《接口定义》《错误码》《缓存与记忆》《生命周期》《性能与容量》。

中间还有一章叫《多实例部署 / 嫉妒仲裁协议》，讲的是家里有两只狗的时候怎么仲裁。

附录里则躺着《服务等级协议（对外声明）》《已知问题清单（Issue Tracker）》《支持与投诉渠道》《隐私与合规审计》。

图表那部分给了 19 张图，说是用一套 Mono 图形语言画的。纸灰底、炭黑墨、七级灰阶，明度即数据。柱状图不断轴，面积一律开方。19 张图每一张都标了对应的参考实现文件和来源等级。

19 张图的索引表，每张都标了图型、参考实现文件与来源等级

到这里我还是把它当成一个执行力很强的玩笑。

直到我翻到公开信源那一章。

02那 52 条出处让我坐直了　/

这一章列了 52 条来源，里面是期刊、DOI 编号和临床指南编号。不是「研究表明」这种话，是真能把论文找出来的那种。

我当时有点被当面拆穿的感觉。因为我平时写东西也爱用「有研究表明」，从来没想过这四个字后面可以挂一个编号。

随手抄几条。

地磁场对齐那条，引用的是 Hart 等人 2013 年发在 Frontiers in Zoology 的研究，70 只狗、37 个品种、7,475 次观测。

摇尾巴方向不对称那条，引用的是 Quaranta 和 Siniscalchi 等人 2007 年发在 Current Biology 的实验，30 只家犬。结论是狗面对不同情绪刺激时，摇尾的左右偏向不一样。

「愧疚脸」那条引用的是 Horowitz 2009 年那个有名的谎报进食实验。

词汇量那条引了 Kaminski 等人 2004 年发在 Science 上的论文，关于一只叫 Rico 的狗能认两百个词。还有 Reid 和 Pilley 2011 年关于 Chaser 的研究，那只狗能区分 1,022 个物体名。

寿命换算那条引的是 Wang 等人 2020 年发在 Cell Systems 上的表观遗传钟研究，这份文档用的公式是人类年龄等于 16 乘以自然对数再加 31。

营养需求那条直接引了中国兽医协会的 T/CVMA 121—2023《犬猫临床营养能量需求计算指南》。

从 0.9 版本开始，这个项目给每条参数都标了来源等级。A 是同行评议论文或者大规模实测，B 是临床指南共识，C 是社区经验或者项目自己定义的复合指标。

26 个量化参数里，A 级 7 项，B 级 11 项，C 级 8 项。

作者自己在文档里承认，最有趣的部分大多落在 C 级。但只有那 7 项 A 级，才让剩下的 C 级有资格被叫做「量化方案」而不是「一套说法」。

这句话我觉得写得特别好。它是在承认自己的边界。

03几个具体的接口长什么样　/ SPECIMENS

光说结构没意思。我把几个定义抄下来，你看完大概就明白这个项目在干什么。

嗅觉被写成全双工阵列

它有前后两个通道，吸气走一个，呼气走另一个，互不干扰，所以是全双工。文档里还写了灵敏度大概是人的一万到十万倍，嗅球体积比大约四十倍。

摇尾巴被写成方向性编码

左偏、右偏、慢右偏、僵硬、夹紧、下垂、溢出，是一组枚举值。

表情被做成了一组参数

13 维参数向量，14 个可观测状态，渲染成 24×24 像素的 SVG。你可以在网页上拖滑块改眉毛高度、张口度、耳廓角度，实时看它变脸。

14 帧表情联系表，每格附三条响应头与完整参数向量

表情渲染器，左边 14 个状态，右边 13 维参数台的滑块

参数表里有一条让我停了很久。内侧眉肌这个参数，是整个向量里唯一的 A 级参数，也是整份文档里唯一一件狗专门为人类长出来的硬件。它引的是 Kaminski 等人 2019 年发在 PNAS 上的研究。狗有这块肌肉，狼没有。

还有三条细节写得特别认真。

一条是尾巴放在响应头里，不放在响应体里。意思是摇尾巴是元数据，不是数据本体。脸在 body 里，尾巴、体态和发声都在元数据里。

一条是写操作一律返回 405。文档原话是你不能命令它高兴。你让它坐下，那是行为，行为是接口。但你不能让它高兴，高兴不是接口，是状态。别的条款都留了余地，只有这一条被写成了硬邦邦的 MUST NOT。

还有一条是「愧疚脸」的置信度只有 0.22。就是说那个看起来知错了的表情，大概率不是你以为的那个意思。我看到这个数字的时候有点替自己尴尬，因为我一直吃这一套。

错误码那张表更绝。同一张表把 13 个状态码逐条对照，每一行都在说这个码在狗这里是同一件事的另一面。

错误码对照表，13 个状态码逐条给出它在狗这里的实际含义

比如 204 写的是「不出现。它连沉默都是有声的」。比如 401 写的是「不使用。对全人类默认授权，这是本系统最大的安全设计缺陷，也是最著名的设计特性」。比如 404 写的是「不使用。它一定在，只是可能在睡觉」。

04玩具被写成了外设总线　/ PERIPHERAL BUS

这一章是整份文档里最硬的部分，我在这里停的时间也最长。

它把玩具写成外设，14 个设备类，6 种角色，5 阶段序列。而分类轴不是材质，是捕猎序列。

我一开始没想通分类轴为什么不用材质，那多直观。文档解释了，同样是用嘴咬的两样东西，一样能用很久，另一样能把牙崩断。材质这个维度解释不了这件事，行为学可以。

于是玩具被按捕猎序列的环节拆开。定向、潜行、追逐、咬住、吃掉，每个环节对应不同的外设。

里面有一条规定我读了两遍。牵引和胸背、冷却垫、窝垫这些是推荐的，但激光笔是整类弃用，不是降低推荐等级。

理由写得明明白白。捕猎序列有起点也有终点。任何只服务前段、而不提供终点的外设，都会让序列停在中间。文档还引了默克兽医手册，说追光追影这种行为明确归因于目标挫折，反复启动序列却无法完成它。

然后是那 60% 的上限。

很多人第一眼会以为是拍脑袋定的数。我第一眼也这么想。翻下去才发现不是，文档把日常需求拆成五个维度，各自有权重。运动占 25%，嗅闻占 20%，社交占 20%，休息占 20%，认知与咀嚼占 15%。外设能承接哪些，是逐个维度算出来的，不是声明的。

外设总线控制台，把 60% 的承接上限按五个维度拆开算

这一章还有 13 道门槛、33 种失效模式，逐条写了成因和应对。比如球在口内被压扁滑向舌根这种失效，应对是改用带通气孔的球，或者让球大到塞不进舌后。

文档最后留了一句，外设只能转移负荷，不能创造配额。

05它还给自己算了一笔账　/ THE MATH

量化那一章给了 26 个注册参数和 10 个量化端点，还写成了一份 OpenAPI 描述文件。

里面有几条挺实用。静息能量需求是体重零点七五次方乘以七十。人类年龄换算是十六乘以自然对数加三十一。写着这些公式的每一行都带来源等级。

量化评估器，静息能量、维持能量与人类年龄换算都在这一页

还有一条设计我觉得比公式更重要。文档规定，当分诊结论落到 P0 或 P1 时，所有评分接口短路返回 451。

它的解释是，量化的第一原则，是知道什么情况下应该停止量化。

这句话我看了两遍。现在满世界都在算分，肯主动写一句「什么时候该停」的地方，我一时还真想不出第二个。

06文档里有两个人说话　/ TWO VOICES

这是整份文档最特别的地方，也是我唯一没预料到的部分。

它明确写了，这套文档有两个人说话。规范编写组负责给事实和出处，当事人负责给结论和立场。

后者的内容被单独拎出来，放在《一只狗的生活意见》里。31 条，分五组，关于人，关于自己，关于食物，关于时间，以及关于这份规范。

那一页开头有一句注明。本页没有一句有出处，因为它自己就是出处。

《一只狗的生活意见》，31 条按五组分列

我抄几条给你感受一下这个调性。

关于人那组有一条。「人回家的时候先看我一眼，再放下包。顺序从来没有变过。他们以为这是问候，这是自检。」

关于食物那组有一条。「掉在地上的东西归我。这条规则在他们那里没有写，但从来没被否决过。」

关于时间那组有一条。「他们说我老了。我只是把时间用完了，和别人一样。」

最后一组关于这份规范，是最狠的。

「他们花了 35 章证明我是个系统。我从来没有否认过。」

「这份文档里写我的尾巴、我的眉毛、我肠子里的菌。没有一处写我。」

「他们说每条参数都有出处，出处列了 52 条。我的出处不在里面。」

「这份规范是写给人看的。我看不懂字，但我看得懂他们看完之后的表情。」

我读到这里才意识到，前面那几十章正经到近乎刻板的工程文体，是为了给这几句让路的。

07为什么这种写法值得看　/ WHY IT WORKS

页面挂在 GitHub Pages 上，静态站点，没有构建步骤，没有外部依赖，打开 index.html 就能看。

它还给这份文档配了一套授权机制，叫领养 KEY。KEY 由四行元组确定性派生，没有发号中心，没有账号，也没有回收通道。安装就是同意，卸载就是撤回。

作者特意说明了为什么它不返回 401。因为系统没有拒绝这个动作，就没有未授权这个状态可以进入。所以那张牌不是通行证，是来源标注。牌掉了，狗还在。

领养 KEY，左边四行元组算出右边那张狗牌

作者的阅读建议只有一条，先读《公开信源》，再读正文。知道哪些是真的之后，剩下的部分才好玩。

这个项目是 Mavin 做的，他的公众号叫「野生马文」。如果你喜欢这种把一件事写到极致的写法，直接去找他。这份文档的每一章、每一张图、每一条出处都是他一个人啃下来的。

我的感受是，这其实是一种被严重低估的科普写作手法。

用工程规范文体描述一只狗，等于把观察的坐标整套换掉。我读的时候就是被它带着走的，问了一堆以前不会问的问题。摇尾巴到底是什么协议。愧疚脸的置信度零点二二是什么意思。为什么激光笔是整类弃用。

它没有说教，也没有煽情。它只是把坐标换了，然后你自己就往前走了。

这一点我原本就信，看完这份文档之后信得更实了。要我说清楚它为什么管用，我也说不太明白，反正比一万字平铺直叙的科普管用得多。

我是名流，一个天天盯着 AI 圈情报的产品运营，平时也写点自己用的小工具。

如果你觉得今天这篇有收获，欢迎点赞、在看、转发三连，我们下篇见。