Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 0 additions & 38 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,6 @@ on:
branches: [main]

jobs:
backend:
name: 后端(Java)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 安装 JDK 17
uses: actions/setup-java@v4
with:
java-version: '17'
distribution: temurin
cache: maven
# 单测均为纯单元测试,不依赖 MySQL,可直接跑
- name: 编译 + 单测
run: ./mvnw -B clean test

app:
name: 桌面端(Flutter)
runs-on: ubuntu-latest
Expand All @@ -40,26 +25,3 @@ jobs:
run: flutter analyze
- name: 单测
run: flutter test

cli:
name: CLI(Node)
runs-on: ubuntu-latest
defaults:
run:
working-directory: clients/cli
steps:
- uses: actions/checkout@v4
- name: 安装 Node 20
uses: actions/setup-node@v4
with:
node-version: '20'
cache: npm
cache-dependency-path: clients/cli/package-lock.json
- name: 装依赖
run: npm ci
- name: 类型检查
run: npm run typecheck
- name: 单测
run: npm test
- name: 构建
run: npm run build
11 changes: 11 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,14 @@ logs/
# CLI 客户端(Node)构建产物与依赖
clients/cli/node_modules/
clients/cli/dist/

# 本地保留的私有实现:不再提交到远程仓库
/src/
/pom.xml
/.mvn/
/mvnw
/mvnw.cmd
/Dockerfile
/docker-compose.yml
/.env.example
/clients/cli/
Binary file removed .mvn/wrapper/maven-wrapper.jar
Binary file not shown.
19 changes: 0 additions & 19 deletions .mvn/wrapper/maven-wrapper.properties

This file was deleted.

107 changes: 23 additions & 84 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,106 +1,45 @@
# 贡献指南

感谢你对 LowenSSH 的兴趣。这份指南帮你快速上手本地开发、了解项目约定与提交流程。

## 项目结构速览

LowenSSH 是「同一套理念、三种独立形态」的项目,三端互不依赖:

| 形态 | 目录 | 技术栈 |
|------|------|--------|
| 后端服务 | `src/` | Java 17 · Spring Boot 3.4 · Spring AI |
| 桌面客户端 | `clients/app/` | Flutter(macOS / Windows) |
| CLI 客户端 | `clients/cli/` | Node 20 · Ink(TUI) |

核心理念(手写 Agent loop + Deny/Ask/Allow 安全门禁 + 上下文管理)在三端各自实现,**门禁规则与事件语义需手动对齐**。改动涉及核心逻辑时,请留意是否需要同步到其他端。

设计取舍详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
感谢你对 LowenSSH 的兴趣。远程仓库当前仅维护 [`clients/app/`](clients/app/) 下的 Flutter 桌面客户端。

## 本地开发环境

### 后端(`src/`)

需要 JDK 17。项目自带 Maven Wrapper,无需预装 Maven。

```bash
export MYSQL_PASSWORD='你的MySQL密码'
export GLM_API_KEY='你的智谱AI key' # https://open.bigmodel.cn 申请

# 初始化数据库
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS lowenssh DEFAULT CHARSET utf8mb4;"
mysql -u root -p lowenssh < src/main/resources/schema.sql

./mvnw spring-boot:run # Windows 用 mvnw.cmd
```

运行测试:

```bash
./mvnw test
```

### 桌面端(`clients/app/`)

需要 Flutter SDK 3.12+。详见 [clients/app/README.md](clients/app/README.md)。
需要 Flutter SDK 3.12+。macOS 构建需要 Xcode;Windows 构建需要 Visual Studio,并安装“使用 C++ 的桌面开发”工作负载。

```bash
cd clients/app
flutter pub get
flutter run -d macos # 或 -d windows
flutter analyze # 提交前确保零问题
flutter run -d macos # 或 flutter run -d windows
flutter analyze
flutter test
```

### CLI(`clients/cli/`)

需要 Node 20+。详见 [clients/cli/README.md](clients/cli/README.md)。
完整运行、打包和模型配置说明见 [`clients/app/README.md`](clients/app/README.md)。

## 代码约定

- **注释用中文,标识符(变量/函数/类名)用英文**
- 优先可读性,不做过度优化;改动范围尽量小,不顺手重构无关代码
- 后端 Java 用 Java 17 语法,不用过时写法
- Flutter 优先 Composition 风格的 Widget 拆分,复用动画/组件放对应封装文件
- 涉及安全门禁规则改动,必须补充或更新对应单元测试
- 注释使用中文,标识符使用英文
- 优先可读性,不重构与当前任务无关的代码
- Widget 保持职责清晰,可复用动画和组件放入对应封装文件
- 修改安全门禁、凭据保存或 SSH 执行逻辑时,必须补充相应测试
- 不提交 API Key、密码、`.env`、本机构建产物和日志

## 提交前检查

- 后端:`./mvnw test` 全绿。
- 桌面端:`flutter analyze` 零问题,`flutter build macos --debug`(或 windows)可编译。
- CLI:按 `clients/cli/README.md` 的检查方式验证。
- 不提交任何明文密钥、`.env` 文件、本地构建产物。

## 提交信息规范

- 用简洁的中文描述「做了什么」,必要时补充「为什么」。
- 前缀标明影响范围,例如 `app:`、`cli:`、`backend:`、`docs:`。
- 一个提交聚焦一件事,避免把无关改动混在一起。

示例:

```
app: 修复切主题时终端不变色

终端配色从冻结的顶层 final 改为按当前 palette 实时计算。
```bash
cd clients/app
flutter analyze
flutter test
flutter build macos --debug # Windows 使用对应构建命令
```

## Pull Request 流程

1. 从 `main` 切出 feature 分支(如 `feature/xxx`、`fix/xxx`),**不要直接提交到 main**。
2. 完成开发并通过提交前检查。
3. 推送分支并发起 PR,目标分支为 `main`。
4. PR 描述请包含:改了什么、为什么、如何测试、是否涉及多端对齐。
5. 等待 review,合并后删除 feature 分支。

## 安全相关改动

本项目的安全门禁(高危命令拦截)是真实防护,不是演示。涉及以下改动请在 PR 中重点说明:

- 修改 deny / ask 规则名单。
- 调整命令拆段、正则匹配逻辑。
- 改动密码加密、密钥读取、审计落库相关代码。
## 提交与 Pull Request

发现安全漏洞请不要直接提 public issue,先通过私下渠道联系维护者。
1. 从 `main` 创建功能分支,不直接提交到 `main`。
2. 一个提交只处理一类问题,提交信息使用简洁中文。
3. 推送分支后创建 PR,目标分支为 `main`。
4. PR 说明应包含改动内容、原因、验证方式和安全影响。

## 报告问题
## 安全问题

提 issue 时请尽量包含:复现步骤、预期与实际行为、运行环境(操作系统、形态、版本)、相关日志或截图
安全门禁和凭据保护属于真实防护。发现可导致未授权命令执行、凭据泄露或安全规则绕过的问题时,请先通过私下渠道联系维护者,不要直接公开利用细节
20 changes: 0 additions & 20 deletions Dockerfile

This file was deleted.

Loading
Loading