Operaciones del sitio de documentación.

Arquitectura del sitio

packages/web es una aplicación de salida del servidor Astro con el adaptador Cloudflare. Los artículos de documentación declaran prerenderizado y se convierten en activos HTML estáticos. Las rutas del servidor manejan la exportación de Markdown, las solicitudes de asistente de documentación, la visualización de artefactos/contenido sin procesar y el respaldo de Production Studio. Esta implementación es independiente del sidecar CAD/CAM.

El sitio de documentación describe el comportamiento de la aplicación y proporciona contenido de referencia generado. No hereda los proyectos de un visitante, el token de portador de la aplicación local, las credenciales del proveedor ni la conexión de escritorio emparejada. Su asistente utiliza extractos de documentación en lugar de operar silenciosamente el espacio de trabajo CAD/CAM.

El Studio local es un proceso Bun adicional porque utiliza bun:sqlite. Vite envía sus solicitudes de API de desarrollo al puerto de bucle invertido 4396. Un Cloudflare Worker implementado no puede abrir esa base de datos local; la API de Studio de producción explica esto deliberadamente con HTTP 503.

Comandos locales

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

Utilice Astro solo para editar artículos cuando Studio no sea necesario. La compilación de producción valida la generación de plantillas y la salida de ruta, pero no llama a un backend de modelo real, no publica artefactos ni verifica una cuenta de Cloudflare implementada.

Generación de contenidos y API

Los artículos viven en src/pages/docs y compartir DocsLayout.astro. La barra lateral en src/data/docsSidebar.ts es el inventario de ruta de documentación. docsIndex.ts agrega resúmenes por ruta y palabras clave para su recuperación. Una página pública debe tener una entrada de navegación y una copia de recuperación precisa; un artículo desvinculado no se vuelve visible simplemente porque su archivo existe.

La referencia de API combina una instantánea del contrato generada con una agrupación de recursos seleccionada en src/data/apiGroups.ts. src/lib/apiReference.ts selecciona cada operación, resuelve esquemas con nombre y proporciona las plantillas de recursos. La instantánea se genera a partir de la aplicación compuesta HttpApi utilizando su implementación Effect instalada.

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

La regeneración escribe el contrato de esquema actual; no escribe guías de dominio ni prueba que una aplicación remota tenga la misma versión. Las páginas escritas a mano explican la validación empresarial, los efectos secundarios, los permisos, la recuperación y los límites de implementación. Mantenga esas explicaciones vinculadas a los manejadores y servicios reales.

Las notas de lectura de fuentes se pueden preparar en packages/web/.tmp/content. Son material editorial temporal, excluido de publicación. Mueva las explicaciones terminadas a las páginas del artículo y actualice la navegación/recuperación; No utilice una nota temporal como única documentación para una operación.

Exportación de rebajas

GET /llm enumera las páginas de documentación conocidas como enlaces de Markdown. Con path, recupera el artículo renderizado correspondiente y lo convierte a Markdown con sabor a GitHub. Añadiendo format=prompt envuelve ese contenido en un mensaje de instrucción que incluye su fuente canónica.

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

El canal solo lee el artículo marcado data-llm-document. Elimina contenido, scripts, estilos, decoración SVG y botones excluidos para que los controles de navegación y copia no se conviertan en contexto de respuesta. Convierte bloques de código, encabezados, tablas y enlaces en lugar de mantener un segundo corpus de Markdown escrito a mano.

Sólo se admiten vías de documentación conocidas. Las rutas desconocidas devuelven 404. Un error al cargar la página devuelve 502; otro error de conversión devuelve 500. La respuesta es Markdown con CORS de lectura permisiva y una política de caché pública de cinco minutos con estado obsoleto mientras se revalida. Estos artículos públicos exportados no contienen credenciales de proyectos locales.

En Cloudflare, el asistente prefiere el enlace ASSETS para páginas prerenderizadas. Esto mantiene la lectura dentro de la implementación del trabajador. El desarrollo puede recurrir a la recuperación en vivo cuando la compilación de activos existente no contiene una página. Por lo tanto, un árbol de distribución local obsoleto y un árbol de origen actual pueden ser entradas diferentes durante la edición.

asistente de documentacion

POST /api/docs-assistant acepta mensajes de conversación, una ruta de documentación opcional y un identificador de sesión de backend opcional. Conserva solo los mensajes del usuario/asistente, recorta cada mensaje a 1,200 caracteres, conserva los 12 mensajes válidos más recientes y requiere una pregunta del usuario.

La recuperación primero califica la pregunta actual y las preguntas anteriores de los usuarios según títulos, rutas, palabras clave y resúmenes. Se conserva la página conocida actual. Cuando está disponible un enlace de Workers AI, un planificador de llamadas de herramientas opcional puede seleccionar rutas de documentación relevantes; las selecciones no válidas o los errores del planificador recurren a la recuperación léxica.

Se cargan hasta tres páginas. Cada uno se condensa en un presupuesto de 5,000 caracteres conservando su introducción y sus secciones coincidentes. Por lo tanto, una página larga de recursos API no se proporciona automáticamente en su totalidad al modelo. Vincular al usuario a la operación relevante cuando el extracto no contenga suficientes detalles.

Markdown cargado se almacena en caché por separado durante 30 minutos cuando la caché del trabajador está disponible. Una edición de origen puede requerir una actualización de la caché en una implementación que ya se está ejecutando. Si no se puede cargar ninguna página seleccionada, la ruta devuelve 502. Si no existe ningún enlace de Workers AI o una configuración completa de backend de nikcli, devuelve 503 antes de la generación.

Una sola solicitud de asistente puede contener como máximo 12 mensajes de conversación y una pregunta está limitada a 1,200 caracteres (MAX_MESSAGES y MAX_QUESTION_CHARS en src/lib/docsAssistant.ts).

Modelos y límites de tarifas

La ruta nikcli crea o reutiliza una sesión remota, se suscribe a su transmisión antes de enviar el mensaje y aplica un tiempo de espera de 90 segundos. Se trata de soporte de documentación en un backend configurado; su token está separado del puente de la aplicación CAD/CAM o de las credenciales del proveedor.

El limitador de velocidad requiere el enlace KV opcional y un encabezado IP de cliente. Su secuencia de lectura/incremento/escritura es de mejor esfuerzo en lugar de una cuota de seguridad atómica, y se permiten fallas de KV. Sin la vinculación, no se aplica un límite por IP. No lo presente como una asignación garantizada ni se base en afirmaciones de precios de modelos históricos.

La configuración del adaptador local desactiva los enlaces remotos. El modelo no tiene implementación local en este sitio. Una vista previa normal de un artículo local puede funcionar mientras las solicitudes del asistente devuelven 503. Configure un backend accesible o valide el comportamiento del modelo en el entorno de implementación previsto.

Artefactos de guía generados

Una solicitud de una guía, lista de verificación, referencia o página reutilizable similar puede producir un borrador de artefacto. Con ARTIFACTS R2 almacenamiento, el asistente lo normaliza a un documento HTML y escribe contenido más metadatos. Un documento vacío normalizado o uno mayor a 256 KiB no se publica.

El enlace devuelto lleva un ?key= capacidad de lectura. Cualquiera que tenga ese enlace completo puede leer el artefacto. El simple identificador no es suficiente; No existe una puerta de inicio de sesión de cuenta de propietario para estos guías anónimos. Trate la clave como una credencial compartida y evite colocar datos privados del proyecto en una guía compartida públicamente.

El visor utiliza un shell privado, sin caché y un entorno limitado de iframe que permite secuencias de comandos y ventanas emergentes sin permiso del mismo origen. La ruta HTML sin formato aplica una política de contenido que permite scripts/estilos en línea e imágenes de blobs/datos incrustados, pero bloquea las recuperaciones de red externas y las cargas de fuentes/estilos/scripts externos. Las guías generadas deben ser independientes; su diseño no puede depender del DOM actual del sitio o del almacenamiento local.

El asistente de publicación actual escribe la versión 1 y una nueva capacidad aleatoria. La ruta sin formato puede seleccionar una versión almacenada válida con v; una versión no válida o fuera de rango recurre a la última versión almacenada. Ese soporte de recuperación no establece una API pública de edición/administración de versiones.

ARTIFACT_PUBLIC_ORIGIN puede seleccionar el origen canónico del enlace compartido para implementaciones no locales. El almacenamiento faltante devuelve 503 en el acceso a los artefactos. El contenido faltante devuelve 404 y una capacidad de lectura rechazada devuelve 401. Mantenga separados el almacenamiento de guías generado y los activos de documentación pública.

estudio local

El estudio elige CADCAMFUN_DB, entonces DATABASE_URL después de eliminar un prefijo de archivo inicial, entonces el repositorio data/cadcamfun.db. Solo abre un archivo existente. Esta selección difiere del valor predeterminado relativo al proceso de la CLI del paquete de base de datos y del directorio de datos de la aplicación del escritorio nativo.

El inicio de sesión verifica la contraseña almacenada de un usuario existente con el verificador de contraseñas de Bun. Escribe una sesión de siete días en la tabla de sesión de la aplicación y establece una cookie SameSite=Lax solo HTTP para el Studio local. Ese servidor local no implementa ningún registro de usuario ni arranque de contraseña inicial. Un perfil local nativo sin contraseña no adquiere una contraseña de Studio automáticamente.

Las consultas de descripción general autenticadas cuentan usuarios, proyectos, dibujos y rutas de herramientas en la instalación seleccionada y luego devuelven los ocho proyectos actualizados más recientemente. Es una descripción general de la instalación local en lugar de un panel filtrado de propiedad por proyecto. Utilice una base de datos y una cuenta locales apropiadas; Abrir Studio no es motivo para apuntar a un archivo de usuario no relacionado.

El retroceso de la producción bajo /studio/api/* es HTTP 503. La implementación de los documentos públicos no carga contenidos de SQLite ni convierte esta herramienta local en un servicio de base de datos alojado.

Despliegue

wrangler.toml declara la entrada de trabajador, el directorio de activos estáticos, los dominios personalizados en cadcam.fun, la IA de trabajadores, los espacios de nombres KV de límite de velocidad de asistente y de sesión, y el depósito de artefactos R2. Wrangler aprovisiona recursos dedicados y los vincula al despliegue. Configure secretos a través del entorno Cloudflare de destino. Un nombre vinculante en una interfaz TypeScript no es prueba de que el recurso existe en la cuenta.

El script de implementación construye Astro, escribe dist/.assetsignore por lo que la entrada Trabajador se excluye de los activos estáticos e invoca la implementación de Wrangler. La implementación es una operación de publicación; La verificación de documentación normal debe utilizar comprobaciones locales y de compilación sin ejecutarla.

Antes de publicar, valide las rutas estáticas y la actualización de las instantáneas de API, confirme los enlaces previstos, verifique el comportamiento de falla del asistente sin su backend y verifique el acceso a la capacidad de los artefactos si el almacenamiento está habilitado. Después de la publicación, inspeccione la implementación resultante y el backend configurado en lugar de tratar una compilación local como evidencia de un servicio activo.

Diagnóstico operativo

Fuentes de implementación: astro.config.mjs, wrangler.toml, script/dev.ts, script/deploy.ts, script/studio-server.ts, src/lib/docsMarkdown.ts, docsRetrieval.ts, nikcliDocsSession.ts, docsArtifact.tsy los controladores de ruta en src/pages.

Scripts del paquete de documentos.

escribiendo una pagina

1. Crear src/pages/docs/<slug>.astro usando DocsLayout con title, subtitle, description y un toc matriz cuyo hrefs coinciden con los identificadores de sección.
2. Escribe cada sección como <section id="…" class="doc-section"> con uno <h2>.
3. Usar DocCode (language, title) para el código, DocCallout (type información, advertencia o nota) para advertencias, DocCard para redes de enlaces, DocRelated al final, y DocViewer3D para vistas previas de 3D.
4. Escapar de llaves literales en el texto como { y }; poner código dentro de una expresión como {String.raw`…`}.
5. Agregue la página a los datos de la barra lateral y ejecute bun run typecheck, que también reconstruye y verifica el índice de búsqueda.

---
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>

3D vistas previas

El componente utiliza three.js con Z hacia arriba, se monta solo cuando se desplaza hacia la vista y muestra un texto alternativo sin WebGL. Entréguele resultados reales, como movimientos del núcleo, en lugar de coordenadas dibujadas a mano.

En 3D