catalog/repos/aidotnet--moyucode.md

# AI编程会话管理工具

`AI编程` `Claude Code` `Codex` `Web界面` `开源工具`

# MoYuCode（摸鱼Coding）

<div align="center">

**一键管理 Codex 和 Claude Code —— ZCode 的开源版本**

[![CI](https://github.com/AIDotNet/MoYuCode/workflows/CI/badge.svg)](https://github.com/AIDotNet/MoYuCode/actions)
[![Release](https://img.shields.io/github/v/release/AIDotNet/MoYuCode)](https://github.com/AIDotNet/MoYuCode/releases)
[![License](https://img.shields.io/github/license/AIDotNet/MoYuCode)](LICENSE)

[English](README.md) | [简体中文](README.zh-CN.md)

</div>

## 简介

MoYuCode（摸鱼Coding）是一款开源工具，旨在帮助用户通过 Web 界面便捷地操作 [Codex](https://github.com/openai/codex) 和 [Claude Code](https://claude.ai/code)。它支持本地部署，并可通过内网穿透对外访问，方便用户在移动设备等平台上远程使用。部分设计体验参考自 [ZCode](https://zcode.dev/)。

## 功能特性

- **Web 界面**：基于 React + TypeScript + Tailwind CSS 构建的现代化响应式 Web UI
- **AI 集成**：无缝集成 OpenAI Codex 和 Claude Code
- **会话管理**：可视化管理 AI 编程会话，提供详细历史记录
- **项目工作区**：集成文件浏览器和代码编辑器，打造流畅的开发工作流
- **Token 用量追踪**：监控并可视化各会话的 Token 消耗情况
- **实时更新**：通过 SSE（Server-Sent Events）实现 AI 响应实时流式传输
- **跨平台**：支持 Windows、Linux 和 macOS
- **系统托盘**：Windows 桌面应用支持托盘图标

## 截图预览

### 系统托盘
启动 MoYuCode.Win.exe 后，系统托盘区会显示图标，后台服务自动运行。

### 项目选择
自动扫描并加载本地已使用过 Codex 的项目，可选择并进入工作区。

### 会话管理
- 开始新对话或从历史会话中选择
- 加载历史会话以恢复完整上下文
- 查看会话详情，包括 Token 用量和时间线

### 文件浏览器
集成文件浏览器，可在与 AI 交互的同时直接查看和编辑代码文件。

## 下载与安装

### Windows 桌面应用

1. 访问 [GitHub Releases](https://github.com/AIDotNet/MoYuCode/releases) 页面
2. 下载最新 Windows 压缩包（`MoYuCode-*-win-x64.zip`）
3. 解压后运行 `MoYuCode.Win.exe`
4. 程序将在系统托盘显示图标
5. 打开浏览器访问 `http://localhost:9110/`

### Linux

1. 从 [Releases](https://github.com/AIDotNet/MoYuCode/releases) 下载最新 Linux 包（`MoYuCode-*-linux-x64.tar.gz`）
2. 解压：
   ```bash
   tar -xzf MoYuCode-*-linux-x64.tar.gz
   cd MoYuCode-*-linux-x64
   ```
3. 直接运行：
   ```bash
   ./run.sh
   ```
4. 或安装为 systemd 服务：
   ```bash
   sudo ./install-service.sh
   ```

### macOS

1. 从 [Releases](https://github.com/AIDotNet/MoYuCode/releases) 下载最新 macOS 包（`MoYuCode-*-osx-x64.tar.gz`）
2. 解压：
   ```bash
   tar -xzf MoYuCode-*-osx-x64.tar.gz
   cd MoYuCode-*-osx-x64
   ```
3. 直接运行：
   ```bash
   ./run.sh
   ```
4. 或安装为 launch daemon：
   ```bash
   sudo ./install-service.sh
   ```

## 前置条件

- **.NET 10.0 Runtime**（独立可执行文件已自包含运行时）
- **Codex CLI**（使用 Codex 集成时必须安装）：
  ```bash
  npm install -g @openai/codex
  ```

## 使用说明

### 访问 MoYuCode（摸鱼Coding）

启动应用后，打开浏览器访问：

- HTTP：`http://localhost:9110/`
- HTTPS：`https://localhost:9111/`（如已配置）

### 项目工作流

1. **选择项目**：MoYuCode 自动扫描有 Codex 使用历史的项目
2. **进入工作区**：点击项目进入其工作区
3. **开始对话**：发起新对话或加载历史会话
4. **查看代码**：使用集成文件浏览器查看和编辑文件
5. **监控用量**：追踪 Token 消耗和会话统计信息

### 会话管理

- 点击右上角的会话列表按钮
- 选择一个历史会话
- 点击"加载会话"以恢复完整上下文
- 查看会话详情，包括 Token 用量、时间线和元数据

## 开发指南

### 后端（C# / ASP.NET Core）

```bash
# 构建
dotnet build src/MoYuCode/MoYuCode.csproj

# 运行（HTTP）
dotnet run --project src/MoYuCode/MoYuCode.csproj --launch-profile http

# 运行（HTTPS）
dotnet run --project src/MoYuCode/MoYuCode.csproj --launch-profile https
```

### 前端（React / Vite）

```bash
cd web

# 安装依赖
npm ci

# 启动开发服务器
npm run dev

# 生产环境构建
npm run build

# 代码检查
npm run lint
```

### 完整应用构建

CI 流水线自动构建前端和后端：

```bash
# 安装前端依赖
npm ci

# 构建前端
npm run build

# 同步前端产物到后端 wwwroot
rsync -a --delete web/dist/ src/MoYuCode/wwwroot/

# 构建后端
dotnet build src/MoYuCode/MoYuCode.csproj -c Release
```

## 架构说明

MoYuCode（摸鱼Coding）采用双栈架构：

### 后端
- **框架**：ASP.NET Core 10.0 Web API
- **通信**：通过 stdio 与 Codex app-server 进行 JSON-RPC 通信
- **数据库**：SQLite + Entity Framework Core
- **协议**：使用 Agent-to-Agent（A2A）协议实现 AI 流式交互

### 前端
- **框架**：React 19 + TypeScript
- **构建工具**：Vite
- **样式**：Tailwind CSS v4
- **状态管理**：React Router + 本地组件状态
- **UI 组件**：Radix UI + 自定义动画

详细架构文档请参见 [CLAUDE.md](CLAUDE.md)。

## 贡献指南

欢迎贡献！请随时提交 Issue 或 Pull Request。

1. Fork 本仓库
2. 创建功能分支
3. 提交你的更改
4. 推送到分支
5. 创建 Pull Request

## 许可证

本项目基于 MIT 许可证 —— 详见 [LICENSE](LICENSE) 文件。

## 社区

- GitHub：[https://github.com/AIDotNet/MoYuCode](https://github.com/AIDotNet/MoYuCode)
- Issues：[https://github.com/AIDotNet/MoYuCode/issues](https://github.com/AIDotNet/MoYuCode/issues)
- Discussions：[https://github.com/AIDotNet/MoYuCode/discussions](https://github.com/AIDotNet/MoYuCode/discussions)

## 致谢

- 灵感来自 [ZCode](https://zcode.dev/)
- 基于 [OpenAI Codex](https://github.com/openai/codex) 和 [Anthropic Claude Code](https://claude.ai/code) 构建

社区微信：wk28u9123456789