Codex
6.1 KiB
6.1 KiB
UniDesk Agent Index
UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文件是项目顶级索引，也承担 scripts/cli.ts 的 CLI 使用说明入口。
Critical Provider Gateway Upgrade Rule
src/components/provider-gateway有任何代码或行为变更时，必须在同一变更集中递增src/components/provider-gateway/package.json的版本号，并在升级后通过 frontend 或debug health确认目标节点上报新版本；权威规则见docs/reference/provider-gateway.md。provider.upgrade预检、执行升级和自动更新记录必须显式显示指定 Provider 的 gateway 版本号，不能只把版本放进原始 JSON；前端和 E2E 要求见docs/reference/provider-gateway.md与TEST.md。- 计算节点
provider-gateway容器的重建/升级必须走带 sleep-and-validate 回滚保护的provider.upgrade mode=schedule远程升级路径或前端等价调度；禁止通过bun scripts/cli.ts ssh <providerId>同步执行docker compose up --build provider-gateway这类自重建命令，权威规则见docs/reference/provider-gateway.md。 - Host SSH / WSL SSH 透传只能用于节点诊断、前置条件修复和升级后验证，不能作为计算节点
provider-gateway自身的重建/升级通道；部署验收必须同时证明远程升级和 SSH 透传可用，测试门禁见TEST.md。
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 和主 server microservice，部署规则见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|todo-note>：以 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 microservice list/status/health/proxy：管理和验证挂载在主 server 或计算节点 Docker 中的业务 microservice，Todo Note on main-server 与 FindJob/Pipeline/MET Nonlinear on D601 的规则见docs/reference/microservices.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 自接入、Todo Note 迁移数据、资源指标曲线、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 和 Todo Note 后端，且只公开 frontend/provider ingress，服务拓扑见docs/reference/deployment.md。src/components/frontend：前端源码固定使用 TypeScript + React，app.tsx只做 shell/router，资源监控含曲线和进程资源排序表，Todo Note、FindJob、Pipeline、MET Nonlinear 等业务页必须拆到独立 TSX 模块，并采用高信息密度工业控制台设计，界面规则见docs/reference/frontend.md。src/components/provider-gateway：当前主 server74.48.78.17也作为 provider gateway 接入 UniDesk，外部节点通过ws://74.48.78.17:18082/ws/provider接入，必须以restart: always部署 always-enabled 远程升级、sleep-and-validate 回滚保护和 Host SSH / WSL SSH 透传并完成自测，部署与 Playwright 公网前端验证方法见docs/reference/provider-gateway.md。microservices：主 server 本地开发边界固定为只开发 UniDesk frontend；非 UniDesk 核心业务后端、Dockerfile、GPU/训练调试必须在目标计算节点通过 SSH 透传完成，Todo Note 这类明确写入主 server 的例外需单独登记，规则见docs/reference/microservices.md。docs/reference/e2e.md：交付前必须执行的自测门禁、Playwright 登录、资源监控进程排序、JSON 展示断言和数据库命名卷持久化要求。
Architecture Docs
docs/reference/arch.md：UniDesk 分布式工作平台的长期架构约束。docs/reference/repo-tree.md：仓库结构目标与组件边界。docs/reference/microservices.md：计算节点 microservice 的配置、代理、安全边界、Todo Note on main-server、FindJob/Pipeline/MET Nonlinear on D601 和验证规则。reference：兼容旧路径的符号链接，指向docs/reference/。