Mukoko News

---

相关仓库。 这个仓库是面向读者的 Web 应用。 网关提供公共 API 和 MCP 服务； 数据管道负责数据采集和增强。问题应提交到对应代码所属的仓库。

---

这是什么？

此仓库是 Mukoko News 的 Next.js 15 前端，部署在 Vercel 上。它是由三个仓库组成的平台之一：

仓库	职责
mukoko-dev/mukoko-news（此仓库）	Web 前端 — Next.js 15、Vercel
mukoko-dev/mukoko-news-gateway	公共 API + MCP 服务 — Cloudflare Workers
mukoko-dev/mukoko-ingestion-pipeline	数据管道 — Fly.io + Cloudflare

前端通过 Next.js Server Actions 直接从 MongoDB Atlas 读取新闻数据。

---

功能

• 泛非覆盖 — 关于这一说法的含义，请参阅覆盖范围
• 探索 — 按国家、类别或来源浏览
• NewsBytes — TikTok 风格的垂直滑动信息流，快速浏览头条
• 搜索 — 对所有文章进行全文搜索
• 深色模式 — 遵循系统偏好设置
• 嵌入式小组件 — 只需添加一个 <script> 标签，即可将新闻信息流嵌入任何网站
• MCP 服务 — AI 助手可在 news.mukoko.dev/mcp 查询泛非新闻
• 无障碍 — Radix UI 基础组件、符合 WCAG AAA 的对比度、Schema.org 结构化数据

---

覆盖范围

非洲联盟的全部 54 个成员国都在范围内。当前 上线 的数量是查询结果，而非固定值。

getLiveCoverageAction() 会统计过去 30 天内实际达到发布门槛的国家数量，而 src/lib/constants.ts 中的 coverageFragment(n) / coverageClaim(n) 是唯一获准使用的表述方式——每个页面、元标签和 JSON-LD 简介都会使用其中一种。因此，有国家开始产出数据时就会自动显示；停止产出时也会自动从中移除，无需更改代码，也不需要任何人去编辑文件中的数字。

本 README 刻意不列出当前数量。在无人测试的文档中硬编码数量，正是应用会在九个各自出现偏差的位置声称“16 个非洲国家”的原因。src/lib/__tests__/coverage-claim.test.ts 会为 src/ 强制执行此规则；而这里则通过不写下具体数量来遵守。

贡献

欢迎为前端贡献力量——UI 改进、新功能、错误修复、无障碍功能、测试和文档都可以。贡献无需连接数据库：整套测试都基于模拟数据运行，大多数 UI 工作只需启动开发服务器并连接线上 API 即可完成。

完整指南请参阅 CONTRIBUTING.md，也欢迎来 Discord 打个招呼——这是最快获得问题解答或确认是否已有其他人处理你选定问题的方式。

贡献者快速入门

# Prerequisites: Node.js 20+, pnpm 10+
git clone https://github.com/mukoko-dev/mukoko-news.git
cd mukoko-news
pnpm install

# Run the test suite — no credentials needed
pnpm test

# Start the dev server (reads from the live API by default)
cp .env.example .env.local
pnpm dev

打开 http://localhost:3000。

无需凭据即可参与的工作

• src/components/ 中的所有 React 组件
• src/app/ 中的页面布局和路由
• public/embed/ 中的嵌入式小组件脚本
• 任意单元测试和集成测试——它们都会模拟数据层
• 文档和无障碍功能改进

运行测试

pnpm test             # full suite
pnpm test:watch       # watch mode
pnpm test:coverage    # with coverage report

---

技术栈

层级	技术
框架	Next.js 15、App Router、React 19
样式	Tailwind CSS 4、CSS 变量
组件	Radix UI（无障碍基础组件）
图标	Lucide React
主题	next-themes
身份验证	WorkOS AuthKit
数据	通过 Server Actions 使用 MongoDB Atlas
测试	Vitest、React Testing Library
部署	Vercel

设计系统

Mzizi 是调色板、背景色阶和字体阶梯的上游来源。请准确说明这种绑定的工作方式，因为它没有“从 Mzizi 读取”所暗示的那么紧密：

• src/app/globals.css 保存了本应用使用的值副本。构建时和运行时都不会获取任何内容——没有 Mzizi 软件包依赖，也不会发起网络调用。
• src/app/__tests__/design-tokens.test.ts 会解析该样式表，并将每个值与测试文件本身中的 SNAPSHOT 对象字面量进行断言。没有单独的快照文件。
• 该快照是 mzizi_get_tokens 在某次有记录日期的刷新中返回内容的副本。只有在经过审核的变更中由人工重新查询 MCP 后，才会有意更新——绝不会通过放宽断言来更新。

因此，CI 会检测 globals.css 是否偏离冻结的副本。但它不会检测 Mzizi 本身是否发生变化；这正是有意刷新的用途。

Mzizi 的完整调色板包含 21 个色系——七种矿物色、七种传承色、七种实验色。本应用使用其中的七种矿物色；以下四种最常见：

角色	浅色	深色	矿物
--primary	#4B0082	#B388FF	坦桑石
--secondary	#0047AB	#00B0FF	钴
--success	#004D40	#64FFDA	孔雀石
--surface	#EEEEEC	#131211	(Mzizi 的 surface——背景色阶，并非矿物色)

字体：Noto Serif（展示文本／标题）、Noto Sans（UI／正文）、JetBrains Mono （数据和标签）——通过 next/font 自托管。

---

嵌入式小组件

将 Mukoko News 信息流添加到任何网站：

<script src="https://news.mukoko.com/embed/widget.js"
        data-layout="cards"
        data-feed="latest"
        data-country="ZW">
</script>

布局：cards · compact · hero · ticker · list
信息流：top · featured · latest · location
国家：任意 ISO 3166-1 alpha-2 代码（例如 ZW、KE、ZA、NG）

---

MCP 服务

AI 助手和 Agent 可以通过 Model Context Protocol 查询泛非新闻：

{
  "mcpServers": {
    "mukoko-news": {
      "type": "http",
      "url": "https://news.mukoko.dev/mcp"
    }
  }
}

读取工具可匿名使用。服务本身位于 mukoko-dev/mukoko-news-gateway，并部署在 news.mukoko.dev，而非本应用中——news.mukoko.com 不提供 /mcp 路由。

---

项目结构

src/
├── app/              # Pages (Next.js App Router)
├── components/
│   ├── ui/           # Primitives (Button, Card, Skeleton, ErrorBoundary, …)
│   ├── layout/       # Header, footer, mobile nav
│   └── *.tsx         # Feature components (ArticleCard, HeroCard, ShareModal, …)
├── contexts/         # PreferencesContext, CoverageContext (theme via next-themes)
└── lib/
    ├── actions/      # Server Actions — all database reads go through here
    ├── mongodb/      # MongoDB query helpers
    ├── constants.ts  # Countries, categories, URL utilities
    └── utils.ts      # Formatting + security helpers
public/
└── embed/            # Self-contained widget script

---

安全

我们高度重视安全问题。请发送电子邮件至 [email protected] 报告漏洞——请勿创建公开的 GitHub issue。详情请参阅 SECURITY.md。

---

许可证

此仓库未附带任何 LICENSE 文件，且 package.json 未声明 license 字段。尽管下方措辞如此，目前并未授予任何许可证——在“开源贡献者”的表述准确之前，需要添加 LICENSE 文件。

© Nyuchi Africa (PVT) Ltd.

---

“Ndiri nekuti tiri”——我之所以存在，是因为我们共同存在

由 Nyuchi Web Services 及贡献者构建。