395 lines
9.1 KiB
Markdown
395 lines
9.1 KiB
Markdown
# Home 页开源贡献卡片文案与层级优化 Follow-up PRD
|
||
|
||
## 背景
|
||
|
||
在 `https://www.ephron.ren/` 首页新增“开源贡献”板块后，线上实际呈现已可用，但从阅读体验看，当前卡片仍有两个小问题：
|
||
|
||
1. **主次信息层级不够自然**
|
||
- 当前卡片把“项目 / 仓库名称”作为主标题
|
||
- 把“贡献角色 / 一句话说明”作为副标题
|
||
- 但首页扫读场景下，用户更想先看到“你贡献了什么”，而不是先看仓库名
|
||
|
||
2. **按钮文案固定为 `查看贡献`，语义偏泛**
|
||
- 无法区分是在看 PR、仓库、提交还是主页
|
||
- 后台当前只能改 link，不能改按钮文案
|
||
|
||
本 PRD 是一个**很小的 follow-up**，只解决这两个问题：
|
||
- 优化开源贡献卡片的标题层级
|
||
- 增加按钮文案可后台配置能力
|
||
|
||
不改其他 home 区块，不做视觉重构。
|
||
|
||
---
|
||
|
||
## 目标
|
||
|
||
### 产品目标
|
||
让“开源贡献”卡片更符合首页阅读习惯：
|
||
- 第一眼先看到**具体贡献成果**
|
||
- 第二眼再看到**项目 / 仓库归属**
|
||
- 按钮文本能表达链接实际含义
|
||
|
||
### 技术目标
|
||
在不破坏已有 `open_source` 数据结构兼容性的前提下，补充一项可选字段并微调现有文案语义。
|
||
|
||
---
|
||
|
||
## 问题定义
|
||
|
||
### 1. 当前标题层级问题
|
||
|
||
当前模板结构为：
|
||
|
||
- `title` → 大标题
|
||
- `role` → 副标题
|
||
|
||
而当前线上实际数据更偏向：
|
||
- `title = 项目 / 仓库名称`
|
||
- `role = 贡献角色 / 一句话说明`
|
||
|
||
这会导致：
|
||
- 用户先看到“仓库名”
|
||
- 后看到“具体贡献点”
|
||
|
||
对于首页扫读来说，信息顺序不够自然。
|
||
|
||
### 2. 当前按钮文案问题
|
||
|
||
当前前台按钮固定写死为：
|
||
|
||
```jinja2
|
||
查看贡献
|
||
```
|
||
|
||
问题：
|
||
- 语义过泛
|
||
- 不能针对不同链接类型定制
|
||
- 后台不可改
|
||
|
||
---
|
||
|
||
## 设计原则
|
||
|
||
### 原则 1：成果优先，出处次之
|
||
开源贡献卡片应优先展示：
|
||
- 你做了什么
|
||
- 贡献结果是什么
|
||
|
||
而不是先展示：
|
||
- 仓库路径 / 项目名
|
||
|
||
### 原则 2：保持最小改动
|
||
这次不推翻 `open_source` 区块设计，不重做 UI，只做：
|
||
- 数据语义调整建议
|
||
- 一个可选字段扩展
|
||
- 模板微调
|
||
|
||
### 原则 3：兼容历史数据
|
||
旧数据里如果没有新增字段，页面仍必须正常渲染。
|
||
|
||
---
|
||
|
||
## 方案设计
|
||
|
||
## 一、调整开源贡献卡片的主次信息语义
|
||
|
||
### 建议语义
|
||
建议将 `open_source` 条目的字段语义明确为：
|
||
|
||
- `title`
|
||
- 用于展示**贡献成果摘要 / 一句话核心贡献**
|
||
- 这是卡片主标题
|
||
- `role`
|
||
- 用于展示**项目名 / 仓库名 / 贡献归属 / 类型补充**
|
||
- 这是卡片副标题
|
||
|
||
### 推荐示例
|
||
|
||
将原来类似：
|
||
|
||
```json
|
||
{
|
||
"title": "NousResearch/hermes-agent",
|
||
"role": "Open-source bug fix：Xiaomi MiMo reasoning_content 兼容性修复"
|
||
}
|
||
```
|
||
|
||
调整为：
|
||
|
||
```json
|
||
{
|
||
"title": "Xiaomi MiMo reasoning_content 兼容性修复",
|
||
"role": "NousResearch/hermes-agent"
|
||
}
|
||
```
|
||
|
||
### 为什么不建议只在模板里互换 `title` / `role`
|
||
|
||
不建议简单把模板渲染位置对调，而保留原字段语义不变。原因：
|
||
|
||
1. **字段语义会更混乱**
|
||
- `title` 名字天然更适合主标题
|
||
- `role` 更适合作为补充说明
|
||
|
||
2. **后台编辑心智会更差**
|
||
- 管理页如果继续写“项目 / 仓库名称”对应 `title`
|
||
- 但前台实际把它渲染成副标题
|
||
- 会让编辑者产生混乱
|
||
|
||
### 结论
|
||
**保持模板结构不变，但调整后台字段文案与数据填写语义。**
|
||
|
||
也就是：
|
||
- `title` 字段改成“贡献摘要 / 主标题”
|
||
- `role` 字段改成“项目 / 仓库名称（可选）”
|
||
|
||
---
|
||
|
||
## 二、增加按钮文案可编辑字段
|
||
|
||
### 新增字段
|
||
在 `open_source` 每条记录中新增：
|
||
|
||
```json
|
||
"link_label": "查看 PR"
|
||
```
|
||
|
||
### 字段含义
|
||
- `link_label`
|
||
- 对应卡片底部跳转按钮的显示文本
|
||
- 可选字段
|
||
|
||
### 示例完整结构
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
### 当前逻辑
|
||
当前逻辑固定为：
|
||
|
||
```jinja2
|
||
{% if item.link %}
|
||
<a href="{{ item.link }}" target="_blank" rel="noopener" class="project-badge project-badge-link">查看贡献</a>
|
||
{% endif %}
|
||
```
|
||
|
||
### 目标逻辑
|
||
改为：
|
||
|
||
```jinja2
|
||
{% 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()`
|
||
|
||
其中新增默认结构建议：
|
||
|
||
```js
|
||
{
|
||
title: '',
|
||
role: '',
|
||
date: '',
|
||
bullets: [],
|
||
tags: [],
|
||
link: '',
|
||
link_label: '',
|
||
is_draft: true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 服务层兼容要求
|
||
|
||
### 必改文件
|
||
- `home/src/services/content.py`
|
||
|
||
### 要求
|
||
这次**不需要复杂迁移逻辑**，因为：
|
||
- `link_label` 是可选字段
|
||
- 前台模板有默认回退 `查看贡献`
|
||
|
||
因此服务层只需要保证：
|
||
- 旧数据没有 `link_label` 时仍可正常使用
|
||
|
||
### 可选做法
|
||
如果你希望数据结构更整齐，可以在 normalize 时为 `open_source` 每条记录补：
|
||
|
||
```python
|
||
item.setdefault("link_label", "")
|
||
```
|
||
|
||
但这不是强制项。
|
||
|
||
---
|
||
|
||
## 数据调整要求
|
||
|
||
### 对现有开源贡献数据的建议
|
||
当前已发布的数据建议同步调整填写语义：
|
||
|
||
- 把当前用于“仓库名”的内容，放到 `role`
|
||
- 把当前用于“一句话贡献说明”的内容，放到 `title`
|
||
|
||
### 注意
|
||
这不是 schema breaking change，属于内容重排。
|
||
|
||
---
|
||
|
||
## 测试要求
|
||
|
||
### 必改文件
|
||
- `home/tests/test_admin_permissions.py`
|
||
或对应 Home 测试文件
|
||
|
||
### 至少补 3 类测试
|
||
|
||
#### 1. 后台编辑页出现新输入项
|
||
验证：
|
||
- 开源贡献编辑区出现 `link_label` 对应输入项
|
||
- 页面中能找到“按钮文案”相关标签或字段
|
||
|
||
#### 2. 前台使用自定义按钮文案
|
||
当 `open_source` 条目包含：
|
||
|
||
```json
|
||
"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。
|
||
|
||
它不改变“开源贡献”板块的整体架构，只做两件事：
|
||
- 让卡片第一眼先表达“贡献成果”
|
||
- 让按钮文案可后台配置，不再被固定为 `查看贡献`
|
||
|
||
这样可以明显提升首页阅读体验，同时保持改动面最小。 |