Cosmosh 项目地图

1. Monorepo 布局

flowchart TB
  ROOT[Cosmosh Root]
  ROOT --> MAIN[packages/main]
  ROOT --> RENDERER[packages/renderer]
  ROOT --> BACKEND[packages/backend]
  ROOT --> API[packages/api-contract]
  ROOT --> I18N[packages/i18n]
  ROOT --> DOCS[docs]
  ROOT --> SCRIPTS[scripts]

2. 目录职责

packages/main

• 角色：Electron 宿主进程。
• 关键文件：
  • src/index.ts：应用启动、窗口配置、IPC 处理器、后端子进程管理。
  • src/preload.ts：安全渲染层桥接。
  • src/security/database-encryption.ts：数据库路径/密钥处理辅助。

packages/renderer

• 角色：React UI 层。
• 关键目录：
  • src/pages：功能页面（Home、SSH、SSHEditor、Settings、SettingsEditor等）。
  • src/components/ui：基于 Radix 的原子组件封装与样式契约。
  • src/components/home：Home/SSH 共享实体模块（卡片/图标渲染、视觉编辑器、可复用的创建文件夹弹窗）。
  • src/components/terminal：终端交互复合组件（右键菜单、选区工具条、自动补全面板）。
  • src/lib：后端传输、i18n、设置启动应用（app-settings.ts）与工具抽象（含共享实体视觉工具与创建文件夹 Hook）。
  • theme：生成 CSS Variables 的令牌源。

packages/backend

• 角色：内部 API + 会话编排运行时。
• 关键目录：
  • src/http/routes：设置、SSH 实体与本地终端动作 REST 路由。
  • src/ssh：SSH 认证/会话逻辑（ssh2、known-host 信任、遥测）。
  • src/settings：设置默认值与请求校验解析。
  • src/local-terminal：本地 PTY 会话逻辑（node-pty）。
  • src/terminal：终端会话共享原语（WebSocket 消息规范化、历史命令解析、尺寸收敛、历史同步时序辅助）。
  • src/terminal/completion：终端自动补全共享领域模块（规范数据、排序引擎、补全响应组装），由 SSH 与本地终端会话服务共同使用。
  • src/db：Prisma 初始化与数据库生命周期。

packages/api-contract

共享协议常量、请求/响应类型、OpenAPI 源与生成产物。

• src/settings-registry.ts：所有设置定义的唯一来源——类型、默认值、约束、枚举集、UI 控件元数据、分类与辅助函数。增删设置项仅需编辑此文件。
• src/settings.ts：基于注册表的通用校验与规范化辅助函数（normalizeSettingsValuesStrict、normalizeSettingsValuesWithDefaults），供 backend 与 renderer 共享。

packages/i18n

main/backend/renderer 作用域共用的语言 JSON 源与运行时 i18n 包。

• 运行时核心与具体文案资源解耦。消费端通过 createMessages(...) + createI18n(...) 显式注册所需语言 JSON。
• backend 作用域可在注册前通过 mergeTranslationTrees(...) 合并生成语料（如 backend-inshellisense.json）。

3. 功能落位规则

flowchart TD
  A[New Feature Request] --> B{UI only?}
  B -- Yes --> C[packages/renderer/src/pages + components]
  B -- No --> D{Needs privileged access?}
  D -- Yes --> E[Add preload bridge API + main IPC]
  E --> F[Main proxies to backend or executes OS action]
  D -- No --> G[Add backend route/service]
  G --> H[Expose through transport in renderer]
  F --> I[Update docs + ipc-protocol]
  H --> I

4. 命名与结构指南

• 进程间契约先落在 api-contract，再供 backend/main/renderer 消费。
• 渲染层副作用放在 src/lib（transport/services），不要直接写在展示组件中。
• 新增 IPC channel 必须通过 preload 暴露，并同步到 renderer/src/vite-env.d.ts。
• 对于后端能力：
  • 路由放在 http/routes/*
  • 业务/会话逻辑放在独立 service 模块
  • 输入校验采用 ssh/validation.ts 风格解析模块。

5. 尚未实现（规划中）

• 完整 SFTP 功能模块（后端服务、WebSocket/文件传输协议、renderer 资源管理器页面）。
• 尚无独立 common 共享包；当前共享通过 api-contract + i18n 实现。

6. 常见改动场景

新增 IPC 动作

1. 需要时先在 packages/api-contract 定义或复用契约类型。
2. 在 packages/main/src/preload.ts 暴露 bridge API。
3. 在 packages/main/src/index.ts 增加 ipcMain 处理和后端代理。
4. 在 packages/renderer/src/lib 接入 transport 封装。
5. 同步更新 docs/zh-CN/developer/core/ipc-protocol.md。

新增后端能力

1. 在 packages/backend/src/http/routes 新增路由。
2. 在对应领域模块（ssh、local-terminal 或新模块）新增 service 逻辑。
3. 增加输入边界校验/解析层。
4. 通过 main bridge 暴露给 renderer。
5. 同步架构与运行时文档。

新增应用设置项

1. 在 packages/api-contract/src/settings-registry.ts 中：
   • 在 SettingsValues 接口中添加 key 及其类型。
   • 在 SETTINGS_REGISTRY 数组中添加一条 SettingDefinition 条目（默认值、约束、UI 控件、分类、i18n key 等）。
2. 在 packages/i18n/locales/en/*.json 和 zh-CN/*.json 中添加 i18n key。
3. 无需修改其他文件——校验、默认值与 UI 渲染均从注册表自动派生。

7. SSH 钥匙链模块归属（2026-03）

• 数据模型归属：
  • packages/backend/prisma/schema.prisma 定义 SshKeychain 与 SshServer.keychainId 关系。
  • 钥匙链的文件夹/标签元数据复用 SshFolder、SshTag（以及 SshKeychainTagLink），不再维护钥匙链专属文件夹/标签表。
• 运行时归属：
  • packages/backend/src/http/routes/ssh.ts 负责钥匙链 CRUD 与凭据读取接口。
  • packages/backend/src/ssh/session-service.ts 负责连接阶段 server→keychain 凭据解析。
• Bridge 归属：
  • packages/main/src/ipc/register-backend-ipc.ts 与 packages/main/src/preload.ts 负责钥匙链 IPC 代理通道。
• Renderer 归属：
  • packages/renderer/src/pages/SSHEditor.tsx 负责单服务器内的钥匙链选择与内联认证回退流程。
  • packages/renderer/src/pages/SSHKeychains.tsx 负责独立钥匙链管理页面的增删改流程。