feat: initialize unidesk platform

2026-05-04 11:09:35 +00:00
commit caa80ee5e7
56 changed files with 3273 additions and 0 deletions
@@ -0,0 +1,28 @@
+# UniDesk CLI Reference
+
+UniDesk 的统一 CLI 入口是根目录 `scripts/cli.ts`，运行方式固定为 `bun scripts/cli.ts <command>`。CLI 默认输出 JSON，所有成功和失败路径都必须向 stdout 写出结构化对象，避免无输出造成状态不可观测。
+
+## Command Model
+
+- `help` 输出命令索引，适合作为交互式入口。
+- `config show` 读取并校验根目录 `config.json`，不从环境变量、默认值或隐藏文件静默补配置。
+- `check` 执行配置校验、文件存在性检查、`scripts/` TypeScript 检查、`src/components/` TypeScript 检查和 Docker Compose 配置检查。
+- `server start` 创建异步 job，在后台执行 Docker 构建和启动；命令本身只负责返回 job id、日志路径和启动命令。
+- `server stop` 创建异步 job，在后台停止固定 Compose project 中的全部 UniDesk 服务。
+- `server status` 查询固定端口、Compose 容器、core/frontend 健康检查和访问 URL。
+- `server logs` 返回 `logs/` 文件日志和 Docker 容器日志的尾部，默认限制输出大小，避免日志爆炸。
+- `job list` 与 `job status` 查询 `.state/jobs/` 文件系统状态，是异步命令的可观测入口。
+- `debug health` 与 `debug dispatch` 走真实 HTTP、WebSocket、数据库和 provider 流程，只用于开发调试，不写入 `TEST.md` 的正式验收步骤。
+- `e2e run` 使用 publicHost 派生的公开 URL 验证 core API、PostgreSQL、provider self-connection 和 Playwright 前端页面，是交付前的自动化 E2E 门禁。
+
+## Async Job State
+
+长时操作采用 Fire-and-Forget 模式：CLI 创建 `.state/jobs/{jobId}.json`，后台进程执行真实命令，并将 stdout、stderr 分别写入 `.state/jobs/{jobId}.stdout.log` 与 `.state/jobs/{jobId}.stderr.log`。调用者通过 `bun scripts/cli.ts job status <jobId>` 查询进度和尾部输出。
+
+## Output Contract
+
+每条命令的最外层 JSON 包含 `ok`、`command` 和 `data` 或 `error`。失败时 CLI 设置非零退出码，但仍然输出 JSON 错误对象；错误对象应包含 `name`、`message` 和可用的 `stack`。
+
+## Debug Contract
+
+`debug` 子命令必须复用真实模块与真实端点，禁止维护平行实现。`debug dispatch` 会调用 core 的 `/api/dispatch`，core 再通过 WebSocket 将任务下发给 provider gateway，因此它可以验证核心调度闭环。