mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
41fdaba973a853051fa9ffcdd89daebcbc9c2501
pikasTech-unidesk/AGENTS.md
T
Codex 79166574e8 feat: integrate codex queue and pipeline oa flow 
- add Codex Queue microservice/frontend integration and related deployment docs
- document 100% Pipeline OA event-flow requirements and E2E gates
- harden Pipeline frontend Gantt/timeline E2E assertions and rendering
2026-05-07 18:11:43 +00:00

46 lines
7.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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|codex-queue>`：以 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 的交互会话或远端命令，并在远端 PATH 注入 `apply_patch` 与 `glob`；`apply-patch`、`py`、结构化 `find`、`glob` 和 `argv` 子命令用于避免远端补丁、Python stdin 执行与常用只读命令的嵌套转义问题，使用规则见 `docs/reference/cli.md` 和 `docs/reference/provider-gateway.md`。
- `bun scripts/cli.ts microservice list/status/health/proxy`：管理和验证挂载在主 server 或计算节点 Docker 中的业务 microservice，Codex Queue/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 [--only pattern[,pattern...]] [--skip pattern[,pattern...]]`：支持按 check/prefix/wildcard 选择性执行公网 frontend/provider ingress、内网 core/database、provider-gateway 自接入与 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 后端和 Codex Queue 后端，且只公开 frontend/provider ingress，服务拓扑见 `docs/reference/deployment.md`。
- `src/components/frontend`：前端源码固定使用 TypeScript + React，`app.tsx` 只做 shell/router，左侧主模块与顶部子标签统一编译为模块前缀路由：`/ops/<tab>/`、`/nodes/<tab>/`、`/tasks/<tab>/`、`/config/<tab>/`，只有微服务使用 `/app/<tab>/` 深链接，资源监控含曲线和进程资源排序表，Todo Note、FindJob、Pipeline、MET Nonlinear、Codex Queue 等业务页必须拆到独立 TSX 模块，界面规则见 `docs/reference/frontend.md`。
- `Pipeline OA event flow`：Pipeline 控制、事件取证和甘特图渲染必须最终 100% 由 OA 事件流驱动，交付态不得保留点对点控制、旧审核事件、旧 batch 推进、runner 私有 JSONL 或 frontend/CLI 直写状态，权威规则见 `docs/reference/pipeline-oa-event-flow.md`。
- `src/components/provider-gateway`：当前主 server `74.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 和验证规则。
- `docs/reference/pipeline-oa-event-flow.md`：Pipeline/OA 事件流、审核/无审核流转、单步调试、甘特图渲染和最终去残留规则。
- `reference`：兼容旧路径的符号链接，指向 `docs/reference/`。
Reference in New Issue View Git Blame Copy Permalink