Aoisop/mawoagent

选用指南

AI 根据 README 整理 · 2026/10/19 07:31:27

适用场景

适用于项目分析、编程辅助，以及学习和扩展 Agent 运行机制。

查看 README 依据

# mawoagent mawoagent 是一个由 Aoisop 创建和维护的、基于 Python 的本地 **Agent Runtime**，同时提供网页工作台和命令行入口。它把模型推理、工具执行、权限确认、会话恢复、长期记忆、Skills 与自进化流程连接在一起，适合用于项目分析、编程辅助，也适合学习和扩展 Agent 的运行机制。 项目重点是 **Harness**：模型提出操作意图，Runtime 负责判断权限、执行工具、保存状态和回写结果。网页与 CLI 共用这套能力。 ## 快速启动：前端与后端 **运行 `python -m agents.web`，即可同时启动后端 API 和前端页面。** 当前前端采用原生 HTML / CSS / JavaScript，由同一个 Python 服务提供，无需安装 npm 依赖或单独运行前端开发服务器。 | 部分 | 源码位置 | 启动或访问方式 | | --- | --- | --- | | 后端服务 | `agents/web.py`、`agents/` | `python -m agents.web` | | 前端页面 | `web/` | 后端启动后，打开 <http://127.0.0.1:8765> |

使用方式

通过网页工作台或命令行入口使用，两者共用同一套 Runtime 能力。

查看 README 依据

# mawoagent mawoagent 是一个由 Aoisop 创建和维护的、基于 Python 的本地 **Agent Runtime**，同时提供网页工作台和命令行入口。它把模型推理、工具执行、权限确认、会话恢复、长期记忆、Skills 与自进化流程连接在一起，适合用于项目分析、编程辅助，也适合学习和扩展 Agent 的运行机制。 项目重点是 **Harness**：模型提出操作意图，Runtime 负责判断权限、执行工具、保存状态和回写结果。网页与 CLI 共用这套能力。 ## 快速启动：前端与后端 **运行 `python -m agents.web`，即可同时启动后端 API 和前端页面。** 当前前端采用原生 HTML / CSS / JavaScript，由同一个 Python 服务提供，无需安装 npm 依赖或单独运行前端开发服务器。 | 部分 | 源码位置 | 启动或访问方式 | | --- | --- | --- | | 后端服务 | `agents/web.py`、`agents/` | `python -m agents.web` | | 前端页面 | `web/` | 后端启动后，打开 <http://127.0.0.1:8765> |

| 模型未配置、鉴权失败或模型不存在 | 核对密钥、Base URL、模型 ID，以及终端环境变量与 `.env` 的优先级；修改后重启 | | 出现请求校验失败或连接中断 | 确认服务仍在运行，刷新当前端口的页面，以重新建立本地会话 | Web 服务固定监听 `127.0.0.1`，面向本机单用户使用。当前 `Dockerfile` 默认启动 CLI，且未包含 `web/` 静态资源；网页工作台请按上述本地方式启动。更多界面功能与运行边界见 [Web 工作台说明](docs/web-workspace.md)。 ## 命令行使用 CLI 与网页是两个可选入口，使用网页时无需同时启动 CLI。下面命令同样在仓库根目录、已激活虚拟环境的终端中执行。 ```bash # 交互式对话 python -m agents.main # 执行一次任务 python -m agents.main "总结这个项目的目录结构和核心模块" # 只读分析并生成计划 python -m agents.main --plan "分析 Skills 检索逻辑应该如何优化" # 恢复当前项目的最近会话 python -m agents.main --resume # 查看全部参数和内置命令 python -m agents.main --help ```

部署要求

推荐使用 Python 3.11 或 3.12，需要配置 OpenAI-compatible 或 Anthropic-compatible 接口的模型连接。

查看 README 依据

| 命令行入口 | `agents/main.py` | `python -m agents.main`，按需使用 | ### 1. 准备环境并安装依赖 推荐使用 Python **3.11 或 3.12**，以下命令适用于 macOS / Linux。Git 用于获取代码，ripgrep 可选；仅运行网页工作台不需要 Node.js。运行前端测试或使用依赖 Node.js 的 MCP 工具时，再准备 Node.js 环境。 在 **mawoagent 仓库根目录**执行： ```bash # 确认 Python 版本 python3 --version # 首次使用时创建虚拟环境 python3 -m venv .venv source .venv/bin/activate # 使用固定版本依赖安装 python -m pip install -r requirements.lock ``` 如果默认 `python3` 版本不合适，可将创建虚拟环境的命令改为 `python3.12 -m venv .venv`。后续启动时只需激活已有虚拟环境，不必重复创建或安装。 ### 2. 配置模型连接 先创建本地配置文件；已有 `.env` 时保留原文件： ```bash test -f .env || cp .env.example .env ```

用编辑器打开项目根目录的 `.env`，将密钥、接口地址和模型 ID 替换为你实际使用的服务配置。下面两种方式**选择一种**；如果使用服务专用变量，需要删除或注释模板里已启用的 `APIKEY`、`API`，避免混用配置。 **OpenAI-compatible 接口：** ```env OPENAI_API_KEY=your-api-key OPENAI_BASE_URL=https://your-provider.example/v1 MODEL=your-model-id ``` **Anthropic-compatible 接口：** ```env ANTHROPIC_API_KEY=your-api-key ANTHROPIC_BASE_URL=https://your-provider.example/anthropic MODEL=your-model-id ``` 上述地址和模型名称都是占位值，请以服务商提供的配置为准。也支持通用变量 `APIKEY` / `API`。 配置读取规则： - 从当前工作目录向上查找 `.env`；终端中已设置的同名环境变量优先于 `.env`。 - 通用 `API` 优先于服务专用的 Base URL；通用密钥也优先于服务专用密钥。

已知限制

Web 服务固定监听 127.0.0.1，面向本机单用户使用；当前 Dockerfile 默认启动 CLI，且未包含 web/ 静态资源。

查看 README 依据

| 模型未配置、鉴权失败或模型不存在 | 核对密钥、Base URL、模型 ID，以及终端环境变量与 `.env` 的优先级；修改后重启 | | 出现请求校验失败或连接中断 | 确认服务仍在运行，刷新当前端口的页面，以重新建立本地会话 | Web 服务固定监听 `127.0.0.1`，面向本机单用户使用。当前 `Dockerfile` 默认启动 CLI，且未包含 `web/` 静态资源；网页工作台请按上述本地方式启动。更多界面功能与运行边界见 [Web 工作台说明](docs/web-workspace.md)。 ## 命令行使用 CLI 与网页是两个可选入口，使用网页时无需同时启动 CLI。下面命令同样在仓库根目录、已激活虚拟环境的终端中执行。 ```bash # 交互式对话 python -m agents.main # 执行一次任务 python -m agents.main "总结这个项目的目录结构和核心模块" # 只读分析并生成计划 python -m agents.main --plan "分析 Skills 检索逻辑应该如何优化" # 恢复当前项目的最近会话 python -m agents.main --resume # 查看全部参数和内置命令 python -m agents.main --help ```