@orca/docs¶

此包包含与 Orca 源代码一起发布的产品文档和公开媒体。

Orca 的开源产品文档，通过 /docs 提供（URL 结构与 https://www.onorca.dev/docs 相同）。

此包是一个自包含的 Next.js 应用。它有意不是根 monorepo 工作区成员，因此安装 Electron 应用依赖时不会拉取 Next/fumadocs。

本地开发¶

cd docs/site
pnpm --ignore-workspace install
pnpm --ignore-workspace dev

打开 http://localhost:3004/docs。

生产构建¶

cd docs/site
pnpm --ignore-workspace install
pnpm --ignore-workspace build
pnpm --ignore-workspace start

pnpm start 在端口 3004 上提供生产构建。路径：

布局¶

• content/docs/ — MDX 页面 + meta.json 导航
• public/docs/ — 仅用于文档的媒体、logo 和 favicon（GIF、海报、截图）
• src/app/docs/ — fumadocs 路由、OG 图片
• src/components/ — 文档作用域的外壳（页眉/页脚/搜索），不是营销站点

更新内容¶

将文档树视为有意设置的发布边界。在导入源材料之前，检查 diff 中的内部引用、凭据、第三方媒体权利以及功能/版本声明，然后仅复制已批准的页面和资源。将应用外壳和部署配置保留在此仓库中，以便仅包含文档的拉取请求可以独立审查和构建。

同域路由¶

文档应用是一个独立的 Vercel 项目（docs 区域），并保留公开的 /docs URL 命名空间。营销站点仍然是 www.onorca.dev 的默认区域；使用这些 beforeFiles 重写规则配置其 Next/Vercel 代理，并将 DOCS_ORIGIN 替换为文档项目的生产 URL：

return {
  beforeFiles: [
    {
      source: '/docs',
      destination: `${DOCS_ORIGIN}/docs`
    },
    {
      source: '/docs/:path*',
      destination: `${DOCS_ORIGIN}/docs/:path*`
    },
    {
      source: '/docs-static/:path*',
      destination: `${DOCS_ORIGIN}/docs-static/:path*`
    }
  ]
}

/docs-static 是 docs 区域的 assetPrefix；它可防止与营销区域发生 _next 资源冲突。将重写规则保留在默认区域中，并在区域之间导航时使用普通 <a> 链接。不要为此应用添加 basePath: '/docs'：其路由树和 Fumadocs baseUrl 已经包含 /docs，这样做会发布 /docs/docs/... URL。如果未来部署需要 basePath，请先将路由树移动到无前缀的 src/app/[[...slug]] 结构，并一起更新所有生成/链接 URL。

部署（Vercel）¶

1. 创建一个 Root Directory 未设置（.）的 Vercel 项目。该工作流从 docs/site 调用 Vercel，因此该目录已经是部署根目录；再次设置会解析为 docs/site/docs/site。保持自动 Git 部署禁用，以便此工作流仍然是唯一的部署路径。
2. 框架预设：Next.js。安装使用 pnpm --ignore-workspace install --frozen-lockfile，构建使用 pnpm --ignore-workspace build；此包在根工作区旁边有自己的 lockfile。
3. 设置 GitHub Actions secrets（生产部署作业所需）：
4. VERCEL_TOKEN
5. VERCEL_ORG_ID
6. VERCEL_PROJECT_ID（文档项目，不是营销站点）
7. 使用必需审查人和针对 main 以及 v* 标签的自定义部署分支策略保护 docs-production GitHub 环境。release-cut 分发从 main 运行；直接已发布 release 的回退从稳定标签运行，而工作流仍然只授权精确的稳定标签。
8. 在 www.onorca.dev 营销项目中准备上述三个重写规则，但在验证文档部署之前保持它们禁用。Vercel 自定义域名本身无法仅委托 /docs；默认区域必须同时代理页面/API/媒体请求和 /docs-static 资源。在过渡期间保留营销项目的旧文档路由以便回滚；将代理规则放在 beforeFiles 中可确保启用后它们优先生效。
9. 部署一个包含 docs/site 的稳定桌面标签，验证 docs origin，然后启用营销重写规则。在此包添加之前切出的标签无法初始化 docs 项目，因为生产环境有意检出标签的精确 commit。在代理稳定后，通过后续操作移除旧的营销文档路由。

.github/workflows/docs.yml 为每个拉取请求运行无凭据检查。它有意不部署 PR 预览：PR 控制的构建不得接收 Vercel 凭据。维护者之后可以添加单独的受信任预览工作流。生产部署仅来自已授权稳定桌面 release：精确的 vX.Y.Z 标签、已发布的非预发布 release，以及 github-actions[bot] release 作者。手动分发必须从默认分支运行，并指定一个满足相同检查的现有 release。移动端、预发布、草稿以及人工创建的 release 会被跳过。Fork 拉取请求仍仅执行构建，因为 GitHub 不会向 fork 作业暴露部署 secrets。

版本管理¶

versioning.config.ts 保持当前无版本 /docs URL 稳定，同时为未来快照保留 content/versions/<id>。版本化路由尚未上线；当需要时，添加相应的 loader/路由和一个版本条目。然后 release 工作流可以在不更改触发的情况下部署它们。

与桌面应用的隔离¶

• 在 docs/site/ 下拥有自己的 package.json + pnpm-lock.yaml
• 未列在根目录的 pnpm-workspace.yaml 中；使用 pnpm --ignore-workspace 安装
• 工程说明仍保留在仓库根目录的 docs/ 中 — 不要将此包与之混淆