# 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-04-22

## 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、DeepSeek 等），在本机完成对话、文件管理、命令执行、记忆存储等一系列智能任务。

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

## 核心特性

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

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

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

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

**🔌 Skills 插件系统（参考 OpenCode 设计）**
支持两种 Skill 定义方式：
- **Prompt Skill**：使用 `SKILL.md` 文件定义，包含 YAML frontmatter 和技能描述
- **Function Skill**：使用 `@skill` 装饰器定义，支持参数 Schema 验证

特性包括：
- 多种执行模式（primary/subagent/tool）
- 工具白名单控制
- 多目录自动发现（skills/、.claude/skills/、.agents/skills/）
- 参数 Schema 验证（参考 Zod 设计）

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

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

## 技术栈

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

## 快速开始

### 安装依赖

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

### 配置模型

创建 `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": "workspace",
  "data_root": "data",
  "llm_orchestration_only": true
}
```

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

### 启动服务

**使用启动脚本（推荐）**

```powershell
# 开发模式（构建前端 + 启动服务）
.\start.bat dev --port 8787

# 生产模式（仅启动服务）
.\start.bat prod --port 8787

# 测试模式（测试模型连接）
.\start.bat test

# PowerShell 版本（功能更强）
.\start.ps1 -Mode dev -Port 8787
.\start.ps1 prod
.\start.ps1 test
```

**直接启动**

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

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

## CLI 用法

```powershell
python main.py                          # 启动 UI（默认）
python main.py ui --port 8787           # 指定端口启动 UI
python main.py config-test              # 测试模型连通性
python main.py chat -u u1 -s s1 -m "你好"  # 单次对话
python main.py repl -u u1 -s s1         # 交互式 REPL
python main.py skill-list               # 列出已注册 Skills
python main.py memory-clear -u u1       # 清空指定用户记忆
```

## 指令前缀

在对话框中输入以下前缀可直接触发对应功能：

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

## Skills 开发

### 方式一：装饰器定义（推荐）

```python
# skills/translate/skill.py
from windows_ai_agent.schema import Schema
from windows_ai_agent.skills import skill, SkillContext

@skill(
    name="translate",
    description="使用 LLM 进行文本翻译",
    mode="subagent",  # primary, subagent, tool
    color="#38A3EE",
    schema={
        "text": Schema.string().required().describe("要翻译的文本"),
        "target_lang": Schema.string().required().describe("目标语言"),
    }
)
def execute(args: dict, context: SkillContext) -> dict:
    text = args["text"]
    target_lang = args["target_lang"]
    # ... 翻译逻辑
    return {"ok": True, "translated": result}
```

### 方式二：SKILL.md 文件

```
skills/my_skill/
├── SKILL.md
└── scripts/
    └── helper.py
```

```markdown
---
name: my_skill
description: 技能描述
mode: subagent
model: gpt-4
tools:
  "*": false
  "read_file": true
---

# Skill 内容

这里是技能的详细说明...
```

### Schema 验证

参考 Zod 设计的 Python Schema 验证系统：

```python
from windows_ai_agent.schema import Schema

# 字符串验证
Schema.string().required().describe("名称").enum(["a", "b"])
Schema.string().min_len(1).max_len(100)

# 数值验证
Schema.number().min(0).max(100)
Schema.integer()

# 数组和对象
Schema.array(Schema.string()).min_len(1)
Schema.object({
    "name": Schema.string().required(),
    "age": Schema.number().optional().default(18),
})
```

## 项目结构

```
windows_ai_agent/
├── agent.py           # 核心 Agent 类，路由分发 + Agentic Loop
├── web_ui_fastapi.py  # FastAPI 服务与 API 端点
├── memory.py          # SQLite 记忆存储
├── context.py         # 会话上下文管理
├── model_client.py    # OpenAI 兼容 HTTP 客户端
├── skills.py          # Skills 注册、发现与调用
├── schema.py          # Schema 验证系统（参考 Zod）
├── spec_manager.py    # Spec 文档管理
├── spec_runtime.py    # Spec 并行执行运行时
├── permission.py      # 权限控制系统
├── orchestration.py   # 全局编排器
└── tools/             # 内置工具模块
    ├── fs_read.py     # 文件读取工具
    ├── fs_write.py    # 文件写入工具
    ├── fs_extra.py    # 文件操作工具
    ├── command.py     # 命令执行工具
    ├── browser.py     # 浏览器自动化工具
    ├── excel.py       # Excel 操作工具
    └── skill.py       # Skill 调用工具

frontend/              # Vue 3 前端
skills/                # Skills 插件目录
├── translate/         # 翻译 Skill
└── echo_skill.py      # 示例 Skill

tests/                 # 单元测试
scripts/               # 脚本工具
├── dev_start.bat      # 开发启动脚本
├── build_exe.ps1      # 打包脚本
└── install_browser.ps1
```

## API 端点

| 方法 | 路径                    | 说明               |
|------|-------------------------|--------------------|
| GET  | `/`                     | 前端页面           |
| GET  | `/api/metrics`          | 遥测快照           |
| POST | `/api/chat`             | 同步对话           |
| POST | `/api/chat/stream`      | SSE 流式对话       |
| GET  | `/api/session/history`  | 会话历史           |
| GET  | `/api/memory`           | 记忆列表（分页）   |
| POST | `/api/memory/upsert`    | 新增/更新记忆      |
| DELETE | `/api/memory/{key}`   | 删除单条记忆       |
| POST | `/api/memory/clear`     | 清空用户记忆       |

## 测试

```powershell
# 运行所有测试
python -m unittest discover -s tests -v

# 运行特定测试
python -m unittest tests.test_schema -v
python -m unittest tests.test_skills -v

# 编译检查
python -m compileall windows_ai_agent tests main.py
```

## 打包

```powershell
.\scripts\build_exe.ps1
```

产物位于 `dist\xiaoshang-agent.exe`。

## 常见问题

**端口占用 (WinError 10048)**
```powershell
# 使用启动脚本会自动释放
.\start.bat dev

# 或手动查找并结束进程
netstat -ano | findstr :8787
taskkill /PID <pid> /F
```

**前端未构建**
访问 UI 显示 "UI Not Built"，需先构建前端：
```powershell
cd frontend && npm run build && cd ..
```

**模型连接失败**
检查 `agent_config.json` 中的 `endpoint` 和 `api_key`，使用以下命令验证：
```powershell
python main.py config-test
```

## License

MIT

---

**相关项目**

本项目 Skills 系统设计参考了 [OpenCode](https://github.com/anomalyco/opencode) 的 Agent/Tool 定义方式。