内容
# create-hayate
> **Hayate 生态系统：** [从这里开始](https://github.com/hayatepy/.github/blob/main/docs/START.md)
> · [生产黄金应用](https://github.com/hayatepy/golden-app)
> · [测试兼容性](https://github.com/hayatepy/.github/blob/main/docs/COMPATIBILITY.md)
> · [前端矩阵](docs/FRONTEND_COMPATIBILITY.md)
Hayate 的可组合、面向生产的项目脚手架。
黄金路径创建一个具有安全请求关联的应用程序核心，紧凑的 JSON 访问事件，API 路由，OpenAPI/Scalar，MCP 2025-11-25，检查 SQL，Cloudflare Access 身份，ASGI 上的 SQLite 和 Cloudflare Workers 上的 D1：
```sh
uvx create-hayate my-app --template workers --preset production
cd my-app
uv run pytest
uv run python manage_workers.py d1 migrations apply DB --local
uv run python manage_workers.py dev
```
生成的 README 在 10 分钟内保持脚手架到启动的路径，并包含一个关闭的生产检查清单。
## 运行环境
| 模板 | 运行环境 | 默认组合 |
|---|---|---|
| `api`（默认） | ASGI | 测试 TODO API |
| `workers` | ASGI 和 Cloudflare Python Workers | 相同的测试 API |
| `mcp` | ASGI 和 Workers | `workers` + MCP 组件 |
`mcp` 保留兼容性快捷方式。它不是复制的模板。
## 功能
显式组合功能，而不是从模板矩阵中选择：
```sh
uvx create-hayate my-app \
--template workers \
--with admin,openapi,mcp,sql \
--auth cloudflare-access
```
| 功能 | 生成边界 |
|---|---|
| 内置 | 验证请求 ID 和无查询结构化访问事件，跨 ASGI 和 Workers |
| `admin` | 显式身份范围 TODO 操作 UI，具有检查 SQL，编辑审计历史，安全品牌和可访问的本地控件 |
| `openapi` | 类型化 UUID/响应契约，OpenAPI 3.1.1，增强 Scalar，固定 TypeScript 导出 |
| `mcp` | MCP 2025-11-25 工具，共享请求身份和存储 |
| `sql` | 检查迁移的 `hayate-sql`；ASGI 上的 SQLite 和 Workers 上的 D1 |
| `--auth cloudflare-access` | 本地显式身份；生产 RS256/JWKS 验证 |
MCP 项目在 uv 通用锁中保留 Emscripten 和 CPython 依赖解析。这保留了 Pyodide 在 Workers 上审查的 `rpds-py` 构建，同时在 macOS 和其他 CPython 平台上安装本机 Python 3.14 轮。
`admin` 意味着 `sql` 和 Cloudflare Access，目前仅限于 `--frontend none` 的 Workers 模板；该模板仍然通过 ASGI 运行不变，以便进行本地和回退验证。生成器不创建匿名模式或默认超级用户。操作员是显式不区分大小写的电子邮件允许列表，记录范围限定为 Access 对象，突变需要精确配置的源，审计行永远不包含提交的值。
所有 52 种支持的后端组合都已生成，依赖关系已解析，并在 CI 中导入。无效组合在写入目标目录之前失败；例如，admin 拒绝显式 `--auth none` 和每个未经审查的前端组合。
## 前端
前端选择独立于运行时，身份验证和可选后端功能：
```sh
uvx create-hayate my-app \
--template workers \
--frontend htmx \
--with openapi,sql
```
| 前端 | 所有权边界 |
|---|---|
| `none`（默认） | 仅后端输出；按字节兼容性路径 |
| `htmx` | 在 `/app` 处可执行的 Hayate + htmx 应用；共享 JSON API 在 `/api` 处 |
| `react` | Vite/React Router SPA，具有生成的，漂移检查的 API 类型 |
| `astro` | 静态 Astro 站点，具有小型 Preact 运行时岛和生成的 API 类型 |
前端层最后组合，禁止覆盖后端文件。`htmx` 生成身份范围 CRUD，验证片段，历史恢复，SSE，CSP/CSRF/缓存默认值，浏览器烟雾测试和校验和验证的自托管 htmx 2.0.10 资产。ASGI 通过 Hayate 提供该资产；Workers 使用 Cloudflare 静态资产，具有相同的同源 URL。
Jinja2 仍然是按字节兼容性的默认设置：
```sh
uvx create-hayate my-app \
--template api \
--frontend htmx \
--renderer htpy
```
`--renderer htpy` 为 ASGI 或 Workers 生成原生类型化 Python 组件。`jx` 在 ASGI 上生成 Jinja 支持的类型化组件，而实验性 `tdom` 在 ASGI 上使用 Python 3.14 t 字符串组件。所有渲染器配置文件都保留相同的路由，身份范围 CRUD，htmx 片段，安全标头和浏览器行为。显式渲染器项目在其 `frontend/renderer.toml` 中记录其运行时和 Python 契约，并添加严格的 mypy 检查在渲染器边界。直到 `hayate-htmx` 发布，ASGI 配置文件固定审查的 0.2.0 候选提交 `c133900`，而 htpy Workers 捆绑相同的小さ typed 边界，因为 Pywrangler 无法从其可移植锁安装 VCS 记录。
`react` 在 `frontend/` 处生成固定的 Node 24/Vite/React Router 应用程序。它自动启用 Hayate OpenAPI，保持 JSON 在 `/api` 下，从检查的生成的类型中派生 `openapi-fetch` 客户端，并在 OpenAPI 文档漂移时在 CI 中失败。Vite 在本地代理 `/api`；Workers 模板通过 Cloudflare 静态资产提供生产构建，具有 API 优先的路由和 SPA 深度链接回退。`npm ci`，类型检查，构建，依赖审计，Chromium CRUD 和真实工作路由在 CI 中进行测试。
`astro` 在相同的 `frontend/` 边界处生成固定的 Node 24 静态站点。公共内容在构建时导入；仅在可见 Preact 岛在浏览器中水合后，才请求经过身份验证的 TODO 数据。React 和 Astro 共享一个生成的 OpenAPI 契约组件，因此两个配置文件都不维护手写的 API 模型。本地开发代理 `/api` 到 Hayate，而 Workers 提供静态构建和 API 来自一个源。生成的静态输出审计拒绝私有数据标记，CI 涵盖 `npm ci`，类型检查，静态构建，Chromium 持久性/深度链接，依赖审计和真实工作路由。Astro SSR 仍然是一个明确的，适配器支持的 BFF 扩展，而不是初始运行时的组成部分。
非 `none` 配置文件在生产预设下被拒绝，直到每个配置文件都有一个审查的生产契约。数据支持的 [前端兼容性矩阵](docs/FRONTEND_COMPATIBILITY.md) 也是 CLI 允许列表：拉取请求从构建轮中执行 10 个边界组合，包括所有显式 htmx 渲染器，而每周和手动运行保留所有 112 个独特的支持运行时/前端/身份验证/功能/入口点组合在确定性分片中。每个运行发布阶段级命令，确切的工具版本和轮摘要为 JSON 证据。
## 生产预设
`--preset production` 是审查的组合：
- `openapi,mcp,sql`；
- Cloudflare Access 身份验证；
- 确切来源 CORS；
- 安全响应头和 1 MiB 请求体上限；
- Cloudflare 原生速率限制绑定；
- D1 迁移和部署配置；
- 在 `PRODUCTION.md` 中明确的秘密，身份验证，CORS，滥用，观察性，迁移和滚动检查。
Admin 仍然是生产预设的可选：
```sh
uvx create-hayate my-app \
--template workers \
--preset production \
--with admin
```
Admin 配置文件复制未经修改的 MIT 许可的审查的确切提交到生成的源树中。这保留了离线，零网络生成并避免了浮动分支和 Pywrangler 的 VCS 锁限制；确切的提交和许可证在 `admin/` 下记录。生成的站点使用转义的纯文本品牌，检查对比度的主题令牌，哈希 CSP 样式，键盘/辅助技术语义和上游应用程序范围的消息目录合同。
本地 CI 在真实的 ASGI HTTP 和真实的 workerd 上驱动生成的预设。Workerd 路径应用真实的 D1 迁移，通过 HTTP API 编写并通过 MCP 读取相同的身份验证数据。
## 设计
- **零依赖 CLI.** 生成仅使用标准库和捆绑的版本化组件；它不执行任何网络获取。
- **小组成表面.** 一个基础应用，一个 Workers 运行时叠加层，四个功能组件和显式身份验证/生产组件替换复制的完整模板组合。
- **正交前端所有权.** 运行时和后端功能首先组合；一个前端叠加层可以仅添加非冲突文件。`htmx` 调用与 JSON API 相同的域和存储函数；React 消耗生成的 OpenAPI 类型而不引入第二个后端；Astro 将公共构建时间内容与浏览器私有状态分开。
- **可移植应用程序核心.** `src/app.py` 在 ASGI 和 Workers 之间不变。运行时资源通过 Hayate 请求上下文进入。
- **默认安全可观察性.** 请求关联包装每个生成的身份，生产和可选功能边界；访问事件包含狭窄的元数据和确切的最终响应状态，而不包含查询字符串，标头或正文。
- **功能完整的 Workers 默认值.** `WorkerEntrypoint` 仍然是默认值。仅 HTTP 服务可以显式请求 `--workers-entrypoint global`。
- **证据优于声明.** CI 运行单元测试，每个依赖项组合，基于轮的前端兼容性，真实的 ASGI，真实的 workerd，D1 迁移，MCP，工作流审计和依赖项审计。
内部设计备忘录（日语，按项目惯例）是 [DESIGN.md](DESIGN.md)；发布历史记录在 [CHANGELOG.md](CHANGELOG.md) 中。
> **状态：alpha（0.11.x）。** 生成的项目固定了已发布的兼容性线。公共 API 在 1.0 之前可能仍会移动。
## 许可证
MIT
