From c7a73e3715fdd6da58f2d8caf6dadde788245cd9 Mon Sep 17 00:00:00 2001 From: yinjianm Date: Wed, 25 Mar 2026 03:20:36 +0800 Subject: [PATCH] =?UTF-8?q?=E2=9C=85=E3=80=90HelloAGENTS=E3=80=91-=20~init?= =?UTF-8?q?=EF=BC=9A=E5=AE=8C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 已完成当前仓库知识库初始化，已创建 .helloagents/ 目录骨架和首批文档，覆盖根工作区、前端、后端、远程桌面网关四个模块。 已生成入口与上下文文档：INDEX.md、context.md、CHANGELOG.md 已生成模块文档：workspace-root.md、frontend.md、backend.md、remote-gateway.md 已创建空目录：plan/、user/ 验收结果：核心文件存在且非空，目录结构完整，未残留模板级占位骨架 未执行项：configure_codex.py 因当前环境不可用 Python 解释器而跳过，这不影响本次知识库初始化 提示：当前 .gitignore 还没有 .helloagents/ 条目；按 ~init 规则，我只提示，不自动修改 --- .helloagents/CHANGELOG.md | 5 ++ .helloagents/INDEX.md | 54 +++++++++++++ .helloagents/archive/_index.md | 23 ++++++ .helloagents/context.md | 102 +++++++++++++++++++++++++ .helloagents/modules/_index.md | 29 +++++++ .helloagents/modules/backend.md | 47 ++++++++++++ .helloagents/modules/frontend.md | 47 ++++++++++++ .helloagents/modules/remote-gateway.md | 47 ++++++++++++ .helloagents/modules/workspace-root.md | 42 ++++++++++ 9 files changed, 396 insertions(+) create mode 100644 .helloagents/CHANGELOG.md create mode 100644 .helloagents/INDEX.md create mode 100644 .helloagents/archive/_index.md create mode 100644 .helloagents/context.md create mode 100644 .helloagents/modules/_index.md create mode 100644 .helloagents/modules/backend.md create mode 100644 .helloagents/modules/frontend.md create mode 100644 .helloagents/modules/remote-gateway.md create mode 100644 .helloagents/modules/workspace-root.md diff --git a/.helloagents/CHANGELOG.md b/.helloagents/CHANGELOG.md new file mode 100644 index 0000000..e6bbb9e --- /dev/null +++ b/.helloagents/CHANGELOG.md @@ -0,0 +1,5 @@ +# 变更日志 + +## [Unreleased] + +- 2026-03-25：初始化 `.helloagents/` 知识库骨架与首批模块文档，不代表源码功能变更。 diff --git a/.helloagents/INDEX.md b/.helloagents/INDEX.md new file mode 100644 index 0000000..7f5cbc2 --- /dev/null +++ b/.helloagents/INDEX.md @@ -0,0 +1,54 @@ +# Nexus Terminal 知识库 + +> 本文件是知识库的入口点 + +## 快速导航 + +| 需要了解 | 读取文件 | +|---------|---------| +| 项目概况、技术栈、开发约定 | [context.md](context.md) | +| 模块索引 | [modules/_index.md](modules/_index.md) | +| 根工作区与部署编排 | [modules/workspace-root.md](modules/workspace-root.md) | +| Web 前端 | [modules/frontend.md](modules/frontend.md) | +| Node.js 后端 | [modules/backend.md](modules/backend.md) | +| 远程桌面网关 | [modules/remote-gateway.md](modules/remote-gateway.md) | +| 项目变更历史 | [CHANGELOG.md](CHANGELOG.md) | +| 历史方案索引 | [archive/_index.md](archive/_index.md) | +| 当前待执行的方案 | [plan/](plan/) | + +## 模块关键词索引 + +> AI 读取此表即可判断哪些模块与当前需求相关，按需深读。 + +| 模块 | 关键词 | 摘要 | +|------|--------|------| +| workspace-root | npm workspaces, docker-compose, patch-package, 部署编排 | Monorepo 根目录，负责依赖管理、镜像编排和共享配置。 | +| frontend | Vue 3, Vite, Pinia, xterm, Monaco, PWA | 提供 Web 终端工作区、设置页和连接管理等交互界面。 | +| backend | Express, WebSocket, SQLite, SSH, SFTP, 认证 | 提供 `/api/v1/*` REST 接口、WebSocket 会话和数据持久化。 | +| remote-gateway | Guacamole, RDP, VNC, token, guacd | 为远程桌面连接生成加密令牌并桥接到 `guacd`。 | + +## 知识库状态 + +```yaml +kb_version: 2.3.7 +最后更新: 2026-03-25 03:17 +模块数量: 4 +待执行方案: 0 +``` + +## 读取指引 + +```yaml +启动任务: + 1. 读取本文件获取导航 + 2. 读取 context.md 获取项目上下文 + 3. 检查 plan/ 是否有进行中方案包 + +任务相关: + - 涉及依赖、构建、部署: 读取 modules/workspace-root.md + - 涉及页面、路由、Pinia 状态: 读取 modules/frontend.md + - 涉及 API、认证、数据库、WebSocket: 读取 modules/backend.md + - 涉及 RDP/VNC、guacd、远程桌面 token: 读取 modules/remote-gateway.md + - 需要历史决策: 搜索 CHANGELOG.md → 读取对应 archive/{YYYY-MM}/{方案包}/proposal.md + - 继续之前任务: 读取 plan/{方案包}/* +``` diff --git a/.helloagents/archive/_index.md b/.helloagents/archive/_index.md new file mode 100644 index 0000000..78f22fb --- /dev/null +++ b/.helloagents/archive/_index.md @@ -0,0 +1,23 @@ +# 方案归档索引 + +> 通过此文件快速查找历史方案 +> 历史年份: 暂无 + +## 快速索引（当前年份） + +| 时间戳 | 名称 | 类型 | 涉及模块 | 决策 | 结果 | +|--------|------|------|---------|------|------| +| 暂无 | - | - | - | - | - | + +## 按月归档 + +### 2026-03 +- 暂无已归档方案 + +## 结果状态说明 +- ✅ 完成 +- ⚠️ 部分完成 +- ❌ 失败/中止 +- ⏸ 未执行 +- 🔄 已回滚 +- 📄 概述 diff --git a/.helloagents/context.md b/.helloagents/context.md new file mode 100644 index 0000000..c939e9c --- /dev/null +++ b/.helloagents/context.md @@ -0,0 +1,102 @@ +# 项目上下文 + +## 1. 基本信息 + +```yaml +名称: Nexus Terminal +描述: 基于 npm workspaces 的远程连接终端平台，提供 Web SSH、SFTP、RDP、VNC 与桌面端相关能力。 +类型: Web应用 +状态: 维护中 +``` + +## 2. 技术上下文 + +```yaml +语言: TypeScript, Vue, Node.js +框架: Vue 3, Vite, Express 5 +包管理器: npm workspaces +构建工具: Vite（frontend）, TypeScript 编译（backend/remote-gateway）, Docker Compose（部署） +``` + +### 主要依赖 +| 依赖 | 版本 | 用途 | +|------|------|------| +| vue | ^3.3.0 | 前端应用框架 | +| vite | >=5.4.19 | 前端开发与构建 | +| pinia | ^3.0.2 | 前端状态管理 | +| element-plus | ^2.9.11 | 前端组件库 | +| xterm | ^5.3.0 | Web 终端渲染 | +| monaco-editor | ^0.52.2 | 在线文件编辑器 | +| express | ^5.1.0 | 后端 REST 服务 | +| express-session | ^1.18.1 | 登录会话管理 | +| sqlite3 | ^5.1.7 | 本地数据持久化 | +| ssh2 | ^1.16.0 | SSH/SFTP 连接能力 | +| guacamole-lite | ^0.7.3 | RDP/VNC 网关封装 | +| ws | ^8.18.1 | WebSocket 通信 | + +## 3. 项目概述 + +### 核心功能 +- 统一管理 SSH、SFTP、RDP、VNC 远程连接。 +- 提供基于 Vue 3 的工作区、布局配置、主题定制和命令输入体验。 +- 提供认证、2FA、Passkey、Captcha、IP 白名单/黑名单、通知和审计能力。 +- 支持远程文件管理、在线编辑、快速命令、命令历史和 SSH 挂起会话。 +- 使用独立 `remote-gateway` 服务为远程桌面连接生成加密令牌并对接 `guacd`。 + +### 项目边界 +```yaml +范围内: + - Web 前端、Node.js 后端、远程桌面网关三部分代码 + - Docker Compose 部署编排和运行时环境变量 + - 基于 SQLite/data 目录的本地持久化 +范围外: + - 自动化数据备份能力 + - 仓库内未出现的桌面端打包代码 + - 完整自动化测试体系（当前仓库未建立） +``` + +## 4. 开发约定 + +### 代码规范 +```yaml +命名风格: TypeScript/JavaScript 代码以 camelCase 为主；Vue 组件使用 PascalCase；目录多为 kebab-case +文件命名: 后端常见 *.controller.ts / *.service.ts / *.repository.ts；前端 composable 使用 use*.ts；Pinia 使用 *.store.ts +目录组织: 根目录以 packages/* 划分应用；frontend 按 views/components/composables/stores 划分；backend 按业务域拆分子目录 +``` + +### 错误处理 +```yaml +错误码格式: 后端与 remote-gateway 主要返回 HTTP 状态码 + JSON error 字段；前端初始化失败时仍尝试挂载应用 +日志级别: 以 console.log / console.warn / console.error 为主，关键启动失败直接 process.exit(1) +``` + +### 测试要求 +```yaml +测试框架: 未配置统一测试框架 +覆盖率要求: 未声明 +测试文件位置: 当前仓库未建立系统化测试目录，变更后以 package 级 build 和手工冒烟验证为主 +``` + +### Git规范 +```yaml +分支策略: 仓库内未声明 +提交格式: 仓库内未声明 +``` + +## 5. 当前约束（源自历史决策） + +> 这些是当前生效的技术约束，详细决策过程见对应方案包 + +| 约束 | 原因 | 决策来源 | +|------|------|---------| +| 暂无已归档方案包约束 | 知识库于 2026-03-25 首次初始化，后续决策应沉淀到 plan/archive | N/A | + +## 6. 已知技术债务（可选） + +> 主动识别的需要未来处理的技术问题 + +| 债务描述 | 优先级 | 来源 | 建议处理时机 | +|---------|--------|------|-------------| +| 根仓与子包均缺少成体系自动化测试，`test` 脚本未形成有效校验 | P1 | 仓库现状 | 涉及核心连接链路、认证或文件操作改造前优先补齐 | +| `packages/backend/src/index.ts` 同时承担环境初始化、数据库启动、路由装配与服务启动，入口职责偏重 | P2 | 代码结构扫描 | 后端进入中型重构或新增启动流程时拆分 | +| `packages/remote-gateway/src/server.ts` 以单文件承载配置、HTTP API、Guacamole 服务器与优雅退出逻辑 | P2 | 代码结构扫描 | 远程桌面能力继续扩展前拆出配置层和控制器层 | diff --git a/.helloagents/modules/_index.md b/.helloagents/modules/_index.md new file mode 100644 index 0000000..5dc19dc --- /dev/null +++ b/.helloagents/modules/_index.md @@ -0,0 +1,29 @@ +# 模块索引 + +> 通过此文件快速定位模块文档 + +## 模块清单 + +| 模块 | 职责 | 状态 | 文档 | +|------|------|------|------| +| workspace-root | 管理 monorepo 工作区、共享依赖、补丁与部署编排 | ✅ | [workspace-root.md](./workspace-root.md) | +| frontend | 提供终端工作区、设置页和连接管理等 Web 界面 | ✅ | [frontend.md](./frontend.md) | +| backend | 提供认证、连接管理、SFTP、通知与 WebSocket 服务 | ✅ | [backend.md](./backend.md) | +| remote-gateway | 生成远程桌面令牌并桥接 `guacd` | ✅ | [remote-gateway.md](./remote-gateway.md) | + +## 模块依赖关系 + +```text +workspace-root → frontend +workspace-root → backend +workspace-root → remote-gateway +frontend → backend +frontend → remote-gateway +remote-gateway → guacd +backend → data(volume) +``` + +## 状态说明 +- ✅ 稳定 +- 🚧 开发中 +- 📝 规划中 diff --git a/.helloagents/modules/backend.md b/.helloagents/modules/backend.md new file mode 100644 index 0000000..913ac6f --- /dev/null +++ b/.helloagents/modules/backend.md @@ -0,0 +1,47 @@ +# backend + +## 职责 + +`packages/backend` 是主后端服务，基于 Express 5、SQLite 和 WebSocket 提供认证、连接管理、SFTP、SSH 挂起、通知、审计、快速命令、主题与外观设置等能力，并负责初始化数据库和共享会话。 + +## 接口定义（可选） + +> 模块对外暴露的公共 API 和数据结构 + +### 公共 API +| 函数/方法 | 参数 | 返回值 | 说明 | +|----------|------|--------|------| +| `GET /api/v1/status` | 无 | `{ status: string }` | 后端健康检查接口。 | +| `/api/v1/auth` 等 REST 路由组 | HTTP 请求体与路径参数 | JSON | 提供认证、连接、SFTP、设置、通知、审计等业务接口。 | +| `initializeWebSocket(server, sessionMiddleware)` | HTTP server, session middleware | WebSocket 服务实例 | 在现有 HTTP 服务上挂接 SSH/SFTP/RDP/Docker 等实时会话。 | + +### 数据结构 +| 字段 | 类型 | 说明 | +|------|------|------| +| `session.userId` | `number` | 登录用户 ID，存入 `express-session`。 | +| `session.username` | `string` | 当前登录用户名。 | +| `data/.env` / 根 `.env` | 环境变量文件 | 保存部署模式、加密密钥、会话密钥等运行配置。 | + +## 行为规范 + +### 启动初始化 +**条件**: 执行 `packages/backend` 的 `dev`、`build && start` 或容器启动流程。 +**行为**: 先读取根 `.env` 与 `data/.env`，缺失 `ENCRYPTION_KEY` 或 `SESSION_SECRET` 时自动生成并尝试写回，再初始化数据库。 +**结果**: 环境变量、数据库和会话存储准备完成后才开始监听 HTTP/WebSocket 服务。 + +### 路由与会话 +**条件**: 应用启动完成并收到前端请求。 +**行为**: 所有业务接口挂载在 `/api/v1/*` 下，`express-session` 通过文件存储共享登录状态，WebSocket 初始化时复用同一会话中间件。 +**结果**: REST 与实时会话使用一致的认证上下文。 + +### 业务分层 +**条件**: 维护业务域代码。 +**行为**: 按 `controller/service/repository/routes` 的分层模式组织连接、通知、设置、快速命令、主题等功能。 +**结果**: 新增后端能力时应优先延续现有业务域目录结构，而不是在入口文件堆叠逻辑。 + +## 依赖关系 + +```yaml +依赖: workspace-root, sqlite(data), express-session, ssh2, ws +被依赖: frontend +``` diff --git a/.helloagents/modules/frontend.md b/.helloagents/modules/frontend.md new file mode 100644 index 0000000..9bb179d --- /dev/null +++ b/.helloagents/modules/frontend.md @@ -0,0 +1,47 @@ +# frontend + +## 职责 + +`packages/frontend` 是 Vue 3 + Vite 的 Web 客户端，负责登录、初始化设置、连接管理、工作区布局、终端与文件编辑、通知与审计视图，以及对后端 REST/WebSocket 和远程桌面网关的前端集成。 + +## 接口定义（可选） + +> 模块对外暴露的公共 API 和数据结构 + +### 公共 API +| 函数/方法 | 参数 | 返回值 | 说明 | +|----------|------|--------|------| +| `src/main.ts` 启动流程 | 无 | Vue 应用实例 | 启动时先检查 setup/auth 状态，再挂载路由和应用。 | +| `src/router/index.ts` | 路由对象 | Vue Router 实例 | 管理 `/`、`/login`、`/workspace`、`/settings` 等页面与路由守卫。 | +| `useWebSocketConnection()` 等 composable | 业务参数 | 响应式状态/方法 | 处理 SSH 会话、文件管理、设置页等前端交互逻辑。 | + +### 数据结构 +| 字段 | 类型 | 说明 | +|------|------|------| +| `authStore` | Pinia store | 保存 `isAuthenticated`、`needsSetup` 等认证状态。 | +| `session.store` | Pinia store | 管理工作区标签、终端、SFTP 与弹窗状态。 | +| `connections.store` | Pinia store | 管理连接列表及其与后端的同步。 | + +## 行为规范 + +### 应用启动 +**条件**: 浏览器加载前端入口。 +**行为**: `main.ts` 先并行拉取 setup 状态与认证状态；若用户已登录，再加载设置和外观数据；最后才注册路由并挂载应用。 +**结果**: 路由守卫在挂载前即可拿到最新认证状态，避免错误跳转。 + +### 路由访问控制 +**条件**: 用户访问任一路由。 +**行为**: `router.beforeEach` 根据 `needsSetup` 与 `isAuthenticated` 决定是否重定向到 `/setup`、`/login` 或首页。 +**结果**: 初始化设置和登录约束由统一路由守卫执行。 + +### 工作区交互 +**条件**: 用户进入 `/workspace` 或相关管理页面。 +**行为**: 通过组件、Pinia 与 composable 协同管理终端、文件管理、命令历史、布局配置、主题和状态监控。 +**结果**: 页面逻辑分散在 `views/`、`components/`、`stores/` 与 `composables/`，改动时应优先在对应层级定位。 + +## 依赖关系 + +```yaml +依赖: workspace-root, backend, remote-gateway, vue-router, pinia +被依赖: 无 +``` diff --git a/.helloagents/modules/remote-gateway.md b/.helloagents/modules/remote-gateway.md new file mode 100644 index 0000000..99c5fab --- /dev/null +++ b/.helloagents/modules/remote-gateway.md @@ -0,0 +1,47 @@ +# remote-gateway + +## 职责 + +`packages/remote-gateway` 是独立的远程桌面网关服务，负责验证 RDP/VNC 连接参数、生成加密 token，并通过 `guacamole-lite` 与 `guacd` 协同提供远程桌面 WebSocket 能力。 + +## 接口定义（可选） + +> 模块对外暴露的公共 API 和数据结构 + +### 公共 API +| 函数/方法 | 参数 | 返回值 | 说明 | +|----------|------|--------|------| +| `POST /api/remote-desktop/token` | `protocol`, `connectionConfig` | `{ token }` | 校验参数后生成加密远程桌面 token。 | +| `GuacamoleLite(websocketOptions, guacdOptions, clientOptions)` | 端口、guacd 配置、加密配置 | GuacamoleLite 实例 | 启动远程桌面 WebSocket 网关。 | +| `gracefulShutdown(signal)` | 进程信号 | 无 | 关闭 HTTP API 与 Guacamole 服务器。 | + +### 数据结构 +| 字段 | 类型 | 说明 | +|------|------|------| +| `REMOTE_GATEWAY_API_PORT` | `string \| number` | HTTP API 监听端口，默认 `9090`。 | +| `REMOTE_GATEWAY_WS_PORT` | `string \| number` | Guacamole WebSocket 监听端口，默认 `8080`。 | +| `connectionConfig` | JSON 对象 | 包含 `hostname`、`port`、`username`、`password`、分辨率等桌面连接参数。 | + +## 行为规范 + +### 网关启动 +**条件**: 启动 `remote-gateway` 进程。 +**行为**: 进程启动时生成仅驻留内存的 AES 密钥，构造允许来源列表，并初始化 `GuacamoleLite` 与 API 服务器。 +**结果**: 每次进程重启都会使用新的内存密钥，旧 token 不应跨进程复用。 + +### Token 生成 +**条件**: 客户端请求 `/api/remote-desktop/token`。 +**行为**: 仅接受 `rdp` 或 `vnc`，按协议要求校验 `hostname`、`port`、账号口令等字段，再将连接配置加密为 base64 token。 +**结果**: 前端拿到可交给远程桌面 WebSocket 使用的短期 token。 + +### 优雅退出 +**条件**: 收到 `SIGINT`、`SIGTERM` 或 `SIGUSR2`。 +**行为**: 先关闭 API server，再尝试关闭 Guacamole server，10 秒后仍未完成则强制退出。 +**结果**: 开发环境重启和生产环境停机时尽量减少悬挂连接。 + +## 依赖关系 + +```yaml +依赖: workspace-root, guacd, guacamole-lite, cors +被依赖: frontend +``` diff --git a/.helloagents/modules/workspace-root.md b/.helloagents/modules/workspace-root.md new file mode 100644 index 0000000..9e848e2 --- /dev/null +++ b/.helloagents/modules/workspace-root.md @@ -0,0 +1,42 @@ +# workspace-root + +## 职责 + +管理仓库根目录的 npm workspaces、共享依赖、`patch-package` 补丁应用以及 Docker Compose 部署编排。该模块不是业务运行时服务，但决定了三个子包如何安装、构建和协同运行。 + +## 接口定义（可选） + +> 模块对外暴露的公共 API 和数据结构 + +### 公共 API +| 函数/方法 | 参数 | 返回值 | 说明 | +|----------|------|--------|------| +| `package.json#workspaces` | `packages/*` | npm workspace 列表 | 声明后端、前端、远程网关三个子包属于同一工作区。 | +| `package.json#postinstall` | 无 | shell 命令 | 安装依赖后自动执行 `patch-package`。 | +| `docker-compose.yml` | 环境变量、卷、端口映射 | 服务编排 | 统一启动 `frontend`、`backend`、`remote-gateway`、`guacd`。 | + +### 数据结构 +| 字段 | 类型 | 说明 | +|------|------|------| +| `packages/*` | 目录集合 | Monorepo 子包入口。 | +| `patches/` | 目录 | 第三方依赖补丁存放位置。 | +| `data/` | 运行时卷目录 | Docker 部署时挂载到后端 `/app/data`。 | + +## 行为规范 + +### 依赖安装 +**条件**: 在仓库根目录执行 `npm install`。 +**行为**: npm 解析 `workspaces`，统一安装根依赖与子包依赖，并在安装结束后运行 `patch-package`。 +**结果**: 三个子包共享锁文件与依赖树，补丁在安装阶段自动落地。 + +### 容器化部署 +**条件**: 使用根目录 `docker-compose.yml` 启动服务。 +**行为**: `frontend` 暴露 `18111:80`，`backend` 读取根 `.env` 并挂载 `./data:/app/data`，`remote-gateway` 依赖 `guacd` 和 `backend`。 +**结果**: Web 入口、REST API、远程桌面网关与 `guacd` 形成完整运行拓扑。 + +## 依赖关系 + +```yaml +依赖: frontend, backend, remote-gateway, docker-compose, .env +被依赖: frontend, backend, remote-gateway +```