ドキュメントサイトの運営

サイトのアーキテクチャ

packages/web cloudflare アダプターを備えた Astro サーバー出力アプリケーションです。ドキュメント記事はプリレンダリングを宣言し、静的な HTML アセットになります。サーバー ルートは、Markdown のエクスポート、ドキュメント アシスタントのリクエスト、アーティファクトの表示/生のコンテンツ、および運用 Studio フォールバックを処理します。この展開は、CAD/CAM サイドカーとは別のものです。

ドキュメント サイトでは、アプリケーションの動作について説明し、生成された参照コンテンツを提供します。訪問者のプロジェクト、ローカル アプリケーション ベアラー トークン、プロバイダーの資格情報、またはペアになったデスクトップ接続は継承されません。そのアシスタントは、CAD/CAM ワークスペースを黙って操作するのではなく、ドキュメントの抜粋を使用します。

ローカル スタジオは追加の Bun プロセスです。 bun:sqlite。 Vite は、開発 API リクエストをループバック ポート 4396 にプロキシします。デプロイされたCloudflare Workerは、そのローカルデータベースを開くことができません。実稼働 Studio 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

Studioが不要な場合はAstro単体で記事編集を行ってください。実稼働コンパイルでは、テンプレートの生成とルート出力を検証しますが、実際のモデルのバックエンドの呼び出し、アーティファクトの公開、デプロイされた Cloudflare アカウントの検証は行いません。

コンテンツとAPIの生成

記事が存在する場所 src/pages/docs そして共有する DocsLayout.astro。のサイドバー src/data/docsSidebar.ts はドキュメントルートの在庫です。 docsIndex.ts ルートごとの概要と検索用のキーワードを追加します。公開ページには、ナビゲーション エントリと正確な検索コピーの両方が必要です。リンクされていない記事は、そのファイルが存在するだけでは検出可能になりません。

API リファレンスは、生成されたコントラクト スナップショットと厳選されたリソース グループを組み合わせます。 src/data/apiGroups.ts. src/lib/apiReference.ts すべての操作を選択し、名前付きスキーマを解決し、リソース テンプレートを提供します。スナップショットは、インストールされたエフェクト実装を使用して、構成されたアプリケーション HttpApi から生成されます。

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

再生成により、現在のスキーマ コントラクトが書き込まれます。ドメイン ガイダンスを記述したり、リモート アプリケーションが同じバージョンであることを証明したりするものではありません。 Handwritten pages explain business validation, side effects, permissions, recovery, and implementation limits.これらの説明は、実際のハンドラーとサービスに関連付けておいてください。

出典閲覧メモは以下で作成できます。 packages/web/.tmp/content。これらは一時的な編集資料であり、出版から除外されています。完成した説明を記事ページに移動し、ナビゲーション/検索を更新します。一時的なメモを操作の唯一の文書として使用しないでください。

マークダウンエクスポート

GET /llm 既知のドキュメント ページを Markdown リンクとしてリストします。と path、対応するレンダリングされた記事を取得し、それを GitHub 風味の Markdown に変換します。追加 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 装飾、ボタンが削除されるため、ナビゲーションやコピー コントロールが回答コンテキストになりません。 2 番目の手書き Markdown コーパスを維持するのではなく、コード ブロック、見出し、テーブル、リンクを変換します。

既知のドキュメント パスのみが許可されます。不明なパスは 404 を返します。ページの読み込みに失敗すると、502 が返されます。別の変換失敗では 500 が返されます。応答は、許容読み取り CORS と stale-while-revalidate を備えたパブリック 5 分間キャッシュ ポリシーを備えた Markdown です。これらのエクスポートされた公開記事には、ローカル プロジェクトの認証情報は含まれません。

Cloudflareでは、ヘルパーは事前レンダリングされたページのASSETSバインディングを優先します。これにより、ワーカー デプロイメント内で読み取りが維持されます。既存のアセット ビルドにページが含まれていない場合、開発はライブ フェッチにフォールバックできます。したがって、古いローカル dist ツリーと現在のソース ツリーは、編集中に異なる入力になる可能性があります。

文書作成アシスタント

POST /api/docs-assistant 会話メッセージ、オプションのドキュメント パス、およびオプションのバックエンド セッション識別子を受け入れます。ユーザー/アシスタント メッセージのみを保持し、各メッセージを 1、200 文字にトリミングし、最新の 12 個の有効なメッセージを保持し、ユーザーの質問を必要とします。

取得では、まず、タイトル、ルート、キーワード、および概要に対して、現在の質問と以前のユーザーの質問にスコアが付けられます。現在の既知のページは保持されます。 Workers AI バインディングが利用可能な場合、オプションのツール呼び出しプランナーは関連するドキュメント ルートを選択できます。無効な選択またはプランナーの失敗は、字句検索にフォールバックします。

最大 3 ページまで読み込まれます。それぞれは、導入部と一致するセクションを保持することで、5、000 文字の予算に凝縮されます。したがって、長い API リソース ページは、完全にモデルに自動的に提供されません。抜粋に十分な詳細が含まれていない場合は、ユーザーを関連する操作にリンクします。

ロードされたマークダウンは、ワーカー キャッシュが使用可能な場合、30 分間個別にキャッシュされます。ソース編集では、すでに実行中のデプロイメントでキャッシュの更新が必要になる場合があります。選択したページをロードできない場合、ルートは 502 を返します。 Workers AI バインディングまたは完全な nikcli バックエンド構成が存在しない場合は、生成前に 503 を返します。

1 つのアシスタント リクエストには最大で 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 KiB を超えるドキュメントは公開されません。

返されたリンクには、 ?key= 読み取り能力。その完全なリンクを知っている人は誰でもアーティファクトを読むことができます。単なる識別子では十分ではありません。これらの匿名ガイドには所有者アカウントのログイン ゲートはありません。キーを共有認証情報として扱い、非公開のプロジェクト データを公開共有ガイドに入れないようにしてください。

ビューアは、キャッシュされていないプライベート シェルと iframe サンドボックスを使用し、同一オリジンのアクセス許可なしでスクリプトとポップアップを許可します。生の HTML ルートは、インライン スクリプト/スタイルおよび埋め込みデータ/BLOB イメージを許可するが、外部ネットワークの取得と外部のフォント/スタイル/スクリプトの読み込みをブロックするコンテンツ ポリシーを適用します。生成されたガイドは自己完結型である必要があります。レイアウトは、サイトの現在の DOM やローカル ストレージに依存することはできません。

現在の公開ヘルパーは、バージョン 1 と新しいランダム機能を書き込みます。 raw ルートは、有効な保存バージョンを選択できます。 v;無効なバージョンまたは範囲外のバージョンは、保存されている最新のバージョンにフォールバックします。この取得サポートは、公開編集/バージョン管理 API を確立しません。

ARTIFACT_PUBLIC_ORIGIN 非ローカル展開の正規の共有リンク起点を選択できます。ストレージが不足していると、アーティファクトへのアクセス時に 503 が返されます。コンテンツが欠落している場合は 404 が返され、読み取り機能が拒否された場合は 401 が返されます。生成されたガイドのストレージと公開ドキュメントの資産を分離してください。

ローカルスタジオ

スタジオが選ぶ CADCAMFUN_DB、 それから DATABASE_URL 初期ファイルのプレフィックスを削除した後、リポジトリの data/cadcamfun.db。既存のファイルを開くだけです。この選択は、DB パッケージ CLI のプロセス相対デフォルトおよびネイティブ デスクトップのアプリケーション データ ディレクトリとは異なります。

ログインは、Bun のパスワード検証機能を使用して、既存のユーザーの保存されたパスワードをチェックします。これは、アプリケーションのセッション テーブルに 7 日間のセッションを書き込み、ローカル Studio に HTTP のみの SameSite=Lax Cookie を設定します。そのローカル サーバーでは、ユーザー登録または初期パスワード ブートストラップは実装されません。パスワードのないネイティブ ローカル プロファイルは、Studio パスワードを自動的に取得しません。

認証された概要クエリは、選択したインストール全体のユーザー、プロジェクト、図面、およびツールパスをカウントし、最後に更新された 8 つのプロジェクトを返します。これは、プロジェクトごとの所有権でフィルターされたダッシュボードではなく、ローカル インストールの概要です。適切なローカル データベースとアカウントを使用します。 Studio を開いたからといって、関係のないユーザーのファイルを指定する理由にはなりません。

本番環境のフォールバック /studio/api/* hTTP 503 です。パブリック ドキュメントを展開しても、SQLite コンテンツがアップロードされたり、このローカル ツールがホストされたデータベース サービスに変わったりすることはありません。

導入

wrangler.toml ワーカー エントリ、静的アセット ディレクトリ、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.

docs パッケージのスクリプト

ページを書く

1. 作成する src/pages/docs/<slug>.astro を使用して DocsLayout と title, subtitle, description そして toc その配列 href■ セクション ID と一致します。
2. 各セクションを次のように書きます <section id="…" class="doc-section"> 1つで <h2>.
3. 使用 DocCode (language, title) コードの場合、 DocCallout (type info、warn、または note) 警告の場合、 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>

3D プレビュー

このコンポーネントは Z を上にして three.js を使用し、ビューにスクロールした場合にのみマウントし、WebGL を使用せずにテキスト フォールバックを表示します。手書きの座標ではなく、カーネルの動きなどの実際の出力を入力します。

3Dで