# Qualia Code

**Repository Path**: lunarlanding/qualia-code

## Basic Information

- **Project Name**: Qualia Code
- **Description**: Qualia Code 是一款 AI 编码助手，用对话驱动 Agent 读写代码、执行命令，并在沙箱工作区里实时审查与预览改动，同时集成知识库、技能市场与定时任务，支持 CLI / Web / 桌面三种形态。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 1
- **Created**: 2026-10-29
- **Last Updated**: 2026-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Qualia Code

> 开源、本地运行的 AI 编码助手。用自然语言描述需求，它会拆解任务、调用工具、审查变更，把整个工作流跑在你自己的机器上。

CLI / Web / 桌面三种形态，共享同一后端与本地配置。不依赖云端账号，不上传数据。

![version](https://img.shields.io/badge/version-0.2.0-blue) ![JDK](https://img.shields.io/badge/JDK-17%2B-orange) ![license](https://img.shields.io/badge/license-MIT-green)

## 它能做什么

- **对话式 Agent 工作流** —— 自然语言需求自动拆解为工具调用，执行步骤以可展开卡片呈现，全程可追溯。
- **沙箱工作区** —— 文件树浏览、变更 Diff 审查与一键还原、内置浏览器即时预览，改了什么、影响在哪，一目了然。
- **长期协作伙伴** —— 资料中心（可检索、可引用的知识库）、技能管理（加载专业能力 / 扩展技能市场）、定时任务（按 cron 周期自动执行）。
- **多形态一体** —— 一份构建产出 Web、CLI、桌面三种用法，配置与会话全部落在本地。

## 功能预览

<table>
  <thead>
    <tr>
      <th align="center">☀️ 日间主题</th>
      <th align="center">🌙 夜间主题</th>
    </tr>
  </thead>
  <tbody>
    <tr><td colspan="2"><b>欢迎页与三栏布局</b> —— 侧栏、对话区与沙箱面板一览</td></tr>
    <tr>
      <td><img src="docs/images/welcome-light.png" alt="欢迎页（日间）" width="520"></td>
      <td><img src="docs/images/welcome-dark.png" alt="欢迎页（夜间）" width="520"></td>
    </tr>
    <tr><td colspan="2"><b>沙箱工作区</b> —— 文件树、变更审查与内置浏览器</td></tr>
    <tr>
      <td><img src="docs/images/workspace-light.png" alt="沙箱工作区（日间）" width="520"></td>
      <td><img src="docs/images/workspace-dark.png" alt="沙箱工作区（夜间）" width="520"></td>
    </tr>
    <tr><td colspan="2"><b>定时任务</b> —— 按 cron 周期自动执行的任务中心</td></tr>
    <tr>
      <td><img src="docs/images/schedules-light.png" alt="定时任务（日间）" width="520"></td>
      <td><img src="docs/images/schedules-dark.png" alt="定时任务（夜间）" width="520"></td>
    </tr>
    <tr><td colspan="2"><b>资料中心</b> —— 会话可检索、可引用的知识库</td></tr>
    <tr>
      <td><img src="docs/images/materials-light.png" alt="资料中心（日间）" width="520"></td>
      <td><img src="docs/images/materials-dark.png" alt="资料中心（夜间）" width="520"></td>
    </tr>
    <tr><td colspan="2"><b>技能管理</b> —— 已安装技能与技能市场</td></tr>
    <tr>
      <td><img src="docs/images/skills-light.png" alt="技能管理（日间）" width="520"></td>
      <td><img src="docs/images/skills-dark.png" alt="技能管理（夜间）" width="520"></td>
    </tr>
  </tbody>
</table>

## 快速开始

### 环境要求

- JDK 17+（桌面打包需完整 JDK，含 `jpackage`）
- Maven 3.8+

### 构建

```bash
# 全量构建（含前端）
mvn clean package -DskipTests

# 跳过前端构建，只重打 Java（改后端代码时用，快）
mvn clean package -DskipTests -Dskip.npm=true -Dskip.installnodenpm=true
```

产物：

| 文件 | 说明 |
|---|---|
| `qualia-code/target/qualia-code-<version>.jar` | Web + CLI 可执行 uber-jar（含前端静态资源） |
| `qualia-code-desktop/target/qualia-code-desktop-<version>.jar` | 桌面壳可执行 uber-jar |

### 运行

```bash
# 初始化配置
java -jar qualia-code/target/qualia-code-0.2.0.jar init

# Web 模式（默认，http://localhost:9090）
java -jar qualia-code/target/qualia-code-0.2.0.jar

# 指定工作区与端口
java -jar qualia-code/target/qualia-code-0.2.0.jar -w /path/to/project -p 9090

# CLI 交互模式
java -jar qualia-code/target/qualia-code-0.2.0.jar --cli -w /path/to/project
```

配置与会话落在 `~/.qualia/code/`，纯本地存储。

## 桌面应用打包

```powershell
# Windows：产物 qualia-code-desktop\target\dist\<version>\Qualia Code\Qualia Code.exe
.\qualia-code-desktop\packaging\package-win.ps1
```

```bash
# macOS：产物 qualia-code-desktop/target/dist/Qualia Code.app（正式分发需签名 + 公证）
./qualia-code-desktop/packaging/package-mac.sh
```

## 项目结构

```
qualia-code/
├── qualia-code-ui/         Vue 3 + Vite 前端，构建产物打进 jar 的 static/
├── qualia-code-desktop/    SWT + 系统 WebView 桌面壳，jpackage 出免安装 app-image
└── qualia-code/            Spring Boot 后端 + picocli CLI，shade 出可执行 jar
```

前端是后端的 Maven 依赖（`qualia-code` 依赖 `qualia-code-ui` 的 jar），一次 `mvn package` 前后端一起产出，无需手工 `npm` 后再重打。

### 前端开发（热更新）

```bash
cd qualia-code-ui
npm install
npm run dev          # 端口 5273，/api 代理到本机后端，默认 http://localhost:9090，可用 QUALIA_BACKEND 覆盖
```

## 版本

本项目版本由根 POM 的 `<revision>` 统一管理，一处改动全模块跟随，桌面安装包版本号也读它。

## License

[MIT](LICENSE)