slug 是硬校验,不是建议:正则是 ^[a-z0-9][a-z0-9-]{0,63}$ —— 首字符必须是小写字母或数字, 之后只允许小写字母、数字、连字符,总长 ≤64。中文、下划线、空格、大写、点号全部不合法。 中文目录名/文件名必须映射成英文或拼音 slug(见 §6 的映射表模板)。

固定四分类的圆点色(建分类时要给,取自 design/README.md 的 token 速查): pm=#2563eb · deep-dive=#16a34a · engineering=#f9c22e · frontier=#8b5cf6。

目录层级必须齐平到两层。 当前 Agent基础知识/ 是「分类/阶段/章节」三层,其余是两层。 三层的处理有且只有两种合法做法,选一种、别混用:

• A(推荐):每个「阶段」当成一个独立系列 → 15 个系列,分类都挂 pm 或 engineering;
• B:整个 Agent基础知识 是一个系列,阶段只体现在章节的 label 与 ordinal 里(如 1.1/1.2)。

2. 交付形态

为什么要 series.json:notes_chapter_upsert 需要 ordinal / label / pinned / title / summary / sourceUrl / publishedAt,而库里不存 frontmatter(R5 裁定)。 把这些写在正文顶部的 --- 块里会被原样当正文渲染出来 —— server 一个字节都不改。 所以元数据必须走 manifest,正文里只有正文。

3. series.json 结构

约束速查:ordinal 与 label 一一对应且系列内不重复;pinned: true 的那条固定 ordinal: 0。

4. 正文(.md)的硬要求

1. 标准 GFM,无 Obsidian 语法:不出现 [[wikilink]]、![[embed]]。 当前导出已满足(211 篇全 0 命中)。
2. 不含 frontmatter。元数据走 series.json。当前导出已满足。
3. 配图引用只能是站内绝对路径 /notes/<系列slug>/<文件名> 或 http(s):// 外链。 相对路径一律不合法 —— 站上没有那个路径,渲染出来就是破图。 当前导出有 56 处相对图片引用(assets/…),全部要改。 其中至少 1 处是语法坏的:![…](<assets/…(阶段-0-的-⭐-最小产出… 括号未配平, 见 Agent基础知识/阶段0-能力盘点与统一词汇/讲义-从模型到Agent产品的四层分工.md。
4. 站外相对链接要清理。当前导出有 73 处非图片相对链接,指向导出包里不存在的路径 (/tables/customers.md、./docs/typescript/、mention://user/userId …),线上全是 404。 处理方式二选一:改成可用的绝对 URL,或退化成纯文本/行内代码。
5. --- 前必须有空行。「一行文本紧跟 ---」在 CommonMark 与 Obsidian 里都会把那行文本 渲染成 H2 标题(setext heading),于是正文段落变大标题、「本章目录」锚点整体错位。 当前导出有 21 处(围栏代码块内的已排除)。 修法是在 --- 前插一个空行。
6. 单篇正文 ≤ 1 MiB(UTF-8 字节)。当前导出全部满足。
7. 正文不要用一级标题重复文章标题。文章页已经把 series.json 的 title 渲染成页面大标题, 正文再以 # <同样的标题> 开头,读者会连着看到两遍。正文的章节标题从 ## 起步,不跳级; 代码围栏成对闭合(第 5 条的检测依赖围栏配平)。 (这条是 R9 上线后才发现的:首批 205 篇里有 153 篇正文首行是与 title 一字不差的 # …, 前端把它降级成 <h2> 渲染,于是页面上标题连出两遍。判据:正文第一个非空行如果是 # X 且 X == title,删掉那一行。)

5. 收录范围(ROUNDS.md R5 所有者裁定,仍然有效)

6. 分类映射(建议,最终以你的裁定为准)

7. 配图

当前导出:55 张 PNG(共 77.3 MB,最大 1.84 MB)+ 1 张 JPG,全部要转 WebP 并改名。 另有 48 处 http 外链图片——保留外链还是下载本地化,请裁定(保留则境内可达性自负; 本地化则并入上面的流程)。

8. 交付前自检清单

逐条跑一遍,全绿再发:

• 每个系列目录名 = series.json 的 slug,且匹配 ^[a-z0-9][a-z0-9-]{0,63}$
• categorySlug 只出现 pm / deep-dive / engineering / frontier 四个值
• 每篇 .md 在 series.json 的 chapters 里有且只有一条;file 指向存在的文件
• 系列内 slug 不重复、ordinal 不重复;pinned: true 的至多一条且 ordinal: 0
• 全库 grep -c '\[\[' = 0(无 wikilink)
• 没有任何 .md 以 --- 开头(无 frontmatter)
• 没有任何 .md 的第一个非空行是与 series.json 里 title 相同的 # 一级标题(会重复渲染)
• 全库图片引用要么 /notes/<系列slug>/…,要么 http(s)://;零条相对路径
• 全库非图片链接:无指向导出包内文件的相对路径
• 无「非空行紧跟 ---」(围栏内不算)
• assets/ 下全是 WebP、文件名全小写、单张 ≤4 MiB,且每一张都被至少一篇正文引用
• 正文里引用的每一个 /notes/<系列slug>/<文件名> 都能在对应 assets/ 里找到
• AI资料 系的每篇都有 sourceUrl
• 内容分享/、原始资料/ 已从交付包移除

9. 满足之后怎么发布

发布走 MCP 管理面(/api/mcp,R6),顺序固定:

1. notes_category_upsert × 4(四个固定分类,只需一次)
2. 每个系列:notes_series_upsert → notes_asset_put(该系列全部配图)→ notes_chapter_upsert(逐篇)
3. 配图必须先于引用它的章节上传,否则文章上线后有一段破图窗口

notes_chapter_upsert 幂等:内容与库内完全一致时整行不动、不刷新 updatedAt,RSS 不会假装有更新。 重跑安全。