nyuchi-docs

Nyuchi 文档

Nyuchi 工程文档——介绍 Nyuchi 的工作方式，以及如何在 Nyuchi 项目中 使用 Mzizi 工具。

在线访问： docs.nyuchi.com | 产品文档： docs.bundu.org | MCP： docs.nyuchi.com/mcp

---

软件包

由六个软件包组成的 pnpm 工作区。

软件包	路径	功能
site	site/	Astro + Starlight 文档站点本身。以带有 Static Assets 的 Cloudflare Worker 形式发布。
@nyuchi/nyuchi-docs-search	nyuchi-docs-search/	适用于 Starlight 站点的 cmdk 风格搜索模态框 + Ask-AI 标签页。尚未发布到 npm。
shamwari-docs-ai	shamwari-docs-ai/	Cloudflare Worker——Ask-AI 聊天代理（SSE）。
nyuchi-docs-mcp-worker	nyuchi-docs-mcp-worker/	Cloudflare Worker nyuchi-docs-mcp——位于 docs.nyuchi.com/mcp 的文档 MCP 服务。
@nyuchi/nyuchi-docs-mcp	nyuchi-docs-mcp/	连接到该托管端点的 stdio 桥接程序，供无法使用 Streamable HTTP 通信的客户端使用。
@nyuchi/nyuchi-docs-skills	nyuchi-docs-skills/	面向 docs.nyuchi.com 的公开 Agent 技能。仓库的编写技能仅供内部使用，特意不予发布。

配套站点

bundu-labs/bundu-docs 涵盖 Bundu Foundation 面向外部的项目——Mzizi 产品、Ubuntu 理念和 Bundu 品牌系统。这是一个仅限内部查看的仓库， 因此只有组织成员才能访问该链接。它使用 @nyuchi/nyuchi-docs-search，并指向 nyuchi-docs-mcp Worker。

@nyuchi/nyuchi-docs-search 尚未发布到 npm——registry.npmjs.org 返回 {"error":"Not found"}（检查日期：2026-09-12）。在它 发布之前，bundu-docs 无法从注册表安装该软件包。

章节（site/src/content/docs/）

• platform/ — Nyuchi 平台的产品指南。
• api/ — API 文档：/v1 网关、WorkOS 身份验证、由控制台管理的 API 密钥、安全性以及产品命名空间。
• analytics/ — 仪表板、报告和数据源连接。
• kweli/ — Mukoko Kweli 产品指南：验证、跨应用操作指南、开放数据、数据质量和设计系统。
• mukoko-weather/ — Mukoko Weather 用户指南和站点。
• integrations/ — 连接器、webhook、文档 MCP 服务和 Mukoko Events MCP 服务。
• identity/ — WorkOS、accounts.mukoko.com（AuthKit 颁发方）、SSO、JWT。
• console/ — 位于 platform.nyuchi.com 的 Nyuchi Console。
• tools/ — 跨仓库工具目录：Nyuchi 和 Bundu 仓库中的所有技能、CLI 和 MCP 服务。
• mzizi-tools/ — mzizi-mcp、mzizi-cli、mzizi-skills、DNA 双螺旋架构、注册表健康状况和 A2A 设计。
• deployment/ — Cloudflare、Vercel 和 Supabase 部署模式。
• conventions/ — PR 准则、提交准则和仓库命名规则。

开发

pnpm install
pnpm dev            # site only
pnpm -r build       # all packages
pnpm -r test        # all packages

站点开发服务器：http://localhost:4321。内容位于 site/src/content/docs/；侧边栏配置在 site/astro.config.mjs 中。

搜索 + 询问 AI

按 ⌘K / Ctrl+K 可打开搜索弹窗。询问 AI 标签页通过检索提供依据并附带引用的方式，流式输出来自 shamwari-docs-ai（Cloudflare Worker）的回答。要在本地启用，请将 site/.env.example 复制为 site/.env：

cp site/.env.example site/.env
# .env:
# PUBLIC_SHAMWARI_AI_URL=https://shamwari-docs-ai.nyuchi.workers.dev

部署

此仓库中的两个 Worker 均通过 Cloudflare Workers Builds 部署——Cloudflare GitHub App 已连接到 nyuchi/nyuchi-docs，每个 Worker 各配置一个触发器（根目录指向对应的 Worker 包）。不使用 GitHub Actions 部署工作流，也不需要 CLOUDFLARE_API_TOKEN 仓库密钥。

• nyuchi-docs（站点） — 根目录为 site/，使用 Workers Static Assets 作为 Cloudflare Worker 发布。 访问地址为 https://nyuchi-docs.nyuchi.workers.dev，且切换已完成：docs.nyuchi.com 现在由此 Worker 提供服务。两个主机返回相同的 Astro 7.2.9 / Starlight 0.41.10 页面（已于 2026-09-12 检查）；顶级域名后面已不再有 Mintlify-on-Vercel 部署。
• shamwari-docs-ai — 根目录为 shamwari-docs-ai/，是位于 Cloudflare AI Search 前的轻量代理。访问地址为 https://shamwari-docs-ai.nyuchi.workers.dev，仅提供两个路由：GET /health 和 POST /chat。其根路径返回 404，符合预期。 关于按语料配置 AI Search 实例（通过 REST API 管理），请参阅 shamwari-docs-ai/README.md。
• nyuchi-docs-mcp — 根目录为 nyuchi-docs-mcp-worker/，是文档 MCP 服务。访问地址为 https://nyuchi-docs-mcp.nyuchi.workers.dev，并通过 docs.nyuchi.com/mcp* 路由。 需要为其单独配置 Workers Builds 触发器（根目录为 nyuchi-docs-mcp-worker/）。

知名且机器可读的端点

docs.nyuchi.com 在文档目录之外提供以下内容。大多数是 site/public/ 中的静态文件；security.txt 则由站点工作器按请求生成。

路径	提供位置	内容
/robots.txt	site/public/robots.txt	爬取规则和站点地图指针。此处的所有内容都旨在被索引。
/llms.txt	site/public/llms.txt	面向大模型的机器可读站点索引。
/AUTH.md	site/public/AUTH.md	面向 Agent 的 WorkOS 身份验证参考，已从 nyuchi/api-gateway 同步。
/.well-known/mcp/server-card.json	site/public/.well-known/mcp/	位于 /mcp 的 nyuchi-docs-mcp 工作器的 MCP 服务卡片。
/.well-known/security.txt	site/src/worker/security-txt.ts	RFC 9116 披露联系信息——按请求生成，不是静态文件。

security.txt 是动态生成的，因为 RFC 9116 要求必须包含 Expires，且其有效期不得超过一年；因此，随着时间推移，已提交到代码库的文件会在不知不觉中变得不合规。site/wrangler.toml 设置了 run_worker_first = true，因此每个请求都会经过 site/src/worker/gate.ts；它会在网关检查和资源路由器之前处理此路径，并根据请求时间计算 Expires（180 天后）。此方案与 mukoko-dev/mukoko-events（原名 nhimbe）和 mukoko-dev/kweli 相同。

为什么使用 pnpm 工作区

搜索包（nyuchi-docs-search）由 nyuchi-docs（本仓库，通过 workspace:*）和 bundu-docs（独立仓库，通过 npm 注册表）共同使用。将其与文档站点放在同一工作区中，意味着在 pnpm dev 期间，对搜索界面的本地更改会立即生效，而发布该包只需运行一次 pnpm publish。

命令

命令	说明
pnpm dev	在 :4321 启动文档站点
pnpm build	构建站点
pnpm build:all	构建所有工作区包
pnpm test	运行每个包的测试
pnpm lint	运行每个包的代码检查器
pnpm check	检查每个包的类型和内容
pnpm skills:validate	验证随包发布的 Agent 技能
pnpm deploy:worker	部署 shamwari-docs-ai
pnpm deploy:mcp	部署 nyuchi-docs-mcp-worker
pnpm ingest	将语料库重新导入 Cloudflare AI Search

切勿对 .mdx 文件运行 prettier --write。Prettier 3.9.x 会将 {/* … */} 改写为 {/_ … _/}，从而生成无效的 MDX。.md 文件则可以安全处理。

生态系统

• docs.bundu.org — Bundu Foundation 产品文档
• mzizi.dev — Mzizi 设计系统，是 Bundu Foundation 的一个开放架构项目，由 Nyuchi 运营和开发
• api.nyuchi.com — 本文档介绍的 /v1 网关

版本管理

发布遵循组织的版本管理政策 (nyuchi/.github#80。分支决定版本号递增方式，且没有版本标签：

• 合并到 staging（正式运行的测试版）后，staging-version.yml 会自动将其标记为下一个补丁版本。
• 发布到 main 时，版本号为高于最高标签的下一个次要版本。发布版本的 PR 会在 nyuchi-docs-mcp/package.json 中设置 version。CI 会拒绝其他版本号，并指出正确的版本号。
• 主要版本只会手动发布：所有者会在 Actions 选项卡中使用 bump: major 运行发布工作流。
• 每个版本号段的范围为 0–999。补丁版本号达到 999 后会进位到下一个次要版本；次要版本号达到 999 后会停止，并提示手动发布主要版本。

2026-10-04 之前发布的版本不会重新编号。

许可证

此仓库为公开仓库，但不包含 LICENSE 文件，因此未授予对整个仓库的许可：保留所有权利。© Nyuchi Africa (PVT) Ltd. @nyuchi/nyuchi-docs-search 包在其自身的 package.json 中声明了 MIT 许可证；如果这是该包的预期许可证，仓库需要提供 LICENSE 文件作为依据。