pikasTech-unidesk/AGENTS.md

UniDesk Agent Index

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

Critical Git / Multi-Repo Sync Rule

• UniDesk 同时存在 main server、D601 ~/cq-deploy 和其他 provider worktree 等多个开发/部署实例；Git remote 是长期 source of truth，本地部署实例只能视为运行副本或缓存。
• 任何需要保留的代码、文档或配置变更，在完成必要自测/部署验证后必须立刻按 git-spec 提交并 push 到 remote；禁止让未推送的本地修改成为部署真相或后续任务依赖。
• 提交前必须用 git status 和 git diff 区分并只提交当前任务相关文件，保留并避开并行任务产生的无关修改；长期规则见 docs/reference/arch.md。

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 登录态远程执行调试、用户服务（底层命令名 microservice）、codex task <taskId> 与节点自测命令，不要求主 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 用户服务，部署规则见 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|project-manager|baidu-netdisk|oa-event-flow>：以 build-first、Compose lock、no-deps force-recreate 和 post-up validation 的异步 job 重建主 server Compose 内单个服务；Code Queue 部署在 D601，规则见 docs/reference/deployment.md。
• bun scripts/cli.ts provider attach <providerId> [--master-server URL] [--up] [--force]：在新增计算节点上生成两项配置的 provider-gateway 挂载包；默认只需要主 server URL（默认 http://74.48.78.17/）和唯一 Provider ID，生成的 Compose 固定 Docker socket、pid: "host"、restart: always、只读 /workspace、SSH 维护私钥挂载和 loopback egress proxy 端口，规则见 docs/reference/provider-gateway.md。
• bun scripts/cli.ts ssh <providerId> [ssh-like args...]：通过 provider-gateway 的 Host SSH / WSL SSH 维护桥打开近似原生 ssh 的交互会话或远端命令，并在远端 PATH 注入 apply_patch、glob 与 skill-discover；apply-patch、py、skills、结构化 find、glob 和 argv 子命令用于避免远端补丁、Python stdin、skill 发现与常用只读命令的嵌套转义问题，使用规则见 docs/reference/cli.md 和 docs/reference/provider-gateway.md。
• bun scripts/cli.ts microservice list/status/health/proxy：管理和验证挂载在主 server、计算节点 Docker 或 v3s 控制面上的用户服务，OA Event Flow/Todo Note/Baidu Netdisk on main-server、V3S Control/Code Queue/FindJob/Pipeline/MET Nonlinear on D601 的规则见 docs/reference/microservices.md。
• bun scripts/cli.ts codex task <taskId>：按 Code Queue 任务 ID 查询初始 prompt、最后 assistant message、工具调用摘要、attempt/judge/error 和耗时，便于新任务引用历史 session。
• bun scripts/cli.ts codex judge <taskId> --attempt <n> [--dry-run]：按指定 task/attempt 用与队列 worker 相同的上下文构建和 MiniMax judge 调用路径单步复现完成判定；--dry-run 只输出 prompt/payload 诊断。
• 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 后端、Baidu Netdisk 后端和 OA Event Flow 后端；Code Queue 由 D601 v3s/k8s 控制面代管，并经 v3sctl-adapter 的 Kubernetes API service proxy 单一路径接入，服务拓扑见 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、Baidu Netdisk、Code Queue、OA Event Flow、V3S Control 等业务页必须拆到独立 TSX 模块，界面规则见 docs/reference/frontend.md。
• backend-core / frontend performance：backend-core 暴露 /api/performance，frontend 暴露同源 /api/frontend-performance 并在 /ops/performance/ 汇总组件请求、失败请求、内部操作和慢操作，规则见 docs/reference/observability.md。backend-core 源码已拆分为 15 个模块，结构见 docs/reference/repo-tree.md。
• Unified OA event flow：oa-event-flow 是独立主 server 用户服务，提供事件表、按 tag 订阅和 Trace/STEP 统计中心，Code Queue 与 Pipeline 都必须接入统一事件流；共享契约见 docs/reference/oa-event-flow.md，Pipeline 专有控制流规则见 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：用户服务配置命名仍保留 microservices；用户服务指挂载在 UniDesk 核心服务上的用户业务能力，支持 unidesk-direct 与 v3sctl-managed 两种部署模式；v3s 代管必须使用标准 k3s/k8s 对象和 Kubernetes API service proxy，禁止业务容器直连、NodePort 和隐藏 fallback；缺少这些服务时核心仍可运行。主 server 本地开发边界固定为只开发 UniDesk frontend；非 UniDesk 核心业务后端、Dockerfile、GPU/训练调试必须在目标计算节点通过 SSH 透传或 v3s 控制面完成，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/observability.md：服务日志、任务活性、通用性能指标 API 和性能面板的可观测性规则。
• docs/reference/microservices.md：用户服务（兼容命名 microservice）的配置、代理、安全边界、unidesk-direct/v3sctl-managed 部署模式、Todo Note/Baidu Netdisk on main-server、V3S Control/Code Queue/FindJob/Pipeline/MET Nonlinear on D601 和验证规则。
• docs/reference/windows-passthrough.md：WSL provider 通过 SSH 透传调用 Windows cmd/PowerShell、Keil、COM 串口和 Windows 侧 skill 的长期规则。
• docs/reference/constar-d601.md：D601 上 ConStart/constar 固件工作区的 UniDesk SSH 入口、WSL skill wrapper、Keil 编译下载和串口/JSON-RPC 验证简要引导。
• docs/reference/oa-event-flow.md：统一 OA 事件流微服务、事件表、tag 订阅、Trace/STEP 统计中心和前端可见性规则。
• docs/reference/pipeline-oa-event-flow.md：Pipeline/OA 事件流、审核/无审核流转、单步调试、甘特图渲染和最终去残留规则。
• docs/reference/pipeline-model-proxy.md：Pipeline v2 model proxy 链路架构、D601 宿主 proxy 服务部署、harness token 注入规则和 smoke test 验证流程。
• reference：兼容旧路径的符号链接，指向 docs/reference/。