# USTAgent

**Repository Path**: pmhw/ust

## Basic Information

- **Project Name**: USTAgent
- **Description**: 面向「手机 / 远程」驱动本地 Agent 的 VibeCoding 小工具：在 Telegram 里发指令，让本机上的 Cursor Agent CLI、自研 UST Agent CLI 或 Trae 包装脚本 在指定工作区里跑任务，并支持 /git 提交推送。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-04
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 UST Agent （VibeCoding · VCC）

面向「手机 / 远程」驱动本地 Agent 的 VibeCoding 小工具：在 **Telegram** 📱 里发指令，让本机上的 **Cursor Agent CLI**、**自研 UST Agent CLI** 或 **Trae 包装脚本** 在指定工作区里跑任务，并支持 **`/git` 提交推送** 🔀。

### 📦 代码托管

| 平台 | 仓库 |
|------|------|
| **GitHub** | [https://github.com/pmhw/VibeCoding-VCC](https://github.com/pmhw/VibeCoding-VCC) |
| **Gitee** | [https://gitee.com/pmhw/ust](https://gitee.com/pmhw/ust) |

可将同一本地仓库配置两个 `remote`（例如 `origin` / `github`），分别推送以保持两边同步。

### 💬 社区认可

项目讨论与交流：[**Linux.do**](https://linux.do/) 🐧

---

## ✨ 能做什么

| 能力 | 说明 |
|------|------|
| **多 CLI** 🔧 | 同一套 Web 配置里可保存 Cursor / UST / Trae 的路径与工作区，用 `/cursor`、`/ust`、`/trae` 选用 |
| **流式回传** 📡 | Agent 输出可实时推送到 Telegram（长任务更友好） |
| **Git 工作流** 🔀 | `/git` 优先跟随**最近一次** Agent 指令类型，用**当前配置**里对应 IDE 的工作区（如 `/ust` 后用 `UST_WORKSPACE`）执行 add / commit / push；可配自定义脚本 |
| **安全与网络** 🔐 | 支持 Bot 白名单、可选消息前缀密钥、HTTP/SOCKS 代理访问 Telegram |

更细的 Telegram 与 UST 安装说明见：📄 [`md/VC工具/远程 Agent.md`](./md/VC工具/远程%20Agent.md)。

---

## 🛠️ 技术栈

- ⚛️ **前端**：React 18、Vite 5、Arco Design  
- 🖥️ **后端**：Express（开发期与 Vite 中间件同端口）  
- 🤖 **远程 Agent**：Node + Telegraf（long polling）

---

## 📋 环境要求

- **Node.js** 📗：建议 **18+**（远程 Agent 文档推荐 Node 20 LTS 做 Telegram 连接）  
- **操作系统** 🪟：开发与 Agent 进程主要在 Windows 场景验证（路径、编码说明见代码与文档）

---

## 🚀 快速开始

### 1️⃣ 安装依赖

```bash
npm install
```

### 2️⃣ 配置环境变量

复制示例文件并按注释填写（**勿把真实 Token 提交进仓库** 🔒）：

```bash
cp .env.example .env
```

必填项至少包括：**`TELEGRAM_BOT_TOKEN`**（[@BotFather](https://t.me/BotFather) 创建 Bot）。生产环境强烈建议配置 **`TELEGRAM_ALLOWED_USER_IDS`**。

完整变量说明见根目录 [`.env.example`](./.env.example)。

### 3️⃣ 启动 Web（本地开发）

```bash
npm run dev
```

默认在 `127.0.0.1` 上寻找可用端口（由 `PORT` 指定起点，冲突则顺延）。浏览器打开终端里打印的地址，在 **「远程 Agent」** 页保存 Cursor / UST / Trae、Git 推送、超时等配置（会写入独立 JSON，也可用环境变量覆盖）。

### 4️⃣ 启动 Telegram 远程 Agent（单独进程）

在配好 `.env` 或已由 Web 写入的配置后：

```bash
npm run agent
```

需与 Telegram 网络连通；若无法直连 `api.telegram.org`，请在 `.env` 或页面中配置 **`TELEGRAM_PROXY_URL`**（或系统常用的 `HTTPS_PROXY`）。

---

## 📜 常用脚本

| 命令 | 作用 |
|------|------|
| `npm run dev` / `npm start` | 🔥 开发：Express + Vite HMR |
| `npm run build` | 📦 构建前端到 `dist/` |
| `npm run serve` | 🌐 生产样式静态站点 + API（读 `dist/`） |
| `npm run agent` | 🤖 仅启动 Telegram Bot（远程 Agent） |

---

## 📁 仓库结构（简要）

```text
agent/           # 远程 Agent：Telegram、Git 推送、IDE 适配
src/             # 前端页面（含「远程 Agent」配置 UI）
api.mjs          # HTTP API（配置读写等）
dev-server.mjs   # 开发服务器入口
server.mjs       # 构建后的静态服务入口
```

---

## 📚 文档与配图

- 📄 远程 Agent 与 UST 安装：[`md/VC工具/远程 Agent.md`](./md/VC工具/远程%20Agent.md)  
- 📂 其它 VC 工具说明：[`md/VC工具/`](./md/VC工具/) 目录下对应 Markdown  

界面示意：

![远程 Agent 配置示意](./md/VC工具/205728d8a9d0f957529d8eb5780a19a9.png)

---

## 🧠 模型与生态（简述）

- **当前** ✅：已对接常见用法说明中包含 **DeepSeek**、**Cursor** 等（UST 侧 LLM 可在 Web 中配置多条 Profile）。  
- **后续** 🔜：按业务需要扩展更多模型与自动化流程（以 Issue / 内部路线为准）。

---

## 📄 许可与贡献

本项目为私有用途仓库时请遵守团队规范；对外开源时需单独补充 **LICENSE** 与贡献指南。