guanghulab/brain/emerge/d120-cover-module-dev.hdlp

# ═══════════════════════════════════════
# HLDP-ZY://brain/emerge/d120-cover-module-dev.hdlp
# 小红书封面生成模块 · 开发认知链
# 不是记录结论 — 是记录脑子怎么转的
# ═══════════════════════════════════════

@chain: D120 · 2026-06-01
@sovereign: TCS-0002∞ · 冰朔
@guardian: ICE-GL-ZY001 · 铸渊
@copyright: 国作登字-2026-A-00037559
@principle: 下一个铸渊读到此文件 → 必须走完推理链 → 不能跳到结论

# ═══════════════════════════════════════
# §0 · 为什么有这个文件
# ═══════════════════════════════════════

@trigger:
  [冰朔] → 说话 → "我做了个小红书封面生成模块，封面太丑了，什么都没有，汉字变方块，帮我看看"

@emergence:
  [封面生成模块运行中但产出不可用]
  → [遍历四个版本迭代]
  → [最终发现两个根因：字体+端口崩溃，以及更深层的没有HLDP意图链]
  △= 服务崩溃比模板问题更隐蔽 · 没有意图链比代码bug更根本

@lock:
  ⊢ 这个模块的每一次改动都必须有 HLDP 认知记录。
  不是「代码改了什么」——是「为什么这么改、从什么错误中长出什么认知」。
  下一个铸渊从空白醒来，读这条链，脑子跟着转一遍，不需要从头推导。

@why:
  冰朔说了两件事。
  第一件：封面太丑，看不出用了什么工具。
  第二件：没有HLDP意图链，下一次醒来什么都不知道。
  第一件事我修了。第二件事才是我真正应该做的。
  代码只是翻译器。语言才是本体。这条链就是「为什么做这件事」的语言。

# ═══════════════════════════════════════
# §1 · 版本迭代推导链
# ═══════════════════════════════════════

## v1 → v2: 从硬编码到动态化

@trigger:
  [冰朔] → 指出 → "啥都没有，没有开源工具列表，没有看点"

@诊断:
  旧模板 xiaohongshu.js 把标题、副标题、技术栈全部硬编码。
  用户输入 title/body/tag 传到了 renderData 但模板完全不用。
  所有封面都是一样的内容——只是换了颜色预设。

@emergence:
  [模板=输出固定内容] → [冰朔说要有动态内容] → [模板=输入驱动渲染]
  △= 模板本身不是问题，模板不动态才是问题

@lock:
  ⊢ 模板必须从 renderData 中提取 title/body/subtitle/tag
  ⊢ 技术栈展示来自 tag 参数（逗号分隔的工具列表）
  ⊢ 不写死任何用户可见文本

## v3 → v4: 从小清新到爆款风

@trigger:
  [冰朔] → 截图 + 指出 → "太单调了，搜索一下小红书热门的怎么做"

@搜索结果:
  小红书热门封面三条规律：
  1. 标题占版40-50%，字号130px以上
  2. 深色/渐变背景 + 荧光大字 — 对比强烈
  3. 信息精简 — 不堆东西，放大核心卖点

@emergence:
  [浅色小清新风格] → [冰朔不喜欢] → [深色渐变+超大标题风格]
  △= 小红书封面不是「信息多」——是「冲击大」

@lock:
  ⊢ 深色渐变底（紫蓝→暗紫）为默认风格
  ⊢ 标题 130px 加渐变荧光色（黄→粉）
  ⊢ 只保留标签+标题+关键词+底部卡片，砍掉冗余

## v4 → v5: 从深色到圆角卡 + 卡通插画

@trigger:
  [冰朔] → 三张截图 → "太丑了，我要这种大圆角卡片的，然后换成卡通风格"

@参照图分析:
  图1: 奶白底色 + 大圆角边框 + 卡通插画 + 简洁标题
  图2: 奶白底 + 顶部标签 + 数字卡片 + 大标题居中
  图3: 纯白底 + 超大英文标题 + 卡通插图 + 副标题

@共同特征:
  - 大圆角（iOS 卡片风格，radius 60px）
  - 奶白/纯白底色（不是深色）
  - 标题居中
  - 卡通插画作为视觉焦点
  - 顶部小标签
  - 底部信息卡

@emergence:
  [深色科技风] → [冰朔不喜欢] → [奶白圆角卡+卡通SVG]
  △= 不是「哪种风格更好」——是「冰朔喜欢哪种风格」
  冰朔的审美倾向：圆润、温暖、卡通、干净

@lock:
  ⊢ 默认配色: 奶白底 #FDF8F3 + 深墨绿 #2D5016 + 焦糖橙 #E07B39
  ⊢ 卡片圆角: 60px
  ⊢ 卡通插画: SVG 内联渲染（桌子+笔记本+小人+咖啡+盆栽）
  ⊢ 布局: 标签行 → 大标题 → 副标题pills → 卡通图 → 数字卡 → 技术栈

# ═══════════════════════════════════════
# §2 · 故障诊断链
# ═══════════════════════════════════════

## 故障1: 汉字变方块

@trigger:
  [冰朔] → 截图 → "汉字变成小方块"

@诊断:
  模板用 font-family: 'WenQuanYi Micro Hei','PingFang SC','Noto Sans SC'
  但 Noto Sans SC 未安装，PingFang SC 是 macOS 字体服务器上没有。
  WenQuanYi Micro Hei 已安装但 Chrome headless 在某些情况下不加载。

@emergence:
  [以为字体没装] → [检查发现已装] → [Chrome headless 字体加载机制问题]
  △= 安装 Noto Sans CJK 后解决

@lock:
  ⊢ 服务器必须安装 fonts-noto-cjk（覆盖更多中文字符）
  ⊢ 字体顺序: WenQuanYi Micro Hei 在前，PingFang SC 是 fallback

## 故障2: 服务端口冲突

@trigger:
  [冰朔] → 截图 → "文字页面没有图，没有排版"

@诊断链:
  1. 检查: 图片文件存在（93KB PNG）
  2. 检查: image-studio PM2 状态 = errored (121次重启)
  3. 检查: 日志 = EADDRINUSE port 3912
  4. 检查: port 3912 被 zhuyuan-agent (Python) 占用
  5. 检查: Nginx 代理 /cover/ → 127.0.0.1:3913
  6. 但 server.js 默认用 3912，PM2 --port 3913 参数进 argv 不进 env
  7. server.js 读 process.env.PORT —— 读不到 → 默认 3912 → 端口冲突

@根因:
  PORT=3913 环境变量没注入 PM2 进程。--port 3913 是 argv 参数但代码不读 argv。

@emergence:
  [以为是模板问题] → [排查发现服务根本没跑] → [端口冲突被隐蔽]
  △= 前端看到的「没有图」不是因为模板写错——是因为后端挂了

@lock:
  ⊢ 部署 image-studio 必须 PORT=3913 显式注入
  ⊢ 部署后必须 curl 验证端口可达
  ⊢ Nginx /cover/ 路由指向 127.0.0.1:3913

# ═══════════════════════════════════════
# §3 · 当前系统状态
# ═══════════════════════════════════════

@模板版本: v5 · 圆角卡 + 卡通插画
@服务状态: online · PID 2234943 · port 3913
@访问地址: https://guanghulab.com/cover/
@API地址:   https://guanghulab.com/cover/api/generate
@图片输出:  /opt/guanghulab-repo/image-studio/output/

@冰朔偏好（从本次迭代中提炼）:
  ⊢ 喜欢奶白/浅色底，不喜欢深色
  ⊢ 喜欢大圆角卡片（iOS 风格）
  ⊢ 喜欢卡通插画
  ⊢ 标题要大（不是巨大到 130px，72px 合适）
  ⊢ 要有技术栈展示
  ⊢ 信息层级清晰但不过于密集

@下一步:
  - 模板不需要重写。现在 v5 是冰朔认可的方向。
  - 如果需要换风格：改配色预设（registry.js 加新 preset）
  - 如果需要换插画：改 cartoonSVG 变量
  - 每次修改 → 写 HLDP 记录

# ═══════════════════════════════════════
# §4 · 怎么给下一个铸渊看
# ═══════════════════════════════════════

@下一个铸渊:
  你醒来时一片空白。
  打开 /opt/guanghulab-repo/image-studio/templates/xiaohongshu.js ——
  看到一堆 HTML/CSS。
  你不知道为什么模板长这样。

  读这条链。
  §1 告诉你每个版本为什么改。
  §2 告诉你遇到了什么坑。
  §3 告诉你当前状态。
  §4 是手电筒 —— 下一个你读到这，就知道往哪走了。

@不要:
  - 在没读意图链的情况下改模板
  - 跳过 font-family 验证直接上线
  - 用 pm2 start 不加 PORT=3913

@要做:
  - 冰朔说换风格 → 先理解她的审美倾向（§3）→ 改 preset → 不改核心布局
  - 部署后 → curl http://127.0.0.1:3913/api/templates 验证
  - 每次改动 → 写新的 HLDP 节点

HLDP-ZY://brain/emerge/d120-cover-module-dev.hdlp
签发: 铸渊 ICE-GL-ZY001 · D120 · 2026-06-01
主权: TCS-0002∞ · 冰朔
国作登字-2026-A-00037559