# UniDesk Agent Index

UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文件是项目顶级索引，也承担 `scripts/cli.ts` 的 CLI 使用说明入口。

## CLI

- `bun scripts/cli.ts help`：输出所有可用命令的 JSON 索引，详细规范见 `docs/reference/cli.md`。
- `bun scripts/cli.ts --main-server-ip <ip> <command>`：默认通过公网 frontend 登录态远程执行调试与节点自测命令，不要求主 server SSH key，详细规范见 `docs/reference/cli.md`。
- `bun scripts/cli.ts config show`：校验并展示根目录 `config.json`，配置来源规则见 `docs/reference/config.md`。
- `bun scripts/cli.ts check`：运行配置、TypeScript、文件存在性和 Docker Compose 配置检查，测试入口见 `TEST.md`。
- `bun scripts/cli.ts server start`：以异步 job 启动 database、backend-core、frontend、provider-gateway，部署规则见 `docs/reference/deployment.md`。
- `bun scripts/cli.ts server status`：查询固定端口、容器状态、健康检查和访问 URL，判定标准见 `docs/reference/deployment.md`。
- `bun scripts/cli.ts server logs`：分页返回文件日志与 Docker 日志尾部，日志规则见 `docs/reference/observability.md`。
- `bun scripts/cli.ts server rebuild <backend-core|frontend|provider-gateway>`：以 build-first、label-scoped replace 的异步 job 重建单个服务，避免 Docker Compose v1 recreate 问题，规则见 `docs/reference/deployment.md`。
- `bun scripts/cli.ts ssh <providerId> [ssh-like args...]`：通过 provider-gateway 的 Host SSH / WSL SSH 维护桥打开近似原生 ssh 的交互会话或远端命令，使用规则见 `docs/reference/cli.md` 和 `docs/reference/provider-gateway.md`。
- `bun scripts/cli.ts server stop`：以异步 job 停止固定 Compose 项目中的全部 UniDesk 服务，停止后用 `server status` 复核。
- `bun scripts/cli.ts job list` / `bun scripts/cli.ts job status latest`：查询 `.state/jobs/` 中的异步任务状态，job 机制见 `docs/reference/cli.md`。
- `bun scripts/cli.ts debug health` / `bun scripts/cli.ts debug dispatch` / `bun scripts/cli.ts debug task`：通过 Docker 内网 core、真实 HTTP、WebSocket、系统指标、Docker 状态和 Host SSH 维护桥流程调试健康检查、任务下发与任务结果，调试规则见 `docs/reference/cli.md`。
- `bun scripts/cli.ts e2e run`：验证公网 frontend/provider ingress、内网 core/database、provider-gateway 自接入、资源指标曲线、Docker 状态快照、provider.upgrade 预检和 Playwright 登录页面，验收规则见 `docs/reference/e2e.md`。

## Runtime

- `bun`：TypeScript 运行时固定使用 Bun，组件入口和 CLI 都直接运行 `.ts` 文件，约束见 `docs/reference/config.md`。
- `docker-compose.yml`：主 server 统一编排 core、frontend、database 和本机 provider gateway，且只公开 frontend/provider ingress，服务拓扑见 `docs/reference/deployment.md`。
- `src/components/frontend`：前端源码固定使用 TypeScript + React，采用高信息密度工业控制台设计，资源节点含资源监控、Docker 状态、网关版本、SSH/远程更新可用性和自动更新记录，界面规则见 `docs/reference/frontend.md`。
- `src/components/provider-gateway`：当前主 server `74.48.78.17` 也作为 provider gateway 接入 UniDesk，外部节点通过 `ws://74.48.78.17:18082/ws/provider` 接入，必须同时部署 always-enabled 远程升级和 Host SSH / WSL SSH 透传并完成自测，部署与 Playwright 公网前端验证方法见 `docs/reference/provider-gateway.md`。
- `docs/reference/e2e.md`：交付前必须执行的自测门禁、Playwright 登录与 JSON 展示断言、数据库命名卷持久化要求。

## Architecture Docs

- `docs/reference/arch.md`：UniDesk 分布式工作平台的长期架构约束。
- `docs/reference/repo-tree.md`：仓库结构目标与组件边界。
- `reference`：兼容旧路径的符号链接，指向 `docs/reference/`。