Работа сайта документации

Архитектура сайта

packages/web — это серверное приложение Astro с адаптером Cloudflare. Статьи документации объявляют предварительную отрисовку и становятся статическими ресурсами HTML. Маршруты сервера обрабатывают экспорт Markdown, запросы помощника по документации, просмотр артефактов/необработанный контент и резервную версию Studio Studio. Это развертывание отделено от дополнительного модуля CAD/CAM.

На сайте документации описывается поведение приложения и предоставляется справочный контент. Он не наследует проекты посетителя, токен носителя локального приложения, учетные данные поставщика или сопряженное подключение к рабочему столу. Его помощник использует отрывки из документации, а не молча управляет рабочим пространством CAD/CAM.

Локальная студия — это дополнительный процесс Bun, поскольку она использует bun:sqlite. Vite передает запросы API разработки на порт обратной связи 4396. Развернутый Cloudflare Worker не может открыть эту локальную базу данных; API производственной студии намеренно объясняет это с помощью HTTP 503.

Локальные команды

bun run --filter @cadcamfun/web start
bun run --filter @cadcamfun/web dev
bun run --filter @cadcamfun/web studio
bun test packages/web/test
bun run --filter @cadcamfun/web typecheck
bun run --filter @cadcamfun/web build

Используйте только Astro для редактирования статей, когда Studio не нужна. Производственная компиляция проверяет создание шаблона и выходные данные маршрута, но не вызывает реальную серверную часть модели, не публикует артефакты и не проверяет развернутую учетную запись Cloudflare.

Генерация контента и API

Статьи живут в src/pages/docs и поделиться DocsLayout.astro. Боковая панель в src/data/docsSidebar.ts — это инвентарь маршрутов документации. docsIndex.ts добавляет сводки по каждому маршруту и ключевые слова для поиска. Публичная страница должна иметь как навигационную запись, так и точную копию для поиска; статья, на которую нет ссылки, не становится доступной для обнаружения только потому, что ее файл существует.

Справочник по API объединяет сгенерированный снимок контракта с тщательно подобранной группой ресурсов в src/data/apiGroups.ts. src/lib/apiReference.ts выбирает каждую операцию, разрешает именованные схемы и предоставляет шаблоны ресурсов. Снимок создается из составленного приложения HttpApi с использованием установленной реализации Effect.

bun run generate:api-reference
bun run check:api-reference
bun run check:docs-index
bun test test

Регенерация записывает текущий контракт схемы; он не записывает руководство по домену и не доказывает, что удаленное приложение использует ту же версию. На рукописных страницах описываются бизнес-проверка, побочные эффекты, разрешения, восстановление и ограничения реализации. Держите эти объяснения привязанными к реальным обработчикам и службам.

Заметки для чтения источников могут быть подготовлены в разделе packages/web/.tmp/content. Это временные редакционные материалы, исключенные из публикации. Переместите готовые пояснения на страницы статей и обновите навигацию/поиск; не используйте временную заметку как единственную документацию для операции.

Экспорт уценки

GET /llm перечисляет известные страницы документации как ссылки Markdown. С path, он извлекает соответствующую визуализированную статью и преобразует ее в Markdown с поддержкой GitHub. Добавление format=prompt оборачивает это содержимое в командную строку, включающую его канонический источник.

curl "$DOCS_ORIGIN/llm"
curl "$DOCS_ORIGIN/llm?path=/docs/cam"
curl "$DOCS_ORIGIN/llm?path=/docs/api/projects&format=prompt"

Конвейер читает только статью, отмеченную data-llm-document. Он удаляет исключенный контент, сценарии, стили, оформление SVG и кнопки, поэтому элементы управления навигацией и копированием не становятся контекстом ответа. Он преобразует блоки кода, заголовки, таблицы и ссылки, а не поддерживает второй рукописный корпус Markdown.

Допускаются только известные пути к документации. Неизвестные пути возвращают 404. При ошибке загрузки страницы возвращается 502; другая ошибка преобразования возвращает 500. Ответом является Markdown с разрешающим чтением CORS и общедоступной пятиминутной политикой кэширования с устаревшей повторной проверкой. Эти экспортированные общедоступные статьи не содержат учетные данные локального проекта.

В Cloudflare помощник предпочитает привязку ASSETS для предварительно обработанных страниц. Это сохраняет чтение в развертывании Worker. Разработка может вернуться к загрузке в реальном времени, если существующая сборка ресурса не содержит страницы. Таким образом, устаревшее локальное дерево дистрибутивов и текущее исходное дерево могут быть разными входными данными при редактировании.

Помощник по документации

POST /api/docs-assistant принимает сообщения диалога, необязательный путь к документации и необязательный идентификатор сеанса серверной части. Он сохраняет только сообщения пользователя/помощника, обрезает каждое сообщение до символов 1,200, сохраняет самые последние действительные сообщения 12 и требует вопроса пользователя.

При извлечении сначала текущий вопрос и предыдущие вопросы пользователя сравниваются с заголовками, маршрутами, ключевыми словами и сводками. Текущая известная страница сохраняется. Если доступна привязка Workers AI, дополнительный планировщик вызовов инструментов может выбирать соответствующие маршруты документирования; неверный выбор или сбой планировщика возвращаются к лексическому поиску.

Загружается до трех страниц. Каждый из них сжимается до 5,000-символьного бюджета за счет сохранения вводного и соответствующего разделов. Поэтому длинная страница ресурса API не предоставляется модели автоматически полностью. Свяжите пользователя с соответствующей операцией, если отрывок не содержит достаточно подробностей.

Загруженный Markdown кэшируется отдельно в течение 30 минут, если доступен рабочий кэш. Редактирование исходного кода может потребовать обновления кэша в уже запущенном развертывании. Если ни одна выбранная страница не может быть загружена, маршрут возвращает 502. Если привязки Workers AI или полной конфигурации серверной части nikcli не существует, перед генерацией возвращается 503.

Один запрос помощника может содержать не более 12 сообщений беседы, а размер вопроса ограничен 1,200 символами (MAX_MESSAGES и MAX_QUESTION_CHARS в src/lib/docsAssistant.ts).

Модели и ограничения ставок

Путь nikcli создает или повторно использует удаленный сеанс, подписывается на его поток перед отправкой сообщения и применяет тайм-аут включения в 90 секунды. Это поддержка документации по настроенному бэкенду; его токен отделен от моста приложения CAD/CAM или учетных данных поставщика.

Ограничителю скорости требуется дополнительная привязка KV и заголовок IP клиента. Его последовательность чтения/инкремента/записи является максимально возможной, а не атомарной квотой безопасности, и сбои KV допускаются. Без привязки не будет принудительного ограничения количества IP-адресов. Не представляйте его как гарантированное распределение и не полагайтесь на заявления о ценообразовании, основанные на исторических моделях.

Конфигурация локального адаптера отключает удаленные привязки. Модель не имеет локальной реализации на этом сайте. Обычный предварительный просмотр локальной статьи может работать, пока запросы помощника возвращают 503. Настройте доступную серверную часть или проверьте поведение модели в предполагаемой среде развертывания.

Созданные артефакты направляющих

Запрос руководства, контрольного списка, справочника или аналогичной многоразовой страницы может привести к появлению черновика. С ARTIFACTS R2, помощник нормализует его в документ HTML и записывает содержимое и метаданные. Нормализованный пустой документ или документ размером более 256 КиБ не публикуется.

Возвращенная ссылка содержит ?key= возможность чтения. Любой, у кого есть эта полная ссылка, может прочитать артефакт. Простого идентификатора недостаточно; для этих анонимных руководств нет входа в систему с учетной записью владельца. Рассматривайте ключ как общие учетные данные и избегайте помещения частных данных проекта в общедоступное руководство.

Средство просмотра использует частную некэшированную оболочку и изолированную программную среду iframe, позволяющую использовать сценарии и всплывающие окна без разрешения того же источника. Маршрут необработанного HTML применяет политику содержимого, которая разрешает встроенные сценарии/стили и встроенные данные/изображения больших двоичных объектов, но блокирует выборку из внешней сети и загрузку внешних шрифтов/стилей/скриптов. Создаваемые руководства должны быть автономными; их макет не может зависеть от текущего DOM или локального хранилища сайта.

Текущий помощник публикации записывает версию 1 и новую случайную возможность. Необработанный маршрут может выбрать действительную сохраненную версию с помощью v; недействительная версия или версия, выходящая за пределы диапазона, возвращается к последней сохраненной версии. Эта поддержка поиска не устанавливает общедоступный API редактирования/управления версиями.

ARTIFACT_PUBLIC_ORIGIN может выбрать канонический источник общей ссылки для нелокальных развертываний. Отсутствующее хранилище возвращает 503 при доступе к артефакту. При отсутствующем содержимом возвращается 404, а при отклонении возможности чтения возвращается 401. Храните сгенерированные руководства и ресурсы общедоступной документации отдельно.

Местная студия

Студия выбирает CADCAMFUN_DB, затем DATABASE_URL после удаления исходного префикса файла, затем файл репозитория data/cadcamfun.db. Он открывает только существующий файл. Этот выбор отличается от значения по умолчанию CLI пакета DB, относящегося к процессу, и каталога данных приложения собственного рабочего стола.

Вход проверяет сохраненный пароль существующего пользователя с помощью средства проверки пароля Bun. Он записывает семидневный сеанс в таблицу сеансов приложения и устанавливает файл cookie SameSite=Lax только для HTTP для локальной студии. Этот локальный сервер не реализует регистрацию пользователей или загрузку начального пароля. Собственный локальный профиль без пароля не получает пароль Studio автоматически.

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

Резервный вариант производства под /studio/api/* это HTTP 503. Развертывание общедоступных документов не загружает содержимое SQLite и не превращает этот локальный инструмент в службу размещенной базы данных.

Развертывание

wrangler.toml объявляет запись Worker, статический каталог ресурсов, пользовательские домены в cadcam.fun, Workers AI, пространства имен KV с ограничением скорости сеанса и помощника и корзину артефактов R2. Wrangler выделяет выделенные ресурсы и привязывает их к развертыванию. Настройте секреты через целевую среду Cloudflare. Имя привязки в интерфейсе TypeScript не является доказательством существования ресурса в учетной записи.

Скрипт развертывания собирает Astro, пишет dist/.assetsignore поэтому запись Worker исключается из статических ресурсов и вызывает развертывание Wrangler. Развертывание — это операция публикации; обычная проверка документации должна использовать сборку и локальные проверки без ее запуска.

Перед публикацией проверьте актуальность статических маршрутов и моментальных снимков API, подтвердите предполагаемые привязки, проверьте поведение помощника при сбое без его серверной части и проверьте доступ к возможностям артефакта, если хранилище включено. После публикации проверьте полученное развертывание и настроенную серверную часть, а не рассматривайте локальную сборку как свидетельство работающего сервиса.

Оперативная диагностика

Источники реализации: astro.config.mjs, wrangler.toml, script/dev.ts, script/deploy.ts, script/studio-server.ts, src/lib/docsMarkdown.ts, docsRetrieval.ts, nikcliDocsSession.ts, docsArtifact.tsи обработчики маршрутов под src/pages.

Скрипты пакета документации

Написание страницы

1. Создавать src/pages/docs/<slug>.astro с использованием DocsLayout с title, subtitle, description и toc массив, чей hrefs соответствует идентификаторам разделов.
2. Запишите каждый раздел как <section id="…" class="doc-section"> с одним <h2>.
3. Использовать DocCode (language, title) для кода, DocCallout (type информация, предупреждение или примечание) для предупреждений, DocCard для сеток ссылок, DocRelated в конце и DocViewer3D для превью 3D.
4. Экранируйте буквенные скобки в тексте как { и }; поместите код внутри выражения, например {String.raw`…`}.
5. Добавьте страницу в данные боковой панели и запустите bun run typecheck, который также перестраивает и проверяет индекс поиска.

---
export const prerender = true
import DocsLayout from "../../layouts/DocsLayout.astro"
import DocCode from "../../components/docs/DocCode.astro"
const toc = [{ title: "Overview", href: "#overview" }]
---
<DocsLayout title="Example" subtitle="One line." description="For search engines." toc={toc}>
  <section id="overview" class="doc-section">
    <h2>Overview</h2>
    <p>Text with an escaped brace: &#123;</p>
    <DocCode language="bash" title="Run">{`bun run typecheck`}</DocCode>
  </section>
</DocsLayout>

3Предварительный просмотр D

Компонент использует Three.js с Z вверх, монтируется только при прокрутке и показывает резервный текст без WebGL. Подавайте ему реальные выходные данные, такие как перемещения ядра, а не нарисованные от руки координаты.

Через 3Д