## 更新日志
### v1.0.11 — 快捷指令

在对话输入框中输入 `/` 即可触发快捷指令下拉菜单，支持键盘上下选择和回车确认：

- **`/init` — 初始化 AGENTS.md** — 引导式生成项目 AGENTS.md 配置文件，为 AI 提供项目上下文和开发规范
- **`/compact` — 压缩当前会话** — 对当前会话进行智能摘要压缩，减少上下文占用，保持对话连贯性
- **`/export` — 导出当前会话** — 将当前会话内容导出为本地文件，方便存档和分享

# cfo-ui

CodeFree-O 的 Web 可视化界面 — 为中国电信研发云 AI 编程助手提供桌面端和移动端的交互体验。

## 它是什么

`cfo-ui` 是一个 npm 包，安装后即可在浏览器中使用 CodeFree-O AI 编程助手。它包含：

- **Express 后端** — 通过 `@srdcloud/codefree-o-sdk` 与 CodeFree-O AI 引擎通信，管理会话、消息和权限
- **React 前端** — 聊天面板、集成终端、文件浏览器、会话管理，支持暗色/亮色主题
- **CLI 入口** — 一条命令启动服务并打开浏览器

## 与 CodeFree-O 的区别

| | CodeFree-O | cfo-ui |
|---|---|---|
| **定位** | AI 编程助手引擎（CLI） | AI 助手的 Web 可视化界面 |
| **交互方式** | 命令行终端 | 浏览器图形界面 |
| **运行环境** | Node.js CLI 进程 | Express 服务器 + 浏览器 |
| **核心能力** | 代码生成、文件操作、Shell 执行 | 聊天对话、终端集成、文件浏览、会话管理 |
| **依赖关系** | 独立运行 | 依赖 CodeFree-O 引擎（本地或远程） |

简单来说：**CodeFree-O 是大脑，cfo-ui 是脸面**。cfo-ui 通过 SDK 调用 CodeFree-O 的能力，将 CLI 交互转化为更直观的 Web 体验。

## 安装

```bash
npm install -g cfo-ui
```

> 需要预先安装 CodeFree-O CLI：`npm install -g @srdcloud/codefree-o`

## 使用

### 一键启动

```bash
codefree-o-ui
```

自动启动后端服务并在浏览器中打开界面。默认地址 `http://localhost:3001`。

不自动打开浏览器：

```bash
codefree-o-ui --no-open
```

### 仅启动服务

```bash
npx cfo-ui --no-open
```

## 环境配置

在项目目录下创建 `.env` 文件：

```bash
# 服务端口（默认 3001）
SERVER_PORT=3001

# CodeFree-O 服务地址（留空则自动启动本地进程）
CODEFREE_BASE_URL=

# API Key（远程服务认证，可选）
CODEFREE_API_KEY=

# 项目目录（为 AI 提供上下文，可选）
CODEFREE_DIRECTORY=
```

### 本地模式

不配置 `CODEFREE_BASE_URL`，SDK 自动在本地启动 CodeFree-O 进程，零配置开箱即用。

### 远程模式

```bash
CODEFREE_BASE_URL=https://codefree.srdcloud.cn
CODEFREE_API_KEY=sk-xxxxxxxx
```

直连已部署的 CodeFree-O 远程服务。

## 功能特性

- **流式对话** — 基于 SSE 的增量响应，逐字输出
- **集成终端** — WebSocket 连接远程 Shell，在浏览器中执行命令
- **文件浏览器** — 交互式文件树，浏览和查看项目文件
- **会话管理** — 多会话切换、历史记录、重命名和删除
- **响应中止** — 随时中断 AI 生成过程
- **权限控制** — 工具调用授权（单次/始终允许/拒绝）
- **响应式设计** — 桌面端和移动端自适应
- **暗色/亮色主题** — 一键切换

## 从源码开发

```bash
# 安装依赖
npm install

# 开发模式（前端热更新 + 后端自动重启）
npm run dev

# 构建生产版本
npm run build

# 运行生产服务
npm run server
```

开发模式下前端运行在 `http://localhost:5173`，自动代理 API 请求到后端。

## 技术栈

| 层 | 技术 |
|---|---|
| 前端 | React 18 + TypeScript + Vite |
| 样式 | Tailwind CSS |
| 后端 | Express + WebSocket (ws) |
| AI 通信 | @srdcloud/codefree-o-sdk |
| 终端 | xterm.js |
| Markdown | react-markdown + remark-gfm |
| 代码高亮 | react-syntax-highlighter |

## 项目结构

```
cfo-ui/
├── server/                  # Express 后端
│   ├── cli.js               # CLI 入口
│   ├── index.js             # 服务主入口
│   ├── services/
│   │   └── aiService.js     # SDK 集成层
│   └── routes/
│       ├── codefreeApi.js   # AI 会话与消息 API
│       ├── sse.js           # SSE 事件流代理
│       ├── sessions.js      # 会话管理 API
│       ├── websocket.js     # 聊天与终端 WebSocket
│       ├── projects.js      # 项目管理 API
│       └── files.js         # 文件操作 API
├── src/                     # React 前端
│   ├── components/
│   │   ├── chat/            # 聊天面板
│   │   ├── sidebar/         # 侧边栏
│   │   ├── file-explorer/   # 文件浏览器
│   │   ├── terminal/        # 终端
│   │   ├── settings/        # 设置
│   │   └── common/          # 通用组件
│   ├── contexts/            # React Context
│   ├── services/            # API 服务层
│   ├── hooks/               # 自定义 Hooks
│   ├── stores/              # 状态管理
│   ├── types/               # TypeScript 类型
│   └── utils/               # 工具函数
├── public/                  # 静态资源
└── package.json
```

## 未来计划

### v1.1.0（预告）— Git 源代码管理

即将支持 **Git 存储库源代码管理**，将版本控制能力深度集成到 AI 编程工作流中：

- **可视化 Git 操作** — 在文件浏览器中直观展示文件的 Git 状态（Modified、Staged、Untracked），支持 Stage / Unstage、Commit、Push / Pull 等常用操作，无需切换到终端手动执行命令。
- **变更对比（Diff View）** — 提供并排或行内差异对比视图，直观展示代码改动内容，方便在提交前或 AI 修改代码后进行审查。
- **分支与历史管理** — 支持创建和切换分支、查看提交历史记录，一目了然地掌握项目演进脉络。
- **AI 辅助提交** — AI 自动分析代码变更，智能生成 Commit Message，提升提交效率和信息质量。
- **冲突解决** — 提供可视化的合并冲突解决界面，降低手动解决冲突的复杂度。



## License

MIT
