microservices-sh

# microservices.sh [](https://www.npmjs.com/package/create-microservices-app) [](https://www.npmjs.com/package/@microservices-sh/mcp) [](https://registry.modelcontextprotocol.io/v0.1/servers?search=sh.microservices/mcp) [](https://github.com/microservices-sh/microservices-sh/actions/workflows/ci.yml) [](https://nodejs.org) 用于 AI 构建的 Cloudflare 应用的生产基础。 microservices.sh 是一个系统工具，用于构建代理应用：源代码可见的 Cloudflare 原生模块、本地合约、锁定文件、确定性检查、项目 CLI 命令、MCP 工具和批准的部署计划。 对于使用 Claude Code、Cursor、Codex 或 Cloudflare 上的其他编码代理的开发人员：从可用的 Workers、D1 和 SvelteKit 应用开始，带有源代码可见、合约检查的模块，适用于危险的生产 30% - 授权、身份、支付、Webhook、电子邮件、审计日志、租户边界和部署检查。您的编码代理可以检查文档、计划更改、运行检查并在您准备好时准备部署计划。本地生成不需要 microservices.sh 账户或 Cloudflare 账户。 ```bash pnpm create microservices-app@latest studio-booking --template booking-sveltekit cd studio-booking pnpm install pnpm microservices local setup pnpm dev ``` 使用 npm： ```bash npm create microservices-app@latest studio-booking -- --template booking-sveltekit ``` `studio-booking` 是您的应用目录和 slug。目前完整的全应用模板 ID 为 `booking-sveltekit`。 ## 您获得的内容 - 一个真正的 Cloudflare SvelteKit 预订应用，带有公共预订流程、登录、支付和管理员屏幕。 - 源代码可见的模块，用于网关、身份验证、身份、客户、预订、审计日志和支付，可选添加电子邮件/管理员/Webhook。 - D1 迁移、Wrangler 配置、本地开发命令和 HTTP 烟雾检查。 - `microservices.lock.json` 用于固定模块版本并使升级可审查。 - `docs/` 下的 LLM 可读文档，以便 Claude、Codex、Cursor 或其他代理在编辑前检查。 - 一个项目 CLI，公开为 `pnpm microservices`，用于模块发现、检查、升级、本地设置和管理预览部署规划。 目标不是将生成的代码隐藏在平台后面。生成的项目是一个正常的仓库，您可以阅读、更改、导出和部署。 在 [什么是 microservices.sh 系统工具？](./docs/system-harness.md) 中阅读产品定义。 最新的干净快速入门证明记录在 [快速入门证明](./docs/quickstart-proof.md) 中。 ## 选择一个启动器 | 启动器 | 最适合 | 包括 | |---------|----------|----------| | `booking-sveltekit` | 服务业务、预约产品、代理演示 | 公共预约流程、管理员屏幕、身份验证、客户、预约、审计日志、D1 | | `saas-starter-sveltekit` | 多租户 B2B SaaS 应用 | 组织注册、团队 RBAC、订阅、管理员外壳、审计日志 | | `client-portal-sveltekit` | 客户门户和账户区域 | 客户身份验证、发票、文件、审计日志 | | `erp-shell-sveltekit` | 内部运营和代理 ERP 演示 | 客户、发票、文件、支持票证、团队、管理员、审计日志 | | `dot-ai-os` | 私有运营商试点工作区 | 任务、关注计划、日历、审查、知识/内容管道、AI 团队、联系人、文件、支持、团队 RBAC | | `company-landing-astro` | 静态公司网站 | Astro landing 页面，带有内容合约，无后端模块 | | `wordpress-emdash-blog-astro` | WordPress 博客迁移 | Astro + EmDash 导入路径、重定向、RSS、站点地图、D1/R2 | | `booking-business` | 低级 Workers/Hono 生成 | 从模块合约生成的 API-first 预订基线 | ## 良好匹配 | 用例 | 为什么此仓库有帮助 | |----------|---------------------| | 技术创始人或小型企业应用 | 从一个可用的预订/客户/支付基础开始，而不是从头开始重建身份验证、数据、迁移和管理流程。 | | 代理或 fractional CTO 交付 | 在客户端重用已知的生产基础，同时保持每个生成的应用的可检查性和客户端所有权。 | | AI 辅助开发 | 为您的代理提供稳定的模块合约、文档、检查和升级计划，而不是要求它临时构建基础设施。 | | 内部工具和运营门户 | 将常见的业务原语（如身份验证、客户、预订、审计日志、电子邮件和支付）组合成 Cloudflare 原生应用。 | | 模块/模板贡献者 | 在明确的合约、测试、文档和管理规则后面添加新模块和模板。 | 这可能不是适合您的情况，如果您想要一个无代码构建器、一个黑盒托管 SaaS 或一个没有升级合约的通用启动器模板。 ## 为什么代理在这里表现更好 - 模块文档生成到应用中，以便代理在编辑前检查本地合约。 - `microservices.lock.json` 固定模块版本，以便升级明确且可审查。 - 项目命令公开 `check`、`add --plan`、`upgrade --plan`、烟雾测试和部署计划，作为代理友好的 CLI 界面。 - 模块安装是版本固定的，因此降级/升级提案是明确的，而不是隐藏在生成的代码中。 - 机密、迁移、提供者操作和管理部署计划保持批准门控。 ## CLI 和 MCP 在应用内使用生成的项目 CLI 进行直接终端控制。这是发布时的规范公共 CLI 故事，因为它随生成的项目一起提供，并且了解该项目的锁定文件、模块和模板。 ```bash pnpm microservices modules list --json pnpm microservices docs booking pnpm microservices check --json pnpm microservices deploy run --plan ``` 在 `packages/cli` 下的根仓库 CLI 用于内部 SDK/控制平面开发。在其目录同步到 create-package 模板之前，请勿将其用作公共模板演示路径。 使用 MCP 服务器时，您希望 Claude、Codex、Cursor 或其他 MCP 客户端检查模块、组成应用计划、运行检查并准备确认门控部署计划。 ```bash npx -y @microservices-sh/mcp ``` MCP 服务器作为 [`@microservices-sh/mcp`](https://www.npmjs.com/package/@microservices-sh/mcp) 发布，并在 [官方 MCP 注册表](https://registry.modelcontextprotocol.io/v0.1/servers?search=sh.microservices/mcp) 中列为 `sh.microservices/mcp`。托管的 Streamable HTTP 端点是： ```text https://api.microservices.sh/mcp ``` ## 代理技能 此仓库在 [`skills/`](./skills) 中包含可移植的代理技能。在生成或检查应用后，将它们与 Codex 或其他技能感知型编码代理一起使用。 核心工作流技能： - [`skills/microservices-app-planner`](./skills/microservices-app-planner) - 为新应用创意选择启动器、模块集、风险、命令和第一个检查。 - [`skills/microservices-app-customizer`](./skills/microservices-app-customizer) - 通过配置、钩子、叠加层、路由、UI 和内容自定义生成的应用程序，同时保留升级边界。 - [`skills/microservices-production-readiness`](./skills/microservices-production-readiness) - 在试点、客户移交、预览或生产之前审计应用程序。 - [`skills/microservices-provider-setup`](./skills/microservices-provider-setup) - 计划和配置提供者集成，如 Stripe、电子邮件、Webhook、Google Calendar、R2、图像生成和广告。 - [`skills/microservices-data-migration`](./skills/microservices-data-migration) - 安全地将应用数据、身份验证用户、文件和提供者记录迁移到 microservices.sh。 - [`skills/microservices-authoring`](./skills/microservices-authoring) - 创建或更新模块、模板、合约、文档、检查和注册表贡献。 兼容性和迁移特定的技能： - [`skills/microservices-sh`](./skills/microservices-sh) - 在生成的应用程序中使用原始的全功能工作流技能。 - [`skills/supabase-to-microservices`](./skills/supabase-to-microservices) - 将 Supabase 应用（Postgres、Auth、Storage、Realtime、Edge Functions）迁移到 microservices.sh 模块，支持 D1、R2、Durable Objects 和 Workers。 - [`skills/firebase-to-microservices`](./skills/firebase-to-microservices) - 以类似的方式迁移 Firebase 应用（Firestore、Auth、Storage、Cloud Functions、FCM），将文档建模为关系型 D1 表。 - [`skills/prisma-postgres-to-d1`](./skills/prisma-postgres-to-d1) - 将 Prisma + Postgres 数据层转换为 D1 上的 Drizzle：模式、查询重写和数据导入。 - [`skills/express-api-to-workers`](./skills/express-api-to-workers) - 将 Express/Node API 移植到 Workers 运行时，位于模块边界后面，涵盖运行时差距（无进程状态、无文件系统、无原生 DB 驱动）。 - [`skills/vercel-next-to-cloudflare`](./skills/vercel-next-to-cloudflare) - 将 Vercel/Next.js 应用移动到 Cloudflare：主机级 OpenNext 移动或更深入的后端重建到 microservices.sh 模块。 - [`skills/wordpress-theme-to-astro`](./skills/wordpress-theme-to-astro) - 将 WordPress 主题重建为 Astro + EmDash 组件，具有基于截图的视觉一致性门控。 使用技能 CLI 从发布的 GitHub 仓库安装： ```bash npx skills add microservices-sh/microservices-sh --skill microservices-sh ``` 在从产品创意开始时，安装应用规划技能： ```bash npx skills add microservices-sh/microservices-sh --skill microservices-app-planner ``` 对于跨项目可用的用户级安装： ```bash npx skills add microservices-sh/microservices-sh --skill microservices-sh --global ``` 要检查仓库公开的内容： ```bash npx skills add microservices-sh/microservices-sh --list ``` 如果您已经在本地检查了此仓库，您也可以通过复制技能文件夹将其安装到 Codex： ```bash mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" cp -R skills/microservices-sh "${CODEX_HOME:-$HOME/.codex}/skills/" ``` 或者，在生成的 microservices.sh 应用内直接使用它，请求您的代理使用 `skills/microservices-sh` 技能。 ## 当前目录 模板列在 [选择启动器](#pick-a-starter) 下。下面的所有模块都是源代码可见且合约检查的；在生成的应用程序中运行 `pnpm microservices modules list`（或在此处运行 `pnpm cli -- modules list`）以获取实时状态。 | 模块 | 功能 | |--------|--------------| | `gateway` | 公共信任边界：API 密钥身份验证、速率限制、范围缩小 | | `auth` | EdDSA 服务令牌颁发/验证、范围检查、JWKS | | `identity` | 无密码电子邮件代码登录 + 服务器端会话 | | `idempotency` | 作用域幂等记录，用于安全重试、重放和重复副作用预防 | | `customer` | 客户资料、联系人字段、备注、生命周期事件 | | `booking` | 服务预订、可用性、预订记录、领域事件 | | `org-team-rbac` | 多租户组织、成员资格、角色、邀请 | | `billing-subscriptions` | Stripe 上的循环计划和订阅状态 | | `payment` | Stripe 支持的支付意图和支付记录 | | `invoice` | 发票，具有无缝原子编号、每行税、草稿→发布 | | `email` | 具有提供者中立端口的事务性电子邮件（Resend） | | `notifications-inapp` | 每用户应用内通知馈送 | | `webhook-delivery` | 事件总线的出站 Webhook 镜像 | | `audit-log` | 附加审计轨迹/领域事件接收器 | | `admin-shell` | 具有模式驱动的 CRUD 管理，适用于您的 D1 表 | | `forms-intake` | 动态表单构建器 + 具有验证的接收 | | `file-media` | R2 支持的上传，具有租户范围的密钥和上传票证 | | `image-generation` | 跨可插拔提供者的文本到图像（kie.ai 等） | | `jobs-workflows` | 具有幂等重试的持久后台作业 | | `calendar-google` | Google Calendar 同步（OAuth，D1） | | `ads-manager` | 跨平台广告监控（Meta，Google） | ## 本地基线 在生成的应用程序运行后，在第二个终端中使用烟雾检查： ```bash pnpm microservices local smoke ``` 常见的生成应用命令： ```bash pnpm microservices modules list --json pnpm microservices docs booking pnpm microservices upgrade booking --plan --json pnpm microservices add payment --plan --json pnpm microservices check --json ``` 托管的预览部署是有意为批准门控的，并通过 microservices.sh API 路由。对于公共启动路径，在托管 Worker/资产上传适配器和路由激活通过之前，请将此作为部署规划和就绪检查呈现。 ```bash pnpm microservices auth login pnpm microservices deploy run --plan # 预览托管部署工作流 pnpm microservices deploy upload-plan --json # 检查托管上传就绪情况 pnpm microservices local smoke --url <preview-url> ``` 需要手动驱动管道（BYO-Cloudflare 或调试）？粒度步骤位于 `pnpm microservices deploy --help-all` 下： ```bash pnpm microservices deploy doctor pnpm microservices deploy preview --confirm deploy --output deployment.json pnpm microservices deploy provision --input deployment.json --confirm provision pnpm microservices deploy migrate --input deployment.json --confirm migrate pnpm microservices deploy upload --input deployment.json --confirm upload pnpm microservices deploy status --input deployment.json pnpm microservices deploy cleanup --input deployment.json --plan ``` 生成的应用程序现在可用于本地测试。托管的预览命令可以准备部署记录、计划资源、报告状态和通过 API 暴露就绪情况/阻止程序。端到端实时托管预览仍然由托管 Worker/资产上传适配器和路由激活控制；`deploy upload-plan --input deployment.json` 报告当前的就绪情况/阻止程序。 对于 CI，请使用工作区 API 密钥并将 Cloudflare 凭证排除在客户流水线之外： ```bash MICROSERVICES_API_KEY=<workspace-api-key> pnpm microservices deploy preview --confirm deploy --ci --json --output deployment.json MICROSERVICES_API_KEY=<workspace-api-key> pnpm microservices deploy provision --input deployment.json --confirm provision --ci --json --output provision.json MICROSERVICES_API_KEY=<workspace-api-key> pnpm microservices deploy migrate --input deployment.json --confirm migrate --ci --json --output migrate.json MICROSERVICES_API_KEY=<workspace-api-key> pnpm microservices deploy upload-plan --input deployment.json --ci --json --output upload-plan.json MICROSERVICES_API_KEY=<workspace-api-key> pnpm microservices deploy cleanup --input deployment.json --confirm cleanup --ci --json --output cleanup.json ``` ## 仓库地图 该仓库包含核心 create-app、CLI、SDK、模块、模板、发布逻辑和治理文档。营销登陆站点和托管控制平面 API 在单独的仓库中维护。 ```text packages/ cli/ 本地开发者/代理 CLI create-microservices-app/ npm create 包 module-contract/ 静态模块/模板合约定义 sdk-internal/ CLI、测试和未来托管界面的共享 SDK workspace-tools/ 仓库本地验证和脚手架命令 modules/ gateway/ API 网关模块 auth/ 身份验证模块 customer/ 客户模块 booking/ 预订模块 audit-log/ 审计日志模块 email/ 电子邮件模块源 payment/ 支付模块源 templates/ booking-sveltekit/ 全功能预订模板（默认） saas-starter-sveltekit/ 多租户 B2B SaaS 启动器 dot-ai-os/ 代理原生操作员工作区 client-portal-sveltekit/ 客户门户（发票、文件） company-landing-astro/ 静态 Astro landing 页面 docs/ modules/ 模块文档和结构标准 templates/ 模板标准和规格 governance/ 提交、审查和生态系统规则 plans/ 策略、MVP 范围、架构和 GTM 注释 ``` ## 开发本仓库 需求： - Node.js 20+ - pnpm 10+ 安装并检查： ```bash pnpm install pnpm cli -- modules list --json pnpm cli -- docs booking --json pnpm discover -- --json pnpm spec:check -- all ``` 在 monorepo 内部运行模板： ```bash pnpm --filter @microservices-sh/template-booking-sveltekit microservices -- check --json pnpm --filter @microservices-sh/template-booking-sveltekit build:app pnpm --filter @microservices-sh/template-booking-sveltekit microservices -- local setup pnpm --filter @microservices-sh/template-booking-sveltekit microservices -- local dev pnpm --filter @microservices-sh/template-booking-sveltekit microservices -- local smoke ``` 本地测试 create 包： ```bash pnpm create:local -- studio-booking --template booking-sveltekit --dir /tmp --no-install --no-git pnpm test:create ``` 从脚手架创建新的目录项： ```bash pnpm scaffold:module -- inventory pnpm scaffold:template -- invoice-sveltekit --framework sveltekit --modules customer,booking pnpm spec:check -- all ``` 本地注册和发现命令被设计为只读的。`pnpm registry:build -- --json` 扫描模块和模板清单，并写入派生的目录到 `.generated/registry` 下。`pnpm discover -- --path <app>` 从 `microservices.lock.json` 和包依赖中报告已安装的模块，而不会改变源代码、密钥、资源或部署。 ## 现有项目迁移交接 CLI 可以为现有的应用程序准备一个代理 Cloudflare 迁移交接，而无需调用 AI 服务。它会编写一个版本化的检查清单和提示，验证外部代理的 `report.json`，然后生成下一个实现提示。 ```bash pnpm cli -- analyze /path/to/app --target cloudflare --agent # 请您的编码代理使用 .microservices/analysis/agent-prompt.md pnpm cli -- doctor --from-report /path/to/app/.microservices/analysis/report.json pnpm cli -- prompt next --from-report /path/to/app/.microservices/analysis/report.json --goal cloudflare-enable ``` 这被故意分阶段。对于具有 Supabase、Firebase、Postgres 或现有无服务器函数的应用程序，通常建议首先启用 Cloudflare 托管，同时保留当前后端，然后仅在报告有文件/行证据时进行有针对性的 Worker/R2/D1 迁移。 ## 代理和控制平面接口 本地 CLI 和 create 包使用相同的内部 SDK，适用于托管 MCP、本地 stdio MCP 和部署控制平面。这使得代理行为在不同访问路径下保持一致。 托管控制平面 API 在此核心仓库之外维护。它公开了 `/mcp` 工具合同和远程部署端点；此仓库保留共享合同、生成器、SDK 和生成的应用程序客户端命令。 代表性工具组： - 目录：`list_templates`、`inspect_template`、`list_modules`、`inspect_module`、`list_module_docs`、`get_module_doc` - 规划：`plan_add_module`、`check_updates`、`plan_module_upgrade`、`validate_config` - 生成和检查：`compose_app`、`generate_project`、`run_checks` - 部署：`deploy_dev`、`deploy_preview`、`deploy_production`、`provision_deployment`、`migrate_deployment`、`plan_deployment_upload`、`upload_deployment`、`cleanup_deployment`、`get_deployment_status`、`get_deployment_resources`、`get_logs` 使用仓库本地 CLI 进行直接 SDK 检查。部署命令需要配置的 API URL 和身份验证，因为它们进入托管控制平面。 ```bash pnpm cli -- templates list --json pnpm cli -- templates inspect booking-business --json pnpm cli -- modules inspect booking --json pnpm cli -- compose booking-business --json pnpm cli -- check booking-business --json pnpm cli -- generate booking-business --out /tmp/booking-business pnpm cli -- deploy production booking-business --plan --json ``` ## 发布 Create 包 create 包位于 [`packages/create-microservices-app`](./packages/create-microservices-app)。分发构建将生成器捆绑到 `dist/index.js` 中： ```bash pnpm --filter create-microservices-app build pnpm --filter create-microservices-app pack --dry-run pnpm --filter create-microservices-app smoke ``` 发布使用 `.github/workflows/npm-publish.yml` 中的手动工作流程。默认运行使用 `dry_run=true`。实际的 npm 发布需要： - 为此仓库和工作流程配置 npm Trusted Publisher。 - 标签推送，例如 `create-microservices-app@0.4.0`，或使用 `dry_run=false` 的手动工作流程运行。 `create-microservices-app` 包声明了 MIT 许可证。在将整个仓库描述为开源之前，请添加/验证根仓库许可证。 ## 贡献 开始： - [`CONTRIBUTING.md`](./CONTRIBUTING.md) - [`SECURITY.md`](./SECURITY.md) - [`docs/governance/module-submission-guide.md`](./docs/governance/module-submission-guide.md) - [`docs/governance/review-process.md`](./docs/governance/review-process.md) - [`docs/llms.txt`](./docs/llms.txt) 新的模块和模板应从第一天起就包含文档、模式、测试、清单元数据、生成的项目命令和升级计划支持。