Sumi Docs

英文 | 简体中文

Sumi Docs 为两类使用者发布一套经过审阅的文档语料库：

• 用户浏览基于 Astro 和 Starlight 构建的网站；

• 代理通过只读 MCP 服务器查询同一语料库。

经过审阅的根级 docs/ 目录树和内容目录是语义事实来源。网站和 MCP 服务器是各自独立可寻址的投影；代理主机是 MCP 客户端。

源代码仓库和文档站点是公开的，并且正在积极开发中。尚未发布任何 npm 包、带标签的 GitHub Release 或受支持的二进制文件。

前提条件

• Node.js 25.5.0 或更高版本

• 通过 Corepack 或 packageManager 中声明的版本使用 pnpm 10.26.0

• 加载仓库提供的代理主机配置时，使用受信任的检出

Related MCP server: mcp-docs

首次运行

pnpm install --frozen-lockfile
pnpm run build
node packages/mcp/dist/index.js doctor --json

Doctor 默认报告项目相对路径或外部来源占位符。仅在本地诊断时添加 --show-paths；不要将该输出附加到公开问题或构建产物中。

已检入的 sumi-docs.config.json 选择根级 docs/ 和示例 OpenAPI 文档。使用以下命令启动人类用户站点：

pnpm --filter @sumi-os/docs-web dev

打开 http://127.0.0.1:4321。Codex、Claude Code 和 VS Code 项目适配器在 Agent 主机集成中进行了描述。它们公开四个 MCP 工具，无需可选的维护者 Skill。

要在环回 Streamable HTTP 端点上公开同一语料库：

node packages/mcp/dist/index.js serve --transport streamable-http

将兼容的 MCP 客户端连接到 http://127.0.0.1:3000/mcp。静态网站和 _mcp 语料库投影本身并不运行该端点。

要使用经过审阅的同一根级语料库构建加固的本地容器：

docker compose up --build

该服务在 http://localhost:3000/mcp 公开 MCP，在 /healthz 公开存活检查，在 /readyz 公开语料库就绪检查。Docker 对于源代码开发是可选的；公开部署仍然需要 HTTPS 终止和显式 Host 策略。

仓库还在 .agents/skills/ 下提供了三个可选的项目工作流：$sumi-docs-use 用于设置和操作，$sumi-docs-pr 用于提案和拉取请求准备，$sumi-docs-audit 用于只读、有证据约束的仓库和发布审计。它们引导工作，但不会取代 MCP 或发布远程更改。

工作区

apps/web/                   Astro/Starlight site and corpus publisher
packages/mcp/               stdio and Streamable HTTP MCP server and CLI
packages/corpus-contract/   manifest schemas and conformance fixtures
docs/                       product handbook and default corpus
.agents/skills/             optional project usage and contribution workflows

本地操作和默认的仅 Pages 发布不需要运行时机密。SITE_URL 仅对发布站点候选是必需的。启用可选的生产 Streamable HTTP 服务需要在受保护的 production-mcp 环境中提供经过审阅的端点变量和 SSH 材料。容器接受文档化的 SUMI_DOCS_* 部署变量；生成的输出、本地状态、日志、缓存和 .env 文件保持被忽略。

包特定的说明保留在各个工作区中。活跃的架构决策位于所属工作区的 docs/decisions/ 目录中；根级手册介绍它们面向用户的影响，而不重复决策记录。

源代码和站点的可见性并不意味着会发布标签、包或二进制文件。这些产物仍然受文档化的发布门禁约束。