star-dsh-desktop: Instructions file for Codex

AGENTS.md — StarHub 协作指引

写给 AI Agent 和人类贡献者:读完这份文件就能上手改这个仓库。架构级变更请同步更新 docs/ 与本文件。

项目是什么

StarHub 是 DevOps 桌面应用,单一窗口整合:数据库客户端(MySQL / PostgreSQL / SQLite / Redis / ClickHouse / SQL Server / Elasticsearch)、SSH 终端、SFTP、Docker 面板、Android 真机、AI 助手。

StarHub 不是桌面项目,是上游 DeepSeek Harness Electron 壳的外部插件集:桌面壳、品牌/签名/更新栈都是上游的,StarHub 交付「插件 + 两个 sidecar 子进程 + 静态资产」三件套。去 Tauri 化(M1–M4)已把原来的 Tauri 壳整体退役,详见 docs/去Tauri化-M1..M4-*.md 四份清单。

架构一句话

三层进程:上游 Electron 壳(零改动) 跑 dsh Host(Node)进程 → Host 里的 starhub-bridge 插件 spawn 两个 sidecar:Rust sidecar(sidecar-rust/,ssh/sftp/android/browser 契约层 + 直播帧枢纽) 与 Go Sidecar(sidecar/,数据库/中间件适配),均经 stdio 换行分帧 JSON-RPC 通话 → 前端是 DSH 主壳 + StarHub React 工作台(vendor/deepseek-harness/,上游 deepseek-ai/deepseek-harness 的 vendored 副本,随仓库直接版本化)。

目录结构

starhub/
├── sidecar-rust/           # Rust sidecar(M1 起域逻辑的新家)
│   └── crates/
│       ├── starhub-sidecar      # 二进制 + stdio JSON-RPC 方法面(模型面 + ui.* 面)
│       ├── starhub-live         # 直播/接管帧枢纽(M3):本地 WS + Android 帧源
│       ├── starhub-contract     # 领域事件 schema + 模型可读能力文本
│       └── starhub-domain-{ssh,db,android,browser}
│
├── sidecar/                 # Go 1.25 Sidecar — 数据库/中间件代理
│   ├── main.go               # stdio JSON-RPC server 入口
│   ├── adapters/             # mysql / postgres / sqlite / redis / clickhouse / mssql /
│   │                         # elasticsearch / broker(Kafka/NSQ)/ docker(+compose,+ssh)/ csv / backup
│   ├── pool/  rpc/           # 连接池 / JSON-RPC 协议
│   └── bin/                  # 构建输出 starhub-sidecar[.exe]
│
├── vendor/deepseek-harness/ # DSH 主壳与 StarHub React 工作台(上游 deepseek-ai/deepseek-harness
│                            # 的 vendored 副本,随仓库直接版本化;上游 commit 记录于
│                            # vendor/deepseek-harness/UPSTREAM_COMMIT.txt)
│   ├── apps/
│   │   ├── starhub-window/   # StarHub 资产工作台构建入口(产物 dist-starhub-react/)
│   │   ├── web/  cli/        # DSH 自身应用
│   │   └── desktop/ desktop-host/  # 上游 DSH 自家 Electron 桌面壳(发布链用它打包)
│   ├── examples/
│   │   ├── starhub-web/      # web 组合的 profile 模板(旧 Tauri 壳用)
│   │   └── starhub-desktop/  # desktop 组合的 profile 模板(provisioning 用)
│   └── packages/starhub/     # 10 个内置插件:approval-bridge / bridge / client-nav /
│                             # domain-events / host-static / live-context /
│                             # session-registry / ssh-assistant / tool-context /
│                             # tools
│
├── scripts/
│   ├── provision-dsh.mjs     # M4:把 StarHub 组合装进 dsh profile
│   ├── smoke-dsh-desktop.mjs # M4:provisioning + 宿主进程冒烟
│   ├── build-plugin-bundle.mjs  # 纯插件形态:拼出自包含 bundle(→ dist-plugin/,--pack 出 .tgz)
│   ├── smoke-plugin-bundle.mjs  # 纯插件形态:pnpm 安装 + 宿主冒烟(五条断言)
│   ├── build-sidecar.*       # Go sidecar 构建
│   ├── build-window.mjs      # React 工作台构建
│   ├── bump-version.mjs      # 版本号同步
│   ├── cargo-sidecar.bat     # Windows 上跑 sidecar-rust 的 cargo(MSVC + 工具链)
│   └── cargo-sidecar.mjs     # 上面的跨平台包装:Windows 转 .bat,其它平台直调 cargo
│
├── dsh-runtime/             # 打包好的 dsh 运行时(gitignore;package:dsh-runtime 产出)
├── dist-starhub-react/      # React 工作台产物(gitignore)
├── dist-plugin/             # 纯插件 bundle 组装产物(gitignore;plugin:bundle 产出,--pack 另出 .tgz)
├── docs/                    # 技术方案 / 设计系统 / 踩坑记录 / 已知坑索引 / 去Tauri化 M1-M4 清单
├── test-sftp/               # SSH/SFTP stub + 桥兼容验收脚本
└── tests/                   # node --test 单测(utils、AI 上下文/滚动/记忆、SSH prompt/cwd/后台任务、provisioning)