Elaina/ephron-ren-prd

Fork 0

Files

Ubuntu 540ae3d261 docs: add home open source contributions PRD

2026-05-18 10:57:23 +08:00

12 KiB

Raw Blame History

Home 页新增“开源贡献”板块与后台可编辑支持 PRD

背景

用户希望在 https://www.ephron.ren/ 首页新增一个独立板块：开源贡献，并且该板块内容必须能够在 Home 后台中编辑、保存草稿、发布，不接受只改前台模板的静态实现。

本 PRD 基于 origin/main 最新源码分析，覆盖 Home 的：

公共渲染模板
Admin 编辑模板
content schema
草稿 / 发布链路
兼容策略
测试要求

现状分析

1. 首页当前内容结构

当前 Home 页公共模板位于：

home/templates/index.html

当前页面主区块顺序大致为：

Hero
工作经历
项目经验
技术栈
页脚
联系方式弹窗

其中内容类区块已经形成清晰模式：

experience：时间线列表
projects：时间线列表 + tags + 可选 badge
skills：分类列表

2. Home 内容 schema 当前主结构

当前 home/src/services/content.py 中 HomeContent 及默认内容模板包含：

hero
experience
projects
skills
contact
footer

当前没有 open_source 或同义字段。

3. 后台编辑页当前主结构

后台模板位于：

home/templates/admin/index.html

当前后台已提供以下可编辑区块：

Hero
工作经历
项目经验
技术栈
联系方式
页脚

其 JS 通过 initialContent + 各类 renderXxx()、addXxx()、updateXxx()、removeXxx() 管理动态列表，再通过 collectFormData() 汇总为完整 content_json。

4. Draft / Publish 机制已存在

Home Admin 已支持：

保存草稿
发布内容
丢弃草稿

问题定义

如果只是简单在前台首页插入一个“开源贡献”区块，会有以下问题：

后台无法维护
- 用户明确要求后台可修改
- 只改模板会让内容写死在代码里
不进入草稿 / 发布流程
- 无法像其他首页内容一样先保存草稿再发布
与 Home 当前内容架构不一致
- Home 当前是 schema 驱动 + admin 驱动
- 新区块也应遵循同样模式
历史内容兼容问题
- 线上已有 content_json 一定不包含新字段
- 如果不做 normalize，可能出现模板取值缺失或后台初始值异常

目标

产品目标

在首页新增一个独立的 开源贡献 板块，用于展示用户的开源贡献记录。

后台目标

管理员可在 Home 后台中：

新增开源贡献条目
编辑开源贡献条目
删除开源贡献条目
标记草稿 / 已发布条目（如果沿用当前列表编辑模式）
保存草稿
发布

技术目标

将“开源贡献”纳入 Home 的统一内容 schema，而不是写死在模板中。

核心设计判断

为什么建议新增独立 `open_source` 区块，而不是复用 `projects`

虽然“开源贡献”看起来和“项目经验”都属于列表，但我不建议复用 projects，原因如下：

语义不同
- 项目经验是个人项目 / 研究 / 比赛 /工程经历
- 开源贡献是对外部开源生态的参与记录
展示重心不同
- 项目经验偏“我做了什么项目”
- 开源贡献偏“我向哪些项目贡献了什么”
后台认知更清晰
- 管理员能清楚区分两类信息
- 避免未来在同一列表中混入不同语义的数据
后续扩展更容易
- 以后可独立增加 repo 链接、PR 链接、贡献类型、状态标签等

结论

本次建议新增独立字段：open_source

数据结构设计

建议新增主字段

在 Home content 顶层新增：

"open_source": []

单条条目建议结构

建议最小结构如下：

{
  "title": "Hermes Agent",
  "role": "提交 PR 修复 MiMo reasoning_content",
  "date": "2026.05",
  "description": [
    "向上游提交并推动合并 MiMo reasoning_content 修复",
    "补充兼容性验证与使用说明"
  ],
  "tags": ["Python", "Hermes", "Open Source"],
  "link": "https://github.com/NousResearch/hermes-agent/pull/25358",
  "is_draft": false
}

字段说明

title
- 开源项目名 / 仓库名 / 贡献对象名
role
- 一句话说明贡献类型或身份
- 例如：修复 PR、功能贡献、文档维护、Issue triage
date
- 贡献时间，沿用当前 Home 的字符串时间格式
description
- 多条描述，后台可按“每行一条”编辑
tags
- 技术标签或贡献类型标签
link
- 对外链接，建议指向 PR / repo / profile / issue
is_draft
- 若沿用现有列表项 draft 切换机制，则保留该字段

为什么建议有 `link`

因为“开源贡献”天然需要外部证明入口：

GitHub PR
仓库主页
个人 Profile

如果没有链接，板块很容易退化成纯文字陈列。

服务层改造

必改文件

home/src/services/content.py

要求

1. 扩展默认 schema

在 _get_empty_content() 中新增：

"open_source": []

2. 扩展 normalize

在 _normalize_content() 中补：

content.setdefault("open_source", [])

3. 兼容性原则

旧内容没有 open_source 时：

首页应正常打开
后台应正常打开
不要求先清洗数据库历史内容

前台首页改造

必改文件

home/templates/index.html

板块位置建议

建议插入在：

项目经验之后
技术栈之前

推荐顺序：

工作经历
项目经验
开源贡献
技术栈

原因

信息层级更合理
- 工作 / 项目 / 开源属于“经历与实践”一组
- 技术栈更适合作为总结性能力列表放在后面
开源贡献不应放到页脚附近
- 会显得像附属信息，而不是正式内容资产

渲染方式建议

建议复用当前 timeline-item 风格，保持页面一致性。

示意结构：

{% if content.open_source %}
<section class="section">
    <h2 class="section-title">开源贡献</h2>
    {% for item in content.open_source if not item.get('is_draft', False) %}
    <div class="timeline-item">
        <div class="timeline-header">
            <div>
                <h3 class="timeline-title">{{ item.title }}</h3>
                <p class="timeline-company">{{ item.role }}</p>
            </div>
            <span class="timeline-date">{{ item.date }}</span>
        </div>
        <div class="timeline-content">
            <ul>
                {% for bullet in item.bullets %}
                <li>{{ bullet }}</li>
                {% endfor %}
            </ul>
            {% if item.tags %}
            <div class="project-tags">
                {% for tag in item.tags %}
                <span class="project-tag">{{ tag }}</span>
                {% endfor %}
            </div>
            {% endif %}
            {% if item.link %}
            <a href="{{ item.link }}" target="_blank" rel="noopener" class="project-badge project-badge-link">查看贡献</a>
            {% endif %}
        </div>
    </div>
    {% endfor %}
</section>
{% endif %}

说明

样式可直接复用 timeline-item、project-tags、project-badge
不建议本次重新发明一套视觉组件
重点是内容建模与后台可维护性，而不是视觉重构

后台管理页改造

必改文件

home/templates/admin/index.html

建议新增一个完整 Section

在“项目经验”和“技术栈”之间新增：

板块标题：开源贡献
列表容器：<div id="openSourceList"></div>
添加按钮：+ 添加开源贡献

建议沿用现有动态列表编辑模式

即仿照：

renderProjects()
addProject()
removeProject()
updateProject()
toggleProjectDraft()

新增一组：

renderOpenSource()
addOpenSource()
removeOpenSource(index)
updateOpenSource(index, field, value)
updateOpenSourceBullets(index, value)
updateOpenSourceTags(index, value)
toggleOpenSourceDraft(index)（若保留每项草稿状态）

单条后台表单建议字段

项目 / 仓库名称（title）
贡献角色 / 一句话说明（role）
时间（date）
描述（每行一条）
标签（逗号分隔）
外部链接（link）

collectFormData 必须同步补充

open_source: initialContent.open_source,

否则后台加了 UI 也不会进入 content_json。

命名一致性要求

当前代码中存在一个值得注意的事实：

前台项目区渲染使用的是 project.bullets
但示例数据文件中很多项目仍然是 description

这说明 Home 当前已有一定字段漂移历史。

本次 PRD 的要求

对于“开源贡献”，字段命名必须从一开始就统一，不要再制造第二套字段名。

建议直接统一使用：

bullets 作为前台 / 后台 / 存储字段名

而不是：

后台叫 description
前台叫 bullets
示例数据再写成第三种

结论

开源贡献条目统一使用 bullets，不要引入 description。

测试要求

必改文件

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

建议至少补 4 类测试

1. Admin 渲染测试

后台页面应出现：

openSourceList
添加开源贡献
对应字段输入结构

2. 首页渲染测试

当 open_source 有已发布数据时：

首页应显示 开源贡献 标题
应显示条目标题 / 链接

3. 空列表隐藏测试

当 open_source 为空时：

首页不应显示空板块

4. 旧 schema 兼容测试

当历史内容没有 open_source 字段时：

首页正常打开
后台正常打开

可选补充

如果你们继续沿用每项 is_draft：

测试首页不会渲染 open_source 中 is_draft=true 的条目

验收标准

前台

首页新增 开源贡献 板块
板块位于“项目经验”之后、“技术栈”之前
存在数据时正常渲染条目
条目链接可打开外部页面
无数据时不显示空板块

后台

管理页新增“开源贡献”编辑区块
支持新增 / 编辑 / 删除条目
保存草稿后刷新后台可回显
发布后首页可见
丢弃草稿后未发布修改可撤销

兼容性

历史 content_json 没有 open_source 字段时不报错
不要求先手工迁移历史数据库内容

非目标

本次 PRD 不包含：

从 GitHub API 自动拉取开源贡献
统计贡献数量、Star、PR 数等自动指标
把开源贡献和项目经验合并
新增单独的 Home Service API
重做首页视觉风格

实施顺序建议

先改 home/src/services/content.py
- schema 默认值
- normalize 兼容
再改 home/templates/admin/index.html
- 新区块 UI
- 新增 JS 列表管理逻辑
- 更新 collectFormData()
最后改 home/templates/index.html
- 新区块渲染
补测试

这样可以避免先改模板后 schema 未补齐导致的半更新问题。

结论

“开源贡献”不是单纯新增一段 HTML，而是一个完整的 Home 内容模型扩展。

要满足“前台显示 + 后台可改 + 草稿发布 + 历史兼容”，最小闭环必须同时覆盖：

schema
normalize
admin 区块
前台渲染
测试

建议采用独立 open_source 列表区块，而不是复用 projects。这样语义更清晰，也更利于后续继续扩展你的开源履历展示。

12 KiB Raw Blame History Unescape Escape

Home 页新增“开源贡献”板块与后台可编辑支持 PRD

背景

现状分析

1. 首页当前内容结构

2. Home 内容 schema 当前主结构

3. 后台编辑页当前主结构

4. Draft / Publish 机制已存在

问题定义

目标

产品目标

后台目标

技术目标

核心设计判断

为什么建议新增独立 open_source 区块，而不是复用 projects

结论

数据结构设计

建议新增主字段

单条条目建议结构

字段说明

为什么建议有 link

服务层改造

必改文件

要求

1. 扩展默认 schema

2. 扩展 normalize

3. 兼容性原则

前台首页改造

必改文件

板块位置建议

原因

渲染方式建议

说明

后台管理页改造

必改文件

建议新增一个完整 Section

建议沿用现有动态列表编辑模式

单条后台表单建议字段

collectFormData 必须同步补充

命名一致性要求

本次 PRD 的要求

结论

测试要求

必改文件

建议至少补 4 类测试

1. Admin 渲染测试

2. 首页渲染测试

3. 空列表隐藏测试

4. 旧 schema 兼容测试

可选补充

验收标准

前台

后台

兼容性

非目标

实施顺序建议

结论

12 KiB

Raw Blame History

为什么建议新增独立 `open_source` 区块，而不是复用 `projects`

为什么建议有 `link`