[代码评审] 仓库全面评审：8 项 P0 + 7 项 P1 + 17 项 P2/P3 问题

[sshnuke3]

仓库代码评审报告

对 modelstudioai/modelstudioai.github.io 仓库进行了全面评审，覆盖代码质量、内容一致性、SEO、可访问性、安全性及工程实践等维度，共发现 32 项问题（P0-P3 四级），并总结了 8 项亮点。

总体评级：B（良好，有明显改进空间）

---

P0 严重问题（建议立即修复）

1. 首页布局不渲染 Markdown 内容，index.md 正文被丢弃

• 文件: _layouts/home.html
• home.html 中完全不包含 {{ content }} 标签，导致 index.md 的全部 Markdown 正文（"三步开始"、"生态全景"表格、"社区"链接）被静默丢弃
• 这些内容与 home.html 中硬编码的 HTML 存在重复且不一致
• 建议: 明确首页为纯硬编码布局并精简 index.md，或重构为通过 {{ content }} 渲染页面内容

2. Sitemap 严重不完整且日期全部过期

• 文件: sitemap.xml
• 手动维护的静态文件，仅列出 9 个 URL，遗漏 5 个重要页面：
  • /playbook/（首页第二大板块，8 岗位样板，36KB 内容）
  • /bund-summit-2026/（首页 banner 重点推广的参赛专区）
  • /blog/（博客列表页）
  • /blog/qwencode-bailian-ai-marketing/（完整博客文章）
  • /blog/qwencode-mpcover-skill-guide/（完整博客文章）
• 所有 lastmod 均为 2026-06-10，距今近 2 个月未更新
• 建议: 引入 jekyll-sitemap 插件自动生成

3. 约 22 个 target="_blank" 链接缺少 rel="noopener"

• 文件: _layouts/home.html, _layouts/doc.html
• 约 24 个 target="_blank" 外部链接中，仅 2 个带有 rel="noopener"
• 存在 tabnabbing（标签页劫持）风险
• 涉及行: home.html 第 243/244/267/290/296/335/337/343/345/351/357/388/390/393 行等，doc.html 第 181/182/220/221/242 行等
• 建议: 全站批量添加 rel="noopener noreferrer"

4. Node.js 版本要求跨页面矛盾

• 文件: playbook/index.md 第 104 行 vs guide/index.md/cli/index.md/workshop/index.md
• playbook/index.md 标注 Node.js ≥ 18，但 bailian-cli 实际要求 Node.js ≥ 22.12
• 用户按 playbook 安装 Node.js 18 后安装 bailian-cli 会失败
• 建议: 统一为 Node.js ≥ 22.12

5. HappyHorse 模型版本号跨页面不一致

• cli/index.md 第 84 行: HappyHorse-1.0 系列
• workshop/index.md 第 199 行: HappyHorse-1.0
• guide/index.md 第 298/316/336 行: HappyHorse 1.1
• playbook/index.md 第 250/528 行: HappyHorse 1.1
• 建议: 确认实际版本并全站统一

6. 博客页引用不存在的 Issue 模板

• 文件: blog/index.md 第 36 行
• 链接指向 modelstudioai/blog 仓库的 article-proposal.yml 模板，但该模板可能不存在

7. FAQ 和视频页存在未完成的 TODO 占位内容

• faq/index.md 第 39、56 行: <!-- TODO: 活动后根据实际问题补充 -->
• videos/index.md 第 17、25 行: <!-- 6/11 Workshop 后补充 -->，且至今仍标注"即将上线"

8. Playbook 页面缺少 keywords frontmatter 字段

• 文件: playbook/index.md
• 是所有内容页面中唯一缺少 keywords 字段的页面

---

P1 高优先级问题

1. 移动端菜单焦点管理完全缺失 — 焦点未移入菜单、未返回触发元素、无焦点陷阱，违反 ARIA 抽屉模式
2. --mute: #888888 对比度不达 WCAG AA — 3.5:1 低于 4.5:1 标准，需加深至 #767676
3. 完全缺少 JSON-LD 结构化数据 — 无 WebSite/Organization/BreadcrumbList/BlogPosting/FAQPage schema
4. 914KB 废弃图片 — og-image.png(764KB) 和 hero-bg.jpg(150KB) 全站无引用，应删除
5. 两个布局文件大量 CSS 重复 — 约 40 行导航 CSS + 24 行变量定义重复，无公共提取
6. 移动端菜单 JS 逻辑重复 — home.html 与 doc.html 的菜单逻辑几乎完全相同
7. 复制按钮缺少 aria-label 且 clipboard 无错误处理 — 屏幕阅读器无法识别，非 HTTPS 环境静默失败

---

P2 中优先级问题

1. CSS 变量定义不一致（字体顺序、字重、独有变量、死变量）
2. 全局使用 var 而非 const/let
3. og-image.png 764KB 过大
4. Showcase 单页超过 898 行、83KB
5. 案例提交入口在四个页面中行为不一致
6. 博客文章存在标点错误和用字错误（"发不到"→"发到"、"，——"标点错误）
7. 外滩大会 2026 页面未纳入侧边栏导航
8. 多处页面重复添加"编辑此页"链接
9. .gitignore 偏简陋，缺少常见防御性条目
10. 侧边栏博客文章链接硬编码

---

P3 低优先级问题

1. Google Fonts 渲染阻塞
2. doc.html 缺少页面级 footer
3. !important 滥用（.nav-cta 规则 4 个 !important）
4. title 字段引号使用不统一
5. GitHub URL 大小写不一致
6. FAQ 标题中英文冗余
7. 博客分类标注单复数不一致

---

做得好的方面

• ✅ 响应式设计完善（safe-area、reduced-motion 支持）
• ✅ SEO 基础完善（OG/Twitter Card/canonical/robots.txt）
• ✅ Commit 规范（Conventional Commits）
• ✅ Issue 模板设计合理
• ✅ 代码复制功能完善
• ✅ 内容丰富详实
• ✅ 设计系统统一
• ✅ 表格自动包裹

---

改进建议优先级

1. 引入 jekyll-sitemap 插件
2. 批量补充 rel="noopener noreferrer"
3. 统一版本信息（Node.js ≥ 22.12、HappyHorse 版本）
4. 提取公共 CSS/JS
5. 修复首页内容渲染
6. 清理废弃资源
7. 补全可访问性
8. 添加 JSON-LD 结构化数据
9. 完成 TODO 内容
10. 现代化 JavaScript

[TreeLin]

感谢这份评审，写得非常细。我们把 8 项 P0 逐条对着当前 main 分支核了一遍，结论如下：6 项确认成立，1 项是误报，1 项成立但结论方向要反过来。

确认成立（6 项）

P0-1 首页布局不渲染 Markdown 正文 — 属实。_layouts/home.html 全文没有 {{ content }}（全仓库只有 _layouts/doc.html:239 有），index.md 的 54 行正文（「三步开始」「生态全景」「社区」）确实被静默丢弃，且与 home.html 里硬编码的 HTML 存在重复。

P0-2 Sitemap 不完整且日期过期 — 属实。sitemap.xml 手工维护，只列了 9 个 URL，缺 /playbook/、/bund-summit-2026/、/blog/ 以及 blog/qwencode-bailian-ai-marketing、blog/qwencode-mpcover-skill-guide 两篇文章；所有 lastmod 都是 2026-06-10。另外 _config.yml 里 plugins: [] 是空的，引入 jekyll-sitemap 之前需要先确认 GitHub Pages 的插件白名单。

P0-3 target="_blank" 缺 rel="noopener" — 数据属实：home.html 17 个 / doc.html 6 个 / Markdown 里另有 3 个，共 26 处，其中只有 2 处带 rel="noopener"。但严重级别我们想下调一档：主流浏览器从 2021 年起对 target="_blank" 已默认隐式启用 noopener，tabnabbing 的实际暴露面很小。仍然值得补齐，按 P2 排期。

P0-5 HappyHorse 版本号跨页面不一致 — 属实。cli/index.md:84 和 workshop/index.md:199 写 HappyHorse-1.0，guide/index.md（315/320/328/336 行）和 playbook/index.md（250/528 行）写 HappyHorse 1.1。从 guide 里带定价和体验页链接的描述看，1.1 是较新的口径，我们会核实现网模型版本后全站统一。

P0-7 FAQ / 视频页残留 TODO 占位 — 属实。faq/index.md 第 39、56 行两处 <!-- TODO: 活动后根据实际问题补充 -->，videos/index.md 第 17 行 <!-- 6/11 Workshop 后补充 -->、第 19 和 27 行仍标「即将上线」，距 6/11 已两个月。

P0-8 playbook 缺 keywords frontmatter — 属实。逐页检查了 12 个 index.md，只有 playbook/index.md 没有 keywords 字段。

误报（1 项）

P0-6 博客页引用不存在的 Issue 模板 — 不成立。modelstudioai/blog 仓库存在，.github/ISSUE_TEMPLATE/article-proposal.yml 也存在（2359 字节），blog/index.md:36 的链接可以正常打开。

成立，但结论要反过来（1 项）

P0-4 Node.js 版本要求跨页面矛盾 — 矛盾属实，但「统一为 ≥ 22.12」这个建议会把用户往更严的方向带，反而不对。

我们查了 npm 上 bailian-cli 的 engines 历史：1.0.0-beta.0 时确实是 >=22.12.0，但从 1.10.1 起已经放宽到 >=18.17.0，当前 latest 1.14.2 的 engines 就是 >=18.17.0。也就是说：

• guide/index.md:97、cli/index.md:35、workshop/index.md:107/216 写的「Node.js ≥ 22.12」是旧口径，现在会把本来能装的用户挡在外面；
• playbook/index.md:104 的「Node.js ≥ 18」方向是对的，只是精度不够，准确值是 ≥ 18.17。

所以正确的收敛方向是全站统一为 Node.js ≥ 18.17，而不是 22.12。这条我们会优先改。

顺带核了一条 P1

P1-4 914KB 废弃图片 — 属实且可以直接清理：assets/og-image.png（747KB）和 assets/hero-bg.jpg（147KB）全仓库无任何引用，_config.yml 的 og_image 指向的是另一个文件 assets/og-image.jpg（132KB）。

我们的处理计划

按这个顺序推进：先修 P0-4（版本口径，直接影响新用户能不能装上）、P0-2（sitemap）、P0-1（首页内容渲染）、P0-7（TODO 占位）、P0-8（keywords），再清理废弃资源和补 rel="noopener"。

再次感谢，这份评审的问题定位和行号引用准确率很高，对我们很有帮助。如果你愿意，欢迎直接对其中任意一条提 PR，我们会尽快 review。

👉 提交加入百炼开源开发者计划：http://bailian.console.aliyun.com/opensource