# ws-agent

**Repository Path**: MH8888/ws-agent

## Basic Information

- **Project Name**: ws-agent
- **Description**: 小熵 Agent 是一个面向 Windows 环境的本地 AI Agent 框架。它以 FastAPI 为后端、Vue 3 为前端，通过 OpenAI 兼容接口接入任意私有或本地大模型（如 Ollama、vLLM、LM Studio 等），在本机完成对话、文件管理、命令执行、记忆存储等一系列智能任务。

项目的核心设计理念是：轻量、可控、可扩展。所有数据（会话历史、用户记忆、运行日志）均存储在本地
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-03-18
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小熵 Windows AI Agent

> 一个运行在 Windows 本地的开源 AI Agent，高效简洁且数据完全自主可控。

## 项目简介

小熵 Agent 是一个面向 Windows 环境的本地 AI Agent 框架。它以 FastAPI 为后端、Vue 3 为前端，通过 OpenAI 兼容接口接入任意私有或本地大模型（如 Ollama、vLLM、LM Studio 等），在本机完成对话、文件管理、命令执行、记忆存储等一系列智能任务。

项目的核心设计理念是：**轻量、可控、可扩展**。所有数据（会话历史、用户记忆、运行日志）均存储在本地，不依赖任何云服务。

## 核心特性

**🤖 Agentic Loop（ReAct 模式）**
Agent 在处理自然语言请求时，会自主进行多轮思考与工具调用（最多 8 轮），支持文件浏览、读取、移动、复制等操作，并内置 Finish Guard 机制——若用户意图包含写操作，Agent 必须实际执行并通过文件大小校验后才能结束，防止"假完成"。

**📋 Spec 模式（复杂任务规划）**
对于复杂的系统级任务，Agent 会先生成结构化的规划文档（`spec.md` + `tasks.md` + `checklist.md`），用户确认后再分步执行。规划与执行分离，过程透明可追溯。

**🧠 长期记忆系统**
基于 SQLite 的用户记忆存储，支持按分类（事实/偏好/经验）管理，使用结巴分词进行中英文混合关键词检索。每次对话后可自动提取并保存记忆，下次对话时自动召回相关上下文。

**🔧 模块化工具系统（Tool Registry）**
内置文件系统、命令执行等工具，支持在 UI 中动态启停。工具定义与执行逻辑解耦，便于扩展自定义工具。

**🔌 Skills 插件机制**
在指定目录下放置 `.py` 文件即可注册新技能，无需修改核心代码。支持自动发现、重试与降级。

**📊 性能监控面板**
实时展示 Token 消耗与流量，并持久化每日数据，支持查看今日、近 7 天、近 30 天的消耗趋势图表。

**🔒 安全设计**
命令执行需显式授权（`approved=true`），高风险命令模式自动拦截；文件操作限制在沙箱目录内；审计日志自动脱敏 `api_key`、`token`、`password` 等敏感字段。

## 技术栈

| 层    | 技术                                        |
| ---- | ----------------------------------------- |
| 后端   | Python 3.10+, FastAPI, Uvicorn            |
| 前端   | Vue 3, Vite, Tailwind CSS, ECharts, Axios |
| 存储   | SQLite（记忆）, JSON 文件（会话/历史指标）              |
| 模型接入 | OpenAI 兼容 API，原生 `urllib` 调用，无第三方 SDK 依赖  |
| 打包   | PyInstaller（可打包为单文件 `.exe`）               |

## 快速开始

**1. 安装依赖**

```powershell
pip install -r requirements.txt
cd frontend
npm install
npm run build
cd ..
```

**2. 配置模型**（`agent_config.json`，放在项目根目录）

```json
{
  "model": {
    "endpoint": "http://127.0.0.1:8000/v1/chat/completions",
    "model": "your-model-name",
    "api_key": "your-api-key"
  },
  "workspace_root": "e:\\agent\\workspace",
  "data_root": "e:\\agent\\data",
  "llm_orchestration_only": true
}
```

`endpoint` 填写任意兼容 OpenAI 格式的模型服务地址即可。

**3. 启动**

```powershell
python main.py ui --port 8787
```

打开浏览器访问 `http://127.0.0.1:8787`，即可使用完整的聊天界面与监控面板。

## CLI 用法

```powershell
python main.py                                         # 启动 UI（默认）
python main.py config-test                             # 测试模型连通性
python main.py chat --user u1 --session s1 --message "你好"
python main.py repl --user u1 --session s1             # 交互式 REPL
python main.py skill-list                              # 列出已注册 Skills
python main.py memory-clear --user u1                  # 清空指定用户记忆
```

## 指令前缀

在对话框中输入以下前缀可直接触发对应功能，无需经过 LLM 路由：

| 前缀          | 说明        | 示例                          |
| ----------- | --------- | --------------------------- |
| `/remember` | 写入记忆      | `/remember language=python` |
| `/forget`   | 删除记忆      | `/forget language`          |
| `/memory`   | 搜索记忆      | `/memory python`            |
| `/cmd`      | 执行命令（需授权） | `/cmd powershell:Get-Date`  |
| `/file`     | 文件操作      | `/file read notes/a.txt`    |
| `/skill`    | 调用 Skill  | `/skill echo {"text":"hi"}` |
| `/spec`     | 复杂任务规划    | `/spec 整理 E 盘的文档`           |

## 项目结构

```
windows_ai_agent/
├── agent.py          # 核心 Agent 类，路由分发 + Agentic Loop
├── web_ui_fastapi.py # FastAPI 服务与 API 端点
├── memory.py         # SQLite 记忆存储
├── context.py        # 会话上下文管理
├── model_client.py   # OpenAI 兼容 HTTP 客户端
├── telemetry.py      # 运行时遥测与历史指标
├── file_ops.py       # 沙箱文件操作
├── command_exec.py   # 命令执行与风险拦截
├── skills.py         # Skills 注册与调用
├── spec_manager.py   # Spec 文档管理
└── tools/            # 内置工具模块
frontend/             # Vue 3 前端
skills/               # Skills 插件目录
tests/                # 单元测试（63 个）
```

## 测试

```powershell
python -m unittest discover -s tests -v
python -m compileall windows_ai_agent tests main.py
```

## License

MIT