Sumi Docs

English | 简体中文

Sumi Docs публикует единый выверенный корпус документации для двух потребителей:

• люди просматривают сайт на Astro и Starlight;

• агенты запрашивают тот же корпус через read-only MCP-сервер.

Выверенное корневое дерево docs/ и каталог контента являются семантическим источником истины. Веб-сайт и MCP-сервер — это независимо адресуемые проекции; хост агента является MCP-клиентом.

Исходный репозиторий и сайт документации являются публичными и находятся в активной разработке. Ни npm-пакет, ни тегированный GitHub Release, ни поддерживаемый бинарный файл не публиковались.

Предварительные требования

• Node.js 25.5.0 или новее

• pnpm 10.26.0 через Corepack или версия, объявленная в packageManager

• доверенный checkout при загрузке конфигурации хоста агента, предоставляемой репозиторием

Related MCP server: mcp-docs

Первый запуск

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

Doctor по умолчанию сообщает пути относительно проекта или плейсхолдеры внешних источников. Добавляйте --show-paths только для локальной диагностики; не прикрепляйте этот вывод к публичным issue или артефактам сборки.

Проверенный в репозитории sumi-docs.config.json выбирает корневой docs/ и пример документа OpenAPI. Запустите человеческий сайт с помощью:

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

Откройте http://127.0.0.1:4321. Адаптеры проектов Codex, Claude Code и VS Code описаны в Интеграция с хостом агента. Они предоставляют четыре MCP-инструмента без необходимости в опциональном Skill сопровождающего.

Чтобы предоставить тот же корпус через loopback-конечную точку 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

Сервис предоставляет MCP на http://localhost:3000/mcp, проверку живости на /healthz, и готовность корпуса на /readyz. Docker необязателен для разработки исходного кода; публичное развёртывание по-прежнему требует HTTPS-терминации и явной политики Host.

Репозиторий также предоставляет три опциональных проектных workflow в .agents/skills/: $sumi-docs-use для настройки и эксплуатации, $sumi-docs-pr для подготовки предложений и pull-request, и $sumi-docs-audit для read-only аудитов репозитория и релизов, привязанных к доказательствам. Они направляют работу, но не заменяют 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 требует выверенных переменных конечной точки и SSH-материалов в защищённом окружении production-mcp. Контейнер принимает документированные переменные развёртывания SUMI_DOCS_*; сгенерированный вывод, локальное состояние, журналы, кеши и файлы .env остаются игнорируемыми.

Инструкции для конкретных пакетов остаются в каждом рабочем пространстве. Активные архитектурные решения находятся в каталоге docs/decisions/ соответствующего рабочего пространства; корневое руководство представляет их пользовательские последствия без дублирования записей решений.

Видимость исходного кода и сайта не публикует тег, пакет или бинарный файл. Эти артефакты остаются подчинёнными документированным шлюзам релиза.