# 构建与入口

人类默认从 `/` 进入；Agent 从 `/agent` 或 `/agent/index.md` 读取 `text/markdown` 索引，根目录 `/llms.txt` 提供发现链接。索引复用技能目录，技能继续使用 `/skills/<id>/SKILL.md` 和现有子文档 URL，避免复制文档。

`ces-control` 必须预装 Docker、Compose，并允许 Runner 访问持久 Docker daemon。CI 只检查环境，不安装系统包、不启停主机服务。当前服务器没有 buildx，先继续使用 daemon 自带层缓存；不要直接粘贴依赖 GitHub cache 服务的 `type=gha` 参数。后续若换 Docker daemon 或清理缓存，会重新冷构建。

Dockerfile 保持单次 COPY，`.dockerignore` 排除非构建输入；根 Markdown 和 docs 不再使应用构建层失效。push 和 PR 对纯文档改动使用 paths，但 public 下的 Markdown 属于产品资源，必须构建部署。public 下的技能 Markdown 继续纳入构建。旧 builder 每条 COPY 实测约 47 秒，避免拆成多条 COPY 增加快照成本。仍保留类型检查、单元测试、smoke 与完整隔离栈集成测试。

当前页面为 Next.js SSR 与编译组件，改 TSX 仍需 next build。把 HTML 的 COPY 移到最后不能避免编译。独立挂载静态文件会破坏镜像版本与回滚的一致性；只有真正独立、无需编译的内容才适合后续拆成单独发布渠道。

## Web 快速发布

main 的 push 与当前已部署 SHA 比较；只有页面、组件、样式、技能文档数据和 public 改动才走 Web 路径，API、共享库、依赖、配置、worker、脚本及数据库变化均回退完整流水线。PR 和手动运行始终完整验证；依赖构建镜像缺失也回退完整流水线。

Web 路径复用当前 runtime 对应的已验证 integration 镜像作为工具环境，在临时容器构建生产 Web，不运行 docker build。编译缓存按基础镜像隔离持久保存。类型检查、单元测试和 Web smoke 仍同步执行，完整隔离栈测试只在全量路径执行。

完整 standalone 产物存入 `/opt/prompt/web-artifacts/<sha>.<run>`，只读挂载到 Web 容器；仅重建 Web，保留 runtime 镜像、worker、Postgres 和 RustFS。切换前检查 main 与当前发布，部署锁与全量流程共用；失败自动恢复旧 Web Compose 配置。发布文件保留变量表达式，不写入生产秘密。健康检查通过后切换 current；原完整发布也能回滚到 Web 快速发布。

首次接入流水线变更仍走完整验证；后续 Web 更新速度需要实测，不能承诺 HMR 的毫秒级反馈。每次发布完整 Web 产物，不把个别 chunk 混入正在运行的 Next.js 版本。