文档站点操作

网站架构

packages/web 是带有 Cloudflare 适配器的 Astro 服务器输出应用程序。文档文章声明预渲染并成为静态 HTML 资源。服务器路由处理 Markdown 导出、文档助理请求、工件查看/原始内容以及制作 Studio 后备。此部署与 CAD/CAM sidecar 是分开的。

该文档站点描述应用程序行为并提供生成的参考内容。它不会继承访问者的项目、本地应用程序承载令牌、提供商凭据或配对桌面连接。它的助手使用文档摘录，而不是默默地操作 CAD/CAM 工作区。

本地Studio是一个额外的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 选择每个操作、解析命名模式并提供资源模板。快照是使用其已安装的 Effect 实现从组合应用程序 HttpApi 生成的。

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，它会获取相应的渲染文章并将其转换为 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 装饰和按钮，因此导航和复制控件不会成为答案上下文。它转换代码块、标题、表格和链接，而不是维护第二个手写 Markdown 语料库。

仅允许已知的文档路径。未知路径返回 404。页面加载失败返回502；另一个转换失败返回 500。响应是带有许可读取 CORS 的 Markdown 和带有 stale-while-revalidate 的公共五分钟缓存策略。这些导出的公共文章不包含本地项目凭据。

在 Cloudflare 上，帮助程序更喜欢预渲染页面的 ASSETS 绑定。这会将读取保留在 Worker 部署中。当现有资产构建不包含页面时，开发可以回退到实时获取。因此，在编辑时，过时的本地 dist 树和当前源树可以是不同的输入。

文档助理

POST /api/docs-assistant 接受对话消息、可选文档路径和可选后端会话标识符。它仅保留用户/助理消息，将每条消息修剪为 1,200 个字符，保留最近的 12 个有效消息，并要求用户提问。

检索首先根据标题、路线、关键字和摘要对当前问题和早期用户问题进行评分。保留当前已知页面。当 Workers AI 绑定可用时，可选的工具调用规划器可以选择相关的文档路线；无效的选择或规划器失败会退回到词汇检索。

最多加载三页。通过保留其介绍和匹配部分，每个预算都压缩为 5,000 字符预算。因此，较长的 API 资源页面不会自动完整地提供给模型。当摘录不包含足够的详细信息时，将用户链接到相关操作。

当 Worker 缓存可用时，加载的 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 KiB 的文档。

返回的链接带有一个 ?key= 读取能力。任何拥有完整链接的人都可以阅读该工件。光有标识符是不够的；这些匿名指南没有所有者帐户登录入口。将密钥视为共享凭证，并避免将私有项目数据放入公开共享的指南中。

查看器使用私有的、非缓存的 shell 和 iframe 沙箱，允许在没有同源权限的情况下执行脚本和弹出窗口。原始 HTML 路由应用内容策略，允许内联脚本/样式和嵌入数据/blob 图像，但阻止外部网络获取和外部字体/样式/脚本加载。生成的指南必须是独立的；它们的布局不能依赖于站点当前的 DOM 或本地存储。

当前的发布助手编写了版本 1 和新的随机功能。原始路由可以选择一个有效的存储版本 v;无效或超出范围的版本会回退到最新存储的版本。该检索支持不建立公共编辑/版本管理 API。

ARTIFACT_PUBLIC_ORIGIN 可以为非本地部署选择规范的共享链接源。缺少存储会在工件访问时返回 503。缺少内容返回 404，拒绝的读取功能返回 401。将生成的指南存储和公共文档资产分开。

本地工作室

工作室选择 CADCAMFUN_DB， 然后 DATABASE_URL 剥离初始文件前缀后，然后存储库的 data/cadcamfun.db。它仅打开现有文件。此选择不同于数据库包 CLI 的进程相关默认值和本机桌面的应用程序数据目录。

登录使用 Bun 的密码验证器检查现有用户存储的密码。它将 7 天的会话写入应用程序会话表，并为本地 Studio 设置仅 HTTP、SameSite=Lax cookie。该本地服务器没有实现用户注册或初始密码引导。没有密码的本机本地配置文件不会自动获取 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.

docs包的脚本

写一页

1. 创造 src/pages/docs/<slug>.astro 使用 DocsLayout 和 title, subtitle, description 和一个 toc 数组，其 hrefs 匹配部分 ID。
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>

3D 预览

该组件使用 Z 向上的 Three.js，仅在滚动到视图中时安装，并在没有 WebGL 的情况下显示文本回退。向其提供真实的输出，例如内核移动，而不是手绘坐标。

在 3D