Skip to main content
Glama
huanggeyu717-beep

personal_agent

by huanggeyu717-beep
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Personal Agent

本地优先的桌面 AI 助手 · Codex 受控执行端

Python Electron MCP SQLite Platform License

功能 │ 从源码启动 │ 接入 Codex │ 开发与验证 │ FAQ

Personal Agent 是一个本地优先的 AI 助手，可以单独作为桌面 Agent 使用，也可以通过 MCP 接入 Codex，作为 Codex 的受控执行端。

接入 Codex 时，Codex 负责分析、规划和验收，Personal Agent 用你配置的模型执行明确委派的子任务。 执行权限由本地 Runtime 决定：上游只能请求动作，不能授予权限。实际可执行范围取路由候选、 任务请求、宿主白名单和既有策略的交集，默认为空；项目改动先生成 diff，人工批准后才写入磁盘。

功能

  • 受控执行端：以 MCP Server 接入 Codex，权限取多方交集、默认拒绝，上游无法为自己扩权。

  • 独立桌面 Agent：不接入 Codex 也能直接聊天、切换模型、管理会话和查看运行过程。

  • 多模型支持：支持 DeepSeek、Qwen、MiniMax、Claude、OpenAI、Gemini、GLM 和 MiMo 等 Provider。

  • 项目上下文：按实际项目目录隔离会话、消息和文件能力，可读取项目资料并运行预定义检查。

  • 文件与附件：支持图片、PDF、DOCX、XLSX、PPTX、源码和普通文件。

  • 长期记忆：保存明确的用户事实和偏好，支持审核、更新、检索与遗忘确认。

  • 受控修改：项目变更先生成 diff，经过人工批准后才应用，并支持回滚。

  • 本地优先：数据保存在本地，桌面端使用 Windows DPAPI 加密 API Key，模型不会直接获得任意 Shell、文件写入或网络权限。

Related MCP server: agent-bridge-mcp

从源码启动

当前开发环境面向 Windows，需要 Python 3.12、Node.js 22 或更新的 LTS 版本，以及 Git。

git clone https://github.com/huanggeyu717-beep/personal-agent.git
cd personal-agent
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\setup-windows.ps1

启动桌面应用：

cd desktop
npm start

首次启动向导会让你选择模型、输入对应 API Key 并选择实际项目目录。API Key 使用 Windows DPAPI 加密，磁盘中只保存与当前 Windows 用户绑定的密文。开发者也可以继续用环境变量：

$env:PERSONAL_AGENT_RUNTIME_PROVIDER = "deepseek"
$env:PERSONAL_AGENT_RUNTIME_MODEL = "deepseek-chat"
$env:DEEPSEEK_API_KEY = "<your-api-key>"

桌面端会启动本地 Python 服务，关闭窗口时一并停止。首次打开后可选择实际项目目录， 所有文件操作都会绑定该目录。

更完整的安装和故障排查见 GitHub 快速开始 和 Windows 源码安装。

接入 Codex

完成首次启动配置后，在桌面端“设置 > 连接 Codex”中复制为当前项目生成的 MCP 配置， 粘贴到 Codex 的 config.toml。该配置包含 MCP 命令、当前项目目录和非密钥环境参数。

源码用户也可以手动计算当前项目的本地项目 ID：

$projectId = node -e "console.log(require('./desktop/project-workspaces.cjs').describeProject(process.cwd()).id)"
$env:PERSONAL_AGENT_ACTIVE_PROJECT_ID = $projectId
$env:PERSONAL_AGENT_CODEX_TASKS_ENABLED = "true"
$env:PERSONAL_AGENT_CODEX_TASK_USER_ID = "local-user"

在 Codex 的 config.toml 中注册 MCP Server：

[mcp_servers.personal_agent]
command = "C:\\path\\to\\personal-agent\\.venv\\Scripts\\personal-agent.exe"
args = ["codex-mcp"]

把仓库中的 Skill 安装到 Codex：

Copy-Item -Recurse -Force `
  .\integrations\codex\skills\personal-agent-routing `
  "$env:USERPROFILE\.codex\skills\personal-agent-routing"

重启 Codex 后显式调用：

$personal-agent-routing 使用 Personal Agent 完成这项任务，并把结果交回 Codex 验证。

默认 Tool 和 Capability 白名单为空。需要文件读取、研究或受控修改时，必须在启动环境中 明确配置对应白名单。完整协议与权限说明见 Codex 集成协议。

CLI 与本地 API

.\.venv\Scripts\personal-agent.exe chat --session default
.\.venv\Scripts\personal-agent.exe memories list
.\.venv\Scripts\personal-agent.exe serve

除 /health 外，所有 /v1/* 请求都需要本地 Bearer Token。桌面端会自动生成并注入该 Token，普通桌面用户不需要手动填写。

开发与验证

Python：

.\.venv\Scripts\python.exe -m pytest -m "not live" -q
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m mypy src

桌面端：

cd desktop
npm install
npm run test:unit
npm run test:contract
npm run build:web

测试默认不访问真实模型。只有显式配置凭据并主动运行 live 测试时才会调用供应商 API。

当前状态

这是一个仍在开发中的本地项目。Windows portable/installer、代码签名和自动更新尚未作为 正式公开 Release 提供。从源码运行时不会包含虚拟环境、Node 依赖、数据库、附件、日志或 API Key。

第三方来源与许可证信息见 Third-party notices。

FAQ

接入 Codex 有什么用？ 可以把适合外部模型完成的子任务交给你自己配置的模型执行，减少这部分工作对 Codex 额度的占用， 同时由 Codex 保留规划、验收和最终控制权。Personal Agent 不会绕过、破解或扩充 Codex 官方配额， 它只通过公开的 MCP 接口，把用户明确委派的工作交给独立的 Runtime 执行。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers