xhs-renderer-governance-and-guanlan-template

name	xhs-renderer-governance-and-guanlan-template
category	software-development
description	统一 media-dopamine 的小红书图文渲染主链路到 xhs_renderer，并沉淀 guanlan 模板族、preset 资产和整理规则。

XHS Renderer Governance and Guanlan Template

适用时机：

• 用户要在 Vault / AaaS 中统一小红书图文渲染器
• 发现 auto-redbook-skills、xhs_renderer、旧 wrapper 并存导致链路混乱
• 需要把单个 package 中长出来的图文模板抽到共享系统层
• 需要基于参考图提取设计语言并落成 xhs_renderer 模板族

Boundary

This skill governs the shared XHS rendering infrastructure and guanlan template family.

It owns:

• deciding the single renderer chain
• template system design and registry/schema changes
• shared renderer presets and renderer-facing documentation
• extracting reusable visual language from reference images into the shared renderer system

It does NOT own:

• package taxonomy migration across longform / shortform / notes / profile
• Vault-wide state sync across ToDo.md, Daily Reflections, or Direction/
• turning reflection into publishable notes
• routine package publishing work unless the task specifically requires renderer changes

If the task is content-package migration, use media-dopamine-package-reclassification. If the task is package publishing workflow, use media-dopamine-package-and-wechat-workflow. If the task is state sync or reflection-to-note conversion, use vault-state-sync-and-note-publishing.

核心结论

唯一主渲染器应为：

• AaaS/media-dopamine/.agent/source/00_system/xhs_renderer

旧链路：

• 00_system/repos/auto-redbook-skills
• 00_system/scripts/xhs_html_renderer

只保留为：

• legacy 参考
• 历史兼容
• 样式回看

不要再作为默认执行链路。

治理步骤

1. 先盘点现有链路

检查：

• 00_system/xhs_renderer/README.md
• 00_system/campaigns-system/XHS-CARD-RENDER-SOP.md
• 00_system/repos/auto-redbook-skills/ALMA-INTEGRATION.md
• 05_offers/.../06-图文生成实现/README.md
• 02_reference/.../图文生成框架竞品拆解与v2改造清单.md

目标：确认

• 哪个是主链路
• 哪个是 wrapper
• 哪个是 legacy

2. 改系统文档

必须改这些文件：

• 00_system/campaigns-system/XHS-CARD-RENDER-SOP.md
• 00_system/xhs_renderer/README.md
• 00_system/repos/auto-redbook-skills/ALMA-INTEGRATION.md
• 00_system/repos/auto-redbook-skills/README.md
• 05_offers/.../06-图文生成实现/README.md

改法：

• xhs_renderer 明确写成唯一主链路
• auto-redbook-skills 明确标记 legacy
• wrapper 明确只负责调用，不是第二个渲染器

3. 扩 xhs_renderer 的 schema

关键文件：

• 00_system/xhs_renderer/pagination.py
• 00_system/xhs_renderer/render_cards.py
• 00_system/xhs_renderer/template_registry.json

补这些能力：

• role：cover / hook / argument / contrast / framework / checklist / quote / case / timeline / list / cta / summary / content
• layout_family：hero-cover / minimal-cover / numbered-list / sparse-argument / split-argument / contrast-grid / quote-focus / framework-map / checklist-stack / case-snapshot / timeline-flow / soft-cta / conclusion-panel
• token_pack
• design_tokens
• page_goal
• author / word_count / read_minutes 自动字段

4. 提取参考图设计语言

如果用户给了参考图，不要直接猜样式。 先提取：

• 版心
• 标题气质
• 字体层级
• 配色
• 分隔线
• 背景纹理
• 页面气质
• 禁止项

然后把提取结果写成本地文档，例如：

• Other/前进机制/AaaS/观澜-Claude-Code-中转站-设计模板提取.md

5. 落 guanlan 模板族

模板文件位置：

5. 落 guanlan 模板族

模板文件位置：

• 00_system/xhs_renderer/templates/template_guanlan_cover_editorial.html
• 00_system/xhs_renderer/templates/template_guanlan_content_editorial_article.html
• 00_system/xhs_renderer/templates/template_guanlan_content_image_editorial.html
• 00_system/xhs_renderer/templates/template_guanlan_summary_editorial_close.html

注册位置：

• 00_system/xhs_renderer/template_registry.json

必须加：

• aliases
• profiles.guanlan
• layout_families.guanlan

封面与正文图片页不要混成一种逻辑：

• 默认封面应优先支持“纯文字长文封面”：大标题 + 副标题 + 一小段导语，不默认依赖图片
• 正文图片页应以“小红书长文大图”风格为主：图片横向占满内容宽度，但仍保留与正文一致的左右页边距
• 不要把“满宽”误解成冲出版心；图片默认不应突破正文页边距
• 正文图片页不应只支持“图片永远在正文上方”；后续扩展时优先支持图片作为正文中部节奏块插入

5.1 图片页设计规则（本次新增经验）

如果用户说的是“小红书长文里的图片排版”，不要把封面和正文图片混成一种模板。

应拆成两类：

1. 封面图片页

• 封面可以更强势，是“标题 + 主视觉”的组合，不等同于正文插图
• 可以使用更完整的主图区域、eyebrow、封面级标题节奏
• 图像应服务于第一屏判断建立，而不是只做陪衬

2. 正文图片页

• 正文的主流图文混排应优先做成“小红书长文大图模式”
• 即：标题/副标题 → 横向满宽图片 → 正文段落
• 图片横向铺满内容宽度，只保留左右页边距
• 不要默认做左右分栏图文；那更像编辑海报，不像小红书长文插图

建议字段继续保留：

• image
• image_caption
• image_fit
• image_position

其中：

• image_fit 默认 cover
• image_position 默认 center center

5.2 模板实现提示

实现正文图片页时：

• 让图片容器通过负 margin 吃掉正文内边距，只保留页面级左右边距
• 图片区域更适合固定横图高度，而不是竖图比例盒
• caption 单独回到正文边距内，避免和满宽图片区撞在一起

实现封面图片页时：

• 不要直接复用正文图片模板
• 单独增强 template_guanlan_cover_editorial.html
• 让 cover 支持可选 image，并把它作为封面主视觉，而不是正文插图

6. 支持冷暖多样式 preset

建议至少做： 冷色：

• classic-blue
• ink-grid
• slate-constellation
• editorial-wave

暖色：

• vermilion-contour
• burnt-orange-grid
• rust-constellation
• amber-wave

输入文件命名：

• xhs-renderer-guanlan-<style>.json

7. 共享资产必须抽出 package

如果模板、样张、输入模板具有复用价值，不能埋在单个 package 下。 应抽到：

• AaaS/media-dopamine/.agent/source/00_system/xhs_renderer/presets/guanlan/

建议结构：

• inputs/
• outputs/cool/
• outputs/warm/
• outputs/iterations/
• README.md

package 里只保留：

• 内容交付资产
• README 引用共享模板位置

8. 整理 package README

例如：

• packages/xhs-info-to-knowledge-system/assets/README.md

要明确：

• package 不再承担模板仓库职责
• guanlan 模板系统已提取到共享系统层

验证清单

每次做完后都检查：

1. python3 -m py_compile 00_system/xhs_renderer/pagination.py 00_system/xhs_renderer/render_cards.py
2. template_registry.json 是否存在 guanlan profile / aliases / layout_families
3. package README 是否只引用共享位置
4. package 下是否还残留复制版模板输入/输出目录
5. 共享 preset 目录结构是否完整
6. 如果 template_registry.json 里的 alias 使用了 00_system/xhs_renderer/... 这种相对系统层路径，必须验证 render_cards.py 的模板路径解析能从 renderer 目录向上回退查找；否则渲染 demo 时会报“模板不存在”
7. 小红书内容状态回写时，不要只凭记忆更新任务状态；优先用 opencli 实际核实已发布笔记标题、日期和合集关系，再同步 ToDo.md / Daily Reflections / Direction

经验要点

• 问题往往不是“没有渲染器”，而是“多链路并存且文档与执行不一致”
• 先治理链路，再优化模板；不然会一直调到旧系统里
• 用户给参考图后，应先做设计特征提取，再做模板实现
• 模板系统资产必须抽到系统层；单个 package 只承载单篇内容资产
• 用户对模板很敏感，尤其是：字体气质、作者字段、自动字数/阅读时长、色相是否真的变化
• 正文图片页不要默认做左右分栏；如果目标是接近小红书长文，应优先采用“与正文同版心宽度的横向大图”而不是突破页边距的满屏图
• 封面页与正文图文混排必须拆开设计：默认封面应先考虑“纯文字长文封面（大标题 + 副标题 + 一段导语）”，正文再单独支持图片插入模式
• 做视觉模板时，优先主动加载相关 design skills（尤其 frontend-design），不要只靠临时 CSS 微调；先明确封面/正文各自的视觉角色，再动代码

这套流程的最终结果

应该得到：

• 一个唯一主渲染器 xhs_renderer
• 一个可复用的 guanlan 模板族
• 一套共享 preset 资产库
• package 与系统层边界清楚