sgents

sgents 是一个基于 Microsoft AutoGen 的交互式 Agent 控制台。 它把 API Key 管理、安全文件/命令工具、JSON 配置和一个 questionary/rich 风格的 CLI 串在一起， 让用户直接在终端里向 Agent 下达任务。

功能

• 交互式 CLI 菜单（上下键选择、彩色面板与状态栏）
• 通过系统凭据管理器安全保存 API Key（Windows 凭据管理器 / macOS 钥匙串 / Linux keyring）
• 工作区限制的文件读写、目录浏览、命令执行与包安装工具
• Sandboxie 沙箱隔离命令执行（不可用时拒绝执行，不回退到宿主机）
• 单 Agent 与「多 Agent 协作」两种执行模式
• 本地任务历史（保存在工作区的 .sgents/history.json）
• JSON 配置文件，启动时自动创建，配置项可热改

安装

项目使用 uv 管理依赖：

uv sync

运行

# 方式一：直接运行入口脚本
python main.py

# 方式二：安装后使用 console script
uv pip install -e .
sgents

首次配置

进入主菜单后选择「配置设置」：

1. 在「设置 API Key」中粘贴你的 OpenAI 兼容 API Key；
2. 如需自定义模型或服务地址，修改「修改模型」和「修改 Base URL」；
3. 如需调整工作区位置，修改「修改工作区」；
4. 系统命令仅在 Sandboxie 已启用且 sandbox_path 下存在 Start.exe 时可用； 缺少沙箱时程序会拒绝执行命令，不会回退到宿主机。

默认配置如下：

{
  "workspace": "./workspace",
  "sandbox_enabled": true,
  "sandbox_path": "D:\\sandboxieplus\\Sandboxie-Plus",
  "command_timeout": 60,
  "max_output_length": 10000,
  "max_file_size": 102400,
  "default_encoding": "utf-8",
  "model": "gpt-4o-mini",
  "base_url": "",
  "model_info": null,
  "api_key_username": "default",
  "max_turns": 20
}

配置文件位于运行目录下的 config.json。

使用非 OpenAI 模型名及兼容 Base URL 时，程序默认采用保守的文本与工具调用能力配置。 如服务能力不同，可在 config.json 中设置 model_info，字段包括 vision、 function_calling、json_output、family 和 structured_output。

任务类型

类型	说明
网页爬取	侧重抓取与解析网页信息
数据处理	侧重用 Python 处理与统计数据
文件操作	侧重工作区内的文件读写与整理
系统命令	侧重通过系统命令完成任务
多 Agent 协作	Coder + Reviewer 两阶段协作

项目结构

sgents/
├── _api_key_tools.py      # keyring 凭据管理
├── _atomic_tools.py       # 安全工作区工具集
├── _save_config.py        # JSON 配置管理
├── core.py                # AutoGen 运行时与任务历史
└── ui/
    └── _main_interface.py # CLI 界面

安全说明

• API Key 存入操作系统凭据管理器，不写入项目文件；
• Agent 的文件操作被限制在工作区内，_get_safe_path 会拒绝路径穿越；
• 包安装工具会校验包名，防止命令注入；
• 命令执行必须通过 Sandboxie，并以工作区作为初始目录；沙箱不可用时相关工具不会暴露给 Agent。

License

GNU Affero General Public License v3.0，详见 LICENSE。