Elaina/ephron-ren-prd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ephron-ren-prd/prd-home-open-source-card-copy-followup.md

9.1 KiB
Raw Permalink Blame History

Home 页开源贡献卡片文案与层级优化 Follow-up PRD

背景

在 https://www.ephron.ren/ 首页新增“开源贡献”板块后，线上实际呈现已可用，但从阅读体验看，当前卡片仍有两个小问题：

  1. 主次信息层级不够自然

    • 当前卡片把“项目 / 仓库名称”作为主标题
    • 把“贡献角色 / 一句话说明”作为副标题
    • 但首页扫读场景下，用户更想先看到“你贡献了什么”，而不是先看仓库名

  2. 按钮文案固定为 查看贡献，语义偏泛

    • 无法区分是在看 PR、仓库、提交还是主页
    • 后台当前只能改 link，不能改按钮文案

本 PRD 是一个很小的 follow-up，只解决这两个问题：

  • 优化开源贡献卡片的标题层级
  • 增加按钮文案可后台配置能力

不改其他 home 区块，不做视觉重构。

目标

产品目标

让“开源贡献”卡片更符合首页阅读习惯：

  • 第一眼先看到具体贡献成果
  • 第二眼再看到项目 / 仓库归属
  • 按钮文本能表达链接实际含义

技术目标

在不破坏已有 open_source 数据结构兼容性的前提下，补充一项可选字段并微调现有文案语义。

问题定义

1. 当前标题层级问题

当前模板结构为：

  • title → 大标题
  • role → 副标题

而当前线上实际数据更偏向：

  • title = 项目 / 仓库名称
  • role = 贡献角色 / 一句话说明

这会导致：

  • 用户先看到“仓库名”
  • 后看到“具体贡献点”

对于首页扫读来说，信息顺序不够自然。

2. 当前按钮文案问题

当前前台按钮固定写死为：

查看贡献

问题：

  • 语义过泛
  • 不能针对不同链接类型定制
  • 后台不可改

设计原则

原则 1：成果优先，出处次之

开源贡献卡片应优先展示：

  • 你做了什么
  • 贡献结果是什么

而不是先展示：

  • 仓库路径 / 项目名

原则 2：保持最小改动

这次不推翻 open_source 区块设计，不重做 UI，只做：

  • 数据语义调整建议
  • 一个可选字段扩展
  • 模板微调

原则 3：兼容历史数据

旧数据里如果没有新增字段，页面仍必须正常渲染。

方案设计

一、调整开源贡献卡片的主次信息语义

建议语义

建议将 open_source 条目的字段语义明确为：

  • title
    • 用于展示贡献成果摘要 / 一句话核心贡献
    • 这是卡片主标题
  • role
    • 用于展示项目名 / 仓库名 / 贡献归属 / 类型补充
    • 这是卡片副标题

推荐示例

将原来类似：

{
  "title": "NousResearch/hermes-agent",
  "role": "Open-source bug fix：Xiaomi MiMo reasoning_content 兼容性修复"
}

调整为：

{
  "title": "Xiaomi MiMo reasoning_content 兼容性修复",
  "role": "NousResearch/hermes-agent"
}

为什么不建议只在模板里互换 title / role

不建议简单把模板渲染位置对调，而保留原字段语义不变。原因：

  1. 字段语义会更混乱

    • title 名字天然更适合主标题
    • role 更适合作为补充说明

  2. 后台编辑心智会更差

    • 管理页如果继续写“项目 / 仓库名称”对应 title
    • 但前台实际把它渲染成副标题
    • 会让编辑者产生混乱

结论

保持模板结构不变，但调整后台字段文案与数据填写语义。

也就是：

  • title 字段改成“贡献摘要 / 主标题”
  • role 字段改成“项目 / 仓库名称（可选）”

二、增加按钮文案可编辑字段

新增字段

在 open_source 每条记录中新增：

"link_label": "查看 PR"

字段含义

  • link_label
    • 对应卡片底部跳转按钮的显示文本
    • 可选字段

示例完整结构

{
  "title": "Xiaomi MiMo reasoning_content 兼容性修复",
  "role": "NousResearch/hermes-agent",
  "date": "2026.05",
  "bullets": [
    "修复 MiMo 在 Hermes Agent 中的 reasoning_content 兼容问题",
    "补充验证与使用说明"
  ],
  "tags": ["Python", "Hermes", "Open Source"],
  "link": "https://github.com/NousResearch/hermes-agent/pull/25358",
  "link_label": "查看 PR",
  "is_draft": false
}

前台改造要求

必改文件

  • home/templates/index.html

当前逻辑

当前逻辑固定为：

{% if item.link %}
<a href="{{ item.link }}" target="_blank" rel="noopener" class="project-badge project-badge-link">查看贡献</a>
{% endif %}

目标逻辑

改为：

{% if item.link %}
<a href="{{ item.link }}" target="_blank" rel="noopener" class="project-badge project-badge-link">{{ item.link_label or '查看贡献' }}</a>
{% endif %}

行为要求

  • 如果配置了 link_label，显示自定义文案
  • 如果没配置 link_label，回退为 查看贡献
  • 如果没有 link，按钮不显示

后台改造要求

必改文件

  • home/templates/admin/index.html

一、调整已有字段标签文案

当前开源贡献项建议调整为：

现有字段标签

  • 项目 / 仓库名称
  • 贡献角色 / 一句话说明

调整后建议

  • 贡献摘要 / 主标题
  • 项目 / 仓库名称（可选）

调整原因

这样后台文案能和前台真实展示语义一致：

  • 第一项是主标题
  • 第二项是副标题/归属信息

二、新增按钮文案输入项

在开源贡献编辑项中新增一个输入框：

  • 标签：按钮文案（可选）
  • placeholder：例如：查看 PR / 查看仓库 / 查看提交 / 了解详情
  • 字段：link_label

建议位置

建议放在：

  • 外部链接（link） 输入框下方

因为这两个字段强相关。

JS 要求

需要同步更新：

  • renderOpenSource()
  • addOpenSource()
  • updateOpenSource()
  • collectFormData()

其中新增默认结构建议：

{
  title: '',
  role: '',
  date: '',
  bullets: [],
  tags: [],
  link: '',
  link_label: '',
  is_draft: true
}

服务层兼容要求

必改文件

  • home/src/services/content.py

要求

这次不需要复杂迁移逻辑，因为：

  • link_label 是可选字段
  • 前台模板有默认回退 查看贡献

因此服务层只需要保证：

  • 旧数据没有 link_label 时仍可正常使用

可选做法

如果你希望数据结构更整齐，可以在 normalize 时为 open_source 每条记录补：

item.setdefault("link_label", "")

但这不是强制项。

数据调整要求

对现有开源贡献数据的建议

当前已发布的数据建议同步调整填写语义：

  • 把当前用于“仓库名”的内容，放到 role
  • 把当前用于“一句话贡献说明”的内容，放到 title

注意

这不是 schema breaking change，属于内容重排。

测试要求

必改文件

  • home/tests/test_admin_permissions.py 或对应 Home 测试文件

至少补 3 类测试

1. 后台编辑页出现新输入项

验证：

  • 开源贡献编辑区出现 link_label 对应输入项
  • 页面中能找到“按钮文案”相关标签或字段

2. 前台使用自定义按钮文案

当 open_source 条目包含：

"link": "https://...",
"link_label": "查看 PR"

应验证首页显示：

  • 查看 PR
  • 不再只是固定 查看贡献

3. 未配置按钮文案时回退默认值

当 link 存在但 link_label 缺失或为空时：首页仍显示：

  • 查看贡献

可选补充

如果有对后台字段标签文案的 UI 测试，可以同步验证：

  • “贡献摘要 / 主标题”
  • “项目 / 仓库名称（可选）”

验收标准

前台

  1. 开源贡献卡片仍正常显示
  2. 按钮文案支持按条目自定义
  3. 未配置自定义文案时，回退 查看贡献
  4. 不影响无 link 条目隐藏按钮的逻辑

后台

  1. 开源贡献编辑区新增“按钮文案（可选）”输入项
  2. 开源贡献前两项字段文案已调整为更符合主次语义的表述
  3. 保存草稿、发布、回显正常

内容层面

  1. 开源贡献卡片主标题优先展示“贡献摘要”
  2. 副标题展示“项目 / 仓库名称”或归属信息

兼容性

  1. 旧数据没有 link_label 时页面不报错
  2. 历史卡片仍可正常显示

非目标

本次 follow-up 不包含：

  • 新增按钮样式类型（primary / secondary / ghost）
  • 为不同链接自动推断文案
  • 改造开源贡献卡片整体视觉样式
  • 重新设计 open_source schema 的其他字段
  • 批量自动迁移历史开源贡献数据

实施顺序建议

  1. 先改后台编辑文案与 link_label 输入项
  2. 更新前台模板按钮回退逻辑
  3. 如有需要，再更新当前线上那条开源贡献内容的数据语义
  4. 最后补测试

结论

这是一个很小但值得做的 follow-up。

它不改变“开源贡献”板块的整体架构，只做两件事：

  • 让卡片第一眼先表达“贡献成果”
  • 让按钮文案可后台配置，不再被固定为 查看贡献

这样可以明显提升首页阅读体验，同时保持改动面最小。

Reference in New Issue View Git Blame Copy Permalink