企业官网建设流程全解析

• 文档
• 教程

导读

HowToCook（程序员做饭指南） 是一个由社区驱动的开源菜谱仓库，其独特之处在于：它把菜谱当作"数据"而非"文章"来维护，追求"形式化、可机读、可复用"。本文以仓库根目录下的 CODE_OF_CONDUCT.md 为骨架，结合 .github/manual_lint.js 校验器、示例菜模板 与 LICENSE，系统解读 HowToCook 的四大仓库原则（弱协议、尽可能形式化、非商业、AI 友好）及其在源码中的落地方式。读完本文，你将理解为什么该仓库能被网站、小程序、MCP 工具甚至 AI 模型二次开发，以及如何按同一套规范贡献菜谱。

为什么维护这个仓库：从"精准菜谱"到生命管理系统

CODE_OF_CONDUCT.md 开篇记录了作者 @Anduin2017 维护仓库的动机：健身 App、手环、医疗平台、买菜平台、外卖平台、智能冰箱等基础设施彼此缺乏沟通能力，用户需要花费大量精力在它们之间周旋计算。文档设想了一个理想的生命管理体系——当医生建议"50 天减肥 15 斤"时，各类应用能够联动：自动设计健身计划、计算应吃的饭菜、自动补货、避免过期、推荐食谱、核算热量摄入与消耗，并根据体重秤数据持续矫正。

在这一宏大设想中，HowToCook 的定位被明确为一句话：

提供一份足够精准的菜谱。

文档强调：对于额外的附加功能开发、可视化、智能化、平台对接、饮食产业等，均可引用这个仓库中的菜谱进行二次开发。也就是说，菜谱本身不是终点，而是整套生命健康系统里"一块可靠又强大的螺丝钉"——它的核心价值是数据准确性与可机器处理性。这正是理解仓库全部设计原则的出发点。

仓库原则总览

CODE_OF_CONDUCT.md 将发展原则归纳为：维持精准的特点，尽可能在保证阅读的同时，统一格式，方便二次开发，并细化为四条可执行的原则：

下面逐一展开。

弱协议：以公有领域授权释放复用限制

"弱协议"原则的目标是让商业公司、饭店、企业或科研机构能够无障碍地引用这个仓库。文档明确声明：任何人都可以自由复制、修改、发布、使用、编译、出售或以菜谱的形式或菜的形式分发，无论是出于商业目的还是非商业目的，以及任何手段。

这一原则在仓库中的直接体现是根目录的 LICENSE 文件，它采用的正是 Unlicense 公有领域协议：作者将软件的全部版权利益奉献给公众，放弃所有现在和未来的权利。协议同时附带"AS IS"免责声明——软件按现状提供，不附带任何明示或默示的担保。这意味着：

• 二次开发者无需担心授权费用或分发限制；
• 下游产品可以自由地将菜谱嵌入 App、小程序、网站甚至商用系统；
• 仓库因此更适合扮演"基础设施"角色，而非封闭的私有内容源。

值得注意的是，HowToCook 的目标读者并不仅限于人类：文档中写道"这份菜谱更多的不是给人类阅读的，而是更多的可能会被机器处理"。弱协议正是为了给机器处理扫清法律障碍。

尽可能形式化：让菜谱可以被计算机理解

"尽可能形式化"是 HowToCook 区别于普通菜谱博客的核心原则，包含三层要求：统一菜谱的文件格式、避免不精准（尤其是计算机无法理解）的单位和操作、保持清晰的目录结构。

清晰的目录结构

仓库在dishes/目录下按食材类别组织菜谱，包括素菜、荤菜、水产、早餐、主食、半成品加工、汤与粥、饮料、酱料和其它材料、甜品等分类，每个菜谱通常独占一个子目录，例如 小龙虾、清蒸鲈鱼。此外tips/目录存放厨房准备、食品安全等通用知识，tips/learn/与tips/advanced/存放从入门到进阶的烹饪技法。这种稳定的路径结构本身就具备"可被程序枚举和索引"的数据特征。

强制统一的文件格式：manual_lint.js 校验器

仓库用脚本强制保障格式统一。根目录 package.json 的lint脚本串联了 textlint、markdownlint 与自定义校验：

"scripts": { "build": "node ./.github/readme-generate.js", "manuallint": "node .github/manual_lint.js", "textlint": "textlint . --fix", "markdownlint": "markdownlint ./dishes ./tips", "lint": "npm run textlint && npm run markdownlint && npm run manuallint && echo 'Lint finished. All passed.'" }

其中 .github/manual_lint.js 是自定义的菜谱规范校验器，对dishes/**/*.md逐文件执行十余项检查。以下是它实际强制的关键规则（含源码行号定位）：

1. 文件名规则：菜谱文件名不能包含空格（manual_lint.js），保证路径可被稳定引用；
2. 主标题与章节结构：主标题必须是# 菜名的做法，且必须严格包含四个二级章节## 必备原料和工具、## 计算、## 操作、## 附加内容（manual_lint.js）。这保证了每个菜谱都是同样的数据 schema；
3. 元信息：主标题与第一个二级标题之间必须包含预估烹饪难度：★...★（1-5 颗星）与预估卡路里：XXX大卡（manual_lint.js），为机器提供可比较的难度与热量数据；
4. 操作章节必须使用有序列表：1. 2. 3.逐条编号，禁止使用无序列表（manual_lint.js），确保操作顺序可被程序按序号执行；
5. 禁止非精准词汇：适量、少许、左右、min均不被允许（min因存在多重含义被建议改为"分钟"）；勺、杯这类容器单位也被禁止，必须给出克（g）或毫升（ml）（manual_lint.js）。这正是文档所说"避免计算机无法理解的单位"的代码级实现；
6. 禁止人称代词：菜谱中不得出现"你""我"（manual_lint.js），保持描述的中立与可复用；
7. 描述长度约束：菜谱介绍必须在 30-300 字之间，并包含菜品特点、营养价值、难度和制作时长（manual_lint.js）；
8. 图片规范：图片 alt 文本必须包含具体菜名，不得使用"成品""效果图""摆盘"等泛称或拼音缩写（manual_lint.js），同时校验引用的图片文件真实存在（manual_lint.js）；
9. 统一收尾文案：每个菜谱末尾必须保留"如果您遵循本指南的制作流程而发现有问题或可以改进的流程，请提出 Issue 或 Pull request 。"（manual_lint.js）；
10. 文件大小限制：所有文件不得超过 1MB（manual_lint.js），避免仓库过度膨胀。

此外，菜谱中不允许出现 HTML 注释（模板文件除外，manual_lint.js），保证内容纯净。

模板即规范：示例菜

示例菜模板 是上述规则的"活文档"，也是贡献者写新菜谱时复制的起点。它通过注释给出了完整的填写指南：

• 预估烹饪难度采用 1-5 星分级，每级对应明确的耗时与经验要求（示例菜.md）；
• 必备原料和工具列出必需原料，帮助读者快速判断手边材料是否足够；燃气灶、饮用水、锅等已在厨房采购部分提及的基础物资不重复列出；
• 计算章节要求给出"每份"的量或计算公式：对于大小不一的食材必须给出质量参考，对于可自行斟酌加量的食材必须给出建议范围，且明确要求"请不要使用有大有小的容器作为单位"，统一使用毫升（示例菜.md）；
• 操作章节禁止"适量""少量""中量""适当"等模糊词汇，凡需等待的步骤必须给出时间公式或结束判断标准（如"等待直至咖喱融化""外观呈粘稠状态"）（示例菜.md）。

这一模板直接对应了文档中"按照同一份菜谱做菜，不同的人也能得到几乎相同的结果"的目标——形式化是为了消除歧义、保证可复现。

形式化的实际效果：以两份菜谱为例

仓库中的真实菜谱充分体现了上述规则的产出效果：

• 小龙虾.md 在"计算"章节给出两斤小龙虾的完整量化清单：油 70 毫升、香叶两片、八角一个、桂皮 3 克、青花椒 10 克、子弹头辣椒 5 克、姜 30 克、蒜 7 瓣、郫县豆瓣 30 克、黄豆酱 30 克、啤酒 500 毫升、生抽 30 毫升、盐 10 克，所有关键原料均有可执行的数量；
• 清蒸鲈鱼.md 在"操作"章节严格使用有序列表，从切姜丝到淋热油共 11 步，并对"鱼肚内塞姜葱白"等关键手法给出明确说明。

这些菜谱可以被搜索引擎、菜谱 App 甚至 AI Agent 直接解析为"原料清单 + 量化步骤"的结构化数据。

非商业：无广告、不绑定品牌、易取材

"非商业"原则有三条具体承诺（CODE_OF_CONDUCT.md）：

1. 永不插入广告：HowToCook 将永远不插入广告，避免内容被商业流量绑架；
2. 不耦合特定品牌：尽可能避免菜谱中的材料耦合特定品牌，防止菜谱依赖某个厂商的产品；
3. 使用容易取得的原材料：尽可能使用容易取得的原材料，降低读者的执行门槛。

这一原则与"弱协议"形成互补：协议层面放开商业复用，内容层面却主动拒绝商业化污染。仓库中的菜谱严格区分"必需原料"与"可选推荐"——例如 示例菜模板 在原料清单中写道"咖喱块（推荐品牌好侍）"，品牌只是降低决策成本的参考，而非必需约束。文档同时声明 HowToCook"永远不讨论变现问题"，并承诺永远由社区驱动维护，界定了项目的非营利治理基调。

AI 友好：面向模型的开放训练

"AI 友好"是仓库原则中最具前瞻性的一条：社区可以使用这个仓库训练任何类型的 AI，并且允许商业使用（CODE_OF_CONDUCT.md）。

从源码结构看，这一承诺的可操作性建立在前三条原则之上：

• **弱协议（Unlicense）**为训练和商用提供了法律上的确定性；
• 尽可能形式化为 AI 提供了高质量的结构化训练语料——统一的章节 schema（必备原料和工具 / 计算 / 操作 / 附加内容）、精确到克和毫升的量化数据、无歧义的操作步骤，天然适合被语言模型或任务规划类 Agent 理解与执行；
• 非商业确保了语料中不夹带广告噪音和品牌植入。

仓库中面向 AI 的衍生工具已成为佐证：README 的"衍生作品推荐"一节收录了 HowToCook-mcp、HowToCook-py-mcp 等 MCP 工具，其定位正是"让 AI 助手变身私人大厨，为一日三餐出谋划策"。从仓库结构可以推断，这类工具无需处理格式各异的非结构化菜谱，直接按固定 schema 读取dishes/下的 Markdown 即可完成检索与执行，这正是"形式化"为 AI 场景带来的直接价值。

衍生产物：二次开发生态与边界声明

CODE_OF_CONDUCT.md 最后指出：目前社区中已有许多基于 HowToCook 二次开发的小程序、App、网站等，并给出了重要的边界声明——HowToCook 仓库与任何衍生产物没有任何合作关系和知情义务，所有衍生产物的行为准则并不受 HowToCook 的行为准则约束，也不代表 HowToCook 仓库的价值观。

这一声明值得二次开发者仔细阅读：

• 一方面，仓库欢迎并乐见衍生生态（弱协议 + AI 友好原则为二次开发扫清障碍）；
• 另一方面，衍生产物的合规性、内容质量与价值观由开发者自行负责，与主仓库无关。

对想要基于本仓库构建应用（如菜谱 App、饮食管理系统、AI 烹饪助手）的团队而言，这意味着：可以放心地引用菜谱数据，但需要在自身产品层面自行承担用户协议、内容审核与安全责任。官方还提供了便捷的查看与部署途径：菜谱可通过 README.md 中给出的 Docker 镜像（aiursoft/howtocookviewer）在本地部署为可视化 Web 服务，便于直接体验仓库的完整内容。

从源码验证原则的落地

将文档原则与仓库代码对照，可以得到完整的落地验证链路：

此外，.github/workflows/ci.yml 的存在表明校验脚本可在持续集成中自动执行，确保每一位贡献者提交的菜谱都符合规范——从仓库结构可以推断，PR 合入前会经过格式与内容校验，这正是"尽可能保证阅读的同时统一格式"在工程层面的保障。

如何参与：遵循同一套规范

如果你希望为仓库贡献菜谱或修正现有菜谱，按照 README.md 的指引与模板要求：

1. 复制模板：从 示例菜模板 复制文件，删除所有注释后按模板结构填写；
2. 遵守格式规范：主标题为# 菜名的做法，四个二级章节齐全，包含难度星级与卡路里元信息，操作步骤使用有序列表，所有用量使用克（g）/毫升（ml），不使用"适量""勺""杯"等模糊单位；
3. 保持内容纯净：不出现 HTML 注释、人称代词，图片 alt 文本包含具体菜名且图片真实存在；
4. 本地校验：可运行npm run lint（包含 textlint、markdownlint 与 manual_lint）自检，通过后提交 Pull request。

正是这套"文档原则 + 脚本强校验"的组合，让 HowToCook 在保持人类可读的同时，成为一份可以被机器、AI 与各类应用稳定引用的精准菜谱数据源。

如果您遵循本指南的制作流程而发现有问题或可以改进的流程，请提出 Issue 或 Pull request。

• 文档
• 教程