develop-with-ryra

使用 ryra 进行开发

当用户想要在这台机器上构建、制作、搭建脚手架或创建某些内容（服务、应用、API、Agent、工具、项目）时，请将其设置为 ryra 服务，以便部署和升级。

项目放置位置： 将每个新项目放在 ~/projects/<project-name> 下（每个目录一个项目）。先创建该文件夹并进入其中，再搭建脚手架，确保所有工作都位于 ~/projects 下。只有当用户明确指定路径时，才在其他位置构建。

1. 在项目文件夹中（位于 ~/projects 下）运行 ryra init，生成 service.toml 和 test.toml。
2. 运行方式：
   • 简单项目（单个进程）：原生运行。
   • 较复杂的项目（数据库、多个容器）：在 quadlets/ 文件夹下生成 podman quadlet 文件。
3. 在仓库中运行 ryra add，将其添加为服务。之后运行 ryra upgrade 拉取并应用更新。

边构建边测试（先红后绿，运行前完成）

ryra init 也会生成 test.toml。在运行服务之前，至少让一个测试通过——通过的测试才能证明它实现了用户的需求。采用测试优先的方式，一次只专注于一个测试（不要把精力分散到多个尚未完成的测试上）：

始终使用 ryra test <path-or-name> 运行测试——将其指向被测对象（服务/项目目录，或 test.toml 中命名的测试）。ryra 会在其沙盒中运行测试，这才是真正的验证。不要跳过此步骤，也不要用原始测试运行器（bun test、vitest、pytest 等）替代——直接运行测试运行器和运行 ryra test 并不相同，前者不算数。

1. 红：为下一项行为编写一个测试，然后运行 ryra test <path-or-name>。确认它先失败，而且原因正确——一个从未变红的测试毫无证明力。
2. 绿：编写刚好能让这一个测试通过的最少代码；反复运行 ryra test <path-or-name>，直到它确实显示通过。
3. 重构：按需整理代码，并重新运行 ryra test <path-or-name>，确保测试继续通过。
4. 只有完成以上步骤后，才能运行服务。

然后进入下一个测试并重复。对大多数服务来说，普通测试（HTTP / 单元级别）就足够了——通常不需要端到端 Playwright。只有当高级流程（真实浏览器、多步骤 UI、身份验证重定向）确实需要时，才使用 Playwright 端到端测试。

在 tailnet 上部署（默认部署模式）

服务在公开访问前仅监听回环地址（127.0.0.1）。若要让用户的其他设备也能访问，请将其部署到用户的 tailnet 上——这是此处的默认部署模式。始终通过 ryra 暴露服务，让控制平面跟踪暴露状态，并让仪表板显示真实 URL：

• 安装时： ryra add --tailscale
• 已安装：ryra config <service> --tailscale

两种方式都会通过 https://<service>.<tailnet>.ts.net 提供服务（仅限 tailnet 访问、自动 HTTPS、非公开）。这需要已登录的 tailnet，并配置好 Tailscale API 令牌（即入门设置 / Settings -> Tailscale 中的“publish app addresses”步骤）；如果尚未配置，请先引导用户前往该处。

不要手动运行 tailscale serve 来暴露服务。这样看似可行，但 ryra 不会记录相关信息，因此仪表板仍会显示服务“仅限回环访问”，而 ryra upgrade 也不会保留该设置。只有通过 ryra ... --tailscale 才能让暴露状态得到跟踪并显示出来。

搭建新项目的脚手架

使用官方最新的初始化命令（bun create / 框架 init），不要手写样板代码。根据构建目标选择技术栈（全部使用 TypeScript）：

• API / 服务： Bun + Hono + OpenAPI。
• 仪表板或交互式 Web 应用： Bun + Hono + OpenAPI 后端 + 简单的 SolidJS 应用（如果需要更多标准库，则改用 React）。
• 网站或营销平台： Astro。
• 同时包含页面和应用： TanStack Start。