开发并部署 Web 应用

在当前工作区中构建一个简单的全栈 Web 应用，以独立进程方式在本地运行，并提供一个外部人员可从本机以外访问的 URL。

若用户提及“轻应用”或“LiteApp”，则视作明确请求使用本能力。

运行规则

• 将生成的 Web 项目创建于 workspaces/web-apps/{userName}/{token} 路径下。
• {token} 视为仅由大写字母与数字组成的 8 字符随机标识符。
• 确保每个新生成的 {token} 在所有已生成应用中全局唯一。
• 若运行时上下文中可获取 userName，则直接使用；若无法从环境或用户请求中推断该值，则在脚手架生成前向用户询问。
• 除非用户显式覆盖输出路径规则，否则不得将应用脚手架置于仓库根目录。
• {token} 同时作为文件夹名与 URL 路径段使用。
• 每个 Web 应用须在独立的 Node.js 进程中运行。
• 使用一个共享的 LiteApp 主机（监听公网端口 33333），将 /{token}/... 的流量路由至对应的应用进程。
• 优先采用双包结构：client/ 存放 React 前端应用，server/ 存放 Express API 后端服务。
• 全栈优先使用 TypeScript。
• React 前端优先使用 Vite。
• SQLite 访问优先使用 better-sqlite3；除非工作区已采用其他 SQLite 库，则沿用既有方案。
• 最终 HTTP 服务应统一为单体服务：生产模式下，Express 应同时托管构建后的前端资源及 /api 接口端点。
• 若用户未指定具体产品构想，则默认构建一个简单待办事项（todo）或笔记（notes）应用，含一个 SQLite 支持的数据实体，并实现完整正向业务流程（happy path）。
• 若目标目录下已存在应用，则应在现有基础上扩展，而非无充分理由地覆盖用户已有可用代码。
• 修改任一已生成的 Web 应用前，须首先阅读其 .ai.md 文件。
• 前端 UI 设计须遵循 references/ui-style.md 中的指导原则；可借鉴 Huashu Design 网站示例中的视觉设计逻辑，但不得直接复用其原始素材或品牌内容。
• 应用必须支持挂载于子路径 /{token}/ 下运行，而不仅限于根路径 /。
• 所有 LiteApp 均须通过共享公网端口 33333 对外暴露。
• 为每个应用进程分配一个专用的内部端口，取值范围为闭区间 33334–39999；从 33334 开始顺序尝试，直至找到空闲端口为止。
• 向用户报告的最终外部 URL 格式为：:33333/{token}。
• 需维护机器可读与人类可读的记录，使当前用户与应用可被查询，无需人工扫描源码文件。
• 保持 ../platform_data/web-app-registry.json 相对于 .openclaw 根目录同步更新；每条记录须包含 name、token、file_path、port、created_at、modified_at 和 user_name 字段。
• 优先使用 scripts/ 目录中预置的 Node 脚本完成应用初始化、内部端口分配、共享主机启动、注册表维护、关闭操作及文档同步等任务，避免临时重写同类逻辑。
• 部署自动化须保持本地化与显式化：不得添加任何用于拉取远程代码、管理密钥、修改无关系统状态或尝试提权的脚本。
• 支持通过注册表驱动的恢复脚本实现重启恢复，但不得静默安装操作系统级启动钩子或计划任务。

工作流

1. 在执行任何变更前，先检查当前工作区状态。
2. 解析输出目录为 workspaces/web-apps/{userName}/{token}，如不存在则创建。
3. 使用 scripts/init-app.js 初始化应用文件夹及基础文档。
4. 判断是扩展目标目录中已存在的应用，还是新建脚手架。
5. 构建一个最小但功能完整的应用：
   • 具备简洁但可用 UI 的 React 前端
   • 基于 TypeScript 的 Express 后端
   • 含 Schema 初始化的 SQLite 数据库
   • 至少实现一个完整的 CRUD 流程
   • 提供健康检查（health）端点
6. 在项目根目录添加顶层脚本，便于安装、运行、构建、启动及通过共享公网端口重新运行应用。
7. 使用 scripts/scaffold-app.js 生成实际项目文件。
8. 使用 scripts/sync-docs.js 同步应用文档。
9. 优先使用 scripts/deploy-app.js 执行有序部署：该脚本依次完成依赖安装、构建、启动、文档同步及注册表更新，避免竞态条件。
10. 若需分步执行部署步骤，请严格按序运行：install-app.js → build-app.js → start-app.js → sync-docs.js → update-registry.js。
11. 使用 status-app.js 与 restart-app.js 进行生命周期状态检查与受控重启。
12. 使用 restore-apps.js 实现重启后恢复；使用 bootstrap-host.js 输出主机级启动机制应执行的命令。
13. 返回所需的最终应用摘要块，连同本地命令及任何重要注意事项。

实现默认配置

• 项目结构与包管理建议参考 references/stack.md。
• 从零开始构建新应用时，参考 references/scaffold.md 中的具体脚手架命令。
• 部署过程使用 scripts/ 目录下的脚本。
• 脚本接口契约参见 references/scripts.md 中的最小化定义。
• 自动加载兼容性规则参见 references/autoload.md。
• 前端样式设计参考 references/ui-style.md。
• 默认本地端口：
  • 前端开发服务器：5173
  • 后端开发服务器：3000 或 3001
  • 共享公网 LiteApp 主机：33333
  • 生产环境应用服务器内部端口：从 33334 至 39999 区间内首个空闲端口
• 开发阶段使用 Vite 的 /api 代理功能。
• 生产阶段，Express 应在基础路径下托管 client/dist，API 路由则位于 /{token}/api 下。
• SQLite 数据库存储于项目本地路径，例如 server/data/app.db。

平台 URL 规则

• 不得止步于文件脚手架生成；任务仅在应用确实可从生成目录运行、且已产出最终 URL 或确认具体阻塞项后才算完成。
• 优先暴露生产构建产物，而非 Vite 开发服务器，确保最终 URL 反映真实集成效果。
• 面向用户的最终访问 URL 按如下格式计算：:33333/{token}。
• 外部端口固定为 33333。
• 内部应用端口通过从 33334 向上扫描，在 39999 内选取首个空闲端口。
• 确保前端资源 URL、路由行为及 API 请求在挂载于该子路径下时仍能正常工作。
• 每个应用须严格隔离于各自进程与目录中；禁止通过单一长时运行服务复用多个应用。
• 若需开发阶段预览 URL，仅作为辅助手段；首要交付物为最终应用 URL 及其已记录的元数据。

可查询性规则

• 应易于回答“存在哪些用户？”和“存在哪些应用？”等问题，且无需启动应用代码即可完成。
• 使用 scripts/update-registry.js 维护根级注册表及按用户划分的索引。
• 每个应用目录中均须维护一份机器可读的应用元数据文件与一份人类可读的应用说明文件，均由 scripts/init-app.js 与 scripts/sync-docs.js 管理。
• 每个应用目录中须保留 .ai.md，用于记录用户需求与 AI 设计说明。
• 生成的应用目录中不得存放 config.json。
• 每次修改应用时，须在同一轮次中同步更新对应的元数据与说明文件。
• 当用户请求查看现有应用时，应优先从注册表文件中响应；仅当细节缺失或过期时，才进一步检查应用目录。

交付要求

每次响应必须以如下内容收尾：

• 一个固定、显式的最终应用信息块，且以下四个字段必须全部存在且非空： Id: {token} Name: {appName} Description: {appSummary} Url template: :33333/{token}

• 上述四个字段缺一不可，即使同时提供了其他交付细节

• 字段名称须严格与上方书写一致

• 若包含额外章节，此四字段块须置于响应末尾

• 生成的项目路径

• 应用摘要

• 创建或更新的主要文件或目录

• 安装与运行命令

• 最终 URL，格式为 :33333/{token}

• 分配的公网端口 33333 及内部应用端口

• 被创建或更新的注册表与应用文档文件

• 任何限制说明，例如该 URL 依赖本地进程持续运行

示例请求

• “帮我构建一个简单的任务追踪器，并提供一个公开 URL。”
• “创建一个用于记笔记的小型 React + Express + SQLite 应用并运行它。”
• “在此文件夹中搭建一个演示用 Web 应用，启动它，并分享一个外部链接。”
• “为内部数据录入创建一个 轻应用。”
• “为此工作流构建一个 LiteApp 并在本地运行。”